@pieai/doc-gov 0.9.4 → 0.9.6

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/commands/approve.ts
-import { readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "node:fs";
-import { join as join4 } from "node:path";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "node:fs";
+import { join as join5 } from "node:path";
 
 // src/core/frontmatter.ts
 import { readFileSync } from "node:fs";
@@ -65,8 +65,7 @@ function parseScalar(value) {
 }
 
 // src/core/files.ts
-import { existsSync, readdirSync, statSync } from "node:fs";
-import { join, relative } from "node:path";
+import { join as join2, relative as relative2 } from "node:path";
 
 // src/core/external-artifacts.ts
 var EXTERNAL_ARTIFACT_PREFIXES = ["docs/brainstorms/", "docs/pulse-reports/"];
@@ -80,35 +79,164 @@ function isExternalArtifactPath(repoPath) {
   return false;
 }
 
-// src/core/files.ts
-function listGovernedMarkdownFiles(rootDir) {
-  const roots = [join(rootDir, "docs")];
+// src/core/markdown-traversal.ts
+import {
+  existsSync,
+  lstatSync,
+  readFileSync as readFileSync2,
+  readdirSync,
+  realpathSync,
+  statSync
+} from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+function listMarkdownFiles(rootDir, roots, options = {}) {
+  const resolvedRootDir = resolve(rootDir);
+  const allowedRoots = canonicalizeRoots(resolvedRootDir, options.allowedRoots ?? []);
   const files = [];
+  const visitedDirectories = /* @__PURE__ */ new Set();
   for (const root of roots) {
-    if (!existsSync(root)) continue;
-    files.push(...walk(rootDir, root));
+    walkEntry(resolveFromRoot(resolvedRootDir, root));
   }
-  return files.sort();
+  return Array.from(new Set(files)).sort();
+  function walkEntry(path) {
+    const repoPath = toRepoPath(resolvedRootDir, path);
+    if (options.shouldSkipTree?.(repoPath)) return;
+    const stat = safeLstat(path);
+    if (!stat) return;
+    if (stat.isDirectory()) {
+      walkDirectory(path);
+      return;
+    }
+    if (!stat.isFile() && !stat.isSymbolicLink()) return;
+    addMarkdownFile(path, repoPath, stat);
+  }
+  function walkDirectory(dir) {
+    const realDirectory = safeRealpath(dir);
+    if (!realDirectory || visitedDirectories.has(realDirectory)) return;
+    visitedDirectories.add(realDirectory);
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const path = join(dir, entry.name);
+      const repoPath = toRepoPath(resolvedRootDir, path);
+      if (options.shouldSkipTree?.(repoPath)) continue;
+      if (entry.isDirectory()) {
+        walkDirectory(path);
+        continue;
+      }
+      if (entry.isFile() || entry.isSymbolicLink()) {
+        addMarkdownFile(path, repoPath, entry);
+      }
+    }
+  }
+  function addMarkdownFile(path, repoPath, entry) {
+    if (!path.endsWith(".md")) return;
+    if (options.includeFile && !options.includeFile(repoPath)) return;
+    if (!isAllowedMarkdownFile(resolvedRootDir, path, allowedRoots, repoPath, entry)) return;
+    files.push(path);
+  }
+}
+function canonicalizeRoots(rootDir, roots) {
+  return Array.from(
+    new Set(
+      [rootDir, ...roots].map((root) => {
+        const resolved = resolveFromRoot(rootDir, root);
+        return safeRealpath(resolved) ?? resolved;
+      }).filter(Boolean)
+    )
+  );
 }
-function walk(rootDir, dir) {
-  const entries = readdirSync(dir, { withFileTypes: true });
-  const files = [];
-  for (const entry of entries) {
-    const path = join(dir, entry.name);
-    const rel = toRepoPath(rootDir, path);
-    if (shouldSkip(rel)) continue;
-    if (entry.isSymbolicLink()) continue;
-    if (entry.isDirectory()) files.push(...walk(rootDir, path));
-    if (entry.isFile() && entry.name.endsWith(".md")) files.push(path);
+function isAllowedMarkdownFile(rootDir, path, allowedRoots, repoPath, entry) {
+  const targetPath = safeRealpath(path);
+  if (!targetPath) return false;
+  const targetStat = safeStat(targetPath);
+  if (!targetStat?.isFile()) return false;
+  if (allowedRoots.some((root) => isPathWithin(targetPath, root))) return true;
+  return entry.isSymbolicLink() && isTrustedPgsSharedRuleTarget(rootDir, repoPath, targetPath);
+}
+function isTrustedPgsSharedRuleTarget(rootDir, repoPath, targetPath) {
+  if (!isSharedRulePath(repoPath)) return false;
+  const centralRoot = findCentralRepositoryRoot(dirname(targetPath));
+  if (!centralRoot) return false;
+  const sourceRoot = safeRealpath(join(centralRoot, "agent-assets/rules/pie-rules"));
+  return Boolean(sourceRoot && isPathWithin(targetPath, sourceRoot));
+}
+function isSharedRulePath(repoPath) {
+  return repoPath.startsWith("docs/policy/shared-rules/") && repoPath.endsWith(".md");
+}
+function findCentralRepositoryRoot(startDir) {
+  let current = startDir;
+  while (true) {
+    if (isCentralRepositoryRoot(current)) return safeRealpath(current) ?? current;
+    const parent = dirname(current);
+    if (parent === current) return void 0;
+    current = parent;
+  }
+}
+function isCentralRepositoryRoot(path) {
+  const packageJsonPath = join(path, "package.json");
+  if (!existsSync(packageJsonPath)) return false;
+  try {
+    const packageJson = JSON.parse(readFileSync2(packageJsonPath, "utf8"));
+    if (packageJson.name !== "project-governance-system" && packageJson.name !== "pro-gov") {
+      return false;
+    }
+  } catch {
+    return false;
   }
-  return files;
+  return existsSync(join(path, "profiles")) && existsSync(join(path, "starter")) && existsSync(join(path, "integrations"));
 }
-function shouldSkip(repoPath) {
-  return isExternalArtifactPath(repoPath) || repoPath.startsWith("docs/governance/templates/") || repoPath === "docs/governance/MANIFEST.yml";
+function isPathWithin(candidate, root) {
+  const relation = relative(root, candidate);
+  return relation === "" || !relation.startsWith(`..${sep}`) && relation !== ".." && !isAbsolute(relation);
+}
+function resolveFromRoot(rootDir, path) {
+  if (isAbsolute(path)) return path;
+  const resolvedRoot = resolve(rootDir);
+  const resolvedPath = resolve(path);
+  return isPathWithin(resolvedPath, resolvedRoot) ? resolvedPath : resolve(resolvedRoot, path);
 }
 function toRepoPath(rootDir, absolutePath) {
   return relative(rootDir, absolutePath).split(/\\/g).join("/");
 }
+function safeLstat(path) {
+  try {
+    return lstatSync(path);
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR") return void 0;
+    throw error;
+  }
+}
+function safeStat(path) {
+  try {
+    return statSync(path);
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP") return void 0;
+    throw error;
+  }
+}
+function safeRealpath(path) {
+  try {
+    return realpathSync(path);
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP") return void 0;
+    throw error;
+  }
+}
+
+// src/core/files.ts
+function listGovernedMarkdownFiles(rootDir) {
+  return listMarkdownFiles(rootDir, ["docs"], {
+    shouldSkipTree: shouldSkip
+  });
+}
+function shouldSkip(repoPath) {
+  return isExternalArtifactPath(repoPath) || repoPath.startsWith("docs/governance/templates/") || repoPath === "docs/governance/MANIFEST.yml";
+}
+function toRepoPath2(rootDir, absolutePath) {
+  return relative2(rootDir, absolutePath).split(/\\/g).join("/");
+}
 
 // src/core/lifecycle.ts
 var normalStatuses = [
@@ -132,7 +260,7 @@ var docTypes = [
   "archive"
 ];
 function validateFrontmatter(rootDir, file) {
-  const path = toRepoPath(rootDir, file.path);
+  const path = toRepoPath2(rootDir, file.path);
   const issues = [];
   const data = file.data;
   const id = stringValue(data.id);
@@ -382,8 +510,8 @@ function pathToRepo(rootDir, path) {
 }
 
 // src/core/paths.ts
-import { existsSync as existsSync2, readdirSync as readdirSync2 } from "node:fs";
-import { join as join2 } from "node:path";
+import { existsSync as existsSync2 } from "node:fs";
+import { basename, join as join3 } from "node:path";
 function planPath(rootDir, type, slugInput) {
   const cleanSlug = slugInput.replace(/^\/+|\/+$/g, "");
   if (!cleanSlug) throw new Error("Slug is required.");
@@ -452,22 +580,18 @@ function planPath(rootDir, type, slugInput) {
   throw new Error(`Unknown type: ${type}`);
 }
 function nextSerial(rootDir, scanDir, regex) {
-  const root = join2(rootDir, scanDir);
+  const root = join3(rootDir, scanDir);
   if (!existsSync2(root)) return "0001";
   let max = 0;
-  walkSerial(root, regex, (n) => {
+  walkSerial(rootDir, scanDir, regex, (n) => {
     if (n > max) max = n;
   });
   return String(max + 1).padStart(4, "0");
 }
-function walkSerial(dir, regex, onMatch) {
-  for (const entry of readdirSync2(dir, { withFileTypes: true })) {
-    const path = join2(dir, entry.name);
-    if (entry.isDirectory()) walkSerial(path, regex, onMatch);
-    else if (entry.isFile() && entry.name.endsWith(".md")) {
-      const m = entry.name.match(regex);
-      if (m && m[1]) onMatch(parseInt(m[1], 10));
-    }
+function walkSerial(rootDir, dir, regex, onMatch) {
+  for (const path of listMarkdownFiles(rootDir, [dir])) {
+    const m = basename(path).match(regex);
+    if (m && m[1]) onMatch(parseInt(m[1], 10));
   }
 }
 function isKebabCase(slug) {
@@ -486,8 +610,8 @@ function todayIso() {
 }
 
 // src/core/manifest.ts
-import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "node:fs";
-import { dirname, join as join3 } from "node:path";
+import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync3, writeFileSync } from "node:fs";
+import { dirname as dirname2, join as join4 } from "node:path";
 function buildManifest(rootDir = process.cwd()) {
   const result = checkDocs(rootDir);
   if (!result.ok) {
@@ -499,14 +623,14 @@ ${error}`);
 }
 function writeManifest(rootDir = process.cwd()) {
   const manifest = buildManifest(rootDir);
-  const path = join3(rootDir, "docs/governance/MANIFEST.yml");
-  mkdirSync(dirname(path), { recursive: true });
+  const path = join4(rootDir, "docs/governance/MANIFEST.yml");
+  mkdirSync(dirname2(path), { recursive: true });
   writeFileSync(path, manifest);
 }
 function manifestInSync(rootDir = process.cwd()) {
-  const path = join3(rootDir, "docs/governance/MANIFEST.yml");
+  const path = join4(rootDir, "docs/governance/MANIFEST.yml");
   if (!existsSync3(path)) return false;
-  return normalizeManifest(readFileSync2(path, "utf8")) === normalizeManifest(buildManifest(rootDir));
+  return normalizeManifest(readFileSync3(path, "utf8")) === normalizeManifest(buildManifest(rootDir));
 }
 function normalizeManifest(value) {
   return value.replace(/^generated_at: .*$/m, "generated_at: <ignored>").replace(/^generator_version: .*$/m, "generator_version: <ignored>");
@@ -535,7 +659,7 @@ function renderManifest(records) {
 function readPackageVersion() {
   for (const candidate of ["../package.json", "../../package.json"]) {
     try {
-      const packageJson = JSON.parse(readFileSync2(new URL(candidate, import.meta.url), "utf8"));
+      const packageJson = JSON.parse(readFileSync3(new URL(candidate, import.meta.url), "utf8"));
       if (typeof packageJson.version === "string") return packageJson.version;
     } catch {
     }
@@ -571,8 +695,8 @@ function runApprove(args2) {
     );
     return 1;
   }
-  const filePath = join4(root, record.path);
-  const content = readFileSync3(filePath, "utf8");
+  const filePath = join5(root, record.path);
+  const content = readFileSync4(filePath, "utf8");
   let next = content;
   next = updateFrontmatterField(next, "status", toStatus);
   next = updateFrontmatterField(next, "canonical", "true");
@@ -618,8 +742,8 @@ ${newLines.join("\n")}${tail}`;
 
 // src/commands/archive.ts
 import { execFileSync } from "node:child_process";
-import { mkdirSync as mkdirSync2, readFileSync as readFileSync4, renameSync, writeFileSync as writeFileSync3 } from "node:fs";
-import { basename, dirname as dirname2, join as join5 } from "node:path";
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync5, renameSync, writeFileSync as writeFileSync3 } from "node:fs";
+import { basename as basename2, dirname as dirname3, join as join6 } from "node:path";
 function runArchive(args2) {
   const positional = args2.filter((a) => !a.startsWith("--"));
   const id = positional[0];
@@ -655,18 +779,18 @@ function runArchive(args2) {
     return 1;
   }
   const oldPath = record.path;
-  const fileName = basename(oldPath);
+  const fileName = basename2(oldPath);
   const archiveDir = `docs/archive/${quarterTag()}-${record.type}`;
   const newPath = `${archiveDir}/${fileName}`;
-  const absNew = join5(root, newPath);
-  const absOld = join5(root, oldPath);
-  let content = readFileSync4(absOld, "utf8");
+  const absNew = join6(root, newPath);
+  const absOld = join6(root, oldPath);
+  let content = readFileSync5(absOld, "utf8");
   content = updateFrontmatterField(content, "type", "archive");
   content = updateFrontmatterField(content, "status", "archived");
   content = updateFrontmatterField(content, "canonical", "false");
   content = updateFrontmatterField(content, "last_reviewed", todayIso());
   content = updateFrontmatterField(content, "archive_reason", reason);
-  mkdirSync2(dirname2(absNew), { recursive: true });
+  mkdirSync2(dirname3(absNew), { recursive: true });
   let movedByGit = false;
   try {
     execFileSync("git", ["mv", oldPath, newPath], { cwd: root, stdio: "ignore" });
@@ -689,12 +813,12 @@ function runArchive(args2) {
 }
 
 // src/commands/audit.ts
-import { existsSync as existsSync5, readdirSync as readdirSync4 } from "node:fs";
+import { existsSync as existsSync5, readdirSync as readdirSync2 } from "node:fs";
 import { join as join7 } from "node:path";
 
 // src/core/link-checker.ts
-import { existsSync as existsSync4, lstatSync, readFileSync as readFileSync5, readdirSync as readdirSync3 } from "node:fs";
-import { dirname as dirname3, extname, join as join6, resolve } from "node:path";
+import { existsSync as existsSync4, readFileSync as readFileSync6 } from "node:fs";
+import { dirname as dirname4, extname, resolve as resolve2 } from "node:path";
 var CURRENT_MARKDOWN_ROOTS = ["AGENTS.md", "README.md", "docs"];
 var CURRENT_DOC_DIR_PREFIXES = [
   "docs/canon/",
@@ -719,7 +843,7 @@ function checkCurrentMarkdownLinks(rootDir = process.cwd()) {
       if (!target || shouldIgnoreTarget(target)) continue;
       checkedLinks += 1;
       if (!localTargetExists(rootDir, filePath, target)) {
-        const file = toRepoPath(rootDir, filePath);
+        const file = toRepoPath2(rootDir, filePath);
         const line = lineNumberAt(content, match.index);
         issues.push({
           file,
@@ -738,30 +862,10 @@ function checkCurrentMarkdownLinks(rootDir = process.cwd()) {
   };
 }
 function listCurrentMarkdownFiles(rootDir) {
-  const files = [];
-  for (const root of CURRENT_MARKDOWN_ROOTS) {
-    const fullPath = join6(rootDir, root);
-    if (!existsSync4(fullPath)) continue;
-    const stat = lstatSync(fullPath);
-    if (stat.isSymbolicLink()) continue;
-    if (stat.isDirectory()) files.push(...walkMarkdown(rootDir, fullPath));
-    else if (stat.isFile() && fullPath.endsWith(".md")) files.push(fullPath);
-  }
-  return Array.from(new Set(files)).sort();
-}
-function walkMarkdown(rootDir, dir) {
-  const files = [];
-  for (const entry of readdirSync3(dir, { withFileTypes: true })) {
-    const fullPath = join6(dir, entry.name);
-    const repoPath = toRepoPath(rootDir, fullPath);
-    if (shouldSkipTree(repoPath)) continue;
-    if (entry.isSymbolicLink()) continue;
-    if (entry.isDirectory()) files.push(...walkMarkdown(rootDir, fullPath));
-    if (entry.isFile() && entry.name.endsWith(".md") && shouldIncludeSource(repoPath)) {
-      files.push(fullPath);
-    }
-  }
-  return files;
+  return listMarkdownFiles(rootDir, CURRENT_MARKDOWN_ROOTS, {
+    shouldSkipTree,
+    includeFile: (repoPath) => repoPath === "AGENTS.md" || repoPath === "README.md" || shouldIncludeSource(repoPath)
+  });
 }
 function shouldSkipTree(repoPath) {
   if (isExternalArtifactPath(repoPath)) return true;
@@ -794,7 +898,7 @@ function shouldIgnoreTarget(target) {
 function localTargetExists(rootDir, sourcePath, target) {
   const pathPart = decodeTarget(target).split("#")[0]?.split("?")[0] ?? "";
   if (!pathPart) return true;
-  const resolved = pathPart.startsWith("/") ? resolve(rootDir, `.${pathPart}`) : resolve(dirname3(sourcePath), pathPart);
+  const resolved = pathPart.startsWith("/") ? resolve2(rootDir, `.${pathPart}`) : resolve2(dirname4(sourcePath), pathPart);
   const candidates = [resolved];
   if (!extname(resolved)) {
     candidates.push(`${resolved}.md`);
@@ -816,7 +920,7 @@ function lineNumberAt(content, index) {
   return line;
 }
 function readText(filePath) {
-  return readFileSync5(filePath, "utf8");
+  return readFileSync6(filePath, "utf8");
 }
 
 // src/commands/audit.ts
@@ -844,7 +948,7 @@ function runAudit() {
       "Stray root-level DocSystemStarter.md exists. The original draft has been archived; remove or re-archive."
     );
   }
-  const rootEntries = new Set(readdirSync4(root));
+  const rootEntries = new Set(readdirSync2(root));
   if (rootEntries.has("Docs")) {
     console.error(
       "Old Docs/ directory still exists. Move remaining files into docs/ or archive them."
@@ -863,7 +967,7 @@ function runAudit() {
 }
 function countFiles(dir) {
   let count = 0;
-  for (const entry of readdirSync4(dir, { withFileTypes: true })) {
+  for (const entry of readdirSync2(dir, { withFileTypes: true })) {
     const path = join7(dir, entry.name);
     if (entry.isDirectory()) count += countFiles(path);
     if (entry.isFile() || entry.isSymbolicLink()) count += 1;
@@ -886,12 +990,12 @@ function runCheck() {
 
 // src/commands/doctor.ts
 import { spawnSync } from "node:child_process";
-import { existsSync as existsSync7, readFileSync as readFileSync7 } from "node:fs";
-import { isAbsolute, join as join9, resolve as resolve2 } from "node:path";
+import { existsSync as existsSync7, readFileSync as readFileSync8 } from "node:fs";
+import { isAbsolute as isAbsolute2, join as join9, resolve as resolve3 } from "node:path";
 
 // src/core/router-integrity.ts
-import { existsSync as existsSync6, lstatSync as lstatSync2, readlinkSync, readdirSync as readdirSync5, readFileSync as readFileSync6 } from "node:fs";
-import { join as join8, relative as relative2 } from "node:path";
+import { existsSync as existsSync6, lstatSync as lstatSync2, readlinkSync, readFileSync as readFileSync7 } from "node:fs";
+import { join as join8, relative as relative3 } from "node:path";
 
 // src/core/symlinks.ts
 function normalizeSymlinkTarget(target) {
@@ -1286,7 +1390,7 @@ function checkRouterIntegrity(rootDir = process.cwd()) {
   for (const requirement of requiredNeedles) {
     const path = join8(rootDir, requirement.file);
     if (!existsSync6(path)) continue;
-    const content = readFileSync6(path, "utf8");
+    const content = readFileSync7(path, "utf8");
     if (!content.includes(requirement.needle)) {
       issues.push({
         file: requirement.file,
@@ -1332,7 +1436,7 @@ function validateHostSsot(rootDir) {
   validateExactSymlink(".claude/skills", "../.agents/skills");
   return issues;
   function validateRegularFile(file) {
-    const stat = safeLstat(join8(rootDir, file));
+    const stat = safeLstat2(join8(rootDir, file));
     if (!stat || stat.isFile()) return;
     issues.push({
       file,
@@ -1341,7 +1445,7 @@ function validateHostSsot(rootDir) {
     });
   }
   function validateDirectory(file) {
-    const stat = safeLstat(join8(rootDir, file));
+    const stat = safeLstat2(join8(rootDir, file));
     if (!stat || stat.isDirectory()) return;
     issues.push({
       file,
@@ -1351,7 +1455,7 @@ function validateHostSsot(rootDir) {
   }
   function validateExactSymlink(file, expectedRawTarget) {
     const path = join8(rootDir, file);
-    const stat = safeLstat(path);
+    const stat = safeLstat2(path);
     if (!stat) return;
     if (!stat.isSymbolicLink()) {
       issues.push({
@@ -1371,7 +1475,7 @@ function validateHostSsot(rootDir) {
     }
   }
 }
-function safeLstat(path) {
+function safeLstat2(path) {
   try {
     return lstatSync2(path);
   } catch (error) {
@@ -1389,7 +1493,7 @@ function isCentralRepository(rootDir) {
 }
 function readPackageName(packageJsonPath) {
   try {
-    const packageJson = JSON.parse(readFileSync6(packageJsonPath, "utf8"));
+    const packageJson = JSON.parse(readFileSync7(packageJsonPath, "utf8"));
     return typeof packageJson.name === "string" ? packageJson.name : "";
   } catch {
     return "";
@@ -1413,7 +1517,7 @@ function validateProjectAgentsRouting(rootDir) {
   }
   const agentsPath = join8(rootDir, "AGENTS.md");
   if (!existsSync6(agentsPath)) return issues;
-  const agents = readFileSync6(agentsPath, "utf8");
+  const agents = readFileSync7(agentsPath, "utf8");
   if (!existingRoutes.some((file) => agents.includes(file))) {
     issues.push({
       file: "AGENTS.md",
@@ -1426,7 +1530,7 @@ function validateProjectAgentsRouting(rootDir) {
 function validateRouterBlock(rootDir, file) {
   const path = join8(rootDir, file);
   if (!existsSync6(path)) return [];
-  const content = readFileSync6(path, "utf8");
+  const content = readFileSync7(path, "utf8");
   const begin = content.indexOf(ROUTER_BLOCK_BEGIN);
   const end = content.indexOf(ROUTER_BLOCK_END);
   const issues = [];
@@ -1453,7 +1557,7 @@ function validateRouterBlock(rootDir, file) {
 function validateBacktickedLocalPaths(rootDir, file, pathRoot = "") {
   const path = join8(rootDir, file);
   if (!existsSync6(path)) return [];
-  const content = readFileSync6(path, "utf8");
+  const content = readFileSync7(path, "utf8");
   const issues = [];
   const seen = /* @__PURE__ */ new Set();
   const matches = content.matchAll(/`([^`]+)`/g);
@@ -1484,7 +1588,7 @@ function isLocalPathReference(value) {
 function validatePortableRouterText(rootDir, file) {
   const path = join8(rootDir, file);
   if (!existsSync6(path)) return [];
-  const content = readFileSync6(path, "utf8");
+  const content = readFileSync7(path, "utf8");
   if (!hasNonPortablePath(content)) return [];
   return [
     {
@@ -1504,25 +1608,9 @@ function hasNonPortablePath(content) {
   ) || /\b(OneDrive|CloudStorage)\b/.test(content);
 }
 function findGovernedReadmes(rootDir) {
-  const matches = [];
-  for (const relRoot of ["docs", "starter/docs"]) {
-    const absRoot = join8(rootDir, relRoot);
-    if (existsSync6(absRoot)) walk2(absRoot);
-  }
-  return matches.sort();
-  function walk2(dir) {
-    for (const entry of readdirSync5(dir, { withFileTypes: true })) {
-      if (entry.isSymbolicLink()) continue;
-      if (entry.isDirectory()) {
-        walk2(join8(dir, entry.name));
-        continue;
-      }
-      if (!entry.isFile()) continue;
-      if (entry.name.toLowerCase() !== "readme.md") continue;
-      const repoPath = relative2(rootDir, join8(dir, entry.name)).split(/\\/g).join("/");
-      if (repoPath !== "README.md") matches.push(repoPath);
-    }
-  }
+  return listMarkdownFiles(rootDir, ["docs", "starter/docs"], {
+    includeFile: (repoPath) => repoPath.toLowerCase().endsWith("/readme.md")
+  }).map((path) => relative3(rootDir, path).split(/\\/g).join("/")).filter((repoPath) => repoPath !== "README.md");
 }
 
 // src/commands/doctor.ts
@@ -1600,7 +1688,7 @@ function checkLefthook(rootDir) {
       }
     ];
   }
-  const content = readFileSync7(path, "utf8");
+  const content = readFileSync8(path, "utf8");
   const issues = [];
   for (const command2 of [
     "pnpm doc-gov router-check",
@@ -1647,7 +1735,7 @@ function checkDocsCheckWorkflow(rootDir) {
       }
     ];
   }
-  const content = readFileSync7(path, "utf8");
+  const content = readFileSync8(path, "utf8");
   const issues = [];
   for (const command2 of [
     "pnpm doc-gov router-check",
@@ -1667,7 +1755,7 @@ function checkDocsCheckWorkflow(rootDir) {
   return issues;
 }
 function hookCallsLefthook(path) {
-  return existsSync7(path) && readFileSync7(path, "utf8").includes("lefthook");
+  return existsSync7(path) && readFileSync8(path, "utf8").includes("lefthook");
 }
 function resolveGitHookPath(rootDir, hookName) {
   const result = spawnSync("git", ["-C", rootDir, "rev-parse", "--git-path", `hooks/${hookName}`], {
@@ -1675,7 +1763,7 @@ function resolveGitHookPath(rootDir, hookName) {
   });
   const gitPath = result.status === 0 ? result.stdout.trim() : "";
   if (!gitPath) return join9(rootDir, ".git/hooks", hookName);
-  return isAbsolute(gitPath) ? gitPath : resolve2(rootDir, gitPath);
+  return isAbsolute2(gitPath) ? gitPath : resolve3(rootDir, gitPath);
 }
 
 // src/commands/find.ts
@@ -1717,7 +1805,7 @@ import { existsSync as existsSync9, mkdirSync as mkdirSync4, writeFileSync as wr
 import { join as join11 } from "node:path";
 
 // src/core/templates.ts
-import { existsSync as existsSync8, mkdirSync as mkdirSync3, readFileSync as readFileSync8, writeFileSync as writeFileSync4 } from "node:fs";
+import { existsSync as existsSync8, mkdirSync as mkdirSync3, readFileSync as readFileSync9, writeFileSync as writeFileSync4 } from "node:fs";
 import { join as join10 } from "node:path";
 var TEMPLATE_FILES = {
   decision: "adr.md",
@@ -1927,7 +2015,7 @@ function loadTemplate(rootDir, type) {
   const file = TEMPLATE_FILES[type];
   if (!file) throw new Error(`No template file mapped for type: ${type}`);
   const path = join10(rootDir, "docs/governance/templates", file);
-  if (existsSync8(path)) return readFileSync8(path, "utf8");
+  if (existsSync8(path)) return readFileSync9(path, "utf8");
   const fallback = DEFAULT_TEMPLATES[file];
   if (fallback) return fallback;
   throw new Error(`Template file is missing: docs/governance/templates/${file}`);
@@ -2049,7 +2137,7 @@ function runLinks() {
 }
 
 // src/commands/migrate.ts
-import { existsSync as existsSync10, readFileSync as readFileSync9 } from "node:fs";
+import { existsSync as existsSync10, readFileSync as readFileSync10 } from "node:fs";
 import { join as join12 } from "node:path";
 var PROFILE_ROUTES = {
   "engineering-runtime": "docs/governance/agents-routing/engineering-runtime-v1.1.md",
@@ -2091,7 +2179,7 @@ function checkMigrationReadiness(rootDir, profile) {
     issues.push(`missing selected profile route: ${route}`);
   }
   const agentsPath = join12(rootDir, "AGENTS.md");
-  if (existsSync10(agentsPath) && !readFileSync9(agentsPath, "utf8").includes(route)) {
+  if (existsSync10(agentsPath) && !readFileSync10(agentsPath, "utf8").includes(route)) {
     issues.push(`AGENTS.md must name selected profile route: ${route}`);
   }
   return issues;
@@ -2139,7 +2227,7 @@ function readFlag(args2, name) {
 
 // src/commands/new.ts
 import { existsSync as existsSync11, mkdirSync as mkdirSync5, writeFileSync as writeFileSync6 } from "node:fs";
-import { dirname as dirname4, join as join13 } from "node:path";
+import { dirname as dirname5, join as join13 } from "node:path";
 function runNew(args2) {
   const positional = args2.filter((a) => !a.startsWith("--"));
   const owner = readFlag2(args2, "--owner") ?? "human";
@@ -2188,7 +2276,7 @@ function runNew(args2) {
     tags: [plan.slug.split("-")[0] ?? "replace-me"],
     pinned: false
   });
-  mkdirSync5(dirname4(absPath), { recursive: true });
+  mkdirSync5(dirname5(absPath), { recursive: true });
   writeFileSync6(absPath, rendered);
   console.log(`Created ${plan.filePath} with id ${plan.id}.`);
   try {
@@ -2249,7 +2337,7 @@ function runScan(args2) {
 }
 
 // src/commands/supersede.ts
-import { readFileSync as readFileSync10, writeFileSync as writeFileSync7 } from "node:fs";
+import { readFileSync as readFileSync11, writeFileSync as writeFileSync7 } from "node:fs";
 import { join as join14 } from "node:path";
 function runSupersede(args2) {
   const [oldId, newId] = args2;
@@ -2287,14 +2375,14 @@ function runSupersede(args2) {
   }
   const today = todayIso();
   const oldPath = join14(root, oldRec.path);
-  let oldContent = readFileSync10(oldPath, "utf8");
+  let oldContent = readFileSync11(oldPath, "utf8");
   oldContent = updateFrontmatterField(oldContent, "status", "superseded");
   oldContent = updateFrontmatterField(oldContent, "canonical", "false");
   oldContent = updateFrontmatterField(oldContent, "superseded_by", newId);
   oldContent = updateFrontmatterField(oldContent, "last_reviewed", today);
   writeFileSync7(oldPath, oldContent);
   const newPath = join14(root, newRec.path);
-  let newContent = readFileSync10(newPath, "utf8");
+  let newContent = readFileSync11(newPath, "utf8");
   newContent = appendToFrontmatterList(newContent, "supersedes", newId === oldId ? "" : oldId);
   newContent = updateFrontmatterField(newContent, "last_reviewed", today);
   writeFileSync7(newPath, newContent);
@@ -2343,13 +2431,13 @@ ${lines.join("\n")}${tail}`;
 
 // src/commands/verify-commit-msg.ts
 import { execFileSync as execFileSync2 } from "node:child_process";
-import { existsSync as existsSync12, readFileSync as readFileSync11 } from "node:fs";
+import { existsSync as existsSync12, readFileSync as readFileSync12 } from "node:fs";
 function runVerifyCommitMsg(args2) {
   const msgFile = args2[0];
   if (!msgFile || !existsSync12(msgFile)) {
     return 0;
   }
-  const message = readFileSync11(msgFile, "utf8");
+  const message = readFileSync12(msgFile, "utf8");
   if (/^Merge\b/m.test(message) || /^Revert\b/m.test(message)) return 0;
   let stagedFiles = [];
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pieai/doc-gov",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "description": "AI-native documentation governance CLI for project docs, agent routing, and lifecycle checks.",
   "keywords": [
     "ai-agents",