qfai 1.7.8 → 1.7.13

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

@@ -6,329 +6,250 @@ argument-hint: "[--auto]"
 allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
 roles:
   [
-    FullStackEngineer,
-    BackendEngineer,
-    FrontendEngineer,
-    DBEngineer,
-    DevOpsCIEngineer,
-    QAEngineer,
-    RuntimeGatekeeper,
-    UIUXReviewer,
-    CodeReviewer,
+    orchestrator,
+    delivery-planner,
+    product-experience-architect,
+    frontend-engineer,
+    backend-engineer,
+    devops-ci-engineer,
+    completion-reviewer,
+    product-surface-reviewer,
+    qa-gatekeeper,
   ]
+routing-profile: ui-bearing
 mode: execution-focused
 ---
 
-<!--
-QFAI Skill Body (SSOT)
-- This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills).
-- Keep wrappers thin and route users to this skill body.
--->
+<!-- QFAI Skill Body (SSOT) -->
 
 ## /qfai-prototyping
 
 [DRIFT-PROTOCOL:MANDATORY]
 
-## User Questions (AskUserQuestion Protocol)
-
-- When a question to the user is needed (e.g., implementation scope decisions, runtime environment confirmation),
-  the agent MUST use AskUserQuestion if the tool is available.
-- When AskUserQuestion supports structured choices (radio/multi-select),
-  the agent MUST prefer structured choices over free-text input.
-- If AskUserQuestion is technically unavailable, present the same question as a normal message
-  with explicit numbered choices.
-  The agent SHOULD preserve structured choice semantics (enumerated options, selection constraints).
-  The reason for unavailability MUST be stated.
-
-Run prototyping as an **all-spec stage**. Scope is fixed to **ALL specs** resolved from `.qfai/specs/spec-*`.
-
-This stage is complete only when all specs pass the minimum runtime contract:
-
-- UI routes are reachable (no dead `#` links for primary flows).
-- API endpoints return non-404 statuses.
-- DB objects needed for runtime are present (real DB or documented in-memory substitute).
-- Evidence is captured and validate can enforce it.
-
-## Visual Review Guard
-
-- Review rendered output, screenshot captures, or generated HTML for every UI-affecting slice; code-only inspection is insufficient.
-- Read the DDP (Design Direction Pack) first before comparing visuals or wiring critique outcomes into implementation.
-- Read order: DDP -> Design Token -> UI Contract -> HTML Mock -> Flow.
-- If rendered/HTML evidence disagrees with code intent, fix the rendered result before declaring completion.
-
-## Definition of Done by fidelity level (Mandatory)
-
-- L1 (`skeleton`):
-  - Route-level rendering exists for declared primary screens.
-  - Surface shape is visible, but interactions may remain minimally wired.
-- L2 (`interactive`, default):
-  - Declared primary interactions are wired with mockable behavior.
-  - At least one declared mock path is executed and recorded per primary flow set.
-  - `uiFidelity` is produced in `prototyping.json`.
-- Default target is L2 (`interactive`).
-  - If L1 fallback is chosen, record explicit user approval and rationale in evidence.
-- Placeholder-only pages (single static string, lorem ipsum, or equivalent) are `REVISE`.
-
-## FORMAT SSOT (Mandatory)
-
-- Before writing or editing any `.qfai/**` artifact, read and follow the relevant directory README template and sample:
-  - `.qfai/require/README.md`
-  - `.qfai/specs/README.md`
-  - `.qfai/contracts/**/README.md`
-  - `.qfai/evidence/README.md`
-- Do not copy templates/samples into this prompt or into other prompt markdown.
-- Generated artifacts must match README-defined structure (headings, ordering, table columns).
-- Completion requires a Format Self-Check in evidence.
-
-## Inputs Priority (Preflight)
-
-When unsure, read inputs in this order:
-
-- P1: `.qfai/assistant/instructions/*`
-- P2: `.qfai/assistant/steering/*`
-- P3: `.qfai/specs/spec-*/01_Spec.md` (Primary SSOT / Consumer View)
-- P4: `.qfai/contracts/ui/**`, `.qfai/specs/_policies/05_Contracts.md`, and each `spec-*/11_Contracts.md`
-- P5: `.qfai/specs/spec-*/09_delta.md` (Decision Records)
-- P6: existing evidence
-
-## Read Set Contract (Mandatory)
-
-- Default Mode:
-  - `.qfai/specs/spec-*/01_Spec.md`
-  - relevant `.qfai/contracts/ui/**`
-- Escalation Mode:
-  - allowed only when `01_Spec.md` Escalation Hook signals ambiguity / conflict / missing constraint / trade-off
-  - read only `.qfai/specs/_policies/01_Objective.md`, `.qfai/specs/_policies/07_Constraints.md`, `.qfai/specs/_policies/08_Decisions.md`
-- Do not read `_policies/**` by default.
+This skill is **static-first**. File-based checks and evidence are the default. Runtime-heavy verification is reserved for **explicit full-harness** runs only.
 
