qfai 2.1.0 → 2.1.2

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.
@@ -44,9 +45,12 @@ commands entry named after the colon:
 7. build/package (if relevant): `Build`
 8. pack/verify (if distributed): `Pack / distribution`
 
-Run listed commands and record outputs. Where the environment cannot run a
-command, ask the user to run it and provide the output. Never assume PASS
-without evidence.
+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. 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
 
@@ -60,6 +64,10 @@ one code review reads the repair, as `qfai-verify`'s `## Review` section says.
 
 - If failing, produce an actionable fix list (not vague). Stop and escalate
   when a gate fails without one.
+- Before attributing a failure to the change, run the gate on the base commit,
+  as `common-gate-run`'s `## A failure that predates the change` says. A
+  failure that is the same there is reported with its baseline and is not
+  repaired.
 - Identify whether the failure is a spec mismatch, a test issue or an
   implementation defect, and fix the root cause. Do not silence a test without
   a reason.
@@ -78,68 +86,168 @@ 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.
+- 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
+
+A gate that fails the same way on the base commit, or could not run, is
+recorded in the report and in `gates` of `verify.json`, with its `baseline` or
+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.
 
 ## Gate
 
 The step is done when:
 
 - every gate in scope ran and is recorded, or is recorded UNRUN with the
-  reason;
+  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, 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/.qfai/waivers.yml

@@ -2,7 +2,7 @@ version: 1
 waivers: []
 # Write `rule:` exactly as the finding's `code` appears in
 # `.qfai/report/validate.json` and in the CLI output — `QFAI-DT-006`,
-# `QFAI-CFG-LINK-002`, `W-ASSISTANT-LAYOUT`. Do not strip the `QFAI-` prefix;
+# `QFAI-CFG-LINK-002`, `QFAI-ASSISTANT-001`. Do not strip the `QFAI-` prefix;
 # the stripped form is kept working only for older waiver files.
 #
 # Waivers apply to `warning` and `info` findings only. A waiver aimed at an

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

@@ -0,0 +1,98 @@
+# AI-Readable Markdown
+
+How a Markdown file that an AI agent reads as instructions is sized and split.
+
+An agent follows fewer instructions as its context grows, and it follows those
+in the middle of a long file worst. A loaded file also stays loaded: every line
+is paid for again on every turn. So the aim is a small, relevant context for
+each task, not merely short files.
+
+## Scope
+
+| Target                                                            | Applies                                           |
+| ----------------------------------------------------------------- | ------------------------------------------------- |
+| Skills, references, templates, rules, agent cards and entry files | Always                                            |
+| Any other Markdown file an agent reads to decide what to do       | Always                                            |
+| Markdown written for people only, such as a changelog             | Outside this rule                                 |
+| How the text in a file is written                                 | Outside this rule; see `documentation-clarity.md` |
+
+## 1. Size limits
+
+- Every Markdown file an agent reads stays at or under **500 lines**.
+- A `SKILL.md` body stays at or under **20,000 characters**.
+
+The body excludes YAML frontmatter; a character is one Unicode code point.
+
+A file near a limit is a signal to move a section out, not to pack more onto
+each line.
+
+## 2. Budget what a task loads
+
+Splitting helps only when the pieces are loaded on demand. A piece that is
+always read together with another saves nothing: the task still loads both, and
+now pays for the pointer as well.
+
+So the budget is what a task loads, not the size of one file. It is the entry
+file, plus every file the task reads because a pointer sent it there. Two files
+that are always read together are one file.
+
+## 3. Every pointer says when
+
+Every pointer to another file says when to read it, when not to, and what it
+holds.
+
+> Read `references/api-errors.md` when the API returns a status other than 200.
+> It lists each error code and what to do about it. Not needed after a
+> successful call.
+
+A generic "see `references/`" does not count. An agent that cannot tell whether
+it needs a file either skips it or reads every file, and both defeat the split.
+
+## 4. One level deep
+
+The entry file names every reference directly. A reference does not point to
+another reference.
+
+An agent tends to preview a file it reached through another one, rather than
+read it whole, and misses what the preview did not show. Where two references
+need each other, point the entry file at both, or merge them.
+
+## 5. A long reference opens with its contents
+
+A reference file over 100 lines opens with a `## Contents` section: a list of
+its `##` headings, in order.
+
+A preview, a truncated read and a context that was compacted all keep the head
+of a file. The list lets the agent see what the rest holds from there.
+
+## 6. What stays in the entry file
+
+An obligation whose trigger the agent cannot judge for itself stays in the entry
+file.
+
+Move a section out only when the task itself shows the agent it needs it: it is
+writing that file, it hit that error, it reached that step. A rule that applies
+before the agent can know it applies — a trap, a stop condition, an input that
+must never be assumed — is read in the entry file or not at all.
+
+## 7. One home per rule
+
+Each rule is written in one place, and every other file references it.
+
+Two copies diverge over time. When they contradict each other, an agent picks one of
+them, and nothing says which.
+
+## Held by
+
+Review, and any check a project adds for itself. `npx qfai doctor` reports a
+Markdown assistant asset over the line limit in § 1.
+
+## Related
+
+- Writing standard for the text itself: `documentation-clarity.md`
+
+## Scope of this file
+
+This is the master copy for every AI coding agent in this repository.
+Tool-specific instruction files point here instead of restating it. Edit this
+file when the rule changes.

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

@@ -31,7 +31,7 @@ In this order, and stop at the first that answers.
 
 Most questions can be answered on more than one of these, which is why the order
 matters. Reaching for the convenient command rather than the cheap one is how an
-allowance goes: several of the forge's own subcommands take the GraphQL path
+allowance runs out: several of the forge's own subcommands take the GraphQL path
 where an equivalent REST path exists.
 
 ## 2. One call for the set, not one per member
@@ -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
 
@@ -78,10 +257,9 @@ The cheap path holds only if it is the default. A repository that gives the
 recurring questions one command gets that; one where each agent reassembles the
 calls gets the habits above again.
 
-The QFAI repository's own command is `scripts/gh-budget.mjs`: the CI state of
-every branch from one call, and a job log saved once. A project with no
-equivalent composes its calls by hand under the rules above, and a project that
-writes one names it here.
+A useful command answers two questions: the CI state of every branch from one
+call, and a job log saved once. A project with no equivalent composes its calls
+by hand under the rules above, and a project that writes one names it here.
 
 ## The reminder