qfai 1.9.0 → 1.9.1

package/assets/init/.qfai/assistant/agents/requirements-analyst.md

@@ -33,6 +33,12 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 - Option set with recommendation and rejected rationale
 - Open questions with owner, decision point, and safe deferral notes
 - Mapping from requirements to impacted artifacts
+- For UI-bearing surfaces: every entry in the UI contract `screens[]` must
+  carry at least one `primary_task` (≥ 1 primary_task per screen). The
+  shipped `ui-contract.sample.yaml` template exposes a `primary_tasks: []`
+  placeholder slot; populate it before handing the contract to the
+  prototyping phase. Empty `primary_tasks` arrays cause the
+  QFAI-AUD-001 aligned validate lane to block `/qfai-prototyping`.
 
 ## Stop conditions
 

package/assets/init/.qfai/assistant/manifest/agent-catalog.yml

@@ -366,95 +366,62 @@ agents:
       - requirements-analyst
       - oq-harvester
       - option-explorer
-    developer_instructions: >-
+    developer_instructions: |-
       ## Mission
 
-
-      - Convert discussions into testable requirements, explicit open questions,
-      and option sets with acceptance signals.
-
+      - Convert discussions into testable requirements, explicit open questions, and option sets with acceptance signals.
 
       ## Domain Responsibilities
 
-
-      - Translate stakeholder intent into requirement statements and acceptance
-      signals.
-
+      - Translate stakeholder intent into requirement statements and acceptance signals.
       - Harvest undefined decisions and maintain the OQ backlog.
-
       - Produce multiple solution options with a recommendation.
-
       - Map requirements to impacted downstream artifacts.
 
-
       ## Inputs you must read
 
-
       - .qfai/assistant/constitution/\*\*
-
       - .qfai/assistant/{manifest,catalog}/\*\*
-
       - .qfai/specs/spec-\*/09_delta.md
-
       - .qfai/discussion/discussion-\*/04_Sources.md
-
       - .qfai/discussion/discussion-\*/06_REQ.md
-
       - .qfai/discussion/discussion-\*/11_OQ-Register.md
-
       - Discussion records under `.qfai/discussion/`
 
-
       ## Deliverables
 
-
       - Requirements list with acceptance signals
-
       - Option set with recommendation and rejected rationale
-
       - Open questions with owner, decision point, and safe deferral notes
-
       - Mapping from requirements to impacted artifacts
-
+      - For UI-bearing surfaces: every entry in the UI contract `screens[]` must
+        carry at least one `primary_task` (≥ 1 primary_task per screen). The
+        shipped `ui-contract.sample.yaml` template exposes a `primary_tasks: []`
+        placeholder slot; populate it before handing the contract to the
+        prototyping phase. Empty `primary_tasks` arrays cause the
+        QFAI-AUD-001 aligned validate lane to block `/qfai-prototyping`.
 
       ## Stop conditions
 
-
-      - Governing specs, routing rules, or required source artifacts are
-      missing.
-
-      - The requested output belongs to another specialist's ownership without
-      an explicit handoff.
-
+      - Governing specs, routing rules, or required source artifacts are missing.
+      - The requested output belongs to another specialist's ownership without an explicit handoff.
       - The task would bypass required validation or reviewer gates.
 
-
       ## Sign-off
 
-
       - [ ] Deliverables are complete
-
       - [ ] Ownership boundaries were respected
-
       - [ ] Required gates and follow-up evidence are recorded
 
-
       ## When to use
 
-
       - Use when `agent-routing.yml` assigns this domain to the current phase.
-
       - Use when the task needs this specialist's owned artifacts or decisions.
 
-
       ## When not to use
 
-
-      - Do not use when the task is primarily review-only and needs a reviewer
-      instead.
-
-      - Do not use when another specialist owns the main artifact or decision
-      surface.
+      - Do not use when the task is primarily review-only and needs a reviewer instead.
+      - Do not use when another specialist owns the main artifact or decision surface.
   - id: solution-architect
     kind: worker
     domain: architecture

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

@@ -15,14 +15,11 @@ mode: execution-focused
 
 This skill is static-first and file-based by default: it runs every
 UI-bearing spec resolved at cycle 0 through up to 10 iterations against
-a frozen brand SSOT (`DESIGN.md`) and a frozen spec set, with one
-prototype lineage per `spec × screen` pair, no parallel candidates
-within a pair, no mode, and a fixed 10-cycle budget. Visual identity
-is fixed for the whole run; every cycle improves information
-architecture, navigation flow, usability, and functionality. Supported
-UI prototyping surfaces are: web, mobile, desktop, mixed. cli is not a
-prototyping execution target and is rejected. ui_bearing: false specs
-are not prototyping execution targets and are excluded.
+a frozen brand SSOT (`DESIGN.md`) and a frozen spec set, one lineage per
+`spec × screen` pair, no parallel candidates, no mode, fixed 10-cycle
+budget. Supported surfaces: web, mobile, desktop, mixed. cli surface is
+rejected and `ui_bearing: false` specs are excluded from prototyping
+execution.
 
 ## Goal
 
