docs/audits/2026-08-26-wealth-ledger-sdd-v2-review/kimi-audit.md

# Анализ openspec SDD-схемы v2: wealth-ledger-sdd

> **Версия схемы:** 2  
> **Автор анализа:** AI-ассистент  
> **Дата:** 2026-08-26

---

## 1. Общая оценка v2

**A− / «Зрелая схема, готовая к production-like использованию»**

Переход с v1 на v2 — качественный скачок. Из 9 рекомендаций из предыдущего анализа **5 полностью или частично учтены**, при этом добавлены 4 новых сильных механизма, которых не было ни в v1, ни в рекомендациях. Схема теперь защищена от основных рисков: каскадных ошибок, scope creep, потери traceability и неконтролируемого rollback.

---

## 2. Сравнение v1 → v2: что изменилось

### 2.1. Schema.yaml — структурные улучшения

| Аспект | v1 | v2 | Оценка |
|--------|-----|-----|--------|
| **Версия** | 1 | 2 | — |
| **Фазы** | 4 (proposal→specs→design→tasks) | 5 (+apply) | ✅ |
| **Artifact boundaries** | Общие запреты | Структурированные MUST NOT include для каждой фазы | ✅✅ |
| **Approval gates** | Неявные («только после approval») | Explicit approval + verify script для каждой фазы | ✅✅ |
| **Invalidation** | Нет | Downstream approvals инвалидируются при mismatch | ✅✅ |
| **Feedback routing** | Нет | Чёткое указание: intent→Proposal, behavior→Specs, architecture→Design, decomposition→Tasks | ✅✅ |
| **Verify script** | Нет | `verify-openspec-planning.sh <change>` на каждой фазе | ✅ |
| **Spec examples** | Только ADDED | Все 4 операции (ADDED, MODIFIED, REMOVED, RENAMED) | ✅ |
| **Traceability** | Нет | `Covers: capability-path — exact Requirement heading` | ✅✅ |
| **Task owner** | Нет | `[frontend\|backend\|specs\|docs\|workspace]` | ✅ |
| **Rollback** | Generic Migration Plan | Rollback Contract с conditional required/N/A | ✅✅ |

### 2.2. Design.md — Rollback Contract

В v1 Migration Plan был generic. В v2 добавлена структурированная таблица:
- `Status`: `required` или `N/A`
- `Trigger`, `Actions`, `Data safety`, `Verification` — обязательны при `required`
- `Reason` — обязателен при `N/A`

Это превращает rollback из «пожелания» в «контракт».

### 2.3. Tasks.md — Traceability + Ownership

В v1 задачи были plain text. В v2:
- **Owner area**: `[frontend]`, `[backend]`, `[specs]`, `[docs]`, `[workspace]`
- **Covers**: явная ссылка `capability-path — exact Requirement heading`
- **N/A rationale**: для `workspace` tasks — обязательное обоснование, почему нет spec-ссылки
- **Verification**: осталась, но теперь в строгом формате

### 2.4. Apply phase — новая фаза

В v1 apply был неявным. В v2 — explicit phase:
- Требует approvals **всех 4 предыдущих фаз**
- Работает только с canonical store
- Feedback routing при mismatch
- Трекинг через checkbox'ы tasks.md

---

## 3. Какие рекомендации из v1-анализа учтены

### ✅ Рекомендация #2: Traceability (specs → tasks)
**Реализация:** `Covers` metadata в tasks.md  
**Качество:** Отлично. Не просто convention, а обязательный формат. Каждый Delta Requirement должен быть покрыт хотя бы одной task. Собственные requirement IDs не вводятся — защита от «фантомных» требований.

### ✅ Рекомендация #3: Полный spec template с examples
**Реализация:** Compact operation examples в schema.yaml instruction  
**Качество:** Хорошо. Все 4 операции (ADDED, MODIFIED, REMOVED, RENAMED) с примерами. Небольшой минус: template-файл `spec.md` всё ещё содержит только ADDED, но AI-агент читает instruction из schema.yaml, так что это компенсируется.

### ✅ Рекомендация #7: Rollback Plan
**Реализация:** Rollback Contract в design.md + conditional logic в schema.yaml  
**Качество:** Отлично. Не просто секция, а structured table с обязательностью полей, зависящей от типа change. `required` для auth/security/migration/public contract, `N/A` с reason для остального.

### ✅ Рекомендация #1: Review gate (частично)
**Реализация:** Explicit approval из разговора + `verify-openspec-planning.sh` + «structural success ≠ approval»  
**Качество:** Хорошо, но иначе, чем предлагалось. Вместо отдельного `review.md` — approval + verify script. Это меньше артефактов, но тот же контроль. Потенциальный риск: AI-агент может «считать», что approval получен, если не строго интерпретировать «explicit approval из разговора». Но verify script добавляет технический барьер.

### ⚠️ Рекомендация #4: Definition of Done
**Статус:** Не реализовано.  
**Комментарий:** Apply phase частично закрывает этот gap (требует approvals всех фаз + verification), но нет единого артефакта `done.md` с completion evidence.

### ❌ Рекомендация #5: Зависимости между changes
**Статус:** Не реализовано.  
**Комментарий:** В multi-repo с shared store это всё ещё риск. Но для pet-проекта — приемлемо.

### ❌ Рекомендация #6: Sizing задач
**Статус:** Не реализовано.  
**Комментарий:** Для AI-агента полезно, но не критично.

### ❌ Рекомендация #8: Context mapping
**Статус:** Не реализовано.  
**Комментарий:** Apply phase говорит «Read context files», но не указывает, какие именно. В multi-repo setup это может привести к переполнению контекста.

### ❌ Рекомендация #9: Convention для commit messages
**Статус:** Не реализовано.  
**Комментарий:** Nice to have.

---

## 4. Новые сильные моменты (не были в рекомендациях)

### 4.1. Artifact Boundaries

В каждой фазе теперь явный список **MUST NOT include**:
- Proposal не может содержать технологии, API signatures, task decomposition
- Specs не может содержать intent вне утверждённого Proposal, internal components, test procedures
- Design не может содержать новое observable behavior, пересказ Specs, future commit identifiers
- Tasks не может содержать новое behavior, архитектурные отклонения, vague actions

Это **scope creep protection** на уровне инструкций. AI-агент, следуя этим границам, физически не сможет «подсунуть» решение на неправильной фазе.

### 4.2. Feedback Routing + Invalidation

В apply phase:

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


При обнаружении mismatch — **остановить downstream work, инвалидировать approvals начиная с самого раннего затронутого artifact**.

Это **каскадная защита**: если на этапе apply обнаружилось, что Design несовместим с Specs, не пытаться «подправить» Tasks — вернуться к Specs и начать заново.

### 4.3. Structural vs Semantic Validation

Явное разделение:
- **Structural validation**: `verify-openspec-planning.sh` — проверяет формат, headers, completeness
- **Semantic verification**: approval Change Owner — проверяет смысл

«Structural success не означает approval Change Owner» — критически важное различие для AI-агента.

### 4.4. Workspace Owner

`[workspace]` — отдельный owner для cross-area orchestration/verification. Защищает от смешивания implementation и orchestration в одной задаче. `N/A` Covers с concrete reason — защита от «пустых» workspace tasks.

---

## 5. Оставшиеся риски

### 5.1. Нет Definition of Done

Apply phase требует approvals, но не фиксирует **completion evidence** в виде артефакта. Нет единого места, где собраны:
- результаты всех verification actions
- proof of regression check
- confirmation of archive

**Mitigation:** Tasks.md с checkbox'ами частично играет эту роль, но это tracking, не evidence.

### 5.2. Нет управления зависимостями между changes

В shared specs store может возникнуть ситуация:
- Change A модифицирует capability X
- Change B зависит от нового behavior X

Сейчас это не выразимо в схеме. Риск параллельной работы над конфликтующими changes.

**Mitigation:** Для pet-проекта — ручной контроль. Для роста — добавить `Dependencies` в proposal.md.

### 5.3. Context mapping для multi-repo

Apply phase: «Read context files». Но какие? Все репозитории? Только affected? AI-агент может:
- Читать лишнее → переполнение контекста
- Пропускать релевантное → решения на неполных данных

**Mitigation:** Для pet-проекта — manageable. Для роста — `.openspec/context.yaml` с `relevant_paths`.

### 5.4. Spec.md template всё ещё неполный

Template-файл `spec.md` содержит только `## ADDED Requirements`. Examples для MODIFIED/REMOVED/RENAMED есть в schema.yaml instruction, но template — это то, что AI «видит» первым. Риск неправильного формата при генерации.

**Mitigation:** Низкий — AI читает instruction перед template (в зависимости от реализации агента).

---

## 6. Итоговая таблица оценок v2

| Критерий | v1 | v2 | Δ | Комментарий |
|----------|-----|-----|---|-------------|
| **Разделение concerns** | A | A | → | Границы стали явными (Artifact boundaries) |
| **Проверяемость specs** | A | A | → | Examples для всех 4 операций |
| **Защита от деградации** | B+ | A− | ↑↑ | Approval gates + verify + invalidation |
| **Traceability** | C+ | A | ↑↑↑ | Covers с capability-path + exact Requirement |
| **Полнота workflow** | B | B+ | ↑ | +apply phase + rollback contract |
| **AI-агент friendliness** | A | A+ | ↑ | Feedback routing + artifact boundaries |
| **Интеграция с openspec** | A− | A | ↑ | Store-aware + verify script |
| **Multi-repo поддержка** | B | B+ | ↑ | Workspace owner + cross-area orchestration |
| **Эволюционность** | B+ | A− | ↑↑ | Invalidation + 4 delta-ops |
| **Документированность** | A | A+ | ↑ | Artifact boundaries + structured examples |

---

## 7. Заключение

**v2 — качественный скачок.** Основные болевые точки v1 закрыты:

- ✅ Traceability: `Covers` связывает tasks и specs
- ✅ Rollback: `Rollback Contract` делает откат предсказуемым
- ✅ Scope creep protection: `Artifact boundaries` на каждой фазе
- ✅ Каскадная защита: `Feedback routing` + `invalidation`
- ✅ Approval discipline: explicit approvals + verify script + structural≠semantic

**Что делает схему зрелой:**
1. **Self-correcting**: при mismatch есть чёткий путь назад (feedback routing)
2. **Self-documenting**: artifact boundaries делают границы очевидными
3. **Self-validating**: verify script + approval gates создают контрольные точки

**Что можно добавить в v3 (по мере роста проекта):**
1. `done.md` — Definition of Done с completion evidence
2. `Dependencies` в proposal.md — для cross-change coordination
3. `.openspec/context.yaml` — для точного контекста в multi-repo
4. Sizing (`S/M/L`) в tasks — для планирования сессий

**Вердикт:** Схема готова к использованию в pet-проекте любой сложности и может масштабироваться на small-team setup без существенных изменений.

---

## 8. План доработок v2 → v3 (чеклист)

> Скопируй этот раздел в отдельный файл и отмечай прогресс.

### 8.1. Definition of Done (`done.md`)

- [ ] Добавить артефакт `done.md` в `schema.yaml`
- [ ] Создать template `done.md` с секциями:
    - Completion Evidence (verification results)
    - Regression Check
    - Archive Confirmation
- [ ] Обновить `apply` phase: `requires: [tasks, done]`

### 8.2. Зависимости между changes

- [ ] Добавить в `proposal.md` template секцию `## Dependencies`
- [ ] Поля: `Blocked By`, `Blocks`, `Related`
- [ ] В `schema.yaml` добавить валидацию: проверять, что `Blocked By` changes завершены

### 8.3. Context mapping для multi-repo

- [ ] Создать `.openspec/context.yaml` в корне workspace
- [ ] Маппинг: `repo name → path → relevant_paths → ignore_paths`
- [ ] Обновить `apply` instruction: читать context mapping перед `Read context files`

### 8.4. Sizing задач

- [ ] Добавить в `tasks.md` template поле `**Size:** S/M/L/XL`
- [ ] В `schema.yaml` instruction для tasks добавить правило sizing
- [ ] Определить границы: S≤1ч, M=2-4ч, L=1-2д, XL=декомпозировать

### 8.5. Commit convention

- [ ] Добавить в `schema.yaml` apply instruction:
    - Формат: `[openspec:<change-id>] <type>: <description>`
    - Примеры для spec-commits и code-commits
    - `Refs:` ссылка на change artifact

### 8.6. Spec.md template — полная версия

- [ ] Обновить `spec.md` template: добавить `## MODIFIED`, `## REMOVED`, `## RENAMED` с placeholder'ами
- [ ] Убедиться, что AI-агент генерирует все 4 операции корректно

---

## 9. 100-балльная оценка v2

| Критерий | Вес | Баллы | Почему не максимум |
|----------|-----|-------|-------------------|
| **Разделение concerns** | 15 | 14 | spec.md template неполный |
| **Проверяемость specs** | 15 | 14 | verify script — внешний инструмент |
| **Защита от деградации** | 15 | 14 | approval «из разговора» — нет механического proof |
| **Traceability** | 10 | **10** | Полная |
| **Полнота workflow** | 10 | 8 | Нет DoD, нет зависимостей |
| **AI-агент friendliness** | 10 | **10** | Отлично |
| **Интеграция с openspec** | 10 | 9 | Нет commit convention |
| **Multi-repo поддержка** | 10 | 7 | Нет context mapping |
| **Эволюционность** | 5 | **5** | Полная |

**Итого: 91 / 100**

---

*Анализ подготовлен на основе сравнения v1 и v2 файлов: schema.yaml, proposal.md, spec.md, design.md, tasks.md*