qfai 2.1.1 → 2.2.0

package/assets/init/.qfai/assistant/skill/qfai-sdd/references/ui-design-contract-normalization.md

@@ -15,33 +15,6 @@ A cli-only target has no root `DESIGN.md`; it still normalizes
 `/qfai-prototyping` records its handoff in
 `.qfai/prototype/final/handoff.json`. SDD does not author it.
 
-## Removed yaml contracts (permanent)
-
-The legacy per-aspect brand yaml contracts have been **removed**. The
-brand SSOT is now root `DESIGN.md` only, authored by `common-design-md`.
-Do not regenerate or reintroduce these files. Their content is subsumed by
-`DESIGN.md`:
-
-- brand archetype / voice / audience → `DESIGN.md` `brand` + `audience` +
-  `# Brand Philosophy` body.
-- negative references / things-to-avoid →
-  `audience.do_not_look_like` and the **Don't** subsection of
-  `# Brand Philosophy`.
-- color / typography / spacing / radius / shadow tokens →
-  `DESIGN.md` `visual.*` token tree.
-
-The following contracts MUST NOT be generated (the corresponding
-concepts do not exist in the current prototyping skill):
-
-- `evaluation-rubric.yaml` — evaluation axes are global constants; no
-  per-project rubric.
-- `evaluator-calibration.yaml` — calibration is the ordinal scale plus
-  a 200–500 word prose critique authored at review time.
-- `absorption-policy.yaml` — absorption / harvest concepts are not
-  used.
-- `selected-direction.yaml` — winner selection is not used; the latest
-  accepted iteration is always the artifact.
-
 ## Sidecar mapping
 
 The remaining UI-bearing sidecar maps to its contract as follows:
@@ -50,12 +23,14 @@ The remaining UI-bearing sidecar maps to its contract as follows:
 
 Project-specific anti-pattern notes live in `audience.do_not_look_like`
 of `DESIGN.md`. Evaluator axes are fixed by the review validation the
-QFAI CLI applies
-and are no longer authored as sidecar files.
+QFAI CLI applies.
 
 ## Normalization Rules
 
 - Preserve source IDs where available.
+- Normalize the sidecar's notes on displayed text into the screen's `supplements`
+  and `structure`, as the UI contract guide shapes them. Notes for the author or
+  the reviewer are not displayed text and are not copied into either key.
 - Convert prose into machine-readable arrays or objects.
 - Reject placeholder text instead of copying it into contracts.
 - Frame negative references in `audience.do_not_look_like` as

package/assets/init/.qfai/assistant/skill/qfai-sdd/templates/change-request.md

@@ -11,5 +11,42 @@ Record a change request as one row in `<paths.specsDir>/decisions.md`. The row h
 - Describe the actual contradiction and its source in `Content`. In `Approach`, state the proposed correction, affected work, and the gate that proves it is applied, inside the form stated at the top of `templates/spec/decisions.md`. Keep both cells concise enough to review as a table row.
 - Append the row only once the user approves the change, at `WIP`, and record in `Approach` who approved it, when, and the option chosen. Move it to `DONE` only after the owner rerun, affected artifacts, and validation evidence are complete. Use `SUPERSEDED (by DEC-NNNN)` when a later decision replaces the row, and `PARTLY SUPERSEDED (by DEC-NNNN)` when it replaces only part of it.
 - Append a declined change at `REJECTED`, recording in `Approach` who declined it and when. It authorizes no edit.
-- After appending, change only `Status`. Never rewrite `ID`, `Content`, or `Approach`, and never delete the row. A row the base holds at DONE authorizes nothing at any Status, so a later change needs a new row. If its scope or proposed correction changes, append a new decision row and supersede the old one.
+- After appending, change only `Status`, apart from the drift protocol's
+  explicit branch-added decision renumbering or published decision prefix
+  recovery. Keep inherited ID, Content and Approach fixed, and never delete a
+  row. A row the base holds at DONE authorizes nothing at any Status, so a later
+  change needs a new row. If its scope or proposed correction changes, append a
+  new decision row and supersede the old one.
 - Keep open questions in `<paths.specsDir>/open-questions.md`. Use the same four columns there, with `OQ-NNNN` IDs and the statuses permitted by that template.
