qfai 1.10.0 → 1.10.2

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

@@ -12,6 +12,40 @@
 - `secondary`: Derived information (summaries, analyses).
 - `external`: Third-party references (specs, RFCs, vendor docs).
 
+## Research Summary
+
+Research-First Protocol output. Schema: `constitution/research-first-protocol.md`.
+Replace every `[...]` placeholder with real research: validation rejects
+bracketed `title` / `url` / `reason` values and requires `published` to be a
+real `YYYY-MM-DD` date, so an unfilled block below reports errors rather than
+passing.
+
+```yaml
+research_summary:
+  sources:
+    - id: SRC-0001
+      title: [Source title]
+      url: [https://example.com/reference]
+      published: [YYYY-MM-DD]
+  best_practices:
+    - id: BP-0001
+      category: [Category]
+      title: [Best practice title]
+      description: [What to do and why]
+      source_id: SRC-0001
+  anti_patterns:
+    - id: AP-0001
+      category: [Category]
+      title: [Anti-pattern title]
+      description: [What to avoid and why]
+      source_id: SRC-0001
+  reflection:
+    - source_id: SRC-0001
+      finding: [What the source implies for this project]
+      action: apply
+      reason: [Why this action was chosen]
+```
+
 ## Trend Scan
 
 ### user expectation / market norm
@@ -62,7 +96,7 @@
 - reference: [Source name or URL]
 - observation: [What color trend or signal was observed]
 - decision_connection: [How the color signal translates into this project]
-- evaluation_connection: [Which TRD-XX axis evaluates this color signal; leave blank to trigger UIX-VAL-T01]
+- evaluation_connection: [How the color signal should be evaluated in design review]
 - local_implication: [What color choices should change locally]
 
 ### typography
@@ -73,7 +107,7 @@
 - reference: [Source name or URL]
 - observation: [What typographic trend or signal was observed]
 - decision_connection: [How the typography signal translates into this project]
-- evaluation_connection: [Which TRD-XX axis evaluates this typography signal; leave blank to trigger UIX-VAL-T01]
+- evaluation_connection: [How the typography signal should be evaluated in design review]
 - local_implication: [What typeface or scale choices should change locally]
 
 ### Visual
@@ -84,7 +118,7 @@
 - reference: [Source name or URL]
 - observation: [What visual motif trend or signal was observed]
 - decision_connection: [How the visual motif translates into this project]
-- evaluation_connection: [Which TRD-XX axis evaluates this visual motif; leave blank to trigger UIX-VAL-T01]
+- evaluation_connection: [How the visual motif should be evaluated in design review]
 - local_implication: [What visual motif choices should change locally]
 
 ### spacing
@@ -95,7 +129,7 @@
 - reference: [Source name or URL]
 - observation: [What spacing convention or density trend was observed]
 - decision_connection: [How the spacing signal translates into this project]
-- evaluation_connection: [Which TRD-XX axis evaluates this spacing signal; leave blank to trigger UIX-VAL-T01]
+- evaluation_connection: [How the spacing signal should be evaluated in design review]
 - local_implication: [What spacing or density choices should change locally]
 
 ### shape
@@ -106,7 +140,7 @@
 - reference: [Source name or URL]
 - observation: [What shape language trend was observed (border-radius, geometric vs organic, etc.)]
 - decision_connection: [How the shape language translates into this project]
-- evaluation_connection: [Which TRD-XX axis evaluates this shape signal; leave blank to trigger UIX-VAL-T01]
+- evaluation_connection: [How the shape signal should be evaluated in design review]
 - local_implication: [What shape-language choices should change locally]
 
 ### imagery
@@ -117,7 +151,7 @@
 - reference: [Source name or URL]
 - observation: [What imagery or illustration style trend was observed]
 - decision_connection: [How the imagery signal translates into this project]
-- evaluation_connection: [Which TRD-XX axis evaluates this imagery signal; leave blank to trigger UIX-VAL-T01]
+- evaluation_connection: [How the imagery signal should be evaluated in design review]
 - local_implication: [What imagery or illustration choices should change locally]
 
 ### design_guideline_research

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

