qfai 1.9.2 → 1.10.0

package/assets/init/.qfai/assistant/skills/qfai-implement/references/change-request-reset.md

@@ -0,0 +1,93 @@
+# Approved Change Request reset (the only sanctioned backward transition)
+
+`tdd/test-list.md` has a forward-only lifecycle
+(`todo -> red -> green -> refactor -> done`) and skips `done` rows on
+re-execution. An approved upstream change can invalidate rows that already
+reached `green`, `refactor` or `done`, and the Change Request template
+(`.qfai/assistant/skills/qfai-sdd/templates/change-request.md`) instructs the
+approved actions to "reset the `tdd/test-list.md` rows this change
+invalidates". Without a stated exception that instruction is unperformable:
+the skill would either violate the forward-only rule or leave a `done` row
+holding an implementation result the approved change already invalidated.
+
+## The mandatory preflight
+
+The reset cannot be reached from the normal loop: `Required Process` starts by
+selecting the first `todo` row, and the skill exits with "nothing to do" when
+every row is `done` — exactly the state an approved reset is meant to reopen.
+So the sweep is a **preflight**, not an opportunistic step:
+
+1. On every run, before the ledger is read for any other purpose, enumerate
+   `.qfai/decisions/CR-*.md` and keep those in scope for the target spec.
+2. Apply every reset the approved ones authorise (conditions below).
+3. Only then judge the ledger. A run whose preflight reset rows must not report
+   "nothing to do", because the all-`done` state it would report is stale.
+
+A run with no in-scope approved CR does nothing here and proceeds unchanged.
+
+## The exception
+
+A `.qfai/decisions/CR-*.md` whose "Approved actions" name a downstream ledger
+sweep may reset the rows that change invalidates back to `todo`. Those rows are
+then re-executed rather than skipped.
+
+This is an operator-approved act, not a skill decision. It is legal only when
+all of the following hold:
+
+- the CR's `Status` is `approved`, with `Approved by` and `Approved at`
+  populated;
+- the CR's "Approved actions" section **enumerates the rows** — the `TDD-ID`s,
+  or a verifiable selection rule — so the reset scope is what the operator
+  approved and not what the skill later decided was invalidated. A row outside
+  that enumeration is not approved; widening the scope needs a new CR;
+- each reset row records that CR's ID in its `DR-ID` column — that column
+  carries both `DR-*` and `CR-*` references as a comma-separated list, and the
+  ID is **retained** as the row re-runs through `red` / `green` / `refactor` /
+  `done`, since clearing it on the next transition erases the only record of the
+  approved reopen; and
+- the reset is recorded in the CR's `Resolution` section (which rows, by
+  `TDD-ID`).
+
+## A retained `CR-*` is not an exception's `DR-*`
+
+A reset row that later hits an anomaly still owes a Decision Record. The
+retained `CR-*` records the approved reopen, not the anomaly, so it does not
+satisfy the `exception` requirement on its own: add the `DR-*` alongside it
+(`DR-NNNN, CR-YYYYMMDD-NNNN`). `TDDLIST_EXCEPTION_MISSING_DR` fires on an
+`exception` row whose `DR-ID` cell is empty **or holds `CR-*` references only**.
+
+## What stays prohibited
+
+- Any backward transition not covered by an approved CR, including the named
+  `green -> red` case. The error text is unchanged:
+  `"Backward transition prohibited: green -> red"`.
+- Resetting rows before approval. A CR at `Status: open` authorises nothing.
+- Resetting rows the CR's "Approved actions" did not name.
+
+## When an in-scope CR counts as resolved
+
+The spec completion gate covers only the `.qfai/decisions/CR-*.md` **in scope for
+this spec**: `Impact scope` names this spec or a shared policy it depends on, or
+this spec's artifacts reference it. A CR confined to another spec never blocks
+this one.
+
+An in-scope CR is **resolved** only when every one of these holds. A CR failing
+any single one — a half-filled record included — is **unresolved** and blocks
+completion:
+
+- `Status` is `approved`, `rejected` or `superseded` (never `open`);
+- `Approved by` / `Approved at` are populated, plus `Approved option` when
+  `Status` is `approved` and `Superseded by` when it is `superseded`;
+- `Resolution` records what was actually done; and
+- when `Status` is `approved`, `Applied at` is populated — approval alone does
+  not release the gate. It is set only after the owner-skill rerun in "Approved
+  actions" completed and upstream artifacts are updated, which is when
+  `constitution/drift-protocol.md` resumes downstream work.
+
+## Ordering against the drift protocol
+
+`.qfai/assistant/constitution/drift-protocol.md` resumes downstream work only
+after the owner skill has been rerun and the upstream artifacts are updated.
+The ledger sweep is downstream work, so it follows the owner-skill rerun; the
+CR's `Applied at` is set once both are done. An `approved` CR without
+`Applied at` is still unresolved and blocks spec completion.

