qfai 2.1.0 → 2.1.2

package/assets/init/.qfai/assistant/skill/qfai-verify/references/verify-output-contract.md

@@ -1,23 +1,94 @@
 # Verify Output Contract — `.qfai/report/verify.json`
 
+## Contents
+
+- Verdict file
+- Per-gate results
+- CI-only checks
+- Scope
+- Example and rules
+
+## Verdict file
+
 `/qfai-verify` MUST write `.qfai/report/verify.json` at the end of the run. This file is the machine-readable verdict; the stage report is the human-readable account. No `qfai` command reads it, so an absent `verify.json` does not fail `npx qfai validate`.
 
-Canonical path: `.qfai/report/verify.json` (NOT `.qfai/output/`). Create the `.qfai/report/` directory if absent — it is the same directory `validate.json` is written to.
+Canonical path: `.qfai/report/verify.json`. Create the `.qfai/report/` directory if absent — it is the same directory `validate.json` is written to.
 
-`.qfai/output/verify.json` is the legacy location, history for projects created before the move. Never write there.
+| Field        | Type             | Required | Meaning                                                                                                                                                 |
+| ------------ | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `status`     | string           | yes      | `"PASS"` when every gate in scope passed, or is delegated to a CI check that is not red; `"FAIL"` otherwise. Only `"PASS"` satisfies a downstream gate. |
+| `scope`      | string           | yes      | Which stage's gate set this run covers. See the enum below.                                                                                             |
+| `flowId`     | string           | no       | The business flow this run targeted, when scoped to one (e.g. `"BF-0001"`).                                                                             |
+| `recordedAt` | ISO-8601 string  | no       | When the run completed.                                                                                                                                 |
+| `summary`    | string           | no       | One or two sentences an operator can read without opening the stage report.                                                                             |
+| `gates`      | array of objects | no       | Per-gate results: as set out below. Advisory; no reader gates on it today.                                                                              |
 
-| Field        | Type             | Required | Meaning                                                                                                  |
-| ------------ | ---------------- | -------- | -------------------------------------------------------------------------------------------------------- |
-| `status`     | string           | yes      | `"PASS"` when every gate in scope passed; `"FAIL"` otherwise. Only `"PASS"` satisfies a downstream gate. |
-| `scope`      | string           | yes      | Which stage's gate set this run covers. See the enum below.                                              |
-| `flowId`     | string           | no       | The business flow this run targeted, when scoped to one (e.g. `"BF-0001"`).                              |
-| `recordedAt` | ISO-8601 string  | no       | When the run completed.                                                                                  |
-| `summary`    | string           | no       | One or two sentences an operator can read without opening the stage report.                              |
-| `gates`      | array of objects | no       | Per-gate results: `{ name, status, command }`. Advisory; no reader gates on it today.                    |
+When the scope includes acceptance scaffolds or unfinished BF/AC acceptance
+bodies, an optional `summary` stays one or two short sentences naming remaining
+work, its owner or UNASSIGNED, and the detailed human-report reference. The
+five-field detail belongs in `verify-repo-gate`'s `## Report` section, not a
+new JSON field or table inside `summary`. Empty-body exemptions, verdicts and
+completion rules stay unchanged.
 
 `status` is a closed two-value enum: `"PASS"` / `"FAIL"`. There is no `"WARN"` — a run with only `warning` / `info` findings is `"PASS"` (waivers apply to those severities only). Any `error` finding makes it `"FAIL"`.
 
