qfai 1.8.0 → 1.8.2

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,13 @@ 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/exploration-brief.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`
 - `.qfai/report/preflight_summary.md`
 - Evidence file: `.qfai/evidence/sdd-spec-XXXX.md`
 
@@ -232,14 +240,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:
 

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/contracts/design-system.sample.yaml

@@ -0,0 +1,22 @@
+# Downstream design-system contract generated by /qfai-sdd
+visual_theme:
+  name: Editorial Clarity
+  rationale: Emphasize calm, data-dense hierarchy with restrained accents.
+checklist:
+  color:
+    - use semantic primary accent only for key actions
+  typography:
+    - keep page title and body scale distinct by at least one step
+  spacing:
+    - use a consistent vertical rhythm
+  border_radius:
+    - keep card and button radius aligned
+  shadow:
+    - reserve strong shadow for overlays only
+  dos_and_donts:
+    - do: maintain clear hierarchy on the primary screen
+    - dont: mix multiple accent palettes on one screen
+  component_tone:
+    - keep components visibly related to the chosen direction
+  motion_rules:
+    - use motion to clarify hierarchy and state change

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/contracts/evaluation-rubric.sample.yaml

@@ -0,0 +1,16 @@
+# Downstream evaluation rubric generated by /qfai-sdd
+axes:
+  - id: design-quality
+    weight: 3
+  - id: originality
+    weight: 3
+  - id: craft
+    weight: 1
+  - id: functionality
+    weight: 1
+hard_floors:
+  - functionality
+  - accessibility-risk
+weighted_axes:
+  - design-quality
+  - originality

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/contracts/evaluator-calibration.sample.yaml

@@ -0,0 +1,9 @@
+# Downstream evaluator calibration generated by /qfai-sdd
+good_critique_examples:
+  - Skeptical, specific, and actionable feedback
+too_lenient_examples:
+  - Praise that ignores blandness
+blandness_fail_examples:
+  - Technically correct but generic
+originality_fail_examples:
+  - Library defaults with no product-specific decisions

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/contracts/exploration-brief.sample.yaml

@@ -0,0 +1,10 @@
+# Downstream exploration brief generated by /qfai-sdd
+product_intent: Create a deliberate, non-generic product surface.
+target_users:
+  - Primary end users
+must_preserve_interactions:
+  - Primary task remains obvious
+brand_signals:
+  - Confident
+differentiation_targets:
+  - Avoid generic dashboard defaults

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/contracts/selected-direction.sample.yaml

@@ -0,0 +1,7 @@
+# Downstream selected direction generated by /qfai-prototyping
+chosen_direction_id: DIR-001
+winning_rationale: Strongest balance of originality and clarity.
+carry_forward_rules:
+  - Preserve hierarchy strategy
+rejected_summary:
+  - DIR-002: too generic

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

@@ -96,8 +96,10 @@ Use the shared schema.
 - Reviewer checks:
   - required roles were delegated;
   - validate evidence exists: `qfai validate --fail-on error` completed with `error=0`;
+  - declared screens have mandatory screenshot and HTML evidence under `.qfai/evidence/prototyping/`;
   - Drift Protocol enforced;
   - test-layer policy enforced against `test-layers.md`.
+  - gate counts and ratios are signals, not gates.
 - Route specialist reviewers from `.qfai/assistant/steering/agent-routing.yml`.
 - Default verify review set:
   - `qa-gatekeeper`
@@ -147,6 +149,7 @@ Run quality gates and produce evidence that the change is correct and safe.
 
 - Repo quality gates PASS (format/lint/type/test/build/etc).
 - QFAI checks PASS (at minimum: `qfai validate`, and optionally `qfai report`).
+- Declared screens have mandatory screenshot and HTML evidence.
 - A concise evidence summary exists (copy‑paste for PR).
 - The PR-ready summary includes **Change Classification (Primary/Tags)** per `.qfai/assistant/instructions/change-classification.md`.
 - Evidence file exists: `.qfai/evidence/verify-<spec-id>.md`.

package/assets/init/.qfai/assistant/steering/agent-catalog.yml

@@ -65,7 +65,7 @@ agents:
   - id: frontend-engineer
     kind: worker
     domain: frontend
-    mission: Implement frontend behavior aligned with selected anchor, strategy, screen contracts, and product-surface decisions.
+    mission: Implement frontend behavior aligned with selected direction, finalized design system, screen contracts, and product-surface decisions.
     owned_artifacts: [ui-implementation, surface-evidence]
     tool_profile: frontend
     permission_profile: authoring

package/assets/init/.qfai/assistant/steering/ui-definition-protocol.md

@@ -8,11 +8,11 @@ spec-0013 (CAP-0013) で定義された、下流 skill（prototyping / ATDD / TD
 **Primary truth** は step 1 の discussion sidecar artifacts にある。step 2 以降は **存在する場合のみ読む supporting input / fallback** であり、init 直後に未作成でも正常である。
 
 1. **Discussion-side UI/UX Sidecar Artifacts** (`discussion-*/uiux/`) — **primary source of truth**
-   - `30_option_comparison.md` — オプション比較（比較 artifact）
-   - `31_selected_anchor_screen.md` — 選定結果 + selected anchor の SSOT
-   - `10_implementation_strategy.md` — 実装戦略（strict canonical schema）
-   - `11_design_taste_interview.md` — デザインテイストインタビュー
-   - `20-24` — 3-layer 評価ファミリー（**invariant / trend-derived / product-specific / aggregate / dynamic overrides** の 5 sidecar のみ。`20` は invariant axes, **Trend Scan は sidecar ではなく `04_Sources.md#Trend Scan` が正本**。旧 `uiux/20_trend_scan.md` は廃止。）
+   - `30_exploration_brief.md` — 探索ブリーフ（product intent / brand signals / must-preserve interactions）
+   - `31_reference_pool.md` — 参照プール（reference registry + local translation）
+   - `32_design_anti_goals.md` — 避けるべきデザイン方向
+   - `33_exploration_rubric.md` — 探索評価基準
+   - `34_evaluator_calibration.md` — evaluator 較正用 examples
    - `40_screen_contracts.md` — スクリーンコントラクト（strong schema）
    - `50_review_input_bundle.md` — レビュー入力バンドル
 
