qfai 0.7.2 → 0.8.1

package/dist/index.mjs

@@ -368,6 +368,7 @@ function configIssue(file, message) {
   return {
     code: "QFAI_CONFIG_INVALID",
     severity: "error",
+    category: "compatibility",
     message,
     file,
     rule: "config.invalid"
@@ -451,8 +452,8 @@ function isValidId(value, prefix) {
 }
 
 // src/core/report.ts
-import { readFile as readFile11 } from "fs/promises";
-import path12 from "path";
+import { readFile as readFile12 } from "fs/promises";
+import path14 from "path";
 
 // src/core/contractIndex.ts
 import { readFile as readFile2 } from "fs/promises";
@@ -1179,8 +1180,8 @@ import { readFile as readFile4 } from "fs/promises";
 import path7 from "path";
 import { fileURLToPath } 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();
@@ -1491,12 +1492,16 @@ function formatError4(error) {
   }
   return String(error);
 }
-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;
   }
@@ -1551,7 +1556,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"
@@ -1581,12 +1586,16 @@ function isMissingFileError2(error) {
   }
   return error.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;
   }
@@ -1671,12 +1680,16 @@ function formatFileList(files, root) {
     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;
   }
@@ -1689,8 +1702,164 @@ function issue3(code, message, severity, file, rule, refs) {
   return issue7;
 }
 
-// src/core/validators/scenario.ts
+// src/core/promptsIntegrity.ts
 import { readFile as readFile8 } from "fs/promises";
+import path13 from "path";
+
+// src/shared/assets.ts
+import { existsSync } from "fs";
+import path12 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 = path12.dirname(basePath);
+  const candidates = [
+    path12.resolve(baseDir, "../../../assets/init"),
+    path12.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 = path13.resolve(root, ".qfai", "prompts");
+  let templateDir;
+  try {
+    templateDir = path13.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([
+        readFile8(templateAbs, "utf-8"),
+        readFile8(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 = path13.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/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 readFile9 } from "fs/promises";
 var GIVEN_PATTERN = /\bGiven\b/;
 var WHEN_PATTERN = /\bWhen\b/;
 var THEN_PATTERN = /\bThen\b/;
@@ -1716,7 +1885,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 (error) {
       if (isMissingFileError3(error)) {
         issues.push(
@@ -1861,12 +2030,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;
   }
@@ -1886,7 +2059,7 @@ function isMissingFileError3(error) {
 }
 
 // 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);
@@ -1907,7 +2080,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 (error) {
       if (isMissingFileError4(error)) {
         issues.push(
@@ -2031,12 +2204,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;
   }
@@ -2056,7 +2233,7 @@ function isMissingFileError4(error) {
 }
 
 // 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) {
@@ -2076,7 +2253,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) {
@@ -2094,7 +2271,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"
@@ -2105,7 +2282,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"
@@ -2118,7 +2295,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",
@@ -2149,7 +2326,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
@@ -2158,7 +2335,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"
@@ -2169,7 +2346,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"
@@ -2182,7 +2359,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",
@@ -2471,7 +2648,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;
@@ -2494,12 +2671,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;
   }
@@ -2518,6 +2699,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),
@@ -2558,15 +2740,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 = path12.resolve(root);
+  const resolvedRoot = path14.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 = path12.join(contractsRoot, "api");
-  const uiRoot = path12.join(contractsRoot, "ui");
-  const dbRoot = path12.join(contractsRoot, "db");
+  const apiRoot = path14.join(contractsRoot, "api");
+  const uiRoot = path14.join(contractsRoot, "ui");
+  const dbRoot = path14.join(contractsRoot, "db");
   const srcRoot = resolvePath(resolvedRoot, config, "srcDir");
   const testsRoot = resolvePath(resolvedRoot, config, "testsDir");
   const specFiles = await collectSpecFiles(specsRoot);
@@ -2680,7 +2862,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}`);
@@ -2688,10 +2902,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));
@@ -2700,14 +3045,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}`);
@@ -2716,7 +3061,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(
@@ -2735,7 +3080,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(
@@ -2753,7 +3098,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) {
@@ -2764,7 +3109,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}`);
@@ -2794,7 +3139,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));
@@ -2811,7 +3156,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"
@@ -2826,7 +3171,7 @@ function formatReportMarkdown(data) {
     }
   }
   lines.push("");
-  lines.push("## Hotspots");
+  lines.push("### Hotspots");
   lines.push("");
   const hotspots = buildHotspots(data.issues);
   if (hotspots.length === 0) {
@@ -2839,35 +3184,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) {
@@ -2881,7 +3219,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) {
@@ -2922,7 +3260,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));
@@ -2940,7 +3278,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;
@@ -2961,7 +3299,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;
     }