Дмитрий
108 lines
14 KiB
Markdown
108 lines
14 KiB
Markdown
# ADR-016: §17 Universal skill-coverage — заменяет §12
|
||
|
||
**Status:** Accepted
|
||
**Date:** 2026-05-25
|
||
**Контекст:** LLM-first router overhaul (Phase 1), spec `docs/superpowers/specs/2026-05-24-llm-first-router-overhaul-design.md` v2.3, plan `docs/superpowers/plans/2026-05-25-llm-first-router-overhaul.md` v1.2 Task 5.
|
||
|
||
## Context
|
||
|
||
§12 «Superpowers — hard rule (инвокация skills первой)» (введено 09.05.2026 на явный запрос заказчика) исходило из ограниченного списка из 14 пар «задача → skill» (§12.2 map). За 16 дней эксплуатации обнаружилось:
|
||
|
||
1. **Карта §12.2 не покрывает всё.** Новые классы задач (security, marketing, multi-step planning без явного «эпик», analysis-only без коды) не имели чётких маппингов. Заказчик регулярно правил карту вручную.
|
||
2. **Рационализация пропуска.** Несмотря на §12.4 «hard-rule статус — рационализация нарушение», в episodes-2026-05 (brain-retro #2 + #3) накопились случаи «direct без skill» с post-hoc обоснованием «эта задача проще» — поведение, которое §12 формально запрещал, но не enforce'ил механически.
|
||
3. **Skill-discipline хуки** (`skill-marker.py` + `skill-check.py`) работали как «speed-bump», а не как блокирующая защита — bypass через Bash был тривиален (см. memory `feedback_superpowers_hard_rule`).
|
||
4. **Continuation case (D1).** «Делай», «дальше», «продолжай» — короткие коротыши без анкера, формально fail на §12 (нет skill в карте) → классифицировались как `direct` → накапливали missed-activations. brain-retro #3 (23.05.2026) показал 7/15 missed-activations были такого рода после очистки шума маппинга (memory `feedback_feature_via_writing_plans`).
|
||
|
||
Brain governance (ADR-011) уже ввёл наблюдателя + 5 контролёров C1-C5 + registry `docs/registry/nodes.yaml` как single source of truth. Inside Phase A/B/C наблюдатель пишет episodes с classifier output (`task_classification`, `node_chosen`, `triggers_matched`, etc) — у нас есть **данные** о реальных пропусках.
|
||
|
||
LLM-first router overhaul (spec v2.3, plan v1.2) предлагает **universal skill-coverage** как замену §12: вместо закрытого списка задача→skill, classifier (Sonnet 4.6 + памятка) на каждом ходе решает class задачи (`conversation` / `micro` / `manual_override` / `feature` / `bugfix` / ...) и enforcement-гейт блокирует direct на non-exempt классах. Closed list (§12.2) → open universe via classifier.
|
||
|
||
## Decision
|
||
|
||
**§12 «Superpowers hard rule» архивируется.** Текст переносится в `docs/archive/llm-bootstrap-2026-05/pravila-12/Pravila_section_12.md` (выполнено Phase 1 Task 4, commit `bca63fc6`).
|
||
|
||
**§17 «Universal skill-coverage rule» добавляется** (Phase 1 Task 5, this commit). Полная формулировка — Pravila §17. Ключевые тезисы:
|
||
|
||
1. **Default-deny на non-conversation задачах.** Все задачи, кроме явных `conversation` / `micro` / `manual_override`, должны быть покрыты skill или цепочкой из `docs/registry/nodes.yaml`. Direct-исполнение допустимо только в 5 exempt-классах §17.2.
|
||
2. **Classifier как источник exempt-decisions.** Не закрытый список пар, а классификатор (Sonnet 4.6 + памятка, активируется Phase 2 Task 10) определяет class задачи; exempt = `conversation` ∪ `micro` ∪ `manual_override` ∪ acknowledgment/cancellation prefilter ∪ escape-hatch.
|
||
3. **Continuation НЕ exempt (D1).** «Да», «делай», «дальше» наследуют classification предыдущего хода; если та была non-conversation — §17 применяется как обычно. `NON_BLOCKING_TASK_TYPES` в router-tool-gate содержит только `conversation` / `micro` / `manual_override`; continuation там нет, и это намеренно.
|
||
4. **Enforcement через `tools/router-tool-gate.mjs`.** Mode = `~/.claude/runtime/router-gate-mode.json` ∈ `{off, warn-only, enforce}`. Default Phase 2 bootstrap — `warn-only`.
|
||
5. **§17 — не hard-rule под §9.** Заказчик может временно перевести mode → `off` (runtime-flag). Но рационализация типа «эта задача проще» не работает: гейт оперирует на classifier output, не на оценке Claude.
|
||
6. **Связь с §16.4.** Missed-activation в §16.4 = симметричный отчёт о пропусках §17. Surface в STATUS.md C5 + `/brain-retro`, не блокирует.
|
||
|
||
## Consequences
|
||
|
||
### Положительные
|
||
|
||
- **Universal coverage.** Любая новая категория задач (security, marketing, audit, etc.) автоматически покрывается классификатором без правки списка §12.2.
|
||
- **Continuation case закрыт.** D1 (наследование classification на коротких коротышах) явно описан и enforce'ится одинаково с явной non-conversation задачей.
|
||
- **Механический enforcement.** Router-tool-gate работает на classifier output + hard-coded exempt list; рационализация Claude через переформулировку не работает — гейт не читает текст хода.
|
||
- **Откатываемость.** 9-флаговая система (см. plan §10) позволяет выключить любой компонент независимо (`router-gate-mode → off`, `router-classifier-mode → regex-fallback`, etc.). Полный откат через `tools/test-rollback.mjs --execute` + `git reset --hard brain-pre-llm-bootstrap` (commit `9d4a30c3`).
|
||
- **Evidence loop.** Каждый ход пишет `classifier_output` в episode JSONL; brain-retro раз в 1-2 недели разбирает paterns, опционально дистиллирует regex-правила (Phase 4 через ~6 месяцев).
|
||
|
||
### Отрицательные / риски
|
||
|
||
- **Стоимость классификатора.** Sonnet 4.6 на каждом ходе — оценка $320-1370/мес на bootstrap (spec §10). Без daily cap, только monitoring через STATUS.md. Принято осознанно как «плата за качество данных» (заказчик 2026-05-25).
|
||
- **Период несогласованности.** Phase 2 bootstrap — `warn-only`; реальный enforce только после явного решения заказчика. До этого §17 действует только как обещание, поведенчески ничего не меняется.
|
||
- **Classifier-cost vs. человеческая оценка.** Возможны ложные классификации (например, рутинный bugfix → classifier label feature). Это нарушения, которые brain-retro подсветит в sanity-check, но они засоряют warn-only метрики.
|
||
- **Регрессия зависит от nodes.yaml gaps.** Если узел реестра не имеет `triggers[].classification` для данного class задачи — classifier выдаст `task_type=feature` но `recommended_node=null`. Router-tool-gate сегодня блокирует на `no_skill_found_block` (см. spec §4.4). При неполном реестре это false-block. Phase 2 Task 8 добавляет `capabilities:` на ~85 узлов, что снижает риск.
|
||
|
||
### Не влияет на
|
||
|
||
- §1-§11 Pravila — без изменений (§11 «Superpowers override §2.2/§4.5/§8.4» остаётся; экономия 0%/5%/25%/50%/75%/100% сохраняется).
|
||
- §13 (Frontend Design plugin paired stack) — без изменений.
|
||
- §14 (Ruflo Queen routing — dormant) — без изменений.
|
||
- §15 (Параллельные сессии) — без изменений.
|
||
- §16 (Brain governance — наблюдатель + контролёры C1-C6) — §16.4 minor update (cross-ref на nodes.yaml вместо JSON-карты, сделано Task 4); §16.5 hard-rule list update (§12 → §17, сделано Task 4).
|
||
- Schema БД, открытые вопросы, ADR-001…ADR-015 — не трогаются.
|
||
- Production code портала liderra.ru — overhaul затрагивает только Claude-meta-слой (router, observer), не application code.
|
||
|
||
## Boundaries
|
||
|
||
| Сценарий | §17 применяется? | Почему |
|
||
|---|---|---|
|
||
| `feature` task type + skill recommended | Да, требует skill | Default-deny на non-conversation |
|
||
| `feature` task + классификатор не нашёл подходящий skill | Да, блокирует на `no_skill_found_block` | Сигнал, что реестр неполон |
|
||
| `bugfix` task + явное «делай через TDD» в prompt | Нет, `manual_override` exempt | П.3 §17.2 |
|
||
| Continuation «делай» после `feature` predecessor | Да, наследует non-conversation classification | П.3 §17.3 (D1) |
|
||
| Continuation «спасибо» / «отлично» | Нет, `conversation` через prefilter | П.4 §17.2 |
|
||
| `<!-- routing: direct_justified=true reason="..." -->` в начале хода | Нет, escape-hatch | П.5 §17.2 |
|
||
| Q&A заказчика без действий над кодом | Нет, `conversation` | П.1 §17.2 |
|
||
| Опечатка в комментарии / переименование переменной | Нет, `micro` | П.2 §17.2 |
|
||
| `<!-- routing: skill="brainstorming" -->` без него | Да (но prefilter уже даёт `manual_override` → exempt) | П.3 §17.2 |
|
||
| ПДн handling, gitleaks pre-commit | НЕ override-ится — §5 + technical compensators выше §17 | §17.5 «замещает §12», но не §5 |
|
||
|
||
## Enforcement
|
||
|
||
1. **Hook chain.** `tools/router-tool-gate.mjs` подписан на `PreToolUse:Edit|Write|MultiEdit|Bash`. На каждый tool-вызов читает `~/.claude/runtime/router-state-<session>.json` (записан router-prehook на UserPromptSubmit), извлекает `classifier_output.task_type` + `recommended_node` + `skillInvokedThisTurn`. Применяет логику §17.4 (`shouldBlock`).
|
||
2. **Mode hot-reload.** Каждый tool-вызов перечитывает `~/.claude/runtime/router-gate-mode.json`. Заказчик может перевести `off` ↔ `warn-only` ↔ `enforce` без рестарта сессии.
|
||
3. **adr-judge.** При попытке Edit на нормативке (`Pravila_raboty_Claude_v1_1.md`, `docs/Plugin_stack_rules_v1.md`, `Tooling_v8_3.md`, `CLAUDE.md`) — adr-judge lefthook job pre-commit (job 9, см. `lefthook.yml`) проверяет, что новые правки не нарушают принятые ADR. ADR-016 декларирует «§17 заменяет §12»: попытка вернуть §12 в Pravila требует sup среды-ADR (опровергнуть/superseded).
|
||
4. **brain-retro discipline.** Раз в 1-2 недели `/brain-retro` skill читает episodes за период, считает sanity-check coverage (`disciplinePercentByClassification`, `routerStepReached`, `boundariesAppliedRate` из `tools/discipline-metrics.mjs`), сравнивает с предыдущим периодом. Расхождение > порога → сигнал в notes.
|
||
5. **STATUS.md C5.** `tools/observer-coverage-checker.mjs` (lefthook job 15, warn-only) считает missed-activations + observer registration; surface в `docs/observer/STATUS.md`.
|
||
|
||
## Rollback
|
||
|
||
Полный откат §17 → §12:
|
||
|
||
```bash
|
||
# 1. Restore user-level (settings.json with skill-marker/skill-check; runtime flags)
|
||
node tools/test-rollback.mjs --execute
|
||
|
||
# 2. Restore git-tracked (Pravila §12 + ADR-016 absent + router-tool-gate revert + lefthook + ...)
|
||
git reset --hard brain-pre-llm-bootstrap # tag at 9d4a30c3
|
||
|
||
# 3. Reinstall deps
|
||
npm install
|
||
```
|
||
|
||
ROLLBACK runbook: `docs/archive/llm-bootstrap-2026-05/ROLLBACK.md` (verified end-to-end in Phase 1 Task 1 smoke proof, commit `dc7fd579`).
|
||
|
||
## Cross-refs
|
||
|
||
- **Pravila §17** — текст правила (introduced this commit).
|
||
- **Pravila §16.4** — обновлено в Task 4 (commit `bca63fc6`) с cross-ref на nodes.yaml.
|
||
- **Pravila §12** — архивировано в Task 4 (`docs/archive/llm-bootstrap-2026-05/pravila-12/Pravila_section_12.md`).
|
||
- **ADR-011** brain-governance — §16 enforcement через 5 контролёров; ADR-016 опирается на observer evidence из ADR-011.
|
||
- **spec** `docs/superpowers/specs/2026-05-24-llm-first-router-overhaul-design.md` §6, §4.4.
|
||
- **plan** `docs/superpowers/plans/2026-05-25-llm-first-router-overhaul.md` Task 5.
|