qfai 1.10.0 → 1.10.2

package/assets/init/.qfai/assistant/skills/qfai-atdd/references/scaffolding.md

@@ -0,0 +1,71 @@
+# Scaffolding
+
+`npx qfai atdd scaffold --spec <spec-id>` bulk-emits one placeholder test per
+`TC-*` **this skill owns**, each carrying its `QFAI:SPEC-XXXX:TC-YYYY`
+annotation. Skeletons land in `tests/integration/<spec-id>/` — the directory
+`QFAI-ATDD-112` scans — so a filled-in skeleton counts as coverage. It is
+idempotent: existing files are left untouched.
+
+## Which language the skeleton is written in
+
+The skeleton's language is derived from
+`qfai.config.yaml#validation.traceability.testFileGlobs` — the same key
+`QFAI-ATDD-112` derives its scan extensions from, so the file the command
+writes is always a file the gate reads. A JS/TS glob set (and the unconfigured
+default) gets a `vitest` body; a Python one gets a `unittest.TestCase`
+subclass, which pytest **and** `python -m unittest discover` both collect —
+the globs name an extension, never a runner, and a module-level `def test_...`
+that unittest never collects would let you clear the gate with zero tests run.
+A stack with neither is refused with a non-zero exit naming the derived
+pattern: author those TCs by hand in `tests/integration/<spec-id>/`, keeping
+the `QFAI:SPEC-XXXX:TC-YYYY` annotation.
+
+The file **path** follows the same key one level finer. The extension is one
+the globs actually admit (`tests/**/*.test.js` gets `.test.js`, not `.test.ts`),
+and the basename follows the configured convention — `test_<tc_id>.py` or
+`<tc_id>_test.py`, `<TC-ID>.test.ts` or `<TC-ID>.spec.ts`; extglob patterns
+(`*.@(test|spec).ts`) are read the way fast-glob reads them. `QFAI-ATDD-112`
+widens to the bare extension, so a file your runner does not collect would
+clear the coverage gate with a test that never runs. The check is made against
+the **whole** destination path, directories included, and it is case-sensitive
+the way fast-glob is: globs that only cover `src/**` do not reach
+`tests/integration/<spec-id>/`, and `TEST_*.py` does not admit the lowercase
+name the command emits, so it refuses in both cases rather than writing a file
+nothing runs. `testFileExcludeGlobs` is applied as well — a destination you
+have excluded is one your own test scan skips. When several languages are
+configured, every one of them is tried and the first whose path your globs
+admit wins, so a repository with `src/**/*.test.ts` and `tests/**/*.py` gets
+the Python skeleton. Add a glob that covers the scaffold directory, or author
+those TCs by hand.
+
+A skeleton an earlier run wrote under a different convention is removed only
+while it is still the untouched skeleton the command emitted. Any file you have
+edited is kept and named on stderr so you can port it — including one where you
+implemented the assertion inside `it.skip(...)` but left the `TODO` comment
+above it, which still looks like a placeholder to the marker heuristic.
+
+The refusal is evaluated only when the spec actually has L3 skeletons to emit,
+so sweeping many specs on an unsupported stack still succeeds for the ones with
+nothing in scope.
+
+## Which TCs are skipped, and why
+
+Skeletons are integration-only, so two groups of TC are skipped, both named on
+stderr.
+
+`L1` / `Unit` and `L2` / `Component`: their skeleton would land in
+`tests/integration/**`, the duplication the Coverage obligations section
+forbids, and `QFAI-ATDD-112` would not count it — filling one in discharges
+nothing. Their ledger row under `/qfai-implement` is where they are owed.
+
+`L4` / `API` and `L5` / `E2E`: their home is `tests/api/**` / `tests/e2e/**`, so
+an integration skeleton is both uncounted and a forbidden reference
+(`QFAI-ATDD-123`). Author those by hand in their own directory — or re-file the
+obligation as `CON-API-*` / `US-*`, which is what a `TC-*` at L4/L5 usually
+means (`.qfai/assistant/catalog/test-layers.md#annotation-routing`).
+
+## A skeleton is not a discharge
+
+A skeleton left in placeholder shape across repeated validate runs escalates
+(`qfai.config.yaml#atdd.scaffoldEscalateCycles`), so scaffolding is a start, not
+a discharge of the obligation.

package/assets/init/.qfai/assistant/skills/qfai-atdd/references/shared-test-artifacts.md

