qfai 1.0.4 → 1.0.6

package/assets/init/.qfai/assistant/prompts.local/README.md

@@ -0,0 +1,8 @@
+# prompts.local/
+
+Optional per-project overrides.
+
+If a file with the same name exists here (e.g., `qfai-spec.md`), a tool wrapper may prefer it to customize behavior for this repo.
+Keep overrides minimal; prefer updating steering/instructions instead.
+
+Note: After `qfai init`, this folder contains only this README. Place an override file here only when you intentionally diverge from the SSOT prompt bodies.

package/assets/init/.qfai/assistant/steering/README.md

@@ -0,0 +1,40 @@
+# steering/
+
+Project context for the AI. Keep these files up to date.
+
+These are intentionally short and practical:
+
+- `product.md` : what we are building and why
+- `tech.md` : stack, versions, constraints
+- `structure.md` : repo structure, key directories, how to run gates
+
+QFAI prompts are expected to read these before producing deliverables.
+
+## AI-managed policy (recommended)
+
+These steering files are intended to be **filled and refreshed by the AI** (via QFAI custom prompts).
+Humans may edit them, but the default workflow is:
+
+- run a QFAI command (e.g., /qfai-require, /qfai-spec, /qfai-implement)
+- the agent analyzes the repository and updates steering if placeholders exist
+
+Guideline:
+
+- do not invent facts; if unknown, write `TBD` with missing evidence
+
+## Evidence-first writing (recommended)
+
+Steering MUST be grounded in repo evidence. When possible, include:
+
+- file paths (e.g., `package.json`, `.github/workflows/ci.yml`)
+- commands (e.g., `pnpm -C packages/qfai test`)
+- directory anchors (e.g., `packages/qfai/src/cli`)
+
+If a fact cannot be verified, mark it as `TBD` and record what evidence is missing.
+
+### Default AI-managed flow (recommended)
+
+1. Run a QFAI command (e.g., `/qfai-require`, `/qfai-spec`, `/qfai-implement`).
+2. The agent loads `steering/*` and fills missing placeholders from **repo evidence**.
+3. If evidence is missing, write `TBD` and add an Open Question (what evidence is required).
+4. Optionally, review changes via PR if your team requires human approval.

package/assets/init/.qfai/assistant/steering/product.md

@@ -0,0 +1,32 @@
+# Product Steering
+
+## What are we building?
+
+- Summary:
+- Evidence: (e.g., README, docs, issue links)
+
+## Who is the user?
+
+- Personas / roles:
+- Evidence:
+
+## What is “success”?
+
+- Success metrics / acceptance definition:
+- Evidence:
+
+## Non-goals
+
+-
+- Evidence:
+
+## Release posture
+
+- Compatibility policy:
+- Breaking change policy:
+- Evidence:
+
+## Open questions
+
+- Blocking:
+- Non-blocking:

package/assets/init/.qfai/assistant/steering/structure.md

@@ -0,0 +1,34 @@
+# Structure Steering
+
+## Repo layout (high level)
+
+- Top-level directories:
+- Evidence:
+
+## Key packages / entrypoints
+
+- Package(s) of interest:
+- CLI entry:
+- Core modules:
+- Evidence:
+
+## Architecture constraints
+
+- Boundaries (what must not depend on what):
+- Conventions (naming, file layout):
+- Evidence:
+
+## Quality gates (SSOT)
+
+- format:
+- lint:
+- typecheck:
+- test:
+- verify-pack / pack:
+- Evidence:
+
+## How to run locally
+
+Provide copy-paste commands and expected outputs.
+
+- Evidence:

package/assets/init/.qfai/assistant/steering/tech.md

@@ -0,0 +1,37 @@
+# Tech Steering
+
+## Runtime / platform
+
+- Node:
+- Evidence:
+- OS assumptions:
+- Evidence:
+- CI environment:
+- Evidence:
+
+## Package manager
+
+- pnpm / npm / yarn:
+- Evidence:
+
+## Language / framework
+
+- TypeScript:
+- Build tool:
+- Test runner:
+- Lint / format:
+- Evidence:
+
+## Constraints
+
+-
+- Evidence:
+
+## Standard commands (copy-paste)
+
+- Install:
+- Test:
+- Lint:
+- Typecheck:
+- Pack/verify:
+- Evidence:

