## Context

Project-local schema v2 уже владеет SDD semantics, а stage-aware verifier
проверяет artifact graph, coverage и Delivery Map. При этом обязательные правила
распределены внутри длинных instructions, единый Delta Spec template начинает с
`ADDED Requirements`, а planning failures не имеют общего явного разделения на
artifact, invocation и environment причины. OpenSpec CLI 1.10.0 остаётся
project version contract; schema API имеет experimental status, поэтому решение
должно сохранять native graph и не вводить новый workflow engine.

Шесть second-round reports находятся как локальный неversioned corpus. Они
содержат повторы прежних claims, предложения, противоречащие действующей policy,
и неполный provenance. Existing remediation workflow уже определяет immutable
snapshot и отдельный live triage, поэтому новый формат evidence не требуется.

## Goals / Non-Goals

**Goals:**

- Сохранить project schema единственным владельцем artifact semantics, сделав
  Critical Rules первыми и устранив повторяющийся explanation text.
- Сохранить один native artifact graph и сделать Delta Spec scaffold нейтральным
  к operation.
- Дать planning verifier устойчивую taxonomy отказов и оставить semantic
  качество `N/A` rationale на human review boundary.
- Использовать уже разрешённый CLI context и существующую repository routing
  policy без второго mapping authority.
- Зафиксировать второй review corpus и его triage в существующей audit model.

**Non-Goals:**

- Универсализация topology за пределы WealthLedger.
- Persistent approval state, дополнительные review/done/solution artifacts или
  cross-change dependency graph.
- CI, commit convention, task sizing, Success Metrics либо schema changelog.
- Числовой quality threshold для instruction size, checksum или byte-count gate
  для audit reports.
- Изменение application runtime, данных или API contract.

## Decisions

### 1. Сохранить текущие authority boundaries и выпустить schema v3

Schema продолжает владеть normative agent semantics; templates владеют исходной
формой artifacts, project config содержит только устойчивый context, scripts
реализуют детерминированные hard invariants, а durable docs описывает as-built
process. Каждая artifact instruction начинается с компактного блока Critical
Rules, после которого идут только stage-specific details. Пояснения приводятся
по-русски, а exact OpenSpec tokens, headings, commands и SHALL/MUST сохраняются
на английском.

Material instruction, template и verifier contract change повышает schema
version до 3. Исторический rationale остаётся в canonical change, archive,
registry и Git history; отдельный changelog не создаётся.

### 2. Сделать Delta Spec scaffold operation-neutral

Единый template не может знать, новая capability или существующая и какая delta
operation требуется. Поэтому он не создаёт активные operation headings, а через
Markdown comments показывает выбор из `ADDED`, `MODIFIED`, `REMOVED`, `RENAMED`
и условный `Purpose`. Агент добавляет только применимые sections. Компактная
shape guidance перемещается из длинной Specs instruction в template comments;
semantic rules полного `MODIFIED`, полей `REMOVED` и формата `RENAMED` остаются
в schema.

### 3. Ввести три machine-distinguishable класса planning failure

Verifier использует стабильные категории результата:

- `artifact-validation` с exit 1 — artifact существует, но нарушает проверяемую
  форму или ссылочную целостность; разрешено исправить только указанное
  нарушение;
- `invocation` с exit 2 — неверное число аргументов, имя или неразрешимый change;
  исправляется вызов, а не artifact;
- `environment` с exit 3 — отсутствует или несовместим runtime, CLI либо другой
  prerequisite; сначала диагностируется окружение, artifact не меняется.

Project instruction ссылается на эти категории и не вводит retry counter.
Unexpected internal failure остаётся blocking result и не маскируется под
artifact validation.

### 4. Разделить structural и semantic качество `N/A`

Hard guardrail отклоняет пустую причину, одиночный separator и неразрешённый
template placeholder. Instruction и template требуют объяснить отсутствие
самостоятельного observable behavior, техническую необходимость и связь с
утверждённым Design или delivery. Смысл непустого rationale оценивают Change
Owner и independent review; blacklist слов и эвристический natural-language
checker не добавляются.

### 5. Использовать CLI-resolved context

Apply instruction прямо требует прочитать все paths из `contextFiles`,
возвращённых native OpenSpec instructions, затем applicable local routing
instructions affected areas. Он не вычисляет planning paths и не требует нового
context map. Это сохраняет portable CLI state единственным владельцем resolved
artifact context.

### 6. Включить review corpus без дополнительной integrity ceremony

