qfai 2.1.2 → 2.2.0

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 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, or authorized cleanup of current-task temporary directories."
+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:
@@ -25,6 +25,7 @@ steps:
   - triage-security-intake
   - triage-handoff
   - triage-owned-cleanup
+  - triage-operate
   - triage-close
 requires: []
 mode: execution-focused
@@ -38,12 +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,
+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. That step rechecks existing user authority and
-repository-local scope before any deletion. No other triage step executes an
-operation, and `triage-handoff` still waits for the person's reported result.
+`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
 
@@ -74,6 +76,7 @@ run it, then move to the next.
 | `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
@@ -114,7 +117,7 @@ list any remaining actions instead.
 
 project_memory:
 
-- Triage changes no tracked file; only `triage-owned-cleanup` executes its bounded cleanup.
+- 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/references/verify-output-contract.md

@@ -36,13 +36,13 @@ completion rules stay unchanged.
 
 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.                     |
+| 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
 

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

@@ -1,7 +1,7 @@
 ---
 name: common-design-md
 owner: common
-purpose: "Author the root DESIGN.md from the recorded design direction when it is missing, validate it, and check it again before anything is built from it."
+purpose: "Author a missing root DESIGN.md or repair its authorized part from the recorded design direction, validate it, and check it again before anything is built from it."
 requires: []
 roles: [product-experience-architect]
 routing-profile: default
@@ -17,8 +17,8 @@ checks every literal of every iteration against them.
 
 Only to a flow on a visual prototyping surface: its classified surface set —
 `primary_surface` and every `secondary_surfaces` entry — names `web`, `mobile`,
-`desktop` or `mixed`. A cli-only target has no root `DESIGN.md`; skip this step
-for it.
+`desktop` or `mixed`. A cli-only target writes no root `DESIGN.md` and leaves
+any existing file unchanged; skip this step for it.
 
 ## Reads
 
@@ -41,18 +41,30 @@ for it.
 
 ## Author and validate
 
-1. **Stop on an unchosen brand.** A pack that records no design direction
-   leaves the brand unchosen. Brand intent is `hard-required`: ask for it, and
-   under `--auto` stop and name it. Never adopt the sample design.
-2. **Write only when the file is missing.** `npx qfai init` seeds the sample and
-   never overwrites it, and a project may have written its own. An existing file
-   is validated as it stands; an unreplaced sample is refused.
-3. **Author from the direction**, following
+1. **Stop on an unchosen brand.** For initial authoring
+   of a missing file, a pack that records no design direction leaves the brand
+   unchosen. Brand intent is `hard-required`: ask for it, and under `--auto`
+   stop and name it. Never adopt the sample design. For an existing valid file,
+   validation and authorized repairs that preserve its brand and tokens
+   require no new brand selection. A brand or token change needs the
+   authorization and source values in step 2.
+2. **Bound an existing-file repair.** Write a missing file from the recorded
+   direction. For an existing file, SDD triage must name its exact path and the
+   requested change, and a new WIP change request must authorize both. Apply
+   only the authorized change; preserve existing brand and tokens unless their
+   change is authorized and supported by recorded direction or named theme
+   values. Stop without writing unsupported values. Without that authorization,
+   validate the existing file without an overwrite; an inherited DONE row
+   authorizes no new change. An unreplaced sample is refused.
+3. **Author a missing file or the authorized fields of an existing file**,
+   following
    `.qfai/assistant/skill/qfai-sdd/references/design-md-authoring.md#output-mapping`:
    the intent fields first, then the archetype, then `brand.theme`, then the
    `visual.*` tokens taken from the named theme's published values
    (`.qfai/assistant/skill/qfai-sdd/references/design-md-authoring.md#taking-the-values-from-the-theme`).
-   Do not compose token values by taste.
+   Do not compose token values by taste. For a repair, record the source of each
+   changed value and leave unrelated content unchanged. Validation without an
+   authorized change writes nothing and does not repeat brand selection.
 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.
@@ -61,7 +73,8 @@ for it.
    `.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.
+   finding. For an existing-file repair, stop unless the authorized change
+   includes its replacement. Replace the value and check the file again.
 
 ## Check before building
 
@@ -77,7 +90,8 @@ Before anything is generated from `DESIGN.md`:
 3. On any of these, stop and fix `DESIGN.md` through § Author and validate.
 
 Once a prototyping loop has started, `DESIGN.md` is read-only for it. To change
-it, edit it; the next iteration is built from it.
+it, return to SDD for a triaged and authorized repair; the next iteration is
+built from the validated result.
 
 ## Passes when
 
@@ -89,13 +103,16 @@ for. The pass names the surface set and the validation result.
 
 ## Writes
 
-- Root `DESIGN.md`, only when it was missing.
+- Root `DESIGN.md`, when missing or only within an authorized existing-file
+  change.
 - In the stage report: the source of each brand field and the validation
-  result.
+  result; for a repair, the authorization and source of each changed value.
 
 ## Gate
 
 `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.