package/assets/init/.qfai/assistant/skills/qfai-implement/references/checkpoint-verification.md

@@ -0,0 +1,106 @@
+# Checkpoint Verification
+
+"Checkpoint verification" is the whole-repository regression check run at a checkpoint boundary. It
+is what item 12 of the 12-point gate refers to and the only thing it refers to.
+
+## Checkpoint boundary
+
+A checkpoint boundary is reached in exactly two places:
+
+- **Per item** — after all routed blocking reviewers have returned PASS for the item and before it
+  transitions `refactor` -> `done`. Every item has exactly one.
+- **Per spec** — after the last item in `test-list.md` reaches `done` or a valid `exception`, before
+  declaring spec-level completion.
+
+No other point is a checkpoint boundary. There is no "every N items" rule.
+
+## Verification command set (per item)
+
+Run all of the following from the repository root, in order. Substitute the project's own runner for
+the placeholders; record the literal commands actually executed in evidence.
+
+1. The item's own test — the ledger's `Test file` **plus** the runner's test-name option applied to
+   the ledger's `Selector`. Two runner-specific decisions, and both must be made from the ledger row:
+
+   **a. The name option.** The `Selector` is a test NAME, and every common runner takes a name
+   through a flag, not a positional argument: a positional is a file filter. Vitest and Jest use
+   `-t`, pytest uses `-k`, `go test` uses `-run`. Passing the selector positionally
+   (`<test runner> '<Selector>'`) exits 1 with "No test files found", so the checkpoint would fail
+   on every item and none could leave `refactor`.
+
+   **b. The unit of selection.** What goes in front of the name option is whatever the runner
+   selects by, which is not always a file:
+   - **File-selecting runners** (vitest, jest, pytest) take the `Test file` itself:
+
+     ```bash
+     <test runner> <Test file> -t '<Selector>'
+     ```
+
+   - **Package-selecting runners** (`go test`) take a package. `go help test` documents the usage
+     as `go test [build/test flags] [packages] [build/test flags & test binary flags]`, and it
+     compiles the package's sources together with the matching `*_test.go` files. Handing it a lone
+     file switches it into file mode and drops the rest of the package from the build, so the item's
+     test normally fails on undefined symbols. Derive the package from the `Test file`'s directory:
+
+     ```bash
+     go test ./<dir of Test file> -run '<Selector>'
+     ```
+
+   Record the literal command actually run either way. If a project's runner selects by something
+   else again, derive that unit from `Test file` in the same manner and say so in the evidence.
+
+2. The full test suite — `<test runner>` with no file filter and no test-name option.
+3. The project's static gates, when the repository defines them — formatter check, linter, and type
+   check.
+4. `npx qfai validate --profile tdd --fail-on error` — qfai is a project dependency, not a global
+   command; a bare `qfai …` is `command not found` (exit 127) on a normal local install, which would
+   fail every checkpoint.
+
+## Verification command set (per spec)
+
+The spec-level boundary has no "item just completed" — a re-run in a later session has none, and
+under parallel slices the ledger order does not identify one either. So step 1 is dropped: the
+spec-level set is steps 2, 3 and 4 only. Everything step 1 would have proved is already covered by
+the full suite.
+
+## Pass criteria
+
+Checkpoint verification PASSES only when **every** command in the applicable set exits 0, and step 4
+reports zero `QFAI-TEST-001` findings. Any non-zero exit is a FAIL: for a per-item checkpoint the
+item stays at `refactor`, the failure is fixed, and the whole set is re-run. A partial run is not a
+pass.
+
+**A fix invalidates the reviewer PASS that preceded it.** The per-item boundary sits after
+`completion-reviewer` and `implementation-reviewer` returned PASS (Phase: Refactor, steps 4-5), so
+those verdicts were given against the pre-fix test and production code. Whenever the fix changes
+either, re-submit to every routed blocking reviewer the change could affect — always the ones whose
+scope it touches — and obtain a fresh PASS **before** re-running the command set. Re-running the
+commands alone would let an item reach `done` carrying code no reviewer ever saw, which the
+skill's own stale-evidence rule forbids. A fix that changes nothing a reviewer judged — re-running
+after a flaky external service, say — needs no re-review; record which case applied.
+
+## Spec-level boundary on an already-complete ledger
+
+A ledger is **terminal** when every row is `done` or a valid `exception` — the same condition the
+spec completion conditions use. The last row reaching `exception` ends the loop exactly as `done`
+does, so both must reach this boundary.
+
+The per-spec boundary is owed once per terminal ledger state, not once per session. Two cases leave
+it unrecorded:
+
+- the run was interrupted between the last row reaching its terminal status and the spec-level
+  verification;
+- `/qfai-implement` is re-run against a ledger that is already terminal.
+
+In both, an unconditional "nothing to do" exit would skip the boundary permanently, and no later
+re-run could repair it — a re-run finds no `todo` rows to process either. So before that exit: read
+`.qfai/evidence/implement-<spec-id>.md` for spec-level `Checkpoint verification command` /
+`Checkpoint verification result` entries covering the current ledger state. Run the **per spec**
+command set above and record them when they are absent, or when they predate the last ledger
+change. Only then report "nothing to do".
+
+## Evidence
+
+Record the result in `.qfai/evidence/implement-<spec-id>.md` using the two per-item evidence fields
+`Checkpoint verification command` and `Checkpoint verification result`. As with RED/GREEN evidence,
+a status without its command is invalid, and evidence from a previous checkpoint MUST NOT be reused.