@@ -47,7 +47,7 @@ spec-0013 (CAP-0013) で定義された、下流 skill（prototyping / ATDD / TD
 
 ## Priority and Override Semantics
 
-- discussion sidecar artifacts が **primary truth**。具体的には (a) `uiux/30_option_comparison.md`（option comparison）、(b) `uiux/31_selected_anchor_screen.md`（selected anchor）、(c) `uiux/10_implementation_strategy.md`（implementation strategy）、(d) `uiux/40_screen_contracts.md`（screen contracts / 強スキーマ）の順で読む。
+- discussion sidecar artifacts が **primary truth**。具体的には (a) `uiux/30_exploration_brief.md`、(b) `uiux/31_reference_pool.md`、(c) `uiux/33_exploration_rubric.md`、(d) `uiux/34_evaluator_calibration.md`、(e) `uiux/40_screen_contracts.md` の順で読む。
 - `.qfai/contracts/ui/` の UI Contracts と Design Token は **存在する場合のみ読む supporting input**（primary truth ではない）。
 - Optional fallback mock はさらに後順位の **fallback**。
 - Design Token の値と HTML Mock の fallback 値が矛盾する場合は warning を発行。

package/assets/init/.qfai/contracts/README.md

@@ -1,15 +1,16 @@
-# .qfai/contracts (contracts + supporting inputs)
+# .qfai/contracts (downstream truth)
 
 ## Purpose
 
-This directory holds two related categories of inputs:
+This directory holds the version-managed artifacts that downstream execution skills consume.
 
 - **Contracts** (`api/`, `db/`, `ui/`) define the **stable surface** that
   specs and tests may reference. Each contract file requires a
   `QFAI-CONTRACT-ID` header and participates in the traceability ledger.
-- **Supporting inputs** (`design/`) supplement contracts — they do **not**
-  carry contract IDs and are not directly cited by specs. Design tokens are
-  referenced indirectly from `ui/*.yaml` via token IDs.
+- **Design definitions** (`design/`) hold downstream-ready design inputs that
+  `/qfai-sdd` normalizes from discussion-side exploration. They are
+  version-managed and may be consumed directly by `/qfai-prototyping`,
+  `/qfai-implement`, and `/qfai-atdd`.
 
 QFAI organizes this directory into four subdirectories:
 
