qfai 1.2.6 → 1.2.12

package/README.md

@@ -58,10 +58,11 @@ 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.
+- **qfai-prototyping**: Implement a minimal runnable skeleton (UI + API + DB) from contracts before test automation. Run after `/qfai-spec` to ensure the app is runnable with `pnpm dev` (or equivalent) before writing tests.
 - **qfai-atdd**: Implement acceptance tests (E2E/API/Integration) and drive Scenario Coverage to 100% using a Coverage Ledger.
 - **qfai-tdd-red**: Implement fast tests first (unit/component) and drive Unit/Component Scenario Coverage to 100% using a Coverage Ledger.
 - **qfai-tdd-green**: Implement production code to make the tests pass.
@@ -104,6 +105,11 @@ AG->>Q: Read .qfai/assistant/prompts/qfai-spec.md
 AG->>R: Create specs + contracts + scenario.feature
 AG-->>U: SDD artifacts ready
 
+U->>AG: Run /qfai-prototyping
+AG->>Q: Read .qfai/assistant/prompts/qfai-prototyping.md
+AG->>R: Implement minimal runnable skeleton (UI + API + DB)
+AG-->>U: Runnable prototype ready (dev server starts)
+
 U->>AG: Run /qfai-atdd
 AG->>Q: Read .qfai/assistant/prompts/qfai-atdd.md
 AG->>R: Implement acceptance tests
@@ -136,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/README.md

@@ -1,60 +1,100 @@
-# .qfai
+# .qfai (QFAI Workspace)
 
 ## Purpose
 
-`.qfai` is the workspace where QFAI artifacts live so requirements, contracts, specs, and reports stay aligned.
+`.qfai/` is the **single workspace** for QFAI artifacts so that requirements, contracts, spec packs, and automation stay aligned and traceable.
 
-## What belongs here
+This folder is generated by `qfai init`. It is designed to be:
 
-- Assistant assets (prompts, instructions, steering, roles)
-- Requirements (single requirements document)
-- Contracts (api/db/ui)
-- Spec packs (spec.md, delta.md, scenario.feature)
-- Evidence files (prompt completion records)
-- Generated reports (validate/report/doctor outputs)
+- **predictable** (stable file layout),
+- **reviewable** (human-readable Markdown/YAML/SQL),
+- **machine-checkable** (validators enforce minimal structural rules).
 
-## What does not belong here
+## Recommended QFAI sequence (project)
 
-- Application source code
-- Generated tests or build artifacts
-- Ad-hoc notes outside the defined structure
+```mermaid
+flowchart TD
+  A[/qfai-discuss/] --> B[/qfai-require/]
+  B --> C[/qfai-spec/]
+  C --> D[/qfai-prototyping/]
+  D --> E[/qfai-atdd/]
+  E --> F[/qfai-tdd-red/]
+  F --> G[/qfai-tdd-green/]
+  G --> H[/qfai-tdd-refactor/]
+```
+
+> Formatting MUST follow the templates in each directory README.
+> Do not invent per-file formats.
 
-## Structure (overview)
+## Directory map
 
 ```text
 .qfai/
-  README.md
-  assistant/
-    agents/
-    instructions/
-    prompts/
-    prompts.local/
-    steering/
-  contracts/
-    README.md
-    api/
-    db/
-    ui/
-  require/
-    README.md
-    <requirements document created by /qfai-require>
-  evidence/
-    <prompt evidence files>
-  specs/
-    README.md
-    <spec packs>
-  report/
-    <generated by qfai validate/report/doctor>
+├── README.md
+├── assistant/
+│   ├── prompts/            # canonical prompts (SSOT)
+│   ├── prompts.local/      # minimal overrides (project-specific)
+│   ├── agents/             # sub-agent missions / guardrails
+│   ├── steering/           # project steering (inputs for prompts)
+│   └── instructions/       # tool/integration instructions
+├── require/
+│   ├── README.md
+│   └── require.md          # single requirements document
+├── contracts/
+│   ├── README.md
+│   ├── api/README.md       # OpenAPI YAML style guide
+│   ├── db/README.md        # SQL contracts style guide
+│   └── ui/README.md        # UI contract YAML style guide
+├── specs/
+│   ├── README.md
+│   └── spec-0001/
+│       ├── spec.md
+│       ├── delta.md
+│       ├── scenario.feature
+│       ├── case-catalogue.md
+│       └── traceability-matrix.md
+└── evidence/
+    ├── README.md
+    └── <prompt>-<run>.md   # completion evidence (gitignored by default)
 ```
 
-## Operating rules
+## Rules (global)
+
+### R1. README-as-SSOT for formatting
+
+Each directory `README.md` defines:
+
+- required files,
+- canonical **template**,
+- realistic **sample**,
+- quality checklist,
+- anti-patterns.
+
+All custom prompts must:
+
+1. read the relevant directory README(s),
+2. generate artifacts matching their templates,
+3. run a self-check before declaring completion.
+
+### R2. Evidence is not versioned by default
+
+Evidence under `.qfai/evidence/` is **gitignored by default** (see repository `.gitignore` and/or project `.git/info/exclude`).
+
+- Evidence is still useful locally and in PR review (attach or paste snippets), but it should not pollute version control.
+
+### R3. Keep artifacts atomic
+
+- Prefer many small, stable identifiers (REQ/BR/AC/CASE/SC) over long paragraphs that hide multiple rules.
+- If a statement contains multiple independent “must” clauses, split it.
+
+### R4. Do not put templates in prompts
 
-- READMEs are reference guides; do not edit them during execution. Raise Open Questions instead.
-- Create new artifacts only in the intended directories.
-- Always run the repo's gates before declaring completion.
+Templates/samples MUST live only in `.qfai/**/README.md`.
+Prompts only **reference** them to avoid double maintenance.
 
-## Checklist
+## Where to look next
 
-- [ ] I used the correct directory for each artifact
-- [ ] I did not edit README files
-- [ ] I ran the repository gate commands and recorded results
+- Requirements format: `require/README.md`
+- Contracts format: `contracts/README.md` and sub-READMEs
+- Spec pack format: `specs/README.md`
+- Evidence rules: `evidence/README.md`

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

@@ -18,6 +18,17 @@ mode: execution-focused
 
 # /qfai-atdd — Implement Automated Acceptance Tests (ATDD)
 
+## 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.
+- The generated artifacts must match the README-defined structure (headings, ordering, table columns).
+- Completion requires a **Format Self-Check** in the evidence: list each artifact and confirm “matches README template”.
+
 ## CRITICAL CONSTRAINTS (Read First)
 
 - Do NOT declare completion based on unit/component tests.
@@ -29,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

@@ -18,6 +18,17 @@ mode: evidence-focused
 
 # /qfai-configure - Configure QFAI for this repository
 
+## 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.
+- The generated artifacts must match the README-defined structure (headings, ordering, table columns).
+- Completion requires a **Format Self-Check** in the evidence: list each artifact and confirm “matches README template”.
+
 ## CRITICAL CONSTRAINTS (Read First)
 
 - Only update `qfai.config.yaml`, `.qfai/assistant/steering/*`, and `.qfai/evidence/configure-<run-id>.md` unless explicitly asked.
@@ -28,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.