@@ -41,10 +41,10 @@
   - Acceptance criteria are consistent with flows/state transitions
   - Security/operations risks are reflected in diagrams where relevant
 - Mermaid diagrams use ` ```mermaid ` fences only
-- Root `DESIGN.md` completeness and differentiation clarity — it parses, and its `# Brand Philosophy` body carries do/don't, brand signals, and exploration references framed as **deviate-from** inputs (when UI-bearing)
-- Reference pool freshness and translation quality into `DESIGN.md`, and Trend Scan freshness and evidence traceability at `04_Sources.md#Trend Scan` (when UI-bearing)
+- Root `DESIGN.md` completeness and differentiation clarity — it parses, and its `# Brand Philosophy` body carries do/don't, brand signals, and exploration references framed as **deviate-from** inputs (when a visual-prototyping surface — `web`/`mobile`/`desktop`/`mixed` — is classified as primary or secondary; a cli-only pack authors no root `DESIGN.md`, so skip this line for it)
+- Reference pool freshness and translation quality — into root `DESIGN.md` when a visual-prototyping surface is classified, otherwise into `uiux/40_screen_contracts.md` — and Trend Scan freshness and evidence traceability at `04_Sources.md#Trend Scan` (when UI-bearing)
 - Canonical `uiux/` family complete — `00_index.md`, `40_screen_contracts.md`, `50_review_input_bundle.md` — with no forbidden legacy sidecar (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 scoring covers all four canonical UX axes — information architecture / navigation flow / usability / functionality, fixed by the review validation the QFAI CLI applies (restated in `.qfai/assistant/skills/qfai-prototyping/references/reviewer-prompt.md`) (when UI-bearing)
 - Evaluator critique skepticism and blandness rejection quality applied against the four axes (when UI-bearing)
 - Planner-first discipline — exploration directions stay unranked, no single visual winner was selected (`qfai-discussion/SKILL.md`), and latest-iteration handling matches the one-lineage / no-best-of-history rule in `qfai-prototyping/SKILL.md` (when UI-bearing)
 - Screen contract sufficiency and strong schema completeness (when UI-bearing)
@@ -56,15 +56,15 @@
 
 <!-- Required for UI-bearing packs. Verifies brand SSOT and sidecar alignment. -->
 
-- 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
+- Brand SSOT (skip on a cli-only pack; required as soon as `web`/`mobile`/`desktop`/`mixed` appears as primary or secondary surface): 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 by the review validation the QFAI CLI applies (restated in `.qfai/assistant/skills/qfai-prototyping/references/reviewer-prompt.md`) and no longer authored as sidecar files
 - History handling: verify `uiux/50_review_input_bundle.md` matches the one-lineage rule in `qfai-prototyping/SKILL.md` — no parallel candidates, no best-of-history, the latest iteration is accepted
 
 ## Sidecar Artifact Review Scope
 
-<!-- Required for UI-bearing packs. Reviews root DESIGN.md + uiux/ sidecar artifacts. -->
+<!-- Required for UI-bearing packs. Reviews root DESIGN.md (visual-prototyping surfaces) + uiux/ sidecar artifacts (every UI-bearing surface, cli included). -->
 
-- 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 root `DESIGN.md` is specific enough (skip on a cli-only pack, which authors none) 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` states the one-lineage handling (latest iteration accepted, no best-of-history)
 - 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

@@ -13,10 +13,10 @@
 - [ ] Clarity and actionability
 - [ ] Mermaid diagrams are sufficient for decisions (scope/AC/risk consistency)
 - [ ] Mermaid diagrams use ` ```mermaid ` fences only
-- [ ] Root `DESIGN.md` completeness and differentiation clarity — it parses, and its `# Brand Philosophy` body carries do/don't, brand signals, and exploration references framed as **deviate-from** inputs (when UI-bearing)
-- [ ] Reference pool freshness and translation quality into `DESIGN.md`, and Trend Scan freshness and evidence traceability at `04_Sources.md#Trend Scan` (when UI-bearing)
+- [ ] Root `DESIGN.md` completeness and differentiation clarity — it parses, and its `# Brand Philosophy` body carries do/don't, brand signals, and exploration references framed as **deviate-from** inputs (when a visual-prototyping surface — `web`/`mobile`/`desktop`/`mixed` — is classified as primary or secondary; a cli-only pack authors no root `DESIGN.md`, so skip this line for it)
+- [ ] Reference pool freshness and translation quality — into root `DESIGN.md` when a visual-prototyping surface is classified, otherwise into `uiux/40_screen_contracts.md` — and Trend Scan freshness and evidence traceability at `04_Sources.md#Trend Scan` (when UI-bearing)
 - [ ] Canonical `uiux/` family complete — `00_index.md`, `40_screen_contracts.md`, `50_review_input_bundle.md` — with no forbidden legacy sidecar (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 scoring covers all four canonical UX axes — information architecture / navigation flow / usability / functionality, fixed by the review validation the QFAI CLI applies (restated in `.qfai/assistant/skills/qfai-prototyping/references/reviewer-prompt.md`) (when UI-bearing)
 - [ ] Evaluator critique skepticism and blandness rejection quality applied against the four axes (when UI-bearing)
 - [ ] Planner-first discipline — exploration directions stay unranked, no single visual winner was selected (`qfai-discussion/SKILL.md`), and latest-iteration handling matches the one-lineage / no-best-of-history rule in `qfai-prototyping/SKILL.md` (when UI-bearing)
 - [ ] Screen contract sufficiency and strong schema completeness (when UI-bearing)

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

@@ -2,6 +2,7 @@
 
 ## Scope
 
+- Producer: `discussion`
 - scope: `discussion-YYYYMMDDhhmmssSSS`
 - layer: `discussion`
 - review-pack: `review-YYYYMMDDhhmmssSSS`
@@ -22,10 +23,10 @@
   - Acceptance criteria are consistent with flows/state transitions
   - Security/operations risks are reflected in diagrams where relevant
 - Mermaid diagrams use ` ```mermaid ` fences only (no ` ```text ` or language-less fences)
-- Root `DESIGN.md` completeness and differentiation clarity — it parses, and its `# Brand Philosophy` body carries do/don't, brand signals, and exploration references framed as **deviate-from** inputs (when UI-bearing)
-- Reference pool freshness and translation quality into `DESIGN.md`, and Trend Scan freshness and evidence traceability at `04_Sources.md#Trend Scan` (when UI-bearing)
+- Root `DESIGN.md` completeness and differentiation clarity — it parses, and its `# Brand Philosophy` body carries do/don't, brand signals, and exploration references framed as **deviate-from** inputs (when a visual-prototyping surface — `web`/`mobile`/`desktop`/`mixed` — is classified as primary or secondary; a cli-only pack authors no root `DESIGN.md`, so skip this line for it)
+- Reference pool freshness and translation quality — into root `DESIGN.md` when a visual-prototyping surface is classified, otherwise into `uiux/40_screen_contracts.md` — and Trend Scan freshness and evidence traceability at `04_Sources.md#Trend Scan` (when UI-bearing)
 - Canonical `uiux/` family complete — `00_index.md`, `40_screen_contracts.md`, `50_review_input_bundle.md` — with no forbidden legacy sidecar (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 scoring covers all four canonical UX axes — information architecture / navigation flow / usability / functionality, fixed by the review validation the QFAI CLI applies (restated in `.qfai/assistant/skills/qfai-prototyping/references/reviewer-prompt.md`) (when UI-bearing)
 - Evaluator critique skepticism and blandness rejection quality applied against the four axes (when UI-bearing)
 - Planner-first discipline — exploration directions stay unranked, no single visual winner was selected (`qfai-discussion/SKILL.md`), and latest-iteration handling matches the one-lineage / no-best-of-history rule in `qfai-prototyping/SKILL.md` (when UI-bearing)
 - Screen contract sufficiency and strong schema completeness (when UI-bearing)

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/review/summary.json

@@ -1,6 +1,9 @@
 {
   "version": "2.0",
+  "revision_form": "content-hash",
+  "revision": "<git rev, or working-tree+<content hash>>",
   "created_at": "YYYY-MM-DDThh:mm:ssZ",
+  "producer": "discussion",
   "target": {
     "kind": "discussion",
     "path": ".qfai/discussion/discussion-YYYYMMDDhhmmssSSS"

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/00_index.md

@@ -9,7 +9,9 @@ Manifest of all UI/UX sidecar artifacts produced during a UI-bearing discussion.
 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.
+sidecar family — on a visual-prototyping surface (`web`, `mobile`,
+`desktop`, `mixed`). A cli-only pack has no root `DESIGN.md` at all,
+so it has no brand-level intent layer either.
 
 | File                      | Purpose                                  | Required |
 | ------------------------- | ---------------------------------------- | -------- |
@@ -19,8 +21,15 @@ sidecar family.
 
 ## Completeness Rule
 
-All required files MUST be present for a UI-bearing pack alongside root
-`DESIGN.md`. Partial generation is not permitted.
+All three required files above MUST be present for every UI-bearing pack.
+Partial generation is not permitted.
+
+Root `DESIGN.md` sits alongside them **only** on a visual-prototyping surface
+(`web`, `mobile`, `desktop`, `mixed`). A cli-only pack — `primary_surface: cli`
+with no visual surface in `secondary_surfaces` — is complete without it:
+`/qfai-discussion` authors no root `DESIGN.md` for such a pack, `/qfai-sdd`
+Phase 0 skips the freeze, and `/qfai-prototyping` does not run on `cli`. Do not
+report a cli-only pack as incomplete for a missing `DESIGN.md`.
 
 ## Forbidden Legacy Files
 
@@ -28,8 +37,8 @@ The following files are NOT part of the canonical family and must NOT be created
 
 - `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`
+- `33_exploration_rubric.md` — replaced by the fixed evaluator axes (`.qfai/assistant/skills/qfai-prototyping/references/reviewer-prompt.md`)
+- `34_evaluator_calibration.md` — replaced by the fixed evaluator axes (`.qfai/assistant/skills/qfai-prototyping/references/reviewer-prompt.md`)
 - `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/40_screen_contracts.md

@@ -4,6 +4,22 @@
 
 Draft interaction contracts for key screens using the strong screen contract schema (11 required fields).
 
+`route:` is required on every surface — `validators/uix/screenContract.ts` demands a
+non-empty string, not a URL — but what it names is surface-specific. Record the real
+navigation identifier for the surface you are on; never invent a URL for a product that
+has none:
+
+| Surface            | `route:` names                                                         | Example                  |
+| ------------------ | ---------------------------------------------------------------------- | ------------------------ |
+| `web`              | URL path                                                               | `/orders/:id`            |
+| `mobile` (native)  | navigation destination, or the deep link when one exists               | `OrderDetail`            |
+| `desktop` (native) | window / view identifier, or the app-scheme deep link                  | `main:order-detail`      |
+| `cli`              | command invocation                                                     | `myapp deploy --dry-run` |
+| `mixed`            | the identifier of the surface that owns the screen, per the rows above | `/orders/:id`            |
+
+Use one convention per surface consistently across the whole file so downstream
+`.qfai/contracts/ui/*.yaml` normalization stays deterministic.
+
 ### Screen: [Screen Name]
 
 - screen_id: SCR-001
@@ -40,6 +56,6 @@ Draft interaction contracts for key screens using the strong screen contract sch
 
 ## Cross-references
 
-- Brand SSOT (product intent, brand signals, anti-goals): root `DESIGN.md`
+- Brand SSOT (product intent, brand signals, anti-goals): root `DESIGN.md` — visual-prototyping surfaces only; a cli-only pack has none
 - Sidecar manifest: `00_index.md`
 - Review handoff: `50_review_input_bundle.md`

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

@@ -4,27 +4,32 @@
 
 Consolidate all sidecar artifacts into a review-ready bundle for design reviewers.
 
+A **cli-only** pack (`primary_surface: cli`, no visual `secondary_surfaces` entry) still
+ships this bundle. It has no root `DESIGN.md` and no `prototyping.yaml`, so mark those two
+rows `n-a: cli-only pack` rather than leaving the bundle incomplete — see
+`references/ui-bearing-playbook.md#visual-prototyping-surfaces-vs-cli`.
+
 ## Bundle Contents
 
-| 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] |
+| Artifact                   | Path                          | Status                                         |
+| -------------------------- | ----------------------------- | ---------------------------------------------- |
+| Brand SSOT (root)          | `DESIGN.md`                   | [draft/reviewed/approved / n-a: cli-only pack] |
+| Screen contracts           | `uiux/40_screen_contracts.md` | [draft/reviewed/approved]                      |
+| Prototyping recommendation | `../prototyping.yaml`         | [draft/reviewed/approved / n-a: cli-only pack] |
 
 ## Trend-derived review focus
 
 - Required references are all present and complete.
 - Stale / overused AI slop patterns are explicitly avoided.
-- Reference research is translated into local design decisions on root `DESIGN.md` and screen contracts.
+- Reference research is translated into local design decisions on root `DESIGN.md` (visual-prototyping surfaces) and on screen contracts (every UI-bearing surface). A cli-only pack has no root `DESIGN.md`: the screen contracts carry the whole translation.
 - Iteration handling follows the one-lineage rule in `qfai-prototyping/SKILL.md`: no parallel
   candidates and no best-of-history — the latest iteration is the accepted one. A middle iteration
   that looked stronger is addressed by pivoting the next cycle, not by reaching back for it.
 
 ## Review Checklist
 
-- [ ] Root `DESIGN.md` aligns with surface type and project constraints
+- [ ] Root `DESIGN.md` aligns with surface type and project constraints (skip on a cli-only pack, which authors none)
 - [ ] Reference pool is complete and translated into local design decisions
-- [ ] Evaluator scoring covers all four canonical UX axes (information architecture / navigation flow / usability / functionality) — fixed in `core/prototyping/evaluatorReview.ts#ORDINAL_AXES`
+- [ ] Evaluator scoring covers all four canonical UX axes (information architecture / navigation flow / usability / functionality) — fixed by the review validation the QFAI CLI applies (restated in `.qfai/assistant/skills/qfai-prototyping/references/reviewer-prompt.md`)
 - [ ] One-lineage handling is explicit (latest iteration accepted; no best-of-history)
 - [ ] Screen contracts cover all required states