qfai 1.8.9 → 1.8.10

package/README.md

@@ -18,11 +18,19 @@ The agent reads the repository, produces the required artifacts, and iterates un
 ## Release status
 
 - Release posture: runtime truthfulness is enforced.
-- Prototyping is UI-only and runs a single-thread evolution loop driven by
-  `qfai prototyping iterate --cycle <n>`, with deterministic stop conditions
-  (exit codes 0 continue / 64 convergence / 65 max-iterations / 2 input error).
+- Prototyping is UI-only and runs a multi-spec evolution loop driven by
+  `qfai prototyping iterate --cycle <n>`. The skill resolves every
+  UI-bearing spec in one invocation, freezes that set at cycle 0, and
+  iterates `cycle 0..9` (max 10 cycles) with deterministic stop conditions
+  (exit codes 0 continue / 64 convergence / 65 max-iterations /
+  66 license-verify failure / 2 input or lock drift).
 - Runtime observation is observed-only (no synthetic 200 / API / DB prototyping coverage).
-- Per-iter evidence is `screenshot.png` + `index.html` per declared screen plus a single `review.json` (4-axis ordinal, prose critique, anti-slop detection, pivot directive).
+- Per-iter evidence is a single `<screen>.review.json` per declared spec ×
+  screen pair (4-axis ordinal verdicts, 6 `*Feel` short-prose impressions
+  bounded to 200 words each, `layoutAntiPatternsDetected[]`,
+  `designMdViolations[]`, and `pivotDirective`). Reviewer-emitted
+  `<screen>.review.json` is the only per-cycle artifact — no `screenshot.png`,
+  `index.html`, or `interaction.json`.
 - Calibration SSOT is the calibration pack referenced by `calibrationRef.packPath`.
 
 ## Quick start
@@ -66,8 +74,8 @@ npx qfai report
     Use `npx qfai prototyping preflight --target-url <url>` for a focused
     prototyping preflight before the skill starts; it surfaces blocking
     `QFAI-DCON-*` design-contract issues alongside runtime assumptions and resolves a runnable Playwright CLI launcher.
-    Use `npx qfai prototyping iterate --cycle <n> --target-url <url>` to drive each cycle of the single-thread
-    evolution loop. Exit codes: 0 (continue), 64 (convergence), 65 (max-iterations), 2 (input error).
+    Use `npx qfai prototyping iterate --cycle <n> --target-url <url>` to drive each cycle of the multi-spec
+    evolution loop. Exit codes: 0 (continue), 64 (convergence), 65 (max-iterations), 66 (license-verify failure), 2 (input or lock drift).
     Traceability refs inside prototyping evidence must use repo-root-relative concrete artifact refs
     (for example `.qfai/specs/spec-0001/01_Spec.md#L3` or `.qfai/evidence/prototyping/iter-03/home.png`).
     Absolute paths are invalid. The same strict ref grammar is enforced for top-level and leaf evidence-bearing fields, including
