qfai 1.9.2 → 1.10.0

package/assets/init/.qfai/assistant/skills/qfai-implement/references/relevant-test-suite.md

@@ -0,0 +1,87 @@
+# Relevant Test Suite
+
+What "run the relevant test suite" resolves to in Phase: Refactor step 2, and
+where the wide run is actually paid for.
+
+## Resolution order
+
+"Relevant" means the smallest selector that covers the module you touched
+**plus everything that depends on it**, direct or indirect.
+
+1. **The touched module's own tests** — the test modules named by this item's
+   ledger row.
+2. **The tests of its reverse dependency closure.** Walk the **production**
+   import graph backwards from the touched module `X`: the modules that import
+   `X`, the modules that import those, and so on until the walk closes. Include
+   the test modules of every module in that closure.
+
+   Searching test files for a direct import of `X` is not enough. The common
+   shape is: `X` <- `Y` (production) <- `Y`'s test. `Y`'s test imports only `Y`,
+   so a test-file scan finds nothing, the fallback is never reached, and a
+   broken `Y` still passes the narrow gate.
+
+3. **Fallback: the package containing the touched module** — whenever the
+   reverse walk cannot be completed. It cannot be completed when the graph
+   contains dynamic imports, DI or container wiring, dependency-injected
+   factories, reflection, generated code, or when no import-graph tool is
+   available. Incomplete resolution always widens; it never narrows.
+4. **Never "every test in the repository"** at this step — the wide run has its
+   own cadence, below.
+
+Record which of 1-3 was used in the item's evidence. "Narrow suite, closure
+resolved" and "narrow suite, package fallback" are different claims, and only
+the first one asserts the dependents were actually checked.
+
+## Cadence
+
+**Narrow suite per item; full suite at each checkpoint boundary.**
+
+Running the whole spec suite once per item costs the sum over all prior items
+and is quadratic in ledger size. That cost is paid at boundaries instead.
+
+### Checkpoint boundaries
+
+The full suite runs at, and only at:
+
+- the **last incomplete row this run completes** — while finishing a row, if no
+  other row is left at `todo` / `red` / `green` / `refactor` / `review-fix`,
+  that row is a boundary. It is deliberately **not** the physical last row of
+  the file: a re-executed ledger routinely has its remaining `todo` rows above
+  already-`done` or `exception` ones — rows appended later, or a backfilled
+  gap — and the physical last row is then skipped, so the spec would finish
+  without a full run at all. A run that completes no row has nothing to verify
+  and no boundary;
+- any row whose implementation **touched modules belonging to more than one
+  package**, or touched a module outside the package that owns this item's own
+  test modules — a cross-package edit re-widens the run immediately. Resolve
+  the owning package of every touched module directly from its path; this is
+  evaluated **independently of the resolution step used above**, so a fully
+  closed reverse walk (step 2, where step 3's fallback package never exists)
+  does not skip it;
+- every **N-th** completed row, with `N = 10` by default. Record the chosen `N`
+  in the item's evidence when a project overrides it.
+
+The counted interval is what keeps the cadence sub-quadratic. An AC or BR group
+is **not** a boundary: in a spec where TC and AC are close to one-to-one — as in
+this repository's `spec-0006`, whose `TC-0006-0001..0009` each map to a distinct
+AC and each occupy one ledger row — every row would be the last of its group and
+the per-item full run would be right back. The boundary must be coarser than the
+obligation granularity, so it is defined by count, not by grouping.
+
+Rows that are not on a boundary are gated on the narrow suite alone: items 6, 7
+and 8 of the 11-point gate are evaluated against it, and item 11 requires the
+full suite only for a row that sits on a boundary.
+
+### Checkpoint runs before `done`, never after
+
+The lifecycle allows `refactor -> exception` but forbids re-opening a `done`
+row, so verification has to happen while the row is still `refactor`:
+
+- run the checkpoint at the end of Refactor, after the reviewers return PASS;
+- PASS -> `refactor -> done`;
+- FAIL -> `refactor -> exception` with a DR-ID, and the regression is filed as
+  a new `todo` row carrying the failing selector.
+
+Rows already `done` from earlier boundaries are never re-opened. Spec completion
+stays blocked until the new row reaches `done`, because "Checkpoint verification
+passed" is a spec completion condition.

package/assets/init/.qfai/assistant/skills/qfai-implement/references/review-artifact-layout.md

@@ -0,0 +1,31 @@
+# Review Artifact Layout
+
+Items 7-9 of the 11-point reviewer gate in `SKILL.md` are evidence-bearing: the reviewer verdicts
+must be written to a review pack, not left in conversation. There is exactly **one**
+`.qfai/review/**` layout, the one validated by
+`packages/qfai/src/core/validators/reviewArtifacts.ts` and archived by `npx qfai doctor`:
+
+```text
+.qfai/review/review-<YYYYMMDDhhmmssSSS>/     # 17-digit timestamp; no other directory shape is recognized
+├── review_request.md                        # required
+├── R01_<reviewer-id>.md                     # required, at least one; R02_, R03_, ... per reviewer
+└── summary.json                             # required
+```
+
+- One pack per review round for one `TDD-ID`. Do not nest `<scope>/<layer>/attempt-NN/`
+  directories under `.qfai/review/` — that layout is not validated and packs written there are
+  invisible to `npx qfai validate`.
+- The scope of the pack is recorded **inside** the artifacts, not in the directory name. In
+  `summary.json` set `target.kind: "spec"` and `target.path` to the spec dir, and name the
+  `TDD-ID` in `review_request.md`.
+- Minimum `summary.json` shape (`version: "2.0"`):
+  `version`, `created_at`, `target.{kind,path}`, `routing_profile`, `overall_status` (`PASS|FAIL`),
+  and `reviewers[]` where each entry is `{ reviewer, status: PASS|FAIL|NA, feedback_count }`.
+  A `REVISE` verdict during iteration is written as `status: "FAIL"` here — see
+  `shared-skill-delegation-baseline.md#verdict-vocabulary`.
+- Each additional review round creates a **new** `review-<timestamp>/` pack. Do not append
+  ad-hoc per-round filenames inside an existing pack.
+- Review artifacts are checked only by the full-scan profiles. Neither `--profile tdd` nor
+  `--profile sdd` reports `QFAI-REVIEW-*`, so a malformed or missing `summary.json` passes both.
+  Run `npx qfai validate --profile verify --fail-on error` (or the default full scan,
+  `npx qfai validate --fail-on error`, or `/qfai-verify`, which runs the same profile) to see them.

package/assets/init/.qfai/assistant/skills/qfai-implement/references/round-evidence.md

@@ -0,0 +1,102 @@
+# Round Evidence
+
+Per-round fields of the `qfai-implement` evidence contract. The skill's
+`### Per-item evidence contract` section carries the summary.
+
+## Round block
+
+One block per RED/GREEN cycle. Round 1 is the original cycle; each blocking
+reviewer `REVISE` that requires new production behaviour adds a round.
+
+- `Round N: RED command` — the exact command executed to observe failure
+- `Round N: RED result` — the failure output (result completeness is
+  best-effort; truncated output is acceptable)
+- `Round N: GREEN command` — the exact command executed to observe success
+- `Round N: GREEN result` — the success output
+- `Round N: reviewer verdict` — the verdict that closed the round (`PASS`, or
+  `REVISE` plus the finding, and which rework path it took). Absent on round 1
+  when no review has run yet.
+
+## What opens a round
+
+Round 1 is the original RED/GREEN cycle. Each blocking reviewer `REVISE` that
+requires new production behaviour adds a round. A `REVISE` that needs none
+(naming, duplication, comments) opens no round and is verified by a refreshed
+`Refactor verify` pair instead. Rounds are numbered and repeatable, not appended
+as free prose.
+
+Every field in a round block carries the `Round N:` prefix — `Round N: RED
+command` / `Round N: RED result` / `Round N: GREEN command` / `Round N: GREEN
+result` / `Round N: reviewer verdict`.
+
+## Single-round items
+
+A single-round item satisfies the contract with `Round 1: ...` and no
+reviewer-verdict line, which is the same content the previous one-pair
+contract required. Nothing existing becomes non-conformant.
+
+## Where the rounds happen
+
+An item at `review-fix` may re-enter the RED/GREEN cycle as many times as the
+rework needs. Each pass is its own round block.
+
+**The row's `Status` stays `review-fix` throughout.** The RED/GREEN passes are
+work, not ledger states here: `review-fix -> red` and `review-fix -> green` are
+not allowed transitions, and writing either would be the backward transition
+the lifecycle forbids. `review-fix -> refactor` is the only status change the
+rework produces; the rounds themselves are recorded in `Evidence`.
+
+## A `REVISE` that needs no new production behaviour
+
+`implementation-reviewer` frequently returns `REVISE` for naming, duplication
+or a comment — rework that changes no observable behaviour. There is no new
+failing test to write, so opening a round would mean inventing a RED phase for
+a change that has none. That rework takes the second path:
+
+1. The status contract is unchanged: the row still moves
+   `refactor -> review-fix` and back.
+2. **No round is opened.** Round blocks record RED/GREEN cycles; a
+   behaviour-preserving change has none.
+3. Make the change, re-run the item's tests, and refresh
+   `Refactor verify command` / `Refactor verify result`. That refreshed pair is
+   the evidence the change kept GREEN, and it must be fresh — the pre-rework
+   pair is stale evidence.
+4. Record the trigger and the path taken on the current round's
+   `Round N: reviewer verdict` line, then return to `refactor` and re-submit.
+
+Which path applies is decided by the finding, not by the reviewer: a `REVISE`
+that requires new production behaviour opens round N+1 even when it came from
+`implementation-reviewer`.
+
+## Who the rework goes back to
+
+Returning to `refactor` re-submits the item to **every routed blocking reviewer
+whose verdict the rework could invalidate** — always the reviewer that opened
+the round, plus any reviewer that already returned `PASS` on artifacts the
+rework changed. A `PASS` recorded against the pre-rework test or production
+code is stale evidence: it does not count towards "After all routed blocking
+reviewers return PASS" and must be re-earned before the item may reach `done`.
+
+## Resuming a `review-fix` item
+
+A `review-fix` row can outlive the session that created it — the operator
+interrupts, or the run ends between the `REVISE` and the rework. On the next
+start, `review-fix` rows are selected **before** any `todo` row (Required
+Process, Phase: Red, step 1), so an interrupted rework is always resumed
+rather than stranded behind newer items.
+
+Resuming a `review-fix` row:
+
+1. Read the round blocks already in the item's evidence and take the highest
+   `Round N`; the reviewer verdict on that round names the finding to fix.
+2. Pick the path the finding calls for: open round `N + 1` and run the
+   RED/GREEN cycle when the fix needs new production behaviour, or take the
+   behaviour-preserving path above when it does not.
+3. Return the row to `refactor` and re-submit per **Who the rework goes back
+   to** above.
+
+A `review-fix` row must already have a `Test file` — it reached `refactor`
+before the `REVISE`. `validateTddList` checks the file exists for
+`review-fix` exactly as it does for `green`, `refactor` and `done`, so a
+rework row that lost its test file is reported (`TDDLIST_TEST_FILE_MISSING`)
+instead of being accepted as a valid ledger state.

package/assets/init/.qfai/assistant/skills/qfai-implement/references/selector-granularity.md

@@ -0,0 +1,24 @@
+# Selector Granularity
+
+`Selector` is **not** restricted to a single test function. A row may legally own several, written as
+a comma-separated list or a glob — but only when they observe the **same** boundary from different
+angles: `test_rejects_expired_token_via_header, test_rejects_expired_token_via_cookie`, or
+`test_rejects_expired_token_*`. Two different rejection reasons (`expired_token` and
+`wrong_audience`) are two boundaries and therefore two rows. What is restricted is what a row may
+_conflate_:
+
+- **One independently observable boundary per row.** Multiple selector entries are for covering that
+  one boundary from more than one angle, never for packing several boundaries behind one `TDD-ID`.
+  RED is still observed **per selector entry**, not once per row — each entry needs its own "watch it
+  fail for the expected reason" observation, and each entry's failure reason is recorded separately
+  in Evidence.
+- **A matrix-shaped `TC-*` must be decomposed before RED begins.** A `TC-*` that enumerates many
+  rejection reasons, a status-code matrix, or several independent state transitions is split across
+  multiple TDD rows — one falsifying oracle per row — rather than accumulated behind one selector.
+  The splitting rule: **one row per independently observable boundary**. Rows that decompose the
+  same `TC-*` all carry that `TC-*` in `TC-Refs`; `TC-Refs` is many-to-many with `TDD-ID`.
+- A selector that accumulates unrelated boundaries **invalidates the RED observation** — see the Red
+  phase below.
+- **Precedence, when the two rules seem to disagree:** the row-splitting rule wins. If you cannot
+  name the single boundary that every selector entry on a row observes, the row is carrying more
+  than one and must be split.

package/assets/init/.qfai/assistant/skills/qfai-implement/references/volume-policy.md

@@ -0,0 +1,149 @@
+# Volume Policy
+
+## Why this exists
+
+The per-item ceremony in `SKILL.md` is written for a ledger of tens of rows. At
+the volume `/qfai-sdd` and `/qfai-atdd` routinely produce it is arithmetically
+unfinishable, and an unfinishable process is abandoned wholesale — taking the
+RED/GREEN evidence and the drift discipline with it. Scaling the ceremony is
+what keeps those intact; dropping a gate is not on the table.
+
+The per-item ceremony below is written for a ledger of tens of rows. At the
+volume `/qfai-sdd` and `/qfai-atdd` routinely produce it is arithmetically
+unfinishable, and an unfinishable process is abandoned wholesale — taking the
+RED/GREEN evidence and drift discipline with it. Scale the ceremony instead.
+
+## Risk tier (derive per row)
+
+Derive the tier from the ledger row's `Layer`, what the item touches, and what
+it would cost to get wrong:
+
+| Tier              | Row shape                                                                                                              | Ceremony                                                                                                                          |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| **T1 — standard** | Pure decision logic; unit/component layer; touches no infrastructure, no public API surface, no UI; not critical below | `qa-gatekeeper` confirms RED/GREEN once per coherent group instead of once per row. Reviews are batched the same way (below).     |
+| **T2 — elevated** | Touches infrastructure, a public API surface, a contract (`CON-*`), or persisted schema — **or** is critical (below)   | Full per-item ceremony: per-row `qa-gatekeeper` RED and GREEN turns, per-row `completion-reviewer` and `implementation-reviewer`. |
+| **T3 — surface**  | Changes UI behavior or rendered output                                                                                 | T2 plus `product-surface-reviewer`.                                                                                               |
+
+Record the tier in the row's `Evidence` cell alongside the RED/GREEN commands.
+A row with no recorded tier is treated as **T2**.
+
+### Criticality outranks connectedness
+
+Tiering is not only about what the code is wired to. A row is **T2 regardless of
+layer**, even as pure unit-level logic touching nothing else, when it implements:
+
+- an authorization or authentication decision (permission checks, role/scope
+  evaluation, token or session validity);
+- cryptographic verification (signature, MAC, hash comparison, nonce or replay
+  checks, key selection);
+- money or accounting arithmetic (pricing, billing, tax, interest, currency
+  conversion, ledger balancing);
+- data-integrity or safety-critical logic (irreversible mutation and deletion
+  rules, quota and rate limits, PII redaction or retention, consent
+  enforcement, idempotency keys).
+
+Cheap to connect is not the same as cheap to get wrong. When it is arguable
+whether a row is critical, it is critical.
+
+### Routing is unchanged
+
+The tier scales **how often** a gate runs, never **whether** it runs.
+`agent-routing.yml` keeps `qa-gatekeeper`, `completion-reviewer` and
+`implementation-reviewer` all **mandatory** for `qfai-implement`; T1 only
+changes the submitted unit from one row to one coherent group. Every row is
+still covered by a live turn from each of those agents, and a group that has
+not been confirmed leaves all of its members short of the 11-point gate.
+
+Note the asymmetry, because "all routed blocking reviewers pass" alone is not
+the item gate: `blocking_agents` lists only `qa-gatekeeper` and
+`completion-reviewer`. `implementation-reviewer` is mandatory but not in that
+list, and a `REVISE` from it still blocks `done` — item 8 of the 11-point gate
+requires its PASS independently of the routing list. Read the 11-point gate as
+the authority for an item transition; `blocking_agents` governs phase
+progression, not the ledger write.
+
+## Batched review
+
+For T1 rows, run **one** `completion-reviewer` pass and **one**
+`implementation-reviewer` pass per _coherent group_ — a set of items that share
+a BR or an AC — instead of one pass per item. The group is the review unit:
+
+- record the group's member `TDD-ID`s as a single block in the evidence file;
+- a `REVISE` on the group blocks every member until it is resolved;
+- a group must not mix tiers; a T2 or T3 row is always reviewed alone.
+
+### Group formation (states and transitions)
+
+Batching adds **no** status value. It adds exactly **one** lifecycle edge, the
+`refactor -> red` QA rejection recovery in `SKILL.md`, because confirming
+RED/GREEN after the row has left `red` is only meaningful if a rejected row can
+redo it. A T1 row whose refactor verify is GREEN sits in `refactor` — that is
+the review-ready state — and waits there for its group. Members still move
+`refactor -> done`, only together.
+
+- **Open** the group when the first T1 row of a BR/AC reaches `refactor`.
+- **Fill** it by continuing to process that BR/AC's remaining rows one item at
+  a time. The one-item-at-a-time constraint is about the Red/Green cycle: at
+  most one row is in `red` or `green` at any moment. A row parked in `refactor`
+  is an in-flight member of the **open** group, not an abandoned item, so
+  parking is not a violation of that constraint.
+- **Close** the group — this is the review-start condition — at whichever comes
+  first: every member has reached `refactor`; the next `todo` row belongs to a
+  different BR/AC; the ledger has no `todo` rows left. A group never spans a
+  spec, so finishing a ledger also closes the open group.
+- **Review** on close: one `qa-gatekeeper` turn over the members' recorded
+  RED/GREEN evidence, one `completion-reviewer` pass, one
+  `implementation-reviewer` pass. On `REVISE` no member goes `done`; where the
+  faulted member goes depends on what was faulted:
+  - `completion-reviewer` / `implementation-reviewer` `REVISE`, or a
+    `qa-gatekeeper` `REVISE` about how the evidence was **written** — fix in
+    place; the member stays in `refactor` and the refactor verify re-runs.
+  - `qa-gatekeeper` `REVISE` rejecting the **cycle** (the RED never failed, or
+    failed for the wrong reason) — that member takes the `refactor -> red` QA
+    rejection recovery, cites the verdict in `Evidence`, and re-runs its
+    micro-cycle. The group stays open and is reviewed again on close. Leaving it
+    in `refactor` instead would strand it: forward-only means it could never
+    redo the RED the gatekeeper rejected.
+- **Checkpoint, then the ledger write.** Reviews passing is not the last gate:
+  `SKILL.md` Refactor step 5 and item 11 of the 11-point gate both require
+  checkpoint verification to pass **before** a row becomes `done`. Run it once
+  for the group after the three reviews return PASS, and only then transition
+  every member `refactor -> done` in the same ledger write. A failing checkpoint
+  leaves the whole group in `refactor` — no member goes `done` on a regression
+  the checkpoint would have caught.
+- A group left open when the run ends is a completion prohibition: rows still in
+  `refactor` already block spec-level completion.
+
+## Multi-spec queue
+
+Auto-discovery may accept **several** specs and process them **one spec at a
+time**, in the order the user confirms. This is a queue, not parallelism: the
+one-spec-at-a-time and one-item-at-a-time constraints are unchanged. It removes
+the "invoke the skill eight times by hand" tax without touching the parallelism
+question.
+
+### Advancing the queue
+
+The queue is only a queue if the skill walks it. Record the confirmed order
+once, then after each ledger:
+
+1. Close the spec normally — report its result, and satisfy the spec completion
+   conditions or report the blockers. `exception` rows do not stop the queue;
+   they are reported with their DR-IDs and carried into the final summary.
+2. Look at the remaining queue. **Empty -> exit.** Otherwise announce the next
+   `spec-id`, load its `test-list.md`, and restart at Phase: Red.
+3. "Report and exit" in CRITICAL CONSTRAINTS applies per ledger, not per run: a
+   ledger whose rows are all `done` yields "nothing to do" **for that spec** and
+   the queue advances past it rather than ending the run.
+4. Exit only after the last queued spec, with a summary naming every processed
+   spec and its outcome.
+
+A queue entry is never skipped silently: a spec that cannot be started (missing
+ledger, unresolved Change Request) is reported as blocked and the queue moves
+on to the next entry.
+
+## Cost visibility
+
+Before starting, state the implied cost: rows × gate cycles at the derived
+tiers. If the ledger exceeds ~50 rows, surface that number to the user before
+processing begins, and offer T1 batching explicitly.

package/assets/init/.qfai/assistant/skills/qfai-prototyping/SKILL.md

@@ -38,7 +38,7 @@ One final prototype satisfying the spec under a locked brand identity, with all
 - `references/design-md-spec.md` — DESIGN.md front-matter schema and
   validation rules
 - `templates/DESIGN.md.sample` — reference content shipped at the
-  consuming-project root by `qfai init`
+  consuming-project root by `npx qfai init`
 
 ## Required Contracts
 
@@ -60,13 +60,13 @@ current `DESIGN.md` hash does not match the lock.
   strict `surface_type: ui-bearing` frontmatter + matching
   `.qfai/contracts/ui/<spec-id>*.yaml`, with legacy title-marker and
   `qfai.config.yaml` `prototyping` pinning folded in. Run
-  `qfai doctor --profile prototyping` to surface the resolved value.
+  `npx qfai doctor --profile prototyping` to surface the resolved value.
   Zero UI-bearing specs at cycle 0 is a deterministic no-op exit `0`.
   Confirm each resolved spec has a supported `surface`.
 - Confirm root `DESIGN.md` and `.qfai/contracts/design/DESIGN.md.lock.yaml`
   both exist; confirm `.qfai/contracts/ui/*.yaml` exists.
-- Run `qfai prototyping preflight --target-url <url>` (alias for
-  `qfai doctor --profile prototyping`) — verifies DESIGN.md parses and
+- Run `npx qfai prototyping preflight --target-url <url>` (alias for
+  `npx qfai doctor --profile prototyping`) — verifies DESIGN.md parses and
   matches the lock sha256.
 
 ### Step 2-B — Verify Environment Preconditions
@@ -74,13 +74,14 @@ current `DESIGN.md` hash does not match the lock.
 - Confirm a capture route exists for each declared screen.
 - Canonical launcher: `npx --no-install playwright` or
   `node_modules/.bin/playwright` when PATH reachability is uncertain.
-- Legacy fallback (deprecation window only, emits
-  `D-DEPRECATED-PROBE` and will be removed in a future minor release):
-  `npx --no-install playwright-cli` or `node_modules/.bin/playwright-cli`.
+- `playwright-cli` was the legacy fallback. Its deprecation window closed:
+  `browserTool: "playwright-cli"` is now rejected by config load and
+  `D-DEPRECATED-PROBE` reports `error`. Install `playwright`
+  (`npm i -D playwright`) rather than reaching for it.
 
 ### Step 2-B.1 — Opt-in iterate flags
 
-Three flags extend `qfai prototyping iterate`; all default OFF so the
+Three flags extend `npx qfai prototyping iterate`; all default OFF so the
 prior invocation pattern is byte-equivalent when no flag is passed:
 
 - `--capture` — enable PNG / HTML capture per screen each cycle via
@@ -90,7 +91,13 @@ prior invocation pattern is byte-equivalent when no flag is passed:
 - `--auto-serve` — start an in-process `node:http` server rooted at
   the prototype tree for the cycle. SIGINT teardown <= 2 s;
   EADDRINUSE on a foreign owner exits 2 (no foreign-process kill).
-  Use when no external dev server is running.
+  Use when no external dev server is running. Routing is SPA-style:
+  a document request (GET/HEAD with `text/html` in `Accept`) that
+  matches no file on disk is served `index.html`, so client-side and
+  parameterized contract routes (`/overview`,
+  `/pairs/:instrument`) resolve instead of 404-ing. Sub-resource
+  requests (`.css`, `.png`, `fetch()`) still 404 when genuinely
+  missing, and the path-traversal 403 guard runs first.
 - `--check-convergence` — read-only peek of `prototyping.json`.
   Exits `0` when converged (`stopReason === "axes-exceptional"` with
   `acceptedIterationIndex` set), exits `2` otherwise. No writes,
@@ -100,9 +107,9 @@ prior invocation pattern is byte-equivalent when no flag is passed:
 
 | Step  | Actor                                                     | Action                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Output                                   |
 | ----- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
-| C0    | product-experience-architect                              | `qfai prototyping iterate --cycle 0 --target-url <url>`. CLI computes `sha256(DESIGN.md)`; lock match enforced. Generator reads contracts + `references/generator-prompt.md` + DESIGN.md tokens and writes `.qfai/prototypes/iter-00/index.html`. Capture + review → `iter-00/review.json`. Append entry; commit `prototyping: iter-00`.                                                                                                                                                                                                                        | iter-00, prototyping.json#designMdSha256 |
-| C1..9 | (a) devops, (b) reviewer, (c) orchestrator, (d) generator | (a) playwright-cli writes `iter-NN/<screen>.{png,html}`; (b) reviewer writes `iter-NN/review.json` per `references/reviewer-prompt.md` (4 UX axes ordinal, 200..500 word critique, `layoutAntiPatternsDetected[]`, `designMdViolations[]`, `pivotDirective`); (c) update `prototyping.json#iterations[]` + `progress.md`, commit `prototyping: iter-NN`; (d) `qfai prototyping iterate --cycle <n+1>` decides exit. After C9 do NOT call `--cycle 10` — the CLI rejects out-of-range cycles. See the "Cycle 9 budget exhaustion" subsection below for recovery. | iter-NN, exit ∈ {0, 64, 65, 66, 2}       |
-| H     | orchestrator                                              | Mirror latest to `.qfai/prototypes/final/index.html`. Per `references/handoff.md`: write `design-system.yaml` (deterministic DESIGN.md token mirror, no HTML extraction) + `prototype-handoff.yaml`. Run `qfai validate --profile prototyping --fail-on error` (produces `validate.json` with `counts.error === 0`), then `/qfai-verify` (produces `verify.json` with `status === "PASS"`), then `qfai prototyping certify` — certify requires both gate files to be present and passing before it will seal the certificate.                                   | DONE                                     |
+| C0    | product-experience-architect                              | `npx qfai prototyping iterate --cycle 0 --target-url <url>`. CLI computes `sha256(DESIGN.md)`; lock match enforced. Generator reads contracts + `references/generator-prompt.md` + DESIGN.md tokens and writes `.qfai/prototypes/iter-00/index.html`. Capture + review → `iter-00/review.json`. Append entry; commit `prototyping: iter-00`.                                                                                                                                                                                                                    | iter-00, prototyping.json#designMdSha256 |
+| C1..9 | (a) devops, (b) reviewer, (c) orchestrator, (d) generator | (a) playwright writes `iter-NN/<screen>.{png,html}`; (b) reviewer writes `iter-NN/review.json` per `references/reviewer-prompt.md` (4 UX axes ordinal, 200..500 word critique, `layoutAntiPatternsDetected[]`, `designMdViolations[]`, `pivotDirective`); (c) update `prototyping.json#iterations[]` + `progress.md`, commit `prototyping: iter-NN`; (d) `npx qfai prototyping iterate --cycle <n+1>` decides exit. After C9 do NOT call `--cycle 10` — the CLI rejects out-of-range cycles. See the "Cycle 9 budget exhaustion" subsection below for recovery. | iter-NN, exit ∈ {0, 64, 65, 66, 2}       |
+| H     | orchestrator                                              | Mirror latest to `.qfai/prototypes/final/index.html`. Per `references/handoff.md`: write `design-system.yaml` (deterministic DESIGN.md token mirror, no HTML extraction) + `prototype-handoff.yaml`. Run `npx qfai validate --profile prototyping --fail-on error` (produces `validate.json` with `counts.error === 0`), then `/qfai-verify` (produces `verify.json` with `status === "PASS"`), then `npx qfai prototyping certify` — certify requires both gate files to be present and passing before it will seal the certificate.                           | DONE                                     |
 
 **Exit codes**: `0` continue (read `pivotDirective`); `64` convergence (4
 axes `exceptional` AND `layoutAntiPatternsDetected` empty AND
@@ -117,7 +124,7 @@ covers `frozenSurfaceUnion` / `frozenLicenseCatalog` drift on cycle ≥ 1).
 
 ### License-verify hard-stop (exit 66)
 
-`qfai prototyping iterate` exits `66` when an `imageSources[]` entry on
+`npx qfai prototyping iterate` exits `66` when an `imageSources[]` entry on
 `prototyping.json` violates the cycle-0 frozen license catalog. The
 verifier rejects five distinct error codes:
 
@@ -142,18 +149,28 @@ Recovery path (no in-loop retry — the verifier is fail-closed):
 
 If convergence is not reached at iter-09, certify rejects the run; H
 handoff artifacts and `validate` / `/qfai-verify` can still execute for
-inspection, but `qfai prototyping certify --check` will exit non-zero
+inspection, but `npx qfai prototyping certify --check` will exit non-zero
 and prevent DONE.
 
-Use `qfai prototyping iterate --cycle 9 --check-convergence` for a
+Use `npx qfai prototyping iterate --cycle 9 --check-convergence` for a
 read-only peek of `prototyping.json` before refreezing: exit `0`
 confirms convergence (no recovery needed), exit `2` confirms the run
 did not converge. Recovery: review `DESIGN.md`, the pivot strategy
 in `references/reviewer-prompt.md`, and the latest `review.json`
-findings, then re-run `qfai prototyping iterate --cycle 0
+findings, then re-run `npx qfai prototyping iterate --cycle 0
 --target-url <url>` to refreeze. Do not seal a certificate against
 an unconverged iter-09.
 
+### Continuing or resetting a converged loop
+
+Only `stopReason: "axes-exceptional"` + `acceptedIterationIndex` seals a loop; `iterate --cycle N`
+then refuses with exit `2` past the accepted index, writing nothing. `license-verify-fail` /
+`input-error` do NOT seal — fix the cause and re-run the same cycle.
+`max-iterations` does not seal either, but iter-09 still stops every `--cycle N >= 1` at exit `65`.
+Recovery for both is the cycle-0 reset; re-running the accepted cycle is reported by the convergence
+gate (exit `64`) and writes nothing, so it is a state read, not a rerun. The reset command, the
+`--force` requirement and the `certify` alternative are in `references/iteration-loop.md#sealed-loop`.
+
 ## Evaluator Inputs (Mandatory)
 
 - Screenshot evidence path: `.qfai/evidence/prototyping/iter-NN/<screen>.png`
@@ -171,7 +188,7 @@ an unconverged iter-09.
 - Token-only colors / fonts / radii / shadows — non-DESIGN.md hex /
   rgb / rgba / hsl / font / radius / shadow values land in
   `designMdViolations[]` and block exit 64.
-- DONE only when `qfai prototyping certify --check` returns 0.
+- DONE only when `npx qfai prototyping certify --check` returns 0.
 - No `mode / round / polish / branch / concept-fit` artifacts.
 
 ## Delegation Scope Table
@@ -192,7 +209,7 @@ an unconverged iter-09.
 ## Completion
 
 DONE = `completion-certificate.json` exists AND
-`qfai prototyping certify --check` returns 0 AND `/qfai-verify` returns
+`npx qfai prototyping certify --check` returns 0 AND `/qfai-verify` returns
 PASS.
 
 Follow `.qfai/assistant/constitution/shared-skill-operating-baseline.md#gate-failure-autorepair-protocol` for validate, doctor, and quality-gate failures.

package/assets/init/.qfai/assistant/skills/qfai-prototyping/references/evidence-requirements.md

@@ -3,7 +3,7 @@
 Prototyping evidence files MUST include a `taskFidelity` section so the
 `QFAI-CRIT-009` gate passes. Below is the required keyword set and
 the canonical markdown shape consumed by the validator and the
-`qfai prototyping iterate --capture` template emitter.
+`npx qfai prototyping iterate --capture` template emitter.
 
 ## Required keywords