qfai 2.1.1 → 2.2.0

package/assets/init/.qfai/assistant/step/verify-release-notes/STEP.md

@@ -17,6 +17,7 @@ Drafts what a user reads about a release. It releases nothing.
 - The changes merged since the last release, from the history.
 - The format the project's earlier release notes use.
 - The version the user named, if any.
+- `.agents/rules/documentation-clarity.md`, when writing the prose this step produces.
 
 ## Writes
 

package/assets/init/.qfai/assistant/step/verify-repeat-run/STEP.md

@@ -22,16 +22,51 @@ run.
 - The number of runs the quarantine record or the work order names, where one
   does.
 - The Test command, through `common-gate-run`.
+- The diagnosis and its executed same-signature Red, and the matching Green (same test and command)
+  for the current exact revision.
 
 ## Writes
 
 - In the stage report: the number of runs and why, then
   every run in order, each with its command, result and revision.
 - Where the runs lift a quarantine: the removal of the quarantine marker and
-  record the quarantine added, and nothing else.
+  record the quarantine added, and nothing else. Name the removed paths in the
+  stage report.
 
 ## Procedure
 
+### Applicability on entry
+
+This step always checks the diagnosis and test evidence. Only a
+`fix-intermittent` diagnosis of a verified ordinary cause, with a prior
+executed Red of the same failure signature and a matching executed Green for
+the current exact revision, can make repetitions unnecessary. A matching
+Green is the same test, run with the same command as that Red, passing at the
+current exact revision; a different test, a wider suite or another command
+does not match. A verified ordinary cause is one the diagnosis demonstrates
+with fixed inputs and a directly constructed failing state: the test sets
+that state up itself and fails on it before the fix, instead of waiting for
+it or reaching it by chance. 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 cause must have no clock, operation order,
+parallelism, load, timing or race dependence or uncertainty. A fixed seed or
+deterministic schedule exposing a race does not qualify. Quarantine never
+uses this case: lifting one always requires the actual consecutive runs
+below.
+
+Missing or unexecuted Red, another signature, a Green that is not the same
+test and command, stale Green, pending CI, an unknown cause or unresolved
+timing or load uncertainty require the real runs.
+Unavailable tools, waits or limited time do not make repetitions unnecessary.
+When the evidence qualifies, cite the inspected diagnosis, prior Red and
+current Green, including their commands, results and revisions, in the stage
+report, with the applicability reason and why load or soak is unnecessary.
+State that repeat runs were not performed. The gate
+checks this proof and reason; report no repeat-run PASS. A later cause never
+changes the earlier record of what ran.
+
+### When repeated runs are required
+
 1. Fix the number of runs before the first one, and record it with its reason.
    Where nothing names a number, take at least three divided by the failure
    rate the diagnosis measured, so a failure that rate predicts would show.
@@ -41,13 +76,20 @@ run.
    reporting, as
    `.qfai/assistant/rule/references/gate-failure-autorepair.md#nondeterministic-gates`
    says.
-4. One failure ends the step. Inside a run, return `needs_repair` with the
-   failure in `debts`, owned by the skill that owns the failing test's layer or
-   the code it exercises. The count starts again only after a new fix.
+4. One failure ends the step. Inside a run, return `needs_repair`. Record
+   the failed run and its evidence in the stage report, with the skill that
+   owns the failing test's layer or code as the repair owner. The count starts
+   again only after a new fix.
 5. When every run passed, lift the quarantine where there is one.
 
 ## Gate
 
+When repeated runs are required:
+
 - The number of runs was fixed and recorded before the first run.
 - Every run is recorded, and all of them passed on the same revision.
 - A lifted quarantine removed only its marker and its record.
+
+For the ordinary `fix-intermittent` case, the inspected diagnosis, prior Red,
+current exact-revision Green and applicability reason are recorded. No
+unperformed repetitions count as passed, and no quarantine is lifted.

package/assets/init/.qfai/assistant/step/verify-repo-gate/STEP.md

