@educa-corp/sdd-framework 0.1.0

package/templates/project-context.yaml

@@ -0,0 +1,161 @@
+# =============================================================
+# Project Context — AI-First Spec-Driven Development
+# =============================================================
+# This is the SINGLE SOURCE OF TRUTH for project-specific
+# paths, tools, and routing used by all workflows.
+#
+# Workflows reference this file for WHERE to find things.
+# Workflow steps define WHAT to do (universal best practices).
+# =============================================================
+#
+# HOW AI AGENTS USE THIS FILE:
+# 1. Open this file at the start of any workflow
+# 2. Parse the YAML structure
+# 3. When a workflow says "→ key.subkey", look up that key
+#    and use the resolved value as the actual path
+# 4. All paths are RELATIVE to workspace root
+# 5. For "{domain}", substitute the feature's domain (PRD: row `Domain` in Metadata / folder path; .feature: @trace.domain)
+# =============================================================
+
+project:
+  name: "{{PROJECT_NAME}}"
+  description: "{{PROJECT_DESCRIPTION}}"
+
+# ----- File Paths -----
+# All paths are relative to workspace root.
+paths:
+  # Feature-Package Layout:
+  #   specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md  — PRD document
+  #   specs/{domain}/{prd-slug}/bdd/             — BDD .feature files
+  #   specs/{domain}/{prd-slug}/tech-docs/       — Technical design docs
+  #   specs/{domain}/{prd-slug}/design-spec/     — Design specs (FE/App only)
+  #   .trace/{domain}/{prd-slug}/{UC-ID}.tsv     — Trace state
+  #
+  # specs_dir is the unified root for all spec artifact types (PRD, BDD, tech-docs, design-spec).
+  # prd-slug is derived from the PRD folder path — not a separate config variable.
+  specs_dir: "specs"
+  templates_dir: "specs/templates"
+  feature_template: ".agent/templates/feature.template"   # SoT skeleton .feature (dùng bởi /generate-bdd qua {{include}})
+  bdd_writing_guide: "specs/templates/bdd-writing-guide.md"
+  trace_report: "specs/.trace/trace-report.md"
+
+  # PRD template (PRDs are at specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md)
+  prd_template: "specs/templates/prd.template.md"
+  refinement_dir: ".agent/review"
+
+  # QC's OWN analysis/design working docs (qc-analyze/plan/design-test outputs:
+  # REQUIREMENT_ANALYSIS.md, DOC_GAPS.md, TEST_PLAN.md, test-cases/*.Test.md).
+  # One subfolder per UC: {qc_dir}/{UC-ID}/. Default "docs" (the QC team's own
+  # convention), VISIBLE — not hidden under .agent/. NOTE: specs (PRD / .feature /
+  # design-spec) are NOT here — they come from the PO spec submodule (spec_source).
+  qc_dir: "docs"
+
+  # WHERE the qc-* commands LOAD their skills from (qa-analyst / qa-designer / qa-planner
+  # / qa-reviewer / qa-runner + DOC_GAPS.template.md). Default = the framework-bundled
+  # copy at .agent/skills/qc (works standalone). The QC team OWNS these skills in their
+  # canonical repo (ai-automation-qc-base) — point this at that repo/submodule (e.g.
+  # "qc-base/.claude/skills") so the skills evolve INDEPENDENTLY and are NOT overwritten
+  # by framework upgrade (--init / upgrade.sh rewrite only .agent/, never this path).
+  qc_skills_dir: ".agent/skills/qc"
+
+  # Product Definitions
+  product_definitions_dir: "specs/product-definition"
+  product_definition_template: "specs/templates/product-definition.template.md"
+
+  # Domain Knowledge
+  domain_knowledge_dir: "specs/domain-knowledge"
+  business_dictionary: "specs/domain-knowledge/business-dictionary.md"
+  core_entities: "specs/domain-knowledge/core-entities.md"
+
+  # Project Lessons (guardrails accumulated via /learn — loaded by context-loader Step 6.7)
+  # Single-service default below. In umbrella/service mode, set this in each service's
+  # .agent/project-context.yaml to ".agent/project-lessons.md" (resolved per service_root).
+  lessons_file: "specs/domain-knowledge/lessons-learned.md"
+
+  # Tech Docs (BE-authored API contract).
+  # Merged into specs_dir in the feature-package layout:
+  # tech-docs live at specs/{domain}/{prd-slug}/tech-docs/.
+  # In umbrella mode with spec_source set, context-loader auto-routes this to
+  # {spec_source}/specs so FE/App read the contract via the spec submodule.
+  tech_docs_dir: "specs"
+
+  # Design Specs (FE/App platforms only — web, app).
+  # In the feature-package layout, design-specs live at specs/{domain}/{prd-slug}/design-spec/.
+  # This variable is no longer needed as a separate path — derived from specs_dir.
+  # design_spec_dir: "specs/design-spec"   ← removed; use specs_dir instead
+
+  # Trace (internal structure: .trace/{domain}/{prd-slug}/{UC-ID}.tsv)
+  trace_dir: ".trace"
+
+  # Tester / QC feedback (written by /report-bug and /propose-scenario).
+  # These live in the SHARED spec repo so PO/Dev see them on their next /sync.
+  # In umbrella mode, context-loader auto-resolves them under {spec_source}/feedback/.
+  bug_reports_dir: "feedback/bug-reports"
+  bdd_proposals_dir: "feedback/bdd-proposals"
+  # PRD change requests (new requirement found in test, not covered by any AC) —
+  # written by /propose-scenario Case B so the PO can add/extend an AC then re-/generate-bdd.
+  prd_change_requests_dir: "feedback/prd-change-requests"
+
+tech_stack:
+  language: "{{LANGUAGE}}"              # e.g., Java 17 / TypeScript / C# / Go
+  framework: "{{FRAMEWORK}}"           # e.g., Spring Boot 3.2 / Angular 17 / .NET 8
+  build_tool: "{{BUILD_TOOL}}"         # e.g., Maven / npm / dotnet / go
+  test_framework: "{{TEST_FRAMEWORK}}" # e.g., JUnit 5 + Mockito / Jest / xUnit
+  database: "{{DATABASE}}"             # e.g., PostgreSQL / MySQL / MongoDB
+  module: "{{MODULE}}"                 # e.g., java-spring / angular / dotnet / golang / context-engineering
+
+conventions:
+  build_command: "{{BUILD_COMMAND}}"   # e.g., mvn clean install -DskipTests
+  test_command: "{{TEST_COMMAND}}"     # e.g., mvn test
+  service_run: "{{RUN_COMMAND}}"       # e.g., mvn spring-boot:run
+  ticket_prefix: "{{TICKET_PREFIX}}"  # e.g., PROJ / FEAT / UC
+
+domains:
+  - "{{DOMAIN_1}}"
+  # - "{{DOMAIN_2}}"
+
+# ----- Multi-Service / Umbrella Setup -----
+# Fill this section ONLY if this is an UMBRELLA repo that contains multiple
+# service submodules. Leave commented out for single-service projects.
+#
+# setup:
+#   mode: umbrella                            # "umbrella" | "single" (default: single)
+#   spec_source: "{{SPEC_SUBMODULE_PATH}}"   # path to PO spec submodule, e.g. "free-trial-specs"
+#
+# When spec_source is set, context-loader auto-derives (ALL specs live in the spec repo
+# using the feature-package layout; service submodules hold only code):
+#   specs_dir            → {spec_source}/specs                # unified root — PRD/BDD/tech-docs/design-spec
+#   tech_docs_dir        → {spec_source}/specs                # merged into specs_dir
+#   domain_knowledge_dir → {spec_source}/specs/domain-knowledge
+#   trace_dir            → {spec_source}/.trace               # structure: .trace/{domain}/{prd-slug}/{UC-ID}.tsv
+# (You can still override these manually in paths: section below.)
+# With spec_source set, only ONE override is needed instead of four separate dir vars.
+#
+# services:                                   # domain → service submodule routing
+#   {{DOMAIN_1}}:                             # must match the PRD's `Domain` (Metadata row) / folder path segment
+#     path: "{{SERVICE_SUBMODULE_DIR}}"       # relative path to service submodule (code + .trace/)
+#     module: "{{STACK_MODULE}}"              # e.g., java-spring, nextjs, flutter
+#     # NOTE: with spec_source set, BDD + tech-docs are cross-team and live in the spec repo —
+#     # do NOT pin per-service specs_dir / tech_docs_dir here (they would be ignored).
+#     # Per-service specs_dir / tech_docs_dir apply ONLY when there is no spec_source.
+#
+# IMPORTANT — per-service CLAUDE.md:
+#   Each service submodule should have its OWN CLAUDE.md ({path}/CLAUDE.md) defining its
+#   architecture + coding standards for ITS stack. context-loader loads CLAUDE.md in two
+#   layers: root CLAUDE.md (umbrella-wide shared rules) + {service}/CLAUDE.md (overlay,
+#   wins on conflict for architecture/coding-standards). The agent sits at the umbrella
+#   root, so without a service CLAUDE.md, code generation falls back to umbrella defaults
+#   (likely the wrong stack). Generate one per service via /setup-ai-first inside each.
+#   {{DOMAIN_2}}:
+#     path: "{{SERVICE_2_DIR}}"
+#     module: "{{STACK_MODULE}}"
+#     specs_dir: "{{SERVICE_2_DIR}}/specs"
+#     tech_docs_dir: "{{SERVICE_2_DIR}}/specs"
+
+# ----- Architecture -----
+architecture:
+  style: "{{ARCH_STYLE}}"              # e.g., Layered / Clean / Hexagonal
+  layers: "{{LAYER_STACK}}"            # e.g., Controller → Facade → Service → Repository
+  key_rules:
+    - "{{ARCH_RULE_1}}"
+    - "{{ARCH_RULE_2}}"

