@kudusov.takhir/ba-toolkit 3.5.0 → 3.6.0

package/skills/references/templates/datadict-template.md

@@ -1,55 +1,98 @@
 # Data Dictionary: [PROJECT_NAME]
 
+**Version:** 0.1
+**Status:** Draft
 **Domain:** [DOMAIN]
 **Date:** [DATE]
 **Slug:** [SLUG]
 **References:** `02_srs_[SLUG].md`, `03_stories_[SLUG].md`
+**Scope:** Logical data model only. Physical schema (DBMS choice, indexes, sharding) lives in `07a_research_[SLUG].md` ADRs.
 
 ---
 
 ## Entity: [EntityName]
 
-**Description:** [What this entity represents in the domain.]
-**Table / Collection:** `[table_name]`
-**Linked FR:** FR-[NNN]
+| Field | Value |
+|-------|-------|
+| **Source** | FR-[NNN], US-[NNN]  *(Required — what introduced this entity)* |
+| **Owner** | [Team or role accountable for schema changes and data quality] |
+| **Sensitivity** | Public / Internal / Confidential / PII / PCI / PHI / Financial |
+| **Description** | [What this entity represents in the domain] |
+| **Logical name** | `[entity_name]`  *(physical table / collection name decided in /research)* |
 
-| Field | Type | Required | Default | Description | Constraints |
-|-------|------|----------|---------|-------------|------------|
+### Attributes
+
+| Field | Logical Type | Required | Default | Description | Constraints |
+|-------|--------------|----------|---------|-------------|-------------|
 | id | UUID | Yes | auto | Primary key | Unique |
-| [field] | [String \| Int \| Boolean \| Timestamp \| Decimal \| Enum \| FK] | Yes/No | [value or —] | [description] | [constraints, e.g. max 255, ≥ 0] |
-| created_at | Timestamp | Yes | now() | Record creation time | |
-| updated_at | Timestamp | Yes | now() | Last update time | |
+| [field] | String / Integer / Decimal / Boolean / Timestamp / UUID / Enum / FK / JSON / Binary | Yes/No | [value or —] | [description] | [PK, FK, unique, not null, enum values, min/max, regex] |
+| created_at | Timestamp | Yes | now() | Record creation time (UTC) | |
+| updated_at | Timestamp | Yes | now() | Last update time (UTC) | |
+
+### Relationships
+
+| Related Entity | Cardinality | FK Field | Cascade on Parent Delete |
+|----------------|-------------|----------|--------------------------|
+| [OtherEntity] | many-to-one | `[other_entity]_id` | Cascade / Restrict / Set null / Prevent |
+
+### State Machine *(required if entity has more than two distinct lifecycle states)*
+
+**States:** Draft → Pending → Confirmed → InProgress → Completed → Archived
+**Terminal states:** Completed, Cancelled, Failed
+
+| From → To | Trigger | Allowed actor | Side effects |
+|-----------|---------|---------------|--------------|
+| Draft → Pending | submit() | Owner | Notification, audit log |
+| Pending → Confirmed | approve() | Reviewer | Status email, FK lock |
+| Confirmed → InProgress | start() | Owner | Timer starts |
+| InProgress → Completed | finish() | Owner | Final notification, FK unlock |
+| Any → Cancelled | cancel() | Owner / Admin | Reservation released, audit log |
+
+### Indexes *(logical — physical indexes decided by /research)*
+
+- `[field]` — for [reason, e.g. "frequent lookup by email during login"]
+- `(field_a, field_b)` — composite, for [reason]
+
+### Retention
 
-**Relationships:**
-- `[EntityName]` belongs to `[OtherEntity]` via `[field]` (many-to-one)
-- `[EntityName]` has many `[OtherEntity]` (one-to-many)
+**Retention class:** [duration in years, or "indefinite", or "until consent withdrawn"]
+**Reason:** [legal / regulatory / operational]
+**Soft delete:** Yes (`deleted_at` timestamp) | No (hard delete only)
 
-**Indexes:**
-- `[field]` — for [reason, e.g. lookup by email]
+### Notes
 
