qfai 2.1.0 → 2.1.1

package/assets/init/.qfai/assistant/rule/drift-protocol.md

@@ -49,14 +49,18 @@ Both classes use the same approval and owner-rerun path.
 
    When the user cannot be asked, write no row to either table: report the proposed change as the decision still
    needed and keep the affected items stopped. A WIP Change request: row is the in-force authorization that the drift gate reads.
-   TODO is not authorization. A DONE row authorizes only on the branch that appended it or moved it from WIP. A DONE
-   row the base already holds records a change already applied, so a later edit to the same path needs a row of its own.
+   TODO is not authorization. A DONE row authorizes only on the branch that appended it or moved it from WIP. A row
+   the base already holds at DONE records a change already applied and authorizes nothing at any Status, so setting it back to WIP
+   reopens nothing and a later edit to the same path needs a row of its own.
 
 4. Rerun the owner skill against the affected artifact. The owner names the approved decision row, the input revision, and whether it is confirming existing content or changing it.
    A contract with a contract ID, such as `API-0002`, is selected by its full ID; a contract without one is selected by its repository-relative path.
    The owner updates the specification and its tests together, then validates the relevant flow.
 5. Recheck every dependent BF, AC, and EX test obligation and every affected contract reference. Rewrite tests where their former expectation is invalid. Report any uncovered obligation. No execution ledger, TC row, or status reset substitutes for this check.
-6. Complete the decision row by changing Status from WIP to DONE only after the owner artifact and dependent checks are complete. Cite the DEC ID in the stage report. A second open request on the same artifact waits for the first outcome and is restated if its premise changed.
+6. Complete the decision row by changing Status from WIP to DONE only after the owner artifact and dependent checks are complete.
+   A row has one Status, so DONE claims every action its Approach lists. While one of them is deferred, keep the row at WIP.
+   Cite the DEC ID in the stage report.
+   A second open request on the same artifact waits for the first outcome and is restated if its premise changed.
 
 The decision table has no separate Applied at field and no standalone CR file. Approval alone does not certify a change as applied.
 
@@ -70,6 +74,13 @@ Open requests have independent affected sets. Their union is the set of work pau
 
 A defect is demonstrable from the deliverable or an existing obligation: incorrect behavior, missing input validation, data loss, or a failing required quality gate. It is blocking with the concrete artifact and evidence as provenance.
 
+No repository gate scans for a security or data-integrity defect. Review is that
+class's detector: `.qfai/assistant/agent/implementation-reviewer.md` checks each
+change for missing validation on an input the code already treats as trusted,
+credential or personal-data exposure, and an injection or traversal path opened
+by the change. A finding the reviewer demonstrates traces to `defect:security`
+and blocks like the other blocking classes.
+
 New scope adds product behavior or a quality bar the approved story tree and contracts do not require. A reviewer records it as advisory and sends it to the SDD owner. It becomes binding only after the owner records the decision and updates the relevant BF, AC, EX, BR, or contract. An advisory does not create a test assertion by itself.
 
 ### Provenance and routing

package/assets/init/.qfai/assistant/rule/references/asset-authoring.md

