qfai 1.9.2 → 1.10.0

package/assets/init/.qfai/assistant/skills/qfai-prototyping/references/generator-prompt.md

@@ -92,10 +92,20 @@ forms caught:
 
 - Inline `border-radius: 12px` / `border-radius: 0.5rem`.
 - Tailwind arbitrary `rounded-[13px]`, `rounded-[0.5rem]`.
-- Tailwind scale aliases (`rounded`, `rounded-sm`, `rounded-md`,
-  `rounded-lg`, `rounded-xl`, `rounded-2xl`, `rounded-3xl`,
-  `rounded-full`, `rounded-none`) — all resolve to Tailwind defaults,
-  not `DESIGN.md` tokens.
+- Tailwind scale aliases with **no** `DESIGN.md.visual.radius` key of
+  the same name: bare `rounded` (Tailwind's `DEFAULT`), `rounded-xl`,
+  `rounded-2xl`, `rounded-3xl`, `rounded-none`. These resolve to
+  Tailwind defaults, not `DESIGN.md` tokens.
+- `rounded-sm` / `rounded-md` / `rounded-lg` / `rounded-full` are
+  **allowed only in an iter whose own envelope re-binds that name**.
+  The schema's `visual.radius` keys are exactly `sm|md|lg|full`, and
+  the mandatory `theme.extend.borderRadius` injection re-binds those
+  four names to the `DESIGN.md` tokens — but the gate verifies that in
+  the iter's html rather than assuming it. An iter that omits the
+  envelope, drops a key from the `borderRadius` map, or binds it to a
+  different value renders Tailwind's default, and the alias is flagged
+  exactly as before. Same for the side/corner prefixes
+  (`rounded-t-md`, `rounded-tl-lg`, …).
 
 ### 4. box-shadow literal ban (including rgba color slot)
 
@@ -105,9 +115,23 @@ Authored forms caught:
 
 - Inline `box-shadow: 0 1px 2px rgba(15,23,42,0.05)`.
 - Tailwind arbitrary `shadow-[0_4px_6px_rgba(0,0,0,0.1)]`.
-- Tailwind scale aliases (`shadow`, `shadow-sm`, `shadow-md`,
-  `shadow-lg`, `shadow-xl`, `shadow-2xl`, `shadow-inner`,
-  `shadow-none`, `drop-shadow-*`).
+- Tailwind scale aliases with **no** `DESIGN.md.visual.shadow` key of
+  the same name: bare `shadow` (Tailwind's `DEFAULT`), `shadow-xl`,
+  `shadow-2xl`, `shadow-inner`, `shadow-none`.
+- Every `drop-shadow-<alias>` form, including `drop-shadow-sm|md|lg` —
+  the alias resolves through `theme.dropShadow`, which the mandatory
+  envelope does not inject, so it renders a Tailwind default no matter
+  what `visual.shadow` declares. The arbitrary form
+  `drop-shadow-[...]` carries its own literal and is judged like any
+  other arbitrary value: compliant when the literal is one of the
+  `visual.shadow` tokens, drift otherwise.
+- `shadow-sm` / `shadow-md` / `shadow-lg` are **allowed only in an iter
+  whose own envelope re-binds that name**. The schema's `visual.shadow`
+  keys are exactly `sm|md|lg`, and the mandatory
+  `theme.extend.boxShadow` injection re-binds those three names to the
+  `DESIGN.md` tokens — but the gate verifies that in the iter's html
+  rather than assuming it, so an iter with a missing, incomplete, or
+  overwritten `boxShadow` map still has its aliases flagged.
 
 ### Safelisted CSS-wide keywords
 
@@ -151,6 +175,81 @@ The generator MUST express every styled surface as one of:
 - One self-contained HTML file; embedded CSS / JS minimal.
 - All declared spec screens reachable; loading / empty / error /
   success states representable.
+- The compliance gate reports **one finding per distinct offending value**, not
+  one per occurrence: a single drifting token repeated across N screens is one
+  entry in `designMdViolations[]`. Fix the value once and the finding clears —
+  do not expect the count to track the number of places it appears.
+
+## Output layout — two trees, two shapes
+
+There are two directory trees and they are NOT interchangeable. The
+generator writes to exactly one of them.
+
+| Tree                                  | Shape                                                    | Written by                               | Read by                                         |
+| ------------------------------------- | -------------------------------------------------------- | ---------------------------------------- | ----------------------------------------------- |
+| `.qfai/prototypes/iter-NN/`           | one `index.html`                                         | **the generator** (you)                  | `--auto-serve`, the operator, `/qfai-implement` |
+| `.qfai/evidence/prototyping/iter-NN/` | `<screenId>.html` + `.png`, one pair per declared screen | `npx qfai prototyping iterate --capture` | `npx qfai prototyping certify`, the reviewer    |
+
+**The generator never writes the evidence tree.** The `--capture` step
+performs the fan-out: it drives a browser to each declared screen's
+contract `route`, and writes one HTML snapshot plus one screenshot per
+screen into `.qfai/evidence/prototyping/iter-NN/`. `certify` reads only
+that tree and hard-fails with "missing HTML for N declared screen(s)"
+when a declared screen has no snapshot there.
+
+### N declared screens, one file
+
+A spec declaring N screens is satisfied by **one** `index.html`
+containing N client-side routes — not N files. Each declared screen
+must be reachable at its own contract `route`, so the capture step can
+navigate to it and snapshot it independently. This is what "all
+declared spec screens reachable" above means operationally.
+
+**Which routing shapes the capture step can actually reach.** Capture
+navigates to `new URL(<contract route>, <target url>)` and treats any
+HTTP status >= 400 as a failed screen, writing no evidence. What the
+target server does with that URL therefore decides the routing shape:
+
+- `--auto-serve` starts the built-in static file server. It resolves
+  every non-root URL to a real file under the served directory and
+  returns 404 when there is none — it has no SPA fallback. With it,
+  declare **hash routes** (`/#/settings`): the browser never sends the
+  fragment, so the server always serves `index.html` and the shell
+  routes client-side.
+- **Path routes** (`/settings`) and any `history.pushState` shell need
+  a server that rewrites unknown paths to `index.html`. Run one
+  yourself and pass `--target-url`; they will 404 under `--auto-serve`.
+- Per-screen files (`--emit-skeletons`, below) are a third option, but
+  only if the contract `route` names the file: `--emit-skeletons` writes
+  `<screenId>.html`, and the static server resolves a URL to a literal
+  path — it does not append `.html`, so a `/settings` route 404s while
+  `/settings.html` serves. `htmlSourceCopy` does not help here: it runs
+  after the capture has already navigated successfully, so it cannot
+  rescue a route the server could not resolve.
+
+Pick the routing shape to match the server you will capture against,
+and keep the contract `route` values consistent with it.
+
+Opt-in **seed aid**, not an alternative output shape:
+`npx qfai prototyping iterate --emit-skeletons` (cycle 0 only) writes one
+placeholder `.qfai/prototypes/iter-00/<screenId>.html` per declared
+screen, and the `htmlSourceCopy` capture option likewise operates on
+per-screen files. Neither writes an `index.html`.
+
+An accepted iteration must still carry `iter-NN/index.html`: Handoff
+below copies it to `.qfai/prototypes/final/index.html`, and without it
+`/qfai-implement` has nothing to read. So consolidate the skeletons into
+the single-file envelope before the loop converges — including when a
+cycle-0 skeleton set scores well enough that cycle 1 would otherwise
+accept it as it stands. If you keep the per-screen files because your
+capture routing needs them, author `index.html` alongside them so the
+accepted iteration carries both.
+
+### Handoff
+
+`.qfai/prototypes/final/index.html` is a copy of the accepted
+`iter-NN/index.html` and is the deliverable `/qfai-implement` reads.
+It is not a certify input; certify never opens the `prototypes/` tree.
 
 ## Cycle 0 (seed)
 

package/assets/init/.qfai/assistant/skills/qfai-prototyping/references/handoff.md

@@ -4,9 +4,19 @@
 
 `.qfai/prototypes/iter-<final>/index.html` — the final accepted
 iteration HTML. The "final" iter is whichever iteration was the latest
-when `qfai prototyping iterate` returned exit 64 (convergence) or 65
+when `npx qfai prototyping iterate` returned exit 64 (convergence) or 65
 (max-iterations).
 
+This is the **authoring** artifact — one self-contained file with one
+client-side route per declared screen, written by the generator. It is
+a distinct tree from the **capture** artifacts at
+`.qfai/evidence/prototyping/iter-<final>/<screenId>.{html,png}`, which
+`npx qfai prototyping iterate --capture` fans out one pair per declared
+screen. Handoff mirrors the authoring artifact; `npx qfai prototyping
+certify` gates on the capture artifacts and never opens the
+`prototypes/` tree. Both must exist before handoff can complete: see
+"Output layout" in `references/generator-prompt.md`.
+
 `DESIGN.md` (root) and `.qfai/contracts/design/DESIGN.md.lock.yaml`
 remain the brand SSOT through handoff.
 
@@ -57,16 +67,35 @@ the SSOT for brand identity. There is no preserve / adapt / copy split.
 
 ## Cert
 
-Order is load-bearing: `qfai prototyping certify` requires
-`.qfai/output/validate.json` (with `counts.error === 0`) and
-`.qfai/output/verify.json` (with `status === "PASS"`) to be present
-on disk before it will seal the certificate. Run the gates in this
-order, every time:
-
-1. `qfai validate --profile prototyping --fail-on error` — writes
-   `.qfai/output/validate.json`.
-2. `/qfai-verify` — writes `.qfai/output/verify.json`.
-3. `qfai prototyping certify` — produces
+Order is load-bearing: `npx qfai prototyping certify` requires the configured
+validate report (with `counts.error === 0`) and `.qfai/report/verify.json`
+(with `status === "PASS"`) to be present on disk before it will seal the
+certificate.
+
+The two reads are not the same shape. The **validate** report is read from
+whatever `output.validateJsonPath` names — one location, no fallback. Only
+**`verify.json`** is canonical-first: it falls back to the legacy
+`.qfai/output/verify.json` and prints a migration note when it does. That
+fallback fires only when the canonical file is **absent** — a canonical file
+that exists but is unparseable, non-object, or unreadable aborts certify with a
+non-zero exit instead, so a leftover legacy `status: "PASS"` can never certify a
+run whose real gate result was never readable. A canonical file that is missing
+in both locations is reported as missing, not as a failing status.
+
+Run the gates in this order, every time:
+
+1. `npx qfai validate --profile prototyping --fail-on error` — writes the path
+   configured at `output.validateJsonPath` (default
+   `.qfai/report/validate.json`), not a fixed `.qfai/output/` literal.
+2. `/qfai-verify` — writes `.qfai/report/verify.json` with
+   `status: "PASS"` and `scope: "prototyping"`. Certify accepts no
+   other scope: `atdd` / `implement` / `full` are refused by the
+   option-B phase-isolation contract, and a `full` run at this point
+   necessarily fails the stage-5 ATDD traceability rules
+   (`QFAI-ATDD-111/112/113`). The field list and the `scope` enum are
+   specified under "Verify Output Contract" in
+   `.qfai/assistant/skills/qfai-verify/SKILL.md`.
+3. `npx qfai prototyping certify` — produces
    `.qfai/evidence/prototyping/completion-certificate.json`. The
    certificate includes `designMdPath` + `designMdSha256` for the
    locked brand identity. Use `certify --check` to verify digests

package/assets/init/.qfai/assistant/skills/qfai-prototyping/references/iteration-loop.md

@@ -21,7 +21,7 @@ one-line summary at each iter's end.
 
 ## Stop conditions (deterministic)
 
-Exit codes for `qfai prototyping iterate --cycle <n+1>`:
+Exit codes for `npx qfai prototyping iterate --cycle <n+1>`:
 
 - `0` — continue.
 - `64` — convergence: latest iter has all 4 UX axes
@@ -73,3 +73,50 @@ proceed unless the two match; the lock value is then cached into
 diverging exits with `2`. To change brand identity mid-project, edit
 `DESIGN.md`, rerun `/qfai-sdd` Phase 0 to refreeze the lock, and
 start `/qfai-prototyping` from cycle 0.
+
+## Sealed loop
+
+A loop is **sealed** once `prototyping.json` records
+`stopReason: "axes-exceptional"` together with an `acceptedIterationIndex`.
+That is the converged state — the only one `--check-convergence` reports as
+converged and the only one `npx qfai prototyping certify` will seal. On a sealed
+loop `npx qfai prototyping iterate --cycle N` refuses with exit `2` for any `N`
+greater than the accepted index, and writes nothing — no `iter-NN/` directory
+is created. That refusal is deliberate: such a directory is stale by
+construction, and the stale-iteration-directory check in
+`npx qfai prototyping certify` hard-fails on it.
+
+`license-verify-fail` and `input-error` do **not** seal the loop. They are
+states you are expected to fix and retry, so the same cycle can be re-run and
+the fix verified.
+
+`max-iterations` does not seal the loop either, but it is **not** retryable in
+the same way: the recorded `iter-09` remains the last iteration, so
+`shouldStop()` returns `max-iterations` again and every `--cycle N >= 1` exits
+`65` before any path is assigned. Its only recovery is the cycle-0 reset
+below.
+
+Two paths remain open on a sealed loop:
+
+- **Seal it** — run `npx qfai prototyping certify`. This is the normal
+  next step after convergence.
+- **Start over** — run `npx qfai prototyping iterate --cycle 0
+--target-url <url> --force`. Cycle 0 is a hard reset and is never
+  refused by the sealed-loop guard; it also deletes stale `iter-NN`
+  directories. `--force` is required, not optional: a converged loop
+  always has an `iter-00`, and the cycle-0 destructive-rerun gate
+  refuses to overwrite it without the flag. With it, `iter-00` is moved
+  to `iter-00.backup-<ISO>` before the reset, so the prior loop is
+  recoverable.
+
+Re-running the accepted cycle itself (`--cycle <acceptedIterationIndex>`)
+is not refused by the sealed-loop guard — that would be a redo of recorded
+work, not an extension past the seal — but it does not re-run the cycle
+either: the convergence gate reads the same recorded iteration, reports
+`axes-exceptional` and exits `64` without assigning paths or writing
+anything. Treat it as a state read, and prefer
+`npx qfai prototyping iterate --check-convergence`, which reports the recorded
+`stopReason` / `acceptedIterationIndex` without the exit-code ambiguity.
+
+If an `iter-NN` directory was created that should not have been, delete
+it before running certify; there is no reserved quarantine name.

package/assets/init/.qfai/assistant/skills/qfai-prototyping/templates/DESIGN.md.sample

@@ -43,6 +43,12 @@ accessibility:
   motion: "respect-reduced-motion"
 ---
 
+<!-- QFAI-SAMPLE-DESIGN-MD: this is the qfai sample brand, NOT your product's brand.
+     Replace the front-matter and the body below with this product's own brand SSOT
+     (`/qfai-discussion` emits the draft), then DELETE this comment. While this comment
+     is present `qfai validate` reports QFAI-DCON-034 and /qfai-sdd Phase 0 refuses to
+     freeze the file's sha256 as the project's brand contract. -->
+
 # Brand Philosophy
 
 Acme Ledger is a calm, confident financial comparison surface. The interface

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

@@ -2,7 +2,7 @@
 name: qfai-sdd
 title: QFAI SDD Unified (Triage/Outline/Slice/Plan/Delta)
 description: "Triage incoming requirements against existing specs, then create or update layered SDD artifacts (_policies + spec-*) in one workflow."
-argument-hint: "[<spec-id-or-name>] [--auto]"
+argument-hint: "[<spec-id-or-name>] [--contract <CON-ID>] [--auto]"
 allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
 roles:
   [
@@ -37,6 +37,8 @@ QFAI Skill Body (SSOT)
 ```
 Stage 0 Preflight  -> Stage 1 Triage  -> Phase 0 Contracts-first
                   -> Phase 1 Outline -> Phase 2 Slice (per spec)
+                  -> Phase 2b Seed tdd/test-list.md (per spec)
+                  -> Phase 2c Obligation reconciliation (per spec)
                   -> Phase 3 Plan finalize -> Phase 4 Delta update
 ```
 
@@ -114,7 +116,7 @@ Follow `.qfai/assistant/constitution/shared-skill-delegation-baseline.md`.
 
 ### Delegation Failure (Hard Stop)
 
-- Do not simulate roles. If the first required delegation fails, stop the stage and report remediation.
+- Do not simulate roles. Classify the failure per the baseline taxonomy first: `unavailable` stops the stage with a remediation report; `saturated` uses the bounded retry branch and keeps the stage open.
 
 Stage minimum roles:
 
@@ -123,7 +125,13 @@ Stage minimum roles:
 - `test-design-analyst` drafts traceability, examples, and test-design.
 - `product-experience-architect` is added when the target is UI-bearing.
 - `orchestrator` integrates outputs and presents for confirmation; never drafts the primary artifact and never self-approves.
-- `completion-reviewer` is delegated independently. Required field: `Status (PASS/REVISE)`.
+- `completion-reviewer` is delegated independently. Required field: `Status (PASS/REVISE/PENDING)`; `PENDING` marks an unrun gate and never counts as `PASS`.
+
+Author↔reviewer separation (MUST): drafting roles and reviewing roles above are routed from one
+list, but no sub-agent may review an artifact it drafted or edited in this run. `independent` is
+defined normatively in
+`.qfai/assistant/constitution/shared-skill-delegation-baseline.md#definition-independent-reviewer-normative`,
+and every reviewer response must carry its `Authored/edited under review:` attestation.
 
 Reviewer routing is fixed by `.qfai/assistant/manifest/agent-routing.yml` and `.qfai/assistant/manifest/review-profiles.yml`.
 
@@ -132,7 +140,7 @@ Reviewer routing is fixed by `.qfai/assistant/manifest/agent-routing.yml` and `.
 - Default: `completion-reviewer`.
 - Conditional: `architecture-reviewer` (structural / contract / CLI), `product-surface-reviewer` (UI-bearing), `qa-gatekeeper` (validate / coverage / runtime / prototyping evidence affected).
 - Drift Protocol compliance is mandatory; reviewers MUST verify no rejected option was reintroduced and no drift from prior decisions.
-- Test-layer policy is checked against `.qfai/assistant/catalog/test-layers.md`; layer pinning is enforced (US→E2E, TC→Integration, CON-API→API).
+- Test-layer policy is checked against `.qfai/assistant/catalog/test-layers.md`; annotation routing is enforced by `.qfai/assistant/catalog/test-layers.md#annotation-routing-is-by-id-type-not-by-level`, which owns the US / TC / CON-API mapping. A `TC-*`'s `Level` is **not** a constant: derive it per TC with `.qfai/assistant/catalog/test-layers.md#layer-derivation-procedure-normative`, keeping the row inside L1–L3 and defaulting to Integration only when the derivation is genuinely indeterminate. A missing `tests/integration/**` trace never rewrites a derived `Level`.
 - Coverage floors / ratios are planning signals, not gates; reviewers must not block on them.
 - Do not declare DONE until all routed blocking reviewers return `PASS`.
 
@@ -141,6 +149,10 @@ Reviewer routing is fixed by `.qfai/assistant/manifest/agent-routing.yml` and `.
 - Without argument: target all capabilities in `_policies/03_Capabilities.md`.
 - Run Contracts-first and Outline once per batch.
 - Delegate Slice in parallel per spec.
+- Parallel delegation here is bound by the stage-independent Concurrency rules in
+  `.qfai/assistant/constitution/workflow.md#concurrency-stage-independent-mandatory`:
+  worktree separation, or the declared degraded mode, plus mandatory commit
+  scoping (`git add <paths>`; never `git add -A` / `git add .` / `git commit -a`).
 - Validate gate and Review gate run once at batch tail after all target specs are integrated.
 
 ## Work Orders Summary
@@ -151,7 +163,7 @@ Per-spec evidence at `.qfai/evidence/sdd-<spec-id>.md` is mandatory and MUST inc
 
 - Follow `references/review-cycle-playbook.md`.
 - Footer SSOT: `references/rcp_footer.md`.
-- Allowed reviewer verdicts: `PASS` and `FAIL`.
+- Allowed in-flight reviewer verdicts: `PASS` and `REVISE` (`REVISE` serializes to `status: "FAIL"` in the pack summary).
 
 ## Workflow Convention
 
@@ -175,36 +187,65 @@ Follow `.qfai/assistant/constitution/shared-skill-operating-baseline.md#delta-re
 
 - With argument (`/qfai-sdd <spec-id-or-name> [--auto]`): update only the matched single spec target.
 - Without argument (`/qfai-sdd`): target all capabilities listed in `_policies/03_Capabilities.md`.
+- Contract-scoped (`/qfai-sdd --contract <CON-ID>`): run Stage 0 + Phase 0 (Contracts-first) + Phase 4 (Delta update) only, against the named contract and the specs that reference it. This is the invocation `constitution/drift-protocol.md#when-drift-is-detected` step 4 names for a contract-class upstream artifact; without it, a contract-only Change Request had no rerun narrower than the whole spec.
 - Reordering capability-to-spec mapping is a Change Request decision and must not be done implicitly.
 
 ## Critical Constraints
 
-1. Use only skill-local templates under `.qfai/assistant/skills/qfai-sdd/templates/contracts`, `templates/report`, and `templates/specs`.
+1. Use only templates under `.qfai/assistant/skills/qfai-sdd/templates/` — the whole directory, not an enumerated subset, so a new template directory is covered on the day it ships.
+   - Named cross-skill exception: `.qfai/assistant/skills/qfai-prototyping/templates/DESIGN.md.sample` (Phase 0 DESIGN.md Freeze). It is an exception, not a licence to read other skills' templates.
+   - Never invent a layout for an artifact a template already covers.
 2. Always write `.qfai/report/preflight_summary.md` before generating shared/spec artifacts.
 3. Contracts-first is mandatory; UI-bearing targets must be normalized into `.qfai/contracts/design/**` and `.qfai/contracts/ui/**` per `references/ui-design-contract-normalization.md`. UI-bearing targets MUST also validate the consuming-project root `DESIGN.md` and freeze its sha256 into `.qfai/contracts/design/DESIGN.md.lock.yaml` (see Phase 0 DESIGN.md Freeze below).
 4. `_policies/05_Contracts.md` must include a Contract Index aligned with `.qfai/contracts/**`.
+   - Phase 0 must also reconcile paired contracts against each other, not only validate each file: every terminal state, status enum value, and error code an API contract mandates must be representable in the paired DB contract. See `references/contract-artifact-rules.md#cross-contract-reconciliation-must`. The reviewer gate checks the pairing before sign-off.
 5. `_policies/04_Business-Flow.md` must be Markdown with Mermaid `flowchart` or `sequenceDiagram`.
 6. `05_Examples.md` must include `EX-ID` and `BR-Ref` mappings.
-7. `06_Test-Cases.md` must include `TC-ID`, `EX-Ref`, `AC-Refs`, and `Type`, with normal-path plus error/boundary coverage.
-8. Stop only when `qfai validate --profile sdd --fail-on error --format github | tee .qfai/report/validate.log` exits with `error=0`.
+7. `06_Test-Cases.md` must include `TC-ID`, `Level`, `EX-Ref`, `AC-Refs`, and `Type`, with normal-path plus error/boundary coverage. `Level` gates `TDDLIST_TC_NOT_COVERED` at `error`, so it is required, not optional.
+8. Stop only when `npx qfai validate --profile sdd --fail-on error --format github` exits with `error=0`.
 
 ## Required Process
 
 1. Stage 0: Preflight (stop on blockers).
 2. Stage 1: Triage (classify + approve + persist Triage table).
 3. Write `.qfai/report/preflight_summary.md`.
-4. Phase 0: Contracts-first (UI-bearing targets normalize in this phase, and freeze root `DESIGN.md` per the Phase 0 DESIGN.md Freeze step below).
+4. Phase 0: Contracts-first (UI-bearing targets normalize in this phase, and freeze root `DESIGN.md` per the Phase 0 DESIGN.md Freeze step below). Close Phase 0 with the cross-contract reconciliation step in `references/contract-artifact-rules.md#cross-contract-reconciliation-must`.
 5. Phase 1: Outline (`_policies/01..11`).
-6. Phase 2: Slice (per spec, gate each).
-7. Phase 3: Plan finalize (after at least one slice gate passes).
-8. Phase 4: Delta update.
-9. Run validate; fix source-layer artifacts and rerun until `error=0`.
-10. Triage density-smell warnings in `.qfai/report/specs-coverage/spec-*.md`.
+6. Phase 2: Slice (per spec, gate each with `npx qfai validate --profile sdd --fail-on error --spec <spec-id>` so a parallel worker gates on its own spec only and does not import a sibling agent's in-flight failures). A `--spec` run writes `<report>/validate.spec-<id>.json` and never the shared `validate.json` / `validate-<profile>.json`, so parallel workers cannot race on one file; an unknown or unparseable `--spec` value fails the run (`QFAI-SCOPE-001` / `QFAI-SCOPE-002`) instead of silently widening to the whole repo.
+7. Phase 2b: Seed each target spec's `tdd/test-list.md` from `06_Test-Cases.md`
+   — one row per coverage-target TC, `Status = todo`; copy
+   `templates/specs/spec/tdd/test-list.md` when absent. Without it
+   `/qfai-implement` starts with zero selectable items. **Seeding is a delta,
+   not a regeneration, in both directions**: unchanged rows keep their state,
+   new TCs append at `todo`, and changed / removed TCs are reset or retired
+   under the upstream-reset rule (`references/sdd-phase-checklists.md`).
+8. Phase 2c: Obligation reconciliation (per spec). Re-read `.qfai/contracts/**`
+   against the `BR` / `AC` Phase 2 produced: name the realizing contract for
+   each, and resolve every persisted attribute it names to a column, field or
+   enum member there — directly or by a stated join. Phase 0 froze the contracts
+   before these obligations existed, so this is the only step that checks they
+   are realizable. See
+   `references/contract-artifact-rules.md#obligation-reconciliation-must--phase-2c`.
+   Fix the contract or the obligation here; both are owned by this skill, and a
+   mismatch carried downstream reaches an implementer who can fix neither.
+9. Phase 3: Plan finalize (after at least one slice gate passes).
+10. Phase 4: Delta update.
+11. Run validate; fix source-layer artifacts and rerun until `error=0`.
+12. Triage density-smell warnings in `.qfai/report/specs-coverage/spec-*.md`.
+
+## Work-log entries
+
+Write a `.qfai/steering/<id>.md` entry when this stage hits one of the conditions in the `kind` trigger table of `.qfai/assistant/catalog/worklog-entry.schema.md` — `blocker`, `handoff`, `consultation-needed` and `decision` are the ones this stage reaches most. `npx qfai validate` polices the surface but nothing else asks for an entry, so an unwritten one is simply lost.
 
 ## Mandatory Outputs
 
 - Shared `_policies/01..11` files
 - Target `spec-*/01..10` files (with valid `Status:` bullet)
+- `spec-*/16_Traceability-ledger.md` when the spec's `BR-*` / `AC-*` are linked to implementation
+  files (optional artifact; create or refresh it in the same change as the BR/AC it links, from
+  `templates/specs/spec/16_Traceability-ledger.md`). Without it `QFAI-TRACE-002` is emitted and the
+  BR/AC ↔ implementation integrity check (`QFAI-TRACE-001`) is skipped for that spec. See
+  `references/spec-traceability-rules.md#traceability-ledger-16_traceability-ledgermd`.
 - Triage section in every changed `09_delta.md` (per-spec) or `_policies/10_delta.md` (cross-spec)
 - Updated contracts under `.qfai/contracts/**`; UI-bearing targets normalize design/ui contracts
 - `.qfai/report/preflight_summary.md`
@@ -220,16 +261,25 @@ When the target spec is UI-bearing, Phase 0 MUST freeze the brand SSOT:
    missing, stop and ask the user to run `/qfai-discussion` (which
    emits the draft) or to author it manually using the sample at
    `.qfai/assistant/skills/qfai-prototyping/templates/DESIGN.md.sample`.
-2. Call `parseDesignMd(text)`. If the result is `{ error: ParseError }`,
+2. Call `isUnreplacedDesignMdSample(text)`. If it returns `true`, the file
+   is still a qfai sample brand and MUST NOT be frozen: stop and ask the
+   user to author this product's own brand SSOT, deleting the
+   `QFAI-SAMPLE-DESIGN-MD` marker comment if present (samples from
+   releases older than the marker are recognised by content instead).
+   `npx qfai init` seeds the sample into the project root and never overwrites
+   it, so step 1's missing-file check cannot catch this — an unreplaced
+   sample parses and validates by construction, and freezing it binds
+   `/qfai-prototyping` and the reviewer lock rule to a fictional brand.
+3. Call `parseDesignMd(text)`. If the result is `{ error: ParseError }`,
    stop and report `path` / `code` / `message` for the parse error.
    Otherwise the result is `{ data: DesignMd; body: string }`; pass
    `data` to `validateDesignMd(data)`. If that issue list is
    non-empty, stop and report each issue. Both functions, together with
    `hashDesignMd` and the `DesignMd` / `ParseError` / `ParseResult` /
    `ValidationIssue` types, are re-exported from the public `qfai`
-   package entry (`import { parseDesignMd, validateDesignMd, hashDesignMd } from "qfai"`).
-3. Call `hashDesignMd(text)` to compute sha256 over the raw bytes.
-4. Write `.qfai/contracts/design/DESIGN.md.lock.yaml` from the
+   package entry (`import { parseDesignMd, validateDesignMd, hashDesignMd, isUnreplacedDesignMdSample } from "qfai"`).
+4. Call `hashDesignMd(text)` to compute sha256 over the raw bytes.
+5. Write `.qfai/contracts/design/DESIGN.md.lock.yaml` from the
    template at
    `templates/contracts/design-md-lock.sample.yaml` with these fields:
    - `designMdPath: "DESIGN.md"`
@@ -237,7 +287,7 @@ When the target spec is UI-bearing, Phase 0 MUST freeze the brand SSOT:
    - `frozenAt: <UTC ISO-8601>`
    - `schemaTokens.colors`, `fontFamilies`, `radii`, `shadows`
      enumerated per the sample.
-5. Record the freeze in `_policies/05_Contracts.md` under the Contract
+6. Record the freeze in `_policies/05_Contracts.md` under the Contract
    Index. The lock yaml plus root `DESIGN.md` are the only brand
    contract; per-aspect brand yaml contracts have been removed.
 
@@ -250,7 +300,14 @@ Run the full checklist from `references/sdd-quality-gate.md`. The gate also cove
 
 ## Evidence
 
-Create `.qfai/evidence/sdd-<spec-id>.md` with: Objective, Inputs reviewed, Preflight summary path, Triage decisions (op + approver per row), Open questions, Decisions made, Work performed, Commands executed, Validate evidence paths, Work Orders Summary, Gaps / Open risks, Final status.
+Create `.qfai/evidence/sdd-<spec-id>.md` from `templates/evidence/sdd-spec.md`. That template is the
+canonical layout for this artifact — copy it, keep every `##` heading in order, and fill it in.
+
+Required sections, in order (the template is authoritative if the two ever disagree): Objective,
+Inputs reviewed, Preflight summary path, Triage decisions (op + approver per row), Open questions,
+Decisions made, Work performed, Commands executed, Validate evidence paths, Work Orders Summary,
+Gaps / Open risks, Final status. Work Orders Summary uses the fixed 6-column schema from
+`shared-skill-delegation-baseline.md`; its `Status` and `Final status` accept only `PASS` or `REVISE`.
 
 ## Done Declaration
 
@@ -270,7 +327,8 @@ When this skill completes, provide a final user-facing message enumerating next
 - Proceed (recommended): `/qfai-prototyping`.
 - Test-first path: `/qfai-atdd`.
 - Spec pack needs correction: rerun `/qfai-sdd` and regenerate evidence.
-- Confirm contracts referenced by `_policies/05_Contracts.md` exist under `.qfai/contracts/**`.
+- Confirm contracts referenced by `_policies/05_Contracts.md` exist under `.qfai/contracts/**`,
+  and that Phase 2c reconciled every `BR` / `AC` against them — existence is not realizability.
 
 ## Default Autopilot Policy
 
@@ -295,6 +353,8 @@ A skill MAY narrow the auto-decide bucket (drop entries) but MUST NOT widen it.
 
 project_memory:
 
-- Phase order is fixed: Stage 0 Preflight → Stage 1 Triage → Phase 0 Contracts-first → Phase 1 Outline → Phase 2 Slice → Phase 3 Plan finalize → Phase 4 Delta update; do not reorder.
+- Phase order is fixed: Stage 0 Preflight → Stage 1 Triage → Phase 0 Contracts-first → Phase 1 Outline → Phase 2 Slice → Phase 2b Seed tdd/test-list.md → Phase 2c Obligation reconciliation → Phase 3 Plan finalize → Phase 4 Delta update; do not reorder.
+- Phase 2c reconciles contracts against the BR/AC written after them: Contracts-first freezes the contract before its obligations exist, and Phase 2c is the only step that checks they are realizable.
+- Phase 2b seeds each target spec's tdd/test-list.md from 06_Test-Cases.md (one row per coverage-target TC, Status = todo) and is a delta: existing rows keep their TDD-ID, Status, Test file, Selector, DR-ID and Evidence.
 - Append-first is the Stage 1 default: UPDATE on an active spec whose subject tokens overlap; CREATE only when there is zero overlap AND the REQ adds a new CAP-NNNN, registered before the CREATE row.
 - Phase 0 DESIGN.md Freeze is mandatory for UI-bearing targets; .qfai/contracts/design/DESIGN.md.lock.yaml is the brand-lock SSOT.