update

ASG_Framework.md

@@ -485,6 +485,18 @@ Each documentation artifact has associated KPIs. Track these to ensure quality:
 | 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
@@ -544,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]
@@ -625,9 +657,12 @@ Describe the high-level approach to solving the problem.
 
 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 |
@@ -635,17 +670,41 @@ Explain the design reasoning behind each major decision — why the solution was
 
 ## 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
-%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#3b82f6'}}}%%
-flowchart TD
-    A[User] --> B[Comparison UI]
-    B --> C[Comparison State]
-    B --> D[Wine API]
-    C --> D
+%% 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**:
-- **[Component Name]**: [Brief description of responsibilities and how it solves part of the problem]
+- **[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
@@ -681,6 +740,161 @@ Link each solution component to specific requirements and assign Solution Design
 | 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