-## Sub-agent Delegation (MANDATORY)
+## CRITICAL CONSTRAINTS (Read First)
 
-This section is mandatory and overrides conflicting fallback text.
+- Scope is **ALL specs** from `.qfai/specs/spec-*`.
+- Evidence is mandatory in **markdown + json** under `.qfai/evidence/`.
+- `DONE is forbidden` until prototyping evidence, reviewer gate, and `qfai validate --fail-on error` pass.
+- `qfai prototyping run` is available as an auxiliary generate-side command, not the primary surface for this skill.
+- Defaulting to full-harness is prohibited.
+- If a required API endpoint still returns `404`, the run is incomplete.
+- `L1` and `L2` critique findings must be reflected in the evidence pack or justified as `REVISE`.
+- `uiFidelity` is the canonical UI evidence block for UI-bearing surfaces.
+- non-ui skip semantics must be preserved. UI-only placeholders are not required when the surface is non-ui.
+- Review rendered output, screenshot evidence, HTML snapshots, or preview artifacts before closing any UI-affecting run.
+- Read the canonical sidecar family first: option comparison / `30_option_comparison.md` -> selected anchor screen / `31_selected_anchor_screen.md` -> strategy / `10_implementation_strategy.md` -> taste interview / `11_design_taste_interview.md` -> trend scan / `04_Sources.md` -> 3-layer evaluation family (`20/21/22/23` + optional `24`) -> screen contracts / `40_screen_contracts.md` -> review input bundle / `50_review_input_bundle.md`.
 
-### Orchestrator Protocol (MUST)
+## Goal
 
-- Orchestrator may only create work orders, delegate tasks, integrate outputs, and present results to the user.
-- Orchestrator MUST NOT generate the primary artifact first draft.
-- Orchestrator MUST NOT serve as Reviewer or skip delegation for convenience.
+Build the minimum runnable vertical slice for **ALL specs** and produce canonical prototyping evidence under `.qfai/evidence/`.
 
-### Capability Probe (MUST)
+## Non-goals
 
-1. Run one harmless Probe Task (for example: "reply with ok") once at stage start.
-2. If subagents are unavailable, explicitly ask the user for Simulation mode approval.
-3. Without explicit approval, stop the stage.
+- Acceptance test automation (`/qfai-atdd`)
+- Contract redesign
+- Public CLI surface expansion
 
-### Simulation mode (Opt-in only)
+## Mode Selection Protocol
 
-- Allowed only when the user explicitly states `Simulation mode allowed`.
-- Record both in evidence:
-  - `Subagents: simulated (reason: <why unavailable>)`
-  - `User approval: <quote or reference>`
+Mode selection precedence:
 
-## Work Orders Summary
+1. explicit request (`mode=low-cost|standard|full-harness`)
+2. discussion recommendation from `prototyping.yaml`
+3. default `standard`
 
-Every major artifact in this stage MUST include this table:
+Record in `prototyping.json`:
 
-| Step | Role (sub-agent) | Task title | Input (refs) | Output (refs) | Status (PASS/REVISE) |
-| ---- | ---------------- | ---------- | ------------ | ------------- | -------------------- |
-| 1    | <role>           | <task>     | <refs>       | <refs>        | PASS/REVISE          |
+- `mode.requested` (optional)
+- `mode.effective` (required)
+- `mode.source` (required)
+- `mode.rationale` (required)
+- `mode.discussionRecommendation` (optional)
 
