qfai 1.8.4 → 1.8.6

package/README.md

@@ -17,8 +17,7 @@ The agent reads the repository, produces the required artifacts, and iterates un
 
 ## Release status
 
-- Current package version: `1.7.15`
-- Release posture: v1.7.15 enforces runtime truthfulness.
+- Release posture: runtime truthfulness is enforced.
 - Prototyping is UI-only; `full-harness` is measurement-driven iteration accumulation for UI-bearing surfaces only.
 - Runtime observation is observed-only (no synthetic 200 / API / DB prototyping coverage).
 - Browser QA is mandatory per screen in full-harness, and `actionsWired` reports action coverage rather than finding count.
@@ -57,8 +56,18 @@ npx qfai report
   - Produces a human-readable report (`report.md` by default) or an internal JSON export (`report.json`) from `validate.json`; use `--base-url` to link file paths in Markdown to your repository viewer.
 - `npx qfai doctor`
   - Diagnoses configuration discovery, path resolution, glob scanning, and `validate.json` inputs before running validate/report; use `--fail-on` to enforce failures in CI.
+    Use `--profile prototyping` to add prototyping-specific preflight checks for the
+    primary spec, UI contracts, design contract readiness, active agent-wrapper
+    integrations, shipped role-input readiness, Playwright CLI launcher
+    resolution/probing, and target URL reachability.
     Note: prototyping evidence (`.qfai/evidence/prototyping.json`) is produced by the AI workflow / skills
     (`/qfai-prototyping` — any mode; modes differ only in `maxCycles`, see spec-0012), not by a general-purpose end-user CLI flow.
+    Use `npx qfai prototyping preflight --target-url <url>` for a focused
+    prototyping preflight before the skill starts; it now surfaces blocking
+    `QFAI-DCON-*` design-contract issues alongside runtime assumptions, resolves
+    a runnable Playwright CLI launcher (project wrapper / local bin / PATH /
+    `npx --no-install`), and still treats the first real delegation failure as a
+    runtime hard-stop.
     Use `npx qfai prototyping round-start --round <r5|r3|r2|r1> --candidates <csv> --target-url <url> --mode <mode>`
     to generate the round-scoped review bundle and command plans the AI evaluator sub-agent consumes, then use
     `round-harvest`, `round-narrow`, `round-absorb`, and `round-reimplement-verify` to advance the candidate funnel.
@@ -220,9 +229,9 @@ Notes.
 - `validate.json`, `report.json`, `doctor.json`, and `run-*` JSON logs are internal exports and are not a stable external contract; prefer `report.md` for integrations that must survive tool upgrades.
 - Scenario files are expected to use the Gherkin extension `*.feature` (not `*.md`).
 - `prototyping.calibration.packPath` points to the calibration pack SSOT; runtime and validator both resolve thresholds and iteration parameters from that pack.
-- `prototyping.calibration.thresholds`, `maxIterations`, `plateauDelta`, and `plateauLookback` are unsupported public config fields in v1.7.15.
+- `prototyping.calibration.thresholds`, `maxIterations`, `plateauDelta`, and `plateauLookback` are unsupported public config fields.
   Put calibration values in the referenced pack instead of `qfai.config.yaml`.
-- Observability modules (`src/core/observability/`) exist as foundation code but are **not integrated into blocking validation** in v1.7.14. They are reserved for future operational instrumentation.
+- Observability modules (`src/core/observability/`) exist as foundation code but are **not yet integrated into blocking validation**. They are reserved for future operational instrumentation.
 
 ## Specifications and contracts (SDD)
 
@@ -251,7 +260,7 @@ flowchart LR
 - Contracts SSOT: `.qfai/contracts/**`
 - Report outputs (`.qfai/report/**`) are derived artifacts and not SSOT.
 
-## Minimal tutorial (v1.7.7)
+## Minimal tutorial
 
 1. `npx qfai init`
 2. Run `/qfai-discussion` to structure scope, open questions, and produce a discussion pack under `.qfai/discussion/discussion-<ts>/`.
@@ -424,6 +433,9 @@ Integration wrappers are also generated for immediate use:
 
 `npx qfai init` installs canonical skills under `.qfai/assistant/skills/**` (SSOT)
 and generates thin wrapper assets for Agents/Codex VS Code / Copilot / Claude Code / Codex.
