qfai 1.9.2 → 1.10.1

package/README.md

@@ -33,6 +33,28 @@ The agent reads the repository, produces the required artifacts, and iterates un
   `index.html`, or `interaction.json`.
 - Calibration SSOT is the calibration pack referenced by `calibrationRef.packPath`.
 
+## Installation
+
+qfai is published on npm as **`qfai`**. Install it as a dev dependency:
+
+```bash
+npm i -D qfai
+# or: pnpm add -D qfai / yarn add -D qfai
+```
+
+Let the package manager write the `devDependencies` entry. Do not hand-pin a version
+here: `package.json#version` in the published package is the only version source, and a
+number copied from prose goes stale on the next release.
+
+> **Do not install from the GitHub repository.** A git specifier such as
+> `"qfai": "github:aganesy/QFAI"` maps the dependency key `qfai` to the private monorepo
+> root — the manifest `name` is irrelevant, so it lands in `node_modules/qfai` regardless.
+> That root ships no `bin` and no built `dist`, so nothing would be runnable or
+> importable. Under npm or yarn a `preinstall` guard refuses the install with an
+> explanatory error rather than completing silently; under pnpm — or any package manager
+> that reports no user agent — it is not caught, so the mistake is yours to avoid. Use the
+> npm package, or run it without installing via `npx qfai@latest <command>`.
+
 ## Quick start
 
 > **Windows users:** `qfai init` creates symlinks internally.
@@ -99,13 +121,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
+  `tdd/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)
 
@@ -123,7 +160,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>/`.
@@ -220,7 +257,10 @@ Operational notes.
 - Skills should delegate work to multiple role-based sub-agents (Planner, Architect, Contract Designer, QA, Code Reviewer, etc.) to emulate a real delivery flow.
 - Change classification (Primary/Tags) is required in `09_delta.md` and recommended in PRs. See `.qfai/assistant/constitution/change-classification.md`.
 - Verification planning is recorded in `09_delta.md` (`Verification -> Plan`) and validated in CI (`VFY-*` rules).
-- Review gate policies (required/optional layers and reviewers) are defined in `.qfai/assistant/catalog/review-gate.rules.yml`.
+- Review gate policies (required/optional layers, default reviewers, optional
+  review modes) are documented in `.qfai/assistant/catalog/review-gate.rules.yml`.
+  This catalog is reference material for agents; it is not machine-enforced.
+- Review pack structure — `.qfai/review/review-<YYYYMMDDhhmmssSSS>/{review_request.md,R01_*.md,summary.json}` — is the one layout enforced by validation (`QFAI-REVIEW-*`).
 - Agent taxonomy and invocation SSOT are defined in `.qfai/assistant/manifest/agent-catalog.yml`, `.qfai/assistant/manifest/agent-routing.yml`, and `.qfai/assistant/manifest/review-profiles.yml`.
 
 ## Configuration
@@ -343,6 +383,11 @@ Recommended baseline.
 
 Waiver policy.
 
+- A waiver's `rule:` is the finding's `code`, copied verbatim from
+  `.qfai/report/validate.json` — `QFAI-ATDD-112`, `TDDLIST_UNKNOWN_LEVEL`,
+  `E_TC_ORPHAN`. Do not strip the `QFAI-` prefix; the stripped form
+  (`ATDD-112`) is kept working only for waiver files written against older
+  releases.
 - Use waivers only for `warning` / `info` findings (false positives).
 - Waivers that target `error` findings are invalid and fail validation (`QFAI-WAIVER-002`).
 - Expired waivers are reported as warnings (`QFAI-WAIVER-003`) and must be renewed or removed with evidence.
@@ -434,7 +479,8 @@ Typical customizations.
 │   │       ├── structure.md
 │   │       ├── tech.md
 │   │       ├── test-layers.md
-│   │       └── ui-definition-protocol.md
+│   │       ├── ui-definition-protocol.md
+│   │       └── worklog-entry.schema.md
 │   └── waivers.yml
 └── qfai.config.yaml
 ```
@@ -443,6 +489,21 @@ Typical customizations.
 contracts, evidence, reports, reviews, placeholder spec directories, or artifact
 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
+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`.
+
+The frontmatter contract and the **per-kind write trigger** — which `kind` an
+agent writes when — are in the seeded
+`.qfai/assistant/catalog/worklog-entry.schema.md`.
+
+Note that `.qfai/steering/` (the work-log surface) is a different directory from
+the legacy `.qfai/assistant/steering/` (the pre-recut assistant path).
+
 Integration wrappers are also generated for immediate use:
 
 - Agents/Codex VS Code: `.agents/skills/**`

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/acceptance-test-engineer.md