+does not ask for. An existing-file repair changes only its authorized part
+and preserves unrelated content. A reviewer fails the gate by naming the pattern.
+An unauthorized change also fails the gate.

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

@@ -188,3 +188,29 @@ not read from a stale one.
 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.
+
+### A suite whose result depends on timing or load
+
+A browser suite or another timing-dependent suite can fail differently from run
+to run, so one base run made under other conditions is not a fair comparison.
+
+- Run the gate on the base commit under the conditions of the run it is
+  compared with, and record the parallelism and the load of both runs in the
+  stage report. A comparison whose conditions are not recorded is not made.
+- Count a chain of failures once. A failure is folded into a chain only when
+  it follows an earlier failure of the same file and reads as a consequence of
+  it, such as a closed browser or a timeout. Match a failure with the base by
+  test identity, and a folded chain by its file.
+- Run alone the files that hold a failure the base run did not show. A failure
+  that passes alone but fails in the suite on the changed branch, and not on the
+  base under the same conditions, is reported as a possible order or
+  shared-state effect of the change, with a suspected cause, as
+  `.qfai/assistant/rule/references/gate-failure-autorepair.md#nondeterministic-gates`
+  says. It is left out of the comparison only after a full-suite rerun of the
+  changed branch under the same conditions that does not show it. Record every
+  run in order.
+- The baseline is still `same`, `different` or `unrun`, and the result is still
+  `FAIL`. A failure left out is not in the base set, so the `reason` of the gate
+  and the final report list each one with its result run alone and in the
+  full-suite rerun, and the user who decides whether to commit sees that list.
+  No other state or field is recorded.

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

@@ -53,5 +53,13 @@ The stage holds one session per run. The row goes in the stage report, under
 | confirmed | <ISO8601> | <ISO8601> | empty | none in flight | <n> | <n> |
 ```
 
-Only `confirmed`, `user-closed` and `no-question` authorize authoring.
-`Authoring began` is later than `Ended at`.
+The authoring endings are `confirmed`, `user-closed`, `no-question`, and
+conditionally `adopted`. For `adopted`, verify
+`.agents/rules/grilling.md#explicit-delegation-for-a-discussion`: actual user
+delegation with source, scope and authority; actual griller-to-author rounds
+with reasons and dissent; no open node or running lookup; all consumed required
+inputs present; and actual human authority for every reserved decision.
+Record these in the stage evidence, not as a fictional human option answer.
+`Ended at` and `Authoring began` are actual timestamps, with authoring later.
+A missing hard-required consumed input authorizes no authoring ending.
+Allowing authoring is not a completion or validation receipt.

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

@@ -12,6 +12,7 @@ Design, tests and code fit a project only when its facts are current. The
 contract this step serves is
 `.qfai/assistant/rule/workflow.md#policy-check-mandatory`:
 it runs once per run, at the start, and no affected work continues on stale policy.
+The ultra-light routes `answer-in-session` and `run-operation` do not run it.
 
 ## Reads
 

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

@@ -22,12 +22,27 @@ them; it is the procedure that applies them.
 
 ## Reads
 
-- **The reviewer set.** In a route, the specification review:
-  `requirements-reviewer`, joined by `architecture-reviewer` when a contract
-  changed; the code review of the whole diff: `implementation-reviewer`. On a
-  flow a UI contract with screens serves, `product-surface-reviewer` joins
-  either review. A parent skill invoked by name uses the reviewers its own
-  `## Review` section names, such as `qfai-discussion`'s.
+- **The reviewer set.** In a route, each review takes exactly these reviewers,
+  each once in that review, with no threshold to judge:
+  - one reviewer for its kind: `requirements-reviewer` for the specification
+    review, `implementation-reviewer` for the code review of the whole diff;
+  - `architecture-reviewer` too, only when the target holds a contract change
+    no earlier review of the route read;
+  - `product-surface-reviewer` too, only when the target holds a screen change
+    no earlier review of the route read: an edit to a UI contract's screen, or
+    to the code, tests or styles that render one, or to a path `uiux.surfacePaths`
+    declares. An uncertain case counts as a screen change
+    (`.qfai/assistant/skill/qfai-implement/references/ui-affecting.md#routing`);
+  - no other reviewer. A stage the plan marks with no review gets none.
+
+  A review whose target's only edits resolve the conflicts of a merge or a
+  branch update between sides that were each already reviewed gets no
+  reviewer. A side is reviewed when it is on the default branch or a review of
+  this route or its pull request covered its commits. A resolution that adds
+  content neither side had is not conflict-only. The stage report names the
+  merge and why no reviewer ran. A parent skill invoked by name uses the
+  reviewers its own `## Review` section names, such as `qfai-discussion`'s.
+
 - **The review target.** The specification review: every path and ID the
   stage it follows wrote or changed, and the source it was written from. The
   code review: the route's whole diff against the revision the route started
