docs(secretary): handoff B влит + эталон settings с SECRETARY_FLUFFY

This commit is contained in:
Дмитрий
2026-06-25 15:09:41 +03:00
parent 1b40f2d861
commit a6eb04e4e2
2 changed files with 423 additions and 44 deletions
@@ -1,7 +1,7 @@
# Эпик «пушистое дерево» секретаря — СТАТУС и HANDOFF (для следующей сессии)
**Дата:** 2026-06-25 · **Состояние main:** `d6dc0f7` (A+C влиты, забэкаплены в gitea) · полная сюита
`tools`**4639 зелёных** · флаг `SECRETARY_FLUFFY` **выключен** → живой секретарь не тронут.
**Дата:** 2026-06-25 · **Состояние main:** `1b40f2d` (A+B+C влиты, забэкаплены в gitea) · полная сюита
`tools`**4665 зелёных + 1 todo** · флаг `SECRETARY_FLUFFY` **выключен** → живой секретарь не тронут.
## Что это за эпик
Превратить вывод секретаря из «ободранного дерева» (ствол + куча статичных скрытых веток) в **пушистое
@@ -13,53 +13,84 @@
|---|---|---|
| **A** | боевой конвейер веток (диагностика 8/8 ∥ ловец → брейншторм → садовник → применение) | ✅ ВЛИТ в main (`aded6b8`) |
| **C** | рендер пушистого дерева (`renderFluffy` + развилка `renderDoc` + проводка в stop-хук) | ✅ ВЛИТ в main (`d6dc0f7`) |
| **B** | фоновый воркер (очередь-один-писатель) + включение флага | ⬜ НЕ НАЧАТ |
| **B** | фоновый воркер (всё в фоне, очередь-один-писатель) | ✅ ВЛИТ в main (`1b40f2d`) |
**КОД ЭПИКА ЗАКРЫТ.** Осталось только включение (owner-gated) — см. ниже.
## Сделано (A + C)
- **A** (`docs/superpowers/specs/2026-06-25-secretary-pipeline-A-design.md` + план
`…/plans/2026-06-25-secretary-pipeline-A.md`): новые модули `secretary-armor.mjs` (JSON-броня,
опора-словарь, линзы), `secretary-trunkdiff.mjs`, `secretary-models.mjs` (5 слотов), `secretary-harvest.mjs`
(диагностика 8/8/ловец/брейншторм без лимита), `secretary-gardener.mjs` (close-с-пруфом + В1-гейт),
`secretary-apply.mjs` (ветки/кандидаты-накопление/тенд). Дирижёр `secretary-distill.mjs` — развилка по
флагу (новый путь / старый аудит). 50 тестов. Промпты перенесены из доказанной песочницы `.scratch/sec/v2.mjs`.
- **C** (`…/specs/2026-06-25-secretary-render-C-design.md` + `…/plans/2026-06-25-secretary-render-C.md`):
`secretary-render-fluffy.mjs``renderFluffy(protocol,opts)` (markdown по макету) + `renderDoc(...,env)`
(флаг ON → пушистый, OFF → старый `renderProtocol`). Проводка: `secretary-stop-hook.mjs:143,165` зовут
`renderDoc`. 10 тестов.
- **Флаг** `fluffyPipelineOn(env)` в `secretary-flag.mjs` (`SECRETARY_FLUFFY=1|true`). ВЫКЛ по умолчанию.
- **A** (`/specs/2026-06-25-secretary-pipeline-A-design.md` + план `…/plans/…-pipeline-A.md`): модули
`secretary-armor.mjs`, `secretary-trunkdiff.mjs`, `secretary-models.mjs` (5 слотов), `secretary-harvest.mjs`,
`secretary-gardener.mjs` (close-с-пруфом + В1-гейт), `secretary-apply.mjs`. Дирижёр `secretary-distill.mjs`
— развилка по флагу. ~50 тестов. Промпты из песочницы `.scratch/sec/v2.mjs`.
- **C** (`…/specs/…-render-C-design.md` + `…/plans/…-render-C.md`): `secretary-render-fluffy.mjs`
`renderFluffy` + `renderDoc(...,env)`. 10 тестов.
## Осталось — B (фоновый воркер). Дизайн уже решён владельцем
**Все 8 архитектурных решений + рабочий поток + про кандидаты/прослеживаемость — в**
`docs/secretary/протокол-наставника/прогон/НАХОДКИ.md`, раздел **«ДИЗАЙН-РЕШЕНИЯ 25.06»** (читать первым).
Ключевое для B:
- **Гонка, которую B обязан решить:** убежали на 3 хода → фон затирает свежий протокол старым (потерянное
обновление). **Решение:** очередь с ОДНИМ работником, спаны по порядку, каждый берёт протокол-после-
предыдущего; никогда два сразу. Протокол ДОГОНЯЮЩИЙ (отстаёт на N ходов), но не ломается. **Лаг принят.**
- **Один протокол, ЕДИНСТВЕННЫЙ писатель — редактор.** Фон сам в файл не пишет — отдаёт результат
редактору. Один писатель = нет затирания.
- Ствол (редактор) — на критпути (или тоже в очередь); ветки (1.1/1.2/1.3/садовник) — в фон.
- **B включает флаг** (`SECRETARY_FLUFFY=1`) — конвейер идёт вживую. Это повышает ставки → B самый рисковый.
- **Непроверенное механикой (тест при B):** гравитация (продвижение кандидата в ствол, когда владелец
заговорил об идее); reopen/обратный каскад (в тесте не было повода); сжатие длинной истории на масштабе.
- Латентность, обосновавшая B: брейншторм 67-97с (см. НАХОДКИ «Латентность флэша»).
## Сделано (B) — спека `…/specs/2026-06-25-secretary-worker-B-design.md`, план `…/plans/…-secretary-worker-B.md`
**Поправка к НАХОДКАМ: решение №1 переписано на «ВСЁ в фоне»** (был гибрид «ствол синхронно»). Причина —
владелец потребовал 15-мин таймауты ВСЕМ ролям + вход/выход без лимитов; синхронный ствол упирался бы в
900с-стену хука. Итог проще: «почтовый ящик» не нужен, писатель один (воркер).
- **Новые модули:** `secretary-queue.mjs` (очередь+курсор, дедуп по index), `secretary-lock.mjs` (пульс-замок
поверх proper-lockfile: живой воркер держит пульс, мёртвого перехватывают), `secretary-spawn.mjs` (detached
выстрел воркера), `secretary-worker.mjs` (`runWorker` — ЕДИНСТВЕННЫЙ писатель протокола; CLI),
`secretary-enqueue.mjs` (`spansToEnqueue`).
- **Правки:** `secretary-stop-hook.mjs` переразведён (НЕ зовёт LLM, НЕ пишет протокол — только сырьё +
очередь + выстрел; `_sessions.json`/catchUp сохранены), `secretary-harvest.mjs` (обрезка 4000 → ручка
`SECRETARY_INPUT_CAP`, дефолт полный), `secretary-index.mjs` (`writeIndexSafely` под файл-замком — параллель
тем), `secretary-flag.mjs` (`fluffyPipelineOn` читает ещё и рантайм-файл-сентинел).
- **Per-role модели (5 слотов) реально работают:** обзор поймал баг — воркер ронял `resolveModel(role)`;
починено `pickModel` (per-call model → callAnthropicAPI options).
- **Таймауты:** 900с/вызов + 2 повтора (env-настраивается); тяжёлые модели в фоне без стены.
- **Механика (решение №8):** reopen/обратный каскад ✅ работает (тест), сжатие истории (свёрнуто≠удалено,
born сохранён) ✅ работает (тест). **Гравитация (кандидат→ствол) — НЕ реализована** (`it.todo` в
`secretary-mechanics.test.mjs`): это суждение редактора, не правило; строить спекулятивно нельзя.
- Прошло: пер-задачный обзор + независимый обзор риска (хук) + финальный обзор интеграции — чисто.
## Как поднять B (следующая сессия)
1. **Включить штатный режим** (`да, штатный`) — экспериментальная работа секретаря шла в нём весь
25.06 (стена опущена, пол/проверки остаются). Стена по умолчанию поднята в новой сессии.
2. **Брейншторм** (передняя дверь) → спека B → план B → исполнение (как A/C). Дизайн B уже почти готов в
НАХОДКИ — брейншторм будет коротким (формализация + решить, где физически живёт очередь и чем триггерится).
3. Реализация — TDD, на ветке (не main), коммит/merge через терминал владельца (пол блокирует агента;
`node tools/produce-verify-receipt.mjs` перед коммитом, `-m` ДО `--`, влитие fast-forward).
## ВКЛЮЧЕНИЕ (owner-gated) — готовый блок для основного ситинга
Два пути, выбери один.
**Путь 1 — рантайм-файл (быстро, без правки settings):** создать пустой файл
`~/.claude/runtime/secretary-fluffy`. Откат — удалить файл.
**Путь 2 — settings.json `env` (то, что копируешь из эталона `.claude/settings - эталон.json`):** в начале
файла, сразу после `"$schema"`, добавлен блок (уже стоит в эталоне):
```json
"env": {
"SECRETARY_FLUFFY": "1"
},
```
`SECRETARY_FLUFFY=1` — сам выключатель (без него ничего не меняется). Скопировать `env`-блок из эталона в
оригинал `.claude/settings.json` (оригинал под read-deny — копирует владелец).
**Тюнинг моделей/таймаутов (опционально, реальными значениями, НЕ пустыми `""`):** дописать в тот же `env`:
- `SECRETARY_LLM_MODEL_<РОЛЬ>` — 5 слотов: `EDITOR` (ствол) · `DIAGNOSTIC` (1.1) · `CATCHER` (1.2) ·
`BRAINSTORM` (1.3) · `GARDENER` (садовник). Незаданный слот → общий `SECRETARY_LLM_MODEL`.
- `SECRETARY_LLM_TIMEOUT_MS` (дефолт `900000`) · `SECRETARY_LLM_RETRIES` (дефолт `2`).
- `SECRETARY_INPUT_CAP` — НЕ задавать = вход целиком; число = обрезать.
**Доступ к LLM** (`SECRETARY_LLM_KEY`, `SECRETARY_LLM_BASE_URL`, `SECRETARY_LLM_MODEL`) — оставить там, где
живой секретарь их уже берёт; без ключа воркер моделей не вызовет (тихий no-LLM, только сырьё+шаг).
**После включения:** прогнать реальную тему, глянуть `protocol.md` (догоняющий — растёт по мере фон-разбора).
Если ок — убрать песочницу `.scratch/sec/*` (CLAUDE.md п.11) и удалить ветку `feat/secretary-worker-b`.
## Два честных хвоста (follow-up, не блокеры)
- **Гравитация** — не реализована (см. выше). Если нужна — отдельная задача: доработка редактор-промпта,
чтобы кандидат поднимался в ствол, когда владелец заговорил об идее.
- **Выход модели жёстко 64k токенов:** `callAnthropicAPI` хардкодит `max_tokens: 65536`, отдельной ручки нет.
Для «выход максимум» это и есть максимум; крутить — только правкой `callAnthropicAPI` (вне эпика).
- **Интеррупт-заметки на спан** (`spanInterruptNote`) хук больше не проставляет; сырьё метки сохраняет, при
желании воркер может считать заметку сам — мелочь, не потеря данных.
## Опорные файлы (карта)
- **Находки + дизайн-решения + макет вида:** `docs/secretary/протокол-наставника/прогон/НАХОДКИ.md`,
`…/прогон/ФИНАЛЬНЫЙ-ВИД-макет.md`.
- **Доказанная песочница (источник промптов/логики):** `.scratch/sec/v2.mjs` (НЕ удалять до конца эпика —
референс для B; после — прибрать по CLAUDE.md п.11).
- **Спеки/планы A,C:** `docs/superpowers/specs/2026-06-25-secretary-*.md`, `…/plans/2026-06-25-secretary-*.md`.
- **Боевой код:** `tools/secretary-{armor,trunkdiff,models,harvest,gardener,apply,render-fluffy,flag,distill,stop-hook}.mjs` + `.test.mjs`.
- **Находки + дизайн-решения + макет:** `docs/secretary/протокол-наставника/прогон/НАХОДКИ.md` (раздел
«ДИЗАЙН-РЕШЕНИЯ 25.06»), `…/прогон/ФИНАЛЬНЫЙ-ВИД-макет.md`.
- **Песочница (источник промптов A):** `.scratch/sec/v2.mjs` (убрать после живого прогона).
- **Спеки/планы A,B,C:** `docs/superpowers/specs/2026-06-25-secretary-*.md`, `…/plans/2026-06-25-secretary-*.md`.
- **Боевой код B:** `tools/secretary-{queue,lock,spawn,worker,enqueue}.mjs` + правки
`{stop-hook,harvest,index,flag}.mjs` + `.test.mjs`.
## Коммит-механика в этом репо (памятка)
Пол блокирует коммит/merge агента. Путь: контроллер `git add` + `node tools/produce-verify-receipt.mjs`
(зелёная сюита) → **владелец вставляет `git commit`/`git merge`/`git push gitea main` в свой терминал**
(`-m` ДО `--`; на unlink-pack отвечать `n`). docs-only коммиты проходят сами, смешанные — нужна расписка.
Пол блокирует коммит/merge агента. Путь: контроллер `git add` → **владелец вставляет
`git commit`/`git merge --ff-only`/`git push gitea main` в свой терминал** (`-m` ДО `--`; на unlink-pack
отвечать `n`). docs-only коммиты проходят сами, смешанные — нужна расписка. Несколько мелких коммитов одной
строкой: `git commit -m "…" -- путь1 путь2 …` (один прогон хуков).