---
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` (заполняет архитектор).
