qfai 0.2.5 → 0.2.8

package/README.md

@@ -1,4 +1,4 @@
-# QFAI Toolkit (v0.2.5)
+# QFAI Toolkit (v0.2.8)
 
 Single-package distribution for QFAI.
 

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

@@ -0,0 +1,42 @@
+# QFAI Project Kit (.qfai)
+
+このディレクトリは QFAI の成果物を集約する専用領域です。`.qfai` 配下だけを見れば「何を書くか」「どこから始めるか」が分かる構成にしています。
+
+## 最短成功（init → validate → report）
+
+```bash
+npx qfai validate --fail-on error --format github --json-path .qfai/out/validate.json
+npx qfai report --json-path .qfai/out/validate.json --out .qfai/out/report.md
+```
+
+## ディレクトリ概要
+
+- `spec/` : 仕様・シナリオ・ADR（意思決定）を置く場所
+- `contracts/` : UI / API / DB 契約を置く場所
+- `prompts/` : 生成プロンプト資産（自動読取はしない）
+- `out/` : `validate` / `report` の出力先（gitignore 推奨）
+
+詳細は各 README を参照してください。
+
+- `spec/README.md`
+- `spec/decisions/README.md`
+- `contracts/README.md`
+- `prompts/README.md`
+- `out/README.md`
+
+## 設定と CI
+
+- 設定ファイル: `qfai.config.yaml`（リポジトリ直下）
+- CI テンプレ: `.github/workflows/qfai.yml`
+
+## Prompts の使い方（重要）
+
+`prompts/` は **人間が手動で使う資産**です。v0.2.6 では自動読取を行いません。
+
+例:
+
+- Copilot: `.github/copilot-instructions.md` に要旨を転記
+- Claude: `CLAUDE.md` に要旨を転記
+- Codex: `AGENTS.md` に要旨を転記
+
+詳細は `prompts/README.md` を参照してください。

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

@@ -0,0 +1,61 @@
+# Contracts (UI / API / DB)
+
+契約は「システム外部との約束」を明文化する場所です。Scenario または Spec から参照される前提で作成します。
+
+## 置くべきファイル
+
+- UI: `ui/ui-0001-<slug>.yaml` または `.yml`
+- API: `api/api-0001-<slug>.yaml` / `.yml` / `.json`（OpenAPI）
+- DB: `db/db-0001-<slug>.sql`（ID は `DATA-xxxx`）
+
+## 最小例（UI）
+
+```yaml
+id: UI-0001
+name: 受注登録画面
+refs:
+  - BR-0001
+```
+
+## 最小例（API）
+
+```yaml
+openapi: 3.0.0
+info:
+  title: Sample API
+  version: 0.1.0
+paths:
+  /health:
+    get:
+      operationId: API-0001
+      responses:
+        "200":
+          description: OK
+```
+
+## 最小例（DB）
+
+```sql
+-- DATA-0001
+CREATE TABLE sample_table (
+  id INTEGER PRIMARY KEY
+);
+```
+
+## CI でチェックされること（抜粋）
+
+- UI/API: パース失敗は error、ID 未定義は error
+- UI: `UI-xxxx` の ID が必要
+- API: OpenAPI 定義があること、`API-xxxx` の operationId が必要
+- DB: 危険 SQL（DROP/TRUNCATE 等）の警告
+- 共通: ID 形式（`PREFIX-0001`）、定義 ID の重複検知
+
+## 依存関係
+
+- Scenario → Contracts（UI/API/DATA のいずれかへ接続）
+- Spec → Contracts（参照は許容）
+
+## 良い例 / 悪い例
+
+- 良い例: `@SC-xxxx` から `UI-xxxx` が参照されている
+- 悪い例: 契約が Scenario から一切参照されない

package/assets/init/{qfai → .qfai}/contracts/api/api-0001-sample.yaml

@@ -1,3 +1,6 @@
+# OpenAPI contract sample (API-0001)
+# - 必須: openapi, info, paths
+# - 参照: BR/SC の ID を x-qfai-refs に記載
 openapi: 3.0.0
 info:
   title: QFAI Sample API

package/assets/init/{qfai → .qfai}/contracts/db/db-0001-sample.sql

@@ -1,5 +1,6 @@
--- DATA-0001
+-- DATA-0001 (DB contract sample)
+-- 破壊的 SQL (削除/破棄系) は警告対象
 CREATE TABLE sample_table (
   id INTEGER PRIMARY KEY,
   name VARCHAR(255) NOT NULL
-);
+);

package/assets/init/.qfai/contracts/ui/ui-0001-sample.yaml

@@ -0,0 +1,6 @@
+# UI contract sample (UI-0001)
+# - 必須: id (例: UI-0001), name, refs
+id: UI-0001
+name: Order Registration
+refs:
+  - BR-0001

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

