qfai 2.1.0 → 2.1.1

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

@@ -23,9 +23,25 @@ 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.
+- Commit the change, or give each reviewer a fixed commit, before a review
+  starts, and leave the working tree alone until every review returns.
 
 ### Capability Probe (MUST)
 
@@ -95,68 +111,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 +162,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 +172,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
 

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

@@ -4,70 +4,11 @@ Use this document to keep SKILL bodies compact. Skill files should reference thi
 
 ## 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.
+Read `.qfai/assistant/rule/references/asset-authoring.md` when you write or change a file under `.qfai/assistant/**` or another shipped asset, including its citation paths. It holds the shape every asset takes, which tree owns a file, how machine-readable assets split, and the form of a citation path. Not needed for a run that only reads assets or edits project files.
 
 ## 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.
+The form of a citation path is in `.qfai/assistant/rule/references/asset-authoring.md`, read under the same condition as the section above.
 
 ## User Questions (AskUserQuestion Protocol)
 
@@ -351,69 +292,11 @@ can resolve stops at preflight.
 
 ## 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` (keys: `.qfai/assistant/skill/qfai-verify/references/validate-json-schema.md`);
-- 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.
+Read `.qfai/assistant/rule/references/gate-failure-autorepair.md` when a gate command fails or its result cannot be trusted. It holds the repair loop (inspect, classify, fix, rerun), the findings that are never repaired, when to stop and what to report, and how a gate that does not give the same answer twice is handled. Not needed while every gate passes.
 
 ## 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.
+Read `.qfai/assistant/rule/references/context-summary.md` when you hand work to a sub-agent or summarize a context for the next stage. It holds what a summary that replaces earlier context must keep. Not needed when no summary is written.
 
 ## Completion Contract (Shared)
 
@@ -433,22 +316,8 @@ report instead of the completion claim.
 
 ### 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.
+Read `.qfai/assistant/rule/references/placeholder-scan.md` when the placeholder scan reports a hit or you decide a hit is not a defect. It lists what the scan does not flag and what a surviving hit obligates. Not needed while the scan reports nothing.
 
 ### 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.
+The obligation a surviving hit carries is in `.qfai/assistant/rule/references/placeholder-scan.md`, read under the condition above.

package/assets/init/.qfai/assistant/rule/stage-cost.md

@@ -1,6 +1,6 @@
 # Stage Cost
 
-What a stage costs, and the levers that change it: how deeply a model reasons
+What a stage costs, and the settings that change it: how deeply a model reasons
 per step, how long the stage is given, and how much of a file an edit rewrites.
 
 None of them is a cap. Where a hard limit is wanted, it is the per-request

package/assets/init/.qfai/assistant/rule/test-layers.md

@@ -26,6 +26,9 @@ locations; a file outside the selection does not establish coverage.
 
 Exercise one unit's observable decisions without real infrastructure. A
 `QFAI:EX-NNNN-NNNN-NN` annotation links a behavioral unit test to its example.
+The annotation counts only on the comment line directly before the `it(`,
+`test(` or `describe(` it marks, or the equivalent test declaration of another
+framework; a file header or a comment inside a test body covers nothing.
 
 ### L2 Component
 
@@ -91,6 +94,45 @@ EX may need an additional focused test even when its parent AC or BF is
 covered. Keep independently observable cases in separate tests so a failure
 points to the behavior that changed.
 
