qfai 1.10.0 → 1.10.2

package/README.md

@@ -18,19 +18,34 @@ The agent reads the repository, produces the required artifacts, and iterates un
 ## Release status
 
 - Release posture: runtime truthfulness is enforced.
-- Prototyping is UI-only and runs a multi-spec evolution loop driven by
-  `qfai prototyping iterate --cycle <n>`. The skill resolves every
-  UI-bearing spec in one invocation, freezes that set at cycle 0, and
-  iterates `cycle 0..9` (max 10 cycles) with deterministic stop conditions
-  (exit codes 0 continue / 64 convergence / 65 max-iterations /
-  66 license-verify failure / 2 input or lock drift).
+- Prototyping is UI-only and runs a primary-spec evolution loop driven by
+  `qfai prototyping iterate --cycle <n>`. Each run resolves exactly one
+  primary UI-bearing spec (`prototyping.primarySpecId` in `qfai.config.yaml`,
+  a `surface_type: ui-bearing` marker, or `--primary-spec-id`), freezes it at
+  cycle 0, and iterates `cycle 0..9` (max 10 cycles) with deterministic stop
+  conditions (exit codes 0 continue / 64 convergence / 65 max-iterations /
+  66 license-verify failure / 2 input or lock drift). The full set of
+  UI-bearing specs is frozen at cycle 0 as `frozenSurfaceUnion` and is read
+  only to detect surface drift on later cycles: secondary specs are **not**
+  evaluated by that run. Only one primary spec can therefore be evolved per
+  project: re-running cycle 0 for a second spec is refused without `--force`,
+  and with `--force` it re-seeds `prototyping.json` (`runId`, `specsCovered`,
+  `frozenSpecsCovered`) around the new single spec, so the earlier spec's
+  iterations do not survive as a valid loop. Iterating a second UI-bearing
+  spec has to wait for the per-spec iteration layout.
 - Runtime observation is observed-only (no synthetic 200 / API / DB prototyping coverage).
 - Per-iter evidence is a single `<screen>.review.json` per declared spec ×
   screen pair (4-axis ordinal verdicts, 6 `*Feel` short-prose impressions
   bounded to 200 words each, `layoutAntiPatternsDetected[]`,
-  `designMdViolations[]`, and `pivotDirective`). Reviewer-emitted
-  `<screen>.review.json` is the only per-cycle artifact — no `screenshot.png`,
-  `index.html`, or `interaction.json`.
+  `designMdViolations[]`, and `pivotDirective`). It is the only
+  reviewer-authored file, not the only per-cycle artifact: the CLI itself
+  always writes `iterate-plan.json` into the same `iter-NN/` directory, and
+  from cycle 1 onward — once the previous cycle is recorded in
+  `prototyping.json#iterations[]` — an advisory `iterate-context.json` holding
+  the prior scores and open blockers. The opt-in `--capture` and
+  `--cycle 0 --emit-skeletons` flags additionally write `<screen>.png` /
+  `<screen>.html` there. Archive the whole `iter-NN/` directory; no
+  `interaction.json` is written on any path.
 - Calibration SSOT is the calibration pack referenced by `calibrationRef.packPath`.
 
 ## Installation
@@ -77,6 +92,17 @@ npx qfai report
 - `npx qfai init`
   - Creates the QFAI workspace under `.qfai/` (requirements/specs/contracts/report) and installs the AI assistant kit
     (`assistant/` with the 4-layer tree — `constitution/`, `manifest/`, `catalog/`, `process/` — plus `agents/` and `skills/`), plus `qfai.config.yaml`.