@@ -0,0 +1,124 @@
+# A shared test artifact outlives the row that recorded it
+
+P1c closes one row before the next test is written, so the `RED test manifest`
+of a `done` row addresses a fixture, snapshot or helper that a **later** row may
+still edit. The hash then disagrees with the tree, and a `done` row has no
+re-entry edge of its own — so the spec either accepts stale evidence or cannot
+be closed.
+
+**Stabilise first where the row can see it coming.** The artifacts an
+acceptance test owns — fixtures, snapshots, helpers under the test tree — are
+written in P2-P4 with every row's obligation in view, not grown one row at a
+time. Where that holds, no later row edits them and the manifests stay true.
+
+**Where a later row does have to edit one, it re-verifies the rows that read
+it — and records that on itself.** The editing row already runs its own
+selector; run the earlier rows' selectors in the same pass and record them in
+**the editing row's** entry, under `Shared-artifact re-verify`: one line per
+earlier row naming **its spec and `TDD-ID` together** (`spec-0002/TDD-0001`) and
+the evidence file that row's anchor points at, then the selector re-run, its
+result, and the artifact's new manifest and hash. A `TDD-ID` is unique within a
+ledger, not across them, and one fixture is read by acceptance tests from
+several specs — named by id alone, a re-verify could clear a hash mismatch on a
+row in the wrong spec, or fail to clear the right one.
+
+**The machine-readable form is fixed.** Write a `Shared-artifact re-verify`
+heading with one `spec-NNNN/TDD-NNNN` subsection per consumer one level below
+it, carrying these fields: `Evidence file`, `Revision`, `Selector`,
+`Re-verify command`, `Re-verify result`, `Proof command`, `Proof result`,
+`Restored GREEN command`, `Restored GREEN result`, `RED test manifest`, and
+`RED test hash`. Both GREEN results are PASS outcomes, the proof result is the
+observed failure, `Revision` names a tree in one of the two forms
+`../../qfai-implement/references/evidence-revision.md` defines, and every
+command is the exact command executed. Gate item 10 accepts a moved current
+manifest only when this complete subsection targets the same spec/item,
+evidence file and selector, and its manifest/hash recompute from the current
+artifacts. Prose mentioning a re-run, or a subsection for another item, clears
+nothing.
+
+**And it is fixed where it is written, not only in what it says.** The record
+goes **inside the editing row's own entry** — `#### Shared-artifact re-verify`
+under that `### TDD-NNNN`, ahead of its review and checkpoint fields, so the
+`audited evidence hash` its reviewers recorded covers these bytes. That
+placement is the whole claim: a block written anywhere else is a paragraph
+nobody audited, and one appended to the consumer's own `done` entry would be
+the row clearing its own mismatch. Gate item 10 reads a record only from an
+entry whose recorded `Spec` and `Code quality audited evidence hash` still
+recompute over it, and never from the consumer's own item.
+
+**When this stage has no row of its own, the record is stage-level.** A fresh
+spec is the ordinary case here and can own no ATDD row at all, while still
+creating and editing the fixtures a completed spec's handed-over rows read. With
+the record tied to an "editing row" there was nowhere to put it: the re-run was
+made and had no home, so the earlier row's `RED test hash` stayed mismatched
+with nothing able to clear it, or the change was accepted unverified. Write the
+same lines under `## Shared-artifact re-verify` in the stage evidence file
+(`.qfai/evidence/coverage-depth-<spec-id>.md`, beside `## Final status`), with
+the same identity — spec and `TDD-ID` together — and the same "a passing re-run
+is not enough on a row that has a proof" rule below. A consumer clearing a
+mismatch reads **both** places: the editing row's entry when one exists, and the
+stage block of any stage that touched the artifact. `/qfai-implement`'s gate
+item 10 does not run on a spec with no rows, so this block is checked where the
+stage's own pack seal is: it is inside the sealed stage evidence, so a record
+added after the fact moves the seal. A stage block is read only from
+`.qfai/evidence/coverage-depth-<spec-id>.md` and only when that file's
+`## Final status` names its `Review pack` and a `Review pack seal` that still
+recomputes from it — the stage has no item entry to hold an audit hash, so the
+seal is what stands in its place.
+
+**A passing re-run is not enough on a row that has a proof.** Weakening an
+assertion helper, a snapshot or an expected-value fixture leaves the earlier
+row's selector passing while making it tautological — and its recorded
+`Oracle proof` was taken against the artifact as it was, so it no longer shows
+what `qa-gatekeeper` requires: that the **current** test fails when the
+predicate the row owns is broken. For each affected row that carries one,
+re-run its original mutation — the one its `Oracle proof` plan or
+`Satisfied-by` names — under the changed artifact, capture the failure, revert,
+and record the restored GREEN, in the same `Shared-artifact re-verify` block.
+A row whose mutation no longer fails the test is the tautology this exists to
+catch, and the editing row does not reach `done` until it is repaired.
+
+**This stage owns no production agent, so on a zero-row stage the mutation is
+handed over.** Every phase here authors tests; none edits production code, and
+the rows being re-verified are already `done`, so `/qfai-implement`'s named-row,
+`todo` and `review-fix` entry paths do not reach them either. Left as written,
+the stage had two ways out and both were wrong: edit production in breach of its
+own Non-goals, or leave the shared fixture's mismatch permanently unclearable.
+So define the handoff explicitly, and keep it transient: hand
+`/qfai-implement` a **mutation-only request** naming, per affected row, its
+`spec/TDD-ID`, the mutation its `Oracle proof` plan or `Satisfied-by` names, and
+the selector to run under the changed artifact. That skill applies the mutation,
+captures the failure, **reverts it in the same step** and returns the pair. It
+does **not** reopen the row: the status stays `done`, no round block is opened,
+and nothing is written to that row's evidence — the returned proof is recorded
+here, in this stage's `Shared-artifact re-verify` block, like every other line
+in it. A `done` row has no legal transition that would let it re-observe
+anything, which is exactly why the proof belongs to the stage that moved the
+artifact rather than to the row that owns the test. **A row whose re-run fails is not
+re-verified** — it is a regression the editing row introduced, and the editing
+row does not reach `done` until it is fixed, exactly as any other failure in
+its own checkpoint.
+
+**The earlier rows' entries are not touched**, and that is deliberate on two
+counts. There is no legal reopen for them: `done` has one exit, the upstream
+reset, and it requires an approved upstream change — a sibling editing a fixture
+is not one. And their evidence is a record of an observation, not a claim about
+the present: a `RED test hash` addresses the manifest **as it was when that RED
+was taken**, which is the only thing it can honestly say. Appending to them
+would also break the very verdicts that closed them, since the audit hash covers
+the entry.
+
+**And the consumer has to accept that pairing.** The completion gate
+recomputes `RED test hash` for every handed-over row from the current manifest,
+so an earlier row whose shared artifact was edited mismatches **by
+construction** — and the mismatch route sends it back here for a fresh RED,
+which a `done` row cannot take. A mismatch is cleared instead by a
+`Shared-artifact re-verify` entry on the editing row that names this `TDD-ID`,
+records the re-run and the re-taken proof, and carries the artifact's new
+manifest and hash: that is the evidence the recomputation was looking for, made
+where a row is still open. Without such an entry the mismatch stands.
+
+So the pairing is: the earlier row keeps the observation it made, and the row
+that moved the ground under it carries the proof that the observation still
+holds. The editing row's own reviewers and checkpoint audit that proof, which is
+what makes it evidence rather than an assertion.

