qfai 0.8.1 → 0.9.0

package/README.md

@@ -12,6 +12,7 @@
 - [Quick Start](#quick-start最短成功)
 - [機能](#できること)
 - [CLI リファレンス](#使い方cli)
+- [analyze（意味矛盾のレビュー補助）](#analyze意味矛盾のレビュー補助)
 - [設定](#設定)
 - [契約](#契約contracts)
 - [Monorepo 対応](#monorepo--サブディレクトリ)
@@ -48,7 +49,7 @@ npx qfai report
 
 ## できること
 
-- `npx qfai init` によるテンプレート生成（specs/contracts に加え、`.qfai/require/README.md`、`.qfai/rules/pnpm.md`、`.qfai/prompts/**`、`.qfai/prompts.local/README.md`、`.qfai/promptpack/` を含む）
+- `npx qfai init` によるテンプレート生成（specs/contracts に加え、`.qfai/require/README.md`、`.qfai/rules/pnpm.md`、`.qfai/prompts/**`、`.qfai/prompts.local/README.md`、`.qfai/prompts/analyze/**`、`.qfai/samples/**`、`.qfai/promptpack/` を含む）
 - `npx qfai validate` による `.qfai/` 内ドキュメントの整合性・トレーサビリティ検査
 - `npx qfai validate` による SC→Test 参照の検証（`validation.traceability.testFileGlobs` に一致するテストファイルから `QFAI:SC-xxxx` を抽出）
 - `npx qfai doctor` による設定/探索/パス/glob/validate.json の事前診断
@@ -107,7 +108,33 @@ doctor の JSON も非契約（内部形式。将来予告なく変更あり）
 }
 ```
 
-`init --yes` は予約フラグです（現行の init は非対話のため挙動差はありません）。既存ファイルがある場合は `--force` が必要です。
+`init --yes` は予約フラグです（現行の init は非対話のため挙動差はありません）。
+
+- `--force` は `.qfai/prompts/**` のみ上書きします（それ以外は既存があればスキップします）
+- `specs/` `contracts/` は初回にサンプルが生成されますが、再実行（force の有無に関わらず）で上書きしません
+- それ以外を再生成したい場合は、対象を手動で削除してから `qfai init` を実行してください（運用中成果物の破壊を避けるため）
+
+## analyze（意味矛盾のレビュー補助）
+
+`validate` は deterministic な構造矛盾（参照/フォーマット/トレーサビリティ）を検査し、CI Hard Gate にできます。一方で、**意味矛盾（解釈/前提/用語/例外/受入条件の齟齬）**は deterministic に検出できないため、v0.9 では **手動プロンプト**として導線を提供します。
+
+重要:
+
+- analyze は **Hard Gate ではありません**（CI を落とさない想定）
+- 出力は **候補**です。根拠（引用）を確認し、最終判断はレビューで行ってください
+
+### 使い方（最短）
+
+1. `.qfai/prompts/analyze/**` から目的に合うプロンプトを選ぶ
+2. 推奨入力（Spec/Scenario/validate結果/差分）を揃えて、AI に貼り付ける
+3. 結果をレビューし、必要な修正や議論に落とす
+
+成果物を残す場合は、`npx qfai init` が同梱する `.qfai/samples/analyze/analysis.md`（テンプレ）を使う運用を推奨します。
+
+### カスタマイズ（Overlay）
+
+analyze も `.qfai/prompts.local/**` の overlay 運用に従います。
+同じ相対パスのファイルがある場合は `.qfai/prompts.local` を優先して参照してください。
 
 ## 設定
 

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

@@ -26,6 +26,7 @@ npx qfai report
 - `require/` : 既存要件の集約（validate 対象外）
 - `rules/` : 規約・運用ルール
 - `prompts/` : QFAI 標準のプロンプト資産（自動読取はしない。更新や再 init で上書きされ得る）
+- `samples/` : analyze 等の手動運用で使う成果物テンプレ（create-only）
 - `prompts.local/` : 利用者カスタムのプロンプト資産（存在する場合は overlay でこちらを優先して読む運用）
 - `promptpack/` : PromptPack（SSOT、運用ルール/観点の正本）
 - `out/` : `validate` / `report` の出力先（gitignore 推奨）
@@ -38,12 +39,17 @@ npx qfai report
 - `rules/conventions.md`
 - `rules/pnpm.md`
 - `prompts/README.md`
+- `prompts/analyze/README.md`
 - `prompts.local/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`
+- `prompts/analyze/spec_scenario_consistency.md`
+- `prompts/analyze/spec_contract_consistency.md`
+- `prompts/analyze/scenario_test_consistency.md`
+- `samples/analyze/analysis.md`
 - `promptpack/constitution.md`
 - `out/README.md`
 
@@ -63,7 +69,8 @@ v0.7 以降、プロンプト資産のカスタマイズは `.qfai/prompts.local
 - 利用者が `.qfai/prompts/**` を直接編集することは非推奨・非サポートです
 - 変更したい場合は同一相対パスで `.qfai/prompts.local/**` に置いて上書きしてください
 - `qfai init` は `.qfai/prompts.local/**` を **保護**します（`--force` でも上書きしません）
-- 現時点の保護対象は `prompts.local` のみです（それ以外は上書きされ得ます）
+- `qfai init` は `root/` と `.qfai/` を create-only（既存があればスキップ）で運用します
+- `--force` は `.qfai/prompts/**` のみ上書きします（`specs/` `contracts/` を含め、その他は上書きしません）
 
 例:
 

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

@@ -9,7 +9,8 @@
 
 - Spec から overview / Business Flow を生成するための素材
 - トレーサビリティ/契約/変更区分の運用支援（CIで止めない領域）
-- 将来（v0.9）の adapter/emit 実装に備えた配布物
+- 意味矛盾（解釈/前提/用語/受入条件の齟齬）のレビュー補助（analyze）
+- 将来の CLI 連携に備えた配布物（現時点では手動利用のみ）
 
 ## Overlay（prompts.local）
 
@@ -27,6 +28,10 @@
 - `qfai-maintain-traceability.md`: 参照切れの修復（Spec/Scenario/Test）
 - `qfai-maintain-contracts.md`: 契約 ID と参照の整合
 - `qfai-classify-change.md`: Compatibility / Change 分類支援
+- `analyze/README.md`: analyze の目的/入力/出力フォーマット
+- `analyze/spec_scenario_consistency.md`: Spec ↔ Scenario の意味整合
+- `analyze/spec_contract_consistency.md`: Spec ↔ Contract の意味整合
+- `analyze/scenario_test_consistency.md`: Scenario ↔ Test（SC参照）の表現妥当性
 
 ## 使い分け表
 

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

@@ -0,0 +1,38 @@
+# analyze（手動利用）
+
+このディレクトリは QFAI の `validate` が扱わない **意味矛盾（レベル1/2）** を、レビューのために洗い出すための **手動プロンプト集**です。
+
+重要:
+
+- analyze は **Hard Gate ではありません**（CI を落とさない想定）
+- 出力は **候補**です。根拠（引用）を必ず確認し、最終判断はレビューで行ってください
+- `validate` が扱う **構造矛盾（参照/フォーマット/トレーサビリティ）** は対象外です
+
+## 推奨入力（最小セット）
+
+- 対象 Spec Pack:
+  - `.qfai/specs/<spec-id>/spec.md`
+  - `.qfai/specs/<spec-id>/delta.md`
+  - `.qfai/specs/<spec-id>/scenario.md`
+- `validate` の結果:
+  - `.qfai/out/report.md`（または `.qfai/out/validate.json` の要約）
+- 変更差分:
+  - PR diff（または変更ファイル一覧）
+
+入力が不足すると見落としが増え、入力が多すぎると回答が拡散しやすくなります。まずは上記のセットに揃える運用を推奨します。
+
+## 推奨出力フォーマット
+
+各指摘を「レビューで決めるべき論点」として、次の項目を固定して出してください。
+
+- 種別: `Contradiction` / `Ambiguity` / `Missing Case` / `Risk` / `Suggestion`
+- 影響範囲: `Spec` / `Scenario` / `Contract` / `Test` / `Docs`
+- 根拠: 入力の該当箇所を短く引用
+- 判断理由: なぜ矛盾/曖昧に見えるか
+- 推奨アクション: 次に何を直す/議論するか（CIを止める結論は出さない）
+
+## プロンプト一覧
+
+- `spec_scenario_consistency.md`: Spec ↔ Scenario の意味整合
+- `spec_contract_consistency.md`: Spec ↔ Contract の意味整合
+- `scenario_test_consistency.md`: Scenario ↔ Test（SC参照）の表現妥当性

package/assets/init/.qfai/prompts/analyze/scenario_test_consistency.md

@@ -0,0 +1,35 @@
+# analyze: Scenario ↔ Test consistency
+
+あなたは QFAI 運用におけるレビュー補助者です。
+目的は Scenario の意図と、テスト（主に SC 参照）で表現している内容の **妥当性**（抜け/重複/過剰な固定）を候補として列挙することです。
+
+重要:
+
+- これは Hard Gate ではありません（CI を落とす結論は出さない）。
+- 出力は候補です。根拠（引用）を必ず添えてください。
+- `validate` が扱う構造矛盾（SC 参照の欠落/未知IDなど）は対象外です。
+
+## 入力
+
+- Scenario: <貼り付け>
+- テストコード抜粋（該当ファイル）: <貼り付け>
+- validate/report 要約: <貼り付け>
+- 変更差分（任意）: <貼り付け>
+
+## 出力（厳守）
+
+以下の形式で、見つかった分だけ列挙してください。最大 12 件まで。
+
+- 種別: Contradiction | Ambiguity | Missing Case | Risk | Suggestion
+- 影響範囲: Spec | Scenario | Contract | Test | Docs
+- 根拠: "..."（短い引用を 1〜2 個）
+- 判断理由: なぜ抜け/重複/過剰固定に見えるか
+- 推奨アクション: 次に何を直す/議論するか
+
+## 観点
+
+- Scenario の受入条件に対してテストが不足している
+- テストが Scenario にない要件を固定してしまっている（過剰な固定）
+- 同じ意図のテストが重複している
+- 境界値/例外系/権限/並行性など、事故りやすい論点が抜けている
+- SC 参照はあるが、シナリオの主張を検証していない

package/assets/init/.qfai/prompts/analyze/spec_contract_consistency.md

@@ -0,0 +1,36 @@
+# analyze: Spec ↔ Contract consistency
+
+あなたは QFAI 運用におけるレビュー補助者です。
+目的は Spec と Contract の **意味整合**（期待する入出力/副作用/用語/エラーの扱い）を確認し、ズレを候補として列挙することです。
+
+重要:
+
+- これは Hard Gate ではありません（CI を落とす結論は出さない）。
+- 出力は候補です。根拠（引用）を必ず添えてください。
+- `validate` が扱う構造矛盾（ID/参照/フォーマット）は対象外です。
+
+## 入力
+
+- Spec: <貼り付け>
+- Contract: <貼り付け>
+- validate/report 要約: <貼り付け>
+- 変更差分（任意）: <貼り付け>
+
+## 出力（厳守）
+
+以下の形式で、見つかった分だけ列挙してください。最大 12 件まで。
+
+- 種別: Contradiction | Ambiguity | Missing Case | Risk | Suggestion
+- 影響範囲: Spec | Scenario | Contract | Test | Docs
+- 根拠: "..."（短い引用を 1〜2 個）
+- 判断理由: なぜ矛盾/曖昧に見えるか
+- 推奨アクション: 次に何を直す/議論するか
+
+## 観点
+
+- 用語/フィールド名/概念の不一致
+- Spec の期待（入力/出力/状態遷移）と Contract の定義の不一致
+- エラー/例外の扱い（HTTP status / error code / validation error の条件）
+- 非機能（性能/レート制限/タイムアウト/整合性）への言及のズレ
+- Contract が Spec の範囲を超えて規定している（過剰な固定）
+- Spec が Contract の重要条件を説明していない（根拠不足）

package/assets/init/.qfai/prompts/analyze/spec_scenario_consistency.md

@@ -0,0 +1,35 @@
+# analyze: Spec ↔ Scenario consistency
+
+あなたは QFAI 運用におけるレビュー補助者です。
+目的は `validate` が扱わない **意味矛盾**（用語/前提/例外/受入条件の齟齬）を、レビューで判断できる形で列挙することです。
+
+重要:
+
+- これは Hard Gate ではありません。CI を落とす結論は出さないでください。
+- 出力は候補です。根拠（引用）を必ず添えてください。
+- `validate` が扱う構造矛盾（参照/フォーマット/ID）は対象外です。
+
+## 入力
+
+- Spec: <貼り付け>
+- Scenario: <貼り付け>
+- validate/report 要約: <貼り付け>
+- 変更差分（任意）: <貼り付け>
+
+## 出力（厳守）
+
+以下の形式で、見つかった分だけ列挙してください。最大 12 件まで。重大度の推定は不要です。
+
+- 種別: Contradiction | Ambiguity | Missing Case | Risk | Suggestion
+- 影響範囲: Spec | Scenario | Contract | Test | Docs
+- 根拠: "..."（短い引用を 1〜2 個）
+- 判断理由: なぜ矛盾/曖昧に見えるか
+- 推奨アクション: 次に何を直す/議論するか
+
+## 観点
+
+- 用語の不一致（同じ概念が別名、別概念が同名）
+- 前提条件/制約の不一致（Spec にあるが Scenario にない、または逆）
+- 例外系/エラー系の扱いの不一致
+- Acceptance Criteria の抜け/過剰/言い回しのズレ
+- Scenario の手順が Spec の要求を満たしていない/逆に余計な要求を足している

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

@@ -27,4 +27,5 @@ QFAI v0.7 以降は、プロンプト資産のカスタマイズ手段を **over
 ## init 再実行時の保護（契約）
 
 - `qfai init` は `.qfai/prompts.local/**` を **保護**します（`--force` を付けても上書きしません）。
-- 現時点でこの保護対象は `prompts.local` のみです。
+- `--force` は `.qfai/prompts/**` のみ上書きします。
+- `specs/` `contracts/` を含め、その他の領域は既存があればスキップします（上書きしません）。

package/assets/init/.qfai/samples/analyze/analysis.md

@@ -0,0 +1,38 @@
+# analyze 実施ログ（テンプレート）
+
+> 目的: analyze は `validate` が扱わない「意味矛盾」の候補を抽出するための **レビュー補助**です。
+> 結果は正解判定ではありません。根拠（引用）を確認し、レビューで判断してください。
+
+## メタ
+
+- 実施日: YYYY-MM-DD
+- 対象: <PR番号 / ブランチ / 変更スコープ>
+- 利用モデル/環境: <任意>
+
+## 入力（貼り付けたもの）
+
+- Spec: <spec.md / delta.md の該当範囲>
+- Scenario: <scenario.md の該当範囲>
+- Contract（任意）: <該当契約>
+- validate/report 要約: <report.md または validate.json の要約>
+- 差分: <PR diff / 変更ファイル一覧>
+
+## 実行したプロンプト
+
+- `.qfai/prompts/analyze/spec_scenario_consistency.md`
+- `.qfai/prompts/analyze/spec_contract_consistency.md`
+- `.qfai/prompts/analyze/scenario_test_consistency.md`
+
+## 結果（候補）
+
+- <貼り付け>
+
+## レビュー判断
+
+- 採用（修正する）: <項目>
+- 却下（問題なし/誤検知）: <項目>
+- 保留（追加調査/議論）: <項目>
+
+## 次アクション
+
+- <誰が/何を/いつまでに>

package/dist/cli/index.cjs

@@ -1015,8 +1015,8 @@ var import_promises7 = require("fs/promises");
 var import_node_path8 = __toESM(require("path"), 1);
 var import_node_url2 = require("url");
 async function resolveToolVersion() {
-  if ("0.8.1".length > 0) {
-    return "0.8.1";
+  if ("0.9.0".length > 0) {
+    return "0.9.0";
   }
   try {
     const packagePath = resolvePackageJsonPath();
@@ -1541,6 +1541,11 @@ async function runInit(options) {
   const qfaiAssets = import_node_path12.default.join(assetsRoot, ".qfai");
   const destRoot = import_node_path12.default.resolve(options.dir);
   const destQfai = import_node_path12.default.join(destRoot, ".qfai");
+  if (options.force) {
+    info(
+      "NOTE: --force \u306F .qfai/prompts/** \u306E\u307F\u4E0A\u66F8\u304D\u3057\u307E\u3059\uFF08prompts.local \u306F\u4FDD\u8B77\u3055\u308C\u3001specs/contracts \u7B49\u306F\u4E0A\u66F8\u304D\u3057\u307E\u305B\u3093\uFF09\u3002"
+    );
+  }
   const rootResult = await copyTemplateTree(rootAssets, destRoot, {
     force: false,
     dryRun: options.dryRun,
@@ -4432,7 +4437,7 @@ Commands:
 Options:
   --root <path>   \u5BFE\u8C61\u30C7\u30A3\u30EC\u30AF\u30C8\u30EA
   --dir <path>    init \u306E\u51FA\u529B\u5148
-  --force         \u65E2\u5B58\u30D5\u30A1\u30A4\u30EB\u3092\u4E0A\u66F8\u304D
+  --force         init: .qfai/prompts \u306E\u307F\u4E0A\u66F8\u304D\uFF08\u305D\u308C\u4EE5\u5916\u306F\u65E2\u5B58\u304C\u3042\u308C\u3070\u30B9\u30AD\u30C3\u30D7\uFF09
   --yes           init: \u4E88\u7D04\u30D5\u30E9\u30B0\uFF08\u73FE\u72B6\u306F\u975E\u5BFE\u8A71\u306E\u305F\u3081\u6319\u52D5\u5DEE\u306A\u3057\u3002\u5C06\u6765\u306E\u5BFE\u8A71\u5C0E\u5165\u6642\u306B\u81EA\u52D5Yes\uFF09
   --dry-run       \u5909\u66F4\u3092\u884C\u308F\u305A\u8868\u793A\u306E\u307F
   --format <text|github>       validate \u306E\u51FA\u529B\u5F62\u5F0F