qfai 1.9.0 → 1.9.2

package/assets/init/.qfai/assistant/skills/qfai-sdd/references/ui-contract-guide.md

@@ -0,0 +1,61 @@
+# UI Contract Authoring Guide
+
+This guide explains how to author a UI contract YAML under
+`.qfai/contracts/ui/` so it satisfies the QFAI validate lanes
+(`QFAI-AUD-001` empty-slot, `QFAI-AUD-020` recommended count band) and
+the downstream `/qfai-prototyping` preflight gates.
+
+## `screens[].primary_tasks` shape
+
+Each entry in `screens[]` MUST carry a `primary_tasks:` slot. Each
+slot entry may be authored in one of two shapes:
+
+1. **String-only (legacy)** — a plain bullet such as
+   `- Review pending orders`. Accepted during the deprecation window
+   for backwards compatibility with contracts authored before the
+   structured shape was introduced.
+
+2. **Structured (closed schema)** — a mapping with exactly three
+   required keys, no additional keys allowed:
+
+   ```yaml
+   - id: t1
+     label: Mark order shipped
+     acceptance: order status flips to shipped
+   ```
+
+   - `id` — short stable handle for the task (used by ATDD scaffolds).
+   - `label` — human-readable task name.
+   - `acceptance` — testable acceptance condition; anchors downstream
+     TODO assertions in ATDD scaffolding.
+
+A structured entry missing any of `id` / `label` / `acceptance`, or
+carrying any extra key (e.g. `priority`, `owner`), is rejected at
+validate time. The schema is intentionally closed (no
+`additionalProperties: true`) — see the related design decision in
+`_policies/08_Decisions.md` for rationale.
+
+## Recommended count band: 3..7
+
+The recommended count band for `screens[].primary_tasks` is **3..7
+entries per screen** (inclusive bounds). Outside the band, validate
+emits `QFAI-AUD-020` at severity=warning, naming the band 3..7
+explicitly:
+
+| count | validate behavior                          |
+| ----- | ------------------------------------------ |
+| 0     | `QFAI-AUD-001` error (empty primary_tasks) |
+| 1..2  | `QFAI-AUD-020` warning (below 3..7 band)   |
+| 3..7  | passes silently                            |
+| 8+    | `QFAI-AUD-020` warning (above 3..7 band)   |
+
+The 3..7 band reflects multi-screen SaaS / dashboard workloads where
+5–6 primary tasks per surface is common; tighter ceilings (e.g. 1..3
+or "single primary CTA") over-flag legitimate productivity surfaces.
+
+## Template
+
+The shipped UI contract template at
+`templates/contracts/ui-contract.sample.yaml` includes inline comments
+that re-state the 3..7 band and the structured-shape schema, so an
+author who reads only the template still learns the contract.

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/contracts/ui-contract.sample.yaml

@@ -12,6 +12,15 @@ screens:
   - id: order_create
     title: Create Order
     route: /orders/new
+    # primary_tasks: at least one entry required per screen (QFAI-AUD-001).
+    # Recommended count band: 3..7 entries per screen (QFAI-AUD-020).
+    # Counts outside the 3..7 band warn at validate time; tune the list
+    # so it covers the screen's core user actions without over-loading
+    # the surface. See references/ui-contract-guide.md for the rationale.
+    # Each entry may be either a plain string (legacy) or a structured
+    # `{id, label, acceptance}` object (closed schema — no other keys).
+    primary_tasks:
+      - submit a new order
     elements:
       - id: customer_id_input
         label: Customer ID

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

@@ -508,6 +508,27 @@ When this skill is complete, provide a final user-facing completion message and
 - Need a report artifact:
   Action: run `qfai report` after validation outputs are up to date.
 
+## Default Autopilot Policy
+
+The skill collapses avoidable per-session prompts to 0-1 by classifying every decision into one of three named buckets:
+
+- auto-decide:
+  - output formatting
+  - ID / sequence numbering
+  - append-vs-create on subject overlap
+  - equivalent-option pick
+- ask-user:
+  - CREATE / DELETE / SPLIT / MERGE / SUPERSEDE / UPDATE:REMOVE triage operations (each with a prompt template that names the target and rationale)
+  - destructive operations (rm / overwrite / force-push)
+  - version-pin changes (`package.json#version`, branch pin)
+  - scope expansions outside the active envelope
+- hard-required:
+  - `companyName`
+  - brand intent
+  - `primarySpecId` (when absent from inputs)
+
+A skill MAY narrow the auto-decide bucket (drop entries) but MUST NOT widen it. Widening triggers a Reviewer-Gate finding.
+
 project_memory:
 
 - Verify is the full-scan approval gate; per-skill validate runs (sdd/atdd/tdd) are signals, the verify gate is the binding pass.