@@ -58,23 +55,13 @@ current `DESIGN.md` hash does not match the lock.
 
 ### Step 2-A — Verify Contract Preconditions
 
-- The skill resolves **every UI-bearing spec in the consumer project in
-  one invocation** via `resolveSurfaceUnion()`
-  (`core/prototyping/specResolution.ts`) — the same resolver the
-  cycle ≥ 1 drift gate and `show-spec`'s live scope consume, so the
-  scope you read here is apples-to-apples with what iterate enforces
-  downstream. `resolveSurfaceUnion()` internally composes
-  `resolveAllUiBearingSpecs()` (the strict `surface_type: ui-bearing`
-  frontmatter signal + the matching `.qfai/contracts/ui/<spec-id>*.yaml`
-  contract fallback) and folds in the legacy `# … prototyping …`
-  title-marker fallback and the operator-pinned spec id from the
-  `qfai.config.yaml` `prototyping` section (run
-  `qfai doctor --profile prototyping` to surface the resolved value).
-  Operators authoring CHG-002-shaped projects can rely on the strict
-  frontmatter alone; the broader composition covers legacy /
-  config-pinned consumers.
-  The operator is never prompted to pick a single spec; zero
-  UI-bearing specs at cycle 0 is a deterministic no-op exit `0`.
+- The skill resolves **every UI-bearing spec in one invocation** via
+  `resolveAllUiBearingSpecs()` (`core/prototyping/specResolution.ts`):
+  strict `surface_type: ui-bearing` frontmatter + matching
+  `.qfai/contracts/ui/<spec-id>*.yaml`, with legacy title-marker and
+  `qfai.config.yaml` `prototyping` pinning folded in. Run
+  `qfai doctor --profile prototyping` to surface the resolved value.
+  Zero UI-bearing specs at cycle 0 is a deterministic no-op exit `0`.
   Confirm each resolved spec has a supported `surface`.
 - Confirm root `DESIGN.md` and `.qfai/contracts/design/DESIGN.md.lock.yaml`
   both exist; confirm `.qfai/contracts/ui/*.yaml` exists.
@@ -85,8 +72,29 @@ current `DESIGN.md` hash does not match the lock.
 ### Step 2-B — Verify Environment Preconditions
 
 - Confirm a capture route exists for each declared screen.
-- Use `npx --no-install playwright-cli` or
-  `node_modules/.bin/playwright-cli` when PATH reachability is uncertain.
+- Canonical launcher: `npx --no-install playwright` or
+  `node_modules/.bin/playwright` when PATH reachability is uncertain.
+- Legacy fallback (deprecation window only, emits
+  `D-DEPRECATED-PROBE` and will be removed in a future minor release):
+  `npx --no-install playwright-cli` or `node_modules/.bin/playwright-cli`.
+
+### Step 2-B.1 — Opt-in iterate flags
+
+Three flags extend `qfai prototyping iterate`; all default OFF so the
+prior invocation pattern is byte-equivalent when no flag is passed:
+
+- `--capture` — enable PNG / HTML capture per screen each cycle via
+  the default Playwright runner (dynamic `import("playwright")`;
+  Playwright is `optionalDependencies`). Use for durable pixel / DOM
+  evidence; skip for fast prose-only cycles.
+- `--auto-serve` — start an in-process `node:http` server rooted at
+  the prototype tree for the cycle. SIGINT teardown <= 2 s;
+  EADDRINUSE on a foreign owner exits 2 (no foreign-process kill).
+  Use when no external dev server is running.
+- `--check-convergence` — read-only peek of `prototyping.json`.
+  Exits `0` when converged (`stopReason === "axes-exceptional"` with
+  `acceptedIterationIndex` set), exits `2` otherwise. No writes,
+  no Playwright launches. Use at cycle 9 before recovery.
 
 ### Step 2-C — Run the Loop
 
@@ -113,41 +121,38 @@ covers `frozenSurfaceUnion` / `frozenLicenseCatalog` drift on cycle ≥ 1).
 `prototyping.json` violates the cycle-0 frozen license catalog. The
 verifier rejects five distinct error codes:
 
-- `license-not-allowlisted` — `source` is not in
-  `frozenLicenseCatalog.allowedSources`
-- `license-tier-unknown` — `license` is not in
-  `frozenLicenseCatalog.licenseTiers[source]`
+- `license-not-allowlisted` — `source` not in `allowedSources`
+- `license-tier-unknown` — `license` not in `licenseTiers[source]`
 - `license-non-https-url` — `url` is not HTTPS
