qfai 1.10.0 → 1.10.2

package/assets/init/.qfai/assistant/manifest/agent-catalog.yml

@@ -43,7 +43,7 @@ agents:
       - Work Orders for each subagent (scope, inputs, outputs, gates)
       - Stage Gates plan + current status
       - Completion report (DoD checklist + evidence links)
-      - Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
+      - Evidence summary for `.qfai/evidence/` (commit only paths re-included by the managed block)
 
       ## Stop conditions
 
@@ -56,7 +56,7 @@ agents:
       ## Sign-off
 
       - [ ] Deliverables are complete
-      - [ ] Evidence is present (gitignored)
+      - [ ] Evidence is present under the managed tracking policy
       - [ ] Stage gates are PASS
       - [ ] Reviewer sign-off recorded
 
@@ -125,6 +125,14 @@ agents:
       - .qfai/specs/spec-\*/01_Spec.md
       - `.qfai/specs/spec-*/tdd/test-list.md` — the execution ledger this role selects
         the next item from and whose Red-Green-Refactor ordering it enforces
+      - **The document the row's obligation column points at.** Item scope is "is this
+        selector a sufficient slice of the obligation", and the obligation is not
+        always a `TC-*`: an `E2E` row owes `US-Refs` and an `API` row owes
+        `CON-API-Refs`. Without these the role has nothing to compare such a row
+        against and can only guess a PASS or stall the gate.
+        - `.qfai/specs/spec-*/06_Test-Cases.md` for a `TC-Refs` row
+        - `.qfai/specs/spec-*/02_User-stories.md` for a `US-Refs` row
+        - `.qfai/contracts/api/**` for a `CON-API-Refs` row
       - .qfai/discussion/discussion-\*/04_Sources.md
       - .qfai/discussion/discussion-\*/06_REQ.md
       - .qfai/discussion/discussion-\*/11_OQ-Register.md
@@ -422,7 +430,8 @@ agents:
       - .github/instructions/principles.instructions.md
       - Root `DESIGN.md` (brand SSOT: front-matter tokens plus `# Brand Philosophy` body)
       - Reference pool framed as deviate-from inputs, screen contracts (`uiux/40_screen_contracts.md`), optional tokens, optional fallback HTML/CSS mock, and Mermaid flows
-      - Evaluator axes are fixed in `core/prototyping/evaluatorReview.ts#ORDINAL_AXES` (information architecture / navigation flow / usability / functionality) and no longer authored as sidecar files
+      - Evaluator axes (information architecture / navigation flow / usability / functionality) are fixed by
+        the review validation the QFAI CLI applies (restated in `.qfai/assistant/skills/qfai-prototyping/references/reviewer-prompt.md`), not sidecar files
       - Runtime screenshots or rendered evidence when available
 
       ## Deliverables
@@ -741,7 +750,10 @@ agents:
       - Coverage plan and layer ownership
       - Test-case quality and traceability findings
       - **Coverage Depth Matrix** (per spec, using the template in the depth checklist reference).
-        Destination: `.qfai/evidence/atdd-<spec-id>.md` from the ATDD stage onward. During SDD there is
+        Destination: `.qfai/evidence/coverage-depth-<spec-id>.md` from the ATDD stage onward — its own
+        file, because it has its own committed governance lifecycle separate from the committed
+        per-item TDD evidence, and the justification behind each `❌` is the input `qa-gatekeeper`
+        reads. During SDD there is
         no evidence artifact that holds it, so report depth gaps as findings instead of producing the
         matrix format.
       - Volume estimate and risk notes
@@ -995,6 +1007,22 @@ agents:
       - .qfai/assistant/catalog/test-layers.md
       - .qfai/specs/spec-\*/09_delta.md
       - Validation evidence and gate results