-`scope` is a closed enum. Write the one that matches the stage you were invoked for:
+## Per-gate results
+
+Each entry of `gates` is `{ name, status, command }`, plus these optional fields:
+
+| Field      | Type   | Meaning                                                                                                                           |
+| ---------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| `status`   | string | `"PASS"`, `"FAIL"`, `"UNRUN"` or `"DELEGATED"`. `"UNRUN"` is a gate with no command, launcher or environment; it is never a pass. |
+| `baseline` | string | On a `"FAIL"`: `"same"` when the base commit fails identically, `"different"` when it does not, `"unrun"` when it cannot run.     |
+| `reason`   | string | On an `"UNRUN"` gate, or a `baseline` of `"unrun"`: what is missing.                                                              |
+| `check`    | string | On a `"DELEGATED"` gate: the CI check that runs it.                                                                               |
+| `ci`       | string | On a `"DELEGATED"` gate: `"green"`, `"red"` or `"pending"`, the state of that check when the file is written.                     |
+
+## CI-only checks
+
+A gate the project's Standard commands declare `CI only: <check name>` is
+recorded `"DELEGATED"` with its `check` and `ci` for the candidate being evaluated.
+`check` names the actual CI check and `ci` its observed state.
+A `"red"` check makes the top-level `status` `"FAIL"` for that candidate.
+A `"pending"` one does not, and `summary` names it. A runnable local gate is
+never delegated to avoid running it. Retain an observed FAIL or
+UNRUN; neither becomes PASS or DELEGATED because a verification commit is wanted.
+
+A `"PASS"` verdict with pending delegated checks supports only the existing
+verification-commit allowance under a user instruction or project policy
+covering that commit and its paths. It does not establish formal completion or
+permission to push, create a pull request or merge. Every nondelegated gate
+must pass. A delegated red check stops transport of the same unchanged candidate.
+Explicit CI-only delegation covering a transport commit may instead carry actual
+changes addressing that failure through the existing planned fix into a new
+candidate, while HEAD still names the failed commit. Preserve the prior head,
+check, run and observed result as FAIL; never relabel that evidence pending.
+Report the actual fix and, after committing, the new head and resume condition.
+The new candidate remains unverified until its own CI results are observed.
+
+The stage report records the target, current head, run ID or URL when available,
+check, actual outcome and counts, blocker and resume condition. No run yet means
+no result; invent neither. `ci: "green"` needs actual passing evidence for that
+same target and head. Missing or mismatched evidence remains pending. Formal
+completion or merge waits for every required check to pass on the current head.
+Keep this evidence in the stage report and `summary`; add no verdict fields or states.
+
+A gate that fails identically on the base, or did not run and is not delegated, still makes the top-level `status` `"FAIL"`. The fields let a reader tell it from a failure the run caused.
+
+Keep the full CI receipt in the stage report, as
+`.qfai/assistant/step/common-gate-run/STEP.md#ci-evidence` requires. A branch
+overview or a confirmed closed cleanup SKIP does not replace actual verification
+or turn it into a behavioral PASS. Preserve failures for the current head;
+unknown identity or purpose remains unverified. The receipt adds no fields or
+states to this contract.
+
+## Scope
+
+`scope` is a closed enum. Write the gate set this invocation covers through
+execution or an explicitly declared matching CI-only check. Delegation never
+claims that the profile already ran; its check must perform the required scan
+and profile. A whole-repository scope still requires full validation. Write the
+one that matches the stage you were invoked for:
 
 | `scope`       | Written by                                                          | validate profile                                |
 | ------------- | ------------------------------------------------------------------- | ----------------------------------------------- |
@@ -28,6 +99,8 @@ Canonical path: `.qfai/report/verify.json` (NOT `.qfai/output/`). Create the `.q
 There is no `implement` value: the enum is closed at these three, and a run after
 `/qfai-implement` is recorded as `full`.
 
+## Example and rules
+
 Minimal conforming example for the prototyping gate:
 
 ```json
@@ -42,6 +115,12 @@ Minimal conforming example for the prototyping gate:
 
 Rules:
 
-- Never write `"status": "PASS"` without the command outputs that justify it. A `FAIL` verdict is a legitimate output — the gate downstream is supposed to stop.
-- Never write a `scope` you did not actually run. Writing `"prototyping"` after a `full` run is a false verdict, not a workaround — and the reverse is just as wrong: a `--profile verify` run is `scope: "full"`, not `scope: "atdd"`, because `atdd` means the ATDD gate set only.
+- A PASS gate needs actual command output or matching CI evidence. The existing
+  top-level pending-DELEGATED allowance supports only the covered verification
+  commit described above. A `FAIL` verdict is a legitimate output; downstream
+  work stops as its gate requires.
+- Never write a `scope` this invocation does not cover by execution or its
+  declared matching CI-only check. Writing `"prototyping"` for a `full` gate set
+  is a false verdict, not a workaround. A `--profile verify` gate is
+  `scope: "full"`, not `scope: "atdd"`; `atdd` covers the ATDD gate set only.
 - Do not add a `version` / `schemaVersion` field. No reader validates one, and a second version series in a distributed artifact is exactly what the distributed-surface rule forbids: the npm package version is the only version this surface has.