-- `license-host-mismatch` — the URL host is not in
-  `frozenLicenseCatalog.sourceHosts[source]`
-- `license-missing-attribution` — `attribution` is undefined / empty /
-  whitespace-only
+- `license-host-mismatch` — URL host not in `sourceHosts[source]`
+- `license-missing-attribution` — `attribution` empty / whitespace
 
 Recovery path (no in-loop retry — the verifier is fail-closed):
 
-1. Inspect `prototyping.json#frozenLicenseCatalog` to see the frozen
+1. Inspect `prototyping.json#frozenLicenseCatalog` for the frozen
    `allowedSources` / `licenseTiers` / `sourceHosts`.
 2. Edit the offending `imageSources[]` entry to use an allowlisted
-   source / known license tier / HTTPS URL / matching host / non-empty
-   attribution. **Do not** edit `frozenLicenseCatalog` mid-loop — that
-   triggers a separate exit-2 lock-drift class.
-3. If the legitimate fix requires a different allowlist (e.g. adding a
-   new source), the only path is to refreeze the catalog by restarting
-   from cycle 0 (`qfai prototyping iterate --cycle 0 --target-url <url>`)
-   with the updated stock-photo configuration.
+   source / known tier / HTTPS URL / matching host / non-empty
+   attribution. **Do not** edit `frozenLicenseCatalog` mid-loop
+   (separate exit-2 lock-drift class).
+3. To change the allowlist, refreeze the catalog by restarting from
+   cycle 0 with the updated stock-photo configuration.
 
 ### Cycle 9 budget exhaustion
 
-If convergence is not reached at iter-09, the certify gate will reject
-the run — H handoff artifacts (final mirror, `design-system.yaml`,
-`prototype-handoff.yaml`) and the `validate` / `/qfai-verify` gates can
-still be written / executed for inspection, but
-`qfai prototyping certify --check` will exit non-zero and prevent DONE.
-The recovery path is to restart from cycle 0: review `DESIGN.md`, the
-pivot strategy in `references/reviewer-prompt.md`, and the latest
-`review.json` findings, then re-run `qfai prototyping iterate
---cycle 0 --target-url <url>` to refreeze the loop. Do not seal a
-completion certificate against an unconverged iter-09.
+If convergence is not reached at iter-09, certify rejects the run; H
+handoff artifacts and `validate` / `/qfai-verify` can still execute for
+inspection, but `qfai prototyping certify --check` will exit non-zero
+and prevent DONE.
+
+Use `qfai prototyping iterate --cycle 9 --check-convergence` for a
+read-only peek of `prototyping.json` before refreezing: exit `0`
+confirms convergence (no recovery needed), exit `2` confirms the run
+did not converge. Recovery: review `DESIGN.md`, the pivot strategy
+in `references/reviewer-prompt.md`, and the latest `review.json`
+findings, then re-run `qfai prototyping iterate --cycle 0
+--target-url <url>` to refreeze. Do not seal a certificate against
+an unconverged iter-09.
 
 ## Evaluator Inputs (Mandatory)
 
@@ -163,8 +168,8 @@ completion certificate against an unconverged iter-09.
   latest iter is always accepted.
 - `DESIGN.md` is frozen for the run; to change it, edit + rerun
   `/qfai-sdd` to refreeze + start cycle 0.
-- Token-only colors / fonts / radii / shadows — non-DESIGN.md hex / rgb /
-  rgba / hsl / font / radius / shadow values are recorded in
+- Token-only colors / fonts / radii / shadows — non-DESIGN.md hex /
+  rgb / rgba / hsl / font / radius / shadow values land in
   `designMdViolations[]` and block exit 64.
 - DONE only when `qfai prototyping certify --check` returns 0.
 - No `mode / round / polish / branch / concept-fit` artifacts.

package/assets/init/.qfai/assistant/skills/qfai-prototyping/references/generator-prompt.md

