qfai 0.4.9 → 0.5.2

package/README.md

@@ -18,7 +18,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 init` によるテンプレート生成（specs/contracts に加え、`.qfai/require/README.md`、`.qfai/rules/pnpm.md`、`.qfai/prompts/require-to-spec.md`、`.qfai/prompts/qfai-generate-test-globs.md`、`.qfai/prompts/qfai-maintain-traceability.md`、`.qfai/prompts/qfai-maintain-contracts.md`、`.qfai/prompts/qfai-classify-change.md`、`.qfai/promptpack/` を含む）
 - `npx qfai validate` による `.qfai/` 内ドキュメントの整合性・トレーサビリティ検査
 - `npx qfai validate` による SC→Test 参照の検証（`validation.traceability.testFileGlobs` に一致するテストファイルから `QFAI:SC-xxxx` を抽出）
 - `npx qfai report` によるレポート出力
@@ -35,19 +35,26 @@ npx qfai report
 ## Contracts
 
 Spec では `QFAI-CONTRACT-REF:` 行で参照する契約IDを宣言します（`none` 可、宣言行は必須）。
+Scenario では `# QFAI-CONTRACT-REF:` のコメント行で契約参照を宣言します（`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.orphanContractsPolicy`: Spec から参照されない契約の扱い（default: `error`、`error` / `warning` / `allow`）
 - `validation.traceability.unknownContractIdSeverity`: Scenario が参照した契約 ID が存在しない場合の severity（default: `error`、`error` / `warning` のみ）
-- Spec の `QFAI-CONTRACT-REF` が未知 ID を参照した場合は常に error（`QFAI-TRACE-021`）
+- Spec の `QFAI-CONTRACT-REF` が未知 ID を参照した場合は常に error（`QFAI-TRACE-024`）
 - `unknownContractIdSeverity` は Scenario 側（`QFAI-TRACE-008`）のみを制御
 
 `npx qfai init` は `.qfai/contracts/` 配下に UI/API/DB のサンプルを生成します。
 
+## CI と Hard Gate
+
+- 「CIで検出する」= `validate` が issue を出す（info/warning/error を含む）
+- 「Hard Gate」= `--fail-on error` で CI を停止する領域
+- Spec→下流参照禁止は Hard Gate にしない（検出する場合でも warning に留める）
+
 SC→Test の参照はテストコード内の `QFAI:SC-xxxx` アノテーションで宣言します。
 SC→Test の対象ファイルは `validation.traceability.testFileGlobs` で指定します。
 除外は `validation.traceability.testFileExcludeGlobs` で指定できます。

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

@@ -9,10 +9,14 @@ npx qfai validate --fail-on error --format github
 npx qfai report
 ```
 
+`validate.json` が無い場合は `npx qfai report --run-validate` を使うか、
+`--in <path>` で入力ファイルを指定してください。
+
 ## トレーサビリティ（SC→Test）
 
 - `validation.traceability.testFileGlobs` に一致するテストコードで `QFAI:SC-xxxx` を参照する（コメント可）
 - Spec→Contract は `spec.md` の `QFAI-CONTRACT-REF` 行で宣言する
+- Scenario→Contract は `scenario.md` の `# QFAI-CONTRACT-REF` で宣言する（none 可）
 
 ## ディレクトリ概要
 
@@ -34,6 +38,9 @@ npx qfai report
 - `prompts/README.md`
 - `prompts/require-to-spec.md`
 - `prompts/qfai-generate-test-globs.md`
+- `prompts/qfai-maintain-traceability.md`
+- `prompts/qfai-maintain-contracts.md`
+- `prompts/qfai-classify-change.md`
 - `promptpack/constitution.md`
 - `out/README.md`
 
@@ -41,6 +48,7 @@ npx qfai report
 
 - 設定ファイル: `qfai.config.yaml`（リポジトリ直下）
 - CI テンプレ: `.github/workflows/qfai.yml`
+- monorepo では `paths.outDir` をパッケージ単位に分けて衝突を避ける
 
 ## Prompts の使い方（重要）
 
@@ -60,3 +68,4 @@ npx qfai report
 
 - 入口: `promptpack/constitution.md`
 - 手動配置の例: Copilot/Claude/Codex 向けの指示ファイル