+Canonical agent markdown under `.qfai/assistant/agents/**` uses a shared YAML frontmatter
+subset (`name`, `description`, `tools`) compatible with Claude Code and GitHub Copilot,
+while Codex consumes mirrored `.codex/agents/*.toml` profiles.
 If wrapper assets drift from canonical skills, rerun `npx qfai init --force` to resync.
 
 ## Contributing (for QFAI maintainers)

package/assets/init/.qfai/assistant/agents/acceptance-test-engineer.md

@@ -1,3 +1,9 @@
+---
+name: acceptance-test-engineer
+description: "Implement E2E, API, and integration acceptance coverage with explicit traceability."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # Acceptance Test Engineer
 
 ## Mission

package/assets/init/.qfai/assistant/agents/architecture-reviewer.md

@@ -1,3 +1,9 @@
+---
+name: architecture-reviewer
+description: "Review architecture and contract decisions for consistency, safety, and rejected-option protection."
+tools: [Read, Glob, Grep, Bash]
+---
+
 # Architecture Reviewer
 
 ## Mission
@@ -22,8 +28,6 @@
 - .qfai/specs/spec-\*/09_delta.md
 - .github/instructions/code-review.instructions.md
 - .github/instructions/principles.instructions.md
-- .instruction/00_universal/development-principles-checklist.md
-- .instruction/01_specialties/design.md
 - Architecture decisions, diagrams, and `.qfai/contracts/**`
 
 ## Deliverables

package/assets/init/.qfai/assistant/agents/backend-engineer.md

@@ -1,3 +1,9 @@
+---
+name: backend-engineer
+description: "Implement backend behavior aligned with specs, API and DB contracts, and operational constraints."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # Backend Engineer
 
 ## Mission
@@ -21,9 +27,6 @@
 - .qfai/specs/spec-\*/09_delta.md
 - .qfai/specs/spec-\*/01_Spec.md
 - .github/instructions/principles.instructions.md
-- .instruction/00_universal/development-principles-checklist.md
-- .instruction/01_specialties/implementation.md
-- .instruction/01_specialties/design.md
 - .qfai/contracts/api/\*\*
 - .qfai/contracts/db/\*\*
 

package/assets/init/.qfai/assistant/agents/completion-reviewer.md

@@ -1,3 +1,9 @@
+---
+name: completion-reviewer
+description: "Independently audit completion contract, prompt DoD, and drift-protocol compliance."
+tools: [Read, Glob, Grep, Bash]
+---
+
 # Completion Reviewer
 
 ## Mission

package/assets/init/.qfai/assistant/agents/delivery-planner.md

@@ -1,3 +1,9 @@
+---
+name: delivery-planner
+description: "Create phased delivery plans, ownership splits, risk controls, and rerun policies."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # Delivery Planner
 
 ## Mission

package/assets/init/.qfai/assistant/agents/devops-ci-engineer.md

@@ -1,3 +1,9 @@
+---
+name: devops-ci-engineer
+description: "Run quality gates and capture reproducible CI and runtime evidence."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # DevOps CI Engineer
 
 ## Mission

package/assets/init/.qfai/assistant/agents/discovery-analyst.md

@@ -1,3 +1,9 @@
+---
+name: discovery-analyst
+description: "Gather pre-knowledge, ask focused questions, and facilitate decision-making."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # Discovery Analyst
 
 ## Mission

package/assets/init/.qfai/assistant/agents/doc-steward.md

@@ -1,3 +1,9 @@
+---
+name: doc-steward
+description: "Keep docs, changelog, and migration notes synchronized with implementation and workflow changes."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # Doc Steward
 
 ## Mission

package/assets/init/.qfai/assistant/agents/frontend-engineer.md

@@ -1,3 +1,9 @@
+---
+name: frontend-engineer
+description: "Implement frontend behavior aligned with the selected direction, finalized design system, screen contracts, and product experience decisions."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # Frontend Engineer
 
 ## Mission
@@ -20,9 +26,6 @@
 - .qfai/specs/spec-\*/09_delta.md
 - .qfai/specs/spec-\*/01_Spec.md
 - .github/instructions/principles.instructions.md
-- .instruction/00_universal/development-principles-checklist.md
-- .instruction/01_specialties/implementation.md
-- .instruction/01_specialties/design.md
 - .qfai/contracts/ui/\*\*
 - UI evidence artifacts when available
 