package/assets/init/.qfai/contracts/README.md

@@ -1,91 +1,11 @@
-# Contracts (UI / API / DB)
+# contracts/
 
-契約は「システム外部との約束」を明文化する場所です。Spec（spec.md）の `QFAI-CONTRACT-REF` による参照が必須で、これが Spec→Contract 対応の SSOT になります。Scenario は `# QFAI-CONTRACT-REF` で契約参照を宣言します（none 可）。
+Contracts define stable interfaces and are referenced by specs/scenarios/tests.
 
-## 置くべきファイル
+Subfolders:
 
-- UI: `ui/ui-0001-<slug>.yaml` または `.yml`
-- THEMA: `ui/thema-001-<slug>.yml`（3桁）
-- API: `api/api-0001-<slug>.yaml` / `.yml` / `.json`（OpenAPI）
-- DB: `db/db-0001-<slug>.sql`（ID は `DB-xxxx`）
-- assets: `ui/assets/<contract-id>/assets.yaml`（参照整合のみ検証）
+- `ui/` : UI contracts (YAML)
+- `api/`: API contracts (YAML)
+- `db/` : DB contracts (SQL / .sql)
 
-## 契約ID宣言（必須）
-
-- 1ファイル = 1ID
-- 契約IDの正は契約ファイル側（`QFAI-CONTRACT-ID` が SSOT）
-- ファイル内に `QFAI-CONTRACT-ID: <ID>` をコメント行で宣言する
-- 例: `# QFAI-CONTRACT-ID: API-0001` / `// QFAI-CONTRACT-ID: UI-0001` / `-- QFAI-CONTRACT-ID: DB-0001`
-
-## 最小例（UI）
-
-```yaml
-# QFAI-CONTRACT-ID: UI-0001
-id: UI-0001
-name: 受注登録画面
-refs:
-  - BR-0001
-themaRef: THEMA-001
-assets:
-  pack: assets/ui-0001-sample
-  use:
-    - UI-0001.desktop.light.default
-```
-
-## 最小例（THEMA）
-
-```yaml
-# QFAI-CONTRACT-ID: THEMA-001
-id: THEMA-001
-name: facebook-like
-tokens:
-  color:
-    background: "#FFFFFF"
-    textPrimary: "#111111"
-    accent: "#1877F2"
-```
-
-## 最小例（API）
-
-```yaml
-# QFAI-CONTRACT-ID: API-0001
-openapi: 3.0.0
-info:
-  title: Sample API
-  version: 0.1.0
-paths:
-  /health:
-    get:
-      operationId: API-0001
-      responses:
-        "200":
-          description: OK
-```
-
-## 最小例（DB）
-
-```sql
--- QFAI-CONTRACT-ID: DB-0001
-CREATE TABLE sample_table (
-  id INTEGER PRIMARY KEY
-);
-```
-
-## CI でチェックされること（抜粋）
-
-- 契約宣言: `QFAI-CONTRACT-ID` の未記載/複数宣言/重複IDは error
-- 契約ID: 配置ディレクトリ（ui/api/db）と prefix（UI/API/DB）の不整合は error
-- UI/API: パース失敗は error
-- API: OpenAPI 定義があること（`openapi`）
-- DB: 危険 SQL（DROP/TRUNCATE 等）の警告
-- 共通: ID 形式（`PREFIX-0001`）、ID の重複検知
-
-## 依存関係
-
-- Spec → Contracts（spec.md に `QFAI-CONTRACT-REF` を必ず1行以上宣言、0件は `none`。この行が SSOT）
-- Scenario → Contracts（scenario.feature に `# QFAI-CONTRACT-REF` を必ず1行以上宣言、0件は `none`）
-
-## 良い例 / 悪い例
-
-- 良い例: Spec で契約を参照し、必要に応じて Scenario でも参照している
-- 悪い例: Spec が契約を参照しておらず orphan contract が発生する（allowOrphanContracts=false で error）
+Create contracts only when needed by the spec (keep minimal).

package/assets/init/.qfai/contracts/api/README.md

@@ -0,0 +1,8 @@
+# contracts/api/
+
+Place API contracts here (YAML).
+
+Guidelines:
+
+- Keep contracts minimal: define only what scenarios/tests need to validate.
+- Include examples where helpful.