-**Soft delete:** Yes — `deleted_at` field / No — hard delete
-**Notes:** [Business rules, state machine, or special handling.]
+[Business rules, validation logic, special handling, edge cases.]
 
 ---
 
 ## Entity: [EntityName2]
 
-**Description:** [What this entity represents in the domain.]
-**Table / Collection:** `[table_name]`
-**Linked FR:** FR-[NNN]
+| Field | Value |
+|-------|-------|
+| **Source** | FR-[NNN] |
+| **Owner** | [team] |
+| **Sensitivity** | [class] |
+| **Description** | [...] |
+| **Logical name** | `[entity_name_2]` |
 
-| Field | Type | Required | Default | Description | Constraints |
-|-------|------|----------|---------|-------------|------------|
+### Attributes
+
+| Field | Logical Type | Required | Default | Description | Constraints |
+|-------|--------------|----------|---------|-------------|-------------|
 | id | UUID | Yes | auto | Primary key | Unique |
 | [field] | [type] | Yes/No | [value] | [description] | [constraints] |
-| created_at | Timestamp | Yes | now() | Record creation time | |
-| updated_at | Timestamp | Yes | now() | Last update time | |
+| created_at | Timestamp | Yes | now() | (UTC) | |
+| updated_at | Timestamp | Yes | now() | (UTC) | |
+
+### Relationships
 
-**Relationships:**
-- [relationship description]
+| Related Entity | Cardinality | FK Field | Cascade on Parent Delete |
+|----------------|-------------|----------|--------------------------|
+| [Entity] | [cardinality] | `[fk_field]` | [cascade rule] |
 
-**Soft delete:** Yes / No
-**Notes:** [Special handling.]
+### Notes
+
+[Notes.]
 
 <!-- Repeat Entity block for each domain entity. -->
 
@@ -65,6 +108,18 @@
 
 ---
 
+## FR → Entity Coverage Matrix
+
+Forward traceability from each Functional Requirement in `02_srs_[SLUG].md` to the entities it reads or writes. An FR with no linked entity is flagged — every data-touching FR must have at least one linked entity.
+
+| FR ID | FR Title | Linked Entities | Read / Write | Coverage Status |
+|-------|----------|-----------------|--------------|-----------------|
+| FR-001 | [title] | User, Session | R/W | ✓ |
+| FR-002 | [title] | Order, OrderLine | R/W | ✓ |
+| FR-003 | [title] | (none) | — | ⚠ Stateless FR — confirm intent |
+
+---
+
 ## Entity Relationship Overview
 
 ```
@@ -72,4 +127,4 @@
 [EntityName2] >── [EntityName3]
 ```
 
-_Full ERD: generated separately by the development team._
+_Full ERD with physical layout: generated by the development team based on this logical model + `07a_research_[SLUG].md` ADRs._

package/skills/references/templates/nfr-template.md

@@ -1,97 +1,203 @@
 # Non-functional Requirements: [PROJECT_NAME]
 
+**Version:** 0.1
+**Status:** Draft
 **Domain:** [DOMAIN]
 **Date:** [DATE]
 **Slug:** [SLUG]
 **References:** `02_srs_[SLUG].md`, `00_principles_[SLUG].md`
+**Standard:** ISO/IEC 25010:2011 Software Quality Model
+
+> Every NFR maps to one of the 8 ISO 25010 characteristics: Functional Suitability, Performance Efficiency, Compatibility, Usability, Reliability, Security, Maintainability, Portability. Project-specific extensions (Compliance, Localisation, Observability) are marked as such and reference the parent ISO characteristic.
 
 ---
 
-## NFR-001: Performance
+## Performance Efficiency (ISO 25010)
 
-| Attribute | Requirement | Measurement Method |
-|-----------|------------|-------------------|
-| [Page / operation] | [Target, e.g. < 2s p95] | [Lighthouse / load test / APM] |
+### NFR-001: [Sub-characteristic — Time behaviour]
 
-**Rationale:** [Why this target matters for this project.]
+| Field | Value |
+|-------|-------|
+| **Sub-characteristic** | Time behaviour |
+| **Description** | [Page / operation / endpoint] response time target |
+| **Metric** | p95 latency in milliseconds |
+| **Acceptance threshold** | < 300ms p95, < 800ms p99 |
+| **Verification** | Load test (k6 / Locust) running [scenario], measured by APM (Datadog / New Relic / Grafana) |
+| **Source** | NFR-baseline from `00_principles_[SLUG].md` §5 / FR-NNN constraint / regulatory requirement |
+| **Rationale** | [Why this target — competitive benchmark, user-perception threshold, contractual SLA] |
+| **Priority** | Must |
+| **Linked FR** | FR-[NNN] |
 
 ---
 
-## NFR-002: Scalability
-
-| Attribute | Requirement | Measurement Method |
-|-----------|------------|-------------------|
-| Concurrent users | [N at peak] | [Load test scenario] |
-| Data volume | [N records, N GB] | [Capacity model] |
+### NFR-002: [Sub-characteristic — Capacity]
 
-**Rationale:** [Expected growth, peak events.]
+| Field | Value |
+|-------|-------|
+| **Sub-characteristic** | Capacity |
+| **Description** | Concurrent users / requests per second the system supports |
+| **Metric** | Concurrent users at peak; sustained RPS |
+| **Acceptance threshold** | [N concurrent users; N RPS sustained for 30 min without error rate > 0.1%] |
+| **Verification** | Load test scenario [name], pass / fail at the threshold |
+| **Source** | [Brief goal G-N or stakeholder] |
+| **Rationale** | [Expected growth, peak events — Black Friday, end-of-quarter, exam day] |
+| **Priority** | Should |
+| **Linked FR** | FR-[NNN] |
 
 ---
 
-## NFR-003: Availability & Reliability
+## Reliability (ISO 25010)
+
+### NFR-003: [Sub-characteristic — Availability]
+
+| Field | Value |
+|-------|-------|
+| **Sub-characteristic** | Availability |
+| **Description** | Service uptime target |
+| **Metric** | Uptime % over rolling 30-day window |
+| **Acceptance threshold** | 99.9% (8.76 hours downtime/year) |
+| **Verification** | Status page measurement, third-party uptime monitor |
+| **Source** | [SLA contract / regulatory requirement] |
+| **Rationale** | [Customer-facing SLA, internal commitment] |
+| **Priority** | Must |
+| **Linked FR** | All customer-facing FRs |
+
+### NFR-004: [Sub-characteristic — Recoverability]
+
+| Field | Value |
+|-------|-------|
+| **Sub-characteristic** | Recoverability |
+| **Description** | Disaster-recovery RTO / RPO |
+| **Metric** | RTO (Recovery Time Objective) in hours; RPO (Recovery Point Objective) in minutes |
+| **Acceptance threshold** | RTO < 4h, RPO < 15min |
+| **Verification** | Documented runbook, tested via DR drill quarterly |
+| **Source** | [Compliance / business continuity policy] |
+| **Rationale** | [Cost of downtime, regulatory requirement] |
+| **Priority** | Must |
 
-| Service | SLA | Maintenance Window |
-|---------|-----|--------------------|
-| [Service name] | 99.9% | [Sun 02:00–04:00 UTC] |
+---
 
-**RTO:** [Recovery Time Objective, e.g. < 4h]
-**RPO:** [Recovery Point Objective, e.g. < 1h]
+## Security (ISO 25010)
+
+### NFR-005: [Sub-characteristic — Confidentiality]
+
+| Field | Value |
+|-------|-------|
+| **Sub-characteristic** | Confidentiality |
+| **Description** | Encryption at rest and in transit |
+| **Metric** | Encryption algorithm + key length |
+| **Acceptance threshold** | TLS 1.2+ in transit; AES-256 at rest |
+| **Verification** | TLS scan, infrastructure config review, pen-test |
+| **Source** | [SOC 2 / PCI DSS / HIPAA / GDPR] |
+| **Rationale** | Regulatory baseline + customer trust |
+| **Priority** | Must |
+
+### NFR-006: [Sub-characteristic — Authenticity / Accountability]
+
+| Field | Value |
+|-------|-------|
+| **Sub-characteristic** | Authenticity, Accountability |
+| **Description** | Authentication strength, audit trail per user action |
+| **Metric** | MFA coverage, audit log completeness |
+| **Acceptance threshold** | MFA mandatory for admin role; every PII access logged with actor + timestamp |
+| **Verification** | Audit log inspection, security review |
+| **Source** | [SOC 2 CC6.1, regulatory requirement] |
+| **Rationale** | Compliance + incident-response capability |
+| **Priority** | Must |
 
 ---
 