package/assets/init/.qfai/assistant/agents/implementation-reviewer.md

@@ -1,3 +1,9 @@
+---
+name: implementation-reviewer
+description: "Review code changes for correctness, maintainability, backend safety, and implementation risk."
+tools: [Read, Glob, Grep, Bash]
+---
+
 # Implementation Reviewer
 
 ## Mission
@@ -23,7 +29,6 @@
 - .qfai/specs/spec-\*/09_delta.md
 - .github/instructions/code-review.instructions.md
 - .github/instructions/principles.instructions.md
-- .instruction/00_universal/development-principles-checklist.md
 - Diff of changed files
 - `.qfai/contracts/api/**` and `.qfai/contracts/db/**`
 

package/assets/init/.qfai/assistant/agents/orchestrator.md

@@ -1,3 +1,9 @@
+---
+name: orchestrator
+description: "Plan, delegate, integrate, and enforce stage gates without self-authoring."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # Orchestrator
 
 ## Mission

package/assets/init/.qfai/assistant/agents/product-experience-architect.md

@@ -1,3 +1,9 @@
+---
+name: product-experience-architect
+description: "Own UX, visual design, navigation, screen transitions, and integrated experience direction."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # Product Experience Architect
 
 ## Mission
@@ -22,8 +28,6 @@
 - .qfai/specs/spec-\*/09_delta.md
 - .qfai/specs/spec-\*/01_Spec.md
 - .github/instructions/principles.instructions.md
-- .instruction/00_universal/development-principles-checklist.md
-- .instruction/01_specialties/design.md
 - Exploration brief, reference pool, evaluation rubric, evaluator calibration, selected direction, finalized design system,
   screen contracts, optional tokens, optional fallback HTML/CSS mock, and Mermaid flows
 - Runtime screenshots or rendered evidence when available

package/assets/init/.qfai/assistant/agents/product-surface-reviewer.md

@@ -1,3 +1,9 @@
+---
+name: product-surface-reviewer
+description: "Review UI implementation, usability, design coherence, and service-level product-surface quality."
+tools: [Read, Glob, Grep, Bash]
+---
+
 # Product Surface Reviewer
 
 ## Mission
@@ -11,6 +17,10 @@
 - Audit visual design, token alignment, and service-level UX coherence.
 - Reconcile sidecar artifacts (selected anchor, strategy, screen contracts), design tokens, mermaid flows, and rendered output consistency.
   HTML mock is optional fallback evidence only. Design tokens are supporting input.
+- For UI implementation, compare rendered output against `.qfai/contracts/design/prototype-handoff.yaml`, canonical prototype screenshots, HTML snapshots, and `.qfai/prototypes/winner/index.html`.
+- Reject prototype parity when implementation loses CTA hierarchy, spacing rhythm, information density,
+  surface framing intent, transition clarity, state coverage, or component character captured by the winning
+  prototype.
 - Review UI changes for KISS and YAGNI at the surface layer: avoid needless states, controls, flows, animations, and configuration that are not justified by the product goal.
 - Check naming, structure, and responsibility split of UI components for clarity, cohesion, and minimal surprise.
 - Validate docs/UX consistency so usage text, labels, error states, and user flows match the intended product behavior.
@@ -24,9 +34,8 @@
 - .qfai/specs/spec-\*/09_delta.md
 - .github/instructions/code-review.instructions.md
 - .github/instructions/principles.instructions.md
-- .instruction/00_universal/development-principles-checklist.md
-- .instruction/01_specialties/design.md
 - UI contract files under `.qfai/contracts/ui/`
+- Prototype handoff contract under `.qfai/contracts/design/prototype-handoff.yaml` when available
 - Runtime screenshots / HTML evidence / relevant diffs
 
 ## Deliverables

package/assets/init/.qfai/assistant/agents/qa-gatekeeper.md

@@ -1,3 +1,9 @@
+---
+name: qa-gatekeeper
+description: "Enforce validate, coverage, runtime-proof, and prototyping evidence gates before completion."
+tools: [Read, Glob, Grep, Bash]
+---
+
 # QA Gatekeeper
 
 ## Mission

package/assets/init/.qfai/assistant/agents/qa-strategist.md

@@ -1,3 +1,9 @@
+---
+name: qa-strategist
+description: "Own QA strategy, quality posture, traceability expectations, and failure-handling design."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # QA Strategist
 
 ## Mission

