qfai 1.8.4 → 1.8.7

package/README.md

@@ -17,13 +17,14 @@ The agent reads the repository, produces the required artifacts, and iterates un
 
 ## Release status
 
-- Current package version: `1.7.15`
-- Release posture: v1.7.15 enforces runtime truthfulness.
-- Prototyping is UI-only; `full-harness` is measurement-driven iteration accumulation for UI-bearing surfaces only.
+- Release posture: runtime truthfulness is enforced.
+- 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
 
@@ -57,13 +58,19 @@ npx qfai report
   - Produces a human-readable report (`report.md` by default) or an internal JSON export (`report.json`) from `validate.json`; use `--base-url` to link file paths in Markdown to your repository viewer.
 - `npx qfai doctor`
   - Diagnoses configuration discovery, path resolution, glob scanning, and `validate.json` inputs before running validate/report; use `--fail-on` to enforce failures in CI.
-    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.
-    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`).
+    Use `--profile prototyping` to add prototyping-specific preflight checks for the
+    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/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 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[]`,
@@ -87,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.
 
@@ -102,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
 
@@ -115,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/`.
@@ -220,9 +229,9 @@ Notes.
 - `validate.json`, `report.json`, `doctor.json`, and `run-*` JSON logs are internal exports and are not a stable external contract; prefer `report.md` for integrations that must survive tool upgrades.
 - Scenario files are expected to use the Gherkin extension `*.feature` (not `*.md`).
 - `prototyping.calibration.packPath` points to the calibration pack SSOT; runtime and validator both resolve thresholds and iteration parameters from that pack.
-- `prototyping.calibration.thresholds`, `maxIterations`, `plateauDelta`, and `plateauLookback` are unsupported public config fields in v1.7.15.
+- `prototyping.calibration.thresholds`, `maxIterations`, `plateauDelta`, and `plateauLookback` are unsupported public config fields.
   Put calibration values in the referenced pack instead of `qfai.config.yaml`.
-- Observability modules (`src/core/observability/`) exist as foundation code but are **not integrated into blocking validation** in v1.7.14. They are reserved for future operational instrumentation.
+- Observability modules (`src/core/observability/`) exist as foundation code but are **not yet integrated into blocking validation**. They are reserved for future operational instrumentation.
 
 ## Specifications and contracts (SDD)
 
@@ -251,7 +260,7 @@ flowchart LR
 - Contracts SSOT: `.qfai/contracts/**`
 - Report outputs (`.qfai/report/**`) are derived artifacts and not SSOT.
 
-## Minimal tutorial (v1.7.7)
+## Minimal tutorial
 
 1. `npx qfai init`
 2. Run `/qfai-discussion` to structure scope, open questions, and produce a discussion pack under `.qfai/discussion/discussion-<ts>/`.
@@ -368,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
@@ -379,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/**`
@@ -424,6 +404,9 @@ Integration wrappers are also generated for immediate use:
 
 `npx qfai init` installs canonical skills under `.qfai/assistant/skills/**` (SSOT)
 and generates thin wrapper assets for Agents/Codex VS Code / Copilot / Claude Code / Codex.
+Canonical agent markdown under `.qfai/assistant/agents/**` uses a shared YAML frontmatter
+subset (`name`, `description`, `tools`) compatible with Claude Code and GitHub Copilot,
+while Codex consumes mirrored `.codex/agents/*.toml` profiles.
 If wrapper assets drift from canonical skills, rerun `npx qfai init --force` to resync.
 
 ## Contributing (for QFAI maintainers)

package/assets/init/.qfai/assistant/agents/acceptance-test-engineer.md

@@ -1,3 +1,9 @@
+---
+name: acceptance-test-engineer
+description: "Implement E2E, API, and integration acceptance coverage with explicit traceability."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # Acceptance Test Engineer
 
 ## Mission

package/assets/init/.qfai/assistant/agents/architecture-reviewer.md

@@ -1,3 +1,9 @@
+---
+name: architecture-reviewer
+description: "Review architecture and contract decisions for consistency, safety, and rejected-option protection."
+tools: [Read, Glob, Grep, Bash]
+---
+
 # Architecture Reviewer
 
 ## Mission
@@ -22,8 +28,6 @@
 - .qfai/specs/spec-\*/09_delta.md
 - .github/instructions/code-review.instructions.md
 - .github/instructions/principles.instructions.md
-- .instruction/00_universal/development-principles-checklist.md
-- .instruction/01_specialties/design.md
 - Architecture decisions, diagrams, and `.qfai/contracts/**`
 
 ## Deliverables