@@ -17,17 +18,17 @@ QFAI organizes this directory into four subdirectories:
 .qfai/contracts/
 ├── api/      # OpenAPI YAML (endpoints, request/response)
 ├── db/       # SQL schema contracts (tables, columns, constraints)
-├── design/   # Design token YAML — optional supporting input
+├── design/   # Exploration brief / rubric / selected direction / design system YAML
 └── ui/       # UI contract YAML (screens, elements, user actions)
 ```
 
-> **Note:** `ui/` is a contract (QFAI-CONTRACT-ID required, cited by specs), but the **primary truth** for UI/UX definitions still lives in the discussion sidecar artifacts (`discussion-*/uiux/*`). UI contracts cite sidecar content by ID and exist specifically to make that sidecar machine-consumable for prototyping and selectors. `design/` is supporting input only (design tokens referenced indirectly from `ui/*.yaml`). After `qfai init`, these directories may contain only placeholder READMEs — this is the normal initial state.
+> **Note:** Discussion-pack UIUX files are upstream discovery artifacts. `/qfai-sdd` is responsible for normalizing the approved design/system/screen decisions into `.qfai/contracts/**`. Downstream execution skills must read these contracts instead of reading `discussion-*/uiux/*` directly.
 
 ## Directory rules
 
 - Contract files are **minimal**: only what specs actually need.
 - Each contract file in `api/`, `db/`, and `ui/` must declare `QFAI-CONTRACT-ID` at the top (`CON-UI-*` / `CON-API-*` / `CON-DB-*`).
-- `design/` (design token YAML) is a supporting input — **not** a contract in the traceability ledger. It does not require a `QFAI-CONTRACT-ID` header and is referenced indirectly from `ui/*.yaml` contracts via token IDs.
+- `design/` files are version-managed downstream inputs. They do not require `QFAI-CONTRACT-ID`, but they are part of the execution-time SSOT.
 - Prefer additive changes; breaking changes require delta notes.
 
 ```text
@@ -41,7 +42,12 @@ QFAI organizes this directory into four subdirectories:
 │   └── db-0001-<slug>.sql
 ├── design/
 │   ├── README.md
-│   └── design-tokens.yaml          (created when needed)
+│   ├── exploration-brief.yaml
+│   ├── evaluation-rubric.yaml
+│   ├── evaluator-calibration.yaml
+│   ├── selected-direction.yaml
+│   ├── design-system.yaml
+│   └── design-tokens.yaml          (optional)
 └── ui/
     ├── README.md
     └── ui-0001-<slug>.yaml
@@ -52,9 +58,10 @@ QFAI organizes this directory into four subdirectories:
 - Traceability Ledger (`16_Traceability-ledger.md`) references contracts via `con_ids`.
 - Layered overlays (`09_Examples.feature`, `11_Contracts.md`) may also reference contracts.
 - `11_Contracts.md` is an index layer and must not become behavior SSOT.
+- Discussion packs may explain where a contract came from, but they are not downstream execution inputs.
 
 ## Checklist
 
 - [ ] Contract IDs exist and are unique.
 - [ ] Contracts match what specs reference (no missing IDs).
-- [ ] Contracts are minimal but sufficient for prototyping and test automation.
+- [ ] Contracts/design files are sufficient for downstream skills without discussion-pack fallback.

package/assets/init/.qfai/contracts/design/README.md

@@ -1,32 +1,40 @@
-# contracts/design (Design Token YAML) — Optional Supporting Input
+# contracts/design (Exploration + Design Execution Inputs)
 
 ## Purpose
 
-Provide a designated location for design token files (`design-tokens*.yaml`) that serve as **optional supporting input** for UI review, validation, and implementation.
+Provide the downstream execution truth for exploration-first prototyping and final design-system extraction that `/qfai-sdd` and `/qfai-prototyping` normalize from UI-bearing discussion packs.
 
-**Primary truth** for UI/UX definitions resides in the discussion sidecar artifacts (`discussion-*/uiux/*`). Design token files in this directory supplement — but never override — those primary artifacts.
+These files are version-managed and may be read directly by `/qfai-prototyping`, `/qfai-implement`, `/qfai-atdd`, and `qfai validate`.
 
 ## Status After Init
 
-After `qfai init`, this directory contains only this README. This is the normal initial state. Design token files are created later when the project needs explicit token definitions.
+After `qfai init`, this directory contains only this README. This is the normal initial state. `/qfai-sdd` creates design files when a UI-bearing capability is normalized for downstream execution.
 
-The absence of design token files is **not** a defect and does not affect the canonical discussion or contracts flow.
+The absence of design files is not a defect for non-UI capabilities. For UI-bearing capabilities, missing required design files should be resolved in `/qfai-sdd`.
 
-## When Design Tokens Are Used
+## Typical Exploration-first Files
 
-Design token files are consumed **only when they exist**:
+Typical files:
 
-- `qfai validate` runs token-level checks (schema, circular references, platform coverage) if token files are present
-- `ui-definition-protocol.md` read-order includes this path as a conditional step
-- Prototyping and review skills reference tokens as supplementary color/spacing/typography values
+- `exploration-brief.yaml` — machine-readable exploration brief generated from discussion
+- `evaluation-rubric.yaml` — machine-readable evaluator rubric with weighted originality/design criteria
+- `evaluator-calibration.yaml` — evaluator alignment examples and anti-leniency guidance
+- `selected-direction.yaml` — current winning direction, rationale, and carry-forward rules
+- `design-system.yaml` — extracted final design system produced after direction convergence
+- `design-tokens*.yaml` — optional token definitions
 
 ## Expected File Names
 
-- `design-tokens.yaml` — primary token definitions (primitive → semantic → component)
-- `design-tokens.mobile.yaml` — mobile-specific overrides (optional)
+- `exploration-brief.yaml`
+- `evaluation-rubric.yaml`
+- `evaluator-calibration.yaml`
+- `selected-direction.yaml`
+- `design-system.yaml`
+- `design-tokens.yaml`
+- `design-tokens.mobile.yaml`
 
 ## What This Directory Is NOT
 
-- **Not** the primary truth for screen layout or component hierarchy
-- **Not** a required baseline for discussion or spec authoring
-- **Not** a substitute for sidecar artifacts or UI contracts
+- **Not** a replacement for specs or UI contracts
+- **Not** an excuse for downstream skills to read discussion-side artifacts directly
+- **Not** a place to finalize a winner before prototyping convergence

package/assets/init/.qfai/contracts/ui/README.md

@@ -2,10 +2,10 @@
 
 ## Purpose
 
-Define UI surface contracts for prototyping and E2E selection.
-The contract must describe screen structure, action coverage targets, and inspection anchors for full-harness evidence.
+Define UI surface contracts for prototyping, implementation review, and E2E selection.
+The contract must describe screen structure, action coverage targets, and stable inspection anchors.
 
-> **Note:** UI contracts are supporting input that supplements the discussion sidecar artifacts (`discussion-*/uiux/*`), which remain the primary truth for UI/UX definitions. In `packages/qfai` v1.7.15, prototyping execution is `full-harness` only; therefore, running the prototype harness requires both canonical screen contracts and matching `CON-UI-*` YAML contracts.
+> **Note:** UI contracts are the downstream execution truth for screen obligations. `/qfai-sdd` may derive them from discussion-side exploration, but `/qfai-prototyping`, `/qfai-implement`, and `/qfai-atdd` must read `contracts/ui/*.yaml` instead of reading `discussion-*/uiux/40_screen_contracts.md` directly.
 
 ## File rules
 
@@ -52,7 +52,7 @@ Add `prototype` at the top level.
 
 ### `prototype.mode` and `mockPaths[]` example
 
-The `mockPaths[]` entry is a **negative-only review ledger** — only populate it when a Browser QA finding or review outcome has identified a failure/gap in the mockable path. Do **not** populate it with expected success flows; those belong in `screens[].actions[]` (contracts) and the discussion sidecar.
+The `mockPaths[]` entry is a **negative-only review ledger** — only populate it when a Browser QA finding or review outcome has identified a failure/gap in the mockable path. Do **not** populate it with expected success flows; those belong in `screens[].actions[]`.
 
 ```yaml
 prototype:
@@ -146,11 +146,11 @@ screens:
   3. Prototyping evidence (`.qfai/evidence/prototyping.json`)
 - If only one side is updated, `QFAI-PROT-238` can remain unresolved in review.
 
-### Q3. "Can I treat this as a static screen?"
+### Q3. "Can I skip this because the discussion pack already has 40_screen_contracts.md?"
 
-- No. `packages/qfai` v1.7.15 prototyping is `full-harness` only.
-- `uiFidelity.mode: skeleton` is not a valid prototyping execution target.
-- Define actionable routes and `actions[]`, then collect real render and Browser QA evidence.
+- No.
+- `discussion-*/uiux/40_screen_contracts.md` is upstream discovery output.
+- Downstream execution and validation read `contracts/ui/*.yaml`; keep them synchronized via `/qfai-sdd`.
 
 ## Checklist
 
@@ -159,3 +159,4 @@ screens:
 - [ ] `elements[].label` matches runtime-visible inspection text or documented marker mapping.
 - [ ] `elements` and `actions` include the minimum fields above.
 - [ ] `prototype.mode` is `interactive` and `mockPaths` is treated as a negative-only issue ledger.
+- [ ] Every declared screen needed by downstream skills exists in `contracts/ui/*.yaml`.

package/assets/init/.qfai/discussion/README.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-`discussion/` stores the unified discussion pack that merges interview outputs (discuss) and requirement intake (require). Discussion packs use 15 required markdown files. When the latest pack is `ui_bearing: true`, it must also include `prototyping.yaml`; when `ui_bearing: false`, `prototyping.yaml` is not required.
+`discussion/` stores the unified discussion pack that merges interview outputs (discuss) and requirement intake (require). Discussion packs use 15 required markdown files. UI-bearing discussion packs may include `prototyping.yaml` as an optional recommendation artifact; non-ui discussion packs typically omit it.
 
 This directory does not directly update `specs/`; it prepares decisions, requirements, open questions, and rationale as inputs for `/qfai-sdd`.
 