-## NFR-004: Security
+## Compatibility (ISO 25010)
 
-| Control | Requirement |
-|---------|-------------|
-| Authentication | [e.g. JWT, OAuth 2.0, MFA for admin] |
-| Authorisation | [e.g. RBAC, row-level security] |
-| Data in transit | [TLS 1.2+] |
-| Data at rest | [AES-256] |
-| [Other control] | [requirement] |
+### NFR-007: [Sub-characteristic — Interoperability]
 
-**Compliance standard:** [PCI DSS / HIPAA / GDPR / none]
+| Field | Value |
+|-------|-------|
+| **Sub-characteristic** | Interoperability |
+| **Description** | Data-exchange formats with external systems |
+| **Metric** | Supported formats |
+| **Acceptance threshold** | JSON over REST + CSV export + webhook OUT |
+| **Verification** | Integration tests with each external system |
+| **Source** | [Stakeholder name / partner contract] |
+| **Rationale** | [Why these formats — partner constraints] |
+| **Priority** | Must |
 
 ---
 
-## NFR-005: Maintainability
+## Usability (ISO 25010)
 
-| Attribute | Requirement |
-|-----------|-------------|
-| Code coverage | [≥ 80% unit test coverage] |
-| Deployment | [CI/CD, zero-downtime deployments] |
-| Logging | [Structured JSON logs, retained N days] |
-| Alerting | [P1 alert → on-call within 5 min] |
+### NFR-008: [Sub-characteristic — Accessibility]
+
+| Field | Value |
+|-------|-------|
+| **Sub-characteristic** | Accessibility (Usability sub-characteristic in ISO 25010) |
+| **Description** | WCAG conformance level |
+| **Metric** | WCAG 2.1 conformance level |
+| **Acceptance threshold** | WCAG 2.1 AA on all customer-facing surfaces |
+| **Verification** | Automated (axe-core) + manual testing with NVDA, JAWS, VoiceOver |
+| **Source** | [Section 508 / EN 301 549 / domain reference] |
+| **Rationale** | Legal requirement (EU public sector, US federal) + customer base inclusion |
+| **Priority** | Must |
 
 ---
 
-## NFR-006: Usability & Accessibility
+## Maintainability (ISO 25010)
+
+### NFR-009: [Sub-characteristic — Testability]
 
-| Attribute | Requirement |
-|-----------|-------------|
-| Accessibility | [WCAG 2.1 AA] |
-| Browser support | [Chrome, Safari, Firefox — latest 2 versions] |
-| Mobile | [Responsive, iOS 15+, Android 10+] |
-| Language | [EN / RU / other] |
+| Field | Value |
+|-------|-------|
+| **Sub-characteristic** | Testability |
+| **Description** | Automated test coverage target |
+| **Metric** | Unit + integration test coverage % |
+| **Acceptance threshold** | ≥ 80% line coverage on core domain modules |
+| **Verification** | CI report on every PR |
+| **Source** | [Internal engineering standard] |
+| **Rationale** | Catch regressions, support refactoring |
+| **Priority** | Should |
 
 ---
 
-## NFR-007: [Additional Category]
+## Portability (ISO 25010)
 
-| Attribute | Requirement | Measurement Method |
-|-----------|------------|-------------------|
-| [attribute] | [requirement] | [method] |
+### NFR-010: [Sub-characteristic — Adaptability]
 
-<!-- Add or remove NFR sections based on project needs. Numbering: NFR-001, NFR-002, ... -->
+| Field | Value |
+|-------|-------|
+| **Sub-characteristic** | Adaptability |
+| **Description** | Browser / OS / device support matrix |
+| **Metric** | Supported browser × OS × device combinations |
+| **Acceptance threshold** | Latest 2 major versions of Chrome, Safari, Firefox, Edge; iOS 15+, Android 10+ |
+| **Verification** | Cross-browser test suite |
+| **Source** | [User analytics on existing audience] |
+| **Rationale** | Coverage of 95%+ of expected user base |
+| **Priority** | Should |
+
+<!-- Add NFR sections as needed. Every NFR maps to an ISO 25010 characteristic. -->
 
 ---
 
