# Анализ обновлённой схемы (v2) ## 1. Улучшения по сравнению с v1 - **Валидация на каждом этапе** – добавлен обязательный запуск `bash specs/scripts/verify-openspec-planning.sh ` на стадиях Proposal, Specs, Design и Tasks. Это исключает синтаксические и структурные ошибки до ревью. - **Явные артефактные границы** – для каждого артефакта чётко прописано, что **нельзя** включать (например, технологии, имена файлов, пошаговые инструкции). Это предотвращает смешение уровней абстракции. - **Утверждение и инвалидация approvals** – каждый следующий артефакт создаётся только после утверждения предыдущего владельцем. При обнаружении несоответствия инвалидируются все downstream approvals. - **Трассируемость задач** – в `tasks.md` добавлены обязательные поля `Covers` и `Verification`. Каждая задача теперь привязана к конкретному требованию (`capability-path — exact Requirement heading`) или имеет обоснование `N/A`. - **Роллбэк-контракт** – в `design.md` внутри раздела Migration Plan добавлен `### Rollback Contract` с полями Status, Trigger, Actions, Data safety, Verification. Обязателен для критичных изменений (auth, данные, публичные контракты). - **Поддержка многокомпонентных изменений** – введены owner‑области (`frontend`, `backend`, `specs`, `docs`, `workspace`). Для каждой `affected` области из Delivery Map должна существовать задача, а `workspace` используется только для оркестрации или верификации. - **Примеры для всех типов дельт** – в инструкции к `specs` добавлены компактные примеры для ADDED, MODIFIED, REMOVED, RENAMED, что снижает неоднозначность для AI. - **Доработан процесс `apply`** – включает проверку approvals, выполнение скрипта, пошаговое выполнение задач с верификацией, а также механизм обратной связи (feedback routing) при обнаружении несоответствий. ## 2. Оставшиеся незначительные нюансы - Инструкции всё ещё достаточно объёмны; можно вынести повторяющиеся части (например, описание `planningHome.root`) в отдельный общий файл. - Отсутствует интеграция с CI/CD для автоматического запуска валидации при создании PR – это уже за рамками схемы, но может быть добавлено. - Нет явного механизма версионирования самих изменений (кроме версии схемы). ## 3. Оценка по 100‑балльной шкале | Критерий | Вес | Оценка | Обоснование | |----------|-----|--------|-------------| | **Полнота жизненного цикла** (proposal → specs → design → tasks → apply) | 20% | 20 | Все этапы присутствуют, с явными переходами и зависимостями. Есть обратная связь и инвалидация approval при несоответствиях. | | **Чёткость разделения уровней абстракции** (why/what/how/do) | 15% | 15 | Артефактные границы жёстко прописаны для каждого этапа. Это предотвращает смешивание intent, поведения, архитектуры и реализации. | | **Поведенческая спецификация** (формат дельт, сценарии WHEN/THEN) | 10% | 10 | Требования используют SHALL/MUST, сценарии с 4 `#`, поддерживаются ADDED/MODIFIED/REMOVED/RENAMED. Полное копирование при модификации – безопасно. | | **Автоматическая валидация** (verify-openspec-planning.sh) | 10% | 10 | Встроенный скрипт на каждом этапе – отличное решение, предотвращающее синтаксические ошибки до ревью. | | **Трассируемость** (Covers в задачах) | 10% | 10 | Каждая задача явно привязана к требованию или имеет обоснование N/A. Это даёт полную прослеживаемость. | | **Управление рисками и решениями** (Solution Assessment, Rollback Contract) | 10% | 9 | Оба раздела присутствуют и формализованы. Немного не хватает конкретных критериев, когда `Solution Assessment` обязателен (хотя области перечислены). | | **Поддержка многокомпонентных изменений** (owner‑areas, workspace) | 10% | 9 | Введены `frontend/backend/specs/docs/workspace` с явными правилами. Есть, но не детализирована синхронизация версий и порядок деплоя – это скорее для проектов с несколькими репозиториями. | | **Процесс утверждений и инвалидаций** | 10% | 10 | Чётко прописано, что каждый артефакт требует approval владельца, а при изменении более раннего артефакта – инвалидируются downstream approvals. | | **Инструкции для AI** (чёткость, примеры, избегание неоднозначности) | 5% | 4 | Инструкции подробны, есть примеры. Однако всё ещё достаточно объёмны; можно было бы вынести повторяющиеся части в отдельный файл. | **Итого:** 20 + 15 + 10 + 10 + 10 + 9 + 9 + 10 + 4 = **94/100** ## 4. Заключение Схема **почти эталонная** для SDD с openspec. Она пригодна для использования в командах, поддерживает сложные сценарии и обеспечивает высокую дисциплину. Оценка **94/100** отражает уверенность в её качестве и практическую применимость. Рекомендуется внедрить её в pet‑проектах и при необходимости адаптировать под конкретные соглашения команды (например, добавить интеграцию с CI/CD). ## 1. Полная схема ### schema.yaml ```yaml name: wealth-ledger-sdd version: 2 description: WealthLedger SDD workflow - proposal → specs → design → tasks → apply artifacts: - id: proposal generates: proposal.md description: Owner-approved intent without implementation details template: proposal.md instruction: | Создай Proposal, который формулирует намерение и объясняет, ПОЧЕМУ изменение нужно. Его должен понимать и утверждать владелец продукта или процесса без знания структуры кода. Sections: Разделы: - **Why**: проблема или возможность и причина заняться ею сейчас. - **What Changes**: намерение, ожидаемый результат и явные non-goals. - **Capabilities**: какие поведенческие specs появятся или изменятся: - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs//spec.md`. Use kebab-case for path segments you introduce (e.g., `user-auth` or `identity/user-auth`) and follow the project's existing spec organization. - **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Use the exact existing path under `openspec/specs/`. Leave empty if no requirement changes. - **Impact**: затронутые пользователи, процессы или части системы только на уровне scope. IMPORTANT: The Capabilities section is critical. It creates the contract between proposal and specs phases. Research existing specs before filling this in. Each capability listed here will need a corresponding spec file. Every change must either declare at least one capability (new or modified) or explicitly opt out of specs: `openspec validate` rejects a change with zero deltas unless the change's `.openspec.yaml` sets `skip_specs: true`. Use `skip_specs: true` only when no spec-level behavior changes (pure refactor, tooling, docs) - specs describe behavior, so if behavior does not change, no spec should change either. Do not invent a requirement just to satisfy validation. Artifact boundary — MUST NOT include: - технологии, библиотеки, зависимости или выбранную архитектуру: эти решения появляются только после Delta Specs в Design; - API signatures, database structures, имена файлов, классов или функций: это implementation detail для Design; - implementation steps, task decomposition или verification commands: это конкретизируется в Tasks после утверждения Design. This is the foundation - specs, design, and tasks all build on this. До сохранения исследуй canonical main specs и remediation registry для audit-derived change. После записи выполни `bash specs/scripts/verify-openspec-planning.sh `: на этой стадии verifier проверяет Proposal и явно оставляет downstream validation pending. Исправь технический формат и повтори check до запроса approval; structural success не означает approval Change Owner. requires: [] - id: specs generates: "specs/**/*.md" description: Observable behavior and invariants changed by the proposal template: spec.md instruction: | Создай Delta Specs, определяющие, ЧТО наблюдаемо изменяется в системе. Spec является behavior contract, а не планом изменения кода. Good spec content: - Observable behavior users or downstream systems rely on - Inputs, outputs, and error conditions - External constraints (security, privacy, reliability, compatibility) - Scenarios that can be tested or explicitly validated Artifact boundary — MUST NOT include: - intent или scope за пределами утверждённого Proposal: сначала верни изменение в Proposal; - internal components, class/function names, files или database structures: implementation structure определяется в Design; - library, framework или infrastructure choices: alternatives и решение принадлежат Design; - step-by-step implementation, delivery sequencing или verification commands: это принадлежит Tasks; - test procedure вместо behavior scenario: scenario фиксирует наблюдаемые WHEN/THEN, а способ проверки выбирается позднее. Quick test: if the implementation can change without changing externally visible behavior, it likely does not belong in the spec. Create one spec file per capability listed in the proposal's Capabilities section. `` is the spec directory relative to `specs/` (for example, `user-auth` or `identity/user-auth`). Preserve the full path: - New capabilities: use the exact path from the proposal at `specs//spec.md`. Any path segment newly introduced in the proposal must be kebab-case. Follow the project's existing organization; do not add a new domain level when the project uses a flat layout. - Modified capabilities: use the exact existing path from `openspec/specs//` when creating the delta at `specs//spec.md`. Do not move or rename the capability. There must be at least one spec file unless the change's `.openspec.yaml` sets `skip_specs: true` (no spec-level behavior change) - `openspec validate` rejects a zero-delta change without that marker. If the proposal lists no capabilities and `skip_specs` is not set, revisit the proposal first. Delta operations (use ## headers): - **ADDED Requirements**: New capabilities - **MODIFIED Requirements**: Changed behavior - MUST include full updated content - **REMOVED Requirements**: Deprecated features - MUST include **Reason** and **Migration** - **RENAMED Requirements**: Name changes only - use FROM:/TO: format Format requirements: - Each requirement: `### Requirement: ` followed by description - Use SHALL/MUST for normative requirements (avoid should/may) - Each scenario: `#### Scenario: ` with WHEN/THEN format - **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently. - Every requirement MUST have at least one scenario. New capabilities only: start the delta spec with a `## Purpose` section - one or two sentences (50+ characters, or `openspec validate --strict` reports it as too brief) describing what the capability is for. Archive copies it into the main spec it creates; without it the new main spec is left with a `TBD ... Update Purpose after archive` placeholder to fill in by hand. Do NOT add `## Purpose` to a delta for an existing capability - that spec already has one and the delta's is ignored. To change an existing capability's Purpose - including a leftover `TBD` placeholder - edit `/openspec/specs//spec.md` directly. `planningHome.root` comes from the `openspec instructions ... --json` response. Always use it rather than a repo-relative path: it resolves to the store whenever the change lives in one - whether that came from `--store`, a project `store:` pointer, or a global default store - and to the current repository otherwise. Do not try to work out which case applies; the field already has. MODIFIED requirements workflow: 1. Locate the existing requirement in `/openspec/specs//spec.md` (the same store-aware root as above) 2. Copy the ENTIRE requirement block (from `### Requirement:` through all scenarios) 3. Paste under `## MODIFIED Requirements` and edit to reflect new behavior 4. Ensure header text matches exactly (whitespace-insensitive) Common pitfall: Using MODIFIED with partial content loses detail at archive time. If adding new concerns without changing existing behavior, use ADDED instead. Compact operation examples: ADDED in a new capability: include Purpose. Purpose Lets users take their data out of the product in a portable format. ADDED Requirements Requirement: User can export data The system SHALL allow users to export their data in CSV format. Scenario: Successful export WHEN user clicks "Export" button THEN system downloads a CSV file with all user data MODIFIED: copy the complete old requirement, then edit it. MODIFIED Requirements Requirement: Session expiration The system MUST reject an expired session and preserve every surviving scenario from the main spec. Scenario: Expired session WHEN a request uses an expired session THEN the system rejects the request REMOVED requires both fields. REMOVED Requirements Requirement: Legacy export Reason: Replaced by new export system Migration: Use new export endpoint at /api/v2/export RENAMED changes only the heading. RENAMED Requirements FROM: ### Requirement: Old name TO: ### Requirement: New name Specs должны быть проверяемыми, но scenario не означает автоматический unit test: уровень проверки выбирается по риску поведения. Перед записью установи явный approval Proposal из разговора. После записи выполни `bash specs/scripts/verify-openspec-planning.sh ` и исправь технические ошибки до запроса approval Delta Specs. Если обнаружено изменение intent, вернись к Proposal и инвалидируй downstream approvals вместо скрытого расширения Specs. requires: - proposal - id: design generates: design.md description: Architectural implementation approach and delivery decisions template: design.md instruction: | Создай Design, объясняющий, КАК архитектурно выполнить утверждённые Delta Specs. Artifact boundary — MUST NOT include: - новое observable behavior или invariant, отсутствующие в утверждённых Delta Specs: сначала верни изменение в Specs; - пересказ Proposal или Specs вместо архитектурных constraints и решений, необходимых для выбранного подхода; - file-by-file implementation checklist, verification commands или пошаговый список правок: это принадлежит Tasks; - будущие delivery results, commit identifiers или Completion Evidence: они фиксируются только после наблюдаемого выполнения. Обязательные разделы: - **Context**: только текущее состояние и ограничения подхода. - **Goals / Non-Goals**: технические границы, не пересказ Proposal. - **Decisions**: крупные решения, rationale и рассмотренные alternatives. - **Delivery Map**: ровно frontend, backend, specs и docs; для каждой области `affected` с ожидаемым архитектурным результатом либо `N/A` с конкретной причиной. `specs` всегда affected. Здесь же зафиксируй Contract Gate Decision для `runtime-openapi`: `required`, только когда change затрагивает обе стороны API contract, либо `N/A` с причиной. - **Risks / Trade-offs**: риск и mitigation. - **Migration Plan**: порядок поставки и rollback, если применимо. Внутри Migration Plan добавь `### Rollback Contract` с table fields. Status `required` обязателен для auth/security, data integrity/migration, public contract и другого существенно труднообратимого решения и требует Trigger, Actions, Data safety и Verification. В остальных случаях Status `N/A` требует конкретный Reason. Отдельный rollback artifact не создавай. Добавь **Solution Assessment**, если изменение вводит или существенно заменяет auth, security, storage, external integration, observability, caching, concurrency или общую infrastructure/tooling либо содержит другое дорогостоящее необратимое решение. Сравни зрелые готовые решения по fit, maturity, security, operating cost, constraints и migration cost. Custom implementation допустима только после фиксации несовместимости подходящих alternatives и принятых рисков. Не создавай отдельный artifact. **Open Questions** допустим только для неизвестного, которое не меняет Specs, выбранный подход или Tasks. Иначе остановись и запроси решение владельца до сохранения Design. Open questions are for genuinely deferrable unknowns, not decisions you skipped. If a question would change the specs, the chosen approach, or the task breakdown, resolve it now - ask the user instead of guessing. Design формируется только после явного owner approval Delta Specs. После записи выполни `bash specs/scripts/verify-openspec-planning.sh ` и исправь технические ошибки до запроса approval. Если Design показывает несовместимость с intent или behavior, остановись, вернись к самому раннему затронутому artifact и инвалидируй downstream approvals. requires: - specs - id: tasks generates: tasks.md description: Implementation checklist with trackable tasks template: tasks.md instruction: | Создай implementation checklist, достаточный для выполнения Design и Delta Specs. Это конкретное DO, а не ещё один архитектурный документ. Before writing tasks, check design.md for Open Questions. If any of them would change what gets built, resolve them with the user first - do not bake an unstated assumption into the task list. **IMPORTANT: Follow the template below exactly.** The apply phase parses checkbox format to track progress. Tasks not using `- [ ]` won't be tracked. Правила: - Группируй задачи под numbered `##` headings и располагай по dependencies. - Каждая задача MUST иметь формат `- [ ] X.Y [area] action`, быть выполнимой за одну рабочую сессию и иметь ровно одного owner из `frontend`, `backend`, `specs`, `docs`, `workspace`. - Сразу после checkbox добавляй ровно по одной indented metadata line: `- **Covers:**` и `- **Verification:**`. - `Covers` содержит одну или несколько пар `` `capability-path` — `exact Requirement heading` `` либо `` `N/A` — concrete reason ``. Каждый Delta Requirement должен быть покрыт хотя бы одной task; собственные requirement IDs не вводятся. - Owner repository не может иметь статус `N/A` в Delivery Map. Cross-repository implementation разделяй; `workspace` используй только для orchestration/verification и с конкретным `N/A` Covers rationale. - Для каждой `affected` области Delivery Map должна существовать задача реализации и её canonical local gate; пустые commits запрещены. - Каждая задача MUST указывать planned verification action: команду, проверку наблюдаемого поведения или delivered artifact. - Автоматические тесты обязательны для security/privacy, денежных расчётов, data integrity/migration, concurrency, public contracts, critical journeys и подтверждённых regressions. - Не требуй отдельный unit test только из-за изменения файла. DTO без логики, declarative structures, thin adapters, прямолинейная orchestration, hygiene scripts и third-party behavior проверяются существующим integration/contract gate, если нет собственного branching, transformation, invariant или regression. - Перед custom implementation в обязательных областях включи действие по утверждённому Solution Assessment из Design. Artifact boundary — MUST NOT include: - новое observable behavior или Requirement: сначала верни изменение в Specs; - новое архитектурное решение или отклонение от утверждённого Design: сначала обнови Design; - одну задачу с несколькими owner repositories: раздели её по delivery areas; - vague action без проверяемого результата: сформулируй конкретное DO и planned Verification; - ещё не наблюдённые результаты как выполненные, предполагаемые commit identifiers, archive path или post-archive Completion Evidence: такое evidence создаётся только после факта. Example: 1. Delivery □ 1.1 [backend] Implement session rejection Covers: user-authentication — Expired session is rejected Verification: Run the backend canonical gate and the expiry contract test. □ 1.2 [workspace] Run cross-area semantic review Covers: N/A — verification only; no independent spec behavior. Verification: Compare delivery against every approved Requirement and Scenario. Reference specs for what needs to be built, design for how to build it. После записи выполни `bash specs/scripts/verify-openspec-planning.sh ` и исправь технические нарушения до запроса approval. Если Tasks требует новое behavior или architecture, не расширяй scope: вернись к Specs или Design и инвалидируй Tasks approval. requires: - design apply: requires: [ tasks ] tracks: tasks.md instruction: | Сначала проверь exact OpenSpec version contract. Работай только с change в canonical store `wealth-ledger-specs` и не создавай parallel planning root. Apply допустим только после явных approvals Proposal, Delta Specs, Design и Tasks из разговора. До реализации выполни `bash specs/scripts/verify-openspec-planning.sh `. Read context files, work through pending tasks, run each planned Verification and mark a checkbox complete only after observed success. Pause if you hit blockers or need clarification. Feedback routing: - intent/scope mismatch → Proposal; - observable behavior mismatch → Delta Specs; - architecture/rollback mismatch → Design; - decomposition/ownership/coverage mismatch → Tasks. Останови downstream work, сообщи наблюдаемое основание и инвалидируй approvals начиная с самого раннего затронутого artifact. Только механическое syntax/format исправление без изменения intent, behavior, decisions или task scope можно исправить и повторно структурно проверить без reapproval. Structural validation не заменяет semantic verification и independent read-only review. design.md (шаблон) ## Context ## Goals / Non-Goals **Goals:** **Non-Goals:** ## Decisions ## Delivery Map | Area | Status | Architectural outcome or N/A reason | | --- | --- | --- | | frontend | `affected` or `N/A` | | | backend | `affected` or `N/A` | | | specs | `affected` | | | docs | `affected` or `N/A` | | ### Contract Gate Decision | Gate | Status | Reason | | --- | --- | --- | | runtime-openapi | `required` or `N/A` | | ## Solution Assessment ## Risks / Trade-offs ## Migration Plan ### Rollback Contract | Field | Decision | | --- | --- | | Status | `required` or `N/A` | | Reason | | | Trigger | | | Actions | | | Data safety | | | Verification | | ## Open Questions proposal.md (шаблон) ## Why ## What Changes ## Capabilities ### New Capabilities - ``: ### Modified Capabilities - ``: ## Impact spec.md (шаблон) ## Purpose ## ADDED Requirements ### Requirement: #### Scenario: - **WHEN** - **THEN** tasks.md (шаблон) ## 1. - [ ] 1.1 [area] - **Covers:** `` — `` - **Verification:** - [ ] 1.2 [area] - **Covers:** `N/A` — - **Verification:** ## 2. - [ ] 2.1 [area] - **Covers:** `` — `` - **Verification:** - [ ] 2.2 [workspace] - **Covers:** `N/A` — - **Verification:** 2. Анализ обновлённой схемы (v2) 2.1. Улучшения по сравнению с v1 Валидация на каждом этапе – добавлен обязательный запуск bash specs/scripts/verify-openspec-planning.sh . Явные артефактные границы – для каждого артефакта чётко перечислено, что нельзя включать, что предотвращает смешение уровней. Утверждение и инвалидация – каждый артефакт требует approval владельца, при обнаружении несоответствия инвалидируются downstream approvals. Трассируемость задач – в tasks.md добавлены поля Covers и Verification, каждая задача привязана к требованию. Роллбэк-контракт – в design.md добавлен обязательный раздел Rollback Contract для критичных изменений. Поддержка многокомпонентности – введены owner‑области (frontend, backend, specs, docs, workspace) с правилами для кросс‑репозиторных изменений. Примеры для всех дельт – в инструкции к specs добавлены компактные примеры для ADDED, MODIFIED, REMOVED, RENAMED. Доработан процесс apply – включает проверку approvals, выполнение скрипта, пошаговую реализацию с верификацией и механизм обратной связи. 2.2. Оставшиеся незначительные нюансы Инструкции всё ещё достаточно объёмны; можно вынести повторяющиеся части (например, описание planningHome.root) в отдельный общий файл. Отсутствует интеграция с CI/CD для автоматического запуска валидации при создании PR – это уже за рамками схемы, но может быть добавлено. Нет явного механизма версионирования самих изменений (кроме версии схемы). 3. Оценка по 100‑балльной шкале Критерий Вес Оценка Обоснование Полнота жизненного цикла (proposal → specs → design → tasks → apply) 20% 20 Все этапы присутствуют, с явными переходами и зависимостями. Есть обратная связь и инвалидация approval при несоответствиях. Чёткость разделения уровней абстракции (why/what/how/do) 15% 15 Артефактные границы жёстко прописаны для каждого этапа. Это предотвращает смешивание intent, поведения, архитектуры и реализации. Поведенческая спецификация (формат дельт, сценарии WHEN/THEN) 10% 10 Требования используют SHALL/MUST, сценарии с 4 #, поддерживаются ADDED/MODIFIED/REMOVED/RENAMED. Полное копирование при модификации – безопасно. Автоматическая валидация (verify-openspec-planning.sh) 10% 10 Встроенный скрипт на каждом этапе – отличное решение, предотвращающее синтаксические ошибки до ревью. Трассируемость (Covers в задачах) 10% 10 Каждая задача явно привязана к требованию или имеет обоснование N/A. Это даёт полную прослеживаемость. Управление рисками и решениями (Solution Assessment, Rollback Contract) 10% 9 Оба раздела присутствуют и формализованы. Немного не хватает конкретных критериев, когда Solution Assessment обязателен (хотя области перечислены). Поддержка многокомпонентных изменений (owner‑areas, workspace) 10% 9 Введены frontend/backend/specs/docs/workspace с явными правилами. Есть, но не детализирована синхронизация версий и порядок деплоя – это скорее для проектов с несколькими репозиториями. Процесс утверждений и инвалидаций 10% 10 Чётко прописано, что каждый артефакт требует approval владельца, а при изменении более раннего артефакта – инвалидируются downstream approvals. Инструкции для AI (чёткость, примеры, избегание неоднозначности) 5% 4 Инструкции подробны, есть примеры. Однако всё ещё достаточно объёмны; можно было бы вынести повторяющиеся части в отдельный файл. Итого: 20 + 15 + 10 + 10 + 10 + 9 + 9 + 10 + 4 = 94/100