@@ -25,7 +25,8 @@ Create and update `.qfai/report/verify.json`.
 
 ## Procedure
 
-1. Run the repository gates (below).
+1. Determine the applicable repository gates through `common-gate-run` before
+   resolving their commands, then run those gates (below).
 2. Run the fix loop until every gate in scope passes, or stop as it says.
 3. Report the result.
 4. Write the verdict.
@@ -46,8 +47,10 @@ commands entry named after the colon:
 
 Run listed commands and record outputs. A gate whose Standard commands entry
 is `CI only: <check name>` is not run here: record it `DELEGATED` with that
-check name. Where the environment cannot run any other command, ask the user to
-run it and provide the output. Never assume PASS without evidence.
+check name. This requires an actual CI check covering the same gate and scope;
+local environment failure alone creates no delegation. Retain observed FAIL or
+UNRUN results. Where the environment cannot run any other command, ask the user
+to run it and provide the output. Never assume PASS without evidence.
 
 ## Fix loop
 
@@ -83,55 +86,141 @@ one code review reads the repair, as `qfai-verify`'s `## Review` section says.
 Report the scope, every gate command with its result, the open risks and the
 next actions.
 
+For CI results, keep the full receipt in the stage report as
+`.qfai/assistant/step/common-gate-run/STEP.md#ci-evidence` requires. A branch
+overview and a confirmed closed cleanup SKIP do not replace actual verification.
+
+For a `DELEGATED` gate, record `check` and `ci` (`green`, `red` or `pending`).
+In the stage report, bind evidence to the target and current head: run ID or URL,
+check, actual outcome and counts, blocker and resume condition. If no run exists,
+record that fact. A result for another head does not pass this head; a missing
+or mismatched result remains pending. Keep earlier failures visible.
+
+Name pending checks in `summary` and the stage report. A covered verification
+commit may use the existing DELEGATED allowance in `verify-commit`; it does not
+complete verification. With explicit CI-only delegation covering transport,
+actual changes addressing a failed check through the existing planned fix may
+be committed while HEAD still names the failing commit. Every nondelegated gate
+must pass. Retain the prior head, check, run and observed result as FAIL, and
+report the actual fix and new head after committing. Never relabel the prior
+failure pending or transport the same unchanged red candidate. The new candidate
+remains unverified until its own results are observed; report a missing run as
+missing. Formal completion or merge requires actual passing results for every
+required check on the current target and head. Pending, red, missing or
+mismatched evidence stops completion. Repair follows the existing
+fix procedure under its own covered authority.
+
+### Acceptance evidence and follow-up
+
+When implementation, verification or handoff scope includes acceptance scaffolds
+or unfinished BF/AC acceptance bodies, include these five fields in the human
+report. A lint-only scope without these bodies needs no acceptance report.
+
+| Field                      | Report                                                                                                                                                                                                                                                  |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Annotation proof           | BF/AC annotation IDs, their test files and the inspection or validation result that established them.                                                                                                                                                   |
+| Acceptance bodies          | Empty, implemented and unclassified body counts, with each counting unit and file references. Keep BF test bodies and AC test bodies separate; test bodies are not unique obligations. Use UNKNOWN, not zero, for a count inspection did not establish. |
+| Asserted behavior and runs | The actual assertion that observes each implemented body's BF or AC, and its actual run results with evidence references. An annotation alone does not establish the assertion or its execution.                                                        |
+| Observed outcomes          | PASS, FAIL, skipped, UNRUN and pending observations, with their logs or evidence references. Only an actual run supplies an execution result. A passing empty body establishes no behavioral proof.                                                     |
+| Remaining work             | Identified unfinished BF/AC bodies and files, the actual owner or UNASSIGNED, completion criteria and the next route. Use `write-acceptance-tests` to write the remaining bodies under its existing acceptance-writing rules.                           |
+
+Do not derive completed ACs by subtracting empty bodies from the suite's pass
+total. An assertion for another EX does not complete an empty AC body. Zero
+validation errors do not prove BF/AC behavior. Guidance fixtures prove the
+reporting guidance they inspect, not an adopter's actual behavior.
+
+For example, an illustrative inspection can identify two AC test bodies, one
+empty and one with recorded assertion and run evidence, plus one unclassified
+BF test body. Report those body counts with their separate units and files;
+the remaining bodies still need owners and completion criteria. If inspection
+has not established the count, write UNKNOWN. If no owner has been assigned,
+write UNASSIGNED; do not invent an assignment or a successful run.
+
+Legitimate empty bodies keep their existing exemption. An actual required-check
+FAIL remains FAIL, and the acceptance-writing completion gate is unchanged.
+When using the existing optional `verify.json` summary, keep one or two short
+sentences naming remaining work, its owner or UNASSIGNED, and the detailed
+report reference. Put the table in the human report, without new JSON fields,
+statuses, scopes, gates or routes.
+
+### Full collection evidence
+
+During the existing normal verify run, record the full intended collection
+and actual collection and execution. Reconcile omitted cases against
+comparable case membership at the same revision, command/filter, runner and
+environment, or explain intentional differences. Preserve the Standard Test
+command's quoted arguments: shell expansion can change collection depth.
+Equal aggregate counts do not prove equal membership. Keep unknown expected
+counts unknown; unexplained omissions prevent a full-scope completion claim.
+
+A focused target pass, file/container success or static annotation linkage
+proves no full collection. For a focused case's source identity, actual body
+execution, terminal state and raw evidence, read
+`.qfai/assistant/skill/qfai-implement/references/red-admissibility.md#selected-case-execution`.
+Keep its result distinct from full-scope evidence. No extra full run is
+required during each focused cycle. Record these facts in the existing human
+report; add no permanent inventory, ledger, JSON field, gate status, runtime
+parser or runner.
+
 ## Verdict
 
 Write `.qfai/report/verify.json` at the end of the run. It is the
 machine-readable verdict downstream gates read, and the evidence markdown does
