## Context

WealthLedger использует project-local OpenSpec schema поверх CLI 1.10.0,
canonical store в отдельном specs-репозитории и project-owned OpenCode
entrypoints в unversioned workspace root. Schema уже задаёт последовательный
artifact graph, а repository scripts защищают store authority, Delivery Map и
terminal verification. Однако planning quality до Apply проверяется
неравномерно, Tasks не имеют машиночитаемой связи с requirements и delivery
areas, а root agent projection проверяется только как локально существующее
состояние и не восстанавливается из четырёх Git-репозиториев.

Custom schema API остаётся experimental, поэтому совместимость нельзя безопасно
выводить только из SemVer. Root workspace не является Git-репозиторием;
versioned authority для новых guardrails и projection recovery должен
принадлежать `specs`, а as-built policy, audit snapshots и dispositions —
`docs`. Других active OpenSpec changes нет. Этот change создан по schema version
1, поэтому его собственные Tasks должны вручную соответствовать утверждённому
v2 contract до того, как Apply сделает этот contract default для будущих
changes.

## Goals / Non-Goals

**Goals:**

- сделать planning structure, task ownership и requirement coverage
  детерминированно проверяемыми до Apply;
- восстановить project-owned agent workflow из versioned inputs и обнаруживать
  drift derived projection;
- сохранить один exact supported CLI contract, пригодный для контролируемого
  будущего upgrade;
- распределить guidance между schema, config, durable policy и verifiers без
  конкурирующих источников;
- сохранить все source assessments и нормализовать их claims с доказательными
  dispositions;
- сохранить пропорциональность workflow и существующие human approval gates.

**Non-Goals:**

- обновление OpenSpec CLI в этом change;
- изменение frontend, backend, runtime API или deployment behavior;
- универсальная схема для других проектов, Fast Track или второй lifecycle;
- собственный workflow engine, identity/signature system для approvals или
  общий dependency scheduler для changes;
- автоматическое доказательство смысловой полноты Proposal, Specs или Design;
- новые review, completion, blocker, revision либо traceability artifacts.

## Decisions

### 1. Native schema v2 остаётся workflow engine

`wealth-ledger-sdd` повышается до version 2, сохраняя граф
`Proposal → Delta Specs → Design → Tasks → Apply`. Изменяется contract
существующих artifacts, а не их число. Schema и templates задают обязательную
форму Tasks, условный rollback contract, stage validation guidance, полный
feedback path и компактные примеры сложных delta operations. Minimal spec
template остаётся ориентированным на `ADDED`; неиспользуемые delta sections не
генерируются как пустые placeholders.

Artifact approval остаётся человеческим фактом разговора. File existence и
CLI status продолжают означать только structural state. Форматное исправление,
не меняющее approved semantics, повторяет structural checks без каскадного
reapproval; любое изменение intent, behavior, architecture или task scope
возвращает workflow к самому раннему затронутому artifact и инвалидирует его
downstream approvals.

### 2. Guidance имеет явных владельцев

Ответственность разделяется так:

| Surface | Authority |
| --- | --- |
| schema instructions | artifact semantics, native syntax и workflow behavior |
| templates | только форма создаваемого Markdown |
| config context | стабильные факты workspace и язык project artifacts |
| config rules | только краткие additive project constraints, отсутствующие в schema |
| governance и ADR | durable rationale, ownership и upgrade policy |
| non-mutating verifiers | Enforceable Engineering Invariants |

Текущие config rules, дословно повторяющие schema, удаляются или сокращаются;
произвольный `_rules.md` не вводится. Project explanations пишутся по-русски,
а OpenSpec tokens, headings, commands и normative keywords сохраняются в их
точной английской форме.

### 3. Planning verifier отделён от full delivery dispatcher

`specs` получает один stage-aware non-mutating planning verifier. Он разрешает
change через canonical store и применяет только доступные на текущем этапе
checks:

- Proposal — metadata, обязательную структуру и разрешимость declared existing
  capability paths;
- Delta Specs — strict change validation и соответствие capability set
  Proposal;
- Design — Delivery Map, Contract Gate Decision и rollback decision;
- Tasks — checkbox shape, area ownership, canonical gate coverage и точные
  requirement references, включая explicit `N/A` rationale.

Verifier не пытается машинно оценивать качество мотивации, архитектурного
rationale или semantic correctness. Full workspace dispatcher вызывает его
перед affected-area gates, а artifact entrypoints запускают доступный stage до
запроса approval. Проверяемая логика получает compliant fixtures и
representative failures для uncovered requirement, invalid area, malformed
rollback decision и projection/version drift. Существующие parsers Delivery Map
переиспользуются либо извлекаются, а не дублируются вторым несовместимым
разбором.

