update

ASG_Framework.md

@@ -9,12 +9,12 @@ This document defines the documentation framework for a software project. It est
 | Document | Purpose | Primary Audience | Format / Content | Example (SaaS Context) | Measurement (KPI) |
 |----------|---------|-----------------|------------------|------------------------|-------------------|
 | **Requirements** | Capture the **business intent** — why we're building this and what success looks like. Defines boundaries and user-visible outcomes. | Stakeholders, Product Owners, Lead Developers | User stories, PRDs, acceptance criteria, non-functional constraints. | "System must process tabular data from Julia to SvelteKit UI with <200ms latency for 5-member teams." | 95% of requests complete <200ms (synthetic monitoring). |
-| **Solution Design** | Translate requirements into an **viable solution** — how the system solves the user problem. Defines approach, components, and trade-offs before technical details. | Product Owners, Architects, Developers | Problem decomposition, solution approach, alternatives considered, high-level component diagram, decision rationale. | "Problem: Users need to compare wines. Solution: Build a comparison table with filtering, sorting, and visual comparison. Components: Data layer (Wine API), UI layer (Table component), Logic layer (Filter/Sort engine)." | 100% of user problems mapped to solution components before spec writing. |
+| **Solution Design** | Translate requirements into **a viable solution** — how the system solves the user problem. Defines approach, components, and trade-offs before technical details. | Product Owners, Architects, Developers | Problem decomposition, solution approach, decision rationale, high-level component diagram, alternatives considered. | "Problem: Users need to compare wines. Solution: Build a comparison table with filtering, sorting, and visual comparison. Components: Data layer (Wine API), UI layer (Table component), Logic layer (Filter/Sort engine)." | 0 solution components without a requirement ID reference. |
-| **Walkthrough** | The **end-to-end trace** — maps the entire system flow from startup to cycle completion. Provides a "big picture" view that validates solution design before technical specification is locked. | Product Owners, Architects, Developers | End-to-end user journey, sequence diagrams, state machine diagrams. Explicitly links to solution-design.md and requirements.md. | "User logs in → selects wine → edits details → saves → backend validates against spec → UI updates with error states." | 100% of user journeys traced across all layers before implementation starts. |
+| **Walkthrough** | The **end-to-end trace** — maps the entire system flow from startup to cycle completion for each participant. Provides a "big picture" view that validates solution design before technical specification is locked. | Product Owners, Architects, Developers, End Users | Per-participant sections, sequence diagrams, state machine diagrams. Explicitly links to `2-solution_design.md` and `1-requirements.md`. | "User logs in → selects wine → edits details → saves → backend validates against spec → UI updates with error states." | 100% of user journeys traced across all layers before implementation starts. |
-| **Specification** | The **technical contract** — precise rules for inputs, outputs, and data shape. Ensures consistency across dev and test. Maps technical implementation to both *what* (requirements) and *how* (solution design). | Developers, QA Engineers, CI/CD pipelines | OpenAPI, Protobuf, AsyncAPI. Endpoint definitions, schemas, error codes. | `contract.yaml` defining a NATS subject (solution-design SD-3.1) that accepts Arrow streams with snake_case headers (requirements FR-001). | 100% of messages validated against spec (CI block rate). |
+| **Specification** | The **technical contract** — precise rules for inputs, outputs, and data shape. Ensures consistency across dev and test. Maps technical implementation to both *what* (requirements) and *how* (solution design). | Developers, QA Engineers, CI/CD pipelines | OpenAPI, Protobuf, AsyncAPI. Endpoint definitions, schemas, error codes. | `contract.yaml` defining a NATS subject (solution-design SD-001.1) that accepts Arrow streams with snake_case headers (requirements FR-001). | 100% of messages validated against spec (CI block rate). |
 | **UI Specification** | The **design contract** — precise rules for UI components, interactions, and visual patterns. Ensures consistency across design and implementation. | Product Designers, Frontend Developers, QA Engineers | Component libraries, style guides, interaction specs, design tokens. | Atomic design system with Figma tokens synced to CSS variables. | 100% of UI components match design spec (visual regression tests). |
 | **Validation** | The **enforcer** — defines tests before implementation begins to ensure spec compliance. Blocks drift and human error. | QA Engineers, Developers, Automation servers | Unit tests, integration tests, performance tests, penetration tests, contract tests, CI jobs, linting rules, schema validation. | CI job rejects PR with camelCase field not allowed by YAML spec. | <1% of PRs bypass validation gates. |
-| **Implementation Plan** | The **execution roadmap** — how implementation is organized, prioritized, and delivered. Maps code to validation tests and specification. | Developers, Project Managers, Lead Developers | Implementation plan, module breakdown, task list, delivery timeline, test strategy. | Phase 1: Core API + data layer; Phase 2: UI components; Phase 3: Integration tests + E2E validation. | 100% of validation tests covered by implementation tasks, <10% timeline drift. |
+| **Implementation Plan** | The **execution roadmap** — how implementation is organized, prioritized, and delivered. Maps code to validation tests and specification. | Developers, Project Managers, Lead Developers | Implementation plan, module breakdown, task list, delivery timeline, test strategy. | Phase 1: Core API + data layer; Phase 2: UI components; Phase 3: Integration tests + E2E validation. | 100% of validation tests covered by implementation tasks. |
 | **Runbook** | The **operational manual** — how the system lives in production, scales, and recovers. Guides on-call engineers. | DevOps, SREs, On-call Developers | K8s manifests, Helm charts, Markdown guides. Deployment, scaling, backup/restore, troubleshooting. | GitOps manifest ensuring 6 Julia replicas restart if memory >80%. | MTTR <15 minutes for P1 incidents. |
 
 ---
@@ -22,7 +22,7 @@ This document defines the documentation framework for a software project. It est
 ## Detailed Document Descriptions
 
 ### 1. Requirements 
-`requirements.md`
+`1-requirements.md`
 
 **Purpose**: Capture the *business intent* — why we're building this and what success looks like. Defines boundaries and user-visible outcomes.
 
@@ -42,7 +42,7 @@ This document defines the documentation framework for a software project. It est
 - Boundary definitions that state what is in scope and out of scope.
 - Security requirements including threat model outcomes, authentication and authorization expectations, data classification, encryption requirements, and compliance controls.
 - Observability requirements specifying required telemetry, metrics, traces, logs, alerting thresholds, and retention policies.
-- Traceability Rule: Requirements must be self-contained (no cross-references to other docs as justification), but must include IDs (e.g., FR-001) so downstream artifacts (spec, UI spec, architecture) can trace back. All downstream documents MUST cite requirement IDs, but requirements themselves stand alone.
+- Traceability Rule: Requirements must be self-contained (no cross-references to other docs as justification), but must include IDs (e.g., FR-001) so downstream artifacts (spec, UI spec, architecture) can trace back. All downstream documents MUST cite requirement IDs, but requirements themselves stand alone. Walkthrough steps (WT-XXX) may also cite requirement IDs directly.
 
 **Best Practices**:
 - **Link each requirement to a measurable KPI** — functional requirements should have explicit KPIs; non-functional requirements should have measurable thresholds
@@ -53,9 +53,9 @@ This document defines the documentation framework for a software project. It est
 ---
 
 ### 2. Solution Design
-`solution-design.md`
+`2-solution_design.md`
 
-**Purpose**: Translate requirements into an *viable solution* — how the system solves the user problem. Defines approach, components, and trade-offs before technical details.
+**Purpose**: Translate requirements into **a viable solution** — how the system solves the user problem. Defines approach, components, and trade-offs before technical details.
 
 **Why It Matters**:
 - Prevents technical-first thinking that skips design decisions
@@ -66,10 +66,10 @@ This document defines the documentation framework for a software project. It est
 
 **Content Guidelines**:
 - Problem decomposition: Break down the user problem into smaller, solvable pieces
-- Solution approach: Describe the high-level approach (e.g., "Use event sourcing for audit trail", "Implement caching layer for performance")
+- Solution approach: Introduce the solution the way Steve Jobs introduced the iPhone — present what you're delivering to the user first, then explain how it solves their problem. The narrative starts with the product, not the technical components. (e.g., "We're building a comparison table that lets users evaluate wines side-by-side with instant filtering and sorting" — not "We'll use event sourcing with a caching layer")
-- Alternatives considered: Document at least 2-3 alternative approaches with rationale for why they were rejected
+- Decision rationale: Explain the design reasoning behind each major decision — why the solution was designed this way, and how each decision connects to form a cohesive approach that solves the user problem. (e.g., "We chose server-side rendering so shared comparisons are indexable by search engines, enabling retailers to distribute links without login walls")
 - High-level component diagram: Show major components and their relationships (not technical details, just the big picture)