-not replace it. `status` is `"PASS"` only when every gate in scope passed.
-`scope` is the one `verify-qfai-gate` ran, never a stage this run did not
-cover. Fields, the closed `scope` enum, a conforming example and what must
+not replace it. `status` is `"PASS"` only when every gate in scope passed or is
+`DELEGATED` to a CI check that is not red for the candidate being evaluated.
+A red check for that candidate or a non-delegated UNRUN gate makes `status`
+`"FAIL"`. Preserve the previous candidate's FAIL evidence when an explicitly
+covered transport commit carries actual repairs into a new candidate. Its own
+pending delegated checks permit only that transport, never formal completion;
+they do not replace the earlier failed result. Keep revision and run evidence
+in the stage report, without adding verdict fields or states.
+`scope` is the gate set `verify-qfai-gate` covered through execution or an
+explicitly declared matching CI-only check, never a stage this run did not
+cover. Delegation does not claim that its validation profile has already run. Fields, the closed `scope` enum, a conforming example and what must
 never be written are in
 `.qfai/assistant/skill/qfai-verify/references/verify-output-contract.md`.
 
-## The stage result
+## Stage report
 
 Inside an `npx qfai workflow` run, the stage runs every required gate over the
 run's change and reports each result.
 
-- The stage writes this run's `.qfai/report/verify.json` and names it in
-  `artifactRefs`.
+- The stage writes this run's `.qfai/report/verify.json` and names its scope and
+  the revision checked in the stage report, with the commands and evidence for
+  each gate.
 - A `verify.json` written by another run, scoped to another flow or kept in a
   shared location is never named as this stage's report.
-- The stage's own `gateResults` are information only: the run decides no gate
-  from them.
-- `outcome` and `testObservation` are reported apart.
-- A required gate that did not run is reported `unrun`, never as a pass.
-- A gate the project runs in CI only is reported `delegated`, with its check
-  name.
+- Report the stage's completion or stop separately from actual test and gate
+  observations. A required gate that did not run is UNRUN, never a pass.
+- A gate the project runs in CI only is DELEGATED, with its check name and
+  observed CI status.
 
