qfai 0.6.3 → 0.7.1

package/README.md

@@ -48,7 +48,7 @@ npx qfai report
 
 ## できること
 
-- `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 init` によるテンプレート生成（specs/contracts に加え、`.qfai/require/README.md`、`.qfai/rules/pnpm.md`、`.qfai/prompts/**`、`.qfai/prompts.local/README.md`、`.qfai/promptpack/` を含む）
 - `npx qfai validate` による `.qfai/` 内ドキュメントの整合性・トレーサビリティ検査
 - `npx qfai validate` による SC→Test 参照の検証（`validation.traceability.testFileGlobs` に一致するテストファイルから `QFAI:SC-xxxx` を抽出）
 - `npx qfai doctor` による設定/探索/パス/glob/validate.json の事前診断
@@ -61,6 +61,15 @@ npx qfai report
 `validate` は `--fail-on` / `--strict` によって CI ゲート化できます。`validate` は常に `.qfai/out/validate.json`（`output.validateJsonPath`）へ JSON を出力します。`--format` は画面表示（text/github）のみを制御します。`--format github` はアノテーションの上限と重複排除を行い、先頭にサマリを出します（全量は `validate.json` か `--format text` を参照）。
 `report` は `.qfai/out/validate.json` を既定入力とし、`--in` で上書きできます（優先順位: CLI > config）。`--run-validate` を指定すると validate を実行してから report を生成します。出力先は `--out` で変更できます（`--format json` の場合は `.qfai/out/report.json`）。
 `doctor` は validate/report の前段で設定/探索/パス/glob/validate.json を診断します。`--format text|json`、`--out` をサポートし、診断のみ（修復はしません）。`--fail-on warning|error` を指定すると該当 severity 以上で exit 1（未指定は常に exit 0）になります。
+
+### Prompts Overlay（v0.7 以降の方針）
+
+QFAI が提供するプロンプト資産は次の 2 つに分離します。
+
+- `.qfai/prompts/**`: QFAI 標準資産（更新や `qfai init` 再実行で上書きされ得る。利用者編集は非推奨・非サポート）
+- `.qfai/prompts.local/**`: 利用者カスタム資産（QFAI はここを上書きしない）
+
+同じ相対パスのファイルがある場合は `.qfai/prompts.local` を優先して参照する運用とします。
 `report.json` は非契約（experimental / internal）として扱います。外部 consumer は依存しないでください。フィールドは例であり固定ではありません。短い例:
 
 ```json
@@ -80,7 +89,7 @@ doctor（text）の例:
 ```text
 qfai doctor: root=. config=qfai.config.yaml (found)
 [ok] config.search: qfai.config.yaml found
