qfai 1.8.0 → 1.8.1

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

@@ -54,6 +54,7 @@ When unsure, read inputs in this order:
   - `.qfai/specs/<spec-id>/05_Examples.md` (EX)
   - `.qfai/specs/<spec-id>/06_Test-Cases.md` (TC)
   - `.qfai/contracts/api/**` (CON-API)
+  - `.qfai/contracts/ui/**` and `.qfai/contracts/design/**` when the target spec is UI-bearing
 - P5: `.qfai/specs/<spec-id>/09_delta.md` (Decision Records; if no spec yet, state "not applicable")
 - P6: legacy artifacts (optional only)
   - `.qfai/specs/<spec-id>/scenario.feature`

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

@@ -75,11 +75,10 @@ Execute the TDD micro-cycle for each pending item in `test-list.md`, transitioni
 ## Visual Review Guard
 
 - Review rendered output, screenshot evidence, or HTML output before closing any UI-affecting item.
-- Read the sidecar family first (selected anchor, strategy, screen contracts) whenever implementation touches UI or critique-driven behavior.
-- Read order: option comparison (30_option_comparison.md) → selected anchor screen (31_selected_anchor_screen.md) →
-  strategy (10_implementation_strategy.md) → taste interview (11_design_taste_interview.md) →
-  trend scan (04_Sources.md#Trend Scan) → 3-layer evaluation family (20/21/22/23 + optional 24) →
-  screen contracts (40_screen_contracts.md) → review input bundle (50_review_input_bundle.md) →
+- 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/anchor-selection.yaml` → `.qfai/contracts/design/evaluation-axes.yaml` →
+  `.qfai/contracts/design/design-system.yaml` → `.qfai/contracts/ui/*.yaml` →
   optional design tokens → optional fallback mock → mermaid flows.
 - If code intent and rendered output diverge, treat the rendered/HTML result as the blocking review input and reconcile before DONE.
 

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

@@ -1,7 +1,7 @@
 ---
 name: qfai-prototyping
-title: QFAI Prototyping (Full-Harness Only)
-description: "Build a contract-aligned UI prototype and block completion until full-harness evidence and validate gate pass."
+title: QFAI Prototyping (Skill-Orchestrated)
+description: "Build a contract-aligned UI prototype, run agent-led visual evaluation, and gate completion through validate/verify."
 argument-hint: "[--auto]"
 allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
 roles:
@@ -24,173 +24,215 @@ mode: execution-focused
 
 [DRIFT-PROTOCOL:MANDATORY]
 
-This skill is static-first for planning and file review, but the package execution contract is `full-harness` only.
-Do not default or downgrade prototyping modes.
+This skill owns prototyping orchestration directly.
+Do not rely on a CLI entrypoint or package runtime loop.
 
 ## CRITICAL CONSTRAINTS (Read First)
 
 - Scope is all specs from `.qfai/specs/spec-*`.
-- Evidence is mandatory in markdown + json under `.qfai/evidence/`.
-- DONE is forbidden until prototyping evidence, reviewer gate, and `qfai validate --fail-on error` pass.
-- Supported prototyping surfaces are `web`, `mobile`, `desktop`, and `mixed`.
+- Screenshot evidence and HTML snapshot evidence are mandatory.
+- Screenshot evidence path: `.qfai/evidence/prototyping/screenshots/<screen-id>.png`
+- HTML snapshot path: `.qfai/evidence/prototyping/html/<screen-id>.html`
+- If either screenshot or HTML is missing for a declared screen, that screen scores `0` and the run is incomplete.
+- Optional evidence is abolished. Missing mandatory evidence must trigger rerun, not waiver.
+- DONE is forbidden until `qfai validate --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.
-- Canonical screen contracts in `discussion-*/uiux/40_screen_contracts.md` are mandatory.
-- Browser QA, render evidence, runtimeGate, uiFidelity, specCoverage, and `fullHarness` are mandatory.
-- `uiFidelity` is screen-level and must be built from real render/browser evidence.
-- `mockPaths` is a negative-only issue ledger with `fail|finding` only.
-- Calibration pack is the SSOT. Runtime and validator both resolve from `calibrationRef.packPath`.
-- `--reviewer <id>` is mandatory and placeholder reviewer ids are rejected.
-- L1 and L2 findings must be fixed or dispositioned before PASS.
+- `cli` is not supported and is not an execution target for prototyping.
+- Canonical screen contracts in `.qfai/contracts/ui/*.yaml` are mandatory.
+- Evaluation is performed by sub-agents; machine checks are limited to schema/evidence validation.
+- Evaluation reviewer findings must be fixed or explicitly dispositioned before PASS.
+- Shared evidence vocabulary includes `render.json` and `browser-qa.json` alongside screenshot and HTML evidence.
 
 ## Goal
 
-Build the minimum runnable slice for all specs and produce canonical `full-harness` evidence under `.qfai/evidence/`.
+Build the minimum runnable slice for all specs and produce reviewable screenshot/HTML evidence for every declared screen.
 
-## Mode
+## Surface / Mode
 
-### Full-harness
+- surface / mode routing uses `standard` as the default execution path.
+- `standard` is the default when no explicit escalation to `full-harness` is requested.
+- `full-harness` is reserved for explicit escalation and review-heavy obligations.
 
-- Full-harness is the package default when prototyping execution is valid.
-- Each `qfai prototyping run --mode full-harness --reviewer <id>` invocation records exactly one measured iteration.
-- Multiple iterations are formed only by real code changes between runs.
-- The runtime does not self-modify code and does not fabricate evidence.
+## Required References
 
-## Obligation matrix
-
-| surface / mode         | specs    | runtimeGate | uiFidelity | render evidence | browser QA | fullHarness |
-| ---------------------- | -------- | ----------- | ---------- | --------------- | ---------- | ----------- |
-| web / full-harness     | required | required    | required   | required        | required   | required    |
-| mobile / full-harness  | required | required    | required   | required        | required   | required    |
-| desktop / full-harness | required | required    | required   | required        | required   | required    |
-| mixed / full-harness   | required | required    | required   | required        | required   | required    |
-
-## Required evidence
-
-## Evidence (MANDATORY)
-
-- `.qfai/evidence/prototyping.md`
-- `.qfai/evidence/prototyping.json`
-- `.qfai/evidence/render.json`
-- `.qfai/evidence/browser-qa.json`
-- `.qfai/evidence/fullHarness.exit.json`
-- `.qfai/evidence/fullHarness.handoff.json`
-- `.qfai/evidence/fullHarness.fakeUiDetection.json`
+Read and follow these references before execution:
 
-## Truthfulness rules
-
-- `mode.effective` must be `full-harness`.
-- `runtimeGate` is observed-only. Synthetic status codes are invalid.
-- `runtimeGate.evidenceRefs` must contain concrete render/browser QA/spec refs only.
-- `specCoverage` must use concrete declared refs and concrete observed refs only.
-- Browser QA evidence must be preserved per screen.
-- `actionsWired` must reflect actionable control coverage, not finding counts.
-- `reviewerSignoff.status` represents final decision, not mere completion.
-- `reviewerLogs[].verdict` must align with decision/termination semantics.
-
-## Review semantics
-
-- `accepted` -> `approved`
-- `rejected` -> `rejected`
-- `abandoned` -> `abandoned`
-- Plateau stop or max-iterations stop must not produce `approved`.
+- `.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/assistant/skills/qfai-prototyping/references/design-system-compliance.md`
+- `.qfai/assistant/skills/qfai-prototyping/references/reviewer-gate.md`
 
 ## Delegation Scope Table
 
 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        |
 | Screenshot capture | devops-ci-engineer                                     |
-| Evaluation L1-L2   | product-surface-reviewer, product-experience-architect |
+| Evaluation review  | product-surface-reviewer, product-experience-architect |
 | Build              | devops-ci-engineer, backend-engineer                   |
 
-Any delegation map entry that assigns a category to an undefined or unlisted role (e.g., `"generic-code-writer"`) MUST produce a violation finding naming the undefined role and the category.
+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
 
-## Required process
+### Step 0 — Execution Plan
 
-### Step 0 — Execution Plan (executionPlan)
+Before any code is written, create an execution plan record in the work evidence.
 
-Before any code is written, create an `executionPlan` record with the following fields:
+Required fields:
 
-- `targetIterations`: integer; minimum 2 for full-harness
-- `evaluationAxesSource`: reference to the discussion pack evaluation-family files (20/21/22/23)
-- `delegationMap`: category-to-role assignments per Delegation Scope Table above
+- `targetIterations`: integer; minimum 2
+- `evaluationAxesSource`: ref to `.qfai/contracts/design/evaluation-axes.yaml`
+- `delegationMap`: category-to-role assignments per Delegation Scope Table
 - `plannedAt`: ISO-8601 timestamp
 
-The executionPlan MUST be present in `prototyping.json` when `mode=full-harness`. A validator MUST reject any full-harness record without an executionPlan.
+### Step 1 — Read Inputs
 
-### Iteration Gate
+Read the downstream-ready spec/contract inputs and verify:
 
-- full-harness convergence requires a minimum of 2 iterations.
-- A single-iteration run that reports `converged=true` is invalid; the iteration gate MUST raise an error with message "minimum 2 iterations required before convergence".
-- The phase transition from iteration N to N+1 is blocked until `terminationCondition` is met or the gate explicitly authorizes continuation.
+- `.qfai/specs/<spec-id>/01_Spec.md`
+- `.qfai/specs/<spec-id>/03_Acceptance-Criteria.md`
+- `.qfai/contracts/design/evaluation-axes.yaml`
+- `.qfai/contracts/design/anchor-selection.yaml`
+- `.qfai/contracts/design/design-system.yaml` when required by the spec
+- `.qfai/contracts/ui/*.yaml`
 
-### 5-Step Iteration Cycle
+Read order:
 
-Each full-harness iteration follows this fixed sequence:
+1. `.qfai/specs/<spec-id>/01_Spec.md`
+2. `.qfai/specs/<spec-id>/03_Acceptance-Criteria.md`
+3. `.qfai/contracts/design/anchor-selection.yaml`
+4. `.qfai/contracts/design/evaluation-axes.yaml`
+5. `.qfai/contracts/design/design-system.yaml`
+6. `.qfai/contracts/ui/*.yaml`
 
-1. **Capture** — Run `packages/qfai/assets/scripts/capture-screenshots.js --url <url> --out <dir>` and record screenshot paths with timestamps under `scoringTrace[i].screenshotDir`.
-2. **Evaluate** — Launch L1 and L2 evaluator sub-agents with full context bundle: (a) screenshots from Step 1, (b) axisDefs from evaluation-family 20/21/22/23, (c) previousScore from prior iteration, (d) designSystemChecklist from `uiux/12_design_system.md`.
-3. **Identify** — Aggregate L1 + L2 findings; flag immediate-fix items.
-4. **Fix** — Apply fixes per finding disposition; do not close items without evidence.
-5. **Re-evaluate** — Re-run Steps 1–4; compare new score to prior score to check plateau.
+### Step 2 — Verify Execution Preconditions
 
-The sequence MUST NOT be permuted. Parallel execution of Capture+Evaluate is prohibited.
+Confirm all of the following before any evaluation:
 
-### Evaluator Input — 4 Required Elements
+- classification is UI-bearing
+- surface is `web`, `mobile`, `desktop`, or `mixed`
+- every declared screen has a stable `screen-id`
+- the design evaluation contract satisfies the required schema
+- the design system checklist is available when required
 
-When launching any L1 or L2 evaluator sub-agent, all 4 elements MUST be present in the input:
+### Step 3 — Implement the Minimum Runnable Slice
 
-(a) screenshots — paths produced by capture-screenshots.js for the current iteration
-(b) axisDefs — scoring axes from discussion-pack evaluation-family (20/21/22/23)
-(c) previousScore — aggregate score from the prior iteration (null for iteration 1)
-(d) designSystemChecklist — the compliance checklist derived from `uiux/12_design_system.md`
+Implement the smallest UI slice that covers all declared screens and primary interactions.
 
-If any element is missing, a reviewer check MUST raise a finding naming the missing element.
-Missing element (d) is a common error when `uiux/12_design_system.md` is absent; the reviewer MUST still flag it.
+### Step 4 — Capture Mandatory Evidence
 
-### Visual Quality Structural Checklist
+For every declared screen:
 
-Each iteration evaluation MUST score all 6 visual categories:
+- capture one screenshot and store it at the canonical screenshot path
+- capture one HTML snapshot and store it at the canonical HTML path
+- record missing evidence immediately; do not continue as if capture succeeded
+
+### Step 5 — Launch Evaluation Reviewers
+
+Launch evaluation reviewer sub-agents with the full context bundle:
+
+- screenshots from Step 4
+- HTML snapshots from Step 4
+- `axisDefs` from `.qfai/contracts/design/evaluation-axes.yaml`
+- `previousScore` from the prior iteration (`null` for iteration 1)
+- `designSystemChecklist` from `.qfai/contracts/design/design-system.yaml`
+
+If any required input is missing, stop the evaluation and classify the screen as `0` points with rerun required.
+
+### Step 6 — Aggregate Findings
+
+Aggregate reviewer findings and classify them as:
+
+- blocking
+- immediate-fix
+- revise
+- manual-review
+
+### Step 7 — Fix and Re-capture
 
-1. Color — color palette adherence to design system tokens
-2. Typography — type scale, weight, line-height compliance
-3. Spacing — spacing scale and grid alignment
-4. Border radius — border-radius consistency across components
-5. Shadow — shadow elevation and opacity standards
-6. Do's&Don'ts — adherence to explicit do/don't rules from `uiux/12_design_system.md`
+Apply fixes per finding disposition, then re-capture screenshot and HTML evidence for every changed screen.
+Do not close a finding without fresh evidence.
 
-### Lighthouse Gate (MUST for web full-harness)
+### Step 8 — Re-evaluate
 
-When `surface=web` and `mode=full-harness`, a Lighthouse performance/accessibility report MUST be captured and attached to the evidence. The reviewer gate MUST raise an error "Lighthouse Gate is MUST for full-harness + web surface" when the report is absent.
+Repeat Steps 4–7 until:
 
-### Steps (continued)
+- at least 2 iterations have completed
+- all declared screens have screenshot + HTML evidence
+- blocking findings are closed or dispositioned
+- validate can pass on required schema/evidence gates
 
-1. Read the latest discussion pack and verify `prototyping.yaml`, `04_Sources.md`, `20/21/22/23`, and `40_screen_contracts.md`.
-   Read order: option comparison / `30_option_comparison.md` -> selected anchor screen / `31_selected_anchor_screen.md` -> strategy / `10_implementation_strategy.md` -> taste interview / `11_design_taste_interview.md` -> trend scan / `04_Sources.md` -> 3-layer evaluation family (`20/21/22/23`) -> screen contracts / `40_screen_contracts.md`.
-2. Verify the classification is UI-bearing and the surface is `web`, `mobile`, `desktop`, or `mixed`.
-3. Create the executionPlan (Step 0 above).
-4. Implement the minimum runnable slice for all specs.
-5. Run `qfai prototyping run --mode full-harness --reviewer <id>` — this executes the 5-Step Iteration Cycle per iteration.
-6. Review render evidence, HTML snapshots, Browser QA, runtimeGate, uiFidelity, and specCoverage for every declared screen.
-7. Fix findings and rerun until the evidence is coherent.
-8. Run `qfai validate --fail-on error`.
-9. Route an independent reviewer and do not declare completion until the result is `PASS`.
+## Iteration Gate
 
-## Reviewer gate
+- minimum 2 iterations are required before phase transition to validation or review.
+- if the iteration gate is not satisfied, phase transition is blocked.
+- terminationCondition cannot bypass the minimum 2 iterations rule.
+
+## Full-harness
+
+- `full-harness` applies only after explicit escalation from the default `standard` path.
+- `full-harness` carries review-heavy obligations and stricter evidence checks.
+
+## Obligation matrix
+
+| surface / mode          | obligation profile                  |
+| ----------------------- | ----------------------------------- |
+| web / default route     | static-first obligations (standard) |
+| web / full-harness      | review-heavy obligations            |
+| mobile / default route  | static-first obligations (standard) |
+| desktop / default route | static-first obligations (standard) |
+| mixed / full-harness    | review-heavy obligations            |
+
+### Step 9 — Validate and Verify
+
+- Run `qfai validate --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`.
+
+## Evaluator Inputs (Mandatory)
+
+When launching any evaluation reviewer sub-agent, all 5 elements MUST be present:
+
+1. screenshots
+2. HTML snapshots
+3. axisDefs
+4. previousScore
+5. designSystemChecklist
+
+## Visual Quality Structural Checklist
+
+Each iteration evaluation MUST score all 6 visual categories:
+
+1. Color
+2. Typography
+3. Spacing
+4. Border radius
+5. Shadow
+6. Do's&Don'ts
 
 ### Reviewer Gate (MUST)
 
-- Reviewer must verify full-harness evidence completeness.
-- Reviewer response must include `Result: PASS | REVISE` (matching shared-skill-delegation-baseline.md#reviewer-response-template).
-- Reviewer must verify calibration pack usage via `calibrationRef`.
-- Reviewer must reject self-reference, synthetic refs, and `mockPaths.status="pass"`.
-- Reviewer must verify `reviewerSignoff`, `reviewerLogs`, `terminationReason`, and `finalDecision` are semantically aligned.
-- Reviewer must verify Drift Protocol compliance and alignment with `test-layers.md`.
-- Review volume guidance remains signals, not gates.
-- Reviewer returns PASS or REVISE only.
+Reviewer checks are defined in:
+
+- `.qfai/assistant/skills/qfai-prototyping/references/reviewer-gate.md`
+
+Minimum reviewer responsibilities:
+
+- verify mandatory screenshot/HTML evidence exists for every declared screen
+- verify 3-layer evaluation references were used
+- verify missing evidence caused rerun rather than waiver
+- verify `qfai validate --fail-on error` completed successfully
+- verify Drift Protocol compliance and alignment with `.qfai/assistant/steering/test-layers.md`
+- treat score/volume heuristics as signals, not gates
+- return `Result: PASS | REVISE`
 
 ## Sub-agent Delegation (MANDATORY)
 
@@ -198,9 +240,9 @@ Follow `.qfai/assistant/instructions/shared-skill-delegation-baseline.md`.
 
 ### Orchestrator Protocol (MUST)
 
-- Additional prototyping-specific overrides:
-- do not self-approve;
-- keep evidence paths canonical and integrate delegated results only.
+- do not self-approve
+- keep evidence paths canonical
+- integrate delegated results only
 
 ### Capability Probe (MUST)
 
@@ -221,19 +263,17 @@ Follow `.qfai/assistant/instructions/shared-skill-operating-baseline.md#completi
 
 Prototyping-specific additions:
 
-- all specs are covered;
-- full-harness evidence is complete and truthful;
-- `qfai validate --fail-on error` passes;
-- reviewer returns `PASS`.
+- all specs are covered
+- all declared screens have screenshot + HTML evidence
+- `qfai validate --fail-on error` passes
+- reviewer returns `PASS`
 
 ## FINAL CHECKLIST (Check Last)
 
-### Completion Checklist (MUST)
-
 - All specs are covered in the Coverage Matrix.
-- Required full-harness evidence is present.
-- 404 findings are resolved or the run is not complete.
-- uiFidelity is present when required.
+- Every declared screen has screenshot evidence.
+- Every declared screen has HTML evidence.
+- Missing evidence triggered rerun instead of waiver.
 - Reviewer returned PASS; otherwise status is REVISE.
 
 ## Completion Message & Next Actions (MUST)
@@ -242,4 +282,4 @@ Action:
 
 - Proceed: `/qfai-atdd`
 - Quality gate: `/qfai-verify`
-- Rework prototyping: rerun `/qfai-prototyping` with corrected evidence
+- Rework prototyping: rerun `/qfai-prototyping` with corrected screenshot/HTML evidence

package/assets/init/.qfai/assistant/skills/qfai-prototyping/references/design-system-compliance.md

@@ -0,0 +1,22 @@
+# Design System Compliance
+
+When `.qfai/contracts/design/design-system.yaml` exists and is required, evaluators must compare the implementation against:
+
+- color palette
+- typography scale and weights
+- spacing scale
+- border radius
+- shadow usage
+- explicit do/don't rules
+
+## Rule
+
+If the implementation clearly contradicts the design system on a primary screen, record an immediate-fix finding.
+
+## Evidence
+
+Support each finding with:
+
+- screenshot evidence
+- HTML snapshot evidence
+- the specific design-system clause or checklist item

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

@@ -0,0 +1,31 @@
+# Evidence Requirements
+
+## Mandatory evidence
+
+For every declared screen in `.qfai/contracts/ui/*.yaml`, collect both:
+
+- screenshot: `.qfai/evidence/prototyping/screenshots/<screen-id>.png`
+- HTML snapshot: `.qfai/evidence/prototyping/html/<screen-id>.html`
+
+If either artifact is missing:
+
+- the screen is scored `0`
+- the run is incomplete
+- rerun is mandatory
+
+Optional evidence is not allowed.
+
+## Capture rules
+
+- Use stable `screen-id` names from the canonical UI contracts.
+- Overwrite stale evidence with fresh evidence from the current iteration.
+- Do not reuse an older screenshot or HTML snapshot after a fix.
+- If capture fails, record the failure in work evidence and stop pretending the screen was evaluated.
+
+## Validate gate expectations
+
+`qfai validate --fail-on error` must be able to confirm:
+
+- every declared screen has a screenshot file
+- every declared screen has an HTML snapshot file
+- the file paths follow the canonical directories above

package/assets/init/.qfai/assistant/skills/qfai-prototyping/references/iteration-cycle.md

@@ -0,0 +1,25 @@
+# Iteration Cycle
+
+Each iteration follows this order:
+
+1. Capture screenshot and HTML for every declared screen.
+2. Launch L1 and L2 evaluator sub-agents with the required inputs.
+3. Aggregate findings and classify them by severity and disposition.
+4. Fix the UI according to findings.
+5. Re-capture screenshot and HTML evidence for every changed screen.
+6. Re-run the evaluators.
+
+## Minimum iteration count
+
+- Completion requires at least 2 iterations.
+- A single successful-looking pass is not enough.
+- If evidence is missing in any iteration, that iteration does not count as complete.
+
+## Stop conditions
+
+You may stop only when all of the following are true:
+
+- all declared screens have screenshot + HTML evidence
+- blocking findings are closed or dispositioned
+- validate passes with `--fail-on error`
+- independent reviewer returns `PASS`

package/assets/init/.qfai/assistant/skills/qfai-prototyping/references/l1-review-guide.md

@@ -0,0 +1,36 @@
+# L1 Review Guide
+
+L1 checks implementation fidelity.
+
+## Inputs
+
+- screenshots
+- HTML snapshots
+- canonical UI contracts from `.qfai/contracts/ui/*.yaml`
+- latest code state
+
+## Required checks
+
+For each declared screen:
+
+- the screen is reachable/rendered
+- screenshot exists
+- HTML snapshot exists
+- required elements are visibly present
+- required actions are wired or explicitly marked missing
+- blocking UI failures are identified
+
+## Failure handling
+
+- Missing screenshot or HTML => score `0`, rerun required
+- Missing primary action wiring => blocking finding
+- Severe route/render failure => blocking finding
+
+## Output
+
+Return:
+
+- per-screen findings
+- blocking/immediate-fix classification
+- a numeric score per axis in the range `0.0..1.0`
+- rationale tied to screenshot/HTML evidence

package/assets/init/.qfai/assistant/skills/qfai-prototyping/references/l2-review-guide.md

@@ -0,0 +1,39 @@
+# L2 Review Guide
+
+L2 checks product experience and design alignment.
+
+## Inputs
+
+- screenshots
+- HTML snapshots
+- `.qfai/contracts/design/evaluation-axes.yaml`
+- `.qfai/contracts/design/anchor-selection.yaml`
+- `.qfai/contracts/design/design-system.yaml`
+- previous iteration score
+
+## 3-layer evaluation family
+
+L2 must explicitly use all of:
+
+- invariant axes
+- trend-derived axes
+- product-specific axes
+- aggregate rules
+
+## Required checks
+
+- visual hierarchy aligns with invariant axes
+- trend-based styling aligns with trend-derived axes
+- product-specific differentiation is visible
+- selected anchor direction is reflected in the current UI
+- design system checklist is respected
+- experience findings are recorded separately from blocking L1 findings
+
+## Output
+
+Return:
+
+- per-axis findings
+- revise/manual-review classification
+- a numeric score per axis in the range `0.0..1.0`
+- rationale tied to screenshot/HTML evidence and axis refs

package/assets/init/.qfai/assistant/skills/qfai-prototyping/references/reviewer-gate.md

@@ -0,0 +1,24 @@
+# Reviewer Gate
+
+The reviewer is an independent gate, not the implementation author.
+
+## Reviewer must verify
+
+- all declared screens have screenshot evidence
+- all declared screens have HTML snapshot evidence
+- L1 and L2 evaluators used the required inputs
+- the 3-layer evaluation family was referenced
+- missing evidence triggered rerun rather than waiver
+- `qfai validate --fail-on error` passed
+
+## Reviewer output
+
+```text
+Result: PASS | REVISE
+Findings:
+- ...
+Required fixes:
+- ...
+Evidence checked:
+- ...
+```

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

@@ -190,9 +190,10 @@ Follow `.qfai/assistant/instructions/shared-skill-operating-baseline.md#delta-re
 - Use only skill-local templates under `.qfai/assistant/skills/qfai-sdd/templates/`, including `templates/contracts`, `templates/report`, and `templates/specs`.
 - Always write `.qfai/report/preflight_summary.md` before generating shared/spec artifacts.
 - Contracts are contract-first mandatory outputs in this skill.
+- UI-bearing targets must be normalized into downstream-ready contracts under `.qfai/contracts/design/**` and `.qfai/contracts/ui/**`.
 - `_policies/05_Contracts.md` must include a Contract Index.
 - `/qfai-sdd` must stop when discussion-pack is missing, incomplete, or has blocking OQ.
-- Discussion-pack preflight is mandatory, including classification-aware `prototyping.yaml` validation.
+- Discussion-pack preflight is mandatory, including contract-first checks that UI-bearing targets are normalized into required design/ui contracts before downstream generation.
 - Reviewer routing is fixed by `.qfai/assistant/steering/agent-routing.yml` and `.qfai/assistant/steering/review-profiles.yml`.
 - RCP wording must be sourced from `.qfai/assistant/skills/qfai-sdd/references/rcp_footer.md`.
 - `_policies/04_Business-Flow.md` must be Markdown and include Mermaid `flowchart` or `sequenceDiagram`.
@@ -221,6 +222,11 @@ Create or update layered SDD artifacts in one run so downstream execution phases
 - Shared `_policies/01..11` layered files
 - Target `spec-XXXX/01..10` layered files
 - Updated contracts under `.qfai/contracts/**`
+- UI-bearing normalized contracts:
+  - `.qfai/contracts/design/design-system.yaml`
+  - `.qfai/contracts/design/evaluation-axes.yaml`
+  - `.qfai/contracts/design/anchor-selection.yaml`
+  - `.qfai/contracts/ui/*.yaml`
 - `.qfai/report/preflight_summary.md`
 - Evidence file: `.qfai/evidence/sdd-spec-XXXX.md`
 
@@ -232,14 +238,15 @@ The canonical file set is defined by skill templates under `.qfai/assistant/skil
 2. Analyze repository context, existing artifacts, constraints, and open decisions.
 3. Write `.qfai/report/preflight_summary.md`.
 4. Execute Phase 0 (Contracts-first).
-5. Execute Phase 1 (Outline).
-6. Ensure `_policies/11_Slice-Policy.md` exists and matches the current slicing model.
-7. Execute Phase 2 (Slice) and pass slice gate for each target spec.
-8. Execute Phase 3 (Plan finalize) after at least one slice gate passes.
-9. Execute Phase 4 (Delta update).
-10. Run `qfai validate --fail-on error --format github | tee .qfai/report/validate.log`.
-11. Review `.qfai/report/specs-coverage/spec-*.md` and triage density-smell warnings.
-12. If validate fails, fix source-layer artifacts and repeat until `error=0`.
+5. For UI-bearing targets, normalize discussion UIUX artifacts into design/ui contracts for downstream execution.
+6. Execute Phase 1 (Outline).
+7. Ensure `_policies/11_Slice-Policy.md` exists and matches the current slicing model.
+8. Execute Phase 2 (Slice) and pass slice gate for each target spec.
+9. Execute Phase 3 (Plan finalize) after at least one slice gate passes.
+10. Execute Phase 4 (Delta update).
+11. Run `qfai validate --fail-on error --format github | tee .qfai/report/validate.log`.
+12. Review `.qfai/report/specs-coverage/spec-*.md` and triage density-smell warnings.
+13. If validate fails, fix source-layer artifacts and repeat until `error=0`.
 
 Use: