qfai 1.9.2 → 1.10.0

package/assets/init/.qfai/assistant/skills/qfai-implement/references/final-checklist.md

@@ -0,0 +1,19 @@
+# Final Checklist
+
+Check this list last, immediately before the completion message. Every box must be ticked; a box that
+cannot be ticked is a reason not to declare completion, not a note to carry forward.
+
+- [ ] CRITICAL CONSTRAINTS were followed.
+- [ ] Each item was processed one test at a time, or inside an item-level parallel dispatch authorized by `SKILL.md#parallelization-policy`.
+- [ ] Red phase: test was written and confirmed to fail — or, on the _RED not observable_ path,
+      the correct test was written first and the falsifiability trio replaces the natural RED
+      (`red-not-observable.md`).
+- [ ] Green phase: minimal code was written and test confirmed to pass — waived on the _RED not
+      observable_ path, where the `Satisfied-by` row already implements the predicate.
+- [ ] Refactor phase: code improved with tests still passing.
+- [ ] `test-list.md` statuses are accurate.
+- [ ] No backward transitions occurred.
+- [ ] Exception items have DR-IDs recorded.
+- [ ] All tests pass.
+- [ ] `npx qfai validate --profile tdd --fail-on error` passes with zero `QFAI-TEST-001` findings (no
+      `it.todo` / `test.todo` / `describe.todo` stubs remain).

package/assets/init/.qfai/assistant/skills/qfai-implement/references/finding-classification.md

@@ -0,0 +1,49 @@
+# Blocking vs advisory findings
+
+Provenance rules: `shared-skill-delegation-baseline.md#finding-provenance-must`.
+
+## Blocking
+
+A **blocking** finding cites either an upstream obligation (`AC-*`, `BR-*`,
+`TC-*`, `CON-*`, or a named constitution/catalog rule) or a defect class
+(`defect:correctness`, `defect:security`, `defect:code-quality`) in its
+`Traces to:` field.
+
+A defect demonstrable from the changed code — an unhandled rejection, a missing
+validation on trusted input, a leak, a broken contract the code itself declares
+— is blocking without needing an `AC-*`.
+
+Only blocking findings force `REVISE`, and only blocking findings hold the item
+out of `done`.
+
+## Advisory
+
+An **advisory** finding is one whose `Traces to:` is `none` — a new product
+obligation upstream never asked for. It MUST NOT be implemented as production
+code or pinned as a test assertion.
+
+Route it per `drift-protocol.md#reviewer-originated-obligations`: record it in
+the reviewer response under `Advisory / Change Request proposals`.
+
+Do **not** edit `08_Open-questions.md` here. It is upstream SSOT under the Drift
+Protocol, and creating spec artifacts is a non-goal of this skill; the owner
+phase (`/qfai-sdd`) records and adjudicates it.
+
+## What an advisory does to `done`
+
+- A new advisory that does **not** change an already-approved obligation leaves
+  the item free to reach `done`.
+- One that **does** change an approved obligation takes the Change Request path,
+  and `drift-protocol.md#when-drift-is-detected` applies: STOP, and no `done`
+  for items depending on the obligation under dispute until approval and the
+  owner rerun.
+
+## The reviewer verdict is still required
+
+`Do not declare DONE until Reviewer returns PASS` is never waived: the Reviewer
+verdict is required on every item, including one whose review produced only
+advisories.
+
+What **blocking** findings change is the verdict itself — only they force
+`REVISE` and hold `done`. An advisory-only review returns `PASS`, and that
+`PASS` is still what releases `done`.

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