-### Reviewer Gate (MUST)
+## Surface Semantics
 
-- Final completion gate MUST be delegated to an independent Reviewer sub-agent.
-- Reviewer checks (minimum):
-  - required roles were delegated (no orchestrator self-authoring),
-  - evidence + validate gate is present,
-  - Drift Protocol was enforced,
-  - test-layer obligations match `test-layers.md` and plan,
-  - floors and ratios are **signals, not gates**.
-- Reviewer returns only `PASS` or `REVISE`.
-- **All reviewers: alternative proposal obligation**:
-  - Every reviewer MUST provide a concrete alternative or fix proposal when returning FAIL. Feedback without a concrete alternative is invalid and triggers re-judgment.
-- **devils-advocate gate**:
-  - devils-advocate FAIL must include a concrete alternative proposal. Bare negation FAIL triggers re-judgment.
-  - 3 consecutive FAILs trigger advisory demotion and allow progression to the next phase.
-- **pattern-doubler gate**:
-  - Each pattern proposed by pattern-doubler must include rationale.
-  - Artifacts with no ID-bearing items (US/AC/BR/EX/TC) are marked N/A.
-
-### Work order template (copy/paste)
-
-```text
-Task title: <short>
-Role: <sub-agent role>
-Goal: <what to decide/produce>
-Inputs (refs):
-- <file/section>
-Constraints:
-- must: enforce Drift Protocol
-- must: verify plan/test-layer adherence (`test-layers.md` + plan)
-- must: verify `qfai validate --fail-on error` evidence
-- must_not: accept floor/ratio as hard gate
-Output format:
-- <headings / bullet schema>
-Quality bar:
-- PASS if ...
-- REVISE if ...
-```
-
-### Reviewer response template
-
-```text
-Result: PASS | REVISE
-Findings:
-- <issue>
-Required fixes:
-- <action>
-Evidence checked:
-- <refs>
-```
-
-## Stage 0 - Steering completion refresh (mandatory)
-
-Before implementation, refresh and verify:
-
-- `.qfai/assistant/steering/manifest.md`
-- `.qfai/assistant/steering/product.md`
-- `.qfai/assistant/steering/structure.md`
-- `.qfai/assistant/steering/tech.md`
-
-If facts are missing, record Open Questions and ask the user.
-
-## Delta Rejected Guard (Mandatory)
-
-- Do not reintroduce options marked as rejected in 09_delta.md.
-- If reconsideration is needed, create a `[RE-OPEN]` Decision Record with explicit approval.
+- `surface: non-ui` means UI-specific evidence is `n/a`.
+- For non-ui projects, `uiFidelity`, render evidence, browser QA, and `runtimeGate.ui` may be absent.
+- Absent is normal for non-ui. Do not force skipped placeholders unless the project intentionally emits them.
+- For UI-bearing projects, route/contract fidelity must be captured when `uiFidelity` is required by mode.
 
-## CRITICAL CONSTRAINTS (Read First)
+## Prototyping Modes
 
-- Scope is ALL specs from `.qfai/specs/spec-*`; do not shrink to one spec.
-- Contracts are strict inputs in this stage.
-- Do not create new files under `.qfai/contracts/**`.
-- If any spec has zero resolved contracts, STOP and route back to `/qfai-discussion`.
-- Do not add ATDD/TDD automation in this stage.
-- You MUST produce both prototyping evidence artifacts in `.qfai/evidence/`.
-- You MUST run runtime checks and capture evidence.
-- DONE is forbidden when Coverage Matrix is incomplete or API checks include status 404.
+### Low-cost
 
-## Completion Contract (Shared)
+- Static checks only.
+- Suitable for early skeleton work.
+- UI-bearing projects may include `uiFidelity` and render/browser artifacts, but they are optional.
+- `skeleton` mode is allowed for lightweight UI proof.
 
-Before declaring completion, you MUST:
+### Standard
 
-- resolve or explicitly defer ambiguous items,
-- verify every required artifact exists and is complete,
-- scan outputs for placeholders (TBD/TODO/OPEN QUESTION and equivalents),
-- run the smallest executable smoke proof and record outcomes.
+- Static checks plus optional light validation.
+- This is the default mode.
+- UI-bearing projects require `uiFidelity`.
+- Runtime gate, render bundle, and browser QA bundle are optional.
 
