spec: finalize wealth-ledger SDD migration

2026-10-09 21:14:22 +03:00
parent 90edab6e33
commit 329d66e767
97 changed files with 3444 additions and 244 deletions
@@ -1,9 +1,69 @@
-schema: wealth-ledger-sdd
+schema: wealth-ledger-sdd-v2

 context: |
-  WealthLedger состоит из независимых frontend, backend, specs и docs Git-репозиториев.
-  Canonical OpenSpec authority — store wealth-ledger-specs в локальном openspec/.
-  Инструкции и validation specs находятся в этом репозитории; соседние checkout не требуются.
-  Локальная разработка и CI используют Node из собственной .nvmrc; порядок работы задаёт AGENTS.md.
-  Project artifacts объясняют решения по-русски; exact OpenSpec headings, tokens,
-  commands и normative keywords SHALL/MUST сохраняются на английском.
+  WealthLedger — multi-repository workspace. The `main` repository is the workspace
+  root and contains sibling repositories `frontend/`, `backend/`, `docs/` and `specs/`.
+  OpenSpec configuration, schemas, changes and canonical behavior specs live only in
+  `specs/openspec/` and are accessed as store `wealth-ledger-specs`. There is no
+  `openspec/` directory or `config.yaml` in `main`, `frontend`, `backend` or `docs`.
+  When an OpenSpec command is invoked from the workspace root, target the canonical
+  store explicitly when that command supports store selection.
+  New changes use `wealth-ledger-sdd-v2`; active changes explicitly pinned to
+  `wealth-ledger-sdd` keep their original proposal → specs → design → tasks → apply
+  lifecycle and existing approvals until completion. Never infer approval from
+  the existence of an artifact. Schema selection comes from each change's
+  `.openspec.yaml`, not from the current default.
+
+  Repository responsibilities and sources of truth:
+  - `main` (`./`): workspace instructions, shared configuration, development Compose
+    and release/workspace orchestration. It MUST NOT contain product feature code.
+  - `frontend/`: React/Vite product implementation.
+  - `backend/`: NestJS product API, Prisma data model and SQLite persistence.
+  - `docs/`: canonical AS-IS product and architecture knowledge. Current architecture,
+    integrations and durable diagrams describe the system as it exists now; historical
+    architectural rationale is preserved in ADRs and archived changes.
+  - `specs/`: OpenSpec changes plus canonical behavior specs. Canonical specs contain
+    normative observable behavior only, not durable implementation documentation.
+  - Future `qa/`: Playwright/E2E automation when the repository actually exists.
+
+  Contract authority:
+  - For v2 changes, new or changed cross-system contracts are planned contract-first
+    in the change's `system-analysis/contracts/` before implementation.
+  - After implementation, backend-generated OpenAPI is the executable/current HTTP API
+    contract and MUST remain semantically compatible with the approved target contract.
+  - Do not create a second permanent machine-readable API source of truth in canonical
+    OpenSpec specs or docs.
+
+  Documentation authority:
+  - `docs/architecture/`, `docs/domains/`, `docs/integrations/` and related pages hold
+    durable AS-IS explanations.
+  - V2 changes select durable knowledge through approved `docs-impact`; legacy
+    changes continue their approved delivery map. Change-specific reasoning,
+    migration history and rejected options remain in the archived OpenSpec change
+    unless an ADR is explicitly required.
+
+  Language and normative terminology:
+  - Human-facing project artifacts are written in Russian, while exact OpenSpec headings,
+    tokens, commands, identifiers and machine-readable contract syntax remain unchanged.
+  - Normative keywords follow BCP 14 (RFC 2119 + RFC 8174). `MUST`, `MUST NOT`,
+    `REQUIRED`, `SHALL`, `SHALL NOT`, `SHOULD`, `SHOULD NOT`, `RECOMMENDED`,
+    `NOT RECOMMENDED`, `MAY` and `OPTIONAL` have normative meaning only when written
+    in uppercase. Lowercase forms have their ordinary-language meaning.
+  - Do not use uppercase BCP 14 keywords merely for emphasis. Use them only when the
+    statement intentionally imposes a normative obligation or permitted variation.
+
+  A downstream artifact cannot silently change upstream semantics: route changes
+  to the earliest affected artifact and reapprove only its affected dependents.
+  Native OpenSpec sync/archive owns behavior delta → canonical specs; docs updates
+  follow approved delivery tasks, not an automatic copy of system analysis.
+
+  Repository-local `AGENTS.md` files remain authoritative for implementation conventions
+  inside their repositories. Load only the affected repository instructions and relevant
+  code/docs; do not scan the entire workspace without need.
+
+operations:
+  archive:
+    guidance:
+      - Keep the change's selected schema and explicit approvals; do not impose v2-only artifacts on legacy changes.
+      - Complete implementation, developer checks, independent verification and canonical documentation before archive. For v2 changes, also check applicable QA Analysis, docs-impact and target contract compatibility with backend-generated OpenAPI.
+      - Native OpenSpec sync/archive updates canonical behavior specs, not implementation documentation.