@@ -32,6 +32,7 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 - Acceptance test plan and implemented coverage
 - Mapping from US / TC / CON-API to test assets
 - Execution proof and evidence summary
+- TDD ledger Status + Evidence entry for each item processed, returned to the orchestrator (which owns the `test-list.md` write; do not edit that file directly)
 - Gaps and follow-up actions
 
 ## Stop conditions

package/assets/init/.qfai/assistant/agents/backend-engineer.md

@@ -35,6 +35,7 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 - Backend implementation summary
 - Changed files and affected contracts
 - Local verification notes
+- TDD ledger Status + Evidence entry for each item processed, returned to the orchestrator (which owns the `test-list.md` write; do not edit that file directly)
 - Evidence summary for `.qfai/evidence/`
 - Notes on invariants, validation, and why added abstractions/configuration are necessary now
 

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

@@ -12,7 +12,7 @@ tools: [Read, Glob, Grep, Bash]
 
 ## Domain Responsibilities
 
-- Return pass/fail only with actionable rework instructions.
+- Return only PASS or REVISE, with actionable rework instructions on REVISE.
 - Enforce validate evidence, required coverage obligations, and no self-approval.
 - Verify rejected options are not reintroduced without RE-OPEN.
 
@@ -24,23 +24,50 @@ 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
 
-- PASS or FAIL with concrete rework list
+- PASS or REVISE with concrete rework list
 - Evidence summary and gaps
 - Open risks or blocking assumptions
 
 ## Stop conditions
 
 - Required evidence, governing specs, or target artifacts are missing.
+  - "Required evidence" means the evidence this review audits — the phase-authored record produced
+    before the review was requested. A completion record that this review's own verdict will be
+    written into is not yet expected to be finalized; its missing verdict fields are not a stop
+    condition and not a blocking finding. Report an unfinalized completion record as a sequencing
+    note, not as a gap.
 - 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.
+- The finding would add a product obligation upstream never asked for. Do not raise it as blocking;
+  raise it as an advisory finding plus a Change Request proposal per
+  `.qfai/assistant/constitution/drift-protocol.md#reviewer-originated-obligations`. A defect you can
+  demonstrate from the changed artifacts (correctness, security / data integrity, or a repository
+  quality gate) is NOT in this category: it stays blocking and traces to its `defect:*` class.
 
 ## Sign-off
 
 - [ ] Review verdict is explicit
 - [ ] Findings cite concrete artifacts or evidence
+- [ ] Every finding declares `Severity:` and `Traces to:`; no blocking finding has `Traces to: none`
 - [ ] Required gates and residual risks are recorded
 
 ## When to use

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

@@ -17,6 +17,13 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 - Define parallel-safe slices and post-merge verification conditions.
 - Own schedule, priority, and risk trade-offs across roles.
 - Produce actionable work orders for workers and reviewers.
+- Own **item selection and item scope** in a TDD micro-cycle, and Red-Green-Refactor phase ordering. Raise a scope REVISE **before** RED/GREEN evidence is submitted to `qa-gatekeeper`; do not
+  re-litigate item scope after `qa-gatekeeper` has passed the observation for that round — open a new ledger row instead.
+
+## Ownership boundaries
+
+- `qa-gatekeeper` owns RED/GREEN **observation** evidence (did the test fail or pass for the expected reason). This role does not overrule that verdict, and that verdict does not widen item scope.
+  See `.qfai/assistant/skills/qfai-implement/SKILL.md#precedence-between-delivery-planner-and-qa-gatekeeper`.
 
 ## Inputs you must read
 
@@ -24,6 +31,16 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 - .qfai/assistant/{manifest,catalog}/\*\*
 - .qfai/specs/spec-\*/09_delta.md
 - .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/frontend-engineer.md

@@ -34,6 +34,7 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 - Frontend implementation summary
 - Changed files and affected flows
 - Local verification notes
+- TDD ledger Status + Evidence entry for each item processed, returned to the orchestrator (which owns the `test-list.md` write; do not edit that file directly)
 - Evidence summary for `.qfai/evidence/`
 - Notes on how simplicity, necessity, and reuse were preserved in the chosen implementation
 

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 an evidence file that is normally ignored, so the diff of changed files
+does not contain them. 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
 
@@ -45,11 +56,17 @@ tools: [Read, Glob, Grep, Bash]
 - 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.
 - The review would rely on speculative future requirements instead of current scope and evidence.
+- The finding would add a product obligation upstream never asked for. Do not raise it as blocking;
+  raise it as an advisory finding plus a Change Request proposal per
+  `.qfai/assistant/constitution/drift-protocol.md#reviewer-originated-obligations`. A defect you can
+  demonstrate from the changed artifacts (correctness, security / data integrity, or a repository
+  quality gate) is NOT in this category: it stays blocking and traces to its `defect:*` class.
 
 ## Sign-off
 
 - [ ] Review verdict is explicit
 - [ ] Findings cite concrete artifacts or evidence
