qfai 1.6.5 → 1.7.1

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

@@ -108,6 +108,24 @@ Every major artifact in this stage MUST include this table schema:
 - `02_Inception-Deck.md` MUST contain at least one Mermaid diagram in ` ```mermaid ` fences.
 - `03_Story-Workshop.md` MUST contain at least one Mermaid diagram in ` ```mermaid ` fences.
 - If UI requirements exist, include an HTML+CSS visual mock in `03_Story-Workshop.md`.
+- **UI-bearing Authoring Requirements**:
+  - A pack is UI-bearing if `03_Story-Workshop.md` contains HTML tags (`<style>`, `<div>`, etc.) or Mermaid screen flow diagrams.
+  - UI-bearing packs MUST include a `## Design Direction Summary` section in `03_Story-Workshop.md` with all 6 subsections:
+    1. `### Option Comparison` — 2+ distinct design options (QFAI-DDP-020)
+    2. `### Anchor Screen Selection` — explicit selection referencing a compared option (QFAI-DDP-021)
+    3. `### Competitive References` — summary referencing 04_Sources.md (QFAI-DDP-022 validates 04_Sources.md fields)
+    4. `### CTA Hierarchy` — must define at least a primary CTA (QFAI-DDP-023)
+    5. `### State Coverage` — must define empty, loading, error, populated states (QFAI-DDP-024)
+    6. `### Design Anti-goals` — 1+ patterns to intentionally avoid (QFAI-DDP-025)
+  - `04_Sources.md` must include a `## Competitive Reference Registry` with entries containing:
+    - `adopted_points`: what was adopted and why
+    - `rejected_points`: what was not adopted and why
+    - `local_translation`: how adopted points were adapted
+    - Placeholder values (TBD, N/A, TODO, empty) are treated as missing (QFAI-DDP-022)
+  - `14_Review-Request.md` must include a `## Design Direction Decisions` section with anchor, rejections, and adopted refs.
+  - `99_delta.md` must include a `## Rejected Visual Directions` section with rationale and recurrence prevention.
+  - All 7 validators (QFAI-DDP-019..025) emit `severity: error` — violations block validation.
+  - Non-UI packs are exempt from all DDS validators (zero new issues).
 - Review roster is fixed by `.qfai/assistant/steering/review-roster.yml` and must be executed in full.
 - RCP wording must be sourced from `.qfai/assistant/skills/qfai-discussion/references/rcp_footer.md`.
 - Discussion artifacts are logs/rationale and must not duplicate spec SSOT.

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