package/assets/init/.qfai/assistant/agents/backend-engineer.md

@@ -1,3 +1,9 @@
+---
+name: backend-engineer
+description: "Implement backend behavior aligned with specs, API and DB contracts, and operational constraints."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # Backend Engineer
 
 ## Mission
@@ -21,9 +27,6 @@
 - .qfai/specs/spec-\*/09_delta.md
 - .qfai/specs/spec-\*/01_Spec.md
 - .github/instructions/principles.instructions.md
-- .instruction/00_universal/development-principles-checklist.md
-- .instruction/01_specialties/implementation.md
-- .instruction/01_specialties/design.md
 - .qfai/contracts/api/\*\*
 - .qfai/contracts/db/\*\*
 

package/assets/init/.qfai/assistant/agents/completion-reviewer.md

@@ -1,3 +1,9 @@
+---
+name: completion-reviewer
+description: "Independently audit completion contract, prompt DoD, and drift-protocol compliance."
+tools: [Read, Glob, Grep, Bash]
+---
+
 # Completion Reviewer
 
 ## Mission

package/assets/init/.qfai/assistant/agents/delivery-planner.md

@@ -1,3 +1,9 @@
+---
+name: delivery-planner
+description: "Create phased delivery plans, ownership splits, risk controls, and rerun policies."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # Delivery Planner
 
 ## Mission

package/assets/init/.qfai/assistant/agents/devops-ci-engineer.md

@@ -1,3 +1,9 @@
+---
+name: devops-ci-engineer
+description: "Run quality gates and capture reproducible CI and runtime evidence."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # DevOps CI Engineer
 
 ## Mission

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

@@ -1,3 +1,9 @@
+---
+name: discovery-analyst
+description: "Gather pre-knowledge, ask focused questions, and facilitate decision-making."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # Discovery Analyst
 
 ## Mission

package/assets/init/.qfai/assistant/agents/doc-steward.md

@@ -1,3 +1,9 @@
+---
+name: doc-steward
+description: "Keep docs, changelog, and migration notes synchronized with implementation and workflow changes."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # Doc Steward
 
 ## Mission

package/assets/init/.qfai/assistant/agents/frontend-engineer.md

@@ -1,3 +1,9 @@
+---
+name: frontend-engineer
+description: "Implement frontend behavior aligned with the selected direction, finalized design system, screen contracts, and product experience decisions."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # Frontend Engineer
 
 ## Mission
@@ -20,9 +26,6 @@
 - .qfai/specs/spec-\*/09_delta.md
 - .qfai/specs/spec-\*/01_Spec.md
 - .github/instructions/principles.instructions.md
-- .instruction/00_universal/development-principles-checklist.md
-- .instruction/01_specialties/implementation.md
-- .instruction/01_specialties/design.md
 - .qfai/contracts/ui/\*\*
 - UI evidence artifacts when available
 

package/assets/init/.qfai/assistant/agents/implementation-reviewer.md

@@ -1,3 +1,9 @@
+---
+name: implementation-reviewer
+description: "Review code changes for correctness, maintainability, backend safety, and implementation risk."
+tools: [Read, Glob, Grep, Bash]
+---
+
 # Implementation Reviewer
 
 ## Mission
@@ -23,7 +29,6 @@
 - .qfai/specs/spec-\*/09_delta.md
 - .github/instructions/code-review.instructions.md
 - .github/instructions/principles.instructions.md
-- .instruction/00_universal/development-principles-checklist.md
 - Diff of changed files
 - `.qfai/contracts/api/**` and `.qfai/contracts/db/**`
 

package/assets/init/.qfai/assistant/agents/orchestrator.md

@@ -1,3 +1,9 @@
+---
+name: orchestrator
+description: "Plan, delegate, integrate, and enforce stage gates without self-authoring."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # Orchestrator
 
 ## Mission

package/assets/init/.qfai/assistant/agents/product-experience-architect.md

@@ -1,3 +1,9 @@
+---
+name: product-experience-architect
+description: "Own UX, visual design, navigation, screen transitions, and integrated experience direction."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # Product Experience Architect
 
 ## Mission
@@ -22,8 +28,6 @@
 - .qfai/specs/spec-\*/09_delta.md
 - .qfai/specs/spec-\*/01_Spec.md
 - .github/instructions/principles.instructions.md