+  - Options:
+
+    | Flag                       | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+    | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+    | `--dir <path>`             | Output directory (default: the current directory).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+    | `--force`                  | Re-generate `.qfai/assistant/{skills,agents}/**` and the published skill/agent wrappers under `.agents/`, `.claude/`, `.codex/` and `.github/`, and prune the legacy wrappers they replace. It also rewrites two kinds of plain (non-wrapper) generated files without asking: the integration READMEs `.agents/README.md`, `.codex/README.md`, `.claude/agents/README.md`, `.github/agents/README.md`, and `.github/copilot-instructions.md` — local edits to those five files are overwritten, so back them up first. `.github/instructions/*.instructions.md` is create-only even under `--force`. The template trees `--force` does not own — `assistant/manifest/**`, `specs/`, `contracts/`, `steering/` and the rest of `.qfai/` — stay create-only. The flag does not narrow what plain `init` always does: the managed `.gitignore` block, the legacy `.qfai/evidence/.gitignore` negations and `git config core.symlinks` are re-applied (and repaired when stale) on every non-dry-run, with or without `--force`. |
+    | `--dry-run`                | Report what would change and write nothing. Use it to rehearse `--upgrade-assistant-tree`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+    | `--upgrade-assistant-tree` | Migrate a pre-recut project to the 4-layer tree. Only the two pre-recut surfaces `.qfai/assistant/instructions/` and `.qfai/assistant/steering/` are scanned; `assistant/manifest/` is already the canonical layer, so it is kept in place and never re-copied. This is what the `D-DEPRECATED-PATH` finding is asking for. Files are copied, never deleted: the legacy paths stay until you remove them, and an existing file at a scanned surface's migration target is kept (reported as `W-USER-EDIT-PRESERVED`) — that warning only ever covers those scanned targets. A project left with nothing but `manifest/` has nothing to migrate and is reported as "no pre-recut surfaces ... found".                                                                                                                                                                                                                                                                                                                         |
+    | `--yes`                    | Reserved for a future interactive mode; no behavioural difference today.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+    | `--help`, `-h`             | Print the CLI usage banner and exit without writing anything. Accepted by every command, `init` included, and handled before the command runs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+
 - `npx qfai validate`
   - Validates specs/contracts/scenarios/traceability and review artifacts
     (`.qfai/review/review-*/summary.json` + minimum schema), writes `.qfai/report/validate.json`,
@@ -96,7 +122,7 @@ npx qfai report
     Use `npx qfai prototyping preflight --target-url <url>` for a focused
     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 multi-spec
+    Use `npx qfai prototyping iterate --cycle <n> --target-url <url>` to drive each cycle of the primary-spec
     evolution loop. Exit codes: 0 (continue), 64 (convergence), 65 (max-iterations), 66 (license-verify failure), 2 (input or lock drift).
     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`).
@@ -121,13 +147,28 @@ npx qfai report
 
 ## ATDD annotation hard gate
 
-`qfai validate` enforces spec-to-test traceability with directory-based rules.
+`qfai validate` enforces spec-to-test traceability. `US` and `CON-API` obligations are routed by ID type;
+a `TC` obligation is routed by the `Level` its spec declares for it.
 
 - `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.
+- Annotate a covered test case with a concrete ID such as `QFAI:SPEC-0001:TC-0001`, in the directory its declared `Level` names:
+
+  | `Level`                       | Annotated in           |
+  | ----------------------------- | ---------------------- |
+  | `L1`/`Unit`, `L2`/`Component` | no ATDD annotation     |
+  | `L3`/`Integration`            | `tests/integration/**` |
+  | `L4`/`API`                    | `tests/api/**`         |
+  | `L5`/`E2E`                    | `tests/e2e/**`         |
+  | none declared, or unreadable  | `tests/integration/**` |
+
+- Unit and Component test cases carry **no** ATDD annotation obligation. They are gated by the
+  per-spec `test-list.md` ledger instead, so do not copy them into `tests/integration/**` to satisfy this gate.
+- A `TC` annotation outside the directory its declared `Level` names is rejected. The rule is `Level`-relative,
+  not a blanket ban: a `TC` in `tests/api/**` is accepted only for a test case that declares `L4`/`API`, and in
+  `tests/e2e/**` only for `L5`/`E2E`.
 - `AC` annotations are not required in code; AC coverage is treated as indirect through full `TC` coverage.
+- These directories follow `paths.testsDir` from `qfai.config.yaml`; `tests/` above is the default.
 
 ## Operating model (skills-driven workflow)
 
@@ -145,7 +186,7 @@ The agent reads QFAI assets under `.qfai/assistant/` and produces or updates SDD
 QFAI includes a small set of custom skills (stored under `.qfai/assistant/skills/`) designed to keep the workflow opinionated and repeatable.
 
 - **qfai-configure**: Analyze the repository (language, frameworks, test layout, directory structure)
-  and tailor `qfai.config.yaml` accordingly (especially `testFileGlobs`).
+  and adjust `qfai.config.yaml` accordingly (especially `testFileGlobs`).
   Run this once right after `npx qfai init`, and re-run it when the repository structure changes.
 - **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>/`.
@@ -162,9 +203,10 @@ QFAI includes a small set of custom skills (stored under `.qfai/assistant/skills
   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**: Multi-spec parallel design evolution loop. Resolves
