qfai 1.8.8 → 1.8.9

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

@@ -28,8 +28,9 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 - .qfai/specs/spec-\*/09_delta.md
 - .qfai/specs/spec-\*/01_Spec.md
 - .github/instructions/principles.instructions.md
-- Exploration brief, reference pool, evaluation rubric, evaluator calibration, selected direction, finalized design system,
-  screen contracts, optional tokens, optional fallback HTML/CSS mock, and Mermaid flows
+- Root `DESIGN.md` (brand SSOT: front-matter tokens plus `# Brand Philosophy` body)
+- Reference pool framed as deviate-from inputs, screen contracts (`uiux/40_screen_contracts.md`), optional tokens, optional fallback HTML/CSS mock, and Mermaid flows
+- Evaluator axes are fixed in `core/prototyping/evaluatorReview.ts#ORDINAL_AXES` (information architecture / navigation flow / usability / functionality) and no longer authored as sidecar files
 - Runtime screenshots or rendered evidence when available
 
 ## Deliverables

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

@@ -32,47 +32,41 @@ Produce a unified 15-file discussion pack plus exploration-first UI sidecars so
 ## CRITICAL CONSTRAINTS (Read First)
 
 - Output path is fixed: `.qfai/discussion/discussion-YYYYMMDDhhmmssSSS/`.
-- Required fixed files (all 15 are mandatory) remain unchanged.
+- All 15 mandatory fixed files remain unchanged.
 - UI-bearing discussion packs may include `prototyping.yaml` as an optional recommendation artifact; non-ui discussion packs typically omit it.
-- Discussion completion requires `Disposition: open` count to be zero in `11_OQ-Register.md`.
+- Completion requires `Disposition: open` count to be zero in `11_OQ-Register.md`.
 - If UI requirements exist, behavior obligations are primary and HTML+CSS mock is optional fallback only.
 - Discussion is planner-first: do not select a single visual winner and do not finalize the design system here.
 - Use artifact files, not conversational summaries, as the downstream handoff.
 
 ## UI-bearing Canonical Sidecar Family
 
-UI-bearing packs must produce the following sidecars as primary truth:
+UI-bearing packs must produce, as primary truth: `uiux/40_screen_contracts.md`, `uiux/50_review_input_bundle.md`. They MUST also emit a draft brand SSOT at the **consuming-project root**:
 
-- `uiux/30_exploration_brief.md`
-- `uiux/31_reference_pool.md`
-- `uiux/32_design_anti_goals.md`
-- `uiux/40_screen_contracts.md`
-- `uiux/50_review_input_bundle.md`
+- `<consuming-project-root>/DESIGN.md` — brand SSOT consumed by `/qfai-sdd` (freezes its sha256 in `.qfai/contracts/design/DESIGN.md.lock.yaml`) and by `/qfai-prototyping` (iterates against locked tokens). Brand intent (product intent, brand signals, anti-goals, reference pool framed as deviate-from inputs) lives in front-matter + `# Brand Philosophy` body — no separate per-aspect sidecar.
 
 ## Required Process
 
 1. Run the core interview for concept, scope, stakeholders, and constraints.
 2. Run Inception Deck and include at least one Mermaid diagram.
-3. Run Story Workshop, capture user stories and user flows, and keep HTML+CSS mock as optional fallback only.
+3. Run Story Workshop, capture user stories and user flows; HTML+CSS mock is optional fallback only.
 4. Register source traceability and reference research in `04_Sources.md`.
 5. Capture scope, REQ, NFR, glossary, constraints, and policies.
 6. Run Example Mapping and capture `Example Seeds`.
 7. Update `11_OQ-Register.md`, resolve OQs until open count is zero, and move deferred items to `13_Deferred.md`.
 8. Generate the exploration-first sidecar family for UI-bearing targets.
-9. Generate `prototyping.yaml` only when the latest discussion pack is UI-bearing and an explicit prototyping recommendation is useful.
-10. Request review and record the Reviewer result.
+9. **Emit root `DESIGN.md` draft** for UI-bearing targets per `references/design-dna-intake.md`. Required when UI-bearing; skip otherwise.
+10. Generate `prototyping.yaml` only when the latest discussion pack is UI-bearing and an explicit prototyping recommendation is useful.
+11. Request review and record the Reviewer result.
 
 For UI-bearing targets, follow `references/design-dna-intake.md` while authoring the UI/UX sidecars. Keep this `SKILL.md` compact; put detailed interview prompts and examples in the reference file.
 
 ## UI-bearing Authoring Requirements
 