package/assets/init/.qfai/assistant/skills/qfai-atdd/references/stale-manifest.md

@@ -0,0 +1,34 @@
+# A project whose manifest predates this contract
+
+`npx qfai init --force` regenerates `assistant/skills/**` and `assistant/agents/**`
+but leaves `assistant/manifest/**` alone: those are the declarative files
+`qfai-configure` owns, and overwriting a project's adjusted agent taxonomy is
+the worse failure. So an existing project can take this skill's update without
+taking the `red` phase the update relies on.
+
+**Two files are stale, not one.** `agent-routing.yml` is the obvious one, and
+`agent-catalog.yml` carries each role's `developer_instructions` — the reviewer's
+own contract — which `constitution/agent-selection.md` treats as SSOT alongside
+routing. An old catalog's `qa-gatekeeper` does not know that `Satisfied-by` takes
+a path and symbol, that an ATDD row's evidence lives in `atdd-<spec-id>.md`, that
+a RED-time Oracle proof is a plan, or that an item cycle is exempt from the
+completion inputs — so it REVISEs correct handoffs, and routing it by hand does
+not help.
+
+The gate still applies, and the remedy is to bring both files forward:
+
+1. **Diff the two files against the installed package** —
+   `node_modules/qfai/assets/init/.qfai/assistant/manifest/agent-catalog.yml` and
+   `agent-routing.yml` — and merge the shipped roles' contracts in, keeping the
+   project's own routing choices and any roles it added. This is the step that
+   actually moves the files. `/qfai-configure` owns these manifests as
+   artifacts, which is why `init --force` leaves them alone, but it edits what
+   the project has rather than reconciling it against the package: there is no
+   migration to invoke, so do not wait for one.
+2. **Until that merge has run**, route `qa-gatekeeper` for the branch-1 rows by
+   hand at P1b **and state in the evidence file that the catalog predates this
+   contract**, so a REVISE that cites a rule the current contract does not have
+   is read as the stale input it is rather than as a finding about the row.
+
+A missing phase is a stale manifest, never the gate not applying — and the same
+is true of the production owners `qfai-implement`'s red phase needs for step 3c.

package/assets/init/.qfai/assistant/skills/qfai-atdd/references/test-case-depth-checklist.md

@@ -3,6 +3,20 @@
 This checklist ensures test cases cover not only happy paths but also boundary values, error paths, edge cases, and combinatorial scenarios.
 Reviewers MUST use this checklist when evaluating test case completeness during ATDD and SDD review gates.
 
+## Where the matrix lives
+
+Re-running `/qfai-atdd` recomputes which cells are `❌`. It does not recompute
+_why_ an uncoverable obligation was accepted, and that judgement is what
+discharges the "no unjustified `❌`" gate — so the matrix is a **governance
+record**, not a regenerable log.
+
+The per-item ATDD evidence is committed because ledger anchors resolve into it,
+but the matrix remains a separate governance artifact with its own validation
+contract and lifecycle. Embedding it in a ledger-evidence entry would not
+satisfy that contract. Write the matrix and one justification per `❌` to
+`.qfai/evidence/coverage-depth-<spec-id>.md`; the stage evidence file links to
+it rather than restating it.
+
 ## 1. Equivalence Partitioning (同値分割)
 
 For each input parameter or condition:
@@ -79,6 +93,13 @@ case's assertion can fail. A test that cannot fail satisfies every category.
 Reviewers and test-design-analysts MUST produce this matrix for each spec under review.
 Mark each cell: ✅ covered, ⚠️ partial, ❌ missing.
 
