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

name: wealth-ledger-sdd-v2
version: 8
description: Multi-repo SDD workflow - proposal → specs → system-analysis → design + qa-analysis → docs-impact → tasks → apply

artifacts:
  - id: proposal
    generates: proposal.md
    description: Owner-approved intent, scope, capabilities, impact and success criteria
    template: proposal.md
    instruction: |
      Purpose:
      Proposal фиксирует намерение изменения: зачем оно нужно, что меняется на
      уровне продукта/системы, где проходит scope и по каким наблюдаемым признакам
      change можно считать успешным. Это не requirements specification, не system
      analysis и не engineering design.

      Read First:
      - Прочитай релевантные canonical behavior specs из `specs/openspec/specs/`.
      - Прочитай только релевантные AS-IS pages в `docs/`: `overview.md`,
        `architecture/`, `domains/`, `integrations/`, `adr/`, `design/`.
      - Не исследуй code-level реализацию глубже, чем требуется для корректного
        scope/impact. Proposal не должен зависеть от случайной структуры кода.

      Critical Rules:
      - Один Proposal = одно связное намерение. Независимо поставляемые или
        независимо согласуемые изменения предпочитай разделять.
      - Пиши языком Change Owner: проблема, цель, scope, observable outcome.
      - Не дублируй будущие Requirements/Scenarios и не проектируй решение.
      - Новую/изменяемую интеграцию можно обозначить как impact/dependency, но
        protocol, endpoint, payload, error mapping и sequence здесь запрещены.
      - Capabilities перечисляют каждую новую или изменяемую behavior spec точным
        canonical path.
      - Если observable behavior не меняется, не выдумывай Requirement: capability
        delta остаётся пустой, а change использует `.openspec.yaml: skip_specs: true`.
      - Breaking observable behavior помечай **BREAKING**.
      - Вопрос, способный изменить intent/scope/capabilities, должен быть разрешён
        до approval Proposal.

      Required Shape:
      - **Why**: проблема/возможность и почему ею нужно заняться сейчас.
      - **What Changes**: краткий список изменяемых outcomes.
      - **Scope**:
        - **In Scope**
        - **Out of Scope / Non-Goals**
      - **Capabilities**:
        - **New Capabilities**: exact `specs/<capability-path>/spec.md`.
        - **Modified Capabilities**: exact existing capability path только если
          меняются Requirements.
      - **Impact**: пользователи, процессы, домены, внешние системы и вероятно
        затрагиваемые areas на high level; без code/repository topology деталей.
      - **Success Criteria**: продуктовые/системные наблюдаемые признаки успеха.
      - **Assumptions / Dependencies**: только существенные для scope.

      MUST NOT Include:
      - files/classes/functions/hooks/tables/ORM entities;
      - libraries/frameworks/storage/cache/queue/transport choices;
      - endpoint/payload/error-code contracts;
      - sequence/component diagrams;
      - unit/integration/E2E plan;
      - implementation/tasks/PR/commit/branch plan;
      - пиксельные UI details или инженерные решения.

      Validation and Approval:
      - После записи используй native OpenSpec validation against the resolved planning home.
      - Structural success не является semantic approval.
      - Покажи Proposal Change Owner и остановись до explicit approval.
    requires: []

  - id: specs
    generates: "specs/**/*.md"
    description: Normative black-box behavioral deltas and acceptance-level invariants
    template: spec.md
    instruction: |
      Purpose:
      Delta Specs — нормативный black-box behavior contract. Они отвечают только
      на вопрос: "Что система обязана делать с точки зрения пользователя или
      внешнего наблюдателя?" После sync/archive они становятся canonical behavior
      specs в repository `specs/`.

      Preconditions:
      - Proposal explicitly approved.
      - Используй только capabilities из approved Proposal.
      - Для existing capability прочитай canonical spec целиком.
      - При `.openspec.yaml: skip_specs: true` не создавай spec files и не
        выдумывай behavior ради workflow.

      Critical Rules:
      - Один Requirement = одно устойчивое observable behavior/invariant.
      - Нормативный язык следует project BCP 14 policy из `config.yaml`:
        SHALL/MUST для обязательств; SHOULD/MAY только при намеренной вариативности.
      - Каждый Requirement имеет минимум один `#### Scenario:` с конкретным
        WHEN/THEN; GIVEN допустим для precondition.
      - Scenario должен быть проверяемым на уровне системы, но не предписывает
        конкретный test level/automation implementation.
      - Покрой значимые happy path, business errors, permissions, boundaries,
        state transitions и compatibility cases; не перечисляй комбинации ради
        искусственной полноты.
      - Security/privacy/reliability/performance constraints включай только если
        они являются observable/contractual obligation.
      - Технический термин допустим только когда он сам является стабильным
        внешним обязательством. Internal implementation terms запрещены.
      - Не дели Requirements на frontend/backend/main/docs/qa: spec описывает
        систему как единое целое.
      - System names, transport, endpoint, schema и code mappings по умолчанию
        принадлежат System Analysis. Они попадают в spec только если их identity
        сама является частью публичного/регуляторного behavior contract.

      Delta Operations:
      - `ADDED`: новый Requirement или capability.
      - `MODIFIED`: скопируй ПОЛНЫЙ existing Requirement block со всеми scenarios,
        затем измени behavior; heading должен совпасть точно.
      - `REMOVED`: добавь **Reason** и **Migration**.
      - `RENAMED`: только rename heading в формате `FROM:` / `TO:`.
      - Не оставляй пустые operation sections.

      New Capability:
      - Добавь `## Purpose` из 1–2 предложений (не менее 50 characters).
      - Existing Purpose в delta не дублируй.
      - Не переименовывай capability path обычной MODIFIED delta.

      Quality Gate:
      - Requirement однозначен и атомарен.
      - Scenario имеет ясный trigger и проверяемый outcome.
      - Нет "работает корректно", "быстро", "удобно" без критерия.
      - Нет implementation details.
      - Нет поведения вне approved Proposal.
      - Нет противоречия canonical specs.
      - Manual QA способен понять expected behavior без чтения implementation code.

      Feedback Routing:
      - intent/scope/capabilities → Proposal.
      - Systems/contracts/mappings/integration semantics → не решай здесь;
        детализируй позже в System Analysis.

      Validation and Approval:
      - После записи используй native OpenSpec validation against the resolved planning home.
      - Owner: System Analyst. QA выполняет testability review; affected engineers
        проверяют реализуемость, не подменяя requirements design.
      - Остановись до explicit Delta Specs approval.
    requires:
      - proposal

  - id: system-analysis
    generates: system-analysis/analysis.md
    description: Cross-system decomposition, complete flows, contract-first interfaces, mappings, failures and semantic observability
    template: system-analysis.md
    instruction: |
      Purpose:
      System Analysis детализирует approved Delta Specs на уровне взаимодействия
      систем. Он отвечает на вопрос: "Как требуемое behavior распределяется между
      системами и какие межсистемные contracts/flows должны существовать?"
      Это артефакт системного аналитика, а не internal engineering design.

      Read First:
      - Approved Proposal и все Delta Specs change.
      - Релевантный AS-IS из `docs/`: `architecture/`, `domains/`, `integrations/`,
        `adr/` и только нужные cross-cutting pages.
      - Для существующего HTTP API прочитай текущий backend-generated OpenAPI.
      - Для существующих внешних integration contracts прочитай их canonical/runtime
        source, если он доступен.
      - Не принимай текущий code layout за обязательный contract.

      Critical Rules:
      - System Analysis MAY elaborate Requirements, но MUST NOT молча вводить
        новое observable behavior. Uppercase BCP 14 keywords используй только для
        реальных межсистемных обязательств, не как усилители обычной прозы. Если обнаружен behavioral gap, сначала обнови
        Delta Specs и переутверди их.
      - System-level interactions и contracts согласуются здесь ДО Design.
      - Sequence diagrams здесь — полные system-level flows: участники, calls/events
        и релевантные success/business-error/technical-failure branches.
      - Design не переизобретает согласованные здесь interactions/contracts.
      - Для сложного процесса предпочти несколько читаемых sequence diagrams одной
        огромной диаграмме.
      - Не описывай internal classes/hooks/modules/repositories/FSD/NestJS layout,
        DB tables или developer unit-test strategy.

      Contract-First Policy:
      - Для нового/изменяемого межсистемного HTTP/event contract target contract
        определяется и согласуется ДО implementation.
      - Machine-readable target contracts храни в
        `system-analysis/contracts/` (OpenAPI/AsyncAPI/Proto/JSON Schema).
      - Markdown фиксирует semantics и ссылается на contract files, не копирует
        большие schemas.
      - Frontend и Backend могут независимо планировать/реализовывать работу против
        approved target contract.
      - WealthLedger backend-generated OpenAPI остаётся executable/runtime source
        после реализации. До закрытия change он MUST быть semantic-compatible с
        approved contract from System Analysis.
      - Не создавай второй вечный canonical OpenAPI в `specs/`: approved contract
        остаётся частью archived change. Текущее executable API подтверждается
        backend code/generated OpenAPI; `docs/` хранит durable explanation, а не
        дублированную machine-readable truth.
      - Semantic mismatch generated OpenAPI ↔ approved contract возвращает change
        в System Analysis; нельзя тихо принять реализацию как новую спецификацию.

      Required Shape:
      - **Requirement Coverage**:
        mapping релевантных Requirements/Scenarios на flows/contracts.
      - **Systems and Responsibilities**:
        participating applications/services/external systems, role и boundary.
      - **Interaction Flows**:
        flows со ссылками на `system-analysis/sequences/*.mmd`.
      - **Contracts**:
        producer/consumer, protocol/transport, operation/event, version,
        machine-readable schema reference, compatibility expectations,
        correlation/idempotency semantics где нужны.
      - **Data and State Semantics**:
        source of truth/data ownership, cross-system mappings, state transitions,
        validation boundaries, consistency expectations.
      - **Error and Recovery Semantics**:
        business vs technical failures, external→domain mapping, timeout,
        duplicate/out-of-order/callback semantics и retry только на boundary level.
      - **Observability Semantics**:
        какие значимые product/business/system events обязаны фиксироваться.
        Допустимы semantic mappings вроде `code=1 → NO_MONEY`,
        `code=2 → FRAUD`, `Pay click → BUTTON_CLICK`, required attributes/triggers.
        SDK/exporter/logger/instrument — Design.
      - **Security and NFR at System Boundaries**:
        authn/authz/trust boundaries, SLA/latency/rate/compatibility constraints,
        только если они являются system contract.
      - **Compatibility / Migration**:
        system-level transition (например SOAP → REST), coexistence/cutover,
        backward compatibility и dependency sequencing.
      - **Durable Documentation Candidates**:
        перечисли только факты/диаграммы/решения, которые вероятно должны остаться
        в AS-IS `docs/` после завершения change. Финальное решение принимает
        `docs-impact` после Engineering Design.
      - **Open Questions**:
        только genuinely non-blocking. Вопрос, меняющий behavior/contract/
        implementability, блокирует approval.

      MUST NOT Include:
      - internal implementation files/classes/framework choices;
      - internal DB schema/migration details;
      - developer unit/component/internal integration test prescriptions;
      - task checklist;
      - новое behavior вне Delta Specs;
      - попытку заранее переписать `docs/`: этот artifact описывает TO-BE change,
        а promotion в canonical AS-IS планируется отдельно.

      Review and Approval:
      - Owner: System Analyst.
      - Mandatory reviewers: affected Frontend/Backend engineers; QA reviews
        testability/failure semantics.
      - behavior change → Specs; intent/scope change → Proposal.
      - После записи используй native OpenSpec validation against the resolved planning home.
      - Остановись до explicit System Analysis approval.
    requires:
      - specs

  - id: design
    generates: design.md
    description: Internal engineering design for implementing approved behavior and system contracts in main/frontend/backend
    template: design.md
    instruction: |
      Purpose:
      Design отвечает на вопрос: "Как affected implementation repositories
      реализуют свою сторону approved Specs и System Analysis?"
      Это internal engineering design, а не повторный system analysis.

      Preconditions:
      - Proposal, applicable Specs и System Analysis approved.
      - System-level sequences/contracts/mappings считаются input constraints.

      Critical Rules:
      - Не добавляй observable behavior вне Specs.
      - Не изменяй system contract/interaction semantics из System Analysis.
      - Технически нереализуемый contract возвращай в System Analysis, не создавай
        альтернативный private contract внутри Design.
      - Не пересказывай upstream artifacts; проектируй внутренний implementation.
      - Files/classes/modules/components допустимы только когда помогают зафиксировать
        существенное решение; Design не file-by-file checklist.
      - Developer-owned test strategy принадлежит implementation owners. QA не
        диктует unit/component/internal integration tests frontend/backend.
      - Blocking вопрос по approach/migration/task decomposition реши до approval.

      Required Shape:
      - **Context and Constraints**: relevant current implementation constraints.
      - **Technical Goals / Non-Goals**.
      - **Implementation Impact Map**:
        рассмотри `main`, `frontend`, `backend` и future `qa`.
        Для каждой area: `affected` + outcome либо `N/A` + reason.
        `main` affected только при workspace/dev/release configuration impact.
        `qa` существует только после появления реального repository.
      - **Decisions**:
        ключевые implementation decisions, rationale, rejected alternatives.
        Разделяй по affected repositories:
        - `main`: Compose/workspace/release/config orchestration only.
        - `frontend`: React/Vite structure, state/data flow, routing, UI composition,
          API client integration, frontend developer verification approach.
        - `backend`: NestJS modules/services, Prisma/SQLite persistence, migrations,
          transactions, background work, backend developer verification approach.
        - `qa`: только когда repo существует; internal Playwright architecture
          принадлежит automation owner.
      - **Cross-cutting Implementation**:
        security implementation, feature flags, technical observability/logging,
        caching, concurrency, performance mechanisms, internal error handling.
      - **Data / Storage Changes**:
        Prisma/SQLite schema, migration/backfill/data-safety details.
      - **Contract Implementation**:
        как implementation будет соответствовать approved contract; для backend
        укажи, как generated OpenAPI будет verified against target contract.
      - **Developer Verification Strategy**:
        разработчики сами определяют unit/component/internal integration coverage
        и technical gates. Не копируй QA system verification matrix.
      - **UI/UX Package**:
        `new/changed`, `reuse` или `N/A`; relevant source/revision, screens, states,
        interactions, responsive/a11y expectations. Не требуй новый mockup для
        неизменяемого UI. Approved package remains accessible after archive.
      - **Risks / Trade-offs**.
      - **Migration / Rollout / Rollback**:
        implementation sequencing across repos, flags, data safety; mandatory
        rollback contract для security/destructive migration/public contract или
        другого труднообратимого решения, иначе `N/A` + reason.
      - **Solution Assessment**:
        обязателен для нового/существенно заменяемого auth, security, storage,
        external integration, observability, caching, concurrency, shared
        infrastructure/tooling или другого дорогостоящего необратимого решения.
        Сравни mature options по fit, maturity, security, operating cost,
        constraints и migration cost; custom implementation обоснуй конкретной
        несовместимостью alternatives. Не создавай отдельный artifact.
      - При UI/UX scope Design сохраняет package revision и exact immutable reuse
        locator (store ID и path от OpenSpec root), применимые части и отличия.
        Inline Markdown достаточен по умолчанию; необходимые PNG/SVG хранятся
        локально под `visuals/` с relative path, purpose и SHA-256 каждого файла.
        SVG самодостаточен: без scripts, handlers, external assets/fonts.
        External-only mutable URL или временный чат не заменяют согласованный
        пакет. Единственный approval Design охватывает всю версию пакета;
        self-hash Design не требуется. При Apply проверь наличие и SHA-256
        перечисленных материалов перед зависимой работой.

      MUST NOT Include:
      - approved system-level sequence diagrams;
      - новые/изменённые API/event contracts без возврата в System Analysis;
      - новое behavior без возврата в Specs;
      - canonical docs update plan (это `docs-impact`);
      - QA system test cases/coverage strategy;
      - implementation checklist/PR plan/future results;
      - длинные production code listings.

      Feedback Routing:
      - intent/scope → Proposal;
      - observable behavior → Specs;
      - systems/contracts/mappings/error semantics/semantic observability → System Analysis;
      - internal implementation choice → Design.

      Validation and Approval:
      - После записи используй native OpenSpec validation against the resolved planning home.
      - Reviewers: owners affected implementation repositories.
      - Остановись до explicit Design approval.
    requires:
      - system-analysis

  - id: qa-analysis
    generates: qa-analysis.md
    description: Risk-based system verification analysis independent from developer-owned internal test architecture
    template: qa-analysis.md
    instruction: |
      Purpose:
      QA Analysis отвечает на вопрос: "Что необходимо проверить, чтобы доказать
      работоспособность системы согласно Specs и System Analysis?"
      Это product/system verification artifact, не internal test design кода.

      Preconditions:
      - Specs approved.
      - System Analysis approved.
      - QA Analysis может выполняться параллельно с Engineering Design.

      Critical Rules:
      - QA проверяет system behavior, а не устройство кода.
      - Не предписывай разработчикам unit/component/internal integration tests,
        mocks внутри application code, coverage percentage, filenames/classes.
      - Не создавай новое behavior: undefined expected result → gap в Specs.
      - Undefined flow/error mapping/contract → gap в System Analysis.
      - Нужный testability hook/environment support формулируй как need для Design,
        но не проектируй его implementation за разработчика.
      - Manual QA и Automation QA используют один artifact. Automation scope —
        black-box API/cross-system/E2E. Internal code tests остаются developer-owned.
      - Не дублируй scenarios; ссылайся на exact Requirement/Scenario.

      Required Shape:
      - **Verification Scope**: in/out capabilities/requirements/scenarios.
      - **Coverage Matrix**: Requirement/Scenario → system-level checks.
      - **Cross-system Verification**: contracts/error mapping/timeouts/unavailable/
        duplicates/out-of-order only where relevant.
      - **Risk-based Priorities**: critical journeys, money/security/data-integrity,
        compatibility/regression hotspots.
      - **Test Data and Environment Needs**: system-level states, accounts,
        permissions, external sandboxes/stubs; без internal mocking prescriptions.
      - **Manual / Exploratory Scope**.
      - **Automation Candidates**: black-box API/cross-system/E2E candidates.
        Пока отдельного QA repo нет, помечай repository automation как
        `deferred until QA repo exists`; не выдумывай paths/tasks.
      - **Observability Verification**: как на system level подтвердить semantic
        events (`NO_MONEY`, `FRAUD`, `BUTTON_CLICK` и т.п.), без SDK code.
      - **Regression Impact**.
      - **Gaps / Blockers**: каждый gap имеет routing destination.

      MUST NOT Include:
      - unit/component/internal integration plan frontend/backend;
      - private code classes/functions/files;
      - application architecture decisions;
      - guessed expected behavior;
      - дублирование Design.

      Review and Approval:
      - Owner: Manual QA / QA responsible for system verification.
      - Automation QA reviews automation feasibility when role exists.
      - Product/System Analyst reviews acceptance interpretation.
      - Affected engineers review testability dependencies.
      - После записи используй native OpenSpec validation against the resolved planning home.
      - Остановись до explicit QA Analysis approval.
    requires:
      - system-analysis

  - id: docs-impact
    generates: docs-impact.md
    description: Promotion plan from change-specific knowledge to canonical AS-IS documentation in docs repository
    template: docs-impact.md
    instruction: |
      Purpose:
      Docs Impact отвечает на вопрос: "Какое durable knowledge после успешной
      реализации должно изменить canonical AS-IS documentation в `docs/`?"
      Это planning artifact в `specs/`, а не сама документация.

      Canonical Documentation Model:
      `docs/` — source of truth для актуального product/architecture description:
      - `README.md`, `overview.md`, `glossary.md` — navigation/product overview/terms;
      - `architecture/` — context, components, HTTP API, deployment;
      - `architecture/cross-cutting/` — cross-cutting system concerns;
      - `domains/` — durable domain/product behavior explanations;
      - `integrations/` — external systems and integrations;
      - `adr/` — historical architectural decisions; accepted ADR не переписывается
        под новое текущее состояние;
      - `design/` — durable visual/design principles.

      Preconditions:
      - System Analysis approved.
      - Engineering Design approved.
      - Прочитай только релевантные current pages в `docs/` и не создавай duplicate
        page, если подходящее canonical location уже существует.

      Critical Rules:
      - Не копируй весь change в docs. Promote только knowledge, полезное после
        того как change перестанет быть актуальной задачей.
      - Canonical docs описывают resulting AS-IS, а не migration history.
      - Migration rationale/history остаётся в archived OpenSpec change; если
        решение архитектурно значимо, создай/обнови ADR plan.
      - Не требуй переносить каждую system-analysis sequence. Promote только
        важные долгоживущие diagrams, которые помогают понимать текущую систему.
      - Не копируй machine-readable OpenAPI из System Analysis как второй canonical
        contract. `docs/` может описывать API/integration semantics и ссылаться на
        generated/runtime API source.
      - `docs-impact` не редактирует `docs/`; он создаёт точный promotion plan,
        из которого Tasks создаст `[docs]` implementation items.

      Required Shape:
      - **Summary**: нужен ли durable docs update вообще.
      - **Documentation Changes**: таблица/список entries со свойствами:
        - `Action`: create | update | remove | none;
        - `Target`: exact path under `docs/`;
        - `Category`: overview | architecture | cross-cutting | domain |
          integration | ADR | design;
        - `Resulting AS-IS`: что именно должно стать истинным после change;
        - `Source`: ссылка на Specs/System Analysis/Design decision;
        - `Verification`: как понять, что canonical docs согласованы с реализацией.
      - **Diagram Promotion**: какие diagrams из `system-analysis/sequences/`
        становятся durable docs, куда именно и почему; default = не переносить.
      - **ADR Decision**:
        - `required` только если принято значимое, долгоживущее архитектурное
          решение с alternatives/consequences;
        - иначе `N/A` + reason.
      - **Glossary / Navigation Impact**: только если реально нужны новые термины
        или navigation entries.
      - **No-Change Rationale**: если docs не меняются, конкретно объясни почему.

      MUST NOT Include:
      - временный migration diary как canonical AS-IS;
      - копию proposal/specs/system-analysis;
      - machine-readable API contract как второй source of truth;
      - implementation tasks; они создаются в Tasks;
      - fictional docs paths без проверки существующей структуры.

      Review and Approval:
      - Owner: System Analyst + affected engineering owner совместно подтверждают,
        что planned docs отражают target system accurately.
      - Для ADR engineering owner подтверждает decision/consequences.
      - После записи используй native OpenSpec validation against the resolved planning home.
      - Остановись до explicit Docs Impact approval.
    requires:
      - design
      - qa-analysis
      - system-analysis

  - id: tasks
    generates: tasks.md
    description: Dependency-ordered, repository-owned delivery checklist derived from approved planning artifacts
    template: tasks.md
    instruction: |
      Purpose:
      Tasks — исполняемый delivery plan. Он отвечает только на вопрос:
      "Какие independently reviewable outcomes нужно доставить и проверить, чтобы
      реализовать approved plan?"

      Preconditions:
      - Design, QA Analysis и Docs Impact explicitly approved.
      - Proposal/Specs/System Analysis остаются authoritative upstream contracts.

      Repository Owners:
      - `[main]` — только workspace/dev/release orchestration changes.
      - `[frontend]` — React/Vite product implementation.
      - `[backend]` — NestJS/Prisma/SQLite product implementation.
      - `[docs]` — canonical AS-IS documentation changes из approved Docs Impact.
      - `[specs]` — только genuine specs-repository maintenance beyond native
        change/sync/archive (например schema/governance change).
      - `[qa]` — только после появления реального QA/E2E repository.

      Task Format:
      Каждый checkbox:
      `- [ ] X.Y [main|frontend|backend|docs|specs|qa] <action + outcome>`
      и содержит:
        - **Covers:** exact `` `capability-path` — `Requirement heading` `` pairs
          либо `` `N/A` — <reason> ``.
        - **Source:** exact approved artifact section/contract/docs-impact entry.
        - **Verification:** owner-controlled command, observable check или delivered
          artifact; не будущий result.
        - **Depends on:** task IDs либо `none`, если зависимость неочевидна.

      Critical Rules:
      - Одна task = один owner repository + один independently reviewable outcome.
      - Cross-repository work всегда разделяй.
      - Product feature code никогда не помещай в `[main]`.
      - `[docs]` tasks MUST соответствовать approved `docs-impact` entries; не
        придумывай документацию заново на этапе Tasks.
      - `[qa]` task запрещена, пока repo не существует. Manual QA/acceptance не
        маскируй под implementation checkbox.
      - Каждый Delta Requirement должен иметь implementation coverage либо ясное
        объяснение, почему implementation work не требуется.
      - При изменении contract обязательно запланируй verification, что
        backend-generated OpenAPI/runtime interface semantic-compatible с approved
        System Analysis contract до закрытия change.
      - Canonical behavior specs не обновляй вручную task'ом: их merge выполняет
        native OpenSpec sync/archive.
      - Developer-owned tests следуют Design; QA system verification следует
        QA Analysis. QA task не диктует unit/component tests разработчика.
      - Не создавай empty/ceremonial tasks.

      Grouping:
      - Группируй numbered `##` sections по dependency/delivery sequence.
      - Repository ownership остаётся явным внутри каждой группы.
      - Documentation updates обычно выполняются после того, как target state
        подтверждён implementation, если только docs нужны раньше для coordination.

      MUST NOT Include:
      - новое behavior → Specs;
      - новый/изменённый system contract/sequence/error semantics → System Analysis;
      - новый internal architecture decision → Design;
      - новый QA coverage decision → QA Analysis;
      - новый docs promotion decision → Docs Impact;
      - business rationale → Proposal;
      - duplicated payload/schema/design prose;
      - commits/branches/issues/post-hoc completion evidence.

      Feedback Routing:
      - semantic change возвращается в самый ранний затронутый artifact и
        инвалидирует downstream approvals.
      - Vague/multi-owner/oversized decomposition исправляется здесь.

      Validation and Approval:
      - После записи используй native OpenSpec validation against the resolved planning home.
      - Покажи Tasks Change Owner(s) и остановись до explicit approval.
    requires:
      - design
      - qa-analysis
      - docs-impact
      - specs