@@ -0,0 +1,17 @@
+# Output (.qfai/out)
+
+`qfai validate` と `qfai report` の出力先です。
+
+## 生成されるファイル
+
+- `validate.json` : 検証結果（JSON）
+- `report.md` / `report.json` : レポート
+
+## 運用メモ
+
+- 原則として **コミットしない** ことを推奨します
+- `.gitignore` への追記例:
+
+```
+.qfai/out/
+```

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

@@ -0,0 +1,32 @@
+# Prompts (手動利用)
+
+このディレクトリのプロンプトは **手動で使う資産**です。v0.2.6 では自動読取を行いません。
+
+## 目的
+
+- Spec から overview / Business Flow を生成するための素材
+- 将来（v0.9）の adapter/emit 実装に備えた配布物
+
+## 使い方（例）
+
+1. 目的のプロンプトを開く（例: `makeOverview.md`）
+2. そのまま AI エージェントに貼り付ける
+3. 指示された出力先に生成結果を保存する
+
+### エージェント別の手動導線（例）
+
+- Copilot: `.github/copilot-instructions.md` に要旨を転記
+- Claude: `CLAUDE.md` に要旨を転記
+- Codex: `AGENTS.md` に要旨を転記
+
+※ いずれも **自動生成はしません**。必要に応じて人手で同期してください。
+
+## 出力先の例
+
+- Overview: `docs/specs/overview.md`
+- Business Flow: `docs/flows/bf-0001-<slug>.md`
+
+## CI との関係
+
+- プロンプト自体は CI の検査対象ではありません
+- 生成物をレビューし、Spec/Scenario/Contracts と整合しているかを確認してください

package/assets/init/{qfai → .qfai}/prompts/makeBusinessFlow.md

@@ -5,7 +5,7 @@ Spec群を読み、Specに明示されている情報のみを根拠として、
 
 ## Inputs
 
-- 対象: qfai/spec/spec.md と qfai/spec/spec-0001-\*.md 形式のファイル（4 桁の数字 + ハイフン + slug。実際のパターン: `spec-\d{4}-[^/\\]+\.md`。存在するもの全て）
+- 対象: .qfai/spec/spec-0001-\*.md 形式のファイル（4 桁の数字 + ハイフン + slug。実際のパターン: `spec-\d{4}-[^/\\]+\.md`。存在するもの全て）
 
 ## Output (Option)
 

package/assets/init/{qfai → .qfai}/prompts/makeOverview.md

@@ -4,7 +4,7 @@
 
 ## Inputs
 
-- 対象: qfai/spec/spec.md と qfai/spec/spec-0001-\*.md 形式のファイル（4 桁の数字 + ハイフン + slug。実際のパターン: `spec-\d{4}-[^/\\]+\.md`。存在するもの全て）
+- 対象: .qfai/spec/spec-0001-\*.md 形式のファイル（4 桁の数字 + ハイフン + slug。実際のパターン: `spec-\d{4}-[^/\\]+\.md`。存在するもの全て）
 
 ## Output
 

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

@@ -0,0 +1,80 @@
+# Spec / Scenario / Decisions
+
+このディレクトリは「仕様（Spec）」「シナリオ（Scenario）」「意思決定（ADR）」の入口です。
+
+## 置くべきファイル
+
+- Spec: `spec-0001-<slug>.md`（必須）
+- Scenario: `scenarios/*.feature`
+- Decisions: `decisions/ADR-0001.md` など
+
+## 最小例（Spec）
+
+```md
+# SPEC-0001: 注文登録の最小要件
+
+## 背景
+
+- 例: 受注の登録ルールを明文化し、手戻りを減らすため
+
+## スコープ
+
+- 例: 新規受注の登録と承認
+
+## 非ゴール
+
+- 例: 既存受注の履歴移行は対象外
+
+## 用語
+
+- 例: 受注 = 顧客からの注文情報
+
+## 前提
+
+- 例: 承認者は1名以上配置されている
+
+## 決定事項
+
+- 例: 承認は1段階で完了とする
+
+## 業務ルール
+
+- [BR-0001] 受注は承認者が承認するまで確定しない
+- [BR-0002] 承認済みの受注のみ出荷依頼に進める
+```
+
+## BR の書き方（重要）
+
+- **1 ルール = 1 BR** を守る
+- 小項目がある場合は **別 BR を採番**する（`BR-0001.1` は使わない）
+- 参照は常に BR ID を使う
+
+## Scenario の最小要件
+
+- `@SC-xxxx` / `@SPEC-xxxx` / `@BR-xxxx` をタグで明示
+- Scenario は複数の SPEC を参照してよい（`@SPEC-xxxx` を複数記載可能）
+- `Given / When / Then` を含める
+- UI/API/DATA 契約に接続する（トレーサビリティのエラー回避）
+
+## CI でチェックされること（抜粋）
+
+- Spec: 必須セクションの有無、SPEC/BR ID の存在、ID 形式（`PREFIX-0001`）、Contract 参照の実在性
+- Scenario: SC/SPEC/BR の参照、Given/When/Then の有無、参照IDの実在性
+- Traceability: BR→SC、SC→契約（UI/API/DATA）の接続、BR の所属 SPEC 整合
+- IDs: 定義 ID の重複検知（Spec/Scenario/Contracts）
+
+## 依存関係
+
+- Spec → Scenario → Contracts
+- Spec → Contracts（参照は許容）
+- Decisions（ADR）→ Spec / BR
+
+## 良い例 / 悪い例
+
+- 良い例: `BR-0001` が Scenario で参照され、UI/API/DATA のいずれかに接続している
+- 悪い例: Spec に `SC-xxxx` を書く（Spec は SC を参照しない）
+
+## 良い運用 / 悪い運用
+
+- 良い運用: Spec/Scenario/Contracts を同じ ID でつなぐ
+- 悪い運用: Spec の BR が Scenario に出てこない（孤立）

