qfai 1.8.4 → 1.8.7

package/assets/init/.qfai/assistant/skills/qfai-discussion/references/discussion-artifact-rules.md

@@ -0,0 +1,62 @@
+# Discussion Artifact Rules
+
+Use this file when `/qfai-discussion` creates or reviews `.qfai/discussion/discussion-*` packs.
+
+## Required Pack
+
+Each pack uses immutable timestamp naming: `.qfai/discussion/discussion-YYYYMMDDhhmmssSSS/`.
+
+Required files:
+
+- `01_Context.md`
+- `02_Inception-Deck.md`
+- `03_Story-Workshop.md`
+- `04_Sources.md`
+- `05_Scope.md`
+- `06_REQ.md`
+- `07_NFR.md`
+- `08_Glossary.md`
+- `09_Constraints.md`
+- `10_Policy.md`
+- `11_OQ-Register.md`
+- `12_OQ-Resolution-Log.md`
+- `13_Deferred.md`
+- `14_Review-Request.md`
+- `99_delta.md`
+
+UI-bearing discussion packs may include `prototyping.yaml` as an optional recommendation artifact; non-ui discussion packs typically omit it. For `ui_bearing: false`, typically omit `prototyping.yaml`. Current discussion-pack readiness does not block on missing `prototyping.yaml`.
+
+## Rules
+
+- Run interview and requirement capture until `Disposition: open` is zero in `11_OQ-Register.md`.
+- OQ `Gate` values are `discussion`, `sdd`, `atdd`, `tdd`, or `ops`.
+- `deferred` is allowed only when `13_Deferred.md` has complete metadata.
+- Discussion outputs are rationale and intake logs; do not duplicate `.qfai/specs/**` SSOT.
+- `03_Story-Workshop.md` must include at least one Mermaid diagram.
+- Use Mermaid fences only for diagrams.
+- `14_Review-Request.md` must reference `.qfai/assistant/steering/agent-routing.yml` and `review-profiles.yml`.
+
+## UI/UX Exploration Family
+
+For UI-bearing packs, use:
+
+- `04_Sources.md` for trend translation and competitive reference registry
+- `uiux/30_exploration_brief.md`
+- `uiux/31_reference_pool.md`
+- `uiux/32_design_anti_goals.md`
+- `uiux/40_screen_contracts.md`
+
+Discussion is exploration-first and must not choose a single visual winner or final design system. Those are downstream prototyping outputs.
+
+## `prototyping.yaml`
+
+When `prototyping.yaml` is present, use the v2.0 single-thread schema:
+
+```yaml
+prototyping:
+  surface: web # web | mobile | desktop | mixed
+```
+
+The v1.x `recommended_mode` / `allowed_modes` / `mode_expectations` fields
+were removed in spec-0017 P3 (the single-thread evolution loop fixes
+iteration count globally to 15).

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/prototyping.yaml

@@ -1,17 +1,9 @@
 prototyping:
-  recommended_mode: full-harness
-  rationale: >
-    Fill this with a concrete reason tied to the full-harness evidence obligations.
-  allowed_modes:
-    - full-harness
+  # v2.0 single-thread evolution loop (spec-0017): mode/maxCycles concepts
+  # are removed; iteration count is fixed at 15 globally in
+  # `core/prototyping/iteration.ts#MAX_ITERATIONS`.
   # Replace `web` with one of the prototyping-supported surfaces if needed:
   #   web | mobile | desktop | mixed
   # (discussion classification also allows `cli` and `non-ui`, but those are
-  #  not valid prototyping execution surfaces; see
-  #  `packages/qfai/src/core/prototyping/surfacePolicy.ts` — PROTOTYPING_SUPPORTED_SURFACES.)
+  #  not valid prototyping execution surfaces.)
   surface: web
-  mode_expectations:
-    full-harness:
-      expected_iterations: "2+"
-      process: "measure -> score -> fix code -> re-run"
-      calibration_ref: "qfai.config.yaml#prototyping.calibration"

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/31_reference_pool.md

@@ -2,12 +2,12 @@
 
 ## Exploration References
 
-| Ref     | Type    | Why it matters | Adopted points | Rejected points | Local translation |
-| ------- | ------- | -------------- | -------------- | --------------- | ----------------- |
-| REF-001 | Product | [why]          | [adopted]      | [rejected]      | [translation]     |
+| Ref     | Kind       | Source URL  | Why it matters | Adopted points | Rejected points | Local translation | Copy risk | Template usage policy |
+| ------- | ---------- | ----------- | -------------- | -------------- | --------------- | ----------------- | --------- | --------------------- |
+| REF-001 | competitor | https://... | ...            | ...            | ...             | ...               | medium    | reference-only        |
 
 ## Design Guideline Research
 