package/assets/init/.qfai/assistant/skill/web-research/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: web-research
 title: "Web Research Pipeline"
-description: "8-stage web research pipeline with MCP integration, caching, and citation generation."
+description: "8-stage web research pipeline with MCP integration, caching, and citation generation. Use when asked to research a topic on the web and report the findings with cited sources."
 argument-hint: "[query] [--max-depth N] [--yolo]"
 allowed-tools: [Read, Glob, Bash, Write, Task, Agent, WebSearch, WebFetch]
 roles: [Researcher, Analyst, FactChecker]
@@ -16,7 +16,7 @@ QFAI Skill Body (SSOT)
 
 ## /web-research — Web Research Pipeline
 
-[DRIFT-PROTOCOL:MANDATORY]
+[DRIFT-PROTOCOL:REQUIRED]
 
 ## User Questions (AskUserQuestion Protocol)
 
@@ -38,14 +38,6 @@ baseline overlap, the baseline governs.
 - The orchestrator may write the research artifact itself, or give independent searches to sub-agents that run in parallel.
 - It never approves its own work.
 
-### Capability Probe
-
-- No additional overrides.
-
-### Delegation Failure (Hard Stop)
-
-- No additional overrides.
-
 ## Work Orders Summary
 
 Every major research artifact must include a `## Work Orders Summary` table.
