# Оценка OpenSpec-схемы `wealth-ledger-sdd` (v2)

**Дата:** 2025-08-25  
**Схема:** `wealth-ledger-sdd` version 2  
**Контекст:** multi-repo pet-проекты, выделенный specs-store (`wealth-ledger-specs`), AI-агент с доступом ко всем репозиториям, SDD через OpenSpec.

---

## 1. Краткий вердикт

| Метрика | Оценка |
|--------|--------|
| Общая зрелость | **9.2 / 10** |
| Соответствие multi-repo + AI-агенту | Отличное |
| Дисциплина границ артефактов | Отличная |
| Практичность для ledger/финансов | Высокая |
| Поддерживаемость instructions | Средняя (главный риск) |
| Сравнение со стандартным `spec-driven` | Существенно сильнее |

Версия 2 — заметный шаг вперёд относительно v1. Вы закрыли почти все критические замечания предыдущей оценки и добавили механизмы, которые реально нужны в multi-repo + agent setup: **Artifact boundary**, **Covers → Requirement traceability**, **Rollback Contract**, **verify-скрипт на каждой стадии**, **Feedback routing** и явные owner-approvals.

Это уже не «кастомный fork», а production-grade internal engineering workflow.

---

## 2. Что изменилось с v1 → v2 (ключевые улучшения)

### 2.1. Artifact boundary (MUST NOT include)

В каждой инструкции теперь явно перечислено, чего **нельзя** писать в данном артефакте, и куда возвращаться, если агент «вылез» за границу:

| Артефакт | Запрещено | Куда возвращаться |
|----------|-----------|-------------------|
| Proposal | технологии, API, файлы, implementation steps | — |
| Specs | intent вне Proposal, internal names, libraries, test procedures | Proposal |
| Design | новое behavior, file-by-file checklist, commit IDs | Specs |
| Tasks | новое behavior/architecture, multi-owner задачи, ненаблюдаемые results | Specs / Design |

Это решает главную болезнь AI-агентов — смешивание Why/What/How/Do.

### 2.2. Rollback Contract в Design

Добавлена обязательная таблица внутри Migration Plan:

```
Status | Reason | Trigger | Actions | Data safety | Verification
```

`required` для auth/security, data integrity/migration, public contracts и других труднообратимых решений. Для ledger-системы это критично.

### 2.3. Tasks: area + Covers + Verification

Формат задачи стал строгим:

```markdown
- [ ] 1.1 [backend] Implement session rejection
  - **Covers:** `user-authentication` — `Expired session is rejected`
  - **Verification:** Run the backend canonical gate and the expiry contract test.
```

- Ровно один owner из `{frontend, backend, specs, docs, workspace}`
- Каждый Delta Requirement должен быть покрыт ≥1 task
- `workspace` только для orchestration/verification
- Пустые commits запрещены

Это даёт **traceability Requirement → Task** и делает apply-фазу проверяемой.

### 2.4. Structural verifier на каждой стадии

После записи каждого артефакта:

```bash
bash specs/scripts/verify-openspec-planning.sh <change>
```

Плюс явные owner-approvals перед переходом дальше. Structural success ≠ semantic approval.

### 2.5. Apply: Feedback routing + invalidation

```
intent/scope mismatch        → Proposal
observable behavior mismatch → Delta Specs
architecture/rollback mismatch → Design
decomposition/ownership/coverage mismatch → Tasks
```

Агент обязан остановить downstream work и инвалидировать approvals начиная с самого раннего затронутого артефакта. Механические syntax-фиксы можно чинить без reapproval.

### 2.6. Templates стали точнее

- `design.md` — Rollback Contract table
- `tasks.md` — `[area]`, **Covers**, **Verification**
- Остальные шаблоны сохранены минималистичными (нагрузка в instructions)

---

## 3. Сильные стороны (сохранились и усилились)

1. **Capabilities как контракт** между Proposal и Specs + `skip_specs: true` для pure refactor.
2. **Строгий порядок** proposal → specs → design → tasks (не parallel design).
3. **Delivery Map** (frontend / backend / specs / docs) + Contract Gate `runtime-openapi`.
4. **Solution Assessment** (build-vs-buy) на auth/security/storage/integration/caching/concurrency.
5. **Canonical store** `wealth-ledger-specs` + запрет parallel planning root.
6. **SHALL/MUST + #### Scenario** + полный copy-paste workflow для MODIFIED.
7. **Purpose ≥ 50 символов** для новых capabilities (защита от TBD после archive).

---

## 4. Сравнение со стандартным OpenSpec `spec-driven`

| Аспект | Стандартный | wealth-ledger-sdd v2 |
|--------|-------------|----------------------|
| Порядок | proposal → (specs ∥ design) → tasks | proposal → specs → design → tasks |
| Границы артефактов | слабые | Artifact boundary + Feedback routing |
| Traceability | почти нет | Covers → Requirement |
| Multi-repo | нет | Delivery Map + area + workspace + store |
| Rollback | опционально | Rollback Contract table |
| Approvals | нет | explicit owner approval на каждой стадии |
| Verify | нет / слабый | verify-openspec-planning.sh после каждого артефакта |
| Apply discipline | базовая | Feedback routing + invalidation rules |

Для финансового/ledger-домена и multi-repo setup ваша схема объективно лучше дефолтной.

---

## 5. Оставшиеся риски и слабые места