-- Decision rationale: Explain why each major decision was made (e.g., "Chose NATS over Kafka for simpler ops", "Used server-side rendering for SEO")
+- Alternatives considered: Document at least 2-3 alternative approaches with rationale for why they were rejected
 - Risk assessment: Identify potential risks and how they will be mitigated
 - Traceability: Link each solution component to specific requirement ID(s) (e.g., FR-001, NFR-201) that it addresses
 - Decision IDs: Assign unique IDs to major decisions using the format `SD-XXX` (e.g., `SD-001` for "Use NATS for async messaging") to enable specification traceability
@@ -80,7 +80,7 @@ This document defines the documentation framework for a software project. It est
 - Use diagrams that are easy to update (Mermaid.js)
 - Document trade-off decisions explicitly
 - Review solution design against requirements to verify completeness
-- Get sign-off from product, architecture, and engineering before creating walkthroughs
+- Create walkthroughs to validate the solution design end-to-end; sign-off from product, architecture, and engineering happens after walkthroughs confirm the approach works
 
 **Gap-Check Question**: Does the Solution Design clearly explain how the system solves the user problem, not just what it does?
 
@@ -89,57 +89,53 @@ This document defines the documentation framework for a software project. It est
 ---
 
 ### 3. Walkthrough
-`walkthrough.md`
+`3-walkthrough.md` (single file with per-participant sections)
 
-**Purpose**: The *end-to-end trace* — maps the entire system flow from startup to cycle completion, incorporating both internal logic and external interactions. Provides a "big picture" view that aligns users and developers, validating the solution design before technical specification is locked.
+**Primary Audience**: Product Owners, Architects, Developers, End Users
 
-**Unified Lifecycle Review**
+**Purpose**: The *end-to-end trace* — each section maps one system participant's complete journey from their own POV, from session start to task completion. Provides a "big picture" view that validates solution design before technical specification is locked. Each section is standalone: described entirely from that participant's perspective, with cross-references to other participants' sections where their workflows intersect.
-The walkthrough functions as a collaborative audit, mapping the proposed solution directly onto your workflow to ensure a shared "single source of truth." It synchronizes the user's operational needs with the developer's technical implementation.
 
-**For the User: Validating Operational Utility**
+**Per-Participant Walkthroughs**
-- **Visual Fidelity**: Concrete demonstration of the UI and user-facing components
+The walkthrough is organized as one document with a dedicated section per system participant, each tracing the complete journey from that participant's perspective.
-- **Workflow Integration**: Clear mapping of how the tool fits into existing day-to-day operations
+- Traces the complete flow from that participant's login/session start to task completion and logout
-- **Operational Control**: Practical exposure to system controls and interaction patterns
+- Explicitly references steps where other participants' actions are triggered (e.g., "Customer places order → see Retailer section step 4.2")
-- **Outcome Verification**: Direct observation of the system's outputs and deliverables
+- Shows error paths, edge cases, and recovery from that participant's perspective
-- **Impact Assessment**: Data-driven evaluation of the solution's ROI and efficiency gains
+- Uses sequence diagrams to illustrate interactions across participants
-- **Expectation Alignment**: Early discovery of discrepancies between intended functionality and actual experience
-
-**For the Developer: Aligning Architecture with Reality**
-- **Requirement Validation**: Confirming the solution satisfies core business objectives
-- **Impact Analysis**: Assessing the solution's real-world behavioral performance
-- **Knowledge Synthesis**: Identifying disconnects between domain intent and technical interpretation
-- **Specification Refinement**: Spotting missing technical dependencies or edge cases
-- **System Harmony**: Observing how the technical workflow and the user process interleave
-- **Code-to-Process Mapping**: Refining abstraction layers to better reflect the user's actual sequence of events
 
 **Why It Matters**:
-- Serves as a single source of truth for system behavior, bridging user experience and technical implementation
+- Each section is written entirely from one participant's POV — what they see, do, and achieve
+- Each participant sees their complete end-to-end journey in a standalone walkthrough section
+- Participants understand how their actions trigger or depend on other participants' workflows
 - Validates that all components (UI, API, backend logic) work together cohesively before implementation begins
-- Exposes solution design gaps and integration risks early in the design phase
+- Exposes solution design gaps and integration risks between participant workflows early in the design phase
-- Aligns stakeholders (product, design, development) on the complete user journey
 - Provides a reference for verifying implementation against intended behavior and for tracing requirements through to architecture
 
 **Content Guidelines**:
-- End-to-end user journey from system startup to task completion
+- One section per system participant, starting from their login/session start to task completion
+- End-to-end flow: what the participant sees, does, and achieves at each step
+- Cross-references to other participants' sections where workflows intersect (e.g., "Customer order placed → see Retailer section step 4.2")
 - External interactions (user actions, API calls, third-party integrations)
-- Internal flow (state transitions, business logic, data transformations)
+- Internal flow (state transitions, business logic, data transformations) triggered by the participant's actions
-- Error paths and edge cases with their handling
+- Error paths and edge cases specific to that participant's journey
-- Sequence diagrams showing request/response patterns across all layers
+- Sequence diagrams showing request/response patterns across participants for complex multi-user flows
-- State machine diagrams for complex workflows
+- State machine diagrams for workflows that span multiple participants
-- Each major walkthrough step must cite the exact **Solution Design decision ID(s)** (e.g., SD-001, SD-002) from `solution-design.md` and/or **Requirement ID(s)** from `requirements.md` that it implements or depends on.
+- Each major walkthrough step must cite the exact **Solution Design decision ID(s)** (e.g., SD-001, SD-002) from `2-solution_design.md` and/or **Requirement ID(s)** from `1-requirements.md` that it implements or depends on.
+- Assign a unique ID to each walkthrough step using the format `WT-XXX` (e.g., `WT-001` for Participant A login, `WT-002` for Participant B order placement) to enable downstream traceability
 
 **Best Practices**:
-- Write walkthroughs from the user's perspective first, then trace the technical implementation
+- Write each section from one participant's perspective, then cross-reference other participants' sections
-- Include concrete examples with realistic data values
+- Include concrete examples with realistic data values for each participant's typical usage
-- Link each step to its corresponding Solution Design decision (SD-XXX IDs) and requirement IDs
+- Link each step to its corresponding Solution Design decision (SD-XXX.Y IDs), Requirement ID(s), and Walkthrough ID (WT-XXX)
-- Document failure modes and recovery paths
+- Map cross-participant interactions explicitly (e.g., "Customer action X → Retailer notification Y")
-- Keep walkthroughs updated as requirements evolve
+- Document failure modes and recovery paths from each participant's perspective
-- Review walkthroughs against the solution design to verify completeness
+- Keep walkthroughs updated as requirements and participant roles evolve
+- Review walkthroughs against the solution design to verify completeness across all participants
 
 ---
 
 ### 4. Specification
-`specification.md`
+`4-specification.md`
+
 **Purpose**: The *technical contract* — precise rules for inputs, outputs, and data shape. Ensures consistency across dev and test. Maps technical implementation to both *what* (requirements) and *how* (solution design).
 
 **Why It Matters**:
@@ -155,10 +151,11 @@ The walkthrough functions as a collaborative audit, mapping the proposed solutio
 - Error codes and their meanings
 - Data validation rules and constraints
 - Rate limiting and quota definitions
+- Assign a unique ID to each specification item using the format `SP-XXX` (e.g., `SP-001` for the Request schema, `SP-002` for POST endpoint) for downstream traceability
 - Each specification item must cite:
-  - **Requirement ID(s)** from requirements.md (e.g., FR-001, NFR-201) — defines *what* the system must do
+  - **Requirement ID(s)** from `1-requirements.md` (e.g., FR-001, NFR-201) — defines *what* the system must do
-  - **Solution Design reference(s)** from solution-design.md (e.g., SD-2.1, SD-3.3) — defines *how* and *why* this technical approach was chosen
+  - **Solution Design reference(s)** from `2-solution_design.md` (e.g., SD-001.1, SD-002.1) — defines *how* and *why* this technical approach was chosen
-  - Link each endpoint, schema, validation rule, error case, etc to the exact requirement(s) and solution design decision(s) it implements or satisfies.
+  - Link each endpoint, schema, validation rule, error case, etc to the exact requirement(s) and solution design it implements or satisfies.
 
 **Best Practices**:
 - Use formal specification languages (OpenAPI 3.0+, AsyncAPI)
@@ -170,7 +167,7 @@ The walkthrough functions as a collaborative audit, mapping the proposed solutio
 ---
 
 ### 5. UI Specification
