diff --git a/cspell-words.txt b/cspell-words.txt index 9c1d160e..038349cc 100644 --- a/cspell-words.txt +++ b/cspell-words.txt @@ -1764,3 +1764,6 @@ unwired неизменён адаптер доктринально +маппингов +флаговая +мигрированы diff --git a/docs/Pravila_raboty_Claude_v1_1.md b/docs/Pravila_raboty_Claude_v1_1.md index 0d72b950..8329391b 100644 --- a/docs/Pravila_raboty_Claude_v1_1.md +++ b/docs/Pravila_raboty_Claude_v1_1.md @@ -1,10 +1,12 @@ # Правила работы Claude в проекте «Лидерра» -**Версия:** v1.40 (24.05.2026) -**Дата:** 24.05.2026 +**Версия:** v1.41 (25.05.2026) +**Дата:** 25.05.2026 **Назначение:** настройки проекта (Project instructions) — Claude читает этот файл в каждом чате и следует правилам ниже. **Статус документа:** ✅ утверждён. Содержимое скопировано в поле "Project instructions" Claude.ai. Файл хранится в архиве как служебный документ. +**Что изменилось в v1.41 относительно v1.40:** LLM-first router overhaul Phase 1 Tasks 4+5. **§12 «Superpowers hard rule» снят** (Task 4, commit `bca63fc6`) — полный текст в `docs/archive/llm-bootstrap-2026-05/pravila-12/Pravila_section_12.md`; §0 priority chain пересобран без §12 + добавлен «NB про §12» pointer на архив. **§17 «Universal skill-coverage rule» добавлен** (Task 5, this commit) — classifier-driven default-deny на non-conversation задачах, 5 exempt-классов §17.2, continuation НЕ exempt (D1, §17.3), enforcement через `tools/router-tool-gate.mjs` mode-flag `off/warn-only/enforce`. **§16.4 cross-refs мигрированы** (Task 4): tools/observer-classification-map.json + tools/.node-dormancy.json → docs/registry/nodes.yaml + buildClassificationMap / buildDormancyMap. **§16.5 hard-rule list:** §12 → §17. Архитектурное обоснование — **ADR-016** (new). Связано: 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. + **Что изменилось в v1.40 относительно v1.39:** Делегирование проектным AI-агентам — §2.4 (новая подсекция) описывает обязанность контроллера передавать класс задач 4 узко-специализированным агентам в `.claude/agents/`: `normative-sync` (#84, синк 4 нормативных файлов после крупной задачи), `prod-deploy-validator` (#85, 8 SSH pre-flight перед выкатом на liderra.ru), плюс прежние `pest-parallel-debugger` и `rls-reviewer`. Project-агенты регистрируются в `docs/registry/nodes.yaml` (subcategory `project-agent`) для missed-activation детектора, но **не входят в Tooling канон счётчиков** #1-#83 (footer-числа не двигаются). Архитектурных изменений §§1, §3–§16: 0. Связано: CLAUDE.md v2.28+ (§3.9), spec `docs/superpowers/specs/2026-05-24-controller-offload-agents-design.md`, agent files `.claude/agents/{normative-sync,prod-deploy-validator}.md`. **Что изменилось в v1.39 относительно v1.38:** C1 marketing-tooling — §13.2 +абзац «Off-phase marketing-tooling»: #74 marketing (Anthropic, первичный решатель C1), #75 marketingskills (вендорен MIT, материал/резерв), #76 brand-voice (Anthropic, вербальный бренд), #77 marketing-ru (self-authored project-скил, РФ-специфика + 152-ФЗ маркетинг), #78 Яндекс.Метрика MCP (READ-ONLY), #79 Яндекс.Директ+Wordstat MCP (**Wordstat-only**, Direct-мутации отключены per IS9), #80 Telegram MCP, #81 Postiz (self-host, AGPL-3.0 internal), #82 DataForSEO (**DEFERRED**, pending Б-1/бюджет), #83 Unisender Go (**DEFERRED**, pending согласования + 152-ФЗ). 18-я off-phase подкатегория, раздел C1. Не UI → вне R6.0/R6.1/R14. Границы — ADR-015. Счётчики — канон Tooling §0. Архитектурных изменений §§1–12, §14–§16: 0. Связано: Tooling v2.23+, PSR_v1 v3.22+, CLAUDE.md v2.27+; план `docs/superpowers/plans/2026-05-22-c1-marketing-tooling.md`. @@ -1003,6 +1005,46 @@ Enforcement — механический, не поведенческая про --- +## 17. Universal skill-coverage rule + +Введено 2026-05-25 как часть LLM-first router overhaul (Phase 1 Task 5). Замещает архивированное §12 «Superpowers hard rule» (см. `docs/archive/llm-bootstrap-2026-05/pravila-12/Pravila_section_12.md`). Архитектурное обоснование — [ADR-016](adr/ADR-016-section17-universal-skill-coverage.md). + +### 17.1. Принцип + +Все задачи, кроме явных `conversation`, `micro` или `manual_override`, должны быть покрыты skill или цепочкой из реестра `docs/registry/nodes.yaml`. Direct-исполнение допустимо только в 5 exempt-классах §17.2. + +### 17.2. Exempt-классы (когда direct OK) + +1. **Conversation** — короткие prompt'ы (length < 15 OR в `CONVERSATION_PATTERNS`) без anchor. +2. **Micro** — тривиальные правки (опечатка / переименование / format / bump). +3. **Manual override** — явное указание заказчика «делай через X». +4. **Acknowledgment / Cancellation** — короткие follow-up'ы без продолжения работы (обрабатываются prefilter'ом как conversation → direct OK). +5. **Escape-hatch** — `` в начале хода. + +### 17.3. Continuation НЕ exempt (D1) + +«Да», «делай», «дальше» и аналогичные коротыши **наследуют** классификацию предыдущего хода. Если та была non-conversation (feature / bugfix / refactor / planning / analysis / security / marketing / ...), §17 enforcement применяется как обычно — direct запрещён. `NON_BLOCKING_TASK_TYPES` в `tools/router-tool-gate.mjs` содержит только `conversation` / `micro` / `manual_override`; continuation там нет, и это **намеренно** (закрывает D1, см. ADR-016 §boundaries). + +### 17.4. Enforcement + +Через `tools/router-tool-gate.mjs` + классификатор `tools/router-classifier.mjs`. Mode читается из `~/.claude/runtime/router-gate-mode.json`: + +- `off` — гейт выключен (для отладки или отката). +- `warn-only` — нарушение инжектируется в context как warning, не блокирует tool-вызов. +- `enforce` — нарушение блокирует tool-вызов с reason. + +Default на момент Phase 2 bootstrap — `warn-only`; переход на `enforce` — отдельным решением заказчика после анализа baseline (см. ADR-016 §rollout). + +### 17.5. Статус + +§17 — **не hard-rule под §9 «Отступления»**, но его enforcement — механический хук, не tier-§13-правило. §9 формально применяется (заказчик может временно поднять mode → off через runtime-flag), но рационализация типа «эта задача проще, чем требует skill» не работает: гейт оперирует на классификаторе и цепочке, не на оценке Claude. Замещает §12 полностью — историческая ссылка `docs/archive/llm-bootstrap-2026-05/pravila-12/Pravila_section_12.md`. + +### 17.6. Связь с §16.4 + +Missed-activation в §16.4 — это симметричный отчёт о пропусках §17: эпизоды, где non-conversation задача исполнена `direct` без exempt-маркера. Surface в STATUS.md C5 + `/brain-retro`, не блокирует коммит — это сигнал для разбора, не enforcement. + +--- + ## Что сделано после утверждения Заказчик согласовал v1.1-DRAFT (короткий ответ «а» = вариант A: поправить §4.8 и шапку, выпустить v1.1) в сессии 05.05.2026. Claude выполнил: diff --git a/docs/adr/ADR-016-section17-universal-skill-coverage.md b/docs/adr/ADR-016-section17-universal-skill-coverage.md new file mode 100644 index 00000000..8049af30 --- /dev/null +++ b/docs/adr/ADR-016-section17-universal-skill-coverage.md @@ -0,0 +1,107 @@ +# 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 | +| `` в начале хода | Нет, escape-hatch | П.5 §17.2 | +| Q&A заказчика без действий над кодом | Нет, `conversation` | П.1 §17.2 | +| Опечатка в комментарии / переименование переменной | Нет, `micro` | П.2 §17.2 | +| `` без него | Да (но 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-.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. diff --git a/docs/observer/STATUS.md b/docs/observer/STATUS.md index 92a4ff91..0fb8546e 100644 --- a/docs/observer/STATUS.md +++ b/docs/observer/STATUS.md @@ -1,6 +1,6 @@ # Brain Status (auto-generated) -Last updated: 2026-05-25T06:41:50.879Z +Last updated: 2026-05-25T07:16:31.351Z | Контролёр | Состояние | Детали | |---|---|---|