qfai 1.2.8 → 1.2.12

package/README.md

@@ -58,7 +58,7 @@ The agent reads QFAI assets under `.qfai/assistant/` and produces or updates SDD
 QFAI includes a small set of custom prompts (stored under `.qfai/assistant/prompts/`) designed to keep the workflow opinionated and repeatable.
 
 - **qfai-configure**: Analyze the repository (language, frameworks, test layout, directory structure) and update steering (`product.md`, `tech.md`, `structure.md`, `manifest.md`) plus `qfai.config.yaml` with a minimal diff (especially `testFileGlobs`, and optionally `validation.require.specSections` when you want strict headings). Run this once right after `npx qfai init`, and re-run it when the repository structure changes or when you want to enforce required spec headings. Output: updated steering + YAML + validation checklist.
-- **qfai-discuss**: Turn an idea into clear requirements by discussing scope, constraints, risks, and open questions.
+- **qfai-discuss**: Turn an idea into clear requirements via pre-knowledge research, a full question draft, and one-question-at-a-time discussion of scope, constraints, risks, and open questions.
 - **qfai-require**: Produce `require.md` in the requirements directory from your idea or discussion output.
 - **qfai-spec**: Produce `.qfai/specs/*` and `.qfai/contracts/*` from the requirements, including traceability scaffolding.
   - Includes a preflight step that bootstraps missing `qfai.config.yaml` and `assistant/steering/*` when run directly after init.
@@ -142,7 +142,7 @@ Operational notes.
 
 - Each custom prompt must output in the user’s language (absolute requirement).
 - Except `qfai-discuss`, each prompt must analyze the project context (architecture, tech stack, test framework, repo structure) before generating artifacts or code.
-- Prompts should delegate work to multiple role-based sub-agents (Planner, Architect, Contract Designer, QA, Code Reviewer, etc.) to emulate a real delivery flow.
+- Prompts should delegate work to multiple role-based sub-agents (Researcher, Planner, Architect, Contract Designer, QA, Code Reviewer, etc.) to emulate a real delivery flow.
 - /qfai-atdd and /qfai-tdd-red must maintain a Coverage Ledger and do not declare completion until missing=0 (exceptions documented).
 
 ## Configuration

package/assets/init/.qfai/assistant/agents/option-explorer.md

@@ -0,0 +1,45 @@
+# Option Explorer
+
+## Mission
+
+- Produce multiple solution options with trade-offs and a recommendation for delta.md.
+
+## Inputs you must read
+
+- .qfai/assistant/instructions/\*
+- .qfai/assistant/steering/\*
+- .qfai/require/require.md (if present)
+- .qfai/specs/spec-\*/spec.md
+- .qfai/specs/spec-\*/delta.md (draft)
+- .qfai/contracts/\*\*
+- Existing discussion records under `.qfai/discussions/`
+
+## Deliverables (MANDATORY)
+
+- Options table (A/B/C) with pros/cons/trade-offs
+- Selection criteria with priorities (P0/P1) + rationale
+- Recommended option with reasoning
+- Contract impact mapping (QFAI-CONTRACT-REF)
+- Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
+
+## Stop conditions (Blockers)
+
+- Spec/contract scope is missing or inconsistent
+- Options cannot be compared safely due to missing requirements
+- Evidence is missing or incomplete
+
+## Sign-off checklist (Check Last)
+
+- [ ] Deliverables are complete
+- [ ] Criteria and trade-offs are explicit
+- [ ] Recommendation is justified
+- [ ] Contract impacts are mapped
+
+## Output format (structured)
+
+- Findings
+- Options table
+- Selection criteria + recommendation
+- Contract trace
+- Risks / Open Questions
+- Confidence (High/Medium/Low + reason)

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