-summary: ok=10 warning=2 error=0
+summary: ok=10 info=1 warning=2 error=0
 ```
 
 doctor の JSON も非契約（内部形式。将来予告なく変更あり）です。フィールドは例であり固定ではありません。短い例:
@@ -221,6 +230,8 @@ qfai.config.yaml
     qfai-maintain-traceability.md
     qfai-maintain-contracts.md
     qfai-classify-change.md
+  prompts.local/
+    README.md
   contracts/
     README.md
     api/

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

@@ -24,7 +24,8 @@ npx qfai report
 - `contracts/` : UI / API / DB 契約を置く場所
 - `require/` : 既存要件の集約（validate 対象外）
 - `rules/` : 規約・運用ルール
-- `prompts/` : 生成プロンプト資産（自動読取はしない）
+- `prompts/` : QFAI 標準のプロンプト資産（自動読取はしない。更新や再 init で上書きされ得る）
+- `prompts.local/` : 利用者カスタムのプロンプト資産（存在する場合は overlay でこちらを優先して読む運用）
 - `promptpack/` : PromptPack（SSOT、運用ルール/観点の正本）
 - `out/` : `validate` / `report` の出力先（gitignore 推奨）
 
@@ -36,6 +37,7 @@ npx qfai report
 - `rules/conventions.md`
 - `rules/pnpm.md`
 - `prompts/README.md`
+- `prompts.local/README.md`
 - `prompts/require-to-spec.md`
 - `prompts/qfai-generate-test-globs.md`
 - `prompts/qfai-maintain-traceability.md`
@@ -54,6 +56,12 @@ npx qfai report
 
 `prompts/` は **人間が手動で使う資産**です。現時点では自動読取は行いません（将来のバージョンで CLI 連携を検討します）。
 
+v0.7 以降、プロンプト資産のカスタマイズは `.qfai/prompts.local/**` に集約します（overlay 運用）。
+
+- `.qfai/prompts/**` は QFAI 標準資産であり、更新や `qfai init` 再実行で上書きされ得ます
+- 利用者が `.qfai/prompts/**` を直接編集することは非推奨・非サポートです
+- 変更したい場合は同一相対パスで `.qfai/prompts.local/**` に置いて上書きしてください
+
 例:
 
 - Copilot: `.github/copilot-instructions.md` に要旨を転記

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

@@ -2,12 +2,22 @@
 
 このディレクトリのプロンプトは **手動で使う資産**です。現時点では自動読取は行いません（将来のバージョンで CLI 連携を検討します）。
 
+重要: `.qfai/prompts/**` は **QFAI 標準資産**です。QFAI のアップデートや `qfai init` の再実行により **上書きされ得ます**。
+利用者が直接編集することは **非推奨・非サポート（ほぼ禁止）**です。変更したい場合は `.qfai/prompts.local/**` に同一相対パスで置いて overlay してください。
+
 ## 目的
 
 - Spec から overview / Business Flow を生成するための素材
 - トレーサビリティ/契約/変更区分の運用支援（CIで止めない領域）
 - 将来（v0.9）の adapter/emit 実装に備えた配布物
 
+## Overlay（prompts.local）
+
+カスタムしたい場合は、次の優先順位で参照する運用とします。
+
+1. `.qfai/prompts.local/<relativePath>`
+2. `.qfai/prompts/<relativePath>`
+
 ## プロンプト一覧
 
 - `makeOverview.md`: Spec 一覧（overview）生成

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

@@ -0,0 +1,25 @@
+# Prompts Local（利用者カスタム / Overlay）
+
+このディレクトリは **利用者が自由に編集・追加できるプロンプト資産**の置き場です。
+
+QFAI v0.7 以降は、プロンプト資産のカスタマイズ手段を **overlay（prompts.local 優先）**に一本化します。
+
+## Overlay ルール（重要）
+
+同じ相対パスのファイルが存在する場合、次の優先順位で参照する運用とします。
+
+1. `.qfai/prompts.local/<relativePath>`（存在すればこちらを優先）
+2. `.qfai/prompts/<relativePath>`（無ければ base を参照）
+
+例:
+
+- base: `.qfai/prompts/require-to-spec.md`
+- local override: `.qfai/prompts.local/require-to-spec.md`
+
+→ `prompts.local` に同じ相対パスで置けば、以降は local を読む運用にできます。
+
+## 重要な注意（サポート境界）
+
+- `.qfai/prompts/**` は **QFAI 標準資産**です（更新や `qfai init` の再実行で上書きされ得ます）。
+- 利用者が `.qfai/prompts/**` を直接編集することは **非推奨・非サポート（ほぼ禁止）**です。
+- 変更したい場合は、対象ファイルを `prompts.local` にコピーして上書きしてください。

package/dist/cli/index.cjs

@@ -889,8 +889,8 @@ var import_promises6 = require("fs/promises");
 var import_node_path6 = __toESM(require("path"), 1);
 var import_node_url = require("url");
 async function resolveToolVersion() {
-  if ("0.6.3".length > 0) {
-    return "0.6.3";
+  if ("0.7.1".length > 0) {
+    return "0.7.1";
   }
   try {
     const packagePath = resolvePackageJsonPath();
@@ -921,7 +921,7 @@ function addCheck(checks, check) {
   checks.push(check);
 }
 function summarize(checks) {
-  const summary = { ok: 0, warning: 0, error: 0 };
+  const summary = { ok: 0, info: 0, warning: 0, error: 0 };
   for (const check of checks) {
     summary[check.severity] += 1;
   }
@@ -993,6 +993,20 @@ async function createDoctorData(options) {
       message: ok ? `${key} exists` : `${key} is missing (did you run 'qfai init'?)`,
       details: { path: toRelativePath(root, resolved) }
     });
+    if (key === "promptsDir") {
+      const promptsLocalDir = import_node_path7.default.join(
+        import_node_path7.default.dirname(resolved),
+        `${import_node_path7.default.basename(resolved)}.local`
+      );
+      const found = await exists4(promptsLocalDir);
+      addCheck(checks, {
+        id: "paths.promptsLocalDir",
+        severity: "info",
+        title: "Prompts overlay (prompts.local)",
+        message: found ? "prompts.local exists (overlay can be used)" : "prompts.local is optional (create it to override prompts)",
+        details: { path: toRelativePath(root, promptsLocalDir) }
+      });
+    }
   }
   const specsRoot = resolvePath(root, config, "specsDir");
   const entries = await collectSpecEntries(specsRoot);
@@ -1191,7 +1205,7 @@ function formatDoctorText(data) {
     lines.push(`[${check.severity}] ${check.id}: ${check.message}`);
   }
   lines.push(
-    `summary: ok=${data.summary.ok} warning=${data.summary.warning} error=${data.summary.error}`
+    `summary: ok=${data.summary.ok} info=${data.summary.info} warning=${data.summary.warning} error=${data.summary.error}`
   );
   return lines.join("\n");
 }
@@ -1240,9 +1254,22 @@ async function copyFiles(files, sourceRoot, destRoot, options) {
   const copied = [];
   const skipped = [];
   const conflicts = [];
+  const protectPrefixes = (options.protect ?? []).map((p) => p.replace(/^[\\/]+/, "").replace(/[\\/]+$/, "")).filter((p) => p.length > 0).map((p) => p + import_node_path9.default.sep);
+  const isProtectedRelative = (relative) => {
+    if (protectPrefixes.length === 0) {
+      return false;
+    }
+    const normalized = relative.replace(/[\\/]+/g, import_node_path9.default.sep);
+    return protectPrefixes.some(
+      (prefix) => normalized === prefix.slice(0, -1) || normalized.startsWith(prefix)
+    );
+  };
   if (!options.force) {
     for (const file of files) {
       const relative = import_node_path9.default.relative(sourceRoot, file);
+      if (isProtectedRelative(relative)) {
+        continue;
+      }
       const dest = import_node_path9.default.join(destRoot, relative);
       if (!await shouldWrite(dest, options.force)) {
         conflicts.push(dest);
@@ -1255,7 +1282,8 @@ async function copyFiles(files, sourceRoot, destRoot, options) {
   for (const file of files) {
     const relative = import_node_path9.default.relative(sourceRoot, file);
     const dest = import_node_path9.default.join(destRoot, relative);
-    if (!await shouldWrite(dest, options.force)) {
+    const forceForThisFile = isProtectedRelative(relative) ? false : options.force;
+    if (!await shouldWrite(dest, forceForThisFile)) {
       skipped.push(dest);
       continue;
     }
@@ -1350,7 +1378,8 @@ async function runInit(options) {
   });
   const qfaiResult = await copyTemplateTree(qfaiAssets, destQfai, {
     force: options.force,
-    dryRun: options.dryRun
+    dryRun: options.dryRun,
+    protect: ["prompts.local"]
   });
   report(
     [...rootResult.copied, ...qfaiResult.copied],