-- `30_exploration_brief.md` must define product intent, brand signals, and differentiation targets.
-- `31_reference_pool.md` must define exploration references with adopted points, rejected points, and copy risk — framed as **deviate-from** inputs (not imitate-this) for downstream `/qfai-prototyping` reviewer.
-- `32_design_anti_goals.md` must contain explicit anti-goals; this also feeds the global anti-slop pattern list consulted by the prototyping reviewer.
-- `50_review_input_bundle.md` must document review inputs for downstream skills.
-
-Evaluation axes are global constants (4-step ordinal: weak / acceptable /
-strong / exceptional) and are not authored as discussion sidecars.
+- Root `DESIGN.md` front-matter must define `brand` (name, archetype, voice), `audience` (emotion, do_not_look_like), and the full `visual.*` token tree (colors, typography, spacing, radius, shadow).
+- `# Brand Philosophy` body documents do/don't, brand signals, and exploration references framed as **deviate-from** inputs (not imitate-this) for the downstream `/qfai-prototyping` reviewer.
+- `40_screen_contracts.md` defines each screen contract per the template schema; `50_review_input_bundle.md` documents review inputs for downstream skills.
+- Evaluation axes are global constants (4-step ordinal: weak / acceptable / strong / exceptional) and are not authored as discussion sidecars.
 
 ## Completion Contract (Shared)
 
@@ -84,7 +78,7 @@ Before declaring completion, you MUST:
 - ensure `Disposition: open` count is zero in `11_OQ-Register.md`;
 - ensure every deferred item has full metadata in `13_Deferred.md`;
 - ensure `02_Inception-Deck.md` and `03_Story-Workshop.md` include Mermaid diagrams;
-- ensure the UI-bearing sidecar family is complete;
+- ensure the UI-bearing sidecar family is complete and the root `DESIGN.md` draft exists at the consuming-project root and parses as valid front-matter;
 - run `qfai validate --profile discussion --fail-on error` and fix discussion-owned findings;
 - avoid selecting a single visual winner in discussion artifacts.
 
@@ -92,15 +86,12 @@ Before declaring completion, you MUST:
 
 Reviewer checks must confirm:
 
-- the 15-file discussion pack is complete
-- `Disposition: open` count is zero in `11_OQ-Register.md`
-- the UI-bearing sidecar family is complete when the pack is UI-bearing
-- discussion stayed planner-first and did not choose a single visual winner
-- Drift Protocol is enforced
-- review policy is checked against `.qfai/assistant/steering/test-layers.md`
-- planning and coverage heuristics are signals, not gates
-- review findings end with `Status (PASS/REVISE)`
-- Reviewer result is explicit as `PASS` or `REVISE`
+- the 15-file discussion pack is complete; `Disposition: open` count is zero in `11_OQ-Register.md`;
+- the UI-bearing sidecar family is complete when the pack is UI-bearing;
+- discussion stayed planner-first and did not choose a single visual winner;
+- Drift Protocol is enforced; review policy is checked against `.qfai/assistant/steering/test-layers.md`;
+- planning and coverage heuristics are signals, not gates;
+- review findings end with `Status (PASS/REVISE)` and Reviewer result is explicit as `PASS` or `REVISE`.
 
 ## Sub-agent Delegation (MANDATORY)
 
@@ -108,9 +99,7 @@ Follow `.qfai/assistant/instructions/shared-skill-delegation-baseline.md`.
 
 ### Orchestrator Protocol (MUST)
 
-- do not self-approve
-- use artifact files as the handoff surface
-- integrate delegated outputs only after checking pack completeness
+- do not self-approve; use artifact files as the handoff surface; integrate delegated outputs only after checking pack completeness.
 
 ### Capability Probe (MUST)
 

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

@@ -6,24 +6,54 @@ Use this reference only for UI-bearing discussion packs.
 
 - Brand personality: list 3-5 traits the product should express.
 - Audience emotion: define what users should feel after the primary task.
-- Category conventions: name the expected layout and interaction patterns for this market.
-- Differentiation targets: state what must feel unlike generic SaaS, generic shadcn, or direct competitors.
-- Anti-template constraints: name default visual patterns that must not survive into prototyping.
-- Reference strategy: collect competitor, adjacent, aspirational, template-seed, and anti-pattern references.
+- Category conventions: name the expected layout and interaction
+  patterns for this market.
+- Differentiation targets: state what must feel unlike generic SaaS or
+  direct competitors.
+- Anti-template constraints: name default visual patterns that must
+  not survive into prototyping.
+- Reference strategy: collect competitor, adjacent, aspirational,
+  template-seed, and anti-pattern references.
 
 ## Reference Rules
 
 - Treat templates as seeds, not winners.
 - Capture both adopted and rejected points for every reference.
