qfai 1.9.2 → 1.10.0

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,38 @@ Quality bar:
 ## Reviewer response template
 
 ```text
+Round: 1 | 2 | 2b
 Result: PASS | REVISE
+Reviewed revision: <git rev> | working-tree+<porcelain digest>
+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.
+
+- `Reviewed revision` is REQUIRED. It names the state the verdict describes — a `git rev-parse HEAD`
+  value, or `working-tree+<digest of git status --porcelain>` when the tree is uncommitted. 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)
 

package/assets/init/.qfai/assistant/constitution/workflow.md

@@ -35,12 +35,13 @@ Do not proceed without a declared Change Type.
 - Read and enforce `.qfai/assistant/constitution/drift-protocol.md`.
 - Downstream phases must not edit upstream SSOT artifacts without explicit user approval.
 - If drift is required, STOP and raise a Change Request (3 options + recommendation), then wait for approval and rerun the owner skill.
+- The STOP is scoped: it halts the affected upstream artifact and every downstream item that depends on it, which the Change Request enumerates. Unaffected items continue, and more than one Change Request may be open at once — see `drift-protocol.md#multiple-open-change-requests`.
 
 ## Test-layer policy (Mandatory)
 
 - Read and enforce `.qfai/assistant/catalog/test-layers.md`.
 - Treat floors/ratios as signals, not completion gates.
-- Completion gate is `qfai validate --fail-on error` with evidence.
+- Completion gate is `npx qfai validate --fail-on error` with evidence.
 
 ---
 
@@ -52,7 +53,8 @@ Do not proceed without a declared Change Type.
 3. Specification (SDD): unified preflight + `_policies` / `spec-*/01..10`
 4. Prototyping (optional): contract-aligned implementation skeleton
 5. Acceptance tests (ATDD): runnable E2E/API/Integration tests derived from specs/contracts obligations (`US` / `TC` / `CON-API`)
-6. Verify: run quality gates and provide evidence
+6. Implementation (TDD): `/qfai-implement` drives the Red/Green/Refactor micro-cycle one `test-list.md` row at a time
+7. Verify: run quality gates and provide evidence
 
 Stage 3 (`/qfai-sdd`) target policy:
 
@@ -64,23 +66,67 @@ Stage 3 (`/qfai-sdd`) target policy:
 Prototyping stage policy:
 
 - `/qfai-prototyping` scope is fixed to **ALL specs** discovered from `.qfai/specs/spec-*`.
-- Completion requires prototyping evidence (markdown + json in `.qfai/evidence/`) and `qfai validate --fail-on error` pass.
+- Completion requires prototyping evidence (markdown + json in `.qfai/evidence/`) and `npx qfai validate --profile prototyping --fail-on error` pass. The profile is explicit on purpose: an omitted `--profile` defaults to `full`, which runs the ATDD traceability rules (`QFAI-ATDD-111/112/113`) at severity `error` — obligations of stage 5, which has not run yet at stage 4.
+- The `/qfai-verify` run that feeds `npx qfai prototyping certify` writes `.qfai/output/verify.json` with `scope: "prototyping"`; certify accepts no other scope. See the Verify Output Contract in `.qfai/assistant/skills/qfai-verify/SKILL.md`.
 - Coverage gaps (missing spec rows, unresolved declared checks, API 404) are blocking.
 
 Implementation stage:
 
 - `/qfai-implement` orchestrates the full TDD micro-cycle (Red/Green/Refactor) one test at a time using `test-list.md` as the execution ledger.
-- Each item requires watch it fail (RED observation confirmed), watch it pass (GREEN observation confirmed), and fresh evidence (command+result pairs, not status-only).
+- Each item requires watch it fail (RED observation confirmed), watch it pass
+  (GREEN observation confirmed), and fresh evidence (command+result pairs, not
+  status-only). A RED is admissible only when an assertion — or an
+  expected-exception check — inside the row's own `Selector` raised the failure;
+  a collection, import, syntax or fixture error, or an unasserted throw, is a
+  missing seam, not a RED
+  (`skills/qfai-implement/references/red-admissibility.md`).
+  - **Exception — RED not observable.** When the obligation is already satisfied
+    by a sibling row, the RED cannot be observed. The row then carries
+    falsifiability evidence in place of the RED pair; see
+    `.qfai/assistant/skills/qfai-implement/references/red-not-observable.md`.
+  - Weakening a correct test to manufacture a RED is forbidden.
 - Completion requires independent spec review and code quality review gates — both must PASS before an item is marked done.
-- Parallel execution is allowed only for independent slices with no shared state; worktree separation is required.
+- Parallel execution is allowed only for independent slices with no shared state.
 
 Legacy note:
 
 - The three legacy TDD skills were abolished. Use `/qfai-implement` instead.
 
+### Concurrency (stage-independent, mandatory)
+
+This subsection binds **every** stage that delegates in parallel, including
+`/qfai-sdd` no-argument batch runs and `/qfai-implement` slice execution. It is
+a real heading so `workflow.md#concurrency-stage-independent-mandatory` resolves
+from the skills and baselines that cite it.
+
+- Worktree separation is required whenever two or more delegated agents write
+  files concurrently. One agent per worktree; no shared index.
+- If worktree separation is not available, parallel delegation degrades to
+  "one agent commits at a time; the others hand back an unstaged diff to the
+  orchestrator". State which of the two modes is in force in the stage
+  evidence.
+- Commit scoping is mandatory in both modes and binds **every** committer —
+  delegated agent and orchestrator alike. Stage only the paths belonging to the
+  task being committed (`git add <paths>`). `git add -A`, `git add .` and
+  `git commit -a` are forbidden while any parallel stage is in flight.
+  - In **degraded / shared-index** mode the damage is immediate: the siblings
+    share one index, so a sweeping stage commits their in-flight files into an
+    unrelated commit and misattributes work in the audit trail the Drift
+    Protocol depends on.
+  - Under **worktree separation** there is no shared index, so no sibling file
+    can be swept in. The ban still holds: a sweeping stage commits whatever
+    else is loose in that agent's own worktree — build output, scratch files, a
+    half-finished edit outside the work order — so the commit still stops
+    matching its declared deliverables, which is what the audit trail reads.
+- Degraded mode makes this the **orchestrator's** obligation above all, since
+  it is the one holding the commit: it commits one handed-back diff at a time,
+  staging that agent's declared deliverable paths only, and never blanket-stages
+  the shared worktree. A diff whose paths it cannot enumerate is not
+  committable — ask the agent for its path list first.
+
 ### Stage 0 — Steering refresh contract (mandatory)
 
-At the beginning of each stage (`qfai-discussion`, `qfai-sdd`, `qfai-prototyping`, `qfai-atdd`, `qfai-verify`):
+At the beginning of each stage (`qfai-discussion`, `qfai-sdd`, `qfai-prototyping`, `qfai-atdd`, `qfai-implement`, `qfai-verify`):
 
 1. Check these steering files:
    - `.qfai/assistant/catalog/manifest.md`
@@ -128,7 +174,7 @@ Typical minimum:
 - typecheck
 - tests
 - pack/verify (if distributed)
-- In CI, use default/full validation (`qfai validate --fail-on error`); `--phase refinement` is local-only.
+- In CI, use default/full validation (`npx qfai validate --fail-on error`); `--phase refinement` is local-only.
 - Waivers are for `warning` / `info` findings only. Waivers targeting `error` findings are treated as configuration errors and must fail.
 
 ---