qfai 1.0.4 → 1.0.6

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

@@ -0,0 +1,291 @@
+<!--
+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-spec
+title: QFAI Spec (SDD Deliverables: specs + contracts + scenario skeleton)
+description: "Create SDD artifacts: spec pack, delta, scenario.feature skeleton, and required contracts."
+argument-hint: "<spec-id-or-name> [--auto]"
+allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
+roles: [Architect, ContractDesigner, TestEngineer, QAEngineer, CodeReviewer, Planner]
+mode: approval-gated
+
+---
+
+# /qfai-spec — Create Specification Pack (SDD)
+
+## Purpose
+
+Create/update a **spec pack** that becomes the source of truth for implementation and testing.
+
+## Success Criteria (Definition of Done)
+
+- A new directory exists: `.qfai/specs/spec-XXXX/` (or an existing one is updated).
+- At minimum, these files exist and are coherent:
+  - `spec.md` (SDD spec)
+  - `delta.md` (change log / impact / migration)
+  - `scenario.feature` (ATDD skeleton aligned with spec)
+- Contracts are added/updated under `.qfai/contracts/` _only when needed_.
+
+## 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.
+
+## 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 → 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 — Determine spec pack identity
+
+If the user does not provide an ID:
+
+- Propose the next available `spec-XXXX` and proceed (or ask if interactive).
+
+## Step 2 — Create/Update spec pack files
+
+### 2.1 `spec.md` template (Architect)
+
+Use this structure:
+
+# Spec: <title>
+
+## 1. Goal
+
+## 2. Non‑Goals
+
+## 3. Background / Context
+
+## 4. Requirements Mapping
+
+Reference the requirement IDs from `.qfai/require/require.md`.
+
+## 5. Proposed Behavior
+
+- User flows
+- Inputs/outputs
+- Error handling
+- Observability
+
+## 6. Interfaces & Contracts
+
+List which contracts are used:
+
+- UI contracts: (file paths / IDs)
+- API contracts:
+- DB contracts:
+
+If a contract is missing, mark it as “to be created” and create it in Step 3.
+
+## 7. Acceptance Criteria
+
+Tie each acceptance criterion to scenarios and/or tests.
+
+## 8. Risks & Mitigations
+
+## 9. Open Questions
+
+(only what truly blocks correctness)
+
+### 2.2 `delta.md` template (Planner + QA)
+
+Use this structure:
+
+# Delta
+
+## Summary
+
+## User-visible changes
+
+## Backward compatibility / migration notes
+
+## Affected areas
+
+## Verification plan (commands + expected results)
+
+## Rollback / recovery notes
+
+## Known limitations
+
+### 2.3 `scenario.feature` skeleton (Test Engineer)
+
+Create a minimal but correct Gherkin skeleton aligned with acceptance criteria:
+
+- Feature + Background
+- 1–3 core scenarios
+- Edge / failure scenarios as needed
+
+## Step 3 — Contracts (Contract Designer)
+
+Only create contracts when the spec requires a stable interface definition.
+
+- Place under:
+  - `.qfai/contracts/ui/`
+  - `.qfai/contracts/api/`
+  - `.qfai/contracts/db/`
+- Keep them minimal and aligned with what tests will validate.
+
+If your repo defines contract schema or naming rules, follow them. Otherwise:
+
+- **UI / API contracts:** write **YAML** and include “Purpose / Fields / Constraints / Examples” as YAML comments.
+- **DB contracts:** write **SQL (`.sql`)** and include a small header comment block, then representative DDL/schema notes.
+
+DB contract default conventions (unless your repo defines others):
+
+- Filename: `db-0001-<slug>.sql`
+- Header (must):
+  ```sql
+  -- QFAI-CONTRACT-ID: DB-0001
+  -- Purpose: <what this schema contract guarantees>
+  -- Constraints: <keys, nullability, ranges, invariants>
+  -- Examples: <optional example rows or queries>
+  ```
+- Body: DDL or schema notes that tests/scenarios can validate (minimal, spec-driven).
+
+## Step 4 — QA + Review
+
+- QA Engineer checks acceptance criteria ↔ scenario consistency.
+- Code Reviewer checks naming, contradictions, missing impact notes.
+- Planner ensures next steps are explicit and minimal.
+
+## Step 5 — Approval gate
+
+If interactive:
+
+- Ask approval before proceeding to test implementation.
+  If `--auto`:
+- Proceed with explicit assumptions flagged.
+
+## Output
+
+- `.qfai/specs/spec-XXXX/spec.md`
+- `.qfai/specs/spec-XXXX/delta.md`
+- `.qfai/specs/spec-XXXX/scenario.feature`
+- (If needed) updated `.qfai/contracts/**`
+- Next recommended command: /qfai-scenario-test and/or /qfai-unit-test

