qfai 1.7.13 → 1.7.14

package/README.md

@@ -17,8 +17,8 @@ The agent reads the repository, produces the required artifacts, and iterates un
 
 ## Release status
 
-- Current package version: `1.7.13`
-- Release posture: v1.7.13 converges init assets, validators, and docs on the canonical sidecar model.
+- Current package version: `1.7.14`
+- Release posture: v1.7.14 converges init assets, validators, and docs on the canonical sidecar model.
 - Current repo note: some repo-wide `qfai validate --fail-on error` blockers still come from historical review/evidence/ATDD/TDD artifacts and are being cleaned incrementally.
 
 ## Quick start
@@ -85,7 +85,9 @@ QFAI includes a small set of custom skills (stored under `.qfai/assistant/skills
 - **qfai-configure**: Analyze the repository (language, frameworks, test layout, directory structure)
   and tailor `qfai.config.yaml` accordingly (especially `testFileGlobs`).
   Run this once right after `npx qfai init`, and re-run it when the repository structure changes.
-- **qfai-discussion**: Run a unified structured discussion that produces and maintains the latest discussion pack as 15 required markdown files plus required prototyping.yaml under `.qfai/discussion/discussion-<ts>/`.
+- **qfai-discussion**: Run a unified structured discussion that produces and maintains the latest discussion pack
+  as 15 required markdown files under `.qfai/discussion/discussion-<ts>/`.
+  UI-bearing discussion packs require `prototyping.yaml`; non-ui discussion packs do not.
 - **qfai-sdd**: Unified SDD entrypoint with discussion-pack preflight guard (missing/incomplete/blocking OQ causes stop + next action guidance).
 - **qfai-prototyping**: Build a contract-aligned implementation skeleton with static-first evidence by default, and escalate to full-harness only when explicitly justified.
 - **qfai-atdd**: Implement acceptance tests driven by specs/scenarios.
@@ -190,7 +192,7 @@ 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` in `qfai.config.yaml` connects full-harness scoring thresholds to the report and validator.
-- Observability modules (`src/core/observability/`) exist as foundation code but are **not integrated into blocking validation** in v1.7.13. They are reserved for future operational instrumentation.
+- 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.
 
 ## Specifications and contracts (SDD)
 
@@ -266,7 +268,7 @@ Recommended baseline.
 
 Waiver policy.
 
-- Use waivers only for `warning` / `info` findings (false positives, phased migration noise).
+- Use waivers only for `warning` / `info` findings (false positives).
 - Waivers that target `error` findings are invalid and fail validation (`QFAI-WAIVER-002`).
 - Expired waivers are reported as warnings (`QFAI-WAIVER-003`) and must be renewed or removed with evidence.
 - Suppressed findings remain visible in reports as `suppressed=true`; waivers do not erase findings.

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

@@ -2,12 +2,12 @@
 
 ## Mission
 
-- Implement frontend behavior aligned with selected direction, strategy, screen contracts, and product experience decisions.
+- Implement frontend behavior aligned with selected anchor, strategy, screen contracts, and product experience decisions.
 
 ## Domain Responsibilities
 
 - Build UI components, states, interactions, and user-facing flows.
-- Respect selected direction, strategy, screen contracts, optional design tokens, optional fallback HTML/CSS mock, and screen flow constraints.
+- Respect selected anchor, strategy, screen contracts, optional design tokens, optional fallback HTML/CSS mock, and screen flow constraints.
 - Coordinate with backend changes without breaking surface contracts.
 - Implement with KISS and YAGNI: prefer the simplest component/state structure that satisfies the current contract, and do not add speculative hooks, props, flags, or abstraction layers.
 - Keep UI code cohesive and readable: isolate concerns, minimize hidden coupling, avoid duplication, and use existing patterns/utilities before inventing new ones.

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

@@ -9,7 +9,7 @@
 - Define UX direction, user journeys, interaction patterns, and accessibility expectations.
 - Define visual design direction, tokens, typography, color, and layout hierarchy.
 - Design navigation structures, IA, and screen transition logic.
-- Integrate selected direction, strategy, screen contracts, evaluation sidecars, and Mermaid flow consistency.
+- Integrate selected anchor, strategy, screen contracts, evaluation sidecars, and Mermaid flow consistency.
 - Resolve conflicts between specialist design perspectives as a unified product experience decision.
 - Apply KISS and YAGNI to product-surface design: only add screens, controls, states, and branching flows that are justified by the current user goal.
 - Keep product experience decisions cohesive and unsurprising across copy, IA, navigation, transitions, and visual hierarchy.
@@ -24,7 +24,7 @@
 - .github/instructions/principles.instructions.md
 - .instruction/00_universal/development-principles-checklist.md
 - .instruction/01_specialties/design.md
-- Selected direction, strategy, screen contracts, evaluation sidecars, optional tokens, optional fallback HTML/CSS mock, and Mermaid flows
+- Selected anchor, strategy, screen contracts, evaluation sidecars, optional tokens, optional fallback HTML/CSS mock, and Mermaid flows
 - Runtime screenshots or rendered evidence when available
 
 ## Deliverables

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

@@ -9,7 +9,7 @@
 - Audit frontend changes for correctness and user-facing risk.
 - Audit layout sanity, interaction usability, and accessibility guardrails.
 - Audit visual design, token alignment, and service-level UX coherence.
-- Reconcile sidecar artifacts (selected direction, strategy, screen contracts), design tokens, mermaid flows, and rendered output consistency.
+- 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.
 - 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.

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

@@ -1,7 +1,7 @@
 ---
 name: qfai-discussion
 title: QFAI Discussion (Unified Discuss + Require)
-description: "Run structured discussion that merges discuss and require into a single 15-file discussion pack with required prototyping.yaml and OQ-driven exit."
+description: "Run structured discussion that merges discuss and require into a single 15-file discussion pack with classification-aware prototyping.yaml requiredness and OQ-driven exit."
 argument-hint: "<idea-or-problem> [--auto]"
 allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
 roles:
@@ -134,17 +134,24 @@ Every major artifact in this stage MUST include this table schema:
     - `uiux/11_design_taste_interview.md` — design taste interview (10 sections)
     - `04_Sources.md#Trend Scan` — trend scan with required category coverage and per-entry completeness
     - `uiux/20-24` — 3-layer evaluation family (invariant, trend-derived, product-specific, aggregate, dynamic overrides)
+      - **Score Scope**: 3-layer evaluation scores measure **design direction quality**
+        (which option best satisfies evaluation criteria).
+        These scores are NOT implementation quality scores.
+        When prototyping.yaml recommends `full-harness`,
+        the prototyping skill will independently evaluate **implementation fidelity**
+        using different scoring criteria.
+        Do not reuse 3-layer aggregate scores as prototyping iteration scores.
     - `uiux/30_option_comparison.md` — option comparison
-    - `uiux/31_selected_anchor_screen.md` — selected anchor screen (Selected Direction single source of truth)
+    - `uiux/31_selected_anchor_screen.md` — selected anchor screen (selected anchor single source of truth)
     - `uiux/40_screen_contracts.md` — screen contracts (strong schema)
     - `uiux/50_review_input_bundle.md` — review input bundle
-  - `04_Sources.md` `## Trend Scan` must include all required categories, and each entry must include: `reference`, `observation`, `freshness_date`, `confidence`, `source_translation`, `local_implication`
+  - `04_Sources.md` `## Trend Scan` must include all required categories, and each entry must include: `reference`, `observation`, `decision_connection`, `evaluation_connection`, `local_implication`
   - `04_Sources.md` `## Competitive Reference Registry` entries must include:
     - `adopted_points`: what was adopted and why
     - `rejected_points`: what was not adopted and why
     - `local_translation`: how adopted points were adapted
     - Placeholder-like values (TBD, N/A, TODO, empty) are treated as missing
-  - `14_Review-Request.md` must review selected direction from `uiux/31_selected_anchor_screen.md` and strategy alignment from `uiux/10_implementation_strategy.md`.
+  - `14_Review-Request.md` must review selected anchor from `uiux/31_selected_anchor_screen.md` and strategy alignment from `uiux/10_implementation_strategy.md`.
   - `99_delta.md` must include a `## Rejected Visual Directions` section with rationale and recurrence prevention.
   - `04_Sources.md` must include a `## Trend Scan` section where each required category has at least one complete entry.
   - `04_Sources.md` must include a `## Competitive Reference Registry` where each entry has: `adopted_points`, `rejected_points`, `local_translation` fields populated.
@@ -166,12 +173,18 @@ Every major artifact in this stage MUST include this table schema:
 Classify the project's surface type to determine whether UI/UX sidecar artifacts are required.
 Classification is based on **surface type only**, not interaction complexity (DR-0057).
 
+Classification surfaces: `web | mobile | desktop | cli | mixed | non-ui`
+Prototyping surfaces (subset): `web | mobile | desktop | cli | mixed`
+
+`non-ui` is a classification-only value used in `01_Context.md` when `ui_bearing: false`.
+It is not a prototyping surface and does not appear in `prototyping.yaml`.
+
 | Surface Type | UI-bearing | Sidecar Generation                       | Example                                  |
 | ------------ | ---------- | ---------------------------------------- | ---------------------------------------- |
 | web          | Yes        | Full 11-file uiux/ sidecar               | Web application with user-facing screens |
 | mobile       | Yes        | Full 11-file uiux/ sidecar               | Mobile app with touch interactions       |
 | desktop      | Yes        | Full 11-file uiux/ sidecar               | Desktop application with GUI             |
-| cli          | No         | No uiux/ directory, no sidecar generated | CLI tool, terminal application           |
+| cli          | Yes        | Full 11-file uiux/ sidecar               | CLI tool, terminal application           |
 | mixed        | Yes        | Full 11-file uiux/ sidecar               | Cross-platform with UI components        |
 | non-ui       | No         | No uiux/ directory, no sidecar generated | API service, library                     |
 
@@ -189,10 +202,10 @@ When UI-bearing is detected:
 2. Apply UX intent cross-references to core templates
 3. Add UI-bearing completion conditions
 
-When non-ui is detected:
+When non-ui is detected (`classification.ui_bearing: false`):
 
 - Skip uiux/ sidecar generation entirely — no uiux/ directory, no errors
-- Core 15-file pack plus required prototyping.yaml is generated as before
+- Core 15-file pack is generated; `prototyping.yaml` is not required
 - No additional UI/UX completion conditions apply
 
 ### UI-bearing Completion Conditions
@@ -209,18 +222,19 @@ For UI-bearing projects, the following conditions must ALL be satisfied before d
    have invariant, trend-derived, and product-specific evaluation criteria
 4. **Dynamic overrides documented**: `uiux/24_design_eval_dynamic_overrides.md` lists any override rules
 5. **Comparison completed**: `uiux/30_option_comparison.md` documents option comparison against scoring axes
-6. **Anchor screen selected**: `uiux/31_selected_anchor_screen.md` documents the selected direction and anchor screen
+6. **Anchor screen selected**: `uiux/31_selected_anchor_screen.md` documents the selected anchor and anchor screen
 7. **Contracts drafted**: `uiux/40_screen_contracts.md` contains screen interaction contracts
 
 Completion is blocked until all 7 conditions are met. Skipping any condition prevents the discussion from being marked as complete.
 
 ### Non-UI Completion
 
-For non-ui projects, completion conditions remain unchanged from prior versions. No additional UI/UX conditions apply; no sidecar artifacts are required.
+For non-UI projects (`classification.ui_bearing: false`), no UI/UX completion conditions apply and no sidecar artifacts are required. `prototyping.yaml` is not required for non-UI packs.
 
 ## Goal
 
-Produce a unified 15-file discussion pack plus required prototyping.yaml with explicit decisions, requirements, OQ states, and rationale so `/qfai-sdd` starts without unresolved blockers.
+Produce a unified 15-file discussion pack with explicit decisions, requirements, OQ states, and rationale so `/qfai-sdd` starts without unresolved blockers.
+The latest discussion pack must include `prototyping.yaml` when `ui_bearing: true`, and must not require it when `ui_bearing: false`.
 
 ## Non-goals
 
@@ -246,7 +260,7 @@ Produce a unified 15-file discussion pack plus required prototyping.yaml with ex
 - `.qfai/discussion/discussion-*/14_Review-Request.md`
 - `.qfai/discussion/discussion-*/99_delta.md`
 - review artifacts under `.qfai/review/review-YYYYMMDDhhmmssSSS/`
-- `.qfai/discussion/discussion-*/prototyping.yaml`
+- `.qfai/discussion/discussion-*/prototyping.yaml` when the latest discussion pack is `ui_bearing: true`
 - Evidence file: `.qfai/evidence/discussion-YYYYMMDDhhmmssSSS.md`
 - Reviewer notes (`PASS` or `REVISE`)
 
@@ -254,7 +268,7 @@ Produce a unified 15-file discussion pack plus required prototyping.yaml with ex
 
 1. Run the core interview for product concept, scope, stakeholders, and constraints (`01_Context.md`).
 2. Run Inception Deck (10 questions) for ambiguity removal and project alignment, and include at least one Mermaid diagram (`02_Inception-Deck.md`).
-3. Run Story Workshop to capture user stories, user flows, and at least one Mermaid diagram; HTML+CSS visual mock is optional fallback only when it materially clarifies the selected direction (`03_Story-Workshop.md`).
+3. Run Story Workshop to capture user stories, user flows, and at least one Mermaid diagram; HTML+CSS visual mock is optional fallback only when it materially clarifies the selected anchor (`03_Story-Workshop.md`).
 4. Register source traceability in `04_Sources.md` with stable `SRC-XXXX` identifiers.
 5. Define scope boundaries and success criteria in `05_Scope.md`.
 6. Capture functional requirements in `06_REQ.md` with `REQ-0001` format.
@@ -267,15 +281,27 @@ Produce a unified 15-file discussion pack plus required prototyping.yaml with ex
 13. Run OQ resolution hearing repeatedly until open count is zero.
 14. Move deferred items to `13_Deferred.md` with all mandatory metadata columns.
 15. Update `12_OQ-Resolution-Log.md`, `14_Review-Request.md`, and `99_delta.md`.
-16. Generate `prototyping.yaml` at the discussion pack top level for downstream prototyping recommendation.
+16. Generate `prototyping.yaml` at the discussion pack top level for downstream prototyping recommendation only when the latest discussion pack is `ui_bearing: true`.
     - MUST use the **namespaced canonical schema** with `prototyping.recommended_mode` (not top-level `recommended_mode`).
-    - Top-level `recommended_mode` is legacy compatibility only and MUST NOT be emitted in new artifacts.
     - All fields (`recommended_mode`, `rationale`, `allowed_modes`, `surface`) are required under the `prototyping:` key.
+    - Top-level recommendation keys are not supported; only the namespaced `prototyping:` block is accepted.
+    - Coexistence of top-level recommendation keys with the namespaced block is invalid and will be rejected by validation and execution.
 17. Choose `recommended_mode` with these defaults:
-
-- `low-cost`: rough draft or strong cost priority
-- `standard`: normal customer-presentable path
-- `full-harness`: only when the premium runtime loop is justified
+    - `low-cost`: rough draft or strong cost priority
+    - `standard`: normal customer-presentable path
+    - `full-harness`: only when the premium runtime loop is justified
+
+    When `recommended_mode: full-harness`, add an `iteration_expectations` block to `prototyping.yaml`:
+
+    ```yaml
+    prototyping:
+      recommended_mode: full-harness
+      iteration_expectations:
+        min_iterations: 5
+        evaluation_axes_source: "uiux/20-23 (3-layer evaluation family)"
+        score_scope: "implementation_fidelity"
+        note: "Discussion 3-layer scores measure design-direction quality. Prototyping scores measure implementation fidelity. Do not copy."
+    ```
 
 18. Request review and record Reviewer result.
 

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/01_Context.md

@@ -4,12 +4,21 @@
 
 ## UI-bearing Classification
 
+Classification determines whether UI/UX sidecar artifacts are required.
+
 - ui_bearing: [true|false]
 - primary_surface: [web|mobile|desktop|cli|mixed|non-ui]
 - secondary_surfaces:
   - [optional]
 - classification_rationale: [Why this classification was chosen]
 
+Notes:
+
+- `primary_surface` is a classification field. Valid values: `web|mobile|desktop|cli|mixed|non-ui`.
+- `non-ui` is only valid when `ui_bearing: false`. It is a classification value, not a prototyping surface.
+- `cli` is a UI-bearing surface. When classified as `cli`, set `ui_bearing: true`.
+- Prototyping surfaces (used in `prototyping.yaml`) are a subset: `web|mobile|desktop|cli|mixed`.
+
 ## Metadata
 
 | Key           | Value                        |

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/03_Story-Workshop.md

@@ -73,7 +73,7 @@ Screen-level contract details are finalized in `uiux/40_screen_contracts.md`. Pr
 ## Appendix: Screen Mock — Optional Fallback (HTML+CSS)
 
 <!-- Optional fallback only — do not use as the primary UI definition artifact.
-     Include only when it materially clarifies the selected direction.
+     Include only when it materially clarifies the selected anchor.
      Behavior Obligations and sidecar artifacts (uiux/) are the primary UI definitions.
      The required state SSOT is uiux/40_screen_contracts.md (`default/loading/empty/error`). -->
 

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/04_Sources.md

@@ -22,7 +22,7 @@
 - observation: [What visual tone signal was observed]
 - freshness_date: YYYY-MM-DD
 - confidence: [high|medium|low]
-- source_translation: [How the signal translates into this project]
+- decision_connection: [How the signal translates into this project]
 - local_implication: [What should change locally]
 
 ### Layout / Composition Trends
@@ -33,7 +33,7 @@
 - observation: [What layout or composition signal was observed]
 - freshness_date: YYYY-MM-DD
 - confidence: [high|medium|low]
-- source_translation: [How the signal translates into this project]
+- decision_connection: [How the signal translates into this project]
 - local_implication: [What should change locally]
 
 ### Density / Hierarchy Trends
@@ -44,7 +44,7 @@
 - observation: [What density or hierarchy signal was observed]
 - freshness_date: YYYY-MM-DD
 - confidence: [high|medium|low]
-- source_translation: [How the signal translates into this project]
+- decision_connection: [How the signal translates into this project]
 - local_implication: [What should change locally]
 
 ### Interaction / Motion Trends
@@ -55,7 +55,7 @@
 - observation: [What interaction or motion signal was observed]
 - freshness_date: YYYY-MM-DD
 - confidence: [high|medium|low]
-- source_translation: [How the signal translates into this project]
+- decision_connection: [How the signal translates into this project]
 - local_implication: [What should change locally]
 
 ### Component Styling Trends
@@ -66,7 +66,7 @@
 - observation: [What component styling signal was observed]
 - freshness_date: YYYY-MM-DD
 - confidence: [high|medium|low]
-- source_translation: [How the signal translates into this project]
+- decision_connection: [How the signal translates into this project]
 - local_implication: [What should change locally]
 
 ### Stale / Overused AI Slop Patterns
@@ -77,7 +77,7 @@
 - observation: [What stale pattern should be avoided]
 - freshness_date: YYYY-MM-DD
 - confidence: [high|medium|low]
-- source_translation: [Why this stale pattern is relevant to avoid here]
+- decision_connection: [Why this stale pattern is relevant to avoid here]
 - local_implication: [What should be explicitly avoided locally]
 
 ## Competitive Reference Registry

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/14_Review-Request.md

@@ -37,22 +37,22 @@
 - Mermaid diagrams use ` ```mermaid ` fences only
 - Strategy alignment and chosen_option consistency (when UI-bearing)
 - Taste reflection completeness and clarity (when UI-bearing)
-- Trend scan freshness and source translation quality (when UI-bearing)
+- Trend scan freshness and evidence traceability (when UI-bearing)
 - 3-layer axes evaluation quality and traceability (when UI-bearing)
 - Option comparison integrity (when UI-bearing)
-- Selected anchor screen clarity and direction justification (when UI-bearing)
+- Selected anchor screen clarity and anchor justification (when UI-bearing)
 - Screen contract sufficiency and strong schema completeness (when UI-bearing)
 - Generic fallback risk — ensure no unreviewed generic/placeholder UI remains (when UI-bearing)
 - OQ register exit condition (open count = 0)
 - Deferred items have full metadata
 
-## Selected Direction Consistency
+## Selected Anchor Consistency
 
 <!-- Required for UI-bearing packs. Verifies sidecar-family alignment. -->
 
-- Selected direction: verify `uiux/31_selected_anchor_screen.md` Selected Direction is populated and references a compared option from `uiux/30_option_comparison.md`
-- Strategy alignment: verify `uiux/10_implementation_strategy.md` aligns with the selected direction in `uiux/31_selected_anchor_screen.md`
-- Evaluation traceability: verify selected direction rationale aligns with 3-layer evaluation family (20/21/22/23 + optional 24)
+- Selected anchor: verify `uiux/31_selected_anchor_screen.md` selected anchor is populated and references a compared option from `uiux/30_option_comparison.md`
+- Strategy alignment: verify `uiux/10_implementation_strategy.md` aligns with the selected anchor in `uiux/31_selected_anchor_screen.md`
+- Evaluation traceability: verify selected anchor rationale aligns with 3-layer evaluation family (20/21/22/23 + optional 24)
 
 ## Sidecar Artifact Review Scope
 
@@ -62,7 +62,7 @@
 - Verify uiux/10_implementation_strategy.md strict canonical schema is complete
 - Verify scoring axes have evaluation criteria and measurement approaches
 - Verify option comparison covers 2+ options against all scoring axes in `uiux/30_option_comparison.md`
-- Verify `uiux/31_selected_anchor_screen.md` Selected Direction references a compared option
+- Verify `uiux/31_selected_anchor_screen.md` selected anchor references a compared option
 - Verify `uiux/24_design_eval_dynamic_overrides.md` has documented override rules
 - Verify screen contracts use nested strong schema with all 4 required states (default/loading/empty/error) and treat `uiux/40_screen_contracts.md` as the state SSOT
 

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/review/Rxx_reviewer.md

@@ -14,9 +14,9 @@
 - [ ] Mermaid diagrams are sufficient for decisions (scope/AC/risk consistency)
 - [ ] Mermaid diagrams use ` ```mermaid ` fences only
 - [ ] Taste interview completeness (when UI-bearing)
-- [ ] Trend freshness and translation quality (when UI-bearing)
+- [ ] Trend freshness and evidence traceability (when UI-bearing)
 - [ ] 3-layer evaluation quality and traceability (when UI-bearing)
-- [ ] Option comparison integrity and selected direction clarity (when UI-bearing)
+- [ ] Option comparison integrity and selected anchor clarity (when UI-bearing)
 - [ ] Strong screen contract completeness (when UI-bearing)
 - [ ] OQ register exit condition (open count = 0)
 - [ ] Deferred items have full metadata

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/review/review_request.md

@@ -23,9 +23,9 @@
   - Security/operations risks are reflected in diagrams where relevant
 - Mermaid diagrams use ` ```mermaid ` fences only (no ` ```text ` or language-less fences)
 - Taste interview completeness and clarity (when UI-bearing)