@@ -127,8 +119,9 @@ Configuration templates: `.qfai/assistant/skill/web-research/mcp-templates/playw
 
 ### 2.4 MCP Failure Recovery
 
-- Crash detection threshold: **< 10 seconds** runtime indicates abnormal termination.
+- Crash detection: notice an MCP server crash or a dropped connection within **10 seconds**.
 - On MCP server crash, fallback to built-in tools (WebSearch / WebFetch).
+- Tell the user that the MCP server is unavailable and that the built-in tools are in use.
 - Rate limit: detect HTTP 429 responses and honour `Retry-After` header with exponential backoff.
 
 ## 3. Security
@@ -150,10 +143,11 @@ The sanitizer is idempotent: applying it twice produces byte-identical output.
 Default policy: **default-deny**.
 
 - Only domains listed in the project allowlist may be fetched.
-- The allowlist is defined in `qfai.config.yaml` under `webResearch.allowlist`.
-- Unknown domains are logged and skipped; the pipeline continues with allowed sources.
+- The allowlist is a domain list in `qfai.config.yaml` under `webResearch.allowlist`, read by the agent; `qfai` does not parse it.
+- Unknown domains are logged with the blocked domain and skipped; the pipeline continues with allowed sources.
 - Redirect chains are followed only while all hops remain on allowlisted domains.
-  A redirect to a non-allowlisted domain is blocked and the fetch is rejected.
+  A redirect to a non-allowlisted domain is blocked at that target, the fetch is rejected,
+  and the redirect chain up to the blocked target is logged.
 
 ### 3.3 --yolo Flag and Security Gates
 
@@ -167,14 +161,14 @@ cannot be bypassed.
 
 Every pipeline execution produces a session log with **6 mandatory fields**:
 
-| Field        | Description                             |
-| ------------ | --------------------------------------- |
-| `session_id` | Unique identifier for this research run |
-| `query`      | The original search query               |
-| `timestamp`  | ISO-8601 start time                     |
-| `stages`     | Array of stage results with timing      |
-| `sources`    | List of fetched URLs with status codes  |
-| `citations`  | Final citation entries                  |
+| Field        | Description                                                             |
+| ------------ | ----------------------------------------------------------------------- |
+| `session_id` | Unique identifier for this research run                                 |
+| `query`      | The request and every search query issued                               |
+| `timestamp`  | ISO-8601 start time                                                     |
+| `stages`     | Stage results with timing, sanitization events and verification results |
+| `sources`    | List of fetched URLs with status codes and content hashes               |
+| `citations`  | Final citation entries                                                  |
 
 The session log is part of the research report, not a file of its own.
 
@@ -194,6 +188,9 @@ Risk-based gating strategy:
 - **Low-risk queries**: Auto-approve. No human gate required.
 - **High-risk queries** (e.g., medical, legal, financial): Gate before cite stage.
   Human must confirm source selection and extracted claims.
+- **A high-risk conclusion** is not applied to code until a human has reviewed it.
+  The gate blocks and shows the diff the conclusion would produce together with its citations.
+  A low-risk conclusion is applied without blocking.
 - `--yolo` flag is **ignored** for security gates (see Section 3.3).
 
 Risk classification is determined by query topic analysis and domain sensitivity rules.
@@ -212,7 +209,7 @@ Default TTL: **24 hours** (24h).
 
 - Entries older than TTL are marked stale and re-fetched on next access.
 - Staleness is tracked per-entry; partial cache invalidation is supported.
-- TTL is configurable via `qfai.config.yaml` under `webResearch.cache.ttl`.
+- TTL is configurable via `qfai.config.yaml` under `webResearch.cache.ttl`, read by the agent; `qfai` does not parse it.
 
 ### 7.3 Storage
 
@@ -235,8 +232,9 @@ the session log as the coordination artifact.
 
 When the search stage returns no results:
 
-- Log "no sources found" to the session log.
-- Return a zero-result response with the original query for user review.
+- Log "no web sources found" to the session log.
+- Report "no web sources found" to the user together with every search query issued, for user review.
+- Generate no citations: the citation block stays empty, and nothing is cited from memory or from a source that was not fetched.
 - Do not proceed to fetch/extract stages.
 
 ### 9.2 Fetch Failure Isolation
@@ -245,14 +243,19 @@ Each URL is fetched independently. A fetch failure for one URL does not
 abort the pipeline. Failed URLs are logged and excluded; the remaining
 successful fetches produce a partial result.
 
+When every fetch fails, no partial result exists. Report that every fetch failed,
+with the failure reason (status code or timeout) for each URL, and do not run the
+extract stage.
+
 This isolation ensures that transient network errors or single-domain
 outages do not block the entire research pipeline.
 
 ### 9.3 Rate Limiting
 
 - Detect HTTP 429 (Too Many Requests) responses.
-- Read and honour the `Retry-After` header.
-- Apply exponential backoff with jitter for retries.
+- Read and honour the `Retry-After` header: retry only after the delay it gives.
+- Apply exponential backoff with jitter for further retries.
+- Log each rate-limit event to the session log with the 429 status, the delay and the retry number.
 
 ## 10. Conservative Defaults
 
@@ -278,7 +281,8 @@ SKILL.md files follow a **progressive disclosure** loading strategy:
 ### 11.1 Invalid SKILL.md Handling
 
 If the YAML front-matter is **invalid** or produces a **parse error** (malformed
-YAML), the loader reports the error to the session log and activates
+YAML), the loader reports the parse error with its details (the YAML error
+message and its location) to the session log and activates
 **default behavior** as a fallback. The skill is still listed in the roster
 but operates with built-in defaults until the YAML is corrected.
 
@@ -296,15 +300,17 @@ rules apply:
 
 ## 13. Golden Task Evaluation
 
-**Golden task** sets are curated query-answer pairs used for regression
-evaluation. Each golden task is scored against 4 metrics:
+**Golden task** sets are curated query-answer pairs, each with its expected
+sources and citations, used for regression evaluation. Each golden task is
+scored against 4 metrics:
 
 - **Citation precision** — accuracy of generated citations.
 - **Coverage** — completeness of query facet coverage.
 - **Freshness** — recency of cited sources.
 - **Security hygiene** — sanitization pass rate.
 
-Golden task results are reported with the evaluation run.
+Each score is compared with its target in Section 5, and the scores and the
+comparison are reported with the evaluation run.
 
 ## Completion Contract (Shared)
 

package/assets/init/.qfai/assistant/skill/web-research/mcp-templates/brave-search/config.toml

@@ -1,6 +1,4 @@
-[mcp.brave-search]
+[mcp_servers.brave-search]
 command = "npx"
 args = ["-y", "@modelcontextprotocol/server-brave-search@0.6.2"]
-
-[mcp.brave-search.env]
-BRAVE_API_KEY = "${BRAVE_API_KEY}"
+env_vars = ["BRAVE_API_KEY"]

package/assets/init/.qfai/assistant/skill/web-research/mcp-templates/brave-search/mcp-config.json

@@ -1,9 +1,13 @@
 {
-  "brave-search": {
-    "command": "npx",
-    "args": ["-y", "@modelcontextprotocol/server-brave-search@0.6.2"],
-    "env": {
-      "BRAVE_API_KEY": "${BRAVE_API_KEY}"
+  "mcpServers": {
+    "brave-search": {
+      "type": "local",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-brave-search@0.6.2"],
+      "env": {
+        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
+      },
+      "tools": ["*"]
     }
   }
 }

package/assets/init/.qfai/assistant/skill/web-research/mcp-templates/firecrawl/.mcp.json

@@ -8,6 +8,5 @@
         "FIRECRAWL_API_URL": "https://api.firecrawl.dev"
       }
     }
-  },
-  "_comment": "Local npx mode is recommended for sensitive environments. Set FIRECRAWL_API_URL to your local instance URL for self-hosted deployment."
+  }
 }

package/assets/init/.qfai/assistant/skill/web-research/mcp-templates/firecrawl/config.toml

@@ -1,10 +1,10 @@
 # Firecrawl MCP - supports both hosted URL and local npx modes
 # Local npx mode: recommended for sensitive environments
 # Hosted mode: set FIRECRAWL_API_URL to https://api.firecrawl.dev
-[mcp.firecrawl]
+[mcp_servers.firecrawl]
 command = "npx"
 args = ["-y", "firecrawl-mcp@3.11.0"]
+env_vars = ["FIRECRAWL_API_KEY"]
 
-[mcp.firecrawl.env]
-FIRECRAWL_API_KEY = "${FIRECRAWL_API_KEY}"
+[mcp_servers.firecrawl.env]
 FIRECRAWL_API_URL = "https://api.firecrawl.dev"

package/assets/init/.qfai/assistant/skill/web-research/mcp-templates/firecrawl/mcp-config.json

@@ -1,11 +1,14 @@
 {
-  "firecrawl": {
-    "command": "npx",
-    "args": ["-y", "firecrawl-mcp@3.11.0"],
-    "env": {
-      "FIRECRAWL_API_KEY": "${FIRECRAWL_API_KEY}",
-      "FIRECRAWL_API_URL": "https://api.firecrawl.dev"
-    },
-    "_comment": "Local npx mode is recommended for sensitive environments. For hosted mode use https://api.firecrawl.dev"
+  "mcpServers": {
+    "firecrawl": {
+      "type": "local",
+      "command": "npx",
+      "args": ["-y", "firecrawl-mcp@3.11.0"],
+      "env": {
+        "FIRECRAWL_API_KEY": "${FIRECRAWL_API_KEY}",
+        "FIRECRAWL_API_URL": "https://api.firecrawl.dev"
+      },
+      "tools": ["*"]
+    }
   }
 }

package/assets/init/.qfai/assistant/skill/web-research/mcp-templates/playwright/config.toml

@@ -1,3 +1,3 @@
-[mcp.playwright]
+[mcp_servers.playwright]
 command = "npx"
 args = ["-y", "@executeautomation/playwright-mcp-server@1.0.12"]

package/assets/init/.qfai/assistant/skill/web-research/mcp-templates/playwright/mcp-config.json

@@ -1,6 +1,10 @@
 {
-  "playwright": {
-    "command": "npx",
-    "args": ["-y", "@executeautomation/playwright-mcp-server@1.0.12"]
+  "mcpServers": {
+    "playwright": {
+      "type": "local",
+      "command": "npx",
+      "args": ["-y", "@executeautomation/playwright-mcp-server@1.0.12"],
+      "tools": ["*"]
+    }
   }
 }

package/assets/init/.qfai/assistant/step/common-design-md/STEP.md

@@ -27,12 +27,17 @@ for it.
   lists it: `01_Context.md#Design Direction`, the reference registries in
   `04_Sources.md`, and the `uiux/` sidecars. For an imported tree, the surface
   the import source names, or the user's answer.
