qfai 1.4.23 → 1.4.25

package/README.md

@@ -210,7 +210,7 @@ flowchart LR
 - Contracts SSOT: `.qfai/contracts/**`
 - Report outputs (`.qfai/report/**`) are derived artifacts and not SSOT.
 
-## Minimal tutorial (v1.4.23)
+## Minimal tutorial (v1.4.25)
 
 1. `npx qfai init`
 2. Run `/qfai-discuss` to structure scope and open questions.
@@ -237,8 +237,8 @@ Release gate behavior:
 
 ## Continuous integration
 
-QFAI v1.4.23 generates `.github/**` only for Copilot integration wrappers
-(`.github/prompts`, `.github/agents`).
+QFAI v1.4.25 generates integration wrappers under `.agents/**`, `.claude/**`,
+`.github/**`, and `.codex/**`.
 It does not generate GitHub Actions workflows.
 Configure CI in your own platform and run:
 
@@ -272,6 +272,11 @@ Typical customizations.
 
 ```text
 .
+├── .agents
+│   ├── README.md
+│   └── skills
+│       └── qfai-configure
+│           └── SKILL.md
 ├── .qfai
 │   ├── assistant
 │   │   ├── agents
@@ -374,6 +379,7 @@ Typical customizations.
 
 Integration wrappers are also generated for immediate use:
 
+- Agents/Codex VS Code: `.agents/skills/**`
 - Claude Code: `.claude/commands/**`, `.claude/agents/**`
 - GitHub Copilot: `.github/prompts/**`, `.github/agents/**`
 - Codex: `.codex/skills/**`
@@ -381,7 +387,7 @@ Integration wrappers are also generated for immediate use:
 ## Agent integrations
 
 `npx qfai init` installs canonical skills under `.qfai/assistant/skills/**` (SSOT)
-and generates thin wrapper assets for Copilot / Claude Code / Codex.
+and generates thin wrapper assets for Agents/Codex VS Code / Copilot / Claude Code / Codex.
 If wrapper assets drift from canonical skills, rerun `npx qfai init --force` to resync.
 
 ## Contributing (for QFAI maintainers)

package/assets/init/.qfai/assistant/agents/coverage-planner.md

@@ -3,21 +3,27 @@
 ## Mission
 
 - Define and maintain coverage ledgers to prevent silent gaps.
+- Convert coverage findings into actionable, perspective-based EX/TC planning.
 
 ## Inputs you must read
 
 - .qfai/assistant/instructions/\*
 - .qfai/assistant/steering/\*
-- .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
-- .qfai/specs/spec-\*/scenario.feature
-- .qfai/specs/spec-\*/spec.md
+- .qfai/specs/spec-\*/09_delta.md (Decision Records; check rejected)
+- .qfai/specs/spec-\*/04_Business-Rules.md
+- .qfai/specs/spec-\*/05_Examples.md
+- .qfai/specs/spec-\*/06_Test-Cases.md
+- .qfai/report/validate.log
+- .qfai/report/specs-coverage/spec-\*.md
 - Existing coverage ledgers and test files
 
 ## Deliverables (MANDATORY)
 
 - Decision Records referenced (DR-IDs) + rejected check (or RE-OPEN request)
+- Hard-gap list (`QFAI-COV-201/202/203/204/205/206`) with source-layer fixes
+- Density-smell list (for example `QFAI-COV-207`) with perspective-based improvement ideas
 - Scope ledger (what must be tested) with exclusions rationale
-- Coverage ledger mapped to scenarios and layers
+- Coverage ledger mapped to BR/EX/TC layers
 - Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
 
 ## Stop conditions (Blockers)
@@ -25,7 +31,7 @@
 - Rejected option would be reintroduced without RE-OPEN DR
 - Hidden exclusions or silent gaps detected
 - Evidence is missing or incomplete
-- Scenario mapping is ambiguous
+- BR/EX/TC mapping is ambiguous
 
 ## Sign-off checklist (Check Last)
 
@@ -38,7 +44,10 @@
 
 - Decision Records (DR-IDs) / rejected check
 - Findings
+- Hard gaps (`QFAI-COV-201..206`)
+- Density smells (`QFAI-COV-207` and similar)
 - Coverage ledger
+- Perspective-based EX/TC proposal (boundary, negative, permission, state)
 - Exclusions rationale
 - Evidence summary
 - Open Questions / Risks

