qfai 1.2.6 → 1.2.8

package/README.md

@@ -62,6 +62,7 @@ QFAI includes a small set of custom prompts (stored under `.qfai/assistant/promp
 - **qfai-require**: Produce `require.md` in the requirements directory from your idea or discussion output.
 - **qfai-spec**: Produce `.qfai/specs/*` and `.qfai/contracts/*` from the requirements, including traceability scaffolding.
   - Includes a preflight step that bootstraps missing `qfai.config.yaml` and `assistant/steering/*` when run directly after init.
+- **qfai-prototyping**: Implement a minimal runnable skeleton (UI + API + DB) from contracts before test automation. Run after `/qfai-spec` to ensure the app is runnable with `pnpm dev` (or equivalent) before writing tests.
 - **qfai-atdd**: Implement acceptance tests (E2E/API/Integration) and drive Scenario Coverage to 100% using a Coverage Ledger.
 - **qfai-tdd-red**: Implement fast tests first (unit/component) and drive Unit/Component Scenario Coverage to 100% using a Coverage Ledger.
 - **qfai-tdd-green**: Implement production code to make the tests pass.
@@ -104,6 +105,11 @@ AG->>Q: Read .qfai/assistant/prompts/qfai-spec.md
 AG->>R: Create specs + contracts + scenario.feature
 AG-->>U: SDD artifacts ready
 
+U->>AG: Run /qfai-prototyping
+AG->>Q: Read .qfai/assistant/prompts/qfai-prototyping.md
+AG->>R: Implement minimal runnable skeleton (UI + API + DB)
+AG-->>U: Runnable prototype ready (dev server starts)
+
 U->>AG: Run /qfai-atdd
 AG->>Q: Read .qfai/assistant/prompts/qfai-atdd.md
 AG->>R: Implement acceptance tests

package/assets/init/.qfai/README.md

@@ -1,60 +1,100 @@
-# .qfai
+# .qfai (QFAI Workspace)
 
 ## Purpose
 
-`.qfai` is the workspace where QFAI artifacts live so requirements, contracts, specs, and reports stay aligned.
+`.qfai/` is the **single workspace** for QFAI artifacts so that requirements, contracts, spec packs, and automation stay aligned and traceable.
 
-## What belongs here
+This folder is generated by `qfai init`. It is designed to be:
 
-- Assistant assets (prompts, instructions, steering, roles)
-- Requirements (single requirements document)
-- Contracts (api/db/ui)
-- Spec packs (spec.md, delta.md, scenario.feature)
-- Evidence files (prompt completion records)
-- Generated reports (validate/report/doctor outputs)
+- **predictable** (stable file layout),
+- **reviewable** (human-readable Markdown/YAML/SQL),
+- **machine-checkable** (validators enforce minimal structural rules).
 
-## What does not belong here
+## Recommended QFAI sequence (project)
 
-- Application source code
-- Generated tests or build artifacts
-- Ad-hoc notes outside the defined structure
+```mermaid
+flowchart TD
+  A[/qfai-discuss/] --> B[/qfai-require/]
+  B --> C[/qfai-spec/]
+  C --> D[/qfai-prototyping/]
+  D --> E[/qfai-atdd/]
+  E --> F[/qfai-tdd-red/]
+  F --> G[/qfai-tdd-green/]
+  G --> H[/qfai-tdd-refactor/]
+```
+
+> Formatting MUST follow the templates in each directory README.
+> Do not invent per-file formats.
 
-## Structure (overview)
+## Directory map
 
 ```text
 .qfai/
-  README.md
-  assistant/
-    agents/
-    instructions/
-    prompts/
-    prompts.local/
-    steering/
-  contracts/
-    README.md
-    api/
-    db/
-    ui/
-  require/
-    README.md
-    <requirements document created by /qfai-require>
-  evidence/
-    <prompt evidence files>
-  specs/
-    README.md
-    <spec packs>
-  report/
-    <generated by qfai validate/report/doctor>
+├── README.md
+├── assistant/
+│   ├── prompts/            # canonical prompts (SSOT)
+│   ├── prompts.local/      # minimal overrides (project-specific)
+│   ├── agents/             # sub-agent missions / guardrails
+│   ├── steering/           # project steering (inputs for prompts)
+│   └── instructions/       # tool/integration instructions
+├── require/
+│   ├── README.md
+│   └── require.md          # single requirements document
+├── contracts/
+│   ├── README.md
+│   ├── api/README.md       # OpenAPI YAML style guide
+│   ├── db/README.md        # SQL contracts style guide
+│   └── ui/README.md        # UI contract YAML style guide
+├── specs/
+│   ├── README.md
+│   └── spec-0001/
+│       ├── spec.md
+│       ├── delta.md
+│       ├── scenario.feature
+│       ├── case-catalogue.md
+│       └── traceability-matrix.md
+└── evidence/
+    ├── README.md
+    └── <prompt>-<run>.md   # completion evidence (gitignored by default)
 ```
 
-## Operating rules
+## Rules (global)
+
+### R1. README-as-SSOT for formatting
+
+Each directory `README.md` defines:
+
+- required files,
+- canonical **template**,
+- realistic **sample**,
+- quality checklist,
+- anti-patterns.
+
+All custom prompts must:
+
+1. read the relevant directory README(s),
+2. generate artifacts matching their templates,
+3. run a self-check before declaring completion.
+
+### R2. Evidence is not versioned by default
+
+Evidence under `.qfai/evidence/` is **gitignored by default** (see repository `.gitignore` and/or project `.git/info/exclude`).
+
+- Evidence is still useful locally and in PR review (attach or paste snippets), but it should not pollute version control.
+
+### R3. Keep artifacts atomic
+
+- Prefer many small, stable identifiers (REQ/BR/AC/CASE/SC) over long paragraphs that hide multiple rules.
+- If a statement contains multiple independent “must” clauses, split it.
+
+### R4. Do not put templates in prompts
 
-- READMEs are reference guides; do not edit them during execution. Raise Open Questions instead.
-- Create new artifacts only in the intended directories.
-- Always run the repo's gates before declaring completion.
+Templates/samples MUST live only in `.qfai/**/README.md`.
+Prompts only **reference** them to avoid double maintenance.
 
-## Checklist
+## Where to look next
 
-- [ ] I used the correct directory for each artifact
-- [ ] I did not edit README files
-- [ ] I ran the repository gate commands and recorded results
+- Requirements format: `require/README.md`
+- Contracts format: `contracts/README.md` and sub-READMEs
+- Spec pack format: `specs/README.md`
+- Evidence rules: `evidence/README.md`

package/assets/init/.qfai/assistant/prompts/qfai-atdd.md

@@ -18,6 +18,17 @@ mode: execution-focused
 
 # /qfai-atdd — Implement Automated Acceptance Tests (ATDD)
 
+## FORMAT SSOT (Mandatory)
+
+- **Before writing or editing any `.qfai/**` artifact\*\*, read and follow the relevant directory README template and sample:
+  - `.qfai/require/README.md`
+  - `.qfai/specs/README.md`
+  - `.qfai/contracts/**/README.md`
+  - `.qfai/evidence/README.md`
+- **Do NOT copy** templates/samples into this prompt or into other prompt markdown.
+- The generated artifacts must match the README-defined structure (headings, ordering, table columns).
+- Completion requires a **Format Self-Check** in the evidence: list each artifact and confirm “matches README template”.
+
 ## CRITICAL CONSTRAINTS (Read First)
 
 - Do NOT declare completion based on unit/component tests.

package/assets/init/.qfai/assistant/prompts/qfai-configure.md

@@ -18,6 +18,17 @@ mode: evidence-focused
 
 # /qfai-configure - Configure QFAI for this repository
 
+## FORMAT SSOT (Mandatory)
+
+- **Before writing or editing any `.qfai/**` artifact\*\*, read and follow the relevant directory README template and sample:
+  - `.qfai/require/README.md`
+  - `.qfai/specs/README.md`
+  - `.qfai/contracts/**/README.md`
+  - `.qfai/evidence/README.md`
+- **Do NOT copy** templates/samples into this prompt or into other prompt markdown.
+- The generated artifacts must match the README-defined structure (headings, ordering, table columns).
+- Completion requires a **Format Self-Check** in the evidence: list each artifact and confirm “matches README template”.
+
 ## CRITICAL CONSTRAINTS (Read First)
 
 - Only update `qfai.config.yaml`, `.qfai/assistant/steering/*`, and `.qfai/evidence/configure-<run-id>.md` unless explicitly asked.

package/assets/init/.qfai/assistant/prompts/qfai-discuss.md

@@ -18,6 +18,17 @@ mode: interactive-by-default
 
 # /qfai-discuss — Discussion → Requirements Clarity
 
+## FORMAT SSOT (Mandatory)
+
+- **Before writing or editing any `.qfai/**` artifact\*\*, read and follow the relevant directory README template and sample:
+  - `.qfai/require/README.md`
+  - `.qfai/specs/README.md`
+  - `.qfai/contracts/**/README.md`
+  - `.qfai/evidence/README.md`
+- **Do NOT copy** templates/samples into this prompt or into other prompt markdown.
+- The generated artifacts must match the README-defined structure (headings, ordering, table columns).
+- Completion requires a **Format Self-Check** in the evidence: list each artifact and confirm “matches README template”.
+
 ## CRITICAL CONSTRAINTS (Read First)
 
 - Do NOT declare completion without covering all Required Coverage topics.

package/assets/init/.qfai/assistant/prompts/qfai-prototyping.md

@@ -0,0 +1,157 @@
+<!--
+QFAI Prompt Body (SSOT)
+- This file is intended to be referenced by tool-specific custom prompt definitions (e.g., Copilot .prompt.md, Claude Code slash commands).
+- Keep tool-specific wrappers thin: "Read this file and follow it."
+-->
+
+---
+
+id: qfai-prototyping
+title: QFAI Prototyping (Implement a runnable contract skeleton)
+description: "Implement a minimal end-to-end runnable skeleton (UI + API + DB) based on contracts, before ATDD/TDD automation."
+argument-hint: "<spec-id> [--auto]"
+allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
+roles: [FullStackEngineer, BackendEngineer, FrontendEngineer, DBEngineer, DevOpsCIEngineer, QAEngineer, CodeReviewer]
+mode: execution-focused
+
+---
+
+# /qfai-prototyping
+
+Build a **minimum runnable vertical slice** from `.qfai/contracts/**` so that:
+
+- developers can start the app locally (`pnpm dev` or equivalent),
+- the UI is navigable (no 404 on routes declared in UI contracts),
+- the API responds for paths declared in OpenAPI contracts,
+- persistence exists at least as a working skeleton (real DB or a clearly marked temporary store),
+- the project is ready for `/qfai-atdd` automation.
+
+## FORMAT SSOT (Mandatory)
+
+- **Before writing or editing any `.qfai/**` artifact\*\*, read and follow the relevant directory README template and sample:
+  - `.qfai/require/README.md`
+  - `.qfai/specs/README.md`
+  - `.qfai/contracts/**/README.md`
+  - `.qfai/evidence/README.md`
+- **Do NOT copy** templates/samples into this prompt or into other prompt markdown.
+- The generated artifacts must match the README-defined structure (headings, ordering, table columns).
+- Completion requires a **Format Self-Check** in the evidence: list each artifact and confirm "matches README template".
+
+## CRITICAL CONSTRAINTS (Read First)
+
+- Do NOT implement acceptance tests or unit tests (that is `/qfai-atdd` and TDD phases).
+- You MUST produce the required evidence file: `.qfai/evidence/prototyping-<spec-id>.md`.
+  - `.qfai/evidence/` is intentionally NOT tracked by Git (it ships with a local `.gitignore`).
+  - Do NOT commit evidence files; summarize key outcomes in the PR description instead.
+- You MUST run the dev server and perform manual verification.
+- You MUST stop and escalate if runtime evidence or contract alignment is missing.
+- Implementation must align with existing project conventions; do NOT introduce new frameworks.
+- Completion must be approved by a reviewer who did not implement the code.
+
+## Inputs (read first)
+
+- `.qfai/contracts/ui/*.yaml` (routes/screens/elements/actions)
+- `.qfai/contracts/api/*.yaml` (OpenAPI)
+- `.qfai/contracts/db/*.sql` (schema constraints)
+- `.qfai/specs/<spec-id>/spec.md` + `delta.md` (scope + decisions)
+- `.qfai/specs/<spec-id>/scenario.feature` (for “what users do”, but do NOT implement tests here)
+
+## Output boundaries
+
+- ✅ You MAY implement application code required for a runnable skeleton.
+- ✅ You MAY add minimal wiring/config (env examples, local DB setup scripts, dev server config).
+- ✅ You MAY add minimal “smoke scripts” (e.g., `scripts/smoke.ts`) if they help manual verification.
+- ❌ Do NOT implement acceptance tests here (that is `/qfai-atdd`).
+- ❌ Do NOT implement unit/component tests here (that is TDD phases).
+- ❌ Do NOT change `.qfai/**/README.md` content. They are templates and remain SSOT.
+
+## Mission (what “prototype” means)
+
+Implement the following **contract-satisfying skeleton**, aiming for the smallest viable integration:
+
+### 1) UI skeleton
+
+- For every screen/route in `contracts/ui/*.yaml`:
+  - create a page/route that renders and is reachable,
+  - include placeholder components for declared elements (table/input/button),
+  - implement declared navigation actions (links/buttons).
+
+### 2) API skeleton
+
+- For every endpoint in `contracts/api/*.yaml` used by the spec pack:
+  - implement the route handler,
+  - return realistic stub responses aligned with schemas,
+  - implement minimal error shape (e.g., validation error payload) if contracts imply it.
+
+### 3) DB skeleton
+
+- Apply or integrate the SQL contracts:
+  - if project uses migrations: add migration(s) from `contracts/db/*.sql`,
+  - else: create schema setup script with explicit instructions.
+- If using a temporary in-memory store initially, it MUST be:
+  - documented in code comments,
+  - shaped to match the DB contract schema,
+  - replaceable by real DB without rewriting the whole app.
+
+### 4) Wiring & dev experience
+
+- Ensure local startup works:
+  - `pnpm install`
+  - `pnpm dev`
+- Add or update minimal documentation under project README (outside `.qfai/`) if needed for running the skeleton.
+
+## Work process (required)
+
+1. **Inventory contracts**: list UI routes, API endpoints, DB tables/constraints.
+2. **Select minimal implementation strategy** based on detected stack:
+   - If Next.js/React: implement pages and API routes accordingly.
+   - If Express/Fastify/etc: implement server routes and connect frontend.
+   - If unknown: choose the project’s existing conventions; do not introduce a new stack.
+3. Implement UI routes first (avoid 404).
+4. Implement API endpoints next (return stub JSON).
+5. Implement DB skeleton and connect (or provide clear temporary store).
+6. Run the dev server and perform a manual “happy path” click-through.
+
+## Completion criteria (hard gate)
+
+You may declare completion ONLY if:
+
+- [ ] Dev server starts locally without errors (`pnpm dev` or project equivalent).
+- [ ] All UI routes declared in UI contracts are reachable (no 404).
+- [ ] At least one end-to-end happy path works in the UI:
+  - list screen loads data (stub OK),
+  - create/edit screen submits and updates list (stub OK),
+  - navigation works.
+- [ ] All implemented API endpoints respond with status codes consistent with the contract.
+- [ ] Evidence file exists: `.qfai/evidence/prototyping-<spec-id>.md`
+  - includes executed commands,
+  - includes “Format Self-Check”,
+  - includes a short manual verification log.
+
+## Reviewer checklist (for CodeReviewer role)
+
+- No test automation was added here.
+- Implementation aligns with project conventions (no new framework added).
+- UI/API/DB skeleton matches contract definitions.
+- Completion criteria are objectively satisfied.
+
+## Evidence (MANDATORY)
+
+- Create evidence file: `.qfai/evidence/prototyping-<spec-id>.md`
+- Include the following sections:
+  1. **Contract Inventory**: list of UI routes, API endpoints, DB tables from contracts.
+  2. **Implementation Summary**: what was implemented for each contract item.
+  3. **Dev Server Startup**: commands executed and result.
+  4. **Manual Verification Log**: step-by-step click-through with observations.
+  5. **Format Self-Check**: list each artifact and confirm "matches README template".
+
+## FINAL CHECKLIST (Check Last)
+
+- [ ] CRITICAL CONSTRAINTS were followed.
+- [ ] Evidence file exists: `.qfai/evidence/prototyping-<spec-id>.md`.
+- [ ] Dev server starts without errors.
+- [ ] All UI routes from contracts are reachable (no 404).
+- [ ] All API endpoints respond with expected status codes.
+- [ ] Manual verification log is complete.
+- [ ] No test automation was added.
+- [ ] Completion approved by a reviewer who did not implement the code.

package/assets/init/.qfai/assistant/prompts/qfai-require.md

@@ -18,6 +18,17 @@ mode: approval-gated
 
 # /qfai-require — Create Requirements Artifact
 
+## FORMAT SSOT (Mandatory)
+
+- **Before writing or editing any `.qfai/**` artifact\*\*, read and follow the relevant directory README template and sample:
+  - `.qfai/require/README.md`
+  - `.qfai/specs/README.md`
+  - `.qfai/contracts/**/README.md`
+  - `.qfai/evidence/README.md`
+- **Do NOT copy** templates/samples into this prompt or into other prompt markdown.
+- The generated artifacts must match the README-defined structure (headings, ordering, table columns).
+- Completion requires a **Format Self-Check** in the evidence: list each artifact and confirm “matches README template”.
+
 ## CRITICAL CONSTRAINTS (Read First)
 
 - Keep `require.md` headings in English and follow the template exactly.

package/assets/init/.qfai/assistant/prompts/qfai-spec.md

@@ -18,6 +18,17 @@ mode: approval-gated
 
 # /qfai-spec — Create Specification Pack (SDD)
 
+## FORMAT SSOT (Mandatory)
+
+- **Before writing or editing any `.qfai/**` artifact\*\*, read and follow the relevant directory README template and sample:
+  - `.qfai/require/README.md`
+  - `.qfai/specs/README.md`
+  - `.qfai/contracts/**/README.md`
+  - `.qfai/evidence/README.md`
+- **Do NOT copy** templates/samples into this prompt or into other prompt markdown.
+- The generated artifacts must match the README-defined structure (headings, ordering, table columns).
+- Completion requires a **Format Self-Check** in the evidence: list each artifact and confirm “matches README template”.
+
 ## CRITICAL CONSTRAINTS (Read First)
 
 - Contracts MUST be completed first; do not write spec/scenario before contracts.

package/assets/init/.qfai/assistant/prompts/qfai-tdd-green.md

@@ -18,6 +18,17 @@ mode: iterative
 
 # /qfai-tdd-green — Implement to Green (TDD)
 
+## FORMAT SSOT (Mandatory)
+
+- **Before writing or editing any `.qfai/**` artifact\*\*, read and follow the relevant directory README template and sample:
+  - `.qfai/require/README.md`
+  - `.qfai/specs/README.md`
+  - `.qfai/contracts/**/README.md`
+  - `.qfai/evidence/README.md`
+- **Do NOT copy** templates/samples into this prompt or into other prompt markdown.
+- The generated artifacts must match the README-defined structure (headings, ordering, table columns).
+- Completion requires a **Format Self-Check** in the evidence: list each artifact and confirm “matches README template”.
+
 ## CRITICAL CONSTRAINTS (Read First)
 
 - Do NOT declare completion based on tests alone.

package/assets/init/.qfai/assistant/prompts/qfai-tdd-red.md

@@ -18,6 +18,17 @@ mode: test-first
 
 # /qfai-tdd-red — Implement Tests First (TDD Red)
 
+## FORMAT SSOT (Mandatory)
+
+- **Before writing or editing any `.qfai/**` artifact\*\*, read and follow the relevant directory README template and sample:
+  - `.qfai/require/README.md`
+  - `.qfai/specs/README.md`
+  - `.qfai/contracts/**/README.md`
+  - `.qfai/evidence/README.md`
+- **Do NOT copy** templates/samples into this prompt or into other prompt markdown.
+- The generated artifacts must match the README-defined structure (headings, ordering, table columns).
+- Completion requires a **Format Self-Check** in the evidence: list each artifact and confirm “matches README template”.
+
 ## CRITICAL CONSTRAINTS (Read First)
 
 - You MUST implement tests only. Do NOT implement production logic.

package/assets/init/.qfai/assistant/prompts/qfai-tdd-refactor.md

@@ -18,6 +18,17 @@ mode: refactor
 
 # /qfai-tdd-refactor — Refactor Safely (TDD Refactor)
 
+## FORMAT SSOT (Mandatory)
+
+- **Before writing or editing any `.qfai/**` artifact\*\*, read and follow the relevant directory README template and sample:
+  - `.qfai/require/README.md`
+  - `.qfai/specs/README.md`
+  - `.qfai/contracts/**/README.md`
+  - `.qfai/evidence/README.md`
+- **Do NOT copy** templates/samples into this prompt or into other prompt markdown.
+- The generated artifacts must match the README-defined structure (headings, ordering, table columns).
+- Completion requires a **Format Self-Check** in the evidence: list each artifact and confirm “matches README template”.
+
 ## CRITICAL CONSTRAINTS (Read First)
 
 - Do NOT change externally visible behavior or specs/contracts.

package/assets/init/.qfai/assistant/prompts/qfai-verify.md

@@ -18,6 +18,17 @@ mode: evidence-focused
 
 # /qfai-verify — Quality Gates and Evidence
 
+## FORMAT SSOT (Mandatory)
+
+- **Before writing or editing any `.qfai/**` artifact\*\*, read and follow the relevant directory README template and sample:
+  - `.qfai/require/README.md`
+  - `.qfai/specs/README.md`
+  - `.qfai/contracts/**/README.md`
+  - `.qfai/evidence/README.md`
+- **Do NOT copy** templates/samples into this prompt or into other prompt markdown.
+- The generated artifacts must match the README-defined structure (headings, ordering, table columns).
+- Completion requires a **Format Self-Check** in the evidence: list each artifact and confirm “matches README template”.
+
 ## CRITICAL CONSTRAINTS (Read First)
 
 - Do NOT declare completion without running the defined gates.

package/assets/init/.qfai/assistant/prompts.local/README.md

@@ -2,21 +2,14 @@
 
 ## Purpose
 
-Allow minimal overrides of canonical prompts when project-specific constraints cannot be captured in steering.
+`prompts.local/` allows **minimal overrides** of canonical prompts when project constraints cannot be expressed via steering.
 
 ## Rules
 
 - Keep diffs minimal and focused.
-- File name must match the canonical prompt name.
-- Do not copy the full canonical prompt into this folder.
-
-## Structure
-
-```text
-prompts.local/
-  README.md
-  <prompt>.md
-```
+- File name must match the canonical prompt name (e.g. `qfai-atdd.md`).
+- Do not copy the entire canonical prompt into this folder.
+- Overrides MUST still respect: README-as-SSOT for formatting.
 
 ## Override template (excerpt)
 
@@ -30,10 +23,8 @@ prompts.local/
 ## Rationale
 
 - <why steering cannot cover this>
-```
 
-## Checklist
+## Additional constraints
 
-- [ ] Override is strictly necessary
-- [ ] Steering cannot express the constraint
-- [ ] The change does not conflict with validation/verification gates
+- <any extra constraints>
+```

package/assets/init/.qfai/contracts/README.md

@@ -2,38 +2,45 @@
 
 ## Purpose
 
-Contracts define the API/DB/UI surface that specs and scenarios may reference. Contracts must be created before specs.
+Contracts define the **stable surface** that specs and tests may reference.
+They are the boundary between “what we promise” and “how we implement”.
 
-## What belongs here
+QFAI organizes contracts into three types:
 
-- contracts/api (YAML)
-- contracts/db (SQL)
-- contracts/ui (YAML)
-
-## What does not belong here
+```text
+contracts/
+├── api/   # OpenAPI YAML (endpoints, request/response)
+├── db/    # SQL schema contracts (tables, columns, constraints)
+└── ui/    # UI contract YAML (screens, elements, user actions)
+```
 
-- categories beyond api/db/ui
-- implementation code or tests
-- markdown embedded inside YAML/SQL
+## Directory rules
 
-## Structure
+- Contract files are **minimal**: only what specs actually need.
+- Each contract file must declare `QFAI-CONTRACT-ID` at the top.
+- Prefer additive changes; breaking changes require delta notes.
 
 ```text
 contracts/
-  README.md
-  api/
-    README.md
-    <api contracts>
-  db/
-    README.md
-    <db contracts>
-  ui/
-    README.md
-    <ui contracts>
+├── README.md
+├── api/
+│   ├── README.md
+│   └── api-0001-<slug>.yaml
+├── db/
+│   ├── README.md
+│   └── db-0001-<slug>.sql
+└── ui/
+    ├── README.md
+    └── ui-0001-<slug>.yaml
 ```
 
+## How contracts relate to specs
+
+- `spec.md` and `scenario.feature` reference contracts via `QFAI-CONTRACT-REF`.
+- Traceability must include “Contracts” in the chain table.
+
 ## Checklist
 
-- [ ] Contracts exist before specs reference them
-- [ ] Only api/db/ui categories are used
-- [ ] Each contract file declares QFAI-CONTRACT-ID
+- [ ] Contract IDs exist and are unique.
+- [ ] Contracts match what specs reference (no missing IDs).
+- [ ] Contracts are minimal but sufficient for prototyping and test automation.