qfai 1.0.6 → 1.1.0

package/dist/cli/index.mjs

@@ -2,11 +2,11 @@
 
 // src/cli/commands/doctor.ts
 import { mkdir, writeFile } from "fs/promises";
-import path11 from "path";
+import path12 from "path";
 
 // src/core/doctor.ts
 import { access as access4 } from "fs/promises";
-import path10 from "path";
+import path11 from "path";
 
 // src/core/config.ts
 import { access, readFile } from "fs/promises";
@@ -24,15 +24,7 @@ var defaultConfig = {
   validation: {
     failOn: "error",
     require: {
-      specSections: [
-        "\u80CC\u666F",
-        "\u30B9\u30B3\u30FC\u30D7",
-        "\u975E\u30B4\u30FC\u30EB",
-        "\u7528\u8A9E",
-        "\u524D\u63D0",
-        "\u6C7A\u5B9A\u4E8B\u9805",
-        "\u696D\u52D9\u30EB\u30FC\u30EB"
-      ]
+      specSections: []
     },
     traceability: {
       brMustHaveSc: true,
@@ -1056,8 +1048,8 @@ import { readFile as readFile4 } from "fs/promises";
 import path9 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 async function resolveToolVersion() {
-  if ("1.0.6".length > 0) {
-    return "1.0.6";
+  if ("1.1.0".length > 0) {
+    return "1.1.0";
   }
   try {
     const packagePath = resolvePackageJsonPath();
@@ -1075,6 +1067,460 @@ function resolvePackageJsonPath() {
   return path9.resolve(path9.dirname(basePath), "../../package.json");
 }
 
+// src/core/decisionGuardrails.ts
+import { readFile as readFile5, stat } from "fs/promises";
+import path10 from "path";
+
+// src/core/parse/markdown.ts
+var HEADING_RE = /^(#{1,6})\s+(.+?)\s*$/;
+function parseHeadings(md) {
+  const lines = md.split(/\r?\n/);
+  const headings = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const match = line.match(HEADING_RE);
+    if (!match) continue;
+    const levelToken = match[1];
+    const title = match[2];
+    if (!levelToken || !title) continue;
+    headings.push({
+      level: levelToken.length,
+      title: title.trim(),
+      line: i + 1
+    });
+  }
+  return headings;
+}
+function extractH2Sections(md) {
+  const lines = md.split(/\r?\n/);
+  const headings = parseHeadings(md).filter((heading) => heading.level === 2);
+  const sections = /* @__PURE__ */ new Map();
+  for (let i = 0; i < headings.length; i++) {
+    const current = headings[i];
+    if (!current) continue;
+    const next = headings[i + 1];
+    const startLine = current.line + 1;
+    const endLine = (next?.line ?? lines.length + 1) - 1;
+    const body = startLine <= endLine ? lines.slice(startLine - 1, endLine).join("\n") : "";
+    sections.set(current.title.trim(), {
+      title: current.title.trim(),
+      startLine,
+      endLine,
+      body
+    });
+  }
+  return sections;
+}
+
+// src/core/decisionGuardrails.ts
+var DEFAULT_DECISION_GUARDRAILS_GLOBS = [".qfai/specs/**/delta.md"];
+var DEFAULT_GUARDRAILS_IGNORE_GLOBS = [
+  "**/node_modules/**",
+  "**/.git/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/.pnpm/**",
+  "**/tmp/**",
+  "**/.mcp-tools/**"
+];
+var SECTION_TITLE = "decision guardrails";
+var ENTRY_START_RE = /^\s*[-*]\s+ID:\s*(.+?)\s*$/i;
+var FIELD_RE = /^\s{2,}([A-Za-z][A-Za-z0-9 _-]*):\s*(.*)$/;
+var CONTINUATION_RE = /^\s{4,}(.+)$/;
+var ID_FORMAT_RE = /^DG-\d{4}$/;
+var TYPE_ORDER = {
+  "non-goal": 0,
+  "not-now": 1,
+  "trade-off": 2
+};
+async function loadDecisionGuardrails(root, options = {}) {
+  const errors = [];
+  const files = await scanDecisionGuardrailFiles(
+    root,
+    options.paths,
+    errors,
+    options.specsRoot
+  );
+  const entries = [];
+  for (const filePath of files) {
+    try {
+      const content = await readFile5(filePath, "utf-8");
+      const parsed = extractDecisionGuardrailsFromMarkdown(content, filePath);
+      entries.push(...parsed);
+    } catch (error2) {
+      errors.push({ path: filePath, message: String(error2) });
+    }
+  }
+  return { entries, errors, files };
+}
+function extractDecisionGuardrailsFromMarkdown(markdown, filePath) {
+  const sections = extractH2Sections(markdown);
+  const section = findDecisionGuardrailsSection(sections);
+  if (!section) {
+    return [];
+  }
+  const lines = section.body.split(/\r?\n/);
+  const entries = [];
+  let current = null;
+  const flush = () => {
+    if (!current) {
+      return;
+    }
+    const entry = {
+      keywords: current.keywords,
+      source: { file: filePath, line: current.startLine },
+      ...current.fields.id ? { id: current.fields.id } : {},
+      ...current.fields.type ? { type: current.fields.type } : {},
+      ...current.fields.guardrail ? { guardrail: current.fields.guardrail } : {},
+      ...current.fields.rationale ? { rationale: current.fields.rationale } : {},
+      ...current.fields.reconsider ? { reconsider: current.fields.reconsider } : {},
+      ...current.fields.related ? { related: current.fields.related } : {},
+      ...current.fields.title ? { title: current.fields.title } : {}
+    };
+    entries.push(entry);
+    current = null;
+  };
+  for (let i = 0; i < lines.length; i += 1) {
+    const rawLine = lines[i] ?? "";
+    const lineNumber = section.startLine + i;
+    const entryMatch = rawLine.match(ENTRY_START_RE);
+    if (entryMatch) {
+      flush();
+      const id = entryMatch[1]?.trim() ?? "";
+      current = {
+        startLine: lineNumber,
+        fields: { id },
+        keywords: []
+      };
+      continue;
+    }
+    if (!current) {
+      continue;
+    }
+    const fieldMatch = rawLine.match(FIELD_RE);
+    if (fieldMatch) {
+      const rawKey = fieldMatch[1] ?? "";
+      const value = fieldMatch[2] ?? "";
+      const key = normalizeFieldKey(rawKey);
+      if (key) {
+        if (key === "keywords") {
+          current.keywords.push(
+            ...value.split(",").map((item) => item.trim()).filter((item) => item.length > 0)
+          );
+        } else {
+          const trimmed = value.trim();
+          if (trimmed.length > 0) {
+            const existing = current.fields[key];
+            current.fields[key] = existing ? `${existing}
+${trimmed}` : trimmed;
+          }
+        }
+        current.lastKey = key;
+      } else {
+        delete current.lastKey;
+      }
+      continue;
+    }
+    const continuationMatch = rawLine.match(CONTINUATION_RE);
+    if (continuationMatch && current.lastKey) {
+      const value = continuationMatch[1]?.trim() ?? "";
+      if (value.length > 0) {
+        const existing = current.fields[current.lastKey];
+        current.fields[current.lastKey] = existing ? `${existing}
+${value}` : value;
+      }
+    }
+  }
+  flush();
+  return entries;
+}
+function normalizeDecisionGuardrails(entries) {
+  const items = [];
+  for (const entry of entries) {
+    const id = entry.id?.trim();
+    const type = normalizeGuardrailType(entry.type);
+    const guardrail = entry.guardrail?.trim();
+    if (!id || !type || !guardrail) {
+      continue;
+    }
+    const item = {
+      id,
+      type,
+      guardrail,
+      keywords: entry.keywords?.filter((word) => word.length > 0) ?? [],
+      source: entry.source
+    };
+    const rationale = entry.rationale?.trim();
+    if (rationale) {
+      item.rationale = rationale;
+    }
+    const reconsider = entry.reconsider?.trim();
+    if (reconsider) {
+      item.reconsider = reconsider;
+    }
+    const related = entry.related?.trim();
+    if (related) {
+      item.related = related;
+    }
+    const title = entry.title?.trim();
+    if (title) {
+      item.title = title;
+    }
+    items.push(item);
+  }
+  return items;
+}
+function sortDecisionGuardrails(items) {
+  return [...items].sort((a, b) => {
+    const typeOrder = (TYPE_ORDER[a.type] ?? 999) - (TYPE_ORDER[b.type] ?? 999);
+    if (typeOrder !== 0) {
+      return typeOrder;
+    }
+    return a.id.localeCompare(b.id);
+  });
+}
+function filterDecisionGuardrailsByKeyword(items, keyword) {
+  const needle = keyword?.trim().toLowerCase();
+  if (!needle) {
+    return items;
+  }
+  return items.filter((item) => {
+    const haystack = [
+      item.title,
+      item.guardrail,
+      item.rationale,
+      item.related,
+      item.keywords.join(" ")
+    ].filter((value) => Boolean(value)).map((value) => value.toLowerCase());
+    return haystack.some((value) => value.includes(needle));
+  });
+}
+function formatGuardrailsForLlm(items, max) {
+  const limit = Math.max(0, Math.floor(max));
+  const lines = ["# Decision Guardrails (extract)", ""];
+  const slice = limit > 0 ? items.slice(0, limit) : [];
+  if (slice.length === 0) {
+    lines.push("- (none)");
+    return lines.join("\n");
+  }
+  for (const item of slice) {
+    lines.push(`- [${item.id}][${item.type}] ${item.guardrail}`);
+    if (item.rationale) {
+      lines.push(`  Rationale: ${item.rationale}`);
+    }
+    if (item.reconsider) {
+      lines.push(`  Reconsider: ${item.reconsider}`);
+    }
+    if (item.related) {
+      lines.push(`  Related: ${item.related}`);
+    }
+  }
+  return lines.join("\n");
+}
+function checkDecisionGuardrails(entries) {
+  const errors = [];
+  const warnings = [];
+  const idMap = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const file = entry.source.file;
+    const line = entry.source.line;
+    const id = entry.id?.trim();
+    const typeRaw = entry.type?.trim();
+    const guardrail = entry.guardrail?.trim();
+    const rationale = entry.rationale?.trim();
+    const reconsider = entry.reconsider?.trim();
+    if (!id) {
+      errors.push({
+        severity: "error",
+        code: "QFAI-GR-001",
+        message: "ID is missing",
+        file,
+        line
+      });
+    } else {
+      const list = idMap.get(id) ?? [];
+      list.push(entry);
+      idMap.set(id, list);
+      if (!ID_FORMAT_RE.test(id)) {
+        warnings.push({
+          severity: "warning",
+          code: "QFAI-GR-002",
+          message: `ID format is not standard: ${id}`,
+          file,
+          line,
+          id
+        });
+      }
+    }
+    if (!typeRaw) {
+      errors.push({
+        severity: "error",
+        code: "QFAI-GR-003",
+        message: "Type is missing",
+        file,
+        line,
+        ...id ? { id } : {}
+      });
+    } else if (!normalizeGuardrailType(typeRaw)) {
+      errors.push({
+        severity: "error",
+        code: "QFAI-GR-004",
+        message: `Type is invalid: ${typeRaw}`,
+        file,
+        line,
+        ...id ? { id } : {}
+      });
+    }
+    if (!guardrail) {
+      errors.push({
+        severity: "error",
+        code: "QFAI-GR-005",
+        message: "Guardrail is missing",
+        file,
+        line,
+        ...id ? { id } : {}
+      });
+    }
+    if (!rationale) {
+      warnings.push({
+        severity: "warning",
+        code: "QFAI-GR-006",
+        message: "Rationale is missing",
+        file,
+        line,
+        ...id ? { id } : {}
+      });
+    }
+    if (!reconsider) {
+      warnings.push({
+        severity: "warning",
+        code: "QFAI-GR-007",
+        message: "Reconsider is missing",
+        file,
+        line,
+        ...id ? { id } : {}
+      });
+    }
+  }
+  for (const [id, list] of idMap.entries()) {
+    if (list.length > 1) {
+      const locations = list.map((entry) => `${entry.source.file}:${entry.source.line}`).join(", ");
+      const first = list[0];
+      const file = first?.source.file ?? "";
+      const line = first?.source.line;
+      errors.push({
+        severity: "error",
+        code: "QFAI-GR-008",
+        message: `ID is duplicated: ${id} (${locations})`,
+        file,
+        ...line !== void 0 ? { line } : {},
+        id
+      });
+    }
+  }
+  return { errors, warnings };
+}
+function normalizeGuardrailType(raw) {
+  if (!raw) {
+    return null;
+  }
+  const normalized = raw.trim().toLowerCase().replace(/[_\s]+/g, "-");
+  if (normalized === "non-goal") {
+    return "non-goal";
+  }
+  if (normalized === "not-now") {
+    return "not-now";
+  }
+  if (normalized === "trade-off") {
+    return "trade-off";
+  }
+  return null;
+}
+function normalizeFieldKey(raw) {
+  const normalized = raw.trim().toLowerCase().replace(/[_\s-]+/g, "");
+  switch (normalized) {
+    case "id":
+      return "id";
+    case "type":
+      return "type";
+    case "guardrail":
+      return "guardrail";
+    case "rationale":
+    case "reason":
+      return "rationale";
+    case "reconsider":
+      return "reconsider";
+    case "related":
+      return "related";
+    case "keywords":
+    case "keyword":
+      return "keywords";
+    case "title":
+    case "heading":
+      return "title";
+    default:
+      return null;
+  }
+}
+async function scanDecisionGuardrailFiles(root, rawPaths, errors, specsRoot) {
+  if (!rawPaths || rawPaths.length === 0) {
+    const scanRoot = specsRoot ? path10.isAbsolute(specsRoot) ? specsRoot : path10.resolve(root, specsRoot) : root;
+    const globs = specsRoot ? ["**/delta.md"] : DEFAULT_DECISION_GUARDRAILS_GLOBS;
+    try {
+      const result = await collectFilesByGlobs(scanRoot, {
+        globs,
+        ignore: DEFAULT_GUARDRAILS_IGNORE_GLOBS
+      });
+      return result.files.sort((a, b) => a.localeCompare(b));
+    } catch (error2) {
+      errors.push({ path: scanRoot, message: String(error2) });
+      return [];
+    }
+  }
+  const files = /* @__PURE__ */ new Set();
+  for (const rawPath of rawPaths) {
+    const resolved = path10.isAbsolute(rawPath) ? rawPath : path10.resolve(root, rawPath);
+    const stats = await safeStat(resolved);
+    if (!stats) {
+      errors.push({ path: resolved, message: "Path does not exist" });
+      continue;
+    }
+    if (stats.isFile()) {
+      files.add(resolved);
+      continue;
+    }
+    if (stats.isDirectory()) {
+      try {
+        const result = await collectFilesByGlobs(resolved, {
+          globs: ["**/delta.md"],
+          ignore: DEFAULT_GUARDRAILS_IGNORE_GLOBS
+        });
+        result.files.forEach((file) => files.add(file));
+      } catch (error2) {
+        errors.push({ path: resolved, message: String(error2) });
+      }
+      continue;
+    }
+    errors.push({ path: resolved, message: "Unsupported path type" });
+  }
+  return Array.from(files).sort((a, b) => a.localeCompare(b));
+}
+async function safeStat(target) {
+  try {
+    return await stat(target);
+  } catch {
+    return null;
+  }
+}
+function findDecisionGuardrailsSection(sections) {
+  for (const [title, section] of sections.entries()) {
+    if (title.trim().toLowerCase() === SECTION_TITLE) {
+      return section;
+    }
+  }
+  return null;
+}
+
 // src/core/doctor.ts
 async function exists4(target) {
   try {
@@ -1098,7 +1544,7 @@ function normalizeGlobs2(values) {
   return values.map((glob) => glob.trim()).filter((glob) => glob.length > 0);
 }
 async function createDoctorData(options) {
-  const startDir = path10.resolve(options.startDir);
+  const startDir = path11.resolve(options.startDir);
   const checks = [];
   const configPath = getConfigPath(startDir);
   const search = options.rootExplicit ? {
@@ -1160,9 +1606,9 @@ async function createDoctorData(options) {
       details: { path: toRelativePath(root, resolved) }
     });
     if (key === "promptsDir") {
-      const promptsLocalDir = path10.join(
-        path10.dirname(resolved),
-        `${path10.basename(resolved)}.local`
+      const promptsLocalDir = path11.join(
+        path11.dirname(resolved),
+        `${path11.basename(resolved)}.local`
       );
       const found = await exists4(promptsLocalDir);
       addCheck(checks, {
@@ -1235,7 +1681,36 @@ 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 = path10.isAbsolute(config.output.validateJsonPath) ? config.output.validateJsonPath : path10.resolve(root, config.output.validateJsonPath);
+  const guardrailsLoad = await loadDecisionGuardrails(root, {
+    specsRoot
+  });
+  const guardrailsItems = normalizeDecisionGuardrails(guardrailsLoad.entries);
+  let guardrailsSeverity;
+  let guardrailsMessage;
+  if (guardrailsLoad.errors.length > 0) {
+    guardrailsSeverity = "warning";
+    guardrailsMessage = `Decision Guardrails scan failed (errors=${guardrailsLoad.errors.length})`;
+  } else if (guardrailsItems.length === 0) {
+    guardrailsSeverity = "info";
+    guardrailsMessage = "Decision Guardrails not found (optional)";
+  } else {
+    guardrailsSeverity = "ok";
+    guardrailsMessage = `Decision Guardrails detected (count=${guardrailsItems.length})`;
+  }
+  addCheck(checks, {
+    id: "guardrails.present",
+    severity: guardrailsSeverity,
+    title: "Decision Guardrails",
+    message: guardrailsMessage,
+    details: {
+      count: guardrailsItems.length,
+      errors: guardrailsLoad.errors.map((item) => ({
+        path: toRelativePath(root, item.path),
+        message: item.message
+      }))
+    }
+  });
+  const validateJsonAbs = path11.isAbsolute(config.output.validateJsonPath) ? config.output.validateJsonPath : path11.resolve(root, config.output.validateJsonPath);
   const validateJsonExists = await exists4(validateJsonAbs);
   addCheck(checks, {
     id: "output.validateJson",
@@ -1245,8 +1720,8 @@ async function createDoctorData(options) {
     details: { path: toRelativePath(root, validateJsonAbs) }
   });
   const outDirAbs = resolvePath(root, config, "outDir");
-  const rel = path10.relative(outDirAbs, validateJsonAbs);
-  const inside = rel !== "" && !rel.startsWith("..") && !path10.isAbsolute(rel);
+  const rel = path11.relative(outDirAbs, validateJsonAbs);
+  const inside = rel !== "" && !rel.startsWith("..") && !path11.isAbsolute(rel);
   addCheck(checks, {
     id: "output.pathAlignment",
     severity: inside ? "ok" : "warning",
@@ -1369,12 +1844,12 @@ async function detectOutDirCollisions(root) {
   });
   const configPaths = configScan.files;
   const configRoots = Array.from(
-    new Set(configPaths.map((configPath) => path10.dirname(configPath)))
+    new Set(configPaths.map((configPath) => path11.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 = path10.normalize(resolvePath(configRoot, config, "outDir"));
+    const outDir = path11.normalize(resolvePath(configRoot, config, "outDir"));
     const roots = outDirToRoots.get(outDir) ?? /* @__PURE__ */ new Set();
     roots.add(configRoot);
     outDirToRoots.set(outDir, roots);
@@ -1400,20 +1875,20 @@ async function detectOutDirCollisions(root) {
   };
 }
 async function findMonorepoRoot(startDir) {
-  let current = path10.resolve(startDir);
+  let current = path11.resolve(startDir);
   while (true) {
-    const gitPath = path10.join(current, ".git");
-    const workspacePath = path10.join(current, "pnpm-workspace.yaml");
+    const gitPath = path11.join(current, ".git");
+    const workspacePath = path11.join(current, "pnpm-workspace.yaml");
     if (await exists4(gitPath) || await exists4(workspacePath)) {
       return current;
     }
-    const parent = path10.dirname(current);
+    const parent = path11.dirname(current);
     if (parent === current) {
       break;
     }
     current = parent;
   }
-  return path10.resolve(startDir);
+  return path11.resolve(startDir);
 }
 
 // src/cli/lib/logger.ts
@@ -1455,8 +1930,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 = path11.isAbsolute(options.outPath) ? options.outPath : path11.resolve(process.cwd(), options.outPath);
-    await mkdir(path11.dirname(outAbs), { recursive: true });
+    const outAbs = path12.isAbsolute(options.outPath) ? options.outPath : path12.resolve(process.cwd(), options.outPath);
+    await mkdir(path12.dirname(outAbs), { recursive: true });
     await writeFile(outAbs, `${output}
 `, "utf-8");
     info(`doctor: wrote ${outAbs}`);
@@ -1475,12 +1950,77 @@ function shouldFailDoctor(summary, failOn) {
   return summary.warning + summary.error > 0;
 }
 
-// src/cli/commands/init.ts
+// src/cli/commands/guardrails.ts
 import path13 from "path";
+var DEFAULT_EXTRACT_MAX = 20;
+async function runGuardrails(options) {
+  if (!options.action) {
+    error("guardrails: action is required (list|extract|check)");
+    return 2;
+  }
+  const root = path13.resolve(options.root);
+  const { entries, errors } = await loadDecisionGuardrails(root, {
+    paths: options.paths
+  });
+  if (errors.length > 0) {
+    errors.forEach((item) => {
+      error(`guardrails: ${item.path}: ${item.message}`);
+    });
+    return 2;
+  }
+  if (options.action === "check") {
+    return runGuardrailsCheck(entries, root);
+  }
+  const items = sortDecisionGuardrails(normalizeDecisionGuardrails(entries));
+  const filtered = filterDecisionGuardrailsByKeyword(items, options.keyword);
+  if (options.action === "extract") {
+    const max = options.max !== void 0 ? options.max : DEFAULT_EXTRACT_MAX;
+    if (!Number.isFinite(max) || max < 0) {
+      error("guardrails: --max must be a non-negative number");
+      return 2;
+    }
+    info(formatGuardrailsForLlm(filtered, max));
+    return 0;
+  }
+  info(formatGuardrailsList(filtered, root));
+  return 0;
+}
+function formatGuardrailsList(items, root) {
+  const lines = ["# Decision Guardrails (list)", ""];
+  if (items.length === 0) {
+    lines.push("- (none)");
+    return lines.join("\n");
+  }
+  for (const item of items) {
+    const relPath = toRelativePath(root, item.source.file);
+    const location = `${relPath}:${item.source.line}`;
+    lines.push(`- [${item.id}][${item.type}] ${item.guardrail} (${location})`);
+  }
+  return lines.join("\n");
+}
+function runGuardrailsCheck(entries, root) {
+  const result = checkDecisionGuardrails(entries);
+  const lines = [
+    `guardrails check: error=${result.errors.length} warning=${result.warnings.length}`
+  ];
+  const formatIssue = (issue7) => {
+    const relPath = toRelativePath(root, issue7.file);
+    const line = issue7.line ? `:${issue7.line}` : "";
+    const id = issue7.id ? ` id=${issue7.id}` : "";
+    return `[${issue7.severity}] ${issue7.code} ${issue7.message} (${relPath}${line})${id}`;
+  };
+  result.errors.forEach((issue7) => lines.push(formatIssue(issue7)));
+  result.warnings.forEach((issue7) => lines.push(formatIssue(issue7)));
+  info(lines.join("\n"));
+  return result.errors.length > 0 ? 1 : 0;
+}
+
+// src/cli/commands/init.ts
+import path15 from "path";
 
 // src/cli/lib/fs.ts
 import { access as access5, copyFile, mkdir as mkdir2, readdir as readdir3 } from "fs/promises";
-import path12 from "path";
+import path14 from "path";
 async function copyTemplateTree(sourceRoot, destRoot, options) {
   const files = await collectTemplateFiles(sourceRoot);
   return copyFiles(files, sourceRoot, destRoot, options);
@@ -1488,7 +2028,7 @@ async function copyTemplateTree(sourceRoot, destRoot, options) {
 async function copyTemplatePaths(sourceRoot, destRoot, relativePaths, options) {
   const allFiles = [];
   for (const relPath of relativePaths) {
-    const fullPath = path12.join(sourceRoot, relPath);
+    const fullPath = path14.join(sourceRoot, relPath);
     const files = await collectTemplateFiles(fullPath);
     allFiles.push(...files);
   }
@@ -1498,13 +2038,13 @@ 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 + path12.sep);
-  const excludePrefixes = (options.exclude ?? []).map((p) => p.replace(/^[\\/]+/, "").replace(/[\\/]+$/, "")).filter((p) => p.length > 0).map((p) => p + path12.sep);
+  const protectPrefixes = (options.protect ?? []).map((p) => p.replace(/^[\\/]+/, "").replace(/[\\/]+$/, "")).filter((p) => p.length > 0).map((p) => p + path14.sep);
+  const excludePrefixes = (options.exclude ?? []).map((p) => p.replace(/^[\\/]+/, "").replace(/[\\/]+$/, "")).filter((p) => p.length > 0).map((p) => p + path14.sep);
   const isProtectedRelative = (relative) => {
     if (protectPrefixes.length === 0) {
       return false;
     }
-    const normalized = relative.replace(/[\\/]+/g, path12.sep);
+    const normalized = relative.replace(/[\\/]+/g, path14.sep);
     return protectPrefixes.some(
       (prefix) => normalized === prefix.slice(0, -1) || normalized.startsWith(prefix)
     );
@@ -1513,7 +2053,7 @@ async function copyFiles(files, sourceRoot, destRoot, options) {
     if (excludePrefixes.length === 0) {
       return false;
     }
-    const normalized = relative.replace(/[\\/]+/g, path12.sep);
+    const normalized = relative.replace(/[\\/]+/g, path14.sep);
     return excludePrefixes.some(
       (prefix) => normalized === prefix.slice(0, -1) || normalized.startsWith(prefix)
     );
@@ -1521,14 +2061,14 @@ async function copyFiles(files, sourceRoot, destRoot, options) {
   const conflictPolicy = options.conflictPolicy ?? "error";
   if (!options.force && conflictPolicy === "error") {
     for (const file of files) {
-      const relative = path12.relative(sourceRoot, file);
+      const relative = path14.relative(sourceRoot, file);
       if (isExcludedRelative(relative)) {
         continue;
       }
       if (isProtectedRelative(relative)) {
         continue;
       }
-      const dest = path12.join(destRoot, relative);
+      const dest = path14.join(destRoot, relative);
       if (!await shouldWrite(dest, options.force)) {
         conflicts.push(dest);
       }
@@ -1538,18 +2078,18 @@ async function copyFiles(files, sourceRoot, destRoot, options) {
     }
   }
   for (const file of files) {
-    const relative = path12.relative(sourceRoot, file);
+    const relative = path14.relative(sourceRoot, file);
     if (isExcludedRelative(relative)) {
       continue;
     }
-    const dest = path12.join(destRoot, relative);
+    const dest = path14.join(destRoot, relative);
     const forceForThisFile = isProtectedRelative(relative) ? false : options.force;
     if (!await shouldWrite(dest, forceForThisFile)) {
       skipped.push(dest);
       continue;
     }
     if (!options.dryRun) {
-      await mkdir2(path12.dirname(dest), { recursive: true });
+      await mkdir2(path14.dirname(dest), { recursive: true });
       await copyFile(file, dest);
     }
     copied.push(dest);
@@ -1573,7 +2113,7 @@ async function collectTemplateFiles(root) {
   }
   const items = await readdir3(root, { withFileTypes: true });
   for (const item of items) {
-    const fullPath = path12.join(root, item.name);
+    const fullPath = path14.join(root, item.name);
     if (item.isDirectory()) {
       const nested = await collectTemplateFiles(fullPath);
       entries.push(...nested);
@@ -1603,10 +2143,10 @@ async function exists5(target) {
 // src/cli/commands/init.ts
 async function runInit(options) {
   const assetsRoot = getInitAssetsDir();
-  const rootAssets = path13.join(assetsRoot, "root");
-  const qfaiAssets = path13.join(assetsRoot, ".qfai");
-  const destRoot = path13.resolve(options.dir);
-  const destQfai = path13.join(destRoot, ".qfai");
+  const rootAssets = path15.join(assetsRoot, "root");
+  const qfaiAssets = path15.join(assetsRoot, ".qfai");
+  const destRoot = path15.resolve(options.dir);
+  const destQfai = path15.join(destRoot, ".qfai");
   if (options.force) {
     info(
       "NOTE: --force \u306F .qfai/assistant/prompts/** \u306E\u307F\u4E0A\u66F8\u304D\u3057\u307E\u3059\uFF08prompts.local \u306F\u4FDD\u8B77\u3055\u308C\u3001specs/contracts \u7B49\u306F\u4E0A\u66F8\u304D\u3057\u307E\u305B\u3093\uFF09\u3002"
@@ -1639,22 +2179,28 @@ async function runInit(options) {
     [...rootResult.copied, ...qfaiResult.copied, ...promptsResult.copied],
     [...rootResult.skipped, ...qfaiResult.skipped, ...promptsResult.skipped],
     options.dryRun,
-    "init"
+    "init",
+    destRoot
   );
 }
-function report(copied, skipped, dryRun, label) {
+function report(copied, skipped, dryRun, label, baseDir) {
   info(`qfai ${label}: ${dryRun ? "dry-run" : "done"}`);
   if (copied.length > 0) {
     info(`  created: ${copied.length}`);
   }
   if (skipped.length > 0) {
     info(`  skipped: ${skipped.length}`);
+    info("  skipped paths:");
+    for (const skippedPath of skipped) {
+      const relative = path15.relative(baseDir, skippedPath);
+      info(`    - ${relative}`);
+    }
   }
 }
 
 // src/cli/commands/report.ts
-import { mkdir as mkdir3, readFile as readFile13, writeFile as writeFile2 } from "fs/promises";
-import path21 from "path";
+import { mkdir as mkdir3, readFile as readFile14, writeFile as writeFile2 } from "fs/promises";
+import path23 from "path";
 
 // src/core/normalize.ts
 function normalizeIssuePaths(root, issues) {
@@ -1694,12 +2240,12 @@ function normalizeValidationResult(root, result) {
 }
 
 // src/core/report.ts
-import { readFile as readFile12 } from "fs/promises";
-import path20 from "path";
+import { readFile as readFile13 } from "fs/promises";
+import path22 from "path";
 
 // src/core/contractIndex.ts
-import { readFile as readFile5 } from "fs/promises";
-import path14 from "path";
+import { readFile as readFile6 } from "fs/promises";
+import path16 from "path";
 
 // src/core/contractsDecl.ts
 var CONTRACT_DECLARATION_RE = /^\s*(?:#|\/\/|--|\/\*+|\*+)?\s*QFAI-CONTRACT-ID:\s*((?:API|UI|DB)-\d{4}|THEMA-\d{3})\s*(?:\*\/)?\s*$/gm;
@@ -1721,9 +2267,9 @@ function stripContractDeclarationLines(text) {
 // src/core/contractIndex.ts
 async function buildContractIndex(root, config) {
   const contractsRoot = resolvePath(root, config, "contractsDir");
-  const uiRoot = path14.join(contractsRoot, "ui");
-  const apiRoot = path14.join(contractsRoot, "api");
-  const dbRoot = path14.join(contractsRoot, "db");
+  const uiRoot = path16.join(contractsRoot, "ui");
+  const apiRoot = path16.join(contractsRoot, "api");
+  const dbRoot = path16.join(contractsRoot, "db");
   const [uiFiles, themaFiles, apiFiles, dbFiles] = await Promise.all([
     collectUiContractFiles(uiRoot),
     collectThemaContractFiles(uiRoot),
@@ -1743,7 +2289,7 @@ async function buildContractIndex(root, config) {
 }
 async function indexContractFiles(files, index) {
   for (const file of files) {
-    const text = await readFile5(file, "utf-8");
+    const text = await readFile6(file, "utf-8");
     extractDeclaredContractIds(text).forEach((id) => record(index, id, file));
   }
 }
@@ -1868,53 +2414,11 @@ function unique3(values) {
   return Array.from(new Set(values));
 }
 
-// src/core/parse/markdown.ts
-var HEADING_RE = /^(#{1,6})\s+(.+?)\s*$/;
-function parseHeadings(md) {
-  const lines = md.split(/\r?\n/);
-  const headings = [];
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i] ?? "";
-    const match = line.match(HEADING_RE);
-    if (!match) continue;
-    const levelToken = match[1];
-    const title = match[2];
-    if (!levelToken || !title) continue;
-    headings.push({
-      level: levelToken.length,
-      title: title.trim(),
-      line: i + 1
-    });
-  }
-  return headings;
-}
-function extractH2Sections(md) {
-  const lines = md.split(/\r?\n/);
-  const headings = parseHeadings(md).filter((heading) => heading.level === 2);
-  const sections = /* @__PURE__ */ new Map();
-  for (let i = 0; i < headings.length; i++) {
-    const current = headings[i];
-    if (!current) continue;
-    const next = headings[i + 1];
-    const startLine = current.line + 1;
-    const endLine = (next?.line ?? lines.length + 1) - 1;
-    const body = startLine <= endLine ? lines.slice(startLine - 1, endLine).join("\n") : "";
-    sections.set(current.title.trim(), {
-      title: current.title.trim(),
-      startLine,
-      endLine,
-      body
-    });
-  }
-  return sections;
-}
-
 // src/core/parse/spec.ts
 var SPEC_ID_RE = /\bSPEC-\d{4}\b/;
 var BR_LINE_RE = /^\s*(?:[-*]\s*)?\[(BR-\d{4})\]\[(P[0-3])\]\s*(.+)$/;
 var BR_LINE_ANY_PRIORITY_RE = /^\s*(?:[-*]\s*)?\[(BR-\d{4})\]\[(P[^\]]+)\]\s*(.+)$/;
 var BR_LINE_NO_PRIORITY_RE = /^\s*(?:[-*]\s*)?\[(BR-\d{4})\](?!\s*\[P)\s*(.*\S.*)$/;
-var BR_SECTION_TITLE = "\u696D\u52D9\u30EB\u30FC\u30EB";
 var VALID_PRIORITIES = /* @__PURE__ */ new Set(["P0", "P1", "P2", "P3"]);
 function parseSpec(md, file) {
   const headings = parseHeadings(md);
@@ -1922,15 +2426,13 @@ function parseSpec(md, file) {
   const specId = h1?.title.match(SPEC_ID_RE)?.[0];
   const sections = extractH2Sections(md);
   const sectionNames = new Set(Array.from(sections.keys()));
-  const brSection = sections.get(BR_SECTION_TITLE);
-  const brLines = brSection ? brSection.body.split(/\r?\n/) : [];
-  const startLine = brSection?.startLine ?? 1;
+  const lines = md.split(/\r?\n/);
   const brs = [];
   const brsWithoutPriority = [];
   const brsWithInvalidPriority = [];
-  for (let i = 0; i < brLines.length; i++) {
-    const lineText = brLines[i] ?? "";
-    const lineNumber = startLine + i;
+  for (let i = 0; i < lines.length; i++) {
+    const lineText = lines[i] ?? "";
+    const lineNumber = i + 1;
     const validMatch = lineText.match(BR_LINE_RE);
     if (validMatch) {
       const id = validMatch[1];
@@ -1988,14 +2490,14 @@ function parseSpec(md, file) {
 }
 
 // src/core/validators/contracts.ts
-import { access as access6, readFile as readFile6 } from "fs/promises";
-import path16 from "path";
+import { access as access6, readFile as readFile7 } from "fs/promises";
+import path18 from "path";
 
 // src/core/contracts.ts
-import path15 from "path";
+import path17 from "path";
 import { parse as parseYaml2 } from "yaml";
 function parseStructuredContract(file, text) {
-  const ext = path15.extname(file).toLowerCase();
+  const ext = path17.extname(file).toLowerCase();
   if (ext === ".json") {
     return JSON.parse(text);
   }
@@ -2017,14 +2519,14 @@ async function validateContracts(root, config) {
   const issues = [];
   const contractIndex = await buildContractIndex(root, config);
   const contractsRoot = resolvePath(root, config, "contractsDir");
-  const uiRoot = path16.join(contractsRoot, "ui");
+  const uiRoot = path18.join(contractsRoot, "ui");
   const themaIds = new Set(
     Array.from(contractIndex.ids).filter((id) => id.startsWith("THEMA-"))
   );
   issues.push(...await validateUiContracts(uiRoot, themaIds));
   issues.push(...await validateThemaContracts(uiRoot));
-  issues.push(...await validateApiContracts(path16.join(contractsRoot, "api")));
-  issues.push(...await validateDbContracts(path16.join(contractsRoot, "db")));
+  issues.push(...await validateApiContracts(path18.join(contractsRoot, "api")));
+  issues.push(...await validateDbContracts(path18.join(contractsRoot, "db")));
   issues.push(...validateDuplicateContractIds(contractIndex));
   return issues;
 }
@@ -2043,7 +2545,7 @@ async function validateUiContracts(uiRoot, themaIds) {
   }
   const issues = [];
   for (const file of files) {
-    const text = await readFile6(file, "utf-8");
+    const text = await readFile7(file, "utf-8");
     const declaredIds = extractDeclaredContractIds(text);
     issues.push(...validateDeclaredContractIds(declaredIds, file, "UI"));
     let doc = null;
@@ -2097,7 +2599,7 @@ async function validateThemaContracts(uiRoot) {
   }
   const issues = [];
   for (const file of files) {
-    const text = await readFile6(file, "utf-8");
+    const text = await readFile7(file, "utf-8");
     const invalidIds = extractInvalidIds(text, [
       "SPEC",
       "BR",
@@ -2231,7 +2733,7 @@ async function validateApiContracts(apiRoot) {
   }
   const issues = [];
   for (const file of files) {
-    const text = await readFile6(file, "utf-8");
+    const text = await readFile7(file, "utf-8");
     const invalidIds = extractInvalidIds(text, [
       "SPEC",
       "BR",
@@ -2300,7 +2802,7 @@ async function validateDbContracts(dbRoot) {
   }
   const issues = [];
   for (const file of files) {
-    const text = await readFile6(file, "utf-8");
+    const text = await readFile7(file, "utf-8");
     const invalidIds = extractInvalidIds(text, [
       "SPEC",
       "BR",
@@ -2497,9 +2999,9 @@ async function validateUiAssets(assets, file, uiRoot) {
     );
     return issues;
   }
-  const packDir = path16.resolve(uiRoot, packValue);
-  const packRelative = path16.relative(uiRoot, packDir);
-  if (packRelative.startsWith("..") || path16.isAbsolute(packRelative)) {
+  const packDir = path18.resolve(uiRoot, packValue);
+  const packRelative = path18.relative(uiRoot, packDir);
+  if (packRelative.startsWith("..") || path18.isAbsolute(packRelative)) {
     issues.push(
       issue(
         "QFAI-ASSET-001",
@@ -2525,7 +3027,7 @@ async function validateUiAssets(assets, file, uiRoot) {
     );
     return issues;
   }
-  const assetsYamlPath = path16.join(packDir, "assets.yaml");
+  const assetsYamlPath = path18.join(packDir, "assets.yaml");
   if (!await exists6(assetsYamlPath)) {
     issues.push(
       issue(
@@ -2540,7 +3042,7 @@ async function validateUiAssets(assets, file, uiRoot) {
   }
   let manifest;
   try {
-    const manifestText = await readFile6(assetsYamlPath, "utf-8");
+    const manifestText = await readFile7(assetsYamlPath, "utf-8");
     manifest = parseStructuredContract(assetsYamlPath, manifestText);
   } catch (error2) {
     issues.push(
@@ -2613,9 +3115,9 @@ async function validateUiAssets(assets, file, uiRoot) {
       );
       continue;
     }
-    const assetPath = path16.resolve(packDir, entry.path);
-    const assetRelative = path16.relative(packDir, assetPath);
-    if (assetRelative.startsWith("..") || path16.isAbsolute(assetRelative)) {
+    const assetPath = path18.resolve(packDir, entry.path);
+    const assetRelative = path18.relative(packDir, assetPath);
+    if (assetRelative.startsWith("..") || path18.isAbsolute(assetRelative)) {
       issues.push(
         issue(
           "QFAI-ASSET-004",
@@ -2656,7 +3158,7 @@ function shouldIgnoreInvalidId(value, doc) {
     return false;
   }
   const normalized = packValue.replace(/\\/g, "/");
-  const basename = path16.posix.basename(normalized);
+  const basename = path18.posix.basename(normalized);
   if (!basename) {
     return false;
   }
@@ -2666,7 +3168,7 @@ function isSafeRelativePath(value) {
   if (!value) {
     return false;
   }
-  if (path16.isAbsolute(value)) {
+  if (path18.isAbsolute(value)) {
     return false;
   }
   const normalized = value.replace(/\\/g, "/");
@@ -2716,8 +3218,8 @@ function issue(code, message, severity, file, rule, refs, category = "compatibil
 }
 
 // src/core/validators/delta.ts
-import { readFile as readFile7 } from "fs/promises";
-import path17 from "path";
+import { readFile as readFile8 } from "fs/promises";
+import path19 from "path";
 async function validateDeltas(root, config) {
   const specsRoot = resolvePath(root, config, "specsDir");
   const packs = await collectSpecPackDirs(specsRoot);
@@ -2726,9 +3228,9 @@ async function validateDeltas(root, config) {
   }
   const issues = [];
   for (const pack of packs) {
-    const deltaPath = path17.join(pack, "delta.md");
+    const deltaPath = path19.join(pack, "delta.md");
     try {
-      await readFile7(deltaPath, "utf-8");
+      await readFile8(deltaPath, "utf-8");
     } catch (error2) {
       if (isMissingFileError2(error2)) {
         issues.push(
@@ -2779,8 +3281,8 @@ function issue2(code, message, severity, file, rule, refs, category = "change",
 }
 
 // src/core/validators/ids.ts
-import { readFile as readFile8 } from "fs/promises";
-import path18 from "path";
+import { readFile as readFile9 } from "fs/promises";
+import path20 from "path";
 var SC_TAG_RE3 = /^SC-\d{4}$/;
 async function validateDefinedIds(root, config) {
   const issues = [];
@@ -2815,7 +3317,7 @@ async function validateDefinedIds(root, config) {
 }
 async function collectSpecDefinitionIds(files, out) {
   for (const file of files) {
-    const text = await readFile8(file, "utf-8");
+    const text = await readFile9(file, "utf-8");
     const parsed = parseSpec(text, file);
     if (parsed.specId) {
       recordId(out, parsed.specId, file);
@@ -2825,7 +3327,7 @@ async function collectSpecDefinitionIds(files, out) {
 }
 async function collectScenarioDefinitionIds(files, out) {
   for (const file of files) {
-    const text = await readFile8(file, "utf-8");
+    const text = await readFile9(file, "utf-8");
     const { document, errors } = parseScenarioDocument(text, file);
     if (!document || errors.length > 0) {
       continue;
@@ -2846,7 +3348,7 @@ function recordId(out, id, file) {
 }
 function formatFileList(files, root) {
   return files.map((file) => {
-    const relative = path18.relative(root, file);
+    const relative = path20.relative(root, file);
     return relative.length > 0 ? relative : file;
   }).join(", ");
 }
@@ -2904,8 +3406,8 @@ async function validatePromptsIntegrity(root, config) {
 }
 
 // src/core/validators/scenario.ts
-import { access as access7, readFile as readFile9 } from "fs/promises";
-import path19 from "path";
+import { access as access7, readFile as readFile10 } from "fs/promises";
+import path21 from "path";
 var GIVEN_PATTERN = /\bGiven\b/;
 var WHEN_PATTERN = /\bWhen\b/;
 var THEN_PATTERN = /\bThen\b/;
@@ -2928,7 +3430,7 @@ async function validateScenarios(root, config) {
   }
   const issues = [];
   for (const entry of entries) {
-    const legacyScenarioPath = path19.join(entry.dir, "scenario.md");
+    const legacyScenarioPath = path21.join(entry.dir, "scenario.md");
     if (await fileExists(legacyScenarioPath)) {
       issues.push(
         issue4(
@@ -2942,7 +3444,7 @@ async function validateScenarios(root, config) {
     }
     let text;
     try {
-      text = await readFile9(entry.scenarioPath, "utf-8");
+      text = await readFile10(entry.scenarioPath, "utf-8");
     } catch (error2) {
       if (isMissingFileError3(error2)) {
         issues.push(
@@ -3125,7 +3627,7 @@ async function fileExists(target) {
 }
 
 // src/core/validators/spec.ts
-import { readFile as readFile10 } from "fs/promises";
+import { readFile as readFile11 } from "fs/promises";
 async function validateSpecs(root, config) {
   const specsRoot = resolvePath(root, config, "specsDir");
   const entries = await collectSpecEntries(specsRoot);
@@ -3146,7 +3648,7 @@ async function validateSpecs(root, config) {
   for (const entry of entries) {
     let text;
     try {
-      text = await readFile10(entry.specPath, "utf-8");
+      text = await readFile11(entry.specPath, "utf-8");
     } catch (error2) {
       if (isMissingFileError4(error2)) {
         issues.push(
@@ -3300,7 +3802,7 @@ function isMissingFileError4(error2) {
 }
 
 // src/core/validators/traceability.ts
-import { readFile as readFile11 } from "fs/promises";
+import { readFile as readFile12 } from "fs/promises";
 var SPEC_TAG_RE3 = /^SPEC-\d{4}$/;
 var BR_TAG_RE2 = /^BR-\d{4}$/;
 async function validateTraceability(root, config) {
@@ -3320,7 +3822,7 @@ async function validateTraceability(root, config) {
   const contractIndex = await buildContractIndex(root, config);
   const contractIds = contractIndex.ids;
   for (const file of specFiles) {
-    const text = await readFile11(file, "utf-8");
+    const text = await readFile12(file, "utf-8");
     extractAllIds(text).forEach((id) => upstreamIds.add(id));
     const parsed = parseSpec(text, file);
     if (parsed.specId) {
@@ -3393,7 +3895,7 @@ async function validateTraceability(root, config) {
     }
   }
   for (const file of scenarioFiles) {
-    const text = await readFile11(file, "utf-8");
+    const text = await readFile12(file, "utf-8");
     extractAllIds(text).forEach((id) => upstreamIds.add(id));
     const scenarioContractRefs = parseContractRefs(text, {
       allowCommentPrefix: true
@@ -3715,7 +4217,7 @@ async function validateCodeReferences(upstreamIds, srcRoot, testsRoot) {
   const pattern = buildIdPattern(Array.from(upstreamIds));
   let found = false;
   for (const file of targetFiles) {
-    const text = await readFile11(file, "utf-8");
+    const text = await readFile12(file, "utf-8");
     if (pattern.test(text)) {
       found = true;
       break;
@@ -3814,16 +4316,17 @@ var ID_PREFIXES2 = [
   "DB",
   "THEMA"
 ];
+var REPORT_GUARDRAILS_MAX = 20;
 async function createReportData(root, validation, configResult) {
-  const resolvedRoot = path20.resolve(root);
+  const resolvedRoot = path22.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 = path20.join(contractsRoot, "api");
-  const uiRoot = path20.join(contractsRoot, "ui");
-  const dbRoot = path20.join(contractsRoot, "db");
+  const apiRoot = path22.join(contractsRoot, "api");
+  const uiRoot = path22.join(contractsRoot, "ui");
+  const dbRoot = path22.join(contractsRoot, "db");
   const srcRoot = resolvePath(resolvedRoot, config, "srcDir");
   const testsRoot = resolvePath(resolvedRoot, config, "testsDir");
   const specFiles = await collectSpecFiles(specsRoot);
@@ -3882,6 +4385,27 @@ async function createReportData(root, validation, configResult) {
   const scSourceRecord = mapToSortedRecord(
     normalizeScSources(resolvedRoot, scSources)
   );
+  const guardrailsLoad = await loadDecisionGuardrails(resolvedRoot, {
+    specsRoot
+  });
+  const guardrailsAll = sortDecisionGuardrails(
+    normalizeDecisionGuardrails(guardrailsLoad.entries)
+  );
+  const guardrailsDisplay = guardrailsAll.slice(0, REPORT_GUARDRAILS_MAX);
+  const guardrailsByType = { nonGoal: 0, notNow: 0, tradeOff: 0 };
+  for (const item of guardrailsAll) {
+    if (item.type === "non-goal") {
+      guardrailsByType.nonGoal += 1;
+    } else if (item.type === "not-now") {
+      guardrailsByType.notNow += 1;
+    } else if (item.type === "trade-off") {
+      guardrailsByType.tradeOff += 1;
+    }
+  }
+  const guardrailsErrors = guardrailsLoad.errors.map((item) => ({
+    path: toRelativePath(resolvedRoot, item.path),
+    message: item.message
+  }));
   const version = await resolveToolVersion();
   const displayRoot = toRelativePath(resolvedRoot, resolvedRoot);
   const displayConfigPath = toRelativePath(resolvedRoot, configPath);
@@ -3929,6 +4453,34 @@ async function createReportData(root, validation, configResult) {
         specToContracts: specToContractsRecord
       }
     },
+    guardrails: {
+      total: guardrailsAll.length,
+      max: REPORT_GUARDRAILS_MAX,
+      truncated: guardrailsAll.length > guardrailsDisplay.length,
+      byType: guardrailsByType,
+      items: guardrailsDisplay.map((item) => {
+        const entry = {
+          id: item.id,
+          type: item.type,
+          guardrail: item.guardrail,
+          source: {
+            file: toRelativePath(resolvedRoot, item.source.file),
+            line: item.source.line
+          }
+        };
+        if (item.rationale) {
+          entry.rationale = item.rationale;
+        }
+        if (item.reconsider) {
+          entry.reconsider = item.reconsider;
+        }
+        if (item.related) {
+          entry.related = item.related;
+        }
+        return entry;
+      }),
+      scanErrors: guardrailsErrors
+    },
     issues: normalizedValidation.issues
   };
 }
@@ -4024,6 +4576,7 @@ function formatReportMarkdown(data, options = {}) {
   lines.push("");
   lines.push("- [Compatibility Issues](#compatibility-issues)");
   lines.push("- [Change Issues](#change-issues)");
+  lines.push("- [Decision Guardrails](#decision-guardrails)");
   lines.push("- [IDs](#ids)");
   lines.push("- [Traceability](#traceability)");
   lines.push("");
@@ -4115,6 +4668,49 @@ function formatReportMarkdown(data, options = {}) {
   lines.push("### Issues");
   lines.push("");
   lines.push(...formatIssueCards(issuesByCategory.change));
+  lines.push("## Decision Guardrails");
+  lines.push("");
+  lines.push(`- total: ${data.guardrails.total}`);
+  lines.push(
+    `- types: non-goal ${data.guardrails.byType.nonGoal} / not-now ${data.guardrails.byType.notNow} / trade-off ${data.guardrails.byType.tradeOff}`
+  );
+  if (data.guardrails.truncated) {
+    lines.push(`- truncated: true (max=${data.guardrails.max})`);
+  }
+  if (data.guardrails.scanErrors.length > 0) {
+    lines.push(`- scanErrors: ${data.guardrails.scanErrors.length}`);
+  }
+  lines.push("");
+  if (data.guardrails.items.length === 0) {
+    lines.push("- (none)");
+  } else {
+    for (const item of data.guardrails.items) {
+      lines.push(`- [${item.id}][${item.type}] ${item.guardrail}`);
+      lines.push(
+        `  - source: ${formatPathWithLine(item.source.file, { line: item.source.line }, baseUrl)}`
+      );
+      if (item.rationale) {
+        lines.push(`  - Rationale: ${item.rationale}`);
+      }
+      if (item.reconsider) {
+        lines.push(`  - Reconsider: ${item.reconsider}`);
+      }
+      if (item.related) {
+        lines.push(`  - Related: ${item.related}`);
+      }
+    }
+  }
+  if (data.guardrails.scanErrors.length > 0) {
+    lines.push("");
+    lines.push("### Scan errors");
+    lines.push("");
+    for (const errorItem of data.guardrails.scanErrors) {
+      lines.push(
+        `- ${formatPathLink(errorItem.path, baseUrl)}: ${errorItem.message}`
+      );
+    }
+  }
+  lines.push("");
   lines.push("## IDs");
   lines.push("");
   lines.push(formatIdLine("SPEC", data.ids.spec));
@@ -4305,7 +4901,7 @@ async function collectSpecContractRefs(specFiles, contractIdList) {
     idToSpecs.set(contractId, /* @__PURE__ */ new Set());
   }
   for (const file of specFiles) {
-    const text = await readFile12(file, "utf-8");
+    const text = await readFile13(file, "utf-8");
     const parsed = parseSpec(text, file);
     const specKey = parsed.specId;
     if (!specKey) {
@@ -4347,7 +4943,7 @@ async function collectIds(files) {
     THEMA: /* @__PURE__ */ new Set()
   };
   for (const file of files) {
-    const text = await readFile12(file, "utf-8");
+    const text = await readFile13(file, "utf-8");
     for (const prefix of ID_PREFIXES2) {
       const ids = extractIds(text, prefix);
       ids.forEach((id) => result[prefix].add(id));
@@ -4366,7 +4962,7 @@ async function collectIds(files) {
 async function collectUpstreamIds(files) {
   const ids = /* @__PURE__ */ new Set();
   for (const file of files) {
-    const text = await readFile12(file, "utf-8");
+    const text = await readFile13(file, "utf-8");
     extractAllIds(text).forEach((id) => ids.add(id));
   }
   return ids;
@@ -4387,7 +4983,7 @@ async function evaluateTraceability(upstreamIds, srcRoot, testsRoot) {
   }
   const pattern = buildIdPattern2(Array.from(upstreamIds));
   for (const file of targetFiles) {
-    const text = await readFile12(file, "utf-8");
+    const text = await readFile13(file, "utf-8");
     if (pattern.test(text)) {
       return true;
     }
@@ -4524,7 +5120,7 @@ function warnIfTruncated(scan, context) {
 
 // src/cli/commands/report.ts
 async function runReport(options) {
-  const root = path21.resolve(options.root);
+  const root = path23.resolve(options.root);
   const configResult = await loadConfig(root);
   let validation;
   if (options.runValidate) {
@@ -4541,7 +5137,7 @@ async function runReport(options) {
     validation = normalized;
   } else {
     const input = options.inputPath ?? configResult.config.output.validateJsonPath;
-    const inputPath = path21.isAbsolute(input) ? input : path21.resolve(root, input);
+    const inputPath = path23.isAbsolute(input) ? input : path23.resolve(root, input);
     try {
       validation = await readValidationResult(inputPath);
     } catch (err) {
@@ -4568,10 +5164,10 @@ async function runReport(options) {
   warnIfTruncated(data.traceability.testFiles, "report");
   const output = options.format === "json" ? formatReportJson(data) : options.baseUrl ? formatReportMarkdown(data, { baseUrl: options.baseUrl }) : formatReportMarkdown(data);
   const outRoot = resolvePath(root, configResult.config, "outDir");
-  const defaultOut = options.format === "json" ? path21.join(outRoot, "report.json") : path21.join(outRoot, "report.md");
+  const defaultOut = options.format === "json" ? path23.join(outRoot, "report.json") : path23.join(outRoot, "report.md");
   const out = options.outPath ?? defaultOut;
-  const outPath = path21.isAbsolute(out) ? out : path21.resolve(root, out);
-  await mkdir3(path21.dirname(outPath), { recursive: true });
+  const outPath = path23.isAbsolute(out) ? out : path23.resolve(root, out);
+  await mkdir3(path23.dirname(outPath), { recursive: true });
   await writeFile2(outPath, `${output}
 `, "utf-8");
   info(
@@ -4580,7 +5176,7 @@ async function runReport(options) {
   info(`wrote report: ${outPath}`);
 }
 async function readValidationResult(inputPath) {
-  const raw = await readFile13(inputPath, "utf-8");
+  const raw = await readFile14(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}`);
@@ -4636,15 +5232,15 @@ function isMissingFileError5(error2) {
   return record2.code === "ENOENT";
 }
 async function writeValidationResult(root, outputPath, result) {
-  const abs = path21.isAbsolute(outputPath) ? outputPath : path21.resolve(root, outputPath);
-  await mkdir3(path21.dirname(abs), { recursive: true });
+  const abs = path23.isAbsolute(outputPath) ? outputPath : path23.resolve(root, outputPath);
+  await mkdir3(path23.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 path22 from "path";
+import path24 from "path";
 
 // src/cli/lib/failOn.ts
 function shouldFail(result, failOn) {
@@ -4659,7 +5255,7 @@ function shouldFail(result, failOn) {
 
 // src/cli/commands/validate.ts
 async function runValidate(options) {
-  const root = path22.resolve(options.root);
+  const root = path24.resolve(options.root);
   const configResult = await loadConfig(root);
   const result = await validateProject(root, configResult);
   const normalized = normalizeValidationResult(root, result);
@@ -4784,12 +5380,12 @@ function issueKey(issue7) {
 }
 async function emitJson(result, root, jsonPath) {
   const abs = resolveJsonPath(root, jsonPath);
-  await mkdir4(path22.dirname(abs), { recursive: true });
+  await mkdir4(path24.dirname(abs), { recursive: true });
   await writeFile3(abs, `${JSON.stringify(result, null, 2)}
 `, "utf-8");
 }
 function resolveJsonPath(root, jsonPath) {
-  return path22.isAbsolute(jsonPath) ? jsonPath : path22.resolve(root, jsonPath);
+  return path24.isAbsolute(jsonPath) ? jsonPath : path24.resolve(root, jsonPath);
 }
 var GITHUB_ANNOTATION_LIMIT = 100;
 
@@ -4807,7 +5403,9 @@ function parseArgs(argv, cwd) {
     doctorFormat: "text",
     validateFormat: "text",
     strict: false,
-    help: false
+    guardrailsPaths: [],
+    help: false,
+    invalidExitCode: 1
   };
   const args = [...argv];
   let command = args.shift() ?? null;
@@ -4816,6 +5414,25 @@ function parseArgs(argv, cwd) {
     options.help = true;
     command = null;
   }
+  const markInvalid = () => {
+    invalid = true;
+    options.help = true;
+    if (command === "guardrails") {
+      options.invalidExitCode = 2;
+    }
+  };
+  if (command === "guardrails") {
+    const candidate = args[0];
+    if (candidate && !candidate.startsWith("--")) {
+      const action = normalizeGuardrailsAction(candidate);
+      if (action) {
+        options.guardrailsAction = action;
+      } else {
+        markInvalid();
+      }
+      args.shift();
+    }
+  }
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
     switch (arg) {
@@ -4823,8 +5440,7 @@ function parseArgs(argv, cwd) {
         {
           const next = readOptionValue(args, i);
           if (next === null) {
-            invalid = true;
-            options.help = true;
+            markInvalid();
             break;
           }
           options.root = next;
@@ -4836,8 +5452,7 @@ function parseArgs(argv, cwd) {
         {
           const next = readOptionValue(args, i);
           if (next === null) {
-            invalid = true;
-            options.help = true;
+            markInvalid();
             break;
           }
           options.dir = next;
@@ -4856,8 +5471,7 @@ function parseArgs(argv, cwd) {
       case "--format": {
         const next = readOptionValue(args, i);
         if (next === null) {
-          invalid = true;
-          options.help = true;
+          markInvalid();
           break;
         }
         applyFormatOption(command, next, options);
@@ -4870,8 +5484,7 @@ function parseArgs(argv, cwd) {
       case "--fail-on": {
         const next = readOptionValue(args, i);
         if (next === null) {
-          invalid = true;
-          options.help = true;
+          markInvalid();
           break;
         }
         if (next === "never" || next === "warning" || next === "error") {
@@ -4883,8 +5496,7 @@ function parseArgs(argv, cwd) {
       case "--out": {
         const next = readOptionValue(args, i);
         if (next === null) {
-          invalid = true;
-          options.help = true;
+          markInvalid();
           break;
         }
         if (command === "doctor") {
@@ -4898,8 +5510,7 @@ function parseArgs(argv, cwd) {
       case "--in": {
         const next = readOptionValue(args, i);
         if (next === null) {
-          invalid = true;
-          options.help = true;
+          markInvalid();
           break;
         }
         options.reportIn = next;
@@ -4912,14 +5523,57 @@ function parseArgs(argv, cwd) {
       case "--base-url": {
         const next = readOptionValue(args, i);
         if (next === null) {
-          invalid = true;
-          options.help = true;
+          markInvalid();
           break;
         }
         options.reportBaseUrl = next;
         i += 1;
         break;
       }
+      case "--path": {
+        if (command !== "guardrails") {
+          break;
+        }
+        const next = readOptionValue(args, i);
+        if (next === null) {
+          markInvalid();
+          break;
+        }
+        options.guardrailsPaths.push(next);
+        i += 1;
+        break;
+      }
+      case "--max": {
+        if (command !== "guardrails") {
+          break;
+        }
+        const next = readOptionValue(args, i);
+        if (next === null) {
+          markInvalid();
+          break;
+        }
+        const parsed = Number.parseInt(next, 10);
+        if (Number.isNaN(parsed)) {
+          markInvalid();
+          break;
+        }
+        options.guardrailsMax = parsed;
+        i += 1;
+        break;
+      }
+      case "--keyword": {
+        if (command !== "guardrails") {
+          break;
+        }
+        const next = readOptionValue(args, i);
+        if (next === null) {
+          markInvalid();
+          break;
+        }
+        options.guardrailsKeyword = next;
+        i += 1;
+        break;
+      }
       case "--help":
       case "-h":
         options.help = true;
@@ -4928,6 +5582,9 @@ function parseArgs(argv, cwd) {
         break;
     }
   }
+  if (command === "guardrails" && !options.help && !options.guardrailsAction) {
+    markInvalid();
+  }
   return { command, invalid, options };
 }
 function readOptionValue(args, index) {
@@ -4966,6 +5623,16 @@ function applyFormatOption(command, value, options) {
     options.validateFormat = value;
   }
 }
+function normalizeGuardrailsAction(value) {
+  switch (value) {
+    case "list":
+    case "extract":
+    case "check":
+      return value;
+    default:
+      return null;
+  }
+}
 
 // src/cli/main.ts
 async function run(argv, cwd) {
@@ -4973,7 +5640,7 @@ async function run(argv, cwd) {
   if (!command || options.help) {
     info(usage());
     if (invalid) {
-      process.exitCode = 1;
+      process.exitCode = options.invalidExitCode;
     }
     return;
   }
@@ -5022,6 +5689,19 @@ async function run(argv, cwd) {
         process.exitCode = exitCode;
       }
       return;
+    case "guardrails":
+      {
+        const resolvedRoot = await resolveRoot(options);
+        const exitCode = await runGuardrails({
+          root: resolvedRoot,
+          ...options.guardrailsAction ? { action: options.guardrailsAction } : {},
+          paths: options.guardrailsPaths,
+          ...options.guardrailsMax !== void 0 ? { max: options.guardrailsMax } : {},
+          ...options.guardrailsKeyword !== void 0 ? { keyword: options.guardrailsKeyword } : {}
+        });
+        process.exitCode = exitCode;
+      }
+      return;
     default:
       error(`Unknown command: ${command}`);
       info(usage());
@@ -5036,6 +5716,7 @@ Commands:
   validate   \u4ED5\u69D8/\u5951\u7D04/\u53C2\u7167\u306E\u691C\u67FB
   report     \u691C\u8A3C\u7D50\u679C\u3068\u96C6\u8A08\u3092\u51FA\u529B
   doctor     \u8A2D\u5B9A/\u30D1\u30B9/\u51FA\u529B\u524D\u63D0\u306E\u8A3A\u65AD
+  guardrails Decision Guardrails \u306E\u62BD\u51FA/\u691C\u67FB\uFF08list|extract|check\uFF09
 
 Options:
   --root <path>   \u5BFE\u8C61\u30C7\u30A3\u30EC\u30AF\u30C8\u30EA
@@ -5053,6 +5734,9 @@ Options:
   --in <path>                   report: validate.json \u306E\u5165\u529B\u5148\uFF08config\u3088\u308A\u512A\u5148\uFF09
   --run-validate                report: validate \u3092\u5B9F\u884C\u3057\u3066\u304B\u3089 report \u3092\u751F\u6210
   --base-url <url>              report: \u30D1\u30B9\u3092\u30EA\u30F3\u30AF\u5316\u3059\u308B\u57FA\u6E96URL
+  --path <path>                 guardrails: \u5BFE\u8C61\u30D5\u30A1\u30A4\u30EB/\u30C7\u30A3\u30EC\u30AF\u30C8\u30EA\uFF08\u8907\u6570\u6307\u5B9A\u53EF\uFF09
+  --max <number>                guardrails extract: \u6700\u5927\u4EF6\u6570
+  --keyword <text>              guardrails list/extract: \u30AD\u30FC\u30EF\u30FC\u30C9\u30D5\u30A3\u30EB\u30BF
   -h, --help      \u30D8\u30EB\u30D7\u8868\u793A
 `;
 }