qfai 0.7.2 → 0.8.1

package/dist/cli/index.mjs

@@ -2,11 +2,11 @@
 
 // src/cli/commands/doctor.ts
 import { mkdir, writeFile } from "fs/promises";
-import path8 from "path";
+import path10 from "path";
 
 // src/core/doctor.ts
 import { access as access4 } from "fs/promises";
-import path7 from "path";
+import path9 from "path";
 
 // src/core/config.ts
 import { access, readFile } from "fs/promises";
@@ -378,6 +378,7 @@ function configIssue(file, message) {
   return {
     code: "QFAI_CONFIG_INVALID",
     severity: "error",
+    category: "compatibility",
     message,
     file,
     rule: "config.invalid"
@@ -865,17 +866,142 @@ function formatError3(error2) {
   return String(error2);
 }
 
-// src/core/version.ts
+// src/core/promptsIntegrity.ts
 import { readFile as readFile3 } from "fs/promises";
+import path7 from "path";
+
+// src/shared/assets.ts
+import { existsSync } from "fs";
 import path6 from "path";
 import { fileURLToPath } from "url";
+function getInitAssetsDir() {
+  const base = import.meta.url;
+  const basePath = base.startsWith("file:") ? fileURLToPath(base) : base;
+  const baseDir = path6.dirname(basePath);
+  const candidates = [
+    path6.resolve(baseDir, "../../../assets/init"),
+    path6.resolve(baseDir, "../../assets/init")
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  throw new Error(
+    [
+      "init \u7528\u30C6\u30F3\u30D7\u30EC\u30FC\u30C8\u304C\u898B\u3064\u304B\u308A\u307E\u305B\u3093\u3002Template assets not found.",
+      "\u78BA\u8A8D\u3057\u305F\u30D1\u30B9 / Checked paths:",
+      ...candidates.map((candidate) => `- ${candidate}`)
+    ].join("\n")
+  );
+}
+
+// src/core/promptsIntegrity.ts
+async function diffProjectPromptsAgainstInitAssets(root) {
+  const promptsDir = path7.resolve(root, ".qfai", "prompts");
+  let templateDir;
+  try {
+    templateDir = path7.join(getInitAssetsDir(), ".qfai", "prompts");
+  } catch {
+    return {
+      status: "skipped_missing_assets",
+      promptsDir,
+      templateDir: "",
+      missing: [],
+      extra: [],
+      changed: []
+    };
+  }
+  const projectFiles = await collectFiles(promptsDir);
+  if (projectFiles.length === 0) {
+    return {
+      status: "skipped_missing_prompts",
+      promptsDir,
+      templateDir,
+      missing: [],
+      extra: [],
+      changed: []
+    };
+  }
+  const templateFiles = await collectFiles(templateDir);
+  const templateByRel = /* @__PURE__ */ new Map();
+  for (const abs of templateFiles) {
+    templateByRel.set(toRel(templateDir, abs), abs);
+  }
+  const projectByRel = /* @__PURE__ */ new Map();
+  for (const abs of projectFiles) {
+    projectByRel.set(toRel(promptsDir, abs), abs);
+  }
+  const missing = [];
+  const extra = [];
+  const changed = [];
+  for (const rel of templateByRel.keys()) {
+    if (!projectByRel.has(rel)) {
+      missing.push(rel);
+    }
+  }
+  for (const rel of projectByRel.keys()) {
+    if (!templateByRel.has(rel)) {
+      extra.push(rel);
+    }
+  }
+  const common = intersectKeys(templateByRel, projectByRel);
+  for (const rel of common) {
+    const templateAbs = templateByRel.get(rel);
+    const projectAbs = projectByRel.get(rel);
+    if (!templateAbs || !projectAbs) {
+      continue;
+    }
+    try {
+      const [a, b] = await Promise.all([
+        readFile3(templateAbs, "utf-8"),
+        readFile3(projectAbs, "utf-8")
+      ]);
+      if (normalizeNewlines(a) !== normalizeNewlines(b)) {
+        changed.push(rel);
+      }
+    } catch {
+      changed.push(rel);
+    }
+  }
+  const status = missing.length > 0 || extra.length > 0 || changed.length > 0 ? "modified" : "ok";
+  return {
+    status,
+    promptsDir,
+    templateDir,
+    missing: missing.sort(),
+    extra: extra.sort(),
+    changed: changed.sort()
+  };
+}
+function normalizeNewlines(text) {
+  return text.replace(/\r\n/g, "\n");
+}
+function toRel(base, abs) {
+  const rel = path7.relative(base, abs);
+  return rel.replace(/[\\/]+/g, "/");
+}
+function intersectKeys(a, b) {
+  const out = [];
+  for (const key of a.keys()) {
+    if (b.has(key)) {
+      out.push(key);
+    }
+  }
+  return out;
+}
+
+// src/core/version.ts
+import { readFile as readFile4 } from "fs/promises";
+import path8 from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
 async function resolveToolVersion() {
-  if ("0.7.2".length > 0) {
-    return "0.7.2";
+  if ("0.8.1".length > 0) {
+    return "0.8.1";
   }
   try {
     const packagePath = resolvePackageJsonPath();
-    const raw = await readFile3(packagePath, "utf-8");
+    const raw = await readFile4(packagePath, "utf-8");
     const parsed = JSON.parse(raw);
     const version = typeof parsed.version === "string" ? parsed.version : "";
     return version.length > 0 ? version : "unknown";
@@ -885,8 +1011,8 @@ async function resolveToolVersion() {
 }
 function resolvePackageJsonPath() {
   const base = import.meta.url;
-  const basePath = base.startsWith("file:") ? fileURLToPath(base) : base;
-  return path6.resolve(path6.dirname(basePath), "../../package.json");
+  const basePath = base.startsWith("file:") ? fileURLToPath2(base) : base;
+  return path8.resolve(path8.dirname(basePath), "../../package.json");
 }
 
 // src/core/doctor.ts
@@ -912,7 +1038,7 @@ function normalizeGlobs2(values) {
   return values.map((glob) => glob.trim()).filter((glob) => glob.length > 0);
 }
 async function createDoctorData(options) {
-  const startDir = path7.resolve(options.startDir);
+  const startDir = path9.resolve(options.startDir);
   const checks = [];
   const configPath = getConfigPath(startDir);
   const search = options.rootExplicit ? {
@@ -975,9 +1101,9 @@ async function createDoctorData(options) {
       details: { path: toRelativePath(root, resolved) }
     });
     if (key === "promptsDir") {
-      const promptsLocalDir = path7.join(
-        path7.dirname(resolved),
-        `${path7.basename(resolved)}.local`
+      const promptsLocalDir = path9.join(
+        path9.dirname(resolved),
+        `${path9.basename(resolved)}.local`
       );
       const found = await exists4(promptsLocalDir);
       addCheck(checks, {
@@ -987,6 +1113,49 @@ async function createDoctorData(options) {
         message: found ? "prompts.local exists (overlay can be used)" : "prompts.local is optional (create it to override prompts)",
         details: { path: toRelativePath(root, promptsLocalDir) }
       });
+      const diff = await diffProjectPromptsAgainstInitAssets(root);
+      if (diff.status === "skipped_missing_prompts") {
+        addCheck(checks, {
+          id: "prompts.integrity",
+          severity: "info",
+          title: "Prompts integrity (.qfai/prompts)",
+          message: "prompts \u304C\u672A\u4F5C\u6210\u306E\u305F\u3081\u691C\u67FB\u3092\u30B9\u30AD\u30C3\u30D7\u3057\u307E\u3057\u305F\uFF08'qfai init' \u3092\u5B9F\u884C\u3057\u3066\u304F\u3060\u3055\u3044\uFF09",
+          details: { promptsDir: toRelativePath(root, diff.promptsDir) }
+        });
+      } else if (diff.status === "skipped_missing_assets") {
+        addCheck(checks, {
+          id: "prompts.integrity",
+          severity: "info",
+          title: "Prompts integrity (.qfai/prompts)",
+          message: "init assets \u304C\u898B\u3064\u304B\u3089\u306A\u3044\u305F\u3081\u691C\u67FB\u3092\u30B9\u30AD\u30C3\u30D7\u3057\u307E\u3057\u305F\uFF08\u30A4\u30F3\u30B9\u30C8\u30FC\u30EB\u72B6\u614B\u3092\u78BA\u8A8D\u3057\u3066\u304F\u3060\u3055\u3044\uFF09",
+          details: { promptsDir: toRelativePath(root, diff.promptsDir) }
+        });
+      } else if (diff.status === "ok") {
+        addCheck(checks, {
+          id: "prompts.integrity",
+          severity: "ok",
+          title: "Prompts integrity (.qfai/prompts)",
+          message: "\u6A19\u6E96 assets \u3068\u4E00\u81F4\u3057\u3066\u3044\u307E\u3059",
+          details: { promptsDir: toRelativePath(root, diff.promptsDir) }
+        });
+      } else {
+        addCheck(checks, {
+          id: "prompts.integrity",
+          severity: "error",
+          title: "Prompts integrity (.qfai/prompts)",
+          message: "\u6A19\u6E96\u8CC7\u7523 '.qfai/prompts/**' \u304C\u6539\u5909\u3055\u308C\u3066\u3044\u307E\u3059\u3002prompts \u306E\u76F4\u7DE8\u96C6\u306F\u975E\u63A8\u5968\u3067\u3059\uFF08\u30A2\u30C3\u30D7\u30C7\u30FC\u30C8/\u518D init \u3067\u4E0A\u66F8\u304D\u3055\u308C\u5F97\u307E\u3059\uFF09\u3002",
+          details: {
+            promptsDir: toRelativePath(root, diff.promptsDir),
+            missing: diff.missing,
+            extra: diff.extra,
+            changed: diff.changed,
+            nextActions: [
+              "\u5909\u66F4\u5185\u5BB9\u3092 .qfai/prompts.local/** \u306B\u79FB\u3059\uFF08\u540C\u4E00\u76F8\u5BFE\u30D1\u30B9\u3067\u914D\u7F6E\uFF09",
+              "\u5FC5\u8981\u306A\u3089 qfai init --force \u3067 prompts \u3092\u6A19\u6E96\u72B6\u614B\u3078\u623B\u3059\uFF08prompts.local \u306F\u4FDD\u8B77\u3055\u308C\u307E\u3059\uFF09"
+            ]
+          }
+        });
+      }
     }
   }
   const specsRoot = resolvePath(root, config, "specsDir");
@@ -1007,7 +1176,7 @@ async function createDoctorData(options) {
     message: missingFiles === 0 ? `All spec packs have required files (count=${entries.length})` : `Missing required files in spec packs (missingFiles=${missingFiles})`,
     details: { specPacks: entries.length, missingFiles }
   });
-  const validateJsonAbs = path7.isAbsolute(config.output.validateJsonPath) ? config.output.validateJsonPath : path7.resolve(root, config.output.validateJsonPath);
+  const validateJsonAbs = path9.isAbsolute(config.output.validateJsonPath) ? config.output.validateJsonPath : path9.resolve(root, config.output.validateJsonPath);
   const validateJsonExists = await exists4(validateJsonAbs);
   addCheck(checks, {
     id: "output.validateJson",
@@ -1017,8 +1186,8 @@ async function createDoctorData(options) {
     details: { path: toRelativePath(root, validateJsonAbs) }
   });
   const outDirAbs = resolvePath(root, config, "outDir");
-  const rel = path7.relative(outDirAbs, validateJsonAbs);
-  const inside = rel !== "" && !rel.startsWith("..") && !path7.isAbsolute(rel);
+  const rel = path9.relative(outDirAbs, validateJsonAbs);
+  const inside = rel !== "" && !rel.startsWith("..") && !path9.isAbsolute(rel);
   addCheck(checks, {
     id: "output.pathAlignment",
     severity: inside ? "ok" : "warning",
@@ -1124,12 +1293,12 @@ async function detectOutDirCollisions(root) {
     ignore: DEFAULT_CONFIG_SEARCH_IGNORE_GLOBS
   });
   const configRoots = Array.from(
-    new Set(configPaths.map((configPath) => path7.dirname(configPath)))
+    new Set(configPaths.map((configPath) => path9.dirname(configPath)))
   ).sort((a, b) => a.localeCompare(b));
   const outDirToRoots = /* @__PURE__ */ new Map();
   for (const configRoot of configRoots) {
     const { config } = await loadConfig(configRoot);
-    const outDir = path7.normalize(resolvePath(configRoot, config, "outDir"));
+    const outDir = path9.normalize(resolvePath(configRoot, config, "outDir"));
     const roots = outDirToRoots.get(outDir) ?? /* @__PURE__ */ new Set();
     roots.add(configRoot);
     outDirToRoots.set(outDir, roots);
@@ -1146,20 +1315,20 @@ async function detectOutDirCollisions(root) {
   return { monorepoRoot, configRoots, collisions };
 }
 async function findMonorepoRoot(startDir) {
-  let current = path7.resolve(startDir);
+  let current = path9.resolve(startDir);
   while (true) {
-    const gitPath = path7.join(current, ".git");
-    const workspacePath = path7.join(current, "pnpm-workspace.yaml");
+    const gitPath = path9.join(current, ".git");
+    const workspacePath = path9.join(current, "pnpm-workspace.yaml");
     if (await exists4(gitPath) || await exists4(workspacePath)) {
       return current;
     }
-    const parent = path7.dirname(current);
+    const parent = path9.dirname(current);
     if (parent === current) {
       break;
     }
     current = parent;
   }
-  return path7.resolve(startDir);
+  return path9.resolve(startDir);
 }
 
 // src/cli/lib/logger.ts
@@ -1201,8 +1370,8 @@ async function runDoctor(options) {
   const output = options.format === "json" ? formatDoctorJson(data) : formatDoctorText(data);
   const exitCode = shouldFailDoctor(data.summary, options.failOn) ? 1 : 0;
   if (options.outPath) {
-    const outAbs = path8.isAbsolute(options.outPath) ? options.outPath : path8.resolve(process.cwd(), options.outPath);
-    await mkdir(path8.dirname(outAbs), { recursive: true });
+    const outAbs = path10.isAbsolute(options.outPath) ? options.outPath : path10.resolve(process.cwd(), options.outPath);
+    await mkdir(path10.dirname(outAbs), { recursive: true });
     await writeFile(outAbs, `${output}
 `, "utf-8");
     info(`doctor: wrote ${outAbs}`);
@@ -1222,36 +1391,59 @@ function shouldFailDoctor(summary, failOn) {
 }
 
 // src/cli/commands/init.ts
-import path11 from "path";
+import path12 from "path";
 
 // src/cli/lib/fs.ts
 import { access as access5, copyFile, mkdir as mkdir2, readdir as readdir3 } from "fs/promises";
-import path9 from "path";
+import path11 from "path";
 async function copyTemplateTree(sourceRoot, destRoot, options) {
   const files = await collectTemplateFiles(sourceRoot);
   return copyFiles(files, sourceRoot, destRoot, options);
 }
+async function copyTemplatePaths(sourceRoot, destRoot, relativePaths, options) {
+  const allFiles = [];
+  for (const relPath of relativePaths) {
+    const fullPath = path11.join(sourceRoot, relPath);
+    const files = await collectTemplateFiles(fullPath);
+    allFiles.push(...files);
+  }
+  return copyFiles(allFiles, sourceRoot, destRoot, options);
+}
 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 + path9.sep);
+  const protectPrefixes = (options.protect ?? []).map((p) => p.replace(/^[\\/]+/, "").replace(/[\\/]+$/, "")).filter((p) => p.length > 0).map((p) => p + path11.sep);
+  const excludePrefixes = (options.exclude ?? []).map((p) => p.replace(/^[\\/]+/, "").replace(/[\\/]+$/, "")).filter((p) => p.length > 0).map((p) => p + path11.sep);
   const isProtectedRelative = (relative) => {
     if (protectPrefixes.length === 0) {
       return false;
     }
-    const normalized = relative.replace(/[\\/]+/g, path9.sep);
+    const normalized = relative.replace(/[\\/]+/g, path11.sep);
     return protectPrefixes.some(
       (prefix) => normalized === prefix.slice(0, -1) || normalized.startsWith(prefix)
     );
   };
-  if (!options.force) {
+  const isExcludedRelative = (relative) => {
+    if (excludePrefixes.length === 0) {
+      return false;
+    }
+    const normalized = relative.replace(/[\\/]+/g, path11.sep);
+    return excludePrefixes.some(
+      (prefix) => normalized === prefix.slice(0, -1) || normalized.startsWith(prefix)
+    );
+  };
+  const conflictPolicy = options.conflictPolicy ?? "error";
+  if (!options.force && conflictPolicy === "error") {
     for (const file of files) {
-      const relative = path9.relative(sourceRoot, file);
+      const relative = path11.relative(sourceRoot, file);
+      if (isExcludedRelative(relative)) {
+        continue;
+      }
       if (isProtectedRelative(relative)) {
         continue;
       }
-      const dest = path9.join(destRoot, relative);
+      const dest = path11.join(destRoot, relative);
       if (!await shouldWrite(dest, options.force)) {
         conflicts.push(dest);
       }
@@ -1261,15 +1453,18 @@ async function copyFiles(files, sourceRoot, destRoot, options) {
     }
   }
   for (const file of files) {
-    const relative = path9.relative(sourceRoot, file);
-    const dest = path9.join(destRoot, relative);
+    const relative = path11.relative(sourceRoot, file);
+    if (isExcludedRelative(relative)) {
+      continue;
+    }
+    const dest = path11.join(destRoot, relative);
     const forceForThisFile = isProtectedRelative(relative) ? false : options.force;
     if (!await shouldWrite(dest, forceForThisFile)) {
       skipped.push(dest);
       continue;
     }
     if (!options.dryRun) {
-      await mkdir2(path9.dirname(dest), { recursive: true });
+      await mkdir2(path11.dirname(dest), { recursive: true });
       await copyFile(file, dest);
     }
     copied.push(dest);
@@ -1293,7 +1488,7 @@ async function collectTemplateFiles(root) {
   }
   const items = await readdir3(root, { withFileTypes: true });
   for (const item of items) {
-    const fullPath = path9.join(root, item.name);
+    const fullPath = path11.join(root, item.name);
     if (item.isDirectory()) {
       const nested = await collectTemplateFiles(fullPath);
       entries.push(...nested);
@@ -1320,51 +1515,39 @@ async function exists5(target) {
   }
 }
 
-// src/cli/lib/assets.ts
-import { existsSync } from "fs";
-import path10 from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
-function getInitAssetsDir() {
-  const base = import.meta.url;
-  const basePath = base.startsWith("file:") ? fileURLToPath2(base) : base;
-  const baseDir = path10.dirname(basePath);
-  const candidates = [
-    path10.resolve(baseDir, "../../../assets/init"),
-    path10.resolve(baseDir, "../../assets/init")
-  ];
-  for (const candidate of candidates) {
-    if (existsSync(candidate)) {
-      return candidate;
-    }
-  }
-  throw new Error(
-    [
-      "init \u7528\u30C6\u30F3\u30D7\u30EC\u30FC\u30C8\u304C\u898B\u3064\u304B\u308A\u307E\u305B\u3093\u3002Template assets not found.",
-      "\u78BA\u8A8D\u3057\u305F\u30D1\u30B9 / Checked paths:",
-      ...candidates.map((candidate) => `- ${candidate}`)
-    ].join("\n")
-  );
-}
-
 // src/cli/commands/init.ts
 async function runInit(options) {
   const assetsRoot = getInitAssetsDir();
-  const rootAssets = path11.join(assetsRoot, "root");
-  const qfaiAssets = path11.join(assetsRoot, ".qfai");
-  const destRoot = path11.resolve(options.dir);
-  const destQfai = path11.join(destRoot, ".qfai");
+  const rootAssets = path12.join(assetsRoot, "root");
+  const qfaiAssets = path12.join(assetsRoot, ".qfai");
+  const destRoot = path12.resolve(options.dir);
+  const destQfai = path12.join(destRoot, ".qfai");
   const rootResult = await copyTemplateTree(rootAssets, destRoot, {
-    force: options.force,
-    dryRun: options.dryRun
+    force: false,
+    dryRun: options.dryRun,
+    conflictPolicy: "skip"
   });
   const qfaiResult = await copyTemplateTree(qfaiAssets, destQfai, {
-    force: options.force,
+    force: false,
     dryRun: options.dryRun,
-    protect: ["prompts.local"]
+    conflictPolicy: "skip",
+    protect: ["prompts.local"],
+    exclude: ["prompts"]
   });
+  const promptsResult = await copyTemplatePaths(
+    qfaiAssets,
+    destQfai,
+    ["prompts"],
+    {
+      force: options.force,
+      dryRun: options.dryRun,
+      conflictPolicy: "skip",
+      protect: ["prompts.local"]
+    }
+  );
   report(
-    [...rootResult.copied, ...qfaiResult.copied],
-    [...rootResult.skipped, ...qfaiResult.skipped],
+    [...rootResult.copied, ...qfaiResult.copied, ...promptsResult.copied],
+    [...rootResult.skipped, ...qfaiResult.skipped, ...promptsResult.skipped],
     options.dryRun,
     "init"
   );
@@ -1380,8 +1563,8 @@ function report(copied, skipped, dryRun, label) {
 }
 
 // src/cli/commands/report.ts
-import { mkdir as mkdir3, readFile as readFile12, writeFile as writeFile2 } from "fs/promises";
-import path18 from "path";
+import { mkdir as mkdir3, readFile as readFile13, writeFile as writeFile2 } from "fs/promises";
+import path19 from "path";
 
 // src/core/normalize.ts
 function normalizeIssuePaths(root, issues) {
@@ -1421,12 +1604,12 @@ function normalizeValidationResult(root, result) {
 }
 
 // src/core/report.ts
-import { readFile as readFile11 } from "fs/promises";
-import path17 from "path";
+import { readFile as readFile12 } from "fs/promises";
+import path18 from "path";
 
 // src/core/contractIndex.ts
-import { readFile as readFile4 } from "fs/promises";
-import path12 from "path";
+import { readFile as readFile5 } from "fs/promises";
+import path13 from "path";
 
 // src/core/contractsDecl.ts
 var CONTRACT_DECLARATION_RE = /^\s*(?:#|\/\/|--|\/\*+|\*+)?\s*QFAI-CONTRACT-ID:\s*((?:API|UI|DB)-\d{4})\s*(?:\*\/)?\s*$/gm;
@@ -1448,9 +1631,9 @@ function stripContractDeclarationLines(text) {
 // src/core/contractIndex.ts
 async function buildContractIndex(root, config) {
   const contractsRoot = resolvePath(root, config, "contractsDir");
-  const uiRoot = path12.join(contractsRoot, "ui");
-  const apiRoot = path12.join(contractsRoot, "api");
-  const dbRoot = path12.join(contractsRoot, "db");
+  const uiRoot = path13.join(contractsRoot, "ui");
+  const apiRoot = path13.join(contractsRoot, "api");
+  const dbRoot = path13.join(contractsRoot, "db");
   const [uiFiles, apiFiles, dbFiles] = await Promise.all([
     collectUiContractFiles(uiRoot),
     collectApiContractFiles(apiRoot),
@@ -1468,7 +1651,7 @@ async function buildContractIndex(root, config) {
 }
 async function indexContractFiles(files, index) {
   for (const file of files) {
-    const text = await readFile4(file, "utf-8");
+    const text = await readFile5(file, "utf-8");
     extractDeclaredContractIds(text).forEach((id) => record(index, id, file));
   }
 }
@@ -1703,14 +1886,14 @@ function parseSpec(md, file) {
 }
 
 // src/core/validators/contracts.ts
-import { readFile as readFile5 } from "fs/promises";
-import path14 from "path";
+import { readFile as readFile6 } from "fs/promises";
+import path15 from "path";
 
 // src/core/contracts.ts
-import path13 from "path";
+import path14 from "path";
 import { parse as parseYaml2 } from "yaml";
 function parseStructuredContract(file, text) {
-  const ext = path13.extname(file).toLowerCase();
+  const ext = path14.extname(file).toLowerCase();
   if (ext === ".json") {
     return JSON.parse(text);
   }
@@ -1730,9 +1913,9 @@ var SQL_DANGEROUS_PATTERNS = [
 async function validateContracts(root, config) {
   const issues = [];
   const contractsRoot = resolvePath(root, config, "contractsDir");
-  issues.push(...await validateUiContracts(path14.join(contractsRoot, "ui")));
-  issues.push(...await validateApiContracts(path14.join(contractsRoot, "api")));
-  issues.push(...await validateDbContracts(path14.join(contractsRoot, "db")));
+  issues.push(...await validateUiContracts(path15.join(contractsRoot, "ui")));
+  issues.push(...await validateApiContracts(path15.join(contractsRoot, "api")));
+  issues.push(...await validateDbContracts(path15.join(contractsRoot, "db")));
   const contractIndex = await buildContractIndex(root, config);
   issues.push(...validateDuplicateContractIds(contractIndex));
   return issues;
@@ -1752,7 +1935,7 @@ async function validateUiContracts(uiRoot) {
   }
   const issues = [];
   for (const file of files) {
-    const text = await readFile5(file, "utf-8");
+    const text = await readFile6(file, "utf-8");
     const invalidIds = extractInvalidIds(text, [
       "SPEC",
       "BR",
@@ -1807,7 +1990,7 @@ async function validateApiContracts(apiRoot) {
   }
   const issues = [];
   for (const file of files) {
-    const text = await readFile5(file, "utf-8");
+    const text = await readFile6(file, "utf-8");
     const invalidIds = extractInvalidIds(text, [
       "SPEC",
       "BR",
@@ -1875,7 +2058,7 @@ async function validateDbContracts(dbRoot) {
   }
   const issues = [];
   for (const file of files) {
-    const text = await readFile5(file, "utf-8");
+    const text = await readFile6(file, "utf-8");
     const invalidIds = extractInvalidIds(text, [
       "SPEC",
       "BR",
@@ -1995,12 +2178,16 @@ function formatError4(error2) {
   }
   return String(error2);
 }
-function issue(code, message, severity, file, rule, refs) {
+function issue(code, message, severity, file, rule, refs, category = "compatibility", suggested_action) {
   const issue7 = {
     code,
     severity,
+    category,
     message
   };
+  if (suggested_action) {
+    issue7.suggested_action = suggested_action;
+  }
   if (file) {
     issue7.file = file;
   }
@@ -2014,8 +2201,8 @@ function issue(code, message, severity, file, rule, refs) {
 }
 
 // src/core/validators/delta.ts
-import { readFile as readFile6 } from "fs/promises";
-import path15 from "path";
+import { readFile as readFile7 } from "fs/promises";
+import path16 from "path";
 var SECTION_RE = /^##\s+変更区分/m;
 var COMPAT_LINE_RE = /^\s*-\s*\[[ xX]\]\s*Compatibility\b/m;
 var CHANGE_LINE_RE = /^\s*-\s*\[[ xX]\]\s*Change\/Improvement\b/m;
@@ -2029,10 +2216,10 @@ async function validateDeltas(root, config) {
   }
   const issues = [];
   for (const pack of packs) {
-    const deltaPath = path15.join(pack, "delta.md");
+    const deltaPath = path16.join(pack, "delta.md");
     let text;
     try {
-      text = await readFile6(deltaPath, "utf-8");
+      text = await readFile7(deltaPath, "utf-8");
     } catch (error2) {
       if (isMissingFileError2(error2)) {
         issues.push(
@@ -2055,7 +2242,7 @@ async function validateDeltas(root, config) {
       issues.push(
         issue2(
           "QFAI-DELTA-002",
-          "delta.md \u306E\u5909\u66F4\u533A\u5206\u304C\u4E0D\u8DB3\u3057\u3066\u3044\u307E\u3059\u3002",
+          "delta.md \u306E\u5909\u66F4\u533A\u5206\u304C\u4E0D\u8DB3\u3057\u3066\u3044\u307E\u3059\u3002`## \u5909\u66F4\u533A\u5206` \u3068\u30C1\u30A7\u30C3\u30AF\u30DC\u30C3\u30AF\u30B9\uFF08Compatibility / Change/Improvement\uFF09\u3092\u8FFD\u52A0\u3057\u3066\u304F\u3060\u3055\u3044\u3002",
           "error",
           deltaPath,
           "delta.section"
@@ -2085,12 +2272,16 @@ function isMissingFileError2(error2) {
   }
   return error2.code === "ENOENT";
 }
-function issue2(code, message, severity, file, rule, refs) {
+function issue2(code, message, severity, file, rule, refs, category = "change", suggested_action) {
   const issue7 = {
     code,
     severity,
+    category,
     message
   };
+  if (suggested_action) {
+    issue7.suggested_action = suggested_action;
+  }
   if (file) {
     issue7.file = file;
   }
@@ -2104,8 +2295,8 @@ function issue2(code, message, severity, file, rule, refs) {
 }
 
 // src/core/validators/ids.ts
-import { readFile as readFile7 } from "fs/promises";
-import path16 from "path";
+import { readFile as readFile8 } from "fs/promises";
+import path17 from "path";
 var SC_TAG_RE3 = /^SC-\d{4}$/;
 async function validateDefinedIds(root, config) {
   const issues = [];
@@ -2140,7 +2331,7 @@ async function validateDefinedIds(root, config) {
 }
 async function collectSpecDefinitionIds(files, out) {
   for (const file of files) {
-    const text = await readFile7(file, "utf-8");
+    const text = await readFile8(file, "utf-8");
     const parsed = parseSpec(text, file);
     if (parsed.specId) {
       recordId(out, parsed.specId, file);
@@ -2150,7 +2341,7 @@ async function collectSpecDefinitionIds(files, out) {
 }
 async function collectScenarioDefinitionIds(files, out) {
   for (const file of files) {
-    const text = await readFile7(file, "utf-8");
+    const text = await readFile8(file, "utf-8");
     const { document, errors } = parseScenarioDocument(text, file);
     if (!document || errors.length > 0) {
       continue;
@@ -2171,16 +2362,20 @@ function recordId(out, id, file) {
 }
 function formatFileList(files, root) {
   return files.map((file) => {
-    const relative = path16.relative(root, file);
+    const relative = path17.relative(root, file);
     return relative.length > 0 ? relative : file;
   }).join(", ");
 }
-function issue3(code, message, severity, file, rule, refs) {
+function issue3(code, message, severity, file, rule, refs, category = "compatibility", suggested_action) {
   const issue7 = {
     code,
     severity,
+    category,
     message
   };
+  if (suggested_action) {
+    issue7.suggested_action = suggested_action;
+  }
   if (file) {
     issue7.file = file;
   }
@@ -2193,8 +2388,39 @@ function issue3(code, message, severity, file, rule, refs) {
   return issue7;
 }
 
+// src/core/validators/promptsIntegrity.ts
+async function validatePromptsIntegrity(root) {
+  const diff = await diffProjectPromptsAgainstInitAssets(root);
+  if (diff.status !== "modified") {
+    return [];
+  }
+  const total = diff.missing.length + diff.extra.length + diff.changed.length;
+  const hints = [
+    diff.changed.length > 0 ? `\u5909\u66F4: ${diff.changed.length}` : null,
+    diff.missing.length > 0 ? `\u524A\u9664: ${diff.missing.length}` : null,
+    diff.extra.length > 0 ? `\u8FFD\u52A0: ${diff.extra.length}` : null
+  ].filter(Boolean).join(" / ");
+  const sample = [...diff.changed, ...diff.missing, ...diff.extra].slice(0, 10);
+  const sampleText = sample.length > 0 ? ` \u4F8B: ${sample.join(", ")}` : "";
+  return [
+    {
+      code: "QFAI-PROMPTS-001",
+      severity: "error",
+      category: "change",
+      message: `\u6A19\u6E96\u8CC7\u7523 '.qfai/prompts/**' \u304C\u6539\u5909\u3055\u308C\u3066\u3044\u307E\u3059\uFF08${hints || `\u5DEE\u5206=${total}`}\uFF09\u3002${sampleText}`,
+      suggested_action: [
+        "prompts \u306E\u76F4\u7DE8\u96C6\u306F\u975E\u63A8\u5968\u3067\u3059\uFF08\u30A2\u30C3\u30D7\u30C7\u30FC\u30C8/\u518D init \u3067\u4E0A\u66F8\u304D\u3055\u308C\u5F97\u307E\u3059\uFF09\u3002",
+        "\u6B21\u306E\u3044\u305A\u308C\u304B\u3092\u5B9F\u65BD\u3057\u3066\u304F\u3060\u3055\u3044:",
+        "- \u5909\u66F4\u3057\u305F\u3044\u5834\u5408: \u540C\u4E00\u76F8\u5BFE\u30D1\u30B9\u3067 '.qfai/prompts.local/**' \u306B\u7F6E\u3044\u3066 overlay",
+        "- \u6A19\u6E96\u72B6\u614B\u3078\u623B\u3059\u5834\u5408: 'qfai init --force' \u3092\u5B9F\u884C\uFF08prompts \u306E\u307F\u4E0A\u66F8\u304D\u3001prompts.local \u306F\u4FDD\u8B77\uFF09"
+      ].join("\n"),
+      rule: "prompts.integrity"
+    }
+  ];
+}
+
 // src/core/validators/scenario.ts
-import { readFile as readFile8 } from "fs/promises";
+import { readFile as readFile9 } from "fs/promises";
 var GIVEN_PATTERN = /\bGiven\b/;
 var WHEN_PATTERN = /\bWhen\b/;
 var THEN_PATTERN = /\bThen\b/;
@@ -2220,7 +2446,7 @@ async function validateScenarios(root, config) {
   for (const entry of entries) {
     let text;
     try {
-      text = await readFile8(entry.scenarioPath, "utf-8");
+      text = await readFile9(entry.scenarioPath, "utf-8");
     } catch (error2) {
       if (isMissingFileError3(error2)) {
         issues.push(
@@ -2365,12 +2591,16 @@ function validateScenarioContent(text, file) {
   }
   return issues;
 }
-function issue4(code, message, severity, file, rule, refs) {
+function issue4(code, message, severity, file, rule, refs, category = "compatibility", suggested_action) {
   const issue7 = {
     code,
     severity,
+    category,
     message
   };
+  if (suggested_action) {
+    issue7.suggested_action = suggested_action;
+  }
   if (file) {
     issue7.file = file;
   }
@@ -2390,7 +2620,7 @@ function isMissingFileError3(error2) {
 }
 
 // src/core/validators/spec.ts
-import { readFile as readFile9 } from "fs/promises";
+import { readFile as readFile10 } from "fs/promises";
 async function validateSpecs(root, config) {
   const specsRoot = resolvePath(root, config, "specsDir");
   const entries = await collectSpecEntries(specsRoot);
@@ -2411,7 +2641,7 @@ async function validateSpecs(root, config) {
   for (const entry of entries) {
     let text;
     try {
-      text = await readFile9(entry.specPath, "utf-8");
+      text = await readFile10(entry.specPath, "utf-8");
     } catch (error2) {
       if (isMissingFileError4(error2)) {
         issues.push(
@@ -2535,12 +2765,16 @@ function validateSpecContent(text, file, requiredSections) {
   }
   return issues;
 }
-function issue5(code, message, severity, file, rule, refs) {
+function issue5(code, message, severity, file, rule, refs, category = "compatibility", suggested_action) {
   const issue7 = {
     code,
     severity,
+    category,
     message
   };
+  if (suggested_action) {
+    issue7.suggested_action = suggested_action;
+  }
   if (file) {
     issue7.file = file;
   }
@@ -2560,7 +2794,7 @@ function isMissingFileError4(error2) {
 }
 
 // src/core/validators/traceability.ts
-import { readFile as readFile10 } from "fs/promises";
+import { readFile as readFile11 } from "fs/promises";
 var SPEC_TAG_RE3 = /^SPEC-\d{4}$/;
 var BR_TAG_RE2 = /^BR-\d{4}$/;
 async function validateTraceability(root, config) {
@@ -2580,7 +2814,7 @@ async function validateTraceability(root, config) {
   const contractIndex = await buildContractIndex(root, config);
   const contractIds = contractIndex.ids;
   for (const file of specFiles) {
-    const text = await readFile10(file, "utf-8");
+    const text = await readFile11(file, "utf-8");
     extractAllIds(text).forEach((id) => upstreamIds.add(id));
     const parsed = parseSpec(text, file);
     if (parsed.specId) {
@@ -2598,7 +2832,7 @@ async function validateTraceability(root, config) {
       issues.push(
         issue6(
           "QFAI-TRACE-020",
-          "Spec \u306B QFAI-CONTRACT-REF \u304C\u3042\u308A\u307E\u305B\u3093\u3002",
+          "Spec \u306B QFAI-CONTRACT-REF \u304C\u3042\u308A\u307E\u305B\u3093\u3002\u4F8B: `QFAI-CONTRACT-REF: none` \u307E\u305F\u306F `QFAI-CONTRACT-REF: UI-0001`",
           "error",
           file,
           "traceability.specContractRefRequired"
@@ -2609,7 +2843,7 @@ async function validateTraceability(root, config) {
         issues.push(
           issue6(
             "QFAI-TRACE-023",
-            "Spec \u306E QFAI-CONTRACT-REF \u306B none \u3068\u5951\u7D04 ID \u304C\u6DF7\u5728\u3057\u3066\u3044\u307E\u3059\u3002",
+            "Spec \u306E QFAI-CONTRACT-REF \u306B none \u3068\u5951\u7D04 ID \u304C\u6DF7\u5728\u3057\u3066\u3044\u307E\u3059\u3002none \u304B \u5951\u7D04ID \u306E\u3069\u3061\u3089\u304B\u4E00\u65B9\u3060\u3051\u306B\u3057\u3066\u304F\u3060\u3055\u3044\u3002",
             "error",
             file,
             "traceability.specContractRefFormat"
@@ -2622,7 +2856,7 @@ async function validateTraceability(root, config) {
             "QFAI-TRACE-021",
             `Spec \u306E\u5951\u7D04 ID \u304C\u4E0D\u6B63\u3067\u3059: ${contractRefs.invalidTokens.join(
               ", "
-            )}`,
+            )} (\u4F8B: UI-0001 / API-0001 / DB-0001)`,
             "error",
             file,
             "traceability.specContractRefFormat",
@@ -2653,7 +2887,7 @@ async function validateTraceability(root, config) {
     }
   }
   for (const file of scenarioFiles) {
-    const text = await readFile10(file, "utf-8");
+    const text = await readFile11(file, "utf-8");
     extractAllIds(text).forEach((id) => upstreamIds.add(id));
     const scenarioContractRefs = parseContractRefs(text, {
       allowCommentPrefix: true
@@ -2662,7 +2896,7 @@ async function validateTraceability(root, config) {
       issues.push(
         issue6(
           "QFAI-TRACE-031",
-          "Scenario \u306B QFAI-CONTRACT-REF \u304C\u3042\u308A\u307E\u305B\u3093\u3002",
+          "Scenario \u306B QFAI-CONTRACT-REF \u304C\u3042\u308A\u307E\u305B\u3093\u3002\u4F8B: `# QFAI-CONTRACT-REF: none` \u307E\u305F\u306F `# QFAI-CONTRACT-REF: UI-0001`",
           "error",
           file,
           "traceability.scenarioContractRefRequired"
@@ -2673,7 +2907,7 @@ async function validateTraceability(root, config) {
         issues.push(
           issue6(
             "QFAI-TRACE-033",
-            "Scenario \u306E QFAI-CONTRACT-REF \u306B none \u3068\u5951\u7D04 ID \u304C\u6DF7\u5728\u3057\u3066\u3044\u307E\u3059\u3002",
+            "Scenario \u306E QFAI-CONTRACT-REF \u306B none \u3068\u5951\u7D04 ID \u304C\u6DF7\u5728\u3057\u3066\u3044\u307E\u3059\u3002none \u304B \u5951\u7D04ID \u306E\u3069\u3061\u3089\u304B\u4E00\u65B9\u3060\u3051\u306B\u3057\u3066\u304F\u3060\u3055\u3044\u3002",
             "error",
             file,
             "traceability.scenarioContractRefFormat"
@@ -2686,7 +2920,7 @@ async function validateTraceability(root, config) {
             "QFAI-TRACE-032",
             `Scenario \u306E\u5951\u7D04 ID \u304C\u4E0D\u6B63\u3067\u3059: ${scenarioContractRefs.invalidTokens.join(
               ", "
-            )}`,
+            )} (\u4F8B: UI-0001 / API-0001 / DB-0001)`,
             "error",
             file,
             "traceability.scenarioContractRefFormat",
@@ -2975,7 +3209,7 @@ async function validateCodeReferences(upstreamIds, srcRoot, testsRoot) {
   const pattern = buildIdPattern(Array.from(upstreamIds));
   let found = false;
   for (const file of targetFiles) {
-    const text = await readFile10(file, "utf-8");
+    const text = await readFile11(file, "utf-8");
     if (pattern.test(text)) {
       found = true;
       break;
@@ -2998,12 +3232,16 @@ function buildIdPattern(ids) {
   const escaped = ids.map((id) => id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
   return new RegExp(`\\b(${escaped.join("|")})\\b`);
 }
-function issue6(code, message, severity, file, rule, refs) {
+function issue6(code, message, severity, file, rule, refs, category = "compatibility", suggested_action) {
   const issue7 = {
     code,
     severity,
+    category,
     message
   };
+  if (suggested_action) {
+    issue7.suggested_action = suggested_action;
+  }
   if (file) {
     issue7.file = file;
   }
@@ -3022,6 +3260,7 @@ async function validateProject(root, configResult) {
   const { config, issues: configIssues } = resolved;
   const issues = [
     ...configIssues,
+    ...await validatePromptsIntegrity(root),
     ...await validateSpecs(root, config),
     ...await validateDeltas(root, config),
     ...await validateScenarios(root, config),
@@ -3062,15 +3301,15 @@ function countIssues(issues) {
 // src/core/report.ts
 var ID_PREFIXES2 = ["SPEC", "BR", "SC", "UI", "API", "DB"];
 async function createReportData(root, validation, configResult) {
-  const resolvedRoot = path17.resolve(root);
+  const resolvedRoot = path18.resolve(root);
   const resolved = configResult ?? await loadConfig(resolvedRoot);
   const config = resolved.config;
   const configPath = resolved.configPath;
   const specsRoot = resolvePath(resolvedRoot, config, "specsDir");
   const contractsRoot = resolvePath(resolvedRoot, config, "contractsDir");
-  const apiRoot = path17.join(contractsRoot, "api");
-  const uiRoot = path17.join(contractsRoot, "ui");
-  const dbRoot = path17.join(contractsRoot, "db");
+  const apiRoot = path18.join(contractsRoot, "api");
+  const uiRoot = path18.join(contractsRoot, "ui");
+  const dbRoot = path18.join(contractsRoot, "db");
   const srcRoot = resolvePath(resolvedRoot, config, "srcDir");
   const testsRoot = resolvePath(resolvedRoot, config, "testsDir");
   const specFiles = await collectSpecFiles(specsRoot);
@@ -3184,7 +3423,39 @@ function formatReportMarkdown(data) {
   lines.push(`- \u8A2D\u5B9A: ${data.configPath}`);
   lines.push(`- \u7248: ${data.version}`);
   lines.push("");
-  lines.push("## \u6982\u8981");
+  const severityOrder = {
+    error: 0,
+    warning: 1,
+    info: 2
+  };
+  const categoryOrder = {
+    compatibility: 0,
+    change: 1
+  };
+  const issuesByCategory = {
+    compatibility: [],
+    change: []
+  };
+  for (const issue7 of data.issues) {
+    const cat = issue7.category;
+    if (cat === "change") {
+      issuesByCategory.change.push(issue7);
+    } else {
+      issuesByCategory.compatibility.push(issue7);
+    }
+  }
+  const countIssuesBySeverity = (issues) => issues.reduce(
+    (acc, i) => {
+      acc[i.severity] += 1;
+      return acc;
+    },
+    { info: 0, warning: 0, error: 0 }
+  );
+  const compatCounts = countIssuesBySeverity(issuesByCategory.compatibility);
+  const changeCounts = countIssuesBySeverity(issuesByCategory.change);
+  lines.push("## Dashboard");
+  lines.push("");
+  lines.push("### Summary");
   lines.push("");
   lines.push(`- specs: ${data.summary.specs}`);
   lines.push(`- scenarios: ${data.summary.scenarios}`);
@@ -3192,10 +3463,141 @@ function formatReportMarkdown(data) {
     `- contracts: api ${data.summary.contracts.api} / ui ${data.summary.contracts.ui} / db ${data.summary.contracts.db}`
   );
   lines.push(
-    `- issues: info ${data.summary.counts.info} / warning ${data.summary.counts.warning} / error ${data.summary.counts.error}`
+    `- issues(total): info ${data.summary.counts.info} / warning ${data.summary.counts.warning} / error ${data.summary.counts.error}`
+  );
+  lines.push(
+    `- issues(compatibility): info ${compatCounts.info} / warning ${compatCounts.warning} / error ${compatCounts.error}`
+  );
+  lines.push(
+    `- issues(change): info ${changeCounts.info} / warning ${changeCounts.warning} / error ${changeCounts.error}`
+  );
+  lines.push(
+    `- fail-on=error: ${data.summary.counts.error > 0 ? "FAIL" : "PASS"}`
+  );
+  lines.push(
+    `- fail-on=warning: ${data.summary.counts.error + data.summary.counts.warning > 0 ? "FAIL" : "PASS"}`
   );
   lines.push("");
-  lines.push("## ID\u96C6\u8A08");
+  lines.push("### Next Actions");
+  lines.push("");
+  if (data.summary.counts.error > 0) {
+    lines.push(
+      "- error \u304C\u3042\u308B\u305F\u3081\u3001\u307E\u305A `qfai validate --fail-on error` \u3092\u901A\u308B\u307E\u3067\u4FEE\u6B63\u3057\u3066\u304F\u3060\u3055\u3044\u3002"
+    );
+    lines.push(
+      "- \u6B21\u306E\u624B\u9806: `qfai doctor --fail-on error` \u2192 `qfai validate --fail-on error` \u2192 `qfai report`"
+    );
+  } else if (data.summary.counts.warning > 0) {
+    lines.push(
+      "- warning \u306E\u6271\u3044\u306F\u30C1\u30FC\u30E0\u5224\u65AD\u3067\u3059\u3002`--fail-on warning` \u904B\u7528\u306A\u3089\u4FEE\u6B63\u3057\u3066\u304F\u3060\u3055\u3044\u3002"
+    );
+    lines.push(
+      "- \u6B21\u306E\u624B\u9806: `qfai doctor --fail-on error` \u2192 `qfai validate --fail-on error` \u2192 `qfai report`"
+    );
+  } else {
+    lines.push("- issue \u306F\u3042\u308A\u307E\u305B\u3093\u3002\u904B\u7528\u30C6\u30F3\u30D7\u30EC\u306B\u6CBF\u3063\u3066\u7D99\u7D9A\u3057\u3066\u304F\u3060\u3055\u3044\u3002");
+    lines.push(
+      "- \u6B21\u306E\u624B\u9806: `qfai doctor` \u2192 `qfai validate` \u2192 `qfai report`\uFF08\u5B9A\u671F\u7684\u306B\u5B9F\u884C\uFF09"
+    );
+  }
+  lines.push("");
+  lines.push("### Index");
+  lines.push("");
+  lines.push("- [Compatibility Issues](#compatibility-issues)");
+  lines.push("- [Change Issues](#change-issues)");
+  lines.push("- [IDs](#ids)");
+  lines.push("- [Traceability](#traceability)");
+  lines.push("");
+  const formatIssueSummaryTable = (issues) => {
+    const issueKeyToCount = /* @__PURE__ */ new Map();
+    for (const issue7 of issues) {
+      const key = `${issue7.category}|${issue7.severity}|${issue7.code}`;
+      const current = issueKeyToCount.get(key);
+      if (current) {
+        current.count += 1;
+        continue;
+      }
+      issueKeyToCount.set(key, {
+        category: issue7.category,
+        severity: issue7.severity,
+        code: issue7.code,
+        count: 1
+      });
+    }
+    const rows = Array.from(issueKeyToCount.values()).sort((a, b) => {
+      const ca = categoryOrder[a.category] ?? 999;
+      const cb = categoryOrder[b.category] ?? 999;
+      if (ca !== cb) return ca - cb;
+      const sa = severityOrder[a.severity] ?? 999;
+      const sb = severityOrder[b.severity] ?? 999;
+      if (sa !== sb) return sa - sb;
+      return a.code.localeCompare(b.code);
+    }).map((x) => [x.severity, x.code, String(x.count)]);
+    return rows.length === 0 ? ["- (none)"] : formatMarkdownTable(["Severity", "Code", "Count"], rows);
+  };
+  const formatIssueCards = (issues) => {
+    const sorted = [...issues].sort((a, b) => {
+      const sa = severityOrder[a.severity] ?? 999;
+      const sb = severityOrder[b.severity] ?? 999;
+      if (sa !== sb) return sa - sb;
+      const code = a.code.localeCompare(b.code);
+      if (code !== 0) return code;
+      const fileA = a.file ?? "";
+      const fileB = b.file ?? "";
+      const file = fileA.localeCompare(fileB);
+      if (file !== 0) return file;
+      const lineA = a.loc?.line ?? 0;
+      const lineB = b.loc?.line ?? 0;
+      return lineA - lineB;
+    });
+    if (sorted.length === 0) {
+      return ["- (none)"];
+    }
+    const out = [];
+    for (const item of sorted) {
+      out.push(
+        `#### ${item.severity.toUpperCase()} [${item.code}] ${item.message}`
+      );
+      if (item.file) {
+        const loc = item.loc?.line ? `:${item.loc.line}` : "";
+        out.push(`- file: ${item.file}${loc}`);
+      }
+      if (item.rule) {
+        out.push(`- rule: ${item.rule}`);
+      }
+      if (item.refs && item.refs.length > 0) {
+        out.push(`- refs: ${item.refs.join(", ")}`);
+      }
+      if (item.suggested_action) {
+        out.push("- suggested_action:");
+        const actionLines = String(item.suggested_action).split("\n");
+        for (const line of actionLines) {
+          out.push(`  ${line}`);
+        }
+      }
+      out.push("");
+    }
+    return out;
+  };
+  lines.push("## Compatibility Issues");
+  lines.push("");
+  lines.push("### Summary");
+  lines.push("");
+  lines.push(...formatIssueSummaryTable(issuesByCategory.compatibility));
+  lines.push("");
+  lines.push("### Issues");
+  lines.push("");
+  lines.push(...formatIssueCards(issuesByCategory.compatibility));
+  lines.push("## Change Issues");
+  lines.push("");
+  lines.push("### Summary");
+  lines.push("");
+  lines.push(...formatIssueSummaryTable(issuesByCategory.change));
+  lines.push("");
+  lines.push("### Issues");
+  lines.push("");
+  lines.push(...formatIssueCards(issuesByCategory.change));
+  lines.push("## IDs");
   lines.push("");
   lines.push(formatIdLine("SPEC", data.ids.spec));
   lines.push(formatIdLine("BR", data.ids.br));
@@ -3204,14 +3606,14 @@ function formatReportMarkdown(data) {
   lines.push(formatIdLine("API", data.ids.api));
   lines.push(formatIdLine("DB", data.ids.db));
   lines.push("");
-  lines.push("## \u30C8\u30EC\u30FC\u30B5\u30D3\u30EA\u30C6\u30A3");
+  lines.push("## Traceability");
   lines.push("");
   lines.push(`- \u4E0A\u6D41ID\u691C\u51FA\u6570: ${data.traceability.upstreamIdsFound}`);
   lines.push(
     `- \u30B3\u30FC\u30C9/\u30C6\u30B9\u30C8\u53C2\u7167: ${data.traceability.referencedInCodeOrTests ? "\u3042\u308A" : "\u306A\u3057"}`
   );
   lines.push("");
-  lines.push("## \u5951\u7D04\u30AB\u30D0\u30EC\u30C3\u30B8");
+  lines.push("### Contract Coverage");
   lines.push("");
   lines.push(`- total: ${data.traceability.contracts.total}`);
   lines.push(`- referenced: ${data.traceability.contracts.referenced}`);
@@ -3220,7 +3622,7 @@ function formatReportMarkdown(data) {
     `- specContractRefMissing: ${data.traceability.specs.contractRefMissing}`
   );
   lines.push("");
-  lines.push("## \u5951\u7D04\u2192Spec");
+  lines.push("### Contract \u2192 Spec");
   lines.push("");
   const contractToSpecs = data.traceability.contracts.idToSpecs;
   const contractIds = Object.keys(contractToSpecs).sort(
@@ -3239,7 +3641,7 @@ function formatReportMarkdown(data) {
     }
   }
   lines.push("");
-  lines.push("## Spec\u2192\u5951\u7D04");
+  lines.push("### Spec \u2192 Contracts");
   lines.push("");
   const specToContracts = data.traceability.specs.specToContracts;
   const specIds = Object.keys(specToContracts).sort(
@@ -3257,7 +3659,7 @@ function formatReportMarkdown(data) {
     lines.push(...formatMarkdownTable(["Spec", "Status", "Contracts"], rows));
   }
   lines.push("");
-  lines.push("## Spec\u3067 contract-ref \u672A\u5BA3\u8A00");
+  lines.push("### Specs missing contract-ref");
   lines.push("");
   const missingRefSpecs = data.traceability.specs.missingRefSpecs;
   if (missingRefSpecs.length === 0) {
@@ -3268,7 +3670,7 @@ function formatReportMarkdown(data) {
     }
   }
   lines.push("");
-  lines.push("## SC\u30AB\u30D0\u30EC\u30C3\u30B8");
+  lines.push("### SC coverage");
   lines.push("");
   lines.push(`- total: ${data.traceability.sc.total}`);
   lines.push(`- covered: ${data.traceability.sc.covered}`);
@@ -3298,7 +3700,7 @@ function formatReportMarkdown(data) {
     lines.push(`- missingIds: ${missingWithSources.join(", ")}`);
   }
   lines.push("");
-  lines.push("## SC\u2192\u53C2\u7167\u30C6\u30B9\u30C8");
+  lines.push("### SC \u2192 referenced tests");
   lines.push("");
   const scRefs = data.traceability.sc.refs;
   const scIds = Object.keys(scRefs).sort((a, b) => a.localeCompare(b));
@@ -3315,7 +3717,7 @@ function formatReportMarkdown(data) {
     }
   }
   lines.push("");
-  lines.push("## Spec:SC=1:1 \u9055\u53CD");
+  lines.push("### Spec:SC=1:1 violations");
   lines.push("");
   const specScIssues = data.issues.filter(
     (item) => item.code === "QFAI-TRACE-012"
@@ -3330,7 +3732,7 @@ function formatReportMarkdown(data) {
     }
   }
   lines.push("");
-  lines.push("## Hotspots");
+  lines.push("### Hotspots");
   lines.push("");
   const hotspots = buildHotspots(data.issues);
   if (hotspots.length === 0) {
@@ -3343,35 +3745,28 @@ function formatReportMarkdown(data) {
     }
   }
   lines.push("");
-  lines.push("## \u30C8\u30EC\u30FC\u30B5\u30D3\u30EA\u30C6\u30A3\uFF08\u691C\u8A3C\uFF09");
+  lines.push("## Guidance");
   lines.push("");
-  const traceIssues = data.issues.filter(
-    (item) => item.rule?.startsWith("traceability.") || item.code.startsWith("QFAI_TRACE") || item.code.startsWith("QFAI-TRACE-")
+  lines.push(
+    "- \u6B21\u306E\u624B\u9806: `qfai doctor --fail-on error` \u2192 `qfai validate --fail-on error` \u2192 `qfai report`"
   );
-  if (traceIssues.length === 0) {
-    lines.push("- (none)");
-  } else {
-    for (const item of traceIssues) {
-      const location = item.file ? ` (${item.file})` : "";
-      lines.push(
-        `- ${item.severity.toUpperCase()} [${item.code}] ${item.message}${location}`
-      );
-    }
-  }
-  lines.push("");
-  lines.push("## \u691C\u8A3C\u7D50\u679C");
-  lines.push("");
-  if (data.issues.length === 0) {
-    lines.push("- (none)");
+  if (data.summary.counts.error > 0) {
+    lines.push("- error \u304C\u3042\u308B\u305F\u3081\u3001\u307E\u305A error \u304B\u3089\u4FEE\u6B63\u3057\u3066\u304F\u3060\u3055\u3044\u3002");
+  } else if (data.summary.counts.warning > 0) {
+    lines.push(
+      "- warning \u306E\u6271\u3044\uFF08Hard Gate \u306B\u3059\u308B\u304B\uFF09\u306F\u904B\u7528\u3067\u6C7A\u3081\u3066\u304F\u3060\u3055\u3044\u3002"
+    );
   } else {
-    for (const item of data.issues) {
-      const location = item.file ? ` (${item.file})` : "";
-      const refs = item.refs && item.refs.length > 0 ? ` refs=${item.refs.join(",")}` : "";
-      lines.push(
-        `- ${item.severity.toUpperCase()} [${item.code}] ${item.message}${location}${refs}`
-      );
-    }
+    lines.push(
+      "- issue \u306F\u691C\u51FA\u3055\u308C\u307E\u305B\u3093\u3067\u3057\u305F\u3002\u904B\u7528\u30C6\u30F3\u30D7\u30EC\u306B\u6CBF\u3063\u3066\u7D99\u7D9A\u3057\u3066\u304F\u3060\u3055\u3044\u3002"
+    );
   }
+  lines.push(
+    "- \u5909\u66F4\u533A\u5206\uFF08Compatibility / Change/Improvement\uFF09\u306F `.qfai/specs/*/delta.md` \u306B\u8A18\u9332\u3057\u307E\u3059\u3002"
+  );
+  lines.push(
+    "- \u53C2\u7167\u30EB\u30FC\u30EB\u306E\u6B63\u672C: `.qfai/promptpack/steering/traceability.md` / `.qfai/promptpack/steering/compatibility-vs-change.md`"
+  );
   return lines.join("\n");
 }
 function formatReportJson(data) {
@@ -3385,7 +3780,7 @@ async function collectSpecContractRefs(specFiles, contractIdList) {
     idToSpecs.set(contractId, /* @__PURE__ */ new Set());
   }
   for (const file of specFiles) {
-    const text = await readFile11(file, "utf-8");
+    const text = await readFile12(file, "utf-8");
     const parsed = parseSpec(text, file);
     const specKey = parsed.specId;
     if (!specKey) {
@@ -3426,7 +3821,7 @@ async function collectIds(files) {
     DB: /* @__PURE__ */ new Set()
   };
   for (const file of files) {
-    const text = await readFile11(file, "utf-8");
+    const text = await readFile12(file, "utf-8");
     for (const prefix of ID_PREFIXES2) {
       const ids = extractIds(text, prefix);
       ids.forEach((id) => result[prefix].add(id));
@@ -3444,7 +3839,7 @@ async function collectIds(files) {
 async function collectUpstreamIds(files) {
   const ids = /* @__PURE__ */ new Set();
   for (const file of files) {
-    const text = await readFile11(file, "utf-8");
+    const text = await readFile12(file, "utf-8");
     extractAllIds(text).forEach((id) => ids.add(id));
   }
   return ids;
@@ -3465,7 +3860,7 @@ async function evaluateTraceability(upstreamIds, srcRoot, testsRoot) {
   }
   const pattern = buildIdPattern2(Array.from(upstreamIds));
   for (const file of targetFiles) {
-    const text = await readFile11(file, "utf-8");
+    const text = await readFile12(file, "utf-8");
     if (pattern.test(text)) {
       return true;
     }
@@ -3557,7 +3952,7 @@ function buildHotspots(issues) {
 
 // src/cli/commands/report.ts
 async function runReport(options) {
-  const root = path18.resolve(options.root);
+  const root = path19.resolve(options.root);
   const configResult = await loadConfig(root);
   let validation;
   if (options.runValidate) {
@@ -3574,7 +3969,7 @@ async function runReport(options) {
     validation = normalized;
   } else {
     const input = options.inputPath ?? configResult.config.output.validateJsonPath;
-    const inputPath = path18.isAbsolute(input) ? input : path18.resolve(root, input);
+    const inputPath = path19.isAbsolute(input) ? input : path19.resolve(root, input);
     try {
       validation = await readValidationResult(inputPath);
     } catch (err) {
@@ -3600,10 +3995,10 @@ async function runReport(options) {
   const data = await createReportData(root, validation, configResult);
   const output = options.format === "json" ? formatReportJson(data) : formatReportMarkdown(data);
   const outRoot = resolvePath(root, configResult.config, "outDir");
-  const defaultOut = options.format === "json" ? path18.join(outRoot, "report.json") : path18.join(outRoot, "report.md");
+  const defaultOut = options.format === "json" ? path19.join(outRoot, "report.json") : path19.join(outRoot, "report.md");
   const out = options.outPath ?? defaultOut;
-  const outPath = path18.isAbsolute(out) ? out : path18.resolve(root, out);
-  await mkdir3(path18.dirname(outPath), { recursive: true });
+  const outPath = path19.isAbsolute(out) ? out : path19.resolve(root, out);
+  await mkdir3(path19.dirname(outPath), { recursive: true });
   await writeFile2(outPath, `${output}
 `, "utf-8");
   info(
@@ -3612,7 +4007,7 @@ async function runReport(options) {
   info(`wrote report: ${outPath}`);
 }
 async function readValidationResult(inputPath) {
-  const raw = await readFile12(inputPath, "utf-8");
+  const raw = await readFile13(inputPath, "utf-8");
   const parsed = JSON.parse(raw);
   if (!isValidationResult(parsed)) {
     throw new Error(`validate.json \u306E\u5F62\u5F0F\u304C\u4E0D\u6B63\u3067\u3059: ${inputPath}`);
@@ -3668,15 +4063,15 @@ function isMissingFileError5(error2) {
   return record2.code === "ENOENT";
 }
 async function writeValidationResult(root, outputPath, result) {
-  const abs = path18.isAbsolute(outputPath) ? outputPath : path18.resolve(root, outputPath);
-  await mkdir3(path18.dirname(abs), { recursive: true });
+  const abs = path19.isAbsolute(outputPath) ? outputPath : path19.resolve(root, outputPath);
+  await mkdir3(path19.dirname(abs), { recursive: true });
   await writeFile2(abs, `${JSON.stringify(result, null, 2)}
 `, "utf-8");
 }
 
 // src/cli/commands/validate.ts
 import { mkdir as mkdir4, writeFile as writeFile3 } from "fs/promises";
-import path19 from "path";
+import path20 from "path";
 
 // src/cli/lib/failOn.ts
 function shouldFail(result, failOn) {
@@ -3691,10 +4086,12 @@ function shouldFail(result, failOn) {
 
 // src/cli/commands/validate.ts
 async function runValidate(options) {
-  const root = path19.resolve(options.root);
+  const root = path20.resolve(options.root);
   const configResult = await loadConfig(root);
   const result = await validateProject(root, configResult);
   const normalized = normalizeValidationResult(root, result);
+  const failOn = resolveFailOn(options, configResult.config.validation.failOn);
+  const willFail = shouldFail(normalized, failOn);
   const format = options.format ?? "text";
   if (format === "text") {
     emitText(normalized);
@@ -3704,11 +4101,10 @@ async function runValidate(options) {
       root,
       configResult.config.output.validateJsonPath
     );
-    emitGitHubOutput(normalized, root, jsonPath);
+    emitGitHubOutput(normalized, root, jsonPath, { failOn, willFail });
   }
   await emitJson(normalized, root, configResult.config.output.validateJsonPath);
-  const failOn = resolveFailOn(options, configResult.config.validation.failOn);
-  return shouldFail(normalized, failOn) ? 1 : 0;
+  return willFail ? 1 : 0;
 }
 function resolveFailOn(options, fallback) {
   if (options.failOn) {
@@ -3733,7 +4129,7 @@ function emitText(result) {
 `
   );
 }
-function emitGitHubOutput(result, root, jsonPath) {
+function emitGitHubOutput(result, root, jsonPath, status) {
   const deduped = dedupeIssues(result.issues);
   const omitted = Math.max(deduped.length - GITHUB_ANNOTATION_LIMIT, 0);
   const dropped = Math.max(result.issues.length - deduped.length, 0);
@@ -3742,7 +4138,8 @@ function emitGitHubOutput(result, root, jsonPath) {
     omitted,
     dropped,
     jsonPath,
-    root
+    root,
+    ...status
   });
   const issues = deduped.slice(0, GITHUB_ANNOTATION_LIMIT);
   for (const issue7 of issues) {
@@ -3766,7 +4163,9 @@ function emitGitHubSummary(result, options) {
     `error=${result.counts.error}`,
     `warning=${result.counts.warning}`,
     `info=${result.counts.info}`,
-    `annotations=${Math.min(options.total, GITHUB_ANNOTATION_LIMIT)}/${options.total}`
+    `annotations=${Math.min(options.total, GITHUB_ANNOTATION_LIMIT)}/${options.total}`,
+    `failOn=${options.failOn}`,
+    `result=${options.willFail ? "FAIL" : "PASS"}`
   ].join(" ");
   process.stdout.write(`${summary}
 `);
@@ -3784,6 +4183,9 @@ function emitGitHubSummary(result, options) {
     `qfai validate note: \u8A73\u7D30\u306F ${relative} \u307E\u305F\u306F --format text \u3092\u53C2\u7167\u3057\u3066\u304F\u3060\u3055\u3044\u3002
 `
   );
+  process.stdout.write(
+    "qfai validate note: \u6B21\u306F qfai report \u3067 report.md \u3092\u751F\u6210\u3067\u304D\u307E\u3059\uFF08\u4F8B: qfai report\uFF09\u3002\n"
+  );
 }
 function dedupeIssues(issues) {
   const seen = /* @__PURE__ */ new Set();
@@ -3808,12 +4210,12 @@ function issueKey(issue7) {
 }
 async function emitJson(result, root, jsonPath) {
   const abs = resolveJsonPath(root, jsonPath);
-  await mkdir4(path19.dirname(abs), { recursive: true });
+  await mkdir4(path20.dirname(abs), { recursive: true });
   await writeFile3(abs, `${JSON.stringify(result, null, 2)}
 `, "utf-8");
 }
 function resolveJsonPath(root, jsonPath) {
-  return path19.isAbsolute(jsonPath) ? jsonPath : path19.resolve(root, jsonPath);
+  return path20.isAbsolute(jsonPath) ? jsonPath : path20.resolve(root, jsonPath);
 }
 var GITHUB_ANNOTATION_LIMIT = 100;