+- The questions behind those answers:
+  `.qfai/assistant/skill/qfai-discussion/references/design-dna-intake.md`.
 - The schema and validation rules:
   `.qfai/assistant/skill/qfai-prototyping/references/design-md-spec.md`.
 - The archetype catalog:
   `.qfai/assistant/skill/qfai-sdd/references/design-md-brand-catalog.md`.
 - The starting sample:
   `.qfai/assistant/skill/qfai-prototyping/templates/DESIGN.md.sample`.
+- The patterns that mark a design as generated, and their displacement table:
+  `.qfai/assistant/skill/qfai-sdd/references/design-anti-patterns.md`. Read it
+  for § Author and validate step 5.
 
 ## Author and validate
 
@@ -51,10 +56,12 @@ for it.
 4. **Parse and validate.** `parseDesignMd(text)` must succeed; pass its `data`
    to `validateDesignMd` and halt on any issue. Both are exported from the
    `qfai` package entry.
-
-The retired per-aspect brand contracts are not regenerated; their content lives
-in `DESIGN.md`
-(`.qfai/assistant/skill/qfai-sdd/references/ui-design-contract-normalization.md#removed-yaml-contracts-permanent`).
+5. **Check the finished file against the pattern list.** Review root
+   `DESIGN.md` against every aspect of
+   `.qfai/assistant/skill/qfai-sdd/references/design-anti-patterns.md` and its
+   Displacement section. A token that prescribes a listed pattern fails unless
+   `01_Context.md#Design Direction` asks for it. Name the pattern in the
+   finding, replace the value, and check the file again.
 
 ## Check before building
 
