Дмитрий
0af5c5696f
РАЗМЕТКА ДОКУМЕНТАЦИИ. Проверка сторожа давала 237 замечаний в 21 файле — стало
0 во всех файлах под учётом git. Пустые строки вокруг списков и заголовков
поправлены автоматом в 12 файлах, два файла пришлось делать руками, потому что
автоправка там навредила:
- в описании починки инцидента номера шагов 1…7 — это ИМЕНА, на них ссылается
сам текст «из шага 2»; автоправка перенумеровала их в 1,1,1,1,2 и сломала
ссылки. Вывел ровно этот файл из-под одного правила, объяснение — в самом
файле, остальные правила действуют.
- в протоколе архитектуры автоправка склеила «R-* / DR-*» в «R-*/ DR-*».
Вместо этого обозначения взяты в обратные кавычки — смысл сохранён.
Семь файлов не тронуты: они вне учёта git — два в папке второй смены и старые
черновики в корне.
ИНТЕРФЕЙС. «Неизвестный тип» убран целиком: было 123 замечания, стало 0.
- Навигация автоподбора описана ОДИН раз — app/resources/js/views/autopodbor/nav.ts.
Раньше девять экранов повторяли описание с «неизвестным типом», а ещё три
описывали его каждый по-своему и не полностью.
- Чтение ошибки от сервера собрано в один помощник — app/resources/js/api/errors.ts,
с проверками. Он намеренно читает ФОРМУ ответа, а не полагается на axios:
тесты экранов подсовывают ошибку простым объектом той же формы, и экран обязан
вести себя в тестах так же, как в бою.
- В тестах вместо «неизвестного типа» — именованный доступ exposed<T> и полные
заготовки: app/tests/Frontend/support/. Каждый тест теперь объявляет ровно те
поля, до которых дотягивается, и опечатка в имени снова становится ошибкой,
а не молчаливым undefined. Заодно сняты 14 построчных отключений правила.
- Разведены задвоенные имена в шаблонах: в таблице сделок в одном шаблоне жили
ДВЕ разные функции isSelected — одна берёт номер сделки, другая строку таблицы.
- Убрана мёртвая функция dirLabel и три неиспользуемые переменные.
ПРОВЕРКА ТИПОВ: было 7 ошибок, стало 5. Две унаследованные закрылись попутно —
более строгие заготовки вскрыли нехватку обязательного поля elements. Оставшиеся
пять были до меня и не в моих строках.
ПРИЁМКА. Разметка проверена вырезанием: подложил поломку обратно — сторож её
поймал, вернул — снова чисто. Полный набор тестов интерфейса: 233 файла,
1750 тестов, 3 пропущено, 0 падений. Рабочий код на PHP не тронут.
NB: LEFTHOOK_EXCLUDE=cspell — тем же приёмом и по той же причине, что и в записи
e0223de4, которой эти шесть файлов исследования заводились в репозиторий: сырой
внешний материал с чужой терминологией. Замерено: до моих правок сторож
орфографии находил в них ровно столько же слов, сколько после — я не добавил
ни одного. Разметка в этих файлах теперь проходит начисто, отключена ТОЛЬКО
орфография и только на эту запись; остальные семнадцать сторожей отработали.
Решение владельца, спрошено отдельно.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
195 lines
16 KiB
Markdown
195 lines
16 KiB
Markdown
# Каталог данных «мозга» Лидерры
|
||
|
||
Полный перечень всего, что новый «мозг» (наблюдатель + защиты router-gate v4) **способен фиксировать**: журнал эпизодов, числовые параметры/счётчики и все оси для факторного анализа.
|
||
|
||
**Статус проверки:** разделы A–E сверены по исходному коду `tools/` (31.05.2026). Раздел F сверен по коду хуков. Все цитаты — `file:line` от корня репозитория.
|
||
|
||
---
|
||
|
||
## A. Эпизод журнала — `docs/observer/episodes-YYYY-MM.jsonl` (схема v4.4, schema_minor 4)
|
||
|
||
Один эпизод = один цикл «промпт заказчика → ответ Claude». Append-only, по строке на эпизод. ПДн вырезаются до записи (`observer-pii-filter.mjs`). Сборка — `observer-transcript-parser.mjs:888` (`parseTranscript`).
|
||
|
||
### A.1. Идентификация и время
|
||
|
||
| Поле | Тип / значения | Смысл |
|
||
|---|---|---|
|
||
| `schema_version` | `4` | версия схемы |
|
||
| `schema_minor` | `3` | подверсия |
|
||
| `task_id` / `task_ref` | string (sessionId) | привязка к сессии |
|
||
| `timestamps.started_at` / `ended_at` | ISO | начало/конец хода |
|
||
|
||
### A.2. Кто и что выбрал
|
||
|
||
| Поле | Значения | Смысл |
|
||
|---|---|---|
|
||
| `path_type` | `regulated` / `improvised` | был ли вызван навык superpowers |
|
||
| `decision_provenance.kind` | `autonomous` / `user_directed_method` / `user_chose_from_options` | кто выбрал маршрут — Claude сам / навязан заказчиком / заказчик выбрал из предложенного |
|
||
| `decision_provenance.claude_would_have_chosen` | string / null | контрфактуал — что выбрал бы Claude сам |
|
||
|
||
### A.3. Исход
|
||
|
||
| Поле | Значения | Смысл |
|
||
|---|---|---|
|
||
| `outcome` | при записи `unknown` | исход (выводится позже, см. C) |
|
||
| `outcome_reviewed` | null → метка | исход по ревью /brain-retro |
|
||
| `outcome_reviewed_source` | null / source | кто проставил ревью |
|
||
|
||
### A.4. Сигнал заказчика
|
||
|
||
| Поле | Значения | Смысл |
|
||
|---|---|---|
|
||
| `prompt_signal` | `correction` / `approval` / `new_task` / `neutral` | тон следующего/текущего промпта |
|
||
| `prompt_embedding_base64` | null → вектор | смысловой вектор первого промпта (дозаполняется асинхронно) |
|
||
|
||
### A.5. Обстановка (`environment`)
|
||
|
||
| Поле | Значения | Смысл |
|
||
|---|---|---|
|
||
| `economy_level` | 0 / 5 / 100 / null | режим экономии |
|
||
| `model` | имя модели | модель контроллера |
|
||
| `post_compaction` | bool | был ли сжат контекст до хода |
|
||
| `session_turn` | int | номер хода после последнего сжатия |
|
||
| `parallel_session` | bool | признак второй активной сессии |
|
||
| `classifier_model` | имя / null | модель LLM-классификатора |
|
||
|
||
### A.6. Размер (`task_size`)
|
||
|
||
`tool_calls` (всего вызовов инструментов) · `files_touched` (уникальных файлов) · `files[]` (список путей). — `observer-transcript-parser.mjs:423`.
|
||
|
||
### A.7. Стоимость и токены (`task_cost`)
|
||
|
||
`observer-transcript-parser.mjs:472`. Базовые: `input_tokens` · `output_tokens` · `cache_read_input_tokens` · `cache_creation_input_tokens` · `web_search_requests` · `web_fetch_requests` · `iterations` (детектор extended-thinking).
|
||
Слой LLM-агентов (дозаполняется): `classifier_input_tokens` · `classifier_output_tokens` · `self_assessment_input_tokens` · `self_assessment_output_tokens` · `reviewer_input_tokens` · `reviewer_output_tokens` · `reviewer_subagent_usd` · `reviewer_direct_fallback_usd` · `judge_spend_usd` (✅ NEW — `judge_calls × JUDGE_PER_CALL_USD`).
|
||
|
||
### A.8. Мета (`task_meta`)
|
||
|
||
`prompt_length_chars` · `mcp_servers_used[]` · `file_type_distribution` по корзинам `src / test / config / spec / norm / data / other` (`classifyFilePath` — `observer-transcript-parser.mjs:358`).
|
||
|
||
### A.9. Классификатор (`classifier_output`) + `degraded_mode`
|
||
|
||
`observer-state-enricher.mjs:52`. `task_type` · `recommended_node` · `recommended_chain` · `recommended_chain_id` · `no_skill_found` · `source` (llm/regex/prefilter/cache) · `reasoning` (≤600 симв.) · `confidence` · `latency_ms` · `retry_count_internal` · `llm_error` · `alternatives_considered[]` (топ-3). Отдельно `degraded_mode` (bool, LLM→regex fallback).
|
||
|
||
### A.10. Рассуждение маршрута (`primary_rationale`)
|
||
|
||
`step` · `node_chosen` · `chain_ref` · `triggers_matched[]` · `candidates_considered[]` · `boundaries_applied[]` · `hard_floor{invoked, rules[]}` · `task_classification` · `recommended_node` · `recommended_chain` · `chain_progress` · `chain_completed`.
|
||
|
||
**`task_classification` — 12 значений** (`observer-transcript-parser.mjs:208`): `memory-sync`, `regulatory-bump`, `planning`, `release`, `refactor`, `bugfix`, `feature`, `docs`, `analysis`, `cleanup`, `monitoring`, `question`, `other`.
|
||
|
||
### A.11. События (`events[]`) — 11 видов
|
||
|
||
`skill_invoked` (skill) · `tool_summary` (counts) · `error` (tool, summary) · `hook_fired` (counts, scripts, errors) · `interrupt` · `retry` · `time_burn` (ход > 15 мин) · `parse_gap` (> 10% битых строк) · `unrecovered_error` (ход кончился на ошибке) · `ask_user_question` (question_count, answer_kind: `option`/`custom`/`no_answer`) · `subagent_invoked` (subagent_type, model, description).
|
||
|
||
### A.12. Сигналы защит router-gate v4 (`v4_signals`) — ✅ NEW (schema_minor 4)
|
||
|
||
Поднимаются в эпизод ридером `observer-v4-signals.mjs` по окну хода `[started_at, ended_at]`: `rationalization_flag_count` (число пойманных самооправданий в окне) · `judge_verdict` (`YES`/`NO`/`block`/`null` — последний вердикт судьи в окне) · `safe_baseline_action` (`allow`/`soft_flag`/`hard_block`/`null` — худшее действие safe-baseline в окне) · `judge_calls` (кумулятивно за сессию из бюджета судьи).
|
||
|
||
---
|
||
|
||
## B. Факторные оси — `FACTOR_FNS` (`brain-retro-analyzer.mjs:326`) — 27 осей + `chain_ref`
|
||
|
||
Каждая ось раскладывает эпизоды по корзинам и строит матрицу «значение фактора × распределение исходов» (`buildFactorMatrix`, `brain-retro-analyzer.mjs:384`).
|
||
|
||
**Pass 0 (из ядра эпизода):** `decision_provenance` · `economy_level` · `model` · `post_compaction` · `session_segment_turn` · `parallel_session` · `task_size` · `node_chosen` · `task_classification` · `recommended_node_for_direct`.
|
||
|
||
**Pass 1 (дешёвые оси из v4):** `prompt_signal` · `classifier_source` · `degraded_mode` · `path_type` · `retry_count` · `error_count` · `hard_floor_invoked` · `iterations_bucket`.
|
||
|
||
**Pass 2 (метрики классификатора):** `latency_bucket` (fast<500 / medium<2000 / slow<10000 / very_slow) · `error_type`.
|
||
|
||
**Pass 3 (динамика):** `prompt_length_bucket` (short<100 / medium<1000 / long<2500 / huge) · `time_of_day_bucket` (night/morning/afternoon/evening, UTC) · `day_of_week` · `inter_prompt_gap_bucket` (<1m / 1-10m / 10-60m / 60m+) · `mcp_server_used` (any/none) · `file_type_main` · `skill_invocations_bucket` (0/1/2+) · `subagent_spawns_bucket` (0/1/2+).
|
||
|
||
**Pass 4 (семантика):** `similar_past_outcome_majority` (исход большинства соседей по смысловому вектору; `no_neighbors` если вектора нет).
|
||
|
||
**Pass 5 (✅ NEW — сигналы router-gate v4):** `rationalization_flag_count` (0/1/2+) · `judge_verdict` (YES/NO/block/null) · `safe_baseline_action` (allow/soft_flag/hard_block/null) · `judge_calls_bucket` (0 / 1-9 / 10+).
|
||
|
||
**Отдельно:** `chain_ref` — мульти-значный (эпизод считается по разу на каждую цепочку).
|
||
|
||
---
|
||
|
||
## C. Вывод исхода — `inferOutcome` (`brain-retro-analyzer.mjs:95`) — 5 меток
|
||
|
||
- `blocked` — ход кончился на неисправленной ошибке (`unrecovered_error`).
|
||
- `rework` — следующий эпизод имеет `prompt_signal = correction`.
|
||
- `success` — следующий = `approval` или `new_task`.
|
||
- `soft_success` — следующий = `neutral` (тихий успех).
|
||
- `unknown` — следующего эпизода ещё нет.
|
||
|
||
---
|
||
|
||
## D. Аналитические срезы (Cuts) `/brain-retro` (`brain-retro-analyzer.mjs`)
|
||
|
||
| Срез | Функция | Что агрегирует |
|
||
|---|---|---|
|
||
| Факторная матрица | `buildFactorMatrix` | 27 осей × распределение исходов |
|
||
| Cut 8 — Class × canon coverage | `buildClassCanonCoverage:448` | по классу задачи: count, канон-узлы, как часто роутер рекомендовал, что взял Claude, попало ли в канон, rework |
|
||
| Cut 9 — Router vs Opus | `buildRouterVsOpus:498` | расхождение роутера и Opus-ревьюера (3 секции) |
|
||
| Cut 10 — Chain-ignore breakdown | `buildChainIgnoreBreakdown:559` | % игнора цепочек + rework-rate по длине (1 / 2 / 3+) |
|
||
| Cut 11 — Chain-hook effectiveness | `analyzeChainHookEffectiveness:36` + `buildChainHookEffectiveness:59` | исходы срабатывания chain-хука по ledger |
|
||
| Router-gate hook effectiveness | `buildRouterGateHookEffectiveness:617` | эффективность router-gate |
|
||
| Self-fabrication signals | `buildSelfFabricationSignals:643` | признаки фейковых результатов |
|
||
|
||
---
|
||
|
||
## E. Числовые счётчики и деньги (вне эпизода)
|
||
|
||
### E.1. `~/.claude/runtime/cost-daily.json` (per-date)
|
||
|
||
`cost-aggregator.mjs:13`. Поля: `classifier_usd` · `self_assessment_usd` · `reviewer_subagent_usd` · `reviewer_direct_fallback_usd` · `self_retrospect_usd` · `total_usd` · `episode_count`.
|
||
|
||
### E.2. `PRICING` (`cost-pricing.mjs`)
|
||
|
||
Sonnet — $3/Mtok вход, $15/Mtok выход. Opus — $15/Mtok вход, $75/Mtok выход.
|
||
|
||
### E.3. `~/.claude/runtime/hook-outcomes.jsonl`
|
||
|
||
6 корзин исхода хука (`classifyOutcome`): `blocked` / `passed-with-skill` / `passed-inline-override` / `passed-global-override` / `passed-short-chain` / `passed-no-mutating`. Строка: rule, outcome, sessionId, timestamp.
|
||
|
||
### E.4. `~/.claude/runtime/override-usage.jsonl`
|
||
|
||
Лог override-фраз. Порог 5/день на фразу (6-я блокируется `enforce-override-limit`). Байпас — фраза «лимит снят».
|
||
|
||
### E.5. Контролёр C5 (`observer-coverage-checker.mjs`) — warn-only
|
||
|
||
`coverage` (хук зарегистрирован, но 0 эпизодов за месяц) · `registration` (Stop-хук + post-commit на месте) · `missed.totalMissed` (промахи активации узлов, `missed-activations.mjs`).
|
||
|
||
### E.6. Три счётчика в `docs/observer/`
|
||
|
||
`.pii-counters.json` (сколько ПДн вырезано) · `.read-counter.json` (когда читали файлы наблюдателя; алерт через 54 недели тишины) · `.self-retrospect-counter.json` (`episodes_since_last`, порог 50 → предложить саморазбор).
|
||
|
||
---
|
||
|
||
## F. Сигналы новых защит router-gate v4
|
||
|
||
> **Обновление 31.05.2026:** F.1–F.3 ✅ **заведены в эпизод** (`v4_signals`, см. A.12) и в факторный анализ (Pass 5, раздел B) через ридер `observer-v4-signals.mjs`. F.4/F.5 — пока только на диске.
|
||
|
||
### F.1. Rationalization-audit (`enforce-rationalization-audit.mjs`)
|
||
|
||
`~/.claude/runtime/rationalization-flags-<session>.jsonl`. Строка: `{kind, evidence}`. Виды (`kind`): `rationalization-phrase` (фраза-самооправдание) · `prod-edit-without-test` (правка прод-кода без теста в том же ходе) · `weak-commit-message` (commit с сообщением < 12 симв.). Блокирует на 3-м флаге за сессию (`decide:112`). Перед сопоставлением снимает цитаты/код (`stripQuotedContext:51`).
|
||
|
||
### F.2. Safe-baseline metering (`enforce-safe-baseline-metering.mjs`)
|
||
|
||
`~/.claude/runtime/safe-baseline-ledger-<sess>.json` (per-task счётчики вызовов safe-инструментов Read/Grep/Glob/LS/TodoWrite/AskUser + `skill_match_within_task` + `lastKeywords`) и `safe-baseline-flags-<sess>.jsonl` (`{ts, tool, reason}`). Действия: `allow` / `soft_flag` / `hard_block` (мутирующий инструмент за порогом без навыка). Escape — любой Skill / EnterPlanMode.
|
||
|
||
### F.3. LLM-судья Layer 4 (`enforce-llm-judge-per-tool.mjs` + `-response-scan.mjs`)
|
||
|
||
Вердикт по каждому мутирующему инструменту: `YES → allow`, `NO`/сомнение → `block`. Spend гейтится `resolveJudgeConfig` (флаг `ROUTER_LLM_JUDGE_ENABLED` И ключ) + per-session бюджет `JUDGE_SESSION_BUDGET` (инкремент только на реальный вызов). Исключения из проверки (scope-fix, не понижение дисциплины): `isReadonlyBashEvent` (readonly git/cat/grep/ls) и `isTestRunnerBashEvent` (vitest/pest/phpunit/artisan test/composer test/npm test без цепочки).
|
||
|
||
### F.4. Router-state writer (`router-prehook.mjs:156`)
|
||
|
||
`~/.claude/runtime/router-state-<session>.json`: `classification` (вывод классификатора — task_type/recommended_node/recommended_chain/source/confidence/reasoning/…) · `chainProgress[]` · `chainCompleted` · `task_cost` (токены классификатора). Это источник, из которого `observer-state-enricher` обогащает эпизод (A.9–A.10).
|
||
|
||
### F.5. Прочие runtime-сигналы
|
||
|
||
`expected-branch-<session>` (защита от угона ветки, `enforce-branch-switch`) · `verify-pass-<session>` (свежесть регрессии перед push, `enforce-verify-before-push`) · `askuser-decisions-<session>.jsonl` (одобрения git-операций) · `session-lock-<workspaceHash>.json` (замок параллельной сессии, `enforce-parallel-session-lock`) · `router-gate-mode.json` и набор `*-mode.json` (рубильники слоёв).
|
||
|
||
---
|
||
|
||
## Кандидаты на расширение факторного анализа
|
||
|
||
✅ **Реализовано 31.05.2026** (план `docs/superpowers/plans/2026-05-31-brain-factor-analysis-f-candidates.md`): следующие 4 оси заведены в эпизод (`v4_signals`) и в `FACTOR_FNS` (Pass 5):
|
||
|
||
- `rationalization_flag_count` (F.1) — число самооправданий за ход/сессию.
|
||
- `safe_baseline_action` (F.2) — allow / soft_flag / hard_block.
|
||
- `judge_verdict` (F.3) — YES / block / disabled (когда Layer 4 активен).
|
||
- `judge_spend_usd` (F.3) — расход судьи (добавить компонентом в `task_cost` и в `cost-daily.json`).
|