@@ -66,6 +81,7 @@ them; it is the procedure that applies them.
 ## Gate
 
 Every routed reviewer responded once, every finding is fixed or answered, and
-the stage report names each verdict and each answer. A finding the author
+the stage report names each verdict and each answer, or says why the review
+dispatched no reviewer. A finding the author
 cannot fix is in the stage's final report, and a critical decision has gone to
 the user.

package/assets/init/.qfai/assistant/step/discussion-interview/STEP.md

@@ -10,8 +10,10 @@ routing-profile: default
 # discussion-interview
 
 The core interview for concept, scope, stakeholders and constraints. It is a
-user session: the interview is this stage's work, so every decision is put to
-the user. An interview with no method is the agent deciding and reporting.
+user session by default: every decision is put to the user. The only delegated
+exception is `.agents/rules/grilling.md#explicit-delegation-for-a-discussion`,
+with actual user authority recorded before agent-to-agent rounds.
+An interview with no method is the agent deciding and reporting.
 
 ## Reads
 
@@ -78,13 +80,14 @@ Where each outcome is recorded is
 
 ## How the session ends
 
-A user session reaches four of the five endings the rule names — `adopted` ends
-only a delegated session — and three of them let authoring start:
+The default user session reaches four of the five endings. An explicitly
+delegated discussion may also end `adopted` under the master's conditions:
 
 | Ended         | What the user did                                                                                                | Authoring                                                                                                                                                                  |
 | ------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `confirmed`   | Confirmed on the session's own condition: no node open — the frontier empty **and** no fact lookup still running | Starts                                                                                                                                                                     |
 | `user-closed` | Said `proceed`, `done`, or words to that effect                                                                  | Starts. Lookups already running are finished and each decision still open becomes a labelled assumption, except one a document requires the user to make and record        |
+| `adopted`     | Explicitly delegated judgment for this scope                                                                     | Starts only after the recorded delegation conditions are met; no open node, lookup or unsupported human decision remains                                                   |
 | `no-question` | Nothing — `--auto` reached nobody                                                                                | Starts. Every node still open is registered — a decision, and a fact only the user holds, which nothing else can supply, and the open count is then what blocks completion |
 | `stopped`     | Said `stop`                                                                                                      | **Does not start.** Report every open decision as open and end the run                                                                                                     |
 
@@ -101,11 +104,14 @@ still there, so a decision they own is put again rather than assumed. The
 run consumes, and this is a decision the run is not permitted to take. The
 visual direction is the case here —
 `.qfai/assistant/skill/qfai-discussion/references/design-dna-intake.md` says
-only the user may choose a theme. The rule states the same bound from its side:
+only the user may choose a theme by default. Only an actual specifically
+applicable user instruction can override that request under the master's
+authority conditions; the agents' choice is never labelled `chosen_by: user`.
+The rule states the same bound from its side:
 closing the questions waives the agent's own uncertainty, never an
 authorization the user has not given.
 
-**`--auto` is the other case, and its answer is already written.** Nobody is
+**`--auto` without qualifying explicit delegation is the other case.** Nobody is
 there to put the question to, so the documented path holds: take the most
 conventional candidate, record it `chosen_by: assumption`, open it in
 `11_OQ-Register.md`, and author — the open count is what blocks completion.
@@ -136,8 +142,9 @@ runs.
 The reviewer confirms:
 
 - the stage report's `## Grilling Session` row shows the session ended before
-  authoring began, with `Ended` one of `confirmed`, `user-closed` or
-  `no-question`;
+  authoring began, with `Ended` one of `confirmed`, `user-closed`,
+  `no-question`, or `adopted` with the recorded explicit-delegation conditions
+  verified;
 - every decision the session settled is recorded where
   `.qfai/assistant/skill/qfai-discussion/references/oq-and-deferred-rules.md`
   says;