package/assets/init/.qfai/assistant/agents/requirements-analyst.md

@@ -1,3 +1,9 @@
+---
+name: requirements-analyst
+description: "Produce testable requirements, option sets, and explicit open-question ledgers."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # Requirements Analyst
 
 ## Mission

package/assets/init/.qfai/assistant/agents/requirements-reviewer.md

@@ -1,3 +1,9 @@
+---
+name: requirements-reviewer
+description: "Review requirements, options, and open-question handling for completeness, neutrality, and safe deferral."
+tools: [Read, Glob, Grep, Bash]
+---
+
 # Requirements Reviewer
 
 ## Mission

package/assets/init/.qfai/assistant/agents/solution-architect.md

@@ -1,3 +1,9 @@
+---
+name: solution-architect
+description: "Define architecture and contract decisions aligned with specs, constraints, and rejected-option history."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # Solution Architect
 
 ## Mission
@@ -23,8 +29,6 @@
 - .qfai/discussion/discussion-\*/04_Sources.md
 - .qfai/discussion/discussion-\*/06_REQ.md
 - .github/instructions/principles.instructions.md
-- .instruction/00_universal/development-principles-checklist.md
-- .instruction/01_specialties/design.md
 - Existing architecture docs and `.qfai/contracts/**`
 
 ## Deliverables

package/assets/init/.qfai/assistant/agents/test-design-analyst.md

@@ -1,3 +1,9 @@
+---
+name: test-design-analyst
+description: "Define test structure, coverage obligations, traceability, and test-scope boundaries."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # Test Design Analyst
 
 ## Mission

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

@@ -39,6 +39,19 @@ Rules:
 - Do not reintroduce options marked as rejected in `09_delta.md`.
 - If a rejected option must be reconsidered, create a `[RE-OPEN]` decision record that references the prior DR-ID, states what changed, and includes explicit approval.
 
+## Gate Failure Autorepair Protocol
+
+When validate, doctor, test, lint, typecheck, build, capture, or report gates fail:
+
+- inspect exit code, logs, `validate.json`, and cited files before reporting;
+- classify each finding as skill-owned artifact, upstream spec/contract, code/test defect, environment/tooling, or user decision;
+- fix skill-owned artifacts and code/test defects autonomously when the fix is local and non-destructive;
+- rerun the same failing gate after each fix batch;
+- do not weaken profiles, lower `--fail-on`, waive errors, invent evidence, or skip required reviewers;
+- stop only for destructive changes, ambiguous product/spec decisions, missing permissions/tools, or repeated no-progress failures.
+
+When stopping, report: cause, attempted fixes, remaining blocker, user action, and retry gate.
+
 ## Completion Contract (Shared)
 
 Before declaring completion, you MUST:

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

@@ -60,6 +60,8 @@ When unsure, read inputs in this order:
   - `.qfai/specs/<spec-id>/scenario.feature`
   - coverage ledger files
 
+Do not read discussion-pack UI/UX sidecars. UI-bearing acceptance tests consume only specs and contracts normalized by `/qfai-sdd`.
+
 ## Read Set Contract (Mandatory)
 
 - Default Mode:
@@ -162,6 +164,7 @@ Follow `.qfai/assistant/instructions/shared-skill-operating-baseline.md#delta-re
 ## 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.
 
 ## Goal
 

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

@@ -131,6 +131,7 @@ Follow `.qfai/assistant/instructions/shared-skill-operating-baseline.md#delta-re
 ## 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.
 
 ## Goal
 

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

@@ -64,17 +64,21 @@ UI-bearing packs must produce the following sidecars as primary truth:
 9. Generate `prototyping.yaml` only when the latest discussion pack is UI-bearing and an explicit prototyping recommendation is useful.
 10. Request review and record the Reviewer result.
 
+For UI-bearing targets, follow `references/design-dna-intake.md` while authoring the UI/UX sidecars. Keep this `SKILL.md` compact; put detailed interview prompts and examples in the reference file.
+
 ## UI-bearing Authoring Requirements
 
 - `30_exploration_brief.md` must define product intent, must-preserve interactions, brand signals, and differentiation targets.
-- `31_reference_pool.md` must define exploration references, adopted points, rejected points, and local translation.
+- `31_reference_pool.md` must define exploration references, adopted points, rejected points, local translation, copy risk, and template usage policy.
 - `32_design_anti_goals.md` must contain explicit anti-goals and recurrence prevention notes.
