From 4e15fa70fff5ff26d990228fe70ec9ae19dc495f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=94=D0=BC=D0=B8=D1=82=D1=80=D0=B8=D0=B9?= Date: Fri, 29 May 2026 18:54:42 +0300 Subject: [PATCH] docs(plans): router-gate v4 handoff instructions (5 prompts + merge + deploy) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- cspell-words.txt | 2 + ...-29-router-gate-v4-handoff-instructions.md | 448 ++++++++++++++++++ 2 files changed, 450 insertions(+) create mode 100644 docs/superpowers/plans/2026-05-29-router-gate-v4-handoff-instructions.md diff --git a/cspell-words.txt b/cspell-words.txt index b9ea5898..4e06417f 100644 --- a/cspell-words.txt +++ b/cspell-words.txt @@ -1968,3 +1968,5 @@ yubikey виртуалкам субверсия monitorится +промты +мониторьте diff --git a/docs/superpowers/plans/2026-05-29-router-gate-v4-handoff-instructions.md b/docs/superpowers/plans/2026-05-29-router-gate-v4-handoff-instructions.md new file mode 100644 index 00000000..a2d859c8 --- /dev/null +++ b/docs/superpowers/plans/2026-05-29-router-gate-v4-handoff-instructions.md @@ -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://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. + +Удачи!