package/assets/init/.qfai/assistant/step/discussion-oq/STEP.md

@@ -16,7 +16,11 @@ discussion from completing, so a decision nobody took cannot close the pack.
 
 The same as `discussion-pack`: this run's stage report holds the
 `## Grilling Session` row, its `Ended at` is written, and `Ended` is
-`confirmed`, `user-closed` or `no-question`. Without that row, or with
+`confirmed`, `user-closed`, `no-question`, or `adopted` meeting
+`.agents/rules/grilling.md#explicit-delegation-for-a-discussion`.
+Check the actual delegation and rounds, required inputs, empty tree and
+human authority in the stage evidence; the ending label alone is insufficient.
+Without that row, or with
 `Ended: stopped`, write nothing and stop.
 
 ## Reads

package/assets/init/.qfai/assistant/step/discussion-pack/STEP.md

@@ -16,7 +16,11 @@ conversational summaries, are the handoff.
 
 **Authoring the pack** does not start until the session has ended. This run's
 stage report holds the `## Grilling Session` row, its `Ended at` is written,
-and `Ended` is `confirmed`, `user-closed` or `no-question`. Without that row,
+and `Ended` is `confirmed`, `user-closed`, `no-question`, or `adopted` meeting
+`.agents/rules/grilling.md#explicit-delegation-for-a-discussion`.
+Check the actual delegation and rounds, required inputs, empty tree and
+human authority in the stage evidence; the ending label alone is insufficient.
+Without that row,
 or with `Ended: stopped`, write no pack file and stop. A pack drafted
 mid-session records a design that was still being decided, and the draft is
 what the rest of the run then defends.

package/assets/init/.qfai/assistant/step/discussion-uiux/STEP.md

@@ -16,7 +16,11 @@ read, without forcing an early visual direction.
 
 The same as `discussion-pack`: this run's stage report holds the
 `## Grilling Session` row, its `Ended at` is written, and `Ended` is
-`confirmed`, `user-closed` or `no-question`. Without that row, or with
+`confirmed`, `user-closed`, `no-question`, or `adopted` meeting
+`.agents/rules/grilling.md#explicit-delegation-for-a-discussion`.
+Check the actual delegation and rounds, required inputs, empty tree and
+human authority in the stage evidence; the ending label alone is insufficient.
+Without that row, or with
 `Ended: stopped`, write nothing and stop.
 
 ## Reads

package/assets/init/.qfai/assistant/step/implement-dep-bump/STEP.md

@@ -45,12 +45,18 @@ into the repository, so steps 5 and 6 are replaced by the upgrade procedure in
 the section "Keeping QFAI itself up to date" of `node_modules/qfai/README.md`:
 `init --force`, the retired files the release notes list, then `doctor` and
 `validate`. `init --force` replaces the skills and steps in use, so read the
-next step from disk after it runs.
+next step from disk after it runs. What `doctor` and `validate` report is part
+of the update: a new required key in `qfai.config.yaml`, and an edit to a spec
+contract, which needs its change request in `decisions.md` under
+`paths.specsDir`, as `.qfai/assistant/rule/drift-protocol.md` describes, before
+the contract file changes.
 
 ## What it writes
 
 - The actual changed paths for the manifest, lockfile and any adapted call,
-  listed in the stage report.
+  listed in the stage report. When the dependency is `qfai` itself, they also
+  include a new key in `qfai.config.yaml` and a spec-contract edit with its
+  change request.
 - A record of the versions, the breaking changes read and how each was met, in the stage report.
 
 ## Gate

package/assets/init/.qfai/assistant/step/implement-procedure/STEP.md