package/assets/init/.qfai/assistant/prompts/qfai-unit-test.md

@@ -0,0 +1,193 @@
+<!--
+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-unit-test
+title: QFAI Unit Test (TDD executable)
+description: "Implement CI-runnable unit tests derived from spec/scenario; includes review and quality checks."
+argument-hint: "<spec-id> [--auto]"
+allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
+roles: [TestEngineer, BackendEngineer, FrontendEngineer, QAEngineer, CodeReviewer]
+mode: test-first
+
+---
+
+# /qfai-unit-test — Implement Unit Tests (TDD)
+
+## Purpose
+
+Implement **unit tests** that enforce the spec and provide fast feedback.
+
+## Success Criteria (Definition of Done)
+
+- Unit tests exist, are deterministic, and runnable in CI.
+- Tests cover core logic and key edge cases derived from spec/scenario.
+- Tests fail meaningfully (actionable errors).
+
+## 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.
+
+## 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 → 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 — Read relevant artifacts
+
+- `.qfai/specs/spec-XXXX/spec.md`
+- `.qfai/specs/spec-XXXX/scenario.feature`
+- referenced contracts (if used by logic)
+
+## Step 2 — Identify units and boundaries (Test Engineer + Architect mindset)
+
+- What are the smallest meaningful units?
+- What should be mocked vs real?
+- Where are seams (interfaces) needed to test cleanly?
+
+## Step 3 — Write tests first (RED)
+
+- Add tests that should fail on current code.
+- Keep them minimal and focused.
+
+## Step 4 — Review test quality
+
+- QA Engineer: edge cases, unwanted behavior, observability
+- Code Reviewer: brittleness, over-mocking, unclear naming
+
+## Step 5 — Provide run commands + evidence
+
+- Document the exact command(s) to run unit tests.
+- Provide summary of pass/fail.
+
+## Output
+
+- Unit test files
+- Run command snippet
+- Evidence summary

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

@@ -0,0 +1,222 @@
+<!--
+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-verify
+title: QFAI Verify (Quality Gates + Evidence)
+description: "Run and document quality gates (repo + qfai validate/report), fix until PASS."
+argument-hint: "[--auto]"
+allowed-tools: [Read, Glob, Bash, Write, TodoWrite, Task]
+roles: [DevOpsCIEngineer, QAEngineer, CodeReviewer, Planner]
+mode: evidence-focused
+
+---
+
+# /qfai-verify — Quality Gates and Evidence
+
+## Purpose
+
+Run quality gates and produce **evidence** that the change is correct and safe.
+
+## Success Criteria (Definition of Done)
+
+- Repo quality gates PASS (format/lint/type/test/build/etc).
+- QFAI checks PASS (at minimum: `qfai validate`, and optionally `qfai report`).
+- A concise evidence summary exists (copy‑paste for PR).
+
+## 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.
+
+## 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 → 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 — Discover project gate commands (DevOps/CI Engineer)
+
+Prefer existing scripts:
+
+- package.json scripts
+- Makefile / task runner
+- CI config
+
+If unknown, propose defaults and mark assumptions.
+
+## Step 2 — Run QFAI gates
+
+Run (adjust as needed):
+
+- `qfai validate --fail-on error`
+- `qfai report` (if used in this repo)
+
+Capture:
+
+- exit codes
+- key errors/warnings
+- file paths affected
+
+## Step 3 — Run repo gates
+
+Run the repo’s standard pipeline in a stable order:
+
+1. format
+2. lint
+3. typecheck
+4. unit tests
+5. scenario/e2e tests
+6. build/package (if relevant)
+
+## Step 4 — Fix loop (Code Reviewer + QA)
+
+If anything fails:
+
+- Identify whether it’s spec mismatch, test issue, or implementation defect.
+- Fix the root cause (do not silence tests without reason).
+
+## Step 5 — Produce Evidence Summary (Planner)
+
+Output this format:
+
+### Verification Evidence
+
+- QFAI:
+  - command:
+  - result:
+- Repo gates:
+  - command:
+  - result:
+- Notes:
+  - assumptions:
+  - risks:
+
+## Output
+
+- Evidence summary
+- Next action suggestion: /qfai-pr (optional) or proceed to PR creation