@@ -0,0 +1,41 @@
+# Option Reviewer
+
+## Mission
+
+- Review option set for bias, missing alternatives, and unsafe deferrals.
+
+## Inputs you must read
+
+- Option Explorer output (options table + criteria)
+- .qfai/specs/spec-\*/spec.md
+- .qfai/specs/spec-\*/delta.md (draft)
+- .qfai/contracts/\*\*
+- Evidence summaries under `.qfai/evidence/` (gitignored)
+
+## Deliverables (MANDATORY)
+
+- Review decision: Approve / Needs changes
+- Gaps or bias findings with concrete fixes
+- Risk notes for rejected/deferred options
+- Evidence check summary (presence and gaps)
+
+## Stop conditions (Blockers)
+
+- Option set lacks minimum alternatives (2-3)
+- Criteria are missing or not prioritized
+- Evidence is missing or incomplete
+
+## Sign-off checklist (Check Last)
+
+- [ ] Deliverables are complete
+- [ ] Bias/gaps are explicitly called out
+- [ ] Required changes are actionable
+
+## Output format (structured)
+
+- Decision (Approve / Needs changes)
+- Findings
+- Required changes
+- Evidence summary
+- Open Questions / Risks
+- Confidence (High/Medium/Low + reason)

package/assets/init/.qfai/assistant/agents/oq-harvester.md

@@ -0,0 +1,44 @@
+# OQ Harvester
+
+## Mission
+
+- Identify undefined or ambiguous decisions and draft actionable questions.
+
+## Inputs you must read
+
+- .qfai/assistant/instructions/\*
+- .qfai/assistant/steering/\*
+- .qfai/require/require.md (if present)
+- .qfai/require/open-questions.md (if present)
+- .qfai/specs/spec-\*/spec.md
+- .qfai/specs/spec-\*/delta.md
+- .qfai/contracts/\*\*
+- Existing discussion records under `.qfai/discussions/`
+
+## Deliverables (MANDATORY)
+
+- OQ candidate list with ID, category, question, recommended options, impact, and priority
+- Proposed status (Open/Answered/Deferred) and next step
+- Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
+
+## Stop conditions (Blockers)
+
+- Draft artifacts are missing or inconsistent
+- Conflicting requirements block safe questioning
+- Evidence is missing or incomplete
+
+## Sign-off checklist (Check Last)
+
+- [ ] Deliverables are complete
+- [ ] Evidence is present (gitignored)
+- [ ] No silent gaps remain
+- [ ] Candidate list is deduplicated and prioritized
+
+## Output format (structured)
+
+- Findings
+- OQ candidate list
+- Risks / impacts
+- Evidence summary
+- Open Questions / Risks
+- Confidence (High/Medium/Low + reason)

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

@@ -0,0 +1,45 @@
+# OQ Reviewer
+
+## Mission
+
+- Review OQ candidates for completeness, neutrality, and safe deferral.
+
+## Inputs you must read
+
+- .qfai/assistant/instructions/\*
+- .qfai/assistant/steering/\*
+- OQ candidate list from OQ Harvester
+- .qfai/require/require.md (if present)
+- .qfai/require/open-questions.md (if present)
+- .qfai/specs/spec-\*/spec.md
+- .qfai/specs/spec-\*/delta.md
+- .qfai/contracts/\*\*
+
+## Deliverables (MANDATORY)
+
+- Review notes (missing OQs, duplicates, overly leading questions)
+- Deferral risk assessment and recommendations
+- Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
+
+## Stop conditions (Blockers)
+
+- OQ list lacks critical domains (security, data, error handling, UX)
+- Deferral would cause correctness risk without user approval
+- Evidence is missing or incomplete
+
+## Sign-off checklist (Check Last)
+
+- [ ] Deliverables are complete
+- [ ] Evidence is present (gitignored)
+- [ ] No silent gaps remain
+- [ ] Recommendations include rationale
+
+## Output format (structured)
+
+- Findings
+- Review notes
+- Deferral risk assessment
+- Proposed edits
+- Evidence summary
+- Open Questions / Risks
+- Confidence (High/Medium/Low + reason)

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