-- Translate references into local product rules instead of copying visual surfaces.
+- Translate references into local product rules instead of copying
+  visual surfaces.
 - Record copy risk as `low`, `medium`, or `high`.
-- Record template usage policy as `none`, `reference-only`, or `implementation-seed`.
-
-## Output Mapping
-
-- Put product intent and brand signals in `30_exploration_brief.md`.
-- Put all reference decisions in `31_reference_pool.md` (deviate-from input, not imitate).
-- Put prohibited visual directions in `32_design_anti_goals.md` (also feeds reviewer anti-slop).
-
-Evaluation axes are global constants (4-step ordinal: weak / acceptable /
-strong / exceptional) and are not authored as discussion sidecars.
+- Record template usage policy as `none`, `reference-only`, or
+  `implementation-seed`.
+
+## Output Mapping (new SSOT path)
+
+The interview produces **one root `DESIGN.md`** at
+`<consuming-project-root>/DESIGN.md`. This file is the brand SSOT
+consumed by `/qfai-sdd` (which freezes its sha256) and by
+`/qfai-prototyping` (which iterates under its tokens).
+
+Map the interview answers into `DESIGN.md` as follows:
+
+- Brand personality → `brand.voice` (1..N short trait words) and the
+  `# Brand Philosophy` body.
+- Brand archetype → `brand.archetype`. Allowed values are the
+  8-archetype catalog in `design-md-brand-catalog.md`
+  (`minimal | bold | corporate | playful | organic | tech | elegant |
+casual`). Use `aesthetic_properties` from the catalog as defaults.
+- Audience emotion → `audience.emotion`.
+- Anti-template constraints + rejected references →
+  `audience.do_not_look_like` and the **Don't** subsection of the
+  `# Brand Philosophy` body.
+- Visual decisions (color, typography, radius, shadow) → the
+  `visual.*` token tree. Schema and validation rules live in
+  `.qfai/assistant/skills/qfai-prototyping/references/design-md-spec.md`.
+- Adopted reference points → the **Do** subsection of
+  `# Brand Philosophy`.
+
+For the schema (12 colors, 3 fonts, 4 radii, 3 shadows, 8 archetypes),
+read `qfai-prototyping/references/design-md-spec.md` and use the
+sample at `qfai-prototyping/templates/DESIGN.md.sample` as a starting
+shape.
+
+Evaluation axes are global constants (4-step ordinal: weak / acceptable
+/ strong / exceptional) and are not authored as discussion sidecars.

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

@@ -41,12 +41,10 @@ UI-bearing discussion packs may include `prototyping.yaml` as an optional recomm
 For UI-bearing packs, use:
 
 - `04_Sources.md` for trend translation and competitive reference registry
-- `uiux/30_exploration_brief.md`
-- `uiux/31_reference_pool.md`
-- `uiux/32_design_anti_goals.md`
+- `DESIGN.md` (root) — brand SSOT draft (front-matter + `# Brand Philosophy` body); `/qfai-sdd` Phase 0 freezes it into `.qfai/contracts/design/DESIGN.md.lock.yaml`
 - `uiux/40_screen_contracts.md`
 
-Discussion is exploration-first and must not choose a single visual winner or final design system. Those are downstream prototyping outputs.
+Discussion is exploration-first and must not choose a single visual winner or final design system. The brand decision is captured once in root `DESIGN.md`; downstream prototyping consumes the frozen tokens.
 
 ## `prototyping.yaml`
 

package/assets/init/.qfai/assistant/skills/qfai-discussion/references/ui-bearing-playbook.md

@@ -26,17 +26,12 @@ Use this file when `/qfai-discussion` needs the full UI-bearing decision logic.
 
 ## Sidecar Family SSOT
 
+For UI-bearing packs the brand SSOT is root `DESIGN.md` (drafted by
+`/qfai-discussion` and frozen by `/qfai-sdd` Phase 0 into
+`.qfai/contracts/design/DESIGN.md.lock.yaml`). The remaining sidecars are
+the screen-level UX inputs:
+
 - `uiux/00_index.md`
-- `uiux/10_implementation_strategy.md`
-- `uiux/11_design_taste_interview.md`
-- `uiux/12_design_system.md`
-- `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/24_design_eval_dynamic_overrides.md`
-- `uiux/30_option_comparison.md`
-- `uiux/31_selected_anchor_screen.md`
 - `uiux/40_screen_contracts.md`
 - `uiux/50_review_input_bundle.md`
 

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