@@ -0,0 +1,69 @@
+---
+name: implement-procedure
+owner: qfai-implement
+purpose: Write an authorized operational procedure within existing policy.
+requires: [common-gate-run]
+roles: [doc-steward]
+routing-profile: default
+---
+
+# implement-procedure
+
+## What this is for
+
+Write instructions a person can follow within the project's existing policy.
+Do not invent a business flow, code, tests, specifications or contracts to
+support this document.
+
+## Reads
+
+- The request and work order: resolve the authorized write scope and target
+  documents before editing.
+- The existing policy and procedures governing the actions: preserve their
+  authority limits and required checks.
+- For every document edit, read `.agents/rules/documentation-clarity.md`.
+
+## Before writing
+
+If the needed edit belongs to policy, a story, a contract or QFAI assistant
+instructions, stop before writing and name its owning stage. Markdown does not
+confer ownership of those surfaces.
+
+If required facts or values are missing, stop the dependent work and report
+what is needed to resume. Never invent values, commands or permission.
+
+## Procedure
+
+1. Identify the inputs, actions, commands, required values, order, failure
+   conditions and recovery steps the request needs.
+2. Check them against existing policy and actual known facts. Write only the
+   authorized documents within the work order's scope.
+3. Keep the instructions usable: name the actor, prerequisites, expected
+   result, stop conditions and recovery for each action.
+4. Run the applicable document lint and link checks through
+   `.qfai/assistant/step/common-gate-run/STEP.md`. Keep actual evidence;
+   unavailable required checks remain UNRUN with their blocker and resume
+   condition. Follow the plan's existing independent code review and closing
+   verification stages.
+
+## Action authority
+
+Authoring does not authorize execution. Do not perform publication, deletion,
+login or permission expansion while writing their instructions. Those actions
+need separate authority and their own applicable route. Required values are
+facts to verify, not authority to act.
+
+## Stage report
+
+Report the changed paths, the procedure authored and the checks actually
+performed with their evidence. State that the documented actions were not
+executed; their outcome is unobserved. Record unavailable checks as UNRUN,
+with the blocker, owner and condition for resuming. Static instructions do not
+prove an adopter's operation succeeded.
+
+## Gate
+
+The authorized document is complete and consistent with existing policy.
+Applicable lint and link checks have actual results through
+`common-gate-run`; failures and unavailable checks prevent completion.
+Protected edits and uncovered actions were stopped before writing or acting.

package/assets/init/.qfai/assistant/step/implement-quarantine/STEP.md

@@ -24,15 +24,29 @@ it.
 
 ## Procedure
 