package/assets/init/.qfai/assistant/skills/qfai-implement/references/cross-spec-ownership.md

@@ -0,0 +1,73 @@
+# Cross-spec Code Ownership
+
+What to do when implementing one spec correctly requires changing something
+another spec's `done` rows certify.
+
+## Why this needs a rule at all
+
+`/qfai-implement` constrains execution to **one spec** and scopes every artifact
+it writes — the ledger, the evidence file — to that spec. The codebase is not
+partitioned at all, qfai defines no module → owning-spec index, and the Refactor
+phase **mandates** duplication removal one line before this rule applies.
+
+So the collision is the normal case, not an edge one. And both available
+outcomes used to violate a shipped rule:
+
+- change the file, and spec A's `done` rows now certify behaviour that was
+  re-tested by nobody — `done` has no outbound edge, so those rows cannot be
+  reopened;
+- do not change it, and the Refactor phase's own instruction is unmet, and
+  spec B ships a duplicate.
+
+Neither left any trace under `.qfai/**`. `drift-protocol.md`'s upstream list
+contains no code or test artifacts, so the STOP → Change Request → owner-rerun
+route never fired for them.
+
+## The rule
+
+**A file another spec's ledger names in `Test file` is that spec's to certify.**
+Editing it does not require permission — it requires a record and a re-review.
+
+1. **Detect.** Before editing a production file in Refactor, search every
+   `tdd/test-list.md` for it. A hit means the edit is cross-spec.
+2. **Record.** Add a `## Cross-spec obligations` entry to this spec's evidence
+   file (fields below).
+3. **Re-review.** Run `completion-reviewer` against the affected specs'
+   obligations as well as this one's. The reviewer is the party that can say
+   whether the other spec's assertions still hold.
+4. **Do not close over it.** An open entry is a completion prohibition
+   (`qfai-implement/SKILL.md#completion-prohibition-conditions`).
+
+## The evidence entry
+
+Per affected spec, in `.qfai/evidence/implement-<spec-id>.md`:
+
+| Field                | Meaning                                                       |
+| -------------------- | ------------------------------------------------------------- |
+| `TDD-ID`             | the row in **this** spec whose work forced the change         |
+| `Blocked spec`       | the spec whose `done` rows the file belongs to                |
+| `Blocked TDD-IDs`    | the rows in that spec that name the file                      |
+| `File`               | the exact path changed                                        |
+| `Change required`    | what had to change, in one sentence                           |
+| `Obligation at risk` | what that spec asserted about the file that is now unverified |
+| `Resolution`         | `re-reviewed` (the reviewer confirmed it holds) or `CR-*`     |
+
+`Obligation at risk` is the load-bearing field. "Changed a shared helper" is not
+a record; "spec-0004 TDD-0012 asserts this helper rejects an empty batch, and
+that path is now routed through the new guard" is.
+
+## When re-review is not enough
+
+If the other spec's obligation genuinely no longer holds — the behaviour it
+asserted has changed, not merely moved — that is upstream drift, and
+`constitution/drift-protocol.md#when-drift-is-detected` governs from step 1.
+Record the CR id in `Resolution`. Re-review cannot ratify a behaviour change the
+other spec never agreed to; only its owner can.
+
+## What this does not do
+
+It does not partition the codebase, and it does not give `done` an outbound
+edge. Both are larger changes. What it does is make the collision **visible and
+blocking** instead of silent — the two outcomes above are still the two
+outcomes, but neither can now be taken without a record that names the
+obligation it puts at risk.