-## Priority Summary
+## FR → NFR Coverage Matrix
+
+Forward traceability from each Functional Requirement in `02_srs_[SLUG].md` §3 to the NFRs that govern its quality. A Must-priority FR with no linked NFR is flagged — every customer-facing Must FR should have at least one Performance, Reliability, or Security NFR attached.
+
+| FR ID | FR Title | Linked NFRs | Coverage Status |
+|-------|----------|-------------|-----------------|
+| FR-001 | [title] | NFR-001, NFR-003, NFR-005 | ✓ |
+| FR-002 | [title] | NFR-001, NFR-005 | ✓ |
+| FR-003 | [title] | (uncovered) | ✗ |
+
+---
 
-| ID | Category | Priority |
-|----|----------|---------|
-| NFR-001 | Performance | Must |
-| NFR-002 | Scalability | Should |
-| NFR-003 | Availability | Must |
-| NFR-004 | Security | Must |
-| NFR-005 | Maintainability | Should |
-| NFR-006 | Usability | Should |
+## Priority Summary by ISO 25010 Characteristic
+
+| ISO 25010 Characteristic | NFRs | Must | Should | Could |
+|--------------------------|------|------|--------|-------|
+| Performance Efficiency | NFR-001, NFR-002 | 1 | 1 | 0 |
+| Reliability | NFR-003, NFR-004 | 2 | 0 | 0 |
+| Security | NFR-005, NFR-006 | 2 | 0 | 0 |
+| Compatibility | NFR-007 | 1 | 0 | 0 |
+| Usability | NFR-008 | 1 | 0 | 0 |
+| Maintainability | NFR-009 | 0 | 1 | 0 |
+| Portability | NFR-010 | 0 | 1 | 0 |
+| Functional Suitability | (covered by FRs) | — | — | — |

package/skills/references/templates/scenarios-template.md

@@ -1,9 +1,11 @@
 # Validation Scenarios: [PROJECT_NAME]
 
+**Version:** 0.1
+**Status:** Draft
 **Domain:** [DOMAIN]
 **Date:** [DATE]
 **Slug:** [SLUG]
-**References:** `03_stories_[SLUG].md`, `05_ac_[SLUG].md`, `09_wireframes_[SLUG].md`, `08_apicontract_[SLUG].md`
+**References:** `02_srs_[SLUG].md`, `03_stories_[SLUG].md`, `05_ac_[SLUG].md`, `06_nfr_[SLUG].md`, `08_apicontract_[SLUG].md`, `09_wireframes_[SLUG].md`
 
 ---
 
@@ -19,13 +21,17 @@
 
 ## SC-001: [Scenario Title]
 
-**Persona:** [Name and role — e.g. "Alex, a returning customer"]
+**Persona:** [Name and role — e.g. "Alex, a returning customer in DE who buys 4–6 times per year"]
 **Type:** Happy path | Negative | Edge case | Performance | Security
 **Priority:** P1 (critical) | P2 (important) | P3 (nice to have)
+**Frequency:** [How often this scenario runs in production — "every login", "once per month per user", "twice per year per admin"]
+**Stakes:** [Cost of failure — "data loss", "lost revenue ~€X per failed run", "regulatory breach", "reputation"]
 **Entry point:** [Where the scenario starts — e.g. "Home screen, not logged in"]
 **Platform:** Web | iOS | Android | API
-**Linked Stories:** US-[NNN], US-[NNN]
-**Linked AC:** US-[NNN] Scenario [N]
+**Source — Linked Stories:** US-[NNN], US-[NNN]
+**Source — Linked FR:** FR-[NNN]
+**Source — Linked NFR:** NFR-[NNN]  *(if scenario validates a quality attribute)*
+**Linked AC:** AC-[NNN]-[NN], AC-[NNN]-[NN]
 
 ### Steps
 