-`ui-specification.md`
+`5-ui_specification.md`
 
 **Purpose**: The *design contract* — precise rules for UI components, interactions, and visual patterns. Ensures consistency across design and implementation.
 
@@ -188,7 +185,8 @@ The walkthrough functions as a collaborative audit, mapping the proposed solutio
 - Design tokens (CSS variables, Figma tokens)
 - Accessibility standards (WCAG compliance)
 - Responsive design breakpoints and layouts
-- Each UI specification artifact must cite the specific requirement ID(s) from requirements.md (for example FR-001, NFR-201) and/or the exact specification ID(s) or spec path(s) from specification.md that it implements or depends on.
+- Each UI specification artifact must cite the specific requirement ID(s) from `1-requirements.md` and/or the exact solution design decision ID(s) from `2-solution_design.md` that it implements or depends on
+- Assign a unique ID to each UI artifact using the format `UI-XXX` (e.g., `UI-001` for Login Form, `UI-002` for Wine Table) to enable downstream traceability
 
 **Best Practices**:
 - Use design systems with versioned component libraries
@@ -201,36 +199,67 @@ The walkthrough functions as a collaborative audit, mapping the proposed solutio
 ---
 
 ### 6. Validation
-`validation.md`
+`6-validation.md`
 
 **Purpose**: The *enforcer* — defines tests **before implementation begins** to ensure spec compliance. Blocks drift and human error.
 
-**Why It Matters**:
+Because implementation must satisfy specifications, Validation derives all test definitions from the preceding 5 documents:
-- Ensures tests are written before implementation, so code can be tested as it's built
-- Prevents breaking changes from reaching production
-- Catches specification violations early in the CI pipeline
-- Maintains data integrity and API consistency
-- Reduces manual QA effort through automation
-- Provides immediate feedback to developers during implementation
-- Validates performance NFRs (latency, throughput) against measurable KPIs before deployment
-- Validates security requirements through adversarial testing before production
 
-**Content Guidelines**:
+| Source Document | What Validation Tests |
-- **Unit tests** — atomic tests for each specification rule, data schema field, and UI component state (cites specification.md sections, ui-specification.md component specs)
+|-----------------|----------------------|
-- **Integration tests** — end-to-end flow validation covering workflows defined in walkthrough.md (cites specification.md endpoint chains, walkthrough.md journeys)
+| **1. Requirements** | NFR thresholds (latency, throughput), security constraints, observability checks |
-- **Performance tests** — load tests, stress tests, and benchmarking against NFR thresholds (cites requirements.md NFRs, solution-design.md performance decisions)
+| **2. Solution Design** | Architectural decisions, performance choices, risk mitigations |
-- **Penetration tests** — adversarial testing of security requirements and auth flows (cites requirements.md security NFRs, specification.md auth endpoints)
+| **3. Walkthrough** | End-to-end flows for each participant section, cross-participant interactions |
-- Contract testing scripts (mapped to specification.md sections)
+| **4. Specification** | API contracts, data schemas, error codes, validation rules |
-- Linting rules and configurations (enforcing style guides from ui-specification.md)
+| **5. UI Specification** | Component states, visual patterns, accessibility compliance |
-- Schema validation jobs (validating data shapes from specification.md)
+
-- Visual regression tests (verifying UI matches ui-specification.md)
+Every specification rule, walkthrough journey, and NFR threshold must have a corresponding test — each spec item carries an `SP-XXX` ID, every walkthrough step carries a `WT-XXX` ID, and every UI artifact carries a `UI-XXX` ID. Tests are written before code so implementation can be validated as it's built. If a spec rule, walkthrough journey, NFR threshold, or UI state has no corresponding test, the Validation doc is incomplete.
-- Security scanning and audit jobs (SAST, dependency vulnerability checks)
+
-- CI/CD pipeline configurations for automated test execution
+**Test Types**
-- Each validation test must include explicit references to:
+
-  - **specification.md** (exact spec IDs or paths — API contracts, data schemas, e.g., sections 3.1, 4.2) — technical rules being tested
+Each validation test must include explicit references to its source document:
-  - **ui-specification.md** (components, interactions, visual states, e.g., sections 15.1, 15.3) — UI contract being verified
+
-  - **requirements.md** (e.g., FR-001, NFR-101, NFR-201) — business intent and NFR thresholds being validated
+| Test Type | Source | Example Reference |
-  - **solution-design.md** (e.g., SD-2.1, SD-3.3) — architectural decisions being tested
+|-----------|--------|-------------------|
+| **Unit tests** | `4-specification.md`, `5-ui_specification.md` | `4-specification.md:3.2.1` rejects camelCase headers; `5-ui_specification.md:## Wine Table` sort states |
+| **Integration tests** | `3-walkthrough.md`, `4-specification.md` | `WT-001` Participant A login → endpoint chain in `4-specification.md`; `SP-002` |
+| **Performance tests** | `1-requirements.md` NFRs, `2-solution_design.md` | `NFR-101` latency threshold; `SD-002` WebSocket performance decision |
+| **Penetration tests** | `1-requirements.md` security NFRs, `4-specification.md` auth endpoints | `NFR-301` authentication; `4-specification.md:auth/login` endpoint |
+| **Contract tests** | `4-specification.md` sections | Mapped to endpoint definitions and schema constraints |
+| **Linting rules** | `5-ui_specification.md` style guides | Enforcing design tokens from `5-ui_specification.md` |
+| **Schema validation** | `4-specification.md` data schemas | Validating Arrow stream headers (snake_case), JSON payloads |
+| **Visual regression** | `5-ui_specification.md` component states | Verifying hover, disabled, error states match spec |
+| **Security scanning** | `1-requirements.md`, `4-specification.md` | SAST, dependency vulnerability checks, OWASP rules |
+| **CI/CD pipeline** | All test types above | Automated execution on every commit and PR |
+
+**Specification-to-Test Execution Trace**
+
+Every traceable item — specification rules (SP-XXX), walkthrough journeys (WT-XXX), UI artifacts (UI-XXX), NFR thresholds, and SD decisions — must have a runnable, verifiable test. This trace maps each item to its corresponding test file, test function, and CI gate — proving that every requirement was tested, not just claimed.
+
+**Trace Format**:
+
+| Requirement/Spec ID | Participant | Source Path | Unit Test File | Unit Test Function | Additional Test File(s) | CI Gate | Status |
+|---------------------|-------------|-------------|----------------|-------------------|------------------------|---------|--------|
+| SP-001 | — | `4-specification.md#/components/schemas/Request` | `tests/unit/schema-validation.test.ts` | `test_rejects_camelCase_headers` | — | `ci/contract-validation.yaml` | Pass |
+| SP-002 | — | `4-specification.md#/paths/~1api~1v1~1endpoint` | `tests/unit/api-routes.test.ts` | `test_post_wine_returns_201` | `tests/integration/wine-flow.test.ts` | `ci/contract-validation.yaml` | Pass |
+| WT-001 | Customer | `3-walkthrough.md:#login` | `tests/integration/customer-login.test.ts` | `test_login_flow` | — | `ci/integration.yaml` | Pass |
+| WT-002 | Retailer | `3-walkthrough.md:#order` | `tests/integration/retailer-order.test.ts` | `test_order_placement` | — | `ci/integration.yaml` | Pass |
+| NFR-101 | — | `1-requirements.md:4.1` | — | — | `tests/performance/load.test.ts` | `ci/performance.yaml` | Pass |
+| SD-001 | — | `2-solution_design.md:5.1` | — | — | `tests/integration/nats-async.test.ts` | `ci/integration.yaml` | Pass |
+| UI-001 | — | `5-ui_specification.md## Wine Table` | `tests/unit/wine-table.test.tsx` | `test_sort_by_name` | `tests/visual/wine-table.spec.js` | `ci/visual-regression.yaml` | Pass |
+
+**Additional Test File(s)** column covers: unit tests (spec rules, UI states), integration tests (WT walkthrough flows), performance tests (NFR benchmarks), penetration tests (security NFRs), contract tests (endpoint/schema pairs), linting rules (design tokens), schema validation (data schemas), security scanning (SAST/dependency checks), and visual regression tests (UI component states).
+
+**Trace Rules**:
+- **Every** specification section with a concrete rule (endpoint, schema field, validation constraint, error code) must have at least one unit test and one contract test — each spec item carries an `SP-XXX` ID
+- **Every** walkthrough journey must have at least one integration test — each walkthrough step carries a `WT-XXX` ID
+- **Every** performance NFR must have at least one performance test (load/stress/benchmark)
+- **Every** security NFR must have at least one penetration test scenario and one security scanning test (SAST/dependency checks)
+- **Every** UI component state must have at least one unit test (behavior) and one visual regression test (appearance) — each UI artifact carries a `UI-XXX` ID
+- **Every** data schema must have at least one schema validation test
+- **Every** style guide token must have at least one linting rule
+- A test may cover multiple spec items, but each spec item must be covered by **at least one** test
+- Status is tracked via CI gate results (Pass/Fail/Skipped) — not manual checks
 
 **Best Practices**:
 - Define tests **before** writing implementation code