@@ -0,0 +1,70 @@
+# Asset Authoring
+
+Read when you write or change a shipped asset.
+
+## Asset Authoring Shape (Mandatory)
+
+A `SKILL.md` states the contract and points at the file that carries the detail. It is not where the detail lives.
+
+- **Keep in `SKILL.md`**: what the skill is for, its non-goals, its hard constraints, the phase/step order, and the gate conditions. Enough for an agent to know what it must do and when it is done.
+- **Move out**: command sets, table schemas, field-by-field contracts, worked procedures, checklists and rationale. These go under the owning tree's own directory:
+  - `references/` — normative detail the body cites (`references/<topic>.md`)
+  - `templates/` — artifacts the file produces, as fillable skeletons
+  - `examples/` — worked instances that illustrate, and bind, nothing
+- **One topic per file.** Do not replace an oversized `SKILL.md` with an oversized `references/everything.md`; that is the same problem one directory down. Split by topic and keep each file readable on its own — a reader who followed one pointer should not have to scan past three unrelated subjects to reach the one they came for.
+- **Every pointer resolves.** A line that moves detail out must name the file (and anchor, when the file covers more than one topic) so the reader is never left guessing where the rule went.
+
+A hard line ceiling backs this up: **800 lines per assistant asset file**, for every `.qfai/assistant/**/*.{md,yml,yaml}` file, counted as `content.split(/\r?\n/).length` — blank lines included. `npx qfai doctor` measures it and reports every file over the ceiling as `assets.lineBudget`. The ceiling is a backstop, not the rule: a file approaching it is a signal to move a section out, not
+to raise the number.
+
+It was raised from 500 once, and on measurement rather than on the "this file is long" claim the number exists to refuse: three skill bodies had converged on that ceiling, and the changes in flight against one of them added 161 lines to a body already at 498 — eleven of them crossing the ceiling on their own. The detail those bodies carry is required to sit in the body rather than behind
+a pointer, so splitting could not absorb it. Converging on the limit was itself the signal — a body at the ceiling stops shedding topics and starts packing them into longer lines, and a line count cannot see that. Raise it again only against evidence of that kind.
+
+**A width ceiling makes the count honest: 400 characters per line.** A count of lines bounds reading cost only while a line is a roughly constant unit of reading, and packing broke that — one line in the shipped tree ran 9,104 characters against a median of 118, and cost the budget one unit. The two are read together, because each permits what the other refuses: width alone allows a thin
+file of a thousand short lines, and the count alone allows a packed one.
+
+Two shapes are not measured, and for the same reason — the author cannot make them narrower:
+
+| not measured   | why                                                       |
+| -------------- | --------------------------------------------------------- |
+| a table row    | markdown gives it no continuation, so it cannot wrap      |
+| a fenced block | its content is a command, a diagram or a sample, verbatim |
+
+A table is found by its delimiter row, not by a leading pipe: that pipe is optional, so a table written without one is still a table, and a paragraph that opens with one is still a paragraph. Rows a blank line has cut off from their delimiter are prose, because that is how they render.
+
+Some shipped files predate the ceiling and carry a recorded width of their own. It is the width each arrives with, so `npx qfai doctor` does not report a fresh tree for content you received rather than wrote. That record belongs to the package and shrinks there; it is not a per-project allowance, and it never loosens the ceiling on an asset you write. **Everything you author is held
+at 400.**
+
+The exemption from the line ceiling does not carry here. Its reason is about a file's length, not about how wide one line may be.
+
+No shipped prose asset has a line-ceiling exemption. Agent definitions are
+individual cards under `assistant/agent/`, so their count does not lengthen
+one roster file.
+
+### The owning tree is the one the file sits in
+
+The ceiling applies to **every** shipped assistant prose asset, including
+rules and cards. A rule at the ceiling moves topic detail to
+`rule/references/<topic>.md`; a skill uses its own `references/` directory.
+The tree that owns the file owns its detail.
+
+For a prose asset, raising the ceiling or claiming an exemption is not the remedy. An exemption claims no split is possible, and a Markdown file whose tree has a `references/` home available cannot make that claim.
+
+### Machine-readable assets split in their own format, or say why they cannot
+
+The ceiling is measured over YAML assets too — package routing and review-profile defaults and the shipped contract templates. The split above is not open to them: a validator parses those files as structured data, or a skill copies one whole into a project, so an entry moved into a Markdown sibling under `references/` leaves the parsed document and stops meaning anything. Prose about the
+file may move there; the file's own items may not.
+
+So for a machine-readable asset at the ceiling the remedy is, in order:
+
+1. **Split it in its own format** — a sibling of the same kind that the loader or schema already reads, so every item stays parsed.
+2. **Record an exemption** where the document has to stay whole — a file generated from another asset, one the schema admits only as a single document — naming what makes the split impossible. "This file is long" is not that reason, and a prose asset may not use this step.
+
+## Citation Path Form (Mandatory)
+
+A pointer only resolves if the reader knows what base to resolve it against. There is one base, and it is the project root.
+
+- **Cite a shared rule by its full path from the project root.** Write the path from the project root, with `#anchor` appended when one applies: `.qfai/assistant/rule/drift-protocol.md`. Not the bare filename, not a relative climb. That form resolves from every directory in the tree,
+  and the only one that still resolves when read with the cwd at the project root — which is where an agent's cwd is.
+- **The same holds when a rule cites another one**, including a sibling in its own directory. A bare name works there only by accident of where the citing file sits; it stops working the moment the text is quoted elsewhere.
+- **Within a skill's own directory, keep pointers relative to that directory**: `references/<topic>.md`, `templates/<name>.md`. Those name the skill's own parts, not a shared document, and the surrounding text already establishes which skill is meant.