+- [ ] Every finding declares `Severity:` and `Traces to:`; no blocking finding has `Traces to: none`
 - [ ] Required gates and residual risks are recorded
 
 ## When to use

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

@@ -23,7 +23,7 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 - .qfai/assistant/constitution/\*\*
 - .qfai/assistant/{manifest,catalog}/\*\*
 - .qfai/assistant/catalog/test-layers.md (SSOT for hard coverage obligations)
-- .qfai/specs/spec-\*/09_delta.md (Decision Records; check rejected)
+- .qfai/specs/spec-\*/07_Decisions.md and .qfai/specs/\_policies/08_Decisions.md (Decision Records, DR-\*; check rejected)
 - Prompt-specific artifacts (traceability, validation evidence, optional legacy scenario/ledger artifacts)
 
 ## Deliverables (MANDATORY)
@@ -37,7 +37,7 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 ## Stop conditions
 
 - Subagent delegation missing when required
-- Validation gate evidence missing/failing (`qfai validate --fail-on error`)
+- Validation gate evidence missing/failing (`npx qfai validate --fail-on error`)
 - Required hard obligations in `test-layers.md` are unmet
 - Reviewer sign-off missing
 - Rejected option would be reintroduced without RE-OPEN DR

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

@@ -17,16 +17,153 @@ tools: [Read, Glob, Grep, Bash]
 - Audit prototyping coverage evidence and unresolved spec coverage.
 - Treat density or volume smells as review signals, not standalone hard gates.
 - Verify test-case quality depth using the Coverage Depth Matrix (see below).
+- Own RED/GREEN **observation** evidence in a TDD micro-cycle: did the test fail (or pass) for the expected reason.
+
+## Ownership boundaries
+
+- `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.
+
+## Oracle Strength Check (MUST)
+
+GREEN is `exit code == 0`. That does not say the pass depends on the behaviour
+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 **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;
+- the mutation is a syntax error, a thrown "not implemented", or a deleted
+  export — that is a load failure, not a discriminating failure;
+- 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
+assertion past the contract — that is reviewer-originated scope, which
+`drift-protocol.md` forbids. Full criteria and the weak-oracle shapes:
+`.qfai/assistant/skills/qfai-implement/references/oracle-strength.md`.
+
+## RED/GREEN Observation Gate (MUST)
+
+This is the gate `qfai-implement` routes here as blocking, per ledger row. Judge
+the row's own evidence; nothing in the calling work order substitutes for it.
+
+**Accept a RED** only when all hold:
+
+- the test module loaded — the failure is not a collection, import, syntax,
+  missing-symbol or fixture error;
+- an assertion (or expected-exception check) inside the row's own `Selector`
+  raised it, and the message names the predicate the row owns;
+- the recorded output retains that assertion message and its location;
+- when the `Selector` holds several entries, each entry's failure was observed
+  separately. One aggregate run is not a RED for several entries.
+
+**Accept a GREEN** only when the same command shape ran after the production
+change and the recorded output shows the row's own selector passing. A full-suite
+pass that does not name the row's selector is not a GREEN for that row.
+
+**Never accept as a substitute** for a captured failing run of the item's own
+test:
+
+- a narrative claim that the test failed, in any artifact, including a commit
+  message written by the implementing agent — that is self-attestation, which is
+  what this gate exists to prevent;
+- a load error standing in for an assertion failure;
+- evidence copied from a previous round or a sibling row;
+- "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 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.
 
 ## Test Case Quality Depth Check (MUST)
 
 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`). If missing, return FAIL.
+- 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 file is ignored by the
+  managed `.gitignore` block, so neither it nor the justification for any `❌` reaches a commit, and the "unjustified"
+  judgement cannot be re-made by anyone reading the repository.
 - 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`
-- This check is a review signal (not a hard gate that blocks validation), but unjustified gaps MUST be documented as findings.
+- Which verdict applies depends on the review cycle, per the scope note below.
+  On an **SDD** cycle this check is a review signal, not a hard gate that blocks validation.
+  From the **ATDD** cycle onward a missing matrix — or one whose ❌ cells are unjustified — is a REVISE.
+  Either way, unjustified gaps MUST be documented as findings.
+
+### Scope of this check
+
+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 to `.qfai/evidence/coverage-depth-<spec-id>.md` — a committed path, unlike the rest of
+`.qfai/evidence/**`. `qfai-sdd` neither defines its 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
+  the matrix under both Mandatory Outputs and Not-done criteria. A missing matrix is a REVISE there,
+  and so is one whose ❌ cells are unjustified.
+- Do NOT evaluate it against an SDD spec pack that has no tests yet. On an SDD review cycle,
+  assess depth directly from `06_Test-Cases.md` (normal path plus error/boundary coverage per
+  AC) and record any gap as a finding, without requiring the matrix format.
 
 ## Inputs you must read
 
@@ -35,19 +172,60 @@ In addition to traceability-based coverage (US/TC/CON-API existence), verify the
 - .qfai/assistant/{manifest,catalog}/\*\*
 - .qfai/assistant/catalog/test-layers.md
 - .qfai/specs/spec-\*/09_delta.md