package/assets/init/.qfai/assistant/agents/qa-gatekeeper.md

@@ -9,8 +9,13 @@
 
 - .qfai/assistant/instructions/\*
 - .qfai/assistant/steering/\*
-- .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
+- .qfai/specs/spec-\*/09_delta.md (Decision Records; check rejected)
+- .qfai/specs/spec-\*/04_Business-Rules.md
+- .qfai/specs/spec-\*/05_Examples.md
+- .qfai/specs/spec-\*/06_Test-Cases.md
 - QA evidence summaries under `.qfai/evidence/` (gitignored)
+- .qfai/report/validate.log
+- .qfai/report/specs-coverage/spec-\*.md
 - Coverage ledgers and traceability reports
 - Gate command outputs
 
@@ -19,6 +24,8 @@
 - Decision Records referenced (DR-IDs) + rejected check (or RE-OPEN request)
 - DONE declaration check (inputs + DR-IDs + rejected guard)
 - Gate status (PASS/FAIL) with rationale
+- Hard gate result summary (`QFAI-COV-201..206`)
+- Density-smell review notes (`QFAI-COV-207` and related warnings)
 - Explicit gap list and required fixes
 - Evidence presence check summary
 
@@ -27,6 +34,7 @@
 - Rejected option would be reintroduced without RE-OPEN DR
 - Evidence is missing or incomplete
 - Coverage ledger is missing or inconsistent
+- Validate gate is missing/failing (`qfai validate --fail-on error --format github`)
 - Runtime or quality gates are not executed
 
 ## Sign-off checklist (Check Last)
@@ -41,6 +49,8 @@
 - Decision Records (DR-IDs) / rejected check
 - Gate decision (PASS/FAIL)
 - Findings
+- Hard gate status (`QFAI-COV-201..206`)
+- Density-smell review (`QFAI-COV-207`)
 - Required fixes
 - Evidence summary
 - Open Questions / Risks

package/assets/init/.qfai/assistant/agents/test-case-owner.md

@@ -8,15 +8,21 @@
 
 - .qfai/assistant/instructions/\*
 - .qfai/assistant/steering/\*
-- .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
-- .qfai/specs/spec-\*/spec.md
-- .qfai/specs/spec-\*/scenario.feature
+- .qfai/specs/spec-\*/09_delta.md (Decision Records; check rejected)
+- .qfai/specs/spec-\*/03_Acceptance-Criteria.md
+- .qfai/specs/spec-\*/04_Business-Rules.md
+- .qfai/specs/spec-\*/05_Examples.md
+- .qfai/specs/spec-\*/06_Test-Cases.md
+- .qfai/report/validate.log
+- .qfai/report/specs-coverage/spec-\*.md
 - Existing test cases and mappings
 
 ## Deliverables (MANDATORY)
 
 - Decision Records referenced (DR-IDs) + rejected check (or RE-OPEN request)
+- Minimal TC set proposal satisfying AC->TC and EX->TC coverage
 - Test case inventory mapped to requirements/contracts
+- Missing boundary/negative case recommendations (perspective-based)
 - Exclusions rationale for any missing coverage
 - Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
 
@@ -25,7 +31,7 @@
 - Rejected option would be reintroduced without RE-OPEN DR
 - Traceability gaps without explicit rationale
 - Evidence is missing or incomplete
-- Test cases cannot be mapped to requirements
+- Test cases cannot be mapped to AC/EX requirements
 
 ## Sign-off checklist (Check Last)
 
@@ -39,6 +45,8 @@
 - Decision Records (DR-IDs) / rejected check
 - Findings
 - Test case mapping
+- Coverage gate status (`QFAI-COV-201..206`)
+- Perspective gaps (boundary, negative, permission, state)
 - Exclusions rationale
 - Evidence summary
 - Open Questions / Risks

package/assets/init/.qfai/assistant/agents/test-volume-estimator.md

@@ -2,44 +2,48 @@
 
 ## Mission
 
-- Compute ATDD floors (E2E/API/Integration) and detect underestimation.
+- Estimate test volume as a risk signal and detect thin areas.
 
 ## Inputs you must read
 
 - .qfai/assistant/instructions/\*
 - .qfai/assistant/steering/\*