package/assets/init/.qfai/assistant/skills/qfai-implement/references/evidence-revision.md

@@ -0,0 +1,77 @@
+# Evidence revision (what state the observation describes)
+
+Four of the twelve gate items — 3, 5, 7 and 8 — are sub-agent observations, and
+`#evidence-hard-rules` says stale evidence MUST NOT be reused. That rule needs
+something to compare against. This file defines it.
+
+## The field
+
+Every observation records the revision it was made against.
+
+```
+Revision: <git rev> | working-tree+<porcelain digest>
+```
+
+- **`<git rev>`** — the output of `git rev-parse HEAD` at the moment of the
+  observation. Preferred: it is exact and someone else can reproduce from it.
+- **`working-tree+<porcelain digest>`** — for an uncommitted tree, the `HEAD`
+  rev plus a short digest of `git status --porcelain`. Not as good, and honest
+  about not being as good: it says "this observation was made against a state
+  that was never committed".
+
+It appears in three places, all carrying the same address:
+
+1. **Reviewer responses** — as `Reviewed revision`, per
+   `constitution/shared-skill-delegation-baseline.md#reviewer-response-template`.
+2. **The per-item evidence contract** — one `Revision` per round block, beside
+   the RED / GREEN commands and results, and one for the refactor-verify pair.
+3. **The review pack** — `summary.json`'s `revision` field, which is what makes
+   the fact machine-checkable (`QFAI-REVIEW-009`).
+
+## Why an address, not a timestamp
+
+A timestamp orders observations; it does not identify what was observed. Two
+runs a second apart against different trees have different meanings and nearly
+identical timestamps. The revision is the only thing that survives the question
+"which code did this verdict actually rule on?".
+
+Reviewers and `qa-gatekeeper` are dispatched against the **integrated** tree by
+design — `constitution/workflow.md`'s worktree-separation rule constrains
+implementers, not reviewers — so the tree a reviewer reads is legitimately
+allowed to move under it. A fully independent reviewer reading a tree that is
+being edited mid-review produces a verdict that is honest, independent and
+unattributable. That is the failure this field exists for, and it is not fixed
+by choosing a better reviewer.
+
+## What makes evidence stale
+
+Mechanically, so it can be checked rather than judged:
+
+> Evidence is **stale** when the revision it names differs from the revision the
+> item's work finally landed at.
+
+Consequences:
+
+- An item's four verdicts (gate items 3, 5, 7, 8) MUST all name the **same**
+  revision. Verdicts from different revisions do not compose into a ruling about
+  one state — the earlier ones ruled on code that no longer exists.
+- A commit that changes any file the observation covered invalidates it. Re-run
+  the observation; do not carry the verdict forward because "the change was
+  unrelated". Whether it was unrelated is exactly the judgement the evidence
+  exists to remove.
+- A reviewer that noticed the tree moving mid-review says so and pins its ruling
+  to a named revision. A pinned ruling is a valid verdict for **that** revision
+  and a stale one for any later revision.
+
+## When the tree moved under a reviewer
+
+State it, in the response, with the revision. Two forms are acceptable:
+
+- **Pinned** — the ruling stands for the named revision. The orchestrator then
+  decides whether that revision is still the item's final state; if it is not,
+  the review is re-run rather than reinterpreted.
+- **Aborted** — the reviewer could not obtain a coherent read at all (for
+  example, a suite whose collected count changed between two runs of the same
+  command). That is `REVISE` with the reason, not `PASS` with a caveat: a
+  mandated back-to-back identical run that could not be produced is a gate that
+  did not pass.

