qfai 1.8.6 → 1.8.8

package/README.md

@@ -18,11 +18,12 @@ The agent reads the repository, produces the required artifacts, and iterates un
 ## Release status
 
 - Release posture: runtime truthfulness is enforced.
-- Prototyping is UI-only; `full-harness` is measurement-driven iteration accumulation for UI-bearing surfaces only.
+- Prototyping is UI-only and runs a single-thread evolution loop driven by
+  `qfai prototyping iterate --cycle <n>`, with deterministic stop conditions
+  (exit codes 0 continue / 64 convergence / 65 max-iterations / 2 input error).
 - Runtime observation is observed-only (no synthetic 200 / API / DB prototyping coverage).
-- Browser QA is mandatory per screen in full-harness, and `actionsWired` reports action coverage rather than finding count.
+- Per-iter evidence is `screenshot.png` + `index.html` per declared screen plus a single `review.json` (4-axis ordinal, prose critique, anti-slop detection, pivot directive).
 - Calibration SSOT is the calibration pack referenced by `calibrationRef.packPath`.
-- Current repo note: some repo-wide `qfai validate --fail-on error` blockers still come from historical review/evidence/ATDD/TDD artifacts and are being cleaned incrementally.
 
 ## Quick start
 
@@ -60,19 +61,15 @@ npx qfai report
     primary spec, UI contracts, design contract readiness, active agent-wrapper
     integrations, shipped role-input readiness, Playwright CLI launcher
     resolution/probing, and target URL reachability.
-    Note: prototyping evidence (`.qfai/evidence/prototyping.json`) is produced by the AI workflow / skills
-    (`/qfai-prototyping` — any mode; modes differ only in `maxCycles`, see spec-0012), not by a general-purpose end-user CLI flow.
+    Note: prototyping evidence (`.qfai/evidence/prototyping/prototyping.json`) is produced by the AI workflow
+    (`/qfai-prototyping`), not by a general-purpose end-user CLI flow.
     Use `npx qfai prototyping preflight --target-url <url>` for a focused
-    prototyping preflight before the skill starts; it now surfaces blocking
-    `QFAI-DCON-*` design-contract issues alongside runtime assumptions, resolves
-    a runnable Playwright CLI launcher (project wrapper / local bin / PATH /
-    `npx --no-install`), and still treats the first real delegation failure as a
-    runtime hard-stop.
-    Use `npx qfai prototyping round-start --round <r5|r3|r2|r1> --candidates <csv> --target-url <url> --mode <mode>`
-    to generate the round-scoped review bundle and command plans the AI evaluator sub-agent consumes, then use
-    `round-harvest`, `round-narrow`, `round-absorb`, and `round-reimplement-verify` to advance the candidate funnel.
-    `qfai validate` consumes the resulting evidence files, including `mode.effective` and `fullHarness` metadata when present.
-    Traceability refs inside prototyping evidence must use repo-root-relative concrete artifact refs (for example `.qfai/specs/spec-0001/01_Spec.md#L3` or `.qfai/evidence/render.json#/screens/0`).
+    prototyping preflight before the skill starts; it surfaces blocking
+    `QFAI-DCON-*` design-contract issues alongside runtime assumptions and resolves a runnable Playwright CLI launcher.
+    Use `npx qfai prototyping iterate --cycle <n> --target-url <url>` to drive each cycle of the single-thread
+    evolution loop. Exit codes: 0 (continue), 64 (convergence), 65 (max-iterations), 2 (input error).
+    Traceability refs inside prototyping evidence must use repo-root-relative concrete artifact refs
+    (for example `.qfai/specs/spec-0001/01_Spec.md#L3` or `.qfai/evidence/prototyping/iter-03/home.png`).
     Absolute paths are invalid. The same strict ref grammar is enforced for top-level and leaf evidence-bearing fields, including
     `runtimeGate.evidenceRefs`, `runtimeGate.ui[].declaredRef`, `runtimeGate.ui[].renderEvidenceRefs[]`,
     `runtimeGate.ui[].browserQaEvidenceRefs[]`, `specs[].coverageRefs[].declaredRef`, `specs[].coverageRefs[].observedRefs[]`,