+
+## Published decision prefix recovery
+
+Use the same four-cell row only after actual approval covers this specific
+recovery. Read `.qfai/assistant/rule/drift-protocol.md#published-decision-prefix-recovery`
+for eligibility, byte boundaries, pre-write checks and stop conditions. Generic
+protocol approval and a diagnostic suggestion do not authorize a target.
+
+- Content names the target's repository-relative file and the unique target
+  DEC ID. Approach records the published source commit, fixed base and unique
+  common ancestor, with evidence the target is absent from the latter two and
+  the source commit is a current-HEAD ancestor.
+- Evidence names actual supporting files. Grounds records the recovery reason,
+  actual approval authority, old and new SHA-256 Approach digests, and the exact
+  approved `- Evidence: <actual file references> - Grounds: ` prefix, including
+  its trailing space. Use actual references in place of the placeholder.
+- The old digest matches the raw published source cell; the new digest matches
+  the prefix plus the complete original Approach. State the single-line valid
+  UTF-8 cell boundary: exclude only delimiter pipes and exactly one ASCII
+  padding space at each end. Decode no escapes and trim or normalize nothing.
+- State that original ordered, nonempty Residual risk and Rollback items are
+  valid. Preserve ID, Content, Status, the full original suffix and every other
+  row. Record the immediate pre-write uniqueness, unchanged-cell and old-digest
+  checks, and the required existing validation without an exemption.
+- Residual risk states the remaining observation and concurrency limits.
+  Rollback removes only the recorded prefix when the current new digest still
+  matches; otherwise it preserves the row and stops. Removal restores the
+  original validation failure. Do not reset, amend or force push.
+
+Inherited records, open-question rows, unavailable provenance, ambiguous byte
+boundaries, duplicate IDs, stale digests and any unapproved change stop recovery.
+Do not fill approval or execution fields with assumed answers or planned results.

package/assets/init/.qfai/assistant/skill/qfai-sdd/templates/contracts/ui-contract.sample.yaml

@@ -19,6 +19,8 @@ prototype:
       purpose: customer id field on the order create form
 screens:
   - id: order_create
+    # The one heading of the screen. A heading beyond it is a group heading
+    # under `structure`.
     title: Create Order
     route: /orders/new
     # primary_tasks: at least one entry required per screen (QFAI-AUD-001).
@@ -36,6 +38,9 @@ screens:
         label: Correct a rejected field
         acceptance: the field-level error clears and submit re-enables
       - id: t3
+        label: Keep the order for later
+        acceptance: the order appears under /orders/drafts and the form keeps what was entered
+      - id: t4
         label: Abandon the draft
         acceptance: navigating away discards the draft and returns to /orders
     elements:
@@ -51,13 +56,55 @@ screens:
         required: true
         validations:
           - must be non-empty
-      - id: submit_button
-        label: Submit
-        type: button
-        required: true
-        validations: []
     actions:
       - id: submit_order
         label: Submit order
         kind: submit
         effect: navigates to /orders and shows the created row
+      - id: save_draft
+        label: Save draft
+        kind: submit
+        effect: stores the order under /orders/drafts, stays on the form and keeps what was entered
+      - id: discard_draft
+        label: Discard draft
+        kind: navigate
+        effect: navigates to /orders without storing the order
+    # structure (optional): the groups the screen is read in, in reading order.
+    # `tasks` are primary_tasks ids, `members` are elements/actions ids, and
+    # `heading` is the displayed heading of the group; leave it out for a group
+    # that shows none. Without `structure` the screen shows no heading beyond
+    # its title. An id belongs to one group.
+    structure:
+      - id: g_customer
+        heading: Customer
+        tasks: [t1, t2]
+        members: [customer_id_input]
+      - id: g_items
+        heading: Items
+        tasks: [t1, t2]
+        members: [item_code_input]
+      - id: g_commit
+        tasks: [t1, t3, t4]
+        members: [submit_order, save_draft, discard_draft]
+    # supplements (required): every text the screen shows beyond its title,
+    # group headings and labels. Field validation messages are the exception;
+    # they belong to the element's `validations`. `[]` says the screen shows
+    # none. `near` is an elements/actions/structure id, `when` is one of
+    # default, empty, loading, error, success, and `why` says what the user
+    # could not know or do without the text, and why a label or the structure
+    # cannot carry it.
+    #
+    # There is no supplement that restates what "Save draft" does: the label
+    # says it. What the label cannot say is where the draft went and what a
+    # failed save means, so those two are declared.
+    supplements:
+      - id: sp_draft_saved
+        near: save_draft
+        when: success
+        text: Saved to Drafts
+        why: After the click the user cannot see where the order went; the label names the action, not the place its result is kept.
+      - id: sp_draft_not_saved
+        near: save_draft
+        when: error
+        text: Not saved. Your entries are still here. Try again.
+        why: A failed save leaves the user unsure whether work was lost and what to do; the label says nothing about failure.