-- `.qfai/report/validate.log`
+- `.qfai/specs/spec-*/tdd/test-list.md` — the ledger row under review
+- **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 / FAIL) with rationale
+- Gate decision (PASS / REVISE) with rationale
 - Hard gate status and required fixes
 - Evidence summary and unresolved quality gaps
 
 ## 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

@@ -17,16 +17,30 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 - Estimate test volume as a planning signal, not a hard gate.
 - Prevent unit/component scope creep and ambiguous layer ownership.
 - Evaluate test-case depth using the structured checklist (see reference below).
-- Produce a Coverage Depth Matrix for each spec to expose gaps in boundary values, error paths, edge cases, and combinatorial scenarios.
+- Produce a Coverage Depth Matrix per spec from the ATDD stage onward, exposing gaps in boundary values, error paths, edge cases,
+  and combinatorial scenarios. During SDD, report the same gaps as findings instead — see the stage split below.
 
 ## Test Case Quality Depth (MUST)
 
 When reviewing or producing test cases, apply the checklist in `.qfai/assistant/skills/qfai-atdd/references/test-case-depth-checklist.md`.
 
+Read the stage split first: the checklist's full category set and the Coverage Depth Matrix are ATDD-stage obligations. `qfai-sdd` neither
+defines the matrix layout nor ships an artifact that holds it, and the tests do not exist yet, so the SDD rules below replace them.
+
+From the ATDD stage onward:
+
 - For each US/TC, verify that test cases exist for: normal path, error path, boundary values, special values, state transitions, and combinatorial scenarios.
 - Produce the Coverage Depth Matrix as a required deliverable. Flag any ❌ cells as gaps.
 - Test cases covering only normal (happy) paths are INCOMPLETE. Return REVISE with specific missing scenarios.
-- When business rules (BR-\*) exist, verify each BR has at least one positive and one negative test case.
+
+During SDD:
+
+- Require normal path plus error/boundary coverage per AC, read directly from `06_Test-Cases.md`.
+- Record any further depth gap (special values, state transitions, combinatorial) as a finding.
+- Do NOT produce the matrix, and do NOT return REVISE solely because the matrix is absent or because
+  special / state-transition / combinatorial cases are not yet enumerated.
+
+At both stages: when business rules (BR-\*) exist, verify each BR has at least one positive and one negative test case.
 
 ## Inputs you must read
 
@@ -43,7 +57,12 @@ When reviewing or producing test cases, apply the checklist in `.qfai/assistant/
 
 - Coverage plan and layer ownership
 - Test-case quality and traceability findings
-- **Coverage Depth Matrix** (per spec, using the template in the depth checklist reference)
+- **Coverage Depth Matrix** (per spec, using the template in the depth checklist reference).
+  Destination: `.qfai/evidence/coverage-depth-<spec-id>.md` from the ATDD stage onward — its own
+  file, because that path is committed while the rest of `.qfai/evidence/**` is ignored, 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
 - Scope-boundary decisions for tests
 

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

@@ -1,11 +1,11 @@
 # CLI UX Guidelines
 
-QFAI が定義する、`qfai validate` の UI/UX 関連出力ガイドライン。
+QFAI が定義する、`npx qfai validate` の UI/UX 関連出力ガイドライン。
 
 ## Output Format
 
 - Issue メッセージにタイムスタンプやランダム値を含めない（冪等性確保）
-- `## Auto Check Results` — `qfai validate` による自動チェック結果セクション
+- `## Auto Check Results` — `npx qfai validate` による自動チェック結果セクション
 - `## Manual Review Results` — product-surface-reviewer による手動レビュー結果セクション
 
 ## Error Message Format

package/assets/init/.qfai/assistant/catalog/spec_required_files.json

@@ -21,6 +21,7 @@
     "07_Constraints.md",
     "08_Decisions.md",
     "09_Open-questions.md",
-    "10_delta.md"
+    "10_delta.md",
+    "11_Slice-Policy.md"
   ]
 }