@@ -82,12 +88,16 @@
 
 | Artifact | Covered | Not Covered |
 |---------|---------|------------|
-| User Stories | [N] / [Total] | US-[NNN], … |
-| Acceptance Criteria Scenarios | [N] / [Total] | |
+| User Stories (Must) | [N] / [Total] | US-[NNN], … |
+| Functional Requirements (Must) | [N] / [Total] | FR-[NNN], … |
+| Non-functional Requirements | [N] / [Total] | NFR-[NNN], … |
+| Acceptance Criteria | [N] / [Total] | AC-[NNN]-[NN], … |
 | API Endpoints | [N] / [Total] | `[endpoint]`, … |
 | Wireframe screens | [N] / [Total] | WF-[NNN], … |
 
 **Happy path scenarios:** [N]
 **Negative scenarios:** [N]
 **Edge case scenarios:** [N]
+**Performance scenarios:** [N]
+**Security scenarios:** [N]
 **Total scenarios:** [N]

package/skills/references/templates/usecases-template.md

@@ -1,5 +1,7 @@
 # Use Cases: [PROJECT_NAME]
 
+**Version:** 0.1
+**Status:** Draft
 **Domain:** [DOMAIN]
 **Date:** [DATE]
 **Slug:** [SLUG]
@@ -7,26 +9,34 @@
 
 ## Use Case Index
 
-| ID | Title | Primary Actor | Linked Stories |
-|----|-------|--------------|---------------|
-| UC-001 | [Title] | [Actor] | US-[NNN] |
+| ID | Title | Goal in Context | Primary Actor | Linked Stories |
+|----|-------|-----------------|---------------|----------------|
+| UC-001 | [Title] | G-1 | [Actor] | US-[NNN] |
 
 ---
 
 ## UC-001: [Use Case Title]
 
 **ID:** UC-001
+**Goal in Context:** [Which Brief goal G-N from `01_brief_[SLUG].md` §2 this UC serves. Required.]
+**Scope:** System | Subsystem | Component
+**Level:** User-goal | Summary | Subfunction
 **Primary Actor:** [Role]
-**Supporting Actors:** [Other roles or external systems]
-**Trigger:** [What event or action initiates this use case]
+**Supporting Actors:** [Other roles or external systems — payment provider, notification service, etc.]
+
+**Stakeholders and Interests:**
+
+| Stakeholder | Interest |
+|-------------|----------|
+| [Primary actor] | [What they want from this UC] |
+| [Other stakeholder] | [What they want / what they want to avoid] |
+
 **Pre-conditions:**
 - [Condition that must be true before the use case starts]
 
-**Post-conditions (Success):**
-- [System state after successful completion]
+**Trigger:** [What event or action initiates this use case]
 
-**Post-conditions (Failure):**
-- [System state after failure or cancellation]
+**Source:** US-[NNN] | FR-[NNN] | regulatory requirement | parent UC-NNN  *(Required — what drove this UC into existence.)*
 
 ### Main Success Scenario
 
@@ -36,16 +46,35 @@
 | 2 | System | [Responds with something] |
 | 3 | [Actor] | [Continues] |
 
-### Alternative Flows
+### Extensions / Alternative Flows
 
 **Alt 1 — [Name]:** At step [N], if [condition], then [action]. Resume at step [M].
 
 ### Exception Flows
 
-**Exc 1 — [Name]:** At step [N], if [error condition], then [system response and outcome].
+**Exc 1 — [Name]:** At step [N], if [error condition], then [system response, recovery action, and final outcome].
+
+### Post-conditions
+
+**Success Guarantees:** [What is true after the Main Success Scenario completes — the contract for the happy path.]
+
+**Minimal Guarantees:** [What is true after *any* termination of the UC, including failure — e.g. "stock reservation released, no partial order created, audit log entry written".]
 
 **Linked Stories:** US-[NNN], US-[NNN]
 **Linked FR:** FR-[NNN]
+**Linked AC:** AC-[NNN]-[NN], AC-[NNN]-[NN]
 **Linked Wireframe:** WF-[NNN]
 
 <!-- Repeat UC block for each use case. Numbering: UC-001, UC-002, ... -->