-`verify.json` itself is unchanged inside a run: its fields and values are
-`.qfai/assistant/skill/qfai-verify/references/verify-output-contract.md`'s,
-and the run's values stay in the stage result.
+Keep these details in the stage report and session handoff. `verify.json`
+keeps only the fields and values in
+`.qfai/assistant/skill/qfai-verify/references/verify-output-contract.md`.
 
 ## Findings verify did not cause
 
 Inside a run, verify edits no artifact another owner holds. A finding it did
-not cause returns `needs_repair`, with the finding listed in `debts` under its
-`resolvingOwner`, so the run sends the repair there.
+not cause returns `needs_repair`. The stage report and handoff name the
+finding, its evidence and affected paths, the repair owner and the repair
+needed before verification can resume.
 
-| Finding                   | `resolvingOwner` |
+| Finding                   | Owner            |
 | ------------------------- | ---------------- |
 | A story or contract gap   | `qfai-sdd`       |
 | An acceptance-test defect | `qfai-implement` |
 | An implementation defect  | `qfai-implement` |
 
-These three are the only repairs verify routes.
+These three are the only repairs verify hands off to an owner.
 
 ## A missing environment
 
-- A gate whose environment is missing returns the stage `blocked`, with the
-  blocker `stage-blocked` and `operator` as the one who clears it.
-- No debt is listed for it, and no repair is routed.
+- A gate whose environment is missing leaves the stage `blocked`. Record
+  the missing environment in the stage report, with the operator as its owner
+  and the capability needed to resume.
+- This is an environment stop, not a product repair. The gate remains UNRUN
+  with its reason.
 
 ## A failure the run did not cause
 
@@ -141,6 +230,18 @@ its `reason`. The top-level `status` stays `"FAIL"`, so the run stops before
 `verify-commit`. The final report lists each such gate apart from the failures
 the run caused, so the user can decide whether to commit.
 
+For a gate with baseline `same`, `reason` names the failing test identifiers
+and the environment they fail in. The identifiers are the ones observed failing
+in the base commit's run, executed as `common-gate-run`'s
+`## A failure that predates the change` says, never assumed. The stage report
+adds how to confirm it: the base commit's result, and the result of the same
+gate in CI when a check covers it, with the run or check named. A CI result that
+was not observed is written as unknown, never as a pass. The report ends by
+asking the user whether to commit with those gates open, as
+`.agents/rules/user-questions.md` says; nothing is committed before the answer.
+Under a no-question mode, or with no question tool, the report lists those gates
+as open and stops without committing.
+
 ## Gate
 
 The step is done when:
@@ -149,14 +250,16 @@ The step is done when:
   reason, or is recorded DELEGATED with its CI check;
 - every gate passes, or each failure has an actionable fix list and an owner;
 - `verify.json` exists, its `status` matches the gate results and its `scope`
-  matches the validate profile that ran.
+  matches the required validate profile. A delegated validation check must cover
+  that same profile and scan; a whole-repository scope still requires a full
+  scan. Pending delegation never claims it ran.
 
 For this skill, the smallest applicable smoke check of
 `.qfai/assistant/rule/shared-skill-operating-baseline.md#completion-contract-shared`
 is the whole gate set of the scope, run to completion, with every outcome in
 `verify.json` and the report.
 
-A PASS needs zero errors in the declared profile, or errors only within the
-project's recorded backlog as `verify-qfai-gate` reports it, and, where the
-project has them, a clean distributed-surface guard and a clean branch version
-pin.
+A PASS needs zero errors in the declared profile. A successful custom Validate
+wrapper does not waive validation errors or replace a full scan. Where the
+project has them, the distributed-surface guard and branch version pin must also
+pass.

package/assets/init/root/.agents/rules/ai-readable-markdown.md

@@ -84,8 +84,8 @@ them, and nothing says which.
 
 ## Held by
 