apply:
  requires:
    - tasks
  tracks: tasks.md
  instruction: |
    Purpose:
    Apply реализует approved delivery plan и не переоткрывает upstream decisions
    без явного feedback cycle.

    Preconditions:
    - Explicit approvals: Proposal; Delta Specs если не `skip_specs`; System
      Analysis; Design; QA Analysis; Docs Impact; Tasks.
    - Используй canonical store `wealth-ledger-specs` для OpenSpec commands.

    Context Loading:
    - Прочитай `contextFiles`, возвращённые native OpenSpec apply instructions.
    - Затем repository-local `AGENTS.md` только affected areas.
    - Для каждой task загружай релевантные upstream sections/contracts, а не весь
      workspace без необходимости.

    Execution:
    - Выполняй pending tasks по dependency order.
    - Не объединяй разные repositories в одну task.
    - Product behavior реализуется только в `frontend/`/`backend/`; `main` меняется
      только при approved workspace/config impact.
    - Запускай task Verification и отмечай checkbox только после observed success.
    - Developer-owned unit/component/internal integration tests выполняются по
      Design/repository rules.
    - QA system/manual validation не считается выполненной только потому, что
      developer tests зелёные; она следует QA Analysis отдельным validation flow.
    - При changed contract backend-generated OpenAPI/runtime contract должен пройти
      semantic comparison с approved System Analysis target before completion.
    - `[docs]` tasks обновляют canonical `docs/` до resulting AS-IS из Docs Impact;
      не переносят change history вместо текущего состояния.
    - Если implementation-owned work остаётся, сохрани checkpoint: completed,
      remaining, observed checks и следующий concrete outcome.
    - READY_FOR_VALIDATION допустим после всех implementation/docs-owned tasks и
      relevant checks. Apply не подменяет independent QA/acceptance.

    Sync / Archive Semantics:
    - Native OpenSpec sync/archive обновляет canonical behavior specs в `specs/`.
    - `docs/` обновляется только через approved `[docs]` tasks из Docs Impact.
    - Full System Analysis, target contracts и migration history остаются в
      archived change как historical planning evidence.
    - Significant architectural decision сохраняется отдельно как immutable ADR в
      `docs/adr/`; AS-IS architecture/integration pages показывают только current state.

    Feedback Routing:
    - intent/scope/capabilities → Proposal;
    - observable behavior/invariants → Specs;
    - systems/sequences/contracts/mappings/error semantics/semantic observability
      → System Analysis;
    - internal architecture/storage/UI implementation/technical observability/
      developer test strategy → Design;
    - system verification/test data/automation candidates → QA Analysis;
    - canonical docs promotion/ADR/diagram retention → Docs Impact;
    - decomposition/ownership/dependencies/task verification → Tasks.

    Change Control:
    - При semantic conflict останови downstream work и сообщи evidence.
    - Инвалидируй approvals от самого раннего затронутого artifact.
    - Mechanical typo/formatting без normative meaning change может не требовать
      reapproval; Requirement/Scenario/contract/sequence/architecture/QA expected
      result/docs target/task verification semantic changes требуют reapproval.
    - Structural validation не заменяет semantic review, tests и independent QA.