@@ -96,9 +93,9 @@ npx qfai report
 
 `qfai validate` enforces spec-to-test traceability with directory-based rules.
 
-- `tests/e2e/**`: annotate all covered user stories with `QFAI:SPEC-XXXX:US-YYYY`.
-- `tests/integration/**`: annotate all covered test cases with `QFAI:SPEC-XXXX:TC-YYYY`.
-- `tests/api/**`: annotate all covered API contracts with `QFAI:CON-API-XXXX`.
+- `tests/e2e/**`: annotate all covered user stories with concrete IDs such as `QFAI:SPEC-0001:US-0001`.
+- `tests/integration/**`: annotate all covered test cases with concrete IDs such as `QFAI:SPEC-0001:TC-0001`.
+- `tests/api/**`: annotate all covered API contracts with concrete IDs such as `QFAI:CON-API-0001`.
 - `tests/api/**` and `tests/e2e/**` must not use `TC` annotations.
 - `AC` annotations are not required in code; AC coverage is treated as indirect through full `TC` coverage.
 
@@ -111,7 +108,7 @@ The agent reads QFAI assets under `.qfai/assistant/` and produces or updates SDD
 ### Where the skills live
 
 - QFAI canonical skills (SSOT): `.qfai/assistant/skills/**` (may be overwritten when you re-run `qfai init --force`).
-- Your local overrides: `.qfai/assistant/skills.local/**` (never overwritten by QFAI; prefer this for project-specific customizations).
+- QFAI no longer creates local override scaffolds. Project-specific guidance should live in your repository's normal agent docs or be created explicitly by your AI workflow.
 
 ### Minimal custom skill set
 
