qfai 1.10.0 → 1.10.2

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

@@ -53,6 +53,7 @@ When unsure, read inputs in this order:
   - `.qfai/specs/<spec-id>/03_Acceptance-Criteria.md` (AC)
   - `.qfai/specs/<spec-id>/05_Examples.md` (EX)
   - `.qfai/specs/<spec-id>/06_Test-Cases.md` (TC)
+  - `.qfai/specs/<spec-id>/tdd/test-list.md` (the execution ledger — enumerate the `Layer = E2E` / `Layer = API` / `Layer = Integration` rows this run owes evidence for, with their `TDD-ID`, obligation column and `Selector`)
   - `.qfai/contracts/api/**` (CON-API)
   - `.qfai/contracts/db/**` (CON-DB)
   - `.qfai/contracts/ui/**` and `.qfai/contracts/design/**` when the target spec is UI-bearing
@@ -70,6 +71,7 @@ Do not read discussion-pack UI/UX sidecars. UI-bearing acceptance tests consume
   - `.qfai/specs/<spec-id>/03_Acceptance-Criteria.md`
   - `.qfai/specs/<spec-id>/05_Examples.md`
   - `.qfai/specs/<spec-id>/06_Test-Cases.md`
+  - `.qfai/specs/<spec-id>/tdd/test-list.md` — read, never written. A seeded row's `Test file` and `Selector` are still `-` there, because Phase 2b seeds them before any test exists: record the path and selector of the test **this run authored** as the handoff entry's row identity rather than copying that placeholder, since this stage is where they first exist and `/qfai-implement` Phase Red step 3b is the step that writes them into the ledger. A run that does not enumerate its `Layer = E2E` / `Layer = API` / `Layer = Integration` rows produces no `## Ledger rows advanced` entry for them, and `/qfai-implement` Phase Red step 3b then stops on a missing handoff.
 - Escalation Mode:
   - allowed only when `01_Spec.md` Escalation Hook signals ambiguity / conflict / missing constraint / trade-off
   - read only `.qfai/specs/_policies/01_Objective.md` and `.qfai/specs/_policies/08_Decisions.md`
@@ -112,9 +114,9 @@ Use the shared schema.
 - Follow `.qfai/assistant/constitution/shared-skill-delegation-baseline.md#reviewer-gate-baseline`.
 - Final completion gate MUST be delegated to an independent `completion-reviewer`.
 - ATDD-specific reviewer checks:
-  - coverage obligations met: E2E covers `US`, API covers `CON-API`, and every `TC` is covered from the directory its declared `Level` routes to;
+  - coverage obligations met: E2E covers `US`, API covers `CON-API`, and every `TC` **that declares `L3`/`L4`/`L5` or no `Level`** is covered from the directory that `Level` routes to. `L1`/`Unit` and `L2`/`Component` owe nothing here (CRITICAL CONSTRAINTS): the ledger covers them. An existing L1/L2 annotation in `tests/integration/**` is not a violation — the validator declines to count it and declines to flag it — so do not require one to be added, and do not require an existing one to be removed;
   - Coverage Depth Matrix is reviewed and no unjustified `X` cells remain;
-  - validation evidence exists and `npx qfai validate --profile atdd --fail-on error` passes;
+  - validation evidence exists and `npx qfai validate --profile atdd --fail-on error --spec <spec-id>` passes;
   - Drift Protocol is enforced;
   - test-layer policy is checked against `.qfai/assistant/catalog/test-layers.md`;
   - coverage floors and ratios are signals, not gates;
