157 lines
14 KiB
Markdown
157 lines
14 KiB
Markdown
---
|
||
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` — зелёный.
|