@@ -240,39 +269,11 @@ The walkthrough functions as a collaborative audit, mapping the proposed solutio
 - Maintain validation job health dashboard
 - Document validation failure remediation steps
 
----
-
-#### Specification-to-Test Execution Trace
-
-Every specification rule must have a runnable, verifiable test. This trace maps each spec item to its corresponding test file, test function, and CI gate — proving that every requirement was tested, not just claimed.
-
-**Trace Format**:
-
-| Requirement ID | Source Path | Unit Test File | Unit Test Function | Additional Test File(s) | CI Gate | Status |
-|----------------|-------------|----------------|-------------------|------------------------|---------|--------|
-| FR-001 | `specification.md:3.2.1` | `tests/unit/schema-validation.test.ts` | `test_rejects_camelCase_headers` | — | `ci/contract-validation.yaml` | Pass |
-| FR-002 | `specification.md:4.1` | `tests/unit/api-routes.test.ts` | `test_post_wine_returns_201` | `tests/integration/wine-flow.test.ts` | `ci/contract-validation.yaml` | Pass |
-| FR-003 | `specification.md:3.2.3` | — | — | `tests/integration/error-handling.test.ts` | `ci/contract-validation.yaml` | Pass |
-| NFR-101 | `requirements.md:4.1` | — | — | `tests/performance/load.test.ts` | `ci/performance.yaml` | Pass |
-| SD-001 | `solution-design.md:5.1` | — | — | `tests/integration/nats-async.test.ts` | `ci/integration.yaml` | Pass |
-| UI-15.3.2 | `ui-specification.md:15.3.2` | `tests/unit/wine-table.test.tsx` | `test_sort_by_name` | `tests/visual/wine-table.spec.js` | `ci/visual-regression.yaml` | Pass |
-
-**Additional Test File(s)** column covers: integration tests (walkthrough flows), performance tests (NFR benchmarks), penetration tests (security NFRs), and visual regression tests (UI component states).
-
-**Trace Rules**:
-- **Every** specification section with a concrete rule (endpoint, schema field, validation constraint, error code) must have at least one unit test
-- **Every** walkthrough journey must have at least one integration test
-- **Every** performance NFR must have at least one performance test (load/stress/benchmark)
-- **Every** security NFR must have at least one penetration test scenario
-- **Every** UI component state must have at least one unit test (behavior) and one visual regression test (appearance)
-- A test may cover multiple spec items, but each spec item must be covered by **at least one** test
-- Status is tracked via CI gate results (Pass/Fail/Skipped) — not manual checks
-
 **How to Maintain**:
-1. When writing a new spec rule, add a trace row **before** implementation
+1. When writing a new spec rule, assign an SP-XXX ID; when writing walkthrough steps assign WT-XXX; when defining UI artifacts assign UI-XXX; when creating implementation tasks assign IMP-XXX — then add trace rows **before** implementation
 2. When writing the test, fill in the test file and function
 3. CI gate auto-updates Status from pipeline results
-4. Gap-Check step 6 (Validation Review) verifies 100% row coverage — no spec rule without a test
+4. **Gap-Check Step 5** (Validation Review) verifies 100% row coverage — no traceable item without a test
 
 **Tooling** (optional):
 - Use YAML or JSON files (e.g., `validation/test-trace.yaml`) as machine-readable trace data
@@ -283,7 +284,7 @@ Every specification rule must have a runnable, verifiable test. This trace maps
 ---
 
 ### 7. Implementation Plan
-`implementation-plan.md`
+`7-implementation-plan.md`
 
 **Why It Matters**:
 - Converts specification into executable code with clear ownership and timeline
@@ -294,14 +295,14 @@ Every specification rule must have a runnable, verifiable test. This trace maps
 **Content Guidelines**:
 - Implementation phases and timeline (e.g., Phase 1: Core API + data layer; Phase 2: UI components; Phase 3: Integration tests + E2E validation)
 - Module/component breakdown with responsibilities and dependencies
-- Task list with assignees, priorities, and estimated effort
+- Task list with assignees, priorities, estimated effort — assign unique task IDs using the format `IMP-XXX` (e.g., `IMP-001` for Core API implementation)
-- Test coverage: which validation tests each implementation task satisfies
+- Test coverage: which validation tests each IMP-XXX task satisfies
 - Build and deployment preparation (CI/CD setup, environment configuration)
 - Risk mitigation: known blockers and mitigation steps
 
 **Best Practices**:
-- Break implementation into small, testable increments (1-3 day sprints)
+- Break implementation into small, testable increments (1-3 day task units)
-- Map each implementation task to specific validation tests (not just specification sections)
+- Assign an `IMP-XXX` ID to each implementation task and map it to specific validation tests it satisfies
 - Define clear ownership for each module or component
 - Include test coverage targets for each phase
 - Document dependencies between modules to avoid blocking work
@@ -310,7 +311,7 @@ Every specification rule must have a runnable, verifiable test. This trace maps
 ---
 
 ### 8. Runbook
-`runbook.md`
+`8-runbook.md`
 
 **Purpose**: The *operational manual* — how the system lives in production, scales, and recovers. Guides on-call engineers.
 
@@ -327,8 +328,8 @@ Every specification rule must have a runnable, verifiable test. This trace maps
 - Troubleshooting guides for common issues
 - Runbook entries for specific error codes
 - Contact information and escalation paths
-- Explicit references to [`specification.md`](specification.md) (API contracts, data schemas, specific endpoint sections)
+- Explicit references to [`4-specification.md`](4-specification.md) (API contracts, data schemas, specific endpoint sections)
-- Explicit references to [`ui-specification.md`](ui-specification.md) (components, interactions, visual states, specific component sections)
+- Explicit references to [`5-ui_specification.md`](5-ui_specification.md) (components, interactions, visual states, specific component sections)
 
 **Best Practices**:
 - Write runbooks for every P1/P2 incident
@@ -352,15 +353,15 @@ Before writing any code or documentation, establish clear requirements. Ask:
 
 ### 2. Define Solution Design
 
-Once requirements are stable, translate them into an viable solution. This ensures the technical approach solves the user problem, not just requirements.
+Once requirements are stable, translate them into a viable solution. This ensures the technical approach solves the user problem, not just requirements.
 
-**Action**: Create `docs/solution-design/` with `solution-design.md`, problem decomposition, alternatives considered, high-level component diagram, and decision rationale.
+**Action**: Create `docs/solution-design/` with `2-solution_design.md`, problem decomposition, solution approach, decision rationale, high-level component diagram, and alternatives considered.
 
 ### 3. Create Walkthroughs Early
 
-As soon as the solution design is defined, create walkthroughs. This helps identify gaps in the flow and provides onboarding material. The walkthrough should be a single source of truth that explicitly links to solution-design.md (SD-XXX IDs) and requirements.md.
+As soon as the solution design is defined, create walkthroughs — one document with a section per system participant. This helps identify gaps in each participant's flow and provides onboarding material. Each section traces the complete journey from that participant's perspective and cross-references other participants' workflows. The walkthrough should explicitly link to `2-solution_design.md` (SD-XXX.Y IDs) and `1-requirements.md`.
 
-**Action**: Create `docs/walkthrough/` with `TOUR.md`, sequence diagrams, and cross-references to solution design decisions and requirements.
+**Action**: Create `docs/walkthrough/` with `3-walkthrough.md` containing one section per participant (e.g., Customer, Retailer, Admin), sequence diagrams, and cross-references to `2-solution_design.md` (SD-XXX.Y IDs) and `1-requirements.md`.
 
 ### 4. Define the Specification
 
@@ -368,25 +369,25 @@ With walkthrough in place, define the technical specification. This becomes the
 - **Requirements** (WHAT - business intent)
 - **Solution Design** (HOW/WHY - architectural decisions)
 
-**Action**: Create `docs/specification/` with `contract.yaml` (or appropriate format), `error-codes.md`, and traceability mappings to requirements.md, solution-design.md, and walkthrough.md.
+**Action**: Create `docs/specification/` with `contract.yaml` (or appropriate format), `error-codes.md`, and traceability mappings to `1-requirements.md`, `2-solution_design.md`, and `3-walkthrough.md`. Each specification item must have an `SP-XXX` ID.
 
 ### 5. Define UI Specification Early
 
 Create UI specifications before implementing frontend components. This ensures design consistency and provides a contract for implementation.
 
