143 lines
14 KiB
Markdown
143 lines
14 KiB
Markdown
---
|
||
work_item: ORCH-078
|
||
stage: analysis
|
||
author_agent: analyst
|
||
status: ready-for-review
|
||
created_at: 2026-06-09
|
||
model_used: claude-opus-4-8
|
||
---
|
||
|
||
# 01 — BRD (бизнес-требования): ORCH-078 — ORCH-52e: трассировка ORCH-NNN (маркеры-стандарт + правило чтения)
|
||
|
||
Work Item: **ORCH-078** · Repo: **orchestrator** (self-hosting) · Стадия: analysis
|
||
|
||
## 1. Бизнес-контекст и проблема
|
||
|
||
Эпик **ORCH-52** формализует «golden source» документации конвейера слоями:
|
||
- **52b** (ORCH-075) — стандарт структуры документов `docs/_standards/PIPELINE_DOCS.md` + скелеты `docs/_templates/`.
|
||
- **52c** (ORCH-076) — машинный frontmatter-контракт `src/frontmatter.py` + спека handoff `docs/_standards/HANDOFF_PROTOCOL.md`.
|
||
- **52d** (ORCH-077) — 6 системных промптов переписаны в каноне Anthropic + эмиссия 52c-схемы.
|
||
|
||
**52e — слой 4 (трассировка).** В коде `src/` де-факто живёт **51 уникальный маркер** `ORCH-NNN`
|
||
(проверено `grep -rhoE 'ORCH-[0-9]+' src/ | sort -u | wc -l`), привязывающий нетривиальные строки/
|
||
инварианты к work item, который их ввёл (напр. `src/serial_gate.py` несёт `t2.id < jobs.task_id`
|
||
с маркером ORCH-088; `src/merge_gate.py` — ORCH-043/065/071/073). Это **сложившаяся практика без
|
||
формального стандарта**: `docs/_standards/` содержит только `PIPELINE_DOCS.md` и
|
||
`HANDOFF_PROTOCOL.md` — стандарта маркеров-трассировки НЕТ.
|
||
|
||
**Боль, которую закрывает 52e:**
|
||
1. **Нет правила чтения.** Агент (developer/architect), правя маркированную строку, не обязан
|
||
прочитать ADR work item, который её ввёл, → риск молча сломать зафиксированный инвариант
|
||
(класс ошибки «фантомный merge», постмортем `docs/history/LESSONS_2026-06-08_phantom-merge.md`,
|
||
из-за которого появились ORCH-071/073). Маркер должен означать «здесь есть зафиксированное
|
||
решение — прочти его прежде, чем менять».
|
||
2. **Reviewer не проверяет соблюдение.** Reviewer-промпт проверяет ADR-соответствие *текущей*
|
||
задачи, но не контролирует, что правка чужого маркированного кода свелась с его ADR.
|
||
3. **Анти-археология.** Файлы с высокой плотностью маркеров (`config.py`=60, `stage_engine.py`=55,
|
||
`launcher.py`=49, `plane_sync.py`=47, `merge_gate.py`=26 вхождений) превращают понимание блока
|
||
в раскопки по 4+ work item. Нужна конвенция: блок с 3+ маркерами ссылается на **один сквозной
|
||
ADR** (`docs/architecture/adr/`) вместо перечисления всех.
|
||
4. **Доступ к чужому work item.** Папка `docs/work-items/ORCH-NNN/06-adr/` может отсутствовать в
|
||
текущей ветке (срезана от `main` без неё) — нужен задокументированный fallback
|
||
`git show origin/main:docs/work-items/ORCH-NNN/06-adr/...`.
|
||
|
||
**⚠️ Что УЖЕ сделано в 52d (анти-дубль, проверено в `main`):** промпты `developer.md`/`architect.md`
|
||
упоминают `ORCH-NNN`/`06-adr`, но **только** как (а) ADR *текущей* задачи («реализуй по `06-adr/`»),
|
||
(б) именование веток `feature/ORCH-NNN-slug`, (в) поля frontmatter-схемы. **Правила «правишь
|
||
маркированный код → читай его ADR перед изменением» среди них НЕТ** (проверено
|
||
`grep -nE 'ORCH-NNN|06-adr|маркер'`). Поэтому 52e **не переписывает промпты** и **не дублирует**
|
||
52d — он добавляет именно отсутствующее правило, точечно, сохраняя XML-канон 52d.
|
||
|
||
## 2. Объём (scope)
|
||
|
||
### В объёме
|
||
- Формальный **стандарт маркеров-трассировки** `docs/_standards/TRACEABILITY.md`: что такое маркер,
|
||
формат, где ставится, как читать историю (с реальным примером из кода), fallback-доступ,
|
||
анти-археология.
|
||
- **Правило чтения** «правишь код с маркером `ORCH-NNN` → прочитай его `06-adr` ПЕРЕД правкой, не
|
||
сломай инвариант» — точечно добавить в `developer.md` и `architect.md` (где 52d его не покрыла).
|
||
- **Контроль соблюдения** — точечно добавить в `reviewer.md` ось «правка маркированного кода
|
||
сверена с его ADR».
|
||
- **Fallback-доступ** `git show origin/main:docs/work-items/ORCH-NNN/...` — задокументировать в
|
||
стандарте и в developer-промпте.
|
||
- **Анти-археология** «3+ маркеров в блоке → сводная ссылка на сквозной ADR» — зафиксировать в
|
||
стандарте и в architect/reviewer-промптах.
|
||
- Обновление `CLAUDE.md`, `docs/architecture/README.md`, `CHANGELOG.md`; анти-регресс-тест промптов.
|
||
|
||
### Вне объёма
|
||
- **Массовый ретро-фит маркеров** в существующий код (≥51 маркер уже есть — не трогаем; стандарт
|
||
действует «на будущее»).
|
||
- **Любое изменение `src/**`**, в т.ч. гейтов, `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`,
|
||
`_parse_*`, схемы БД.
|
||
- **Полная перезапись промптов** — 52d уже дал канон; 52e лишь точечно дополняет.
|
||
- Включение `frontmatter_validation_strict` / любого enforcement.
|
||
|
||
## 3. Заинтересованные стороны
|
||
- **Owner (Слава)** — заказчик эпика ORCH-52; ручной BRD-гейт (Approved) этой задачи. Лейбл
|
||
`autoDeploy` (орк сам деплоит после staging), BRD-гейт — ручной.
|
||
- **Агенты developer/architect** — потребители правила чтения (получают защиту от слома инвариантов).
|
||
- **Агент reviewer** — получает явную ось контроля соблюдения трассировки.
|
||
- **Self-hosting** — промпты `cat`-аются из worktree в момент запуска → правило вступает в силу на
|
||
следующем worktree от `main` без прод-рестарта (групповой риск не возникает).
|
||
|
||
## 4. Бизнес-требования (BR)
|
||
|
||
- **BR-1** — В `docs/_standards/` создан формальный стандарт маркеров-трассировки (`TRACEABILITY.md`):
|
||
определение маркера `ORCH-NNN`, формат, правило размещения (рядом с нетривиальным инвариантом, не
|
||
на тривиальном коде), способ чтения истории — с **реальным, проверяемым примером из кода**
|
||
(маркер в `src/` → конкретный `docs/work-items/ORCH-NNN/06-adr/...`).
|
||
- **BR-2** — Правило «правишь код с маркером `ORCH-NNN` → прочитай `docs/work-items/ORCH-NNN/06-adr`
|
||
ПЕРЕД изменением, не сломай инвариант» присутствует в `developer.md` и `architect.md`. Если 52d
|
||
частично покрыла смежное — **ссылаться/усилить, не повторять** (BR-5).
|
||
- **BR-3** — Reviewer-промпт **проверяет соблюдение** правила: правка чужого маркированного кода без
|
||
сверки с его ADR / со сломом инварианта → finding с severity.
|
||
- **BR-4** — Задокументирован fallback-доступ к чужому work item:
|
||
`git show origin/main:docs/work-items/ORCH-NNN/06-adr/...` (когда папки нет в текущей ветке).
|
||
- **BR-5** — Анти-археология: конвенция «функция/блок несёт 3+ маркеров → сводная ссылка на сквозной
|
||
ADR (`docs/architecture/adr/`) вместо раскопок по каждому» зафиксирована в стандарте.
|
||
- **BR-6 (АНТИ-ДУБЛЬ)** — 52e НЕ дублирует уже сделанное 52d. Там, где 52d уже задаёт смежное
|
||
поведение, 52e ссылается/усиливает. XML-структура 52d (5 секций) и эмиссия 52c-схемы сохраняются.
|
||
- **BR-7** — Сопутствующая документация обновлена: `CLAUDE.md` (правила для агентов), `docs/
|
||
architecture/README.md` (упоминание стандарта как слоя 4 эпика 52), `CHANGELOG.md`; архитектор
|
||
заводит ADR.
|
||
|
||
## 5. Нефункциональные требования (NFR)
|
||
|
||
- **NFR-1 (нулевое касание кода)** — Изменяются ТОЛЬКО `docs/**` и `.openclaw/agents/*.md`
|
||
(+ структурный тест промптов в `tests/`). `src/**`, `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`,
|
||
`_parse_*`, схема БД — **не трогаются**.
|
||
- **NFR-2 (анти-регресс промптов, как 52d)** — Не потеряны: 5 обязательных XML-секций
|
||
(`<context>`/`<task>`/`<deliverables>`/`<constraints>`/`<output_format>`), 6 полей 52c-схемы,
|
||
и machine-verdict ключи **байт-в-байт** (`verdict:`/`result:`/`staging_status:`/`deploy_status:`/
|
||
`security_status:` с точным регистром и наборами значений). Существующие
|
||
`tests/test_agent_prompts_canon.py` и `tests/test_agent_frontmatter_no_model.py` остаются
|
||
зелёными; полный `pytest tests/ -q` зелёный.
|
||
- **NFR-3 (только на будущее)** — Стандарт описательно-нормативный для нового/изменяемого кода;
|
||
существующие 51 маркер не переразмечаются.
|
||
- **NFR-4 (self-hosting, без рестарта)** — Промпт `cat`-ается из git-worktree агента в момент
|
||
запуска → правка вступает в силу на следующем worktree от `main` без прод-рестарта контейнера
|
||
`orchestrator` (8500).
|
||
- **NFR-5 (обратимость)** — Чисто текстовое изменение: `git revert` PR полностью откатывает; нет
|
||
миграций/состояния/kill-switch (нечего гейтить — поведение кода идентично).
|
||
|
||
## 6. Допущения и ограничения
|
||
- Промпты 52d в `main` — стабильная база; 52e накладывается на неё (XML-канон не меняем).
|
||
- Стандарт `PIPELINE_DOCS.md`/`HANDOFF_PROTOCOL.md` — соседи нового `TRACEABILITY.md` в
|
||
`docs/_standards/`; формат и тон выдерживаются в том же стиле.
|
||
- Реальный пример в стандарте ссылается на существующие в `main` файл `src/` + ADR (проверяемость).
|
||
- Архитектурное обоснование (нужен ли сквозной ADR, точные формулировки правок промптов) —
|
||
зона архитектора (`06-adr`), не аналитика.
|
||
|
||
## 7. Критерии успеха
|
||
Создан стандарт маркеров с реальным примером; правило чтения есть в developer/architect, reviewer
|
||
его проверяет; fallback-доступ и анти-археология задокументированы; 52d не продублирована; код не
|
||
изменён, анти-регресс промптов держится, регресс зелёный; доки обновлены. Детальные PASS/FAIL —
|
||
`03-acceptance-criteria.md`.
|
||
|
||
## 8. Риски
|
||
- **Дублирование 52d** (правило уже частично есть) → митигируется явной сверкой (см. §1, BR-6) и
|
||
ссылками вместо повтора.
|
||
- **Расползание в ретро-фит** (соблазн расставить маркеры по коду) → жёсткая граница «вне объёма».
|
||
- **Регресс промптов** (потеря verdict-ключа/запрета при точечной правке) → анти-регресс-тест (NFR-2).
|
||
- Детальный разбор технических рисков — `10-tech-risks.md` (заполняет архитектор).
|