+## Test-suite sizing
+
+Every source change still carries test coverage, and every obligation still
+has its test. This section sizes that coverage. It never removes any.
+
+- **Size a new test file like the ones next to it.** Aim for roughly one
+  focused test per stated behaviour.
+- **Choose a process-per-case suite, never inherit one.** A suite that spawns a
+  process for every case is the shape that makes a CI lane expensive. Pick it
+  for the suite in hand, not because the file beside it has it.
+- **A scratch check is not a deliverable.** Verify the work in progress any way
+  you like. Do not turn a scratch check into a permanent test file. Scratch
+  files go where `.agents/rules/temporary-files.md` puts them.
+
+These are review signals, not gates. No validator reads them.
+
+## End-to-end test cost
+
+An end-to-end test is the slowest test a project runs, and a failing one costs
+the most. A test that cannot find an element waits for its whole timeout, and
+waits again for every retry. One failure costs the timeout times the attempts,
+and a red suite with no limit runs until the job is killed. The number of
+failures sets the bill more than the number of tests does.
+
+- **Set a failure limit.** Stop the run after a small number of failures.
+- **Set a job time limit** well below the CI platform's default.
+- **Lower the test timeout** to what a passing test needs. Allow at most one
+  retry in CI.
+- **Do not share one database across parallel workers.** Concurrent tests
+  change each other's data, so one commit gives different results and a
+  failure cannot be told from noise. Give each worker its own data, or run one
+  worker.
+- **Record traces only on a retry in CI,** not on every test.
+- **Hold a count ceiling that only moves down.** Count end-to-end tests per
+  business flow, not per story or example. Prove an acceptance criterion or an
+  example in a lower layer.
+
+These are review signals, not gates. No validator reads them.
+
 ## Test stub detection
 
 A test is incomplete if its body contains a placeholder, skips the

package/assets/init/.qfai/assistant/skill/qfai-configure/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: qfai-configure
 title: QFAI Configure (Tune qfai.config.yaml)
-description: "Analyze the repository and tune qfai.config.yaml test globs and project overrides."
+description: "Analyze the repository and tune qfai.config.yaml test globs and project overrides. Use when asked to configure QFAI for a repository, or to fix test globs that match the wrong files or none."
 argument-hint: "[--auto]"
 allowed-tools: [Read, Glob, Write, Edit, TodoWrite, Task, Agent]
 roles:
@@ -25,7 +25,7 @@ QFAI Skill Body (SSOT)
 
 ## /qfai-configure - Configure QFAI for this repository
 
-[DRIFT-PROTOCOL:MANDATORY]
+[DRIFT-PROTOCOL:REQUIRED]
 
 ## User Questions (AskUserQuestion Protocol)
 
@@ -69,18 +69,6 @@ When unsure, read inputs in this order:
 
 Follow `.qfai/assistant/rule/shared-skill-delegation-baseline.md`.
 
-### Orchestrator Protocol
-
-- No additional overrides.
-
-### Capability Probe
-
-- No additional overrides.
-
-### Delegation Failure (Hard Stop)
-
-- No additional overrides.
-
 ### Work Orders Summary (evidence)
 
 Use the shared schema.
@@ -179,30 +167,13 @@ The final report includes:
 - gaps and open risks ("none" is acceptable if justified)
 - the final status (PASS/FAIL) and who confirmed it
 
-## Non-Negotiable Principles (QFAI Articles)
-
-These principles are inspired by "constitution / articles" patterns used by other agent frameworks, but adapted to QFAI.
-
-1. **SDD First (Specification is the source of truth)**  
-   If there is a conflict between code and spec, treat the spec as authoritative and either (a) fix code or (b) raise an explicit Open Question to change the spec.
+## Working principles
 
-2. **Traceability is mandatory**  
-   Every meaningful change must connect a business flow, story, acceptance criterion, example, test, code, and verification evidence. BF is covered by E2E tests, AC by integration or API tests, and EX by a selected non-E2E test. Full rule: `.qfai/assistant/rule/constitution.md` Article V.
-
-3. **Evidence over confidence**  
-   Prefer observable proof (logs, commands, file diffs, test results). If you cannot verify, say so and record it.
-
-4. **Minimize scope, but never hide gaps**  
-   Keep changes minimal, but do not "paper over" missing decisions. If something blocks correctness, stop and ask.
-
-5. **Quality gates are the decision mechanism**  
-   Use tests/lint/typecheck/build/pack verification (whatever the repo defines) as the primary guardrail. Fix until PASS.
-
-6. **Make it runnable**  
-   Outputs must be executable in terminal/CI. Provide copy-paste commands.
-
-7. **User time is expensive**  
-   Ask only the questions that are truly blocking. Everything else: make reasonable assumptions and label them clearly.
+Read `references/principles.md` when a choice is not settled by a step below.
+It holds the seven principles the steps follow: the specification is the
+source of truth, traceability, evidence over confidence, minimal scope without
+hidden gaps, quality gates, runnable output, and the user's time. A choice a step
+settles needs no reading of it.
 
 ## README Rule
 