@@ -35,10 +35,10 @@
   - Acceptance criteria are consistent with flows/state transitions
   - Security/operations risks are reflected in diagrams where relevant
 - Mermaid diagrams use ` ```mermaid ` fences only
-- Exploration brief completeness and differentiation clarity (when UI-bearing)
-- Reference pool freshness and translation quality (when UI-bearing)
-- Exploration rubric quality and evaluation traceability (when UI-bearing)
-- Evaluator calibration skepticism and blandness rejection quality (when UI-bearing)
+- Root `DESIGN.md` completeness and differentiation clarity (when UI-bearing)
+- Reference pool freshness and translation quality into `DESIGN.md` (when UI-bearing)
+- Evaluator scoring covers all four canonical UX axes — information architecture / navigation flow / usability / functionality, fixed in `core/prototyping/evaluatorReview.ts#ORDINAL_AXES` (when UI-bearing)
+- Evaluator critique skepticism and blandness rejection quality applied against the four axes (when UI-bearing)
 - Best-of-history handling and winner selection consistency (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)
@@ -47,21 +47,17 @@
 
 ## Exploration Direction Consistency
 
-<!-- Required for UI-bearing packs. Verifies sidecar-family alignment. -->
+<!-- Required for UI-bearing packs. Verifies brand SSOT and sidecar alignment. -->
 
-- Exploration brief: verify `uiux/30_exploration_brief.md` defines product intent, must-preserve interactions, brand signals, and differentiation targets
-- Evaluation alignment: verify `uiux/33_exploration_rubric.md` and `uiux/34_evaluator_calibration.md` support skeptical evaluation and originality pressure
+- Brand SSOT: verify root `DESIGN.md` defines `brand`, `audience`, and `visual.*` tokens, and that `# Brand Philosophy` body documents product intent, must-preserve interactions, brand signals, and differentiation targets
+- Evaluator axes: confirm reviewers will score against the four canonical UX axes (information architecture / navigation flow / usability / functionality) — these are fixed in `core/prototyping/evaluatorReview.ts#ORDINAL_AXES` and no longer authored as sidecar files
 - History handling: verify `uiux/50_review_input_bundle.md` documents best-of-history comparison instead of latest-only preference
 
 ## Sidecar Artifact Review Scope
 
-<!-- Required for UI-bearing packs. Reviews uiux/ sidecar artifacts. -->
+<!-- Required for UI-bearing packs. Reviews root DESIGN.md + uiux/ sidecar artifacts. -->
 