-**Action**: Create `docs/ui-specification/` with `component-library.md`, `style-guide.md`, and `design-tokens.json`.
+**Action**: Create `docs/ui-specification/` with `component-library.md`, `style-guide.md`, and `design-tokens.json`. Each UI artifact must have a `UI-XXX` ID.
 
 ### 6. Define Validation Tests Before Implementation
 
-Write validation tests **before** implementation begins. This ensures every specification rule and UI state has a corresponding test that defines success. Tests should reference specification.md, ui-specification.md, requirements.md (NFR thresholds), and solution-design.md (performance decisions). Create a specification-to-test execution trace that maps every spec item to its test file, test function, and CI gate.
+Write validation tests **before** implementation begins. This ensures every specification rule (SP-XXX), walkthrough journey (WT-XXX), UI state (UI-XXX), and NFR threshold has a corresponding test that defines success. Tests should reference `4-specification.md`, `5-ui_specification.md`, `3-walkthrough.md`, `1-requirements.md` (NFR thresholds), and `2-solution_design.md` (performance decisions). Create a specification-to-test execution trace that maps every spec item to its test file, test function, and CI gate.
 
-**Action**: Create `docs/validation/` with `unit-tests/` (spec rules, schema fields, component states), `integration-tests/` (end-to-end flows from walkthrough.md), `performance-tests/` (NFR benchmarks: latency, TPS), `penetration-tests/` (security NFRs, auth flows), `contract-tests/`, `ci-pipeline.yaml`, `lint-rules/`, and `test-trace.yaml` (specification-to-test execution trace mapping every spec path to its test file, test function, and CI gate).
+**Action**: Create `docs/validation/` with `unit-tests/` (spec rules, schema fields, component states), `integration-tests/` (WT-XXX walkthrough flows), `performance-tests/` (NFR benchmarks: latency, TPS), `penetration-tests/` (security NFRs, auth flows), `contract-tests/`, `ci-pipeline.yaml`, `lint-rules/`, and `test-trace.yaml` (specification-to-test execution trace mapping every spec path to its test file, test function, and CI gate).
 
 ### 7. Create Implementation Plan
 
-With validation tests defined, create the implementation plan. Map each implementation task to specific validation tests that it must satisfy.
+With validation tests defined, create the implementation plan. Assign `IMP-XXX` IDs to each task and map them to the specific validation tests they must satisfy.
 
-**Action**: Create `docs/implementation-plan/` with phases, module breakdown, task list with assignees, and test coverage targets.
+**Action**: Create `docs/implementation-plan/` with `7-implementation-plan.md` containing phases, module breakdown, task list with assignees/priorities/effort (`IMP-XXX` IDs), and test coverage targets.
 
 ### 8. Document Operations from Day One
 
@@ -403,11 +404,11 @@ Since all docs defined in the ASG Framework are **living documents** that evolve
 | Stage Transition | Goal | Gap-Check Question | Example Gap | Result |
 |------------------|------|-------------------|-------------|--------|
 | **Requirements → Solution Design** | Turn a "Wish" into a "Solution" | Does the Solution Design clearly explain how the system solves the user problem, not just what it does? | Requirements say "users can compare wines", but solution design only mentions "wine comparison API" without explaining how users will actually use the comparison feature | Add UI flow and user interaction patterns to the solution design |
-| **Solution Design → Walkthrough** | Turn a "Solution" into a "Story" | Does the Walkthrough trace the complete flow the Solution Design describes, including all SD-XXX decisions? | Solution design says "use NATS for async messaging", but Walkthrough doesn't trace the async flow or reference SD-001 | Add the async messaging flow with SD-001 reference to Walkthrough |
+| **Solution Design → Walkthrough** | Turn a "Solution" into a "Story" | Does every SD-XXX decision appear in at least one participant's walkthrough section? Is there a WT-XXX ID for every walkthrough step? Is there a section for each system participant? | Solution design defines SD-001 (NATS async messaging), but no participant section traces the async flow | Add an async messaging flow to Participant B section with SD-001 reference and WT-003 ID |
-| **Walkthrough → Specification** | Turn the "Story" into "Rules" | Does the Specification cover all the behaviors defined in the Walkthrough? | Walkthrough shows 10 IoT sensors sending real-time updates, but Specification only defines REST API | Add NATS/MQTT protocol definitions to Specification |
+| **Walkthrough → Specification** | Turn the "Story" into "Rules" | Does every WT-XXX walkthrough step trace to at least one SP-XXX specification rule? | Walkthrough defines 20 WT-XXX steps across 3 participants, but only 10 map to SP-XXX rules | Add SP-XXX rules for the 10 unlinked WT-XXX steps |
-| **Specification → UI Specification** | Turn a "Rule" into a "Button" | Does the UI Specification expose all the data and states defined in the Specification? | Specification says device must "Handshake" within 5 seconds, but UI Specification has no connection status indicator | Add a `Connection Status` component to UI Specification |
+| **Specification → UI Specification** | Turn a "Rule" into a "Button" | Does the UI Specification expose all data entities and states defined in the Specification? Are UI-XXX IDs assigned to every UI artifact? | Specification defines 15 API response schemas with 30 fields, but UI Specification only has 3 components (UI-001 through UI-003) | Add the remaining UI components for each data entity with UI-XXX IDs to match Specification coverage
 | **UI Specification → Validation** | Turn "Design" into "Tests" | Do the Validation tests cover all specification rules, UI states, performance NFRs, and security requirements? | UI Spec defines 15 component states but Validation only has 5 unit tests; NFR-101 latency threshold has no performance test | Add unit tests for all component states, performance benchmarks for NFR thresholds, and pen test scenarios for security NFRs |
-| **Validation → Implementation Plan** | Turn "Tests" into "Tasks" | Does the Implementation Plan satisfy all validation tests with clear ownership? | Validation defines 30 test cases but Implementation Plan only has tasks for 20 | Add implementation tasks for remaining test cases with assignees and timelines |
+| **Validation → Implementation Plan** | Turn "Tests" into "Tasks" | Does the Implementation Plan satisfy all validation tests with clear ownership? | Validation defines 30 test cases but Implementation Plan only has tasks for 20 | Verify every validation test maps to at least one implementation task with an assignee and timeline |
 
 ### Why Gap-Checks Matter
 
@@ -420,13 +421,14 @@ Since all docs defined in the ASG Framework are **living documents** that evolve
 
 1. **Requirements Review**: After writing requirements, ask "What happens if X?" for each user story
 2. **Solution Design Review**: After writing solution design, verify every requirement is addressed by at least one solution component with a corresponding requirement ID reference
-3. **Walkthrough Review**: After writing walkthrough, verify every SD-XXX decision and requirement is traced in the end-to-end flow with error paths included
+3. **Walkthrough Review**: After writing walkthrough, verify every SD-XXX.Y decision, requirement ID, and WT-XXX walkthrough step is traced in every participant section with error paths included, and that each system participant has a dedicated section
 4. **Specification Review**: After writing the spec, verify every spec item has:
-   - At least one requirement ID reference (WHAT)
+    - An `SP-XXX` ID assigned for downstream traceability
-   - At least one solution design reference (HOW/WHY)
+    - At least one requirement ID reference (WHAT)
-   - Coverage for all behaviors defined in the Walkthrough
+    - At least one solution design reference (HOW/WHY)
-5. **UI Specification Review**: After writing UI Specification, verify every spec rule has at least one UI representation with a corresponding requirement ID reference
+    - Coverage for all behaviors defined in each participant section
-6. **Validation Review**: After writing Validation, verify every specification section and UI state has at least one corresponding unit/integration test case; every performance NFR has a benchmark test; every security NFR has a penetration test scenario — each with explicit references to specification.md, ui-specification.md, and/or requirements.md
+5. **UI Specification Review**: After writing UI Specification, verify every `UI-XXX` artifact has a corresponding requirement ID, solution design reference, and specification ID
+6. **Validation Review**: After writing Validation, verify every specification section and UI state has at least one corresponding test case — unit tests for SP-XXX spec rules and UI-XXX UI states, integration tests for WT-XXX walkthrough flows, performance tests for NFR thresholds, penetration test scenarios for security NFRs, contract tests for SP-XXX endpoint/schema definitions, linting rule coverage for `5-ui_specification.md` style guides, schema validation for all data schemas, and security scanning for all security NFRs — each with explicit references to `4-specification.md`, `5-ui_specification.md`, `3-walkthrough.md`, and/or `1-requirements.md`
 7. **Implementation Plan Review**: After writing the plan, verify every validation test is covered by at least one implementation task with an assignee and timeline
 
 ---