@@ -77,7 +84,8 @@ it, edit it; the next iteration is built from it.
 Read first: the flow's classified surface set and root `DESIGN.md`. The step
 passes when the flow is not on a visual prototyping surface, or when root
 `DESIGN.md` exists, is not the unreplaced sample, and parses and validates with
-no issue. The pass names the surface set and the validation result.
+no issue and shows no listed pattern that the recorded direction does not ask
+for. The pass names the surface set and the validation result.
 
 ## Writes
 
@@ -87,5 +95,7 @@ no issue. The pass names the surface set and the validation result.
 
 ## Gate
 
-`DESIGN.md` parses and validates with no issue, and no value was written that
-the recorded direction or the named theme does not supply.
+`DESIGN.md` parses and validates with no issue, no value was written that
+the recorded direction or the named theme does not supply, and no token
+prescribes a pattern from `design-anti-patterns.md` that the recorded direction
+does not ask for. A reviewer fails the gate by naming the pattern.

package/assets/init/.qfai/assistant/step/common-gate-run/STEP.md

@@ -26,35 +26,111 @@ Neither is restated here.
   globs.
 - The launcher the preflight established, for a qfai command
   (`.qfai/assistant/rule/shared-skill-operating-baseline.md#canonical-qfai-launcher-mandatory`).
+- `.agents/rules/temporary-files.md`, when this step writes captured output or a script to a
+  file.
+- `.agents/rules/api-budget.md`, when this step reads CI state or the project's items through
+  the forge's API.
 
 ## Procedure
 
-1. **Resolve the launcher once per stage.** Before the first qfai gate, run the
+1. **Determine applicable gates before resolving commands.** Use the calling
+   stage's scope and the project's declared scope. Do not narrow the gate set
+   from the diff alone. Decide whether the conditional `Build` (if relevant)
+   and `Pack / distribution` (if distributed) gates apply from those scopes.
+   When a condition is false, omit its gate from `gates` and record the reason
+   in the stage report. A required gate with a missing command, launcher or
+   environment remains UNRUN.
+2. **Resolve the launcher once per stage.** Before the first qfai gate, run the
    launcher preflight. Where it fails, every qfai gate is UNRUN: record it as a
    blocker and stop.
-2. **Resolve the command.** A qfai gate is the validate profile and scope the
+3. **Resolve the command.** A qfai gate is the validate profile and scope the
    calling step names, for example
    `npx qfai validate --profile sdd --fail-on error --flow BF-NNNN`. A project
    gate is the matching entry of the Standard commands section, used as
    written. An entry that is missing makes the gate UNRUN: record it and route
    the gap as the rule says; never substitute a command from another stack.
-3. **Run it** on the tree the stage will hand to its reviewer, in the
+   An entry written `CI only: <check name>` instead of a command is not run
+   here: record the gate DELEGATED with that check name. Record its `ci` state
+   as `green`, `red` or `pending` from the pull request when one exists; with no
+   result yet, record `pending`.
+4. **Run it** on the tree the stage will hand to its reviewer, in the
    environment the `Runtime` and `Platform` rows declare.
