qfai 1.10.0 → 1.10.2

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

@@ -136,73 +136,13 @@ review in this run.
 - 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.
+### Round budget and convergence (MUST)
+
+Both live in `.qfai/assistant/constitution/review-convergence.md`: the
+two-round budget, the escalation exits and their severity floor, the
+one-shot corrective review, and the convergence rules that decide which
+findings are still in budget. They moved there because this file reached
+the shipped-asset line ceiling; the rules are unchanged by the move.
 
 ### Reviewer remit (in scope per stage)
 
@@ -229,19 +169,19 @@ in/out split is not re-derived per run.
 
 - 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;
+  - an upstream obligation — an `AC-*`, `BR-*`, `TC-*`, `CON-*` ID, or a named constitution/catalog 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 `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: a ledger cell, a round block, an evidence anchor, the provenance prose. `<CODE>` names the record rule;
   - `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`.
+- `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 (`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-atdd`, `/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, re-attested in a new pack where a reviewer hashed it; `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 false
+  `Authored/edited under review` attestation claim work that was not done or independence the reviewer lacked. `agents/qa-gatekeeper.md` and the response rules below refuse a `PASS`
+  built on them, 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 (`drift-protocol.md#reviewer-originated-obligations`); a `record:*` advisory takes the queue above. Neither goes to the implementer.
+- Only `blocking` findings — those citing a behaviour-governing obligation or a defect class — force `REVISE`.
 
 ### Reviewer budget exhausted
 
@@ -273,20 +213,21 @@ Constraints:
   STOP + Change Request + owner rerun per constitution/drift-protocol.md
 Output format:
 - <headings / bullet schema>
-Quality bar:
-- PASS if ...
-- REVISE if ...
+Acceptance bar: <accept when ...> | <rework when ...>   # never `PASS`/`REVISE`: that is the reviewer's vocabulary and the completion gate matches on it, so a doer told to report in it emits a verdict on its own work
 ```
 
 ## Reviewer response template
 
 ```text
+Reviewer role: <sub-agent role that produced this response>   # REQUIRED — a `Result:` line with no speaker is a report, not a verdict
+Reviewed artifact: <path/anchor this verdict rules on>        # REQUIRED — bounds the ruling; a PASS here clears nothing else
 Round: 1 | 2 | 2b
 Result: PASS | REVISE
-Reviewed revision: <git rev> | working-tree+<porcelain digest>
+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> | Severity: blocking|advisory | Traces to: <AC-*/BR-*/TC-*/CON-*/rule-name|defect:correctness|defect:security|defect:code-quality|none>
+- <issue> | Severity: blocking|advisory | Traces to: <AC-*/BR-*/TC-*/CON-*/rule-name|defect:correctness|defect:security|defect:code-quality|record:<CODE>|none>
 Required fixes:
 - <action>   # blocking findings only
 Advisory / Change Request proposals:
@@ -295,18 +236,193 @@ Evidence checked:
 - <refs>
 ```
 
-`Round` is required — the round budget above is counted from it. `2b` is the
+`Round` is required — the round budget in `review-convergence.md` 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` / `revision`, 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+<digest of git status --porcelain>` when the tree is uncommitted. Without
+  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
+  refactor-verify run and the reviews, so hashing all of `git diff HEAD` here
+  produced a `Reviewed revision` that could never equal the phase-authored
+  `Refactor verify 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.
+- `Reviewer role`, `Reviewed artifact` and `Authored/edited under review` are REQUIRED. A response omitting any of them is not a valid review verdict and MUST NOT satisfy a completion gate — re-request it rather than reading a bare `Result:` line out of it, which is how a doer's self-assessment gets counted as a reviewer's ruling.
 - 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`).
@@ -317,8 +433,8 @@ post-escalation verification review of a user-named fix.
 
 - Reviewer responses in-flight use `Result: PASS | REVISE` (this file).
 - `summary.json` archived into review packs historically uses
-  `status: "PASS|FAIL"` (validated by
-  `packages/qfai/src/core/validators/reviewArtifacts.ts`).
+  `status: "PASS|FAIL"` (validated by the review-artifact validator
+  shipped inside the QFAI package, which `npx qfai validate` runs).
 - A `REVISE` verdict during iteration maps to `status: "FAIL"` when the
   final `summary.json` is written; they represent the same outcome.
   Review packs should not invent a third verdict.

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

@@ -26,8 +26,19 @@ It is not where the detail lives.
   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.
+A hard line ceiling backs this up: **500 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.
+
+One shipped file is exempt, and only because it is a roster rather than prose:
+`assistant/manifest/agent-catalog.yml` holds one entry per agent, mirroring
+`assistant/agents/<id>.md`, so its length tracks the number of agents — whether
+shipped or adjusted through `qfai-configure` — and splitting it would mean
+splitting the roster itself. `npx qfai doctor` names it under `exempt` with that
+reason. No prose asset has an exemption.
 
 ## User Questions (AskUserQuestion Protocol)
 
@@ -116,7 +127,7 @@ Rules:
 
 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;
+- 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/skills/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/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;
@@ -125,7 +136,7 @@ When validate, doctor, test, lint, typecheck, build, capture, or report gates fa
 - 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;
-- 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`.
+- 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 `review-convergence.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**.
 
@@ -175,5 +186,48 @@ Before declaring completion, you MUST:
 
 - resolve or explicitly defer undefined or ambiguous items with rationale;
 - verify every expected artifact exists and required sections are populated;
-- scan generated artifacts for unresolved placeholders such as `TBD`, `TODO`, `TBA`, `TBC`, `XXX`, `???`, `OQ`, `OPEN QUESTION`, `UNDEFINED`, and `PLACEHOLDER`;
+- scan generated artifacts for unresolved placeholders — `TODO`, `TBA`, `TBC`, `XXX`, `???`, `UNDEFINED`, `PLACEHOLDER`, and **undocumented** `TBD` — under the two rules below;
 - run the smallest applicable smoke check, or state "not applicable" with a short rationale.
+
+### What the placeholder scan does not flag
+
+**`OQ` and `OPEN QUESTION` are exempt only as tracking structure.** Exempt: an
+Open Questions register row carrying its tracking fields — ID, owner, status,
+due — and the `Open Questions` heading, `OQ-ID` table header and empty-state row
+that the required `Open-questions.md` files ship with while recording zero open
+questions. Article II and `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 its owner, status or due date, is a hit
+like any other token.
+
+**A documented `TBD` is a compliant record.** `constitution.md` Article II and
+`thinking.md` require writing `TBD` together with a note of what evidence is
+missing, and `thinking.md` requires raising the matching Open Question for the
+same fact. Both halves together are the finished form, not an unfinished one; do
+not report it and do not delete it — deleting it destroys the record of the
+missing evidence, which is the whole point of the marker. A `TBD` missing either
+half — no note, or no Open Question — is a hit.
+
+### What a surviving hit obligates
+
+A hit is **reported, not silently cleared**, and **cleared by a re-scan, not by
+assertion**. Fix what you can, then run the scan again over the same artifacts:
+_resolved_ is the verdict for a hit the re-run no longer reports, and that re-run
+is its evidence. It is not available for a hit still present at that file and
+line — a token still readable there is unresolved whatever the report calls it.
+List every hit the re-scan still finds alongside the completion claim — file,
+line, token — and state for each one whether it is deferred with rationale or
+recorded as an Open Question. A completion claim that omits a surviving hit is
+invalid evidence under the rules above. Completion is blocked while a surviving
+hit is neither of the two.
+
+**Severity floor on the verdict.** _Deferred with rationale_ and _recorded as an
+Open Question_ are NOT available for a hit that stands in for a concrete
+security defect, data loss or corruption, or a correctness defect that would
+break a released contract. Such a hit is cleared only by a named fix or by
+dropping the item from scope; recording it and declaring completion anyway is
+prohibited, exactly as `shared-skill-delegation-baseline.md` withholds that same
+exit for that same class. While neither of the two remaining verdicts applies,
+completion stays blocked.