-## Goal
+### Full-harness
 
-Build the minimum runnable vertical slice for **all specs** so `/qfai-atdd` can proceed without hidden scope gaps.
+- Explicit opt-in only. Never auto-activate.
+- Adds runtime-heavy obligations and full-harness audit metadata.
+- UI-bearing projects require runtime gate, render bundle, browser QA bundle, and `fullHarness`.
+- Non-ui projects require `fullHarness`, but UI-specific bundles remain n/a.
 
-## Non-goals
+## Obligation Matrix
 
-- Acceptance test automation (`/qfai-atdd`).
-- Unit/component tests (TDD phases).
-- Contract redesign during prototyping.
+### surface / mode
 
-## Mandatory Outputs
+| surface / mode            | specs    | runtimeGate | uiFidelity                        | render evidence                      | browser QA   | fullHarness  |
+| ------------------------- | -------- | ----------- | --------------------------------- | ------------------------------------ | ------------ | ------------ |
+| non-ui / low-cost         | required | optional    | n/a                               | n/a                                  | n/a          | absent       |
+| non-ui / standard         | required | optional    | n/a                               | n/a                                  | n/a          | absent       |
+| non-ui / full-harness     | required | optional    | n/a                               | n/a                                  | n/a          | required     |
+| ui-bearing / low-cost     | required | optional    | optional (`skeleton` allowed)     | optional (`captured/skipped/failed`) | optional     | absent       |
+| ui-bearing / standard     | required | optional    | **required** (`interactive` only) | optional (`captured/skipped/failed`) | optional     | absent       |
+| ui-bearing / full-harness | required | required    | **required** (`interactive` only) | **required**                         | **required** | **required** |
 
-- Updated runnable skeleton implementation.
-- Coverage Matrix for all specs.
-- Runtime Gate v2 log for declared UI routes and API endpoints.
-- Prototyping evidence artifacts (markdown + json) under `.qfai/evidence/`.
-- `prototyping.json` includes `uiFidelity` for L2 reporting.
-- Reviewer result (`PASS` or actionable `REVISE`).
+`uiFidelity.mode` policy:
 
-## Scope SSOT (ALL contracts -> ALL specs)
+- `low-cost`: `skeleton` or `interactive`
+- `standard`: `interactive` only — `skeleton` is rejected by the validator
+- `full-harness`: `interactive` only — `skeleton` is rejected; render evidence, Browser QA, runtimeGate, and fullHarness block are all required
+- `non-ui`: `uiFidelity` is not emitted
 
-1. Enumerate all specs from `.qfai/specs/spec-*`.
-2. Resolve each spec's contracts via `_policies/05_Contracts.md` and/or `spec-*/11_Contracts.md`.
-3. Do not declare completion while any spec lacks contract assignment.
+Interpretation:
 
-## Preflight (required)
+- `required`: validator enforces presence and completeness
+- `optional`: if present, schema must be valid; if absent, no issue
+- `n/a`: absent is normal success
 
-- Build spec list first and create Coverage Matrix rows for every spec.
-- Resolve declared counts per spec:
-  - `uiRoutes`
-  - `apiEndpoints`
-  - `dbObjects`
-- Stop conditions:
-  - any spec has zero contract assignment,
-  - UI primary flow is undefined for a spec,
-  - evidence schema cannot represent all specs.
+## Required Evidence
 
-## Execution (required)
+### Evidence (MANDATORY)
 
-Process specs in dependency order (foundation first, then business modules):
+- `.qfai/evidence/prototyping.md`
+- `.qfai/evidence/prototyping.json`
+- `.qfai/evidence/render.json` when render evidence is emitted or required by mode
+- `.qfai/evidence/browser-qa.json` when browser QA evidence is emitted or required by mode
+- `Coverage Matrix` covering all specs
+- critique summary with `L1` / `L2` findings and disposition
 
-- UI: primary route renders (stub data is acceptable).
-- API: declared endpoints return non-404 status (stub handler is acceptable).
-- DB: minimum schema/store exists so runtime does not crash.
-- UI quality floor: avoid placeholder-only pages; this must be marked `REVISE`.
+### low-cost obligations
 