@@ -149,28 +151,44 @@ Follow `.qfai/assistant/constitution/shared-skill-operating-baseline.md#delta-re
 - Do NOT declare completion based on unit/component tests.
 - `10_Plan.md` is the primary How SSOT for execution phases.
 - If `10_Plan.md` is missing, stop and run owner planning flow before proceeding.
-- Completion gate is validation with zero errors (`npx qfai validate --profile atdd --fail-on error`).
+- Completion gate is validation with zero errors **for this spec**: `npx qfai validate --profile atdd --fail-on error --spec <spec-id>`. The scope flag is not optional bookkeeping. This skill runs one spec per invocation, and unscoped it reports every other spec's `QFAI-ATDD-111` / `-112` obligations — findings this run cannot act on and must not be blocked by. A `--spec` run also writes `<report>/validate.spec-<id>.json` rather than the shared `validate.json`, so the JSON gate artifact is per spec, and an unknown or unparseable value fails the run (`QFAI-SCOPE-001` / `QFAI-SCOPE-002`) instead of silently widening back to the whole repository. **That is not the same as being parallel-safe.** `<report>/validate.log` and the run-log pointer are shared by every run, scoped or not, and nothing serializes them — so two stages running at once can leave that pointer naming the other one's run. Cite the per-run `<report>/run-*/` directory, or this spec's `validate.spec-<id>.json`, as the Validate Hard Gate evidence; do not cite `validate.log` from a run you shared with another stage.
+- **`--spec` scopes the spec-owned rules only, and the gate still fails on the rest.** Every rule whose finding names a spec is scoped: `QFAI-ATDD-111` (US) and `QFAI-ATDD-112` (TC) by the specs they name, `QFAI-ATDD-101` / `-102` by the spec in the unknown token, `QFAI-ATDD-121` / `-122` / `-123` by the specs whose TCs are misplaced, and `D-SCAFFOLD-PLACEHOLDER` by the spec its skeleton belongs to. A scoped run reports all of those for the requested spec and drops a sibling's. What cannot be scoped **does** fail a scoped gate:
+  - `QFAI-ATDD-113` (`CON-API`) and `QFAI-ATDD-115` (`CON-DB`) are attributed to `.qfai/contracts/**`, which has no spec owner in the model;
+  - a reference, or a scaffold directory, naming a spec number no spec pack has, **and sitting where no spec owns it either**: `--spec` on that number is itself rejected, so nothing would report it otherwise. A file under the canonical `tests/<layer>/spec-NNNN/**` layout is owned by _that_ spec whatever its annotation says, so the same broken reference inside `tests/integration/spec-0002/**` belongs to `--spec 0002` and to no other run — reading it as a repo-wide blocker in a sibling run reports something that run cannot see;
+  - anything else reported against a repo-level path.
+
+  So a sibling spec's uncovered contract exits 1 on this spec's gate. That is a real limit, not a formality. When it happens: record the finding, its owning spec and why it is not this stage's work as a cross-spec obligation in this stage's evidence, and say so in the completion report — do **not** claim the gate passed, weaken the profile, lower `--fail-on`, or waive it. Closing them is the owning spec's next `/qfai-atdd` run. The repo-wide run belongs to `/qfai-verify`, at the end of the stage.
+
 - Coverage obligations are mandatory:
-  - `tests/e2e/**` must cover all required `US-*`.
+  - `tests/e2e/**` must cover all required `US-*`. A story outside the current slice is deferred in `02_User-stories.md` with a `- x-qfai-status: planned` meta line in its own `US-XXXX` block (a `##`-or-deeper heading, or its catalog list entry) — the same token both contract kinds use — and is named at `info` by `QFAI-ATDD-118`. It is not left uncovered, and it is not covered by a test that asserts nothing. `exception` is not the alternative here: that branch belongs to a ledger row, and a `US-*` owns none (`references/red-provenance.md#a-spec-with-no-atdd-owned-rows`).
   - Every `TC-*` must be covered from the directory its declared `Level` routes
     to: `L3`/`Integration` -> `tests/integration/**`, `L4`/`API` ->
     `tests/api/**`, `L5`/`E2E` -> `tests/e2e/**`. A TC with no declared `Level`
     routes to `tests/integration/**`.
-  - `tests/api/**` must cover all required `CON-API-*`.
+  - **`L1`/`Unit` and `L2`/`Component` owe nothing here** — out of this skill's
+    scope, excluded from `QFAI-ATDD-112`, gated by `tdd/test-list.md` under
+    `/qfai-implement`, and named on every run by `QFAI-ATDD-117` (`info`). Do
+    not duplicate an L1/L2 annotation into `tests/integration/**` to quiet a
+    gate: that is the all-integration collapse `catalog/test-layers.md` lists as
+    an anti-pattern.
+  - `tests/api/**` must cover all required `CON-API-*`. **An ID carried by a file that declares no test is not coverage**: the scan reads markdown too, and a `.test.ts` holding only the annotation is the same ledger renamed. `QFAI-ATDD-119` (`info`) names them, and coverage is `missing` **and** `coveredByCarrierOnly` in `summary.json`, never `missing` alone. This skill runs one spec, so gate on the narrowed `QFAI-ATDD-119` in `<report>/validate.spec-<id>.json`: `summary.json` stays repo-wide under every scope, and a sibling spec's placeholder would keep its arrays non-empty forever.
 - Forbidden references (a TC annotation outside its declared home):
-  - `tests/api/**` must not contain `QFAI:SPEC-XXXX:TC-YYYY` unless that TC
-    declares `Level` `L4`/`API`.
-  - `tests/e2e/**` must not contain `QFAI:SPEC-XXXX:TC-YYYY` unless that TC
-    declares `Level` `L5`/`E2E`.
+  `tests/api/**` and `tests/e2e/**` must not contain `QFAI:SPEC-XXXX:TC-YYYY`
+  unless that TC declares `Level` `L4`/`API` or `L5`/`E2E` respectively.
 - Unknown references (`US/TC/CON-API` not declared) must be treated as errors.
+- **The E2E/API ledger rows this stage feeds are bound by `/qfai-implement`'s lifecycle.** See "Execution Ledger" below: a row advanced on none of the three RED-provenance forms is a lifecycle violation.
 - Floors/ratios are planning signals only, not gates.
 - Legacy `scenario.feature` or coverage ledgers may exist but are not mandatory inputs for completion.
-- Evidence file is required under `.qfai/evidence/`. Stage evidence is
-  **regenerable** and is not committed. **Governance records are different**:
-  Change Requests (`.qfai/decisions/CR-*.md`) and durable decision records
-  (`.qfai/evidence/decisions/*.json`) carry user approval, are not
-  regenerable, and stay in version control — the managed `.gitignore` block
-  negates them for that reason.
+- The per-item evidence file `.qfai/evidence/atdd-<spec-id>.md` is required and
+  committed. Ledger `Evidence` cells point to its anchors, and validation must
+  resolve them on a fresh clone. The managed `.gitignore` block re-includes it,
+  alongside `.qfai/evidence/implement-<spec-id>.md`. **Governance records also
+  stay in version control**: Change Requests (`.qfai/decisions/CR-*.md`),
+  durable decision records (`.qfai/evidence/decisions/*.json`) and the
+  **Coverage Depth Matrix** (`.qfai/evidence/coverage-depth-<spec-id>.md`).
+- **The matrix is a governance record, not a log**, so it is committed:
+  `.qfai/evidence/coverage-depth-<spec-id>.md`, one justification per `❌`
+  (`references/test-case-depth-checklist.md#where-the-matrix-lives`).
 
 ## Completion Contract (Shared)
 
@@ -181,10 +199,36 @@ Follow `.qfai/assistant/constitution/shared-skill-operating-baseline.md#gate-fai
 
 Turn specs/contracts obligations (`US` / `TC` / `CON-API` / `CON-DB`) into runnable acceptance tests in this repository.
 
+## Execution Ledger: the rows this skill feeds
+
+`.qfai/specs/<spec-id>/tdd/test-list.md` is `/qfai-implement`'s execution
+ledger, and `qfai-implement/SKILL.md` states the split: **`Layer = E2E`,
+`Layer = API` and `Layer = Integration` rows are tracked there, but their tests
+are authored here.** Integration is there because this skill's scope puts it
+there: `QFAI-ATDD-112` covers every `L3` TC, and every TC with no declared
+`Level`, from `tests/integration/**`, and P4 writes those tests. Self-owned,
+they had `/qfai-implement` demand a fresh RED for a test already green here.
+
+- **This skill does not write the ledger.** `/qfai-implement` owns the `Status` / `DR-ID` / `Evidence` cells of every row — one writer, as `constitution/drift-protocol.md` grants. This stage owes the **evidence those cells point at**, in `.qfai/evidence/atdd-<spec-id>.md`.
+- **The lifecycle is `../qfai-implement/references/execution-ledger.md#allowed-transitions`**: forward-only from `todo`, and `todo -> red` requires an **admissible RED** observed before the code that makes it pass exists.
+- **`/qfai-sdd` Phase 2b seeds one `Layer = E2E` row per active `US-*` and one `Layer = API` row per active `CON-API-*` the spec owns — the lowest-numbered spec naming that contract; this stage still cannot create them.** A spec with an active obligation **of its own** therefore normally arrives with rows here — enumerate them and build the handoff from them. Zero is legitimate when every obligation is exempt **and** every active `CON-API-*` the spec references is owned by another spec, and even then is not "nothing to do"; a row missing for an **active** obligation this spec owns is an incomplete Phase 2b — report it, never write it. Do not demand an API row for a contract another spec owns: that row must not exist twice. `references/red-provenance.md#a-spec-with-no-atdd-owned-rows`.
+- **The stage order makes that a real question**: Work Orders build the surfaces a journey needs (P3, P4), so a journey written after them passes first run — an anomaly bound for `exception`, which then becomes the only reachable terminal state.
+
+### RED provenance for an ATDD-owned row (MUST)
+
+**Read `references/red-provenance.md` before advancing any row.** It defines
+three branches, in order — observed RED (stage gate **P1b**, before P2-P4 build
+any surface), falsifiability when the surface is already there, and `exception`
+with a `DR-*` when neither is available. Take the first that applies, record
+which one, and put the evidence in `.qfai/evidence/atdd-<spec-id>.md` under
+`## Ledger rows advanced` — `/qfai-implement` consumes that entry rather than
+re-observing a RED. Branch 3 is the last resort: a stage that routes every row
+to `exception` has recorded that it did not try branches 1 and 2.
+
 ## Scope (ATDD only)
 
-- In scope: E2E, API, Integration.
-- Out of scope: Unit and Component (`/qfai-implement`).
+In scope: E2E, API, Integration. Out of scope: Unit and Component
+(`/qfai-implement`). Tests that must sign in: `references/credential-reuse.md`.
 
 ## Non-goals
 
@@ -194,18 +238,16 @@ Turn specs/contracts obligations (`US` / `TC` / `CON-API` / `CON-DB`) into runna
 ## Mandatory Outputs
 
 1. Test Volume Estimate (signal table with evidence)
-2. **Coverage Depth Matrix** (per spec; see `references/test-case-depth-checklist.md`)
-3. Coverage obligations checklist (`US` / `TC` / `CON-API`)
-4. Implemented tests per layer (E2E/API/Integration)
-5. Reviewer notes (`PASS` or concrete rework list)
-6. Evidence file: `.qfai/evidence/atdd-<spec-id>.md`
+2. **Coverage Depth Matrix**, written to `.qfai/evidence/coverage-depth-<spec-id>.md` (per spec; template and scoring in `references/test-case-depth-checklist.md`). Committed — see CRITICAL CONSTRAINTS.
+3. Coverage obligations checklist (`US` / `TC` / `CON-API`), and the implemented tests per layer (E2E/API/Integration)
+4. Reviewer notes (`PASS` or concrete rework list)
+5. Evidence file: `.qfai/evidence/atdd-<spec-id>.md`
 
 ## Volume Signals (mandatory, not gates)
 
-- E2E signal: number of required `US-*`
-- API signal: number of declared `CON-API-*`
-- Integration signal: number of required `TC-*`
-- When signals are low/high, propose options and recommendation; do not fail solely on signal values.
+E2E = required `US-*`, API = declared `CON-API-*`, Integration = required `TC-*`.
+When a signal is low or high, propose options and a recommendation; never fail
+on a signal value alone.
 
 ### Estimator output table (required)
 
@@ -217,55 +259,43 @@ Turn specs/contracts obligations (`US` / `TC` / `CON-API` / `CON-DB`) into runna
 
 ## Scaffolding
 
-`npx qfai atdd scaffold --spec <spec-id>` bulk-emits one placeholder test per
-coverage-target `TC-*`, 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.
-
-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.
+`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, into `tests/integration/<spec-id>/` — the directory `QFAI-ATDD-112` scans. It is idempotent. `L1`/`L2` and `L4`/`L5` TCs are skipped and named on stderr, and a skeleton left in placeholder shape escalates: `references/scaffolding.md`.
 
 ## Annotation obligations (mandatory)
 
 Every generated ATDD test MUST include QFAI annotations by layer:
 
-- `tests/e2e/**`: `QFAI:SPEC-XXXX:US-YYYY` (plus `QFAI:SPEC-XXXX:TC-YYYY` for a
-  TC that declares `Level` `L5`/`E2E`)
-- `tests/integration/**`: `QFAI:SPEC-XXXX:TC-YYYY` (TCs declaring `L3`/
-  `Integration`, and TCs with no declared `Level`)
-- `tests/api/**`: `QFAI:CON-API-XXXX` (plus `QFAI:SPEC-XXXX:TC-YYYY` for a TC
-  that declares `Level` `L4`/`API`)
+- `tests/e2e/**`: `QFAI:SPEC-XXXX:US-YYYY` (plus `QFAI:SPEC-XXXX:TC-YYYY` for a TC that declares `Level` `L5`/`E2E`)
+- `tests/integration/**`: `QFAI:SPEC-XXXX:TC-YYYY` (TCs declaring `L3`/`Integration`, and TCs with no declared `Level`)
+- `tests/api/**`: `QFAI:CON-API-XXXX` (plus `QFAI:SPEC-XXXX:TC-YYYY` for a TC that declares `Level` `L4`/`API`)
 - `tests/integration/**` also carries `QFAI:CON-DB-XXXX` for every declared DB
   contract the slice exercises
 
 Notes:
 
-- A TC's annotation belongs in exactly one directory — the one its declared
-  `Level` routes to. Placing it elsewhere is both uncovered (`QFAI-ATDD-112`)
-  and forbidden (`QFAI-ATDD-121` / `QFAI-ATDD-122` / `QFAI-ATDD-123`). The rule
-  is symmetric: an annotation left behind in `tests/integration/**` after the
-  TC moved to `L4`/`L5` is rejected by `QFAI-ATDD-123` just as an early one in
-  `tests/api/**` is rejected by `QFAI-ATDD-121`.
+- A TC's annotation belongs in exactly one directory — the one its declared `Level` routes to. Elsewhere it is both uncovered (`QFAI-ATDD-112`) and forbidden, symmetrically: one left behind in `tests/integration/**` after the TC moved to `L4`/`L5` is rejected by `QFAI-ATDD-123` just as an early one in `tests/api/**` is rejected by `QFAI-ATDD-121`.
 - AC annotations are optional in code.
 - `QFAI:CON-API-*` in E2E is not forbidden, but contract guarantee belongs to API tests.
 
 ## Success Criteria (Definition of Done)
 
-- All required `US` are covered by E2E tests.
+- All required `US` are covered by E2E tests (`QFAI-ATDD-111`); a story outside the current slice is deferred with `- x-qfai-status: planned` in its `02_User-stories.md` block and reported by `QFAI-ATDD-118` (`info`), not left uncovered.
 - All required `TC` are covered from the directory their declared `Level` routes
   to (`L3`/`Integration` -> `tests/integration/**`, `L4`/`API` ->
   `tests/api/**`, `L5`/`E2E` -> `tests/e2e/**`, no declared `Level` ->
-  `tests/integration/**`). Duplicating a TC into a second layer is a
-  not-done condition, not extra credit.
+  `tests/integration/**`). **`L1`/`Unit` and `L2`/`Component` are outside this
+  obligation** — the ledger covers them — so a spec whose TCs are all L1/L2 is
+  done here with no ATDD annotation at all. Duplicating a TC into a second layer
+  is a not-done condition, not extra credit.
 - All required `CON-API` are covered by API tests.
 - All required `CON-DB` are covered by integration tests (`QFAI-ATDD-115`); a contract
   outside the current slice is deferred with `-- x-qfai-status: planned`, not left uncovered.
-- Validation passes: `npx qfai validate --profile atdd --fail-on error`.
+- Validation passes for this spec: `npx qfai validate --profile atdd --fail-on error --spec <spec-id>`.
 - Repository quality gates (format/lint/type/tests/pack) pass with evidence.
 - Evidence file exists and includes work orders + reviewer notes.
+- Every ledger row this cycle advanced carries one of the three RED-provenance forms — an observed RED pair with its `Oracle proof`, the `Satisfied-by` + falsifiability trio, or a `DR-*` recording why neither was available — and `qa-gatekeeper` has accepted it. The third form is a valid _branch_, and it is **not a completion**: `exception` is a blocking output and needs a user-approved `TDDLIST-001` waiver, or the row is parked and the spec stays open (`references/red-provenance.md#branch-3-does-not-close-a-spec-on-its-own`).
 - Completion is approved by a reviewer who did not implement tests.
+- **The P8 reviewer's `Audited evidence hash` is recomputed before completion is declared**, from the current stage evidence file and Coverage Depth Matrix, by the stage-review procedure that produced it (`.qfai/assistant/constitution/shared-skill-delegation-baseline.md#reviewer-response-template`); a mismatch means the evidence moved after the verdict. **Seal the P8 pack too**: when the last reviewer response lands, and before this stage writes its verdict, hash the pack this stage opened — `.qfai/review/review-<timestamp>/`, whole — by the same procedure, and record it **outside the pack** in the stage evidence file's `## Final status` as `Review pack:` (that path) and `Review pack seal:` (that hash). That section is the one part excluded from the P8 audit subject, so writing it there does not stale the verdict, and it exists even on a spec with no ATDD-owned rows — where there is no item evidence entry to hold the seal at all. At completion, recompute the seal over the recorded path and compare it with the **recorded** value — `../qfai-implement/references/evidence-revision.md` states that rule once and it applies here: `## Final status` is outside every audit subject and outside the working-tree revision, so an expected value read from the working tree could be rewritten in the same pass that edited the pack, and every recomputation would still agree, and check that `## Final status` says what that pack says. The recording and the recomputation must be two moments: a value computed from the pack at completion always matches itself whatever was edited in between, and the stage hash covers the evidence but not the verdict, so a `REVISE` edited to `PASS` in the response, the summary and the status together left every recomputation unchanged. On a spec with no ATDD-owned rows `/qfai-implement`'s gate item 10 never runs, so without this the stored hash was written by P8 and read by nobody — and the evidence tree is out of the working-tree revision, so a later edit moved nothing else either.
 
 ## Not-done criteria
 
@@ -274,6 +304,8 @@ Notes:
 - Tests exist but were never executed.
 - Validation evidence is missing or failing.
 - Coverage Depth Matrix is missing or contains unjustified ❌ cells (normal-path-only coverage is incomplete).
+- A ledger row was advanced past `todo` with none of the three forms — no observed RED, no falsifiability evidence, and no `DR-*`.
+- A row was sent to `exception` without a `DR-*` recording why **both** branches were unavailable. "The surface was built earlier in this cycle" is not such a reason.
 
 ## Failure handling (mandatory)
 
@@ -284,19 +316,17 @@ Notes:
 
 Create and update: `.qfai/evidence/atdd-<spec-id>.md`
 
-Required sections:
+Required sections: the template below is the list. Two of them carry a contract
+the heading cannot:
 
-- Objective
-- Inputs reviewed (files/paths)
-- Decisions made (with rationale)
-- Work performed (what changed, where)
-- Commands executed + key outputs
-- Test volume estimate
-- Coverage obligations checklist
-- Work Orders Summary
-- Execution logs
-- Gaps / Open risks
-- Final status (PASS/FAIL) + who confirmed
+- **Ledger rows advanced** — an index table plus one `### TDD-NNNN` section per
+  row. Exactly one form per row, never both and never neither; the cell is an
+  anchor and the payload goes in the section
+  (`references/red-provenance.md#evidence-shape`).
+- **Coverage Depth Matrix** — a link to
+  `.qfai/evidence/coverage-depth-<spec-id>.md` and the `✅`/`⚠️`/`❌` totals.
+  The matrix and its per-`❌` justifications live in that committed file;
+  restating them here would lose them.
 
 Template:
 
@@ -317,6 +347,15 @@ Template:
 
 ## Coverage obligations checklist
 
+## Ledger rows advanced
+
+<!-- Index table + one `### TDD-NNNN` section per row:
+     `references/red-provenance.md#evidence-shape`. -->
+
+## Coverage Depth Matrix
+
+See `.qfai/evidence/coverage-depth-<spec-id>.md` (committed). Totals: ✅ N / ⚠️ N / ❌ N.
+
 ## Work Orders Summary
 
 ## Execution logs
@@ -330,9 +369,7 @@ Template:
 
 - **Test Case Depth Analyst**: `test-design-analyst` evaluates test cases using `references/test-case-depth-checklist.md`, produces Coverage Depth Matrix, flags gaps in boundary/error/edge coverage.
 - Test Volume Estimator: compute US/TC/CON signals with evidence.
-- ATDD E2E Implementer: implement required `US` coverage.
-- ATDD API Implementer: implement required `CON-API` coverage.
-- ATDD Integration Implementer: implement required `TC` coverage.
+- ATDD Implementers, one per layer: required `US` coverage in E2E, `CON-API` in API, `TC` in Integration.
 - Reviewer: validate coverage obligations + gate results + Coverage Depth Matrix (non-edit).
 - Runtime Gatekeeper: run suites and capture logs.
 
@@ -343,11 +380,29 @@ Template:
 
 ## Stage Gates (Do not skip)
 
-- P0: Plan and obligations checklist prepared.
+- P0: Plan and obligations checklist prepared. A project whose routing has no
+  `red` phase predates it: `references/red-provenance.md#a-project-without-the-red-phase`.
 - P1: Layer assignment validated against `.qfai/assistant/catalog/test-layers.md#layer-derivation-procedure-normative`.
+- P1b: **A branch is chosen for every row**, provisional until its handoff.
+- P1c: **A branch 1 row is discharged in that loop** — write the test, take the
+  RED, `qa-gatekeeper` PASS, hand it to `/qfai-implement`, GREEN, checkpoint —
+  before the next branch-1 row's failing test is written, and before P2-P4 build
+  any surface. One loop per `TDD-ID`; the nested run is an item cycle, not a
+  completion gate (`references/red-provenance.md#what-the-nested-run-owes`).
+- P1d: **Branch 3 rows are judged here, then handed over.** Route
+  `qa-gatekeeper` on the `DR-*` — the claim is that the obligation genuinely
+  cannot be observed — and hand the row over **with that PASS recorded**. P1b's
+  gatekeeper judges branch 1 only and `/qfai-implement`'s exception path writes
+  `todo -> exception` and stops, so without this a correct branch-3 row reached
+  a terminal status judged by nobody. `/qfai-implement` is the only writer of
+  `Status` / `DR-ID` / `Evidence`, so every branch needs a handoff; which goes
+  when: `references/red-provenance.md#which-stage-hands-a-row-over`.
 - P2: E2E implementation completed.
 - P3: API implementation completed.
 - P4: Integration implementation completed.
+- P4b: **Branch 2 rows are handed over**, after P4 and before P6 — their mutation
+  needs the surface P2-P4 build, the trio is the row's RED payload, and that nested
+  run is an item cycle like P1c's (`references/red-provenance.md#what-the-nested-run-owes`).
 - P5: Validation gate passed.
 - P6: Runtime evidence captured.
 - P7: Repo quality gates passed.
@@ -361,9 +416,13 @@ Before declaring completion:
 2. Run:
 
    ```bash
-   npx qfai validate --profile atdd --fail-on error
+   npx qfai validate --profile atdd --fail-on error --spec <spec-id>
    ```
 
+   `--spec` scopes the gate to the spec this invocation owns. Omitting it makes
+   the gate report obligations belonging to specs this run never touched, which
+   is how a spec with every obligation discharged still fails to close.
+
 3. Run repository standard gates:
    - format check
    - lint
@@ -383,11 +442,9 @@ If commands cannot be run due to environment limits, request user execution and
 
 ## DONE Declaration (Mandatory Output)
 
-When declaring DONE, include:
-
-- Referenced inputs (instructions/steering and spec delta)
-- DR-IDs referenced (or "none")
-- Confirmation that no rejected options were reintroduced (or RE-OPEN DR-IDs)
+Include the referenced inputs (instructions/steering and spec delta), the DR-IDs
+referenced (or "none"), and confirmation that no rejected options were
+reintroduced (or the RE-OPEN DR-IDs).
 
 ## FINAL CHECKLIST (Check Last)
 
@@ -437,6 +494,6 @@ A skill MAY narrow the auto-decide bucket (drop entries) but MUST NOT widen it.
 
 project_memory:
 
-- Coverage obligations stay layer-pinned for US and CON-API: tests/e2e/** must cover all required US; tests/api/\*\* all required CON-API. Each TC is covered from the directory its declared Level routes to (L3/Integration -> tests/integration/**, L4/API -> tests/api/\*\*, L5/E2E -> tests/e2e/\*\*; no declared Level -> tests/integration/\*\*).
+- Coverage obligations stay layer-pinned for US and CON-API: tests/e2e/** must cover all required US; tests/api/\*\* all required CON-API. Each TC declaring L3/L4/L5, or no Level, is covered from the directory that Level routes to (L3/Integration -> tests/integration/**, L4/API -> tests/api/\*\*, L5/E2E -> tests/e2e/\*\*; no declared Level -> tests/integration/\*\*). L1/Unit and L2/Component owe no ATDD annotation — tdd/test-list.md covers them. An existing one in tests/integration/\*\* is neither counted nor flagged, so do not require adding or removing it.
 - Forbidden references guard the test-layer policy: a TC annotation outside its declared home is rejected — tests/api/** must not carry QFAI:SPEC-XXXX:TC-YYYY unless that TC declares L4/API, and tests/e2e/** likewise unless it declares L5/E2E.
 - Floor / ratio signals are planning hints, never gates; legacy scenario.feature / coverage ledger files remain optional inputs.

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

@@ -0,0 +1,146 @@
+# Credential reuse across parallel workers
+
+Acceptance tests that need an authenticated actor pay for the sign-in once per worker, not once
+per test. This file is the rule set. It is prose guidance — it adds no validator, no finding code,
+no test layer and no annotation token, and nothing here is checked by a tool.
+
+## Scope
+
+These rules oblige the **E2E, API and Integration** layers only, which is this skill's whole scope.
+They introduce no unit or component obligation: those layers belong to `/qfai-implement`, and a
+unit test that needs a credential is describing an integration.
+
+This guidance names no test runner and no browser automation library. Every rule below is stated
+about a _session cache_ and a _worker_, which every parallel runner has under some spelling, so
+choosing the tool stays the adopter's decision.
+
+## Not dogfooded here
+
+**QFAI's own suite has zero credentials.** Nothing in this repository signs in, so none of these
+rules is exercised by running the tests here. They are recorded because the rule set is the
+transferable asset, not because they were verified by execution in this tree — read them as
+guidance to adopt, not as a report of something that already runs.
+
+## The seven session-reuse rules
+
+Each is a separate obligation. A harness can satisfy six of them and still authenticate on every
+test, or still leak one account across workers.
+
+### 1. Never sign in per test
+
+Authentication belongs to worker setup, not to a test body. A suite that signs in per test pays
+the slowest operation it has once per case, and the cost grows with the suite instead of with the
+worker count.
+
+### 2. Never share one account across parallel workers
+
+Two workers driving the same actor at the same time is a race with no test to blame it on: a
+sign-out, a session invalidation or a state change made by one worker arrives inside the other's
+assertions. One account per worker, always — a shared account is not an optimisation, it is a
+cross-test dependency that the runner cannot see.
+
+### 3. Key the cached session by the pair of worker index and actor
+
+Neither half is sufficient on its own. Keyed by actor alone, two workers exercising the same role
+collide — rule 2 again, arriving through the cache. Keyed by worker alone, a suite that needs an
+administrator and an ordinary user hands the second one the first one's session, and the test
+fails on an authorisation it never intended to exercise. The key is the **pair**.
+
+### 4. Tear the cache down at worker exit
+
+A session cache that outlives its worker is a credential on disk. It also becomes a correctness
+problem the next run: a restored session from a previous run reflects a state the current run
+never established, so a test can pass against data it did not create. Bind the cache's lifetime to
+the worker's.
+
+### 5. Re-authenticate and rewrite the cache when a restored session is rejected
+
+A cached session expires, gets revoked, or stops being valid because the environment was reset
+between runs. The harness must detect the rejection, sign in again, and **overwrite** the cache
+with the fresh session. Two failure modes this closes: a suite that treats the rejection as a test
+failure reports a red that says nothing about the product, and a suite that retries against the
+stale cache loops.
+
+### 6. A test that mutates its own account creates a dedicated one
+
+Changing a password, disabling the account, altering a profile, consuming a one-time entitlement:
+each of those breaks the cached session every _other_ test on that actor depends on. A test whose
+subject is the account itself provisions its own actor, uses it, and does not put it back in the
+pool.
+
+### 7. Test-level parallelism costs more workers, not more sign-ins
+
+Raising parallelism adds workers; each new worker pays one sign-in. If raising parallelism raises
+the sign-in count faster than the worker count, one of the six rules above is not being followed —
+most often rule 1, and most often because a helper was called from a test body rather than from
+setup. The ratio is the diagnostic.
+
+## The companion rule: a caller-injected environment is not the harness's to manage
+
+When the caller injects an environment identifier — a target URL, a tenant, a named deployment,
+any handle that says _use this one_ — the harness **must not provision that environment and must
+not tear it down.** It signs in against it, runs, and leaves it exactly as it found it.
+
+The reason is that the injection is what tells the harness the environment is owned elsewhere.
+A harness that provisions when it was handed a target creates a second environment nobody asked
+for; a harness that tears one down at the end of a run destroys a shared or long-lived environment
+that other work depends on. Both are irreversible from inside the run.
+
+The rule is about _ownership_, not about the shape of the value: a harness that creates its own
+ephemeral environment when nothing was injected is following this rule, not breaking it.
+
+## Script naming: adopter guidance
+
+**A credential-free lane and a credentialed lane should be reachable under different script
+names.** A lane that structurally cannot touch the network is a different thing from one that must
+have a working account, and giving them one name makes that difference invisible to whoever runs
+them: contributors without credentials cannot tell which lane they can run, and CI cannot express
+"run the half that needs no secrets" without a name for it.
+
+Two properties do the work, whatever the names are:
+
+- the credential-free lane is runnable by someone who has no account at all, and
+- reading the script name tells you which of the two you are about to run.
+
+**This is adopter guidance and QFAI adopts none of it.** QFAI keeps its own script names unchanged;
+because its suite has no credentials there is no credentialed lane here to name, and renaming a
+lane to model a distinction this repository does not have would be a cost with no reader.
+
+## A worked example, as one illustration among possible backends
+
+The shape below is **one** way to satisfy the rules, sketched in no particular tool. Any runner
+with per-worker setup and a place to persist a session can express it, and the rules — not this
+sketch — are what has to survive the translation.
+
+```text
+worker setup:
+    key   = (worker index, actor role)
+    cached = load(key)                       # rule 3: the pair is the key
+    if cached is absent:
+        session = sign_in(actor for key)     # rule 1: once per worker
+        save(key, session)
+    else:
+        if not accepted(cached):             # rule 5: a restored session can be rejected
+            session = sign_in(actor for key)
+            save(key, session)               #         ...and the cache is rewritten
+
+each test:
+    attach the session for this worker's key # never sign_in here
+
+a test that mutates its actor:
+    actor = create_dedicated_actor()         # rule 6: not from the pool
+    ...
+    (the pooled session is untouched)
+
+worker teardown:
+    discard(key)                             # rule 4: lifetime is the worker's
+
+environment:
+    if the caller injected a target:
+        use it; provision nothing; tear down nothing   # the companion rule
+    else:
+        the harness may create and destroy its own
+```
+
+Nothing in that sketch names a library, and it should not: the moment a rule is expressed as one
+tool's API call, it stops being portable to the next one.