-- Trend freshness and source translation quality (when UI-bearing)
+- Trend freshness and evidence traceability (when UI-bearing)
 - 3-layer evaluation quality and traceability (when UI-bearing)
-- Option comparison integrity and selected direction clarity (when UI-bearing)
+- Option comparison integrity and selected anchor clarity (when UI-bearing)
 - Strong screen contract completeness (when UI-bearing)
 - OQ register exit condition (open count = 0)
 - Deferred items have full metadata in `13_Deferred.md`

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/10_implementation_strategy.md

@@ -1,20 +1,38 @@
 # Implementation Strategy
 
-## Strategy Definition
+## Surface
 
-<!-- Use exactly one canonical strategy block. -->
+- surface: web
 
-### Strategy
+## Selection Requirement
 
-- surface: [web|mobile|desktop|cli|mixed|non-ui]
-- decision: [template|component-library|design-system|native-pattern|bespoke|none]
-- why_this_strategy: [Why this strategy is the right fit for the current product and surface]
-- expected_strengths: [Concrete strengths expected from this strategy]
-- known_risks: [Concrete risks, failure modes, or tradeoffs]
-- fit_for_this_product: [Why this strategy matches the actual product context]
+- selection_required: true
 
-## Constraints
+## Decision
 
-- Use only the canonical enum values shown above.
-- Do not add legacy keys or freeform alternative enums.
-- Keep the strategy aligned with `01_Context.md` classification and `31_selected_anchor_screen.md`.
+- decision: component-library
+
+## Candidate Options
+
+- candidate_options:
+  - component-library
+  - bespoke
+
+## Chosen Option
+
+- chosen_option: component-library
+
+## Rationale
+
+- rationale:
+  - Existing design-system alignment is more valuable than bespoke variance.
+
+## Verification Expectations
+
+- verification_expectations:
+  - Primary tasks remain obvious without generic dashboard drift.
+
+## Notes for Reviewer
+
+- notes_for_reviewer:
+  - Check that the selected anchor stays aligned with the anchor screen and screen contracts.

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/20_trend_scan.md