-| Ref    | Guideline   | Rule refs   | Why it matters | Local translation |
-| ------ | ----------- | ----------- | -------------- | ----------------- |
-| GL-001 | [guideline] | [rule refs] | [why]          | [translation]     |
+| Ref    | Guideline | Rule refs | Why it matters | Local translation |
+| ------ | --------- | --------- | -------------- | ----------------- |
+| GL-001 | ...       | ...       | ...            | ...               |

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

@@ -60,7 +60,7 @@ Skill-specific examples:
 
 - This skill processes **one test at a time** from `test-list.md`.
 - Each item goes through the full TDD micro-cycle: write a **failing test** first, then make it pass, then refactor.
-- The execution ledger is located at `.qfai/specs/spec-XXXX/tdd/test-list.md`.
+- The execution ledger is located at `.qfai/specs/<spec-id>/tdd/test-list.md`.
 - Items are processed **serially** by default. Parallel processing is allowed only when items target independent SUT slices with no shared state.
 - Status transitions follow a strict forward-only lifecycle: `todo` -> `red` -> `green` -> `refactor` -> `done`.
 - The `exception` status can be reached from any active status when an anomaly is detected.
@@ -76,13 +76,21 @@ Execute the TDD micro-cycle for each pending item in `test-list.md`, transitioni
 
 - Review rendered output, screenshot evidence, or HTML output before closing any UI-affecting item.
 - Read spec + contract inputs first whenever implementation touches UI or critique-driven behavior.
-- Read order: `01_Spec.md` → `03_Acceptance-Criteria.md` → `05_Examples.md` →
+- Read order (v2.0, spec-0017 P11): `01_Spec.md` → `03_Acceptance-Criteria.md` → `05_Examples.md` →
   `.qfai/contracts/design/exploration-brief.yaml` →
-  `.qfai/contracts/design/anchor-selection.yaml` (legacy alias, when present) →
-  `.qfai/contracts/design/evaluation-axes.yaml` (legacy alias, when present) →
-  `.qfai/contracts/design/evaluation-rubric.yaml` → `.qfai/contracts/design/evaluator-calibration.yaml` →
-  `.qfai/contracts/design/selected-direction.yaml` → `.qfai/contracts/design/design-system.yaml` → `.qfai/contracts/ui/*.yaml` →
-  optional design tokens → optional fallback mock → mermaid flows.
+  `.qfai/contracts/design/reference-pool.yaml` → `.qfai/contracts/design/brand-design.yaml` →
+  `.qfai/contracts/design/design-system.yaml` (extracted from final iter) →
+  `.qfai/contracts/design/prototype-handoff.yaml` → `.qfai/contracts/ui/*.yaml` →
+  canonical prototype evidence under `.qfai/evidence/prototyping/iter-NN/<screen>.{png,html}` →
+  `.qfai/prototypes/final/index.html`.
+- The v1.x evaluation-rubric / evaluator-calibration / selected-direction contracts and
+  `prototypes/winner/index.html` were removed in spec-0017 P4/P8.
+- Do not read discussion-pack UI/UX sidecars, fallback mocks, or legacy design aliases.
+- Prototype HTML is analysis input, not production source. Reimplement with project-native
+  patterns while preserving the visual identity captured in `prototype-handoff.yaml`
+  `implementationNotes` (free-form prose); the v1.x mustPreserve / mayAdapt / mustNotCopy
+  three-category split is removed.
+- UI-affecting items require product-surface-reviewer prototype parity review before `done`.
 - If code intent and rendered output diverge, treat the rendered/HTML result as the blocking review input and reconcile before DONE.
 
 ## Non-goals
@@ -94,7 +102,7 @@ Execute the TDD micro-cycle for each pending item in `test-list.md`, transitioni
 
 ## Execution Ledger: test-list.md
 
-The execution ledger at `.qfai/specs/spec-XXXX/tdd/test-list.md` tracks progress with these required columns:
+The execution ledger at `.qfai/specs/<spec-id>/tdd/test-list.md` tracks progress with these required columns:
 
 | Column    | Description                                              |
 | --------- | -------------------------------------------------------- |