package/assets/init/.qfai/contracts/db/README.md

@@ -0,0 +1,25 @@
+# contracts/db/
+
+Place **DB contracts** here as **SQL DDL files** (`.sql`).
+
+## File naming
+
+- `db-0001-<slug>.sql`
+  - Contract ID: `DB-0001` (4-digit fixed)
+
+## Required header
+
+Include the contract ID in the SQL header comments so QFAI can discover/index it:
+
+```sql
+-- QFAI-CONTRACT-ID: DB-0001
+-- DB-0001 (short description)
+```
+
+## Guidelines
+
+- Keep DB contracts minimal and spec-driven (only what scenarios/tests need).
+- This directory is for the **contract/schema snapshot**, not migrations history.
+- If your project uses an ORM schema (Prisma, etc.), decide one:
+  - (Recommended for v1.0.6) Keep a minimal `.sql` contract snapshot here, and link to the real schema in the spec.
+  - (Future) Add support for other schema formats via config (out of scope for v1.0.6).

package/assets/init/.qfai/contracts/ui/README.md

@@ -0,0 +1,8 @@
+# contracts/ui/
+
+Place UI contracts here (YAML).
+
+Guidelines:
+
+- Keep contracts minimal: define only what scenarios/tests need to validate.
+- Include examples where helpful.

package/assets/init/.qfai/report/README.md

@@ -0,0 +1,13 @@
+# report/
+
+This directory is reserved for generated outputs.
+
+Examples:
+
+- `qfai report` output
+- generated traceability reports
+- diagnostic artifacts you choose to store
+
+Recommended:
+
+- commit policy is project-dependent (often: do NOT commit large generated files)

package/assets/init/.qfai/require/README.md

@@ -1,28 +1,6 @@
-# .qfai/require/
+# require/
 
-既存の要件定義書や外部資料を集約するためのディレクトリです。
-QFAI は `.qfai/require/` を **入力（上流）** として扱い、ここに置かれた内容を根拠に Spec を作成します。
+This folder contains the Requirements SSOT.
 
-## 置き方（例）
-
-- `.qfai/require/req-0001-<slug>.md`
-- `.qfai/require/links.md`（外部ドキュメントへのリンク集）
-- `.qfai/require/raw/`（PDFや画像などの原本）
-
-> 形式は限定しません。内容が参照可能であることを優先してください。
-
-## 参照ルール（重要）
-
-- `.qfai/require/` は **上流のSSOT** です。
-- `.qfai/specs` や `contracts` は **.qfai/require を参照してよい**。
-- `.qfai/require` 側から `.qfai/specs` や `contracts` を参照するのは **禁止**（循環参照防止）。
-
-## AI プロンプトの利用
-
-- `.qfai/prompts/require-to-spec.md` を使用し、要件から Spec を作成します。
-- 生成後は必ず人間がレビューし、Spec/Scenario/Contracts の整合を確認してください。
-
-## 注意
-
-- `.qfai/require/` の内容は QFAI の validate 対象外です。
-- 機密情報の取り扱いは各プロジェクトのルールに従ってください。
+- `require.md` is the single-file requirements artifact.
+- Keep requirements **testable** (EARS) and avoid implementation detail.

package/assets/init/.qfai/require/require.md

@@ -0,0 +1,74 @@
+# Requirements
+
+> Fill this in using `/qfai-require`.
+
+## 1. Overview
+
+- Problem / opportunity:
+- Target users:
+- Success definition:
+
+## 2. Scope
+
+### In scope
+
+-
+
+### Out of scope
+
+-
+
+## 3. Constraints & Assumptions
+
+### Constraints
+
+-
+
+### Assumptions
+
+-
+
+## 4. Glossary
+
+-
+
+## 5. Functional Requirements (EARS)
+
+### REQ-FUNC-001: <title>
+
+- Statement (EARS):
+- Rationale:
+- Acceptance criteria:
+- Notes / edge cases:
+
+## 6. Non‑Functional Requirements
+
+### Security
+
+-
+
+### Performance
+
+-
+
+### Reliability / Availability
+
+-
+
+### Observability
+
+-
+
+## 7. Acceptance Criteria (summary)
+
+-
+
+## 8. Open Questions
+
+### Blocking
+
+-
+
+### Non‑blocking
+
+-

