qfai 1.2.0 → 1.2.2

package/README.md

@@ -62,9 +62,10 @@ QFAI includes a small set of custom prompts (stored under `.qfai/assistant/promp
 - **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-scenario-test**: Implement acceptance tests (ATDD) driven by specs/scenarios.
-- **qfai-unit-test**: Implement unit tests (TDD) driven by specs/scenarios.
-- **qfai-implement**: Implement the feature; iterate test→fix until all quality gates are green.
+- **qfai-atdd**: Implement acceptance tests (ATDD) driven by specs/scenarios.
+- **qfai-tdd-red**: Implement fast tests first (unit/component/integration).
+- **qfai-tdd-green**: Implement production code to make the tests pass.
+- **qfai-tdd-refactor**: Refactor safely after tests are green.
 - **qfai-verify**: Run/interpret the local quality gates and produce a PR-ready summary.
 
 ### Workflow sequence (example)
@@ -103,23 +104,28 @@ 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-scenario-test
-AG->>Q: Read .qfai/assistant/prompts/qfai-scenario-test.md
+U->>AG: Run /qfai-atdd
+AG->>Q: Read .qfai/assistant/prompts/qfai-atdd.md
 AG->>R: Implement acceptance tests
-AG-->>U: Scenario tests ready
+AG-->>U: Acceptance tests ready
 
-U->>AG: Run /qfai-unit-test
-AG->>Q: Read .qfai/assistant/prompts/qfai-unit-test.md
-AG->>R: Implement unit tests
-AG-->>U: Unit tests ready
+U->>AG: Run /qfai-tdd-red
+AG->>Q: Read .qfai/assistant/prompts/qfai-tdd-red.md
+AG->>R: Implement fast tests (RED)
+AG-->>U: RED tests ready
 
-U->>AG: Run /qfai-implement
-AG->>Q: Read .qfai/assistant/prompts/qfai-implement.md
+U->>AG: Run /qfai-tdd-green
+AG->>Q: Read .qfai/assistant/prompts/qfai-tdd-green.md
 loop Implement and fix until green
 AG->>R: Implement code changes
 AG->>R: Run project tests locally
 end
-AG-->>U: Working implementation (quality gates passing)
+AG-->>U: Working implementation (tests green)
+
+U->>AG: Run /qfai-tdd-refactor
+AG->>Q: Read .qfai/assistant/prompts/qfai-tdd-refactor.md
+AG->>R: Refactor safely
+AG-->>U: Refactor complete
 
 U->>R: Run npx qfai validate
 U->>R: Run npx qfai report
@@ -221,6 +227,14 @@ QFAI uses a small, opinionated set of artifacts to reduce ambiguity and prevent
 
 Traceability is validated across these artifacts, so code changes remain grounded in the specs and the tests prove compliance.
 
+### Test strategy tags (optional)
+
+You can annotate scenarios with lightweight test strategy metadata to keep the test pyramid/trophy healthy.
+These tags are opt-in and only produce warnings, so you can roll them out gradually without breaking existing specs.
+
+- Layer tags: `@layer-unit`, `@layer-component`, `@layer-integration`, `@layer-api`, `@layer-e2e`
+- Size tags: `@size-s`, `@size-m`, `@size-l`
+
 ## Continuous integration (GitHub Actions)
 
 (GitHub Actions)
@@ -260,11 +274,12 @@ Typical customizations.
 │   └── commands
 │       ├── qfai-configure.md
 │       ├── qfai-discuss.md
-│       ├── qfai-implement.md
+│       ├── qfai-atdd.md
 │       ├── qfai-require.md
-│       ├── qfai-scenario-test.md
 │       ├── qfai-spec.md
-│       ├── qfai-unit-test.md
+│       ├── qfai-tdd-green.md
+│       ├── qfai-tdd-red.md
+│       ├── qfai-tdd-refactor.md
 │       └── qfai-verify.md
 ├── .codex
 │   └── skills
@@ -272,15 +287,17 @@ Typical customizations.
 │       │   └── SKILL.md
 │       ├── qfai-discuss
 │       │   └── SKILL.md
-│       ├── qfai-implement
+│       ├── qfai-atdd
 │       │   └── SKILL.md
 │       ├── qfai-require
 │       │   └── SKILL.md
-│       ├── qfai-scenario-test
-│       │   └── SKILL.md
 │       ├── qfai-spec
 │       │   └── SKILL.md
-│       ├── qfai-unit-test
+│       ├── qfai-tdd-green
+│       │   └── SKILL.md
+│       ├── qfai-tdd-red
+│       │   └── SKILL.md
+│       ├── qfai-tdd-refactor
 │       │   └── SKILL.md
 │       └── qfai-verify
 │           └── SKILL.md
@@ -288,11 +305,12 @@ Typical customizations.
 │   ├── prompts
 │   │   ├── qfai-configure.prompt.md
 │   │   ├── qfai-discuss.prompt.md
-│   │   ├── qfai-implement.prompt.md
+│   │   ├── qfai-atdd.prompt.md
 │   │   ├── qfai-require.prompt.md
-│   │   ├── qfai-scenario-test.prompt.md
 │   │   ├── qfai-spec.prompt.md
-│   │   ├── qfai-unit-test.prompt.md
+│   │   ├── qfai-tdd-green.prompt.md
+│   │   ├── qfai-tdd-red.prompt.md
+│   │   ├── qfai-tdd-refactor.prompt.md
 │   │   └── qfai-verify.prompt.md
 │   ├── workflows
 │   │   └── qfai.yml
@@ -325,11 +343,12 @@ Typical customizations.
 │   │   │   ├── README.md
 │   │   │   ├── qfai-configure.md
 │   │   │   ├── qfai-discuss.md
-│   │   │   ├── qfai-implement.md
+│   │   │   ├── qfai-atdd.md
 │   │   │   ├── qfai-require.md
-│   │   │   ├── qfai-scenario-test.md
 │   │   │   ├── qfai-spec.md
-│   │   │   ├── qfai-unit-test.md
+│   │   │   ├── qfai-tdd-green.md
+│   │   │   ├── qfai-tdd-red.md
+│   │   │   ├── qfai-tdd-refactor.md
 │   │   │   └── qfai-verify.md
 │   │   ├── prompts.local
 │   │   │   └── README.md

package/assets/init/.qfai/assistant/prompts/{qfai-scenario-test.md → qfai-atdd.md}

@@ -6,25 +6,25 @@ QFAI Prompt Body (SSOT)
 
 ---
 
-id: qfai-scenario-test
-title: QFAI Scenario Test (ATDD executable)
-description: "Implement executable scenario tests from spec pack and scenario.feature; includes review and quality checks."
+id: qfai-atdd
+title: QFAI ATDD (Executable acceptance tests)
+description: "Implement automated acceptance tests (E2E/API/Integration) aligned with scenario.feature and specs."
 argument-hint: "<spec-id> [--auto]"
 allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
-roles: [TestEngineer, DevOpsCIEngineer, QAEngineer, CodeReviewer, Planner]
+roles: [TestEngineer, QAEngineer, BackendEngineer, FrontendEngineer, CodeReviewer, DevOpsCIEngineer]
 mode: execution-focused
 
 ---
 
-# /qfai-scenario-test — Implement Executable Scenario Tests (ATDD)
+# /qfai-atdd — Implement Automated Acceptance Tests (ATDD)
 
 ## Purpose
 
-Turn `.qfai/specs/spec-XXXX/scenario.feature` into **runnable scenario tests** in this repository (terminal + CI).
+Turn `.qfai/specs/spec-XXXX/scenario.feature` into **runnable acceptance tests** (E2E/API/Integration) in this repository (terminal + CI).
 
 ## Success Criteria (Definition of Done)
 
-- Scenario tests exist and are runnable via documented commands.
+- Acceptance tests exist and are runnable via documented commands.
 - Tests are stable (no flakiness) and diagnostic (failures explain why).
 - Existing acceptance automation (if any) is reused; no new framework is added without approval.
 - Quality checks (lint/typecheck/tests) pass in the repo’s standard way.
@@ -193,7 +193,7 @@ Read:
 
 **Rationale:** QFAI validate rules require unique SC tags per file, and large scenario counts should be split to keep traceability clear.
 
-## Step 2 — Choose (or detect) scenario test harness
+## Step 2 — Choose (or detect) acceptance test harness
 
 Prefer existing project tooling. Determine:
 
@@ -218,13 +218,14 @@ When approval is granted:
 
 - Add minimal dependencies and configuration.
 - Implement steps mapped to `scenario.feature`.
-- Integrate a single command to run scenario tests.
+- Integrate a single command to run acceptance tests.
 
-## Step 3 — Implement scenario tests (Test Engineer)
+## Step 3 — Implement acceptance tests (Test Engineer)
 
 Rules:
 
 - Scenarios must map to executable steps.
+- Prioritize Scenario tags that carry @layer-api / @layer-e2e / @layer-integration.
 - Keep step definitions reusable but not overly generic.
 - Ensure each scenario asserts observable behavior.
 
@@ -316,7 +317,7 @@ If you cannot run these commands (environment limitation):
 
 ## Output
 
-- Scenario test implementation files (with SC annotations)
+- Acceptance test implementation files (with SC annotations)
 - "Runbook" snippet (copy‑paste command)
 - Short verification evidence summary
 - Gate results: all PASS

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

@@ -730,4 +730,4 @@ If you cannot run these commands (environment limitation):
 - `.qfai/specs/spec-*/traceability-matrix.md`
 - (If needed) updated `.qfai/contracts/**`
 - Validation evidence: command outputs showing PASS
-- Next recommended command: /qfai-scenario-test and/or /qfai-unit-test
+- Next recommended command: /qfai-atdd and/or /qfai-tdd-red

package/assets/init/.qfai/assistant/prompts/{qfai-implement.md → qfai-tdd-green.md}

@@ -6,33 +6,33 @@ QFAI Prompt Body (SSOT)
 
 ---
 
-id: qfai-implement
-title: QFAI Implement (Spec-driven implementation)
-description: "Implement the program feature according to specs/contracts/scenario; includes review and full quality gate."
+id: qfai-tdd-green
+title: QFAI TDD Green (Implement to pass tests)
+description: "Implement production code to make TDD RED tests pass, then keep gates green."
 argument-hint: "<spec-id> [--auto]"
 allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
-roles: [Planner, Architect, BackendEngineer, FrontendEngineer, TestEngineer, QAEngineer, RuntimeGatekeeper, CodeReviewer, DevOpsCIEngineer]
+roles: [BackendEngineer, FrontendEngineer, QAEngineer, CodeReviewer, DevOpsCIEngineer]
 mode: iterative
 
 ---
 
-# /qfai-implement — Implement Feature (Spec‑Driven)
+# /qfai-tdd-green — Implement to Green (TDD)
 
 ## Purpose
 
-Implement the required feature/changes according to **spec + contracts + scenario**, then reach a **green quality gate**.
+Implement production code according to **spec + contracts + scenario** so the RED tests pass and the **green quality gate** is reached.
 
 ## Guardrails
 
 - Do not invent DB/API/infra. If missing, return to Contracts and fix them.
 - Do not mark "done" without runtime evidence.
-- Do NOT write unit tests here; delegate to `/qfai-unit-test` or `/qfai-scenario-test`.
+- Do NOT write new tests here; delegate to `/qfai-tdd-red` (fast tests) or `/qfai-atdd` (acceptance tests).
 - Stubs/mocks are allowed only for clearly defined external dependencies and must be documented as such.
 
 ## Success Criteria (Definition of Done)
 
 - Implementation matches the spec and contracts.
-- Scenario tests + unit tests pass.
+- TDD tests pass (and ATDD tests pass when applicable).
 - Repo quality gates pass (lint/type/build/pack as applicable).
 - Verification evidence is recorded (commands + results).
 - Program is runnable; runtime evidence is recorded and meets project-type expectations.
@@ -216,8 +216,8 @@ Rules:
 
 ## Step 4 — Keep tests aligned (Test Engineer)
 
-- Do NOT write unit tests here. If tests are missing or need coverage, run `/qfai-unit-test` first.
-- For acceptance tests, use `/qfai-scenario-test` instead of adding them here.
+- Do NOT write new tests here. If fast tests are missing or need coverage, run `/qfai-tdd-red` first.
+- For acceptance tests, use `/qfai-atdd` instead of adding them here.
 - Exception: if existing tests are broken and gates cannot pass, apply the minimal fix. Avoid creating new tests.
 
 ## Step 5 — Review & QA checks
@@ -342,4 +342,4 @@ All must pass; otherwise, report as not complete.
 - Runtime evidence summary (commands + outcomes)
 - DoD section (required)
 - Gate results: all PASS
-- Suggested next command: /qfai-verify (if not already done)
+- Suggested next command: /qfai-tdd-refactor (then /qfai-verify)

package/assets/init/.qfai/assistant/prompts/{qfai-unit-test.md → qfai-tdd-red.md}

@@ -6,21 +6,21 @@ QFAI Prompt Body (SSOT)
 
 ---
 
-id: qfai-unit-test
-title: QFAI Unit Test (TDD executable)
-description: "Implement CI-runnable unit tests derived from spec/scenario; includes review and quality checks."
+id: qfai-tdd-red
+title: QFAI TDD Red (Test-first)
+description: "Implement fast tests first (unit/component/integration) and stop at RED."
 argument-hint: "<spec-id> [--auto]"
 allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
-roles: [TestEngineer, BackendEngineer, FrontendEngineer, QAEngineer, UnitTestScopeEnforcer, CodeReviewer]
+roles: [UnitTestScopeEnforcer, TestEngineer, QAEngineer, CodeReviewer]
 mode: test-first
 
 ---
 
-# /qfai-unit-test — Implement Unit Tests (TDD)
+# /qfai-tdd-red — Implement Tests First (TDD Red)
 
 ## Purpose
 
-Implement **unit tests** that enforce the spec and provide fast feedback.
+Implement **fast tests** (unit/component/integration) that enforce the spec and provide fast feedback.
 
 ## Scope Guardrails (tests-only)
 
@@ -62,7 +62,7 @@ Without approval, do not proceed.
 If tests cannot proceed because implementation is missing:
 
 - Stop after writing failing tests (RED).
-- Instruct the user to run `/qfai-implement` next.
+- Instruct the user to run `/qfai-tdd-green` next.
 - Record blockers as Open Question / TODO.
 - Capture failing test evidence and do not run full repository gates.
 
@@ -231,7 +231,7 @@ QFAI expects `assistant/steering/` to contain **project‑specific facts** so al
 
 ## Blocked States (hard stop)
 
-- If the required test surface is missing and would require new production artifacts, stop and request `/qfai-implement`.
+- If the required test surface is missing and would require new production artifacts, stop and request `/qfai-tdd-green`.
 - If production code changes are required for testability without explicit approval, stop and request approval.
 
 ## Step 2 — Identify units and boundaries (Test Engineer + Architect mindset)

package/assets/init/.qfai/assistant/prompts/qfai-tdd-refactor.md

@@ -0,0 +1,344 @@
+<!--
+QFAI Prompt Body (SSOT)
+- This file is intended to be referenced by tool-specific custom prompt definitions (e.g., Copilot .prompt.md, Claude Code slash commands).
+- Keep tool-specific wrappers thin: "Read this file and follow it."
+-->
+
+---
+
+id: qfai-tdd-refactor
+title: QFAI TDD Refactor (Improve structure safely)
+description: "Refactor code without behavior change after tests are green."
+argument-hint: "<spec-id> [--auto]"
+allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
+roles: [ArchitectReviewer, BackendEngineer, FrontendEngineer, QAEngineer, CodeReviewer]
+mode: refactor
+
+---
+
+# /qfai-tdd-refactor — Refactor Safely (TDD Refactor)
+
+## Purpose
+
+Refactor the codebase **without behavior change** after tests are green, preserving spec and contract intent.
+
+## Guardrails
+
+- Do not invent DB/API/infra. If missing, stop and raise Open Questions.
+- Do NOT add new tests here; this step is refactor-only.
+- Do NOT change externally visible behavior or specs/contracts.
+- Keep refactors minimal and reversible; prefer small, reviewable changes.
+
+## Success Criteria (Definition of Done)
+
+- Behavior remains unchanged and matches the spec and contracts.
+- TDD/ATDD tests remain green after refactor.
+- Repo quality gates pass (lint/type/build/pack as applicable).
+- Verification evidence is recorded (commands + results).
+
+## Non‑Negotiable Principles (QFAI Articles)
+
+These principles are inspired by “constitution / articles” patterns used by other agent frameworks, but tailored to QFAI.
+
+1. **SDD First (Specification is the source of truth)**  
+   If there is a conflict between code and spec, treat the spec as authoritative and either (a) fix code or (b) raise an explicit Open Question to change the spec.
+
+2. **Traceability is mandatory**  
+   Every meaningful change must be traceable: **Require → Spec → Scenario → Tests → Code → Verification evidence**.
+
+3. **Evidence over confidence**  
+   Prefer observable proof (logs, commands, file diffs, test results). If you cannot verify, say so and record it.
+
+4. **Minimize scope, but never hide gaps**  
+   Keep changes minimal, but do not “paper over” missing decisions. If something blocks correctness, stop and ask.
+
+5. **Quality gates are the decision mechanism**  
+   Use tests/lint/typecheck/build/pack verification (whatever the repo defines) as the primary guardrail. Fix until PASS.
+
+6. **Make it runnable**  
+   Outputs must be executable in terminal/CI. Provide copy‑paste commands.
+
+7. **User time is expensive**  
+   Ask only the questions that are truly blocking. Everything else: make reasonable assumptions and label them clearly.
+
+## README Rule
+
+Do not edit any `.qfai/**/README.md` file; raise an Open Question instead.
+
+- READMEs are reference guides. Follow their structure, templates, and checklists.
+
+## Absolute Rule — Output Language
+
+**All outputs MUST be written in the user’s working language for this session.**
+
+- If the user writes in Japanese, output Japanese.
+- If the user writes in English, output English.
+- If the user mixes languages, prefer the dominant language unless explicitly instructed otherwise.  
+  This rule overrides all other stylistic preferences.
+
+## Multi‑Role Orchestration (Subagents)
+
+This workflow assumes the environment _may_ support subagents (e.g., Claude Code “Task” tool) or may not.
+
+### 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 → Runtime Gatekeeper → Code Reviewer → DevOps/CI Engineer
+
+**Pseudo‑invocation pattern** (adjust to your tool):
+
+```text
+Task(
+  subagent_type="planner",
+  description="Create an execution plan and DoD",
+  prompt="Context: ...\nGoal: ...\nConstraints: ...\nReturn: phases + risks + DoD"
+)
+```
+
+### If subagents are NOT supported
+
+Simulate roles by running the same sequence yourself:
+
+- Write a short “role output” section per role, then consolidate into the final deliverable(s).
+
+## Step 0 — Load Context (always)
+
+1. Read relevant **project steering** (if present):
+   - `.qfai/assistant/steering/structure.md`
+   - `.qfai/assistant/steering/tech.md`
+   - `.qfai/assistant/steering/product.md`
+   - any additional files under `.qfai/assistant/steering/`
+
+2. Read **project constitution / instructions** (if present):
+   - `.qfai/assistant/instructions/constitution.md`
+   - `.qfai/assistant/instructions/workflow.md` (or equivalent)
+
+3. Read existing artifacts for the current work item (if present):
+   - `.qfai/require/`
+   - `.qfai/specs/spec-*/`
+   - `.qfai/contracts/`
+
+4. Inspect repo conventions:
+   - package manager (pnpm/npm/yarn), test runner, lint/typecheck scripts, CI definitions
+   - existing test patterns (unit/integration/e2e)
+
+## Step 0 — Project Analysis (mandatory)
+
+Before producing any deliverable, **thoroughly analyze the current project** so your outputs fit the repo’s:
+
+- background and goals
+- directory structure and conventions
+- chosen technologies and versions (runtime, package manager, test runner)
+- architecture boundaries (packages, CLI, core modules)
+- existing patterns for tests, docs, and CI
+
+### Minimum analysis checklist
+
+- [ ] Read key repo docs: README / CHANGELOG / RELEASE (if present)
+- [ ] Inspect `.qfai/` layout and existing SDD/ATDD/TDD artifacts (if present)
+- [ ] Inspect `packages/qfai` structure (CLI entrypoints, core modules, validators, assets/init)
+- [ ] Identify standard gate commands (format/lint/type/test/verify-pack) and where they are defined
+- [ ] Search for existing examples/patterns of similar changes in tests (if available)
+- [ ] Note constraints: Node versions, CI matrix, packaging rules, verify-pack expectations
+
+If analysis cannot be performed (missing access), clearly state what could not be verified and proceed with minimal-risk assumptions.
+
+## Step 0.5 — Steering Bootstrap / Refresh (mandatory when incomplete)
+
+QFAI expects `assistant/steering/` to contain **project‑specific facts** so all subsequent design/test/implementation fits this repository.
+
+### What to do
+
+1. Open these files:
+
+- `.qfai/assistant/steering/product.md`
+- `.qfai/assistant/steering/tech.md`
+- `.qfai/assistant/steering/structure.md`
+
+2. If they are missing, mostly empty, or still have placeholders (e.g., `- ` only), **populate them by analyzing the current repository**:
+
+- derive “what/why/users/success/non-goals” from README/docs/issues (product.md)
+- derive runtime/tooling versions + constraints from package.json, CI config, lockfiles (tech.md)
+- derive repo layout + key directories + gate commands from the file tree and scripts (structure.md)
+
+3. Do **not** invent facts. If something cannot be verified, write it as:
+
+- `TBD` + what evidence is missing, or
+- an Open Question (if it blocks correctness)
+
+### Steering refresh checklist
+
+- [ ] product.md: what we build / users / success / non-goals / release posture
+- [ ] tech.md: Node / package manager / TS / test / lint / CI constraints
+- [ ] structure.md: repo layout, key packages, entrypoints, standard gate commands, how to run locally
+
+## Step 1 — Confirm prerequisites
+
+### 1.1 Read delta decision log (mandatory)
+
+Before implementing, read `.qfai/specs/spec-XXXX/delta.md` and treat it as authoritative for:
+
+- what options were considered (Decision Table)
+- what options were rejected or deferred (Decision Guardrails)
+
+Hard rule:
+
+- Do not implement rejected/deferred options unless the spec/delta is explicitly updated.
+- If you need an exception, raise an Open Question and propose a spec change first.
+
+Must exist:
+
+- `.qfai/specs/spec-XXXX/spec.md`
+- `.qfai/specs/spec-XXXX/delta.md`
+- `.qfai/specs/spec-XXXX/scenario.feature`
+  If missing, stop and request /qfai-spec.
+
+## Step 2 — Plan the implementation (Planner + Architect)
+
+Create a short plan:
+
+- Tasks (ordered)
+- Files likely affected
+- Risks + mitigations
+- Definition of Done (commands that must pass)
+
+If tool supports TodoWrite, record tasks.
+
+## Step 3 — Implement in small increments (Engineers)
+
+Rules:
+
+- Prefer small, reviewable commits (even if local).
+- Keep changes minimal and aligned with spec.
+- If spec is ambiguous, do not guess silently: record an Open Question and/or propose a spec update.
+
+## Step 4 — Keep tests aligned (Test Engineer)
+
+- Do NOT write new tests here. If tests are missing or need coverage, run `/qfai-tdd-red` first.
+- For acceptance tests, use `/qfai-atdd` instead of adding them here.
+- Exception: if existing tests are broken and gates cannot pass, apply the minimal fix. Avoid creating new tests.
+
+## Step 5 — Review & QA checks
+
+- Code Reviewer reviews diffs for maintainability and risk.
+- QA Engineer checks acceptance criteria coverage and failure handling.
+
+## Runtime Evidence (MANDATORY)
+
+Determine project type and provide evidence accordingly:
+
+### CLI tool
+
+- command executes without crash
+- expected outputs observed for at least:
+  - normal case
+  - invalid input case
+
+### Web/API service
+
+- service boots successfully
+- at least one contract path is exercised (local run or integration test)
+- request/response matches contract (status codes, schemas)
+
+### Library
+
+- build succeeds
+- a small integration "smoke usage" exists (example test or minimal consumer snippet)
+- public API compiles and behaves per acceptance criteria
+
+You must record:
+
+- exact commands executed
+- expected vs observed outcomes
+
+## Prohibited "done" criteria
+
+You must NOT declare completion based on:
+
+- code compilation only
+- unit tests only
+- spec text satisfaction without runtime run
+- mocked acceptance tests presented as real runtime (unless explicitly approved)
+
+## Step 6 — Integration checks (DevOps/CI Engineer)
+
+- ensure compilation/type checks pass
+- ensure runtime wiring exists (entrypoints, configuration)
+
+## Step 7 — Runtime evidence (Runtime Gatekeeper)
+
+- execute the runtime evidence commands above
+- capture expected vs observed outcomes
+
+## Step 8 — Run quality gates (DevOps/CI Engineer)
+
+Run the repo’s standard commands. At minimum:
+
+- formatting
+- lint
+- typecheck (if applicable)
+- unit tests
+- scenario tests (if applicable)
+
+Record:
+
+- commands
+- outputs (summary)
+- PASS/FAIL
+
+## Step 9 — If any gate fails: fix loop
+
+Iterate until all gates pass, prioritizing:
+
+1. correctness vs spec
+2. test determinism
+3. maintainability
+
+## Completion Criteria (Final Gate)
+
+**Before declaring implementation complete, you MUST verify:**
+
+1. Runtime evidence commands executed and outcomes recorded.
+
+2. Run QFAI validation:
+
+   ```bash
+   qfai validate --fail-on error
+   ```
+
+3. Run repository standard gates (discover from package.json/CI/docs):
+   - format check
+   - lint
+   - typecheck
+   - tests
+   - pack/verify (if distributed)
+
+   Record the exact commands and results.
+
+4. All gates must PASS.
+
+If you cannot run these commands (environment limitation):
+
+- Request the user to run them and provide the output.
+- Do NOT assume PASS without evidence.
+
+## Definition of Done (Mandatory Output)
+
+Include a **DoD** section with:
+
+- Commands executed (format/lint/type/unit/integration/verify-pack/dry-run as applicable)
+- Runtime evidence commands and results
+- A note on any mocks/stubs and why they are acceptable
+
+All must pass; otherwise, report as not complete.
+
+## Output
+
+- Implementation diffs
+- Updated tests (if needed)
+- Verification evidence (commands + results)
+- Runtime evidence summary (commands + outcomes)
+- DoD section (required)
+- Gate results: all PASS
+- Suggested next command: /qfai-verify (if not already done)