-4. **Report** in the stage report: the exact
+5. **Report** in the stage report: the exact
    command, the exit code, the counts or outcome, the revision the run read,
    and for a validate run the `<paths.outDir>/validate.log` path and the
    `run-*/` directory its `run_log:` line names. The CLI writes that log on
    every run; shell redirection is not needed.
-5. **Read a validate result from its JSON** where the step selects work from
+6. **Read a validate result from its JSON** where the step selects work from
    it. The result is usable only when the file exists, its `profile` is the one
    run, and its `generatedAt` is no earlier than this run's start. Read `counts`
    for the verdict and `issues[].code` for each finding; the array is `issues`
    (`.qfai/assistant/skill/qfai-verify/references/validate-json-schema.md`).
-6. **On a failure**, classify each finding and repair only what this stage
+7. **On a failure**, classify each finding and repair only what this stage
    owns, then rerun the same gate on the same scope. A gate that failed and then
    passed with no change in between is a nondeterministic gate: record every
    run, in order.
 
+## CI evidence
+
+A branch overview locates runs; it is not a formal verification receipt.
+For each required verification, record the following in the stage report:
+
+- Target, current full head SHA, verification and intended purpose.
+- Workflow identity and name, event, run ID or URL containing the run ID, and run attempt.
+- Job identity and name, check identity and name, status and conclusion.
+- For test checks, actual test counts and the executed behavior they cover, with the job log or
+  artifact that proves them. Distinguish missing counts from zero executed tests.
+- For lint, build and other non-test checks, evidence of actual execution and
+  results from their logs or artifacts. Do not invent test counts for these checks.
+- Any closed-pull-request cleanup purpose, with the evidence that confirms the
+  pull request was closed and this run was selected for cleanup rather than verification.
+- Remaining blocker and resume condition, or an explicit statement that neither
+  remains. Record unavailable identity or purpose as unknown and unverified.
+
+Identify job IDs and check IDs separately where present; record their absence
+where the platform provides neither. An ID labelled only as check/job is
+ambiguous: record its identity as unverified until the job and check are distinguished.
+
+Use head, workflow, event, run attempt, job, check and purpose together. The same
+head SHA and check name do not make two runs the same verification. A
+`pull_request` event or later timestamp alone does not prove closed cleanup.
+A confirmed closed cleanup SKIP is neither a behavioral PASS nor an override
+of verification. A matrix job skipped by the declared selection policy may be
+legitimate, but its SKIP does not prove that its behavior ran.
+Retain an identified successful verification for its target and head when a
+later run is confirmed closed cleanup; the cleanup SKIP does not replace it.
+
+A green result for an old SHA does not verify the current head. A later failure
+for the same verification on the current head cannot be replaced by its older
+success. Keep the failure visible until a matching verification actually passes.
+Missing logs or unknown purpose leave execution unverified. For test checks,
+missing counts or zero executed tests do not prove behavioral coverage.
+These receipt details belong in the stage report; do not
+add fields or states to `verify.json`.
+
+### Synthetic worked example
+
+The following receipts are synthetic, not evidence from an actual repository.
+They concern test checks for the required unit suite.
+All target branch `example/topic` at full head
+`aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa`, with required verification
+`unit suite` and check name `tests`. Each run, attempt, job, check and log is
+identified separately.
+
+| Receipt              | Workflow identity / name; event  | Run ID / attempt | Job identity / name; check identity / name | Purpose and proof                                                                                 | Status / conclusion     | Actual counts and behavior                             | Log                                                                                          |
+| -------------------- | -------------------------------- | ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
+| Earlier verification | `71` / `CI`; `push`              | `91001` / `1`    | `81001` / `unit`; `71001` / `tests`        | Run configuration selects the unit suite                                                          | `completed` / `success` | 29 passed, 0 failed, 0 skipped; 29 unit tests executed | `receipts/unit-success.log` contains the test summary                                        |
+| Later verification   | `71` / `CI`; `workflow_dispatch` | `91002` / `2`    | `81002` / `unit`; `71002` / `tests`        | Run configuration selects the same unit suite                                                     | `completed` / `failure` | 28 passed, 1 failed, 0 skipped; 29 unit tests executed | `receipts/unit-failure.log` contains the failing test and summary                            |
+| Closed cleanup       | `72` / `Cleanup`; `pull_request` | `91003` / `3`    | `81003` / `unit`; `71003` / `tests`        | Payload action is `closed`, target state is closed, and a selection job log confirms cleanup only | `completed` / `skipped` | 0 passed, 0 failed, 0 executed; no unit test coverage  | `receipts/cleanup-selection.log` records the selection; the skipped test job has no test log |
+
+The required unit verification remains FAIL after the later verification. The
+cleanup SKIP neither clears it nor proves the unit behavior passed. Resume with
+the actual repair and a matching verification on the resulting current head.
+
+For a test check, if an actual reported run has only a head and check name, its missing workflow,
+event, attempt, job, purpose, counts and logs remain unknown. Record it as
+unverified with those gaps as blockers; the synthetic rows do not fill them.
+
 ## Scope
 
 - A flow-scoped gate covers that flow. A result for another flow or another