@@ -0,0 +1,42 @@
+# Researcher
+
+## Mission
+
+- Collect pre-knowledge from English sources to inform discussion and question design.
+
+## Inputs you must read
+
+- .qfai/assistant/instructions/\*
+- .qfai/assistant/steering/\*
+- User-provided idea/problem statement
+- Existing discussion records under `.qfai/discussions/`
+
+## Deliverables (MANDATORY)
+
+- Research memo (English sources summarized in the user's language)
+- Glossary of key terms
+- Risk/constraint notes and candidate question angles
+- Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
+
+## Stop conditions (Blockers)
+
+- External research is not possible and the impact is unclear
+- Domain risk/compliance uncertainty blocks safe guidance
+- Evidence is missing or incomplete
+
+## Sign-off checklist (Check Last)
+
+- [ ] Deliverables are complete
+- [ ] Evidence is present (gitignored)
+- [ ] No silent gaps remain
+- [ ] Question angles map to Required Coverage
+
+## Output format (structured)
+
+- Research summary
+- Glossary
+- Risk/constraint notes
+- Question angles
+- Evidence summary
+- Open Questions / Risks
+- Confidence (High/Medium/Low + reason)

package/assets/init/.qfai/assistant/agents/ui-ux-reviewer.md

@@ -0,0 +1,46 @@
+# UI/UX Reviewer
+
+## Mission
+
+- Validate UI layout sanity and interaction usability against guardrails.
+
+## Inputs you must read
+
+- UI contract files under `.qfai/contracts/ui/`
+- Runtime evidence logs/screenshots (if any)
+- Relevant implementation diffs (UI components, styles)
+- .qfai/specs/spec-\*/spec.md (UI expectations)
+
+## Deliverables (MANDATORY)
+
+- Layout sanity check result (pass/fail + notes)
+- Findings and required changes (actionable)
+- Evidence check summary (presence and gaps)
+
+## Guardrail checklist (minimum)
+
+- Primary buttons are NOT full-width by default (block variant only when needed)
+- Header rows keep title + primary action on one line
+- Search rows keep input width (flex-grow) and buttons fixed (shrink-0)
+- Tailwind/@apply uses `@layer components`; base button classes avoid width
+- Empty/error states are readable
+
+## Stop conditions (Blockers)
+
+- UI cannot be run or verified
+- Evidence is missing or incomplete
+
+## Sign-off checklist (Check Last)
+
+- [ ] Deliverables are complete
+- [ ] Guardrail checklist is evaluated
+- [ ] Required changes are explicit
+
+## Output format (structured)
+
+- Decision (Pass / Needs changes)
+- Findings
+- Required changes
+- Evidence summary
+- Open Questions / Risks
+- Confidence (High/Medium/Low + reason)

package/assets/init/.qfai/assistant/instructions/agent-selection.md

@@ -12,6 +12,11 @@ Delegate work to specialized roles to reduce blind spots and improve quality.
 
 ## Default delegation map
 
+- **Researcher**: collect pre-knowledge (English sources), glossary, risks, and question angles
+- **OQ Harvester**: extract undefined/ambiguous decisions and draft question candidates
+- **OQ Reviewer**: review OQ candidates for completeness, neutrality, and safe deferral
+- **Option Explorer**: propose multiple solution options + trade-offs + recommendation for delta.md
+- **Option Reviewer**: review options for bias, missing alternatives, and unsafe deferrals
 - **Requirements Analyst**: clarify intent, scope, acceptance criteria, open questions
 - **Planner**: plan phases, risks, gating, rollback strategy
 - **Architect**: design, boundaries, compatibility considerations
@@ -19,6 +24,7 @@ Delegate work to specialized roles to reduce blind spots and improve quality.
 - **QA Engineer**: risk-based checks, regression scope, quality gate review
 - **Test Engineer**: scenario.feature and test scaffolding strategy
 - **Front-end / Back-end Engineer**: implementation within repo conventions
+- **UI/UX Reviewer**: layout sanity, interaction usability, and UI guardrail checks
 - **DevOps/CI Engineer**: verify-pack/CI impacts
 - **Code Reviewer**: style, maintainability, correctness
 

package/assets/init/.qfai/assistant/prompts/qfai-atdd.md

@@ -40,6 +40,15 @@ mode: execution-focused
 - You MUST stop and escalate if scenarios are left unimplemented without explicit exclusions.
 - Completion must be approved by a reviewer who did not implement the tests.
 
+## Completion Contract (Shared)
+
+Before declaring completion, you MUST:
+
+- OQ / undefined resolution: detect undefined or ambiguous items; resolve them or explicitly defer them with documented rationale and (when required by this prompt) user approval.
+- Deliverable completeness: verify every expected artifact listed in this prompt (and required README templates) exists and is fully populated; no missing required sections.
+- OQ / placeholder scan: scan all generated artifacts (including evidence) for placeholders such as "TBD", "TODO", "TBA", "TBC", "XXX", "???", "OQ", "OPEN QUESTION", "UNDEFINED", "PLACEHOLDER", and localized equivalents in the user's language. Resolve or explicitly defer; do not leave silent placeholders.
+- Smoke check (if applicable): when the prompt produces runnable code/tests/configs, execute the smallest command that proves basic run/start/operate and record evidence. If not applicable, state "not applicable" with a short rationale.
+
 ## Goal
 
 Turn `.qfai/specs/spec-XXXX/scenario.feature` into runnable acceptance tests (E2E/API/Integration) in this repository (terminal + CI).

package/assets/init/.qfai/assistant/prompts/qfai-configure.md

@@ -39,6 +39,15 @@ mode: evidence-focused
 - You MUST stop and escalate if tooling choices or runnable path remain ambiguous.
 - Completion must be approved by a reviewer who did not modify the config.
 
+## Completion Contract (Shared)
+
+Before declaring completion, you MUST:
+
+- OQ / undefined resolution: detect undefined or ambiguous items; resolve them or explicitly defer them with documented rationale and (when required by this prompt) user approval.
+- Deliverable completeness: verify every expected artifact listed in this prompt (and required README templates) exists and is fully populated; no missing required sections.
+- OQ / placeholder scan: scan all generated artifacts (including evidence) for placeholders such as "TBD", "TODO", "TBA", "TBC", "XXX", "???", "OQ", "OPEN QUESTION", "UNDEFINED", "PLACEHOLDER", and localized equivalents in the user's language. Resolve or explicitly defer; do not leave silent placeholders.
+- Smoke check (if applicable): when the prompt produces runnable code/tests/configs, execute the smallest command that proves basic run/start/operate and record evidence. If not applicable, state "not applicable" with a short rationale.
+
 ## Goal
 
 Analyze the repository and update `qfai.config.yaml` so traceability checks are actionable, with a documented minimum runnable path.

package/assets/init/.qfai/assistant/prompts/qfai-discuss.md

@@ -11,7 +11,7 @@ title: QFAI Discuss (Idea → Clear Requirements)
 description: "Socratic discussion to turn a vague idea into a clear, testable set of requirements inputs."
 argument-hint: "<idea-or-problem> [--auto]"
 allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
-roles: [Facilitator, Interviewer, RequirementsAnalyst, QAEngineer, Planner]
+roles: [Researcher, Facilitator, Interviewer, RequirementsAnalyst, QAEngineer, Planner]
 mode: interactive-by-default
 
 ---
@@ -36,10 +36,23 @@ mode: interactive-by-default
 - You MUST produce the required evidence file: `.qfai/evidence/discuss-<discuss-id>.md`.
   - `.qfai/evidence/` is intentionally NOT tracked by Git (it ships with a local `.gitignore`).
   - Do NOT commit evidence files; summarize key outcomes in the PR description instead.
+- You MUST complete pre-knowledge research before drafting questions (delegate to Researcher when supported; Codex performs this inline).
+- You MUST draft the full question set and share the goal/approach before asking any question.
+- You MUST ask one question at a time with `Question X/Y` and a 3-options + "recommend for me" format.
+- You MUST re-optimize the remaining questions after each answer and update the total count.
 - You MUST run the mandatory checks listed below and record outcomes.
 - You MUST stop and escalate if scope remains ambiguous or required inputs are missing.
 - Completion must be approved by a reviewer who did not lead the discussion.
 
+## Completion Contract (Shared)
+
+Before declaring completion, you MUST:
+
+- OQ / undefined resolution: detect undefined or ambiguous items; resolve them or explicitly defer them with documented rationale and (when required by this prompt) user approval.
+- Deliverable completeness: verify every expected artifact listed in this prompt (and required README templates) exists and is fully populated; no missing required sections.
+- OQ / placeholder scan: scan all generated artifacts (including evidence) for placeholders such as "TBD", "TODO", "TBA", "TBC", "XXX", "???", "OQ", "OPEN QUESTION", "UNDEFINED", "PLACEHOLDER", and localized equivalents in the user's language. Resolve or explicitly defer; do not leave silent placeholders.
+- Smoke check (if applicable): when the prompt produces runnable code/tests/configs, execute the smallest command that proves basic run/start/operate and record evidence. If not applicable, state "not applicable" with a short rationale.
+
 ## Goal
 
 Turn a vague idea into explicit, testable requirements and decisions that downstream prompts can implement without guesswork.
@@ -58,6 +71,7 @@ Turn a vague idea into explicit, testable requirements and decisions that downst
 - Open risks are not assumed away.
 - Required coverage topics are complete.
 - Discuss record is saved with decision table and handoff.
+- Pre-knowledge research notes and question design rationale are recorded in evidence.
 
 ## Not-done criteria
 
@@ -88,7 +102,7 @@ The discussion MUST cover the following topics before completion:
 6. **Constraints** — Compatibility, rollout strategy, timeline, platform limits
 7. **Scope boundary** — Explicitly state what is OUT of scope for this iteration.
 
-If the user has not decided on any of the above, **propose at least 3 options** and ask the user to choose.
+If the user has not decided on any of the above, **propose at least 3 options plus a "recommend for me" option** and ask the user to choose.
 
 ## Non‑Negotiable Principles (QFAI Articles)
 
@@ -134,15 +148,23 @@ Do not edit any `.qfai/**/README.md` file; raise an Open Question instead.
 
 This workflow assumes the environment _may_ support subagents (e.g., Claude Code “Task” tool) or may not.
 
+Pre-knowledge research is mandatory and must be conducted in English sources before drafting questions. If subagents are supported, delegate this to **Researcher** using a structured brief (Codex is the exception: do it inline without subagents).
+
 ### If subagents are supported
 
 Delegate to multiple roles and then merge the results. Use a “real‑world workflow” order:
 
-- Facilitator → Interviewer → Requirements Analyst → Planner → Architect → (Contract Designer) → Test Engineer → QA Engineer → Code Reviewer → DevOps/CI Engineer
+- Researcher → Facilitator → Interviewer → Requirements Analyst → Planner → Architect → (Contract Designer) → Test Engineer → QA Engineer → Code Reviewer → DevOps/CI Engineer
 
 **Pseudo‑invocation pattern** (adjust to your tool):
 
 ```text
+Task(
+  subagent_type="researcher",
+  description="Collect pre-knowledge (English sources) and question angles",
+  prompt="Context: ...\nKnown facts: ...\nUnknowns: ...\nAngles to research: domain terms, risks, constraints, benchmarks\nReturn: summary + glossary + question cues + open risks"
+)
+
 Task(
   subagent_type="planner",
   description="Create an execution plan and DoD",
@@ -154,6 +176,7 @@ Task(
 
 Simulate roles by running the same sequence yourself:
 
+- Start with a short Researcher section (English pre-knowledge + question cues), then proceed role by role.
 - Write a short “role output” section per role, then consolidate into the final deliverable(s).
 
 ## Completion Separation (mandatory)
@@ -190,6 +213,24 @@ Every 5 major actions, pause and restate:
    - package manager (pnpm/npm/yarn), test runner, lint/typecheck scripts, CI definitions
    - existing test patterns (unit/integration/e2e)
 
+## Step 0.5 — Pre-knowledge research (Researcher)
+
+Before drafting questions, collect background knowledge using **English sources** (or explicitly state if external research is not possible) and summarize findings in the user's language. Focus on:
+
+- domain terminology and glossary
+- typical constraints, benchmarks, and risks
+- regulatory/compliance considerations (if relevant)
+- common failure modes and user expectations
+
+Deliver:
+
+- concise research memo
+- glossary of key terms
+- list of unknowns and assumptions
+- candidate question angles mapped to Required Coverage topics
+
+Record the research memo and question design rationale in the evidence file.
+
 ## Step 1 — Frame the discussion (Facilitator)
 
 Produce a short framing first (no more than ~10 lines):
@@ -200,19 +241,38 @@ Produce a short framing first (no more than ~10 lines):
 - Scope boundary (in / out)
 - Constraints (time, platform, compatibility posture)
 
-## Step 2 — Ask only high‑value questions (Interviewer)
+Also share the discussion approach:
+
+- confirm pre-knowledge research is complete
+- state that a full question draft will be shown before Q&A
+- state that questions will be asked one at a time with counts (Question X/Y)
 
-Generate questions in **priority order**:
+## Step 2 — Build the full question draft (Interviewer)
+
+Draft the **entire question set** before asking anything. Questions must be in **priority order**:
 
 - **Blockers**: must be answered to write requirements
 - **Clarifiers**: improve precision but can be assumed temporarily
 
+For each question, include:
+
+- purpose and the decision it unlocks
+- default assumption if unanswered
+- answer format: **3 options + "recommend for me"**
+
+Share the full draft list (numbered, with total count) before Q&A begins.
+
+## Step 3 — Ask one question at a time (Interviewer)
+
 Use a _Socratic style_:
 
 - Ask one question at a time in interactive mode.
+- Prefix with `Question X/Y` and show the total count.
+- Present 3 options plus a "recommend for me" option.
+- After each answer, re-optimize the remaining list; if the list changes, state the new total and what changed.
 - If `--auto` is provided, make explicit assumptions and mark them.
 
-## Step 3 — Draft the Requirements Seed (Requirements Analyst)
+## Step 4 — Draft the Requirements Seed (Requirements Analyst)
 
 Write a draft in this format:
 
@@ -231,7 +291,7 @@ Write a draft in this format:
 - **Open Questions (blockers)**:
 - **Open Questions (non‑blockers)**:
 
-## Step 3.5 — Decision Table (mandatory)
+## Step 4.5 — Decision Table (mandatory)
 
 Record ALL options that were considered during the discussion, including rejected and deferred ones.
 
@@ -250,7 +310,7 @@ Rules:
 - Rejected options MUST include "why rejected" in Rationale.
 - Deferred options MUST include "conditions to reconsider" in Rationale.
 
-## Step 4 — QA sanity check (QA Engineer)
+## Step 5 — QA sanity check (QA Engineer)
 
 Validate:
 
@@ -258,7 +318,7 @@ Validate:
 - Failure modes are considered.
 - Observability is defined (logs/messages/output).
 
-## Step 5 — Produce handoff to /qfai-require (Planner)
+## Step 6 — Produce handoff to /qfai-require (Planner)
 
 Generate the minimal input payload for /qfai-require:
 
@@ -267,7 +327,7 @@ Generate the minimal input payload for /qfai-require:
 - Remaining questions (if any)
 - Proposed requirement ID namespace (optional)
 
-## Step 6 — Save discuss record (mandatory)
+## Step 7 — Save discuss record (mandatory)
 
 Save the complete discussion output to `.qfai/discussions/discuss-XXXX.md`.
 
@@ -281,8 +341,8 @@ Save the complete discussion output to `.qfai/discussions/discuss-XXXX.md`.
 The saved file MUST include:
 
 1. **Header** with timestamp, topic, and participants (if known)
-2. **Requirements Seed** (full content from Step 3)
-3. **Decision Table** (full content from Step 3.5)
+2. **Requirements Seed** (full content from Step 4)
+3. **Decision Table** (full content from Step 4.5)
 4. **Handoff summary** for /qfai-require
 
 ### Example header
@@ -301,6 +361,8 @@ Create and update: `.qfai/evidence/discuss-<discuss-id>.md`
 
 Evidence must include:
 
+- pre-knowledge research memo (English sources or stated limits)
+- question draft and rationale (including changes after answers)
 - decision table (options, pros/cons, recommendation)
 - unresolved questions (even if "none")
 
@@ -308,6 +370,8 @@ Evidence must include:
 
 - Objective
 - Inputs reviewed (files/paths)
+- Pre-knowledge research summary
+- Question design rationale
 - Decisions made (with rationale)
 - Work performed (what changed, where)
 - Commands executed + key outputs
@@ -323,6 +387,10 @@ Evidence must include:
 
 ## Inputs reviewed (files/paths)
 
+## Pre-knowledge research summary
+
+## Question design rationale
+
 ## Decisions made (with rationale)
 
 ## Work performed (what changed, where)

package/assets/init/.qfai/assistant/prompts/qfai-prototyping.md

@@ -11,7 +11,7 @@ title: QFAI Prototyping (Implement a runnable contract skeleton)
 description: "Implement a minimal end-to-end runnable skeleton (UI + API + DB) based on contracts, before ATDD/TDD automation."
 argument-hint: "<spec-id> [--auto]"
 allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
-roles: [FullStackEngineer, BackendEngineer, FrontendEngineer, DBEngineer, DevOpsCIEngineer, QAEngineer, CodeReviewer]
+roles: [FullStackEngineer, BackendEngineer, FrontendEngineer, DBEngineer, DevOpsCIEngineer, QAEngineer, RuntimeGatekeeper, UIUXReviewer, CodeReviewer]
 mode: execution-focused
 
 ---
@@ -44,10 +44,21 @@ Build a **minimum runnable vertical slice** from `.qfai/contracts/**` so that:
   - `.qfai/evidence/` is intentionally NOT tracked by Git (it ships with a local `.gitignore`).
   - Do NOT commit evidence files; summarize key outcomes in the PR description instead.
 - You MUST run the dev server and perform manual verification.
+- You MUST pass the Runtime Interaction Gate (boot + access + interaction) before completion.
+- You MUST check UI layout sanity (no oversized primary buttons, no broken header/search rows).
 - You MUST stop and escalate if runtime evidence or contract alignment is missing.
 - Implementation must align with existing project conventions; do NOT introduce new frameworks.
 - Completion must be approved by a reviewer who did not implement the code.
 
+## Completion Contract (Shared)
+
+Before declaring completion, you MUST:
+
+- OQ / undefined resolution: detect undefined or ambiguous items; resolve them or explicitly defer them with documented rationale and (when required by this prompt) user approval.
+- Deliverable completeness: verify every expected artifact listed in this prompt (and required README templates) exists and is fully populated; no missing required sections.
+- OQ / placeholder scan: scan all generated artifacts (including evidence) for placeholders such as "TBD", "TODO", "TBA", "TBC", "XXX", "???", "OQ", "OPEN QUESTION", "UNDEFINED", "PLACEHOLDER", and localized equivalents in the user's language. Resolve or explicitly defer; do not leave silent placeholders.
+- Smoke check (if applicable): when the prompt produces runnable code/tests/configs, execute the smallest command that proves basic run/start/operate and record evidence. If not applicable, state "not applicable" with a short rationale.
+
 ## Inputs (read first)
 
 - `.qfai/contracts/ui/*.yaml` (routes/screens/elements/actions)
@@ -76,6 +87,14 @@ Implement the following **contract-satisfying skeleton**, aiming for the smalles
   - include placeholder components for declared elements (table/input/button),
   - implement declared navigation actions (links/buttons).
 
+#### UI layout guardrails (mandatory)
+
+- Do NOT make primary buttons full-width by default; use a separate block variant when needed.
+- Header rows: title and primary action stay on one line (no overflow or wrap).
+- Search rows: input uses flex-grow; buttons are fixed width (shrink-0) so inputs do not collapse.
+- If using Tailwind/@apply: define component classes in `@layer components` and avoid width in base button classes (separate `btn` vs `btn-block`).
+- Empty/error states must be readable and not visually broken.
+
 ### 2) API skeleton
 
 - For every endpoint in `contracts/api/*.yaml` used by the spec pack:
@@ -112,17 +131,38 @@ Implement the following **contract-satisfying skeleton**, aiming for the smalles
 5. Implement DB skeleton and connect (or provide clear temporary store).
 6. Run the dev server and perform a manual “happy path” click-through.
 
+## Sub-agent assignments (recommended)
+
+- UI Skeleton Builder: FrontendEngineer (apply UI layout guardrails).
+- API/DB Skeleton Builder: BackendEngineer + DBEngineer.
+- Runtime Smoke Checker: RuntimeGatekeeper (boot/access/interaction evidence).
+- UI/UX Reviewer: UIUXReviewer (layout sanity check).
+
+## Runtime Interaction Gate (mandatory)
+
+You may declare completion only after capturing evidence for:
+
+- Boot: `pnpm dev` (or equivalent) starts without errors.
+- Access: main URL(s) render without runtime errors.
+- Interaction: at least one user interaction succeeds (click/input/submit/navigation).
+- Optional (recommended): Playwright smoke (`@smoke`) if available.
+
+Record commands, logs, and interaction steps in evidence.
+
 ## Completion criteria (hard gate)
 
 You may declare completion ONLY if:
 
 - [ ] Dev server starts locally without errors (`pnpm dev` or project equivalent).
+- [ ] Runtime Interaction Gate evidence is captured (boot/access/interaction).
 - [ ] All UI routes declared in UI contracts are reachable (no 404).
+- [ ] UI layout guardrails are satisfied (no oversized buttons; header/search rows intact).
 - [ ] At least one end-to-end happy path works in the UI:
   - list screen loads data (stub OK),
   - create/edit screen submits and updates list (stub OK),
   - navigation works.
 - [ ] All implemented API endpoints respond with status codes consistent with the contract.
+- [ ] If Playwright smoke exists, `@smoke` passes (or document why it cannot run).
 - [ ] Evidence file exists: `.qfai/evidence/prototyping-<spec-id>.md`
   - includes executed commands,
   - includes “Format Self-Check”,
@@ -133,6 +173,8 @@ You may declare completion ONLY if:
 - No test automation was added here.
 - Implementation aligns with project conventions (no new framework added).
 - UI/API/DB skeleton matches contract definitions.
+- Runtime Interaction Gate evidence is present and reproducible.
+- UI layout guardrails were checked (UI/UX reviewer sign-off).
 - Completion criteria are objectively satisfied.
 
 ## Evidence (MANDATORY)
@@ -142,8 +184,10 @@ You may declare completion ONLY if:
   1. **Contract Inventory**: list of UI routes, API endpoints, DB tables from contracts.
   2. **Implementation Summary**: what was implemented for each contract item.
   3. **Dev Server Startup**: commands executed and result.
-  4. **Manual Verification Log**: step-by-step click-through with observations.
-  5. **Format Self-Check**: list each artifact and confirm "matches README template".
+  4. **Runtime Interaction Gate**: access + interaction steps with results.
+  5. **UI Layout Sanity Check**: guardrails checked + screenshots/notes if available.
+  6. **Manual Verification Log**: step-by-step click-through with observations.
+  7. **Format Self-Check**: list each artifact and confirm "matches README template".
 
 ## FINAL CHECKLIST (Check Last)