-- .instruction/00_universal/development-principles-checklist.md
-- .instruction/01_specialties/design.md
 - Exploration brief, reference pool, evaluation rubric, evaluator calibration, selected direction, finalized design system,
   screen contracts, optional tokens, optional fallback HTML/CSS mock, and Mermaid flows
 - Runtime screenshots or rendered evidence when available

package/assets/init/.qfai/assistant/agents/product-surface-reviewer.md

@@ -1,3 +1,9 @@
+---
+name: product-surface-reviewer
+description: "Review UI implementation, usability, design coherence, and service-level product-surface quality."
+tools: [Read, Glob, Grep, Bash]
+---
+
 # Product Surface Reviewer
 
 ## Mission
@@ -11,6 +17,10 @@
 - Audit visual design, token alignment, and service-level UX coherence.
 - Reconcile sidecar artifacts (selected anchor, strategy, screen contracts), design tokens, mermaid flows, and rendered output consistency.
   HTML mock is optional fallback evidence only. Design tokens are supporting input.
+- For UI implementation, compare rendered output against `.qfai/contracts/design/prototype-handoff.yaml`, canonical prototype screenshots, HTML snapshots, and `.qfai/prototypes/winner/index.html`.
+- Reject prototype parity when implementation loses CTA hierarchy, spacing rhythm, information density,
+  surface framing intent, transition clarity, state coverage, or component character captured by the winning
+  prototype.
 - Review UI changes for KISS and YAGNI at the surface layer: avoid needless states, controls, flows, animations, and configuration that are not justified by the product goal.
 - Check naming, structure, and responsibility split of UI components for clarity, cohesion, and minimal surprise.
 - Validate docs/UX consistency so usage text, labels, error states, and user flows match the intended product behavior.
@@ -24,9 +34,8 @@
 - .qfai/specs/spec-\*/09_delta.md
 - .github/instructions/code-review.instructions.md
 - .github/instructions/principles.instructions.md
-- .instruction/00_universal/development-principles-checklist.md
-- .instruction/01_specialties/design.md
 - UI contract files under `.qfai/contracts/ui/`
+- Prototype handoff contract under `.qfai/contracts/design/prototype-handoff.yaml` when available
 - Runtime screenshots / HTML evidence / relevant diffs
 
 ## Deliverables

package/assets/init/.qfai/assistant/agents/qa-gatekeeper.md

@@ -1,3 +1,9 @@
+---
+name: qa-gatekeeper
+description: "Enforce validate, coverage, runtime-proof, and prototyping evidence gates before completion."
+tools: [Read, Glob, Grep, Bash]
+---
+
 # QA Gatekeeper
 
 ## Mission

package/assets/init/.qfai/assistant/agents/qa-strategist.md

@@ -1,3 +1,9 @@
+---
+name: qa-strategist
+description: "Own QA strategy, quality posture, traceability expectations, and failure-handling design."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # QA Strategist
 
 ## Mission

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

@@ -1,3 +1,9 @@
+---
+name: requirements-analyst
+description: "Produce testable requirements, option sets, and explicit open-question ledgers."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # Requirements Analyst
 
 ## Mission

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

@@ -1,3 +1,9 @@
+---
+name: requirements-reviewer
+description: "Review requirements, options, and open-question handling for completeness, neutrality, and safe deferral."
+tools: [Read, Glob, Grep, Bash]
+---
+
 # Requirements Reviewer
 
 ## Mission

package/assets/init/.qfai/assistant/agents/solution-architect.md

@@ -1,3 +1,9 @@
+---
+name: solution-architect
+description: "Define architecture and contract decisions aligned with specs, constraints, and rejected-option history."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # Solution Architect
 
 ## Mission
@@ -23,8 +29,6 @@
 - .qfai/discussion/discussion-\*/04_Sources.md
 - .qfai/discussion/discussion-\*/06_REQ.md
 - .github/instructions/principles.instructions.md
-- .instruction/00_universal/development-principles-checklist.md
-- .instruction/01_specialties/design.md
 - Existing architecture docs and `.qfai/contracts/**`
 
 ## Deliverables

package/assets/init/.qfai/assistant/agents/test-design-analyst.md

@@ -1,3 +1,9 @@
+---
+name: test-design-analyst
+description: "Define test structure, coverage obligations, traceability, and test-scope boundaries."
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
 # Test Design Analyst
 
 ## Mission

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/shared-skill-operating-baseline.md

@@ -39,6 +39,19 @@ Rules:
 - Do not reintroduce options marked as rejected in `09_delta.md`.
 - If a rejected option must be reconsidered, create a `[RE-OPEN]` decision record that references the prior DR-ID, states what changed, and includes explicit approval.
 
