---
work_item: ORCH-078
stage: architecture
author_agent: architect
status: proposed
created_at: 2026-06-09
model_used: claude-opus-4-8
---

# adr-0022: Стандарт маркеров-трассировки `ORCH-NNN` + правило чтения ADR перед правкой

- **Статус:** proposed
- **Дата:** 2026-06-09
- **Источник:** ORCH-078 (эпик ORCH-52, слой 52e — трассировка, слой 4)
- **Связи:** продолжает цепочку стандартов эпика 52 — adr-0019 (52b, `PIPELINE_DOCS.md`),
  adr-0020 (52c, frontmatter-контракт), adr-0021 (52d, канон промптов). Детально —
  `docs/work-items/ORCH-078/06-adr/ADR-001-traceability-marker-standard.md`.

## Контекст

Эпик ORCH-52 строит сквозной контракт документации конвейера: **52b** (adr-0019) — описательный
стандарт документов + скелеты; **52c** (adr-0020) — машинный frontmatter-контракт + `HANDOFF_PROTOCOL.md`;
**52d** (adr-0021) — 6 промптов в каноне Anthropic + добровольная эмиссия 52c-схемы. Закрыты слои
структуры (52b), машинного вердикта (52c) и формы промптов (52d), но **слой трассировки кода к
решениям не формализован**.

Факты, сверенные с кодом `main`:
- В `src/` живёт **51 уникальный** маркер `ORCH-NNN` (`grep -rhoE 'ORCH-[0-9]+' src/ | sort -u | wc -l`),
  привязывающий нетривиальные инварианты к породившему их work item — **сложившаяся практика без
  формального стандарта** (`docs/_standards/` несёт лишь `PIPELINE_DOCS.md`/`HANDOFF_PROTOCOL.md`).
- Высокая плотность: `config.py`=63, `stage_engine.py`=55, `agents/launcher.py`=50, `plane_sync.py`=48,
  `merge_gate.py`=26 вхождений.

Три незакрытые проблемы:
1. **Нет правила чтения.** Агент, правя маркированную строку, не обязан прочитать ADR, который её
   ввёл → риск молча сломать инвариант. Это класс «фантомного merge»
   (`docs/history/LESSONS_2026-06-08_phantom-merge.md`), породившего ORCH-071/073.
2. **Reviewer не контролирует соблюдение** — ось «Соответствие ADR» проверяет ADR текущей задачи, не
   сверку правки чужого маркированного кода с его ADR.
3. **Анти-археология** — блок с 50+ маркерами = раскопки по 4+ work item.

## Решение

Ввести **нормативный стандарт маркеров-трассировки** `docs/_standards/TRACEABILITY.md` (слой 4 эпика
52) и точечно дополнить промпты правилом чтения / контролем соблюдения **со ссылкой на единый
источник**. Это **docs + prompts-only**, нулевое касание кода; стандарт — описательно-нормативный
документ + анти-регресс-тест промптов, **не машинный гейт конвейера**.

1. **`TRACEABILITY.md`** кодифицирует существующий контракт (не вводит новый синтаксис): определение
   маркера, формат (inline-комментарий, рекомендуется ссылка на решение), правило размещения (рядом с
   нетривиальным инвариантом), чтение истории **с реальным проверяемым примером**
   (`src/serial_gate.py` → ORCH-088 → `ADR-001-serial-gate.md`), fallback-доступ, анти-археология,
   каноничный текст правила чтения.
2. **Единый источник истины правила.** Каноничная формулировка живёт только в `TRACEABILITY.md`;
   промпты несут короткую врезку-**ссылку**, не копию → нет дрейфа между файлами (анти-дубль 52d).
3. **Точечные врезки (аддитивно, 52d-канон не переписывается):** `developer.md` — правило чтения +
   fallback-доступ («❌ X → ✅ Y»); `architect.md` — правило чтения + анти-археология; `reviewer.md` —
   усиление оси «Соответствие ADR» под-пунктом «правка маркированного кода сверена с его ADR; слом →
   finding ≥P1».
4. **Анти-археология:** блок с **≥3** маркерами → одна сводная ссылка на сквозной ADR
   (`docs/architecture/adr/`) вместо перечисления всех work item. Пример: `src/merge_gate.py` →
   `adr-0006/0013/0014/0016`.
5. **Fallback-доступ:** `git show origin/main:docs/work-items/ORCH-NNN/06-adr/ADR-001-<slug>.md` —
   когда папки нет в текущей ветке.
6. **Анти-регресс машинно:** расширение `tests/test_agent_prompts_canon.py` (tests-only) — утверждает
   присутствие reading-rule/`TRACEABILITY`-маркеров; существующие проверки 52d и
   `test_agent_frontmatter_no_model.py` остаются зелёными.

**Границы:** `src/**`, `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, `_parse_*`, `src/frontmatter.py`,
схема БД — **не трогаются**. `frontmatter_validation_strict` остаётся `False`; новый QG не вводится.
Массовый ретро-фит 51 существующего маркера **вне объёма** — стандарт действует «на будущее».

**Норматив на будущее:** новый/правимый значимый инвариант → ставь маркер своей задачи рядом; блок с
3+ маркерами → сводный сквозной ADR; правка чужого маркера → читай его `06-adr` до изменения.

## Альтернативы

- **Машинный гейт/CI-lint маркеров.** Отвергнуто: правка `src/`/CI вне scope; для self-hosting
  рискованно (ложный fail валит конвейер всех проектов); премэйчур до описательного стандарта.
  Enforcement — потенциальная будущая задача (как hard-fail схемы в adr-0021).
- **Массовый ретро-фит 51 маркера.** Отвергнуто: огромный диф, риск регресса смысла, вне объёма.
- **Копировать правило в каждый промпт.** Отвергнуто: дрейф между файлами, нарушение анти-дубль.
- **Только per-work-item ADR без глобального.** Отвергнуто: рвёт цепочку эпика 52 (52b/c/d имеют
  глобальный ADR); нет точки входа для будущих агентов.

## Последствия

- **+** Замкнут слой 4 эпика 52: практика маркеров формализована, правило чтения защищает от слома
  инвариантов; reviewer получает ось контроля.
- **+** Единый источник правила → нет дрейфа; обновление в одном файле.
- **+** Self-hosting без рестарта: промпт `cat`-ается из worktree → правило действует на следующем
  worktree от `main` без рестарта 8500.
- **+** Полная обратимость: чисто текстовое изменение, нет миграций/состояния/kill-switch.
- **−** Рост объёма 3 промптов (митигейшн: короткие врезки-ссылки).
- **−** Стандарт нормативен, но не enforced машинно → соблюдение на дисциплине + ревью (осознанный
  компромисс).
- **Откат:** `git revert` PR — стандарт удаляется, врезки исчезают, поведение кода/гейтов идентично.

## Связи
- Продолжает: adr-0019 (52b), adr-0020 (52c), adr-0021 (52d).
- Per-work-item: `docs/work-items/ORCH-078/06-adr/ADR-001-traceability-marker-standard.md`.
- Стандарты-соседи: `docs/_standards/PIPELINE_DOCS.md`, `docs/_standards/HANDOFF_PROTOCOL.md`,
  будущий `docs/_standards/TRACEABILITY.md` (создаёт стадия development).
- Сверено по коду: `src/serial_gate.py:241,269` (ORCH-088), `src/merge_gate.py` (26 маркеров),
  `tests/test_agent_prompts_canon.py`, `.openclaw/agents/{developer,architect,reviewer}.md`.
- Прецедент класса ошибки: `docs/history/LESSONS_2026-06-08_phantom-merge.md`.