+
+---
+
+## US → UC Coverage Matrix
+
+Forward traceability from each User Story in `03_stories_[SLUG].md` to the Use Cases that detail it. Every Must-priority story should have at least one linked UC; uncovered stories are flagged here as `(uncovered)` so they cannot silently fall through to AC without UC context.
+
+| US ID | US Title | Linked UCs | Coverage Status |
+|-------|----------|------------|-----------------|
+| US-001 | [title] | UC-001, UC-007 | ✓ |
+| US-002 | [title] | UC-003 | ✓ |
+| US-003 | [title] | (uncovered) | ✗ |

package/skills/references/templates/wireframes-template.md

@@ -1,9 +1,12 @@
 # Wireframe Descriptions: [PROJECT_NAME]
 
+**Version:** 0.1
+**Status:** Draft
 **Domain:** [DOMAIN]
 **Date:** [DATE]
 **Slug:** [SLUG]
-**References:** `03_stories_[SLUG].md`, `04_usecases_[SLUG].md`, `05_ac_[SLUG].md`
+**References:** `03_stories_[SLUG].md`, `04_usecases_[SLUG].md`, `05_ac_[SLUG].md`, `06_nfr_[SLUG].md`, `08_apicontract_[SLUG].md`
+**Accessibility target:** WCAG 2.1 AA
 
 > These are textual wireframe descriptions, not visual diagrams. Each screen is described with sufficient detail for a designer to produce a high-fidelity mockup.
 
@@ -19,11 +22,15 @@
 
 ## WF-001: [Screen Name]
 
+**Source:** US-[NNN]  *(Required — which user story this screen serves)*
 **Platform:** Web | iOS | Android | All
 **Route / Deep link:** `[/path or app://screen]`
 **Entry points:** [Where the user comes from — e.g. Home → tap "Browse"]
 **Linked Stories:** US-[NNN], US-[NNN]
 **Linked UC:** UC-[NNN]
+**Linked AC:** AC-[NNN]-[NN]  *(scenarios this screen verifies)*
+**Linked NFR:** NFR-[NNN]  *(performance, accessibility, or other UI-impacting NFRs)*
+**Internationalisation:** LTR / RTL / both; long-string accommodation: yes / no
 
 ### Layout
 
@@ -36,14 +43,19 @@
 **Footer / Bottom navigation:**
 [Describe persistent navigation or action bar if present.]
 
-### States
+### States *(canonical 8 — every screen describes all that apply)*
 
 | State | Description |
 |-------|-------------|
-| Loading | [Skeleton screen / spinner / progress bar] |
-| Empty | [Empty state message and CTA] |
-| Error | [Error message and recovery action] |
-| [Feature state] | [Description, e.g. "item added to cart — badge updates"] |
+| Default | [Initial state when the screen first appears, if distinct from "loaded"] |
+| Loading | [Skeleton screen / spinner / progress bar — what the user sees while data fetches] |
+| Empty | [Empty state message + primary CTA — first-time experience] |
+| Loaded | [Data is present and rendered — the canonical "happy" state] |
+| Partial | [Some data shown, more loading — pagination / streaming] |
+| Success | [After a user action completes — confirmation banner, toast, animation] |
+| Error | [Failure state — message + recovery action] |
+| Disabled | [Action not available — visible reason for the user, no dead-end] |
+| [Feature state] | [Optional feature-specific state, e.g. "trial expired", "offline mode"] |
 
 ### Interactions
 
@@ -94,3 +106,15 @@
 - [Note]
 
 <!-- Repeat WF block for each screen. Numbering: WF-001, WF-002, ... -->
+
+---
+
+## US → WF Coverage Matrix
+
+Forward traceability from each User Story to the screen(s) that implement it. Every Must-priority story should have at least one linked screen; uncovered stories are flagged.
+
+| US ID | US Title | Linked Wireframes | Coverage Status |
+|-------|----------|-------------------|-----------------|
+| US-001 | [title] | WF-001, WF-002 | ✓ |
+| US-002 | [title] | WF-003 | ✓ |
+| US-003 | [title] | (uncovered) | ✗ |