qfai 2.1.0 → 2.1.2

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.

package/assets/init/.qfai/assistant/rule/references/worker-edit-boundary.md

@@ -0,0 +1,48 @@
+# Worker edits and work orders
+
+Read when assigning worker write paths or handling a refused edit.
+
+## Edit boundary
+
+The work order names the checkout assigned to the task by the host, the worker's
+write paths and the permitted edit method. Creating a Git worktree does not
+grant the host's tools permission to edit it. Even an assigned checkout can
+receive a refusal; verify the actual edit result rather than claiming access.
+
+If an edit is refused, stop writes to that target. Report the tool, working
+directory, target path and refusal text, omitting secrets. Return the owned
+paths and a reviewable diff that can be prepared within the worker's permitted
+area. Do not bypass the refusal through a shell, script or another tool.
+This does not forbid shell authoring where the host already permits it.
+
+The orchestrator checks the diff against the current files in its own permitted
+checkout before applying it. If that edit is refused too, leave the application
+pending and continue only independent work. Follow the existing worktree or
+shared-index mode in `.qfai/assistant/rule/workflow.md#concurrency-stage-independent-mandatory`
+when assigning writers and integrating their paths.
+
+## Work order template
+
+```text
+Task title: <short>
+Role: <sub-agent role>
+Review series: <reviewed artifact> + <reviewer role> + <replacement ordinal>   # review work orders only
+Goal: <what to decide/produce>
+Checkout: <absolute checkout assigned to this task by the host>
+Write paths: <exact owned paths, or none for a read-only task>
+Edit method: <host-permitted tool; worktree creation does not grant access>
+If an edit is refused: stop that target; return tool, cwd, target, refusal text, owned paths and a reviewable diff
+Inputs (refs):
+- <file/section>
+- .qfai/assistant/rule/drift-protocol.md#core-rule  <!-- the protected set, in front of the agent -->
+Constraints:
+- must: enforce Drift Protocol
+- must: follow applicable test-layer or validation policy
+- must_not: patch upstream artifacts directly; every upstream change requires
+  STOP + Change Request + owner rerun per .qfai/assistant/rule/drift-protocol.md
+Output format:
+- <headings / bullet schema>
+Time budget: none | <seconds>   # advisory: nothing stops at it. See .qfai/assistant/rule/stage-cost.md
+Elapsed line: end every message with `elapsed <seconds>s / <budget>s`, or `elapsed <seconds>s` when the budget is none
+Acceptance bar: <accept when ...> | <rework when ...>   # never `PASS`/`REVISE`: that is the reviewer's vocabulary and the completion gate matches on it, so a doer told to report in it emits a verdict on its own work
+```

package/assets/init/.qfai/assistant/rule/shared-skill-delegation-baseline.md

@@ -1,12 +1,12 @@
 # Shared Skill Delegation Baseline
 
-Use this document to keep SKILL bodies compact. Skill files should reference this baseline and only add role-, stage-, or gate-specific rules.
+Skills cite this baseline and add only role, stage or gate overrides.
 
 ## Sub-agent Delegation (MANDATORY)
 
-This section binds every skill and every step as written. A skill or step
-restates none of it and writes no placeholder stanza for a subsection it does
-not change; it states only an override, under the subsection it overrides.
+This section binds every skill and step. A skill or step repeats none of it
+and adds no placeholder for a subsection it does not change. State only an
+override, under the subsection it overrides.
 
 Delegation is optional. The session agent, called the orchestrator below, may
 author any artifact itself. It uses a sub-agent only for work that runs in
@@ -23,9 +23,32 @@ classified by the taxonomy below before any response.
 - The orchestrator may author any artifact itself, or give independent parts of
   the work to sub-agents that run in parallel. It integrates and presents the
   results.
+- The orchestrator is not required to wait while a sub-agent runs. Where the
+  host starts a delegation and returns at once, delivers the finished result
+  later as a message, and lets the orchestrator wait for a result on purpose,
+  the orchestrator carries on with its own work meanwhile and waits only when
+  it has none. A host without all three keeps the orchestrator waiting.
+- That work is planning, preparing the next work order, integrating results
+  already returned, and its own part of the task. It never repeats the work it
+  handed out. Starting another delegation needs the independence conditions of
+  `.qfai/assistant/skill/qfai-implement/references/parallelization-policy.md`.
+  Where the stage's ledger or a seam makes an ordering mandatory, carrying on
+  does not override it.
 - A review is done by an agent that did not author what it reviews. The
   orchestrator never reviews its own work and never approves it for
   convenience.
+- A read-only agent never runs `git checkout` or `git switch` in a worktree it
+  shares; it reads other revisions with `git show <rev>:<path>`. Each agent
+  writes scratch files only under a path of its own.
+- Give each reviewer a fixed commit. Leave the checkout alone until reviews
+  return. Only read-only fixed-SHA `git show` reviews permit clean switches.
+  Writers, local gates and reviews using live files or checkout-dependent
+  execution must finish first.
+
+### Worker edit boundary
+
+Before assigning write paths or handling a refused edit, read
+`.qfai/assistant/rule/references/worker-edit-boundary.md`.
 
 ### Capability Probe (MUST)
 