+**Home: `.qfai/evidence/coverage-depth-<spec-id>.md`.** That path is negated in
+the managed `.gitignore` block, so the matrix and the justifications below it
+are committed. The per-item `atdd-<spec-id>.md` is committed too, but it is the
+ledger's evidence payload, not the matrix artifact that the PASS/REVISE criteria
+below read. Write the matrix once, in its own file, and link it from the stage
+evidence.
+
 | US/TC ID | Normal path | Error path | Boundary values | Special values | State transitions | Combinatorial | Oracle strength | Status |
 | -------- | ----------- | ---------- | --------------- | -------------- | ----------------- | ------------- | --------------- | ------ |
 | US-0001  | ✅/⚠️/❌    | ✅/⚠️/❌   | ✅/⚠️/❌        | ✅/⚠️/❌       | ✅/⚠️/❌          | ✅/⚠️/❌      | ✅/⚠️/❌        | —      |
@@ -91,9 +112,25 @@ Mark each cell: ✅ covered, ⚠️ partial, ❌ missing.
   category cells are ✅ and whose Oracle strength cell is ❌ is a REVISE: it has
   cases in every category and no evidence that any of them can fail.
 - **REVISE**: Any cell is ❌ without an explicit justification (e.g., Decision Record).
+- **A justification counts only where it survives.** It goes under the matrix in
+  `.qfai/evidence/coverage-depth-<spec-id>.md`, naming the cell, why the
+  obligation is not coverable at this layer, and the `DR-*` or `CR-*` that
+  carries the decision when one exists. A justification recorded anywhere else
+  under `.qfai/evidence/**` does not satisfy the matrix's dedicated artifact
+  contract and cannot discharge this gate.
 
 ### Usage
 
 - `test-design-analyst`: Produce this matrix when defining coverage obligations. Flag ❌ cells as gaps.
-- `qa-gatekeeper`: Verify the matrix exists and no unjustified ❌ cells remain.
+- `qa-gatekeeper`: Verify the matrix exists and no unjustified ❌ cells remain. Read
+  `.qfai/evidence/coverage-depth-<spec-id>.md`; a matrix that exists only in an
+  ATDD per-item evidence file is a missing matrix.
 - `completion-reviewer`: Confirm the matrix was reviewed and any ⚠️ cells have rationale.
+- `npx qfai validate --profile atdd` reports the three file-level facts the readings
+  above assume: `QFAI-ATDD-131` when a spec with ATDD-owned tests has no matrix,
+  `QFAI-ATDD-132` when the matrix is excluded by a `.gitignore` — any of them,
+  from the git worktree root down — without already being tracked, and
+  `QFAI-ATDD-133` when the stage evidence has no `## Coverage Depth Matrix`
+  section at all, inlines the table, points at no matrix file, or points at one
+  without the counted `✅ N / ⚠️ N / ❌ N` totals beside it. None of them reads
+  the cells — that judgement stays with the reviewer.

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