@@ -0,0 +1,55 @@
+# Ledger preconditions
+
+`.qfai/specs/<spec-id>/tdd/test-list.md` is the execution ledger every step of
+`/qfai-implement` reads. This file states where it comes from, how to recover it
+when it is absent, and how to tell a truthfully empty ledger from an incomplete
+one.
+
+## Producer
+
+`/qfai-sdd` Phase 2b seeds one row per coverage-target TC from
+`06_Test-Cases.md`. `US-*` / `CON-API-*` are ATDD obligations traced by `QFAI:`
+annotations, not ledger rows — they never appear as rows here.
+
+## Recovery when it is missing
+
+Rerun `/qfai-sdd <spec-id>` for the target spec, or copy
+`.qfai/assistant/skills/qfai-sdd/templates/specs/spec/tdd/test-list.md` into the
+spec directory and derive the rows from `06_Test-Cases.md`.
+
+Do **not** proceed with an absent ledger, and do **not** invent rows that no TC
+backs.
+
+## An empty ledger is a fault only when `06_Test-Cases.md` disagrees
+
+A header-only table has two very different causes and they need opposite
+responses, so never treat "no rows" as "nothing to do" on its own.
+
+Before exiting, read `06_Test-Cases.md` and confirm it declares **no**
+coverage-target TC, judged exactly as the validator judges it
+(`qfai-sdd/references/spec-traceability-rules.md#tdd-execution-ledger`).
+
+### What counts as a coverage target
+
+A TC is a target **unless** its `Level` names a non-coverage layer. Both
+spellings the shipped artifacts use count: the words `integration` / `e2e` /
+`system` / `acceptance` / `api`, and the codes `L3` / `L4` / `L5` that
+`06_Test-Cases.md` writes. Matching is case-insensitive.
+
+That is an exclusion list, not an allowlist:
+
+- an empty or unrecognised `Level` makes the TC a target;
+- a `06_Test-Cases.md` with no `Level` column at all makes **every** TC a target.
+
+Never narrow this to a chosen pair of level names. Guidance that names a
+narrower allowlist makes a header-only ledger look truthful and skips the whole
+implementation.
+
+### The two outcomes
+
+- **No coverage-target TC is declared** — the ledger is truthfully empty. Report
+  "nothing to do" and exit. Rerunning `/qfai-sdd` derives the same empty table
+  and loops.
+- **At least one is declared** — the ledger is incomplete (a partial copy or an
+  interrupted Phase 2b) and `npx qfai validate` reports `TDDLIST_TC_NOT_COVERED`.
+  Run the recovery above instead of exiting.

package/assets/init/.qfai/assistant/skills/qfai-implement/references/oracle-strength.md

@@ -0,0 +1,81 @@
+# Oracle Strength
+
+Whether a passing test's pass **depends on the behaviour the item owns**.
+
+Nothing in qfai asked this. The completion gate and the per-item evidence contract
+record a command that failed and a command that passed; GREEN is measured as
+`exit code == 0`. Downstream, ATDD coverage is annotation presence, the strongest
+content check on a `done` row is that the test file exists, and the Coverage
+Depth Matrix counts **case categories**, never oracle strength. A test that
+cannot fail therefore cleared RED, GREEN, refactor, all completion points,
+`QFAI-ATDD-111/112/113` and `npx qfai validate`.
+
+## `Oracle proof` — the evidence field
+
+Per item, alongside the RED/GREEN pair:
+
+1. Name the **smallest production change** that makes this item's test fail
+   again — one line, in the code the item owns.
+2. Apply it, run the row's `Selector`, and record the command and its **failing**
+   output.
+3. **Revert immediately.** The mutation is evidence, not a deliverable; it must
+   never appear in the commit.
+
+One mutation per item. It is the only evidence that separates a discriminating
+test from a vacuous one, and it costs one run.
+
+A row on the _RED not observable_ path already carries
+`Falsifiability command` / `Falsifiability result`, which is the same proof by
+the same method. That satisfies `Oracle proof`; do not do it twice.
+
+## Reject an `Oracle proof` when
+
+- the mutation is outside the code the item owns — breaking a shared helper
+  proves the helper is used, not that this test discriminates;
+- the mutation is a syntax error, a thrown "not implemented", or a deleted
+  export — that is a load failure, the same non-observation
+  `red-admissibility.md` rejects for RED;
+- the failing output names a different selector than the row's;
+- the recorded command differs from the `GREEN command`. Proving a different
+  test discriminates says nothing about this one.
+
+## Weak-oracle shapes to look for
+
+These are the failure modes seen in the wild. Each passes today's gates.
+
+- **Truthiness where the value is available.** `expect(result).toBeTruthy()` when
+  the boundary's own value is in hand. Assert the value.
+- **Round-tripping the fixture's own helper.** Comparing a stored value against
+  the same function that wrote it: the assertion holds for every implementation
+  of the function, including a wrong one.
+- **Loops over a collection that is empty by construction.** A `for` over a
+  filtered set that no fixture can populate asserts nothing, and reports as a
+  pass.
+- **Observations the transport discards.** Asserting on a field the client
+  strips, or a log the harness swallows, is an assertion against nothing.
+- **Assertions on the mock.** Verifying that a stub was called with what the
+  test just passed it re-states the test's own input.
+
+## The equivalent-mutant case
+
+Sometimes no mutation can be found because the **upstream contract is weaker
+than the obligation** — every implementation the contract permits passes the
+test, so the test cannot discriminate without asserting something upstream never
+promised.
+
+That is not an implementer defect and must not be worked around by strengthening
+the assertion past the contract: doing so encodes a reviewer-originated
+obligation in a hard assertion, which
+`constitution/drift-protocol.md#reviewer-originated-obligations` forbids in
+exactly those terms.
+
+The route:
+
+1. Record `Oracle proof: equivalent-mutant`, naming the contract clause that is
+   weaker than the obligation.
+2. Raise it as an advisory / Change Request per
+   `drift-protocol.md#when-drift-is-detected`. `/qfai-sdd` owns closing it, by
+   tightening the contract.
+3. The row may reach `done` against its existing obligation with the advisory
+   recorded — the gap is upstream, and blocking the implementer on a finding
+   they are forbidden to act on would be a deadlock, not a gate.

