qfai 1.8.6 → 1.8.7

package/README.md

@@ -18,11 +18,13 @@ The agent reads the repository, produces the required artifacts, and iterates un
 ## Release status
 
 - Release posture: runtime truthfulness is enforced.
-- Prototyping is UI-only; `full-harness` is measurement-driven iteration accumulation for UI-bearing surfaces only.
+- Prototyping is UI-only; v2.0 (spec-0017) runs a single-thread evolution loop
+  driven by `qfai prototyping iterate --cycle <n>`, with deterministic stop
+  conditions (exit codes 0/64/65/2). The v1.x mode tier and full-harness
+  machinery are removed.
 - Runtime observation is observed-only (no synthetic 200 / API / DB prototyping coverage).
-- Browser QA is mandatory per screen in full-harness, and `actionsWired` reports action coverage rather than finding count.
+- 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).
 - Calibration SSOT is the calibration pack referenced by `calibrationRef.packPath`.
-- Current repo note: some repo-wide `qfai validate --fail-on error` blockers still come from historical review/evidence/ATDD/TDD artifacts and are being cleaned incrementally.
 
 ## Quick start
 
@@ -60,19 +62,15 @@ npx qfai report
     primary spec, UI contracts, design contract readiness, active agent-wrapper
     integrations, shipped role-input readiness, Playwright CLI launcher
     resolution/probing, and target URL reachability.
-    Note: prototyping evidence (`.qfai/evidence/prototyping.json`) is produced by the AI workflow / skills
-    (`/qfai-prototyping` — any mode; modes differ only in `maxCycles`, see spec-0012), not by a general-purpose end-user CLI flow.
+    Note: prototyping evidence (`.qfai/evidence/prototyping/prototyping.json` v3.0) is produced by the AI workflow
+    (`/qfai-prototyping` v2.0, see spec-0017), not by a general-purpose end-user CLI flow.
     Use `npx qfai prototyping preflight --target-url <url>` for a focused