### 4. Tasks используют area owner и встроенную coverage metadata

Каждый checkbox использует формат `X.Y [area] action`, где `area` — ровно одна
из `frontend`, `backend`, `specs`, `docs`, `workspace`. Следующие indented
metadata lines содержат:

- `Covers`: одна или несколько пар `capability path — exact Requirement
  heading` либо `N/A — concrete reason`;
- `Verification`: planned command, observable check или delivered artifact.

OpenSpec продолжает отслеживать progress по checkbox line, а planning verifier
связывает последующие metadata lines с ближайшим checkbox. Cross-repository
implementation разбивается по repository owners; `workspace` используется
только для orchestration и verification. Requirement heading остаётся native
identity OpenSpec; дополнительный ID namespace не создаётся.

### 5. Root agent projection получает versioned canonical source

Текущие project-owned `commands` и `skills` импортируются как canonical source
tree под `specs/agent-projection/opencode`. Package manifests, installed
dependencies и machine-local runtime state не входят в source. Явная sync
команда атомарно обновляет соответствующие каталоги root `.opencode`, а
отдельный non-mutating verifier сравнивает required file set и contents с
canonical source.

На upgrade новая upstream projection сначала создаётся в isolated staging.
Upstream delta и минимальные WealthLedger overlays — fixed store,
one-artifact-at-a-time approvals, feedback path и hard archive blockers —
переносятся в canonical source, после чего sync обновляет root derived output.
Authority verifier получает expected version из единственного version contract
и проверяет совпадение каждого required generated marker. Concrete CLI version
не закрепляется в verifier logic или fixtures независимо от contract.

Canonical source tree выбран вместо:

- patch set: меньше committed content, но patches хрупки к upstream text churn;
- custom generator: устраняет дублирование, но создаёт новый transformation
  engine и повышает maintenance cost;
- symlink: устраняет copy drift, но связывает agent discovery с filesystem и
  tool-specific symlink behavior;
- manual staging only: сохраняет текущую простоту, но не обеспечивает recovery
  из clean checkouts.

### 6. Rollback contract является условной частью Design

Design template получает внутри Migration Plan структурированный rollback
decision. Для auth/security, data integrity или migration, public contract и
других труднообратимых решений status `required` раскрывает trigger, actions,
data safety и verification. Для остальных changes status `N/A` требует
конкретной причины. Отдельный rollback artifact не создаётся.

У этого change rollback contract имеет status `N/A`: application data,
security behavior и public contracts не меняются, а committed specs/docs
обратимы через Git. Initial projection cutover выполняется атомарно и сохраняет
предыдущее local derived state до успешного verification, чтобы failed sync не
оставил частично обновлённый workspace.

### 7. Multi-source assessment хранит raw evidence и отдельный triage

Пять исходных model reports переносятся byte-for-byte в один dated audit
snapshot set под `docs/audits`; index обозначает их как external, non-authority
claims и фиксирует checksums. После проверки совпадения исходная unversioned
папка удаляется, чтобы не оставить competing copy.

Live registry получает нормализованные Audit IDs. Повторяющиеся claims имеют
одну запись со ссылками на все sources. Triage disposition
`confirmed | already-covered | rejected | deferred` хранится отдельно от
remediation status. Confirmed findings этого scope связываются с текущим active
change; already-covered получают existing evidence; rejected — rationale;
deferred — review trigger. Следующим planned remediation после завершения этого
change снова становится ранее выбранная auth platform assessment.

### 8. Version contract фиксирует совместимость, а не вечную версию

Текущая exact version остаётся неизменной. Появление новой stable версии не
блокирует delivery и не меняет contract автоматически. Future upgrade является
отдельным SDD change и проходит staged projection comparison, schema/status/
instructions compatibility, canonical-store checks, disposable lifecycle и
positive/negative authority fixtures. Historical archives и Completion Evidence
сохраняют фактические версии своих запусков.

## Delivery Map

| Area | Status | Architectural outcome or N/A reason |
| --- | --- | --- |
| frontend | `N/A` | Change не меняет frontend behavior, source, contract или canonical gate. |
| backend | `N/A` | Change не меняет backend behavior, source, contract или canonical gate. |
| specs | `affected` | Schema v2, planning/projection guardrails, canonical agent source и нормативные lifecycle requirements образуют единый проверяемый SDD contract. |
| docs | `affected` | Immutable multi-source audit, dispositions, governance, lifecycle documentation и ADR отражают поставленную SDD-систему. |

### Contract Gate Decision

| Gate | Status | Reason |
| --- | --- | --- |
| runtime-openapi | `N/A` | Change не затрагивает backend runtime API, frontend generated client или committed OpenAPI snapshot. |

## Solution Assessment

