chore: harden SDD governance workflow

openspec/schemas/wealth-ledger-sdd/schema.yaml

@@ -0,0 +1,244 @@
+name: wealth-ledger-sdd
+version: 1
+description: WealthLedger SDD workflow - proposal → specs → design → tasks
+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/<capability-path>/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.
+
+      MUST NOT включать технологии, библиотеки, API signatures, имена файлов,
+      зависимости, классы или пошаговую реализацию. Эти решения появляются
+      только после Delta Specs в Design.
+
+      This is the foundation - specs, design, and tasks all build on this.
+    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
+
+      Не включай в specs:
+      - Internal class/function names
+      - Library or framework choices
+      - Step-by-step implementation details
+      - Detailed execution plans (those belong in design.md or tasks.md)
+
+      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.
+      `<capability-path>` 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/<capability-path>/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/<capability-path>/` when creating the delta at `specs/<capability-path>/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: <name>` followed by description
+      - Use SHALL/MUST for normative requirements (avoid should/may)
+      - Each scenario: `#### Scenario: <name>` 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 `<planningHome.root>/openspec/specs/<capability-path>/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 `<planningHome.root>/openspec/specs/<capability-path>/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.
+
+      Example (a new capability, so it opens with `## 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
+
+      ## REMOVED Requirements
+
+      ### Requirement: Legacy export
+      **Reason**: Replaced by new export system
+      **Migration**: Use new export endpoint at /api/v2/export
+      ```
+
+      Specs должны быть проверяемыми, но scenario не означает автоматический
+      unit test: уровень проверки выбирается по риску поведения.
+    requires:
+      - proposal
+
+  - id: design
+    generates: design.md
+    description: Architectural implementation approach and delivery decisions
+    template: design.md
+    instruction: |
+      Создай Design, объясняющий, КАК архитектурно выполнить утверждённые
+      Delta Specs. Не превращай его в построчную инструкцию или список правок.
+
+      Обязательные разделы:
+      - **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, если применимо.
+
+      Добавь **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.
+    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 ...` и быть выполнимой за
+        одну рабочую сессию.
+      - Для каждой `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.
+      - MUST NOT записывать ещё не наблюдённые результаты как выполненные,
+        предполагаемые commit identifiers, archive path или post-archive
+        Completion Evidence. Такое evidence создаётся только после факта.
+
+      Example:
+      ```
+      ## 1. Setup
+
+      - [ ] 1.1 Create new module structure and verify expected files are present
+      - [ ] 1.2 Add dependencies to package.json and verify package installation succeeds
+
+      ## 2. Core Implementation
+
+      - [ ] 2.1 Implement data export function and verify the export test passes
+      - [ ] 2.2 Add CSV formatting utilities and verify unit tests cover quoting and delimiters
+      ```
+
+      Reference specs for what needs to be built, design for how to build it.
+    requires:
+      - design
+
+apply:
+  requires: [ tasks ]
+  tracks: tasks.md
+  instruction: |
+    Сначала проверь exact OpenSpec version contract. Работай только с change в
+    canonical store `wealth-ledger-specs` и не создавай parallel planning root.
+    Read context files, work through pending tasks, mark complete as you go.
+    Pause if you hit blockers or need clarification.

openspec/schemas/wealth-ledger-sdd/templates/design.md

@@ -0,0 +1,48 @@
+## Context
+
+<!-- Current state and constraints that shape the approach. See proposal.md for motivation - don't restate it -->
+
+## Goals / Non-Goals
+
+**Goals:**
+<!-- What this design aims to achieve -->
+
+**Non-Goals:**
+<!-- What is explicitly out of scope -->
+
+## Decisions
+
+<!-- Key design decisions with rationale and alternatives considered -->
+
+## Delivery Map
+
+| Area | Status | Architectural outcome or N/A reason |
+| --- | --- | --- |
+| frontend | `affected` or `N/A` | <!-- concrete result or reason --> |
+| backend | `affected` or `N/A` | <!-- concrete result or reason --> |
+| specs | `affected` | <!-- normative result --> |
+| docs | `affected` or `N/A` | <!-- as-built documentation result or reason --> |
+
+### Contract Gate Decision
+
+| Gate | Status | Reason |
+| --- | --- | --- |
+| runtime-openapi | `required` or `N/A` | <!-- required only when both API contract sides change; otherwise concrete N/A reason --> |
+
+## Solution Assessment
+
+<!-- Include only when the change crosses a mandatory build-vs-buy trigger.
+     Compare mature options and custom implementation; otherwise remove section. -->
+
+## Risks / Trade-offs
+
+<!-- Known risks and trade-offs -->
+
+## Migration Plan
+
+<!-- Delivery order and rollback, when applicable -->
+
+## Open Questions
+
+<!-- Only questions that cannot change Specs, approach or Tasks; otherwise
+     resolve with the Change Owner before saving Design. Remove if empty. -->

openspec/schemas/wealth-ledger-sdd/templates/proposal.md

@@ -0,0 +1,30 @@
+## Why
+
+<!-- Explain the motivation for this change. What problem does this solve? Why now? -->
+
+## What Changes
+
+<!-- Describe the intended outcome and explicit non-goals without technologies,
+     APIs, files, dependencies or implementation decisions. -->
+
+## Capabilities
+
+### New Capabilities
+<!-- Capabilities being introduced. Use kebab-case for path segments you introduce
+     (e.g., user-auth or identity/user-auth) that follow the project's existing
+     spec organization. Each creates specs/<capability-path>/spec.md. -->
+- `<capability-path>`: <brief description of what this capability covers>
+
+### Modified Capabilities
+<!-- Existing capabilities whose REQUIREMENTS are changing (not just implementation).
+     Only list here if spec-level behavior changes. Each needs a delta spec file.
+     Use the exact existing path under openspec/specs/. Leave empty if no requirement
+     changes. A change with no capabilities at all (pure refactor, tooling, docs)
+     must set `skip_specs: true` in its .openspec.yaml - openspec validate rejects
+     a zero-delta change without that marker. Do not invent a requirement just to
+     satisfy validation. -->
+- `<existing-capability-path>`: <what requirement is changing>
+
+## Impact
+
+<!-- Affected users, processes or system areas at scope level only. -->

openspec/schemas/wealth-ledger-sdd/templates/spec.md

@@ -0,0 +1,11 @@
+## Purpose
+<!-- New capabilities only: one or two sentences (50+ characters) on what this capability is for. Delete this section for an existing capability. -->
+
+## ADDED Requirements
+
+### Requirement: <!-- requirement name -->
+<!-- requirement text -->
+
+#### Scenario: <!-- scenario name -->
+- **WHEN** <!-- condition -->
+- **THEN** <!-- expected outcome -->

openspec/schemas/wealth-ledger-sdd/templates/tasks.md

@@ -0,0 +1,9 @@
+## 1. <!-- Task Group Name -->
+
+- [ ] 1.1 <!-- Concrete implementation action and its planned verification -->
+- [ ] 1.2 <!-- Concrete implementation action and its planned verification -->
+
+## 2. <!-- Task Group Name -->
+
+- [ ] 2.1 <!-- Affected repository action and canonical local gate -->
+- [ ] 2.2 <!-- Cross-area verification when required -->