---
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-<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` — зелёный.