-- .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
-- .qfai/specs/spec-\*/scenario.feature
-- .qfai/specs/spec-\*/case-catalogue.md
-- .qfai/specs/spec-\*/traceability-matrix.md
+- .qfai/specs/spec-\*/09_delta.md (Decision Records; check rejected)
+- .qfai/specs/spec-\*/04_Business-Rules.md
+- .qfai/specs/spec-\*/05_Examples.md
+- .qfai/specs/spec-\*/06_Test-Cases.md
+- .qfai/report/specs-coverage/spec-\*.md
+- .qfai/report/validate.log
 - .qfai/contracts/\*\*
 
 ## Deliverables (MANDATORY)
 
 - Decision Records referenced (DR-IDs) + rejected check (or RE-OPEN request)
-- Floor estimate table (Layer / Raw count / Multiplier / Floor / Evidence / Notes)
-- K rationale (3..5) with complexity signals
+- Risk-signal table (Layer / Raw count / Signal / Evidence / Notes)
+- Density-smell findings (for example multi-BR EX rows) and impact summary
+- Improvement proposals by perspective (boundary/negative/permission/state)
 - BLOCKED list when data is missing
 - Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
 
 ## Stop conditions (Blockers)
 
 - Rejected option would be reintroduced without RE-OPEN DR
-- Endpoint count cannot be derived and no fallback is available
+- BR/EX/TC source counts cannot be derived and no fallback is available
 - Evidence is missing or incomplete
 
 ## Sign-off checklist (Check Last)
 
 - [ ] Deliverables are complete
 - [ ] Evidence is present (gitignored)
-- [ ] Floors are justified with evidence
+- [ ] Risk signals are justified with evidence
 - [ ] BLOCKED items are explicit
 
 ## Output format (structured)
 
 - Decision Records (DR-IDs) / rejected check
-- Floor table
-- K rationale
+- Risk-signal table
+- Density-smell findings
+- Perspective-based improvement proposals
 - BLOCKED list (if any)
 - Evidence summary
 - Open Questions / Risks

package/assets/init/.qfai/assistant/skills/qfai-discuss/SKILL.md

