update

ASG_Framework.md

@@ -9,8 +9,8 @@ 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 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)." | 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 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. |
 | **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). |
 | **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. |
@@ -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.
 
@@ -53,7 +53,7 @@ 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.
 
@@ -89,57 +89,59 @@ This document defines the documentation framework for a software project. It est
 ---
 
 ### 3. Walkthrough
-`walkthrough.md`
+`3-walkthrough.md`
 
-**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
-- **Operational Control**: Practical exposure to system controls and interaction patterns
-- **Outcome Verification**: Direct observation of the system's outputs and deliverables
-- **Impact Assessment**: Data-driven evaluation of the solution's ROI and efficiency gains
-- **Expectation Alignment**: Early discovery of discrepancies between intended functionality and actual experience
 
-**For the Developer: Aligning Architecture with Reality**
+| Walkthrough Section | System Participant | What It Shows |
-- **Requirement Validation**: Confirming the solution satisfies core business objectives
+|---------------------|-------------------|---------------|
-- **Impact Analysis**: Assessing the solution's real-world behavioral performance
+| **Participant A Section** | Primary system user (e.g., wine retailer customer) | End-to-end journey: browse → interact → complete task → receive outcome |
-- **Knowledge Synthesis**: Identifying disconnects between domain intent and technical interpretation
+| **Participant B Section** | Secondary system user (e.g., wine retailer admin) | End-to-end journey: manage → configure → review → reconcile |
-- **Specification Refinement**: Spotting missing technical dependencies or edge cases
+| **Participant C Section** | Tertiary system user (e.g., system administrator) | End-to-end journey: configure → monitor → handle incidents → audit |
-- **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
+Each section:
+- Traces the complete flow from that participant's login/session start to task completion and logout
+- Explicitly references steps where other participants' actions are triggered (e.g., "Customer places order → see Retailer section step 4.2")
+- Shows error paths, edge cases, and recovery from that participant's perspective
+- Uses sequence diagrams to illustrate interactions across participants
 
 **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.
 
 **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
-- 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**:
@@ -170,7 +172,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.
 
@@ -201,7 +203,7 @@ 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.
 
@@ -217,7 +219,7 @@ The walkthrough functions as a collaborative audit, mapping the proposed solutio
 
 **Content Guidelines**:
 - **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)
+- **Integration tests** — end-to-end flow validation covering workflows defined in 3-walkthrough.md (cites specification.md endpoint chains, 3-walkthrough.md participant sections)
 - **Performance tests** — load tests, stress tests, and benchmarking against NFR thresholds (cites requirements.md NFRs, solution-design.md performance decisions)
 - **Penetration tests** — adversarial testing of security requirements and auth flows (cites requirements.md security NFRs, specification.md auth endpoints)
 - Contract testing scripts (mapped to specification.md sections)
@@ -227,8 +229,8 @@ The walkthrough functions as a collaborative audit, mapping the proposed solutio
 - Security scanning and audit jobs (SAST, dependency vulnerability checks)
 - CI/CD pipeline configurations for automated test execution
 - 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
+  - **specification.md** (spec IDs or paths — API contracts, data schemas, e.g., `/api/v1/endpoint` or `#/components/schemas/Request`)
-  - **ui-specification.md** (components, interactions, visual states, e.g., sections 15.1, 15.3) — UI contract being verified
+  - **ui-specification.md** (components, interactions, visual states, e.g., `## Wine Table` or `### Sort States`)
   - **requirements.md** (e.g., FR-001, NFR-101, NFR-201) — business intent and NFR thresholds being validated
   - **solution-design.md** (e.g., SD-2.1, SD-3.3) — architectural decisions being tested
 
@@ -257,11 +259,11 @@ Every specification rule must have a runnable, verifiable test. This trace maps
 | 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).
+**Additional Test File(s)** column covers: integration tests (participant section 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** participant section 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)
@@ -283,7 +285,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
@@ -310,7 +312,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.
 
@@ -358,9 +360,9 @@ Once requirements are stable, translate them into an viable solution. This ensur
 
 ### 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 solution-design.md (SD-XXX IDs) and 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 solution design decisions and requirements.
 
 ### 4. Define the Specification
 
@@ -368,7 +370,7 @@ 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 requirements.md, solution-design.md, and 3-walkthrough.md.
 
 ### 5. Define UI Specification Early
 
@@ -380,7 +382,7 @@ Create UI specifications before implementing frontend components. This ensures d
 
 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.
 
-**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/` (end-to-end flows from each participant walkthrough section), `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
 
@@ -403,8 +405,8 @@ 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 participant section trace the complete flow the Solution Design describes, including all SD-XXX decisions? Is there a section for each system participant? | Solution design says "use NATS for async messaging", but Participant A section doesn't trace the async flow or reference SD-001 | Add the async messaging flow with SD-001 reference to Participant A section |
-| **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 the Specification cover all the behaviors defined in every participant section? | Participant A section shows 10 interaction steps, but Specification only defines 2 REST endpoints | Add the missing endpoint definitions to Specification |
 | **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 |
 | **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 |
@@ -420,11 +422,11 @@ 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 decision and requirement 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)
+    - At least one requirement ID reference (WHAT)
-   - At least one solution design reference (HOW/WHY)
+    - At least one solution design reference (HOW/WHY)
-   - Coverage for all behaviors defined in the Walkthrough
+    - Coverage for all behaviors defined in each participant section
 5. **UI Specification Review**: After writing UI Specification, verify every spec rule has at least one UI representation with a corresponding requirement ID reference
 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
 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
@@ -439,7 +441,7 @@ This habit ensures that each documentation stage is complete and validated befor
 |-------|-----------------|----------------|
 | **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 |
-| **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 full flow, 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*) |
 | **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 |
 | **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 |
@@ -475,7 +477,7 @@ 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 |
 | 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 |