package/assets/init/.qfai/assistant/skill/qfai-sdd/templates/spec/decisions.md

@@ -13,6 +13,18 @@ No item is empty, and only the last two may take `none — <reason>`. What a
 kind of row must state in its Approach, such as a change request's proposed
 correction, goes inside these items. Write a `|` inside a cell as `\|`.
 
+Use this form for every new row. A passing validation result does not prove
+that every decision row follows it.
+
+A release approval, with `<...>` standing for the project's values, has this
+Content cell:
+
+Release <X.Y.Z> approved by <name> on <date>, option "<label>"
+
+and this Approach cell, written on one line and without backticks around it:
+
+- Evidence: file:CHANGELOG.md; command:<the release checks> → <result> - Grounds: <why the checks support the release> - Residual risk: none — <reason> - Rollback: <the steps that retract the release>
+
 A row that records a spec change following from an earlier approval may name
 that earlier decision by its ID in `Grounds:`, in place of a new answer from
 the user. Its `Evidence:` still lists what supports the change.

package/assets/init/.qfai/assistant/skill/qfai-triage/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: qfai-triage
-title: QFAI Triage (Requests that end without a change)
-description: "Use when invoked by name or handed a QFAI work order for a request that ends without a change to the project: a question to answer, a duplicate, missing information, a request to split, automated reports, a security report to take in, or an operation only a person can run."
+title: QFAI Triage (Requests that end without a tracked change)
+description: "Use when invoked by name or handed a QFAI work order for a request that ends without a tracked change: a question, a duplicate, missing information, a split, automated reports, a security report, an operation only a person can run, an operation the user named on finished work, or authorized cleanup of current-task temporary directories."
 argument-hint: "<the request, as it was reported>"
 allowed-tools: [Read, Glob, Grep, Write, Bash, TodoWrite, Task, Agent]
 roles:
@@ -24,12 +24,14 @@ steps:
   - triage-cluster
   - triage-security-intake
   - triage-handoff
+  - triage-owned-cleanup
+  - triage-operate
   - triage-close
 requires: []
 mode: execution-focused
 ---
 
-## /qfai-triage - Requests that end without a change
+## /qfai-triage - Requests that end without a tracked change
 
 [DRIFT-PROTOCOL:REQUIRED]
 
@@ -37,9 +39,13 @@ Run the entry check of
 `.qfai/assistant/rule/shared-skill-operating-baseline.md#workflow-run-entry-check-mandatory`
 first.
 
-This skill answers, closes, splits or hands over a request, and changes no
-file git tracks. Work the request needs is recorded as a follow-up request,
-never done here.
+This skill answers, closes, splits or hands over a request, or carries out an
+operation the user named, and changes no file git tracks. Work the request needs is recorded as a follow-up request,
+never done here except the exact current-task temporary cleanup that
+`triage-owned-cleanup` permits, after rechecking existing user authority and
+repository-local scope, and the named operation `triage-operate` runs. No other
+triage step executes an operation, and `triage-handoff` still waits for the
+person's reported result.
 
 ## Inputs
 
@@ -59,17 +65,19 @@ Invoked by name, run the steps in this order, as
 states: read `.qfai/assistant/step/<name>/STEP.md` for the current step only,
 run it, then move to the next.
 
