admin/orchestrator
1
0
Fork 0
Code Issues Pull Requests 4 Actions Packages Projects Releases Wiki Activity
Files
8064ae2c5def117d3f2da390816637dbf7b18bf4
orchestrator/docs/work-items/ORCH-078/01-brd.md

14 KiB
Raw Blame History

work_item, stage, author_agent, status, created_at, model_used
work_item stage author_agent status created_at model_used
ORCH-078 analysis analyst ready-for-review 2026-06-09 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 (заполняет архитектор).
Reference in New Issue View Git Blame Copy Permalink