Change существенно меняет общую project tooling infrastructure, поэтому
сравнение alternatives обязательно.

### Workflow enforcement

| Option | Fit и maturity | Security / operating cost | Constraints / migration cost | Decision |
| --- | --- | --- | --- | --- |
| Native OpenSpec schema/config + thin project verifiers | Полностью сохраняет canonical artifact graph; используемые extension points уже работают в 1.10, хотя schema API experimental | Local-only, без новых secrets/services; низкая стоимость поверх существующих gates | Требует exact compatibility contract и fixtures при upgrade; incremental migration | Selected |
| Prompt/docs-only conventions | Markdown mature и дёшев, но не отклоняет нарушения | Низкая стоимость, высокий риск silent drift | Не выполняет требования machine validation и reproducibility | Rejected |
| Собственный workflow engine | Максимальный theoretical fit, но custom maturity отсутствует | Новый privileged control surface и высокая постоянная стоимость | Дублирует OpenSpec lifecycle, требует migration всех entrypoints и state | Rejected |
| Общая monorepo/CI platform | Зрелые продукты существуют, но workspace не имеет общего build/dependency graph и CI | Существенная installation и operating cost | Не решает approval semantics или audit traceability сама по себе | Rejected |

### Projection recovery

| Option | Fit и maturity | Operating cost | Main constraint | Decision |
| --- | --- | --- | --- | --- |
| Versioned canonical source tree + sync/check | Простая file projection с детерминированным сравнением | Низкая; около 115 KB source Markdown | Source и derived copy должны проверяться на drift | Selected |
| Versioned overlay patches | Компактно | Средняя/высокая при каждом upstream text change | Patch fragility | Rejected |
| Programmatic overlay generator | Гибко | Высокая; собственная transformation logic | Риск второго workflow engine | Rejected |
| Symlink в specs-owned tree | Минимум duplication | Низкая локально | Tool/filesystem portability и смешение machine-local package state | Rejected |

Выбранный вариант не реализует OpenSpec behavior самостоятельно: native CLI
остаётся engine, а project scripts только синхронизируют derived files и
проверяют детерминированные инварианты.

## Risks / Trade-offs

- **Canonical source и derived projection дублируют Markdown.** Drift блокирует
  verifier; изменения вносятся только в source и распространяются explicit
  sync-командой.
- **Markdown parser может стать хрупким.** Машиночитаемые prefixes и metadata
  намеренно узкие, fixture suite покрывает compliant и representative invalid
  inputs, а semantic review остаётся отдельным gate.
- **Traceability создаёт ложное ощущение semantic coverage.** Verifier
  подтверждает наличие ссылок, но semantic verification и independent review
  продолжают проверять полноту реализации.
- **Форматное исключение может скрыть semantic edit.** Оно ограничено ошибками,
  не меняющими intent, behavior, decisions или tasks; сомнение возвращает
  artifact на обычный reapproval path.
- **Schema instructions могут разрастись.** Duplicate config rules удаляются,
  examples остаются короткими, а final instruction size сравнивается с
  baseline без жёсткого token threshold.
- **Raw model reports могут выглядеть authoritative.** Snapshot index и registry
  явно разделяют source claims, triage evidence и project authority.
- **Initial source-tree bootstrap не имеет прежней versioned baseline.** Sync
  сохраняет local pre-cutover state до успешного gate; после поставки все
  дальнейшие projection versions становятся восстановимыми через Git history.
- **Future OpenSpec release может изменить experimental interfaces.** Exact
  contract блокирует silent adoption, а отдельный upgrade change выполняет
  staged compatibility assessment.

## Migration Plan

1. Ввести canonical projection source и non-mutating planning/projection checks,
   подтвердив compliant и controlled-invalid fixtures до переключения schema.
2. Обновить schema, templates, config и canonical agent source до v2 contract;
   собственные Tasks этого change оформить уже в новом формате.
3. Атомарно синхронизировать root derived projection и отклонить delivery при
   любом content/version drift.
4. Перенести raw assessments в immutable indexed snapshot, проверить
   byte-for-byte equality, удалить unversioned copy и обновить live registry.
5. Обновить governance, lifecycle docs и ADR до фактической архитектуры, затем
   выполнить specs/docs gates, semantic verification и independent review.

### Rollback Contract

| Field | Decision |
| --- | --- |
| Status | `N/A` |
| Reason | Change не меняет application data, security behavior или public contracts; committed state обратим через Git, а projection является derived output с atomic cutover. |
| Failed cutover handling | Sync восстанавливает сохранённое pre-cutover local state и не объявляет source/projection согласованными. |
| Verification | Planning, projection, authority, strict OpenSpec и docs gates должны снова подтвердить выбранное состояние. |