@@ -132,10 +140,19 @@ QFAI includes a small set of custom skills (stored under `.qfai/assistant/skills
   in `.qfai/specs/_policies/03_Capabilities.md` before the row is accepted
   (`QFAI-TRIAGE-006`). Every `01_Spec.md` declares a lifecycle
   `Status: active | superseded | deprecated | removed` (`QFAI-STATUS-001..006`).
-- **qfai-prototyping**: Single-thread design evolution loop. One prototype iterated through up to
-  15 cycles of generate -> capture -> review with a 4-axis ordinal rubric, anti-slop detection,
-  prose critique, and explicit pivot permission. Stops deterministically when all four axes hit
-  `exceptional` (exit 64) or the iteration budget is exhausted (exit 65).
+- **qfai-prototyping**: Multi-spec parallel design evolution loop. Resolves
+  every UI-bearing spec in one invocation, freezes that set at cycle 0,
+  and iterates each `spec × screen` pair through up to 10 cycles
+  (`cycle 0..9`) of generate → capture → review with a 4-axis ordinal
+  rubric, 6 `*Feel` short-prose impressions (200-word bounded), explicit
+  layout anti-pattern detection (`lap-001..lap-008`), DESIGN.md token
+  violation detection, and explicit pivot permission. Stops
+  deterministically when every `spec × screen` pair satisfies the AND
+  convergence condition (all four ordinal axes `exceptional` AND
+  `layoutAntiPatternsDetected` empty AND `designMdViolations` empty)
+  (exit 64), when the 10-cycle budget is exhausted (exit 65), or when a
+  stock-photo source violates the cycle-0 frozen license catalog
+  (exit 66). Lock drift / input errors exit 2.
 - **qfai-atdd**: Implement acceptance tests driven by specs/scenarios.
 - **qfai-implement**: Unified TDD micro-cycle (Red/Green/Refactor) one test at a time using `test-list.md` as the execution ledger, including ledger status updates and exception closure.
 - **qfai-verify**: Run full-scan local quality gates (`validate --fail-on error`, `report`, repo gates) and produce reviewer-approved evidence under `.qfai/evidence/`.

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

@@ -1,7 +1,7 @@
 ---
 name: qfai-prototyping
 title: QFAI Prototyping (DESIGN.md-driven UX Loop)
-description: "Iterate one prototype through up to 15 cycles of generate-capture-review against a frozen DESIGN.md, focusing on information architecture, navigation flow, usability, and functionality."
+description: "Iterate one prototype through up to 10 cycles of generate-capture-review against a frozen DESIGN.md, focusing on information architecture, navigation flow, usability, and functionality."
 argument-hint: ""
 allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
 roles: [orchestrator, product-experience-architect, product-surface-reviewer, devops-ci-engineer]
@@ -13,14 +13,16 @@ mode: execution-focused
 
 [DRIFT-PROTOCOL:MANDATORY]
 
-This skill is static-first and file-based by default: it runs one prototype
-through up to 15 iterations against a frozen brand SSOT (`DESIGN.md`), with
-no parallel candidates, no mode, and a fixed 15-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.
+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.
 
 ## Goal
 
@@ -56,7 +58,24 @@ current `DESIGN.md` hash does not match the lock.
 
 ### Step 2-A — Verify Contract Preconditions
 
-- Confirm the selected spec is UI-bearing and has a supported `surface`.
+- 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`.
+  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.
 - Run `qfai prototyping preflight --target-url <url>` (alias for
@@ -71,17 +90,64 @@ current `DESIGN.md` hash does not match the lock.
 
 ### Step 2-C — Run the Loop
 
-| Step   | Actor                                                     | Action                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Output                                   |
-| ------ | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
-| C0     | product-experience-architect                              | `qfai prototyping iterate --cycle 0 --target-url <url>`. CLI computes `sha256(DESIGN.md)`; lock match enforced. Generator reads contracts + `references/generator-prompt.md` + DESIGN.md tokens and writes `.qfai/prototypes/iter-00/index.html`. Capture + review → `iter-00/review.json`. Append entry; commit `prototyping: iter-00`.                                                                                                                                                                                      | iter-00, prototyping.json#designMdSha256 |
-| C1..14 | (a) devops, (b) reviewer, (c) orchestrator, (d) generator | (a) playwright-cli writes `iter-NN/<screen>.{png,html}`; (b) reviewer writes `iter-NN/review.json` per `references/reviewer-prompt.md` (4 UX axes ordinal, 200..500 word critique, `layoutAntiPatternsDetected[]`, `designMdViolations[]`, `pivotDirective`); (c) update `prototyping.json#iterations[]` + `progress.md`, commit `prototyping: iter-NN`; (d) `qfai prototyping iterate --cycle <n+1>` decides exit.                                                                                                           | iter-NN, exit ∈ {0, 64, 65, 2}           |
-| H      | orchestrator                                              | Mirror latest to `.qfai/prototypes/final/index.html`. Per `references/handoff.md`: write `design-system.yaml` (deterministic DESIGN.md token mirror, no HTML extraction) + `prototype-handoff.yaml`. Run `qfai validate --profile prototyping --fail-on error` (produces `validate.json` with `counts.error === 0`), then `/qfai-verify` (produces `verify.json` with `status === "PASS"`), then `qfai prototyping certify` — certify requires both gate files to be present and passing before it will seal the certificate. | DONE                                     |
+| Step  | Actor                                                     | Action                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Output                                   |
+| ----- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| C0    | product-experience-architect                              | `qfai prototyping iterate --cycle 0 --target-url <url>`. CLI computes `sha256(DESIGN.md)`; lock match enforced. Generator reads contracts + `references/generator-prompt.md` + DESIGN.md tokens and writes `.qfai/prototypes/iter-00/index.html`. Capture + review → `iter-00/review.json`. Append entry; commit `prototyping: iter-00`.                                                                                                                                                                                                                        | iter-00, prototyping.json#designMdSha256 |
+| C1..9 | (a) devops, (b) reviewer, (c) orchestrator, (d) generator | (a) playwright-cli writes `iter-NN/<screen>.{png,html}`; (b) reviewer writes `iter-NN/review.json` per `references/reviewer-prompt.md` (4 UX axes ordinal, 200..500 word critique, `layoutAntiPatternsDetected[]`, `designMdViolations[]`, `pivotDirective`); (c) update `prototyping.json#iterations[]` + `progress.md`, commit `prototyping: iter-NN`; (d) `qfai prototyping iterate --cycle <n+1>` decides exit. After C9 do NOT call `--cycle 10` — the CLI rejects out-of-range cycles. See the "Cycle 9 budget exhaustion" subsection below for recovery. | iter-NN, exit ∈ {0, 64, 65, 66, 2}       |
+| H     | orchestrator                                              | Mirror latest to `.qfai/prototypes/final/index.html`. Per `references/handoff.md`: write `design-system.yaml` (deterministic DESIGN.md token mirror, no HTML extraction) + `prototype-handoff.yaml`. Run `qfai validate --profile prototyping --fail-on error` (produces `validate.json` with `counts.error === 0`), then `/qfai-verify` (produces `verify.json` with `status === "PASS"`), then `qfai prototyping certify` — certify requires both gate files to be present and passing before it will seal the certificate.                                   | DONE                                     |
 
 **Exit codes**: `0` continue (read `pivotDirective`); `64` convergence (4
 axes `exceptional` AND `layoutAntiPatternsDetected` empty AND
-`designMdViolations` empty); `65` 15 cycles reached; `2` input error
+`designMdViolations` empty); `65` 10 cycles reached; `66` license-verify
+failure (`imageSources[]` resolved to a non-allowlisted source, unknown
+license tier, non-HTTPS URL, host mismatch vs the cycle-0 frozen
+`sourceHosts`, or missing / empty `attribution` — see "License-verify
+hard-stop (exit 66)" below for recovery); `2` input error or lock drift
 (incl. DESIGN.md hash mismatch — re-run prototyping from cycle 0 after
-editing `DESIGN.md` and refreezing the lock via `/qfai-sdd` Phase 0).
+editing `DESIGN.md` and refreezing the lock via `/qfai-sdd` Phase 0; also
+covers `frozenSurfaceUnion` / `frozenLicenseCatalog` drift on cycle ≥ 1).
+
+### License-verify hard-stop (exit 66)
+
+`qfai prototyping iterate` exits `66` when an `imageSources[]` entry on
+`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-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
+
+Recovery path (no in-loop retry — the verifier is fail-closed):
+
+1. Inspect `prototyping.json#frozenLicenseCatalog` to see 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.
+
+### 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.
 
 ## Evaluator Inputs (Mandatory)
 

package/assets/init/.qfai/assistant/steering/agent-routing.yml

@@ -106,9 +106,11 @@ routing:
     review_profile: runtime-heavy
 
   - skill: qfai-prototyping
-    # Single-thread evolution loop: one prototype, 15 iter, 4 ordinal axes,
-    # prose critique, pivot directive. Routing is the 3 active roles plus
-    # completion-reviewer at handoff.
+    # Multi-spec evolution loop: every UI-bearing spec resolved at cycle 0,
+    # one prototype lineage per spec × screen pair, 10 iter (cycle 0..9),
+    # 4 ordinal axes + 6 *Feel impressions + layout anti-pattern detection
+    # + DESIGN.md token violation gates, prose critique, pivot directive.
+    # Routing is the 3 active roles plus completion-reviewer at handoff.
     phases:
       - id: seed
         mandatory_agents: [product-experience-architect]