qfai 1.9.2 → 1.10.1

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

@@ -15,37 +15,248 @@ Skill files should reference this baseline and only add role-, stage-, or gate-s
 
 1. Attempt the first required delegation at stage start using the platform's native delegation mechanism.
 2. Treat that first real delegation attempt as the capability check. Do not gate execution on preflight availability questions or synthetic probe-only checks.
-3. If the delegation fails, stop the stage immediately. Do not simulate roles and do not continue with self-execution.
+3. If the delegation fails, classify the failure first (see `Delegation Failure Taxonomy`), then apply the response for that class. Never simulate roles and never continue with self-execution, whatever the class.
+
+### Delegation Failure Taxonomy (MUST)
+
+Every delegation failure belongs to exactly one of two classes.
+
+| Class         | Meaning                                                                                                                                                                                                     | Sanctioned response                       |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| `unavailable` | The host has no usable delegation mechanism, the role is unknown, or the failure is a configuration / tooling / quota gap only the user can close — including a limit that waiting cannot clear.            | Hard stop.                                |
+| `saturated`   | The host can delegate but is momentarily out of budget — `agent thread limit reached`, concurrency cap, queue full, rate limit, busy pool. The identical call would succeed later with no change by anyone. | Bounded wait-and-retry on the same stage. |
+
+- Classify from the raw failure reason, and classify `saturated` only when the reason states or
+  plainly implies that the identical call would succeed later **with no change by anyone**: a queue
+  or pool that is currently full, a rate limit with a retry window, a concurrency cap that is
+  momentarily reached, an explicit "try again later".
+- A limit or quota that only a user can lift is `unavailable`, not `saturated` — a configured
+  concurrency cap of 0, a maximum delegation depth, an input-size limit, an exhausted account
+  quota or plan. Waiting cannot clear those, so the retry loop would burn 30/60/120 seconds and
+  then report "no user action needed" about a condition that needs exactly that.
+- When retryability is not explicit, default to `unavailable`. The two classes are not
+  symmetric: mis-classifying as `unavailable` costs one unnecessary stop the user can act on,
+  while mis-classifying as `saturated` hides an actionable failure behind a pointless wait.
+- `saturated` never authorises self-execution of a primary artifact or of a blocking review, and never authorises discarding stage progress.
+- When the `saturated` retry budget is exhausted, fall through to the hard stop and report the class as `saturated (retry budget exhausted)`.
+
+### Delegation Failure — `saturated` (Bounded Retry)
+
+- Retry the identical delegation with backoff: 30s, then 60s, then 120s. Attempt cap: 3 retries per work order.
+- Do not re-scope, re-plan, or re-route the work order between retries — same role, same task.
+- The stage stays open and resumable across the wait; completed work orders keep their `PASS` status.
+- Report on entering the retry loop and on its outcome:
+  - `Delegation deferred: <raw reason or concise summary>`
+  - `Failure class: saturated`
+  - `Attempted role: <role>`
+  - `Attempted task: <task title>`
+  - `Retry condition: retry after <N> seconds / when a delegation slot frees`
+  - `Attempts used: <n>/3`
+  - `Stage state: held open and resumable — no stage progress discarded`
 
 ### Delegation Failure (Hard Stop)
 
+Applies to `unavailable`, and to `saturated` once the retry budget is exhausted.
+
 - Report all of:
   - `Delegation failure: <raw reason or concise summary>`
+  - `Failure class: unavailable | saturated (retry budget exhausted)`
   - `Attempted role: <role>`
   - `Attempted task: <task title>`
   - `Why stopped: QFAI requires real sub-agent delegation in this environment.`
-  - `User action needed: <settings or tooling changes required>`
+  - `User action needed: <settings or tooling changes required — or "none; wait for a delegation slot to free" when the class is saturated>`
   - `Retry condition: rerun after the required delegation succeeds`
 