package/assets/init/.qfai/assistant/skills/qfai-implement/references/execution-ledger.md

@@ -0,0 +1,303 @@
+# Execution Ledger: test-list.md
+
+The execution ledger at `.qfai/specs/<spec-id>/tdd/test-list.md` is the single record of what
+`/qfai-implement` has done and may still do. This file holds its schema and its status rules.
+
+## Required columns
+
+| Column    | Description                                                                                                                                                                                                                 |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| TDD-ID    | Unique identifier for the TDD item (e.g., TDD-0001)                                                                                                                                                                         |
+| TC-Refs   | References to test cases from `06_Test-Cases.md`. Belongs on `Layer = Unit` / `Component` / `Integration` rows                                                                                                              |
+| Layer     | Test layer. Legal values: `Unit`, `Component`, `Integration`, `API`, `E2E`                                                                                                                                                  |
+| Test file | Path to the test file                                                                                                                                                                                                       |
+| Selector  | Test selector(s) for targeted execution — one entry, a comma-separated list, or a glob pattern                                                                                                                              |
+| Status    | Current lifecycle status                                                                                                                                                                                                    |
+| DR-ID     | Decision Record / Change Request IDs, comma-separated: a `DR-*` is required for `exception` rows, a `CR-*` for a row reset by an approved Change Request and is retained through that row's later statuses; blank otherwise |
+| Evidence  | The RED/GREEN outcome in one word each, plus an anchor into `.qfai/evidence/implement-<spec-id>.md` for this TDD-ID. **Not** the commands and output themselves — see "Evidence cell contract" below                        |
+
+## Declared seam column (optional, required for parallel dispatch)
+
+| Column        | Description                                                                                |
+| ------------- | ------------------------------------------------------------------------------------------ |
+| Owning module | The production module this row will write, as a repo-relative path or a dotted module path |
+
+`Owning module` is a **declaration, not an observation**, and that is the whole
+point: it exists before the code does.
+
+The parallel-dispatch gate asks whether two items write the same source module.
+Under RED-first the production module does not exist when `delivery-planner`
+has to answer, and the only path-valued required column is `Test file` — two
+items trivially have independent test files and land on the same production
+module. So the planner had nothing to evaluate against, and
+`parallelization-policy.md`'s "cannot be explained with concrete file/module
+evidence" asked for exactly what test-first withholds.
+
+- Fill it at ledger-authoring time (`/qfai-sdd` Phase 2b) from the TC's parent
+  `BR`, which already names the behaviour's home.
+- One module per row. A row that would honestly need two is a row that should
+  be split — that is the same signal `selector-granularity.md` describes.
+- `-` is legal and means "not declared". A row carrying `-` is **not eligible
+  for parallel dispatch**; it may still be executed serially.
+- It is a claim the row is later measured against, not a lock. See
+  `parallelization-policy.md#seam-reconciliation-after-a-parallel-run`.
+
+## Obligation columns (optional, required by layer)
+
+A row's obligation lives in the column its `Layer` selects. `TC-Refs` is the one
+every row has; the other two are optional columns that become required when the
+row's layer cannot host a `TC-*`.
+
+| Column       | Description                                                                       |
+| ------------ | --------------------------------------------------------------------------------- |
+| US-Refs      | `US-*` obligations this row implements. Legal **only** on `Layer = E2E` rows      |
+| CON-API-Refs | `CON-API-*` obligations this row implements. Legal **only** on `Layer = API` rows |
+| Blocked-By   | What a `blocked` row is waiting on. Required on `blocked` rows, blank otherwise   |
+
+`Blocked-By` takes a Change Request ID (`CR-YYYYMMDD-NNNN`), a contract path
+with line (`.qfai/contracts/db/CON-DB-0005.sql:2715`), or a cross-spec row
+(`spec-0006:TDD-0034`). `DR-ID` is **not** widened to carry it: that column is
+what distinguishes a parked `exception` from a row that never started, and
+overloading it would merge the two states the `blocked` status exists to
+separate.
+
+`test-layers.md` forbids `TC-*` annotations in `tests/e2e/**` and `tests/api/**`,
+so an E2E or API row has no legal `TC-Refs` value. Those rows carry `-` in
+`TC-Refs` and record their obligation in `US-Refs` / `CON-API-Refs` instead.
+
+The binding is enforced in both directions: a `TC-*` on an E2E/API row raises
+`TDDLIST_OBLIGATION_LAYER_MISMATCH` and is **not** counted towards TC coverage,
+so a forbidden placement cannot close a coverage-target TC.
+`TDDLIST_OBLIGATION_LAYER_MISMATCH` likewise rejects a `US-Refs` /
+`CON-API-Refs` value on a layer that does not own it.
+
+A `Layer` outside the legal values raises `TDDLIST_UNKNOWN_LAYER` (warning) —
+without a legal `Layer` the row has no obligation column. Coverage counting
+excludes `API` and `E2E` specifically rather than allowlisting the other three,
+so a mistyped layer keeps counting and is reported by that warning, which names
+the real cause; an allowlist would instead drop the row silently and resurface
+as a coverage error about a TC the author did cover.
+
+Coverage measurement is otherwise unaffected: it reads `TC-*` tokens only, so
+non-TC obligation IDs are inert to it by design.
+
+## Evidence cell contract
+
+The `Evidence` cell is a **pointer**, not the payload.
+
+`.qfai/evidence/implement-<spec-id>.md` is the single home for the per-item
+evidence contract — the RED/GREEN commands, their output, and the reviewer
+verdicts. The ledger cell records the outcome and says where to read the proof:
+
+```
+RED fail / GREEN pass — evidence at `.qfai/evidence/implement-spec-0001.md#tdd-0027`
+```
+
+### Why it cannot hold the payload
+
+A GFM table row is **one physical line**, and `splitMarkdownRow` ends a cell at
+every unescaped `|`. Pasting a command and its output into the cell has two
+failure modes, both silent:
+
+- a newline ends the row — `parseAllMarkdownTables` stops the table at the first
+  line that does not start with `|`, so every row below it disappears from the
+  ledger the validators read;
+- a bare `|` — a shell pipe, a table in the output, a regex alternation — splits
+  the row into extra cells and misaligns every column after `Evidence`.
+
+The column description used to read "RED/GREEN command+result pairs proving the
+TDD cycle", so following it literally corrupted the evidence or destroyed the
+ledger. None of the Evidence hard rules change: they now bind the evidence file,
+which can hold what they ask for.
+
+### Evidence cell encoding
+
+When a cell must contain either character, encode it with
+`specPackParsers.ts#escapeTableCell` — the exported encoder the parser inverts.
+The left column is the character **in the value you want the cell to hold**;
+the right column is what is **written into the row**. Both are shown as HTML
+entities, because a literal pipe in this table would split its own row.
+
+Exactly two rules:
+
+| Character in the value | Written into the cell |
+| ---------------------- | --------------------- |
+| a pipe (&#124;)        | &#92;&#124;           |
+| CR / LF / CRLF         | a single space        |
+
+A literal `\` is **not** escaped: the parser passes it through unchanged, so
+doubling it would corrupt Windows paths and regex literals while keeping the
+column count valid — a corruption no validator can see.
+
+## Evidence cell rules (enforced)
+
+`Evidence` is checked as content, not only as a header name. On a row whose
+`Status` is `green`, `refactor`, `review-fix` or `done` — the statuses that
+assert a cycle has run:
+
+| Finding                        | Fires when                                                          | Severity |
+| ------------------------------ | ------------------------------------------------------------------- | -------- |
+| `TDDLIST_EVIDENCE_EMPTY`       | the cell is empty or holds only dash placeholders (`-`, `–`, `—`)   | error    |
+| `TDDLIST_EVIDENCE_STATUS_ONLY` | the cell claims a verdict (`PASS`, `looks good`, …) with no command | warning  |
+
+A command is recognised by shape, not from a list of known runners, so the rule
+holds on any stack: a program name followed by an argument carrying a flag, a
+path, a selector or an assignment. Backticked commands and the common runners
+are accepted directly.
+
+`TDDLIST_EVIDENCE_STATUS_ONLY` is a warning, waivable under `TDDLIST-004`: a
+ledger written before the check exists carries prose verdicts, and failing a
+build on them is a migration rather than a gate. An empty cell is unambiguous,
+so `TDDLIST_EVIDENCE_EMPTY` stays at `error`.
+
+Rows at `todo`, `red` and `exception` are not checked — the first two have
+nothing to show yet, and a parked row records its reason in `DR-ID`, which
+`TDDLIST_EXCEPTION_MISSING_DR` gates.
+
+Freshness is **not** gated: the ledger records no run identity, so no validator
+can distinguish a fresh command+result pair from a copied one. That rule stays
+with the routed reviewer (`qfai-implement/SKILL.md` "Evidence hard rules").
+
+A pointer cell satisfies these rules: the `evidence at <path>` form carries a
+path, which is one of the command shapes the gate accepts. The rules reject a
+bare verdict, not a pointer.
+
+## Selector granularity (MUST)
+
+`Selector` is **not** restricted to a single test function: a row may own several entries, written
+as a comma-separated list or a glob. What is restricted is what a row may _conflate_ — **one
+independently observable boundary per selector entry**, with RED observed per entry, and a
+matrix-shaped `TC-*` decomposed across rows before RED begins (`TC-Refs` is many-to-many with
+`TDD-ID`). A selector that accumulates unrelated boundaries invalidates the RED observation. Rules
+and examples: `selector-granularity.md`.
+
+## Status Lifecycle
+
+Valid status values: `todo`, `blocked`, `red`, `green`, `refactor`, `review-fix`, `done`, `exception`.
+
+Allowed transitions:
+
+- `todo` -> `blocked` (the row cannot be started: an upstream defect, an
+  unresolved Change Request, or an unfinished row in another spec). Name the
+  blocker in `Blocked-By`; `TDDLIST_BLOCKED_MISSING_REF` errors without it.
+- `blocked` -> `todo` (the blocker cleared). This is a **resumption, not a
+  backward transition**: the row never started, so nothing is being undone.
+- `todo` -> `red` (write a failing test)
+- `red` -> `green` (make the test pass with minimal code)
+- `green` -> `refactor` (improve code quality while keeping tests green)
+- `refactor` -> `done` (item complete)
+- `refactor` -> `review-fix` (a blocking reviewer returned `REVISE`)
+- `review-fix` -> `refactor` (rework complete; re-submit to the reviewer)
+- Any active status -> `exception` (anomaly detected; record DR-ID in DR-ID column)
+- `red` | `green` | `refactor` | `done` | `exception` -> `todo` — **upstream
+  reset**, the only legal reopen, available from every status a row can hold.
+  Permitted **only** when an approved upstream change (Drift Protocol step 4
+  rerun) invalidated the row's obligation. The invalidating CR/DR ID MUST be
+  recorded in the `DR-ID` column, and the reset MUST cite it in `Evidence`.
+  That ID MUST be retained as the row moves on through `red`, `green`,
+  `refactor` and `done` — clearing it on the next transition erases the only
+  record of why a completed row was reopened. A row swept out of `exception`
+  keeps the anomaly's DR-ID alongside the reset ID. A reset without a recorded
+  approval is a backward transition and is prohibited.
+- `exception` -> `todo` — **anomaly resolved**, the item re-enters the cycle
+  from the start. This is the exit `exception` previously lacked; without it a
+  parked item could never be un-parked without a lifecycle violation. Distinct
+  from the upstream reset above: nothing upstream changed, so it needs no CR/DR
+  approval — the anomaly's own DR-ID stays in place.
+- A reset row is at `todo`, so it owes no test file until it reaches `green`.
+  The `Test file` existence check is unchanged for `green` / `refactor` /
+  `done`: those statuses assert a test that ran.
+
+- `refactor` -> `red` (**QA rejection recovery — the only re-entry**): a routed
+  `qa-gatekeeper` returned `REVISE` on this row's RED/GREEN evidence because the
+  cycle itself was wrong. Batched (T1) review defers that confirmation until
+  after the row has left `red`, so without this edge a rejected row could never
+  redo the RED it was faulted for and could never reach `done`. Cite the verdict
+  in `Evidence`, re-run the micro-cycle; rules:
+  `volume-policy.md#group-formation-states-and-transitions`.
+
+Backward transitions are otherwise prohibited and nothing but that QA rejection
+re-opens a row. Attempting `green` -> `red` must produce:
+`"Backward transition prohibited: green -> red"`. The upstream reset above is
+not a backward transition: it is an owner-approved re-entry, and the row starts
+its cycle again from `todo`.
+
+The one exception is an approved Change Request reset — the only sanctioned
+backward transition. Preconditions and the reset procedure:
+`references/change-request-reset.md`.
+
+### Reviewer rework is not a backward transition
+
+A blocking reviewer's `REVISE` moves the item `refactor -> review-fix`. While at
+`review-fix` the item MAY re-enter the RED/GREEN cycle as many times as the
+rework needs — write the new failing test, watch it fail, make it pass — without
+any of those runs counting as a backward transition. The row's status does not
+change during that cycle: `review-fix -> red` and `review-fix -> green` are not
+allowed transitions. When the rework is done the item returns to `refactor` and
+is re-submitted.
+
+`review-fix` is not a completion state and appears in the completion-prohibition
+list. Round-by-round evidence rules: `round-evidence.md`.
+
+## Blocked rows
+
+`blocked` means **cannot be started**, not "not started yet" and not "anomaly".
+
+- It is **completion-prohibiting**, exactly like `todo`. A spec must not close
+  over an unimplemented obligation, and naming the blocker does not discharge it.
+- It is **not** selectable. Phase Red picks the first `todo` row and skips
+  `blocked` ones, so the loop head stops re-issuing rows that cannot proceed.
+- It is **not** `exception`. `exception` is scoped to an anomaly, requires a
+  `DR-*`, and satisfies spec completion — filing a blocked row there would
+  silently close the obligation.
+- `npx qfai report` counts it inside `open` but prints it separately
+  (`open: N (blocked: M)`), so "not started" and "cannot start" are readable
+  apart without changing what completion means.
+
+## Exception Handling
+
+`exception` means **anomaly, work paused** — not "accepted risk, closed". The
+two are different states sharing one status today; the `DR-ID` distinguishes
+them and only the accepted-risk form is completion-satisfying. Resolve a paused
+item via `exception` -> `todo`.
+
+When transitioning to `exception`:
+
+- A DR-ID (Decision Record ID) must be recorded in the DR-ID column.
+- A retained `CR-*` does not satisfy this: it records the approved reopen, not the anomaly. Add the `DR-*` alongside it (`DR-NNNN, CR-YYYYMMDD-NNNN`).
+- If the DR-ID column is empty, or holds `CR-*` references only, emit error: `"exception status requires DR-ID in DR-ID column"`.
+
+### Where the Decision Record is written
+
+Write it to `.qfai/decisions/DR-<id>-<slug>.md`, beside the Change
+Requests, using the same `DR-*` ID scheme those files declare. Do **not** write
+`07_Decisions.md` or `09_delta.md`.
+
+Those two are upstream SSOT (`constitution/drift-protocol.md#core-rule`) and
+this skill carries `[DRIFT-PROTOCOL:MANDATORY]`, so a downstream write to either
+is a protocol violation — while the `exception` transition itself is an ordinary
+inline step of Phase Red that `TDDLIST_EXCEPTION_MISSING_DR` blocks at `error`
+without a `DR-*`. `.qfai/decisions/` is the one home that satisfies both: the
+protocol whitelists **creating** a record there
+(`drift-protocol.md#allowed-exceptions-minimal-whitelist`), and the managed `.gitignore` block
+already tracks it as a governance record.
+
+The upstream cross-reference is a separate, later write. If the anomaly turns
+out to change an approved obligation, that is drift: raise a Change Request per
+`drift-protocol.md#when-drift-is-detected`, and the owner skill's rerun is what
+records the reference in `07_Decisions.md` / `09_delta.md`. Parking the row does
+not require that to have happened.
+
+### Parked items and the `TDDLIST-001` waiver
+
+Every `exception` row raises `TDDLIST_EXCEPTION_PARKED` (warning, rule
+`TDDLIST-001`). The validator cannot read the DR to tell a paused defect from an
+approved accepted risk, so the approval is recorded where QFAI already checks
+approvals: a `TDDLIST-001` waiver in `.qfai/waivers.yml`.
+
+The waiver carries `id` / `reason` / `expires` / `evidence` / `scope.paths`,
+plus `match.dl_ids` listing the approved rows' `TDD-ID`s. `match.dl_ids` is not
+optional — omit it and `QFAI-WAIVER-005` rejects the waiver, because a single
+path-scoped entry would otherwise clear every parked row in the same ledger.
+
+Without a matching waiver the warning stands, which is the intended signal.