qfai 1.10.0 → 1.10.2

package/assets/init/.qfai/assistant/constitution/drift-protocol.md

@@ -13,7 +13,12 @@ Upstream artifacts include, at minimum:
 - `10_Plan.md` and other owner-phase planning outputs
 - Legacy spec-pack SSOT files when present: `spec.md`, `delta.md`, `plan.md`, `traceability-matrix.md`, `scenario.feature`, `case-catalogue.md`, and numbered pack files (for example `01_Spec.md`..`18_delta.md`)
 - contracts and schema decisions owned by earlier phases
-- outputs of discussion/sdd/review stages
+- outputs of the sdd and review stages. A **discussion pack is NOT upstream
+  SSOT** — it is non-normative discovery material, and `.qfai/specs/**` is the
+  behaviour and design SSOT it feeds. A defect found in one downstream is fixed
+  in the SDD-owned artifact, the discrepancy recorded in delta/evidence. This
+  reclassifies ONLY the pack: genuine upstream is still repaired upstream-first.
+
 - **test or production artifacts another spec's completed implement run
   certifies** — a file named in another `tdd/test-list.md`'s `Test file` column
   on a `done` row. Changing one is not forbidden (the codebase is not
@@ -25,8 +30,9 @@ Upstream artifacts include, at minimum:
 
 One file inside `.qfai/specs/**` is carved out of that last line:
 `<spec-id>/tdd/test-list.md`, and only its `Status` / `DR-ID` / `Evidence`
-cells. See `#allowed-exceptions-minimal-whitelist`. Its **rows** — which obligations exist and
-what each covers — remain upstream.
+cells unconditionally, plus its `Test file` and `Selector` cells under the two
+machine-checkable conditions in `#allowed-exceptions-minimal-whitelist`. Its
+**rows** — which obligations exist and what each covers — remain upstream.
 
 **Every artifact in this list requires an owner rerun by definition.** There is
 no downstream test for "is an owner rerun required here?" — being on this list
@@ -40,10 +46,24 @@ case required reading the agent roster and reasoning backwards from it.
 
 - `.qfai/evidence/**` append/update
 - `.qfai/specs/<spec-id>/tdd/test-list.md` — the `Status`, `DR-ID` and
-  `Evidence` cells only, append/update by `/qfai-implement`. Every other column
-  of that file, and every other file under `.qfai/specs/**`, stays upstream
-  SSOT: adding, removing or re-scoping a row is an upstream change and takes the
+  `Evidence` cells unconditionally, append/update by `/qfai-implement`, plus two
+  cells that are writable **only** while a stated condition holds:
+  - the `Test file` cell, only while the seeded value is empty or a dash
+    placeholder;
+  - the `Selector` cell, only while the seeded value does not resolve against
+    the row's named test file — the validator's own `selectorResolves`
+    predicate is false.
+
+  Both conditions are machine-checkable, so a reviewer verifies the precondition
+  instead of taking the writing stage's word for it, and both are one-way: once
+  the condition that authorised the write has ceased to hold — a `Test file` that
+  names a path, a `Selector` that resolves — rewriting it is no longer covered.
+  Every other
+  column of that file — `TC-Refs`, `Layer`, `US-Refs`, `CON-API-Refs` — and
+  every other file under `.qfai/specs/**`, stays upstream SSOT: adding, removing
+  or re-scoping a row is an upstream change and takes the
   `#when-drift-is-detected` path.
+
 - **creating** a governance record under `.qfai/decisions/` — a Change Request
   (`CR-YYYYMMDD-NNNN-<slug>.md`, per `#when-drift-is-detected` step 2) or an
   anomaly Decision Record (`DR-<id>-<slug>.md`, where `<id>` follows the
@@ -56,7 +76,7 @@ Any exception beyond this list requires explicit user approval.
 `/qfai-implement` must write `tdd/test-list.md` after every phase transition,
 and the file lives inside `.qfai/specs/**`. The protocol never classified it in
 either direction, but `#core-rule`'s list is explicitly open-ended ("at minimum")
-and sweeps in "outputs of discussion/sdd/review stages" — and the ledger's schema
+and sweeps in "outputs of the sdd and review stages" — and the ledger's schema
 is documented in `skills/qfai-sdd/references/spec-traceability-rules.md`, an
 SDD-stage reference. On the natural reading the ledger _is_ an sdd-stage output,
 so "Downstream skills must not patch upstream SSOT directly" applied to it.
@@ -81,6 +101,46 @@ So an agent obeying the protocol could not satisfy gate item 10, and an agent
 satisfying it was in drift. The entry above names the file and the three cells
 unconditionally, which is what removes the choice.
 
+### Why `Test file` and `Selector` are conditional
+
+The deadlock that put the ledger on this list recurs one and two columns over,
+and two shipped validator rules are what create it:
+
+- `TDDLIST_TEST_FILE_MISSING` fires at **error** severity for a row whose
+  `Test file` cell is empty or a dash placeholder, once its `Status` is `green`,
+  `refactor`, `review-fix` or `done`.
+- `TDDLIST_SELECTOR_UNRESOLVED` fires when the `Selector` cell's text is not
+  found in the named test file, and its own remediation text says to update the
+  selector. The per-row checkpoint command is `<runner> <Test file> -t
+'<Selector>'`, so an unresolved selector also produces a run that selects
+  nothing while exiting 0.
+
+A row is seeded with a descriptive selector and, commonly, no test file: the
+path is a downstream decision, and the test's title does not exist until the
+micro-cycle authors it. So the writing stage cannot hold the status the first
+three cells **do** authorise without also writing a cell they do **not** — and
+the earlier status it would otherwise have to keep is false, because the row has
+already passed that phase. Seeding both cells upstream does not resolve it
+either: it would require inventing titles that implementers then match exactly,
+inverting the direction of authority between the spec and the test.
+
+The conditions are what keep this narrow. They authorise **filling a placeholder
+and repairing an unresolvable selector**, never rewriting a cell that already
+resolves, and never touching the columns that carry the row's obligation
+identity. Decomposing an existing obligation across rows stays in remit for the
+executing stage; minting a new obligation id does not, and that line is
+unchanged.
+
+One limit is worth stating, because the `Selector` condition is narrower than it
+reads. `selectorResolves` is deliberately lenient: it accepts verbatim
+containment, then containment of the selector's last identifier-shaped token. So
+a `Selector` that is materially wrong — one that misdescribes which obligations
+its row covers — but happens to share a trailing token with its test file still
+**resolves**, the condition is false, and this carve-out does **not** authorise
+repairing it. That is the conservative direction and it is intended: only a
+selector the runner's own file could not match is repairable here, and a merely
+misdescribing one stays an upstream change.
+
 ### Why the Decision Record is on this list
 
 A downstream stage cannot always avoid needing one. `qfai-implement` Phase Red
@@ -277,17 +337,36 @@ is a defect.
 - Every reviewer finding declares a `Traces to:` value. See
   `shared-skill-delegation-baseline.md#finding-provenance-must` for the response schema. Legal
   values:
-  - an upstream obligation (`AC-*`, `BR-*`, `TC-*`, `CON-*`) or a named constitution/catalog rule;
+  - an upstream obligation (`AC-*`, `BR-*`, `TC-*`, `CON-*`) or a named constitution/catalog rule
+    **that governs the product's behaviour**;
   - `defect:correctness`, `defect:security`, or `defect:code-quality` — the deliverable-defect
     classes above, each of which MUST carry the concrete evidence in the changed artifacts that
     demonstrates it;
+  - `record:<CODE>` — a defect in the run's own record rather than in the product;
   - `none` — reviewer-originated scope.
-- The first two are **blocking** and gate `done`.
+- The first two are **blocking** and gate `done`. `record:*` and `none` are not.
+- `Traces to: record:<CODE>` is a record defect: the ledger, a round block, an evidence anchor or
+  the provenance prose is wrong while the product is not. It MUST be recorded as `advisory`, MUST
+  NOT be `blocking`, and settles in the spec's record-defect queue (`#the-record-defect-queue`)
+  rather than by re-running the row. `record:unchecked` is a bug report against `validateTddList`,
+  not against the item — a record rule worth a round is worth a validator code.
+- **A record that misrepresents the run is not a record defect.** Evidence copied from a previous
+  round or a sibling row, an evidence anchor resolving to a run other than the one it names, and a
+  false `Authored/edited under review` attestation do not merely mis-state the work — they claim
+  work that was not done, or independence the reviewer did not have. `agents/qa-gatekeeper.md`
+  rejects the first two outright and
+  `shared-skill-delegation-baseline.md#reviewer-response-template` forbids a `PASS` on the third,
+  so classifying them `record:*` would let an advisory-only review return `PASS` and release
+  `done` over the very evidence the gate exists to reject. They stay **blocking** as
+  `defect:code-quality` and MUST NOT be filed as `record:*`. `record:*` covers a record that is
+  honestly produced and merely wrong — a tier missing from an Evidence cell, a `Satisfied-by`
+  naming the wrong sibling row, an unlabelled round block.
 - `Traces to: none` is reviewer-originated scope. It is **drift**, and it is **not satisfiable
   downstream**: encoding it as production code plus a hard test assertion is the same violation as
   patching upstream SSOT, inverted. It MUST be recorded as `advisory`, MUST NOT be `blocking`, and
   is routed to the Change Request / Open Question path — never to the implementer.
-- Routing an advisory finding:
+- Routing a `none` advisory (a `record:*` advisory takes `#the-record-defect-queue` instead — the
+  Change Request path adjudicates product obligations and cannot repair a record):
   1. The reviewer records it in its response under `Advisory / Change Request proposals`, with
      enough context for the owner phase to adjudicate. The reviewer does **not** write it into
      `08_Open-questions.md`: that file is upstream SSOT (see `#core-rule`) and is owned by
@@ -308,10 +387,94 @@ is a defect.
   Completing against an obligation that is known to be under revision would ship a knowingly
   inconsistent SSOT.
 
+### The record-defect queue
+
+Making `record:*` advisory removes the round it used to force. It does not remove the defect, so
+the class is only honest if the defect lands somewhere with an owner and is consumed. That place is
+one queue per spec, and it is defined by a destination, an owner, an entry shape and a drain.
+
+- **Where.** A `## Record defects` section in the evidence file the reviewing stage's **own
+  completion contract** names. For a `/qfai-implement` review that is
+  `.qfai/evidence/implement-<spec-id>.md` when that file exists, otherwise
+  `.qfai/evidence/atdd-<spec-id>.md` — the same file rule the spec-level checkpoint boundary uses,
+  so a spec never has this queue in two places. **Do not derive the path from a
+  `<stage>-<spec-id>.md` pattern.** Each stage names its own evidence file and not every one of
+  them is spec-scoped — `/qfai-configure` writes `.qfai/evidence/configure-<run-id>.md`, one per
+  run, and has no `configure-<spec-id>.md` at all — so the pattern named files no stage creates.
+  Never `08_Open-questions.md`: that file is upstream SSOT owned by `/qfai-sdd` (see
+  `#core-rule`), and a record defect is not a product obligation.
+- **The class needs a drain, so a stage whose completion contract has none does not use it.** Every
+  stage sharing `shared-skill-delegation-baseline.md` reads the provenance rules, but an entry is
+  only worth filing where something consumes it, and the queue above is defined as much by the
+  drain as by the destination. The test is textual and local: **that stage's own completion
+  conditions must require this queue drained before it declares completion.** `/qfai-implement`
+  states it (`skills/qfai-implement/SKILL.md#spec-completion-conditions`), and no other stage's
+  completion conditions mention the queue at all — so `/qfai-sdd`, `/qfai-atdd`, `/qfai-configure`,
+  `/qfai-verify`, `/qfai-discussion` and `/web-research` reviewers MUST NOT classify a finding
+  `record:*`; it keeps the class it would have had, blocking under the rule it names. A stage gains
+  the class by adding the drain to its completion conditions, never by being named here. A class
+  whose entries are written where nothing drains them is the round-dropped-and-defect-dropped
+  outcome this queue exists to prevent, and it is worse in the stages that never gained the queue
+  than the round ever was.
+- **Who.** The reviewer records the finding in its response as an advisory, as for any advisory.
+  The **orchestrator** that dispatched the review appends it to the queue when the round closes —
+  the same role that owns the ledger. A finding that stays in the reviewer response and never
+  reaches the queue is an unrouted advisory, which the review gate already forbids.
+- **Entry.** One line per defect: the `<CODE>`, the row or artifact it is against, what the record
+  says against what the run actually did, and the round it came from. That is what makes it
+  repairable later by someone who did not watch the round.
+- **Drain, at the spec boundary.** Before spec-level completion is declared, every open entry is
+  **repaired in place**: the record is corrected to what the run did, with no row re-run and no
+  status change. Repair is the only close. When the rule the entry names is one no validator
+  checks, the entry **also** produces a validator bug report per the `record:unchecked` ratchet
+  above — that report tracks the missing check and does not stand in for the repair. Closing an
+  entry on the report alone leaves the wrong record exactly as wrong as it was, with the round
+  that found it already spent: a missing tier stays missing, and the item stays complete. The two
+  are different obligations against different backlogs. Completion is not declared while an entry
+  is open. This gates the **spec** boundary only: a `record:*` finding still never holds an
+  individual row out of `done`, which is the whole point of the class.
+- **When the record cannot be repaired honestly.** Repair means writing what the run actually did,
+  which needs the round's artifacts to still say what that was. Where they do not — nothing
+  reconciles the entry with any run — the finding was never a record defect: what is missing is
+  not a correct record of the work but any evidence the work happened, which is the integrity case
+  above. Reclassify it as `defect:code-quality`, blocking, and take the ordinary REVISE path.
+  There is no third exit: an entry closes on a corrected record or on a blocking finding.
+- **Re-attest a repair in a pack of its own; never re-run it, and never edit a sealed one.** A
+  defect inside a `Satisfied-by`, a round block or any other phase-authored field sits inside the
+  exact bytes a reviewer's `Audited evidence hash` covers, and the completion gate recomputes that
+  hash — so repairing in place makes a correct PASS read as stale, and skipping the recomputation
+  would accept evidence nobody read. Repair the record, then have a reviewer **of the role that
+  issued the verdict** re-read the repaired entry and emit a **record re-attestation**: the
+  `TDD-ID`, the same `Reviewed revision`, the same `Result`, a recomputed `Audited evidence hash`,
+  and the queue entry's `<CODE>`.
+- **The re-attestation is a new review pack, and the pack it supersedes is left untouched.** A
+  verdict lives in a `review-<timestamp>/` pack fixed by a `Review pack seal` the completion gate
+  recomputes, so replacing that verdict's `Audited evidence hash` line where it is stored breaks
+  the seal by construction, and replacing only the evidence file's copy leaves the sealed reviewer
+  response carrying a hash nothing agrees with. Write the re-attestation as its own
+  `review-<timestamp>/` pack, sealed by the same procedure. The superseded verdict keeps the hash
+  it recorded — it was correct over the bytes it read — and its pack keeps recomputing. The
+  evidence entry records `Record re-attestation` beside the verdict it supersedes, with its own
+  `Record re-attestation pack` and `Record re-attestation pack seal`; the completion gate
+  recomputes the superseding hash and both seals, which is what makes the re-attestation an
+  artifact a validator can see rather than an untraceable edit. No code runs, no row changes
+  status, and it spends no round — it opens none, so it is not a `Round N:` pack. The revision a
+  verdict names excludes `.qfai/evidence/**`, so by construction nothing outside the record moved.
+  **A repair that would move the revision is not a record repair**: it is a change to the
+  deliverable and takes the ordinary path. A repaired entry whose verdict carries no
+  re-attestation is still an open entry.
+
+An unconsumed queue would make the class worse than what it replaced: the round is gone and the
+defect is gone with it. The drain is what pays for dropping the round.
+
 ### Which evidence is committed
 
-- **Regenerable** — stage evidence (`.qfai/evidence/<stage>-<spec-id>.md`),
-  run logs, reports. Reproducible by rerunning the owner skill; not committed.
+- **Durable per-item TDD evidence** — `.qfai/evidence/implement-<spec-id>.md`
+  and `.qfai/evidence/atdd-<spec-id>.md`. Ledger `Evidence` cells point to
+  anchors in these files, and validation resolves those anchors on a fresh
+  clone, so the managed `.gitignore` block re-includes and commits them.
+- **Regenerable** — other stage logs, run logs, and reports. Reproducible by
+  rerunning the owner skill; not committed.
 - **Governance record** — Change Requests (`.qfai/decisions/CR-*.md`) and
   durable decision records (`.qfai/evidence/decisions/*.json`). They carry
   user approval and cannot be regenerated, so they are committed. The managed
@@ -325,8 +488,8 @@ is a defect.
   — diffs the branch against `baseBranch` and emits `QFAI-DRIFT-001` (`error`)
   for every changed file under `paths.contractsDir`, under `_policies/`, or
   matching a protected spec-pack filename. A Change Request at `Status:
-approved` that **names the changed path** silences it; an `open` CR does not,
-  because an open CR authorises nothing. The check does not run in the `sdd`
+approved` whose **`## Impact scope` names the changed path** silences it — not
+  a path named elsewhere in it, not a contract ID, and never an `open` CR. The check does not run in the `sdd`
   profile: `/qfai-sdd` owns these files.
 - Downstream reviewers must not originate binding obligations that upstream SSOT does not contain.
 - If approval is not available, stay in STOP state **for that CR's blocked set**

package/assets/init/.qfai/assistant/constitution/review-convergence.md

@@ -0,0 +1,121 @@
+# Review Convergence
+
+How a review round ends, and what may follow it. Referenced from
+`shared-skill-delegation-baseline.md#round-budget-and-convergence-must`,
+which owns the delegation rules these sit beside.
+
+### 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_. The severity floor below then withholds _accept as Open
+    Question_ for its classes, so for those findings the intersection of the
+    two rules leaves _drop the item from scope_ alone — which is the state
+    **Corrective review** below exists to give an exit.
+  - **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.
+  - **Corrective review (the one exit the floor leaves open).** The two rules
+    above compose into a dead end, and it is reachable: a Round 2b that
+    correctly reports a defect the named fix INTRODUCED or EXPOSED escalates a
+    second time, at which point the 2b cap withholds _apply a named fix_ and
+    the severity floor withholds _accept as Open Question_ — so for a security,
+    data-loss or released-contract-correctness finding the only remaining
+    option is _drop the item from scope_. Fixing the defect and keeping the
+    requirement has no path: the fix cannot be verified, and the artifact
+    stays at `REVISE` forever. Round 2b doing its job is what puts the stage
+    there.
+
+    When that state is reached AND the user chooses to fix rather than drop,
+    the stage MAY open **one corrective review artifact**. It is not a third
+    round and not a budget reset; it is a separate artifact with a remit
+    narrower than any round, and it is bounded so that the two rules above
+    cannot compose through it either.
+
+    Required before the review runs — all of it, in the stage's evidence:
+    1. the originating artifact, and the Round 2b finding verbatim;
+    2. the user's decision, recorded where the stage records decisions
+       (`*_delta.md` / `07_Decisions.md` / a Change Request);
+    3. what was changed to fix it;
+    4. the before and after revision of every artifact the fix touched, as
+       digests a reader can re-derive rather than as a round name.
+
+    Constraints on the review itself:
+    - **Remit is the finding and the named fix, nothing else.** Narrower than a
+      round: a corrective reviewer may not re-open the artifact generally. An
+      unrelated finding goes to the owning stage's delta or a Change Request
+      under the convergence rules, and does NOT extend this review.
+    - **One independent review, once.** Recorded as `Round: corrective` — not
+      `2c`, and not a numbered round, because a number invites a successor.
+    - **`PASS` supersedes the Round 2b finding** on the originating artifact
+      and returns the stage to the review gates it had not yet reached. It does
+      not retro-`PASS` anything else.
+    - **`REVISE` is terminal.** The stage stops with the finding recorded. No
+      second corrective artifact, no further review, and no route back to
+      _apply a named fix_. This is the guaranteed end the 2b cap exists to
+      provide, moved one step later rather than removed.
+    - **The floor and the Open Question prohibition are unchanged.** A
+      corrective review cannot return `PASS` over a live security, data-loss or
+      released-contract defect, and the finding cannot be deferred to an Open
+      Question at any point in this path.
+    - **A discussion pack is not an input to this.** It is non-normative
+      reference material, so a corrective review neither repairs one nor treats
+      one as the upstream to fix.
+
+- 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.