@@ -0,0 +1,41 @@
+# Trend Scan
+
+## user expectation / market norm
+
+### Entry 1
+
+- reference: https://example.com/user-expectation
+- observation: Users expect the primary workflow to be immediately legible without tutorial debt.
+- decision_connection: Favors the option that exposes the primary task in the first viewport.
+- evaluation_connection: Becomes a scoring lens for first-run clarity and task discoverability.
+- local_implication: Keep the anchor screen focused on the primary job-to-be-done.
+
+## product neighbor / comparable flow
+
+### Entry 1
+
+- reference: https://example.com/product-neighbor
+- observation: Comparable flows reduce ambiguity by keeping one dominant action above the fold.
+- decision_connection: Pushes against multi-primary-action layouts.
+- evaluation_connection: Adds a comparison criterion for action hierarchy quality.
+- local_implication: Treat scattered entry points as a regression.
+
+## platform convention
+
+### Entry 1
+
+- reference: https://example.com/platform-convention
+- observation: The target platform uses predictable navigation and standard control placement.
+- decision_connection: Prefers familiar component placement over novelty.
+- evaluation_connection: Scores adherence to platform conventions and navigation predictability.
+- local_implication: Reuse established navigation patterns before inventing new ones.
+
+## accessibility / compliance relevant signal
+
+### Entry 1
+
+- reference: https://example.com/accessibility
+- observation: Accessible naming, focus order, and contrast remain non-negotiable quality floors.
+- decision_connection: Rejects any option that depends on hidden or ambiguous affordances.
+- evaluation_connection: Creates explicit checks for accessibility compliance and interaction clarity.
+- local_implication: Bake accessibility review points into contracts and Browser QA expectations.

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/23_design_eval_aggregate.md