package/assets/init/.qfai/specs/README.md

@@ -1,59 +1,11 @@
-# Specs (Spec Pack)
+# specs/
 
-このディレクトリは「Spec / Delta / Scenario」を **1セット（Spec Pack）** として管理するための入口です。
+A **spec pack** lives under `specs/spec-XXXX/` and contains:
 
-## 置くべきファイル
+- `spec.md` : SDD spec (source of truth for behavior)
+- `delta.md` : impact / migration / verification plan
+- `scenario.feature` : Gherkin scenarios (ATDD skeleton)
 
-- `spec-0001/spec.md`（必須）
-- `spec-0001/delta.md`（必須）
-- `spec-0001/scenario.feature`（必須・Gherkin）
+Create/update spec packs with `/qfai-spec`.
 
-> `spec-0001` は **4桁連番**。Spec ID も **4桁（SPEC-0001）** です。
-
-## Spec（spec.md）最小例
-
-```md
-# SPEC-0001: 注文登録の最小要件
-
-QFAI-CONTRACT-REF: UI-0001, API-0001, DB-0001, THEMA-001
-
-## 背景
-
-- 例: 受注の登録ルールを明文化し、手戻りを減らすため
-
-## 業務ルール
-
-- [BR-0001][P2] 受注は承認者が承認するまで確定しない
-```
-
-### BR の書き方
-
-- **1ルール = 1 BR** を守る
-- Priority は **P0/P1/P2/P3** のいずれかを必ず付与
-- BR 定義は **`## 業務ルール` セクション内のみ**（他セクションは参照扱い）
-
-### Contract 参照の書き方
-
-- `QFAI-CONTRACT-REF:` 行で契約IDを宣言する（複数行可）
-- 参照不要な場合は `QFAI-CONTRACT-REF: none`
-
-## Delta（delta.md）
-
-- 変更の要約・根拠・影響範囲・受入観点を明記する
-
-## Scenario（scenario.feature）最小要件
-
-- **Gherkin 記法**（Given/When/Then）
-- **1ファイル = 1 Scenario**（Scenario Outline 含む）
-- `# QFAI-CONTRACT-REF: ...` をコメント行で **必須宣言**（参照なしは `none`）
-- `@SPEC-xxxx` は Feature レベルに **ちょうど1つ**必要
-- Scenario / Scenario Outline には `@SC-xxxx` が **ちょうど1つ**必要
-- Scenario / Scenario Outline には `@BR-xxxx` が **1つ以上**必要
-
-## CI でチェックされること（抜粋）
-
-- Spec: 必須セクション、SPEC/BR ID、BR Priority、ID 形式、Contract 参照の実在性、Contract 参照の必須宣言
-- Delta: delta.md の存在
-- Scenario: Feature/Scenario の存在、タグ要件、Given/When/Then、契約参照の宣言/形式
-- Traceability: BR→SC、Spec→Contract、SC→Test の接続、BR の所属 SPEC 整合
-- IDs: 定義 ID の重複検知（Spec/Scenario/Contracts）
+Note: After `qfai init`, this folder contains only this README. Spec packs (`spec-XXXX/`) are created by running `/qfai-spec`.

package/assets/init/root/.github/workflows/qfai.yml

@@ -19,4 +19,4 @@ jobs:
       - uses: actions/upload-artifact@v4
         with:
           name: qfai-validation
-          path: .qfai/out/validate.json
+          path: .qfai/report/validate.json

package/assets/init/root/qfai.config.yaml

@@ -1,8 +1,8 @@
 paths:
   specsDir: .qfai/specs
   contractsDir: .qfai/contracts
-  outDir: .qfai/out
-  promptsDir: .qfai/prompts
+  outDir: .qfai/report
+  promptsDir: .qfai/assistant/prompts
   srcDir: src
   testsDir: tests
 validation:
@@ -29,4 +29,4 @@ validation:
     orphanContractsPolicy: error
     unknownContractIdSeverity: error
 output:
-  validateJsonPath: .qfai/out/validate.json
+  validateJsonPath: .qfai/report/validate.json