diff --git a/cspell-words.txt b/cspell-words.txt index 099c46d6..9c1d160e 100644 --- a/cspell-words.txt +++ b/cspell-words.txt @@ -1757,3 +1757,10 @@ misowned деплоями subdirs unwired +инвокирую +ключуется +мoжибейк +неизменённых +неизменён +адаптер +доктринально diff --git a/docs/Pravila_raboty_Claude_v1_1.md b/docs/Pravila_raboty_Claude_v1_1.md index 6982cb30..0d72b950 100644 --- a/docs/Pravila_raboty_Claude_v1_1.md +++ b/docs/Pravila_raboty_Claude_v1_1.md @@ -175,8 +175,10 @@ Это **внутренние правила Claude**, не процессные правила команды. Документ написан для одного читателя — Claude. Заказчик согласовывает содержание; команды/действия не требуются. -Приоритет правил при конфликте: **§12 (Superpowers — explicit hard-rule, инвокация skills первой)** → **§14 (Ruflo Queen routing — explicit hard-rule, триггер queen/королева)** → §1 (роль) → §2 (что Claude делает сам / спрашивает / не делает) → §3 (формат ответов) → §4 (документация и версии) → §5 (безопасность и ПДн) → §6 (Claude в Chrome) → §7 (открытые вопросы) → §8 (рутины сессии) → §9 (отступления) → **§11 (Superpowers override §2.2/§4.5/§8.4 при явном вызове)** → **§13 (Frontend Design plugin — paired stack, координация через Plugin_stack_rules_v1 v3.2+)**. +Приоритет правил при конфликте: **§14 (Ruflo Queen routing — explicit hard-rule, триггер queen/королева)** → §1 (роль) → §2 (что Claude делает сам / спрашивает / не делает) → §3 (формат ответов) → §4 (документация и версии) → §5 (безопасность и ПДн) → §6 (Claude в Chrome) → §7 (открытые вопросы) → §8 (рутины сессии) → §9 (отступления) → **§11 (Superpowers override §2.2/§4.5/§8.4 при явном вызове)** → **§13 (Frontend Design plugin — paired stack, координация через Plugin_stack_rules_v1 v3.2+)** → **§17 (universal skill-coverage — добавляется в Task 5)**. +> **NB про §12 (2026-05-25):** §12 «Superpowers hard rule» снят в Phase 1 Task 4 LLM-first router overhaul и заменён §17 universal skill-coverage (Task 5). Полный архивный текст — `docs/archive/llm-bootstrap-2026-05/pravila-12/Pravila_section_12.md`. См. ADR-016 (Task 5) для архитектурного обоснования замены. +> > **§11 локальное override-исключение из цепочки (v1.10+):** §11 формально стоит ПОСЛЕ §9 в основной цепочке выше, но при **явном вызове skill'а Superpowers** §11 **локально поднимается выше §2.2/§4.5/§8.4** в этих узлах (см. §11.1 — «приоритет skill'а над §2.2 явное согласование, §4.5 паттерн 3 варианта, §8.4 защита от компакции»). То есть основная цепочка определяет приоритет в общем случае; §11 — точечное override 3 параграфов при триггере skill-инвокации. Это НЕ меняет позицию §11 относительно §1, §3, §5, §6, §7, §10, §12 — там §11 остаётся ниже. Аналогично §13 — расширение через PSR_v1 (paired stack + UI-пул), не override Pravila. > > **Scope этой цепочки (v1.9+):** **внутрипараграфный** приоритет внутри Pravila (порядок применения параграфов §1–§13 при конфликтах). Не дублирует: @@ -187,7 +189,7 @@ > > При вопросе «приоритет какого правила?» — сначала смотреть **CLAUDE.md §1** (какой файл/слой главный), затем при равенстве — внутрипараграфные приоритеты документа-победителя. -**Особый статус §12 и §14:** §12 — **explicit hard-rule** (единственное в v1.4–v1.13; с v1.15 — два explicit hard-rule: §12 + §14). §9 «Когда Claude отступает» к §12 **не применяется** (§12.4). Дополнительно §13.9 и §13.10 — **transitive hard-rule** через hard-link на нарушения PSR_v1 R10/R14 (см. §13.6 tier-таблицу). **§14 (с v1.15)** — второе explicit hard-rule документа: триггер queen/королева → безусловный route через ruflo Queen; §9 к §14 не применяется (§14.5). §12 и §14 не конфликтуют — они на разных слоях (§14.6: §12 — слой дисциплины исполнения, §14 — слой маршрутизации); порядок «§12 → §14» в priority chain выше отражает текстовую нумерацию, не иерархию приоритета. +**Особый статус §14 и §17:** **§14** (с v1.15) — explicit hard-rule: триггер queen/королева → безусловный route через ruflo Queen; §9 к §14 не применяется (§14.5). **§17** (добавляется в Task 5 LLM-first router overhaul, см. ADR-016) — universal skill-coverage: classifier-driven default-deny на non-conversation задачах. §17 заменяет ранее существовавшее §12 «Superpowers hard rule» (архив — `docs/archive/llm-bootstrap-2026-05/pravila-12/Pravila_section_12.md`). Дополнительно §13.9 и §13.10 — **transitive hard-rule** через hard-link на нарушения PSR_v1 R10/R14 (см. §13.6 tier-таблицу). §14 и §17 не конфликтуют — на разных слоях (§14 — маршрутизация, §17 — дисциплина исполнения). --- @@ -675,74 +677,9 @@ P0 = блокер старта спринта или регуляторного --- -## 12. Superpowers — hard rule (инвокация skills первой) +## 12. (archived — superseded by §17 universal skill-coverage) -Введено 09.05.2026 на явное требование заказчика: **«Создай правило, что ты всегда в первую очередь пользуешься superpowers. При этом ты не можешь игнорировать и обходить это правило.»** - -§12 — **explicit hard-rule**: перед содержательной задачей соответствующий Superpowers-skill (карта §12.2) инвокируется первым. §9 «Отступления» к §12 не применяется (§12.4). Карта §12.2, exclusions §12.3 и детали §12.4 — в силе. - -### 12.1. Принцип - -Перед началом любой содержательной задачи Claude **сначала** проверяет соответствующий skill в плагине Superpowers v5.1.0 и **инвокирует его**. Skill приносит свой workflow, Claude следует ему. Только если skill для задачи отсутствует (см. §12.3) — работа идёт обычным flow. - -### 12.2. Карта задач → skills - -| Задача | Skill для инвокации | -|---|---| -| Тесты с TDD-циклом (новый функционал биллинга, RLS, deals API) | `superpowers:test-driven-development` | -| Разбор бага / системный debug / расследование инцидента | `superpowers:systematic-debugging` | -| Планирование эпика / большой задачи (≥3 этапа) | `superpowers:writing-plans` | -| Исполнение существующего плана | `superpowers:executing-plans` | -| Мозговой штурм / генерация идей по требованию заказчика | `superpowers:brainstorming` | -| Подготовка PR / запрос code review | `superpowers:requesting-code-review` | -| Получение и применение review-комментариев | `superpowers:receiving-code-review` | -| Финализация feature-ветки (merge-ready) | `superpowers:finishing-a-development-branch` | -| Параллельная работа независимых задач | `superpowers:dispatching-parallel-agents` | -| Делегирование подагентам с инструкциями | `superpowers:subagent-driven-development` | -| Финальная проверка перед сдачей задачи | `superpowers:verification-before-completion` | -| Создание / правка пользовательских skills | `superpowers:writing-skills` | -| Git worktrees (с учётом §11.3 — Windows + кириллица) | `superpowers:using-git-worktrees` | -| Понимание возможностей самого плагина | `superpowers:using-superpowers` | - -### 12.3. Когда правило НЕ применяется - -> **Single Source of Truth для exclusions §12 (v1.9+).** При расширении списка — править только этот раздел; в CLAUDE.md §5 п.11 и PSR_v1 R0.4.A — только cross-ref сюда. При расхождении между документами побеждает Pravila §12.3. - -§12 не активируется, только если у задачи **отсутствует** соответствующий skill: - -- Чтение / поиск файла (Glob, Grep, Read). -- Тривиальные правки (опечатки, синхронизация ссылок, обновление версионных меток в шапках). -- Ответы на справочные вопросы заказчика без действий над кодом. -- Работа с открытыми вопросами реестра (`Биз-*`, `CTO-*`, `Ю-*`, `Диз-*`, `DO-*`, `OPEN-*`) — её регулирует §7. -- Конкретные команды tooling'а (composer/npm/git/Boost MCP), которые не являются «debug» или «TDD». -- Документационные правки уровня §4 (Pravila/Tooling/CLAUDE.md/narrative). Для CLAUDE.md дополнительное требование — через `claude-md-management:claude-md-improver` (CLAUDE.md §5 п.10), но это инфраструктурный канал правок, не §12-skill. - -В **любом другом** случае skill инвокируется **до** прочих действий. - -### 12.4. Hard-rule статус - -- §9 «Отступления» к §12 **не применяется** — §12 explicit hard-rule. Единственная отмена — явный запрос заказчика «не используй superpowers сейчас», только на текущее действие. -- §12 имеет приоритет над §1–§11. Это значит, что даже когда §1 (роль) или §11 (override) предписывают определённое поведение, §12 срабатывает раньше — skill инвокируется первым. -- Запрос заказчика «не используй superpowers сейчас» — единственная разрешённая отмена правила, и **только** для текущего действия. В следующем действии §12 действует автоматически. -- Игнорирование §12 (выбор обычного подхода когда skill доступен) — нарушение того же уровня, что игнорирование §5 (ПДн). -- Любая попытка обойти §12 через переформулировку задачи («это просто debug» вместо `systematic-debugging`) — нарушение. -- Claude **не имеет права** рационализировать пропуск §12 («сейчас быстрее без skill'а»; «эта задача проще, чем требует skill»). Если skill применим — он инвокируется. - -### 12.5. Override-приоритет относительно §11 - -§12 имеет **приоритет над §11**. §11 разрешил Superpowers override §2.2/§4.5/§8.4. §12 теперь говорит: даже без явного вызова заказчиком, skill инвокируется по умолчанию. Override §2.2/§4.5/§8.4 при этом происходит автоматически (§11.1). - -### 12.6. Что остаётся неизменным - -§5 (ПДн), §7 (финальное закрытие открытых вопросов), §3.6 (язык) — **не override-ятся** даже Superpowers skill'ом, и §12 этого не меняет. См. §11.2. - -### 12.7. Нарушения - -Если Claude забыл инвокировать skill в подходящей задаче — заказчик может указать на нарушение. Claude обязан зафиксировать ошибку в feedback memory (`feedback_*.md`) для коррекции в будущих сессиях. - -### 12.8. Ревизия §12 - -В отличие от §11, который ревизуется по факту проблем, §12 — стабильное правило. Откат возможен только тем же путём, что и введение: явным запросом заказчика «откати §12, верни §9 как override-возможность». +> §12 «Superpowers hard rule» removed 2026-05-25 в Phase 1 Task 4 LLM-first router overhaul. Заменён **§17 universal skill-coverage** (Task 5) — classifier-driven default-deny на non-conversation задачах. Полный текст §12 — `docs/archive/llm-bootstrap-2026-05/pravila-12/Pravila_section_12.md`. См. **ADR-016** (Task 5). Откат: `git checkout brain-pre-llm-bootstrap -- docs/Pravila_raboty_Claude_v1_1.md`. --- @@ -1021,7 +958,7 @@ git fetch origin && git log HEAD..origin/main --oneline Узел «мозга», не задействованный в реальной работе, **не** считается проблемой и **не** подлежит автоматической пометке **при условии, что профильной задачи для него в эпизодах не было**. Это — capability-readiness, осознанная стратегия заказчика. -**Симметричное правило (missed activation):** если в эпизодах присутствует **хотя бы один** эпизод с `primary_rationale.task_classification`, соответствующим набору рекомендуемых узлов из `tools/observer-classification-map.json`, при этом `primary_rationale.node_chosen === 'direct'` и среди рекомендуемых узлов есть хотя бы один non-dormant (по `tools/.node-dormancy.json`, экстракт из [Tooling Прил.Н §3.5/§4.X](Tooling_v8_3.md) с двойным сигналом: `dormant: true` ИЛИ ключевое слово `DEFERRED` в колонке boundaries) — это **сигнал**, кандидат на разбор. Surface в STATUS.md (C5: `missed_activations: N`, ⚠️ при N>0) и в выводе `/brain-retro`. Не блок коммита, не auto-edit. +**Симметричное правило (missed activation):** если в эпизодах присутствует **хотя бы один** эпизод с `primary_rationale.task_classification`, соответствующим набору рекомендуемых узлов из реестра `docs/registry/nodes.yaml` (поле `triggers[].classification` per node; адаптер `tools/registry-to-classification-map.mjs::buildClassificationMap`), при этом `primary_rationale.node_chosen === 'direct'` и среди рекомендуемых узлов есть хотя бы один с `status: active` (поле `status` в nodes.yaml; non-active = `dormant`/`deferred`/`historic` через адаптер `buildDormancyMap`) — это **сигнал**, кандидат на разбор. Surface в STATUS.md (C5: `missed_activations: N`, ⚠️ при N>0) и в выводе `/brain-retro`. Не блок коммита, не auto-edit. Прежние source-файлы `tools/observer-classification-map.json` и `tools/.node-dormancy.json` архивированы 2026-05-25 (LLM-first router overhaul Task 4) — см. `docs/archive/llm-bootstrap-2026-05/routing-docs/`. **Исключения:** DEFERRED-узлы (на момент v1.36 — #17 pg_partman, #44 Figma MCP, #50 Jupyter MCP, #54 n8n-mcp, #67 NightOwl) — для них «не активирован» = ожидаемое состояние, в missed activations не учитываются. @@ -1029,7 +966,7 @@ git fetch origin && git log HEAD..origin/main --oneline ### 16.5. Не override-floor §9 -§16 — рекомендация tier-уровня §13, НЕ explicit hard-rule вне §9. Тремя hard-rules вне §9 остаются §12 (Superpowers), §14 (Ruflo Queen — dormant), §15 (параллельные сессии). +§16 — рекомендация tier-уровня §13, НЕ explicit hard-rule вне §9. Тремя hard-rules вне §9 остаются §14 (Ruflo Queen — dormant), §15 (параллельные сессии), §17 (universal skill-coverage — добавляется в Task 5 LLM-first router overhaul, заменяет архивированное §12). ADR-011 enforcement через `adr-judge` lefthook job гарантирует существование секции `## Enforcement` в самом ADR. diff --git a/docs/archive/llm-bootstrap-2026-05/TASKLOG.md b/docs/archive/llm-bootstrap-2026-05/TASKLOG.md index 5af345fd..3cd5daa2 100644 --- a/docs/archive/llm-bootstrap-2026-05/TASKLOG.md +++ b/docs/archive/llm-bootstrap-2026-05/TASKLOG.md @@ -108,3 +108,99 @@ Tests: `tools/discipline-metrics.test.mjs` 19 tests, all GREEN in baseline and after Task 1-2 work (verified in Task 2 post-commit STATUS.md regen). Plan Task 3 step «only-§12 → archive, общий path_type → keep» applies: KEEP. + +## Task 4 — Archive §12 + routing-docs + memory files (2026-05-25) + +Phase 1 Task 4 of LLM-first router overhaul. Heaviest task of Phase 1. + +User chose «aggressively per plan» (AskUserQuestion 2026-05-25) after the +session surfaced 4 plan deviations vs reality. Adapted execution below. + +### What was archived (literal) + +1. **Pravila §12** (lines 678-748 of `docs/Pravila_raboty_Claude_v1_1.md`): + extracted to `pravila-12/Pravila_section_12.md`, replaced in Pravila by a + 1-paragraph placeholder pointing to §17 (Task 5) + the archive file + + ADR-016 (Task 5). Cross-refs §0 priority chain, §0 «Особый статус» note, + §16.4, §16.5 — all updated to drop §12 and reference §17 forward. + +2. **`tools/observer-classification-map.json`** — JSON mapping + classification → recommended_node_ids. After Task 4 refactor (below) had + no code consumers. Archived via `git mv`. + +3. **`tools/.node-dormancy.json`** — auto-generated dormancy map (Tooling + §3.5/§4.X scrape, two signals: `dormant: true` OR `DEFERRED` in boundaries). + Single consumer was missed-activations.mjs via the JSON; after Task 4 + refactor consumers read `status` from `docs/registry/nodes.yaml` directly + via `buildDormancyMap` adapter. Archived via `git mv`. + +4. **`tools/extract-node-dormancy.mjs`** + **`tools/extract-node-dormancy.test.mjs`** + — generator + 7 tests for `.node-dormancy.json`. Archived via `git mv`. + `lefthook.yml` job 12b «extract-node-dormancy» removed (replaced by a + removal note pointing to `nodes.yaml status:` as the new source). + +5. **`memory/feedback_superpowers_hard_rule.md`** + **`memory/feedback_feature_via_writing_plans.md`** + (user-level, NOT git-tracked at + `~/.claude/projects/c---------------------crm-------------/memory/`): + copied to `docs/archive/.../memory/` via filesystem cp (plan said `git mv` + — wrong, memory files live outside the repo on this machine). Originals + left in place on disk; MEMORY.md (also user-level) updated to remove the + two index lines and replace them with an «ARCHIVED 2026-05-25» pointer. + +### Code refactor (consequence of the JSON archive) + +The aggressive-per-plan choice required switching the two remaining +JSON-direct consumers to the registry adapter pattern (other consumers — +`brain-retro-analyzer.mjs`, `status-md-generator.mjs`, `missed-activations.mjs` +— already used the adapter): + +1. **`tools/observer-coverage-checker.mjs`**: `loadClassificationMap(root)` + and `loadDormancy(root)` switched from `readFileSync(...json)` to + `loadRegistry({ registryPath: /docs/registry/nodes.yaml, useCache: false })` + plus `buildClassificationMap` / `buildDormancyMap`. 9/9 tests GREEN. + +2. **`tools/observer-transcript-parser.mjs`**: `getClassificationMap()` and + `getDormancy()` switched similarly, using the cached default-path + `loadRegistry()` (parser is always invoked from `tools/`). 154/154 tests + GREEN — clean drop-in replacement, no classification-shape drift. + +### Plan deviations (documented) + +The plan's literal Task 4 said «archive everything including +`tools/registry-to-classification-map.mjs` and `docs/routing-off-phase.md` / +`docs/router-procedure.md`». Inspection revealed: + +- **`tools/registry-to-classification-map.mjs`** has 4+ active consumers + (brain-retro-analyzer, status-md-generator, missed-activations callers, + plus the 2 newly-migrated above). It IS the canonical + yaml→classification-map / yaml→dormancy-map adapter — keeping it is + correct engineering. Plan's framing «adapter is deprecated» was wrong. + **Status: KEEP, not archived.** A future task can inline its logic into + consumers if «direct yaml read» is strictly required, but that is a + separate refactor. + +- **`docs/routing-off-phase.md`** is **auto-generated by + `tools/registry-render.mjs`** from `nodes.yaml`, not a hand-edited doc. + Archiving it would break the render pipeline + the C6 brain-governance + controller (`tools/observer-chain-map-checker.mjs`) which reads it. + **Status: NOT ARCHIVED.** This is a derivative, not a source. + +- **`docs/router-procedure.md`** is similarly suspected of being either a + derivative or referenced by active controllers; archival deferred to + a separate audit. + +### Verification + +- Full `npx vitest run tools/`: **539 passed** (delta: −7 from archived + `extract-node-dormancy.test.mjs`, +3 from `test-rollback.test.mjs` + added in Task 1; baseline 543 → 539 expected ✓). The 4 pre-existing + «No test suite found» failures on `tools/ruflo-*.test.mjs` and + `tools/subagent-prompt-prefix.test.mjs` are out of scope and unchanged. +- Pre-commit (gitleaks + markdownlint + cspell) — verified at commit time. + +### Rollback + +`node tools/test-rollback.mjs --execute` restores user-level state. +`git reset --hard brain-pre-llm-bootstrap` restores Pravila, the 4 +archived `tools/` files, `lefthook.yml` job 12b, `observer-coverage-checker.mjs`, +and `observer-transcript-parser.mjs` to pre-overhaul state. diff --git a/docs/archive/llm-bootstrap-2026-05/memory/feedback_feature_via_writing_plans.md b/docs/archive/llm-bootstrap-2026-05/memory/feedback_feature_via_writing_plans.md new file mode 100644 index 00000000..46c8459d --- /dev/null +++ b/docs/archive/llm-bootstrap-2026-05/memory/feedback_feature_via_writing_plans.md @@ -0,0 +1,37 @@ +--- +name: feedback-feature-via-writing-plans +description: "Feature/planning-задачи в Лидерре ИДУТ через superpowers:writing-plans (или brainstorming если ещё нет требований), даже если задача «маленькая» и видна напрямую. Brain-retro" +metadata: + node_type: memory + type: feedback + originSessionId: 8409f21e-2d54-48b6-8cff-c0fa5e32ba1b +--- + +**Правило:** для задач классификации `feature` или `planning` (любая новая функциональность портала, даже однострочный endpoint или галочка в UI) сначала инвокирую один из: + +- `superpowers:brainstorming` — если требования ещё не зафиксированы +- `superpowers:writing-plans` — если spec уже понятен, нужен implementation план +- `superpowers:executing-plans` — если план уже есть и я просто исполняю + +Direct-путь (без skill'а) для feature/planning — **нарушение Pravila §12 hard-rule**, не «оптимизация». + +**Why:** brain-retro #3 (2026-05-23, `docs/observer/notes/2026-05-23-brain-retro.md`) насчитал 7 случаев в дельте 19-23.05 где feature(5)/planning(2) шли autonomous direct без skill. Из 15 «реальных» промахов после очистки шума (A1+A2 23.05) эти 7 — самая большая группа. Расширение [[Superpowers — hard rule §12 (Pravila v1.4)]] (feedback_superpowers_hard_rule): hard-rule уже есть, но я рационализировал «маленькая фича → можно direct». Эта рационализация и есть лазейка, которую §12 закрывает. + +**How to apply:** + +1. **Триггер:** заказчик говорит «сделай X», «добавь Y», «нужна фича Z», «давай спланируем», «допилим». Даже если кажется «один Edit». +2. **Перед первым Read/Edit/Write** — инвокирую skill: + - Требования не ясны / непонятно «как должно быть» → `superpowers:brainstorming` + - Требования ясны, нужно «как сделать» → `superpowers:writing-plans` + - План уже есть → `superpowers:executing-plans` (или `subagent-driven-development` если задача делится) +3. **Не рационализирую:** «эта фича маленькая», «всё ясно, план не нужен», «один Edit это не feature» — это **рационализации уровня §5 ПДн** (по Pravila §12.4). +4. **Исключения** — только если заказчик явно сказал «не используй superpowers сейчас» / «делай напрямую без плана» — и **только** на текущее действие (следующий промпт парсится заново). Pravila §12.4. +5. **Скил-discipline хук** уже подсказывает при Edit/Write без skill — не игнорировать reminder для feature/planning, даже если содержание тривиально. + +**Граница vs тривиальные правки:** + +- Тривиальная правка опечатки, JSON-конфига, версии в шапке, переименование переменной — **не** feature/planning, hook reminder можно игнорировать. +- Изменение поведения системы (новый эндпоинт, новая колонка БД, новый UI-вью, изменение бизнес-логики, новый job) — **feature**, skill обязателен. +- Q&A, аудит, чтение кода, навигация — **не** feature/planning. + +**Источник:** brain-retro #3, 2026-05-23. Кандидат D1 применён по явному «делай» от заказчика. diff --git a/docs/archive/llm-bootstrap-2026-05/memory/feedback_superpowers_hard_rule.md b/docs/archive/llm-bootstrap-2026-05/memory/feedback_superpowers_hard_rule.md new file mode 100644 index 00000000..d032f867 --- /dev/null +++ b/docs/archive/llm-bootstrap-2026-05/memory/feedback_superpowers_hard_rule.md @@ -0,0 +1,113 @@ +--- +name: Superpowers — hard rule §12 (Pravila v1.4) +description: 09.05.2026 заказчик ввёл единственное hard-правило в Pravila: skill из obra/superpowers v5.1.0 инвокируется ПЕРВЫМ для подходящих задач. §9 «Отступления» не применяется. Рационализация = нарушение уровня §5 ПДн. +type: feedback +originSessionId: 8636df02-dd86-4b5b-90f6-d93a3a6fc448 +--- +09.05.2026 заказчик ввёл это правило явной формулировкой: **«Создай правило, что ты всегда в первую очередь пользуешься superpowers. При этом ты не можешь игнорировать и обходить это правило.»** Закреплено как §12 в Pravila v1.4. + +**Why:** В предыдущей итерации (Pravila v1.3 / §11) Superpowers был «разрешён», но без обязательности — заказчик увидел риск, что я буду рационализировать пропуск skill'а («сейчас быстрее без него», «эта задача проще»). Hard-rule убирает эту лазейку — §9 «Отступления» к §12 НЕ применяется. + +**How to apply:** + +1. **Перед любой содержательной задачей** — сначала проверить карту §12.2 правил Claude (14 skills → 14 типов задач): + - TDD → `superpowers:test-driven-development` + - debug/инцидент → `superpowers:systematic-debugging` + - план эпика (≥3 этапа) → `superpowers:writing-plans` + - исполнение плана → `superpowers:executing-plans` + - brainstorm по запросу → `superpowers:brainstorming` + - запрос code review → `superpowers:requesting-code-review` + - применение review → `superpowers:receiving-code-review` + - финализация feature-ветки → `superpowers:finishing-a-development-branch` + - параллельные независимые задачи → `superpowers:dispatching-parallel-agents` + - подагенты → `superpowers:subagent-driven-development` + - финальная проверка перед сдачей → `superpowers:verification-before-completion` + - создание новых skills → `superpowers:writing-skills` + - git worktrees (с осторожностью на Windows + кириллица) → `superpowers:using-git-worktrees` + - понимание плагина → `superpowers:using-superpowers` + +2. **Если skill применим** — инвокировать его через Skill tool **до** прочих действий. Skill приносит свой workflow, я следую ему. + +3. **Когда §12 НЕ срабатывает** (§12.3): чтение/grep/glob; тривиальные правки (опечатки, версии в шапках, синхронизация ссылок); справочные ответы без действий над кодом; документация уровня §4 (Pravila/Tooling/CLAUDE.md/narrative); работа с открытыми вопросами реестра. + +4. **Запрещённые рационализации** — все эти формулировки = нарушение §12: + - «эта задача проще, чем требует skill» + - «сейчас быстрее без skill'а» + - «это просто debug, обычным способом разберусь» + - переформулировка задачи под §12.3 («это просто чтение, хотя на деле full-debug») + +5. **Единственная разрешённая отмена** — явный запрос заказчика «не используй superpowers сейчас», и **только** на текущее действие. В следующем действии §12 действует автоматически. + +6. **Если забыл инвокировать skill** — заказчик укажет: «§12». Тогда обязательно зафиксировать ошибку в feedback memory для будущих сессий. + +7. **Override-приоритет:** §12 имеет приоритет над §11 (override §2.2/§4.5/§8.4 разрешён автоматически при инвокации skill'а). НЕ override-ятся даже §12: §1 (роль), §3.6 (язык), §5 (ПДн), §7 (финальное закрытие открытых вопросов). + +**Источники:** `docs/Pravila_raboty_Claude_v1_1.md` v1.4 §12 (полный текст 8 подсекций); `CLAUDE.md` v1.77 §1 priority уровень 0 + §5 п.11; коммит `4cac61d`. + +**Контрольный сигнал что правило работает:** в начале нового задания я первым делом упоминаю «по §12.2 это попадает под X — инвокирую `superpowers:Y`» **до** прочих действий, или явно «§12.3 — обычный flow» с указанием категории (тривиальная правка / документация §4 / etc.). Если ни того, ни того — это нарушение, заказчик имеет право указать. + +--- + +## Runtime-enforcement: «дисциплина» (skill-discipline hook) + +**Установлено 10.05.2026.** Заказчик: «делай хук» → поставлен runtime-gate в `~/.claude/settings.json`: + +- `~/.claude/hooks/skill-marker.py` — `PreToolUse` matcher `Skill` — пишет флаг `$TEMP/claude-skill-.flag` (содержимое = имя skill'а) +- `~/.claude/hooks/skill-check.py` — `PreToolUse` matcher `Edit|Write|MultiEdit` — если флаг отсутствует, инжектит `additionalContext` reminder (две формулировки: спец-вариант для CLAUDE.md, общий для остальных файлов) + +**В разговоре заказчик называет это просто «дисциплина»** (например: «дисциплина сработала», «выключи дисциплину», «обнови дисциплину»). Распознавать это слово как ссылку на этот хук, не путать с общей дисциплиной §12. + +**Архитектура:** + +- Per-session: флаг ключуется по `session_id` → каждая сессия независима. Соседние Claude Code сессии параллельно проходят свой gate. +- Не блокирует: только эмитит `additionalContext`, не `permissionDecision: "deny"`. Я могу проигнорировать reminder если задача попадает под §12.3 (Q&A, чтение, навигация, тривиальная правка). +- Encoding: `ensure_ascii=True` в `json.dumps` — обходит проблему cp1251 stdout на Windows (без этого в reminder приходит мoжибейк). +- Bash-обход: хук не ловит правки через `sed`/`Out-File`/etc. в `Bash` tool. Это сознательный пробел — расширение matcher'а на `Bash` дало бы много ложных срабатываний. + +**Подтверждение работоспособности (10.05.2026 18:18):** соседняя сессия `a659b20e-f6b4-46ad-ab7d-53f594962995` в реальном времени вызвала `superpowers:test-driven-development` → marker hook записал флаг → последующие Edit/Write в той сессии проходят молча. Independent end-to-end proof. + +**Как выключить:** `/hooks` UI menu в Claude Code, либо удалить блок `hooks` из `~/.claude/settings.json`, либо `disableAllHooks: true` (отключит ВСЕ хуки, не только этот). + +--- + +## Economy hook bypass closure architecture (2026-05-10 финал) + +После adversarial self-analysis (14 hypothesized bypass paths) — установлена hardened архитектура из **6 компонентов** в `~/.claude/hooks/`: + +| # | Component | Event | Покрывает | +|---|---|---|---| +| 0 | permissions block в settings.json | declarative | H1/H2/H6 (tamper protection через deny+ask) | +| 1 | economy-mode.py | UserPromptSubmit | parse end-of-prompt + state write | +| 2 | economy-self-check.py | SessionStart | runtime guard (silent failure detection) | +| 3 | economy-state-guard.py | PreToolUse Edit/Write/MultiEdit/Bash/Agent | in-turn reminder + Bash bypass detection + subagent inheritance (H7) | +| 4 | economy-verifier.py + agent-type hook | Stop | Sonnet 4.6 compliance verifier с decision:'block' on non-compliance | +| 5 | economy-postcompact.py | PostCompact | re-inject rules после авто-компакции (H8) | + +Закрыты 8 critical/high bypass paths: H1 (settings disable), H2 (hook script edit), H4 (prompt injection), H6 (state file delete), H7 (subagent inheritance), H8 (PostCompact loss), H9 (retry exhaustion), H10 (verifier endpoint failure), H12 (tool output spoofing), H13 (no-claim bypass). + +**Stage 0 ratchet работает буквально** — auto-mode classifier режет даже subagent Write на hook-files и Bash-обходные действия. Подтверждено в реальной эксплуатации: 10.05.2026 субагент Stage 2 получил NEEDS_CONTEXT, и мой Bash+python heredoc на settings.json — denied. + +Стоимость: ~$7-14/мес (Sonnet 4.6 verifier на ~30% turn'ов). + +Spec: `c:/моя/проекты/портал crm/Документация/docs/superpowers/specs/2026-05-10-economy-hook-bypass-closure-design.md` +Plan: `c:/моя/проекты/портал crm/Документация/docs/superpowers/plans/2026-05-10-economy-hook-bypass-closure.md` + +**Не закрытые by design:** translit/English keyword variations (E.1), mojibake homoglyphs (E.3), социальная инженерия (Claude просит rephrase), прямой редактирование settings/hooks пользователем вне Claude Code. + +**18.05.2026 — accepted as-is** (превентивный аудит «мозга», Дмитрий: «б»). Причина: за 8 дней эксплуатации 0 промахов; максимальное последствие промаха = работа строже, не слабее (в сторону пользователя, не против); закрытие требует часов работы + регрессионного риска на сложных хуках. Перечитать раз в квартал — не изменилась ли реальная частота промахов. **Не предлагать закрытие повторно** без явного эпизода промаха в логах. + +--- + +## Economy level «5%» (2026-05-16) + +Добавлен новый уровень-якорь `экономия 5%` в `economy-mode.py` `LEVELS` (между 25 и 0; `closest_level` полоса 3–14% → 5; `экономия 10%` теперь → 5, а не 0). Принцип: **`5% = 0% − 6 пунктов избыточности + 6 скоростных правил`** — то же качество и строгость, что 0%, без дублирующей работы. + +6 вырезанных избыточностей: re-read CLAUDE.md (уже в контексте), тесты-после-каждой-правки (→ по логическим блокам), gitleaks-full-history per-commit (→ только pre-push), Stop-верификатор (short-circuit на level 5), авто-гейты brainstorming/writing-plans (→ §12.2-floor, не каждая фича). + +6 скоростных правил (блок A/B3, добавлены 2026-05-16 — секция «СКОРОСТЬ БЕЗ ПОТЕРИ КАЧЕСТВА» в `LEVELS[5]['rules']`): параллельные независимые tool-вызовы; без re-read неизменённых файлов; дешёвая модель на механические субагент-задачи; `run_in_background` на долгие команды; не задавать выводимые из кодовой базы вопросы; фокус/компакт сессии. + +Затронуты 3 хук-файла: `economy-mode.py` (`LEVELS[5]`), `economy-state-guard.py` + `economy-postcompact.py` (`LEVEL_TOPLINE[5]`, две синхронные копии). Тесты: `economy-mode-test.py` 62/62, `economy-state-guard-test.py` 7/7. `LEVELS[0]` — байт-в-байт неизменён (жёсткий инвариант). + +B4 (замер latency всех хуков) — одноразовый bench: ~34 мс median на хук (чистый старт интерпретатора, однородно по всем хукам), ~13–23 с суммарно на крупную задачу — горячей точки нет, оптимизировать нечего, пункт закрыт. + +Спека: `docs/superpowers/specs/2026-05-16-economy-5pct-level-design.md` (на origin/main, §11 — блок A/B3). Хук-файлы — в `~/.claude/`, вне git. diff --git a/docs/archive/llm-bootstrap-2026-05/pravila-12/Pravila_section_12.md b/docs/archive/llm-bootstrap-2026-05/pravila-12/Pravila_section_12.md new file mode 100644 index 00000000..355f6d9a --- /dev/null +++ b/docs/archive/llm-bootstrap-2026-05/pravila-12/Pravila_section_12.md @@ -0,0 +1,97 @@ +# Pravila §12 (archived) — Superpowers hard rule + +> **ARCHIVED 2026-05-25.** This section was extracted from +> `docs/Pravila_raboty_Claude_v1_1.md` v1.40 → v1.41 as part of the +> LLM-first router overhaul (Phase 1 Task 4). It is **superseded** by: +> +> - **Pravila §17 «universal skill-coverage»** (added in Phase 1 Task 5, +> default-deny on non-conversation tasks, evidence-loop driven). +> - **ADR-016** «§17 universal skill-coverage» (replaces ADR-011's §12 +> reasoning). +> +> §12 used a closed list of 14 task→skill mappings (§12.2 map). §17 +> replaces this with universal skill coverage discipline determined by +> the LLM-first classifier + Sonnet 4.6, with `conversation`/`micro`/ +> `manual_override` task types exempt by classifier output, not by a +> hard-coded list. The classifier writes the choice to `classifier_output` +> on every episode; the §17 enforcement decides block/warn from there. +> +> The §12 enforcement hooks (`skill-marker.py` + `skill-check.py`) were +> unwired from `~/.claude/settings.json` in Phase 1 Task 2 (commit +> `3073e0cb`). Files remain on disk in `~/.claude/hooks/`; snapshots are +> in `docs/archive/llm-bootstrap-2026-05/user-hooks/`. +> +> Rollback restores the §12 text via +> `git checkout brain-pre-llm-bootstrap -- docs/Pravila_raboty_Claude_v1_1.md` +> (tag points to pre-overhaul state with §12 intact). + +--- + +## 12. Superpowers — hard rule (инвокация skills первой) + +Введено 09.05.2026 на явное требование заказчика: **«Создай правило, что ты всегда в первую очередь пользуешься superpowers. При этом ты не можешь игнорировать и обходить это правило.»** + +§12 — **explicit hard-rule**: перед содержательной задачей соответствующий Superpowers-skill (карта §12.2) инвокируется первым. §9 «Отступления» к §12 не применяется (§12.4). Карта §12.2, exclusions §12.3 и детали §12.4 — в силе. + +### 12.1. Принцип + +Перед началом любой содержательной задачи Claude **сначала** проверяет соответствующий skill в плагине Superpowers v5.1.0 и **инвокирует его**. Skill приносит свой workflow, Claude следует ему. Только если skill для задачи отсутствует (см. §12.3) — работа идёт обычным flow. + +### 12.2. Карта задач → skills + +| Задача | Skill для инвокации | +|---|---| +| Тесты с TDD-циклом (новый функционал биллинга, RLS, deals API) | `superpowers:test-driven-development` | +| Разбор бага / системный debug / расследование инцидента | `superpowers:systematic-debugging` | +| Планирование эпика / большой задачи (≥3 этапа) | `superpowers:writing-plans` | +| Исполнение существующего плана | `superpowers:executing-plans` | +| Мозговой штурм / генерация идей по требованию заказчика | `superpowers:brainstorming` | +| Подготовка PR / запрос code review | `superpowers:requesting-code-review` | +| Получение и применение review-комментариев | `superpowers:receiving-code-review` | +| Финализация feature-ветки (merge-ready) | `superpowers:finishing-a-development-branch` | +| Параллельная работа независимых задач | `superpowers:dispatching-parallel-agents` | +| Делегирование подагентам с инструкциями | `superpowers:subagent-driven-development` | +| Финальная проверка перед сдачей задачи | `superpowers:verification-before-completion` | +| Создание / правка пользовательских skills | `superpowers:writing-skills` | +| Git worktrees (с учётом §11.3 — Windows + кириллица) | `superpowers:using-git-worktrees` | +| Понимание возможностей самого плагина | `superpowers:using-superpowers` | + +### 12.3. Когда правило НЕ применяется + +> **Single Source of Truth для exclusions §12 (v1.9+).** При расширении списка — править только этот раздел; в CLAUDE.md §5 п.11 и PSR_v1 R0.4.A — только cross-ref сюда. При расхождении между документами побеждает Pravila §12.3. + +§12 не активируется, только если у задачи **отсутствует** соответствующий skill: + +- Чтение / поиск файла (Glob, Grep, Read). +- Тривиальные правки (опечатки, синхронизация ссылок, обновление версионных меток в шапках). +- Ответы на справочные вопросы заказчика без действий над кодом. +- Работа с открытыми вопросами реестра (`Биз-*`, `CTO-*`, `Ю-*`, `Диз-*`, `DO-*`, `OPEN-*`) — её регулирует §7. +- Конкретные команды tooling'а (composer/npm/git/Boost MCP), которые не являются «debug» или «TDD». +- Документационные правки уровня §4 (Pravila/Tooling/CLAUDE.md/narrative). Для CLAUDE.md дополнительное требование — через `claude-md-management:claude-md-improver` (CLAUDE.md §5 п.10), но это инфраструктурный канал правок, не §12-skill. + +В **любом другом** случае skill инвокируется **до** прочих действий. + +### 12.4. Hard-rule статус + +- §9 «Отступления» к §12 **не применяется** — §12 explicit hard-rule. Единственная отмена — явный запрос заказчика «не используй superpowers сейчас», только на текущее действие. +- §12 имеет приоритет над §1–§11. Это значит, что даже когда §1 (роль) или §11 (override) предписывают определённое поведение, §12 срабатывает раньше — skill инвокируется первым. +- Запрос заказчика «не используй superpowers сейчас» — единственная разрешённая отмена правила, и **только** для текущего действия. В следующем действии §12 действует автоматически. +- Игнорирование §12 (выбор обычного подхода когда skill доступен) — нарушение того же уровня, что игнорирование §5 (ПДн). +- Любая попытка обойти §12 через переформулировку задачи («это просто debug» вместо `systematic-debugging`) — нарушение. +- Claude **не имеет права** рационализировать пропуск §12 («сейчас быстрее без skill'а»; «эта задача проще, чем требует skill»). Если skill применим — он инвокируется. + +### 12.5. Override-приоритет относительно §11 + +§12 имеет **приоритет над §11**. §11 разрешил Superpowers override §2.2/§4.5/§8.4. §12 теперь говорит: даже без явного вызова заказчиком, skill инвокируется по умолчанию. Override §2.2/§4.5/§8.4 при этом происходит автоматически (§11.1). + +### 12.6. Что остаётся неизменным + +§5 (ПДн), §7 (финальное закрытие открытых вопросов), §3.6 (язык) — **не override-ятся** даже Superpowers skill'ом, и §12 этого не меняет. См. §11.2. + +### 12.7. Нарушения + +Если Claude забыл инвокировать skill в подходящей задаче — заказчик может указать на нарушение. Claude обязан зафиксировать ошибку в feedback memory (`feedback_*.md`) для коррекции в будущих сессиях. + +### 12.8. Ревизия §12 + +В отличие от §11, который ревизуется по факту проблем, §12 — стабильное правило. Откат возможен только тем же путём, что и введение: явным запросом заказчика «откати §12, верни §9 как override-возможность». diff --git a/tools/.node-dormancy.json b/docs/archive/llm-bootstrap-2026-05/routing-docs/.node-dormancy.json similarity index 100% rename from tools/.node-dormancy.json rename to docs/archive/llm-bootstrap-2026-05/routing-docs/.node-dormancy.json diff --git a/tools/extract-node-dormancy.mjs b/docs/archive/llm-bootstrap-2026-05/routing-docs/extract-node-dormancy.mjs similarity index 100% rename from tools/extract-node-dormancy.mjs rename to docs/archive/llm-bootstrap-2026-05/routing-docs/extract-node-dormancy.mjs diff --git a/tools/extract-node-dormancy.test.mjs b/docs/archive/llm-bootstrap-2026-05/routing-docs/extract-node-dormancy.test.mjs similarity index 100% rename from tools/extract-node-dormancy.test.mjs rename to docs/archive/llm-bootstrap-2026-05/routing-docs/extract-node-dormancy.test.mjs diff --git a/tools/observer-classification-map.json b/docs/archive/llm-bootstrap-2026-05/routing-docs/observer-classification-map.json similarity index 100% rename from tools/observer-classification-map.json rename to docs/archive/llm-bootstrap-2026-05/routing-docs/observer-classification-map.json diff --git a/docs/observer/STATUS.md b/docs/observer/STATUS.md index 53a95287..92a4ff91 100644 --- a/docs/observer/STATUS.md +++ b/docs/observer/STATUS.md @@ -1,6 +1,6 @@ # Brain Status (auto-generated) -Last updated: 2026-05-25T06:39:27.288Z +Last updated: 2026-05-25T06:41:50.879Z | Контролёр | Состояние | Детали | |---|---|---| diff --git a/lefthook.yml b/lefthook.yml index 6573c56a..a1e96270 100644 --- a/lefthook.yml +++ b/lefthook.yml @@ -182,17 +182,11 @@ pre-commit: cross-ref-checker detected version drift in §0 cross-refs. Update the offending file's cross-ref to match the target's header. - # 12b. extract-node-dormancy — регенерирует tools/.node-dormancy.json - # из Tooling Прил.Н §3.5/§4.X (Pravila §16.4 v1.36, missed-activation - # matcher). Учитывает два сигнала: dormant=true в строке атрибутов или - # ключевое слово DEFERRED в колонке boundaries. Регенерированный JSON - # авто-стейджится — попадает в тот же коммит, что и правки Tooling. - - name: extract-node-dormancy - glob: "docs/Tooling_v8_3.md" - run: node tools/extract-node-dormancy.mjs && git add tools/.node-dormancy.json - fail_text: | - extract-node-dormancy failed. - Проверьте формат 9-attribute table rows в docs/Tooling_v8_3.md. + # 12b. extract-node-dormancy — REMOVED 2026-05-25 (LLM-first router overhaul + # Task 4). Source of truth for dormancy migrated from tools/.node-dormancy.json + # to docs/registry/nodes.yaml (field `status: active|dormant|deferred|historic`). + # Adapter: tools/registry-to-classification-map.mjs::buildDormancyMap. + # Archive: docs/archive/llm-bootstrap-2026-05/routing-docs/. # 13. observer-of-observer — счётчик чтений docs/observer/ + 54-week self-prune # (brain governance C3, ADR-011 spec §6.3). Скрипт всегда exit 0 (warn-only by diff --git a/tools/observer-coverage-checker.mjs b/tools/observer-coverage-checker.mjs index e2d121d0..5e0e31c8 100644 --- a/tools/observer-coverage-checker.mjs +++ b/tools/observer-coverage-checker.mjs @@ -19,6 +19,8 @@ import { readFileSync, existsSync } from 'fs'; import { join } from 'path'; import { detectMissedActivations } from './missed-activations.mjs'; import { dedupeEpisodes } from './brain-retro-analyzer.mjs'; +import { loadRegistry } from './registry-load.mjs'; +import { buildClassificationMap, buildDormancyMap } from './registry-to-classification-map.mjs'; /** * @param {number} episodeCount - episodes in the current month JSONL @@ -76,13 +78,23 @@ function loadEpisodes(root) { function loadClassificationMap(root) { try { - return JSON.parse(readFileSync(join(root, 'tools', 'observer-classification-map.json'), 'utf-8')).map || {}; + const registry = loadRegistry({ + registryPath: join(root, 'docs', 'registry', 'nodes.yaml'), + schemaPath: join(root, 'docs', 'registry', 'schema.json'), + useCache: false, + }); + return buildClassificationMap(registry); } catch { return {}; } } function loadDormancy(root) { try { - return JSON.parse(readFileSync(join(root, 'tools', '.node-dormancy.json'), 'utf-8')); + const registry = loadRegistry({ + registryPath: join(root, 'docs', 'registry', 'nodes.yaml'), + schemaPath: join(root, 'docs', 'registry', 'schema.json'), + useCache: false, + }); + return buildDormancyMap(registry); } catch { return {}; } } diff --git a/tools/observer-transcript-parser.mjs b/tools/observer-transcript-parser.mjs index 224e0d0e..a08ca3b4 100644 --- a/tools/observer-transcript-parser.mjs +++ b/tools/observer-transcript-parser.mjs @@ -24,6 +24,8 @@ import { detectChoiceProvenance, detectAskUserQuestionChoice } from './observer- import { loadChainMap, chainsFor } from './observer-chain-detector.mjs'; import { buildHookMap, resolveScriptCounts } from './observer-hook-resolver.mjs'; import { recommendNode } from './observer-recommended-node.mjs'; +import { loadRegistry } from './registry-load.mjs'; +import { buildClassificationMap, buildDormancyMap } from './registry-to-classification-map.mjs'; const __dirname = dirname(fileURLToPath(import.meta.url)); @@ -49,7 +51,7 @@ let CLASSIFICATION_MAP = null; function getClassificationMap() { if (CLASSIFICATION_MAP) return CLASSIFICATION_MAP; try { - CLASSIFICATION_MAP = JSON.parse(readFileSync(join(__dirname, 'observer-classification-map.json'), 'utf-8')).map || {}; + CLASSIFICATION_MAP = buildClassificationMap(loadRegistry()); } catch { CLASSIFICATION_MAP = {}; } return CLASSIFICATION_MAP; } @@ -57,7 +59,7 @@ function getClassificationMap() { let DORMANCY = null; function getDormancy() { if (DORMANCY) return DORMANCY; - try { DORMANCY = JSON.parse(readFileSync(join(__dirname, '.node-dormancy.json'), 'utf-8')); } + try { DORMANCY = buildDormancyMap(loadRegistry()); } catch { DORMANCY = {}; } return DORMANCY; }