+### Commit Scoping (MUST)
+
+- 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.
+- Isolation requirements for concurrent stages are defined once in
+  `constitution/workflow.md#concurrency-stage-independent-mandatory`.
+
 ## Work Orders Summary
 
 Every major artifact in the stage should include this table schema:
 
-| Step | Role (sub-agent) | Task title | Input (refs) | Output (refs) | Status (PASS/REVISE) |
-| ---- | ---------------- | ---------- | ------------ | ------------- | -------------------- |
-| 1    | <role>           | <task>     | <refs>       | <refs>        | PASS/REVISE          |
+| Step | Role (sub-agent) | Agent instance | Task title | Input (refs) | Output (refs) | Status (PASS/REVISE/PENDING) |
+| ---- | ---------------- | -------------- | ---------- | ------------ | ------------- | ---------------------------- |
+| 1    | <role>           | <instance id>  | <task>     | <refs>       | <refs>        | PASS/REVISE/PENDING          |
 
 - `Output (refs)` should point to in-file anchors or relative evidence paths.
+- `Agent instance` is a run-stable identifier for the sub-agent that actually performed the step
+  (platform-supplied id where available, otherwise `<role>#<n>` assigned in order of first use).
+  It exists so an author→reviewer collision is detectable after the fact from the evidence alone;
+  the same instance appearing in an authoring step and in a review step over the same artifact is
+  a reviewer-independence violation.
+- `PENDING` records a gate that could not be run — the only honest status for the exhausted-budget
+  branch below, which mandates it. It is never a substitute for `PASS`: DONE stays blocked while
+  any row is `PENDING`, and the stage stays resumable. A skill that allows only `PASS`/`REVISE`
+  would force an agent on that path to either break the schema or mislabel an unrun gate.
 
 ## Reviewer Gate Baseline
 
 - Final completion gate must be delegated to an independent reviewer.