-  every UI-bearing spec in one invocation, freezes that set at cycle 0,
-  and iterates each `spec × screen` pair through up to 10 cycles
+- **qfai-prototyping**: Primary-spec design evolution loop. Resolves exactly
+  one primary UI-bearing spec per invocation and freezes it at cycle 0 (the
+  full UI-bearing set is recorded as `frozenSurfaceUnion` for drift detection
+  only), then iterates each `spec × screen` pair through up to 10 cycles
   (`cycle 0..9`) of generate → capture → review with a 4-axis ordinal
   rubric, 6 `*Feel` short-prose impressions (200-word bounded), explicit
   layout anti-pattern detection (`lap-001..lap-008`), DESIGN.md token
@@ -277,7 +319,14 @@ validation:
 
 Notes.
 
-- `validate.json`, `report.json`, `doctor.json`, and `run-*` JSON logs are internal exports and are not a stable external contract; prefer `report.md` for integrations that must survive tool upgrades.
+- `validate.json` is a **public** surface: its keys are documented in
+  `.qfai/assistant/skills/qfai-verify/references/validate-json-schema.md` and a change to
+  them takes the `@api` path (`.qfai/assistant/constitution/change-classification.md`). The
+  skills instruct agents to read it, so it is a contract whether or not this file says so —
+  it used to say the opposite, which left a consumer following the skills depending on
+  something the README disclaimed. `message` text and the order of `issues` are still not
+  stable; match on `issues[].code`
+- `report.json`, `doctor.json`, and `run-*` JSON logs are internal exports and are not a stable external contract; prefer `report.md` for integrations that must survive tool upgrades.
 - Scenario files are expected to use the Gherkin extension `*.feature` (not `*.md`).
 - `prototyping.calibration.packPath` points to the calibration pack SSOT; runtime and validator both resolve thresholds and iteration parameters from that pack.
 - `prototyping.calibration.thresholds`, `maxIterations`, `plateauDelta`, and `plateauLookback` are unsupported public config fields.
@@ -349,8 +398,10 @@ Release gate behavior:
 
 QFAI generates integration wrappers under `.agents/**`, `.claude/**`,
 `.github/**`, and `.codex/**`.