@@ -65,3 +65,48 @@ flowchart TD
   border-radius: 12px;
 }
 ```
+
+## Design Direction Summary
+
+<!-- Required for UI-bearing packs. Validated by QFAI-DDP-019..025. -->
+
+### Option Comparison
+
+<!-- List 2+ design options. Each must be a separate entry. (QFAI-DDP-020) -->
+
+- **Option A**: [Name and description]
+- **Option B**: [Name and description]
+
+### Anchor Screen Selection
+
+<!-- Select one of the compared options as the anchor. (QFAI-DDP-021) -->
+
+Selected: [Option X] — [Reason for selection]
+
+### Competitive References
+
+<!-- Summarize competitive references from 04_Sources.md. (QFAI-DDP-022) -->
+
+See 04_Sources.md for full competitive reference registry.
+
+### CTA Hierarchy
+
+<!-- Define CTA hierarchy with at least a primary CTA. (QFAI-DDP-023) -->
+
+- Primary: [CTA label and placement]
+- Secondary: [CTA label and placement]
+
+### State Coverage
+
+<!-- Define all 4 required states. (QFAI-DDP-024) -->
+
+- empty: [Empty state display]
+- loading: [Loading state display]
+- error: [Error state display]
+- populated: [Populated state display]
+
+### Design Anti-goals
+
+<!-- List 1+ design patterns to intentionally avoid. (QFAI-DDP-025) -->
+
+- Anti-goal: [Pattern to avoid and reason]

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

@@ -12,6 +12,16 @@
 - `secondary`: Derived information (summaries, analyses).
 - `external`: Third-party references (specs, RFCs, vendor docs).
 
+## Competitive Reference Registry
+
+<!-- Required for UI-bearing packs. Each entry must have all 3 fields populated. (QFAI-DDP-022) -->
+
+### Reference: [Product/Service Name]
+
+- adopted_points: [What was adopted from this reference and why]
+- rejected_points: [What was not adopted and why]
+- local_translation: [How adopted points were adapted for this project]
+
 ## Traceability
 
 - Each REQ/NFR should reference at least one SRC-ID.

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

@@ -40,6 +40,14 @@
 - OQ register exit condition (open count = 0)
 - Deferred items have full metadata
 
+## Design Direction Decisions
+
+<!-- Required for UI-bearing packs. Populated from DDS in 03_Story-Workshop.md. -->
+
+- Anchor screen: [Selected option reference]
+- Rejection rationale: [Why other options were not selected]
+- Adopted competitive references: [Key references adopted from 04_Sources.md]
+
 ## Required Reviewers
 
 - Load all reviewers from `.qfai/assistant/steering/review-roster.yml`.

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

@@ -19,6 +19,14 @@
 | ---------- | ------- | --------------- | ------ | --------------------- |
 | YYYY-MM-DD | OQ-0001 | Option B        | TBD    | TBD                   |
 
+## Rejected Visual Directions
+
+<!-- Required for UI-bearing packs when visual directions are rejected. -->
+
+| Date       | Direction      | Rationale | Recurrence Prevention |
+| ---------- | -------------- | --------- | --------------------- |
+| YYYY-MM-DD | [Option/Style] | [Why]     | [How to prevent]      |
+
 ## Drift Events
 
 | Date       | Trigger | Impact Assessment | Files Updated |

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

@@ -45,6 +45,13 @@ QFAI Skill Body (SSOT)
 
 Execute the TDD micro-cycle for each pending item in `test-list.md`, transitioning each through Red -> Green -> Refactor -> Done, producing tested production code aligned with the spec.
 
+## Visual Review Guard
+
+- Review rendered output, screenshot evidence, or HTML output before closing any UI-affecting item.
+- Read the DDP (Design Direction Pack) first whenever implementation touches UI or critique-driven behavior.
+- Read order: DDP -> Design Token -> UI Contract -> HTML Mock -> Flow.
+- If code intent and rendered output diverge, treat the rendered/HTML result as the blocking review input and reconcile before DONE.
+
 ## Non-goals
 
 - Writing spec artifacts (use `/qfai-sdd`).

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

@@ -49,6 +49,13 @@ This stage is complete only when all specs pass the minimum runtime contract:
 - DB objects needed for runtime are present (real DB or documented in-memory substitute).
 - Evidence is captured and validate can enforce it.
 
+## Visual Review Guard
+
+- Review rendered output, screenshot captures, or generated HTML for every UI-affecting slice; code-only inspection is insufficient.
+- Read the DDP (Design Direction Pack) first before comparing visuals or wiring critique outcomes into implementation.
+- Read order: DDP -> Design Token -> UI Contract -> HTML Mock -> Flow.
+- If rendered/HTML evidence disagrees with code intent, fix the rendered result before declaring completion.
+
 ## Definition of Done by fidelity level (Mandatory)
 
 - L1 (`skeleton`):

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

@@ -49,6 +49,36 @@ Recommended approach:
 
 When `uiFidelity` is present, keep all minimum fields above.
 
+### Render evidence bundle conventions
+
+When render capture is enabled, keep render metadata path-only and store artifacts on disk:
+
+- default bundle path: `.qfai/evidence/render.json`
+- default viewports: `desktop`, `mobile`
+- `uiFidelity.screens[].renders[]` is the normalized in-band source for validator/report use
+- captured entries require `imagePath` and `htmlPath`
+- skipped entries require `skippedReason`
+- failed entries require `error`
+
+Degraded mode is allowed:
+
+- if renderer setup is unavailable, record `status: "skipped"` with a concrete reason
+- do not inline screenshot bytes or HTML bodies into JSON
+- keep `prototyping.json` and `render.json` aligned by file path only
+
+```json
+{
+  "renderEvidence": {
+    "status": "skipped",
+    "requested": true,
+    "autogenEnabled": false,
+    "viewports": ["desktop", "mobile"],
+    "outputPath": ".qfai/evidence/render.json",
+    "reason": "render requested without autogen-ui-fidelity"
+  }
+}
+```
+
 Good example references:
 
 - Repository docs sample: `docs/examples/prototyping-ui-fidelity.good.json`