@@ -438,11 +440,11 @@ This habit ensures that each documentation stage is complete and validated befor
 | Stage | Debug Checklist | Why It Matters |
 |-------|-----------------|----------------|
 | **Requirements** | If I can't state the Value, I'm building a feature nobody needs. | Clarifies the business impact before technical discussion begins |
-| **Solution Design** | If I can't Imagine the solution, I'm building without a compass. | Ensures the technical approach solves the user problem before spec writing |
+| **Solution Design** | If I can't see the Solution, I'm building without a compass. | Ensures the technical approach solves the user problem before spec writing |
-| **Walkthrough** | If I can't Trace the full flow, the system has a 'broken bridge'. | Identifies gaps between components and validates the solution design end-to-end |
+| **Walkthrough** | If I can't Trace every participant's flow with **WT-XXX** IDs, the system has broken bridges. | Identifies gaps between components and validates the solution design end-to-end for each system participant |
-| **Specification** | If I can't write a Rule with a requirement ID reference AND/OR solution design reference, I haven't thought the logic through. | Ensures traceability from technical rules to both business requirements (*what*) and architectural decisions (*how/why*) |
+| **Specification** | If I can't write a Rule with a requirement and solution design reference, I haven't thought the logic through. | Ensures traceability from technical rules to both business requirements (*what*) and architectural decisions (*how/why*) |
-| **UI Specification** | If I can't See it with a requirement ID reference, the user has no way to trigger the logic. | Ensures traceability from UI elements to business requirements |
+| **UI Specification** | If I can't See it with a **UI-XXX** ID and traceability reference, the user has no way to trigger the logic. | Ensures traceability from UI elements to business requirements |
-| **Validation** | If I can't Write a Test for every spec rule, UI state, NFR threshold, and security requirement, implementation is untestable. | Ensures code can be tested from day one — unit, integration, performance, and pen tests define success before implementation begins |
+| **Validation** | If I can't Write a Test for every traceable item, implementation is untestable. | Ensures code can be tested from day one — unit, integration, performance, contract, and security tests define success before implementation begins |
 
 **How to Use This Habit:**
 
@@ -475,14 +477,26 @@ Each documentation artifact has associated KPIs. Track these to ensure quality:
 | Document | KPI | Target |
 |----------|-----|--------|
 | Requirements | Requirement coverage | 100% of features have associated requirements |
-| Solution Design | Solution completeness | 100% of user problems mapped to solution components before spec writing |
+| Solution Design | Solution completeness | 0 solution components without a requirement ID reference |
+| Walkthrough | Participant coverage | 100% of identified system participants have a walkthrough section |
 | Specification | Specification compliance rate | 100% of messages validate against spec |
 | UI Specification | UI spec compliance | 100% of components match design spec (visual regression tests) |
-| Walkthrough | New dev time-to-first-PR | <2 days from onboarding to first contribution |
-| Implementation | Test coverage | >80% unit test coverage |
 | Validation | Bypass rate | <1% of PRs bypass validation gates |
+| Implementation | Implementation coverage | 100% of validation tests mapped to at least one task |
 | Runbook | MTTR | <15 minutes for P1 incidents |
 
+### Delivery & Outcome Metrics
+
+The table above measures documentation adherence. This group measures the *actual system and how fast the team ships* — the axes doc-compliance never could. DORA is the delivery bundle; the Outcome row is the post-deploy business KPI (KPI-XXX) defined per requirement in `1-requirements.md`.
+
+| Category | KPI | Source |
+|----------|-----|--------|
+| Delivery (DORA) | Lead time for changes — median time from commit to production deploy | CI/CD pipeline |
+| Delivery (DORA) | Deployment frequency — deployments per unit time | CI/CD pipeline |
+| Delivery (DORA) | Change failure rate — % of deploys requiring rollback or fix | CI/CD pipeline |
+| Delivery (DORA) | MTTR — mean time to recover from a production incident | CI/CD pipeline (see Runbook MTTR KPI) |
+| Outcome | Post-deploy business KPI — whether a feature achieves its goal after release | `1-requirements.md` KPI-XXX |
+
 **Review Cadence**:
 - Weekly: Review KPI dashboards and documentation gaps
 - Monthly: Update documentation based on incident learnings
@@ -542,6 +556,26 @@ These rules serve as a binary decision framework:
 - **NFR-XXX**: [Deployment-specific requirement]
 - *Example: NFR-501 - System shall be deployed to MicroK8s cluster with relative URL support*
 
+### System Context (C4 Level 1)
+
+Show the system as a black box and the people and external systems around it. This diagram is the visual form of the In Scope / Out of Scope / Dependencies statements above: it fixes scope for sign-off and shows only what touches the system.
+
+```mermaid
+%% C4 Level 1 - System Context
+flowchart LR
+    roleC[Customer<br/>Retail shop user]
+    roleR[Retailer<br/>Catalog manager]
+    system[(sommpanion<br/>System)]
+    extDB[(Wine Data Service)]
+    extNats[NATS<br/>Messaging Broker]
+
+    roleC -->|views catalog, selects wines| system
+    roleR -->|manages wine catalog| system
+    system -->|reads master wine data| extDB
+    system -->|publishes catalog updates| extNats
+    extNats -->|pushes inventory notifications| roleR
+```
+
 ## 3. Functional Requirements (FR)
 
 ### FR-XXX: [Requirement Title]
@@ -590,19 +624,6 @@ These rules serve as a binary decision framework:
 - [ ] **NFR-XXX**: [Verifiable acceptance condition]
 - *Example: [ ] FR-001: Sommpanion landing page renders with all required elements*
 
