Дмитрий
af2ff720ec
Handoff document for transition to new session. Contains: - TL;DR of where we left off (spec v3.1 ready, impl not started) - 4-step instructions for next session (read spec, writing-plans, subagent-driven impl, post-impl tasks) - Context (brain-retro #10 trigger, self-retrospect #2 confirmation, user choice of Level 4) - 7 design principles from spec section 2 - Architecture TL;DR (gate, 4 behaviors, baseline, deletes, preserved) - All 4 spec versions in git with commits - Cross-refs to L1+L2 plan, brain-retro, self-retrospect - 5 open questions for writing-plans phase Cannot write to memory/ path in this turn (memory-coverage hook requires direct:memory-sync coverage, current turn has different coverage). Memory entry can be added in next session via Skill or manual annotation. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
190 lines
11 KiB
Markdown
190 lines
11 KiB
Markdown
# Handoff — Router-gate Hard Wall Уровень 4
|
||
|
||
**Создан:** 2026-05-28 поздний вечер
|
||
**Статус:** spec v3.1 готов, implementation НЕ начата
|
||
**Для:** следующая Claude-сессия, переход к writing-plans skill
|
||
|
||
---
|
||
|
||
## TL;DR
|
||
|
||
Заказчик выбрал **Уровень 4** (полная переделка enforcement-архитектуры) после серии brainstorming-сессий 28.05.2026.
|
||
|
||
**Уровень 1+2** уже реализован и выкачен на origin/main (5 commits, последний `c95445de`).
|
||
|
||
**Уровень 4 spec** — `docs/superpowers/specs/2026-05-28-router-gate-hard-wall-design.md` (версия v3.1, последний commit `fab8e72d`). Прошёл 3 раунда adversarial audit, закрыто 30 holes. Implementation 13.5-20 часов sequential / 6-9 часов wall-clock через subagent-driven parallelism.
|
||
|
||
---
|
||
|
||
## Что нужно сделать в новой сессии
|
||
|
||
### Шаг 1 — Прочитать спек
|
||
|
||
Открыть `docs/superpowers/specs/2026-05-28-router-gate-hard-wall-design.md` целиком. Особое внимание:
|
||
|
||
- **TL;DR в начале** — fast orientation.
|
||
- **§3-§7** — основная архитектура.
|
||
- **§8** — этапы implementation.
|
||
- **§10.2** — JSON-схемы 8 state-файлов.
|
||
- **§10.3** — test strategy.
|
||
- **§10.4** — success metrics.
|
||
- **§10.5** — rollback plan.
|
||
- **§10.6** — parallelism между этапами.
|
||
|
||
### Шаг 2 — Перейти к writing-plans skill
|
||
|
||
Per brainstorming workflow последний шаг — invocation `superpowers:writing-plans`. Это правильный next step. Команда:
|
||
|
||
```
|
||
/superpowers:writing-plans (или вызвать Skill('superpowers:writing-plans') напрямую)
|
||
```
|
||
|
||
Skill попросит контекст: укажи спек `docs/superpowers/specs/2026-05-28-router-gate-hard-wall-design.md`.
|
||
|
||
Skill сгенерирует детальный план implementation в формате `docs/superpowers/plans/2026-05-XX-router-gate-hard-wall.md` со всеми этапами как TDD-tasks.
|
||
|
||
### Шаг 3 — Implementation через subagent-driven-development
|
||
|
||
После writing-plans → перейти к `subagent-driven-development` skill (проектный wrapper). Делегировать каждый этап Sonnet субагенту.
|
||
|
||
**Parallelism opportunity (§10.6 спека):**
|
||
|
||
- Этап 1 (pure decision module) — sequential первым, остальные ждут.
|
||
- Этапы 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8 — параллельны (8 подэтапов, max 3 субагента одновременно). Дают существенное wall-clock сокращение.
|
||
- Этап 2 — sequential после всех 1.X (нужны все модули перед удалением старых хуков).
|
||
- Этапы 2.1 и 2.2 — параллельны с этапом 2.
|
||
- Этап 3 — sequential после 2/2.1/2.2.
|
||
- Этап 6 (brain-retro adaptation) — sequential после Этапа 3 (нужны real data).
|
||
|
||
**Per Pravila §15.1:** субагенты git-commit задач только Sonnet/Opus, никогда Haiku. Git-safety верификация после каждого субагента — pre-spawn HEAD, post-commit parent сравнение, branch check.
|
||
|
||
### Шаг 4 — После implementation
|
||
|
||
- Push на origin (ветка может быть `feat/router-gate-l4` для PR-flow или прямо main с feature-branch merge).
|
||
- Brain-retro #11 через ~1 неделю под Уровнем 4.
|
||
- Self-retrospect #3 через ~50 эпизодов под новой архитектурой.
|
||
- Pravila §16/§17 обновление через `claude-md-management` skill (отдельная задача, не в этом эпике).
|
||
|
||
---
|
||
|
||
## Контекст для понимания «зачем»
|
||
|
||
### Триггер (brain-retro #10)
|
||
|
||
Override-events trend за 4 дня: **12 → 229 → 348 → 679**. Из них `recovery` ушёл 525/день 28.05.2026. Это не аварийные случаи — это **шаблонная привычка обхода gate'а**.
|
||
|
||
Текущая архитектура (Уровни 1+2) сделала vocab более узкой и rate-limited, но не закрыла структурные дырки:
|
||
|
||
- Одна override-фраза снимает 5 хуков разом.
|
||
- Inline `router-skip: <50+ chars>` — self-bypass.
|
||
- Substring-match без user explicit consent.
|
||
|
||
### Self-retrospect #2 подтверждение
|
||
|
||
5 commitments утреннего self-retrospect (override-дисциплина / feature→план first / Sentry-first / Semgrep / coder-agent на массовое) → **сломаны 2 из 5 за 6 часов**. Тезис «привычку без enforcement не удержать» теперь подтверждён двумя независимыми данными.
|
||
|
||
### Решение заказчика
|
||
|
||
«**Hard wall**. Никаких обходов. Разрешение на любой обход даёт **только заказчик**. Все router-рекомендации (одиночные и цепочки) — через явную санкцию. Любая неясная ситуация — controller ничего не делает сам, спрашивает заказчика с честными рекомендациями.»
|
||
|
||
Это explicit acknowledged risk — заказчик соглашается быть recovery-каналом ручной правкой файлов при ошибочном lockout.
|
||
|
||
---
|
||
|
||
## Принципы дизайна (из §2 спека)
|
||
|
||
1. Hard wall, no escape valves в коде.
|
||
2. User approval everywhere для router output (single + chains).
|
||
3. Прямые поручения заказчика (`/skill`, явные «делай X») — без переспрашивания.
|
||
4. Read-only действия — всегда разрешены.
|
||
5. Honest reasoning required в каждом AskUserQuestion.
|
||
6. Recovery — explicit acknowledged risk (ручная правка settings.json / state-файлов при ошибочном lockout).
|
||
7. All decisions logged для post-hoc анализа в brain-retro.
|
||
|
||
---
|
||
|
||
## Архитектура (TL;DR из §3-7 спека)
|
||
|
||
### Новый компонент
|
||
|
||
`tools/enforce-router-gate.mjs` — единственный PreToolUse-хук. Регистрируется в `.claude/settings.json` с `matcher: ""` (все tools).
|
||
|
||
На каждый tool call:
|
||
|
||
1. Читает `~/.claude/runtime/router-state-<sess>.json` (classifier output).
|
||
2. Читает `~/.claude/runtime/chain-state-<sess>.json` (across-turns chain progress).
|
||
3. Анализирует transcript (askuser_called_this_turn, skill_invoked_matching).
|
||
4. Резолвит «разрешено / заблокировано» по 4 поведениям.
|
||
5. Пишет в `~/.claude/runtime/router-gate-decisions.jsonl`.
|
||
|
||
### 4 поведения
|
||
|
||
| # | Когда | Что разрешено |
|
||
|---|---|---|
|
||
| 1 | Direct invocation заказчика (slash-cmd / Skill() / используй #N / делай exact) | Matching skill/Task + read-only baseline |
|
||
| 2 | Single router-рекомендация | Matching Skill/Task + baseline, mutating требует AskUser approval |
|
||
| 3 | Chain router-рекомендация | Текущий шаг chain (state persists across turns, TTL 24h) |
|
||
| 4 | Silence | Baseline только, mutating требует AskUser в 1/2+/0-формате |
|
||
|
||
### Безопасная база (всегда)
|
||
|
||
Read / Grep / Glob / LS / TodoWrite / AskUserQuestion (лимит 2 per turn) / ListMcpResourcesTool / ReadMcpResourceTool (только marked read-only) / text response.
|
||
|
||
`Bash` — НЕ в baseline, отдельные правила в §5.1.
|
||
|
||
### Удаляется
|
||
|
||
5 хуков (chain-recommendation / classifier-match / graph-first / semgrep-security / override-limit) + `enforce-override-vocab.json` + 3 helper-функции (findOverride / findOverrideAttempt / loadOverrideVocab) → stubs.
|
||
|
||
### Сохраняется (7 preserved)
|
||
|
||
tdd-gate / coverage-verify / memory-coverage / verify-before-push / rationalization-audit / prompt-injection / branch-switch. 6 из 7 используют findOverride — после удаления vocab.json эти вызовы возвращают null, hooks работают корректно без правки кода. Acknowledged risk: 6 preserved хуков теряют escape-фразы для починки их самих → требуют ручного вмешательства заказчика при ошибках инфры.
|
||
|
||
---
|
||
|
||
## Версии спека в git
|
||
|
||
| Версия | Commit | Что |
|
||
|---|---|---|
|
||
| v1 | `7a43c175` | Initial design — 5 hooks replaced by single gate, vocab gone |
|
||
| v2 | `b510a758` | Closes 10 holes from v1 adversarial audit |
|
||
| v3 | `b632bcba` | Closes 10 new holes from v2 audit (subagent inheritance fatal, race conditions, DoS, script execution, etc) |
|
||
| **v3.1** | **`fab8e72d`** | **Clarification pass — TL;DR, schemas, test strategy, success metrics, cross-refs, rollback, parallelism** |
|
||
|
||
Все 4 версии на origin/main. v3.1 — рабочая версия для writing-plans.
|
||
|
||
---
|
||
|
||
## Связанные артефакты
|
||
|
||
- L1+L2 план (уже merged): `docs/superpowers/plans/2026-05-28-router-discipline-level-1-2.md` — commit `c95445de`.
|
||
- Brain-retro #10: `docs/observer/notes/2026-05-28-brain-retro-10.md`.
|
||
- Self-retrospect #2: `docs/observer/notes/2026-05-28-self-retrospect-2.md`.
|
||
- Pravila §16 (brain governance) + §17 (universal skill-coverage) — обновится после implementation эпика отдельной задачей через `claude-md-management`.
|
||
|
||
---
|
||
|
||
## Известные limitations / open questions для writing-plans
|
||
|
||
Из §9 спека v3.1:
|
||
|
||
- Точный формат AskUserQuestion message templates — нужно выбрать в плане implementation.
|
||
- Throttling AskUserQuestion (если 3+ вызова в одном turn) — есть лимит 2, но fail-CLOSE поведение можно tighten.
|
||
- Free-form answer интерпретация — может потребоваться LLM-парсинг (cost considerations).
|
||
- Logging granularity — раздельные файлы для askuser/gate-decisions/errors vs unified.
|
||
- Bash whitelist completeness — итеративно расширяется по реальной работе.
|
||
|
||
Эти 5 вопросов решаются на этапе writing-plans, не сейчас.
|
||
|
||
---
|
||
|
||
## Дальше
|
||
|
||
**Команда для новой сессии (после прочтения этого handoff):**
|
||
|
||
```
|
||
Я прочитал handoff `docs/superpowers/handoff-router-gate-l4.md`. Перехожу к writing-plans для эпика router-gate Уровень 4.
|
||
```
|
||
|
||
Затем вызвать `superpowers:writing-plans` skill с reference на spec.
|