orchestrator/docs/architecture/adr/adr-0022-traceability-marker-standard.md

work_item, stage, author_agent, status, created_at, model_used

work_item	stage	author_agent	status	created_at	model_used
ORCH-078	architecture	architect	proposed	2026-06-09	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.