-    prototyping preflight before the skill starts; it now surfaces blocking
-    `QFAI-DCON-*` design-contract issues alongside runtime assumptions, resolves
-    a runnable Playwright CLI launcher (project wrapper / local bin / PATH /
-    `npx --no-install`), and still treats the first real delegation failure as a
-    runtime hard-stop.
-    Use `npx qfai prototyping round-start --round <r5|r3|r2|r1> --candidates <csv> --target-url <url> --mode <mode>`
-    to generate the round-scoped review bundle and command plans the AI evaluator sub-agent consumes, then use
-    `round-harvest`, `round-narrow`, `round-absorb`, and `round-reimplement-verify` to advance the candidate funnel.
-    `qfai validate` consumes the resulting evidence files, including `mode.effective` and `fullHarness` metadata when present.
-    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/render.json#/screens/0`).
+    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 v2.0 single-thread
+    evolution loop. Exit codes: 0 (continue), 64 (convergence), 65 (max-iterations), 2 (input error).
+    Traceability refs inside prototyping evidence must use repo-root-relative concrete artifact refs
+    (for example `.qfai/specs/spec-0017/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
     `runtimeGate.evidenceRefs`, `runtimeGate.ui[].declaredRef`, `runtimeGate.ui[].renderEvidenceRefs[]`,
     `runtimeGate.ui[].browserQaEvidenceRefs[]`, `specs[].coverageRefs[].declaredRef`, `specs[].coverageRefs[].observedRefs[]`,
@@ -96,9 +94,9 @@ npx qfai report
 
 `qfai validate` enforces spec-to-test traceability with directory-based rules.
 
-- `tests/e2e/**`: annotate all covered user stories with `QFAI:SPEC-XXXX:US-YYYY`.
-- `tests/integration/**`: annotate all covered test cases with `QFAI:SPEC-XXXX:TC-YYYY`.
-- `tests/api/**`: annotate all covered API contracts with `QFAI:CON-API-XXXX`.
+- `tests/e2e/**`: annotate all covered user stories with concrete IDs such as `QFAI:SPEC-0001:US-0001`.
+- `tests/integration/**`: annotate all covered test cases with concrete IDs such as `QFAI:SPEC-0001:TC-0001`.
+- `tests/api/**`: annotate all covered API contracts with concrete IDs such as `QFAI:CON-API-0001`.
 - `tests/api/**` and `tests/e2e/**` must not use `TC` annotations.
 - `AC` annotations are not required in code; AC coverage is treated as indirect through full `TC` coverage.
 
@@ -111,7 +109,7 @@ The agent reads QFAI assets under `.qfai/assistant/` and produces or updates SDD
 ### Where the skills live
 
 - QFAI canonical skills (SSOT): `.qfai/assistant/skills/**` (may be overwritten when you re-run `qfai init --force`).
-- Your local overrides: `.qfai/assistant/skills.local/**` (never overwritten by QFAI; prefer this for project-specific customizations).
+- QFAI no longer creates local override scaffolds. Project-specific guidance should live in your repository's normal agent docs or be created explicitly by your AI workflow.
 
 ### Minimal custom skill set
 
@@ -124,9 +122,11 @@ QFAI includes a small set of custom skills (stored under `.qfai/assistant/skills
   as 15 required markdown files under `.qfai/discussion/discussion-<ts>/`.
   UI-bearing discussion packs may include `prototyping.yaml` as an optional recommendation artifact; non-ui discussion packs typically omit it.
 - **qfai-sdd**: Unified SDD entrypoint with discussion-pack preflight guard (missing/incomplete/blocking OQ causes stop + next action guidance).
-- **qfai-prototyping**: Build a contract-aligned UI prototype using the Playwright CLI + AI
-  evaluator harness (spec-0012). Modes (`low-cost`/`standard`/`full-harness`) run the same
-  strictest review cycle; only `maxCycles` (1/3/20) differs.
+- **qfai-prototyping** (v2.0, spec-0017): 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). The v1.x funnel,
+  mode tier, polish/branch cycles, and 100/100 completion gate are removed.
 - **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/`.
@@ -377,10 +377,7 @@ Typical customizations.
 │   │   │   │   └── SKILL.md
 │   │   │   └── qfai-verify
 │   │   │       └── SKILL.md
-│   │   ├── skills.local
-│   │   │   └── README.md
 │   │   ├── steering
-│   │   │   ├── README.md
 │   │   │   ├── agent-catalog.yml
 │   │   │   ├── agent-routing.yml
 │   │   │   ├── review-gate.rules.yml
@@ -388,40 +385,14 @@ Typical customizations.
 │   │   │   ├── product.md
 │   │   │   ├── structure.md
 │   │   │   └── tech.md
-│   │   └── README.md
-│   ├── discussion
-│   │   ├── README.md
-│   │   └── discussion-YYYYMMDDhhmmssSSS
-│   │       ├── 01_Context.md
-│   │       ├── ...
-│   │       ├── 14_Review-Request.md
-│   │       ├── 99_delta.md
-│   │       └── prototyping.yaml
-│   ├── contracts
-│   │   ├── api
-│   │   │   └── README.md
-│   │   ├── db
-│   │   │   └── README.md
-│   │   ├── ui
-│   │   │   └── README.md
-│   │   └── README.md
-│   ├── report
-│   │   ├── .gitignore
-│   │   ├── README.md
-│   │   └── run-20260218123456789
-│   │       ├── run.json
-│   │       ├── validator.json
-│   │       ├── traceability.json
-│   │       └── summary.md
-│   ├── review
-│   │   ├── .gitignore
-│   │   └── README.md
-│   ├── specs
-│   │   └── README.md
-│   └── README.md
+│   └── waivers.yml
 └── qfai.config.yaml
 ```
 
+`qfai init` does not seed `.qfai` workflow artifacts such as specs, discussions,
+contracts, evidence, reports, reviews, placeholder spec directories, or artifact
+README files. Those files are created later by QFAI skills when real work exists.
+
 Integration wrappers are also generated for immediate use:
 
 - Agents/Codex VS Code: `.agents/skills/**`

package/assets/init/.qfai/assistant/instructions/requirements-decomposition.md

@@ -41,7 +41,7 @@ This document is the decision rule SSOT for AI and humans when answering:
 ### Rule 3 - Keep ambiguity explicit
 
 - Unknowns remain explicit as Open Questions.
-- Resolved answers are promoted to `_policies` or `spec-XXXX` artifacts, then OQ status is updated.
+- Resolved answers are promoted to `_policies` or target spec artifacts, then OQ status is updated.
 
 ## How to decompose (mechanical procedure)
 

package/assets/init/.qfai/assistant/instructions/workflow.md

@@ -49,7 +49,7 @@ Do not proceed without a declared Change Type.
 0. Steering refresh (project memory bootstrap)
 1. Discussion (optional): clarify idea → requirement seed
 2. Requirements: discussion pack in `.qfai/discussion/`
-3. Specification (SDD): unified preflight + `_policies` / `spec-XXXX/01..10`
+3. Specification (SDD): unified preflight + `_policies` / `spec-*/01..10`
 4. Prototyping (optional): contract-aligned implementation skeleton
 5. Acceptance tests (ATDD): runnable E2E/API/Integration tests derived from specs/contracts obligations (`US` / `TC` / `CON-API`)
 6. Verify: run quality gates and provide evidence
@@ -59,7 +59,7 @@ Stage 3 (`/qfai-sdd`) target policy:
 - With argument (`/qfai-sdd <spec-id-or-name>`): scope is the matched single spec only.
 - Without argument (`/qfai-sdd`): scope is all capabilities from `.qfai/specs/_policies/03_Capabilities.md` in order.
 - `/qfai-sdd` must create or refresh `.qfai/specs/_policies/11_Slice-Policy.md` before deciding whether a spec change is CREATE / UPDATE / DELETE.
-- For no-argument batch runs, execute Contracts-first and Outline once, then delegate Slice/Plan/Delta in parallel per `spec-XXXX`.
+- For no-argument batch runs, execute Contracts-first and Outline once, then delegate Slice/Plan/Delta in parallel per target spec.
 
 Prototyping stage policy:
 

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

@@ -40,11 +40,11 @@ Skill-specific examples:
 
 - Follow `.qfai/assistant/instructions/shared-skill-operating-baseline.md#format-ssot-mandatory`.
 
-- Before writing or editing any `.qfai/**` artifact, read and follow the relevant directory README template and sample:
-  - `.qfai/discussion/README.md`
-  - `.qfai/specs/README.md`
-  - `.qfai/contracts/**/README.md`
-  - `.qfai/evidence/README.md`
+- Before writing or editing any `.qfai/**` artifact, read the relevant skill-local reference or template:
+  - `.qfai/assistant/skills/qfai-discussion/references/discussion-artifact-rules.md`
+  - `.qfai/assistant/skills/qfai-sdd/references/spec-traceability-rules.md`
+  - `.qfai/assistant/skills/qfai-sdd/references/contract-artifact-rules.md`
+  - `.qfai/assistant/skills/qfai-prototyping/references/evidence-requirements.md`
 
 ## Inputs Priority (Preflight)
 
@@ -244,7 +244,7 @@ These principles are inspired by "constitution / articles" patterns used by othe
 
 ## README Rule
 
-Do not edit any `.qfai/**/README.md` file; raise an Open Question instead.
+Do not create `.qfai/**/README.md` files as scaffold or format documentation; keep artifact guidance in skill references/templates.
 
 - READMEs are reference guides. Follow their structure, templates, and checklists.
 

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

@@ -46,8 +46,6 @@ UI-bearing packs must produce the following sidecars as primary truth:
 - `uiux/30_exploration_brief.md`
 - `uiux/31_reference_pool.md`
 - `uiux/32_design_anti_goals.md`
-- `uiux/33_exploration_rubric.md`
-- `uiux/34_evaluator_calibration.md`
 - `uiux/40_screen_contracts.md`
 - `uiux/50_review_input_bundle.md`
 
@@ -68,12 +66,14 @@ For UI-bearing targets, follow `references/design-dna-intake.md` while authoring
 
 ## UI-bearing Authoring Requirements
 
-- `30_exploration_brief.md` must define product intent, must-preserve interactions, brand signals, and differentiation targets.
-- `31_reference_pool.md` must define exploration references, adopted points, rejected points, local translation, copy risk, and template usage policy.
-- `32_design_anti_goals.md` must contain explicit anti-goals and recurrence prevention notes.
-- `33_exploration_rubric.md` must define design quality, originality, craft, functionality, brand memorability, category distinctiveness, template dependency risk, and localization-fit grading criteria.
-- `34_evaluator_calibration.md` must include good critique examples, too-lenient examples, blandness-fail examples, originality-fail examples, and template-copy fail examples.
-- `50_review_input_bundle.md` must document best-of-history handling so later iterations are not automatically preferred.
+- `30_exploration_brief.md` must define product intent, brand signals, and differentiation targets.
+- `31_reference_pool.md` must define exploration references with adopted points, rejected points, and copy risk — framed as **deviate-from** inputs (not imitate-this) for downstream `/qfai-prototyping` reviewer.
+- `32_design_anti_goals.md` must contain explicit anti-goals; this also feeds the global anti-slop pattern list consulted by the v2.0 reviewer.
+- `50_review_input_bundle.md` must document review inputs for downstream skills.
+
+v1.x sidecars `33_exploration_rubric.md` and `34_evaluator_calibration.md`
+are removed in spec-0017 P4 (axes are global constants in
+`core/prototyping/iteration.ts#OrdinalScore`, ordinal 4-step scale).
 
 ## Completion Contract (Shared)
 

package/assets/init/.qfai/assistant/skills/qfai-discussion/references/design-dna-intake.md

@@ -22,7 +22,9 @@ Use this reference only for UI-bearing discussion packs.
 ## Output Mapping
 
 - Put product intent and brand signals in `30_exploration_brief.md`.
-- Put all reference decisions in `31_reference_pool.md`.
-- Put prohibited visual directions in `32_design_anti_goals.md`.
-- Put brand and template-risk scoring in `33_exploration_rubric.md`.
-- Put examples of good critique and weak critique in `34_evaluator_calibration.md`.
+- Put all reference decisions in `31_reference_pool.md` (deviate-from input, not imitate).
+- Put prohibited visual directions in `32_design_anti_goals.md` (also feeds reviewer anti-slop).
+
+v1.x sidecars `33_exploration_rubric.md` and `34_evaluator_calibration.md`
+are removed in spec-0017 P4. Evaluation axes are now global constants in
+`core/prototyping/iteration.ts#OrdinalScore`.

package/assets/init/.qfai/assistant/skills/qfai-discussion/references/discussion-artifact-rules.md

@@ -0,0 +1,62 @@
+# Discussion Artifact Rules
+
+Use this file when `/qfai-discussion` creates or reviews `.qfai/discussion/discussion-*` packs.
+
+## Required Pack
+
+Each pack uses immutable timestamp naming: `.qfai/discussion/discussion-YYYYMMDDhhmmssSSS/`.
+
+Required files:
+
+- `01_Context.md`
+- `02_Inception-Deck.md`
+- `03_Story-Workshop.md`
+- `04_Sources.md`
+- `05_Scope.md`
+- `06_REQ.md`
+- `07_NFR.md`
+- `08_Glossary.md`
+- `09_Constraints.md`
+- `10_Policy.md`
+- `11_OQ-Register.md`
+- `12_OQ-Resolution-Log.md`
+- `13_Deferred.md`
+- `14_Review-Request.md`
+- `99_delta.md`
+
+UI-bearing discussion packs may include `prototyping.yaml` as an optional recommendation artifact; non-ui discussion packs typically omit it. For `ui_bearing: false`, typically omit `prototyping.yaml`. Current discussion-pack readiness does not block on missing `prototyping.yaml`.
+
+## Rules
+
+- Run interview and requirement capture until `Disposition: open` is zero in `11_OQ-Register.md`.
+- OQ `Gate` values are `discussion`, `sdd`, `atdd`, `tdd`, or `ops`.
+- `deferred` is allowed only when `13_Deferred.md` has complete metadata.
+- Discussion outputs are rationale and intake logs; do not duplicate `.qfai/specs/**` SSOT.
+- `03_Story-Workshop.md` must include at least one Mermaid diagram.
+- Use Mermaid fences only for diagrams.
+- `14_Review-Request.md` must reference `.qfai/assistant/steering/agent-routing.yml` and `review-profiles.yml`.
+
+## UI/UX Exploration Family
+
+For UI-bearing packs, use:
+
+- `04_Sources.md` for trend translation and competitive reference registry
+- `uiux/30_exploration_brief.md`
+- `uiux/31_reference_pool.md`
+- `uiux/32_design_anti_goals.md`
+- `uiux/40_screen_contracts.md`
+
+Discussion is exploration-first and must not choose a single visual winner or final design system. Those are downstream prototyping outputs.
+
+## `prototyping.yaml`
+
+When `prototyping.yaml` is present, use the v2.0 single-thread schema:
+
+```yaml
+prototyping:
+  surface: web # web | mobile | desktop | mixed
+```
+
+The v1.x `recommended_mode` / `allowed_modes` / `mode_expectations` fields
+were removed in spec-0017 P3 (the single-thread evolution loop fixes
+iteration count globally to 15).

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/prototyping.yaml

@@ -1,17 +1,9 @@
 prototyping:
-  recommended_mode: full-harness
-  rationale: >
-    Fill this with a concrete reason tied to the full-harness evidence obligations.
-  allowed_modes:
-    - full-harness
+  # v2.0 single-thread evolution loop (spec-0017): mode/maxCycles concepts
+  # are removed; iteration count is fixed at 15 globally in
+  # `core/prototyping/iteration.ts#MAX_ITERATIONS`.
   # Replace `web` with one of the prototyping-supported surfaces if needed:
   #   web | mobile | desktop | mixed
   # (discussion classification also allows `cli` and `non-ui`, but those are
-  #  not valid prototyping execution surfaces; see
-  #  `packages/qfai/src/core/prototyping/surfacePolicy.ts` — PROTOTYPING_SUPPORTED_SURFACES.)
+  #  not valid prototyping execution surfaces.)
   surface: web
-  mode_expectations:
-    full-harness:
-      expected_iterations: "2+"
-      process: "measure -> score -> fix code -> re-run"
-      calibration_ref: "qfai.config.yaml#prototyping.calibration"

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

@@ -60,7 +60,7 @@ Skill-specific examples:
 
 - This skill processes **one test at a time** from `test-list.md`.
 - Each item goes through the full TDD micro-cycle: write a **failing test** first, then make it pass, then refactor.
-- The execution ledger is located at `.qfai/specs/spec-XXXX/tdd/test-list.md`.
+- The execution ledger is located at `.qfai/specs/<spec-id>/tdd/test-list.md`.
 - Items are processed **serially** by default. Parallel processing is allowed only when items target independent SUT slices with no shared state.
 - Status transitions follow a strict forward-only lifecycle: `todo` -> `red` -> `green` -> `refactor` -> `done`.
 - The `exception` status can be reached from any active status when an anomaly is detected.
@@ -76,15 +76,20 @@ Execute the TDD micro-cycle for each pending item in `test-list.md`, transitioni
 
 - Review rendered output, screenshot evidence, or HTML output before closing any UI-affecting item.
 - Read spec + contract inputs first whenever implementation touches UI or critique-driven behavior.
-- Read order: `01_Spec.md` → `03_Acceptance-Criteria.md` → `05_Examples.md` →
+- Read order (v2.0, spec-0017 P11): `01_Spec.md` → `03_Acceptance-Criteria.md` → `05_Examples.md` →
   `.qfai/contracts/design/exploration-brief.yaml` →
   `.qfai/contracts/design/reference-pool.yaml` → `.qfai/contracts/design/brand-design.yaml` →
-  `.qfai/contracts/design/evaluation-rubric.yaml` → `.qfai/contracts/design/evaluator-calibration.yaml` →
-  `.qfai/contracts/design/selected-direction.yaml` → `.qfai/contracts/design/design-system.yaml` →
+  `.qfai/contracts/design/design-system.yaml` (extracted from final iter) →
   `.qfai/contracts/design/prototype-handoff.yaml` → `.qfai/contracts/ui/*.yaml` →
-  canonical prototype screenshots / HTML snapshots → `.qfai/prototypes/winner/index.html`.
+  canonical prototype evidence under `.qfai/evidence/prototyping/iter-NN/<screen>.{png,html}` →
+  `.qfai/prototypes/final/index.html`.
+- The v1.x evaluation-rubric / evaluator-calibration / selected-direction contracts and
+  `prototypes/winner/index.html` were removed in spec-0017 P4/P8.
 - Do not read discussion-pack UI/UX sidecars, fallback mocks, or legacy design aliases.
-- Prototype code is analysis input, not production source. Reimplement with project-native patterns while preserving `prototype-handoff.yaml` `mustPreserve`; adapt `mayAdapt`; do not copy `mustNotCopy`.
+- Prototype HTML is analysis input, not production source. Reimplement with project-native
+  patterns while preserving the visual identity captured in `prototype-handoff.yaml`
+  `implementationNotes` (free-form prose); the v1.x mustPreserve / mayAdapt / mustNotCopy
+  three-category split is removed.
 - UI-affecting items require product-surface-reviewer prototype parity review before `done`.
 - If code intent and rendered output diverge, treat the rendered/HTML result as the blocking review input and reconcile before DONE.
 
@@ -97,7 +102,7 @@ Execute the TDD micro-cycle for each pending item in `test-list.md`, transitioni
 
 ## Execution Ledger: test-list.md
 
-The execution ledger at `.qfai/specs/spec-XXXX/tdd/test-list.md` tracks progress with these required columns:
+The execution ledger at `.qfai/specs/<spec-id>/tdd/test-list.md` tracks progress with these required columns:
 
 | Column    | Description                                              |
 | --------- | -------------------------------------------------------- |
@@ -298,7 +303,7 @@ Completion MUST NOT be declared when any of the following are true:
 
 ## Evidence (MANDATORY)
 
-Create/update: `.qfai/evidence/implement-spec-XXXX.md`
+Create/update: `.qfai/evidence/implement-<spec-id>.md`
 
 Required sections: