liderra/brain
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
edea1ea40c187914de58a03a2d40df1dcd4bd839
brain/docs/adr/ADR-016-section17-universal-skill-coverage.md
T

14 KiB
Raw Blame History

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:

# 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.
Reference in New Issue View Git Blame Copy Permalink