-## 6. Requirements Traceability Matrix
-
-| Requirement ID | Description | Implementation File | Test File |
-|----------------|-------------|---------------------|-----------|
-| FR-XXX | [Brief description] | `path/to/file.ext` | `tests/file.spec.js` |
-| NFR-XXX | [Brief description] | `path/to/file.ext` | `tests/file.spec.js` |
-
-**Notes**:
-- Functional Requirements (FR) define what the system shall do
-- Non-Functional Requirements (NFR) define system qualities (performance, availability, security, etc.)
-- KPIs are measurable targets that validate whether requirements were met post-deployment
-- Each requirement must include a clear requirement ID for traceability
-- All acceptance conditions must be verifiable through testing or manual inspection
 ```
 
 ### Solution Design Template
@@ -632,7 +653,61 @@ Describe the high-level approach to solving the problem.
 - [e.g., "Use server-side rendering for SEO"]
 - [e.g., "Support unlimited wine comparisons for power users"]
 
-## 3. Alternatives Considered
+## 3. Decision Rationale
+
+Explain the design reasoning behind each major decision — why the solution was designed this way, and how each decision connects to form a cohesive approach that solves the user problem.
+
+| Decision ID | Decision | Rationale | Alternatives Rejected |
+|-------------|----------|-----------|----------------------|
+| Decision ID | Decision | Rationale | Alternatives Rejected |
+|-------------|----------|-----------|----------------------|
+| SD-001 | Use NATS for async messaging | Required for real-time messaging with low overhead | Kafka - too complex for current scale |
+| SD-001.1 | NATS subject naming | Use `catalog:updates` for inventory changes | Static polling |
+| SD-002 | Use WebSockets for real-time updates | Required for <100ms feedback | REST polling - too slow, too many requests |
+| SD-003 | Store comparison list in localStorage | Allows offline comparison editing | Redux - overkill for this feature |
+| SD-004 | Server-side rendering for comparison view | SEO for comparison pages shared via unique links | Client-side rendering - no SEO benefit |
+| SD-005 | Server-side PDF/CSV export | Generates downloadable exports with user data | Client-side export — requires user browser permissions |
+
+## 4. High-Level Component Diagram
+
+### C4 Level 1 - System Context
+
+The scope boundary for sign-off: the system as a black box plus the people and external systems it interacts with. Mirrors the walkthrough's System Context and the Requirements diagram; keep this one stable so downstream docs can reference it.
+
+```mermaid
+%% C4 Level 1 - System Context
+flowchart LR
+    roleC[Customer<br/>Retail shop user]
+    roleR[Retailer<br/>Catalog manager]
+    system[(sommpanion<br/>System)]
+    extDB[(Wine Data Service)]
+    extNats[NATS<br/>Messaging Broker]
+
+    roleC -->|views catalog, selects wines| system
+    roleR -->|manages wine catalog| system
+    system -->|reads master wine data| extDB
+    system -->|publishes catalog updates| extNats
+    extNats -->|pushes inventory notifications| roleR
+```
+
+### C4 Level 2 - Container
+
+The high-level tech stack and how the building blocks communicate. This is the architecture diagram the Solution Design's Decision Rationale (Section 3) explains — each container maps to a decision, and each decision maps back to a requirement.
+
+```mermaid
+%% C4 Level 2 - Container
+flowchart LR
+    user[Customer<br/>Browser SPA] -->|HTTPS| ssr[SvelteKit SSR API]
+    ssr -->|reads / writes| post[(PostgreSQL)]
+    ssr -->|publishes catalog:updates| nats[(NATS)]
+    nats -->|pushes updates| dash[Retailer Dashboard]
+```
+
+**Component Descriptions**:
+- **[Container Name]**: [Brief description of the container's responsibilities and how it solves part of the problem]
+  - Links to requirements: FR-001, NFR-201
+
+## 5. Alternatives Considered
 
 Document at least 2-3 alternative approaches with rationale.
 
@@ -642,32 +717,6 @@ Document at least 2-3 alternative approaches with rationale.
 | Server-side comparison | Centralized, scalable | Latency, complex state sync | Accepted - matches performance requirements |
 | Hybrid approach | Best of both worlds | Complex, hard to maintain | Rejected - over-engineering |
 
-## 4. High-Level Component Diagram
-
-```mermaid
-%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#3b82f6'}}}%%
-flowchart TD
-    A[User] --> B[Comparison UI]
-    B --> C[Comparison State]
-    B --> D[Wine API]
-    C --> D
-```
-
-**Component Descriptions**:
-- **[Component Name]**: [Brief description of responsibilities and how it solves part of the problem]
-  - Links to requirements: FR-001, NFR-201
-
-## 5. Decision Rationale
-
-Explain why each major decision was made.
-
-| Decision ID | Decision | Rationale | Alternatives Rejected |
-|-------------|----------|-----------|----------------------|
-| SD-001 | Use NATS for async messaging | Required for real-time messaging with low overhead | Kafka - too complex for current scale |
-| SD-002 | Use WebSockets for real-time updates | Required for <100ms feedback | REST polling - too slow, too many requests |
-| SD-003 | Store comparison list in localStorage | Allows offline comparison editing | Redux - overkill for this feature |
-| SD-004 | Server-side rendering for comparison export | SEO for shared comparisons | Client-side rendering - no SEO benefit |
-
 ## 6. Risk Assessment
 
 Identify potential risks and mitigation strategies.
@@ -685,12 +734,167 @@ Link each solution component to specific requirements and assign Solution Design
 | Solution Component | Requirement ID | Decision ID | Description |
 |-------------------|----------------|-------------|-------------|
 | Comparison table UI | FR-101 | SD-001 | Display wines in table format (uses NATS messaging) |
-| Filtering | FR-102 | SD-002 | Filter wines by criteria (uses WebSocket updates) |
+| Filtering | FR-102 | SD-003 | Filter wines by criteria (stored in localStorage) |
-| Sorting | FR-103 | SD-003 | Sort wines by any column (stored in localStorage) |
+| Sorting | FR-103 | SD-004 | Sort wines by any column (stored in localStorage) |
 | Real-time updates | NFR-201 | SD-002 | Updates appear within 100ms (uses WebSocket) |
-| Export comparison | FR-201 | SD-004 | Export comparison to PDF/CSV (uses server-side rendering) |
+| Export comparison | FR-201 | SD-005 | Export comparison to PDF/CSV (uses server-side rendering) |
 
 
+### Walkthrough Template
+
+```markdown
+# Walkthrough: Feature Name
+
+## Structural Guidance
+
+- One **overview sequence diagram** per participant (high-level flow, all major steps)
+- **Detailed sub-diagrams** for complex interaction points (e.g., multi-step checkout, validation error paths)
+- Use sequence diagrams for request/response patterns; use state machine diagrams for multi-participant state transitions
+
+---
+
+## Customer
+
+### Session Start
+
+**WT-001**: User opens app, navigates to `/compare`
+
+> Cross-reference: `2-solution_design.md:SD-004` (SSR for SEO-friendly comparison links)
+
+**Sequence**:
+```mermaid
+sequenceDiagram
+    participant User as Customer (Browser)
+    participant UI as SvelteKit SSR
+    participant WineAPI as Wine Service
+
+    User->>UI: GET /compare
+    UI->>WineAPI: Get wine list
+    WineAPI-->>UI: JSON response
+    UI-->>User: Rendered HTML
+```
+
+---
+
+### Select Wines for Comparison
+
+**WT-002**: User selects 3 wines from inventory table
+
+| Step | Action | System Response | Traceability |
+|------|--------|-----------------|--------------|
+| WT-002.1 | Clicks "Add to Compare" on Wine A | Adds to localStorage comparison array | FR-101, SD-003 |
+| WT-002.2 | Clicks "Add to Compare" on Wine B | Adds to array, updates sidebar count | FR-101, SD-003 |
+| WT-002.3 | Clicks "Add to Compare" on Wine C | Adds to array, triggers comparison preview | FR-101, SD-003 |
+
+**WT-003**: Comparison preview renders with selected wines
+
+> Cross-reference: `5-ui_specification.md:UI-002` (Wine Table)
+
+**Sequence**:
+```mermaid
+sequenceDiagram
+    participant User as Customer
+    participant UI as StateStore
+    participant Sidebar as ComparisonSidebar
+
+    User->>UI: addToCompare(wine)
+    UI->>Sidebar: emit 'comparison:updated'
+    Sidebar->>Sidebar: Render preview (3 wines)
+    Sidebar-->>User: Visual feedback
+```
+
+---
+
+### Edit Wine Details
+
+**WT-004**: User modifies price or notes for a selected wine
+
+> Cross-reference: `2-solution_design.md:SD-003` (localStorage storage)
+
+**WT-005**: User clicks "Save Changes"
+
+**Sequence**:
+```mermaid
+sequenceDiagram
+    participant User as Customer
+    participant UI as FormComponent
+    participant Local as localStorage
+    participant Backend as WineAPI
+
+    User->>UI: Edit form fields
+    UI->>Local: Update cached values
+    User->>UI: Click Save
+    UI->>Backend: PUT /api/v1/wine/:id
+    Backend-->>UI: 200 OK
+    UI-->>User: Confirmation toast
+```
+
+---
+
+### Error Paths
+
+**WT-006**: Backend rejects edit (validation error)
+
+> Same participant POV — shows rejection from customer's perspective
+
+```mermaid
+sequenceDiagram
+    participant User as Customer
+    participant UI as FormComponent
+    participant Backend as WineAPI
+
+    User->>UI: Click Save
+    UI->>Backend: PUT /api/v1/wine/:id
+    Backend-->>UI: 422 Unprocessable Entity
+    UI->>UI: Render field-level errors
+    UI-->>User: "Price must be numeric" inline message
+```
+
+**WT-007**: User clears comparison list
+
+> See Retailer section step 4.2 — retailer sees updated catalog
+
+```mermaid
+sequenceDiagram
+    participant User as Customer
+    participant UI as StateStore
+    participant Local as localStorage
+
+    User->>UI: Click "Clear All"
+    UI->>Local: Set comparison = []
+    Local-->>UI: Confirm write
+    UI-->>User: Sidebar collapses
+```
+
+---
+
+## Retailer
+
+### Receive Updated Catalog
+
+**WT-008**: Retailer views updated wine inventory
+
+> Cross-reference: `3-walkthrough.md:#Customer` (WT-005 save event triggers notification)
+
+**Sequence**:
+```mermaid
+sequenceDiagram
+    participant Retailer as Retailer Dashboard
+    participant Nats as NATS Bridge
+    participant Backend as WineService
+
+    Retailer->>Nats: Listen to catalog:updates
+    Backend-->>Nats: catalog:updated {wine_ids:[...]}
+    Nats-->>Retailer: Push notification
+    Retailer->>Retailer: Refresh inventory table
+```
+
+> Cross-reference: `2-solution_design.md:SD-001` (NATS async messaging)
+
+---
+
+```
+
 ### Specification Template
 
 ```yaml
@@ -716,7 +920,8 @@ paths:
               schema:
                 $ref: '#/components/schemas/Response'
       x-requirement-id: FR-001    # Reference to Requirements document (WHAT)
-      x-solution-design-ref: SD-3.1  # Reference to Solution Design decision (HOW/WHY)
+      x-solution-design-ref: SD-001.1  # Reference to Solution Design decision (HOW/WHY)
+      x-spec-id: SP-001           # Specification item ID for downstream traceability
 components:
   schemas:
     Request:
@@ -724,15 +929,32 @@ components:
       properties:
         data:
           type: string