package/assets/init/.qfai/assistant/skills/qfai-implement/references/parallelization-policy.md

@@ -0,0 +1,235 @@
+# Parallelization Policy
+
+Full rules for item-level parallelism inside one spec. `qfai-implement/SKILL.md`
+carries the summary and the precedence statement.
+
+## Scope of this policy
+
+- **Cross-spec parallelism is barred.** One spec per invocation, always. This
+  is the Non-goal above and it is not approvable.
+- **Item-level parallelism inside one spec** is what the rest of this section
+  governs. `parallel_groups: []` in `agent-routing.yml` describes **role
+  fan-out within a phase**, not item dispatch; it neither permits nor forbids
+  what this section decides.
+
+## Gates and precedence
+
+Two gates apply, and **both must hold**:
+
+1. **Technical gate** — the conditions below. Adjudicated by
+   `delivery-planner`, which is the sole authority for authorizing parallel
+   dispatch.
+2. **Consent gate** — explicit user approval.
+
+**Precedence: user approval cannot override a technical DENY.** A DENY from
+`delivery-planner` ends the question; approval is only sought after the
+technical gate passes.
+
+- **Default**: Serial execution. Items are processed one test at a time in `test-list.md` order.
+- Serial execution ensures that each test is written and verified in isolation before moving to the next.
+
+## Allow conditions (all must be true)
+
+Stated as **concurrent write conflicts**, not as the existence of shared
+things. A read-only fixture module or a DI container that every item constructs
+independently does not veto the policy; a shared database is resolved by
+per-worker schema isolation, not by a blanket deny.
+
+- **Every concurrently dispatched row declares an `Owning module`**, and no two
+  of them declare the same one. This is the operational form of the next
+  bullet: under RED-first the source module does not exist yet, so the only
+  thing that can be compared before dispatch is what each row _declares_ it
+  will write (`execution-ledger.md#declared-seam-column-optional-required-for-parallel-dispatch`).
+  A row carrying `-` in that column is not eligible for parallel dispatch.
+- No two concurrently dispatched items **write** the same source module.
+- No two concurrently dispatched items **write** the same test module.
+- No item **writes** a module that another concurrently dispatched item's test
+  or implementation **reads**. A write/read overlap is a conflict even when no
+  two items write the same file: the reader's RED/GREEN would observe a
+  half-applied module and become timing-dependent.
+- No two concurrently dispatched items **mutate** the same fixture instance,
+  singleton instance, or DI container instance. (Constructing a fresh instance
+  per item is fine.)
+- No two concurrently dispatched items **write** the same schema or the same
+  database rows. Per-worker schema or database isolation satisfies this.
+- No two concurrently dispatched items contend for the same **external runtime
+  resource**. Worktree separation isolates the checkout and the index and
+  nothing else, so these live outside it and must be checked explicitly:
+  - fixed TCP/UDP ports the items' tests bind;
+  - absolute or `os.tmpdir()`-rooted paths written outside the worktree;
+  - external caches, queues, brokers, containers and other daemons;
+  - environment variables and OS-global state the tests set.
+
+  Satisfy it either by a **disjoint write set** (each item owns different
+  ports/paths/keys) or by **per-worker isolation** (ephemeral port 0, a
+  `mkdtemp` directory per worker, a namespaced cache/queue prefix). A resource
+  neither disjoint nor isolated is a DENY: `constitution/workflow.md#concurrency-stage-independent-mandatory`
+  requires no shared state, and the collision would appear at run time as a
+  flaky RED/GREEN rather than at adjudication.
+
+- No sequential dependency: item B does not consume item A's output.
+- A post-merge integration verify plan exists.
+
+Read dependencies are enumerated from the declared write sets: for every write
+target, `delivery-planner` resolves the importers reachable from the other
+items' test and implementation files. An import graph that cannot be resolved
+is a DENY, because the independence claim then has no concrete evidence.
+
+## Isolation requirement (worktree separation)
+
+Adjudicated separately from the "all must be true" list above, and **not
+waivable**. Per `constitution/workflow.md#concurrency-stage-independent-mandatory`,
+worktree separation is required for parallel execution, so
+`delivery-planner` has two outcomes, not three:
+
+- **Separate worktrees in force** (one worker per `git worktree`, one index
+  each) -> requirement met.
+- **Anything else -> DENY.** Record the reason in the dispatch decision and run
+  the items serially.
+
+A branch is **not** a substitute. Branch separation still shares one working
+tree and one index: workers observe each other's half-written files and
+generated artifacts, which is exactly the hidden coupling the requirement
+exists to prevent, and a sweeping stage command would commit a sibling's
+in-flight files.
+
+Worktree separation is also **not sufficient on its own**. It separates the
+checkout and the index; ports, out-of-worktree paths and external services stay
+shared across workers. The external-runtime-resource condition in the allow
+list covers those, and it is evaluated whether or not worktrees are in force.
+
+qfai does not provision worktrees itself, so in practice this exception stays
+unreachable until the operator (or the orchestrator, explicitly) creates one
+worktree per worker. That is the intended outcome: serial execution is the
+correct behavior when isolation cannot be guaranteed, and an unreachable
+exception is preferable to a documented way around an upstream SSOT rule.
+
+## Deny conditions (any one blocks parallel dispatch)
+
+- Two concurrently dispatched items share the same behavior's Red/Green/Refactor cycle.
+- Two concurrently dispatched items declare the same `Owning module`, or either
+  of them declares none.
+- Two concurrently dispatched items modify the same public API surface. Before
+  RED this is evaluated over the declared seams; the surface itself does not
+  exist yet.
+- Two concurrently dispatched items write the same shared fixture, shared mock,
+  or shared global setup **file**. (A shared fixture module that neither item
+  writes and each consumes read-only is not a deny — see the allow conditions.)
+- Two concurrently dispatched items bind the same fixed port, write the same
+  out-of-worktree path, or share an un-namespaced external cache/queue.
+- Sequential dependency: "A must finish before B has meaning".
+- The independence claim cannot be explained with concrete file/module
+  evidence. Before RED that evidence is the rows' declared `Owning module`
+  values — not the source tree, which does not yet contain the modules under
+  discussion. **If the ledger carries no `Owning module` column, the allow
+  conditions cannot be evaluated at all**, and parallel dispatch is permitted
+  only for slices whose seams already exist in the repository. "The test files
+  differ" is not an independence claim.
+
+## Seam reconciliation (after a parallel run)
+
+The post-merge integration verify detects a broken build. It does not detect
+two slices deciding the same thing twice under two names in one module, which
+is the outcome the deny conditions exist to prevent — and that outcome can
+leave the suite green.
+
+So after the slices merge, and **independently of whether the merged suite
+passes**:
+
+1. For each slice, list the `src/` paths it actually touched
+   (`git diff --name-only <base>..<slice-head> -- <source root>`).
+2. Compare that list against the slice's declared `Owning module`.
+3. Report every touched path that no slice declared, and every path touched by
+   more than one slice, as a **deny-condition breach**. It is a breach whether
+   or not anything broke: the gate was passed on a claim that turned out to be
+   false, so the next authorization is being made on the same basis.
+4. A breach does not automatically roll back a green merge. It does require the
+   overlapping modules to be re-read for duplicated behaviour, and the finding
+   to be recorded before `delivery-planner` authorizes another parallel run.
+
+## Coordinated parallel mode (ledger ownership)
+
+When parallel dispatch is authorized, the ledger has one writer:
+
+- The **orchestrator** owns every `test-list.md` write. Workers never edit it.
+- Workers return a per-item evidence block carrying **every** field of the
+  `SKILL.md` "Per-item evidence contract": `TDD-ID`, `TC-ref`, RED command and
+  result, GREEN command and result, Refactor verify command and result,
+  `Spec review`, `Code quality review`, and `Prototype parity` for UI-affecting
+  items — plus the resulting status and `DR-ID`.
+- Item 10 of the 11-point gate is satisfied by the orchestrator applying a
+  **complete** evidence block to the row, not by the worker writing it. A block
+  missing any contract field does not satisfy item 10: the orchestrator obtains
+  the missing fields first, and the row stays out of `done` until it has them.
+
+## Ledger ownership
+
+`.qfai/specs/<spec-id>/tdd/test-list.md` has exactly one writer: the
+**orchestrator**, in the **trunk**.
+
+This is not a style preference. Delegation is mandatory and the orchestrator may
+not write code, so the only role that ever observes RED/GREEN is the
+implementation agent — and the ledger it would have to write lives _inside_ the
+tree that worktree separation copies. N workers would each hold a private copy of
+the one table that is the completion gate, and merging them is a text merge of
+the artifact the gate reads.
+
+So:
+
+- Parallel workers **MUST NOT** edit `.qfai/specs/<spec-id>/tdd/**`. Their
+  worktree copy is read-only for the duration of the slice.
+- Each worker returns, per item it processed: `TDD-ID`, final `Status`, and the
+  `Evidence` payload in the per-item evidence contract's form.
+- The orchestrator writes those rows into the trunk ledger during
+  `#post-parallel-integration-verify`, before the verify runs.
+- A merged item whose row is still `todo` fails that verify. Silence there is
+  indistinguishable from work that was never done.
+
+In serial mode the same rule holds with no merge step: the implementation agent
+returns Status + Evidence, the orchestrator writes them.
+
+## Failed integration verify
+
+The old rule was one unconditional destructive branch — "flag all slices for
+re-examination and roll back the merge" — with no step attributing the failure to
+anything. That contradicts the Gate Failure Autorepair Protocol the skill
+imports twenty lines later, which classifies this class as a local,
+non-destructive code/test defect to fix and re-run, and reserves stopping for
+_destructive_ changes. It also contradicts the forward-only lifecycle, and never
+said what happened to the rolled-back items' statuses.
+
+Classify first, then apply the matching remedy.
+
+### 1. Defect outside every merged slice
+
+A stale fixture, a stale composition helper, a shared factory none of the slices
+declared. **Fix locally and re-run integration verify. Do not roll back.**
+
+The fix lands outside every slice's declared write boundary, so it is the
+**orchestrator's** to make — no slice owns it, and returning it to a worker would
+route it to an agent whose boundary excludes the file. Record it in the stage
+evidence as an integration fix, not as a slice's work.
+
+### 2. Defect inside one slice
+
+Return **that slice's items only**. The other slices keep their state and their
+merged code; re-examining them would discard work the verify did not fault.
+Rows go to `review-fix`, which is the status that exists for rework and has an
+outbound edge back to `refactor`.
+
+### 3. The union itself is inadmissible
+
+Only when the slices are individually correct and jointly wrong — a genuine
+interaction the merge exposed — flag all slices and roll back the merge.
+
+This is the **one sanctioned backward move** in this skill besides an approved
+Change Request reset. It is a _merge_ rollback, not a status rollback: the rows
+return to `review-fix`, not to `todo`, so the forward-only lifecycle is
+unbroken and the RED/GREEN evidence each row already earned is retained. A row
+that must genuinely restart needs the upstream-reset rule and its recorded
+approval, exactly as elsewhere.
+
+### Round budget
+
+Repeating any of the three without progress escalates to the user on the third
+round, per the autorepair protocol. "Roll back and retry" is not a loop.