+      - `.qfai/specs/<spec-id>/tdd/test-list.md` — the ledger, for the row under review
+      - The per-item evidence file that row's `Layer` owns: `.qfai/evidence/implement-<spec-id>.md`,
+        or `.qfai/evidence/atdd-<spec-id>.md` for an `E2E` / `API` / `Integration` row
+
+      **Validate evidence is a completion-gate input, not an item-cycle one.** When
+      this role is routed inside an item cycle — `/qfai-atdd` stage gate P1c hands a
+      single row to `/qfai-implement` and that run's reviewers gate its checkpoint —
+      `.qfai/report/validate.log`, the coverage reports and runtime evidence are P5/P6
+      artifacts of the calling stage and do not exist yet. Requiring them there
+      stopped the first branch-1 row at `refactor`, which Phase Red does not
+      re-select, so the calling stage never reached P2. Judge the row's own
+      phase-authored evidence; the completion gate is where the rest is owed. **The
+      two inputs above are what makes that possible** — without the ledger and the
+      evidence home its `Layer` selects, this role cannot identify the artifact it is
+      being asked to judge, and falls into its own Stop condition ("Required evidence
+      ... missing") on a correct branch-1 or branch-2 row.
 
       ## Deliverables
 
@@ -1022,7 +1050,7 @@ agents:
 
       - [ ] Review verdict is explicit
       - [ ] Findings cite concrete artifacts or evidence
-      - [ ] Every finding declares `Severity:` and `Traces to:`; no blocking finding has `Traces to: none`
+      - [ ] Every finding declares `Severity:` and `Traces to:`; no blocking finding traces to `none` or `record:*`
       - [ ] Required gates and residual risks are recorded
 
       ## When to use
@@ -1206,6 +1234,17 @@ agents:
       - .github/instructions/principles.instructions.md
       - Diff of changed files
       - `.qfai/contracts/api/**` and `.qfai/contracts/db/**`
+      - `.qfai/specs/<spec-id>/tdd/test-list.md` — the ledger, for the row under review
+      - The per-item evidence file that row's `Layer` owns: `.qfai/evidence/implement-<spec-id>.md`,
+        or `.qfai/evidence/atdd-<spec-id>.md` for an `E2E` / `API` / `Integration` row
+
+      **The last two are what the `Audited evidence hash` is computed over.** This
+      role records that hash itself, over the row's phase-authored fields — and those
+      live in a committed per-item evidence file so a fresh clone can reproduce the
+      audit. Without the ledger and the evidence home the row's
+      `Layer` selects, this role cannot identify its own audit subject: the hash goes
+      missing and gate items 10-11 stop, or the orchestrator computes it instead,
+      which is the one thing the contract says must not happen.
 
       ## Deliverables
 
@@ -1230,7 +1269,7 @@ agents:
 
       - [ ] Review verdict is explicit
       - [ ] Findings cite concrete artifacts or evidence
-      - [ ] Every finding declares `Severity:` and `Traces to:`; no blocking finding has `Traces to: none`
+      - [ ] Every finding declares `Severity:` and `Traces to:`; no blocking finding traces to `none` or `record:*`
       - [ ] Required gates and residual risks are recorded
 
       ## When to use
@@ -1270,7 +1309,7 @@ agents:
       - Audit frontend changes for correctness and user-facing risk.
       - Audit layout sanity, interaction usability, and accessibility guardrails.
       - Audit visual design, token alignment, and service-level UX coherence.
-      - Reconcile sidecar artifacts (selected anchor, strategy, screen contracts), design tokens, mermaid flows, and rendered output consistency.
+      - Reconcile sidecar artifacts (screen contracts), design tokens, mermaid flows, and rendered output consistency.
         HTML mock is optional fallback evidence only. Design tokens are supporting input.
       - For UI implementation, compare rendered output against `.qfai/contracts/design/prototype-handoff.yaml`, canonical prototype screenshots, HTML snapshots, and `.qfai/prototypes/winner/index.html`.
       - Reject prototype parity when implementation loses CTA hierarchy, spacing rhythm, information density,
@@ -1359,7 +1398,9 @@ agents:
 
       ## Ownership boundaries
 
-      - `delivery-planner` owns **item selection and item scope** — whether a ledger row's selector is a sufficient slice of its `TC-*` obligation. Do not adjudicate item scope here; a PASS on observation
+      - `delivery-planner` owns **item selection and item scope** — whether a ledger
+        row's selector is a sufficient slice of the obligation its `Layer` names
+        (`TC-Refs`, `US-Refs` or `CON-API-Refs`). Do not adjudicate item scope here; a PASS on observation
         evidence is explicitly scoped to that observation and never widens or ratifies item scope. See `.qfai/assistant/skills/qfai-implement/SKILL.md#precedence-between-delivery-planner-and-qa-gatekeeper`.
       - Refuse to evaluate RED/GREEN evidence while an unresolved `delivery-planner` scope REVISE is open on the same item.
 
@@ -1370,7 +1411,8 @@ agents:
       and the Depth Matrix counts case categories. A test that cannot fail otherwise
       clears every gate.
 
-      Require an `Oracle proof` on each item and **reject** it when:
+      Require an `Oracle proof` on each item **at a GREEN or completion gate**, and
+      **reject** it when:
 
       - the mutation is outside the code the item owns — breaking a shared helper
         proves the helper is used, not that this test discriminates;
@@ -1379,6 +1421,14 @@ agents:
       - the failing output names a selector other than the row's;
       - the recorded command differs from the `GREEN command`.
 
+      **At a RED observation the proof is a plan, and a plan is enough.** Branch 1's
+      RED is taken before any production behaviour exists, so there is nothing to
+      mutate: the item names the predicate it will break and the command it will run.
+      Requiring a demonstrated mutation there made a correct observed RED unable to
+      pass P1b and so unable to reach Phase Green — the phase that builds the code the
+      mutation needs. Judge the plan for whether it names this row's predicate and
+      selector; judge the demonstration once the behaviour exists.
+
       `equivalent-mutant` is acceptable **only** when the named contract clause is
       genuinely weaker than the obligation. It is an upstream gap: route it as an
       advisory / Change Request, do not send the implementer to strengthen an
@@ -1416,12 +1466,46 @@ agents:
       - "the suite is green" in place of the row's own GREEN.
 
       The one legitimate absence is the _RED not observable_ path: the obligation is
-      already satisfied by a sibling row, so the correct test passes first run. Then
-      require `Satisfied-by`, `Falsifiability command` and `Falsifiability result`
-      instead — never both forms, never neither. See
+      already satisfied by something already in the tree, so the correct test passes
+      first run. Then require `Satisfied-by`, `Falsifiability command` and
+      `Falsifiability result` instead — never both forms, never neither.
+
+      **On an `E2E` / `API` / `Integration` row, `Satisfied-by` need not be a sibling `TDD-NNNN`.** A
+      production **path and symbol** is equally valid there and is the normal answer
+      for a row whose surface no ledger row owns; rejecting it sends every such row to
+      `exception`, the terminal state the path exists to avoid. Judge it on whether it
+      answers "what would I mutate to falsify this row".
+
+      **A commit id alone does not answer it — REVISE.** A commit that touched
+      several routes and a helper names no single predicate, so the ownership check
+      below has no boundary to apply and would accept a mutation anywhere inside it.
+      The producer contract requires the symbol for this reason
+      (`../skills/qfai-atdd/references/red-provenance.md#the-three-branches-must`); a
+      commit recorded **alongside** the path and symbol is provenance and is fine.
+
+      **And the mutation may touch it.** The Oracle Strength Check rejects a mutation
+      outside the code the item owns, which on an `E2E` / `API` / `Integration` row is every
+      production predicate there is — the same sentence above says no ledger row owns
+      that surface. Applied literally, no branch-2 row could ever produce
+      falsifiability evidence that passes. On a handed-over row, **the predicate
+      `Satisfied-by` names is the owned code** for this check; anything else is still
+      out of bounds.
+
+      **On any other row the sibling row is still required** — production code
+      no ledger row owns is the anomaly case there, not a substitute. See
       `.qfai/assistant/skills/qfai-implement/references/red-not-observable.md` and
       `.qfai/assistant/skills/qfai-implement/references/red-admissibility.md`.
 
+      **A `Layer = E2E` / `Layer = API` row from `/qfai-atdd` is judged the same
+      way.** Its journey is often written after the surface the same cycle built, so
+      the falsifiability form is the expected evidence rather than a concession —
+      accept it, with the mutated predicate being one the journey actually asserts
+      on. What is **not** acceptable is the third outcome appearing by default: a row
+      routed to `exception` whose `DR-*` says only that the surface came first has
+      not shown that either branch was unavailable, and that is a REVISE. See
+      `.qfai/assistant/skills/qfai-atdd/SKILL.md#red-provenance-for-an-atdd-owned-row-must`
+      and `.qfai/assistant/skills/qfai-implement/references/execution-ledger.md#atdd-owned-rows`.
+
       Verdict scope: a PASS covers the observation for that round and nothing else. It
       does not ratify item scope and does not clear the completion gate.
 
@@ -1429,7 +1513,10 @@ agents:
 
       In addition to traceability-based coverage (US/TC/CON-API existence), verify the **depth** of test cases:
 
-      - Confirm a Coverage Depth Matrix exists (produced by `test-design-analyst`). Missing matrix: REVISE from the ATDD review cycle onward; on an SDD review cycle record it as a finding. See the scope note.
+      - Confirm a Coverage Depth Matrix exists at `.qfai/evidence/coverage-depth-<spec-id>.md` (produced by `test-design-analyst`).
+        Missing matrix: REVISE from the ATDD review cycle onward; on an SDD review cycle record it as a finding. See the scope note.
+        A matrix that exists only inside `.qfai/evidence/atdd-<spec-id>.md` is a **missing** matrix: that committed file is the
+        ledger's per-item evidence payload, not the dedicated matrix artifact whose justifications this gate reads.
       - Check that each US/TC has test cases for at minimum: normal path AND error/failure path.
       - Flag any US/TC that has only normal-path test cases as a coverage gap.
       - Reference: `.qfai/assistant/skills/qfai-atdd/references/test-case-depth-checklist.md`
@@ -1443,8 +1530,9 @@ agents:
       The Coverage Depth Matrix is an **ATDD-stage artifact**: it is defined in
       `.qfai/assistant/skills/qfai-atdd/references/test-case-depth-checklist.md`, listed as an ATDD
       Mandatory Output,
-      and written into `.qfai/evidence/atdd-<spec-id>.md`. `qfai-sdd` neither defines its layout nor
-      ships a section for it, so:
+      and written to `.qfai/evidence/coverage-depth-<spec-id>.md` — a committed governance path alongside
+      `implement-<spec-id>.md` and `atdd-<spec-id>.md`. Only run-scoped evidence remains ignored.
+      `qfai-sdd` neither defines the matrix layout nor ships a section for it, so:
 
       - Apply this check from the **ATDD review cycle onward**, where
         `.qfai/assistant/skills/qfai-atdd/SKILL.md` lists
@@ -1462,14 +1550,47 @@ agents:
       - .qfai/assistant/catalog/test-layers.md
       - .qfai/specs/spec-\*/09_delta.md
       - `.qfai/specs/spec-*/tdd/test-list.md` — the ledger row under review
-      - `.qfai/evidence/implement-<spec-id>.md` — the per-item RED/GREEN evidence this
-        role adjudicates. Both are listed because the Stop condition below ("target
-        artifacts are missing") is not checkable against an artifact this role was
-        never told to open.
-      - `.qfai/report/validate.log`
+      - **The per-item RED/GREEN evidence for the row under review — in the file its
+        `Layer` owns, and only that one.** `.qfai/evidence/atdd-<spec-id>.md`, under
+        `## Ledger rows advanced`, for a `Layer = E2E` / `Layer = API` / `Layer = Integration` row;
+        `.qfai/evidence/implement-<spec-id>.md` for every other row. Both are listed
+        because the Stop condition below ("target artifacts are missing") is not
+        checkable against an artifact this role was never told to open — but
+        requiring **both** makes that condition fire on a spec that legitimately has
+        one: a Unit-only spec never ran `/qfai-atdd`, and a spec whose rows are all
+        `E2E` / `API` / `Integration` has no implement file. Either way the gate would stop before
+        reading the evidence that does exist.
+        **The three below are required at a completion gate, not at a RED/GREEN
+        observation.** `/qfai-atdd` routes this role as blocking at stage gate P1b, and
+        validate output, coverage reports and runtime evidence are first produced at its
+        P5 and P6 — so requiring them there stopped a fresh run that had a perfectly
+        good RED pair, on artifacts its own ordering says cannot exist yet. At an
+        observation gate the row's own evidence above is the whole input.
+
+      - The scoped validate JSON for the spec under review — `validate.spec-<id>.json`
+        **beside the configured `output.validateJsonPath`**, not under a fixed
+        `.qfai/report/` — or the `run-*/` directory of the run that produced it, under
+        the configured `paths.outDir`. Read both from `qfai.config.yaml` the way the
+        SDD and discussion contracts do. A project that moved either output writes its
+        evidence where it said to, and looking for it at the default path reported a
+        missing artifact and stopped completion on a validate run that had succeeded
+        and left everything it owed. **Not `validate.log`**: it and the run-log pointer are shared by every
+        run, scoped or not, and nothing serializes them, so a sibling stage validating
+        at the same time overwrites what this one wrote — a failing run followed by a
+        sibling's success reads as this spec's PASS
       - `.qfai/report/specs-coverage/spec-*.md`
       - Runtime evidence and prototyping evidence artifacts
 
+      **Branch 3 gets its own verdict.** The observation gate admits an observed RED
+      or a falsifiability trio and calls anything else "never neither" — but a genuine
+      branch-3 row _has_ neither, by the finding that put it there. Judged by the two
+      forms it can only be REVISE, and skipping the gate leaves the stage's completion
+      condition unmet, so the row could not close either way. Judge these on their own
+      terms: a `DR-*` that records **what could not be observed and why each branch was
+      unavailable**, PASS or REVISE on that. A missing `DR-*`, or one that names no
+      unavailability, is still REVISE — this is a third form of evidence, not an
+      exemption from having any.
+
       ## Deliverables
 
       - Gate decision (PASS / REVISE) with rationale
@@ -1478,7 +1599,10 @@ agents:
 
       ## Stop conditions
 
-      - Required evidence, governing specs, or target artifacts are missing.
+      - Required evidence, governing specs, or target artifacts are missing — judged
+        against what the invoking phase requires, per the note above the last three
+        inputs. At a RED/GREEN observation that is the row's own evidence; at a
+        completion gate it is all of them.
       - The request requires implementation or file editing instead of independent review.
       - The issue falls outside this review domain and must be rerouted to another specialist first.
 

package/assets/init/.qfai/assistant/manifest/agent-routing.yml

@@ -75,11 +75,34 @@ routing:
       # the row is allowed to proceed to `build`.
       - id: red
         iteration: per-ledger-item
-        mandatory_agents: [qa-gatekeeper]
-        conditional_agents: []
+        # `qa-gatekeeper` is **conditional**, not mandatory. `/qfai-atdd`
+        # invokes this phase for step 3a alone when a new route or export
+        # needs its seam before a RED can be taken — the row has no RED yet,
+        # which is the whole reason for the trip. Listed as mandatory, the
+        # gate had no assertion failure to judge and could only return
+        # REVISE, so `SKILL.md`'s "do not route `qa-gatekeeper` for a
+        # seam-only invocation" contradicted this manifest and the round trip
+        # stopped. It stays blocking: whenever a RED *is* submitted, its
+        # verdict decides.
+        mandatory_agents: []
+        # The production owners are conditional here, not absent. Two steps
+        # in this phase touch production source before any RED exists, and
+        # the orchestrator may not implement (`SKILL.md` Orchestrator
+        # Protocol): step 3a's minimal seam, which a new-surface row needs
+        # before its failure is an assertion rather than a 404, and step 3c's
+        # falsifiability mutation for a handed-over row whose evidence is not
+        # written yet. Without them the phase had `qa-gatekeeper` alone and
+        # neither step had anyone to perform it.
+        conditional_agents: [qa-gatekeeper, frontend-engineer, backend-engineer]
         parallel_groups: []
         blocking_agents: [qa-gatekeeper]
-        rerun_policy: failed-agents-only
+        # `changed-scope-dependents`: the gatekeeper's REVISE here is usually
+        # *about* the seam or the mutation — it touched code the row does not
+        # own, or the selector did not fail. Re-running only the agent that
+        # returned non-PASS re-judges an unchanged artifact and returns the
+        # same REVISE, so the row never leaves `red`. Whoever wrote the
+        # production edit has to be rerun with it.
+        rerun_policy: changed-scope-dependents
       - id: build
         iteration: per-ledger-item
         mandatory_agents: [qa-gatekeeper]
@@ -121,6 +144,49 @@ routing:
         parallel_groups: []
         blocking_agents: [test-design-analyst]
         rerun_policy: failed-agents-only
+      # Stage gate P1b. `references/red-provenance.md` branch 1 requires
+      # `qa-gatekeeper` to confirm the RED *before any production code exists*,
+      # which is the same rule `qfai-implement` applies to its own rows — and
+      # there was no phase here to submit that to, so the instruction named a
+      # routing phase this skill did not have. It must sit before
+      # `implementation`: after the surfaces are built there is nothing left to
+      # watch fail.
+      - id: red
+        # `delivery-planner` is blocking here, ahead of `qa-gatekeeper`:
+        # `qfai-implement/SKILL.md` makes it the only authority on whether a
+        # selector covers a sufficient slice of its obligation, and requires a
+        # scope REVISE to be settled BEFORE the RED is submitted. Approving the
+        # RED first leaves the planner only "keep the PASS and open a new row",
+        # which cannot repair a handoff taken at the wrong granularity.
+        #
+        # `qa-gatekeeper` is **conditional**, not mandatory: it judges the rows
+        # that have evidence at this gate — the branch 1 ones. A branch 2 row's
+        # payload is its falsifiability trio, which by design does not exist
+        # until P4b, and the role stops when a row's evidence is missing. Listed
+        # as mandatory it therefore stopped a run whose rows are all branch 2
+        # before it could reach the P4b handoff that produces the trio: the gate
+        # blocked on the absence of something it is the reason for. It stays
+        # blocking — when it is routed, its verdict decides.
+        #
+        # `iteration: per-ledger-item`, matching this manifest's
+        # `qfai-implement` red phase. The default is `per-invocation`, which
+        # routes each agent once for the whole ledger — so
+        # `acceptance-test-engineer` would leave several deliberate REDs open at
+        # once and `qa-gatekeeper` would never see a row in its own RED state,
+        # neither of which is the one-row-at-a-time loop P1b/P1c require.
+        iteration: per-ledger-item
+        mandatory_agents: [delivery-planner, acceptance-test-engineer]
+        conditional_agents: [qa-gatekeeper]
+        parallel_groups: []
+        blocking_agents: [delivery-planner, qa-gatekeeper]
+        # `changed-scope-dependents`, not `failed-agents-only`: a
+        # `delivery-planner` REVISE here means the selector covers too little
+        # of its obligation, and the repair is `acceptance-test-engineer`
+        # splitting the test — then a fresh `qa-gatekeeper` verdict on the new
+        # RED. Re-running only the agent that failed would have the planner
+        # re-read an unchanged selector and return the same REVISE, or leave
+        # the previous gatekeeper PASS standing over a test that changed.
+        rerun_policy: changed-scope-dependents
       - id: implementation
         mandatory_agents: [acceptance-test-engineer]
         conditional_agents: []