package/assets/init/.qfai/assistant/rule/references/context-summary.md

@@ -0,0 +1,30 @@
+# Context Summary
+
+Read when a context summary is written.
+
+## Context Summary Contract
+
+When context is summarized, preserve the requests, decisions and stage state
+needed to continue.
+
+Every summary that replaces earlier context keeps these six:
+
+1. Difficulties that came up, and how each was resolved.
+2. Options raised, tried or set aside, and why.
+3. Everything asked for, decided, agreed, ruled out or established as a constraint — in the exact words.
+4. Where things stand: what is covered, settled or complete.
+5. What is still open, promised or expected next.
+6. Details that are hard to reconstruct: names, numbers, dates, exact wording, references.
+
+It also keeps the stage state. None of it can be recovered from the code, and a summary that keeps the six and drops it still misleads the next window.
+
+| Stage state                                                                               | What goes wrong when it is dropped                                                                                   |
+| ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| The execution ledger and the row in progress                                              | Finished rows are worked again, or a row in `red` is taken for untouched                                             |
+| Every open question, with its ID and status                                               | A question stays open with nobody tracking it, or is answered twice                                                  |
+| The clarification budget spent in this invocation, and the questions it was spent on      | The next window asks what the user already answered, or asks past the cap                                            |
+| Every assumption recorded under `--auto` or after the budget ran out, with its label      | A labelled assumption is read back as a decision someone took                                                        |
+| Whether the stage's review has run, and each finding's fix or answer                      | The review runs a second time, or an answered finding is raised again (`.qfai/assistant/rule/review-convergence.md`) |
+| A grilling session's decision tree, its current frontier, and the answers already settled | An answered question is asked again, or a question is put before the one it depends on (`.agents/rules/grilling.md`) |
+
+Keep what the user said close to their own words. Your own reasoning may be condensed to what it concluded, as long as nothing listed above is dropped. Be complete on these items even when that makes the summary longer.

package/assets/init/.qfai/assistant/rule/references/gate-failure-autorepair.md