-- Verify exploration sidecars are present and complete (`30` to `34`, `40`, `50`)
-- Verify `uiux/30_exploration_brief.md` is specific enough to support divergent exploration
-- Verify `uiux/31_reference_pool.md` documents adopted, rejected, and locally translated references
-- Verify `uiux/33_exploration_rubric.md` weights design quality and originality explicitly
-- Verify `uiux/34_evaluator_calibration.md` contains good-critique / too-lenient / blandness-fail / originality-fail examples
+- Verify root `DESIGN.md` is specific enough to support divergent exploration (front-matter populated, `# Brand Philosophy` body written, do/don't and reference notes framed as deviate-from inputs)
 - Verify `uiux/50_review_input_bundle.md` preserves best-of-history handling
 - 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/uiux/00_index.md

@@ -6,27 +6,30 @@ Manifest of all UI/UX sidecar artifacts produced during a UI-bearing discussion.
 
 ## File Inventory
 
-| File                        | Purpose                                      | Required |
-| --------------------------- | -------------------------------------------- | -------- |
-| 00_index.md                 | This manifest                                | Yes      |
-| 30_exploration_brief.md     | Exploration brief and design intent          | Yes      |
-| 31_reference_pool.md        | Exploration references and local translation | Yes      |
-| 32_design_anti_goals.md     | Anti-goals and recurrence prevention         | Yes      |
-| 33_exploration_rubric.md    | Evaluator rubric                             | Yes      |
-| 34_evaluator_calibration.md | Evaluator calibration examples               | Yes      |
-| 40_screen_contracts.md      | Screen interaction contracts (11 fields)     | Yes      |
-| 50_review_input_bundle.md   | Review input bundle                          | Yes      |
+Brand-level intent (product intent, brand signals, anti-goals,
+reference pool framed as deviate-from inputs) lives in root
+`DESIGN.md` (front-matter + `# Brand Philosophy` body), not in this
+sidecar family.
+
+| File                      | Purpose                                  | Required |
+| ------------------------- | ---------------------------------------- | -------- |
+| 00_index.md               | This manifest                            | Yes      |
+| 40_screen_contracts.md    | Screen interaction contracts (11 fields) | Yes      |
+| 50_review_input_bundle.md | Review input bundle                      | Yes      |
 
 ## Completeness Rule
 
-All required files (8 files) MUST be present for a UI-bearing pack. Partial generation is not permitted (BR-0026-0002).
+All required files MUST be present for a UI-bearing pack alongside root
+`DESIGN.md`. Partial generation is not permitted.
 
 ## Forbidden Legacy Files
 
 The following files are NOT part of the canonical family and must NOT be created in new packs:
 
-- `30_option_comparison.md` — replaced by `30_exploration_brief.md`
-- `31_selected_anchor_screen.md` — replaced by `31_reference_pool.md` + `selected-direction.yaml`
+- `30_option_comparison.md` — replaced by root `DESIGN.md`
+- `31_selected_anchor_screen.md` — replaced by root `DESIGN.md`
+- `33_exploration_rubric.md` — replaced by `core/prototyping/evaluatorReview.ts#ORDINAL_AXES`
+- `34_evaluator_calibration.md` — replaced by `core/prototyping/evaluatorReview.ts#ORDINAL_AXES`
 - `40_contracts.md` — replaced by `40_screen_contracts.md`
 - `50_review_bundle.md` — replaced by `50_review_input_bundle.md`
 - `60_critique_loop.md` — removed (critique integrated into review bundle)

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

@@ -6,27 +6,23 @@ Consolidate all sidecar artifacts into a review-ready bundle for design reviewer
 
 ## Bundle Contents
 
-| Artifact                   | Path                               | Status                    |
-| -------------------------- | ---------------------------------- | ------------------------- |
-| Exploration brief          | `uiux/30_exploration_brief.md`     | [draft/reviewed/approved] |
-| Reference pool             | `uiux/31_reference_pool.md`        | [draft/reviewed/approved] |
-| Design anti-goals          | `uiux/32_design_anti_goals.md`     | [draft/reviewed/approved] |
-| Exploration rubric         | `uiux/33_exploration_rubric.md`    | [draft/reviewed/approved] |
-| Evaluator calibration      | `uiux/34_evaluator_calibration.md` | [draft/reviewed/approved] |
-| Screen contracts           | `uiux/40_screen_contracts.md`      | [draft/reviewed/approved] |
-| Prototyping recommendation | `../prototyping.yaml`              | [draft/reviewed/approved] |
+| Artifact                   | Path                          | Status                    |
+| -------------------------- | ----------------------------- | ------------------------- |
+| Brand SSOT (root)          | `DESIGN.md`                   | [draft/reviewed/approved] |
+| Screen contracts           | `uiux/40_screen_contracts.md` | [draft/reviewed/approved] |
+| Prototyping recommendation | `../prototyping.yaml`         | [draft/reviewed/approved] |
 
 ## Trend-derived review focus
 
 - Required references are all present and complete.
 - Stale / overused AI slop patterns are explicitly avoided.
-- Reference research is translated into exploration and evaluator calibration inputs.
+- Reference research is translated into local design decisions on root `DESIGN.md` and screen contracts.
 - Later iterations are not automatically preferred over stronger middle iterations.
 
 ## Review Checklist
 
-- [ ] Exploration brief aligns with surface type and project constraints
+- [ ] Root `DESIGN.md` aligns with surface type and project constraints
 - [ ] Reference pool is complete and translated into local design decisions
-- [ ] Evaluator calibration includes skeptical critique examples
+- [ ] Evaluator scoring covers all four canonical UX axes (information architecture / navigation flow / usability / functionality) — fixed in `core/prototyping/evaluatorReview.ts#ORDINAL_AXES`
 - [ ] Best-of-history handling is explicit
 - [ ] Screen contracts cover all required states

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

@@ -33,19 +33,13 @@ QFAI Skill Body (SSOT)
 
 ## Spec Auto-Discovery Protocol
 
-When no explicit argument is given, detect the candidate spec and constrain execution to one spec only.
-
-### One-Spec-at-a-Time Guarantee
-
-- Auto-discovery selects at most one spec for this run.
-- This protocol does NOT enable multi-spec parallel execution.
-- If multiple candidate specs are detected, do not start implementation until the user selects exactly one spec.
+When no explicit argument is given, detect the candidate spec and constrain execution to one spec only. Auto-discovery selects at most one spec; this protocol does NOT enable multi-spec parallel execution.
 
 ### User Selection Flow
 
-- Single spec detected: announce the detected spec and ask for confirmation when scope is ambiguous.
-- Multiple specs detected: display the candidates and require the user to choose one spec.
-- Zero specs detected: stop and ask the user to provide the target spec explicitly.
+- Single spec: announce the detected spec; ask for confirmation when scope is ambiguous.
+- Multiple specs: display the candidates and require the user to choose one spec.
+- Zero specs: stop and ask the user to provide the target spec explicitly.
 
 ## User Questions (AskUserQuestion Protocol)
 
@@ -75,20 +69,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 spec + contract inputs first whenever implementation touches UI or critique-driven behavior.
-- Read order: `01_Spec.md` → `03_Acceptance-Criteria.md` → `05_Examples.md` →
-  `.qfai/contracts/design/exploration-brief.yaml` →
-  `.qfai/contracts/design/reference-pool.yaml` → `.qfai/contracts/design/brand-design.yaml` →
-  `.qfai/contracts/design/design-system.yaml` (extracted from final iter) →
-  `.qfai/contracts/design/prototype-handoff.yaml` → `.qfai/contracts/ui/*.yaml` →
-  canonical prototype evidence under `.qfai/evidence/prototyping/iter-NN/<screen>.{png,html}` →
-  `.qfai/prototypes/final/index.html`.
+- 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` → root `DESIGN.md` → `.qfai/contracts/design/DESIGN.md.lock.yaml` → `.qfai/contracts/design/design-system.yaml` (post-loop token mirror) → `.qfai/contracts/design/prototype-handoff.yaml` → `.qfai/contracts/ui/*.yaml` → `.qfai/evidence/prototyping/iter-NN/<screen>.{png,html}` → `.qfai/prototypes/final/index.html`.
 - Do not read discussion-pack UI/UX sidecars or fallback mocks.
-- Prototype HTML is analysis input, not production source. Reimplement with project-native
-  patterns while preserving the visual identity captured in `prototype-handoff.yaml`
-  `implementationNotes` (free-form prose).
-- UI-affecting items require product-surface-reviewer prototype parity review before `done`.
-- If code intent and rendered output diverge, treat the rendered/HTML result as the blocking review input and reconcile before DONE.
+- Prototype HTML is analysis input, not production source. Reimplement with project-native patterns while preserving the visual identity captured in `prototype-handoff.yaml` `implementationNotes` (free-form prose).
+- UI-affecting items require product-surface-reviewer prototype parity review before `done`. If code intent and rendered output diverge, treat the rendered/HTML result as the blocking review input and reconcile before DONE.
 
 ## Non-goals
 

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

@@ -1,7 +1,7 @@
 ---
 name: qfai-prototyping
-title: QFAI Prototyping (Single-Thread Design Evolution Loop)
-description: "Iterate one prototype through up to 15 cycles of generate-capture-review with explicit pivot permission, until 4 axes reach exceptional or the budget is exhausted."
+title: QFAI Prototyping (DESIGN.md-driven UX Loop)
+description: "Iterate one prototype through up to 15 cycles of generate-capture-review against a frozen DESIGN.md, focusing on information architecture, navigation flow, usability, and functionality."
 argument-hint: ""
 allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
 roles: [orchestrator, product-experience-architect, product-surface-reviewer, devops-ci-engineer]
@@ -13,79 +13,95 @@ mode: execution-focused
 
 [DRIFT-PROTOCOL:MANDATORY]
 
-This skill runs one prototype through up to 15 iterations. There is no funnel, no parallel candidates, no mode. Iteration count is fixed at 15.
-
-The workflow is static-first and file-based by default. Supported UI prototyping surfaces are: web, mobile, desktop, mixed. `cli` is not a prototyping execution target and is rejected. `ui_bearing: false` specs are excluded from prototyping execution.
+This skill is static-first and file-based by default: it runs one prototype
+through up to 15 iterations against a frozen brand SSOT (`DESIGN.md`), with
+no parallel candidates, no mode, and a fixed 15-cycle budget. Visual identity
+is fixed for the whole run; every cycle improves information architecture,
+navigation flow, usability, and functionality. Supported UI prototyping
+surfaces are: web, mobile, desktop, mixed. cli is not a prototyping
+execution target and is rejected. ui_bearing: false specs are not prototyping
+execution targets and are excluded.
 
 ## Goal
 
-Produce an artifact in which a creative breakthrough has emerged through serial iteration — the kind of self-driven "scrap and reimagine" that arises when the model accumulates enough critique signal that staying on the current path is worse than rebuilding (Anthropic Dutch art museum pattern).
+One final prototype satisfying the spec under a locked brand identity, with all four UX axes `exceptional`, no layout anti-patterns, and no DESIGN.md violations.
 
 ## Required References
 
-- `references/iteration-loop.md` — flow + evidence paths
-- `references/generator-prompt.md` — generator system prompt + pivot permission
-- `references/reviewer-prompt.md` — reviewer output schema + global anti-slop list
-- `references/handoff.md` — design-system extraction + handoff yaml
+- `references/iteration-loop.md` — flow, exit codes, evidence paths
+- `references/generator-prompt.md` — generator system prompt + Tailwind
+  CDN + DESIGN.md token injection rules
+- `references/reviewer-prompt.md` — reviewer schema, 4 UX axes,
+  layout anti-patterns (`lap-001..006` static regex + `lap-007..008` semantic),
+  `designMdViolations`, pivot rules
+- `references/handoff.md` — post-loop `design-system.yaml` (DESIGN.md
+  token mirror) and `prototype-handoff.yaml`
+- `references/design-md-spec.md` — DESIGN.md front-matter schema and
+  validation rules
+- `templates/DESIGN.md.sample` — reference content shipped at the
+  consuming-project root by `qfai init`
 
 ## Required Contracts
 
 - `.qfai/specs/spec-*/{01_Spec.md, 03_Acceptance-Criteria.md}`
 - `.qfai/contracts/ui/*.yaml`
-- `.qfai/contracts/design/exploration-brief.yaml`
-- `.qfai/contracts/design/reference-pool.yaml`
-- `.qfai/contracts/design/brand-design.yaml`
+- root `DESIGN.md`
+- `.qfai/contracts/design/DESIGN.md.lock.yaml`
 
-`reference-pool.yaml` is read as **deviate-from**, not imitate-this.
+The brand identity is governed by root `DESIGN.md`. The lock yaml records
+its sha256 at `/qfai-sdd` Phase 0 freeze. The loop refuses to run if the
+current `DESIGN.md` hash does not match the lock.
 
 ## Required Process
 
 ### Step 2-A — Verify Contract Preconditions
 
-- Confirm the selected spec is UI-bearing and has a supported `surface` value.
-- Confirm `.qfai/contracts/ui/*.yaml` and design contracts exist before generation.
-- Run `qfai prototyping preflight --target-url <url>` or `qfai doctor --profile prototyping`.
+- Confirm the selected spec is UI-bearing and has a supported `surface`.
+- Confirm root `DESIGN.md` and `.qfai/contracts/design/DESIGN.md.lock.yaml`
+  both exist; confirm `.qfai/contracts/ui/*.yaml` exists.
+- Run `qfai prototyping preflight --target-url <url>` (alias for
+  `qfai doctor --profile prototyping`) — verifies DESIGN.md parses and
+  matches the lock sha256.
 
 ### Step 2-B — Verify Environment Preconditions
 
 - Confirm a capture route exists for each declared screen.
-- Use `npx --no-install playwright-cli` or `node_modules/.bin/playwright-cli` when PATH reachability is uncertain.
-
-1. **Seed (cycle 0)**
-   - Run `qfai prototyping iterate --cycle 0 --target-url <url>`.
-   - Generator (product-experience-architect) reads contracts + `references/generator-prompt.md`.
-   - Generator writes `.qfai/prototypes/iter-00/index.html` (one self-contained file).
-   - Capture + review (steps 2-a / 2-b).
-   - Append entry to `prototyping.json#iterations[]`. Commit `prototyping: iter-00`.
-
-2. **Loop (cycle 1..14)**
-   - **(a) Capture** (devops-ci-engineer): playwright-cli writes `iter-NN/<screen>.{png,html}`.
-   - **(b) Review** (product-surface-reviewer): per `references/reviewer-prompt.md`, write `iter-NN/review.json` with 4-axis ordinal scores, 200–500 word prose critique, `slopPatternsDetected[]`, and `pivotDirective`.
-   - **(c) Update** `prototyping.json#iterations[]` and `progress.md`. Commit `prototyping: iter-NN`.
-   - **(d) Iterate**: run `qfai prototyping iterate --cycle <n+1>`.
-     - exit `0` → continue. Generator reads `pivotDirective` and produces iter-(n+1).
-     - exit `64` → all axes exceptional, go to step 3.
-     - exit `65` → 15 cycles reached, go to step 3.
-
-3. **Handoff**
-   - Mirror latest iter to `.qfai/prototypes/final/index.html`.
-   - Per `references/handoff.md`: extract `design-system.yaml`, write `prototype-handoff.yaml`.
-   - Run `qfai prototyping certify`.
-   - Run `qfai validate --profile prototyping --fail-on error` and `/qfai-verify`.
+- Use `npx --no-install playwright-cli` or
+  `node_modules/.bin/playwright-cli` when PATH reachability is uncertain.
+
+### Step 2-C — Run the Loop
+
+| Step   | Actor                                                     | Action                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Output                                   |
+| ------ | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| C0     | product-experience-architect                              | `qfai prototyping iterate --cycle 0 --target-url <url>`. CLI computes `sha256(DESIGN.md)`; lock match enforced. Generator reads contracts + `references/generator-prompt.md` + DESIGN.md tokens and writes `.qfai/prototypes/iter-00/index.html`. Capture + review → `iter-00/review.json`. Append entry; commit `prototyping: iter-00`.                                                                                                                                                                                      | iter-00, prototyping.json#designMdSha256 |
+| C1..14 | (a) devops, (b) reviewer, (c) orchestrator, (d) generator | (a) playwright-cli writes `iter-NN/<screen>.{png,html}`; (b) reviewer writes `iter-NN/review.json` per `references/reviewer-prompt.md` (4 UX axes ordinal, 200..500 word critique, `layoutAntiPatternsDetected[]`, `designMdViolations[]`, `pivotDirective`); (c) update `prototyping.json#iterations[]` + `progress.md`, commit `prototyping: iter-NN`; (d) `qfai prototyping iterate --cycle <n+1>` decides exit.                                                                                                           | iter-NN, exit ∈ {0, 64, 65, 2}           |
+| H      | orchestrator                                              | Mirror latest to `.qfai/prototypes/final/index.html`. Per `references/handoff.md`: write `design-system.yaml` (deterministic DESIGN.md token mirror, no HTML extraction) + `prototype-handoff.yaml`. Run `qfai validate --profile prototyping --fail-on error` (produces `validate.json` with `counts.error === 0`), then `/qfai-verify` (produces `verify.json` with `status === "PASS"`), then `qfai prototyping certify` — certify requires both gate files to be present and passing before it will seal the certificate. | DONE                                     |
+
+**Exit codes**: `0` continue (read `pivotDirective`); `64` convergence (4
+axes `exceptional` AND `layoutAntiPatternsDetected` empty AND
+`designMdViolations` empty); `65` 15 cycles reached; `2` input error
+(incl. DESIGN.md hash mismatch — re-run prototyping from cycle 0 after
+editing `DESIGN.md` and refreezing the lock via `/qfai-sdd` Phase 0).
 
 ## Evaluator Inputs (Mandatory)
 
 - Screenshot evidence path: `.qfai/evidence/prototyping/iter-NN/<screen>.png`
 - HTML snapshot path: `.qfai/evidence/prototyping/iter-NN/<screen>.html`
-- Review inputs: latest screenshot, latest HTML snapshot, prior `review.json` files, `progress.md`, and `reference-pool.yaml` as deviate-from input.
+- Review inputs: latest screenshot, latest HTML snapshot, prior
+  `review.json` files, `progress.md`, root `DESIGN.md` (read-only),
+  `axisDefs`, `previousScore`, `designSystemChecklist`.
 
 ## Critical Constraints
 
-- DO NOT generate parallel candidates. One lineage only.
-- DO NOT preserve elements out of caution; the latest iter is always accepted.
-- DO NOT declare DONE before `qfai prototyping certify --check` returns 0.
-- DO NOT add `mode/round/polish/branch/concept-fit/design-system-compliance` artifacts.
-- DO NOT score similarity to `reference-pool` positively; it is deviate-from input.
+- One lineage only — no parallel candidates, no best-of-history; the
+  latest iter is always accepted.
+- `DESIGN.md` is frozen for the run; to change it, edit + rerun
+  `/qfai-sdd` to refreeze + start cycle 0.
+- Token-only colors / fonts / radii / shadows — non-DESIGN.md hex / rgb /
+  rgba / hsl / font / radius / shadow values are recorded in
+  `designMdViolations[]` and block exit 64.
+- DONE only when `qfai prototyping certify --check` returns 0.
+- No `mode / round / polish / branch / concept-fit` artifacts.
 
 ## Delegation Scope Table
 
@@ -99,11 +115,16 @@ Produce an artifact in which a creative breakthrough has emerged through serial
 
 - Check Drift Protocol compliance before DONE.
 - Check `.qfai/assistant/steering/test-layers.md` alignment.
-- Treat reviewer findings as signals, not gates, unless certify/validate/verify fails.
+- Treat reviewer findings as signals, not gates, unless
+  certify/validate/verify fails.
 
 ## Completion
 
-DONE = `completion-certificate.json` exists AND `qfai prototyping certify --check` returns 0 AND `/qfai-verify` returns PASS.
+DONE = `completion-certificate.json` exists AND
+`qfai prototyping certify --check` returns 0 AND `/qfai-verify` returns
+PASS.
+
+Follow `.qfai/assistant/instructions/shared-skill-operating-baseline.md#gate-failure-autorepair-protocol` for validate, doctor, and quality-gate failures.
 
 ## Next