qfai 1.10.1 → 1.10.2

package/assets/init/.qfai/assistant/catalog/test-layers.md

@@ -3,9 +3,8 @@
 This document is the SSOT for ATDD test-layer semantics and completion gates.
 
 For which CI lane runs which layer, see the sibling map
-[`test-layers-ci-lanes.md`](./test-layers-ci-lanes.md). That file is a crosswalk only — the
-policy loader reads this file and not that one, so nothing there can change the
-vocabulary declared below.
+[`test-layers-ci-lanes.md`](./test-layers-ci-lanes.md). That file is a crosswalk only — the policy
+loader reads this file and not that one, so nothing there can change the vocabulary declared below.
 
 ## Layer vocabulary crosswalk (normative)
 
@@ -46,21 +45,20 @@ Rules:
   ID type. A `TC-*` is answered from the directory **its own declared `Level`**
   names, which for a correctly filed row is `<testsDir>/integration/**`; see
   [Annotation routing](#annotation-routing) for the full table and the
-  misplacement rules.
-  L4's goal is `CON-API-*` and L5's is `US-*` (see the layer definitions
-  below), so an oracle that lands at L4 or L5 means the obligation is misfiled:
-  record it as `CON-API-*` or `US-*` rather than leaving a `TC-*` row at a
-  layer whose goal is another ID type.
+  misplacement rules. L4's goal is `CON-API-*` and L5's is `US-*` (see the
+  layer definitions below), so an oracle that lands at L4 or L5 means the
+  obligation is misfiled: record it as `CON-API-*` or `US-*` rather than
+  leaving a `TC-*` row at a layer whose goal is another ID type.
 - The two code-side word lists (`tddHelpers.ts#UNIT_COMPONENT_LAYERS` /
   `#NON_COVERAGE_LAYERS`) accept both the code and the word form for the same
   layer; they MUST stay in step with this table.
 
 ## How this file is consumed
 
-The layer set below is read by `core/layerPolicy.ts` and is the SSOT for two
-checks: `QFAI-EX-005` on the legacy spec-pack layout, and `QFAI-EX-105` on the
-layered layout `npx qfai init` produces. Until both consumed it, the file was
-read, reported on, and then ignored on every modern project.
+This file is the SSOT for the layer set below: `npx qfai validate` reads the layers
+from here and applies them to two checks — `QFAI-EX-005` on the legacy spec-pack
+layout, and `QFAI-EX-105` on the layered layout `npx qfai init` produces. Until both
+consumed it, the file was read, reported on, and then ignored on every modern project.
 
 - A file that yields no layers raises `QFAI-SPACK-090` (error) rather than
   silently widening to the built-in set.
@@ -96,19 +94,19 @@ writer targets a declared layer instead.
 
 - Scope: real infrastructure integration (for example DB/queue/filesystem) within service boundaries.
 - Goal: verify `TC-*` obligations from specs.
-- Location rule: `tests/integration/**`.
+- Location rule: `<testsDir>/integration/**`.
 
 ### L4 API
 
 - Scope: service-boundary contracts (HTTP/gRPC/etc), auth, and error contracts.
 - Goal: verify `CON-API-*` obligations from contracts.
-- Location rule: `tests/api/**`.
+- Location rule: `<testsDir>/api/**`.
 
 ### L5 E2E
 
 - Scope: representative full-system journeys across UI/API/data.
 - Goal: verify `US-*` obligations from specs.
-- Location rule: `tests/e2e/**`.
+- Location rule: `<testsDir>/e2e/**`.
 
 ## Layer derivation procedure (normative)
 
@@ -184,22 +182,21 @@ all-integration suite.
 
 ### Annotation routing
 
-The derived `Level` records which oracle owns the obligation, and the
-[ATDD annotation hard gate](#atdd-annotation-hard-gate) routes each obligation
-ID to exactly one directory. `US-*` is answered from `tests/e2e/**`
-(`QFAI-ATDD-111`) and `CON-API-*` from `tests/api/**` (`QFAI-ATDD-113`); those
-two are fixed by the ID type. A `TC-*` is answered from the directory **its own
-declared `Level`** names (`QFAI-ATDD-112`):
-
-| `Level`                       | Answered from                  |
-| ----------------------------- | ------------------------------ |
-| `L1`/`Unit`                   | no ATDD obligation             |
-| `L2`/`Component`              | no ATDD obligation             |
-| `L3`/`Integration`            | `tests/integration/**`         |
-| `L4`/`API`                    | `tests/api/**` (note)          |
-| `L5`/`E2E`                    | `tests/e2e/**` (note)          |
-| none declared                 | `tests/integration/**`         |
-| anything else — typo, `L3/L5` | `tests/integration/**` (note2) |
+The derived `Level` records which oracle owns the obligation, and the [ATDD annotation hard
+gate](#atdd-annotation-hard-gate) routes each obligation ID to exactly one directory. `US-*` is
+answered from `<testsDir>/e2e/**` (`QFAI-ATDD-111`) and `CON-API-*` from `<testsDir>/api/**`
+(`QFAI-ATDD-113`); those two are fixed by the ID type. A `TC-*` is answered from the directory **its
+own declared `Level`** names (`QFAI-ATDD-112`):
+
+| `Level`                       | Answered from                       |
+| ----------------------------- | ----------------------------------- |
+| `L1`/`Unit`                   | no ATDD obligation                  |
+| `L2`/`Component`              | no ATDD obligation                  |
+| `L3`/`Integration`            | `<testsDir>/integration/**`         |
+| `L4`/`API`                    | `<testsDir>/api/**` (note)          |
+| `L5`/`E2E`                    | `<testsDir>/e2e/**` (note)          |
+| none declared                 | `<testsDir>/integration/**`         |
+| anything else — typo, `L3/L5` | `<testsDir>/integration/**` (note2) |
 
 **(note)** A `TC-*` **should not be** at L4 or L5 — the first bullet below says
 why and what to do instead. The gate routes it there rather than rejecting it so
@@ -213,12 +210,10 @@ answer to a cell qfai cannot read, never a supported spelling: fix the cell
 (see [Obligation spanning more than one layer](#obligation-spanning-more-than-one-layer)).
 `TDDLIST_UNKNOWN_LEVEL` (`warning`) names such a cell on the ledger side.
 
-Exactly one directory, never two: an annotation outside the one its `Level`
-names is both uncovered and rejected (`QFAI-ATDD-121` / `QFAI-ATDD-122` /
-`QFAI-ATDD-123`), and
-the rejection is symmetric — an annotation left in `tests/integration/**` after
-its TC moved to `L4`/`L5` is rejected the same way an early one in
-`tests/api/**` is. Two consequences bind every `TC-*` row:
+Exactly one directory, never two: an annotation outside the one its `Level` names is both uncovered
+and rejected (`QFAI-ATDD-121` / `QFAI-ATDD-122` / `QFAI-ATDD-123`), and the rejection is symmetric —
+an annotation left in `<testsDir>/integration/**` after its TC moved to `L4`/`L5` is rejected the
+same way an early one in `<testsDir>/api/**` is. Two consequences bind every `TC-*` row:
 
 - **A `TC-*` row's `Level` stays within L1–L3.** L4's goal is `CON-API-*` and
   L5's goal is `US-*` (see the layer definitions above), so an oracle that
@@ -247,13 +242,19 @@ its TC moved to `L4`/`L5` is rejected the same way an early one in
   `tdd/test-list.md` and `TDDLIST_TC_NOT_COVERED`, not through an annotation in
   a directory ATDD scans.
 
-## TestKind resolution (single source)
+## Directory → AtddTestKind (code-side, derived from the crosswalk)
 
-- `tests/unit/**` -> Unit
-- `tests/component/**` -> Component
-- `tests/e2e/**` -> E2E
-- `tests/api/**` -> API
-- `tests/integration/**` -> Integration
+Derived from `## Layer vocabulary crosswalk (normative)`, which is the
+authority for this mapping. This list only restates the three kinds the ATDD
+scan can resolve:
+
+- `<testsDir>/integration/**` -> Integration
+- `<testsDir>/api/**` -> API
+- `<testsDir>/e2e/**` -> E2E
+
+L1 Unit and L2 Component resolve to no kind. They follow project convention, no
+directory maps to them, and none of them is scanned — see the crosswalk rules
+and `**Unit and Component owe no ATDD annotation.**` above.
 
 ## Annotation schema (code-side)
 
@@ -272,7 +273,7 @@ its TC moved to `L4`/`L5` is rejected the same way an early one in
 
 - E2E obligations:
   - Every `US-*` in a **user-facing** spec must be referenced at least once from
-    `tests/e2e/**`. "User-facing" is the same surface **union**
+    `<testsDir>/e2e/**`. "User-facing" is the same surface **union**
     `/qfai-prototyping` enforces. Any one of these signals puts a spec in it:
     - frontmatter `surface_type: ui-bearing` in `01_Spec.md`;
     - a matching UI contract `.qfai/contracts/ui/<spec-id>*.yaml` — a project
@@ -286,37 +287,33 @@ its TC moved to `L4`/`L5` is rejected the same way an early one in
   - Scoping applies only when the project declares at least one UI-bearing
     spec. A project that has never declared a surface has not opted into
     surface typing, so the obligation stays project-wide for it.
+  - **Deferral.** A story whose acceptance cannot be observed at E2E in the current slice defers with a `- x-qfai-status: planned` meta line inside its own `US-XXXX` block (a `##`-or-deeper heading, or its catalog list entry) in `02_User-stories.md` — the same token the two contract kinds use. It leaves `QFAI-ATDD-111` and is reported as `QFAI-ATDD-118` (`info`); remove the marker when the slice is implemented. It counts only inside the story block it is written in, so one above the first `US-XXXX` heading defers nothing — one line must not drop the obligation for a whole file. It removes the test obligation, not the declaration. A deferred `US-*` stays a known ID, so an early E2E test is counted, not an unknown reference. This is per story, unlike the surface-type scoping above, a whole-spec property that would erase the siblings too.
   - Do not create an E2E tree whose only purpose is to receive annotations.
     That is the "convert all obligations into E2E" anti-pattern below.
   - Use `QFAI:SPEC-XXXX:US-YYYY` annotations.
 
 - Integration obligations (enforced today):
-  - Every `TC-*` in specs must be referenced at least once 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` defaults to `tests/integration/**`. **L1/Unit and L2/Component owe
-    no reference at all** — see "Unit and Component owe no ATDD annotation"
-    below. This is what `QFAI-ATDD-112` checks.
+  - Every `TC-*` in specs must be referenced at least once from the directory its declared `Level`
+    routes to: L3/Integration -> `<testsDir>/integration/**`, L4/API -> `<testsDir>/api/**`, L5/E2E
+    -> `<testsDir>/e2e/**`. A TC with no declared `Level` defaults to `<testsDir>/integration/**`.
+    **L1/Unit and L2/Component owe no reference at all** — see "Unit and Component owe no ATDD
+    annotation" below. This is what `QFAI-ATDD-112` checks.
   - Use `QFAI:SPEC-XXXX:TC-YYYY` annotations.
-  - A `TC-*` annotation outside the directory its declared `Level` names is
-    rejected (`QFAI-ATDD-121` / `QFAI-ATDD-122` / `QFAI-ATDD-123`). The rule is
-    `Level`-relative,
-    not a blanket ban: a `TC-*` in `tests/api/**` is rejected **unless** that TC
-    declares `L4`/`API`, and in `tests/e2e/**` unless it declares `L5`/`E2E` —
-    an annotation matching its own `Level` is what discharges the obligation
-    there. A `TC-*` should not be at L4 or L5 in the first place (see
-    "Annotation routing"): re-file that obligation as `CON-API-*` or `US-*`.
-    But while the row exists at that `Level`, its annotation belongs in the one
-    directory the `Level` names, and putting it anywhere else leaves the TC
-    uncovered as well as forbidden.
-  - Every declared `CON-DB-*` must be referenced at least once from
-    `tests/integration/**` (`QFAI-ATDD-115`). Use `QFAI:CON-DB-XXXX`
-    annotations. L3 owns this because a DB contract is only exercised against
-    real infrastructure, which is L3's declared scope; a `CON-DB` reference
-    from `tests/e2e/**` is not counted, or an end-to-end assertion that never
-    touches the schema could close the obligation. A contract outside the
-    current slice defers with a `-- x-qfai-status: planned` comment line,
-    reported at `info` by `QFAI-ATDD-116` so the deferral stays visible.
+  - A `TC-*` annotation outside the directory its declared `Level` names is rejected
+    (`QFAI-ATDD-121` / `QFAI-ATDD-122` / `QFAI-ATDD-123`). The rule is `Level`-relative, not a
+    blanket ban: a `TC-*` in `<testsDir>/api/**` is rejected **unless** that TC declares `L4`/`API`,
+    and in `<testsDir>/e2e/**` unless it declares `L5`/`E2E` — an annotation matching its own
+    `Level` is what discharges the obligation there. A `TC-*` should not be at L4 or L5 in the first
+    place (see "Annotation routing"): re-file that obligation as `CON-API-*` or `US-*`. But while
+    the row exists at that `Level`, its annotation belongs in the one directory the `Level` names,
+    and putting it anywhere else leaves the TC uncovered as well as forbidden.
+  - Every declared `CON-DB-*` must be referenced at least once from `<testsDir>/integration/**`
+    (`QFAI-ATDD-115`). Use `QFAI:CON-DB-XXXX` annotations. L3 owns this because a DB contract is
+    only exercised against real infrastructure, which is L3's declared scope; a `CON-DB` reference
+    from `<testsDir>/e2e/**` is not counted, or an end-to-end assertion that never touches the
+    schema could close the obligation. A contract outside the current slice defers with a
+    `-- x-qfai-status: planned` comment line, reported at `info` by `QFAI-ATDD-116` so the
+    deferral stays visible.
 
 - **Unit and Component owe no ATDD annotation.** A `TC-*` whose declared
   `Level` is L1 or L2 is outside `QFAI-ATDD-112` entirely: it is not required
@@ -327,20 +324,22 @@ its TC moved to `L4`/`L5` is rejected the same way an early one in
     `qfai-atdd/SKILL.md` puts Unit and Component out of its scope, and the
     crosswalk above gives L1/L2 no mandated directory — only L3-L5 are
     directory-pinned and only those three roots are scanned.
-  - Previously L1/L2 fell through to `tests/integration/**` — the fallback for
+  - Previously L1/L2 fell through to `<testsDir>/integration/**` — the fallback for
     a spec with no `Level` column at all — so every declared Unit and Component
     TC was an `error` demanding an annotation in a directory this file says is
     not its home. `QFAI-WAIVER-002` refuses waivers on `error` rules, so a
     project that filed unit tests where L1's own entry says to had no exit, and
     the only validator-clean path was duplicating every annotation into
-    `tests/integration/**` — the all-integration collapse named under
+    `<testsDir>/integration/**` — the all-integration collapse named under
     Anti-patterns below.
   - **They are still gated, by the other stage.** Every coverage-target `TC-*`
     owes a `tdd/test-list.md` row, and `TDDLIST_TC_NOT_COVERED` (`error`)
     reports a missing one. L1/L2 belong to `/qfai-implement`, which is the
     stage that writes unit and component tests.
+
+- **An annotation carrier is not a test.** The scan reads `.feature` and `.md` too, and a file's kind is read from its body: a `.feature` with a `Scenario:` declares a test, a `.md` never does, and a `.test.ts` holding only the annotation is the same ledger renamed. An obligation no carrier declares a test for clears `QFAI-ATDD-111` / `-112` / `-113` / `-115` with nothing behind it, so `QFAI-ATDD-119` (`info`) names it — a legitimate placeholder that must not read as coverage. A repo-wide gate reads `missing.<kind>` **and** `coveredByCarrierOnly` in `summary.json`, never `missing` alone; a `--spec` gate reads the narrowed `QFAI-ATDD-119` in `validate.spec-<id>.json`, because `summary.json` is repo-wide under every scope. A skipped test still counts as declared, and the partition is suppressed, not empty, when `scan.truncated` says the scan was cut short.
 - API obligations:
-  - Every declared `CON-API-*` must be referenced at least once from `tests/api/**`.
+  - Every declared `CON-API-*` must be referenced at least once from `<testsDir>/api/**`.
   - Use `QFAI:CON-API-XXXX` annotations.
   - **Deferral.** `/qfai-sdd` authors contracts in Phase 0 (Contracts-first) and
     slices them in Phase 2, so a contract legitimately exists before its slice
@@ -358,20 +357,20 @@ its TC moved to `L4`/`L5` is rejected the same way an early one in
       under `deferred.conApi`, so an empty `missing.conApi` can be told apart
       from a project where every contract is still planned.
 - Forbidden references:
-  - `tests/api/**` must not include `QFAI:SPEC-XXXX:TC-YYYY` **for a TC whose
+  - `<testsDir>/api/**` must not include `QFAI:SPEC-XXXX:TC-YYYY` **for a TC whose
     declared `Level` is not L4/API**. A TC that declares an API-level
-    obligation belongs in `tests/api/**`, and its annotation there counts as
+    obligation belongs in `<testsDir>/api/**`, and its annotation there counts as
     coverage. The rule exists to stop obligations drifting into the wrong
     layer, not to make the correct layer unusable.
-  - `tests/e2e/**` must not include `QFAI:SPEC-XXXX:TC-YYYY` **for a TC whose
+  - `<testsDir>/e2e/**` must not include `QFAI:SPEC-XXXX:TC-YYYY` **for a TC whose
     declared `Level` is not L5/E2E**. Same reason as above: the routing rule
     and the forbidden rule must agree, or the layer the routing selects
     becomes unusable.
-  - `tests/integration/**` must not include `QFAI:SPEC-XXXX:TC-YYYY` **for a TC
+  - `<testsDir>/integration/**` must not include `QFAI:SPEC-XXXX:TC-YYYY` **for a TC
     whose declared `Level` is not L3/Integration** (`QFAI-ATDD-123`). The rule
     is symmetric so "exactly one directory" holds in both directions: an
     annotation left behind here after the TC moved to L4/L5 is as wrong as one
-    filed early into `tests/api/**`.
+    filed early into `<testsDir>/api/**`.
 - Unknown references (`US/TC/CON-API` not declared) are errors.
 - A `TC-*` annotation outside the directory its `Level` routes to is a
   misplacement, whichever directory it lands in. **This applies to L3-L5 only.**
@@ -379,7 +378,7 @@ its TC moved to `L4`/`L5` is rejected the same way an early one in
   an annotation for one is neither required nor misplaced, in
   `tests/unit/**`, `tests/component/**` or anywhere else.
 - AC annotations are not required in code; AC coverage is treated as indirect through TC coverage.
-- `QFAI:CON-API-*` in `tests/e2e/**` is not forbidden, but contract guarantee belongs to API tests.
+- `QFAI:CON-API-*` in `<testsDir>/e2e/**` is not forbidden, but contract guarantee belongs to API tests.
 
 ## Test-file granularity
 
@@ -472,10 +471,9 @@ Treat these as review signals in the same class as volume floors — worth a fin
 - a very low `test_` functions per file ratio in a module that carries many obligations
 - a single selector whose recorded runtime grows monotonically across RED rounds
 
-## Test stub detection (QFAI-TEST-001 / QFAI-TEST-002)
+## Test stub detection (QFAI-TEST-001 / -002 / -003)
 
-`QFAI-TEST-001` (error) reports the silent-placeholder construct of each
-supported stack:
+`QFAI-TEST-001` (error) reports the silent-placeholder construct of each supported stack:
 
 | Extensions           | Construct                                                           |
 | -------------------- | ------------------------------------------------------------------- |
@@ -487,6 +485,14 @@ supported stack:
 | `.rb`                | a line starting `skip` / `pending`                                  |
 | `.cs`                | `[Ignore` / `Skip = "`                                              |
 
+`QFAI-TEST-003` (warning) is the JS/TS `.skip` family — `it.skip(` / `test.skip(` /
+`describe.skip(`, chained `.each` spellings included. It is its own rule, not a graded-down
+`QFAI-TEST-001`: a waiver is judged against the highest severity its rule produced in the run,
+so sharing one code would let a single `.todo` promote the pair to `error` and take the
+per-path waiver in `.qfai/waivers.yml` away from every `.skip`. The fix differs too — a `.skip`
+keeps its body (it is what `npx qfai atdd scaffold` emits for a skeleton awaiting
+implementation), so drop the modifier rather than delete the test.
+
 `QFAI-TEST-002` (info) names any extension the scan opened that has no dialect.
 Without it a clean run on an unsupported stack is indistinguishable from a
 checked one — the detector used to be JS-only while file selection was

package/assets/init/.qfai/assistant/catalog/worklog-entry.schema.md

@@ -3,9 +3,10 @@
 - Contract scope: frontmatter and body schema for `.qfai/steering/*.md` entries
 - Owners: the validate stage (schema enforcement), the implement stage (primary writer) and the Reviewer-Gate stage (consumer)
 - Used-by: All implementation/review-phase skills, `npx qfai validate`, Reviewer subagents
-- SSOT modules:
-  - `packages/qfai/src/core/worklog/parseEntry.ts` (pure parser: `string → Result<Entry, SchemaError>`)
-  - `packages/qfai/src/core/worklog/validateLinks.ts` (link-integrity check)
+- SSOT modules (shipped inside the QFAI package, run by `npx qfai validate`):
+  - the work-log entry parser (`string → Result<Entry, SchemaError>`)
+  - the work-log link-integrity check
+- The field checks, enums and required headings are compiled into the CLI, not read from this file: this document is their reference, so editing it does not change what `validate` accepts. Report a divergence as a QFAI bug instead of customizing the schema here.
 
 ## Storage model
 

package/assets/init/.qfai/assistant/constitution/agent-selection.md

@@ -15,9 +15,15 @@ version: 2.0.0
 
 # エージェント選択ガイド（QFAI Toolkit）
 
-QFAI のサブエージェントは、**agent-catalog + agent-routing + review-profiles** を SSOT とする。  
+QFAI のサブエージェントの**選定**は、**agent-catalog + agent-routing + review-profiles** を SSOT とする。  
 選定は「成果物の種類」と「phase の役割」で行い、skill 本文の直感では決めない。
 
+ただしエージェントの**本文（mission / responsibilities / stop conditions 等）**の SSOT は
+`.qfai/assistant/agents/<id>.md` である。`agent-catalog.yml` の `developer_instructions`
+はそこから導出される派生コピーであり、そこに新しい内容を書き起こさない。本文を変更するときは
+markdown 側を編集し、その `## Mission` 見出し以降をそのままブロックへ写して一致させる
+（乖離もブロックの欠落も `QFAI-AGENT-014` が警告する）。
+
 ## 中核原則
 
 - 司令塔は常に `orchestrator`

package/assets/init/.qfai/assistant/constitution/communication.md

@@ -35,7 +35,7 @@ When an agent needs to ask the user a question, the following rules apply (see a
 
 All SKILL.md files MUST include a
 `## User Questions (AskUserQuestion Protocol)` section with MUST-level wording.
-SSOT: `packages/qfai/assets/init/.qfai/assistant/skills/*/SKILL.md`.
+SSOT: the skill templates shipped inside the QFAI package.
 Deployed copy (updated by `npx qfai init`): `.qfai/assistant/skills/*/SKILL.md`.
 
 ## Error handling

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

@@ -160,10 +160,16 @@ This article survives context compaction because `constitution.md` is a P1 reloa
 
 All temporary files, scratch scripts, and intermediate build artifacts **MUST** be placed under the repository‑root `tmp/` directory.
 
+Scope: this article is about files written **into the working tree** — scratch
+scripts, intermediate build artifacts, downloaded fixtures, notes. A sandbox a
+test creates with `mkdtemp` under the OS temporary directory is **not** covered:
+it lives outside the repository, so it cannot put a file in any of the
+directories Rule 1 protects, and the test that created it removes it.
+
 Rules:
 
 1. **Never** create temporary files in the repository root, `src/`, `.qfai/specs/`, or any other production/artifact directory.
 2. Use `tmp/` (repository root) as the sole staging area. Create subdirectories as needed (e.g., `tmp/glossary/`, `tmp/build/`).
 3. `tmp/` MUST be listed in `.gitignore` so temporary files are never committed.
 4. Clean up `tmp/` contents when the task that created them is complete.
-5. If a temporary file is found outside `tmp/`, treat it as a defect and move or delete it immediately.
+5. If a temporary file is found outside `tmp/` **in the working tree**, treat it as a defect and move or delete it immediately. A test's `mkdtemp` sandbox is not one — see Scope above.

package/assets/init/.qfai/assistant/constitution/drift-protocol.md

@@ -13,7 +13,12 @@ Upstream artifacts include, at minimum:
 - `10_Plan.md` and other owner-phase planning outputs
 - Legacy spec-pack SSOT files when present: `spec.md`, `delta.md`, `plan.md`, `traceability-matrix.md`, `scenario.feature`, `case-catalogue.md`, and numbered pack files (for example `01_Spec.md`..`18_delta.md`)
 - contracts and schema decisions owned by earlier phases
-- outputs of discussion/sdd/review stages
+- outputs of the sdd and review stages. A **discussion pack is NOT upstream
+  SSOT** — it is non-normative discovery material, and `.qfai/specs/**` is the
+  behaviour and design SSOT it feeds. A defect found in one downstream is fixed
+  in the SDD-owned artifact, the discrepancy recorded in delta/evidence. This
+  reclassifies ONLY the pack: genuine upstream is still repaired upstream-first.
+
 - **test or production artifacts another spec's completed implement run
   certifies** — a file named in another `tdd/test-list.md`'s `Test file` column
   on a `done` row. Changing one is not forbidden (the codebase is not
@@ -71,7 +76,7 @@ Any exception beyond this list requires explicit user approval.
 `/qfai-implement` must write `tdd/test-list.md` after every phase transition,
 and the file lives inside `.qfai/specs/**`. The protocol never classified it in
 either direction, but `#core-rule`'s list is explicitly open-ended ("at minimum")
-and sweeps in "outputs of discussion/sdd/review stages" — and the ledger's schema
+and sweeps in "outputs of the sdd and review stages" — and the ledger's schema
 is documented in `skills/qfai-sdd/references/spec-traceability-rules.md`, an
 SDD-stage reference. On the natural reading the ledger _is_ an sdd-stage output,
 so "Downstream skills must not patch upstream SSOT directly" applied to it.
@@ -332,17 +337,36 @@ is a defect.
 - Every reviewer finding declares a `Traces to:` value. See
   `shared-skill-delegation-baseline.md#finding-provenance-must` for the response schema. Legal
   values:
-  - an upstream obligation (`AC-*`, `BR-*`, `TC-*`, `CON-*`) or a named constitution/catalog rule;
+  - an upstream obligation (`AC-*`, `BR-*`, `TC-*`, `CON-*`) or a named constitution/catalog rule
+    **that governs the product's behaviour**;
   - `defect:correctness`, `defect:security`, or `defect:code-quality` — the deliverable-defect
     classes above, each of which MUST carry the concrete evidence in the changed artifacts that
     demonstrates it;
+  - `record:<CODE>` — a defect in the run's own record rather than in the product;
   - `none` — reviewer-originated scope.
-- The first two are **blocking** and gate `done`.
+- The first two are **blocking** and gate `done`. `record:*` and `none` are not.
+- `Traces to: record:<CODE>` is a record defect: the ledger, a round block, an evidence anchor or
+  the provenance prose is wrong while the product is not. It MUST be recorded as `advisory`, MUST
+  NOT be `blocking`, and settles in the spec's record-defect queue (`#the-record-defect-queue`)
+  rather than by re-running the row. `record:unchecked` is a bug report against `validateTddList`,
+  not against the item — a record rule worth a round is worth a validator code.
+- **A record that misrepresents the run is not a record defect.** Evidence copied from a previous
+  round or a sibling row, an evidence anchor resolving to a run other than the one it names, and a
+  false `Authored/edited under review` attestation do not merely mis-state the work — they claim
+  work that was not done, or independence the reviewer did not have. `agents/qa-gatekeeper.md`
+  rejects the first two outright and
+  `shared-skill-delegation-baseline.md#reviewer-response-template` forbids a `PASS` on the third,
+  so classifying them `record:*` would let an advisory-only review return `PASS` and release
+  `done` over the very evidence the gate exists to reject. They stay **blocking** as
+  `defect:code-quality` and MUST NOT be filed as `record:*`. `record:*` covers a record that is
+  honestly produced and merely wrong — a tier missing from an Evidence cell, a `Satisfied-by`
+  naming the wrong sibling row, an unlabelled round block.
 - `Traces to: none` is reviewer-originated scope. It is **drift**, and it is **not satisfiable
   downstream**: encoding it as production code plus a hard test assertion is the same violation as
   patching upstream SSOT, inverted. It MUST be recorded as `advisory`, MUST NOT be `blocking`, and
   is routed to the Change Request / Open Question path — never to the implementer.
-- Routing an advisory finding:
+- Routing a `none` advisory (a `record:*` advisory takes `#the-record-defect-queue` instead — the
+  Change Request path adjudicates product obligations and cannot repair a record):
   1. The reviewer records it in its response under `Advisory / Change Request proposals`, with
      enough context for the owner phase to adjudicate. The reviewer does **not** write it into
      `08_Open-questions.md`: that file is upstream SSOT (see `#core-rule`) and is owned by
@@ -363,10 +387,94 @@ is a defect.
   Completing against an obligation that is known to be under revision would ship a knowingly
   inconsistent SSOT.
 
+### The record-defect queue
+
+Making `record:*` advisory removes the round it used to force. It does not remove the defect, so
+the class is only honest if the defect lands somewhere with an owner and is consumed. That place is
+one queue per spec, and it is defined by a destination, an owner, an entry shape and a drain.
+
+- **Where.** A `## Record defects` section in the evidence file the reviewing stage's **own
+  completion contract** names. For a `/qfai-implement` review that is
+  `.qfai/evidence/implement-<spec-id>.md` when that file exists, otherwise
+  `.qfai/evidence/atdd-<spec-id>.md` — the same file rule the spec-level checkpoint boundary uses,
+  so a spec never has this queue in two places. **Do not derive the path from a
+  `<stage>-<spec-id>.md` pattern.** Each stage names its own evidence file and not every one of
+  them is spec-scoped — `/qfai-configure` writes `.qfai/evidence/configure-<run-id>.md`, one per
+  run, and has no `configure-<spec-id>.md` at all — so the pattern named files no stage creates.
+  Never `08_Open-questions.md`: that file is upstream SSOT owned by `/qfai-sdd` (see
+  `#core-rule`), and a record defect is not a product obligation.
+- **The class needs a drain, so a stage whose completion contract has none does not use it.** Every
+  stage sharing `shared-skill-delegation-baseline.md` reads the provenance rules, but an entry is
+  only worth filing where something consumes it, and the queue above is defined as much by the
+  drain as by the destination. The test is textual and local: **that stage's own completion
+  conditions must require this queue drained before it declares completion.** `/qfai-implement`
+  states it (`skills/qfai-implement/SKILL.md#spec-completion-conditions`), and no other stage's
+  completion conditions mention the queue at all — so `/qfai-sdd`, `/qfai-atdd`, `/qfai-configure`,
+  `/qfai-verify`, `/qfai-discussion` and `/web-research` reviewers MUST NOT classify a finding
+  `record:*`; it keeps the class it would have had, blocking under the rule it names. A stage gains
+  the class by adding the drain to its completion conditions, never by being named here. A class
+  whose entries are written where nothing drains them is the round-dropped-and-defect-dropped
+  outcome this queue exists to prevent, and it is worse in the stages that never gained the queue
+  than the round ever was.
+- **Who.** The reviewer records the finding in its response as an advisory, as for any advisory.
+  The **orchestrator** that dispatched the review appends it to the queue when the round closes —
+  the same role that owns the ledger. A finding that stays in the reviewer response and never
+  reaches the queue is an unrouted advisory, which the review gate already forbids.
+- **Entry.** One line per defect: the `<CODE>`, the row or artifact it is against, what the record
+  says against what the run actually did, and the round it came from. That is what makes it
+  repairable later by someone who did not watch the round.
+- **Drain, at the spec boundary.** Before spec-level completion is declared, every open entry is
+  **repaired in place**: the record is corrected to what the run did, with no row re-run and no
+  status change. Repair is the only close. When the rule the entry names is one no validator
+  checks, the entry **also** produces a validator bug report per the `record:unchecked` ratchet
+  above — that report tracks the missing check and does not stand in for the repair. Closing an
+  entry on the report alone leaves the wrong record exactly as wrong as it was, with the round
+  that found it already spent: a missing tier stays missing, and the item stays complete. The two
+  are different obligations against different backlogs. Completion is not declared while an entry
+  is open. This gates the **spec** boundary only: a `record:*` finding still never holds an
+  individual row out of `done`, which is the whole point of the class.
+- **When the record cannot be repaired honestly.** Repair means writing what the run actually did,
+  which needs the round's artifacts to still say what that was. Where they do not — nothing
+  reconciles the entry with any run — the finding was never a record defect: what is missing is
+  not a correct record of the work but any evidence the work happened, which is the integrity case
+  above. Reclassify it as `defect:code-quality`, blocking, and take the ordinary REVISE path.
+  There is no third exit: an entry closes on a corrected record or on a blocking finding.
+- **Re-attest a repair in a pack of its own; never re-run it, and never edit a sealed one.** A
+  defect inside a `Satisfied-by`, a round block or any other phase-authored field sits inside the
+  exact bytes a reviewer's `Audited evidence hash` covers, and the completion gate recomputes that
+  hash — so repairing in place makes a correct PASS read as stale, and skipping the recomputation
+  would accept evidence nobody read. Repair the record, then have a reviewer **of the role that
+  issued the verdict** re-read the repaired entry and emit a **record re-attestation**: the
+  `TDD-ID`, the same `Reviewed revision`, the same `Result`, a recomputed `Audited evidence hash`,
+  and the queue entry's `<CODE>`.
+- **The re-attestation is a new review pack, and the pack it supersedes is left untouched.** A
+  verdict lives in a `review-<timestamp>/` pack fixed by a `Review pack seal` the completion gate
+  recomputes, so replacing that verdict's `Audited evidence hash` line where it is stored breaks
+  the seal by construction, and replacing only the evidence file's copy leaves the sealed reviewer
+  response carrying a hash nothing agrees with. Write the re-attestation as its own
+  `review-<timestamp>/` pack, sealed by the same procedure. The superseded verdict keeps the hash
+  it recorded — it was correct over the bytes it read — and its pack keeps recomputing. The
+  evidence entry records `Record re-attestation` beside the verdict it supersedes, with its own
+  `Record re-attestation pack` and `Record re-attestation pack seal`; the completion gate
+  recomputes the superseding hash and both seals, which is what makes the re-attestation an
+  artifact a validator can see rather than an untraceable edit. No code runs, no row changes
+  status, and it spends no round — it opens none, so it is not a `Round N:` pack. The revision a
+  verdict names excludes `.qfai/evidence/**`, so by construction nothing outside the record moved.
+  **A repair that would move the revision is not a record repair**: it is a change to the
+  deliverable and takes the ordinary path. A repaired entry whose verdict carries no
+  re-attestation is still an open entry.
+
+An unconsumed queue would make the class worse than what it replaced: the round is gone and the
+defect is gone with it. The drain is what pays for dropping the round.
+
 ### Which evidence is committed
 
-- **Regenerable** — stage evidence (`.qfai/evidence/<stage>-<spec-id>.md`),
-  run logs, reports. Reproducible by rerunning the owner skill; not committed.
+- **Durable per-item TDD evidence** — `.qfai/evidence/implement-<spec-id>.md`
+  and `.qfai/evidence/atdd-<spec-id>.md`. Ledger `Evidence` cells point to
+  anchors in these files, and validation resolves those anchors on a fresh
+  clone, so the managed `.gitignore` block re-includes and commits them.
+- **Regenerable** — other stage logs, run logs, and reports. Reproducible by
+  rerunning the owner skill; not committed.
 - **Governance record** — Change Requests (`.qfai/decisions/CR-*.md`) and
   durable decision records (`.qfai/evidence/decisions/*.json`). They carry
   user approval and cannot be regenerated, so they are committed. The managed
@@ -380,8 +488,8 @@ is a defect.
   — diffs the branch against `baseBranch` and emits `QFAI-DRIFT-001` (`error`)
   for every changed file under `paths.contractsDir`, under `_policies/`, or
   matching a protected spec-pack filename. A Change Request at `Status:
-approved` that **names the changed path** silences it; an `open` CR does not,
-  because an open CR authorises nothing. The check does not run in the `sdd`
+approved` whose **`## Impact scope` names the changed path** silences it — not
+  a path named elsewhere in it, not a contract ID, and never an `open` CR. The check does not run in the `sdd`
   profile: `/qfai-sdd` owns these files.
 - Downstream reviewers must not originate binding obligations that upstream SSOT does not contain.
 - If approval is not available, stay in STOP state **for that CR's blocked set**