docs(plans): router-gate v4 handoff instructions (5 prompts + merge + deploy)

Handoff document for non-programmer user — how to launch 5 parallel
Claude sessions, monitor progress, merge results, and activate v4.0+v4.1+v4.2.

Contains:
- Ready-to-copy prompts for Streams A, B, C, D, E
- VM Sandbox hands-on guide pointer (Stream F)
- Checkpoint 1 merge instructions
- Stream G (cleanup + register) prompt
- User-run Smokes guide
- Stream H (brain-retro + docs sync) prompt
- Final verification + worktree cleanup

+ cspell vocab additions (промты, мониторьте) for Russian content.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Дмитрий
2026-05-29 18:54:42 +03:00
parent 534e93d50d
commit 4e15fa70ff
2 changed files with 450 additions and 0 deletions
+2
View File
@@ -1968,3 +1968,5 @@ yubikey
виртуалкам
субверсия
monitorится
промты
мониторьте
@@ -0,0 +1,448 @@
# Router-gate v4 — Инструкции по запуску параллельных сессий и сборке
**Дата:** 2026-05-29 (вечер)
**Цель:** запустить 5 параллельных Claude-сессий, дождаться их завершения, склеить результаты, проверить и активировать.
**База:**
- Master coordination plan: [`docs/superpowers/plans/2026-05-29-router-gate-v4-master.md`](2026-05-29-router-gate-v4-master.md)
- Спеки: v4.0 + v4.1 + v4.2 в `docs/superpowers/specs/`
---
## Часть 1. Запуск 5 параллельных сессий
### Шаг 1.1 — Открыть 5 окон VS Code
Worktree уже созданы автоматически. Их 5:
```
C:\моя\проекты\портал crm\v4-stream-A ← Stream A (pure modules)
C:\моя\проекты\портал crm\v4-stream-B ← Stream B (shell parsing)
C:\моя\проекты\портал crm\v4-stream-C ← Stream C (static scan + MCP)
C:\моя\проекты\портал crm\v4-stream-D ← Stream D (LLM-judge Layer 4)
C:\моя\проекты\портал crm\v4-stream-E ← Stream E (AskUser + subagent)
```
Откройте каждую папку отдельным окном VS Code:
```powershell
code "C:\моя\проекты\портал crm\v4-stream-A"
code "C:\моя\проекты\портал crm\v4-stream-B"
code "C:\моя\проекты\портал crm\v4-stream-C"
code "C:\моя\проекты\портал crm\v4-stream-D"
code "C:\моя\проекты\портал crm\v4-stream-E"
```
(Можно запустить эти 5 команд по очереди в PowerShell.)
### Шаг 1.2 — В каждом окне запустить Claude
В каждом из 5 окон VS Code откройте новый terminal (`Ctrl+~`) и запустите:
```powershell
claude
```
Получите 5 одновременно работающих Claude-сессий.
### Шаг 1.3 — Скопировать-вставить промт в каждую сессию
**Каждой сессии — свой промт.** Скопируйте соответствующий блок и вставьте в Claude.
---
## Промт для Stream A — Pure decision modules
```
Запускаю Stream A из router-gate v4 implementation.
1. Прочитай docs/superpowers/plans/2026-05-29-router-gate-v4-master.md (мастер-план координации).
2. Прочитай разделы §3 Architecture спека docs/superpowers/specs/2026-05-29-router-gate-v4-design.md (§3.1.2 safe-baseline metering, §3.7 skill scope verifier, §3.9 TodoWrite verifier, §3.11 TDD real-test) и v4.1 amendment docs/superpowers/specs/2026-05-29-router-gate-v4-1-max-closure.md (§3.7 content-level scope, §3.10 cascade Skill, §3.12 self-debrief, §3.9 hard sync).
3. Используй superpowers:writing-plans skill чтобы написать детальный sub-plan для Stream A. Сохрани в docs/superpowers/plans/2026-05-29-router-gate-v4-stream-A-pure-modules.md.
Scope Stream A (8 модулей + tests, ~250 unit-тестов):
- tools/router-gate-decide.mjs (core decide() function, 4 поведения §4)
- tools/safe-baseline-metering.mjs (Direction 1)
- tools/skill-scope-verifier.mjs (Direction 2 + v4.1 content-level)
- tools/decomposition-detector.mjs (Direction 3 + v4.1 hard-block)
- tools/todowrite-skill-verifier.mjs (Direction 4 + v4.1 hard sync)
- tools/self-debrief-detector.mjs (§3.12 v4.1 NEW)
- tools/tdd-real-test-verifier.mjs (§3.11)
- tools/path-normalization.mjs (упрощённый §3.1.1)
Каждый файл создаётся через TDD: failing test → minimal code → green → commit. Atomic commits.
Заглушки для интерфейсов из Stream B/C/D/E — допустимы, помечай в коде `// stub for stream X`.
4. После approval плана — используй superpowers:subagent-driven-development skill для реализации task-by-task с двухступенчатым ревью.
5. Когда все 8 модулей готовы и vitest GREEN — пушни ветку feat/v4-stream-A на origin.
Записывай прогресс в docs/sessions/CURRENT.md (Pravila §15.2).
Текущий worktree: C:\моя\проекты\портал crm\v4-stream-A
Текущая ветка: feat/v4-stream-A
```
---
## Промт для Stream B — Shell content parsing
```
Запускаю Stream B из router-gate v4 implementation.
1. Прочитай docs/superpowers/plans/2026-05-29-router-gate-v4-master.md (мастер-план).
2. Прочитай разделы §5.1 Bash content rules и §5.1.2 PowerShell content rules спека docs/superpowers/specs/2026-05-29-router-gate-v4-design.md плюс v4.1 amendment docs/superpowers/specs/2026-05-29-router-gate-v4-1-max-closure.md (G5 git --no-verify, G6 gpgsign, G7 wget, G8 nc/socat, G10 $env: direct set, C16 stderr redirects, #4 node -e fs.X, #21 env modifiers, #22 watch flag, #34 echo injection).
3. Используй superpowers:writing-plans skill чтобы написать sub-plan для Stream B. Сохрани в docs/superpowers/plans/2026-05-29-router-gate-v4-stream-B-shell-content.md.
Scope Stream B:
- tools/shell-content-rules.mjs (shared classify/tokenize/pathDenyOverlay)
- tools/bash-tokenizer.mjs (extend существующий через shell-quote npm)
- tools/enforce-router-gate.mjs (Bash matcher § 5.1 — whitelist + hard-blacklist + sub-shell sweep + path-deny + file-watcher + conditional after approve_git_operation)
- tools/enforce-powershell-gate.mjs (PowerShell matcher § 5.1.2 — зеркало Bash)
Все v4.0 + v4.1 hard-blacklist patterns включены. Заглушки для path-normalization (Stream A) — допустимы.
4. После approval плана — реализация через superpowers:subagent-driven-development.
5. Когда vitest GREEN — пушни ветку feat/v4-stream-B на origin.
Текущий worktree: C:\моя\проекты\портал crm\v4-stream-B
Текущая ветка: feat/v4-stream-B
```
---
## Промт для Stream C — Static scan + MCP
```
Запускаю Stream C из router-gate v4 implementation.
1. Прочитай docs/superpowers/plans/2026-05-29-router-gate-v4-master.md (мастер-план).
2. Прочитай разделы §5.2 Static content scan, F7 framework boot-path scan, F8 Glob post-execution filter, §5.3 MCP path-deny overlay спека docs/superpowers/specs/2026-05-29-router-gate-v4-design.md плюс v4.1 amendment (G1 WebSearch/WebFetch, G11 commit message scan, G12 MCP database-query full-statement).
3. Используй superpowers:writing-plans skill чтобы написать sub-plan для Stream C. Сохрани в docs/superpowers/plans/2026-05-29-router-gate-v4-stream-C-static-mcp.md.
Scope Stream C:
- tools/static-content-scanner.mjs (multi-language: PHP/Ruby/Go/Java/Rust/.NET suspicious patterns)
- tools/framework-boot-scanner.mjs (Laravel app/Providers/*, bootstrap/*, routes/*, Kernel.php, Middleware/*, Console/Commands/*)
- tools/glob-restricted-filter.mjs (F8 — post-execution filter для Glob ~/.claude/runtime/** wildcards)
- tools/mcp-tool-classifier.mjs (§5.3 — classification map + path_args + query_full_statement_scan для database-query + URL whitelist для browser_navigate/WebFetch)
- tools/commit-message-scanner.mjs (G11 — pre-consume validation commit message + LLM-judge stub)
Заглушки для path-normalization (Stream A) и llm-judge (Stream D) — допустимы.
4. После approval плана — реализация через superpowers:subagent-driven-development.
5. Когда vitest GREEN — пушни ветку feat/v4-stream-C на origin.
Текущий worktree: C:\моя\проекты\портал crm\v4-stream-C
Текущая ветка: feat/v4-stream-C
```
---
## Промт для Stream D — LLM-judge Layer 4
```
Запускаю Stream D из router-gate v4 implementation.
1. Прочитай docs/superpowers/plans/2026-05-29-router-gate-v4-master.md (мастер-план).
2. Прочитай раздел §4.7 Question quality detector + §3.6.1/§3.6.2 Normative-content gate спека docs/superpowers/specs/2026-05-29-router-gate-v4-design.md плюс v4.1 amendment (Layer 4 — multi-judge consensus Sonnet+Haiku+Opus, per-tool LLM-judge на каждый mutating tool, LLM-judge на response text для self-replicating instruction).
3. Используй superpowers:writing-plans skill чтобы написать sub-plan для Stream D. Сохрани в docs/superpowers/plans/2026-05-29-router-gate-v4-stream-D-llm-judge.md.
Scope Stream D:
- tools/llm-judge.mjs (helper для multi-judge consensus — Sonnet+Haiku+Opus через ProxyAPI; delimiter tokens 24-char random; pre-filter strips SYSTEM:/<judge>/JSON-fragments; any YES → block)
- tools/llm-judge-per-tool.mjs (PreToolUse на mutating tools — "consistent с declared task?")
- tools/llm-judge-response-scan.mjs (Stop hook на response text — self-replicating instruction / metadata injection detection)
- tools/enforce-normative-content-rules.mjs (§3.6.2 — second-layer gate для writes на memory/CLAUDE.md/Pravila/PSR/Tooling; restored multi-judge v4.1)
Cache: per-session, TTL 1h, invalidation on UserPromptSubmit. Budget: 200 LLM-calls/session.
API key через env var ROUTER_LLM_KEY (упрощено vs v3.8 keytar).
4. После approval плана — реализация через superpowers:subagent-driven-development. Используй mock LLM responses для tests; интеграция с ProxyAPI verified в Checkpoint 1.
5. Когда vitest GREEN — пушни ветку feat/v4-stream-D на origin.
Текущий worktree: C:\моя\проекты\портал crm\v4-stream-D
Текущая ветка: feat/v4-stream-D
```
---
## Промт для Stream E — AskUser + subagent
```
Запускаю Stream E из router-gate v4 implementation.
1. Прочитай docs/superpowers/plans/2026-05-29-router-gate-v4-master.md (мастер-план).
2. Прочитай разделы §3.2 Subagent inheritance, §3.4 Subagent constraints + return scanner, §4.5 AskUser answer parser, §4.7 cosmetic AskUser detector спека docs/superpowers/specs/2026-05-29-router-gate-v4-design.md плюс v4.1 amendment (G2 subagent narrative validation + structured output schema, cosmetic AskUser hard-block, S27 stop-keywords +25 Russian variants, E33 invisible Unicode strip, E34 whitespace-normalized approval).
3. Используй superpowers:writing-plans skill чтобы написать sub-plan для Stream E. Сохрани в docs/superpowers/plans/2026-05-29-router-gate-v4-stream-E-askuser-subagent.md.
Scope Stream E:
- tools/askuser-answer-parser.mjs (§4.5 + расширенный stop-keywords + invisible Unicode pre-filter + whitespace-normalized approval pattern matching)
- tools/askuser-cosmetic-detector.mjs (v4.1 hard-block при >2 simple AskUser/session без brainstorming skill)
- tools/enforce-subagent-return-scanner.mjs (§3.4 + G2 narrative test claim patterns scanner; PostToolUse Task matcher)
- tools/subagent-output-schema.json (structured output schema для test claims)
- tools/subagent-prompt-prefix.mjs (extension — env-based inheritance + parent_random_id 256-bit sentinel + restricted/ subagent-block path)
Заглушки для llm-judge (Stream D) — допустимы.
4. После approval плана — реализация через superpowers:subagent-driven-development.
5. Когда vitest GREEN — пушни ветку feat/v4-stream-E на origin.
Текущий worktree: C:\моя\проекты\портал crm\v4-stream-E
Текущая ветка: feat/v4-stream-E
```
---
## Часть 2. Параллельно — Stream F (VM-песочница) у вас
Это не Claude-сессия. Это hands-on у вас по спеку v4.2.
Откройте спек `docs/superpowers/specs/2026-05-29-router-gate-v4-2-vm-sandbox.md` и идите по §2 (7 шагов):
1. Установить VirtualBox.
2. Создать виртуальную машину claude-sandbox.
3. Установить Windows Server 2022 Evaluation внутри.
4. Установить Node, Git, VS Code, Claude CLI, PHP, Composer, Pest, PostgreSQL клиент внутри.
5. Настроить Shared Folder host → VM.
6. Перенести `~/.claude/` внутрь VM.
7. Сделать snapshot `clean-state-2026-05-29`.
~10-12 часов хands-on. Можно делать параллельно пока 5 Claude-сессий работают над кодом.
---
## Часть 3. Мониторинг прогресса
В master сессии (где сейчас сидите — `Документация`) раз в 1-2 часа проверяйте прогресс:
```powershell
# Посмотреть кто что закоммитил
git fetch --all
git log feat/v4-stream-A --oneline -5
git log feat/v4-stream-B --oneline -5
git log feat/v4-stream-C --oneline -5
git log feat/v4-stream-D --oneline -5
git log feat/v4-stream-E --oneline -5
```
Если какая-то сессия зависла >2 часа без коммитов — откройте то окно VS Code, проверьте что Claude там делает, разблокируйте.
Каждая сессия должна записывать заявку в `docs/sessions/CURRENT.md` — следите за статусами `in_progress` / `review` / `merged`.
---
## Часть 4. Сборка (Checkpoint 1) — когда все 5 streams готовы
В master сессии (папка `Документация`):
```powershell
# 1. Подтянуть все ветки
git fetch --all
# 2. Перейти на main и обновить
git checkout main
git pull origin main
# 3. Слить каждую stream-ветку в main (одну за другой)
git merge feat/v4-stream-A --no-ff -m "feat(router-gate): v4 stream A — pure decision modules"
git merge feat/v4-stream-B --no-ff -m "feat(router-gate): v4 stream B — shell content parsing"
git merge feat/v4-stream-C --no-ff -m "feat(router-gate): v4 stream C — static scan + MCP path-deny"
git merge feat/v4-stream-D --no-ff -m "feat(router-gate): v4 stream D — LLM-judge Layer 4"
git merge feat/v4-stream-E --no-ff -m "feat(router-gate): v4 stream E — AskUser + subagent integration"
# 4. Проверить что всё собралось — запустить полную регрессию
npx vitest run tools/ --exclude='**/worktrees/**'
# 5. Если GREEN — пушнуть собранное
git push origin main
```
### Если на каком-то merge будет конфликт
Возможен конфликт если стримы случайно правили один файл (по мастер-плану §3 этого быть не должно, но всякое случается). Тогда:
1. Скриншот ошибки → откройте новую Claude-сессию (НЕ те 5 что работают над стримами) → пришлите туда → разберём.
---
## Часть 5. Stream G (cleanup + регистрация) — отдельная сессия
После Checkpoint 1 (всё в main).
В master сессии откройте Claude (если ещё не открыт) и напечатайте:
```
Запускаю Stream G — cleanup + settings.json registration.
1. Прочитай docs/superpowers/plans/2026-05-29-router-gate-v4-master.md раздел §Stream G.
2. Используй superpowers:writing-plans skill чтобы написать sub-plan для Stream G. Сохрани в docs/superpowers/plans/2026-05-29-router-gate-v4-stream-G-cleanup-register.md.
Scope Stream G:
УДАЛИТЬ файлы (5 v3.9 хуков + vocab):
- tools/enforce-chain-recommendation.mjs + test
- tools/enforce-classifier-match.mjs + test
- tools/enforce-graph-first.mjs + test
- tools/enforce-semgrep-security.mjs + test
- tools/enforce-override-limit.mjs + test
- tools/enforce-override-vocab.json
МОДИФИЦИРОВАТЬ:
- tools/enforce-hook-helpers.mjs — findOverride/findOverrideAttempt/loadOverrideVocab → permanent stubs (return null/null/empty)
- .claude/settings.json — снять registrations 5 удалённых хуков, добавить новые v4 hooks (router-gate, powershell-gate, normative-content-rules, subagent-return-scanner, tdd-real-test, self-debrief, todowrite-skill-verifier, askuser-cosmetic-detector, llm-judge-per-tool, llm-judge-response-scan, parallel-session-lock, mcp-classification)
3. Реализация через superpowers:subagent-driven-development.
4. После завершения — НЕ пушить сразу, сначала backup-ветка:
git branch backup-pre-v4-cleanup main
git push origin backup-pre-v4-cleanup
5. Потом коммит Stream G и push.
Это последний этап перед smokes.
```
---
## Часть 6. User-run Smokes (8 проверок)
После Stream G merged на origin/main.
**Откройте ЧИСТУЮ Claude сессию** (новое окно VS Code в основной папке `Документация`). В ней проведите 8 smoke-проверок из спека v4.0 §3.2.0 + v4.1 §F9.
Промт для Claude:
```
Помоги мне провести 8 user-run smoke tests из спека router-gate v4 §3.2.0 и v4.1 §F9.
Прочитай docs/superpowers/specs/2026-05-29-router-gate-v4-design.md раздел §3.2.0 (Smoke 1, 2, 3, 4, 5, 7, 8) и docs/superpowers/specs/2026-05-29-router-gate-v4-1-max-closure.md (Smoke 9 — PostToolUse modify capability).
Каждый smoke объясни простым языком: что проверяем, какой prompt мне написать, какой результат ожидать (PASS/FAIL).
После каждого smoke зафиксируй результат в docs/observer/smoke-results.md.
Если хоть один FAIL — сделай отдельный fix-task до Stream H.
```
---
## Часть 7. Stream H (Brain-retro + Docs sync) — финальная сессия
После всех Smokes PASS.
Откройте Claude в основной папке. Промт:
```
Запускаю Stream H — brain-retro Table 16-17 + recovery procedures + Pravila/PSR/Tooling/CLAUDE.md sync.
1. Прочитай docs/superpowers/plans/2026-05-29-router-gate-v4-master.md раздел §Stream H.
2. Используй superpowers:writing-plans skill чтобы написать sub-plan для Stream H. Сохрани в docs/superpowers/plans/2026-05-29-router-gate-v4-stream-H-docs.md.
Scope Stream H:
- tools/brain-retro-analyzer.mjs — Table 16-new (15 behavioral bypass categories) + Table 17-new (LLM-judge per-tool stats)
- .claude/skills/brain-retro/SKILL.md — mandatory tables 11→13
- docs/recovery-procedures.md — НОВЫЙ файл, plain-Russian cheatsheet по §6.1
- CLAUDE.md — version bump v2.40 → v2.41, добавить запись про v4 deployment
- docs/Pravila_raboty_Claude_v1_1.md — bump v1.43 → v1.44, §17 universal skill-coverage updated
- docs/Plugin_stack_rules_v1.md — bump v3.23 → v3.24
- docs/Tooling_v8_3.md Прил. Н — bump v2.24 → v2.25
3. Реализация через superpowers:subagent-driven-development.
4. Финальный commit + push.
```
---
## Часть 8. Финальная проверка и закрытие
После Stream H merged на origin/main.
```powershell
# В master сессии (папка Документация)
# 1. Полная регрессия
npx vitest run tools/ --exclude='**/worktrees/**'
# Ожидается ~250+ tests GREEN
# 2. Полный lefthook
npx lefthook run pre-push
# 3. Удалить worktrees (cleanup)
git worktree remove "C:\моя\проекты\портал crm\v4-stream-A"
git worktree remove "C:\моя\проекты\портал crm\v4-stream-B"
git worktree remove "C:\моя\проекты\портал crm\v4-stream-C"
git worktree remove "C:\моя\проекты\портал crm\v4-stream-D"
git worktree remove "C:\моя\проекты\портал crm\v4-stream-E"
# 4. Удалить локальные feat/v4-stream-X ветки (они уже на origin)
git branch -D feat/v4-stream-A feat/v4-stream-B feat/v4-stream-C feat/v4-stream-D feat/v4-stream-E
# 5. Опционально — удалить ветки и на origin
git push origin --delete feat/v4-stream-A feat/v4-stream-B feat/v4-stream-C feat/v4-stream-D feat/v4-stream-E
```
---
## Часть 9. Активация защиты v4.0+v4.1
После Stream H push и регрессии — защита уже активна в `.claude/settings.json` (Stream G это сделал).
**Перезапустите** все Claude CLI чтобы они подхватили новые хуки.
Через 1 неделю работы — проведите brain-retro #11:
```
В Claude:
/brain-retro
```
Если bypass rate ~2-5% и нет critical incidents — v4.0+v4.1 успешно развернут.
---
## Итог по времени (ваш человеко-час)
| Что | Сколько вашего времени |
|---|---|
| Открыть 5 окон VS Code + запустить Claude + вставить промты | ~15 минут |
| Мониторинг 5 параллельных сессий (раз в 1-2 часа открывать смотреть) | ~30 минут за 8-12 часов работы Claude'ов |
| Checkpoint 1 — слить ветки в main | ~30 минут |
| Stream G + Stream H — открыть Claude, дать промт, дождаться | ~15 минут активно + 4-6 часов работы Claude |
| Smokes — проверки руками | ~2 часа |
| VM Sandbox (Часть 2) — параллельно если делаете | ~10-12 часов hands-on |
| Cleanup | ~10 минут |
**Без VM:** ~3-4 часа вашего активного времени за 1-2 дня.
**С VM:** +10-12 часов настройки VirtualBox.
---
## Если что-то пойдёт не так
- **Любая сессия зависла** → откройте окно VS Code где она сидит → дайте промт «продолжай» → если не помогает, пришлите скриншот в новую Claude session.
- **Конфликт при merge** → скриншот → новая Claude session.
- **Smoke FAIL** → следуйте инструкции degraded mode из §3.2.0 спека.
- **Хуки rationalization снова блокируют** → запушено `fix(rationalization-audit)` — должно быть OK. Если нет — `$env:LEFTHOOK = "0"` для одной команды.
---
## Готово
Master plan + handoff на месте. Worktree созданы. Промты готовы.
Дальше — выполняйте Часть 1, потом мониторьте, потом Checkpoint 1.
Удачи!