qfai 1.9.1 → 1.9.2

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

@@ -374,6 +374,27 @@ When this skill is complete, provide a final user-facing completion message and
 - Acceptance tests need fixes: rerun `/qfai-atdd`.
   Action: close uncovered `US` / `TC` / `CON-API` obligations and rerun validation.
 
+## 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:
 
 - Coverage obligations stay layer-pinned: tests/e2e/** must cover all required US; tests/integration/** all required TC; tests/api/\*\* all required CON-API.

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

@@ -444,6 +444,27 @@ When this skill is complete, provide a final user-facing completion message and
 - Configuration needs refinement: rerun `/qfai-configure`.
   Action: provide additional include/exclude evidence and update `qfai.config.yaml`.
 
+## 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:
 
 - qfai-configure is the user-facing entrypoint for editing `qfai.config.yaml` and the `.qfai/assistant/manifest/` declarative manifests; edits to those files MUST go through this skill so the agent-catalog / agent-routing / review-profiles SSOTs stay consistent.

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

@@ -36,6 +36,7 @@ Produce a unified 15-file discussion pack plus exploration-first UI sidecars so
 - UI-bearing discussion packs may include `prototyping.yaml` as an optional recommendation artifact; non-ui discussion packs typically omit it.
 - 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.
+- When an HTML+CSS mock includes links, author them in anchor-form (`<a href="#name">`); external `http(s)://` links are also allowed. Do NOT use same-origin absolute paths (`/orders/`) — a static mock cannot serve them and the validator rejects them (QFAI-MOCK-010).
 - 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.
 
@@ -121,6 +122,27 @@ You MUST end the user-facing output with a handoff sentence to `/qfai-sdd` in th
 - Japanese output (use this exact sentence):
   ディスカッションが完了しました。他に要望などがあればご提示ください。問題なければ『/qfai-sdd』と入力してください。
 
+## 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:
 
 - 15-file mandatory output set is fixed; the UI-bearing sidecar family (40_screen_contracts.md + 50_review_input_bundle.md + root DESIGN.md) is required only when the target is UI-bearing.

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

@@ -75,12 +75,15 @@ Screen-level contract details are finalized in `uiux/40_screen_contracts.md`. Pr
 <!-- Optional fallback only — do not use as the primary UI definition artifact.
      Include only when it materially clarifies the selected anchor.
      Behavior Obligations and sidecar artifacts (uiux/) are the primary UI definitions.
-     The required state SSOT is uiux/40_screen_contracts.md (`default/loading/empty/error`). -->
+     The required state SSOT is uiux/40_screen_contracts.md (`default/loading/empty/error`).
+     Links MUST be anchor-form (`<a href="#name">`) — never same-origin absolute
+     paths (`/orders/`), which a static mock cannot serve and which the validator rejects. -->
 
 ```html
 <section class="screen-mock">
   <h1>Screen Title</h1>
   <p>Primary information shown to the user.</p>
+  <a href="#orders">View Orders</a>
   <button type="button">Primary Action</button>
 </section>
 ```

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

@@ -349,6 +349,27 @@ When this skill is complete, provide a final user-facing completion message and
 - Acceptance tests: `/qfai-atdd`.
   Action: ensure acceptance test coverage aligns with implementation.
 
+## 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:
 
 - One TDD item at a time from test-list.md; status lifecycle is forward-only (todo → red → green → refactor → done); exception requires DR-ID.

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

@@ -201,6 +201,27 @@ Follow `.qfai/assistant/constitution/shared-skill-operating-baseline.md#gate-fai
 
 - `/qfai-atdd` / `/qfai-implement` / `/qfai-verify`
 
+## 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:
 
 - Iteration count cap is 10; --cycle is 0-indexed; reaching cycle 9 on a non-converged iteration set exits 65 directly (no cycle-mismatch path).

package/assets/init/.qfai/assistant/skills/qfai-prototyping/references/evidence-requirements.md

@@ -0,0 +1,46 @@
+# Evidence Requirements: `taskFidelity` section
+
+Prototyping evidence files MUST include a `taskFidelity` section so the
+`QFAI-CRIT-009` gate passes. Below is the required keyword set and
+the canonical markdown shape consumed by the validator and the
+`qfai prototyping iterate --capture` template emitter.
+
+## Required keywords
+
+Every evidence file that records a critique iteration MUST surface
+these `taskFidelity` keys with concrete values:
+
+- `cta_visibility` — does the primary call-to-action stay on-screen and
+  visually distinct at both desktop (>= 1024px) and mobile (<= 480px)
+  viewports?
+- `four_state_check` — has the interactive flow been checked in all
+  four reachable states (default / hover / focused / disabled), with a
+  pass/fail observation per state?
+
+The SSOT for this list lives at
+`packages/qfai/src/core/validators/taskFidelityKeywords.ts`
+(`TASK_FIDELITY_REQUIRED_KEYWORDS`). The validator (`QFAI-CRIT-009`),
+the `--capture` template emitter, and this document all read from
+that constant so the keyword set cannot silently drift between the
+three surfaces.
+
+## Canonical markdown structure
+
+The validator detects the section via the literal heading
+`## taskFidelity`. The minimal accepted shape is:
+
+```markdown
+## taskFidelity
+
+- step_count: 3
+- max_primary_steps: 5
+- cta_visibility: PASS — primary CTA stays anchored at the viewport bottom on
+  desktop (1440px) and remains tappable on mobile (375px).
+- four_state_check: PASS — default / hover / focused / disabled states each
+  render the expected variant; disabled is non-interactive.
+```
+
+Authors may add free-form prose between the bullets so long as each
+required keyword appears at least once. The `--capture` template emits
+a stub with TODO placeholders for every required keyword so the
+operator never silently forgets one.

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

@@ -272,6 +272,27 @@ When this skill completes, provide a final user-facing message enumerating next
 - Spec pack needs correction: rerun `/qfai-sdd` and regenerate evidence.
 - Confirm contracts referenced by `_policies/05_Contracts.md` exist under `.qfai/contracts/**`.
 
+## 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:
 
 - Phase order is fixed: Stage 0 Preflight → Stage 1 Triage → Phase 0 Contracts-first → Phase 1 Outline → Phase 2 Slice → Phase 3 Plan finalize → Phase 4 Delta update; do not reorder.

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

@@ -13,7 +13,12 @@ screens:
     title: Create Order
     route: /orders/new
     # primary_tasks: at least one entry required per screen (QFAI-AUD-001).
-    # Replace the example below with the actual primary user action(s).
+    # 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:

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.