-1. Show the flakiness: run the test a recorded number of times at one
-   revision and count the failures. A test that fails every time is not
-   flaky; stop and report it as failing.
+1. Show the flakiness: run the test at one revision at least five times,
+   record the number of runs and count the failures. A test that fails every
+   run is not flaky: see
+   [A test that fails every run](#a-test-that-fails-every-run).
 2. Quarantine it with the project's own mechanism. Add one only where the
    project has none.
 3. Keep it running where it blocks nothing, such as a non-gating job, where
    the project can.
 4. Change neither what it asserts nor the code it tests. Delete nothing.
 
+## A test that fails every run
+
+When all of at least five recorded runs fail, nothing is quarantined, no marker
+is written and no non-gating job is added: a skip would hide a failure that is
+real, and a failure rate the runs do not show cannot be invented. With fewer
+runs, or with one passing run, the test is not shown to fail every run, so run
+it again or quarantine it as flaky. Record the runs, their count and the
+failure's signature in the stage report, then report the outcome
+`failing-consistently` with an extraction of the report as a test that fails
+every run, so the decision rules route it again. The stage ends there: the
+stages after it do not run, and the next route's diagnosis and test repair take
+over.
+
 ## What it writes
 
 - The changed file path for the quarantine entry or marker, listed in the
@@ -43,4 +57,7 @@ it.
 ## Gate
 
 The step is done when the flakiness is shown by a recorded failure rate, the
-test no longer gates, and its quarantine entry states what lifts it.
+test no longer gates, and its quarantine entry states what lifts it. It is also
+done when a test that failed all of at least five recorded runs is reported as
+`failing-consistently`, with the runs in the stage report and nothing
+quarantined.

package/assets/init/.qfai/assistant/step/implement-regression-fix/STEP.md

@@ -31,9 +31,9 @@ else.
 3. Re-run the same test. The same test turning GREEN again confirms the fix.
 4. The fix and the re-run are reported in the stage report.
 
-The route's code review judges the fix. A UI-affecting fix, as
-`.qfai/assistant/skill/qfai-implement/references/ui-affecting.md` defines it,
-adds the product-surface-reviewer to that review. The full suite and the
+The route's code review judges the fix. A fix that changes a screen, as
+`common-review-cycle`'s reviewer set defines it, adds `product-surface-reviewer`
+to that review. The full suite and the
 project gates run once, in the verify stage.
 
 The example stays annotated by the same test. No `Change request:` row is

package/assets/init/.qfai/assistant/step/implement-stress-harness/STEP.md

@@ -22,9 +22,37 @@ be checked against something more than one lucky run.
   the failure appears.
 - The commands of `common-gate-run`, and the test tools the project already
   carries.
+- Existing Red evidence with its command, signature and revision, and the
+  evidence that establishes its cause.
 
 ## Procedure
 
+### Applicability on entry
+
+This step always checks the evidence on entry. Pressure is unnecessary only
+when a prior executed Red reproduces the same failure signature and a verified
+ordinary cause explains it without clock, operation order, parallelism, load,
+timing or race dependence. A verified ordinary cause is one demonstrated with
+fixed inputs and a directly constructed failing state: the test sets up that
+state itself instead of waiting for it, and fails on it. One recorded Red
+cannot show a failure on every run, so cite the recorded Red results, or state
+why the failing state is deterministic. The original report of an intermittent
+failure, a single observed failure or a Red that fails only sometimes is not
+that proof. A fixed seed or controlled schedule that exposes a race is not an
+ordinary cause.
+Uncertainty requires the real harness below. Missing or unexecuted Red,
+another signature or an unknown cause cannot justify omitting pressure.
+Stale or pending CI, unavailable tools, waits and limited time do not supply
+missing proof. A cause found later cannot justify claiming that an earlier
+harness was unnecessary or not performed.
+
+When the entry evidence qualifies, build no harness and run no pressure. In
+the stage report, cite the inspected Red and cause evidence, record why load
+or soak is unnecessary, and state that the stress run was not performed. The
+gate checks this applicability reason and its proof; report no stress PASS.
+
+### When a harness is required
+
 1. Pick the cheapest pressure that reaches the failure:
    - a deterministic schedule: a fixed seed, an injected clock, or a
      controlled order of the operations that interleave;
@@ -49,5 +77,8 @@ be checked against something more than one lucky run.
 
 ## Gate
 
-The step is done when the harness reproduces the reported failure at a
-recorded rate, and no production code changed.
+When a harness is required, the step is done when it reproduces the reported
+failure at a recorded rate, and no production code changed.
+For the ordinary-cause case, the entry proof and applicability reason are
+recorded, and no production code changed. No unperformed stress run counts
+as passed.

package/assets/init/.qfai/assistant/step/prototyping-preflight/STEP.md

@@ -42,6 +42,14 @@ Nothing. The CLI checks are read-only.
 - Confirm a dev server or a static file server can serve
   `.qfai/prototype/` at the URL passed to
   `npx qfai doctor --profile prototyping --target-url <url>`.
+- Doctor sends one `GET` to exactly the URL it is given, without following a
+  redirect, and waits 3 seconds. A status from 200 to 399 passes; a 404 or any
+  other status fails the check, and so does no answer. It probes that one URL,
+  not a file under it. A server that serves `.qfai/prototype/` with no
+  `index.html` at its root can answer 404 on `/`, so pass a URL that answers
+  200, for example `http://localhost:3100/iter-01/<screen>.html`. A server on
+  one address family while `localhost` resolves to the other also fails the
+  probe.
 - Confirm every declared screen ID matches `[A-Za-z0-9._-]+` and does not
   contain `..`. The loop builds file names from it, so an ID that fails either
   test stops the run, naming the contract and the ID.

package/assets/init/.qfai/assistant/step/sdd-triage/STEP.md

@@ -101,8 +101,10 @@ before the dependent write and report pending approvals.
 UI-bearing is a property of the affected flow, not of the files this run
 happened to edit. Resolve it from the source's surface classification and the UI
 contracts linked to that flow, and record it for each affected flow. Route
-`product-experience-architect` during design and `product-surface-reviewer`
-during review whenever either signal identifies the flow as UI-bearing.
+`product-experience-architect` during design whenever either signal identifies
+the flow as UI-bearing. `product-surface-reviewer` joins a review in a route
+only for a screen change, as `common-review-cycle`'s reviewer set says;
+`qfai-sdd` invoked by name keeps the reviewers its own `## Review` section names.
 
 ## Which surface owns the truth
 

package/assets/init/.qfai/assistant/step/triage-answer/STEP.md

@@ -25,8 +25,8 @@ Answers a question about the project from what the project already says.
 2. Cite each source it rests on: a document section, a file and line, or an
    evidence record. An answer with no source is a guess, and is not given.
 3. Where a source is missing or wrong, such as an option the documentation
-   never mentions, record it as a follow-up for `triage-close`. Do not fix it
-   here.
+   never mentions, record it as a follow-up for `triage-close`, or for the
+   final report where no close step follows. Do not fix it here.
 
 ## What it writes