feat: add experimental wealth-ledger-sdd-lab OpenSpec schema (#61)

2026-10-29 05:58:29 +03:00
parent 093185d44d
commit 322ddf6a7f
18 changed files with 1457 additions and 0 deletions
@@ -0,0 +1,29 @@
+# Data Mapping
+
+<!-- guide: Field-level transformation between systems. Large mappings go to a
+     machine-checkable file in contracts/ and are referenced here. Remove guides. -->
+
+## Source and Target
+
+| Mapping | Source (owner) | Target (owner) | Direction | Trigger |
+| --- | --- | --- | --- | --- |
+
+## Field Mapping
+
+| Target field | Source field(s) | Transformation | Unit / currency / scale | Nullability | Default | Validation | On failure |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+
+## Invariants
+
+<!-- guide: Conservation rules that must hold after mapping, e.g. "total = sum of
+     positions + cash; each money unit counted once", sign conventions, rounding
+     point. Each invariant references the spec requirement it protects. -->
+
+## Double-counting and Classification Risks
+
+<!-- guide: Every source record type that could fall into two target aggregates,
+     and the rule that assigns it to exactly one. -->
+
+## Transformation Errors
+
+## Open Questions
@@ -0,0 +1,58 @@
+# Engineering Design
+
+<!-- guide: How affected repositories implement approved specs and system
+     obligations. Reference upstream ids; do not restate them. Remove guides. -->
+
+## Inputs
+
+<!-- guide: Exact upstream artifacts this design implements (specs, selected
+     system-analysis modules, ux-design, security-analysis). -->
+
+## Architecture Drivers
+
+<!-- guide: Requirements, NFR ids, constraints and risks that force decisions. -->
+
+## Technical Goals / Non-Goals
+
+## Implementation Impact Map
+
+| Area | Affected | Outcome or N/A reason |
+| --- | --- | --- |
+| main | | |
+| frontend | | |
+| backend | | |
+
+## Decisions
+
+<!-- guide: Per decision: context, chosen option, rejected alternatives, driver it
+     satisfies. Group by repository when that helps. -->
+
+## Components and Responsibilities
+
+## Data / Storage Changes
+
+## Contract Implementation
+
+<!-- guide: How each contract is produced/consumed and how published OpenAPI is
+     compared with the target contract. N/A when no contracts changed. -->
+
+## Cross-cutting Implementation
+
+## UI Implementation
+
+<!-- guide: With ux-design.md: component composition, state, data fetching, how
+     each UI state is produced — no restated UX. Without ux-design.md: state
+     new/changed, reuse or N/A with reason, plus the needed screen/state detail. -->
+
+## Developer Verification Strategy
+
+## Migration / Rollout / Rollback
+
+## Solution Assessment
+
+<!-- guide: Required for new auth, security, storage, integration, observability,
+     caching, concurrency or shared tooling; otherwise N/A with reason. -->
+
+## Risks / Trade-offs
+
+## ADR Candidates
@@ -0,0 +1,18 @@
+# Documentation Impact
+
+<!-- guide: Plan only; docs/ is edited by [docs] tasks. Remove guides. -->
+
+## Summary
+
+## Documentation Changes
+
+| Action | Target | Category | Resulting AS-IS | Source | Verification |
+| --- | --- | --- | --- | --- | --- |
+
+## Diagram Promotion
+
+## ADR Decision
+
+## Glossary / Navigation Impact
+
+## No-Change Rationale
@@ -0,0 +1,26 @@
+# Failure Model
+
+<!-- guide: Boundary-level failure semantics. Implementation of mechanisms (queues,
+     locks, libraries) belongs to design.md. Remove guides before G3. -->
+
+## Failure Scenarios
+
+| ID | Boundary / step | Failure | Detection | Required system behavior | Observable result | Requirement |
+| --- | --- | --- | --- | --- | --- | --- |
+
+## Timeouts and Retries
+
+## Idempotency and Duplicate Handling
+
+<!-- guide: Idempotency key, scope, retention; what a duplicate request/event
+     yields. -->
+
+## Ordering and Concurrency
+
+## Partial Failure and Compensation
+
+## Recovery Behavior
+
+## Compatibility During Failure
+
+## Open Questions
@@ -0,0 +1,14 @@
+# Non-Functional Requirements
+
+<!-- guide: Only measurable constraints that change design or verification.
+     Each row needs a threshold and a way to measure it. Remove guides. -->
+
+| ID | Category | Requirement | Threshold | Measurement / evidence | Rationale / source |
+| --- | --- | --- | --- | --- | --- |
+
+## Constraints Without Thresholds
+
+<!-- guide: Constraints that are real but not measurable yet; state why and who
+     decides the threshold. -->
+
+## Open Questions
@@ -0,0 +1,24 @@
+# Observability
+
+<!-- guide: What must be observable and why; not which SDK, exporter or logger
+     (design.md). Remove guides before G3. -->
+
+## Semantic Events
+
+| Event | Trigger | Required attributes | Consumer / purpose |
+| --- | --- | --- | --- |
+
+## Logs, Metrics and Traces
+
+## Correlation
+
+## SLI and Alert Conditions
+
+| SLI | Definition | Target | Alert condition |
+| --- | --- | --- | --- |
+
+## Diagnostic Scenarios
+
+<!-- guide: "When X happens, an operator can determine Y from Z." -->
+
+## Open Questions
@@ -0,0 +1,57 @@
+# Process Record
+
+**Mode:** <!-- guide: lab | delivery -->
+**Class:** <!-- guide: standard | complex -->
+**Issue:** <!-- guide: Gitea Issue link -->
+
+## Change Profile
+
+<!-- guide: One row per conditional artifact, all ten rows required. Selected =
+     yes|no. Reason cites the concrete trigger from the instruction table or why
+     it does not apply; "lab practice" is a valid reason only in lab mode and
+     must name the practice. -->
+
+| Artifact | Selected | Reason |
+| --- | --- | --- |
+| research | | |
+| ux-design | | |
+| system-analysis | | |
+| data-mapping | | |
+| failure-model | | |
+| nfr | | |
+| observability | | |
+| security-analysis | | |
+| test-cases | | |
+| docs-impact | | |
+
+## Gate Log
+
+<!-- guide: Append-only, chronological. Scope = artifact ids covered by the
+     decision. Validation = commands run and their results, review verdicts.
+     Decision = `approved "<quoted owner words>"`, `rejected`, `changes requested`
+     or `invalidated: <reason>`. Never write a decision the owner did not give. -->
+
+| Gate | Date | Scope | Validation | Findings | Decision |
+| --- | --- | --- | --- | --- | --- |
+
+## Descoped Work
+
+<!-- guide: Tasks removed from tasks.md after G3. Reason and approving gate are
+     required. Leave the header row only when nothing was descoped. -->
+
+| Task | Reason | Gate |
+| --- | --- | --- |
+
+## Lab Journal
+
+<!-- guide: lab mode: one row per completed stage, written right after it.
+     Unique findings = what this stage found that no other stage did.
+     Cost = subagent calls, approximate tokens or time. delivery mode: optional. -->
+
+| Stage | Role / subagent | Unique findings | Decisions | Risks found / excluded | Handoff issues | Skills | Cost | Transferable |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+
+## Retrospective
+
+<!-- guide: Written after G4. Which stages paid off, which were redundant for this
+     class of change, what to change in the schema. Facts first, then opinion. -->
@@ -0,0 +1,36 @@
+# Proposal
+
+<!-- guide: Language of the Change Owner. No files, APIs, tables, libraries,
+     diagrams or test plans. Remove every guide comment before G1. -->
+
+## Why
+
+## What Changes
+
+## Scope
+
+### In Scope
+
+### Out of Scope / Non-Goals
+
+## Capabilities
+
+### New Capabilities
+
+### Modified Capabilities
+
+## Impact
+
+## Success Criteria
+
+## Evidence
+
+<!-- guide: Facts that justify the change, each with a source: Issue, research
+     (link or `research.md`), incident, measurement. Mark hypotheses as such. -->
+
+## Assumptions / Dependencies
+
+## Open Decisions
+
+<!-- guide: Decisions not yet taken that may change scope. Each item: question,
+     who decides, what blocks until it is answered. Empty only if none exist. -->
@@ -0,0 +1,34 @@
+# QA Analysis
+
+<!-- guide: Risk-based system verification strategy. Reference scenarios; do not
+     restate them. No developer unit/component test plans. Remove guides. -->
+
+## Risk Assessment
+
+| Risk | Affected requirements | Likelihood | Impact | Verification depth |
+| --- | --- | --- | --- | --- |
+
+## Coverage Matrix
+
+<!-- guide: One row per delta requirement. Check = system-level way of proving
+     it; test case ids when test-cases is selected; or "not verified: <risk
+     reason>". -->
+
+| Requirement | Check | Level | Test cases |
+| --- | --- | --- | --- |
+
+## Negative and Boundary Focus
+
+## Cross-system Verification
+
+## Test Data and Environment Needs
+
+## Manual / Exploratory Scope
+
+## Automation Candidates
+
+## Regression Impact
+
+## Gaps / Blockers
+
+<!-- guide: Each gap names its routing destination artifact. -->
@@ -0,0 +1,28 @@
+# Product Research
+
+<!-- guide: Input context, not a requirement source. Every claim is marked
+     [F] fact with source, [I] interpretation or [H] hypothesis. Remove guides. -->
+
+## Problem Statement
+
+## Target Audience
+
+## Research Questions
+
+## Existing Solutions and Alternatives
+
+| Option | What it does | Strengths | Weaknesses | Source |
+| --- | --- | --- | --- | --- |
+
+## Evidence & Sources
+
+## Assumptions
+
+## Risks
+
+## Conclusions
+
+## Recommendation
+
+<!-- guide: build / do not build / narrow scope / research more, with reasons.
+     "Do not build" is a valid outcome. -->
@@ -0,0 +1,26 @@
+# Security Analysis
+
+<!-- guide: Threat model of this change only. Reference security NFR rows by id;
+     do not restate them. No generic checklist. Remove guides before G3. -->
+
+## Scope
+
+## Assets
+
+## Trust Boundaries
+
+## Threats
+
+| ID | Threat (STRIDE) | Attack scenario | Asset / boundary | Existing control | Likelihood / impact |
+| --- | --- | --- | --- | --- | --- |
+
+## Recommended Mitigations
+
+| Threat | Mitigation | Owner artifact (specs / system-analysis / design) |
+| --- | --- | --- |
+
+## Residual Risks
+
+## Validation Requirements
+
+<!-- guide: Evidence needed before G4: review focus, negative tests, tooling. -->
@@ -0,0 +1,18 @@
+<!--
+Choose only the sections this delta needs; delete this guide before approval.
+
+New capability only: add `## Purpose` with 1–2 sentences (50+ characters).
+Existing capability: do not add Purpose.
+
+Supported operations:
+- `## ADDED Requirements`: new complete Requirement blocks.
+- `## MODIFIED Requirements`: full existing Requirement blocks with every
+  surviving Scenario, then edited behavior; heading matches exactly.
+- `## REMOVED Requirements`: Requirement heading plus **Reason** and **Migration**.
+- `## RENAMED Requirements`: `FROM:` and `TO:` heading pairs only.
+
+Every normative Requirement uses BCP 14 (RFC 2119 + RFC 8174) uppercase
+SHALL/MUST deliberately, and at least one `#### Scenario:` with `- **WHEN**`
+and `- **THEN**`. Lowercase must/should/may are ordinary language.
+Do not leave empty operation sections or a sample Requirement.
+-->
@@ -0,0 +1,50 @@
+# System Analysis
+
+<!-- guide: Hub document. Owns context, boundaries, flows overview and contract
+     semantics; details live in selected modules and are referenced, not copied.
+     Remove guides before G3. -->
+
+## Requirement Coverage
+
+| Requirement | Flow / contract | Module |
+| --- | --- | --- |
+
+## System Context and Boundaries
+
+## As-Is / To-Be
+
+## Impact Analysis
+
+## Systems and Responsibilities
+
+## Data Ownership
+
+| Data | Source of truth | Writers | Readers |
+| --- | --- | --- | --- |
+
+## Interaction Flows
+
+<!-- guide: Reference diagrams/*.mmd; text only for what a diagram cannot carry. -->
+
+## Contracts
+
+<!-- guide: Per contract: producer/consumer, operation/event, version, file in
+     contracts/, compatibility class (additive / breaking), published source it
+     must match after implementation. -->
+
+| Contract | Producer → Consumer | File | Compatibility | Published source |
+| --- | --- | --- | --- | --- |
+
+## Error Semantics
+
+<!-- guide: Business vs technical failures at boundaries. Detailed retry/
+     idempotency/recovery belongs to failure-model.md when selected. -->
+
+## Compatibility / Migration
+
+## Detailed Modules
+
+<!-- guide: Link each selected module (data-mapping, failure-model, nfr,
+     observability) with one line on what it decides. -->
+
+## Open Questions
@@ -0,0 +1,18 @@
+# Tasks
+
+<!-- guide: Task line format:
+- [ ] X.Y [main|frontend|backend|docs|specs] <Kind>: <action + outcome>
+  - **Covers:** `capability` — `Requirement heading` pairs, or `N/A` — <reason>
+  - **Source:** exact upstream artifact section / contract / docs-impact entry
+  - **Verification:** owner-controlled command, observable check or artifact
+  - **Depends on:** task ids or none
+Kinds: Implementation, Migration, Automated Testing, Contract Parity, Docs,
+Independent Review, QA Verification, Verification. Remove guides before G3. -->
+
+## 1. <!-- guide: delivery phase -->
+
+## Docs Impact
+
+<!-- guide: Only when docs-impact is not selected: list docs/ targets with
+     resulting AS-IS, or one concrete no-change reason. Delete when docs-impact.md
+     exists. -->
@@ -0,0 +1,16 @@
+# Test Cases — <!-- guide: area -->
+
+<!-- guide: One file per area under test-cases/. A case adds concrete data, steps
+     or an oracle that the scenario does not already state; otherwise reference the
+     scenario from qa-analysis instead of writing a case. Remove guides. -->
+
+### TC-<!-- guide: AREA-NNN --> <!-- guide: title -->
+
+- **Verifies:** `capability` — `Requirement heading` / Scenario
+- **Risk / Priority:**
+- **Preconditions:**
+- **Test Data:**
+- **Steps:**
+  1.
+- **Expected Results:**
+- **Automation Candidate:** <!-- guide: yes (level) | no (reason) -->
@@ -0,0 +1,40 @@
+# UX Design
+
+<!-- guide: Interaction design of observable behavior from Delta Specs. Reference
+     requirements as `capability` — `Requirement heading`; do not restate them.
+     No server architecture, contracts or component/state-management choices.
+     Remove guides before G3. -->
+
+## User Goals
+
+## User Flows
+
+<!-- guide: Mermaid flowchart or numbered steps per flow, with entry and exit points. -->
+
+## Information Architecture and Screen Structure
+
+## Interaction Behavior
+
+## UI States
+
+| Screen / region | Loading | Empty | Error | Success | Partial / stale |
+| --- | --- | --- | --- | --- | --- |
+
+## Validation Feedback
+
+## Responsive Behavior
+
+## Accessibility
+
+<!-- guide: Keyboard path, focus order, names/roles, contrast, non-color cues. -->
+
+## Design System Reuse
+
+## Materials
+
+<!-- guide: Inline Markdown by default; local files follow the Visual Package rule. -->
+
+| Material ID | Relative path / reference | Screen/state and purpose | SHA-256 |
+| --- | --- | --- | --- |
+
+## Open UX Questions