qfai 1.10.0 → 1.10.2

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,10 @@
 
 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,27 +35,30 @@ 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.
 
 ## 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.
@@ -73,7 +80,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,25 +88,25 @@ 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
 
 - 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)
 
@@ -137,8 +144,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 +180,40 @@ 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 `<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
+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 `<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
@@ -185,22 +232,29 @@ 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.
-
-## TestKind resolution (single source)
-
-- `tests/unit/**` -> Unit
-- `tests/component/**` -> Component
-- `tests/e2e/**` -> E2E
-- `tests/api/**` -> API
-- `tests/integration/**` -> Integration
+- **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.
+
+## Directory → AtddTestKind (code-side, derived from the crosswalk)
+
+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)
 
@@ -219,7 +273,7 @@ routes by obligation ID: `US-*` is answered from `tests/e2e/**`
 
 - 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
@@ -233,40 +287,59 @@ routes by obligation ID: `US-*` is answered from `tests/e2e/**`
   - 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/**`. 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.
-  - 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.
-
-- 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/**`.
+  - 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 `<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
+  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 `<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
+    `<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
@@ -284,26 +357,28 @@ routes by obligation ID: `US-*` is answered from `tests/e2e/**`
       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 — 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.
+- `QFAI:CON-API-*` in `<testsDir>/e2e/**` is not forbidden, but contract guarantee belongs to API tests.
 
 ## Test-file granularity
 
@@ -396,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                                                           |
 | -------------------- | ------------------------------------------------------------------- |
@@ -411,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

@@ -1,7 +1,7 @@
 # QFAI Constitution (Non‑Negotiable)
 
 This document defines **non‑negotiable operating rules** for QFAI agents and subagents.
-It is inspired by proven “constitution / articles / guardrails” patterns in existing SDD toolchains, but tailored to QFAI’s minimal workflow.
+It is inspired by proven “constitution / articles / guardrails” patterns in existing SDD toolchains, but adapted to QFAI’s minimal workflow.
 
 ---
 
@@ -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.