@@ -50,12 +50,102 @@ tokens (e.g. `bg-primary`, `text-text`, `rounded-md`, `shadow-lg`,
 
 ## Hard constraints (enforced by the compliance gate)
 
-- No `#hex`, `rgb(...)`, `rgba(...)`, `hsl(...)`, `hsla(...)` value
-  outside `DESIGN.md.visual.colors`.
-- No `font-family:` whose first token is outside
-  `DESIGN.md.visual.typography.family_*`.
-- No `border-radius:` outside `DESIGN.md.visual.radius`.
-- No `box-shadow:` outside `DESIGN.md.visual.shadow`.
+The compliance gate scans rendered HTML — `<style>` blocks, inline
+`style="..."` attributes, AND Tailwind `class="..."` attributes — for
+four categories of forbidden literals. Findings are **advisory-failing**:
+the gate blocks convergence by default, but a Reviewer can override
+when a finding is a known false positive.
+
+### 1. color literal ban
+
+No raw color literals outside `DESIGN.md.visual.colors`. The scanner
+catches every authoring path:
+
+- `#hex` (3 / 4 / 6 / 8 nibbles): e.g. `color: #ff0000`,
+  `bg-[#ff0000]`.
+- `rgb(...)` / `rgba(...)`: e.g. `background: rgb(255 0 0)`,
+  `bg-[rgb(255_0_0)]`.
+- `hsl(...)` / `hsla(...)`: e.g. `color: hsl(0 100% 50%)`.
+- CSS named-color keywords (`red`, `white`, `blue`, …) when placed
+  on a color-bearing property (`color`, `background`, `border`,
+  `outline`, `fill`, `stroke`, `caret-color`, `text-decoration`,
+  `column-rule`, and their `-color` longhands / shorthand variants).
+- Tailwind palette utilities (`bg-blue-500`, `text-slate-900`,
+  `border-red-400`, etc.) — the CDN cannot read `DESIGN.md`, so
+  every palette class is by definition drift.
+
+### 2. font-family literal ban
+
+No `font-family:` whose first family token is outside
+`DESIGN.md.visual.typography.family_sans` / `family_display` /
+`family_mono`. Authored forms caught:
+
+- Inline `font-family: Inter, sans-serif` (quoted or unquoted).
+- Tailwind arbitrary `font-[Inter]`. Numeric / named font-weight
+  arbitraries (`font-[600]`, `font-[medium]`) are weight tokens —
+  not font-family drift — and pass through.
+
+### 3. border-radius literal ban
+
+No `border-radius:` value outside `DESIGN.md.visual.radius`. Authored
+forms caught:
+
+- Inline `border-radius: 12px` / `border-radius: 0.5rem`.
+- Tailwind arbitrary `rounded-[13px]`, `rounded-[0.5rem]`.
+- Tailwind scale aliases (`rounded`, `rounded-sm`, `rounded-md`,
+  `rounded-lg`, `rounded-xl`, `rounded-2xl`, `rounded-3xl`,
+  `rounded-full`, `rounded-none`) — all resolve to Tailwind defaults,
+  not `DESIGN.md` tokens.
+
+### 4. box-shadow literal ban (including rgba color slot)
+
+No `box-shadow:` declaration outside `DESIGN.md.visual.shadow`. The
+shadow value's embedded `rgba(...)` color slot is also covered.
+Authored forms caught:
+
+- Inline `box-shadow: 0 1px 2px rgba(15,23,42,0.05)`.
+- Tailwind arbitrary `shadow-[0_4px_6px_rgba(0,0,0,0.1)]`.
+- Tailwind scale aliases (`shadow`, `shadow-sm`, `shadow-md`,
+  `shadow-lg`, `shadow-xl`, `shadow-2xl`, `shadow-inner`,
+  `shadow-none`, `drop-shadow-*`).
+
+### Safelisted CSS-wide keywords
+
+The following values are **not** treated as drift by any of the four
+scanners above — they are CSS inheritance / system keywords with no
+visual identity:
+
+- `inherit`
+- `initial`
+- `unset`
+- `revert`
+- `currentColor` (case-insensitive)
+- `transparent`
+- `none`
+- `0` (dimensionless)
+
+Authoring `font-family: inherit`, `border-radius: 0`, or
+`box-shadow: none` passes the gate even when not present in
+`DESIGN.md`.
+
+### Allowed expression forms
+
+The generator MUST express every styled surface as one of:
+
+- A Tailwind utility class whose token resolves through the
+  `tailwind.config.theme.extend.*` injection above (e.g. `bg-primary`,
+  `text-text`, `rounded-md`, `shadow-lg`, `font-display`). These
+  utilities reference `DESIGN.md` tokens by name and never carry a
+  literal in the rendered DOM.
+- A CSS custom-property reference via `var(--token-name)` where the
+  `--token-name` is declared in a `:root { ... }` block inside the
+  iter's `<style>` head. The scanner resolves the `var()` against
+  the `:root` map and re-validates the resolved value against
+  `DESIGN.md`.
+- A `theme(...)` reference to the injected Tailwind theme.
+
+### Other envelope constraints
+
 - No component library beyond Tailwind + Lucide. No external CSS, no
   design-system imports.
 - One self-contained HTML file; embedded CSS / JS minimal.

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

@@ -12,6 +12,10 @@ screens:
   - id: order_create
     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).
+    primary_tasks:
+      - submit a new order
     elements:
       - id: customer_id_input
         label: Customer ID