qfai 0.4.7 → 0.5.0

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` によるレポート出力
@@ -42,10 +42,18 @@ Contract ID prefix は `UI-0001` / `API-0001` / `DB-0001` です。
 契約関連の検証は `validation.traceability` で制御します。
 
 - `validation.traceability.allowOrphanContracts`: Spec から参照されない契約の許可（default: `false`）
-- `validation.traceability.unknownContractIdSeverity`: Spec が参照した契約 ID が存在しない場合の severity（default: `error`、`error` / `warning` のみ）
+- `validation.traceability.unknownContractIdSeverity`: Scenario が参照した契約 ID が存在しない場合の severity（default: `error`、`error` / `warning` のみ）
+- Spec の `QFAI-CONTRACT-REF` が未知 ID を参照した場合は常に error（`QFAI-TRACE-021`）
+- `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

@@ -34,6 +34,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`
 

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,6 +2,11 @@
 
 参照は下流→上流のみを許可する（下流参照禁止の対象はテスト/実装）。
 
+## 用語（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参照は任意）
 - テスト/コードは QFAI:SC-xxxx で SC を参照する
@@ -16,4 +21,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`）を崩さない
+- allowOrphanContracts の変更を無断で行わない
+
+## 出力フォーマット
+
+- 追加/変更する 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/dist/cli/index.cjs

@@ -1280,8 +1280,8 @@ var import_promises8 = require("fs/promises");
 var import_node_path9 = __toESM(require("path"), 1);
 var import_node_url2 = require("url");
 async function resolveToolVersion() {
-  if ("0.4.7".length > 0) {
-    return "0.4.7";
+  if ("0.5.0".length > 0) {
+    return "0.5.0";
   }
   try {
     const packagePath = resolvePackageJsonPath();
@@ -2624,8 +2624,11 @@ async function createReportData(root, validation, configResult) {
     db: dbFiles
   } = await collectContractFiles(uiRoot, apiRoot, dbRoot);
   const contractIndex = await buildContractIndex(root, config);
-  const specContractRefs = await collectSpecContractRefs(specFiles);
   const contractIdList = Array.from(contractIndex.ids);
+  const specContractRefs = await collectSpecContractRefs(
+    specFiles,
+    contractIdList
+  );
   const referencedContracts = /* @__PURE__ */ new Set();
   for (const ids of specContractRefs.specToContractIds.values()) {
     ids.forEach((id) => referencedContracts.add(id));
@@ -2706,6 +2709,7 @@ async function createReportData(root, validation, configResult) {
       },
       specs: {
         contractRefMissing: specContractRefs.missingRefSpecs.size,
+        missingRefSpecs: toSortedArray2(specContractRefs.missingRefSpecs),
         specToContractIds: specToContractIdsRecord
       }
     },
@@ -2788,6 +2792,16 @@ function formatReportMarkdown(data) {
     }
   }
   lines.push("");
+  lines.push("## Spec\u3067 contract-ref \u672A\u5BA3\u8A00");
+  const missingRefSpecs = data.traceability.specs.missingRefSpecs;
+  if (missingRefSpecs.length === 0) {
+    lines.push("- (none)");
+  } else {
+    for (const specId of missingRefSpecs) {
+      lines.push(`- ${specId}`);
+    }
+  }
+  lines.push("");
   lines.push("## SC\u30AB\u30D0\u30EC\u30C3\u30B8");
   lines.push(`- total: ${data.traceability.sc.total}`);
   lines.push(`- covered: ${data.traceability.sc.covered}`);
@@ -2891,10 +2905,13 @@ function formatReportMarkdown(data) {
 function formatReportJson(data) {
   return JSON.stringify(data, null, 2);
 }
-async function collectSpecContractRefs(specFiles) {
+async function collectSpecContractRefs(specFiles, contractIdList) {
   const specToContractIds = /* @__PURE__ */ new Map();
   const idToSpecs = /* @__PURE__ */ new Map();
   const missingRefSpecs = /* @__PURE__ */ new Set();
+  for (const contractId of contractIdList) {
+    idToSpecs.set(contractId, /* @__PURE__ */ new Set());
+  }
   for (const file of specFiles) {
     const text = await (0, import_promises15.readFile)(file, "utf-8");
     const parsed = parseSpec(text, file);
@@ -2902,13 +2919,15 @@ async function collectSpecContractRefs(specFiles) {
     const refs = parsed.contractRefs;
     if (refs.lines.length === 0) {
       missingRefSpecs.add(specKey);
+      continue;
     }
     const currentContracts = specToContractIds.get(specKey) ?? /* @__PURE__ */ new Set();
     for (const id of refs.ids) {
       currentContracts.add(id);
-      const specs = idToSpecs.get(id) ?? /* @__PURE__ */ new Set();
-      specs.add(specKey);
-      idToSpecs.set(id, specs);
+      const specs = idToSpecs.get(id);
+      if (specs) {
+        specs.add(specKey);
+      }
     }
     specToContractIds.set(specKey, currentContracts);
   }