-## Runtime Interaction Gate v2 (required)
+- always: `specs[]`, `meta.generatedAt`, `meta.toolVersion`, `meta.commands[]`, `mode.*`
+- ui-bearing: `uiFidelity` optional, render/browser optional
+- non-ui: UI-specific evidence is n/a
 
-Check the **full declared list** from preflight and record all results:
+### standard obligations
 
-- UI routes: HTTP GET / route navigation checks.
-- API endpoints: runtime calls with status capture (`404` is forbidden).
-- DB objects: presence checks against schema or temporary store.
-- Mock paths: record at least one pass path for interactive flows when L2 is targeted.
+- always: `specs[]`, `meta.*`, `mode.*`
+- ui-bearing: `uiFidelity` required
+- non-ui: UI-specific evidence is n/a
+- runtime gate and browser QA remain optional
 
-If any check fails, completion is blocked.
+### full-harness obligations
 
-## Evidence (MANDATORY)
+- always: `specs[]`, `meta.*`, `mode.*`, `fullHarness`
+- ui-bearing: `runtimeGate`, `.qfai/evidence/render.json`, `.qfai/evidence/browser-qa.json`, `uiFidelity`
+- non-ui: UI-specific evidence remains n/a
 
-Create/update both artifacts in `.qfai/evidence/`:
+## Full-harness minimum completeness
 
-1. Markdown evidence with sections:
-   - Coverage Matrix
-   - Runtime Gate Log
-   - Deviations / Exceptions
-   - Work Orders Summary
-   - Format Self-Check
-2. JSON evidence with minimum fields:
-   - `specs[]` with `specId`, `declared`, `checked`, `missing`
-   - `runtimeGate.ui[]` and `runtimeGate.api[]`
-   - `uiFidelity.version`, `uiFidelity.mode`, `uiFidelity.screens[]` for L2
-   - `meta.generatedAt`, `meta.toolVersion`, `meta.commands[]`
+When `mode.effective = full-harness`, record:
 
-`uiFidelity` is a stage DoD requirement in this skill.
-Validator compatibility remains backward-compatible: existing required fields stay unchanged.
+- `fullHarness.enabled = true`
+- `fullHarness.available`
+- `fullHarness.runId`
+- `fullHarness.iterationCount >= 1`
+- `fullHarness.bestIteration >= 1`
+- `fullHarness.terminationReason`
+- `fullHarness.reviewerSignoff`
+- `fullHarness.scoringTrace`
 
-## DONE Declaration (Mandatory Output)
+## Canonical Bundles
 
-When declaring DONE, include:
+- render bundle: `.qfai/evidence/render.json`
+- browser QA bundle: `.qfai/evidence/browser-qa.json`
 
-- referenced instructions/steering/spec inputs,
-- DR-IDs checked and rejected-option result,
-- confirmation that evidence and validate gate both passed.
+Render bundle uses `captured | skipped | failed`.
+Browser QA bundle uses `completed | skipped | failed`.
 
-## FINAL CHECKLIST (Check Last)
+## Required Process
+
+1. Read `.qfai/specs/spec-*` and determine the surface and requested mode.
+2. Build the minimum runnable slice across **ALL specs**.
+3. Produce `prototyping.md` and `prototyping.json` with a complete Coverage Matrix.
+4. If UI-bearing, capture `uiFidelity`; if full-harness, capture runtime gate, render bundle, and browser QA bundle.
+5. Review rendered output, screenshot evidence, HTML snapshots, or preview artifacts against the canonical sidecar family.
+6. Record critique findings, classify each as `L1` or `L2`, and either fix or mark the result `REVISE`.
+7. Use the read order `option comparison (30_option_comparison.md) -> selected anchor screen (31_selected_anchor_screen.md) -> strategy (10_implementation_strategy.md) -> taste interview (11_design_taste_interview.md) -> trend scan (04_Sources.md) -> 3-layer evaluation family (20/21/22/23 + optional 24) -> screen contracts (40_screen_contracts.md) -> review input bundle (50_review_input_bundle.md)` when the project is UI-bearing.
+8. Run `qfai validate --fail-on error`.
+9. Route reviewer gate and do not declare completion until the result is `PASS`.
+
+## Sub-agent Delegation (MANDATORY)
+
+### Orchestrator Protocol (MUST)
 
