qfai 0.8.1 → 0.9.2

package/README.md

@@ -12,6 +12,7 @@
 - [Quick Start](#quick-start最短成功)
 - [機能](#できること)
 - [CLI リファレンス](#使い方cli)
+- [analyze（意味矛盾のレビュー補助）](#analyze意味矛盾のレビュー補助)
 - [設定](#設定)
 - [契約](#契約contracts)
 - [Monorepo 対応](#monorepo--サブディレクトリ)
@@ -23,7 +24,7 @@
 ## インストール
 
 ```sh
-npm install qfai
+npm install -D qfai
 ```
 
 または
@@ -32,6 +33,12 @@ npm install qfai
 npx qfai init
 ```
 
+pnpm の場合（推奨）:
+
+```sh
+pnpm add -D qfai
+```
+
 **必要環境**: Node.js >= 18
 
 ## パッケージ
@@ -42,13 +49,14 @@ npx qfai init
 
 ```sh
 npx qfai init
+npx qfai doctor --fail-on error
 npx qfai validate --fail-on error --format github
 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,12 +115,41 @@ 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. `npx qfai analyze --list` でプロンプト一覧を確認する
+2. `npx qfai analyze --prompt spec_to_scenario` のようにプロンプトを出力し、AI に貼り付ける
+3. 推奨入力（Spec/Scenario/Test/Contract の抜粋 + validate/report 要約 + 差分）を揃えて検討する
+
+入力の用意に迷う場合は、`npx qfai init` が同梱する `.qfai/samples/analyze/input_bundle.md`（完成例）をコピーして編集してください。
+成果物を残す場合は `.qfai/samples/analyze/analysis.md`（テンプレ）を使う運用を推奨します。
+
+### カスタマイズ（Overlay）
+
+analyze も `.qfai/prompts.local/**` の overlay 運用に従います。
+同じ相対パスのファイルがある場合は `.qfai/prompts.local` を優先して参照してください。
+
+例: `.qfai/prompts.local/analyze/` に `spec_to_scenario.md` を置くと標準を上書きできます。
 
 ## 設定
 
 設定はリポジトリ直下の `qfai.config.yaml` で行います。
-命名規約は `docs/rules/naming.md` を参照してください。
+命名規約は GitHub の[命名規約ドキュメント](https://github.com/aganesy/QFAI/blob/main/docs/rules/naming.md)を参照してください。
 
 ## 契約（Contracts）
 
@@ -183,7 +220,9 @@ jobs:
           path: .qfai/out/report.md
 ```
 
-validate.json のスキーマと例は `docs/schema` / `docs/examples` を参照してください。
+validate.json のスキーマと例は GitHub の
+[schema](https://github.com/aganesy/QFAI/tree/main/docs/schema) /
+[examples](https://github.com/aganesy/QFAI/tree/main/docs/examples) を参照してください。
 PromptPack は非契約（互換保証なし）です。編集する場合はラップ運用を推奨します。
 
 ## 生成される構成（例）

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,18 @@ 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`
+- `samples/analyze/analysis.md`
+- `samples/analyze/input_bundle.md`
+- `prompts/analyze/spec_to_scenario.md`
+- `prompts/analyze/spec_to_contract.md`
+- `prompts/analyze/scenario_to_test.md`
 - `promptpack/constitution.md`
 - `out/README.md`
 
@@ -63,7 +70,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_to_scenario.md`: Spec ↔ Scenario の意味整合
+- `analyze/spec_to_contract.md`: Spec ↔ Contract の対応漏れ/参照不整合
+- `analyze/scenario_to_test.md`: Scenario ↔ Test の網羅/抜け/誤差
 
 ## 使い分け表
 

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

@@ -0,0 +1,21 @@
+# analyze（手動利用）
+
+このディレクトリは QFAI の `validate` が扱わない **意味レベル** の矛盾/抜け/リスクを、レビューのために洗い出すための **手動プロンプト集**です。
+
+重要:
+
+- analyze は **Hard Gate ではありません**（CI を落とさない想定）
+- 出力は **候補**です。根拠（引用）を必ず確認し、最終判断はレビューで行ってください
+- `validate` が扱う **構造矛盾（参照/フォーマット/トレーサビリティ）** は対象外です
+
+## 推奨入力（最小セット）
+
+- Project Context / Spec / Scenario / Test / Contract のうち、今回関係する箇所を **抜粋**で用意する
+- `validate` / `report` の結果（必要なら要約）
+- 変更差分（PR diff / 変更ファイル一覧）
+
+## プロンプト一覧（v0.9.x）
+
+- `spec_to_scenario.md`: Spec ↔ Scenario の意味整合
+- `spec_to_contract.md`: Spec ↔ Contract の参照整合（紐付け漏れ/根拠薄弱）
+- `scenario_to_test.md`: Scenario ↔ Test の網羅性/ズレ

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

@@ -0,0 +1,8 @@
+# Deprecated
+
+このプロンプトは v0.9.1 で命名/雛形を整理しました。
+
+- 代替: `.qfai/prompts/analyze/scenario_to_test.md`
+- 理由: v0.9.1 の `qfai analyze --list` / `--prompt` が標準3本（spec_to_scenario/spec_to_contract/scenario_to_test）に揃えているため
+
+以降は新しいプロンプトを利用してください。

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

@@ -0,0 +1,56 @@
+# analyze: Scenario ↔ Test 網羅性/ズレチェック
+
+## 目的
+
+- Scenario（受入条件）が Test で担保されているかを確認する
+- Test が Scenario の意図を誤解していないかを確認する
+
+## 入力の前提（貼り付けて埋める）
+
+入力が多すぎる場合は「抜粋にする」「代表ケースだけに絞る」を優先してください。
+
+### Project Context（任意）
+
+- 対象機能:
+- 前提/制約:
+- 対象外（Non-goals）:
+
+### Scenario Excerpts
+
+- ...
+
+### Test Excerpts
+
+- ...
+
+### Spec Excerpts（任意）
+
+- ...
+
+### Contract / Trace Links（任意）
+
+- （Scenario ID）→（Test名/ファイル など）
+- ...
+
+### Open Concerns（任意）
+
+- ...
+
+## チェック観点
+
+- シナリオの各条件がテストに対応しているか（対応表を作る）
+- 例外系・境界条件がテストされているか
+- テスト名/説明がシナリオ用語と一致しているか
+- テストが多すぎる/少なすぎることによるリスク
+
+## 期待する出力形式
+
+- 対応表（Scenario項目 → Test名/箇所）
+- 漏れ（未テスト）とズレ（誤解）のリスト
+- 優先度（高/中/低）を付ける
+
+## 次アクション
+
+- Test追加/修正案:
+- Scenario追加/修正案:
+- 追加で確認すべき質問:

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

@@ -0,0 +1,8 @@
+# Deprecated
+
+このプロンプトは v0.9.1 で命名/雛形を整理しました。
+
+- 代替: `.qfai/prompts/analyze/spec_to_contract.md`
+- 理由: v0.9.1 の `qfai analyze --list` / `--prompt` が標準3本（spec_to_scenario/spec_to_contract/scenario_to_test）に揃えているため
+
+以降は新しいプロンプトを利用してください。

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

@@ -0,0 +1,8 @@
+# Deprecated
+
+このプロンプトは v0.9.1 で命名/雛形を整理しました。
+
+- 代替: `.qfai/prompts/analyze/spec_to_scenario.md`
+- 理由: v0.9.1 の `qfai analyze --list` / `--prompt` が標準3本（spec_to_scenario/spec_to_contract/scenario_to_test）に揃えているため
+
+以降は新しいプロンプトを利用してください。

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

@@ -0,0 +1,54 @@
+# analyze: Spec ↔ Contract トレーサビリティチェック
+
+## 目的
+
+- Spec と Contract（参照関係）が噛み合っているかを確認する
+- 紐付け漏れ・参照の根拠薄弱を抽出する
+
+## 入力の前提（貼り付けて埋める）
+
+入力が多すぎる場合は「抜粋にする」「代表ケースだけに絞る」を優先してください。
+
+### Project Context
+
+- 対象機能:
+- 前提/制約:
+- 対象外（Non-goals）:
+
+### Spec Excerpts
+
+- ...
+
+### Contract / Trace Links
+
+- （Spec ID）→（Scenario ID / Test ID など）
+- ...
+
+### Scenario Excerpts（任意）
+
+- ...
+
+### Test Excerpts（任意）
+
+- ...
+
+### Open Concerns（任意）
+
+- ...
+
+## チェック観点
+
+- Spec に対してリンクが存在しない箇所（紐付け漏れ）
+- Contract で参照しているが、Spec 側に根拠が見当たらない箇所
+- 参照の向きが不自然な箇所（誤ったID、転記ミスの疑い）
+
+## 期待する出力形式
+
+- 「紐付け漏れ」「根拠薄弱」「参照ミス疑い」に分類
+- それぞれに修正案（Contract修正 / Spec補強 / Scenario追加）を付ける
+
+## 次アクション
+
+- Contract修正案:
+- Spec補強案:
+- 追加で確認すべき質問:

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

@@ -0,0 +1,56 @@
+# analyze: Spec ↔ Scenario 整合性チェック
+
+## 目的
+
+- Spec（仕様）の主張が Scenario（受入シナリオ）に反映されているかを確認する
+- Scenario が Spec を逸脱していないかを確認する
+
+## 入力の前提（貼り付けて埋める）
+
+入力が多すぎる場合は「抜粋にする」「代表ケースだけに絞る」を優先してください。
+
+### Project Context
+
+- 対象機能:
+- 前提/制約:
+- 対象外（Non-goals）:
+
+### Spec Excerpts
+
+- ...
+
+### Scenario Excerpts
+
+- ...
+
+### Test Excerpts（任意）
+
+- ...
+
+### Contract / Trace Links（任意）
+
+- （Spec ID）→（Scenario ID / Test ID など）
+- ...
+
+### Open Concerns（任意）
+
+- ...
+
+## チェック観点
+
+- 用語定義の不一致（同じ言葉で別の意味）
+- 例外条件/境界条件の不足
+- 受入条件（Given/When/Then 等）が仕様の制約を満たすか
+- 仕様にあるのにシナリオがない項目（漏れ）
+- シナリオにあるのに仕様に根拠がない項目（逸脱）
+
+## 期待する出力形式
+
+- 矛盾 / 不明点 / 漏れ をそれぞれ箇条書き
+- それぞれに「根拠（Spec/Scenario抜粋の引用）」と「提案（修正案）」を付ける
+
+## 次アクション
+
+- Spec修正案:
+- Scenario追加/修正案:
+- 追加で確認すべき質問:

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_to_scenario.md`
+- `.qfai/prompts/analyze/spec_to_contract.md`
+- `.qfai/prompts/analyze/scenario_to_test.md`
+
+## 結果（候補）
+
+- <貼り付け>
+
+## レビュー判断
+
+- 採用（修正する）: <項目>
+- 却下（問題なし/誤検知）: <項目>
+- 保留（追加調査/議論）: <項目>
+
+## 次アクション
+
+- <誰が/何を/いつまでに>

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

@@ -0,0 +1,54 @@
+# analyze 入力バンドル（サンプル）
+
+> 目的: `analyze` 用の入力をブレなく用意するための完成例です。
+> 本ファイルは架空の小規模機能を題材にしています。自プロジェクトではコピーして編集してください。
+
+## Project Context
+
+- 対象機能: パスワードリセット（メールでワンタイムリンクを送る）
+- 前提/制約:
+  - リンクは 15 分で失効
+  - 送信頻度制限（IP + アカウント単位）
+  - 失効後は再送が必要
+- 対象外（Non-goals）:
+  - 多要素認証
+  - 端末認証
+
+## Spec Excerpts
+
+- ユーザーがメールアドレスを入力すると、登録済みならリセットリンクを送る
+- 未登録メールでも挙動は同じに見せる（ユーザー列挙防止）
+- リンクは 15 分で失効し、失効後はエラーを表示する
+
+## Scenario Excerpts
+
+- Given 登録済みユーザーがいる
+  When パスワードリセットを要求する
+  Then リセットメールが送信される
+- Given 未登録のメールアドレス
+  When パスワードリセットを要求する
+  Then 同じメッセージが表示される（送信の有無は漏らさない）
+- Given 期限切れのリセットリンク
+  When リセットリンクを開く
+  Then 期限切れとして扱われ、再送導線が提示される
+
+## Test Excerpts
+
+- unit: `requestPasswordReset` は常に成功レスポンスを返す（登録有無を分岐しない）
+- unit: `verifyResetToken` は失効時に `TokenExpired` を返す
+- integration: 送信頻度制限が発動した場合でも同じメッセージを返す
+
+## Contract / Trace Links
+
+- Spec: SPEC-RESET-001 → Scenario: SC-RESET-001, SC-RESET-002, SC-RESET-003
+- Scenario: SC-RESET-003 → Test: tests/auth/reset.test.ts#expired
+
+## Open Concerns
+
+- 送信頻度制限のしきい値（運用で調整するか、固定か）
+- 期限切れ時のUX（単に失敗か、再送導線を必須にするか）
+
+## Non-goals
+
+- メール配信基盤の冗長化
+- 監査ログの永続化