@@ -244,11 +215,6 @@ Return:
 - proposed globs + rationale + evidence refs
 ```
 
-### Failure rule
-
-- A delegation the orchestrator chose to make is its own capability check.
-- A failed delegation is handled as `.qfai/assistant/rule/shared-skill-delegation-baseline.md` sets out. Do not simulate roles.
-
 ## Completion Separation (mandatory)
 
 - Config changes (`devops-ci-engineer`) and their approval (`qa-gatekeeper`) must be separate.

package/assets/init/.qfai/assistant/skill/qfai-configure/references/principles.md

@@ -0,0 +1,25 @@
+# Working principles
+
+The seven principles behind the steps of this skill. Read them when a choice is
+not settled by a step.
+
+1. **SDD First (Specification is the source of truth)**  
+   If there is a conflict between code and spec, treat the spec as authoritative and either (a) fix code or (b) raise an explicit Open Question to change the spec.
+
+2. **Traceability is mandatory**  
+   Every meaningful change must connect a business flow, story, acceptance criterion, example, test, code, and verification evidence. BF is covered by E2E tests, AC by integration or API tests, and EX by a selected non-E2E test. Full rule: `.qfai/assistant/rule/constitution.md` Article V.
+
+3. **Evidence over confidence**  
+   Prefer observable proof (logs, commands, file diffs, test results). If you cannot verify, say so and record it.
+
+4. **Minimize scope, but never hide gaps**  
+   Keep changes minimal, but do not "paper over" missing decisions. If something blocks correctness, stop and ask.
+
+5. **Quality gates are the decision mechanism**  
+   Use tests/lint/typecheck/build/pack verification (whatever the repo defines) as the primary guardrail. Fix until PASS.
+
+6. **Make it runnable**  
+   Outputs must be executable in terminal/CI. Provide copy-paste commands.
+
+7. **User time is expensive**  
+   Ask only the questions that are truly blocking. Everything else: make reasonable assumptions and label them clearly.

package/assets/init/.qfai/assistant/skill/qfai-discussion/SKILL.md

@@ -23,7 +23,7 @@ mode: interactive-by-default
 
 ## /qfai-discussion - Exploration Planner
 
-[DRIFT-PROTOCOL:MANDATORY]
+[DRIFT-PROTOCOL:REQUIRED]
 
 Run the entry check of
 `.qfai/assistant/rule/shared-skill-operating-baseline.md#workflow-run-entry-check-mandatory`

package/assets/init/.qfai/assistant/skill/qfai-discussion/references/discussion-completion-matrix.md

@@ -2,6 +2,14 @@
 
 Use this file for the full completion logic behind `/qfai-discussion`.
 
+## Contents
+
+- All Packs
+- UI-bearing Packs
+- CLI Packs
+- Non-UI Packs
+- Notes
+
 ## All Packs
 
 Blocking for every pack, UI-bearing or not:
@@ -88,8 +96,7 @@ so conditions 1 and 5 above do not apply to it:
 - Conditions 2, 3, 4, 6 and 7 apply unchanged: all three canonical `uiux/` sidecars, the
   full screen-contract schema, unranked exploration directions, no forbidden legacy
   sidecar, and zero open OQs.
-- `route:` on a `cli` screen contract names the command invocation, not a web path (see
-  `ui-bearing-playbook.md#visual-prototyping-surfaces-vs-cli`).
+- `route:` on a `cli` screen contract names the command invocation, not a web path, as the `cli` section of the UI-bearing playbook sets out.
 - No `prototyping.yaml`: `cli` is not a valid prototyping execution surface.
 - `primary_surface: cli` with a visual `secondary_surfaces` entry is NOT a cli-only pack —
   conditions 1 and 2 stay blocking for it.