-| Step                     | What it does                                                   | Skipped when                                                                     |
-| ------------------------ | -------------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| `triage-dedupe`          | Finds the same or a successor item, and links it               | The request neither may repeat an existing item nor rests on a premise that aged |
-| `triage-request-info`    | Asks for the facts the request is missing                      | The request states every fact its handling needs                                 |
-| `triage-investigate`     | Reads internals, history and outside facts to find the answer  | The documents and code as they stand answer the question                         |
-| `triage-answer`          | Answers, citing what shows the answer                          | The request asks no question                                                     |
-| `triage-decompose`       | Splits the request into child requests with their dependencies | The request is one piece of work                                                 |
-| `triage-cluster`         | Groups automated reports by signature                          | The request is not a set of automated reports                                    |
-| `triage-security-intake` | Takes a vulnerability report in privately                      | The request reports no exploitable weakness                                      |
-| `triage-handoff`         | Gives a person the steps of an operation only they can run     | The request needs no operation that only a person can run                        |
-| `triage-close`           | Records the outcome and each follow-up, and closes             | Only `triage-security-intake` ran: the fix follows it, so the request stays open |
+| Step                     | What it does                                                               | Skipped when                                                                     |
+| ------------------------ | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `triage-dedupe`          | Finds the same or a successor item, and links it                           | The request neither may repeat an existing item nor rests on a premise that aged |
+| `triage-request-info`    | Asks for the facts the request is missing                                  | The request states every fact its handling needs                                 |
+| `triage-investigate`     | Reads internals, history and outside facts to find the answer              | The documents and code as they stand answer the question                         |
+| `triage-answer`          | Answers, citing what shows the answer                                      | The request asks no question                                                     |
+| `triage-decompose`       | Splits the request into child requests with their dependencies             | The request is one piece of work                                                 |
+| `triage-cluster`         | Groups automated reports by signature                                      | The request is not a set of automated reports                                    |
+| `triage-security-intake` | Takes a vulnerability report in privately                                  | The request reports no exploitable weakness                                      |
+| `triage-handoff`         | Gives a person the steps of an operation only they can run                 | The request needs no operation that only a person can run                        |
+| `triage-owned-cleanup`   | Removes authorized current-task temporary directories and verifies absence | The request is not the specific repository-local cleanup the step permits        |
+| `triage-operate`         | Runs the operation the user named on finished work, and reports its result | The request names no operation                                                   |
+| `triage-close`           | Records the outcome and each follow-up, and closes                         | Only `triage-security-intake` ran: the fix follows it, so the request stays open |
 
 Invoked by name, the skill ends at this stage. It starts no other stage and
 routes no follow-up: a request to carry a follow-up out goes to `qfai-run`.