+
+### Definition: independent reviewer (NORMATIVE)
+
+An **independent reviewer** is a sub-agent that did **not** author or edit any artifact under
+review in this run.
+
+- The protected invariant is independence from authorship, not reviewer instance identity.
+  An agent that produced or modified none of the artifacts under review is independent even if
+  it filled another role earlier in the run; an agent that drafted or edited one of them is not
+  independent, however it is routed.
+- Independence is judged per review target, over the whole run — not per phase. Authoring in an
+  earlier phase disqualifies the agent from reviewing that artifact in a later one.
+- Role name alone never establishes independence. Routing dispatches by role; independence is a
+  separate constraint the routed agent must satisfy and attest to.
+- A reviewer that discovers it authored or edited a review target MUST stop, declare the
+  conflict, and hand the same evidence set to a non-participating reviewer. It MUST NOT return
+  `PASS` on an artifact it authored.
+- This definition governs every skill. Skill-local wording (e.g. `qfai-configure`'s "a reviewer
+  who did not modify the config") is an instance of it, not a competing rule.
+
 - Reviewers must verify Drift Protocol enforcement.
 - Reviewers must verify test-layer policy enforcement when relevant.
 - Do not treat test volume ratios or floors as hard gates unless the skill explicitly says so.
 - Do not declare DONE until all routed blocking reviewers return `PASS`.
 - Every reviewer returning `FAIL` or `REVISE` must include a concrete fix proposal.
 
+### Round budget (MUST)
+
+- **Two rounds per reviewer per artifact.** Round 1 is the initial review;
+  round 2 reviews the fixes. **The budget is spent the moment round 2 returns
+  `REVISE`**: the orchestrator MUST NOT start a third review, and MUST stop and
+  escalate to the user with the open findings, the fixes already applied, and a
+  recommendation. The decision point is round 2's verdict, never a prediction
+  about a review that must not run.
+- Escalation is not failure. The artifact stays at its current status and the
+  user decides: accept with the finding recorded as an Open Question, apply a
+  named fix, or drop the item from scope.
+- **Completion after escalation.** The user's decision is the exception to
+  "no DONE until all blocking reviewers `PASS`", so the escalation has an exit:
+  - _Accept as Open Question_ or _drop from scope_ — the artifact may reach
+    DONE with the finding recorded; the reviewer's outstanding `REVISE` is
+    superseded by the recorded user decision. Cite the decision where the
+    stage records decisions (`*_delta.md` / `07_Decisions.md` / a Change
+    Request).
+  - _Apply a named fix_ — one **verification review** of exactly that fix is
+    permitted and does not consume budget (it is round 2b, not round 3). Its
+    remit is the named fix only. It may not raise findings unrelated to that
+    fix, but a defect the fix **introduced or exposed** is in remit and MUST be
+    reported rather than passed over: verifying only the named lines and
+    returning `PASS` while a regression sits next to them is a false `PASS`.
+    Such a finding escalates immediately (see the severity floor below) and
+    still does not start a round 3. The review returns `PASS` or escalates
+    again.
+  - **One 2b per artifact, total.** The verification review is free of budget,
+    not unbounded: a second escalation on the same artifact MUST NOT be
+    answered with another _apply a named fix_ + 2b cycle. Without this cap the
+    two rules compose into a loop — 2b costs nothing, and escalating again is
+    always allowed — so the gate has no guaranteed end. At the second
+    escalation the user is offered only _accept as Open Question_ or _drop the
+    item from scope_ (subject to the severity floor below); if the floor
+    withholds both, the artifact does not reach DONE and the stage stops with
+    the finding recorded.
+  - **Severity floor on the exit.** _Accept as Open Question_ is NOT available
+    for a finding that names a concrete security defect, data loss or
+    corruption, or a correctness defect that would break a released contract.
+    Present the user only _apply a named fix_ or _drop the item from scope_ for
+    those, and say why the third option is withheld. Without this the general
+    exit is a route around "deferring such a finding to an Open Question so a
+    `PASS` can be returned is prohibited" — one that needs no lateness and no
+    reviewer consent, only a user click.
+- The round number MUST be recorded on each reviewer response
+  (`Round:` in the shared response template).
+
+### Convergence (MUST)
+
+- A finding first raised in round N > 1 MUST state why it was not raisable in
+  round N-1 — the fix introduced it, or the fix exposed it. A finding that was
+  raisable in round 1 and was not raised is **out of budget**: record it as an
+  Open Question or a `*_delta.md` Decision Record for the owning stage, do not
+  block on it.
+- A reviewer MUST NOT open a new blocking _class_ of finding after the artifact
+  under review has been declared stable. New classes go to the owning stage.
+- **Severity overrides lateness.** The out-of-budget rule is about review
+  discipline, not about shipping known harm. A late finding that names a
+  concrete security defect, data loss or corruption, or a correctness defect
+  that would break a released contract is **not** deferrable: the orchestrator
+  stops and escalates to the user immediately, exactly as it does when the
+  round budget is spent. It is still not a third round — no further review is
+  started, the finding goes straight to the user with its evidence. Deferring
+  such a finding to an Open Question so a `PASS` can be returned is prohibited.
+  That prohibition does not depend on lateness or on who proposes the deferral:
+  the escalation exit in the round budget withholds _Accept as Open Question_
+  for this same class, so a user choice cannot supersede it either.
+
+### 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      | Runtime enforcement correctness, code quality  |
+| `/qfai-atdd`       | Obligation coverage, layer placement, annotation validity         | Implementation structure                       |
+| `/qfai-implement`  | Code quality, spec alignment of the item, RED/GREEN evidence      | Upstream spec content, contract design         |
+| `/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         |
+
+**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.
+
+### Finding provenance (MUST)
+
+- 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 — an `AC-*`, `BR-*`, `TC-*`, `CON-*` ID, or a named
+    constitution/catalog rule;
+  - `defect:correctness`, `defect:security`, or `defect:code-quality` — a defect demonstrable from
+    the changed artifacts themselves, cited together with the evidence that demonstrates it. See
+    `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;
+  - `none` — reviewer-originated scope, i.e. a new product obligation upstream never asked for.
+- A finding whose `Traces to:` is `none` MUST be recorded as `advisory`. It cannot be `blocking`,
+  and it cannot gate `DONE`.
+- An advisory finding is routed to the Change Request / Open Question path defined in
+  `drift-protocol.md#reviewer-originated-obligations`, not to the implementer.
+- Only `blocking` findings — those citing an upstream obligation or a defect class — force
+  `REVISE`.
+
+### Reviewer budget exhausted
+
+A blocking review that cannot be delegated because the agent budget is spent is a `saturated`
+failure, not a licence to skip the gate or to self-review.
+
+- First apply the `saturated` bounded retry. A freed slot is the preferred outcome.
+- If retries are exhausted, a reviewer role MAY be reused sequentially with a cleared context,
+  provided the reviewer did not author or edit any artifact under review in this run. The
+  protected invariant is independence from authorship, not reviewer instance identity.
+- Record the reuse in the Work Orders Summary (`Task title` prefixed `re-review (sequential reuse)`).
+- If even sequential reuse is impossible, hard stop with the review gate recorded as `PENDING`
+  rather than `PASS`. `PENDING` is not `PASS`; DONE stays blocked and the stage stays resumable.
+- Never record a waived or self-performed review as `PASS`.
+
 ## Work order template
 
 ```text
@@ -54,10 +265,12 @@ Role: <sub-agent role>
 Goal: <what to decide/produce>
 Inputs (refs):
 - <file/section>
+- constitution/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 when owner rerun is required
+- must_not: patch upstream artifacts directly; every upstream change requires
+  STOP + Change Request + owner rerun per constitution/drift-protocol.md
 Output format:
 - <headings / bullet schema>
 Quality bar:
@@ -68,15 +281,213 @@ Quality bar:
 ## Reviewer response template
 
 ```text
+Round: 1 | 2 | 2b
 Result: PASS | REVISE
+Reviewed revision: <git rev> | working-tree+<content hash>
+Audited evidence hash: <content hash of the evidence read>   # one line per TDD-ID on a T1 group
+Authored/edited under review: none | <artifact refs this reviewer authored or edited in this run>
 Findings:
-- <issue>
+- <issue> | Severity: blocking|advisory | Traces to: <AC-*/BR-*/TC-*/CON-*/rule-name|defect:correctness|defect:security|defect:code-quality|none>
 Required fixes:
-- <action>
+- <action>   # blocking findings only
+Advisory / Change Request proposals:
+- <proposal>  # findings with `Traces to: none`; not a DONE gate
 Evidence checked:
 - <refs>
 ```
 
+`Round` is required — the round budget above is counted from it. `2b` is the
+post-escalation verification review of a user-named fix.
+
+- `Audited evidence hash` is REQUIRED wherever the evidence tree is what the
+  verdict is about. `Reviewed revision` excludes `.qfai/evidence/**` — see below
+  for why it has to — so nothing else pins the RED/GREEN output this reviewer
+  read, or the coverage justifications it accepted: edited after a PASS they
+  leave the revision unchanged and the verdict reads as fresh. Hash the row's
+  **phase-authored** entry, meaning the entry with the reviewer-appended fields
+  removed — which is exactly what was read — plus
+  `.qfai/evidence/coverage-depth-<spec-id>.md` where the row has one, in the
+  same `path + NUL + blob hash` manifest form, sorted by path. **The reviewer
+  computes it**, on the evidence it read; an orchestrator filling it in on the
+  reviewer's behalf is recording something nobody audited.
+- **How to compute it, exactly.** The subject is part of a file, so a
+  file-level manifest alone is ambiguous, and two readers hashing different
+  extents produce a verdict that is either always stale or never checked. One
+  procedure, in four steps:
+  1. **Extract — the fields this observation could read, named.** Not "the
+     section minus what is written later": the entry keeps growing after every
+     observation, so subtracting a list only moved the problem to the next
+     field added. The RED gatekeeper hashes an entry that has no GREEN yet, the
+     GREEN gatekeeper one that has no `Refactor verify`, and each was stale as
+     soon as the phase wrote on. **Three subjects, from the row's
+     `### <TDD-ID>` section** of the evidence file its `Layer` owns — the
+     heading line through the line before the next `###` heading that names a
+     `TDD-` id, or the next `##` / `#` heading, or end of file, **counting only
+     headings outside a fenced block** (` ``` ` / `~~~`, closed at that length or
+     longer; a body that would close its own fence gets a longer one). Every
+     recorded output is fenced for this reason: a test asserting on Markdown
+     prints `## ...` of its own, and a boundary that took it dropped the GREEN,
+     the `Oracle proof` and the round evidence out of the subject. Each takes
+     only its own fields, in the order the contract lists them:
+     - **Row identity, in all three**: `TDD-ID`, `Layer`, `Test file` and
+       `Selector` — copied from the ledger, which the revision excludes.
+       Without them, changing `Selector` after a PASS to another valid test in
+       the same file left every hash and revision unmoved, and a verdict that
+       only ran the old selector stood as evidence for the new one. Mutable
+       bookkeeping — `Status`, `Evidence` — stays out: it moves on its own.
+
+       **The copy is checked against the ledger, not trusted** — the four
+       identity fields **and the obligation reference**. Hashing a value the
+       entry already holds proves only that the entry has not changed: edit
+       `Selector` in `test-list.md` after the PASS and copy, hash and revision
+       are all unmoved. Gate item 10 reads the four fields from
+       `test-list.md` and requires them to equal the copy; a difference is the
+       row moving under its own evidence, and the verdict is not fresh. The
+       obligation is on that list for the same reason: change `TC-Refs` /
+       `US-Refs` / `CON-API-Refs` alone after the PASS and the entry still holds
+       the old copy, so a verdict about one requirement stands for another.
+
+     - **RED observation**: the obligation reference the row's
+       `Layer` selects (`TC-ref`, or `US-ref` on `E2E` and `CON-API-ref` on
+       `API` — an ATDD-owned row has no `TC-ref`, so naming only that one left
+       its obligation outside every hash), `RED test hash`, the row's own
+       transient revision (`RED revision` or `Falsifiability revision`), and the
+       RED pair or the falsifiability trio with `RED failure mode`. **Not
+       `Revision`**: it names the tree the GREEN landed at and does not exist
+       yet, so including it made every correct RED PASS stale at GREEN.
+     - **GREEN observation**: the RED subject plus `Revision`, the GREEN pair,
+       `Oracle proof` and, where the row has one, `Replacement proof revision` —
+       it addresses the tree a re-taken proof ran against, which the revision
+       does not reach, so a subject without it let that proof be attributed to a
+       tree it never ran on.
+     - **Stage review** (a `completion-reviewer` judging a stage rather than a
+       row — a spec with no ATDD-owned rows is the ordinary case, and
+       `qfai-atdd/SKILL.md` treats zero as a legitimate count): the stage
+       evidence file **whole**, under its repo-relative path, plus
+       `.qfai/evidence/coverage-depth-<spec-id>.md` whole — **minus the
+       `## Final status` section**, which the P8 reviewer's own answer fills in.
+       Whole-file included it, so writing PASS and the confirmer's name straight
+       after hashing made the verdict stale on being recorded. There is no
+       `### <TDD-ID>` section to extract and no per-row boundary to draw, so the
+       rest of the file is the subject; step 2 normalizes it, steps 3 and 4 are
+       unchanged.
+       Without this the final review of such a spec either omitted a required
+       field or PASSed with nothing pinning the evidence it read.
+     - **Branch 3** (`exception`): row identity, the obligation reference the
+       row's `Layer` selects, the `DR-ID`, and the `DR-*` artifact it names. The
+       obligation is what the DR says cannot be observed, so a subject without
+       it let the reference be pointed at a different requirement after the PASS
+       — the ledger is out of the revision, and item 10's identity check covers
+       four fields, so nothing moved. Item 10 checks this one against the ledger
+       as well. There is no RED and no GREEN on this branch — the
+       claim is that neither could be had — so the DR **is** the evidence, and
+       leaving it out of every subject let the pointer be swapped after the PASS
+       for another existing `DR-*`, one already waived perhaps, with the
+       revision and the hash both unmoved. Gate item 10 also requires the
+       verdict to name the `DR-ID` the row currently carries.
+     - **Completion review** (`completion-reviewer` / `implementation-reviewer`):
+       the GREEN subject plus `Refactor verify command` / `result`, the
+       `Shared-artifact re-verify` block when the row has one — it records the
+       earlier rows' re-runs and re-taken proofs, which these reviewers are the
+       ones who audit, so leaving it out let it be edited or deleted without
+       moving either hash — and, from every `### Round N` block the row
+       carries, that block's **phase-authored** fields only. `Round N: reviewer verdict` is written by these reviewers
+       after they have read the block, so taking the whole block put their own
+       line inside what they hashed.
+
+     A field absent at that point contributes nothing — it is not a placeholder
+     and not an error. Nothing written after an observation is in its subject,
+     which is what makes a verdict re-checkable at all: gate item 10 recomputes
+     each one against its own list. **When in doubt about a new field, ask which
+     observation could have read it**; that is the whole rule, and it is why the
+     subjects are named rather than derived by subtraction. **A field written
+     after every reviewer is in no subject at all** — the checkpoint pair, which
+     the revision and the pack seal both miss — so it carries a seal of its own,
+     taken as it is written and recomputed by the gate that reads it.
+
+  2. **Normalize.** LF line endings; strip trailing whitespace from every line;
+     drop leading and trailing blank lines; end with exactly one newline.
+  3. **Serialize.** One record per artifact — the repo-relative path, a NUL
+     byte, then the SHA-256 of that artifact's normalized bytes — sorted by
+     path, joined with newlines. **This is the audit hash, not the working-tree
+     revision**: that one has its own four steps, including the untracked
+     record's `kind` and `mode`, in
+     `../skills/qfai-implement/references/evidence-revision.md`, and restating
+     it here is how the two came to disagree. Two artifacts: the extracted
+     section, recorded under the evidence file's path, and
+     on a branch-3 row the `DR-*` artifact the row names, whole, under its
+     repo-relative path — the subject says the DR is that branch's evidence, and
+     a subject with no record for it is a hash that does not move when the DR
+     text changes; and
+     the part of `.qfai/evidence/coverage-depth-<spec-id>.md` that belongs to
+     this row's obligation — not the file whole, and matched **exactly**. A
+     row may legitimately carry several (`TC-Refs: TC-0001, TC-0002`), so split
+     the copied column on commas first and take each id in the order the column
+     lists them; comparing the whole column against a single-id matrix cell
+     matched nothing, and a row with two obligations had no matrix rows in its
+     subject at all. For each id: the table rows whose obligation cell equals it
+     (`TC-0001` does not match `TC-00011`), plus each justification paragraph
+     whose first line names it. A justification that names no obligation belongs to
+     none of them and is left out; "everything after the table" was the other
+     reading, and two readers taking one each computed different hashes from one
+     file. The matrix is one document
+     for the spec and a later `/qfai-atdd` run recomputes it, so hashing all of
+     it made every existing verdict stale when an unrelated obligation's cell
+     moved, and a `done` row has no re-review path to clear that. Take the table
+     rows whose obligation column matches, with any justification lines under
+     them, normalized by step 2 as well; a row whose obligation appears nowhere
+     in the matrix contributes nothing.
+  4. **Hash.** SHA-256 of that record list; record the hex digest.
+
+  **A T1 coherent group is one pass and several rows** (`volume-policy.md`).
+  One hash over a representative would leave the other members' evidence free to
+  change after the PASS, and a private concatenation of their sections has no
+  defined member order or record shape for gate item 10 to reproduce. Record
+  **one `Audited evidence hash` per `TDD-ID` in the group**, each by these four
+  steps over that row's own subject, listed in the verdict beside the id it
+  belongs to. Nothing about a group is special then; it is the single-row rule
+  applied as many times as the group has members.
+
+  Gate item 10 runs the same four steps. A row with no coverage-depth file, or
+  none whose matrix names its obligation, has one record rather than a
+  placeholder — an absent artifact contributes nothing, not a name with an empty
+  hash.
+
+- `Reviewed revision` is REQUIRED. It names the state the verdict describes — a `git rev-parse HEAD`
+  value, or `working-tree+<content hash>` when the tree is uncommitted, computed by
+  the four-step procedure in `../skills/qfai-implement/references/evidence-revision.md`:
+  collect, exclude, serialize, hash. **Do not restate it**: it was restated here as
+  `path + NUL + hash`, the canonical since gained the untracked record's `kind`
+  and `mode`, and the two spellings gave producer and reviewer different
+  addresses for one tree on any run with an untracked file in it — which a new
+  acceptance test is.
+  **The ledger, the evidence tree and the review pack are excluded**, exactly
+  as that contract says — `.qfai/specs/*/tdd/test-list.md`, `.qfai/evidence/**`
+  and `.qfai/review/**`. The pack is on the list because a project may
+  legitimately track it, and then storing R01 moves the address R02 computes,
+  so items 7-8 could not PASS on one revision. The phases write `test-list.md`
+  and `.qfai/evidence/**` between the
+  GREEN and the reviews, so hashing all of `git diff HEAD` here produced a
+  `Reviewed revision` that could never equal the phase-authored `Revision` —
+  and gate item 10 wants them equal. `references/evidence-revision.md` is the
+  field's contract and this restates it; the two have to agree or the verdict
+  cannot be re-checked. **Not** a
+  `git status --porcelain` digest: that names the changed paths and their states, so it does not
+  move when only the content of an already-changed file does, and a stale PASS reads as fresh.
+  Without
+  it a verdict cannot be re-checked, cannot be invalidated by a later commit, and cannot be told
+  apart from a stale one, so "stale evidence MUST NOT be reused" has nothing to compare against.
+  Reviewers are dispatched against the integrated tree by design, so the tree is legitimately
+  allowed to move under them: an honest, independent verdict on a tree that no longer exists is the
+  normal failure this field addresses. If the tree changed mid-review, say so and name the revision
+  the ruling is pinned to.
+- `Authored/edited under review` is REQUIRED. A response omitting it is not a valid review verdict.
+- Anything other than `none` is a declared independence conflict: the verdict cannot be `PASS`,
+  and the review must be handed to a non-participating reviewer (see
+  `Definition: independent reviewer`).
+- `Result: REVISE` is legal only when at least one finding is `Severity: blocking`. A response
+  whose findings are all advisory returns `Result: PASS` with the proposals attached.
+
 ### Verdict vocabulary
 
 - Reviewer responses in-flight use `Result: PASS | REVISE` (this file).

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

@@ -3,6 +3,32 @@
 Use this document to keep SKILL bodies compact.
 Skill files should reference this baseline and only restate skill-specific additions or overrides.
 
+## SKILL.md 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 skill's own
+  directory:
+  - `references/` — normative detail the skill body cites (`references/<topic>.md`)
+  - `templates/` — artifacts the skill 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 `SKILL.md` 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 in the asset tests, but it is a backstop, not
+the rule. A skill approaching it is a signal to move a section out.
+
 ## User Questions (AskUserQuestion Protocol)
 
 - When a question to the user is needed, use AskUserQuestion if the tool is available.
@@ -11,6 +37,53 @@ Skill files should reference this baseline and only restate skill-specific addit
 - Preserve structured choice semantics when falling back.
 - State why AskUserQuestion was unavailable.
 
+## Canonical qfai Launcher (Mandatory)
+
+- **Launcher preflight — run once, before the first gate.** Confirm the project
+  resolves qfai from its own dependencies. Either proof is sufficient:
+  - **A local binary at `node_modules/.bin/qfai`.** The normal case for npm,
+    pnpm and Yarn configured with `nodeLinker: node-modules`.
+  - **A Plug'n'Play install.** Yarn Berry's default `nodeLinker: pnp` writes no
+    `node_modules/.bin`, so the file check alone would report a correctly
+    installed project as UNRUN forever. Accept it when the project has a
+    `.pnp.cjs` / `.pnp.loader.mjs` at its root and lists `qfai` in
+    `package.json` `dependencies` / `devDependencies`; `yarn exec qfai --help`
+    exiting 0 is the direct confirmation.
+
+  If neither proof holds, every gate below is UNRUN: report it as a blocker and
+  stop. The fix is to install the dependency (`npm i -D qfai`, or the pnpm /
+  yarn equivalent). `qfai` does not add itself to `package.json` on init, so a
+  project bootstrapped with `npx qfai init` alone has no local dependency yet.
+
+- Once the preflight passes, invoke every gate through the launcher that proof
+  established:
+  - local binary -> `npx qfai …`, which resolves to it.
+    `node_modules/.bin/qfai …` is the same thing spelled out; prefer it when
+    PATH reachability is uncertain.
+  - Plug'n'Play -> `yarn exec qfai …` (equivalently `yarn qfai …`), which sets
+    up the PnP environment for the child process. Do **not** fall back to
+    `npx qfai` there: outside the PnP runtime it cannot see the workspace
+    dependency and would fetch a remote copy instead.
+
+  Read every `npx qfai …` example in the shipped docs as "the launcher the
+  preflight established", not as a literal command for a PnP project.
+
+- Never launch a gate as a bare `qfai` command: qfai is a project dependency,
+  not a global one, so that is `command not found` on a normal local install —
+  and a gate that cannot run is a gate that silently passes.
+- The preflight is the guard, not a flag. `npx` runs "a command from a local
+  **or remote** npm package": with nothing resolvable locally it downloads and
+  runs one (non-interactive shells do this without prompting), and
+  `npx --no-install` still executes a copy already sitting in the npx cache.
+  Neither spelling can tell you the qfai that ran was this project's; only the
+  preflight can.
+- If the launcher cannot be resolved at any point, the gate is UNRUN, not PASS.
+  Report it as a blocker instead of completing the stage.
+- The same launcher is documented in `.qfai/assistant/catalog/tech.md` and
+  `.qfai/assistant/catalog/structure.md`. The CI workflow generated by
+  `npx qfai init` is the one deliberate exception: it runs before any project
+  install can be assumed and must still be able to bootstrap.
+
 ## FORMAT SSOT (Mandatory)
 
 - Before writing or editing `.qfai/**`, read the relevant README/template/sample for the target artifact.
@@ -41,16 +114,60 @@ Rules:
 
 ## Gate Failure Autorepair Protocol
 
-When validate, doctor, test, lint, typecheck, build, capture, or report gates fail:
+When validate, doctor, test, lint, typecheck, build, capture, or report gates fail — **or when a blocking reviewer returns `REVISE`** (the in-flight verdict; `status: "FAIL"` is only what a review pack's `summary.json` serializes — see `shared-skill-delegation-baseline.md#verdict-vocabulary`):
 
 - inspect exit code, logs, `validate.json`, and cited files before reporting;
 - 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;
-- rerun the same failing gate after each fix batch;
+- **upstream spec/contract findings: never repair.** STOP and follow `.qfai/assistant/constitution/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 only for destructive changes, ambiguous product/spec decisions, missing permissions/tools, or repeated no-progress failures.
-
-When stopping, report: cause, attempted fixes, remaining blocker, user action, and retry gate.
+- 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;
+- stop on **round count** as well as on lack of progress: a reviewer gate that would enter its third round escalates to the user, even when every round has made progress. See `shared-skill-delegation-baseline.md#round-budget-must`.
+
+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 CON-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.
 
 ## Completion Contract (Shared)