@@ -39,3 +39,15 @@ This file defines how scores from invariant, trend-derived, and product-specific
 - Product-specific axes: `22_design_eval_product_specific.md`
 - Dynamic overrides (optional): `24_design_eval_dynamic_overrides.md`
 - Option comparison: `30_option_comparison.md`
+
+## Score Scope Limitation
+
+**IMPORTANT**: Scores produced by this aggregate evaluation measure **design direction quality** — i.e., how well each design option satisfies the evaluation criteria for option comparison and selection.
+
+These scores are **NOT** implementation quality scores. When the selected design direction proceeds to `/qfai-prototyping` in full-harness mode:
+
+- Prototyping evaluates **implementation fidelity** against the selected anchor.
+- Prototyping uses its own scoring criteria (calibration baselines, dimension weights).
+- Discussion aggregate scores MUST NOT be copied into `fullHarness.scoringTrace`.
+
+The boundary is: discussion scores inform the **what** (which direction); prototyping scores measure the **how well** (implementation quality).

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/40_screen_contracts.md

@@ -32,7 +32,7 @@ Draft interaction contracts for key screens using the strong screen contract sch
 - notes_for_verify: [notes for verification/testing]
 - notes_for_reviewer: [any additional context for the reviewer]
 
-<!-- Nested list format is canonical for primary_tasks, secondary_tasks, required_states, transitions, observable_outcomes. Inline CSV is accepted for backward compatibility. -->
+<!-- Nested list format is canonical for primary_tasks, secondary_tasks, required_states, transitions, observable_outcomes. -->
 
 > **Note:** `required_states` primary truth lives in this file. Each screen's state set is authoritative here.
 > **Note:** `secondary_tasks` documents non-primary user workflows available on the screen.

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/50_review_input_bundle.md