@@ -94,9 +102,13 @@ Follow `.qfai/assistant/rule/shared-skill-operating-baseline.md#completion-contr
 find changed when it started.
 
 The report states the outcome `triage-close` recorded and lists each follow-up
-request. It never says a change is done. It ends with a question listing the
-next actions, as `.agents/rules/user-questions.md` § 6 sets out; under a
-no-question mode, list them in the report instead.
+request. It never says a tracked change is done. `cleaned` says only that the
+named temporary targets were removed and their absence and unchanged tracked
+contents and index were verified; unfinished cleanup cannot use it.
+Ask for the next action only when
+proceeding requires the user's answer, as `.agents/rules/user-questions.md`
+§ 6 sets out. A closure-only report needs no question. Under a no-question mode,
+list any remaining actions instead.
 
 ## Default Autopilot Policy
 
@@ -105,6 +117,7 @@ no-question mode, list them in the report instead.
 
 project_memory:
 
-- Triage changes no tracked file; work it finds is a follow-up request.
+- Triage changes no tracked file; only `triage-owned-cleanup` and `triage-operate` execute an operation.
+- Other work it finds is a follow-up request.
 - A follow-up is recorded, never routed inside the run that found it.
 - A security report stays private until the fix is ready to disclose.

package/assets/init/.qfai/assistant/skill/qfai-verify/SKILL.md

@@ -106,10 +106,11 @@ Questions about this skill's own inputs or settings stay in its own output for
 the user to answer. This skill does not write `open-questions.md`.
 
 The completion message lists each decision the agents adopted, with its
-reason and any disagreeing position. None of them is put as a question. The
-message then ends with a question listing every next action, as
-`.agents/rules/user-questions.md` § 6 sets out; under a no-question mode it lists
-them in the report instead:
+reason and any disagreeing position. None of them is put as a question. Ask for
+the next action only when proceeding requires the user's answer, as
+`.agents/rules/user-questions.md` § 6 sets out. A completion-only report needs
+no question. Under a no-question mode, list any remaining actions instead.
+The applicable next actions are:
 
 - Proceed (recommended): create a PR on your hosting platform, with the
   verification report as its description.

package/assets/init/.qfai/assistant/skill/qfai-verify/references/context-load.md

@@ -1,9 +1,12 @@
 # Step 0 — Load context
 
+`<paths.specsDir>` and `<paths.contractsDir>` are the directories `qfai.config.yaml` sets.
+
 1. Read relevant **project policy** (if present):
-   - `.qfai/spec/01_policy/objective.md`
-   - `.qfai/spec/01_policy/initiative.md`
-   - `.qfai/spec/03_contract/tech.md`
+   - `<paths.specsDir>/01_policy/objective.md`
+   - `<paths.specsDir>/01_policy/initiative.md`
+   - `<paths.specsDir>/01_policy/principle.md`
+   - `<paths.contractsDir>/tech.md`
    - `.qfai/assistant/rule/agent-selection.md`. From
      `.qfai/assistant/rule/agent-selection.md` read the acting role's entry
      when a role needs one, not the whole file
@@ -14,9 +17,9 @@
    - `.qfai/assistant/rule/workflow.md` (or equivalent)
 
 3. Read existing artifacts for the current work item (if present):
-   - `.qfai/spec/02_business-flow/`
-   - `.qfai/spec/03_contract/`
-   - `.qfai/spec/decisions.md`
+   - `<paths.specsDir>/02_business-flow/`
+   - `<paths.contractsDir>/`
+   - `<paths.specsDir>/decisions.md`
 
    Do not use discussion-pack artifacts as verification inputs. Verify reads normalized specs, contracts, tests and code only.
 

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

@@ -1,10 +1,18 @@
 # Verify Output Contract — `.qfai/report/verify.json`
 
-`/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`.
+## Contents
+
+- Verdict file
+- Per-gate results
+- CI-only checks
+- Scope
+- Example and rules
 
-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.
+## Verdict file
 
-`.qfai/output/verify.json` is the legacy location, history for projects created before the move. Never write there.
+`/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`. Create the `.qfai/report/` directory if absent — it is the same directory `validate.json` is written to.
 
 | Field        | Type             | Required | Meaning                                                                                                                                                 |
 | ------------ | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -15,23 +23,72 @@ Canonical path: `.qfai/report/verify.json` (NOT `.qfai/output/`). Create the `.q
 | `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.                                                                              |
 
+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"`.
 
-Each entry of `gates` is `{ name, status, command }`, plus these optional fields:
+## Per-gate results
 
-| 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.                     |
+Each entry of `gates` is `{ name, status, command }`, plus these optional fields:
 
-A gate the project runs in CI only is recorded `"DELEGATED"` with its `check` and `ci`. A `"red"` check makes the top-level `status` `"FAIL"`. A `"pending"` one does not, and `summary` names it, so a reader sees what the run left to CI. A gate that can run here is never delegated to avoid running it.
+| 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. On a `baseline` of `"same"`: the failing test identifiers and the environment, in one or two sentences (see `verify-repo-gate`). |
+| `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.
 
-`scope` is a closed enum. Write the one that matches the stage you were invoked for:
+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                                |
 | ------------- | ------------------------------------------------------------------- | ----------------------------------------------- |
@@ -42,6 +99,8 @@ A gate that fails identically on the base, or did not run and is not delegated,
 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
@@ -56,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

@@ -119,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
@@ -142,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
 
@@ -159,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.
 
@@ -186,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.
@@ -204,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
 
@@ -227,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
@@ -237,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
 
@@ -270,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.
 
@@ -288,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": ["*"]
     }
   }
 }