ADR-0007: Operational Layer

Status

Accepted (2026-04-15)

Context

Внешний review манифеста дал оценку 8/10 как knowledge architecture, 6.5/10 как manifesto.

Knowledge architecture на месте: ADR, Decision-Log, агенты, процессы, роли, правила. Но отсутствует operational layer — как система принимает решения и останавливается без человека.

Без operational layer агенты не знают:

• Когда продолжать, когда спросить (→ Decision Rights)
• Что считается “сделано” (→ Definition of Done)
• Что делать если разошлись во мнениях (→ Conflict Resolution)
• Какие следы оставлять для аудита (→ Observability Contract)
• Что никогда не нарушается (→ Invariants)
• Когда конкретно останавливаться (→ Escalation Policy)

Week 3.1 reproducibility runs подтвердили проблему: 2/3 pipeline runs не прошли aggregation, cost tracking не работал в error paths, нет формального DoD для research tasks.

Decision

Добавлен Operational Layer — 7 документов в 00-Core/:

Документ	Назначение
Invariants	5 инвариантов — что никогда не нарушается
NorthStar	Миссия и единая метрика успеха
DecisionRights	Матрица: кто какие решения принимает
EscalationPolicy	6 конкретных триггеров остановки агента
DefinitionOfDone	DoD по типам задач (research, code, decision, pipeline)
ObservabilityContract	Какие артефакты обязательны после каждой задачи
ConflictResolution	4-шаговый алгоритм разрешения разногласий

Также обновлены:

• README.md — 5 Invariants + Decision Flow в топе
• Manifesto.md — секция Operational Layer со ссылками

Alternatives Considered

(a) Оставить как есть

• Pros: меньше документов, проще поддерживать
• Cons: агенты продолжают работать без формальных правил остановки; повторяются failure modes из Week 3.1; нет baseline для Judge agent (3.2)
• Вердикт: отклонено — проблема подтверждена эмпирически

(b) Встроить в существующие ADR и Rules

• Pros: не создаёт новых файлов, использует существующую структуру
• Cons: размазывает operational concerns по 10+ файлам; агент не может процитировать конкретный пункт; нарушает принцип “один концепт — один файл”
• Вердикт: отклонено — operational layer это отдельный concern

(c) Отдельный слой в 00-Core/ ← выбрано

• Pros: каждый документ — one-pager; агент цитирует конкретный INV-N или триггер; не трогает существующие ADR/Rules; добавляет machine-checkable условия
• Cons: +7 файлов в vault; нужно поддерживать в sync с кодом
• Вердикт: принято — операбельность важнее минимализма

Consequences

Что теперь агенты обязаны делать иначе

1. До выполнения задачи: проверить budget (INV-3), проверить тип решения по DecisionRights
2. Во время: мониторить cost/confidence/scope (EscalationPolicy триггеры)
3. После: записать _meta (ObservabilityContract), проверить DoD
4. При конфликте: алгоритм ConflictResolution, не усреднение
5. При failure: записать _meta даже в error path (INV-2, INV-3)

Что нужно доработать в коде (synth-brain)

• mark_task_done() — проверять DoD перед сменой статуса
• LLM agents — писать _meta в error path
• Director aggregate — увеличить max_tokens (failure mode из 3.1)
• Judge agent (3.2) — автоматическая проверка DoD + ObservabilityContract

Риски

• Over-documentation: агенты “цитируют” правила но не следуют
• Drift: код и манифест расходятся — нужен periodic sync check