-It does not generate GitHub Actions workflows.
-Configure CI in your own platform and run:
+Into `.github/workflows/` it writes exactly two files — `qfai-validate.yml`
+and `qfai-tests.yml` — and touches nothing else there; both open with a
+`# Generated by \`qfai init\`` line. Configure the rest of CI in your own
+platform and run:
 
 ```bash
 pnpm ci:gate
@@ -463,6 +514,7 @@ Typical customizations.
 │   │       ├── spec_required_files.json
 │   │       ├── structure.md
 │   │       ├── tech.md
+│   │       ├── test-layers-ci-lanes.md
 │   │       ├── test-layers.md
 │   │       ├── ui-definition-protocol.md
 │   │       └── worklog-entry.schema.md
@@ -477,7 +529,7 @@ README files. Those files are created later by QFAI skills when real work exists
 ### AI work-log surface (`.qfai/steering/`)
 
 `qfai init` also creates `.qfai/steering/`, the per-project work-log surface for
-AI coding agents, with a `README.md` and `_templates/entry.md`. Each entry is a
+AI coding agents, with a `README.md` and an `entry.md` template under `_templates/`. Each entry is a
 markdown file with YAML frontmatter, and `npx qfai validate` polices the surface in
 the `sdd` and full profiles via `W-WORKLOG-SCHEMA`, `W-WORKLOG-BROKEN-LINK`,
 `W-WORKLOG-STALE`, `W-PENDING-PROMOTION` and `R-HANDOFF-INCOMPLETE`.
@@ -494,7 +546,7 @@ Integration wrappers are also generated for immediate use:
 - Agents/Codex VS Code: `.agents/skills/**`
 - Claude Code: `.claude/skills/**`, `.claude/agents/**`
 - GitHub Copilot: `.github/skills/**`, `.github/agents/**`
-- Codex: `.codex/skills/**`
+- Codex: `.codex/skills/**`, `.codex/agents/**`
 
 ## Agent integrations
 
@@ -502,12 +554,30 @@ Integration wrappers are also generated for immediate use:
 and generates thin wrapper assets for Agents/Codex VS Code / Copilot / Claude Code / Codex.
 Canonical agent markdown under `.qfai/assistant/agents/**` uses a shared YAML frontmatter
 subset (`name`, `description`, `tools`) compatible with Claude Code and GitHub Copilot,
-while Codex consumes mirrored `.codex/agents/*.toml` profiles.
-If wrapper assets drift from canonical skills, rerun `npx qfai init --force` to resync.
+while Codex consumes `.codex/agents/*.toml` profiles generated from that same markdown.
+The `.claude` / `.github` agent wrappers are symlinks and follow the canonical document
+automatically; the Codex profiles are generated files, so rerun `npx qfai init --force`
+to refresh them (and any other wrapper asset that has drifted).
+`--force` deletes as well as overwrites: it removes the command and prompt wrappers earlier releases
+installed under `.claude/commands/` and `.github/prompts/`, and the skill wrappers it installed under
+`.claude/skills/`, `.agents/skills/`, `.codex/skills/` and `.github/skills/` for skills QFAI no longer
+ships — the directory wrappers releases before the symlink recut copied there as well as the symlinks
+that replaced them. Files it did not write — a project's own slash command, prompt file or skill,
+including one published from a project-authored `.qfai/assistant/skills/` entry — are left in place,
+whatever they are named. Ownership is read from the file, not the name: a wrapper is removed only when
+it carries the delegation line to the canonical document of the same name, or is a symlink into
+`.qfai/assistant/skills/`. One consequence of that: a symlink has no content to prove who wrote it, so
+if you publish a canonical skill of your own under a name QFAI itself once shipped, `--force` removes
+that link. Your `.qfai/assistant/skills/` entry is untouched; re-create the link to publish it again.
 
 ## Contributing (for QFAI maintainers)
 
-This repository is a monorepo, and the distributable package is under `packages/qfai`; if you change documentation, keep the repository root README and the package README aligned (the CI enforces this).
+This repository is a monorepo, and the distributable package is under `packages/qfai`.
+The repository root `README.md` and `packages/qfai/README.md` are kept aligned by
+`scripts/check-readme-alignment.mjs`, which CI runs as part of `pnpm ci:lint`: every line
+outside a `readme-align:ignore-start` / `readme-align:ignore-end` HTML-comment block must be
+identical in both files. When you change documentation, apply the edit to both READMEs, or
+wrap the intentionally file-specific part in those markers.
 
 ## License
 

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

@@ -0,0 +1,27 @@
+# QFAI assistant tree
+
+This directory is the canonical source for QFAI's skills, agents, constitution,
+manifest and catalog. `npx qfai init` writes it once and never removes it, and the
+tool-specific integration directories are built from it.
+
+## Canonical entrypoint
+
+Every tool integration resolves through symlinks that point back here:
+
+- .qfai/assistant/skills/ — skill documents
+- .qfai/assistant/agents/ — agent definitions
+
+These documents are the SSOT. Edit them here, not through the symlinks under
+`.claude/`, `.agents/`, `.codex/` or `.github/`.
+
+## Integration surface
+
+`npx qfai init` creates the wrappers under those four directories. They are
+generated, so re-running `npx qfai init` restores any that a checkout flattened or
+a cleanup removed; nothing there needs to be edited by hand.
+
+`npx qfai validate` checks that the wrappers still resolve to the documents above.
+It reads this file to tell "init has run here and the surface was deleted" from
+"init has never run here" — the two look identical from the integration
+directories alone once every wrapper is gone, and only one of them is a
+problem. Leave it in place.

package/assets/init/.qfai/assistant/agents/completion-reviewer.md

@@ -24,6 +24,22 @@ tools: [Read, Glob, Grep, Bash]
 - .qfai/assistant/catalog/test-layers.md
 - .qfai/specs/spec-\*/09_delta.md
 - Validation evidence and gate results
