qfai 1.10.0 → 1.10.1

package/README.md

@@ -121,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)
 
@@ -145,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>/`.

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

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

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

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

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

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

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

@@ -31,6 +31,17 @@ tools: [Read, Glob, Grep, Bash]
 - .github/instructions/principles.instructions.md
 - Diff of changed files
 - `.qfai/contracts/api/**` and `.qfai/contracts/db/**`
+- `.qfai/specs/<spec-id>/tdd/test-list.md` — the ledger, for the row under review
+- The per-item evidence file that row's `Layer` owns: `.qfai/evidence/implement-<spec-id>.md`,
+  or `.qfai/evidence/atdd-<spec-id>.md` for an `E2E` / `API` / `Integration` row
+
+**The last two are what the `Audited evidence hash` is computed over.** This
+role records that hash itself, over the row's phase-authored fields — and those
+live in 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
 

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

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

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

@@ -58,7 +58,9 @@ At both stages: when business rules (BR-\*) exist, verify each BR has at least o
 - Coverage plan and layer ownership
 - Test-case quality and traceability findings
 - **Coverage Depth Matrix** (per spec, using the template in the depth checklist reference).
-  Destination: `.qfai/evidence/atdd-<spec-id>.md` from the ATDD stage onward. During SDD there is
+  Destination: `.qfai/evidence/coverage-depth-<spec-id>.md` from the ATDD stage onward — its own
+  file, because 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

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

@@ -0,0 +1,60 @@
+# Test layers to CI lanes
+
+A crosswalk between the test layers in [`test-layers.md`](./test-layers.md) and the CI lanes
+the shipped workflows run. It exists so that "which job runs my L3 tests" has one answer a
+reader can find, instead of being rediscovered from a workflow file each time.
+
+**The layer policy loader does not read this file.** (Written without a hyphen on purpose: the
+loader extracts anything matching `layer-<word>` from the file it parses, and while it does not
+parse this one, a catalog-directory file carrying such a token is a hazard waiting for the day
+someone widens the loader to scan the directory.) It resolves `catalog/test-layers.md` by
+exact path and reads nothing else in this directory, so nothing written here can widen or
+narrow the layer vocabulary. That is deliberate: this document is a map, and a map that could
+change the territory would be a second source of truth for something that already has one. If
+you need to change what layers exist, change `test-layers.md` — this file follows.
+
+## The mapping
+
+| Layer          | What it exercises                             | Shipped CI lane |
+| -------------- | --------------------------------------------- | --------------- |
+| L1 Unit        | one module, no I/O                            | `unit`          |
+| L2 Component   | one component and its immediate collaborators | `component`     |
+| L3 Integration | several modules across a real boundary        | `integration`   |
+| L4 API         | a running interface, contract-first           | `api`           |
+| L5 E2E         | the product as a user reaches it              | `e2e`           |
+
+Two lanes in the shipped workflow are not layers and have no row above:
+
+- **`detection`** decides which of the lanes above need to run for a given change, and
+  publishes that decision as job outputs. It is infrastructure, not a test level.
+- **`verdict`** aggregates the lanes into the single status a branch-protection rule can name.
+  It runs unconditionally so that a run where every lane was skipped is still distinguishable
+  from a run where nothing was verified.
+
+## Lane names are a project's choice
+
+The names in the third column are the ones the shipped workflow uses. They are not a contract:
+a project that calls its integration lane `service-tests` is not violating anything, and this
+table is not a rename list. What matters is that each layer a project uses has some lane that
+runs it, and that the lane's name stays put once branch protection refers to it — a check name
+is a repository setting, and renaming one silently makes a required check unsatisfiable.
+
+## Per-level routing is not enforced
+
+`test-layers.md` marks per-level annotation routing as a target state and says plainly: not
+enforced, do not follow yet. This document does not change that and does not activate it. The
+live traceability gate reads one directory for annotations, and it is the gate — not this
+table — that decides where an annotation counts.
+
+So: read this file to find out which lane runs a layer. Do not read it as instructions about
+where anything belongs in the tree. That question is settled by the gate's own scope, and by
+`test-layers.md` for the vocabulary.
+
+## Keeping this file honest
+
+- Every layer code here also appears in `test-layers.md`'s crosswalk. If you add a layer there
+  and not here, this table is incomplete; if you add one here and not there, you have invented
+  a layer nothing enforces.
+- The lane column describes the shipped workflow. If the shipped workflow's job set changes,
+  this table is stale, and stale is worse than absent for a document whose only job is to save
+  someone a lookup.

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

@@ -2,6 +2,11 @@
 
 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.
+
 ## Layer vocabulary crosswalk (normative)
 
 qfai spells the same layer four ways across shipped artifacts. This table is
@@ -31,17 +36,21 @@ Rules:
 - L1 and L2 have no mandated directory: unit and component tests live wherever
   the project's own convention puts them. Only L3-L5 are directory-pinned, and
   only those directories are scanned by the ATDD traceability rules.
-- **A `TC-*` row's `Level` is L1-L3.** The ATDD annotation hard gate routes an
-  obligation by its ID, not by its `Level`: `US-*` is answered from
-  `<testsDir>/e2e/**` (`QFAI-ATDD-111`), `TC-*` from
-  `<testsDir>/integration/**` (`QFAI-ATDD-112`) and `CON-API-*` from
-  `<testsDir>/api/**` (`QFAI-ATDD-113`) and `CON-DB-*` from
-  `<testsDir>/integration/**` (`QFAI-ATDD-115`), while a `TC-*` reference inside
-  `<testsDir>/api/**` or `<testsDir>/e2e/**` is rejected outright
-  (`QFAI-ATDD-121` / `QFAI-ATDD-122`). 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 as a `TC-*` row no test directory can carry.
+- **A `TC-*` row's `Level` is L1-L3.** Of those, only L3 owes an ATDD
+  annotation: L1 and L2 have no mandated directory, so `QFAI-ATDD-112` does not
+  apply to them and `QFAI-ATDD-117` (`info`) names them instead. Their gate is
+  `tdd/test-list.md` / `TDDLIST_TC_NOT_COVERED`, under `/qfai-implement`.
+  `US-*` is answered from `<testsDir>/e2e/**` (`QFAI-ATDD-111`), `CON-API-*`
+  from `<testsDir>/api/**` (`QFAI-ATDD-113`) and `CON-DB-*` from
+  `<testsDir>/integration/**` (`QFAI-ATDD-115`) — those three are fixed by the
+  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.
 - 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.
@@ -73,7 +82,7 @@ writer targets a declared layer instead.
 - Scope: pure decision logic — a single module's inputs and return values, with
   no port collaboration and no real infrastructure.
 - Goal: verify `TC-*` obligations whose oracle observes inputs and outputs only.
-- Location rule: `tests/unit/**`.
+- Convention: `tests/unit/**`. L1 has no mandated directory and owes no ATDD annotation — see the crosswalk and "Unit and Component owe no ATDD annotation".
 
 ### L2 Component
 
@@ -81,7 +90,7 @@ writer targets a declared layer instead.
   with no real infrastructure.
 - Goal: verify `TC-*` obligations whose oracle observes the interaction with a
   port rather than infrastructure state.
-- Location rule: `tests/component/**`.
+- Convention: `tests/component/**`. L2 has no mandated directory and owes no ATDD annotation — see the crosswalk and "Unit and Component owe no ATDD annotation".
 
 ### L3 Integration
 
@@ -137,8 +146,23 @@ falsifying-oracle rule:
 observable at two layers, it is two obligations: write one TC per oracle and
 give each its own `Level`.
 
-- A multi-valued `Level` cell (`L3/L5`) is **illegal**. Nothing consumes it and
-  no validator can route it.
+- A multi-valued `Level` cell (`L3/L5`, `L1/L2`, `L1, L3`) is **illegal**. It
+  matches no entry in the crosswalk, so no rule can read a layer out of it.
+- **What a reader does with one: split the row.** One TC per oracle, each with
+  its own single `Level`. Nothing else is a fix — in particular, do not record
+  a normalization that "drops one half": no tool performs one, and a note
+  saying an `L3/L5` row "normalizes to `L3`" is a claim about a value that only
+  `06_Test-Cases.md` can make.
+- **What the validators do with one, until it is split.** They neither guess
+  nor let it through:
+  - `QFAI-ATDD-112` routes the TC to the same place a TC with no declared
+    `Level` goes — `<testsDir>/integration/**` — and keeps the obligation.
+    Unreadable is deliberately not "excused": if a cell qfai cannot read
+    discharged the obligation, `L1/L2` would be a one-keystroke way to delete
+    any TC from the gate. That default is where the obligation is _reported_,
+    not where the obligation _belongs_.
+  - `TDDLIST_UNKNOWN_LEVEL` (`warning`) names the cell, and the TC stays a
+    coverage target, so `tdd/test-list.md` still owes it a row.
 - If splitting is genuinely impossible, escalate through the Drift Protocol
   rather than inventing a combined value.
 
@@ -158,15 +182,43 @@ L4" applies only when the service-boundary values are themselves what the
 parent BR owns. Inverting this is what collapses a designed pyramid into an
 all-integration suite.
 
-### Annotation routing is by ID type, not by `Level`
-
-The derived `Level` records which oracle owns the obligation. It does **not**
-move the traceability annotation. The [ATDD annotation hard gate](#atdd-annotation-hard-gate)
-routes by obligation ID: `US-*` is answered from `tests/e2e/**`
-(`QFAI-ATDD-111`), `TC-*` from `tests/integration/**` (`QFAI-ATDD-112`), and
-`CON-API-*` from `tests/api/**` (`QFAI-ATDD-113`); a `TC-*` reference inside
-`tests/api/**` or `tests/e2e/**` is rejected outright (`QFAI-ATDD-121` /
-`QFAI-ATDD-122`). Two consequences bind every `TC-*` row:
+### 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) |
+
+**(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
+a misfiled row is reported once, by the rule that names the real cause, instead
+of twice as "uncovered in integration" and "forbidden in api".
+
+**(note2)** A `Level` the crosswalk does not list — a typo, a project's own
+word, or the illegal multi-valued cell — falls to the same default as an
+undeclared one, and keeps its obligation. The default is the conservative
+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:
 
 - **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
@@ -185,14 +237,15 @@ routes by obligation ID: `US-*` is answered from `tests/e2e/**`
   parent BR keeps a spec-side obligation, split the row instead: keep a `TC-*`
   for the part the BR owns — by step 2 that part derives to L1–L3 — and re-file
   only the boundary assertion as `CON-API-*` / `US-*`.
-- **An L1/L2 `Level` does not relax `QFAI-ATDD-112`, and the gate does not
-  change the `Level`.** The two are independent: the `Level` records what the
-  oracle observes and is derived before any test exists, while the
-  `QFAI:SPEC-XXXX:TC-YYYY` annotation is still owed to `tests/integration/**`.
-  Never rewrite a derived L1/L2 to L3 because no integration trace exists yet —
-  that would make the recorded oracle depend on implementation order and hide
-  the unit/component work `/qfai-implement` selects. The missing annotation is
-  an open ATDD obligation to satisfy, not evidence that the `Level` was wrong.
+- **An L1/L2 `Level` carries no `QFAI-ATDD-112` obligation, and the gate does
+  not change the `Level`.** The two are independent: the `Level` records what
+  the oracle observes and is derived before any test exists, while
+  `QFAI-ATDD-112` asks only about the layers ATDD owns. Never rewrite a derived
+  L1/L2 to L3 to make a gate quieter — that would make the recorded oracle
+  depend on implementation order and hide the unit/component work
+  `/qfai-implement` selects. An L1/L2 row's obligation is discharged through
+  `tdd/test-list.md` and `TDDLIST_TC_NOT_COVERED`, not through an annotation in
+  a directory ATDD scans.
 
 ## TestKind resolution (single source)
 
@@ -241,11 +294,21 @@ routes by obligation ID: `US-*` is answered from `tests/e2e/**`
   - 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/**`. This is what `QFAI-ATDD-112`
-    checks. - Use `QFAI:SPEC-XXXX:TC-YYYY` annotations.
-  - `tests/api/**` and `tests/e2e/**` must not carry `TC-*` annotations
-    (`QFAI-ATDD-121` / `QFAI-ATDD-122`), so an L4 obligation is discharged as a
-    `CON-API-*` reference, never as a `TC-*` one.
+    `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.
+  - 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
@@ -255,16 +318,27 @@ routes by obligation ID: `US-*` is answered from `tests/e2e/**`
     current slice defers with a `-- x-qfai-status: planned` comment line,
     reported at `info` by `QFAI-ATDD-116` so the deferral stays visible.
 
-- Per-level routing (target state — **not enforced, do not follow yet**):
-  - The intended end state is one required location per declared `Level`:
-    L1 -> `tests/unit/**`, L2 -> `tests/component/**`,
-    L3 -> `tests/integration/**`. L4 stays `CON-API-*` in `tests/api/**` and
-    L5 stays `US-*` in `tests/e2e/**`.
-  - **This is not live.** `buildAtddTestGlobs` scans only
-    `tests/{e2e,api,integration}`, so an annotation placed in `tests/unit/**`
-    or `tests/component/**` is invisible to the scanner and `QFAI-ATDD-112`
-    still reports the TC as uncovered. Until the scanner and `QFAI-ATDD-112`
-    resolve per-TC, keep discharging every `TC-*` in `tests/integration/**`.
+- **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
+  in any directory, and an annotation for it inside a scanned directory is not
+  a violation either. `QFAI-ATDD-117` (`info`) names the excluded TCs on every
+  run so the exclusion is visible rather than silent.
+  - This is the only reading consistent with the rest of the package.
+    `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
+    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
+    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.
 - API obligations:
   - Every declared `CON-API-*` must be referenced at least once from `tests/api/**`.
   - Use `QFAI:CON-API-XXXX` annotations.
@@ -300,8 +374,10 @@ routes by obligation ID: `US-*` is answered from `tests/e2e/**`
     filed early into `tests/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 — including the two new
-  locations `tests/unit/**` and `tests/component/**`.
+  misplacement, whichever directory it lands in. **This applies to L3-L5 only.**
+  L1 and L2 route nowhere — they carry no ATDD annotation obligation at all — so
+  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.