--- work_item: ORCH-078 stage: analysis author_agent: analyst status: ready-for-review created_at: 2026-06-09 model_used: 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-.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-эмиссию. В `` (и/или `` списком «что прочесть») добавить пункт в формате «❌ 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` — зелёный.