@@ -123,10 +120,22 @@ QFAI includes a small set of custom skills (stored under `.qfai/assistant/skills
 - **qfai-discussion**: Run a unified structured discussion that produces and maintains the latest discussion pack
   as 15 required markdown files under `.qfai/discussion/discussion-<ts>/`.
   UI-bearing discussion packs may include `prototyping.yaml` as an optional recommendation artifact; non-ui discussion packs typically omit it.
-- **qfai-sdd**: Unified SDD entrypoint with discussion-pack preflight guard (missing/incomplete/blocking OQ causes stop + next action guidance).
-- **qfai-prototyping**: Build a contract-aligned UI prototype using the Playwright CLI + AI
-  evaluator harness (spec-0012). Modes (`low-cost`/`standard`/`full-harness`) run the same
-  strictest review cycle; only `maxCycles` (1/3/20) differs.
+- **qfai-sdd**: Unified SDD entrypoint with discussion-pack preflight guard
+  (missing/incomplete/blocking OQ causes stop + next action guidance).
+  After preflight, the skill runs a mandatory **Stage 1 Triage** that classifies
+  every incoming requirement into one of 8 first-class operations
+  (CREATE / UPDATE:APPEND / UPDATE:MODIFY / UPDATE:REMOVE / DELETE / SPLIT /
+  MERGE / SUPERSEDE) with an **append-first** bias: existing active specs
+  absorb the change unless there is zero subject-token overlap.
+  CREATE / DELETE / SPLIT / MERGE / SUPERSEDE / UPDATE:REMOVE require explicit
+  `AskUserQuestion` approval, and CREATE rows must register a new `CAP-NNNN`
+  in `.qfai/specs/_policies/03_Capabilities.md` before the row is accepted
+  (`QFAI-TRIAGE-006`). Every `01_Spec.md` declares a lifecycle
+  `Status: active | superseded | deprecated | removed` (`QFAI-STATUS-001..006`).
+- **qfai-prototyping**: Single-thread design evolution loop. One prototype iterated through up to
+  15 cycles of generate -> capture -> review with a 4-axis ordinal rubric, anti-slop detection,
+  prose critique, and explicit pivot permission. Stops deterministically when all four axes hit
+  `exceptional` (exit 64) or the iteration budget is exhausted (exit 65).
 - **qfai-atdd**: Implement acceptance tests driven by specs/scenarios.
 - **qfai-implement**: Unified TDD micro-cycle (Red/Green/Refactor) one test at a time using `test-list.md` as the execution ledger, including ledger status updates and exception closure.
 - **qfai-verify**: Run full-scan local quality gates (`validate --fail-on error`, `report`, repo gates) and produce reviewer-approved evidence under `.qfai/evidence/`.
@@ -283,6 +292,16 @@ Release gate behavior:
   - A: Include all required sections (`Change Summary`, `Rationale`, `Candidates Considered`, `Adopted`, `Rejected`, `Impact`, `Follow-ups`) and include both `DO NOT` and `Temptation` in `Rejected`.
 - Q: release_candidate validation fails due open questions.
   - A: Keep specs definition-only, use `.qfai/report/run-*` as execution logs, and convert open OQ to `resolved` or `deferred` with evidence.
+- Q: `qfai validate` reports `QFAI-STATUS-001` ("Status bullet が見つかりません") on every spec.
+  - A: Each `01_Spec.md` must declare `- Status: active | superseded | deprecated | removed` (introduced in 1.8.8).
+    Add `Status: active` for currently-authoritative specs; superseded specs need a `- Superseded-by: spec-NNNN` companion bullet,
+    and deprecated/removed specs need `- Deprecated-at: YYYY-MM-DD`. The previous `QFAI-STATUS-001` (status-leak guard) was renamed to `QFAI-STATUSLEAK-001` to free the namespace.
+- Q: `/qfai-sdd` is asking for `AskUserQuestion` approval that earlier versions never asked for.
+  - A: Stage 1 Triage classifies each requirement into one of 8 first-class operations and gates approval-required ops
+    (CREATE / DELETE / SPLIT / MERGE / SUPERSEDE / UPDATE:REMOVE) on explicit user confirmation. Append-first means UPDATE:APPEND on an existing active spec is the default;
+    CREATE additionally requires a new `CAP-NNNN` row in `.qfai/specs/_policies/03_Capabilities.md` before the row is accepted (`QFAI-TRIAGE-006`).
+- Q: `delta.md` validation reports `QFAI-TRIAGE-001` ("Change Summary はあるが Triage がありません") as a warning.
+  - A: 1.8.8 introduced a `## Triage` section requirement. Existing operational deltas without it currently fail soft (warning); future minor versions will promote this to an error after operational backfill.
 
 ## Continuous integration
 
@@ -377,10 +396,7 @@ Typical customizations.
 │   │   │   │   └── SKILL.md
 │   │   │   └── qfai-verify
 │   │   │       └── SKILL.md
-│   │   ├── skills.local
-│   │   │   └── README.md
 │   │   ├── steering
-│   │   │   ├── README.md
 │   │   │   ├── agent-catalog.yml
 │   │   │   ├── agent-routing.yml
 │   │   │   ├── review-gate.rules.yml
@@ -388,40 +404,14 @@ Typical customizations.
 │   │   │   ├── product.md
 │   │   │   ├── structure.md
 │   │   │   └── tech.md
-│   │   └── README.md
-│   ├── discussion
-│   │   ├── README.md
-│   │   └── discussion-YYYYMMDDhhmmssSSS
-│   │       ├── 01_Context.md
-│   │       ├── ...
-│   │       ├── 14_Review-Request.md
-│   │       ├── 99_delta.md
-│   │       └── prototyping.yaml
-│   ├── contracts
-│   │   ├── api
-│   │   │   └── README.md
-│   │   ├── db
-│   │   │   └── README.md
-│   │   ├── ui
-│   │   │   └── README.md
-│   │   └── README.md
-│   ├── report
-│   │   ├── .gitignore
-│   │   ├── README.md
-│   │   └── run-20260218123456789
-│   │       ├── run.json
-│   │       ├── validator.json
-│   │       ├── traceability.json
-│   │       └── summary.md
-│   ├── review
-│   │   ├── .gitignore
-│   │   └── README.md
-│   ├── specs
-│   │   └── README.md
-│   └── README.md
+│   └── waivers.yml
 └── qfai.config.yaml
 ```
 
+`qfai init` does not seed `.qfai` workflow artifacts such as specs, discussions,
+contracts, evidence, reports, reviews, placeholder spec directories, or artifact
+README files. Those files are created later by QFAI skills when real work exists.
+
 Integration wrappers are also generated for immediate use:
 
 - Agents/Codex VS Code: `.agents/skills/**`

package/assets/init/.qfai/assistant/instructions/requirements-decomposition.md

@@ -41,7 +41,7 @@ This document is the decision rule SSOT for AI and humans when answering:
 ### Rule 3 - Keep ambiguity explicit
 
 - Unknowns remain explicit as Open Questions.
-- Resolved answers are promoted to `_policies` or `spec-XXXX` artifacts, then OQ status is updated.
+- Resolved answers are promoted to `_policies` or target spec artifacts, then OQ status is updated.
 
 ## How to decompose (mechanical procedure)
 

package/assets/init/.qfai/assistant/instructions/workflow.md

@@ -49,7 +49,7 @@ Do not proceed without a declared Change Type.
 0. Steering refresh (project memory bootstrap)
 1. Discussion (optional): clarify idea → requirement seed
 2. Requirements: discussion pack in `.qfai/discussion/`
-3. Specification (SDD): unified preflight + `_policies` / `spec-XXXX/01..10`
+3. Specification (SDD): unified preflight + `_policies` / `spec-*/01..10`
 4. Prototyping (optional): contract-aligned implementation skeleton
 5. Acceptance tests (ATDD): runnable E2E/API/Integration tests derived from specs/contracts obligations (`US` / `TC` / `CON-API`)
 6. Verify: run quality gates and provide evidence
@@ -59,7 +59,7 @@ Stage 3 (`/qfai-sdd`) target policy:
 - With argument (`/qfai-sdd <spec-id-or-name>`): scope is the matched single spec only.
 - Without argument (`/qfai-sdd`): scope is all capabilities from `.qfai/specs/_policies/03_Capabilities.md` in order.
 - `/qfai-sdd` must create or refresh `.qfai/specs/_policies/11_Slice-Policy.md` before deciding whether a spec change is CREATE / UPDATE / DELETE.
-- For no-argument batch runs, execute Contracts-first and Outline once, then delegate Slice/Plan/Delta in parallel per `spec-XXXX`.
+- For no-argument batch runs, execute Contracts-first and Outline once, then delegate Slice/Plan/Delta in parallel per target spec.
 
 Prototyping stage policy:
 

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

@@ -40,11 +40,11 @@ Skill-specific examples:
 
 - Follow `.qfai/assistant/instructions/shared-skill-operating-baseline.md#format-ssot-mandatory`.
 
-- Before writing or editing any `.qfai/**` artifact, read and follow the relevant directory README template and sample:
-  - `.qfai/discussion/README.md`
-  - `.qfai/specs/README.md`
-  - `.qfai/contracts/**/README.md`
-  - `.qfai/evidence/README.md`
+- Before writing or editing any `.qfai/**` artifact, read the relevant skill-local reference or template:
+  - `.qfai/assistant/skills/qfai-discussion/references/discussion-artifact-rules.md`
+  - `.qfai/assistant/skills/qfai-sdd/references/spec-traceability-rules.md`
+  - `.qfai/assistant/skills/qfai-sdd/references/contract-artifact-rules.md`
+  - `.qfai/assistant/skills/qfai-prototyping/references/evidence-requirements.md`
 
 ## Inputs Priority (Preflight)
 
@@ -244,7 +244,7 @@ These principles are inspired by "constitution / articles" patterns used by othe
 
 ## README Rule
 
-Do not edit any `.qfai/**/README.md` file; raise an Open Question instead.
+Do not create `.qfai/**/README.md` files as scaffold or format documentation; keep artifact guidance in skill references/templates.
 
 - READMEs are reference guides. Follow their structure, templates, and checklists.
 

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

@@ -46,8 +46,6 @@ UI-bearing packs must produce the following sidecars as primary truth:
 - `uiux/30_exploration_brief.md`
 - `uiux/31_reference_pool.md`
 - `uiux/32_design_anti_goals.md`
-- `uiux/33_exploration_rubric.md`
-- `uiux/34_evaluator_calibration.md`
 - `uiux/40_screen_contracts.md`
 - `uiux/50_review_input_bundle.md`
 
@@ -68,12 +66,13 @@ For UI-bearing targets, follow `references/design-dna-intake.md` while authoring
 
 ## UI-bearing Authoring Requirements
 
-- `30_exploration_brief.md` must define product intent, must-preserve interactions, brand signals, and differentiation targets.
-- `31_reference_pool.md` must define exploration references, adopted points, rejected points, local translation, copy risk, and template usage policy.
-- `32_design_anti_goals.md` must contain explicit anti-goals and recurrence prevention notes.
-- `33_exploration_rubric.md` must define design quality, originality, craft, functionality, brand memorability, category distinctiveness, template dependency risk, and localization-fit grading criteria.
-- `34_evaluator_calibration.md` must include good critique examples, too-lenient examples, blandness-fail examples, originality-fail examples, and template-copy fail examples.
-- `50_review_input_bundle.md` must document best-of-history handling so later iterations are not automatically preferred.
+- `30_exploration_brief.md` must define product intent, brand signals, and differentiation targets.
+- `31_reference_pool.md` must define exploration references with adopted points, rejected points, and copy risk — framed as **deviate-from** inputs (not imitate-this) for downstream `/qfai-prototyping` reviewer.
+- `32_design_anti_goals.md` must contain explicit anti-goals; this also feeds the global anti-slop pattern list consulted by the prototyping reviewer.
+- `50_review_input_bundle.md` must document review inputs for downstream skills.
+
+Evaluation axes are global constants (4-step ordinal: weak / acceptable /
+strong / exceptional) and are not authored as discussion sidecars.
 
 ## Completion Contract (Shared)
 

package/assets/init/.qfai/assistant/skills/qfai-discussion/references/design-dna-intake.md

@@ -22,7 +22,8 @@ Use this reference only for UI-bearing discussion packs.
 ## Output Mapping
 
 - Put product intent and brand signals in `30_exploration_brief.md`.
-- Put all reference decisions in `31_reference_pool.md`.
-- Put prohibited visual directions in `32_design_anti_goals.md`.
-- Put brand and template-risk scoring in `33_exploration_rubric.md`.
-- Put examples of good critique and weak critique in `34_evaluator_calibration.md`.
+- Put all reference decisions in `31_reference_pool.md` (deviate-from input, not imitate).
+- Put prohibited visual directions in `32_design_anti_goals.md` (also feeds reviewer anti-slop).
+
+Evaluation axes are global constants (4-step ordinal: weak / acceptable /
+strong / exceptional) and are not authored as discussion sidecars.

package/assets/init/.qfai/assistant/skills/qfai-discussion/references/discussion-artifact-rules.md

@@ -0,0 +1,62 @@
+# Discussion Artifact Rules
+
+Use this file when `/qfai-discussion` creates or reviews `.qfai/discussion/discussion-*` packs.
+
+## Required Pack
+
+Each pack uses immutable timestamp naming: `.qfai/discussion/discussion-YYYYMMDDhhmmssSSS/`.
+
+Required files:
+
+- `01_Context.md`
+- `02_Inception-Deck.md`
+- `03_Story-Workshop.md`
+- `04_Sources.md`
+- `05_Scope.md`
+- `06_REQ.md`
+- `07_NFR.md`
+- `08_Glossary.md`
+- `09_Constraints.md`
+- `10_Policy.md`
+- `11_OQ-Register.md`
+- `12_OQ-Resolution-Log.md`
+- `13_Deferred.md`
+- `14_Review-Request.md`
+- `99_delta.md`
+
+UI-bearing discussion packs may include `prototyping.yaml` as an optional recommendation artifact; non-ui discussion packs typically omit it. For `ui_bearing: false`, typically omit `prototyping.yaml`. Current discussion-pack readiness does not block on missing `prototyping.yaml`.
+
+## Rules
+
+- Run interview and requirement capture until `Disposition: open` is zero in `11_OQ-Register.md`.
+- OQ `Gate` values are `discussion`, `sdd`, `atdd`, `tdd`, or `ops`.
+- `deferred` is allowed only when `13_Deferred.md` has complete metadata.
+- Discussion outputs are rationale and intake logs; do not duplicate `.qfai/specs/**` SSOT.
+- `03_Story-Workshop.md` must include at least one Mermaid diagram.
+- Use Mermaid fences only for diagrams.
+- `14_Review-Request.md` must reference `.qfai/assistant/steering/agent-routing.yml` and `review-profiles.yml`.
+
+## UI/UX Exploration Family
+
+For UI-bearing packs, use:
+
+- `04_Sources.md` for trend translation and competitive reference registry
+- `uiux/30_exploration_brief.md`
+- `uiux/31_reference_pool.md`
+- `uiux/32_design_anti_goals.md`
+- `uiux/40_screen_contracts.md`
+
+Discussion is exploration-first and must not choose a single visual winner or final design system. Those are downstream prototyping outputs.
+
+## `prototyping.yaml`
+
+When `prototyping.yaml` is present, use the single-thread schema:
+
+```yaml
+prototyping:
+  surface: web # web | mobile | desktop | mixed
+```
+
+Mode-tier fields (`recommended_mode` / `allowed_modes` / `mode_expectations`)
+are not supported. The single-thread evolution loop fixes iteration count
+globally to 15.

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/prototyping.yaml

@@ -1,17 +1,8 @@
 prototyping:
-  recommended_mode: full-harness
-  rationale: >
-    Fill this with a concrete reason tied to the full-harness evidence obligations.
-  allowed_modes:
-    - full-harness
+  # Single-thread evolution loop. Iteration count is fixed at 15 globally
+  # (no per-mode override).
   # Replace `web` with one of the prototyping-supported surfaces if needed:
   #   web | mobile | desktop | mixed
   # (discussion classification also allows `cli` and `non-ui`, but those are
-  #  not valid prototyping execution surfaces; see
-  #  `packages/qfai/src/core/prototyping/surfacePolicy.ts` — PROTOTYPING_SUPPORTED_SURFACES.)
+  #  not valid prototyping execution surfaces.)
   surface: web
-  mode_expectations:
-    full-harness:
-      expected_iterations: "2+"
-      process: "measure -> score -> fix code -> re-run"
-      calibration_ref: "qfai.config.yaml#prototyping.calibration"

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

@@ -60,7 +60,7 @@ Skill-specific examples:
 
 - This skill processes **one test at a time** from `test-list.md`.
 - Each item goes through the full TDD micro-cycle: write a **failing test** first, then make it pass, then refactor.
-- The execution ledger is located at `.qfai/specs/spec-XXXX/tdd/test-list.md`.
+- The execution ledger is located at `.qfai/specs/<spec-id>/tdd/test-list.md`.
 - Items are processed **serially** by default. Parallel processing is allowed only when items target independent SUT slices with no shared state.
 - Status transitions follow a strict forward-only lifecycle: `todo` -> `red` -> `green` -> `refactor` -> `done`.
 - The `exception` status can be reached from any active status when an anomaly is detected.
@@ -79,12 +79,14 @@ Execute the TDD micro-cycle for each pending item in `test-list.md`, transitioni
 - Read order: `01_Spec.md` → `03_Acceptance-Criteria.md` → `05_Examples.md` →
   `.qfai/contracts/design/exploration-brief.yaml` →
   `.qfai/contracts/design/reference-pool.yaml` → `.qfai/contracts/design/brand-design.yaml` →
-  `.qfai/contracts/design/evaluation-rubric.yaml` → `.qfai/contracts/design/evaluator-calibration.yaml` →
-  `.qfai/contracts/design/selected-direction.yaml` → `.qfai/contracts/design/design-system.yaml` →
+  `.qfai/contracts/design/design-system.yaml` (extracted from final iter) →
   `.qfai/contracts/design/prototype-handoff.yaml` → `.qfai/contracts/ui/*.yaml` →
-  canonical prototype screenshots / HTML snapshots → `.qfai/prototypes/winner/index.html`.
-- Do not read discussion-pack UI/UX sidecars, fallback mocks, or legacy design aliases.
-- Prototype code is analysis input, not production source. Reimplement with project-native patterns while preserving `prototype-handoff.yaml` `mustPreserve`; adapt `mayAdapt`; do not copy `mustNotCopy`.
+  canonical prototype evidence under `.qfai/evidence/prototyping/iter-NN/<screen>.{png,html}` →
+  `.qfai/prototypes/final/index.html`.
+- Do not read discussion-pack UI/UX sidecars or fallback mocks.
+- Prototype HTML is analysis input, not production source. Reimplement with project-native
+  patterns while preserving the visual identity captured in `prototype-handoff.yaml`
+  `implementationNotes` (free-form prose).
 - UI-affecting items require product-surface-reviewer prototype parity review before `done`.
 - If code intent and rendered output diverge, treat the rendered/HTML result as the blocking review input and reconcile before DONE.
 
@@ -97,7 +99,7 @@ Execute the TDD micro-cycle for each pending item in `test-list.md`, transitioni
 
 ## Execution Ledger: test-list.md
 
-The execution ledger at `.qfai/specs/spec-XXXX/tdd/test-list.md` tracks progress with these required columns:
+The execution ledger at `.qfai/specs/<spec-id>/tdd/test-list.md` tracks progress with these required columns:
 
 | Column    | Description                                              |
 | --------- | -------------------------------------------------------- |
@@ -294,11 +296,11 @@ Completion MUST NOT be declared when any of the following are true:
 - Items with `todo`, `red`, `green`, or `refactor` status still exist (for spec-level completion)
 - Parallel slices were used but integration verify has not been run post-merge
 - Checkpoint boundary was reached but verification was not executed
-- `it.todo(...)` / `test.todo(...)` / `describe.todo(...)` stubs remain in any file covered by `validation.traceability.testFileGlobs` (`QFAI-TEST-001`, spec-0012). Implement the body or delete the stub — an opt-out via `validation.testStrategy.forbidTestTodoStubs: false` is permitted only with an accompanying waiver DR-ID.
+- `it.todo(...)` / `test.todo(...)` / `describe.todo(...)` stubs remain in any file covered by `validation.traceability.testFileGlobs` (`QFAI-TEST-001`). Implement the body or delete the stub — an opt-out via `validation.testStrategy.forbidTestTodoStubs: false` is permitted only with an accompanying waiver DR-ID.
 
 ## Evidence (MANDATORY)
 
-Create/update: `.qfai/evidence/implement-spec-XXXX.md`
+Create/update: `.qfai/evidence/implement-<spec-id>.md`
 
 Required sections:
 
@@ -342,7 +344,7 @@ Each TDD item MUST have fresh evidence containing at minimum:
 - [ ] No backward transitions occurred.
 - [ ] Exception items have DR-IDs recorded.
 - [ ] All tests pass.
-- [ ] `qfai validate --profile tdd --fail-on error` passes with zero `QFAI-TEST-001` findings (no `it.todo` / `test.todo` / `describe.todo` stubs remain; spec-0012).
+- [ ] `qfai validate --profile tdd --fail-on error` passes with zero `QFAI-TEST-001` findings (no `it.todo` / `test.todo` / `describe.todo` stubs remain).
 
 ## Completion Checklist (MUST)