-- [ ] ALL specs from `.qfai/specs/spec-*` are covered in Coverage Matrix.
-- [ ] Every spec satisfies UI/API/DB minimum runtime conditions.
-- [ ] API runtime gate has zero 404 results.
-- [ ] Prototyping evidence artifacts are updated.
-- [ ] `prototyping.json` includes `uiFidelity` for L2 output.
-- [ ] Placeholder-only pages are not accepted (marked `REVISE` if present).
-- [ ] `qfai validate --fail-on error` passes.
-- [ ] Independent Reviewer returned PASS.
+- Orchestrator may only create work orders, delegate tasks, integrate outputs, and present results.
+- Orchestrator MUST NOT self-approve.
+- Orchestrator MUST keep evidence paths canonical and ensure outputs stay under `.qfai/evidence/`.
+
+### Capability Probe (MUST)
+
+1. Run one harmless Probe Task once at stage start.
+2. If subagents are unavailable, explicitly ask for Simulation mode approval.
+3. Without explicit approval, stop the stage.
+
+### Simulation mode (Opt-in only)
+
+- Simulation mode allowed only when user explicitly states `Simulation mode allowed`.
+- Record both:
+  - `Subagents: simulated (reason: <why unavailable>)`
+  - `User approval: <quote or reference>`
+
+## Work Orders Summary
+
+Every major artifact in this stage MUST include this table schema:
+
+| Step | Role (sub-agent) | Task title | Input (refs) | Output (refs) | Status (PASS/REVISE) |
+| ---- | ---------------- | ---------- | ------------ | ------------- | -------------------- |
+| 1    | `role`           | `task`     | `refs`       | `refs`        | PASS/REVISE          |
+
+### Reviewer Gate (MUST)
+
+- Delegate final completion gate to an independent Reviewer.
+- Reviewer checks Drift Protocol compliance and alignment with `.qfai/assistant/steering/test-layers.md`.
+- Test volume floors/ratios are not gates; they are signals.
+- Reviewer must verify evidence obligations for the chosen `surface / mode`.
+- Do not declare DONE until Reviewer returns `PASS`; otherwise apply `REVISE`.
+
+## Completion Contract (Shared)
+
+Before DONE:
+
+- package assets and generated evidence must match the obligation matrix
+- `qfai validate --fail-on error` must pass
+- reviewer gate must return PASS
+- UI-bearing runs must reconcile `uiFidelity`, render evidence, and critique outputs
+- non-ui runs must preserve `n/a` semantics without fake placeholders
+
+## FINAL CHECKLIST (Check Last)
 
-## Completion Checklist (MUST)
+### Completion Checklist (MUST)
 
-- [ ] This skill's Definition of Done is satisfied.
-- [ ] Required artifacts were produced or updated.
-- [ ] Open questions were logged when needed.
-- [ ] Completion message was presented to the user.
-- [ ] Next actions were enumerated.
+- All specs are covered in the Coverage Matrix.
+- `prototyping.md` and `prototyping.json` are both updated.
+- Required mode/surface evidence is present.
+- `404` findings are resolved or the run is not complete.
+- `L1` / `L2` critique findings are documented and dispositioned.
+- `uiFidelity` is present when required.
+- Reviewer returned `PASS`; otherwise status is `REVISE`.
 
 ## Completion Message & Next Actions (MUST)
 
-When complete, provide a final user-facing completion message and list actions.
+Action:
 
-- Proceed (recommended): `/qfai-atdd`.
-  Action: implement acceptance tests against the all-spec prototype runtime behavior.
-- Quality gate run: `/qfai-verify`.
-  Action: run full validation/report flow and publish gate evidence.
-- Rework prototyping: rerun `/qfai-prototyping`.
-  Action: fix missing matrix rows, 404 findings, or unresolved contract mapping gaps.
+- Proceed: `/qfai-atdd`
+- Quality gate: `/qfai-verify`
+- Rework prototyping: rerun `/qfai-prototyping` with corrected evidence