@@ -122,8 +122,8 @@ Follow `.qfai/assistant/constitution/shared-skill-operating-baseline.md#delta-re
 
 - Only update `qfai.config.yaml`, `.qfai/assistant/manifest/*` + `.qfai/assistant/catalog/*`, `.qfai/assistant/constitution/quality.md` (gate capabilities only — never the surrounding rules), and `.qfai/evidence/configure-<run-id>.md` unless explicitly asked.
 - You MUST produce the required evidence file: `.qfai/evidence/configure-<run-id>.md`.
-  - `.qfai/evidence/` is intentionally NOT tracked by Git. The mechanism is the QFAI-managed block `npx qfai init` writes into the **project root** `.gitignore` (marker `# ── QFAI managed (generated by qfai init) ──`), which carries `.qfai/evidence/*`. A project generated by `npx qfai init` has no per-directory `.qfai/evidence/.gitignore`: nothing under the init asset set ships one, so an operator who needs to change what is tracked edits the root file, not a directory-local one. (qfai's own repository does carry that file, as a working-tree file outside the init assets — which is why the claim above used to read the other way.)
-  - Do NOT commit evidence files; summarize key outcomes in the PR description instead.
+  - The run-scoped `.qfai/evidence/configure-<run-id>.md` remains local and ignored. The mechanism is the QFAI-managed block `npx qfai init` writes into the **project root** `.gitignore` (marker `# ── QFAI managed (generated by qfai init) ──`), which carries `.qfai/evidence/*`. A project generated by `npx qfai init` has no per-directory `.qfai/evidence/.gitignore`: nothing under the init asset set ships one, so an operator who needs to change what is tracked edits the root file, not a directory-local one. (qfai's own repository does carry that file, as a working-tree file outside the init assets — which is why the claim above used to read the other way.)
+  - Durable per-item `implement-*.md` and `atdd-*.md` governance records are committed through the managed negations. Do not commit the configure run file; summarize its key outcomes in the PR description instead.
 - You MUST run the mandatory checks listed below and record outcomes.
 - You MUST stop and escalate if tooling choices or runnable path remain ambiguous.
 - Completion must be approved by a reviewer who did not modify the config.
@@ -223,7 +223,7 @@ Evidence must include:
 
 ## Non-Negotiable Principles (QFAI Articles)
 
-These principles are inspired by "constitution / articles" patterns used by other agent frameworks, but tailored to QFAI.
+These principles are inspired by "constitution / articles" patterns used by other agent frameworks, but adapted to QFAI.
 
 1. **SDD First (Specification is the source of truth)**  
    If there is a conflict between code and spec, treat the spec as authoritative and either (a) fix code or (b) raise an explicit Open Question to change the spec.
@@ -476,4 +476,5 @@ A skill MAY narrow the auto-decide bucket (drop entries) but MUST NOT widen it.
 project_memory:
 
 - qfai-configure is the user-facing entrypoint for editing `qfai.config.yaml` and the `.qfai/assistant/manifest/` declarative manifests; edits to those files MUST go through this skill so the agent-catalog / agent-routing / review-profiles SSOTs stay consistent.
+- Exception: `agent-catalog.yml#agents[].developer_instructions` is a derived copy of `.qfai/assistant/agents/<id>.md`. Edit the markdown file — the source — then bring the block back into agreement by copying that file from its `## Mission` heading onward, verbatim; never author new content in the block. `QFAI-AGENT-014` warns when the two diverge and when the block is missing.
 - Run after every major workflow change to refresh the consuming project to the current QFAI baseline. Do NOT edit `qfai.config.yaml` directly when the skill is available.

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

@@ -42,9 +42,11 @@ Produce a unified 15-file discussion pack plus exploration-first UI sidecars so
 
 ## UI-bearing Canonical Sidecar Family
 
-UI-bearing packs must produce, as primary truth: `uiux/40_screen_contracts.md`, `uiux/50_review_input_bundle.md`. They MUST also emit a draft brand SSOT at the **consuming-project root**:
+Every UI-bearing pack must produce, as primary truth: `uiux/00_index.md`, `uiux/40_screen_contracts.md`, `uiux/50_review_input_bundle.md`. Only a pack on a **visual-prototyping surface** (`web`, `mobile`, `desktop` or `mixed`, as `primary_surface` or in `secondary_surfaces`) MUST additionally emit a draft brand SSOT at the **consuming-project root**; a cli-only pack MUST NOT author it:
 
-- `<consuming-project-root>/DESIGN.md` — brand SSOT consumed by `/qfai-sdd` (freezes its sha256 in `.qfai/contracts/design/DESIGN.md.lock.yaml`) and by `/qfai-prototyping` (iterates against locked tokens). Brand intent (product intent, brand signals, anti-goals, reference pool framed as deviate-from inputs) lives in front-matter + `# Brand Philosophy` body — no separate per-aspect sidecar.
+- `<consuming-project-root>/DESIGN.md` — **visual-prototyping surfaces only.** Brand SSOT consumed by `/qfai-sdd` (freezes its sha256 in `.qfai/contracts/design/DESIGN.md.lock.yaml`) and by `/qfai-prototyping` (iterates against locked tokens). Brand intent (product intent, brand signals, anti-goals, reference pool framed as deviate-from inputs) lives in front-matter + `# Brand Philosophy` body — no separate per-aspect sidecar.
+
+Root `DESIGN.md` is required only on the visual-prototyping surfaces (`web`, `mobile`, `desktop`, `mixed`), and the test is the whole classified surface set — `primary_surface` **and** every `secondary_surfaces` entry. Only a **cli-only** pack (`primary_surface: cli`, no visual secondary surface) skips it: it stays `ui_bearing: true` and keeps all three screen-level sidecars, but does NOT author root `DESIGN.md`, because `/qfai-prototyping` rejects `cli` and no downstream reader consumes its `visual.*` tokens. `/qfai-sdd` Phase 0 skips the freeze for the same packs. See `references/ui-bearing-playbook.md#visual-prototyping-surfaces-vs-cli`.
 
 ## Required Process
 
@@ -56,15 +58,15 @@ UI-bearing packs must produce, as primary truth: `uiux/40_screen_contracts.md`,
 6. Run Example Mapping and capture `Example Seeds`.
 7. Update `11_OQ-Register.md`, resolve OQs until open count is zero, and move deferred items to `13_Deferred.md`.
 8. Generate the exploration-first sidecar family for UI-bearing targets.
-9. **Emit root `DESIGN.md` draft** for UI-bearing targets per `references/design-dna-intake.md`. Required when UI-bearing; skip otherwise.
-10. Generate `prototyping.yaml` only when the latest discussion pack is UI-bearing and an explicit prototyping recommendation is useful.
+9. **Emit root `DESIGN.md` draft** per `references/design-dna-intake.md`. Required when any classified surface — primary or secondary — is `web`, `mobile`, `desktop` or `mixed`; skip for cli-only and non-ui targets.
+10. Generate `prototyping.yaml` only when the latest discussion pack targets a prototyping execution surface (`web`, `mobile`, `desktop`, `mixed`) and an explicit prototyping recommendation is useful. A cli-only pack emits none — `/qfai-prototyping` rejects `cli`.
 11. Request review and record the Reviewer result.
 
 For UI-bearing targets, follow `references/design-dna-intake.md` while authoring the UI/UX sidecars. Keep this `SKILL.md` compact; put detailed interview prompts and examples in the reference file.
 
 ## UI-bearing Authoring Requirements
 
-- Root `DESIGN.md` front-matter must define `brand` (name, archetype, voice), `audience` (emotion, do_not_look_like), and the full `visual.*` token tree (colors, typography, spacing, radius, shadow).
+- Root `DESIGN.md` front-matter must define `brand` (name, archetype, voice), `audience` (emotion, do_not_look_like), and the full `visual.*` token tree (colors, typography, spacing, radius, shadow). Visual-prototyping surfaces only — a cli-only pack omits root `DESIGN.md` entirely.
 - `# Brand Philosophy` body documents do/don't, brand signals, and exploration references framed as **deviate-from** inputs (not imitate-this) for the downstream `/qfai-prototyping` reviewer.
 - `40_screen_contracts.md` defines each screen contract per the template schema; `50_review_input_bundle.md` documents review inputs for downstream skills.
 - Evaluation axes are global constants (4-step ordinal: weak / acceptable / strong / exceptional) and are not authored as discussion sidecars.
@@ -83,7 +85,7 @@ Before declaring completion, you MUST:
 - ensure `Disposition: open` count is zero in `11_OQ-Register.md`;
 - ensure every deferred item has full metadata in `13_Deferred.md`;
 - ensure `02_Inception-Deck.md` and `03_Story-Workshop.md` include Mermaid diagrams;
-- ensure the UI-bearing sidecar family is complete and the root `DESIGN.md` draft exists at the consuming-project root and parses as valid front-matter;
+- ensure the UI-bearing sidecar family is complete, and — when any classified surface (primary or secondary) is `web`, `mobile`, `desktop` or `mixed` — that the root `DESIGN.md` draft exists at the consuming-project root and parses as valid front-matter;
 - run `npx qfai validate --profile discussion --fail-on error` and fix discussion-owned findings;
 - avoid selecting a single visual winner in discussion artifacts.
 
@@ -117,7 +119,7 @@ Follow `.qfai/assistant/constitution/shared-skill-delegation-baseline.md`.
 
 ## Work Orders Summary
 
-Use the shared schema (per-row `Status (PASS/REVISE/PENDING)` column, reviewer response `Result: PASS | REVISE`).
+Use the shared schema (per-row `Status (PASS/REVISE/PENDING)` column, reviewer response `Reviewer role:` + `Reviewed artifact:` + `Result: PASS | REVISE`). A response missing the role or artifact line is not a verdict; re-request it.
 
 ## Completion Message & Next Actions (MUST)
 
@@ -149,6 +151,6 @@ A skill MAY narrow the auto-decide bucket (drop entries) but MUST NOT widen it.
 
 project_memory:
 
-- 15-file mandatory output set is fixed; the UI-bearing sidecar family (40_screen_contracts.md + 50_review_input_bundle.md + root DESIGN.md) is required only when the target is UI-bearing.
+- 15-file mandatory output set is fixed; the UI-bearing sidecar family (00_index.md + 40_screen_contracts.md + 50_review_input_bundle.md) is required whenever the target is UI-bearing, cli included, and root DESIGN.md only when a visual-prototyping surface (web/mobile/desktop/mixed) appears as primary or secondary — never for a cli-only pack.
 - Discussion is planner-first: never pick a single visual winner; carry exploration references as deviate-from inputs, not imitate-this.
 - Completion requires Disposition: open count = 0 in 11_OQ-Register.md; deferred items must move to 13_Deferred.md with full metadata.

package/assets/init/.qfai/assistant/skills/qfai-discussion/references/discussion-completion-matrix.md

@@ -7,9 +7,11 @@ Use this file for the full completion logic behind `/qfai-discussion`.
 Completion is blocked until all are true:
 
 1. Root `DESIGN.md` exists at the consuming-project root and parses as valid front-matter
-   (`brand`, `audience`, and the full `visual.*` token tree).
+   (`brand`, `audience`, and the full `visual.*` token tree). Required whenever any
+   classified surface — `primary_surface` **or** an entry in `secondary_surfaces` — is
+   `web`, `mobile`, `desktop` or `mixed`. See `## CLI Packs` below.
 2. `# Brand Philosophy` body documents do/don't, brand signals, and exploration references
-   framed as **deviate-from** inputs.
+   framed as **deviate-from** inputs. Visual-prototyping surfaces only.
 3. The canonical `uiux/` family is complete: `00_index.md`, `40_screen_contracts.md`,
    `50_review_input_bundle.md`.
 4. Every screen contract in `40_screen_contracts.md` carries the full template schema.
@@ -23,6 +25,25 @@ Evaluation axes are global constants (4-step ordinal: weak / acceptable / strong
 exceptional) and are NOT authored as discussion sidecars, so no scoring, override, strategy,
 taste-interview, option-comparison or selected-anchor sidecar is required or permitted.
 
+## CLI Packs
+
+A **cli-only** pack — `primary_surface: cli` with no `web`/`mobile`/`desktop`/`mixed`
+entry in `secondary_surfaces` — is UI-bearing but is not a visual-prototyping surface,
+so conditions 1 and 2 above do not apply to it:
+
+- No root `DESIGN.md` required, and no `visual.*` token tree to author. `/qfai-prototyping`
+  rejects `cli`, so nothing downstream ever reads the token values. `/qfai-sdd` Phase 0
+  skips the DESIGN.md freeze for a cli-only project, and
+  `validators/designContractReadiness.ts` skips `QFAI-DCON-030`/`-031` for it.
+- Conditions 3-7 apply unchanged: all three canonical `uiux/` sidecars, the full
+  screen-contract schema, unranked exploration directions, no forbidden legacy sidecar,
+  and zero open OQs.
+- `route:` on a `cli` screen contract names the command invocation, not a web path (see
+  `ui-bearing-playbook.md#visual-prototyping-surfaces-vs-cli`).
+- No `prototyping.yaml`: `cli` is not a valid prototyping execution surface.
+- `primary_surface: cli` with a visual `secondary_surfaces` entry is NOT a cli-only pack —
+  conditions 1 and 2 stay blocking for it.
+
 ## Non-UI Packs
 
 - No uiux sidecars required

package/assets/init/.qfai/assistant/skills/qfai-discussion/references/review-cycle-playbook.md

@@ -18,5 +18,20 @@ Use this file for detailed review-pack handling in `/qfai-discussion`.
 
 ## summary.json
 
-- `target.kind` must be `"discussion"`.
+- `target.kind` must be `"discussion"` and `target.path` must be the discussion pack it names — a
+  `kind` the path contradicts raises `QFAI-REVIEW-007` and is ignored when deciding which gate the
+  pack faces.
+- `producer` must be `"discussion"`, and `review_request.md` carries a matching
+  `Producer: discussion` line so the pack is placed before `summary.json` exists. That is what
+  makes this stage's gate yours: it judges `producer: "discussion"` packs only, so neither an SDD
+  worker's in-flight spec pack nor an implementation one ever fails a discussion cycle. A pack that
+  declares no owner at all is judged by both stages, since no other gate would see it.
+- A discussion pack belongs to no spec, so a `--spec` run keeps it: it is a repo-level finding, and
+  those stay in every slice.
+- `revision_form: "content-hash"` and `revision` are written here too — the state these verdicts
+  describe, as a git rev or `working-tree+<content hash>`
+  (`../../qfai-implement/references/evidence-revision.md`). A pack without them raises
+  `QFAI-REVIEW-007` in this stage's own hard gate
+  (`npx qfai validate --profile discussion --fail-on error`, `rcp_footer.md`) as well as in the
+  repo-wide `/qfai-verify --fail-on error`.
 - Keep rerun history append-only.

package/assets/init/.qfai/assistant/skills/qfai-discussion/references/ui-bearing-playbook.md

@@ -8,14 +8,14 @@ Use this file when `/qfai-discussion` needs the full UI-bearing decision logic.
 
 ## Surface Mapping
 
-| Surface | UI-bearing | Result                            |
-| ------- | ---------- | --------------------------------- |
-| web     | Yes        | Generate full uiux sidecar family |
-| mobile  | Yes        | Generate full uiux sidecar family |
-| desktop | Yes        | Generate full uiux sidecar family |
-| cli     | Yes        | Generate full uiux sidecar family |
-| mixed   | Yes        | Generate full uiux sidecar family |
-| non-ui  | No         | Skip uiux sidecars                |
+| Surface | UI-bearing | Result                                                                                                                                             |
+| ------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| web     | Yes        | Generate full uiux sidecar family                                                                                                                  |
+| mobile  | Yes        | Generate full uiux sidecar family                                                                                                                  |
+| desktop | Yes        | Generate full uiux sidecar family                                                                                                                  |
+| cli     | Yes        | Generate the canonical uiux sidecars (`00_index.md`, `40_screen_contracts.md`, `50_review_input_bundle.md`); no root `DESIGN.md` visual token tree |
+| mixed   | Yes        | Generate full uiux sidecar family                                                                                                                  |
+| non-ui  | No         | Skip uiux sidecars                                                                                                                                 |
 
 ## Detection Signals
 
@@ -26,15 +26,51 @@ Use this file when `/qfai-discussion` needs the full UI-bearing decision logic.
 
 ## Sidecar Family SSOT
 
-For UI-bearing packs the brand SSOT is root `DESIGN.md` (drafted by
-`/qfai-discussion` and frozen by `/qfai-sdd` Phase 0 into
-`.qfai/contracts/design/DESIGN.md.lock.yaml`). The remaining sidecars are
+For UI-bearing packs on a visual-prototyping surface the brand SSOT is root
+`DESIGN.md` (drafted by `/qfai-discussion` and frozen by `/qfai-sdd` Phase 0
+into `.qfai/contracts/design/DESIGN.md.lock.yaml`). The remaining sidecars are
 the screen-level UX inputs:
 
 - `uiux/00_index.md`
 - `uiux/40_screen_contracts.md`
 - `uiux/50_review_input_bundle.md`
 
+### Visual-prototyping Surfaces vs `cli`
+
+Visual-prototyping surfaces are `web`, `mobile`, `desktop` and `mixed` — the
+surfaces `/qfai-prototyping` actually executes. Root `DESIGN.md` and its
+`visual.*` token tree are required **only** when the pack targets one of
+them: the sole consumer of the token values is the prototyping loop's
+DESIGN.md drift scanner, and that loop rejects `cli`.
+
+**Judge the whole classified surface set, not `primary_surface` alone.**
+`secondary_surfaces` accepts every UI-bearing surface, so
+`primary_surface: cli` with `secondary_surfaces: [web]` still ships a visual
+surface and still needs the token SSOT. The carve-out applies only to a
+**cli-only** pack: `primary_surface: cli` with no visual surface anywhere in
+`secondary_surfaces`.
+
+A cli-only pack stays `ui_bearing: true` and keeps all three screen-level UX
+inputs above — those have downstream readers. It must NOT be blocked on
+inventing brand colors, font stacks, a type scale, spacing tokens, radii or
+shadows:
+
+- Do not author root `DESIGN.md` for a cli-only pack. `/qfai-sdd` Phase 0
+  skips the DESIGN.md freeze for it, and nothing on the `cli` path reads a
+  token value.
+- Screen contracts stay mandatory, including their `route:` field, which on
+  `cli` names the command invocation (e.g. `route: myapp deploy --dry-run`)
+  instead of a web path. `templates/uiux/40_screen_contracts.md` carries the
+  per-surface `route:` meanings.
+- No `prototyping.yaml`: `cli` is not a valid prototyping execution surface,
+  so a recommendation naming it cannot be executed downstream.
+- `templates/uiux/00_index.md` carries the same carve-out: the three sidecars
+  are the whole family for a cli-only pack, with no root `DESIGN.md` beside them.
+- Downstream, `/qfai-implement`'s Visual Review Guard drops the four
+  design-contract inputs (root `DESIGN.md`, its lock, `design-system.yaml`,
+  `prototype-handoff.yaml`) and both prototype-evidence inputs for a cli-only
+  target, leaving `.qfai/contracts/ui/*.yaml` as its UI contract input.
+
 ### Trend Scan SSOT
 
 Trend Scan is **not** a sidecar file. Trend Scan lives at

package/assets/init/.qfai/assistant/skills/qfai-discussion/references/ui_ux/trend_scan_playbook.md

@@ -44,7 +44,7 @@ Always translate a reference into:
 - whether it fits the product's users and task frequency;
 - whether it improves or harms clarity;
 - whether it changes the brand direction recorded in root `DESIGN.md`;
-- whether it affects the selected anchor or contracts;
+- whether it affects the screen contracts in `uiux/40_screen_contracts.md`;
 - whether it should be adopted, adapted, or rejected.
 
 ## Rejection Rules

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

@@ -105,10 +105,12 @@ packs it resolves through:
 - review handoff: `uiux/50_review_input_bundle.md`
 
 Those three are the entire canonical sidecar family. Evaluation axes are global constants
-(4-step ordinal: weak / acceptable / strong / exceptional, in
-`core/prototyping/evaluatorReview.ts#ORDINAL_AXES`) and are not authored as discussion
-sidecars. Discussion is planner-first: it carries exploration directions unranked and does
-not select a single visual winner, so there is no strategy, taste-interview, scoring,
+(4-step ordinal: weak / acceptable / strong / exceptional) fixed by the review validation the
+QFAI CLI applies — not by any file in this tree. The shipped
+`.qfai/assistant/skills/qfai-prototyping/references/reviewer-prompt.md` restates that axis set
+for the reviewer prompt; editing it does not change the set the CLI accepts. Axes are not
+authored as discussion sidecars. Discussion is planner-first: it carries exploration directions
+unranked and does not select a single visual winner, so there is no strategy, taste-interview, scoring,
 override, option-comparison or selected-anchor sidecar. Do NOT create
 `10_implementation_strategy.md`, `11_design_taste_interview.md`, the `20-24`
 design-evaluation family, `30_option_comparison.md`, or `31_selected_anchor_screen.md` —

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/01_Context.md

@@ -16,8 +16,8 @@ Notes:
 
 - `primary_surface` is a classification field. Valid values: `web|mobile|desktop|cli|mixed|non-ui`.
 - `non-ui` is only valid when `ui_bearing: false`. It is a classification value, not a prototyping surface.
-- `cli` is a UI-bearing surface. When classified as `cli`, set `ui_bearing: true`.
-- Prototyping surfaces (used in `prototyping.yaml`) are a subset: `web|mobile|desktop|cli|mixed`.
+- `cli` is a UI-bearing surface. When classified as `cli`, set `ui_bearing: true`. `cli` is not a visual-prototyping surface, so a **cli-only** pack — `primary_surface: cli` with no `web`/`mobile`/`desktop`/`mixed` entry in `secondary_surfaces` — does not author root `DESIGN.md` (see `references/ui-bearing-playbook.md#visual-prototyping-surfaces-vs-cli`). A visual `secondary_surfaces` entry still requires it.
+- Prototyping execution surfaces (used in `prototyping.yaml`) are a narrower subset: `web|mobile|desktop|mixed`. `cli` and `non-ui` are classification values only — `/qfai-prototyping` rejects them, so a cli-only pack emits no `prototyping.yaml`.
 
 ## Metadata
 

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/03_Story-Workshop.md

@@ -81,7 +81,7 @@ Screen-level contract details are finalized in `uiux/40_screen_contracts.md`. Pr
 ## Appendix: Screen Mock — Optional Fallback (HTML+CSS)
 
 <!-- Optional fallback only — do not use as the primary UI definition artifact.
-     Include only when it materially clarifies the selected anchor.
+     Include only when it materially clarifies a behavior obligation that prose cannot.
      Behavior Obligations and sidecar artifacts (uiux/) are the primary UI definitions.
      The required state SSOT is uiux/40_screen_contracts.md (`default/loading/empty/error`).
      Links MUST be anchor-form (`<a href="#name">`) — never same-origin absolute