qfai 0.4.0 → 0.4.4

package/README.md

@@ -20,7 +20,7 @@ npx qfai report
 
 - `npx qfai init` によるテンプレート生成（specs/contracts に加え、`.qfai/require/README.md`、`.qfai/rules/pnpm.md`、`.qfai/prompts/require-to-spec.md`、`.qfai/promptpack/` を含む）
 - `npx qfai validate` による `.qfai/` 内ドキュメントの整合性・トレーサビリティ検査
-- `npx qfai validate` による SC→Test 参照の検証（`tests/` 配下を走査）
+- `npx qfai validate` による SC→Test 参照の検証（`validation.traceability.testFileGlobs` に一致するテストファイルから `QFAI:SC-xxxx` を抽出）
 - `npx qfai report` によるレポート出力
 
 ## Usage
@@ -32,8 +32,27 @@ npx qfai report
 設定はリポジトリ直下の `qfai.config.yaml` で行います。
 命名規約は `docs/rules/naming.md` を参照してください。
 
+## Contracts
+
+Spec では `QFAI-CONTRACT-REF:` 行で参照する契約IDを宣言します（`none` 可、宣言行は必須）。
+契約ファイルは `QFAI-CONTRACT-ID: <ID>` を **1ファイル1ID** で宣言します。
+Contract ID prefix は `UI-0001` / `API-0001` / `DB-0001` です。
+宣言では大文字（`UI-0001`）、ファイル名は小文字（`ui-0001-...`）を使用します。
+
+契約関連の検証は `validation.traceability` で制御します。
+
+- `validation.traceability.allowOrphanContracts`: Spec から参照されない契約の許可（default: `false`）
+- `validation.traceability.unknownContractIdSeverity`: Spec が参照した契約 ID が存在しない場合の severity（default: `error`、`error` / `warning` のみ）
+
+`npx qfai init` は `.qfai/contracts/` 配下に UI/API/DB のサンプルを生成します。
+
+SC→Test の参照はテストコード内の `QFAI:SC-xxxx` アノテーションで宣言します。
+SC→Test の対象ファイルは `validation.traceability.testFileGlobs` で指定します。
+除外は `validation.traceability.testFileExcludeGlobs` で指定できます。
 SC→Test 検証は `validation.traceability.scMustHaveTest` と
 `validation.traceability.scNoTestSeverity` で制御できます。
 
+- `validation.traceability.testFileGlobs`: SC→Test 判定に使用するテストファイル glob（配列）
+- `validation.traceability.testFileExcludeGlobs`: 追加の除外 glob（配列、任意）
 - `validation.traceability.scMustHaveTest`: SC→Test 検証の有効/無効を制御（`true` で有効、`false` で無効）
 - `validation.traceability.scNoTestSeverity`: SC 未参照時の重要度を指定（`error` / `warning`）

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

@@ -11,7 +11,8 @@ npx qfai report
 
 ## トレーサビリティ（SC→Test）
 
-- `tests/` 配下のテストコードで `SC-xxxx` を参照する（コメント可）
+- `validation.traceability.testFileGlobs` に一致するテストコードで `QFAI:SC-xxxx` を参照する（コメント可）
+- Spec→Contract は `spec.md` の `QFAI-CONTRACT-REF` 行で宣言する
 
 ## ディレクトリ概要
 
@@ -32,6 +33,7 @@ npx qfai report
 - `rules/pnpm.md`
 - `prompts/README.md`
 - `prompts/require-to-spec.md`
+- `prompts/qfai-generate-test-globs.md`
 - `promptpack/constitution.md`
 - `out/README.md`
 

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

@@ -6,11 +6,18 @@
 
 - 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`）
+- DB: `db/db-0001-<slug>.sql`（ID は `DB-xxxx`）
+
+## 契約ID宣言（必須）
+
+- 1ファイル = 1ID
+- ファイル内に `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:
@@ -20,6 +27,7 @@ refs:
 ## 最小例（API）
 
 ```yaml
+# QFAI-CONTRACT-ID: API-0001
 openapi: 3.0.0
 info:
   title: Sample API
@@ -36,7 +44,7 @@ paths:
 ## 最小例（DB）
 
 ```sql
--- DATA-0001
+-- QFAI-CONTRACT-ID: DB-0001
 CREATE TABLE sample_table (
   id INTEGER PRIMARY KEY
 );