Шесть reports переносятся в новый immutable audit snapshot set без изменения
их текста. Короткий index перечисляет sources и известные provenance
ограничения; checksum, byte-count manifest и отдельный validation framework не
добавляются. Live registry дедуплицирует claims против существующих Audit IDs:
повторы получают existing evidence/rationale, а действительно residual gaps —
новые follow-up records, связанные с этим change.

### 7. Проверять сохранение invariants, а не оптимизировать цифру

Verification сопоставляет принятые lifecycle invariants с одним authoritative
owner, проверяет compliant и controlled-invalid cases для новых hard guards и
фиксирует наблюдаемое удаление duplication. Instruction length может быть
сообщена как diagnostic, но не становится blocking threshold. Внешний model
score не является completion evidence.

## Delivery Map

| Area | Status | Architectural outcome or N/A reason |
| --- | --- | --- |
| frontend | `N/A` | Client behavior, implementation и local gate не меняются. |
| backend | `N/A` | API behavior, implementation и local gate не меняются. |
| specs | `affected` | Schema v3, planning verifier, templates, fixtures и canonical Delta Specs поставляют новый workflow contract. |
| docs | `affected` | Второй audit snapshot, live triage и as-built lifecycle documentation отражают поставленный process. |

### Contract Gate Decision

| Gate | Status | Reason |
| --- | --- | --- |
| runtime-openapi | `N/A` | Ни backend runtime contract, ни frontend committed client snapshot не меняются. |

## Solution Assessment

Change существенно меняет shared agent tooling, поэтому применён обязательный
build-versus-buy review.

| Option | Fit and maturity | Security / operating cost | Constraints / migration cost | Decision |
| --- | --- | --- | --- | --- |
| Native project OpenSpec schema, templates и existing verifier | Полностью сохраняет используемый OpenSpec 1.10.0 graph и уже поставленные project gates. | Не добавляет runtime или data surface; поддерживается текущими local gates. | Требует узкой правки project-owned contracts и controlled fixtures; active changes остаются совместимыми по artifact IDs. | Selected. |
| Global agent prompt или внешний common-rules file | Может сократить schema text, но загрузка зависит от agent framework и не гарантируется native OpenSpec. | Создаёт competing authority и постоянную стоимость синхронизации. | Потребовал бы projection/versioning discipline и миграцию всех entrypoints. | Rejected. |
| Дополнительный workflow framework или новые approval/context/done artifacts | Может хранить больше machine-readable state, но дублирует native graph и решает неподтверждённые risks. | Увеличивает process surface и число stale states без security benefit. | Высокая миграционная и эксплуатационная стоимость; конфликт с утверждённой governance. | Rejected. |

Native project-local schema выбрана потому, что текущий OpenSpec 1.10.0 contract
уже предоставляет используемую extension boundary для artifacts, templates и
instructions, а external prompt и дополнительные state artifacts не выполняют
утверждённые authority constraints. Review trigger: несовместимое изменение
native schema API либо появление поддерживаемого OpenSpec mechanism для общих
typed rules и failure classification.

## Risks / Trade-offs

- **При сокращении потеряется обязательное правило.** Mitigation: inventory
  действующих invariants, authority fixtures и semantic comparison до/после.
- **Neutral scaffold даст слишком мало shape guidance.** Mitigation: commented
  operation menu и controlled deltas для всех четырёх operations.
- **Failure будет отнесён не к той категории.** Mitigation: отдельные controlled
  failures для artifact, invocation и environment paths; неожиданный failure
  остаётся blocking.
- **Непустой, но слабый `N/A` пройдёт structural gate.** Это осознанный trade-off:
  semantic approval и independent review остаются владельцами смысла, чтобы
  эвристика не выдавала false confidence.
- **Schema v3 применяется к текущему active change.** Mitigation: artifact IDs и
  dependency graph не меняются; current change повторно проходит planning и
  strict schema/change validation после migration.

## Migration Plan

1. Сначала обновить normative schema contract и operation-neutral template,
   сохранив artifact IDs и dependency graph.
2. Затем обновить verifier taxonomy и controlled fixtures, после чего повторно
   проверить active change новым contract.
3. Перенести review corpus в immutable docs snapshot, выполнить deduplicated
   triage и синхронизировать as-built lifecycle wording.
4. Выполнить canonical gates affected areas, semantic verification и
   independent read-only review до archive.

### Rollback Contract

| Field | Decision |
| --- | --- |
| Status | `N/A` |
| Reason | Изменение обратимо в versioned tooling/docs, не меняет auth, данные, migration или public contract и не требует отдельного rollback contract. |
| Trigger | N/A |
| Actions | N/A |
| Data safety | N/A; application data не затрагиваются. |
| Verification | N/A |