qfai 1.9.2 → 1.10.0

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

@@ -2,7 +2,15 @@
 
 ## User Stories
 
-### US-001: <Story Title>
+> Discussion-layer IDs use the `D` prefix (`DUS-`, `DAC-`) so they can never be read as
+> spec-layer IDs (`US-0001`, `AC-0001`) or as a traceability scenario tag (`SC-NNNN-NNNN`).
+> Carry these IDs into the spec layer as `<pack-id>#<discussion-id>`: the `- Source:` line of
+> the matching `## US-NNNN` block in `qfai-sdd/templates/specs/spec/02_User-stories.md`, and
+> the `# Source:` comment inside the AC's Gherkin block in `03_Acceptance-Criteria.md`. The
+> AC Catalog table has no `Source` column — provenance lives in the required Gherkin block so
+> a spec that omits the optional catalog still carries it.
+
+### DUS-001: <Story Title>
 
 - As a: <role>
 - I want: <action>
@@ -10,8 +18,8 @@
 
 #### Acceptance Criteria
 
-- AC-001-01:
-- AC-001-02:
+- DAC-001-01:
+- DAC-001-02:
 
 #### Example Seeds
 

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/05_Scope.md

@@ -20,10 +20,13 @@
 
 ## Success Criteria
 
+> IDs use the `DSC-` prefix. Bare `SC-NNNN-NNNN` is reserved for the traceability
+> scenario tag (`QFAI:SC-...`) and must not be used for a success criterion.
+
 | Criterion | Measurement | Target  | Priority |
 | --------- | ----------- | ------- | -------- |
-| SC-001    | <metric>    | <value> | must     |
-| SC-002    | <metric>    | <value> | should   |
+| DSC-001   | <metric>    | <value> | must     |
+| DSC-002   | <metric>    | <value> | should   |
 
 ## Assumptions
 

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/07_NFR.md

@@ -1,6 +1,6 @@
 # 07 NFR (Non-Functional Requirements)
 
-<!-- UX-INTENT: If UI-bearing, see uiux/20_design_eval_invariant.md for usability measurement targets -->
+<!-- UX-INTENT: If UI-bearing, see uiux/40_screen_contracts.md for usability measurement targets -->
 
 ## Requirements Table
 

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/09_Constraints.md

@@ -1,12 +1,15 @@
 # 09 Constraints
 
-<!-- UX-INTENT: If UI-bearing, see uiux/20_design_eval_invariant.md for accessibility constraints (invariant layer) -->
+<!-- UX-INTENT: If UI-bearing, see root DESIGN.md (top-level `accessibility`) and uiux/40_screen_contracts.md for accessibility constraints -->
 
 ## Technical Constraints
 
-| ID   | Constraint | Rationale | Impact |
-| ---- | ---------- | --------- | ------ |
-| TC-1 | TBD        | TBD       | TBD    |
+> IDs use the `DTC-` prefix. Bare `TC-NNNN` is the spec-layer Test Case ID and must not
+> be used for a technical constraint.
+
+| ID    | Constraint | Rationale | Impact |
+| ----- | ---------- | --------- | ------ |
+| DTC-1 | TBD        | TBD       | TBD    |
 
 ## Operational Constraints
 

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

@@ -1,6 +1,6 @@
 # 10 Policy
 
-<!-- UX-INTENT: If UI-bearing, see uiux/10_implementation_strategy.md for design policy alignment -->
+<!-- UX-INTENT: If UI-bearing, see root DESIGN.md for design policy alignment (brand SSOT) -->
 
 ## Security Policy
 

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/11_OQ-Register.md

@@ -1,6 +1,6 @@
 # 11 OQ Register
 
-<!-- UX-INTENT: If UI-bearing, track design direction OQs from uiux/30_option_comparison.md and uiux/31_selected_anchor_screen.md -->
+<!-- UX-INTENT: If UI-bearing, track design direction OQs against root DESIGN.md and uiux/40_screen_contracts.md -->
 
 ## OQ Table
 

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/12_OQ-Resolution-Log.md

@@ -1,6 +1,6 @@
 # 12 OQ Resolution Log
 
-<!-- UX-INTENT: If UI-bearing, log design critique resolutions from uiux/30_option_comparison.md and uiux/31_selected_anchor_screen.md -->
+<!-- UX-INTENT: If UI-bearing, log design critique resolutions from uiux/50_review_input_bundle.md -->
 
 ## Resolution Timeline
 

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

@@ -4,7 +4,13 @@
 
 - scope: `discussion-YYYYMMDDhhmmssSSS`
 - layer: `discussion`
-- review-pack: `review-YYYYMMDDhhmmssSSS`
+- review-pack: `assigned per review cycle` — see `.qfai/review/`
+
+<!-- Do NOT record a single review-pack id here. `references/review-cycle-playbook.md`
+     requires a new review pack per cycle, so one discussion pack is reviewed by N packs.
+     The authoritative pointer for a given cycle is that pack's own
+     `.qfai/review/review-<id>/review_request.md#Scope`, which names the directory that
+     contains it. -->
 
 ## Target Files
 
@@ -35,11 +41,12 @@
   - 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 (when UI-bearing)
-- Reference pool freshness and translation quality into `DESIGN.md` (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 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)
+- 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 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)
+- 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)
 - Generic fallback risk — ensure no unreviewed generic/placeholder UI remains (when UI-bearing)
 - OQ register exit condition (open count = 0)
@@ -51,14 +58,14 @@
 
 - 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
+- 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. -->
 
 - 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 `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
 
 ## Required Reviewers
@@ -67,7 +74,7 @@
 - Always run reviewers listed in `profiles.<routing_profile>.always_required` in `review-profiles.yml`.
 - Add `architecture-reviewer` only when architecture-affecting decisions exist.
 - Add `product-surface-reviewer` only when the pack is UI-bearing.
-- Allowed verdicts: `PASS`, `FAIL`.
+- Allowed in-flight verdicts: `PASS`, `REVISE`. `REVISE` is what starts the fix-and-rerun cycle; it serializes to `status: "FAIL"` when the pack's `summary.json` is written (see `.qfai/assistant/constitution/shared-skill-delegation-baseline.md#verdict-vocabulary`).
 
 ## RCP Rules (Mandatory)
 

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/99_delta.md

@@ -1,6 +1,6 @@
 # 99 Delta
 
-<!-- UX-INTENT: If UI-bearing, record design direction changes from uiux/30_option_comparison.md and uiux/31_selected_anchor_screen.md -->
+<!-- UX-INTENT: If UI-bearing, record design direction changes against root DESIGN.md and uiux/40_screen_contracts.md -->
 
 ## Change History
 

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

@@ -2,7 +2,7 @@
 
 - reviewer_id: `Rxx`
 - reviewer_role: `<reviewer-name>`
-- verdict: `PASS` <!-- PASS | FAIL -->
+- Result: `PASS` <!-- PASS | REVISE -->
 - reviewed_at: `YYYY-MM-DDThh:mm:ssZ`
 
 ## Checked
@@ -13,11 +13,14 @@
 - [ ] Clarity and actionability
 - [ ] 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 evidence traceability (when UI-bearing)
-- [ ] 3-layer evaluation quality and traceability (when UI-bearing)
-- [ ] Option comparison integrity and selected anchor clarity (when UI-bearing)
-- [ ] Strong screen contract completeness (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 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)
+- [ ] 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 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)
+- [ ] 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
 
@@ -27,4 +30,10 @@
 
 ## Decision
 
-- PASS / FAIL
+- PASS / REVISE
+
+> In-flight reviewer responses use `PASS` / `REVISE`, per
+> `.qfai/assistant/constitution/shared-skill-delegation-baseline.md#reviewer-response-template`.
+> A `REVISE` verdict maps to `status: "FAIL"` when the review pack's `summary.json` is written
+> — see `.qfai/assistant/constitution/shared-skill-delegation-baseline.md#verdict-vocabulary`.
+> Do not invent a third verdict.

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

@@ -22,11 +22,14 @@
   - 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)
-- Taste interview completeness and clarity (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 anchor clarity (when UI-bearing)
-- Strong screen contract completeness (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 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)
+- 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 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)
+- 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 in `13_Deferred.md`
 - Validate hard gate evidence exists (`.qfai/report/validate.log`).
@@ -37,7 +40,7 @@
 - Resolve reviewers from `.qfai/assistant/manifest/agent-routing.yml` and `.qfai/assistant/manifest/review-profiles.yml`.
 - Always run reviewers listed in `profiles.<routing_profile>.always_required` in `review-profiles.yml`.
 - Add conditional reviewers according to `conditional_required` and related routing rules defined in `agent-routing.yml` and `review-profiles.yml` (do not introduce additional ad-hoc conditions in this template).
-- Allowed verdicts: `PASS`, `FAIL`.
+- Allowed in-flight verdicts: `PASS`, `REVISE`. `REVISE` is what starts the fix-and-rerun cycle; it serializes to `status: "FAIL"` when the pack's `summary.json` is written (see `.qfai/assistant/constitution/shared-skill-delegation-baseline.md#verdict-vocabulary`).
 
 ## RCP Rules (Mandatory)
 

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

@@ -40,5 +40,6 @@ Draft interaction contracts for key screens using the strong screen contract sch
 
 ## Cross-references
 
-- Selected anchor: `31_selected_anchor_screen.md`
-- Option comparison: `30_option_comparison.md`
+- Brand SSOT (product intent, brand signals, anti-goals): root `DESIGN.md`
+- 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

@@ -17,12 +17,14 @@ Consolidate all sidecar artifacts into a review-ready bundle for design reviewer
 - 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.
-- Later iterations are not automatically preferred over stronger middle iterations.
+- 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
 - [ ] 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`
-- [ ] Best-of-history handling is explicit
+- [ ] One-lineage handling is explicit (latest iteration accepted; no best-of-history)
 - [ ] Screen contracts cover all required states