@@ -253,8 +261,9 @@ Use the shared schema (per-row `Status (PASS/REVISE)` column, reviewer response
 ## Completion Contract (Shared)
 
 Follow `.qfai/assistant/instructions/shared-skill-operating-baseline.md#completion-contract-shared`.
+Follow `.qfai/assistant/instructions/shared-skill-operating-baseline.md#gate-failure-autorepair-protocol` for validate, doctor, and quality-gate failures.
 
-### Item completion checklist (10-point gate)
+### Item completion checklist (11-point gate)
 
 An item in `test-list.md` may transition to `done` only when ALL of the following are satisfied:
 
@@ -266,8 +275,9 @@ An item in `test-list.md` may transition to `done` only when ALL of the followin
 6. Refactor was performed and GREEN was re-confirmed after refactor
 7. `completion-reviewer` returned PASS (spec / completion review gate)
 8. `implementation-reviewer` returned PASS (code quality review gate)
-9. `test-list.md` Status and Evidence columns are updated with fresh evidence
-10. Checkpoint verification passed
+9. UI-affecting items have prototype parity PASS from `product-surface-reviewer`
+10. `test-list.md` Status and Evidence columns are updated with fresh evidence
+11. Checkpoint verification passed
 
 ### Spec completion conditions
 
@@ -293,7 +303,7 @@ Completion MUST NOT be declared when any of the following are true:
 
 ## Evidence (MANDATORY)
 
-Create/update: `.qfai/evidence/implement-spec-XXXX.md`
+Create/update: `.qfai/evidence/implement-<spec-id>.md`
 
 Required sections:
 
@@ -317,6 +327,7 @@ Each TDD item MUST have fresh evidence containing at minimum:
 - `Refactor verify result` — the output confirming GREEN is maintained
 - `Spec review` — completion-reviewer result (PASS or FAIL)
 - `Code quality review` — implementation-reviewer result (PASS or FAIL)
+- `Prototype parity` — product-surface-reviewer result for UI-affecting items (PASS or REVISE)
 
 ### Evidence hard rules
 

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

@@ -1,21 +1,10 @@
 ---
 name: qfai-prototyping
-title: QFAI Prototyping (Exploration-First Harness)
-description: "Run a planner/generator/evaluator UI harness with a 5→3→2→1 direction funnel, breakthrough detection, and final design-system extraction."
-argument-hint: "[--auto]"
+title: QFAI Prototyping (Single-Thread Design Evolution Loop)
+description: "Iterate one prototype through up to 15 cycles of generate-capture-review with explicit pivot permission, until 4 axes reach exceptional or the budget is exhausted."
+argument-hint: ""
 allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
-roles:
-  [
-    orchestrator,
-    delivery-planner,
-    product-experience-architect,
-    frontend-engineer,
-    backend-engineer,
-    devops-ci-engineer,
-    completion-reviewer,
-    product-surface-reviewer,
-    qa-gatekeeper,
-  ]
+roles: [orchestrator, product-experience-architect, product-surface-reviewer, devops-ci-engineer]
 routing-profile: ui-surface-aware
 mode: execution-focused
 ---
@@ -24,341 +13,98 @@ mode: execution-focused
 
 [DRIFT-PROTOCOL:MANDATORY]
 
-This skill owns prototyping orchestration directly.
-Do not rely on a CLI entrypoint or package runtime loop.
+This skill runs one prototype through up to 15 iterations. There is no funnel, no parallel candidates, no mode. Iteration count is fixed at 15.
 
-## CRITICAL CONSTRAINTS (Read First)
-
-- Scope is all specs from `.qfai/specs/spec-*`.
-- The AI evaluator sub-agent performs visual evaluation. QFAI does not score visual quality. (per the resolved primary prototyping spec — see `qfai prototyping show-spec`)
-- Playwright CLI (`playwright-cli`) is the sole standard browser tool. Playwright MCP, Node Playwright direct invocation, and screenshot-capture shell scripts are not used. (per the resolved primary prototyping spec)
-- QFAI pre-assigns evidence paths. The evaluator MUST use the paths in the command plan (`review-bundle.json` → `command-plans.json`); it MUST NOT invent paths.
-- For every declared screen and every active candidate in every round, 4 evidence artifacts are mandatory:
-  - screenshot: `.qfai/evidence/prototyping/rounds/<round>/candidates/<candidate-id>/<screen-id>.png`
-  - HTML: `.qfai/evidence/prototyping/rounds/<round>/candidates/<candidate-id>/<screen-id>.html`
-  - accessibility snapshot: `.qfai/evidence/prototyping/rounds/<round>/candidates/<candidate-id>/<screen-id>.snapshot.txt`
-  - command log: `.qfai/evidence/prototyping/rounds/<round>/candidates/<candidate-id>/<screen-id>.commands.json`
-- Canonical latest screenshot path: `.qfai/evidence/prototyping/screenshots/<screen-id>.png`
-- Canonical latest HTML path: `.qfai/evidence/prototyping/html/<screen-id>.html`
-- Canonical latest paths MUST mirror the latest accepted winner/polish artifacts.
-- If any of the 4 artifacts is missing for a declared screen, the round is incomplete; rerun is mandatory, not waiver.
-- Mode differences are limited to `maxCycles` only (low-cost=1, standard=3, full-harness=20). Every other gate, obligation, reviewer severity, and completion criterion is identical across modes. (per the resolved primary prototyping spec)
-- DONE is forbidden until `qfai validate --profile prototyping --fail-on error` passes and `/qfai-verify` can approve the run.
-- Supported UI prototyping surfaces are `web`, `mobile`, `desktop`, and `mixed`.
-- `cli`, API-only, backend-only, and `ui_bearing: false` classifications are not prototyping execution targets.
-- Machine checks are limited to schema/evidence validation, mode invariant enforcement, review-cycle completeness, and breakthrough trigger detection.
-- Shared evidence vocabulary: `prototyping.json`, `review-bundle.json`, `command-plans.json`, `evaluator-reviews/<candidate-id>.json`, `harvest.json`, `absorption-plan.json`, `reimplementation.json`, `breakthrough.json`.
-- Direction funnel completion is not stage completion.
-- Selecting the first winner does not satisfy completion. Completion review is forbidden until at least one post-selection polish cycle has completed.
-- Completion requires every reviewer sub-agent to score every evaluation axis at `100/100`; `95` is not a completion border.
-- Do not use `complete`, `completed`, `done`, or equivalent completion wording in other languages before the completion checklist passes. Use `exploration complete`, `winner selected`, `polishing`, `breakthrough checking`, or `reviewer gate pending` for interim states.
+The workflow is static-first and file-based by default. Supported UI prototyping surfaces are: web, mobile, desktop, mixed. `cli` is not a prototyping execution target and is rejected. `ui_bearing: false` specs are excluded from prototyping execution.
 
 ## Goal
 
-Generate multiple design directions, converge on a winner, extract the selected direction and final design system, and keep the winner open to breakthrough pivots during later polish iterations.
-
-## Surface / Mode
-
-- surface / mode routing uses `standard` as the default execution path.
-- **Mode Invariant**: modes differ only by `maxCycles`. Review gate, evidence requirements, reviewer severity, best-of-history, breakthrough detection, and completion criteria are identical across modes.
-  - `low-cost`: `maxCycles = 1`
-  - `standard`: `maxCycles = 3` (default)
-  - `full-harness`: `maxCycles = 20`
-- No mode weakens obligations. Choosing a lower mode buys fewer chances to iterate, not a looser gate.
+Produce an artifact in which a creative breakthrough has emerged through serial iteration — the kind of self-driven "scrap and reimagine" that arises when the model accumulates enough critique signal that staying on the current path is worse than rebuilding (Anthropic Dutch art museum pattern).
 
 ## Required References
 
-Read and follow these references before execution:
+- `references/iteration-loop.md` — flow + evidence paths
+- `references/generator-prompt.md` — generator system prompt + pivot permission
+- `references/reviewer-prompt.md` — reviewer output schema + global anti-slop list
+- `references/handoff.md` — design-system extraction + handoff yaml
 
-- **Primary SSOT for the prototyping harness**: resolve at runtime by running
-  `qfai prototyping show-spec` from the repo root. The output gives you the
-  resolved spec ID and `01_Spec.md` path (configured via
-  `qfai.config.yaml: prototyping.primarySpecId`, or auto-detected via the
-  `surface_type: ui-bearing` marker in `01_Spec.md`). Do not assume any
-  particular spec ID exists — read whatever `show-spec` returns.
-- `.qfai/assistant/skills/qfai-prototyping/references/evidence-requirements.md`
-- `.qfai/assistant/skills/qfai-prototyping/references/iteration-cycle.md`
-- `.qfai/assistant/skills/qfai-prototyping/references/l1-review-guide.md`
-- `.qfai/assistant/skills/qfai-prototyping/references/l2-review-guide.md`
-- `.qfai/contracts/design/anchor-selection.yaml` when legacy validator slices are exercised
-- `.qfai/contracts/design/evaluation-axes.yaml` when legacy validator slices are exercised
-- `.qfai/assistant/skills/qfai-prototyping/references/design-system-compliance.md`
-- `.qfai/assistant/skills/qfai-prototyping/references/reviewer-gate.md`
-- `.qfai/assistant/steering/test-layers.md`
-
-## Delegation Scope Table
+## Required Contracts
 
-All sub-agent delegation in this skill MUST follow the category-to-role mapping below.
-Assigning a task to a role not listed for the category is a violation and MUST be flagged.
-Evaluation scoring and screenshot capture must use only the allowed roles below.
-
-| Category                           | Allowed Role(s)                                        |
-| ---------------------------------- | ------------------------------------------------------ |
-| UI implementation                  | frontend-engineer, product-experience-architect        |
-| Playwright CLI execution & capture | product-surface-reviewer, product-experience-architect |
-| Evaluation scoring                 | product-surface-reviewer, product-experience-architect |
-| Build                              | devops-ci-engineer, backend-engineer                   |
-| Breakthrough planning              | product-experience-architect, frontend-engineer        |
-
-Any delegation map entry that assigns a category to an undefined or unlisted role MUST produce a violation finding naming the undefined role and the category.
-
-## Required Process
-
-### Step 0 — Execution Plan
-
-Before any code is written, create an execution plan record in the work evidence.
-
-Required fields:
-
-- `targetRounds`: ordered array; default funnel is `["r5", "r3", "r2", "r1"]`
-- `funnelPolicy`: `5->3->2->1`
-- `evaluationAxesSource`: ref to `.qfai/contracts/design/evaluation-rubric.yaml`
-- `delegationMap`: category-to-role assignments per Delegation Scope Table
-- `plannedAt`: ISO-8601 timestamp
-
-### Step 1 — Read Inputs
-
-Read the downstream-ready spec/contract inputs and verify:
-
-- `.qfai/specs/<spec-id>/01_Spec.md`
-- `.qfai/specs/<spec-id>/03_Acceptance-Criteria.md`
-- `.qfai/contracts/design/exploration-brief.yaml`
-- `.qfai/contracts/design/evaluation-rubric.yaml`
-- `.qfai/contracts/design/evaluator-calibration.yaml`
-- `.qfai/contracts/design/anchor-selection.yaml` when legacy validator slices are exercised
-- `.qfai/contracts/design/evaluation-axes.yaml` when legacy validator slices are exercised
-- `.qfai/contracts/design/selected-direction.yaml` when already created
-- `.qfai/contracts/design/design-system.yaml` when already created
+- `.qfai/specs/spec-*/{01_Spec.md, 03_Acceptance-Criteria.md}`
 - `.qfai/contracts/ui/*.yaml`
+- `.qfai/contracts/design/exploration-brief.yaml`
+- `.qfai/contracts/design/reference-pool.yaml`
+- `.qfai/contracts/design/brand-design.yaml`
 
-Read order:
-
-1. `.qfai/specs/<spec-id>/01_Spec.md`
-2. `.qfai/specs/<spec-id>/03_Acceptance-Criteria.md`
-3. `.qfai/contracts/design/exploration-brief.yaml`
-4. `.qfai/contracts/design/evaluation-rubric.yaml`
-5. `.qfai/contracts/design/evaluator-calibration.yaml`
-6. `.qfai/contracts/design/anchor-selection.yaml` (legacy validator alias, when present)
-7. `.qfai/contracts/design/evaluation-axes.yaml` (legacy validator alias, when present)
-8. `.qfai/contracts/design/selected-direction.yaml`
-9. `.qfai/contracts/design/design-system.yaml`
-10. `.qfai/contracts/ui/*.yaml`
-
-### Step 2 — Verify Execution Preconditions
-
-Confirm all of the following before any evaluation:
-
-- classification is UI-bearing
-- surface is `web`, `mobile`, `desktop`, or `mixed`
-- every declared screen has a stable `screen-id`
-- the exploration brief, evaluation rubric, and evaluator calibration contracts satisfy the required schema
-
-### Step 3 — Generate Divergent Directions
-
-Generate 5 clearly distinct design directions before selecting a winner.
-Do not begin with a single incumbent direction.
-
-### Step 4 — Round Start: Prepare Candidate Review Bundle & Command Plans
-
-Before launching the evaluator, prepare the round-scoped artifacts via QFAI (not by hand):
-
-- Run `qfai prototyping round-start --round <rN> --candidates <csv> --target-url <url> --mode <mode>`.
-- QFAI produces:
-  - `.qfai/evidence/prototyping/rounds/<rN>/command-plans.json` — the candidate-aware Playwright CLI command plans
-  - `.qfai/evidence/prototyping/rounds/<rN>/review-bundle.json` — the evaluator input bundle (candidates, axisDefs, designSystemChecklist, commandPlanRef)
-- Do not invent evidence paths. Paths are fixed by QFAI per the resolved primary prototyping spec.
-
-### Step 5 — AI Evaluator Executes the Command Plans and Captures Evidence
-
-For every declared screen of every active candidate in the current round, the AI evaluator sub-agent:
-
-1. Reads `command-plans.json` for the round
-2. Runs `playwright-cli goto <url>` for the candidate route
-3. Runs `playwright-cli snapshot --save <candidate-path>/<screen-id>.snapshot.txt`
-4. Performs interaction commands (click/fill) to exercise `primaryTasks` noted in the plan
-5. Runs `playwright-cli screenshot --full-page --save <candidate-path>/<screen-id>.png`
-6. Runs `playwright-cli eval "document.documentElement.outerHTML" > <candidate-path>/<screen-id>.html`
-7. Saves the sequence of executed commands to `<candidate-path>/<screen-id>.commands.json`
-
-If any capture step fails, the evaluator records the failure and stops pretending the screen was evaluated. The round is incomplete and must be rerun.
-
-### Step 6 — Launch Evaluation Reviewers
-
-Launch evaluation reviewer sub-agents with the full context bundle. Inputs are read from `review-bundle.json`:
-
-- per-screen screenshot, HTML, accessibility snapshot, and command log under `rounds/<round>/candidates/<candidate-id>/`
-- `axisDefs` (from `.qfai/contracts/design/evaluation-rubric.yaml`)
-- `previousScore` from the prior round when available
-- `designSystemChecklist` (from `.qfai/contracts/design/design-system.yaml`)
-- `commandPlanRef` pointing at `command-plans.json`
-
-The reviewer writes `rounds/<round>/evaluator-reviews/<candidate-id>.json` with concrete `evidenceRefs[]` for every score. Placeholder refs are rejected.
-
-### Step 7 — Harvest and Direction Funnel
-
-Run the mandatory convergence funnel:
-
-- `r5`: 5 directions -> top 3
-- `r3`: top 3 remixed -> top 2
-- `r2`: top 2 -> selected winner `r1`
-
-At the end of each harvestable round:
-
-- run `qfai prototyping round-harvest --round <rN>`
-- record survivors with `qfai prototyping round-narrow --round <rN> --survivors <csv>`
-- for `r3|r2|r1`, generate absorption templates with `qfai prototyping round-absorb --round <rN> --survivors <csv>`
-
-### Step 8 — Extract Winner Contracts
-
-After the first winner is selected:
-
-- write `.qfai/contracts/design/selected-direction.yaml`
-- extract `.qfai/contracts/design/design-system.yaml`
-
-Selecting the first winner is not completion. Do not start completion review and do not use completion wording until Step 9, Step 10, Step 12, reviewer gate, and the perfect-100 score gate pass.
-
-### Step 9 — Polish the Winner
-
-Iterate on the selected winner with normal critique/rework loops.
-Do not assume the latest iteration is automatically best; keep best-of-history in evidence.
-At least one full post-selection polish loop is mandatory. Each polish loop must include critique, fix, re-capture, re-review, and breakthrough check evidence.
-
-## Cycle Gate
+`reference-pool.yaml` is read as **deviate-from**, not imitate-this.
 
-- Completion requires at least one `polish` cycle after winner selection (per the resolved primary prototyping spec). This applies to all modes.
-- The same gate applies in every mode; modes differ only in `maxCycles` (low-cost=1, standard=3, full-harness=20).
-- If the polish-cycle budget is exhausted before the gate is satisfied, the run does NOT complete. The evaluator returns `REVISE` and the developer may re-run at a higher mode.
-- Any phase transition to completion must pass through the cycle gate and the reviewer gate.
+## Required Process
 
-### Step 10 — Breakthrough Detection
+### Step 2-A — Verify Contract Preconditions
 
-After each polish iteration, run the mechanical breakthrough detector.
-If `allReviewerAxesPerfect100` is false and score improvement is below the configured plateau threshold and code change is below the configured diff threshold, trigger breakthrough branching.
+- Confirm the selected spec is UI-bearing and has a supported `surface` value.
+- Confirm `.qfai/contracts/ui/*.yaml` and design contracts exist before generation.
+- Run `qfai prototyping preflight --target-url <url>` or `qfai doctor --profile prototyping`.
 
-### Step 11 — Breakthrough Branch Loop
+### Step 2-B — Verify Environment Preconditions
 
-When breakthrough is triggered:
+- Confirm a capture route exists for each declared screen.
+- Use `npx --no-install playwright-cli` or `node_modules/.bin/playwright-cli` when PATH reachability is uncertain.
 
-- generate exactly 2 branch directions
-- compare incumbent + 2 branches
-- replace the mainline if a branch wins
-- refresh selected-direction/design-system if the winner changes
-- record the decision in `.qfai/evidence/breakthrough.json`
+1. **Seed (cycle 0)**
+   - Run `qfai prototyping iterate --cycle 0 --target-url <url>`.
+   - Generator (product-experience-architect) reads contracts + `references/generator-prompt.md`.
+   - Generator writes `.qfai/prototypes/iter-00/index.html` (one self-contained file).
+   - Capture + review (steps 2-a / 2-b).
+   - Append entry to `prototyping.json#iterations[]`. Commit `prototyping: iter-00`.
 
-### Step 12 — Validate and Verify
+2. **Loop (cycle 1..14)**
+   - **(a) Capture** (devops-ci-engineer): playwright-cli writes `iter-NN/<screen>.{png,html}`.
+   - **(b) Review** (product-surface-reviewer): per `references/reviewer-prompt.md`, write `iter-NN/review.json` with 4-axis ordinal scores, 200–500 word prose critique, `slopPatternsDetected[]`, and `pivotDirective`.
+   - **(c) Update** `prototyping.json#iterations[]` and `progress.md`. Commit `prototyping: iter-NN`.
+   - **(d) Iterate**: run `qfai prototyping iterate --cycle <n+1>`.
+     - exit `0` → continue. Generator reads `pivotDirective` and produces iter-(n+1).
+     - exit `64` → all axes exceptional, go to step 3.
+     - exit `65` → 15 cycles reached, go to step 3.
 
-- Run `qfai validate --profile prototyping --fail-on error`.
-- Route `/qfai-verify` or its equivalent gate workflow for final quality approval.
-- Do not declare completion until the reviewer result is `PASS`.
+3. **Handoff**
+   - Mirror latest iter to `.qfai/prototypes/final/index.html`.
+   - Per `references/handoff.md`: extract `design-system.yaml`, write `prototype-handoff.yaml`.
+   - Run `qfai prototyping certify`.
+   - Run `qfai validate --profile prototyping --fail-on error` and `/qfai-verify`.
 
 ## Evaluator Inputs (Mandatory)
 
-Evaluation reviewer sub-agents MUST be launched with the `review-bundle.json` for the current round. The bundle contains all required inputs. At a minimum, the bundle MUST reference:
-
-1. screenshots (per declared screen, round/candidate path)
-2. HTML snapshots (per declared screen, round/candidate path)
-3. accessibility snapshots (`<screen-id>.snapshot.txt` per declared screen, round/candidate path)
-4. Playwright CLI command log (`<screen-id>.commands.json` per declared screen, round/candidate path)
-5. `axisDefs` from `.qfai/contracts/design/evaluation-rubric.yaml`
-6. `previousScore` from the prior round when available
-7. `designSystemChecklist` from `.qfai/contracts/design/design-system.yaml`
-8. `commandPlanRef` pointing at `command-plans.json`
-
-The evaluator writes `evaluator-reviews/<candidate-id>.json` with per-axis `score`, `rationale`, and `evidenceRefs[]`. Every `evidenceRefs[]` entry MUST point to an existing artifact; placeholder strings (`""`, `"tbd"`, `"TBD"`) are rejected by `qfai validate`.
-
-## Visual Quality Structural Checklist
+- Screenshot evidence path: `.qfai/evidence/prototyping/iter-NN/<screen>.png`
+- HTML snapshot path: `.qfai/evidence/prototyping/iter-NN/<screen>.html`
+- Review inputs: latest screenshot, latest HTML snapshot, prior `review.json` files, `progress.md`, and `reference-pool.yaml` as deviate-from input.
 
-Each iteration evaluation MUST score all 6 visual categories:
+## Critical Constraints
 
-1. Design quality
-2. Originality
-3. Craft
-4. Functionality
-5. Accessibility risk
-6. Implementation plausibility
+- DO NOT generate parallel candidates. One lineage only.
+- DO NOT preserve elements out of caution; the latest iter is always accepted.
+- DO NOT declare DONE before `qfai prototyping certify --check` returns 0.
+- DO NOT add `mode/round/polish/branch/concept-fit/design-system-compliance` artifacts.
+- DO NOT score similarity to `reference-pool` positively; it is deviate-from input.
 
-### Reviewer Gate (MUST)
-
-Reviewer checks are defined in:
-
-- `.qfai/assistant/skills/qfai-prototyping/references/reviewer-gate.md`
-- `.qfai/assistant/steering/test-layers.md`
-
-Minimum reviewer responsibilities:
-
-- enforce the Drift Protocol before approving a completion transition
-- verify mandatory screenshot/HTML evidence exists for every declared screen
-- verify exploration brief, evaluation rubric, and evaluator calibration were used
-- verify missing evidence caused rerun rather than waiver
-- verify `qfai validate --profile prototyping --fail-on error` completed successfully
-- verify breakthrough trigger evidence is present
-- verify best-of-history handling is documented
-- verify at least one post-selection polish iteration completed after winner selection
-- verify every reviewer sub-agent scored every evaluation axis at `100/100`
-- reject completion claims based on any 95-point threshold
-- treat score/volume heuristics as signals, not gates
-- return `Result: PASS | REVISE`
-
-## Sub-agent Delegation (MANDATORY)
-
-Follow `.qfai/assistant/instructions/shared-skill-delegation-baseline.md`.
-
-### Orchestrator Protocol (MUST)
-
-- do not self-approve
-- keep evidence paths canonical
-- integrate delegated results only
-
-### Capability Probe (MUST)
-
-- No additional overrides.
-
-### Delegation Failure (Hard Stop)
-
-- No additional overrides.
-- Do not simulate roles. If the first required delegation fails, stop the stage and report remediation.
-
-## Work Orders Summary
-
-Use the shared schema (per-row `Status (PASS/REVISE)` column, reviewer response `Result: PASS | REVISE`).
-
-## Completion Contract (Shared)
-
-Follow `.qfai/assistant/instructions/shared-skill-operating-baseline.md#completion-contract-shared`.
+## Delegation Scope Table
 
-Prototyping-specific additions (apply to all modes identically):
+| Work                               | Allowed Role                 |
+| ---------------------------------- | ---------------------------- |
+| Generation                         | product-experience-architect |
+| Playwright CLI execution & capture | devops-ci-engineer           |
+| Evaluation scoring                 | product-surface-reviewer     |
 
-- all specs are covered
-- all declared screens have 4 artifacts per active candidate / round: screenshot, HTML, accessibility snapshot, Playwright CLI command log
-- canonical latest paths mirror the latest accepted winner/polish state
-- `review-bundle.json`, `command-plans.json`, and per-candidate evaluator reviews exist for every round
-- `selected-direction.yaml` exists
-- `design-system.yaml` exists
-- `breakthrough.json` exists
-- `bestOfHistory` and `breakthrough` sections present in `prototyping.json`
-- at least one post-selection polish cycle completed after winner selection
-- every reviewer sub-agent scored every evaluation axis at `100/100`
-- independent reviewer gate returned `PASS`
-- `qfai validate --profile prototyping --fail-on error` passes
+### Reviewer Gate
 
-## FINAL CHECKLIST (Check Last)
+- Check Drift Protocol compliance before DONE.
+- Check `.qfai/assistant/steering/test-layers.md` alignment.
+- Treat reviewer findings as signals, not gates, unless certify/validate/verify fails.
 
-- All specs are covered in the Coverage Matrix.
-- Every declared screen has screenshot, HTML, accessibility snapshot, and command log evidence per active candidate / round.
-- Canonical latest paths mirror the latest accepted winner/polish artifacts.
-- Mode invariant: `maxCycles` is the only mode-dependent field in `prototyping.json` (validated by `QFAI-PROT-MODE-001`).
-- Missing evidence triggered rerun instead of waiver.
-- Direction funnel `5->3->2->1` completed.
-- Direction funnel completion was not treated as stage completion.
-- At least one post-selection polish cycle completed with critique/fix/re-capture/re-review/breakthrough checks.
-- Every reviewer sub-agent scored every evaluation axis at `100/100`.
-- Breakthrough detector ran after polish cycles.
-- Independent reviewer returned PASS; otherwise status is REVISE.
+## Completion
 
-## Completion Message & Next Actions (MUST)
+DONE = `completion-certificate.json` exists AND `qfai prototyping certify --check` returns 0 AND `/qfai-verify` returns PASS.
 
-Action:
+## Next
 
-- Proceed: `/qfai-atdd`
-- Quality gate: `/qfai-verify`
-- Rework prototyping: rerun `/qfai-prototyping` with corrected screenshot/HTML evidence
+- `/qfai-atdd` / `/qfai-implement` / `/qfai-verify`