package/templates/tech-design.template.md

@@ -0,0 +1,498 @@
+<!--
+  ════════════════════════════════════════════════════════════════════════════
+  TEMPLATE: Technical Design Document (per-PRD, full-stack, merged)
+  Used by: /generate-tech-docs
+  ════════════════════════════════════════════════════════════════════════════
+
+  SCOPE MODEL
+  - ONE document per PRD (not per UC). It covers EVERY use case of the PRD in a
+    single merged, full-stack design: backend (API, data model, DB) AND client
+    (components, state, API-integration) side by side, joined by cross-tier
+    sequence diagrams. This is the "construction blueprint" any developer opens
+    to implement the whole feature.
+  - INPUT is the BDD feature files of the PRD (web/ · app/ · system/), NOT the
+    PRD prose. The PRD is loaded only for Overview/Goals/Actors context.
+
+  INCREMENTAL / APPEND
+  - When new BDD is added to the same PRD later, this document is EXTENDED, not
+    regenerated: add the new UC's sections + sequence diagrams, update the
+    UC Coverage matrix (§10) and the Changelog. Never clobber existing content
+    or hand edits.
+
+  FILLING RULES
+  - Replace every {…} placeholder with real content. Delete guidance comments.
+  - TERMINOLOGY: obey the project dictionary 100%
+    (specs/domain-knowledge/business-dictionary.md). Status/enum values →
+    core-entities.md (Enum Registry). Entities → core-entities.md.
+  - Keep code/DTO/DB samples in the project's stack idiom (see the active module
+    stack-profile). The C#/Angular snippets below are ILLUSTRATIVE — swap for
+    the real stack.
+  - A section that does not apply to this PRD: keep the heading and write
+    "N/A — {reason}" rather than deleting it, so the shape stays predictable.
+  - Every sequence diagram / API / rule should be traceable back to a scenario:
+    reference the SC id (e.g. UC1-SC3) it serves.
+-->
+
+# {Feature Area} — {PRD Title} Technical Design Document
+
+<!-- @trace block (PRD-level). ucs = every UC covered by this doc; append ids as UCs are added. -->
+---
+@trace.id: {TICKET-ID}
+@trace.domain: {domain}
+@trace.prd: {TICKET-ID}
+@trace.ucs: {TICKET-ID}-UC1, {TICKET-ID}-UC2{, …}
+@trace.service: {service — from BDD header @trace.service}
+@trace.module: {module(s) involved — e.g. dotnet, angular}
+@trace.platforms: {system | web | app — whichever BDD folders exist}
+@trace.bdd_version: {per-platform map — e.g. system=1.5, web=1.9, app=1.7; only platforms present. Each feature carries its own bdd_version; do not flatten to one number.}
+@trace.api_source: {existing | —}
+@trace.revision: 1
+@trace.status: draft
+@trace.generated_at: {YYYY-MM-DD}
+---
+
+> **Related docs:** {link sibling PRDs / tech-designs this depends on, e.g. [OTHER-TICKET](../{other-slug}/tech-docs/{OTHER-TICKET}-tech-design.md)}. Delete if none.
+
+## 1. Overview
+
+<!-- 2–4 sentences: what this feature does, who uses it, the key technical shape
+     (data sources, primary side effects). Name where data comes from (DB vs
+     external API) and the main write. Source: PRD + system BDD. -->
+
+{What the feature does, its main actor, and the core technical mechanism. State
+which data is owned (DB) vs sourced live (external API), and the primary write.}
+
+### Goals
+
+<!-- Bullet the technical goals — derived from PRD goals, phrased as what the
+     system must guarantee. -->
+
+- {Goal 1}
+- {Goal 2}
+
+### Business Actors
+
+| Actor | Description | Channel |
+|-------|-------------|---------|
+| {Actor} | {role & permission} | {entry path, e.g. App → Widget → Portal → API} |
+
+---
+
+## 2. Architecture Overview
+
+### 2.1 High-level Architecture
+
+<!-- ASCII (or mermaid) topology showing the systems this feature touches:
+     client → gateway → service(s) → data stores / external APIs. Keep it to the
+     components THIS PRD actually exercises. Source: architecture.md /
+     project-context.yaml (services, stack). -->
+
+```
+{ASCII or mermaid diagram of the components this feature touches}
+```
+
+> **Note:** {call out which data is fetched live from an external API vs stored in the owned DB, and any cache layer + TTL.}
+
+### 2.2 Communication Patterns
+
+| Pattern | Usage | Scope (UC/SC) |
+|---------|-------|---------------|
+| {Client → Gateway → API} | {auth / action} | {UC1} |
+| {API → External API} | {what it fetches, cache TTL} | {UC1-SC…} |
+
+---
+
+## 3. Data Model
+
+<!-- Source: core-entities.md (owned entities) + BDD Then-clauses (state) + PRD.
+     Distinguish OWNED entities (in the DB) from API-SOURCED models (fetched
+     live, not persisted). List only fields this PRD reads or writes. -->
+
+### 3.1 Entity Design
+
+#### {EntityName} ({DB entity | API-sourced POCO})
+
+{One line: what it represents, and whether it is persisted or fetched live.}
+
+| Field | Type | Usage in {TICKET-ID} |
+|-------|------|----------------------|
+| `{field}` | `{type}` | {how this feature uses it — read/write, which SC} |
+
+<!-- Repeat per entity. If the feature has meaningful state transitions, add a
+     small state table/diagram like below. -->
+
+**State transitions (if any):**
+
+```
+{state A}:  {condition}  → {outcome / UI signal}
+{state B}:  {condition}  → {outcome}
+```
+
+**Constraints:**
+- {invariant enforced in application/DB logic, e.g. exactly one primary per tenant}
+
+### 3.2 Entity Relationships
+
+```
+{relationship diagram — cardinalities, join keys, which fields are read-only vs owned}
+```
+
+### 3.3 Data Source Boundaries
+
+<!-- Crisp statement of what THIS PRD reads vs writes, and what is delegated
+     elsewhere. Prevents scope bleed. -->
+
+**{TICKET-ID} scope: {READ … / WRITE …}.**
+
+| Responsibility | In scope? | Handled by |
+|----------------|-----------|-----------|
+| {read merged list} | ✅ Yes | {endpoint / service} |
+| {write X flag} | ✅ Yes | {service} |
+| {base data} | ❌ Read-only | {external API + cache} |
+| {other module concern} | ❌ No | {module/team} |
+
+### 3.4 Multi-tenant & Sharding
+
+<!-- Only if the project is multi-tenant. Else write "N/A — single tenant". -->
+
+- {tenant key on entities, query-filter isolation, shard resolution — from architecture.md}
+
+---
+
+## 4. API Contracts
+
+<!-- Backend contract. For greenfield: design endpoints from BDD scenarios. For
+     brownfield (@trace.api_source = existing): reverse-document the live API
+     as-is and note gaps vs BDD expectations. Mark REUSE vs NEW explicitly.
+     CLIENT-ONLY PRD (no system/ BDD — this feature owns no backend): do NOT
+     fabricate a BE contract. §4.1 then lists the endpoints the client CONSUMES
+     (external / third-party / another team's / existing), marked "consumed
+     (external)", reverse-documented from the client BDD Then-clauses + PRD;
+     fill §4.2/§4.3 only if the shape is known. If the feature makes no network
+     calls at all → write "N/A — client-only, no backend". §4.5.4 maps client
+     methods to whatever §4.1 lists (or none). -->
+
+
+### 4.1 Endpoints
+
+```
+{METHOD} {/path}          # NEW | REUSE ({source}) — {one-line purpose}
+```
+
+### 4.2 Request/Response Models
+
+<!-- Show DTO shapes in the stack's idiom. Note which fields come from DB vs
+     external API. -->
+
+```{lang}
+{DTO definitions with per-field source comments}
+```
+
+### 4.3 Validation & Error Codes
+
+**Validation rules:**
+
+```{lang}
+{validation rules, in the stack's idiom (e.g. FluentValidation / class-validator)}
+```
+
+| Code | HTTP Status | Description | Trace |
+|------|-------------|-------------|-------|
+| `{ERROR_CODE}` | {4xx/5xx} | {when it fires} | {UC1-SC…} |
+
+### 4.4 Handler Logic (key endpoints)
+
+<!-- For non-trivial writes, spell out the ordered steps (validation →
+     transaction → commit/rollback → return). Keeps the sequence diagram and
+     the code aligned. -->
+
+**{HandlerName}:**
+1. {step}
+2. {step — transaction boundary if any}
+
+### 4.5 UI Component Mapping — {platform} ({framework})
+
+<!-- CLIENT design, GROUPED BY PLATFORM: one "### 4.5 … — {platform}" section per
+     client platform present in the BDD (a web group, an app group). Do NOT title
+     this heading by screen — screens/UCs live in the sub-blocks below.
+     Inside a platform group:
+       • §4.5.1 Component Hierarchy — repeat the sub-block per screen/UC:
+         "#### 4.5.1.x {Screen} — {UC}". A PRD with many screens/UCs → many sub-blocks
+         in the SAME platform group (never a second 4.5 group for the same platform).
+       • §4.5.2–§4.5.5 — likewise per screen/UC where they differ.
+       • §4.5.6 Test Selectors — ONE shared table for the whole platform group; its
+         "Serves SC" column carries (UC · SC) so per-UC consumers filter their rows.
+     Append: new platform → new "### 4.5 — {platform}" group; new screen/UC in an
+     existing platform → add a sub-block + rows to §4.5.6 (don't duplicate the group).
+     Omit §4.5 entirely for a backend-only PRD. -->
+
+> **Source:** {Figma file + node id, from design-spec}
+> **Stack:** {framework, state primitive, component library}
+> <!-- @figma.url: {node-level figma url} -->
+
+#### 4.5.1 Component Hierarchy — {Screen} ({UC})
+
+<!-- Repeat this sub-block per screen/UC in this platform group (4.5.1.a, 4.5.1.b …). -->
+
+```
+{component tree — container vs presentational, conditional children}
+```
+
+#### 4.5.2 Component File Mapping
+
+| Component | Path | Type | Purpose |
+|-----------|------|------|---------|
+| `{Component}` | `{path}` | {Feature/Child} | {responsibility} |
+
+#### 4.5.3 State Management ({state primitive})
+
+<!-- State shape derived from System BDD Then-clauses + response shapes from §4.2.
+     Show derived/computed values and their inputs. -->
+
+```{lang}
+{state declarations with source comments (which BDD field / BE field each maps to)}
+```
+
+#### 4.5.4 API Integration Layer (port/adapter)
+
+<!-- Modal/route config + API-integration map: each client service method → a
+     REAL endpoint from §4.1 (do not invent endpoints). Error → UI state per SC.
+     This table is what /generate-code --phase=integration reads to wire the real adapter. -->
+
+| Client method | Endpoint (§4.1) | Request map | Response → model | Error → UI |
+|---------------|-----------------|-------------|------------------|-----------|
+| {svc.getX()} | {GET /…} | {params} | {DTO → ViewModel} | {4xx → state/toast} |
+
+#### 4.5.5 Figma → Design System Mapping
+
+| Figma element | Design system class/token | Notes |
+|---------------|---------------------------|-------|
+| {element} | {class / token} | {size, color, state} |
+
+#### 4.5.6 Test Selectors — element IDs for actionable elements (QC contract)
+
+<!-- Stable test-id per interactive element so QC locates directly (no runtime
+     scan). Convention: {uc-lower}-{screen}-{element}-{type}; DO NOT embed
+     scenario numbers. Attribute per platform: web data-testid · RN testID ·
+     Flutter Key/Semantics · iOS accessibilityIdentifier. Reuse the same id
+     VALUE across web/app for the same logical element.
+     ONE shared table for the whole platform group (covers every screen/UC of this
+     platform). The "Serves SC" column carries (UC · SC) so a per-UC consumer
+     (generate-code / qc) filters to its own rows via §10. This §4.5 group is
+     already platform-scoped, so the platform is implicit (web block → web · SC). -->
+
+| Test-ID | Element | Component (§4.5.1.x) | Action | Serves SC (UC · SC) |
+|---------|---------|----------------------|--------|---------------------|
+| `{uc}-{screen}-{element}-{type}` | {Submit button} | {Component} | {submit} | {UC1 · SC1, UC1 · SC3} |
+
+---
+
+## 5. Key Flows (Sequence Diagrams)
+
+<!-- ONE mermaid sequence diagram per meaningful scenario. Participants span tiers:
+     client component → service → API → external API → DB.
+     ⚠ SC ids are unique only within (UC × platform): `{UC}-SC1` on `system` and
+     `{UC}-SC1` on `web` are DIFFERENT scenarios. So group flows into PLATFORM LANES
+     (5.A system · 5.B web · 5.C app) and ALWAYS pair the SC with its platform,
+     e.g. "(web · UC1-SC1)". Never write a bare "UC1-SC1" here — it is ambiguous.
+     Only include the lanes whose BDD exists in this PRD. -->
+
+### 5.A System flows
+
+<!-- One diagram per system-BDD scenario. Skip this lane if no system/ BDD. -->
+
+#### 5.A.1 {name} (system · {UC}-SC…)
+
+```mermaid
+sequenceDiagram
+    participant {A} as {Actor}
+    {…}
+```
+
+### 5.B Web flows
+
+<!-- One diagram per web-BDD scenario. Skip this lane if no web/ BDD. -->
+
+#### 5.B.1 {name} (web · {UC}-SC…)
+
+```mermaid
+sequenceDiagram
+    {…}
+```
+
+### 5.C App flows
+
+<!-- One diagram per app-BDD scenario. Skip this lane if no app/ BDD. -->
+
+#### 5.C.1 {name} (app · {UC}-SC…)
+
+```mermaid
+sequenceDiagram
+    {…}
+```
+
+<!-- Number within each lane: 5.A.1, 5.A.2 … / 5.B.1 … / 5.C.1 …. For a scenario
+     whose effect crosses into another module, note "(covered by {OTHER-UC})". -->
+
+**Key integration points (optional table per flow):**
+
+| Step | State transition | Verified by (platform · SC) |
+|------|------------------|-----------------------------|
+| {step} | {before → after} | {web · UC1-SC…} |
+
+---
+
+## 6. Integration Points
+
+| Integration | Direction | Method | Description |
+|-------------|-----------|--------|-------------|
+| {Client → API} | Outbound (client) | {REST/Bearer} | {what} |
+| {API → External} | Outbound (server) | {REST + header} | {what, cache TTL} |
+
+### 6.1 Event Bus / Messaging
+
+<!-- Kafka/queue events produced/consumed by this feature. "N/A — no events" if none. -->
+
+{events, or N/A}
+
+### 6.2 Cross-Service Dependencies
+
+| Dependent service | What's needed | Contract | Status |
+|-------------------|---------------|----------|--------|
+| {service} | {need} | {endpoint} | {✅ Exists / ⚠️ pending} |
+
+---
+
+## 7. Security & Authorization
+
+### 7.1 Authentication
+
+{Auth flow + token type/TTL. Source: PRD auth + project rules.}
+
+### 7.2 Authorization Rules
+
+| Action | Required role/permission | Description | Trace |
+|--------|--------------------------|-------------|-------|
+| {action} | {role} | {how enforced, where} | {UC1-SC… / out of scope} |
+
+---
+
+## 8. Error Handling & Edge Cases
+
+<!-- One row per error / edge / negative scenario in the BDD. This must line up
+     with §4.3 error codes and the §5 error sequence diagrams. -->
+
+| Scenario | Strategy | Details | Trace |
+|----------|----------|---------|-------|
+| {condition} | {approach} | {behavior, message, side effect} | {UC1-SC…, BR…} |
+
+---
+
+## 9. Design Decisions
+
+<!-- The "why" behind non-obvious choices, with alternatives considered. Source:
+     PRD alternatives/assumptions + reasoning during generation. This is what lets
+     a reviewer trust the design. -->
+
+| # | Decision | Rationale | Alternatives considered |
+|---|----------|-----------|-------------------------|
+| 1 | **{decision}** | {why} | {alt — why rejected} |
+
+### NFR-to-Design Mapping
+
+| NFR category | PRD requirement | Design decision |
+|--------------|-----------------|-----------------|
+| {e.g. Multi-tenant isolation} | {requirement} | {mechanism} |
+
+---
+
+## 10. UC Coverage
+
+<!-- THE APPEND ANCHOR **and the INDEX for per-UC consumers**. Every UC of the PRD
+     gets a row; every scenario maps to the section(s) that design it.
+     - /generate-tech-docs uses it to detect what is already covered vs missing.
+     - /generate-code, /map-testids, /qc-* work on ONE UC of a PRD-level doc — they
+       look this UC up HERE first to locate its scenarios → the sections/§5-lanes
+       (and thus the §4.1 endpoints its §5 flows call) that belong to it. Don't
+       pull another UC's endpoints/sections.
+     ⚠ Scenario coverage is keyed by (platform, SC) because SC ids repeat across
+     platforms — the Platform column disambiguates. -->
+
+| UC | Feature | Platforms | Sections covered | Status |
+|----|---------|-----------|------------------|--------|
+| {TICKET-ID}-UC1 | {title} | {system, web, app} | §… | ✅ Covered |
+
+### UC1 Scenario Coverage
+
+<!-- One row per (platform, SC). Same SC number on different platforms = different
+     scenarios → separate rows. -->
+
+| Platform | Scenario | Section | Business rule |
+|----------|----------|---------|---------------|
+| system | {UC}-SC1: {name} | §5.A.1 | {BR…} |
+| web | {UC}-SC1: {name} | §4.5 (web), §5.B.1 | {BR…} |
+
+<!-- Repeat a scenario-coverage block per UC. -->
+
+---
+
+## 11. Cross-cutting & Assumptions (Out-of-Scope Reference)
+
+<!-- Upstream concerns this PRD DEPENDS ON but does not implement (admin gate,
+     downstream UI in another module, order snapshotting…). Keep for cross-team
+     context. Reference the owning UC/team + doc. Source: PRD out-of-scope +
+     BDD BR "out of scope" notes. -->
+
+### 11.1 {Concern}
+
+> {Quote the BDD/PRD line that scopes it out.}
+
+{Explanation of the boundary + a reference sequence diagram if useful.}
+
+**Owned by:** {team / module}. See {link}.
+
+---
+
+## 12. GAP Register — ẩn số thiết kế chưa chốt
+
+<!--
+  Mọi [GAP: Gn] / [ASSUMPTION: An] đánh dấu inline trong doc PHẢI có đúng MỘT dòng ở đây
+  (và ngược lại — không marker mồ côi, không dòng thừa). Đây là sổ quản lý vòng đời ẩn số.
+
+  - Loại:
+      • nội tại      — BE tự quyết (đóng: BE điền giá trị, thay marker)
+      • cross-service — cần team/partner khác (đóng: qua T7 sign-off của owner)
+      • spec-defect  — BDD/PRD sai/thiếu (KHÔNG tự đóng: escalate PO sửa .feature/PRD → regen; xem §9 Conflict)
+  - Severity:
+      • 🔴 blocker    — code BẮT BUỘC phải có mới đúng → CHẶN approve
+      • 🟢 non-blocker — đoán tạm chạy được, chỉ cần confirm → không chặn
+    (Nhãn GAP/ASSUMPTION KHÔNG tự quyết severity — một ASSUMPTION vẫn có thể là blocker nếu đoán sai sẽ vỡ.)
+  - Status: open → resolved (owner điền giá trị thật → thay marker inline → bump @trace.revision).
+
+  GATE: còn ≥1 🔴 blocker ở trạng thái `open` → @trace.status KHÔNG được lên `approved`
+        (giữ `in-review`) → generate-code bị chặn. Cùng pattern design-spec giữ `draft` khi còn ❌ Missing.
+-->
+
+| id | Dùng ở (§) | Điều chưa biết | Loại | Owner confirm | Severity | Status | Đóng thế nào |
+|----|-----------|----------------|------|---------------|----------|--------|--------------|
+| G1 | {§4.3} | {shape lỗi khi partner từ chối} | cross-service | {team-payment} | 🔴 blocker | open | {T7 sign-off — owner cung cấp contract} |
+| A1 | {§4.1} | {timeout mặc định 30s} | nội tại | {BE lead} | 🟢 non-blocker | open | {BE xác nhận, thay giá trị} |
+
+> Nếu doc **không có** ẩn số nào → ghi "Không có — mọi thiết kế đều có nguồn." **KHÔNG** bịa dòng để lấp trống.
+
+---
+
+## Figma Design References
+
+<!-- @figma.url: {node-level figma url per screen} -->
+- {Screen}: [Figma — {frame}]({url})
+- Exported: {YYYY-MM-DD}
+
+---
+
+## Changelog
+
+| Revision | Date | Changes |
+|----------|------|---------|
+| 1 | {YYYY-MM-DD} | Initial generation from {TICKET-ID} BDD (v{bdd_version}): {list UCs covered} |
+<!-- On append: add a row per extension, e.g. "2 | {date} | Added UC3 (§5.9, §10) from new BDD v{n}" -->