@@ -44,16 +52,17 @@ CREATE TABLE sample_table (
 
 ## CI でチェックされること（抜粋）
 
-- UI/API: パース失敗は error、ID 未定義は error
-- UI: `UI-xxxx` の ID が必要
-- API: OpenAPI 定義があること、`API-xxxx` の operationId が必要
+- 契約宣言: `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 の重複検知
+- 共通: ID 形式（`PREFIX-0001`）、ID の重複検知
 
 ## 依存関係
 
-- Scenario → Contracts（UI/API/DATA のいずれかへ接続）
-- Spec → Contracts（参照は許容）
+- Spec → Contracts（`QFAI-CONTRACT-REF` で宣言、`none` 可）
+- Scenario → Contracts（UI/API/DB の参照は任意）
 
 ## 良い例 / 悪い例
 

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

@@ -1,6 +1,7 @@
+# QFAI-CONTRACT-ID: API-0001
 # OpenAPI contract sample (API-0001)
+# - 必須: QFAI-CONTRACT-ID (1ファイル1ID)
 # - 必須: openapi, info, paths
-# - 重要: operationId に API-0001 のような ID を含める（validate が参照整合に利用）
 openapi: 3.0.0
 info:
   title: QFAI Sample API
@@ -8,7 +9,7 @@ info:
 paths:
   /health:
     get:
-      operationId: API-0001
+      operationId: healthCheck
       responses:
         "200":
           description: OK

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

@@ -1,4 +1,5 @@
--- DATA-0001 (DB contract sample)
+-- QFAI-CONTRACT-ID: DB-0001
+-- DB-0001 (DB contract sample)
 -- 破壊的 SQL (削除/破棄系) は警告対象
 CREATE TABLE sample_table (
   id INTEGER PRIMARY KEY,

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

@@ -1,5 +1,7 @@
+# QFAI-CONTRACT-ID: UI-0001
 # UI contract sample (UI-0001)
-# - 必須: id (例: UI-0001), name, refs
+# - 必須: QFAI-CONTRACT-ID (1ファイル1ID)
+# - 任意: id, name, refs
 id: UI-0001
 name: Order Registration
 refs:

package/assets/init/.qfai/promptpack/modes/change.md

@@ -1,4 +1,5 @@
 # Mode: Change
 
-- 仕様変更の根拠を delta.md に必ず記録する
-- 影響範囲を整理し、テストを増分で設計する
+- 期待値/挙動/互換性が変わる場合は Change を選ぶ
+- 仕様変更の根拠（Why）を delta.md に必ず記録する
+- 影響範囲、移行・運用への影響、受入テスト更新方針を明記する

package/assets/init/.qfai/promptpack/modes/compatibility.md

@@ -1,4 +1,6 @@
 # Mode: Compatibility
 
 - 既存仕様との整合を最優先にする
+- 期待値/外部I/Fの変更は行わない（変更がある場合は Change へ）
 - 影響範囲を最小化し、回帰テストを重視する
+- 分類と根拠（Why）、影響範囲、受入テスト更新方針を明記する

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

@@ -12,6 +12,7 @@
 - `makeOverview.md`: Spec 一覧（overview）生成
 - `makeBusinessFlow.md`: 業務フロー（BF）整理
 - `require-to-spec.md`: 既存要件から Spec Pack を起こす
+- `qfai-generate-test-globs.md`: テストファイル glob の生成支援（`qfai.config.yaml` 更新）
 
 ## 使い方（例）
 

package/assets/init/.qfai/prompts/qfai-generate-test-globs.md

@@ -0,0 +1,29 @@
+# QFAI: テストファイル glob 生成（プロジェクト分析→qfai.config.yaml 更新）
+
+あなたはリポジトリを解析し、QFAI の SC→Test 判定に使用する「テストファイル glob」を作成します。
+
+## 目的
+
+- SC→Test の根拠は **テストファイル内の `QFAI:SC-xxxx`** アノテーションです。
+- その抽出対象（テストファイル集合）を、プロジェクト実態に合わせて **過不足なく**指定してください。
+
+## 手順
+
+1. どのテストフレームワーク/ランナーが使われているかを特定してください。
+   - 例: `package.json` の dependencies/devDependencies、設定ファイル（`vitest.config.*`, `jest.config.*`, `playwright.config.*` 等）、CI 設定など
+2. テストファイルが存在するディレクトリと命名規則を列挙してください。
+   - `tests/` 配下だけでなく、**`src/` 同居**（`*.test.*`）も考慮すること
+   - e2e / integration / unit が分かれている場合はそれも考慮すること
+3. 「テストファイル glob（含める）」を 3-10 個程度で提案してください。
+   - 過剰に広い `**/*` は禁止（性能・誤検知の観点）
+4. 「除外 glob」を提案してください（既定除外に加えて必要なら）。
+5. `qfai.config.yaml` を更新してください。
+   - `validation.traceability.testFileGlobs` に glob 配列を設定
+   - 必要なら `validation.traceability.testFileExcludeGlobs` も設定
+6. 更新後、実在するテストファイルを 5-15 件サンプリングし、各ファイルが提案 glob にマッチすることを示してください。
+7. 最後に、提案 glob を 1 行ずつコメント付きでまとめてください（採用理由を短く）。
+
+## 制約
+
+- `.qfai/` 配下、`node_modules/`、ビルド成果物（`dist/`, `build/` 等）は対象外
+- 変更は **glob 設定に限定**（テストやソースの内容改変はしない）

package/assets/init/.qfai/prompts/require-to-spec.md

@@ -19,12 +19,14 @@
 ## Rules
 
 - **推測しない**。要件に書かれていないことは `TBD` と明記する。
-- ID は `PREFIX-0001` 形式（SPEC/BR/SC/UI/API/DATA）。
+- ID は `PREFIX-0001` 形式（SPEC/BR/SC/UI/API/DB）。
 - `spec.md` の必須セクションは `qfai.config.yaml` の設定に従う。
 - BR は `## 業務ルール` にのみ定義し、`- [BR-0001][P1] ...` 形式で書く。
+- `spec.md` に `QFAI-CONTRACT-REF:` を必ず記載する（不要なら `none`）。
 - `scenario.md` は Gherkin で書き、Feature に `@SPEC-xxxx` を付与する。
 - 各 Scenario は `@SC-xxxx` を **ちょうど1つ**、`@BR-xxxx` を **1つ以上**持つこと。
-- 契約 ID（UI/API/DATA）が必要なら、タグまたは本文に明示する。
+- 契約ファイルには `QFAI-CONTRACT-ID: <ID>` を宣言する。
+- 契約 ID（UI/API/DB）を Scenario で参照する場合はタグまたは本文に明示する。
 - `delta.md` の「変更区分」は **Compatibility / Change/Improvement のいずれか1つにチェック**する。
   - 判断できない場合は `Compatibility` を選び、`TBD` を理由欄に記載する。
 

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

@@ -15,6 +15,8 @@
 ```md
 # SPEC-0001: 注文登録の最小要件
 
+QFAI-CONTRACT-REF: UI-0001, API-0001, DB-0001
+
 ## 背景
 
 - 例: 受注の登録ルールを明文化し、手戻りを減らすため
@@ -30,6 +32,11 @@
 - Priority は **P0/P1/P2/P3** のいずれかを必ず付与
 - BR 定義は **`## 業務ルール` セクション内のみ**（他セクションは参照扱い）
 
+### Contract 参照の書き方
+
+- `QFAI-CONTRACT-REF:` 行で契約IDを宣言する（複数行可）
+- 参照不要な場合は `QFAI-CONTRACT-REF: none`
+
 ## Delta（delta.md）
 
 - 互換維持 / 仕様変更の **どちらか1つ**に必ずチェックする
@@ -44,8 +51,8 @@
 
 ## CI でチェックされること（抜粋）
 
-- Spec: 必須セクション、SPEC/BR ID、BR Priority、ID 形式、Contract 参照の実在性
+- Spec: 必須セクション、SPEC/BR ID、BR Priority、ID 形式、Contract 参照の実在性、Contract 参照の必須宣言
 - Delta: 変更区分（互換/変更）のチェック状態
 - Scenario: Feature/Scenario の存在、タグ要件、Given/When/Then
-- Traceability: BR→SC、SC→契約（UI/API/DATA）、SC→Test の接続、BR の所属 SPEC 整合
+- Traceability: BR→SC、Spec→Contract、SC→Test の接続、BR の所属 SPEC 整合
 - IDs: 定義 ID の重複検知（Spec/Scenario/Contracts）

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

@@ -1,5 +1,7 @@
 # SPEC-0001: 注文登録の最小仕様（サンプル）
 
+QFAI-CONTRACT-REF: API-0001, UI-0001, DB-0001
+
 > このテンプレは **最小例** です。実際の仕様に合わせて書き換えてください。
 
 ## 背景

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

@@ -19,8 +19,13 @@ validation:
       - 業務ルール
   traceability:
     brMustHaveSc: true
-    scMustTouchContracts: true
     scMustHaveTest: true
+    testFileGlobs:
+      - tests/**/*.test.ts
+      - tests/**/*.spec.ts
+      - src/**/*.test.ts
+      - src/**/*.spec.ts
+    testFileExcludeGlobs: []
     scNoTestSeverity: error
     allowOrphanContracts: false
     unknownContractIdSeverity: error

package/assets/init/root/tests/qfai-traceability.sample.test.ts

@@ -1,2 +1,2 @@
-// Traceability sample: reference SC IDs in tests (comments are enough).
-// SC-0001
+// Traceability sample: reference SC IDs via annotations (comments are enough).
+// QFAI:SC-0001