@@ -29,7 +29,7 @@ discussion/
     ├── 13_Deferred.md
     ├── 14_Review-Request.md
     ├── 99_delta.md
-    └── prototyping.yaml  # required only when ui_bearing: true
+    └── prototyping.yaml  # optional recommendation artifact for UI-bearing packs
 ```
 
 ## File responsibilities
@@ -52,16 +52,17 @@ discussion/
 
 ## UI/UX canonical family
 
-For UI-bearing packs, the canonical design-evaluation source-of-truth is:
+For UI-bearing packs, the canonical exploration-first source-of-truth is:
 
 - `04_Sources.md` for trend translation and competitive reference registry
-- `uiux/20_design_eval_invariant.md`
-- `uiux/21_design_eval_trend_derived.md`
-- `uiux/22_design_eval_product_specific.md`
-- `uiux/23_design_eval_aggregate.md`
+- `uiux/30_exploration_brief.md`
+- `uiux/31_reference_pool.md`
+- `uiux/32_design_anti_goals.md`
+- `uiux/33_exploration_rubric.md`
+- `uiux/34_evaluator_calibration.md`
 - `uiux/40_screen_contracts.md`
 
-`05_Scope.md` is not a trend source-of-truth for L2 scoring, and fallback scans such as `uiux/*trend*` or `uiux/*competitive*` must not replace these canonical files.
+Discussion must not choose a single winner or finalize a design system. Those are downstream prototyping outputs.
 
 ## OQ Register rules
 
@@ -116,16 +117,16 @@ For UI-bearing packs, the canonical design-evaluation source-of-truth is:
 - Use timestamp directory naming for new outputs: `discussion-YYYYMMDDhhmmssSSS`.
 - `14_Review-Request.md` must reference routing SSOT: `.qfai/assistant/steering/agent-routing.yml` and `.qfai/assistant/steering/review-profiles.yml`.
 
-## prototyping.yaml (Classification-aware Recommendation Artifact)
+## prototyping.yaml (Optional Recommendation Artifact)
 
-Each UI-bearing discussion pack (`ui_bearing: true`) **must** include a `prototyping.yaml` file that recommends the prototyping mode for the project. Non-UI discussion packs (`ui_bearing: false`) do not require `prototyping.yaml`.
+UI-bearing discussion packs (`ui_bearing: true`) may include a `prototyping.yaml` file to record a recommended prototyping mode. Non-UI discussion packs (`ui_bearing: false`) typically omit `prototyping.yaml`.
 
-### Canonical namespaced schema (required)
+### Canonical namespaced schema (when present)
 
 ```yaml
 prototyping:
   recommended_mode: full-harness
-  rationale: UI validation requires the full-harness runtime loop in packages/qfai.
+  rationale: Exploration-first prototyping requires the full-harness runtime loop in packages/qfai.
   allowed_modes:
     - full-harness
   surface: web
@@ -133,7 +134,7 @@ prototyping:
 
 ### Field reference
 
-All 4 fields are **required**. An artifact missing any field will fail validation.
+If you create this artifact, populate all 4 fields.
 
 | Field              | Required | Description                                    |
 | ------------------ | -------- | ---------------------------------------------- |
@@ -142,12 +143,11 @@ All 4 fields are **required**. An artifact missing any field will fail validatio
 | `allowed_modes`    | yes      | Unique array; must contain only `full-harness` |
 | `surface`          | yes      | `web`, `mobile`, `desktop`, or `mixed`         |
 
-### Validation rules
+### Current behavior
 
-- Only the canonical namespaced schema under the `prototyping:` key is accepted. Top-level recommendation keys (`recommended_mode`, `rationale`, `allowed_modes`, `surface` at root level) are not supported and will cause validation failure.
-- Coexistence of top-level recommendation keys with the namespaced `prototyping:` block is invalid.
-- `recommended_mode` must be included in `allowed_modes`. In packages/qfai, this means `recommended_mode` must be `full-harness` and `allowed_modes` must only contain `full-harness`.
-- An artifact that does not conform to the canonical namespaced schema is invalid and will be rejected by both validation and execution/CLI. No fallback to explicit mode or default mode is performed for invalid artifacts.
+- Current discussion-pack readiness does not block on missing `prototyping.yaml`.
+- When `prototyping.yaml` is present, prefer the canonical namespaced schema under the `prototyping:` key.
+- `recommended_mode` should be included in `allowed_modes`. In packages/qfai, this means `recommended_mode` should be `full-harness` and `allowed_modes` should contain only `full-harness`.
 
 ## Suggested naming
 

package/assets/uix-rev/comparison-review.md

@@ -1,18 +1,16 @@
 # UIX-REV: Comparison Review
 
-Review only `30_option_comparison.md` as the option comparison artifact.
+Review exploration artifacts as comparison inputs, not a fixed option-comparison artifact.
 
-## Comparison Quality (30_option_comparison.md)
+## Comparison Quality
 
-- Must contain at least 2 options with structured evaluation
-- Each option should have pros/cons/trade-off analysis
-- Evaluation criteria must reference the 3-layer evaluation family
-- Rejected/deferred options must have explicit rationale
-- Reconsideration conditions must be documented for deferred options
-- Do not move selected anchor ownership back into `30_option_comparison.md`
+- Exploration must start from multiple divergent directions
+- Comparison criteria must reflect the exploration rubric and evaluator calibration
+- Rejected or superseded directions must have explicit rationale
+- Best-of-history handling must remain visible during later loops
 
 ### Trend-derived conversion check
 
-- Trend scan results are converted to comparison axes
+- Reference-pool inputs are translated into comparison pressure
 - Stale / overused AI slop avoidance is reflected in comparison criteria
-- Keep selected-anchor ownership in `31_selected_anchor_screen.md` and scoring-ready field ownership in `50_review_input_bundle.md`
+- Keep winner ownership in `selected-direction.yaml` and history handling in `50_review_input_bundle.md`

package/assets/uix-rev/contracts-review.md

@@ -22,7 +22,7 @@ Review screen contracts for canonical 11-field schema completeness.
 - Routes must be unique across all contracts
 - Required states must include `default`, `loading`, `empty`, and `error`
 - All 11 fields must be present and non-empty for each screen
-- Screen contracts must stay consistent with `31_selected_anchor_screen.md`
+- Screen contracts must stay consistent with the exploration brief and selected direction
 - Screen contracts must stay consistent with Browser QA findings and screen-linked evidence
 - Do not reference legacy filenames such as `40_contracts.md`
 - Keep wording aligned with scoring-ready canonical fields and avoid stale migration vocabulary