orchestrator/docs/work-items/ORCH-078/02-trz.md

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

02 — ТЗ (TRZ): ORCH-078 — ORCH-52e: трассировка ORCH-NNN (маркеры-стандарт + правило чтения)

Work Item: ORCH-078 · Repo: orchestrator (self-hosting) · Стадия: analysis

ТЗ описывает конкретные изменения (выведенные из BRD и фактического содержимого репозитория). Архитектурное обоснование (нужен ли сквозной ADR, точные формулировки врезок в промпты, форма стандарта) — задача архитектора (06-adr). Это docs + prompts-only задача: src/** не меняется.

1. Сводка изменения

Ввести формальный стандарт маркеров-трассировки docs/_standards/TRACEABILITY.md и точечно (не переписывая) дополнить 3 системных промпта правилом чтения ADR перед правкой маркированного кода (developer/architect) и контролем его соблюдения (reviewer). Задокументировать fallback-доступ к чужому work item и анти-археологию (3+ маркеров → сводный сквозной ADR). Сопутствующе обновить CLAUDE.md, docs/architecture/README.md, CHANGELOG.md; расширить структурный анти-регресс-тест промптов. Существующие 51 маркер в src/ не переразмечаются.

2. Задействованные модули / пути

Путь	Действие
docs/_standards/TRACEABILITY.md	создать (новый стандарт; см. FR-1)
.openclaw/agents/developer.md	точечно дополнить — правило чтения + fallback-доступ (FR-2, FR-5); ссылка на стандарт
.openclaw/agents/architect.md	точечно дополнить — правило чтения + анти-археология (FR-3, FR-6); ссылка на стандарт
.openclaw/agents/reviewer.md	точечно дополнить — ось контроля соблюдения трассировки (FR-4); ссылка на стандарт
CLAUDE.md	обновить — раздел «Правила для агентов» / «Конвенции»: правило трассировки + ссылка на TRACEABILITY.md (FR-7)
docs/architecture/README.md	обновить — упоминание стандарта как слоя 4 эпика 52 (FR-7)
CHANGELOG.md	добавить запись ## [Unreleased]
tests/test_agent_prompts_canon.py	расширить (tests-only) — анти-регресс reading-rule маркеров (FR-8); НЕ трогает src/
docs/work-items/ORCH-078/06-adr/ADR-001-*.md	создать (архитектор)
docs/architecture/adr/adr-NNNN-*.md	создать при необходимости (архитектор, если решение сквозное)
НЕ трогать	src/** (любой), STAGE_TRANSITIONS, QG_CHECKS, check_*, _parse_*, src/frontmatter.py, схема БД; XML-канон и 52c-эмиссия промптов 52d

3. Функциональные требования

FR-1 — Стандарт docs/_standards/TRACEABILITY.md (BR-1, BR-4, BR-5)

Новый нормативный документ в стиле соседей (PIPELINE_DOCS.md/HANDOFF_PROTOCOL.md). Обязательные смысловые блоки:

1. Назначение и определение. Маркер ORCH-NNN (и ET-NNN) в коде = обязательный стандарт трассировки: привязка нетривиальной строки/блока/инварианта к work item, который его ввёл, и к его ADR. (Зафиксировать существующий факт: ~51 уникальный маркер в src/.)
2. Формат маркера. Inline-комментарий, содержащий ORCH-NNN (например, в docstring модуля и/или у строки инварианта); рекомендуется указывать ссылку на решение (ORCH-088, ADR-001 D1). Не вводить нового синтаксиса — кодифицировать сложившийся.
3. Где ставится. Рядом с нетривиальным инвариантом (fail-open/fail-closed выбор, точное условие сериализации, идемпотентность, обходимая дыра конвейера), а не на тривиальном/ самоочевидном коде. Правило для нового кода: вводишь значимый инвариант → ставь маркер своей задачи рядом.
4. Как читать историю — с РЕАЛЬНЫМ примером (AC-1). Пошагово: маркер в коде → docs/work-items/ ORCH-NNN/06-adr/. Обязателен ≥1 проверяемый пример из существующего кода, например: src/serial_gate.py строка t2.id < jobs.task_id несёт маркер ORCH-088 (ADR-001 D1 / FR-2, FIFO-уточнение) → читать docs/work-items/ORCH-088/06-adr/ADR-001-serial-gate.md. Пример обязан ссылаться на реально существующие в main файл и ADR.
5. Fallback-доступ (BR-4). Если папки docs/work-items/ORCH-NNN/ нет в текущей ветке (срезана от main без неё) — читать из origin/main: git show origin/main:docs/work-items/ORCH-NNN/06-adr/ADR-001-<slug>.md (при необходимости git fetch origin заранее; листинг — git ls-tree origin/main:docs/work-items/ORCH-NNN/06-adr/).
6. Анти-археология (BR-5). Если функция/блок несёт 3+ маркеров ORCH-NNN — вместо раскопок по каждому work item ставится сводная ссылка на один сквозной ADR (docs/architecture/adr/ adr-NNNN-*), агрегирующий эволюцию. Пример из кода: src/merge_gate.py несёт ORCH-043/065/071/073 → сводные сквозные adr-0006/adr-0013/adr-0014/adr-0016.
7. Правило чтения (нормативная формулировка). «Правишь код с маркером ORCH-NNN → прочитай его 06-adr ПЕРЕД изменением; не сломай зафиксированный инвариант; не можешь — эскалируй/верни в анализ» — каноничный текст, на который ссылаются промпты (BR-6: единый источник, без повтора).

FR-2 — Правило чтения в developer.md (BR-2)

Точечная врезка (НЕ перезапись), сохраняющая 5 XML-секций и 52c-эмиссию. В <constraints> (и/или <context> списком «что прочесть») добавить пункт в формате «❌ X → ✅ Y»:

• ❌ Не правь строку/блок с маркером ORCH-NNN вслепую → ✅ перед изменением прочитай docs/work-items/ORCH-NNN/06-adr/ и не сломай зафиксированный инвариант; стандарт — docs/_standards/TRACEABILITY.md.
• Включить fallback-доступ (FR-5). Существующее 52d-упоминание «реализуй по 06-adr/» относится к ADR текущей задачи — НЕ дублировать, а дополнить правилом для чужих маркеров.

FR-3 — Правило чтения + анти-археология в architect.md (BR-2, BR-5)

Точечная врезка: при изменении маркированного компонента архитектор обязан свериться с ADR work item(ов), породивших инвариант; при введении/правке блока с 3+ маркерами — оформить/обновить сводный сквозной ADR (docs/architecture/adr/) согласно TRACEABILITY.md §анти-археология. Ссылка на стандарт; без перезаписи существующих секций.

FR-4 — Контроль соблюдения в reviewer.md (BR-3)

Точечная врезка в ось «Соответствие ADR» (или новый под-пункт): reviewer проверяет, что правка кода, несущего чужой маркер ORCH-NNN, сверена с его 06-adr и не ломает инвариант; нарушение (правка маркированного инварианта без обоснования / со сломом) → finding. Рекомендуемая severity — P1 (must-fix); слом критического инварианта конвейера может быть P0 на усмотрение reviewer. Ссылка на TRACEABILITY.md. НЕ дублировать существующую общую ADR-ось — усилить её этим под-пунктом.

FR-5 — Fallback-доступ задокументирован (BR-4)

Команда git show origin/main:docs/work-items/ORCH-NNN/06-adr/... присутствует и в TRACEABILITY.md (FR-1.5), и в developer.md (рядом с правилом чтения), чтобы агент, у которого нет папки в ветке, знал штатный способ прочитать чужой ADR.

FR-6 — Анти-археология зафиксирована (BR-5)

Конвенция «3+ маркеров → сводный сквозной ADR» присутствует в TRACEABILITY.md (FR-1.6) и в architect.md (FR-3). Reviewer может опираться на неё при ревью (FR-4).

FR-7 — Сопутствующая документация (BR-7)

• CLAUDE.md — в «Правила для агентов» и/или «Конвенции» добавить правило трассировки одной строкой
  • ссылку на docs/_standards/TRACEABILITY.md (по образцу того, как там уже ссылаются на PIPELINE_DOCS.md/HANDOFF_PROTOCOL.md).
• docs/architecture/README.md — в разделе про стандарты документов конвейера (ORCH-075/077) упомянуть TRACEABILITY.md как слой 4 (трассировка) эпика ORCH-52 со ссылкой.
• CHANGELOG.md — запись под ## [Unreleased] (docs:).

FR-8 — Анти-регресс промптов (NFR-2)

Расширить tests/test_agent_prompts_canon.py (tests-only, src/ не трогается) так, чтобы он утверждал присутствие reading-rule маркеров в developer/architect/reviewer (напр. строка TRACEABILITY и/или паттерн правила чтения у маркированного кода) — аналогично существующим _ANTI_REGRESS-проверкам. Существующие проверки 52d (5 XML-секций, 6 полей схемы, точный регистр verdict-ключей, self-hosting-маркеры deployer) остаются и зелёные; tests/test_agent_frontmatter_no_model.py остаётся зелёным.

4. Изменения API

Нет. Эндпоинты не добавляются/не меняются.

5. Изменения схемы БД

Нет. Таблицы/миграции/индексы не трогаются.

6. Требования к новым/изменённым QG checks

Нет. QG_CHECKS, check_*, _parse_*, STAGE_TRANSITIONS — без изменений. frontmatter_validation_strict остаётся False; enforcement не вводится. Новый QG не добавляется (стандарт трассировки — нормативный документ + анти-регресс-тест промптов, не машинный гейт конвейера).

7. Совместимость / регресс

• Нулевое касание кода (NFR-1): меняются только docs/** и .openclaw/agents/*.md (+ tests-only расширение структурного теста). Поведение src/ идентично → нулевая функциональная регрессия, enduro-trails не затронут.
• Анти-регресс промптов (NFR-2): точечные врезки сохраняют 5 XML-секций, 52c-эмиссию и machine-verdict ключи байт-в-байт; гарантируется расширенным test_agent_prompts_canon.py.
• Self-hosting (NFR-4): промпт cat-ается из worktree при запуске → новое правило действует на следующем worktree от main без прод-рестарта (8500).
• Обратимость (NFR-5): чисто текстовое изменение; git revert PR — полный откат; kill-switch не нужен (нет машинного поведения); нет миграций/состояния.
• Анти-дубль (BR-6): промпты ссылаются на единый текст правила в TRACEABILITY.md, а не повторяют его; 52d-канон не переписывается.
• Тесты: полный pytest tests/ -q — зелёный.