+- `.qfai/specs/<spec-id>/tdd/test-list.md` — the ledger, for the row under review
+- The per-item evidence file that row's `Layer` owns: `.qfai/evidence/implement-<spec-id>.md`,
+  or `.qfai/evidence/atdd-<spec-id>.md` for an `E2E` / `API` / `Integration` row
+
+**Validate evidence is a completion-gate input, not an item-cycle one.** When
+this role is routed inside an item cycle — `/qfai-atdd` stage gate P1c hands a
+single row to `/qfai-implement` and that run's reviewers gate its checkpoint —
+`.qfai/report/validate.log`, the coverage reports and runtime evidence are P5/P6
+artifacts of the calling stage and do not exist yet. Requiring them there
+stopped the first branch-1 row at `refactor`, which Phase Red does not
+re-select, so the calling stage never reached P2. Judge the row's own
+phase-authored evidence; the completion gate is where the rest is owed. **The
+two inputs above are what makes that possible** — without the ledger and the
+evidence home its `Layer` selects, this role cannot identify the artifact it is
+being asked to judge, and falls into its own Stop condition ("Required evidence
+... missing") on a correct branch-1 or branch-2 row.
 
 ## Deliverables
 
@@ -51,7 +67,7 @@ tools: [Read, Glob, Grep, Bash]
 
 - [ ] Review verdict is explicit
 - [ ] Findings cite concrete artifacts or evidence
-- [ ] Every finding declares `Severity:` and `Traces to:`; no blocking finding has `Traces to: none`
+- [ ] Every finding declares `Severity:` and `Traces to:`; no blocking finding traces to `none` or `record:*`
 - [ ] Required gates and residual risks are recorded
 
 ## When to use

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

@@ -33,6 +33,14 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 - .qfai/specs/spec-\*/01_Spec.md
 - `.qfai/specs/spec-*/tdd/test-list.md` — the execution ledger this role selects
   the next item from and whose Red-Green-Refactor ordering it enforces
+- **The document the row's obligation column points at.** Item scope is "is this
+  selector a sufficient slice of the obligation", and the obligation is not
+  always a `TC-*`: an `E2E` row owes `US-Refs` and an `API` row owes
+  `CON-API-Refs`. Without these the role has nothing to compare such a row
+  against and can only guess a PASS or stall the gate.
+  - `.qfai/specs/spec-*/06_Test-Cases.md` for a `TC-Refs` row
+  - `.qfai/specs/spec-*/02_User-stories.md` for a `US-Refs` row
+  - `.qfai/contracts/api/**` for a `CON-API-Refs` row
 - .qfai/discussion/discussion-\*/04_Sources.md
 - .qfai/discussion/discussion-\*/06_REQ.md
 - .qfai/discussion/discussion-\*/11_OQ-Register.md

package/assets/init/.qfai/assistant/agents/implementation-reviewer.md

@@ -31,6 +31,17 @@ tools: [Read, Glob, Grep, Bash]
 - .github/instructions/principles.instructions.md
 - Diff of changed files
 - `.qfai/contracts/api/**` and `.qfai/contracts/db/**`
+- `.qfai/specs/<spec-id>/tdd/test-list.md` — the ledger, for the row under review
+- The per-item evidence file that row's `Layer` owns: `.qfai/evidence/implement-<spec-id>.md`,
+  or `.qfai/evidence/atdd-<spec-id>.md` for an `E2E` / `API` / `Integration` row
+
+**The last two are what the `Audited evidence hash` is computed over.** This
+role records that hash itself, over the row's phase-authored fields — and those
+live in a committed per-item evidence file so a fresh clone can reproduce the
+audit. Without the ledger and the evidence home the row's
+`Layer` selects, this role cannot identify its own audit subject: the hash goes
+missing and gate items 10-11 stop, or the orchestrator computes it instead,
+which is the one thing the contract says must not happen.
 
 ## Deliverables
 
@@ -55,7 +66,7 @@ tools: [Read, Glob, Grep, Bash]
 
 - [ ] Review verdict is explicit
 - [ ] Findings cite concrete artifacts or evidence
-- [ ] Every finding declares `Severity:` and `Traces to:`; no blocking finding has `Traces to: none`
+- [ ] Every finding declares `Severity:` and `Traces to:`; no blocking finding traces to `none` or `record:*`
 - [ ] Required gates and residual risks are recorded
 
 ## When to use

package/assets/init/.qfai/assistant/agents/orchestrator.md

@@ -32,7 +32,7 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 - Work Orders for each subagent (scope, inputs, outputs, gates)
 - Stage Gates plan + current status
 - Completion report (DoD checklist + evidence links)
-- Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
+- Evidence summary for `.qfai/evidence/` (commit only paths re-included by the managed block)
 
 ## Stop conditions
 
@@ -45,7 +45,7 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 ## Sign-off
 
 - [ ] Deliverables are complete
-- [ ] Evidence is present (gitignored)
+- [ ] Evidence is present under the managed tracking policy
 - [ ] Stage gates are PASS
 - [ ] Reviewer sign-off recorded
 

package/assets/init/.qfai/assistant/agents/product-experience-architect.md

@@ -30,7 +30,8 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 - .github/instructions/principles.instructions.md
 - Root `DESIGN.md` (brand SSOT: front-matter tokens plus `# Brand Philosophy` body)
 - Reference pool framed as deviate-from inputs, screen contracts (`uiux/40_screen_contracts.md`), optional tokens, optional fallback HTML/CSS mock, and Mermaid flows
-- Evaluator axes are fixed in `core/prototyping/evaluatorReview.ts#ORDINAL_AXES` (information architecture / navigation flow / usability / functionality) and no longer authored as sidecar files
+- Evaluator axes (information architecture / navigation flow / usability / functionality) are fixed by
+  the review validation the QFAI CLI applies (restated in `.qfai/assistant/skills/qfai-prototyping/references/reviewer-prompt.md`), not sidecar files
 - Runtime screenshots or rendered evidence when available
 
 ## Deliverables

package/assets/init/.qfai/assistant/agents/product-surface-reviewer.md

@@ -15,7 +15,7 @@ tools: [Read, Glob, Grep, Bash]
 - Audit frontend changes for correctness and user-facing risk.
 - Audit layout sanity, interaction usability, and accessibility guardrails.
 - Audit visual design, token alignment, and service-level UX coherence.
-- Reconcile sidecar artifacts (selected anchor, strategy, screen contracts), design tokens, mermaid flows, and rendered output consistency.
+- Reconcile sidecar artifacts (screen contracts), design tokens, mermaid flows, and rendered output consistency.
   HTML mock is optional fallback evidence only. Design tokens are supporting input.
 - For UI implementation, compare rendered output against `.qfai/contracts/design/prototype-handoff.yaml`, canonical prototype screenshots, HTML snapshots, and `.qfai/prototypes/winner/index.html`.
 - Reject prototype parity when implementation loses CTA hierarchy, spacing rhythm, information density,

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

@@ -21,7 +21,9 @@ tools: [Read, Glob, Grep, Bash]
 
 ## Ownership boundaries
 
-- `delivery-planner` owns **item selection and item scope** — whether a ledger row's selector is a sufficient slice of its `TC-*` obligation. Do not adjudicate item scope here; a PASS on observation
+- `delivery-planner` owns **item selection and item scope** — whether a ledger
+  row's selector is a sufficient slice of the obligation its `Layer` names
+  (`TC-Refs`, `US-Refs` or `CON-API-Refs`). Do not adjudicate item scope here; a PASS on observation
   evidence is explicitly scoped to that observation and never widens or ratifies item scope. See `.qfai/assistant/skills/qfai-implement/SKILL.md#precedence-between-delivery-planner-and-qa-gatekeeper`.
 - Refuse to evaluate RED/GREEN evidence while an unresolved `delivery-planner` scope REVISE is open on the same item.
 
@@ -32,7 +34,8 @@ the item owns, and nothing downstream re-asks: coverage is annotation presence
 and the Depth Matrix counts case categories. A test that cannot fail otherwise
 clears every gate.
 
-Require an `Oracle proof` on each item and **reject** it when:
+Require an `Oracle proof` on each item **at a GREEN or completion gate**, and
+**reject** it when:
 
 - the mutation is outside the code the item owns — breaking a shared helper
   proves the helper is used, not that this test discriminates;
@@ -41,6 +44,14 @@ Require an `Oracle proof` on each item and **reject** it when:
 - the failing output names a selector other than the row's;
 - the recorded command differs from the `GREEN command`.
 
+**At a RED observation the proof is a plan, and a plan is enough.** Branch 1's
+RED is taken before any production behaviour exists, so there is nothing to
+mutate: the item names the predicate it will break and the command it will run.
+Requiring a demonstrated mutation there made a correct observed RED unable to
+pass P1b and so unable to reach Phase Green — the phase that builds the code the
+mutation needs. Judge the plan for whether it names this row's predicate and
+selector; judge the demonstration once the behaviour exists.
+
 `equivalent-mutant` is acceptable **only** when the named contract clause is
 genuinely weaker than the obligation. It is an upstream gap: route it as an
 advisory / Change Request, do not send the implementer to strengthen an
@@ -78,12 +89,46 @@ test:
 - "the suite is green" in place of the row's own GREEN.
 
 The one legitimate absence is the _RED not observable_ path: the obligation is
-already satisfied by a sibling row, so the correct test passes first run. Then
-require `Satisfied-by`, `Falsifiability command` and `Falsifiability result`
-instead — never both forms, never neither. See
+already satisfied by something already in the tree, so the correct test passes
+first run. Then require `Satisfied-by`, `Falsifiability command` and
+`Falsifiability result` instead — never both forms, never neither.
+
+**On an `E2E` / `API` / `Integration` row, `Satisfied-by` need not be a sibling `TDD-NNNN`.** A
+production **path and symbol** is equally valid there and is the normal answer
+for a row whose surface no ledger row owns; rejecting it sends every such row to
+`exception`, the terminal state the path exists to avoid. Judge it on whether it
+answers "what would I mutate to falsify this row".
+
+**A commit id alone does not answer it — REVISE.** A commit that touched
+several routes and a helper names no single predicate, so the ownership check
+below has no boundary to apply and would accept a mutation anywhere inside it.
+The producer contract requires the symbol for this reason
+(`../skills/qfai-atdd/references/red-provenance.md#the-three-branches-must`); a
+commit recorded **alongside** the path and symbol is provenance and is fine.
+
+**And the mutation may touch it.** The Oracle Strength Check rejects a mutation
+outside the code the item owns, which on an `E2E` / `API` / `Integration` row is every
+production predicate there is — the same sentence above says no ledger row owns
+that surface. Applied literally, no branch-2 row could ever produce
+falsifiability evidence that passes. On a handed-over row, **the predicate
+`Satisfied-by` names is the owned code** for this check; anything else is still
+out of bounds.
+
+**On any other row the sibling row is still required** — production code
+no ledger row owns is the anomaly case there, not a substitute. See
 `.qfai/assistant/skills/qfai-implement/references/red-not-observable.md` and
 `.qfai/assistant/skills/qfai-implement/references/red-admissibility.md`.
 
+**A `Layer = E2E` / `Layer = API` row from `/qfai-atdd` is judged the same
+way.** Its journey is often written after the surface the same cycle built, so
+the falsifiability form is the expected evidence rather than a concession —
+accept it, with the mutated predicate being one the journey actually asserts
+on. What is **not** acceptable is the third outcome appearing by default: a row
+routed to `exception` whose `DR-*` says only that the surface came first has
+not shown that either branch was unavailable, and that is a REVISE. See
+`.qfai/assistant/skills/qfai-atdd/SKILL.md#red-provenance-for-an-atdd-owned-row-must`
+and `.qfai/assistant/skills/qfai-implement/references/execution-ledger.md#atdd-owned-rows`.
+
 Verdict scope: a PASS covers the observation for that round and nothing else. It
 does not ratify item scope and does not clear the completion gate.
 
@@ -91,7 +136,10 @@ does not ratify item scope and does not clear the completion gate.
 
 In addition to traceability-based coverage (US/TC/CON-API existence), verify the **depth** of test cases:
 
-- Confirm a Coverage Depth Matrix exists (produced by `test-design-analyst`). Missing matrix: REVISE from the ATDD review cycle onward; on an SDD review cycle record it as a finding. See the scope note.
+- Confirm a Coverage Depth Matrix exists at `.qfai/evidence/coverage-depth-<spec-id>.md` (produced by `test-design-analyst`).
+  Missing matrix: REVISE from the ATDD review cycle onward; on an SDD review cycle record it as a finding. See the scope note.
+  A matrix that exists only inside `.qfai/evidence/atdd-<spec-id>.md` is a **missing** matrix: that committed file is the
+  ledger's per-item evidence payload, not the dedicated matrix artifact whose justifications this gate reads.
 - Check that each US/TC has test cases for at minimum: normal path AND error/failure path.
 - Flag any US/TC that has only normal-path test cases as a coverage gap.
 - Reference: `.qfai/assistant/skills/qfai-atdd/references/test-case-depth-checklist.md`
@@ -105,8 +153,9 @@ In addition to traceability-based coverage (US/TC/CON-API existence), verify the
 The Coverage Depth Matrix is an **ATDD-stage artifact**: it is defined in
 `.qfai/assistant/skills/qfai-atdd/references/test-case-depth-checklist.md`, listed as an ATDD
 Mandatory Output,
-and written into `.qfai/evidence/atdd-<spec-id>.md`. `qfai-sdd` neither defines its layout nor
-ships a section for it, so:
+and written to `.qfai/evidence/coverage-depth-<spec-id>.md` — a committed governance path alongside
+`implement-<spec-id>.md` and `atdd-<spec-id>.md`. Only run-scoped evidence remains ignored.
+`qfai-sdd` neither defines the matrix layout nor ships a section for it, so:
 
 - Apply this check from the **ATDD review cycle onward**, where
   `.qfai/assistant/skills/qfai-atdd/SKILL.md` lists
@@ -124,14 +173,47 @@ ships a section for it, so:
 - .qfai/assistant/catalog/test-layers.md
 - .qfai/specs/spec-\*/09_delta.md
 - `.qfai/specs/spec-*/tdd/test-list.md` — the ledger row under review
-- `.qfai/evidence/implement-<spec-id>.md` — the per-item RED/GREEN evidence this
-  role adjudicates. Both are listed because the Stop condition below ("target
-  artifacts are missing") is not checkable against an artifact this role was
-  never told to open.
-- `.qfai/report/validate.log`
+- **The per-item RED/GREEN evidence for the row under review — in the file its
+  `Layer` owns, and only that one.** `.qfai/evidence/atdd-<spec-id>.md`, under
+  `## Ledger rows advanced`, for a `Layer = E2E` / `Layer = API` / `Layer = Integration` row;
+  `.qfai/evidence/implement-<spec-id>.md` for every other row. Both are listed
+  because the Stop condition below ("target artifacts are missing") is not
+  checkable against an artifact this role was never told to open — but
+  requiring **both** makes that condition fire on a spec that legitimately has
+  one: a Unit-only spec never ran `/qfai-atdd`, and a spec whose rows are all
+  `E2E` / `API` / `Integration` has no implement file. Either way the gate would stop before
+  reading the evidence that does exist.
+  **The three below are required at a completion gate, not at a RED/GREEN
+  observation.** `/qfai-atdd` routes this role as blocking at stage gate P1b, and
+  validate output, coverage reports and runtime evidence are first produced at its
+  P5 and P6 — so requiring them there stopped a fresh run that had a perfectly
+  good RED pair, on artifacts its own ordering says cannot exist yet. At an
+  observation gate the row's own evidence above is the whole input.
+
+- The scoped validate JSON for the spec under review — `validate.spec-<id>.json`
+  **beside the configured `output.validateJsonPath`**, not under a fixed
+  `.qfai/report/` — or the `run-*/` directory of the run that produced it, under
+  the configured `paths.outDir`. Read both from `qfai.config.yaml` the way the
+  SDD and discussion contracts do. A project that moved either output writes its
+  evidence where it said to, and looking for it at the default path reported a
+  missing artifact and stopped completion on a validate run that had succeeded
+  and left everything it owed. **Not `validate.log`**: it and the run-log pointer are shared by every
+  run, scoped or not, and nothing serializes them, so a sibling stage validating
+  at the same time overwrites what this one wrote — a failing run followed by a
+  sibling's success reads as this spec's PASS
 - `.qfai/report/specs-coverage/spec-*.md`
 - Runtime evidence and prototyping evidence artifacts
 
+**Branch 3 gets its own verdict.** The observation gate admits an observed RED
+or a falsifiability trio and calls anything else "never neither" — but a genuine
+branch-3 row _has_ neither, by the finding that put it there. Judged by the two
+forms it can only be REVISE, and skipping the gate leaves the stage's completion
+condition unmet, so the row could not close either way. Judge these on their own
+terms: a `DR-*` that records **what could not be observed and why each branch was
+unavailable**, PASS or REVISE on that. A missing `DR-*`, or one that names no
+unavailability, is still REVISE — this is a third form of evidence, not an
+exemption from having any.
+
 ## Deliverables
 
 - Gate decision (PASS / REVISE) with rationale
@@ -140,7 +222,10 @@ ships a section for it, so:
 
 ## Stop conditions
 
-- Required evidence, governing specs, or target artifacts are missing.
+- Required evidence, governing specs, or target artifacts are missing — judged
+  against what the invoking phase requires, per the note above the last three
+  inputs. At a RED/GREEN observation that is the row's own evidence; at a
+  completion gate it is all of them.
 - The request requires implementation or file editing instead of independent review.
 - The issue falls outside this review domain and must be rerouted to another specialist first.
 

package/assets/init/.qfai/assistant/agents/test-design-analyst.md

@@ -58,7 +58,10 @@ At both stages: when business rules (BR-\*) exist, verify each BR has at least o
 - Coverage plan and layer ownership
 - Test-case quality and traceability findings
 - **Coverage Depth Matrix** (per spec, using the template in the depth checklist reference).
-  Destination: `.qfai/evidence/atdd-<spec-id>.md` from the ATDD stage onward. During SDD there is
+  Destination: `.qfai/evidence/coverage-depth-<spec-id>.md` from the ATDD stage onward — its own
+  file, because it has its own committed governance lifecycle separate from the committed
+  per-item TDD evidence, and the justification behind each `❌` is the input `qa-gatekeeper`
+  reads. During SDD there is
   no evidence artifact that holds it, so report depth gaps as findings instead of producing the
   matrix format.
 - Volume estimate and risk notes

package/assets/init/.qfai/assistant/catalog/cli-ux-guidelines.md

@@ -42,6 +42,9 @@ QFAI が定義する、`npx qfai validate` の UI/UX 関連出力ガイドライ
 - 許容値: `web`, `windows`, `mobile-ios`, `mobile-android`, `cross-platform`
 - 未指定時: 自動検出（config → project files → fallback to `web`）
 - 未知の値: warning 発行。platform 値は保持しつつ、実質的に common ルールのみ適用
+- 参照する profile: `prototyping` / `verify` / `full` / `saas-package` のみ。
+  `discussion` / `sdd` / `atdd` / `tdd` は platform を読まないため、これらに
+  `--platform` を渡すと未使用である旨の warning のみを発行する（未知値チェックは走らない）
 
 ## Known Limitations