@@ -64,14 +140,51 @@ Neither is restated here.
   is neither repaired here nor counted as this gate's pass.
 - A repository-wide PASS is never claimed from one flow's result.
 
+### Selected-case execution
+
+When the caller selects a focused Test case, record its command arguments,
+cwd, file and case selection, actual runtime version, reporter, revision and raw output.
+Link the EX and source declaration to the full file/parent/case identity and
+observed body execution and terminal result. Keep exit, counts, containers
+and static scanner linkage separate; none proves that selected behavior ran.
+
+Zero selected executions or unidentifiable, skipped, TODO, cancelled or
+interrupted target results cannot close the focused phase. Retain the output,
+name the missing evidence, correct selection or observation and repeat it.
+Read
+`.qfai/assistant/skill/qfai-implement/references/red-admissibility.md#selected-case-execution`
+before judging a focused RED or ordinary success. A focused result establishes
+only its selected case; the existing verify run owns full collection coverage.
+This human receipt changes no gate status or JSON field and adds no runner.
+
 ## Outcomes
 
-| Outcome | Means                                                              |
-| ------- | ------------------------------------------------------------------ |
-| `PASS`  | The command ran on the reviewed tree and exited 0 with zero errors |
-| `FAIL`  | The command ran and reported an error or a non-zero exit           |
-| `UNRUN` | No command, no launcher, or no environment to run it in            |
+| Outcome     | Means                                                              |
+| ----------- | ------------------------------------------------------------------ |
+| `PASS`      | The command ran on the reviewed tree and exited 0 with zero errors |
+| `FAIL`      | The command ran and reported an error or a non-zero exit           |
+| `UNRUN`     | No command, no launcher, or no environment to run it in            |
+| `DELEGATED` | The project runs the gate in CI only, by the check its entry names |
 
-Only `PASS` satisfies a gate. `FAIL` and `UNRUN` go in the stop report with the
-reason and the retry condition. Do not weaken a profile, lower `--fail-on`,
+Only `PASS` satisfies a gate here. A `DELEGATED` gate is satisfied by its CI
+check, which runs on the pull request: it is not a pass, and it is not a
+failure until that check is red. `FAIL` and `UNRUN` go in the stop report with
+the reason and the retry condition. Do not weaken a profile, lower `--fail-on`,
 waive an error or invent a result to reach `PASS`.
+
+## A failure that predates the change
+
+Before a failing gate is attributed to the change, run it again on the base
+commit: the revision the change branched from, in a clean checkout that holds
+none of the change. Build it the same way, so a failure that needs a build is
+not read from a stale one.
+
+| Base result                            | Record                                       |
+| -------------------------------------- | -------------------------------------------- |
+| The same failures                      | `FAIL`, baseline `same`: it predates the run |
+| Fewer, other or no failures            | `FAIL`, baseline `different`: the run's own  |
+| The gate cannot run on the base either | `FAIL`, baseline `unrun`, with the reason    |
+
+The comparison is between the failing tests or findings, not the exit code.
+The result stays `FAIL`; a baseline of `same` explains it and never turns it
+into a pass. The run did not cause it, so it is reported and not repaired.