package/assets/init/.qfai/assistant/skills/qfai-implement/references/red-admissibility.md

@@ -0,0 +1,91 @@
+# RED Admissibility
+
+What makes a failure count as the RED observation for a ledger row.
+
+`Phase: Red` step 4 says "confirm the test actually fails for the expected
+reason". That phrase used to be the whole standard qfai shipped — it appeared
+three times across the assistant tree, always as an obligation and never as a
+definition, and no validator adjudicated it. This file is the definition.
+
+## The criterion
+
+A failure is an **admissible RED** when all four hold:
+
+1. The test module **imports and loads successfully**. Nothing under test is
+   missing at the module level.
+2. The failure is raised by an **assertion** — or an expected-exception check —
+   **executing inside the row's own `Selector`**. Not in a fixture, not in a
+   sibling test, not at collection time.
+3. The failure message **names the predicate the row owns**: the value, state or
+   error the obligation is about. "expected 3, received undefined" names it;
+   "cannot find module" does not.
+4. Deleting every assertion in the test would make the run **pass**. If the run
+   would fail identically with no assertions at all, the observation carries no
+   information about the assertions.
+
+## What is not a RED
+
+A **missing seam**, not a RED:
+
+- collection / import / module-resolution error
+- syntax error
+- missing symbol or missing export
+- fixture, factory or test-harness setup error
+- a failure raised outside the row's `Selector`
+
+Each of these proves the seam is absent. None of them says anything about
+whether the assertions discriminate — which is the property RED exists to
+establish.
+
+This matters most exactly where discriminating power matters most. Under the
+skill's own ordering, Phase Red writes the test and Phase Green writes the
+production code, so for any row that introduces a new module or symbol the first
+failure is a load error **by construction**. Without step 3a below, the gate
+would be met vacuously for every such row.
+
+## Step 3a: create the seam first
+
+Before running the test, create the **minimal seam** the test imports: the
+module, export, class or function signature, with **no behaviour** — a no-op
+body, or one returning a placeholder value.
+
+Do **not** make the seam throw. An unasserted exception fails the run before any
+assertion executes, which is the same non-observation as a load error: it shows
+the seam is unfinished, not that the assertions discriminate. The one exception
+is a test whose oracle _is_ an expected-exception check — there the throw is what
+the assertion inspects, and the row records `expected-error`.
+
+This is not production code and does not satisfy Phase Green's step 1: it
+implements no predicate. Its only job is to make the module load, so that the
+failure the row records is an assertion failure rather than a resolution
+failure.
+
+## Recording it
+
+The per-item evidence contract carries `RED failure mode`, whose value is one
+of:
+
+| Value            | Meaning                                                      |
+| ---------------- | ------------------------------------------------------------ |
+| `assertion`      | admissible — an assertion inside the row's `Selector` failed |
+| `expected-error` | admissible — an expected-exception check failed              |
+| `falsifiability` | the _RED not observable_ path; see `red-not-observable.md`   |
+
+There is no admissible value for a load error, and that is deliberate: a row
+whose only failure was a load error has not observed RED yet. Create the seam
+and re-run.
+
+`RED result` truncation: the general "truncated output is acceptable" allowance
+does **not** extend to the part of the output that demonstrates admissibility.
+The recorded result must retain the assertion message and its location. Truncate
+the stack tail, never the assertion line.
+
+## When an assertion-level RED is genuinely unobservable
+
+One case is legitimate: the obligation is already satisfied by a sibling row, so
+the correct test passes on first run. That is **not** a licence to accept a load
+error instead — it is a different path with its own evidence, and it is
+specified in `red-not-observable.md`. Record `RED failure mode: falsifiability`
+and follow that procedure.
+
+Never weaken a correct test until it fails in order to manufacture a RED.