package/assets/init/.qfai/spec/decisions/ADR-0001.md

@@ -0,0 +1,9 @@
+# ADR-0001: 承認フローは1段階にする
+
+> このファイルは「なぜその判断をしたか」を残すためのテンプレです。
+
+- Status: Proposed
+- Context: 承認者を増やすと運用が複雑になる
+- Decision: v0.2.6 では1段階の承認に固定する
+- Consequences: 多段承認が必要な場合は拡張が必要
+- Related: BR-0001, SPEC-0001

package/assets/init/.qfai/spec/decisions/README.md

@@ -0,0 +1,36 @@
+# ADR (Architecture Decision Record)
+
+ADR は「なぜその判断をしたか」を記録するための軽量な意思決定ログです。
+
+## いつ書くか
+
+- 仕様の前提や制約が変わるとき
+- 技術選定や設計方針を決めたとき
+- 重要なトレードオフがあるとき
+
+## 最小例
+
+```md
+# ADR-0001: 承認フローは1段階にする
+
+- Status: Proposed
+- Context: 承認者を増やすと運用が複雑になる
+- Decision: v0.2.6 では1段階の承認に固定する
+- Consequences: 多段承認が必要な場合は拡張が必要
+- Related: BR-0001, SPEC-0001
+```
+
+## CI でチェックされること（抜粋）
+
+- ID 形式（`PREFIX-0001`。ADR を含む）
+- 参照 ID の整合性（トレーサビリティ）
+
+## 依存関係
+
+- ADR は Spec / BR と一緒に参照される
+- Scenario/Contracts から参照されることは少ない
+
+## 良い例 / 悪い例
+
+- 良い例: Context/Decision/Consequences が簡潔に書かれている
+- 悪い例: Decision が空のまま放置されている

package/assets/init/.qfai/spec/scenarios/scenarios.feature

@@ -0,0 +1,6 @@
+@SC-0001 @BR-0001 @SPEC-0001 @UI-0001 @API-0001 @DATA-0001
+Feature: Order registration
+  Scenario: Register a new order
+    Given no order exists for the customer
+    When the user submits a new order
+    Then the order is created as pending approval

package/assets/init/.qfai/spec/spec-0001-sample.md

@@ -0,0 +1,36 @@
+# SPEC-0001: 注文登録の最小仕様（サンプル）
+
+> このテンプレは **最小例** です。実際の仕様に合わせて書き換えてください。
+
+## 背景
+
+- 例: 受注の登録ルールを統一し、手戻りを減らす
+
+## スコープ
+
+- 例: 新規受注の登録と承認
+
+## 非ゴール
+
+- 例: 既存受注の履歴移行は対象外
+
+## 用語
+
+- 例: 受注 = 顧客からの注文情報
+
+## 前提
+
+- 例: 承認者は1名以上配置されている
+
+## 決定事項
+
+- 例: 承認は1段階で完了とする
+
+## 業務ルール
+
+- [BR-0001] 受注は承認者が承認するまで確定しない
+
+### 書き方メモ
+
+- BR は **原子ルール** として採番する（`BR-0001.1` は使わない）
+- Spec では **SC ID** を参照しない

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

@@ -1,12 +1,11 @@
 paths:
-  specDir: qfai/spec
-  decisionsDir: qfai/spec/decisions
-  scenariosDir: qfai/spec
-  rulesDir: qfai/rules
-  contractsDir: qfai/contracts
-  uiContractsDir: qfai/contracts/ui
-  apiContractsDir: qfai/contracts/api
-  dataContractsDir: qfai/contracts/db
+  specDir: .qfai/spec
+  decisionsDir: .qfai/spec/decisions
+  scenariosDir: .qfai/spec/scenarios
+  contractsDir: .qfai/contracts
+  uiContractsDir: .qfai/contracts/ui
+  apiContractsDir: .qfai/contracts/api
+  dataContractsDir: .qfai/contracts/db
   srcDir: src
   testsDir: tests
 validation:
@@ -24,6 +23,7 @@ validation:
     brMustHaveSc: true
     scMustTouchContracts: true
     allowOrphanContracts: false
+    unknownContractIdSeverity: error
 output:
   format: text
   jsonPath: .qfai/out/validate.json