@@ -0,0 +1,42 @@
+# Gate Failure Autorepair
+
+Read when a gate fails.
+
+## Gate Failure Autorepair Protocol
+
+Follow this protocol when any of the validate, doctor, test, lint, typecheck, build, capture, or report gates fail. A reviewer's `REVISE` is not a gate failure and is not rerun: the author fixes or answers each finding once, as `.qfai/assistant/rule/review-convergence.md` sets out.
+
+- inspect exit code, logs, `validate.json`, and cited files before reporting — in `validate.json`, read `counts` for the verdict and `issues[].code` for each finding; the array is `issues`, not `findings`;
+- classify each finding as skill-owned artifact, upstream spec/contract, code/test defect, environment/tooling, or user decision;
+- fix skill-owned artifacts and code/test defects autonomously when the fix is local and non-destructive;
+- **upstream spec/contract findings: never repair.** STOP and follow `.qfai/assistant/rule/drift-protocol.md` (Change Request + owner-skill rerun) — **even when the fix looks local and non-destructive, and even when it is one token and obviously correct**. "Local and non-destructive" is a permission for the two classes above it; it is not a test that upstream artifacts can pass.
+  Ownership, not size, decides;
+- environment/tooling findings: repair the environment when it is yours to repair (install a missing dev dependency, regenerate a lockfile, create a scratch directory). Stop for anything needing credentials, network access you do not have, or a change to CI configuration or the host machine;
+- user decision findings: never decide by default. Record the question, state the option you would take and why, and stop — a decision taken silently to keep a gate green is the same failure as repairing upstream, one layer up;
+- rerun the same failing gate after each fix batch, **and once with no intervening change** when the failure looks nondeterministic — see `#nondeterministic-gates` below. The confirmation rerun is bounded at one: after it the finding is classified, not re-rolled;
+- do not weaken profiles, lower `--fail-on`, waive errors, invent evidence, or skip required reviewers;
+- stop for destructive changes, **any upstream spec/contract finding**, ambiguous product/spec decisions, missing permissions/tools, or repeated no-progress failures — the stop list is closed over the classification above, so every class the agent is told to use has a defined next action;
+
+When stopping, report: cause, attempted fixes, remaining blocker, user action, retry gate, and **the work counts — how many items are complete, how many are blocked, and by which finding**.
+
+The counts are not decoration. Restating the ownership rule does not change the incentive that breaks it: an agent facing "repair five upstream defects or report most of the batch as blocked" reaches for the repair because the alternative reads as failure. `26 items: 21 complete, 5 blocked on DB-0007` is a report of work done, and it is what makes STOP a credible answer rather than a
+surrender. Blocked is a status, not a verdict on the run.
+
+### Nondeterministic gates
+
+A gate whose answer varies on identical inputs is a finding in its own right, not a run to discard. The protocol classifies it as `environment/tooling`; what follows is what that class obliges.
+
+**When a gate fails and a rerun with no intervening change passes**, all of the following are REQUIRED. A clean rerun on its own is not evidence for that gate.
+
+- **Record it as an `environment/tooling` finding.** Not as a pass, and not as a code/test defect — nothing was fixed between the two runs.
+- **Disclose every run.** Report the results of all runs of that gate, in order, with their commands. Reporting only the run that passed is [selective reporting](#selective-reporting-is-invented-evidence) and is forbidden: the evidence rules are satisfied by a clean run's command and output, so nothing else stops it.
+- **Re-run the failing selectors in isolation** and report that result too. A selector that passes alone and fails in the suite is the signature of shared state, not of a defect in that test.
+- **Name the suspected cause**, concretely: a contended port, a shared database or schema, an `os.tmpdir()` path, an un-namespaced cache or queue, ordering between workers. "Flaky" is not a cause.
+
+Do not fix the flake by rerunning until green, and do not fix it by weakening the test. Either the shared resource is isolated per worker or the run is serialised — both are real changes with a real cost, which is the point.
+
+A gate reported this way has **not passed**. It is a blocker with a named cause, and it goes in the stop report like any other.
+
+#### Selective reporting is invented evidence
+
+Reporting the clean run and omitting the red ones satisfies every existing evidence rule — a real command, a real result, freshly obtained — and still misrepresents what happened. Which of N runs is reported is itself part of the evidence, so omitting runs of the same gate is on the same footing as inventing one.

package/assets/init/.qfai/assistant/rule/references/griller-recommendations.md

@@ -0,0 +1,23 @@
+# Griller Recommendations
+
+Read when a griller's recommendation is used.
+
+## A griller's recommendations, and what they disqualify
+
+A grilling session puts a recommended answer beside each question (`.agents/rules/grilling.md`). Who settled the decision decides what happens next.
+
+| The decision was settled                              | What follows                                                                      |
+| ----------------------------------------------------- | --------------------------------------------------------------------------------- |
+| By the user, from the recommendation among the inputs | The decision is theirs. The griller may review the artifact                       |
+| Agent to agent, not critical                          | The decision stands. The griller that recommended it does not review the artifact |
+| Agent to agent, critical, with no user adjudication   | The artifact is wrong, and no reviewer can clear it                               |
+
+**The second row is how a delegated session is meant to end** (`.agents/rules/grilling.md`), not a finding. The reviewer checks that the decision is in the final report and is not critical. A reviewer that doubts its merit raises that as an ordinary finding against the artifact, under its own remit, as it would for any other content.
+
+**The third row is not a routing problem.** A critical decision is the user's in every session, and a run that could not ask records it as an open question rather than adopting it. An agent-adopted critical decision is therefore an artifact carrying something nobody with the standing decided, and handing it to a different reviewer would launder it.
+The reviewer must return `REVISE` and name the decision: it is reopened and put to the user, or recorded open where no question can be asked.
+
+The first row needs a reason, because the intuitive one is wrong. A sub-agent starting with a reset context cannot defer to something it does not remember, so deference is not the risk. **Correlation** is: a fresh instance of the same agent, on the same model, over the same evidence, re-derives the preference that produced the recommendation and finds it good on the merits. Resetting the
+context removes the memory, not the disposition — which is why role name alone never establishes independence either. Where the user chose, that disposition is one input among several and the decision is not the griller's to re-derive.
+
+**The stage's final report is the record.** It lists every decision the agents adopted and the agent that recommended it, so a reviewer with a reset context reads the third row off the report rather than off recollection.

package/assets/init/.qfai/assistant/rule/references/host-backstops.md

@@ -0,0 +1,60 @@
+# Host Backstops
+
+Read when a host limit on agents is involved.
+
+## Host backstops above the declared shape
+
+The dispatch limits in this baseline and in each skill's own policy are read by
+the agent doing the dispatch. A run that has lost its way is the one least likely
+to apply them, so nothing here bounds a run that spawns more workers than it
+declared, nests delegation deeper than the stage intended, or keeps spending.
+
+Some hosts refuse delegation outside their limits. Each control below states
+what it covers.
+QFAI sets none of them, so the host defaults stand.
+
+**A backstop sits above the declared shape, never at it.** Leave room for other
+permitted agents sharing the host limit. The policy decides the ordinary case.
+
+Claude Code 2.1.217 or later:
+
+| Control                                                                              | Default                      | What it bounds                                             |
+| ------------------------------------------------------------------------------------ | ---------------------------- | ---------------------------------------------------------- |
+| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`                                               | 3 (1 in 2.1.217 and 2.1.218) | How deep delegation nests. `1` turns nesting off           |
+| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`                                               | 20                           | When new Agent tool spawns are refused                     |
+| `--max-budget-usd` in print mode; `maxBudgetUsd` / `max_budget_usd` in the Agent SDK | none                         | What one run may spend, in US dollars, sub-agents included |
+
+The spawn limit has exceptions for ultracode, `/subtask` forks, and resuming an
+exited agent.
+
+Codex:
+
+| Control                                                                                   | Default                    | What it bounds                                                        |
+| ----------------------------------------------------------------------------------------- | -------------------------- | --------------------------------------------------------------------- |
+| `agents.max_concurrent_threads_per_session` in `config.toml` (alias `agents.max_threads`) | chosen by Codex when unset | How many spawned-agent threads are open at once, the primary excluded |
+
+No equivalent was confirmed for nesting depth or for a spend cap.
+
+GitHub Copilot CLI:
+
+| Control                            | Documented default                   | What it bounds                           |
+| ---------------------------------- | ------------------------------------ | ---------------------------------------- |
+| `subagents.maxDepth` setting       | 6 in the limits table                | How deep sub-agents nest                 |
+| `COPILOT_SUBAGENT_MAX_DEPTH`       | 4 in the environment-variable table  | How deep sub-agents nest                 |
+| `subagents.maxConcurrency` setting | set by the Copilot plan, 2 to 32     | How many sub-agents run at once          |
+| `COPILOT_SUBAGENT_MAX_CONCURRENT`  | 32 in the environment-variable table | How many sub-agents run at once          |
+| `--max-ai-credits`                 | unset                                | AI credits per response, as a soft limit |
+
+The two settings take effect only on usage-based billing plans.
+
+The depth defaults disagree across the CLI documentation. Which control takes
+precedence was not confirmed.
+
+VS Code Local harness (`runSubagent`):
+
+| Control                                        | Default | What it bounds                                                        |
+| ---------------------------------------------- | ------- | --------------------------------------------------------------------- |
+| `chat.subagents.allowInvocationsFromSubagents` | `false` | Whether a sub-agent may start sub-agents. Nesting stops at depth five |
+
+No equivalent was confirmed for concurrent sub-agents or for a spend cap. None
+was confirmed for any of the three in the Copilot cloud agent.

package/assets/init/.qfai/assistant/rule/references/placeholder-scan.md

@@ -0,0 +1,25 @@
+# Placeholder Scan
+
+Read when the placeholder scan reports a hit.
+
+## What the placeholder scan does not flag
+
+**`OQ` and `OPEN QUESTION` are exempt only as tracking structure.** Exempt: the `Open Questions` heading, a register
+table header, and a question row containing the fields required by its register. Story-tree `open-questions.md` uses
+`ID | Content | Approach | Status`; an empty register contains the heading and table header without a question row.
+Discussion registers use their own template fields. A register row's Status is structure too: `TODO` in the Status cell of a
+`decisions.md` or `open-questions.md` row is the row's state, not a placeholder. Article II and `.qfai/assistant/rule/workflow.md` both end an
+unverifiable fact by recording an Open Question, so the tracked record they prescribe must never be reported as an
+unresolved placeholder. Everywhere else the two strings are still scanned: a bare `OQ` or `OPEN QUESTION` left as a
+value in generated spec prose or a contract field, or a row missing a required field, is a hit like any other token.
+
+**A documented `TBD` is a compliant record.** `.qfai/assistant/rule/constitution.md` Article II and `.qfai/assistant/rule/thinking.md` require writing `TBD` together with a note of what evidence is missing, and `.qfai/assistant/rule/thinking.md` requires raising the matching Open Question for the same fact. Both halves together are the finished form, not an
+unfinished one; do not report it and do not delete it — deleting it destroys the record of the missing evidence, which is the whole point of the marker. A `TBD` missing either half — no note, or no Open Question — is a hit.
+
+## What a surviving hit obligates
+
+A hit is **reported, not silently cleared**, and **cleared by a re-scan, not by assertion**. Fix what you can, then run the scan again over the same artifacts: _resolved_ is the verdict for a hit the re-run no longer reports, and that re-run is its evidence. It is not available for a hit still present at that file and line — a token still readable there is unresolved whatever the report
+calls it. List every hit the re-scan still finds alongside the completion claim — file, line, token — and state for each one whether it is deferred with rationale or recorded as an Open Question. A completion claim that omits a surviving hit is invalid evidence under the rules above. Completion is blocked while a surviving hit is neither of the two.
+
+**Severity floor on the verdict.** _Deferred with rationale_ and _recorded as an Open Question_ are NOT available for a hit that stands in for a concrete security defect, data loss or corruption, or a correctness defect that would break a released contract. Such a hit is cleared only by a named fix or by dropping the item from scope; recording it and declaring completion anyway is
+prohibited, exactly as `.qfai/assistant/rule/shared-skill-delegation-baseline.md` withholds that same exit for that same class. While neither of the two remaining verdicts applies, completion stays blocked.

package/assets/init/.qfai/assistant/rule/references/reviewer-findings.md

@@ -0,0 +1,41 @@
+# Reviewer Findings
+
+Read when a reviewer finding is written or judged.
+
+## Finding provenance
+
+- Every finding must declare a severity (`blocking` or `advisory`) and a `Traces to:` value.
+- `Traces to:` names what the finding enforces. Legal values:
+  - an upstream obligation — a `BF-*`, `AC-*`, `EX-*`, `BR-*` or contract ID, or a named shared rule **that governs the product's behaviour**;
+  - `defect:correctness`, `defect:security`, or `defect:code-quality` — a defect demonstrable from the changed artifacts themselves, cited with the evidence that demonstrates it (see `.qfai/assistant/rule/drift-protocol.md#defect-or-new-scope-decide-this-first`). A reviewer who can show the deliverable is wrong on its own terms does not need an `AC-*` to say so;
+  - `record:<CODE>` — a defect in the run's own record rather than in the product: an evidence section, a round block, an anchor, or provenance prose. `<CODE>` names the record rule;
+  - `none` — reviewer-originated scope, i.e. a new product obligation upstream never asked for.
+- `record:*` and `none` MUST be recorded as `advisory`; neither can be `blocking` or gate `DONE`. A `record:*` finding never re-runs the row: the orchestrator files it in the record-defect queue the reviewing stage's own completion contract names, and that contract is what drains it (`.qfai/assistant/rule/drift-protocol.md#the-record-defect-queue`). **The class needs a drain:
+  only a stage whose completion conditions require that queue drained may use it — today `/qfai-implement` alone, so `/qfai-sdd`, `/qfai-configure`, `/qfai-verify`, `/qfai-discussion` and `/web-research` reviewers must not, and there the finding keeps the class it would otherwise have had.** An entry closes only on a repaired record;
+  `record:unchecked` is never a substitute for the repair — a record rule worth a round is worth a validator code.
+- **Integrity is not record class.** Evidence copied from another round or a sibling row, an anchor resolving to a run other than the one it names, and a reviewer that authored what it reviews all claim work that was not done or independence that is missing. A `PASS` built on them is refused,
+  so they stay `blocking` as `defect:code-quality` and are never filed as `record:*` — which covers an honestly produced record that is merely wrong.
+- A `none` advisory takes the Change Request / Open Question path (`.qfai/assistant/rule/drift-protocol.md#reviewer-originated-obligations`); a `record:*` advisory takes the queue above. Neither goes to the implementer.
+- Only `blocking` findings force `REVISE`, and only a finding citing a behaviour-governing obligation or a defect class may be one. **The trace class bounds which findings may block; the severity is declared, and it settles whether one does.** Read as "an obligation trace is blocking", the same item was a discussion-blocking defect to one reviewer and carried advice to the next.
+- An obligation-traced finding is recorded `advisory` where a named section places the work outside the reviewed stage. The discussion review's implementation precision is that section
+  (`.qfai/assistant/rule/review-convergence.md#discussion-review-precision`): the obligation is agreed, and what the advice is about is how a later stage implements it, so the finding is carried to that stage rather than demanded here. Nothing else lowers a behaviour-governing finding to `advisory`.
+
+## What a reviewer may demand more of (MUST)
+
+A finding that asks for more work — another item, more detail, a wider set — is admissible only on
+the concrete artifacts.
+
+| Admissible on                                                           | Inadmissible on                                                                   |
+| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| business flows, user stories, acceptance criteria, examples, test cases | business rules, non-functional requirements, policies and decisions, architecture |
+
+Two demands stay admissible on any artifact:
+
+- that an abstract item already recorded carry its mandatory pair, such as a quality floor naming
+  its verification method;
+- that a safety-floor item be met: security, accessibility, data-loss handling, or validation at a
+  trust boundary (`.agents/rules/minimal-implementation.md` § 2).
+
+This bounds what a reviewer may require, never what a reviewer may report. A demand the table does
+not admit, such as one for another business rule, is recorded as `advisory` and cannot force
+`REVISE`.

package/assets/init/.qfai/assistant/rule/references/reviewer-remit.md

@@ -0,0 +1,35 @@
+# Reviewer Remit
+
+Read when a reviewer is briefed.
+
+## Reviewer remit (in scope per stage)
+
+A finding outside the reviewing stage's remit is recorded and deferred, never blocking:
+
+| Stage                      | In scope                                                                                                                                                                                                                                               | Out of scope (record and defer)                                                                                      |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `/qfai-discussion`         | Requirement clarity, scope boundary, decision traceability                                                                                                                                                                                             | Spec structure, runtime behavior                                                                                     |
+| `/qfai-sdd`                | Spec / contract consistency, testability, traceability edges, each document in its template's shape                                                                                                                                                    | Runtime enforcement correctness, code quality                                                                        |
+| `/qfai-implement`          | Code quality, spec alignment of the item, RED/GREEN evidence, silent failure and type design across the whole of every file the change touches, and security across the same files and along every input the change adds or alters to where it is used | Upstream spec content, contract design, and a finding on code in a touched file that the change did not add or alter |
+| `/qfai-prototyping`        | The prototype against its UI contracts and the root `DESIGN.md`, loop evidence, the handoff                                                                                                                                                            | Spec and contract content, downstream implementation code                                                            |
+| `/qfai-migration-v1-to-v2` | Migration plan and report fidelity, ID mapping, every deletion listed in the reports, each written document in its template's shape                                                                                                                    | New story content and downstream implementation quality                                                              |
+| `/qfai-configure`          | Config / manifest validity and the surfaces the run generated                                                                                                                                                                                          | Spec content, implementation structure                                                                               |
+| `/qfai-verify`             | Gate execution, evidence completeness, report / artifact fidelity                                                                                                                                                                                      | Authoring quality of the artifacts it verifies                                                                       |
+| `/web-research`            | Source authority and freshness, citation accuracy, claim support                                                                                                                                                                                       | Spec content, implementation structure                                                                               |
+| `/qfai-grilling`           | Decisions asked rather than assumed, facts naming where they were read, the session's end condition                                                                                                                                                    | The merit of what the user decided, and the artifacts the invoking stage writes from it                              |
+| `/qfai-grill`              | The same, reported to the user rather than to a stage                                                                                                                                                                                                  | The merit of what the user decided; there is no artifact to review                                                   |
+| `/qfai-maintain`           | That the diff changes no behaviour, and the checks run over it                                                                                                                                                                                         | Whether the new wording is the better one                                                                            |
+| `/qfai-triage`             | That no tracked file changed, the recorded outcome, each follow-up, and the sources an answer cites                                                                                                                                                    | The work a follow-up request describes                                                                               |
+| `/qfai-run`                | The artifacts the session writes, in the specification or code review the plan names after a stage                                                                                                                                                     | Whether the route the decision rules chose was the right one                                                         |
+
+Article VII excess in the reviewing stage's own artifacts is in scope;
+quality of downstream implementation code is deferred at upstream stages.
+
+Apply this route only where the installed Article VII governs the artifact.
+A retained constitution does not gain newer authority from refreshed cards.
+Report an unsupported Article VII route as advisory and follow the installed constitution.
+
+A step's remit is its owner's row. A `common-*` step's work is reviewed under
+the row of the skill whose stage ran it.
+
+**Fallback for any stage not listed.** A stage that references this baseline without a row above has, as its remit, the artifacts that stage itself produces; everything upstream of them is out of scope, recorded and deferred. Add the row when a new stage starts routing blocking reviewers, so the in/out split is not re-derived per run.