package/assets/init/.qfai/assistant/skills/qfai-implement/references/red-not-observable.md

@@ -0,0 +1,70 @@
+# RED Not Observable (obligation already satisfied)
+
+Handling for `Phase: Red` step 5 when a newly written test passes on its first
+run.
+
+## Classify first
+
+- **Obligation already satisfied by a sibling row** — the new test exercises a
+  predicate an earlier `done` row already made pass. This is the usual case
+  when a BR binds several ACs to one common validator. It is **not an anomaly**
+  and does **not** go to `exception`. Follow the procedure below.
+- **Anything else** — the test is wrong, the SUT is wrong, or the cause is
+  unknown. Transition to `exception` and record the anomaly.
+
+Never weaken a correct test until it fails in order to manufacture a RED.
+
+## Falsifiability evidence
+
+An honest GREEN from a sibling item is evidence the system works, not a defect.
+The row still needs to be falsifiable, so substitute falsifiability evidence
+for the natural RED and let the row proceed to `green` and `done`:
+
+1. Record `Satisfied-by: TDD-NNNN` — the row whose implementation already
+   satisfies this obligation.
+2. Break the shared predicate deliberately (inject a mutation), run this row's
+   test, and confirm it **fails**. Record the command and its output as
+   `Falsifiability command` / `Falsifiability result`.
+3. Revert the mutation and confirm the test passes again. That run is the row's
+   GREEN evidence.
+4. A mutation-testing result covering the same predicate is an acceptable
+   substitute for the **falsifiability demonstration** — step 2 and the revert
+   half of step 3 — with the report standing in for `Falsifiability command` /
+   `Falsifiability result`. It does **not** substitute for GREEN: the row still
+   records a `GREEN command` / `GREEN result` from a run with the predicate
+   intact, either the original passing run or an explicit re-run.
+
+## Effect on the gates
+
+The `Evidence` cell carries `Satisfied-by`, `Falsifiability command`,
+`Falsifiability result` and the GREEN pair in place of a RED pair. The
+11-point gate is all-conditions-required, so every item this path touches is
+listed here — a substitute that only covered item 3 would still leave the row
+unable to reach `done`.
+
+- **Item 2 ("A failing test was added first")** is satisfied by adding the
+  correct test first and proving it falsifiable by mutation. A test that
+  passes on its first run because the predicate is already implemented is
+  still test-first; the alternative — weakening it until it fails — is what
+  the classification step forbids.
+- **Item 3 ("RED was observed")** is satisfied by the falsifiability evidence.
+- **Item 4 ("Minimal production code was written")** is **waived**: the
+  `Satisfied-by` row already wrote it. Inventing an unrelated change to tick
+  this box is worse than the gap it fills. `Phase: Green` step 1 likewise has
+  nothing to write on this path and proceeds straight to running the test.
+- **The per-item evidence contract** treats the RED pair and the
+  falsifiability trio as **exclusive alternatives**: exactly one form is
+  present, never both and never neither. `qa-gatekeeper` accepts the
+  falsifiability form as the minimum evidence for this row.
+- **The completion prohibition** "No RED fresh evidence exists for the item"
+  does not apply to a row carrying falsifiability evidence.
+- **The `FINAL CHECKLIST` Red and Green boxes** are ticked by this path's
+  substitutes: the falsifiability trio for Red, and the observed pass with no
+  new production code for Green.
+- **`project_memory` and `constitution/workflow.md`** restate "fresh RED +
+  GREEN evidence is mandatory per item"; both now carry this path's exception,
+  so a run that reloads only its memory context does not re-impose the RED pair
+  and force a fabricated failure.
+
+Every other gate item is unchanged: GREEN must still be observed, refactor
+must still be verified, and both blocking reviewers must still return PASS.