+## Gate Failure Autorepair Protocol
+
+When validate, doctor, test, lint, typecheck, build, capture, or report gates fail:
+
+- inspect exit code, logs, `validate.json`, and cited files before reporting;
+- classify each finding as skill-owned artifact, upstream spec/contract, code/test defect, environment/tooling, or user decision;
+- fix skill-owned artifacts and code/test defects autonomously when the fix is local and non-destructive;
+- rerun the same failing gate after each fix batch;
+- do not weaken profiles, lower `--fail-on`, waive errors, invent evidence, or skip required reviewers;
+- stop only for destructive changes, ambiguous product/spec decisions, missing permissions/tools, or repeated no-progress failures.
+
+When stopping, report: cause, attempted fixes, remaining blocker, user action, and retry gate.
+
 ## Completion Contract (Shared)
 
 Before declaring completion, you MUST:

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-atdd/SKILL.md

@@ -60,6 +60,8 @@ When unsure, read inputs in this order:
   - `.qfai/specs/<spec-id>/scenario.feature`
   - coverage ledger files
 
+Do not read discussion-pack UI/UX sidecars. UI-bearing acceptance tests consume only specs and contracts normalized by `/qfai-sdd`.
+
 ## Read Set Contract (Mandatory)
 
 - Default Mode:
@@ -162,6 +164,7 @@ Follow `.qfai/assistant/instructions/shared-skill-operating-baseline.md#delta-re
 ## Completion Contract (Shared)
 
 Follow `.qfai/assistant/instructions/shared-skill-operating-baseline.md#completion-contract-shared`.
+Follow `.qfai/assistant/instructions/shared-skill-operating-baseline.md#gate-failure-autorepair-protocol` for validate, doctor, and quality-gate failures.
 
 ## Goal
 

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)
 
@@ -131,6 +131,7 @@ Follow `.qfai/assistant/instructions/shared-skill-operating-baseline.md#delta-re
 ## Completion Contract (Shared)
 
 Follow `.qfai/assistant/instructions/shared-skill-operating-baseline.md#completion-contract-shared`.
+Follow `.qfai/assistant/instructions/shared-skill-operating-baseline.md#gate-failure-autorepair-protocol` for validate, doctor, and quality-gate failures.
 
 ## Goal
 
@@ -243,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`
 
@@ -64,17 +62,23 @@ UI-bearing packs must produce the following sidecars as primary truth:
 9. Generate `prototyping.yaml` only when the latest discussion pack is UI-bearing and an explicit prototyping recommendation is useful.
 10. Request review and record the Reviewer result.
 
+For UI-bearing targets, follow `references/design-dna-intake.md` while authoring the UI/UX sidecars. Keep this `SKILL.md` compact; put detailed interview prompts and examples in the reference file.
+
 ## 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, and local translation.
-- `32_design_anti_goals.md` must contain explicit anti-goals and recurrence prevention notes.
-- `33_exploration_rubric.md` must define design quality, originality, craft, and functionality grading criteria.
-- `34_evaluator_calibration.md` must include good critique examples, too-lenient examples, blandness-fail examples, and originality-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)
 
+Follow `.qfai/assistant/instructions/shared-skill-operating-baseline.md#gate-failure-autorepair-protocol` for validate, doctor, and quality-gate failures.
+
 Before declaring completion, you MUST:
 
 - verify all 15 mandatory output files exist and are populated;

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

@@ -0,0 +1,30 @@
+# Design DNA Intake
+
+Use this reference only for UI-bearing discussion packs.
+
+## Interview Targets
+
+- Brand personality: list 3-5 traits the product should express.
+- Audience emotion: define what users should feel after the primary task.
+- Category conventions: name the expected layout and interaction patterns for this market.
+- Differentiation targets: state what must feel unlike generic SaaS, generic shadcn, or direct competitors.
+- Anti-template constraints: name default visual patterns that must not survive into prototyping.
+- Reference strategy: collect competitor, adjacent, aspirational, template-seed, and anti-pattern references.
+
+## Reference Rules
+
+- Treat templates as seeds, not winners.
+- Capture both adopted and rejected points for every reference.
+- Translate references into local product rules instead of copying visual surfaces.
+- Record copy risk as `low`, `medium`, or `high`.
+- Record template usage policy as `none`, `reference-only`, or `implementation-seed`.
+
+## Output Mapping
+
+- Put product intent and brand signals in `30_exploration_brief.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`.