WealthLedger/docs
5
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d80e2e32b2ebadcd93a53105e1ac337fe2c1f4f6
docs/audits/2026-08-26-wealth-ledger-sdd-v2-review/kimi-audit.md
T

17 KiB
Raw Blame History

Анализ 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

Reference in New Issue View Git Blame Copy Permalink