+- PromptPack は非契約です（互換保証なし）。編集する場合はラップ運用や差分管理を推奨します。

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

@@ -1,6 +1,6 @@
 # Contracts (UI / API / DB)
 
-契約は「システム外部との約束」を明文化する場所です。Spec（spec.md）の `QFAI-CONTRACT-REF` による参照が必須で、これが Spec→Contract 対応の SSOT になります。Scenario からの参照は任意です。
+契約は「システム外部との約束」を明文化する場所です。Spec（spec.md）の `QFAI-CONTRACT-REF` による参照が必須で、これが Spec→Contract 対応の SSOT になります。Scenario は `# QFAI-CONTRACT-REF` で契約参照を宣言します（none 可）。
 
 ## 置くべきファイル
 
@@ -63,7 +63,7 @@ CREATE TABLE sample_table (
 ## 依存関係
 
 - Spec → Contracts（spec.md に `QFAI-CONTRACT-REF` を必ず1行以上宣言、0件は `none`。この行が SSOT）
-- Scenario → Contracts（UI/API/DB の参照は任意。付けるなら関連が強い箇所に限定）
+- Scenario → Contracts（scenario.md に `# QFAI-CONTRACT-REF` を必ず1行以上宣言、0件は `none`）
 
 ## 良い例 / 悪い例
 

package/assets/init/.qfai/promptpack/commands/implement.md

@@ -4,3 +4,5 @@
 - 入力検証と失敗パスを先に書く
 - 早期 return でネストを浅くする
 - ログ/エラーメッセージは具体的かつ最小限にする
+- 契約追加/変更時は `prompts/qfai-maintain-contracts.md` を使う
+- 参照切れがある場合は `prompts/qfai-maintain-traceability.md` を使う

package/assets/init/.qfai/promptpack/commands/plan.md

@@ -7,3 +7,5 @@
 - 手順（小さく分割）
 - テスト方針
 - リスクと確認点
+- testFileGlobs が未整備なら `prompts/qfai-generate-test-globs.md` を使う
+- Compatibility/Change が不明なら `prompts/qfai-classify-change.md` で整理する

package/assets/init/.qfai/promptpack/commands/review.md

@@ -2,5 +2,6 @@
 
 - Spec/Scenario/Contracts と実装の整合
 - 互換維持/変更の区分が delta.md に記録されているか
+- 区分が曖昧なら `prompts/qfai-classify-change.md` で再整理する
 - 影響範囲とテスト結果の妥当性
 - セキュリティ/運用上の懸念がないか

package/assets/init/.qfai/promptpack/steering/traceability.md

@@ -2,8 +2,14 @@
 
 参照は下流→上流のみを許可する（下流参照禁止の対象はテスト/実装）。
 
+## 用語（CI と Hard Gate）
+
+- 「CIで検出する」: validate が issue を出す（info/warning/error を含む）
+- 「Hard Gate」: `--fail-on error` で CI を止める領域
+
 - Spec は QFAI-CONTRACT-REF で契約IDを宣言する（none可、宣言行は必須）
-- Scenario は @SPEC-xxxx / @SC-xxxx / @BR-xxxx を持つ（契約ID参照は任意）
+- Scenario は @SPEC-xxxx / @SC-xxxx / @BR-xxxx を持つ
+- Scenario は `# QFAI-CONTRACT-REF` で契約参照を宣言する（none 可、宣言行は必須）
 - テスト/コードは QFAI:SC-xxxx で SC を参照する
 - Spec はテスト/実装（src/tests）を参照しない
 
@@ -16,4 +22,4 @@
 
 ## CIで検出しないため運用で担保する範囲
 
-- Spec→下流参照禁止（Spec がテスト/実装を参照しないこと）
+- Spec→下流参照禁止（検出する場合でも warning に留め、Hard Gate 化しない）

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

@@ -5,6 +5,7 @@
 ## 目的
 
 - Spec から overview / Business Flow を生成するための素材
+- トレーサビリティ/契約/変更区分の運用支援（CIで止めない領域）
 - 将来（v0.9）の adapter/emit 実装に備えた配布物
 
 ## プロンプト一覧
@@ -13,6 +14,21 @@
 - `makeBusinessFlow.md`: 業務フロー（BF）整理
 - `require-to-spec.md`: 既存要件から Spec Pack を起こす
 - `qfai-generate-test-globs.md`: テストファイル glob の生成支援（`qfai.config.yaml` 更新）
+- `qfai-maintain-traceability.md`: 参照切れの修復（Spec/Scenario/Test）
+- `qfai-maintain-contracts.md`: 契約 ID と参照の整合
+- `qfai-classify-change.md`: Compatibility / Change 分類支援
+
+## 使い分け表
+
+| Prompt                          | 目的             | 必須入力                                      | 出力の期待形式                 | よくある失敗        |
+| ------------------------------- | ---------------- | --------------------------------------------- | ------------------------------ | ------------------- |
+| `qfai-maintain-traceability.md` | 参照切れの修復   | spec/delta/scenario + validate/report + tests | 修正方針 + diff + 再実行手順   | ID形式崩し/SSOT無視 |
+| `qfai-maintain-contracts.md`    | 契約と参照の整合 | contracts + spec + report                     | 採番案 + 参照更新案 + diff     | ID変更の無断実施    |
+| `qfai-classify-change.md`       | 変更区分の判断   | delta.md + 変更差分                           | 分類 + 根拠 + 影響範囲         | 根拠なし分類        |
+| `qfai-generate-test-globs.md`   | テストglob生成   | package.json/設定/テスト配置                  | glob案 + 更新案 + サンプル確認 | glob過剰/不足       |
+| `makeOverview.md`               | Spec一覧生成     | spec.md                                       | 一覧テーブル/サマリ            | spec未読            |
+| `makeBusinessFlow.md`           | 業務フロー整理   | spec.md/要件                                  | フロー手順/根拠                | 要件の飛ばし        |
+| `require-to-spec.md`            | 要件からSpec作成 | require資料                                   | Spec Pack草案                  | ID採番の逸脱        |
 
 ## 使い方（例）
 

package/assets/init/.qfai/prompts/qfai-classify-change.md

@@ -0,0 +1,33 @@
+# QFAI: Compatibility / Change 分類（変更区分の判断支援）
+
+あなたは差分を分析し、変更が Compatibility か Change かを分類します。
+
+## 目的
+
+- delta.md の変更区分を明確にし、レビューポイントを固定する
+- 影響範囲（Spec/Scenario/Test/Contract）を明示する
+
+## 必須入力
+
+- `.qfai/specs/**/delta.md`
+- 変更差分（`git diff`）
+- 参照元の Spec/Scenario/Contracts（必要に応じて）
+
+## 手順
+
+1. 差分を読み、ユーザー影響（互換維持/破壊）を分類する。
+2. 影響範囲（Spec/Scenario/Test/Contract）を列挙する。
+3. 変更区分の根拠を簡潔にまとめる。
+4. 必要なドキュメント更新（README/CHANGELOG/Spec）を列挙する。
+
+## 禁止事項
+
+- 仕様を勝手に変更しない
+- delta.md の内容を無断で上書きしない
+- 変更理由の捏造をしない
+
+## 出力フォーマット
+
+- 分類（Compatibility / Change）と根拠
+- 影響範囲（ファイル/機能/テスト）
+- 追記すべきドキュメントのチェックリスト

package/assets/init/.qfai/prompts/qfai-maintain-contracts.md

@@ -0,0 +1,35 @@
+# QFAI: 契約保守（Contract ID と Spec 参照の整合）
+
+あなたは契約ファイルの追加/変更に合わせて、ID と参照の整合を保ちます。
+
+## 目的
+
+- `QFAI-CONTRACT-ID` と `QFAI-CONTRACT-REF` の整合を保つ
+- orphan contract を発生させずに運用できるようにする
+
+## 必須入力
+
+- `.qfai/contracts/**`（追加/変更した契約）
+- 関連する `spec.md`（候補は report の Spec→契約一覧）
+- `.qfai/out/report.md` / `.qfai/out/validate.json`（あれば）
+
+## 手順
+
+1. 追加/変更した契約の種別（UI/API/DB）と命名規約を確認する。
+2. `QFAI-CONTRACT-ID` の採番案を作り、ファイル名と一致させる。
+3. 参照すべき Spec を特定し、`QFAI-CONTRACT-REF` へ追記案を作る。
+4. orphan contract が出る場合は、Spec 追加/更新の方針を提示する。
+5. 変更後の validate / report 手順を示す。
+
+## 禁止事項
+
+- 既存の Contract ID を無断で変更しない
+- ID 形式（`UI|API|DB-0001`）を崩さない
+- orphanContractsPolicy の変更を無断で行わない
+
+## 出力フォーマット
+
+- 追加/変更する Contract ID と根拠
+- 参照を追加する Spec 一覧と編集案
+- 提案 diff（またはパッチ単位）
+- 再実行コマンド（`qfai validate` / `qfai report`）

package/assets/init/.qfai/prompts/qfai-maintain-traceability.md

@@ -0,0 +1,36 @@
+# QFAI: トレーサビリティ保守（Spec/Scenario/Test の参照整合）
+
+あなたは QFAI の成果物を分析し、壊れた参照（Spec/Scenario/Test）を修復します。
+
+## 目的
+
+- Spec/Scenario/Test の ID 参照が壊れた箇所を特定し、整合させる
+- 互換維持/変更（Compatibility/Change）の区分を明確にする
+
+## 必須入力
+
+- `.qfai/specs/**/spec.md` / `scenario.md` / `delta.md`
+- `.qfai/out/validate.json`（あれば）
+- `.qfai/out/report.md`（あれば）
+- テストコード（`validation.traceability.testFileGlobs` に一致する範囲）
+
+## 手順
+
+1. validate/report の結果から、壊れている参照（Spec/BR/SC/Contract/Test）を列挙する。
+2. Spec Pack（spec/delta/scenario）を読み、ID と参照の意図を把握する。
+3. 修正が Compatibility か Change かを判断し、根拠を整理する。
+4. 参照切れを解消する最小修正案（Spec/Scenario/Test）を作る。
+5. 変更後の validate / report 手順を示す。
+
+## 禁止事項
+
+- 仕様の勝手な拡張や要件追加をしない
+- ID 形式（`PREFIX-0001`）を崩さない
+- 参照の SSOT を変更しない（Spec→Contract は Spec の `QFAI-CONTRACT-REF` が正）
+
+## 出力フォーマット
+
+- 変更区分（Compatibility / Change）と根拠
+- 修正対象一覧（ファイル/ID/理由）
+- 提案 diff（またはパッチ単位）
+- 再実行コマンド（`qfai validate` / `qfai report` / テスト）

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

@@ -45,6 +45,8 @@ QFAI-CONTRACT-REF: UI-0001, API-0001, DB-0001
 ## Scenario（scenario.md）最小要件
 
 - **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つ以上**必要
@@ -53,6 +55,6 @@ QFAI-CONTRACT-REF: UI-0001, API-0001, DB-0001
 
 - Spec: 必須セクション、SPEC/BR ID、BR Priority、ID 形式、Contract 参照の実在性、Contract 参照の必須宣言
 - Delta: 変更区分（互換/変更）のチェック状態
-- Scenario: Feature/Scenario の存在、タグ要件、Given/When/Then
+- Scenario: Feature/Scenario の存在、タグ要件、Given/When/Then、契約参照の宣言/形式
 - Traceability: BR→SC、Spec→Contract、SC→Test の接続、BR の所属 SPEC 整合
 - IDs: 定義 ID の重複検知（Spec/Scenario/Contracts）

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

@@ -3,7 +3,8 @@ Feature: 注文登録
 
 Rule: 承認者が存在する
 
-    @SC-0001 @BR-0001 @UI-0001 @API-0001 @DB-0001
+    # QFAI-CONTRACT-REF: UI-0001, API-0001, DB-0001
+    @SC-0001 @BR-0001
     Scenario: 承認者が承認するまで注文は確定しない
       Given ...
       When ...

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

@@ -27,7 +27,7 @@ validation:
       - src/**/*.spec.ts
     testFileExcludeGlobs: []
     scNoTestSeverity: error
-    allowOrphanContracts: false
+    orphanContractsPolicy: error
     unknownContractIdSeverity: error
 output:
   validateJsonPath: .qfai/out/validate.json