-Review, and any check a project adds for itself. `npx qfai doctor` reports an
-assistant asset over 800 lines, which is a second check above the limit in § 1.
+Review, and any check a project adds for itself. `npx qfai doctor` reports a
+Markdown assistant asset over the line limit in § 1.
 
 ## Related
 

package/assets/init/root/.agents/rules/api-budget.md

@@ -43,6 +43,154 @@ asking it once costs what asking about a single item costs.
 Three branches polled separately spend three times what the answer needs, and
 the multiplier grows with the work rather than staying put.
 
+### A first snapshot of two pull requests
+
+When git and a REST listing cannot answer the combined CI and review question,
+use aliases and a common fragment. Supply the repository owner, name and two
+pull-request numbers as variables. This query reads the first pages only.
+
+```graphql
+query PullRequestSnapshot($owner: String!, $name: String!, $firstPR: Int!, $secondPR: Int!) {
+  repository(owner: $owner, name: $name) {
+    first: pullRequest(number: $firstPR) {
+      ...PullRequestState
+    }
+    second: pullRequest(number: $secondPR) {
+      ...PullRequestState
+    }
+  }
+}
+
+fragment PullRequestState on PullRequest {
+  id
+  number
+  headRefOid
+  state
+  mergeable
+  commits(last: 1) {
+    nodes {
+      commit {
+        id
+        oid
+        statusCheckRollup {
+          id
+          state
+          contexts(first: 50, after: null) {
+            nodes {
+              __typename
+              ... on CheckRun {
+                id
+                name
+                status
+                conclusion
+                detailsUrl
+                completedAt
+              }
+              ... on StatusContext {
+                id
+                context
+                state
+                targetUrl
+              }
+            }
+            pageInfo {
+              hasNextPage
+              endCursor
+            }
+          }
+        }
+      }
+    }
+    pageInfo {
+      hasPreviousPage
+      startCursor
+    }
+  }
+  reviewThreads(first: 50, after: null) {
+    nodes {
+      id
+      isResolved
+      isOutdated
+      comments(first: 20, after: null) {
+        nodes {
+          id
+          body
+          author {
+            login
+          }
+          createdAt
+          updatedAt
+          url
+        }
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+      }
+    }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+  }
+  reviews(first: 50, after: null) {
+    nodes {
+      id
+      state
+      body
+      author {
+        login
+      }
+      submittedAt
+      commit {
+        oid
+      }
+      url
+    }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+  }
+  comments(first: 50, after: null) {
+    nodes {
+      id
+      body
+      author {
+        login
+      }
+      createdAt
+      updatedAt
+      url
+    }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+  }
+}
+```
+
+- Keep a separate cursor for each PR's contexts, threads, reviews and comments,
+  and for each thread's comments. While `hasNextPage` is true, fetch that
+  connection with its own `endCursor` as `after`, retaining earlier pages.
+  Batch independent next-page requests with distinct aliases and variables;
+  never reuse one connection's cursor for another.
+- `commits(last: 1)` selects the head evidence, not the full commit history.
+  Its commit `oid` must equal that PR's `headRefOid`. Earlier commits indicated
+  by `hasPreviousPage` need not be fetched for this head check.
+- Require every page of the status and review connections before claiming
+  coverage. API errors, null PRs or required evidence, missing heads, or an OID
+  mismatch leave the snapshot incomplete. A null rollup does not prove CI passed.
+  If the head changes during pagination, discard that head's coverage and
+  collect a new snapshot. Apply the project's completion and merge rules only
+  to complete evidence for the current head.
+
+GitHub's [pull-request fields](https://docs.github.com/en/graphql/reference/pulls),
+[commit status fields](https://docs.github.com/en/graphql/reference/commits) and
+[pagination guide](https://docs.github.com/en/graphql/guides/using-pagination-in-the-graphql-api)
+define the query's fields and cursors.
+
 ## 3. Save a payload once and read it locally
 
 A log, a diff or a listing that will be searched more than once is written to
@@ -60,17 +208,48 @@ already said.
 Where the subject's duration is unknown, ask once, wait, and widen the gap as
 the wait grows.
 
+### One watcher for the task
+
+The root agent names one API watcher for recurring hosted-state checks. The
+root and all its descendants together have at most one such watcher. Other
+workers read its saved payloads and request fresh snapshots from it. Save the
+capture time, covered PRs and heads, pagination state and response headers with
+each payload so workers can judge whether it answers their question.
+
+Coordinate targets and timing with other known tasks using the same account;
+reuse their watcher where it can cover the combined set. This does not reserve
+the account or guarantee exclusive access against unknown sessions. It limits
+API polling, not workers doing local work or making necessary non-polling calls.
+
+These are operating instructions. The reminder does not elect a watcher or
+enforce the limit.
+
 ## 5. `rate_limit` is not the budget
 
-A dedicated rate-limit endpoint can report a stale or wrong figure. One has
-answered `0` calls used against a token that a real endpoint reported, minutes
-later, as most of the way through its allowance. An agent that trusts the
-endpoint reads reassurance and keeps spending.
+Read the budget from the response to a call that was going to be made anyway,
+never a dedicated `rate_limit` probe. Record that response's resource, remaining count
+and reset time. On GitHub these are `x-ratelimit-resource`,
+`x-ratelimit-remaining` and `x-ratelimit-reset`; also retain `Retry-After` when
+present. REST and GraphQL have separate primary allowances. Missing headers
+leave the budget unknown; a saved count is not a reservation for the next call.
+
+### Recover from an actual refusal
+
+When a real response refuses a request because of a rate limit, stop calls to
+the affected resource and tell the watcher and known account-sharing tasks.
+A successful HTTP status with a rate-limit error in the body is also a refusal.
+For a secondary limit, pause affected requests across REST and GraphQL for the
+same account. Changing tokens or API surfaces is not recovery.
+Wait for `Retry-After` and any applicable reset time. For a secondary limit
+with neither delay nor an exhausted primary allowance, wait at least one minute.
 
-The instrument is the response to a call that was going to be made anyway.
-Every response carries the remaining count, the reset time and the name of the
-allowance it was drawn from — and that last one is what says which allowance a
-refusal came from, where REST and GraphQL are counted separately.
+After the wait, make one real request already needed for the work. Resume that
+resource only when the request succeeds and its own headers show available
+budget. If it is refused again or the headers are missing, keep it stopped;
+do not run a retry loop or a `rate_limit` probe. Continue work that needs no
+call to that resource. GitHub's
+[rate-limit guidance](https://docs.github.com/en/graphql/overview/rate-limits-and-query-limits-for-the-graphql-api)
+describes the refusal signals and wait headers.
 
 ## The command, where there is one
 

package/assets/init/root/.agents/rules/document-schema.md

@@ -61,6 +61,23 @@ Both run the checker the installed package carries, against its schemas, with
 the `@jackchuka/mdschema` version the package depends on. Neither can be
 switched off in `qfai.config.yaml`.
 
+To run the lane's two checks before you push, install the checkers into
+`tmp/qfai-docs-tools` with the `npm install` line of the step
+"Install the document-shape and diagram checkers" in `qfai-docs.yml` that
+matches your project: the line for a project with its own `node_modules/qfai`,
+or the line for one without it. That line pins the versions the lane uses. Then
+run the two commands the lane runs:
+
+```bash
+node node_modules/qfai/assets/scripts/check-mdschema.mjs --tools tmp/qfai-docs-tools --scope all --summary
+node node_modules/qfai/assets/scripts/check-mermaid.mjs --tools tmp/qfai-docs-tools
+```
+
+A project with no `node_modules/qfai` of its own runs the script from
+`tmp/qfai-docs-tools/node_modules/qfai/assets/scripts/` instead, as the lane
+does. `npx qfai validate` already reports the shape violations; the Mermaid
+check is the one only this install provides.
+
 ## 8. What a schema cannot say
 
 A schema reads structure. A cell's value, the content of a fenced block, and