@@ -88,6 +88,8 @@ Every major artifact in this stage MUST include this table schema:
 - RCP wording must be sourced from `.qfai/assistant/templates/rcp_footer.md`.
 - Discuss artifacts are logs/rationale and must not duplicate spec SSOT.
 - If diagrams are written, Mermaid syntax must be in ` ```mermaid ` fences only.
+- Do not enforce fixed EX/BR or TC/EX ratios in this phase.
+- Example Mapping is mandatory and must be captured as `Example Seeds` sections.
 
 ## Goal
 
@@ -118,12 +120,32 @@ Produce a fixed discuss pack with explicit decisions and OQ states so downstream
 
 1. Run the core interview for product concept, scope, and policy.
 2. Run config hearing for steering, constraints, and test-layer readiness.
-3. Run deep dive for risks, boundary conditions, and alternatives.
-4. Update `05_OQ-Register.md` with all identified OQs.
-5. Run OQ resolution hearing repeatedly until open count is zero.
-6. Move deferred items to `07_Deferred.md` with mandatory metadata.
-7. Update `06_OQ-Resolution-Log.md`, `08_Review-Request.md`, and `09_delta.md`.
-8. Request review and record Reviewer result.
+3. Run Example Mapping pass for each BR/AC candidate and capture `Example Seeds` in:
+   - `02_Hearing.md` (requirements-oriented seeds)
+   - `03_Config-Hearing.md` (constraints/policy-oriented seeds)
+4. Run deep dive for risks, boundary conditions, and alternatives.
+5. Update `05_OQ-Register.md` with all identified OQs.
+6. Run OQ resolution hearing repeatedly until open count is zero.
+7. Move deferred items to `07_Deferred.md` with mandatory metadata.
+8. Update `06_OQ-Resolution-Log.md`, `08_Review-Request.md`, and `09_delta.md`.
+9. Request review and record Reviewer result.
+
+## Example Mapping Perspectives (Mandatory)
+
+For each BR/AC candidate, enumerate concrete example seeds with these perspectives:
+
+1. Happy path
+2. Negative path
+3. Edge / boundary
+4. Permission / role
+5. State transition (if stateful)
+6. Idempotency / retry (if external I/O exists)
+
+Rules:
+
+- Use perspective coverage as the gate, not raw case counts.
+- Mark intentionally skipped perspectives with reason and follow-up.
+- Feed unresolved seeds into OQ items with owner and decision point.
 
 ## OQ Data Model (Mandatory)
 
@@ -188,6 +210,7 @@ Before declaring completion, you MUST:
 - verify all mandatory output files exist and are populated;
 - ensure `Disposition: open` count is zero;
 - ensure every deferred item has full metadata;
+- ensure `Example Seeds` sections are present and perspective coverage is explicit;
 - avoid duplicating finalized spec content in discuss outputs.
 
 ## Evidence (MANDATORY)

package/assets/init/.qfai/assistant/skills/qfai-discuss/templates/02_Hearing.md

@@ -16,3 +16,14 @@
 - In scope:
 - Out of scope:
 - Key constraints:
+
+## Example Seeds (Requirements)
+
+| BR/AC Candidate   | Perspective         | Seed (concrete) | Notes |
+| ----------------- | ------------------- | --------------- | ----- |
+| BR-0001 / AC-0001 | Happy               | TBD             | TBD   |
+| BR-0001 / AC-0001 | Negative            | TBD             | TBD   |
+| BR-0001 / AC-0001 | Edge / Boundary     | TBD             | TBD   |
+| BR-0001 / AC-0001 | Permission / Role   | TBD             | TBD   |
+| BR-0001 / AC-0001 | State transition    | TBD             | TBD   |
+| BR-0001 / AC-0001 | Idempotency / Retry | TBD             | TBD   |

package/assets/init/.qfai/assistant/skills/qfai-discuss/templates/03_Config-Hearing.md

@@ -18,3 +18,11 @@
 ## Open Gaps to Resolve in Discuss
 
 - OQ candidate:
+
+## Example Seeds (Constraints / Policy)
+
+| BR/AC Candidate   | Perspective         | Constraint-aware seed | Policy / gate note |
+| ----------------- | ------------------- | --------------------- | ------------------ |
+| BR-0001 / AC-0001 | Permission / Role   | TBD                   | TBD                |
+| BR-0001 / AC-0001 | State transition    | TBD                   | TBD                |
+| BR-0001 / AC-0001 | Idempotency / Retry | TBD                   | TBD                |

package/assets/init/.qfai/assistant/skills/qfai-discuss/templates/08_Review-Request.md

@@ -23,3 +23,6 @@
 - OQ state integrity (`open` must be zero at completion)
 - Deferred metadata completeness and risk handling
 - Traceability of decisions and rationale
+- Validate evidence availability (`.qfai/report/validate.log`)
+- Hard gate status (`QFAI-COV-201/202/203/204/205/206` should be zero)
+- Coverage report observations from `.qfai/report/specs-coverage/spec-*.md` (perspective gaps over raw count requests)

package/assets/init/.qfai/assistant/skills/qfai-discuss/templates/review/review_request.md

@@ -19,6 +19,9 @@
 - Operational and security risks
 - Mermaid diagrams use ` ```mermaid ` fences only (no ` ```text ` or language-less fences)
 - Business Flow artifacts include required `flowchart` or `sequenceDiagram` where applicable
+- Validate hard gate evidence exists (`.qfai/report/validate.log`).
+- Coverage hard gates are clear (`QFAI-COV-201/202/203/204/205/206` = 0).
+- `specs-coverage/spec-*.md` was reviewed and density-smell findings (for example `QFAI-COV-207`) are called out as perspective gaps.
 
 ## Required Reviewers
 

package/assets/init/.qfai/assistant/skills/qfai-prototyping/SKILL.md

@@ -161,6 +161,8 @@ Rules:
 - If `plan.md` exists, you MUST follow it as implementation constraints.
 - `implementation-brief.md` is deprecated and must not be used as How SSOT.
 - If `plan.md` is missing, STOP and run `/qfai-sdd` before proceeding.
+- If `_shared/05_Contracts.md` (or equivalent contracts index) references any contract ID whose declared file does not exist under `.qfai/contracts/**`, STOP and rerun `/qfai-sdd`.
+- `/qfai-prototyping` MUST NOT create new contract files; contracts are strict inputs in this stage.
 - 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.
@@ -225,6 +227,7 @@ Build a minimal runnable vertical slice from contracts so the app boots and user
 - ✅ 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 create new files under `.qfai/contracts/**` in this stage.
 - ❌ Do NOT change `.qfai/**/README.md` content. They are templates and remain SSOT.
 
 ## Mission (what “prototype” means)

package/assets/init/.qfai/assistant/skills/qfai-require/templates/review/review_request.md

@@ -19,6 +19,9 @@
 - Operational and security risks
 - Mermaid diagrams use ` ```mermaid ` fences only (no ` ```text ` or language-less fences)
 - Business Flow artifacts include required `flowchart` or `sequenceDiagram` where applicable
+- Validate hard gate evidence exists (`.qfai/report/validate.log`).
+- Coverage hard gates are clear (`QFAI-COV-201/202/203/204/205/206` = 0).
+- `specs-coverage/spec-*.md` was reviewed and density-smell findings (for example `QFAI-COV-207`) are called out as perspective gaps.
 
 ## Required Reviewers
 

package/assets/init/.qfai/assistant/skills/qfai-sdd/SKILL.md

@@ -98,6 +98,12 @@ Every major artifact in this stage MUST include a `## Work Orders Summary` secti
 - Reviewer checks (minimum):
   - Required roles were delegated (no orchestrator self-authoring).
   - DoD satisfied (coverage ledger, gates, evidence, DR-IDs).
+  - Validate gate evidence exists and is fresh:
+    - `qfai validate --fail-on error --format github` completed with `error=0`.
+    - `.qfai/report/validate.log` and `.qfai/report/specs-coverage/spec-*.md` are present.
+  - Layer coverage hard gates are all clear:
+    - `QFAI-COV-201/202/203/204/205/206` are `0`.
+    - `QFAI-COV-207` warnings are reviewed as density-smell signals.
   - **Drift Protocol enforced**:
     - No upstream artifact edits were made without an explicit user-approved Change Request.
     - If upstream changes exist, the correct owner skill was re-run after approval; downstream did not patch upstream directly.
@@ -171,7 +177,7 @@ Rules:
 
 ## Workflow Convention (Mandatory)
 
-- **This skill proceeds in this exact order: Outline -> Slice -> Plan finalize -> Delta update.**
+- **This skill proceeds in this exact order: Contracts-first -> Outline -> Slice -> Plan finalize -> Delta update.**
 - **Upper-to-lower references are forbidden. Lower-to-upper references are allowed.**
 - **Connections between layers MUST be represented by IDs and required edges (`US->AC->BR->EX->TC`).**
 - **Plan finalize MUST happen after at least one user-story slice is grounded.**
@@ -184,6 +190,17 @@ Rules:
   - `.qfai/assistant/skills/qfai-sdd/templates/specs/`
   - `.qfai/assistant/skills/qfai-sdd/templates/contracts/`
 - Always write `.qfai/report/preflight_summary.md` before generating shared/spec artifacts.
+- Contracts are contract-first mandatory outputs in this skill:
+  - create/update `.qfai/contracts/(api|db|ui)/**` before shared/spec slices
+  - `_shared/05_Contracts.md` must include a Contract Index with short IDs (`DB-001`, `API-001`, `UI-001`)
+  - every indexed short ID must map to a declared file with `QFAI-CONTRACT-ID`:
+    - `DB-001 -> CON-DB-0001 -> db-0001-<slug>.sql`
+    - `API-001 -> CON-API-0001 -> api-0001-<slug>.yaml`
+    - `UI-001 -> CON-UI-0001 -> ui-0001-<slug>.yaml`
+  - `<slug>` comes from entity/router/screen and must be sanitized to kebab-case
+  - allocate new contract IDs by scanning existing declarations and using next sequential NNNN per kind
+  - never duplicate existing declared IDs; update in-place when the contract already exists
+  - contract stubs must be syntactically valid (OpenAPI YAML / UI YAML / executable SQL skeleton)
 - `/qfai-sdd` must stop when require-pack is missing/incomplete or has blocking OQ (guide to `/qfai-require` or `/qfai-discuss` first).
 - Review roster is fixed by `.qfai/assistant/steering/review-roster.yml` and must be executed in full.
 - RCP wording must be sourced from `.qfai/assistant/templates/rcp_footer.md`.
@@ -192,6 +209,9 @@ Rules:
 - If diagrams are written in discuss/require/spec/evidence artifacts, Mermaid syntax must be inside ` ```mermaid ` fences only.
 - `05_Examples.md` must include `EX-ID` and `BR-Ref` mappings.
 - `06_Test-Cases.md` must include `TC-ID`, `EX-Ref`, and `AC-Refs`.
+- Do not complete this stage until:
+  - `qfai validate --fail-on error --format github | tee .qfai/report/validate.log` exits successfully.
+  - `.qfai/report/specs-coverage/spec-*.md` has been read for density review.
 - Reference direction rules from `.qfai/specs/README.md` must be enforced:
   - upper-to-lower references are forbidden
   - lower-to-upper references are allowed
@@ -205,6 +225,22 @@ Rules:
   - ask the user when certainty is below threshold
   - unresolved decisions become explicit Open Questions
 
+### Phase 0 - Contracts-first (mandatory)
+
+Create/update:
+
+- `.qfai/contracts/api/**`
+- `.qfai/contracts/db/**`
+- `.qfai/contracts/ui/**`
+- `_shared/05_Contracts.md` Contract Index table (DB/API/UI short IDs)
+
+Rules:
+
+- This phase MUST complete before Outline/Slice.
+- If `_shared/05_Contracts.md` lists an ID, the corresponding declared contract file MUST exist.
+- If a contract is empty, create a valid minimal stub and include `QFAI-CONTRACT-ID`.
+- `none` is allowed only when there is no contract impact and rationale is written.
+
 ### Phase 1 - Outline (layer-first)
 
 Create/update:
@@ -216,11 +252,15 @@ Create/update:
 - `_shared/05_Contracts.md`
 - `_shared/06_Glossary.md`
 - `_shared/07_Constraints.md`
+- `_shared/08_Decisions.md`
+- `_shared/09_Open-questions.md`
+- `_shared/10_delta.md`
 
 Rules:
 
 - Temporary `TBD` is allowed, but each `TBD` must be mirrored into `_shared/09_Open-questions.md`.
 - `_shared/04_Business-Flow.md` must include Mermaid and keep diagram syntax inside ` ```mermaid ` fences.
+- `_shared/08_Decisions.md` and `_shared/10_delta.md` must exist even when empty, and must explicitly state `0 items`.
 
 ### Phase 2 - Slice (slice-first)
 
@@ -232,6 +272,8 @@ Create/update:
 - `spec-XXXX/04_Business-Rules.md`
 - `spec-XXXX/05_Examples.md`
 - `spec-XXXX/06_Test-Cases.md`
+- `spec-XXXX/07_Decisions.md`
+- `spec-XXXX/08_Open-questions.md`
 
 Slice gate (must pass before Phase 3):
 
@@ -239,6 +281,7 @@ Slice gate (must pass before Phase 3):
 - For each AC, BR and SC must exist.
 - For each TC, EX reference must exist.
 - `SC` tags must align with the target `spec-XXXX` namespace.
+- `07_Decisions.md` and `08_Open-questions.md` must exist even when empty and include explicit `0 items` statements.
 
 ### Phase 3 - Plan finalize
 
@@ -271,6 +314,11 @@ Before declaring completion, you MUST:
 - Deliverable completeness: verify all required artifacts and sections are present.
 - OQ / placeholder scan: remove unresolved placeholders (`TBD`, `TODO`, `???`, `OPEN QUESTION`, etc.) unless explicitly deferred.
 - Run static checks proving the pack is reviewable.
+- Run validate gate and keep evidence:
+  - `qfai validate --fail-on error --format github | tee .qfai/report/validate.log`
+  - `.qfai/report/specs-coverage/spec-*.md`
+- If validate fails, fix spec-layer sources and rerun validate until `error=0`.
+- Do not patch upstream intent from downstream artifacts (Drift Protocol applies).
 
 ## Goal
 
@@ -291,15 +339,20 @@ Create or update layered SDD artifacts in one run so downstream execution phases
 - `.qfai/specs/_shared/05_Contracts.md`
 - `.qfai/specs/_shared/06_Glossary.md`
 - `.qfai/specs/_shared/07_Constraints.md`
+- `.qfai/specs/_shared/08_Decisions.md`
+- `.qfai/specs/_shared/09_Open-questions.md`
+- `.qfai/specs/_shared/10_delta.md`
 - `.qfai/specs/spec-XXXX/01_Spec.md`
 - `.qfai/specs/spec-XXXX/02_User-stories.md`
 - `.qfai/specs/spec-XXXX/03_Acceptance-Criteria.md`
 - `.qfai/specs/spec-XXXX/04_Business-Rules.md`
 - `.qfai/specs/spec-XXXX/05_Examples.md`
 - `.qfai/specs/spec-XXXX/06_Test-Cases.md`
+- `.qfai/specs/spec-XXXX/07_Decisions.md`
+- `.qfai/specs/spec-XXXX/08_Open-questions.md`
 - `.qfai/specs/spec-XXXX/10_Plan.md`
 - `.qfai/specs/spec-XXXX/09_delta.md` (or `*_delta.md`)
-- Updated contracts under `.qfai/contracts/**` when required
+- Updated contracts under `.qfai/contracts/**` (mandatory in this workflow)
 - `.qfai/report/preflight_summary.md`
 - Evidence file: `.qfai/evidence/sdd-<spec-id>.md`
 
@@ -309,11 +362,15 @@ Create or update layered SDD artifacts in one run so downstream execution phases
 2. If readiness checks fail, stop and show blockers with `/qfai-require` and `/qfai-discuss`.
 3. Analyze repository context, existing artifacts, constraints, and open decisions.
 4. Write `.qfai/report/preflight_summary.md` from `templates/report/preflight_summary.md`.
-5. Execute Phase 1 (Outline) in layer-first order.
-6. Execute Phase 2 (Slice) for at least one user-story slice and pass slice gate.
-7. Execute Phase 3 (Plan finalize) and make `10_Plan.md` actionable as How-only.
-8. Execute Phase 4 (Delta update) and record adoption/rejection rationale.
-9. Run static checks and record outcomes in evidence.
+5. Execute Phase 0 (Contracts-first) and ensure `_shared/05_Contracts.md` index and `.qfai/contracts/**` are aligned.
+6. Execute Phase 1 (Outline) in layer-first order.
+7. Execute Phase 2 (Slice) for at least one user-story slice and pass slice gate.
+8. Execute Phase 3 (Plan finalize) and make `10_Plan.md` actionable as How-only.
+9. Execute Phase 4 (Delta update) and record adoption/rejection rationale.
+10. Run `qfai validate --fail-on error --format github | tee .qfai/report/validate.log`.
+11. Run Density Review Pass using `.qfai/report/specs-coverage/spec-*.md` and `QFAI-COV-207` warnings.
+12. If any validate error exists, fix the source layer table(s) and repeat steps 10-11 until `error=0`.
+13. Record static checks, validate evidence, and density review outcomes in evidence.
 
 ## Unified SDD Quality Gate
 
@@ -327,6 +384,8 @@ Run static checks:
 - Confirm reference direction follows lower-to-upper only.
 - Confirm required edges `US -> AC -> BR -> EX -> TC`.
 - Confirm BR/Examples/Test-cases contain non-empty IDs and coverage mapping.
+- Confirm `QFAI-COV-201/202/203/204/205/206` are zero.
+- Confirm `.qfai/report/specs-coverage/spec-*.md` was reviewed and `QFAI-COV-207` warnings were triaged.
 - Confirm `10_Plan.md` exists and contains implementation/test strategy as How-only.
 - Confirm `specs/plan.md` does not exist.
 - Confirm `09_delta.md` (or `*_delta.md`) includes rejected guardrails (`DO NOT`, `Temptation`) when rejections exist.
@@ -344,6 +403,7 @@ Required sections:
 - Decisions made (with rationale)
 - Work performed (what changed, where)
 - Commands executed + key outputs
+- Validate evidence paths (`.qfai/report/validate.log`, `.qfai/report/specs-coverage/spec-*.md`)
 - Gaps / Open risks
 - Final status (PASS/FAIL) + who confirmed
 
@@ -352,7 +412,7 @@ Required sections:
 When declaring DONE, include:
 
 - Referenced inputs and spec-id
-- Confirmation of phase order: Outline -> Slice -> Plan finalize -> Delta update
+- Confirmation of phase order: Contracts-first -> Outline -> Slice -> Plan finalize -> Delta update
 - Decision record IDs touched in `09_delta.md` (or `*_delta.md`)
 - Confirmation that no rejected option was reintroduced (or list RE-OPEN IDs)
 - Unified SDD quality gate result
@@ -361,7 +421,8 @@ When declaring DONE, include:
 
 - [ ] CRITICAL CONSTRAINTS were followed.
 - [ ] `.qfai/report/preflight_summary.md` was generated before spec authoring.
-- [ ] Outline -> Slice -> Plan finalize -> Delta update order was preserved.
+- [ ] Contracts-first -> Outline -> Slice -> Plan finalize -> Delta update order was preserved.
+- [ ] `_shared/05_Contracts.md` index and `.qfai/contracts/**` declared files are aligned.
 - [ ] Upper-to-lower references were not introduced.
 - [ ] At least one user-story slice passed gate before plan finalization.
 - [ ] Required `_shared` + `spec-XXXX` outputs exist and are internally consistent.
@@ -370,6 +431,9 @@ When declaring DONE, include:
 - [ ] `10_Plan.md` is finalized with implementation/test strategy (How-only).
 - [ ] `specs/plan.md` was not created.
 - [ ] `09_delta.md` (or `*_delta.md`) contains adoption/rejection rationale.
+- [ ] `qfai validate --fail-on error --format github` ran and produced `error=0`.
+- [ ] `QFAI-COV-201/202/203/204/205/206` are all zero.
+- [ ] `.qfai/report/specs-coverage/spec-*.md` was reviewed for density-smell signals (`QFAI-COV-207`).
 - [ ] Unresolved items are tracked in shared/spec Open Questions files.
 - [ ] Quality gate checks are recorded in evidence.
 - [ ] Evidence file exists and is complete.
@@ -392,7 +456,7 @@ When this skill is complete, provide a final user-facing completion message and
   Action: build contract-aligned skeleton implementation before deeper coding.
 - Test-first path: `/qfai-atdd`.
   Action: implement acceptance tests from the finalized spec pack.
-- Want to add contracts:
-  Action: create files under `.qfai/contracts/(api|db|ui)/` from `templates/contracts/*` and declare `QFAI-CONTRACT-ID`.
+- Contracts status:
+  Action: confirm contracts were created/updated under `.qfai/contracts/**` and referenced by `_shared/05_Contracts.md`.
 - Spec pack needs correction: rerun `/qfai-sdd`.
   Action: fix layered `_shared + spec-XXXX` consistency and decision records, then regenerate evidence.

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/specs/_shared/05_Contracts.md

@@ -2,25 +2,49 @@
 
 ## Purpose
 
-- Describe API/UI/DB contract boundaries in shared language.
-- Model relationships with Mermaid when expressing entities or ownership.
+- Keep contracts as SSOT under `.qfai/contracts/**` with deterministic IDs.
+- Use this file as a readable index with short IDs for planning and review.
+
+## Contract Index
+
+### DB Contracts
+
+| Short ID | Entity       | Declared ID | File                                    | Purpose           |
+| -------- | ------------ | ----------- | --------------------------------------- | ----------------- |
+| DB-001   | order_drafts | CON-DB-0001 | `.qfai/contracts/db/db-0001-<slug>.sql` | draft persistence |
+
+### API Contracts
+
+| Short ID | Router      | Declared ID  | File                                       | Purpose      |
+| -------- | ----------- | ------------ | ------------------------------------------ | ------------ |
+| API-001  | /api/orders | CON-API-0001 | `.qfai/contracts/api/api-0001-<slug>.yaml` | create draft |
+
+### UI Contracts
+
+| Short ID | Screen       | Declared ID | File                                     | Purpose          |
+| -------- | ------------ | ----------- | ---------------------------------------- | ---------------- |
+| UI-001   | order-create | CON-UI-0001 | `.qfai/contracts/ui/ui-0001-<slug>.yaml` | draft input form |
+
+## Mapping Rules
+
+- `DB-001` maps to `CON-DB-0001`, file `db-0001-<slug>.sql`.
+- `API-001` maps to `CON-API-0001`, file `api-0001-<slug>.yaml`.
+- `UI-001` maps to `CON-UI-0001`, file `ui-0001-<slug>.yaml`.
+- `<slug>` must be kebab-case from entity/router/screen.
+- If no contracts are needed, keep each table and state `0 items` explicitly.
 
 ## Diagram (Mermaid required for ER/relationship)
 
 ```mermaid
 erDiagram
-  USER ||--o{ ORDER : places
+  USER ||--o{ ORDER_DRAFT : creates
   USER {
     string id
     string email
   }
-  ORDER {
+  ORDER_DRAFT {
     string id
     string user_id
+    string status
   }
 ```
-
-## Notes
-
-- Keep detailed SSOT in `.qfai/contracts/**`.
-- Use this file as the shared contract index and relationship map.