-- `33_exploration_rubric.md` must define design quality, originality, craft, and functionality grading criteria.
-- `34_evaluator_calibration.md` must include good critique examples, too-lenient examples, blandness-fail examples, and originality-fail examples.
+- `33_exploration_rubric.md` must define design quality, originality, craft, functionality, brand memorability, category distinctiveness, template dependency risk, and localization-fit grading criteria.
+- `34_evaluator_calibration.md` must include good critique examples, too-lenient examples, blandness-fail examples, originality-fail examples, and template-copy fail examples.
 - `50_review_input_bundle.md` must document best-of-history handling so later iterations are not automatically preferred.
 
 ## Completion Contract (Shared)
 
+Follow `.qfai/assistant/instructions/shared-skill-operating-baseline.md#gate-failure-autorepair-protocol` for validate, doctor, and quality-gate failures.
+
 Before declaring completion, you MUST:
 
 - verify all 15 mandatory output files exist and are populated;

package/assets/init/.qfai/assistant/skills/qfai-discussion/references/design-dna-intake.md

@@ -0,0 +1,28 @@
+# Design DNA Intake
+
+Use this reference only for UI-bearing discussion packs.
+
+## Interview Targets
+
+- Brand personality: list 3-5 traits the product should express.
+- Audience emotion: define what users should feel after the primary task.
+- Category conventions: name the expected layout and interaction patterns for this market.
+- Differentiation targets: state what must feel unlike generic SaaS, generic shadcn, or direct competitors.
+- Anti-template constraints: name default visual patterns that must not survive into prototyping.
+- Reference strategy: collect competitor, adjacent, aspirational, template-seed, and anti-pattern references.
+
+## Reference Rules
+
+- Treat templates as seeds, not winners.
+- Capture both adopted and rejected points for every reference.
+- Translate references into local product rules instead of copying visual surfaces.
+- Record copy risk as `low`, `medium`, or `high`.
+- Record template usage policy as `none`, `reference-only`, or `implementation-seed`.
+
+## Output Mapping
+
+- Put product intent and brand signals in `30_exploration_brief.md`.
+- Put all reference decisions in `31_reference_pool.md`.
+- Put prohibited visual directions in `32_design_anti_goals.md`.
+- Put brand and template-risk scoring in `33_exploration_rubric.md`.
+- Put examples of good critique and weak critique in `34_evaluator_calibration.md`.

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-discussion/templates/uiux/33_exploration_rubric.md

@@ -25,3 +25,22 @@
 ## Implementation Plausibility
 
 - What level of complexity is acceptable for the current slice:
+
+## Brand Memorability
+
+- What makes the screen recognizable after one use:
+- What makes it forgettable:
+
+## Category Distinctiveness
+
+- Which category conventions are intentionally kept:
+- Which category conventions are intentionally broken:
+
+## Template Dependency Risk
+
+- What indicates an unmodified shadcn/Tailwind/template surface:
+- What local translation is required before passing:
+
+## Localization Fit
+
+- How language length, density, and domain terms affect the design:

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/34_evaluator_calibration.md

@@ -15,3 +15,7 @@
 ## Originality Fail
 
 - Example of a design that copies defaults without deliberate product-specific choices:
+
+## Template Copy Fail
+
+- Example of a shadcn/Tailwind/template-derived design that keeps default tokens, rhythm, or component composition without local translation:

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

@@ -78,11 +78,14 @@ Execute the TDD micro-cycle for each pending item in `test-list.md`, transitioni
 - 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` →
   `.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/reference-pool.yaml` → `.qfai/contracts/design/brand-design.yaml` →
   `.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/selected-direction.yaml` → `.qfai/contracts/design/design-system.yaml` →
+  `.qfai/contracts/design/prototype-handoff.yaml` → `.qfai/contracts/ui/*.yaml` →
+  canonical prototype screenshots / HTML snapshots → `.qfai/prototypes/winner/index.html`.
+- Do not read discussion-pack UI/UX sidecars, fallback mocks, or legacy design aliases.
+- Prototype code is analysis input, not production source. Reimplement with project-native patterns while preserving `prototype-handoff.yaml` `mustPreserve`; adapt `mayAdapt`; do not copy `mustNotCopy`.
+- 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
@@ -253,8 +256,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 +270,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
 
@@ -317,6 +322,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