@@ -26,11 +26,13 @@ Consolidate all sidecar artifacts into a review-ready bundle for design reviewer
 - Required trend categories are all present and complete.
 - Stale / overused AI slop patterns are explicitly avoided.
 - Trend research is translated into scoring, comparison, and selected anchor decisions.
+- Scoring-ready axes use canonical fields: `origin`, `layer`, `source_refs`, `goal_refs`, `evidence_required`, `review_questions`.
 
 ## Review Checklist
 
 - [ ] Strategy aligns with surface type and project constraints
 - [ ] Trend categories are complete and translated into local design decisions
 - [ ] Competitive references include adopted_points, rejected_points, and local_translation
+- [ ] Scoring-ready axes expose canonical fields including origin/source_refs/goal_refs/evidence_required/review_questions
 - [ ] Selected anchor clearly documents rationale and downstream implications
 - [ ] Screen contracts cover all required states

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

@@ -77,8 +77,12 @@ 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 direction, 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) → 3-layer evaluation family (20/21/22/23 + optional 24) → screen contracts (40_screen_contracts.md) → review input bundle (50_review_input_bundle.md) → optional design tokens → optional fallback mock → mermaid flows.
+- 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 (uiux/20_trend_scan.md) → 3-layer evaluation family (20/21/22/23 + optional 24) →
+  screen contracts (40_screen_contracts.md) → review input bundle (50_review_input_bundle.md) →
+  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.
 
 ## Non-goals