### 5.1. Длина и плотность instructions (главный риск)

`schema.yaml` ≈ 18.5 KB / 349 строк. Критические правила размазаны по длинным абзацам на смеси RU/EN.

Риски:
- Агент «пропускает» пункт в середине instruction.
- Сложно diff’ить и поддерживать.
- При смене модели качество следования может упасть.

### 5.2. Delivery Map жёстко фиксирует 4 области

`frontend / backend / specs / docs` (+ `workspace` в tasks).  
При появлении mobile, workers, data-pipelines, infra-as-code придётся расширять схему.

### 5.3. Approval — только в тексте instruction

Нет машиночитаемого статуса (`Approved-by`, `Approved-at`) в артефактах. Агент может «забыть» спросить approval, если prompt длинный.

### 5.4. Нет отдельной verify / archive кастомизации

Apply есть, а явной post-apply verify-фазы или правил archive (особенно для денежных миграций) — нет. Скрипт `verify-openspec-planning.sh` покрывает structural, но не semantic/runtime.

### 5.5. Templates всё ещё минималистичны

Почти вся дисциплина живёт в instructions. При fork/обновлении OpenSpec или смене модели это может стать хрупким.

### 5.6. Строгая последовательность specs → design

Повышает качество, но замедляет exploratory-работу, когда нужно быстро проверить техническую feasibility до фиксации behavior.

---

## 6. Предложения по улучшению

### Высокий приоритет

**1. Структурировать instructions: Critical Rules сверху**

В начале каждой instruction добавить короткий блок:

```yaml
instruction: |
  ## Critical Rules (do not skip)
  - ...
  - ...

  ## Details
  ...
```

Вынести:
- Artifact boundary (MUST NOT)
- Required sections / format
- Когда остановиться и вернуться назад
- Вызов verify-скрипта

Остальной текст — ниже. Это резко повышает шанс, что модель не пропустит важное.

**2. Машиночитаемый approval marker**

В конец каждого артефакта (или в `.openspec.yaml` change) добавить:

```markdown
## Approval
- Status: pending | approved | invalidated
- By: <owner>
- At: <ISO datetime>
- Notes: ...
```

Или хотя бы требовать в instruction явную строку `Approved-by: ...` перед переходом дальше. Тогда verify-скрипт сможет проверять наличие approval.

**3. Сделать Delivery Map расширяемым**

Разрешить дополнительные rows с обоснованием:

```markdown
| mobile | affected | ... |
| workers | N/A | no background jobs in this change |
```

Сейчас «ровно frontend, backend, specs и docs» — хрупко.

### Средний приоритет

**4. Унифицировать язык**

Либо полностью русский, либо английский с русскими комментариями только в Critical Rules. Сейчас смесь усложняет и человеку, и модели.

**5. Лёгкая verify-фаза после tasks (опционально)**

Даже не отдельный artifact, а секция в apply или отдельный checklist:

- все local gates зелёные;
- Covers 100% покрыты;
- Rollback Contract (если required) проверен;
- Completion Evidence зафиксирован.

**6. Solution Assessment как условный артефакт**

Сейчас секция внутри design. При частых build-vs-buy решениях удобнее отдельный `solution-assessment.md` (requires: specs), чтобы его можно было переиспользовать и ревьюить отдельно.

**7. Явный rule для cross-repo verification**

В tasks уже есть `workspace`. Стоит добавить в Critical Rules:

> После всех affected areas — одна `workspace`-задача на semantic review против каждого approved Requirement/Scenario.

### Низкий приоритет / nicety

**8. Success Metrics / Observable Outcomes в Proposal**

1–3 пункта «как поймём, что изменение достигло цели». Помогает писать scenarios и Acceptance в apply.

**9. Сократить примеры в instructions**

Сейчас примеры (особенно в specs) занимают много места. Можно вынести в отдельный `examples/` или оставить только один компактный.

**10. Versioning schema + changelog**

У вас уже `version: 2`. Имеет смысл вести короткий CHANGELOG рядом со schema, чтобы при обновлении агента/команды было видно, что изменилось в дисциплине.

---

## 7. Рекомендуемый минимальный diff (идеи, не патч)

1. В каждый artifact instruction добавить в самое начало блок `## Critical Rules`.
2. В templates `proposal.md`, `spec.md`, `design.md`, `tasks.md` добавить в конец:

```markdown
## Approval
- Status: pending
- By:
- At:
```

3. В Delivery Map instruction заменить «ровно frontend, backend, specs и docs» на «обязательные: frontend, backend, specs, docs; дополнительные области — с обоснованием».
4. В apply instruction оставить Feedback routing, но вынести его в Critical Rules.

Эти четыре изменения дадут максимум пользы при минимальном усложнении.

---

## 8. Итог

**v2 — сильная, зрелая схема.**  
Вы закрыли основные дыры v1 (границы артефактов, rollback, traceability Requirement→Task, structural verify, feedback routing). Для multi-repo ledger-проекта с AI-агентом это один из лучших кастомных OpenSpec workflow, которые можно собрать на текущем API схем.

Главный оставшийся рычаг улучшения — **не добавлять ещё правил, а сделать существующие правила короче, заметнее и машиночитаемее** (Critical Rules сверху + approval markers + расширяемый Delivery Map).

После этих точечных правок схема спокойно может жить как внутренний стандарт без постоянных переделок.