-          x-requirement-id: FR-002    # Reference to Requirements document (WHAT)
+          x-requirement-id: FR-002
-          x-solution-design-ref: SD-3.2  # Reference to Solution Design decision (HOW/WHY)
+          x-solution-design-ref: SD-001.2
+          x-spec-id: SP-002
+        metadata:
+          type: object
+          properties:
+            timestamp:
+              type: string
+              format: date-time
+              x-requirement-id: FR-004
+              x-solution-design-ref: SD-001.3
+              x-spec-id: SP-004
     Response:
       type: object
       properties:
         status:
           type: string
-          x-requirement-id: FR-003    # Reference to Requirements document (WHAT)
+          x-requirement-id: FR-003
-          x-solution-design-ref: SD-3.1  # Reference to Solution Design decision (HOW/WHY)
+          x-solution-design-ref: SD-001.1
+          x-spec-id: SP-003
+        record_count:
+          type: integer
+          minimum: 0
+          x-requirement-id: FR-005
+          x-solution-design-ref: SD-001.4
+          x-spec-id: SP-005
 ```
 
 ### UI Specification Template
@@ -744,13 +966,14 @@ components:
 **Name**: [Component Name]
 **Status**: [Draft/Approved/Deprecated]
 **Version**: 1.0.0
+**UI-XXX**: [Unique UI spec ID assigned to this component]
 
 ## Requirements Traceability
-| UI Element | Requirement ID | Solution Design Ref | Description |
+| UI Element | UI Spec Ref | Requirement ID | Solution Design Ref | Description |
-|------------|----------------|---------------------|-------------|
+|------------|-------------|----------------|---------------------|-------------|
-| Login form | FR-001 | SD-2.1 | Username/password authentication |
+| Login form | UI-001 | FR-001 | SD-001.1 | Username/password authentication |
-| Sidebar menu | NFR-202 | Collapsible sidebar for usability |
+| Sidebar menu | UI-002 | FR-102 | SD-002.1 | Collapsible sidebar for navigation |
-| Wine table | FR-101 | Sortable, searchable inventory table |
+| Wine table | UI-003 | FR-101 | SD-003.1 | Sortable, searchable inventory table |
 
 ## Design Tokens
 - **Color**: `--color-primary`
@@ -758,12 +981,13 @@ components:
 - **Spacing**: `--spacing-md`
 
 ## Component States
-| State | Description | Example | Requirement ID |
+**UI-XXX**: [UI spec ID from the Component Overview]
-|-------|-------------|---------|----------------|
+| State | Description | Example | Requirement ID | UI Spec Ref |
-| Default | Normal state | `<Button />` | FR-001 |
+|-------|-------------|---------|----------------|-------------|
-| Hover | Mouse over | `<Button hover />` | NFR-201 |
+| Default | Normal state | `<Button />` | FR-001 | UI-001 |
-| Disabled | Disabled state | `<Button disabled />` | NFR-203 |
+| Hover | Mouse over | `<Button hover />` | FR-002 | UI-001 |
-| Error | Error state | `<Button error />` | EH-004 |
+| Disabled | Disabled state | `<Button disabled />` | FR-003 (disabled state) | UI-001 |
+| Error | Error state | `<Button error />` | FR-003 | UI-001 |
 
 ## Accessibility
 - [ ] WCAG 2.1 AA compliant
@@ -778,38 +1002,18 @@ components:
 ## References
 - Figma: [Link to design file]
 - Storybook: [Link to component story]
-- Requirements: [`docs/requirements.md`](../requirements.md)
+- Requirements: [`1-requirements.md`](../1-requirements.md)
 ```
 
-### Architecture Template
+### Specification Traceability Template
-
-```mermaid
-%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#3b82f6'}}}%%
-flowchart TD
-    A[Client] --> B[Caddy]
-    B --> C[Node.js API]
-    C --> D[Julia Worker]
-    D --> E[NATS Cluster]
-    E --> F[Storage]
-    
-    style A fill:#f9f9f9,stroke:#333
-    style E fill:#e0e7ff,stroke:#3b82f6
-```
 
 **Specification Traceability:**
-| Architecture Component | Solution Design Ref | Specification Section | UI Specification Section | Requirement ID |
+| Architecture Component | Solution Design Ref | Specification Section | Specification ID (SP) | UI Specification Section | UI Spec Ref (UI) | Requirement ID | Walkthrough Ref (WT) |
-|------------------------|---------------------|----------------------|--------------------------|----------------|
+|------------------------|---------------------|----------------------|----------------------|--------------------------|------------------|----------------|----------------------|
-| NATS Bridge (smartsend) | SD-3.1 | specification.md:3.1 | - | FR-301, NFR-201 |
+| NATS Bridge (smartsend) | SD-001.1 | `4-specification.md`:3.1 | SP-001 | - | - | FR-301, NFR-201 | WT-001 |
-| Login Form | SD-2.1 | specification.md:10.1 | ui-specification.md:15.2.1 | FR-001, NFR-201 |
+| Login Form | SD-002.1 | `4-specification.md`:10.1 | SP-002 | `5-ui_specification.md`:15.2.1 | UI-001 | FR-001, NFR-201 | WT-002 |
-| Wine Inventory Table | SD-2.2 | specification.md:4.2 | ui-specification.md:15.3.3 | FR-101, NFR-205 |
+| Wine Inventory Table | SD-002.2 | `4-specification.md`:4.2 | SP-003 | `5-ui_specification.md`:15.3.3 | UI-002 | FR-101, NFR-205 | WT-003 |
-| Sidebar Menu | SD-2.3 | specification.md:11.1 | ui-specification.md:15.3.2 | NFR-202 |
+| Sidebar Menu | SD-002.3 | `4-specification.md`:11.1 | SP-004 | `5-ui_specification.md`:15.3.2 | UI-003 | NFR-202 | WT-004 |
-
-**Component Details:**
-- **Caddy**: Static file serving (specification.md:2.2, ui-specification.md:15.1, solution-design.md:SD-1.1)
-- **Node.js API**: NATS bridge client (specification.md:3.1, solution-design.md:SD-3.1)
-- **Julia Worker**: Backend processing (specification.md:4.1, solution-design.md:SD-4.1)
-- **NATS Cluster**: Message bus (specification.md:3.3, solution-design.md:SD-3.3)
-- **Storage**: Data persistence (specification.md:5.1, solution-design.md:SD-5.1)
 
 ### Runbook Template
 
@@ -831,6 +1035,10 @@ flowchart TD
 ## Rollback
 - Run: `kubectl rollout undo deployment/natsbridge`
 
+## References
+- API contract: [`4-specification.md`](4-specification.md)
+- UI component states: [`5-ui_specification.md`](5-ui_specification.md)
+
 ## Post-Incident
 - [ ] Review logs for root cause
 - [ ] Update runbook if needed
@@ -838,6 +1046,28 @@ flowchart TD
 
 ---
 
+## Appendix: Requirements Traceability Matrix
+
+This matrix traces each requirement through all downstream artifacts. It is maintained as a living cross-reference document, not embedded inline in `1-requirements.md`.
+
+| Requirement ID | WT ID | SP ID | UI ID | IMP ID | Description | Implementation File | Test File |
+|----------------|-------|-------|-------|--------|-------------|---------------------|-----------|
+| FR-XXX | WT-XXX | SP-XXX | UI-XXX | IMP-XXX | [Brief description] | `path/to/file.ext` | `tests/file.spec.js` |
+| NFR-XXX | WT-XXX | SP-XXX | UI-XXX | IMP-XXX | [Brief description] | `path/to/file.ext` | `tests/file.spec.js` |
+
+**Notes**:
+- Functional Requirements (FR) define what the system shall do
+- Non-Functional Requirements (NFR) define system qualities (performance, availability, security, etc.)
+- **WT-XXX** IDs link requirements to walkthrough journey steps in `3-walkthrough.md`
+- **SP-XXX** IDs are assigned to each specification item in `4-specification.md` for downstream traceability (Validation, Implementation Plan)
+- **UI-XXX** IDs are assigned to each UI artifact in `5-ui_specification.md` for downstream traceability (Validation, Implementation Plan)
+- **IMP-XXX** IDs are assigned to each implementation task in `7-implementation-plan.md` for downstream mapping to validation tests
+- KPIs are measurable targets that validate whether requirements were met post-deployment
+- Each requirement must include a clear requirement ID for traceability
+- All acceptance conditions must be verifiable through testing or manual inspection
+
+---
+
 ## Conclusion
 
 This ASG Documentation Framework ensures that documentation is:

etc.md

@@ -0,0 +1,8 @@
+1. Specification YAML template missing
+me: agreed. fix it
+
+2. Requirements Traceability Matrix
+me: remove Requirements's Traceability Matrix. it should be in an appendix.
+
+
+