@@ -95,68 +118,13 @@ has to do, and the class is `unavailable` or
 ### Commit Scoping
 
 - A delegated agent stages only the paths it declared as deliverables in its work order: `git add <path> …`.
-- `git add -A`, `git add .` and `git commit -a` are forbidden for delegated agents, in both isolation modes. In degraded / shared-index mode the concurrent agents share one index, so a sweeping stage command commits a sibling agent's in-flight files and misattributes work in the audit trail. Under worktree separation there is no shared index and no sibling file to sweep, but the command
-  still stages everything else loose in that agent's own worktree, so the commit still stops matching its declared deliverables.
-- When the agent's deliverable paths are not known up front, it hands back an unstaged diff and the orchestrator commits — under the same rule. The orchestrator commits one handed-back diff at a time, stages that agent's declared paths only, and is equally forbidden from `git add -A` / `git add .` / `git commit -a` while a parallel stage is in flight. Being the committer does not exempt
-  it; in degraded mode it is the only committer, so a sweeping stage there mixes every sibling's work into one commit.
+- `git add -A`, `git add .` and `git commit -a` are forbidden for delegated agents, in both isolation modes. In degraded / shared-index mode the concurrent agents share one index, so a sweeping stage command commits a sibling agent's in-flight files and misattributes work in the audit trail. Under worktree separation the command still stages whatever else is loose in that agent's own worktree.
+- When the agent's deliverable paths are not known up front, it hands back an unstaged diff and the orchestrator commits — under the same rule. The orchestrator commits one handed-back diff at a time, stages that agent's declared paths only, and is equally forbidden from `git add -A` / `git add .` / `git commit -a` while a parallel stage is in flight. Being the committer does not exempt it.
 - Isolation requirements for concurrent stages are defined once in `.qfai/assistant/rule/workflow.md#concurrency-stage-independent-mandatory`.
 
 ### 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.
+Read `.qfai/assistant/rule/references/host-backstops.md` when you set or read a host limit on agents, or a run stops at one. It holds the backstops each host applies above the declared shape and how to leave room for them. Not needed when no host limit is involved.
 
 ## Work Orders Summary
 
@@ -201,26 +169,6 @@ use subagents to verify your own work" does not apply to this gate. The
 definition above already excludes an agent reviewing its own output. The author
 cannot accept its own output.
 
-#### 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.
-
 - Reviewers must verify Drift Protocol enforcement
   (`.qfai/assistant/rule/drift-protocol.md`).
 - Reviewers must verify test-layer policy enforcement when relevant
@@ -231,79 +179,25 @@ context removes the memory, not the disposition — which is why role name alone
 - An in-scope blocking finding from a routed reviewer prevents DONE until it is fixed or answered; no reviewer is rerun.
 - Every reviewer returning `REVISE` must include a concrete fix proposal.
 
+#### A griller's recommendations, and what they disqualify
+
+Read `.qfai/assistant/rule/references/griller-recommendations.md` when a griller's recommendation is offered as evidence for a decision, or when you check whether a griller may review the work it interviewed. Not needed otherwise.
+
 ### Review convergence
 
 A stage is reviewed once, and the author fixes or answers every finding with no re-review: `.qfai/assistant/rule/review-convergence.md`.
 
 ### 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 | 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.
+Read `.qfai/assistant/rule/references/reviewer-remit.md` when you brief a reviewer or judge whether a finding is in scope for the stage under review. It holds what each stage's reviewer may and may not examine. Not needed when no review runs.
 
 ### 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 a bug report against `validateTddList` and 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`.
+Read `.qfai/assistant/rule/references/reviewer-findings.md` when you write or judge a reviewer finding: where it comes from, and what a reviewer may demand more of. Not needed when no review runs.
 
 ### 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`.
+What a reviewer may demand is in `.qfai/assistant/rule/references/reviewer-findings.md`, read under the condition above.
 
 ### Reviewer budget exhausted
 
@@ -325,25 +219,8 @@ A blocking review that cannot be delegated because the agent budget is spent is
 
 ## Work order template
 
-```text
-Task title: <short>
-Role: <sub-agent role>
-Review series: <reviewed artifact> + <reviewer role> + <replacement ordinal>   # review work orders only
-Goal: <what to decide/produce>
-Inputs (refs):
-- <file/section>
-- .qfai/assistant/rule/drift-protocol.md#core-rule  <!-- the protected set, in front of the agent -->
-Constraints:
-- must: enforce Drift Protocol
-- must: follow applicable test-layer or validation policy
-- must_not: patch upstream artifacts directly; every upstream change requires
-  STOP + Change Request + owner rerun per .qfai/assistant/rule/drift-protocol.md
-Output format:
-- <headings / bullet schema>
-Time budget: none | <seconds>   # advisory: nothing stops at it. See .qfai/assistant/rule/stage-cost.md
-Elapsed line: end every message with `elapsed <seconds>s / <budget>s`, or `elapsed <seconds>s` when the budget is none
-Acceptance bar: <accept when ...> | <rework when ...>   # never `PASS`/`REVISE`: that is the reviewer's vocabulary and the completion gate matches on it, so a doer told to report in it emits a verdict on its own work
-```
+When preparing a delegation, use the template in
+`.qfai/assistant/rule/references/worker-edit-boundary.md#work-order-template`.
 
 ## Reviewer response template