@pieai/doc-gov 0.3.0

package/dist/cli.js

@@ -0,0 +1,2387 @@
+#!/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";
+
+// src/core/frontmatter.ts
+import { readFileSync } from "node:fs";
+function readFrontmatterFile(path) {
+  const content = readFileSync(path, "utf8");
+  if (!content.startsWith("---\n")) return null;
+  const closing = content.indexOf("\n---", 4);
+  if (closing === -1) return null;
+  const raw = content.slice(4, closing).trimEnd();
+  const body = content.slice(closing + 4).replace(/^\n/, "");
+  return { path, body, raw, data: parseFrontmatter(raw) };
+}
+function parseFrontmatter(raw) {
+  const data = {};
+  let currentArrayKey = "";
+  for (const line of raw.split("\n")) {
+    if (!line.trim() || line.trimStart().startsWith("#")) continue;
+    const arrayItem = line.match(/^\s+-\s+(.+)$/);
+    if (arrayItem && currentArrayKey) {
+      const value2 = data[currentArrayKey];
+      if (Array.isArray(value2)) value2.push(parseScalar(arrayItem[1] ?? ""));
+      continue;
+    }
+    const keyValue = line.match(/^([A-Za-z0-9_-]+):(?:\s*(.*))?$/);
+    if (!keyValue) {
+      currentArrayKey = "";
+      continue;
+    }
+    const key = keyValue[1] ?? "";
+    const value = keyValue[2] ?? "";
+    if (!value) {
+      data[key] = [];
+      currentArrayKey = key;
+      continue;
+    }
+    data[key] = parseScalar(value);
+    currentArrayKey = "";
+  }
+  return data;
+}
+function stringValue(value) {
+  return typeof value === "string" ? value : "";
+}
+function booleanValue(value) {
+  if (typeof value === "boolean") return value;
+  if (value === "true") return true;
+  if (value === "false") return false;
+  return null;
+}
+function stringArrayValue(value) {
+  return Array.isArray(value) ? value : [];
+}
+function parseScalar(value) {
+  const trimmed = value.trim().replace(/^['"]|['"]$/g, "");
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+  if (trimmed === "null") return null;
+  if (trimmed === "[]") return [];
+  return trimmed;
+}
+
+// src/core/files.ts
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+function listGovernedMarkdownFiles(rootDir) {
+  const roots = [join(rootDir, "docs")];
+  const files = [];
+  for (const root of roots) {
+    if (!existsSync(root)) continue;
+    files.push(...walk(rootDir, root));
+  }
+  return files.sort();
+}
+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);
+  }
+  return files;
+}
+function shouldSkip(repoPath) {
+  return repoPath.startsWith("docs/governance/templates/") || repoPath === "docs/governance/MANIFEST.yml";
+}
+function toRepoPath(rootDir, absolutePath) {
+  return relative(rootDir, absolutePath).split(/\\/g).join("/");
+}
+
+// src/core/lifecycle.ts
+var normalStatuses = [
+  "draft",
+  "active",
+  "completed",
+  "stable",
+  "superseded",
+  "archived"
+];
+var decisionStatuses = ["proposed", "accepted", "rejected", "superseded"];
+
+// src/core/schema.ts
+var docTypes = [
+  "policy",
+  "decision",
+  "spec",
+  "plan",
+  "canon",
+  "reference",
+  "archive"
+];
+function validateFrontmatter(rootDir, file) {
+  const path = toRepoPath(rootDir, file.path);
+  const issues = [];
+  const data = file.data;
+  const id = stringValue(data.id);
+  const title = stringValue(data.title);
+  const type = stringValue(data.type);
+  const status = stringValue(data.status);
+  const canonical = booleanValue(data.canonical);
+  const owner = stringValue(data.owner);
+  const created = stringValue(data.created);
+  const lastReviewed = stringValue(data.last_reviewed);
+  const domain = stringValue(data.domain);
+  const tags = stringArrayValue(data.tags);
+  const related = stringArrayValue(data.related);
+  const pinned = booleanValue(data.pinned) ?? false;
+  const supersedes = stringArrayValue(data.supersedes);
+  const supersededByRaw = stringValue(data.superseded_by);
+  const supersededBy = supersededByRaw ? supersededByRaw : void 0;
+  const archiveReasonRaw = stringValue(data.archive_reason);
+  const archiveReason = archiveReasonRaw ? archiveReasonRaw : void 0;
+  for (const [field, value] of Object.entries({
+    id,
+    title,
+    type,
+    status,
+    owner,
+    created,
+    last_reviewed: lastReviewed
+  })) {
+    if (!value)
+      issues.push({
+        file: path,
+        code: "missing-field",
+        message: `Missing required frontmatter field: ${field}`
+      });
+  }
+  if (canonical === null)
+    issues.push({
+      file: path,
+      code: "invalid-canonical",
+      message: "canonical must be true or false."
+    });
+  if (!docTypes.includes(type)) {
+    issues.push({ file: path, code: "invalid-type", message: `Invalid type: ${type}` });
+  }
+  const allowedStatuses = type === "decision" ? decisionStatuses : normalStatuses;
+  if (!allowedStatuses.includes(status)) {
+    issues.push({
+      file: path,
+      code: "invalid-status",
+      message: `Invalid status for ${type}: ${status}`
+    });
+  }
+  if ((status === "archived" || status === "superseded" || status === "rejected") && canonical !== false) {
+    issues.push({
+      file: path,
+      code: "terminal-canonical",
+      message: `${status} documents must have canonical: false.`
+    });
+  }
+  if (!isPathAllowedForType(path, type)) {
+    issues.push({
+      file: path,
+      code: "path-type-mismatch",
+      message: `Path does not match type ${type}.`
+    });
+  }
+  if (tags.length === 0) {
+    issues.push({
+      file: path,
+      code: "missing-tags",
+      message: "tags must contain at least one item."
+    });
+  }
+  if (created && lastReviewed && lastReviewed < created) {
+    issues.push({
+      file: path,
+      code: "bad-review-date",
+      message: "last_reviewed cannot be earlier than created."
+    });
+  }
+  if (status === "superseded" && !supersededBy) {
+    issues.push({
+      file: path,
+      code: "missing-superseded-by",
+      message: "status=superseded requires superseded_by to point at the successor document id."
+    });
+  }
+  if (issues.length > 0) return { issues };
+  return {
+    issues,
+    record: {
+      id,
+      title,
+      type,
+      status,
+      canonical: canonical ?? false,
+      owner,
+      created,
+      lastReviewed,
+      domain,
+      tags,
+      pinned,
+      related,
+      supersedes,
+      supersededBy,
+      archiveReason,
+      path
+    }
+  };
+}
+function isPathAllowedForType(path, type) {
+  if (path.startsWith("docs/governance/") && !path.startsWith("docs/governance/templates/")) {
+    return type === "policy" || type === "reference";
+  }
+  if (type === "policy") return path.startsWith("docs/policy/");
+  if (type === "decision") return path.startsWith("docs/decisions/");
+  if (type === "spec") return path.startsWith("docs/specs/");
+  if (type === "plan") return path.startsWith("docs/plans/");
+  if (type === "canon") return path.startsWith("docs/canon/");
+  if (type === "reference") return path.startsWith("docs/reference/");
+  if (type === "archive") return path.startsWith("docs/archive/");
+  return false;
+}
+
+// src/core/checker.ts
+function checkDocs(rootDir = process.cwd()) {
+  const issues = [];
+  const records = [];
+  for (const path of listGovernedMarkdownFiles(rootDir)) {
+    const repoPath = pathToRepo(rootDir, path);
+    issues.push(...validateGovernedPath(repoPath));
+    const file = readFrontmatterFile(path);
+    if (!file) {
+      issues.push({
+        file: repoPath,
+        code: "missing-frontmatter",
+        message: "Markdown file must start with YAML frontmatter."
+      });
+      continue;
+    }
+    const result = validateFrontmatter(rootDir, file);
+    issues.push(...result.issues);
+    if (result.record) records.push(result.record);
+  }
+  issues.push(...validateGlobalIntegrity(records));
+  return {
+    ok: issues.length === 0,
+    records: records.sort((a, b) => a.path.localeCompare(b.path)),
+    issues
+  };
+}
+function validateGlobalIntegrity(records) {
+  const issues = [];
+  const byId = /* @__PURE__ */ new Map();
+  for (const record of records) {
+    byId.set(record.id, [...byId.get(record.id) ?? [], record]);
+  }
+  for (const [id, matches] of byId.entries()) {
+    if (matches.length > 1) {
+      for (const match of matches) {
+        issues.push({
+          file: match.path,
+          code: "duplicate-id",
+          message: `Duplicate document id: ${id}`
+        });
+      }
+    }
+  }
+  const ids = new Set(records.map((record) => record.id));
+  for (const record of records) {
+    for (const relatedId of record.related) {
+      if (!ids.has(relatedId)) {
+        issues.push({
+          file: record.path,
+          code: "missing-related",
+          message: `related id does not exist: ${relatedId}`
+        });
+      }
+    }
+    for (const supersededId of record.supersedes) {
+      if (!ids.has(supersededId)) {
+        issues.push({
+          file: record.path,
+          code: "missing-supersedes",
+          message: `supersedes id does not exist: ${supersededId}`
+        });
+      }
+    }
+    if (record.supersededBy && !ids.has(record.supersededBy)) {
+      issues.push({
+        file: record.path,
+        code: "missing-superseded-by-target",
+        message: `superseded_by id does not exist: ${record.supersededBy}`
+      });
+    }
+  }
+  return issues;
+}
+function validateGovernedPath(path) {
+  const issues = [];
+  const segments = path.split("/");
+  const fileName = segments[segments.length - 1] ?? "";
+  const baseName = fileName.replace(/\.md$/i, "").toLowerCase();
+  if (fileName.toLowerCase() === "readme.md") {
+    issues.push({
+      file: path,
+      code: "non-root-readme",
+      message: "Governed docs must use purpose-based names, not README.md. Keep README.md as the root human introduction only."
+    });
+  }
+  const forbiddenFileNames = /* @__PURE__ */ new Set([
+    "temp",
+    "tmp",
+    "scratch",
+    "notes",
+    "untitled",
+    "new",
+    "copy",
+    "final",
+    "final-final",
+    "final-v2",
+    "latest",
+    "wip",
+    "todo"
+  ]);
+  if (forbiddenFileNames.has(baseName)) {
+    issues.push({
+      file: path,
+      code: "forbidden-doc-name",
+      message: "Governed docs must use content-based names, not temp/latest/final/todo-style names."
+    });
+  }
+  const aiNameSegment = segments.find(
+    (segment) => /^(opus|codex|copilot|claude|gemini|cursor)(?:[-_ .]?\d.*)?$/i.test(segment)
+  );
+  if (aiNameSegment) {
+    issues.push({
+      file: path,
+      code: "ai-name-directory",
+      message: `Do not classify governed docs by AI/tool name (${aiNameSegment}); classify by type and domain.`
+    });
+  }
+  return issues;
+}
+function pathToRepo(rootDir, path) {
+  return path.startsWith(rootDir) ? path.slice(rootDir.length + 1).split(/\\/g).join("/") : path;
+}
+
+// src/core/paths.ts
+import { existsSync as existsSync2, readdirSync as readdirSync2 } from "node:fs";
+import { join as join2 } from "node:path";
+function planPath(rootDir, type, slugInput) {
+  const cleanSlug = slugInput.replace(/^\/+|\/+$/g, "");
+  if (!cleanSlug) throw new Error("Slug is required.");
+  const parts = cleanSlug.split("/").filter(Boolean);
+  const baseSlug = parts[parts.length - 1] ?? "";
+  const subdir = parts.slice(0, -1).join("/");
+  if (!isKebabCase(baseSlug)) {
+    throw new Error(`Slug "${baseSlug}" must be kebab-case (lowercase, digits, hyphens).`);
+  }
+  if (type === "decision") {
+    const n = nextSerial(rootDir, "docs/decisions", /^ADR-(\d{4})-/);
+    return {
+      filePath: `docs/decisions/ADR-${n}-${baseSlug}.md`,
+      id: `ADR-${n}`,
+      slug: baseSlug,
+      subdir: ""
+    };
+  }
+  if (type === "spec") {
+    const n = nextSerial(rootDir, "docs/specs", /^SPEC-(\d{4})-/);
+    return {
+      filePath: `docs/specs/active/SPEC-${n}-${baseSlug}.md`,
+      id: `SPEC-${n}`,
+      slug: baseSlug,
+      subdir: ""
+    };
+  }
+  if (type === "plan") {
+    const n = nextSerial(rootDir, "docs/plans", /^PLAN-(\d{4})-/);
+    return {
+      filePath: `docs/plans/active/PLAN-${n}-${baseSlug}.md`,
+      id: `PLAN-${n}`,
+      slug: baseSlug,
+      subdir: ""
+    };
+  }
+  if (type === "canon") {
+    const dir = subdir ? `docs/canon/${subdir}` : "docs/canon";
+    return {
+      filePath: `${dir}/${baseSlug}.md`,
+      id: kebabToUpper(baseSlug),
+      slug: baseSlug,
+      subdir
+    };
+  }
+  if (type === "policy") {
+    return {
+      filePath: `docs/policy/${baseSlug}.md`,
+      id: kebabToUpper(baseSlug),
+      slug: baseSlug,
+      subdir: ""
+    };
+  }
+  if (type === "reference") {
+    const dir = subdir ? `docs/reference/${subdir}` : "docs/reference";
+    return {
+      filePath: `${dir}/${baseSlug}.md`,
+      id: `REF-${kebabToUpper(baseSlug)}`,
+      slug: baseSlug,
+      subdir
+    };
+  }
+  if (type === "archive") {
+    throw new Error('Use "doc-gov archive <id>" instead of "doc-gov new archive ...".');
+  }
+  throw new Error(`Unknown type: ${type}`);
+}
+function nextSerial(rootDir, scanDir, regex) {
+  const root = join2(rootDir, scanDir);
+  if (!existsSync2(root)) return "0001";
+  let max = 0;
+  walkSerial(root, 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 isKebabCase(slug) {
+  return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug);
+}
+function kebabToUpper(slug) {
+  return slug.toUpperCase();
+}
+function quarterTag(date = /* @__PURE__ */ new Date()) {
+  const y = date.getUTCFullYear();
+  const q = Math.floor(date.getUTCMonth() / 3) + 1;
+  return `${y}-q${q}`;
+}
+function todayIso() {
+  return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+}
+
+// src/core/manifest.ts
+import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "node:fs";
+import { dirname, join as join3 } from "node:path";
+function buildManifest(rootDir = process.cwd()) {
+  const result = checkDocs(rootDir);
+  if (!result.ok) {
+    const error = result.issues.map((issue) => `${issue.file}: ${issue.code}: ${issue.message}`).join("\n");
+    throw new Error(`Cannot build manifest while doc-gov check fails:
+${error}`);
+  }
+  return renderManifest(result.records);
+}
+function writeManifest(rootDir = process.cwd()) {
+  const manifest = buildManifest(rootDir);
+  const path = join3(rootDir, "docs/governance/MANIFEST.yml");
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, manifest);
+}
+function manifestInSync(rootDir = process.cwd()) {
+  const path = join3(rootDir, "docs/governance/MANIFEST.yml");
+  if (!existsSync3(path)) return false;
+  return normalizeManifest(readFileSync2(path, "utf8")) === normalizeManifest(buildManifest(rootDir));
+}
+function normalizeManifest(value) {
+  return value.replace(/^generated_at: .*$/m, "generated_at: <ignored>").replace(/^generator_version: .*$/m, "generator_version: <ignored>");
+}
+function renderManifest(records) {
+  const lines = [
+    "# docs/governance/MANIFEST.yml \u2014 auto-generated, DO NOT EDIT MANUALLY",
+    "# Regenerate: pnpm doc-gov scan",
+    `generated_at: ${(/* @__PURE__ */ new Date()).toISOString()}`,
+    "generator_version: doc-gov@0.3.0",
+    `docs_count: ${records.length}`,
+    "docs:"
+  ];
+  for (const record of records) {
+    lines.push(`  - id: ${record.id}`);
+    lines.push(`    path: ${record.path}`);
+    lines.push(`    type: ${record.type}`);
+    lines.push(`    status: ${record.status}`);
+    lines.push(`    canonical: ${record.canonical}`);
+    lines.push(`    last_reviewed: ${record.lastReviewed}`);
+    lines.push(`    pinned: ${record.pinned}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+// src/commands/approve.ts
+function runApprove(args2) {
+  const id = args2[0];
+  if (!id) {
+    console.error("Usage: pnpm doc-gov approve <id>");
+    return 1;
+  }
+  const root = process.cwd();
+  const result = checkDocs(root);
+  if (!result.ok) {
+    console.error("doc-gov check currently fails; fix issues before approving.");
+    return 1;
+  }
+  const record = result.records.find((r) => r.id === id);
+  if (!record) {
+    console.error(`No doc found with id: ${id}`);
+    return 1;
+  }
+  const fromStatus = record.status;
+  let toStatus;
+  if (fromStatus === "draft") toStatus = "active";
+  else if (fromStatus === "proposed") toStatus = "accepted";
+  else {
+    console.error(
+      `Cannot approve doc with status=${fromStatus}. Only draft or proposed can be approved.`
+    );
+    return 1;
+  }
+  const filePath = join4(root, record.path);
+  const content = readFileSync3(filePath, "utf8");
+  let next = content;
+  next = updateFrontmatterField(next, "status", toStatus);
+  next = updateFrontmatterField(next, "canonical", "true");
+  next = updateFrontmatterField(next, "last_reviewed", todayIso());
+  writeFileSync2(filePath, next);
+  console.log(`Approved ${id}: ${fromStatus} \u2192 ${toStatus}, canonical=true.`);
+  console.log(`
+IMPORTANT: when committing this change, include in the commit message:`);
+  console.log(`  Approves: ${id}`);
+  console.log(`(Lefthook commit-msg hook checks for this line on draft\u2192active transitions.)`);
+  try {
+    writeManifest(root);
+  } catch (err) {
+    console.error(err.message);
+    return 1;
+  }
+  return 0;
+}
+function updateFrontmatterField(content, key, value) {
+  if (!content.startsWith("---\n")) {
+    throw new Error("File has no frontmatter.");
+  }
+  const closing = content.indexOf("\n---", 4);
+  if (closing === -1) throw new Error("Frontmatter is unterminated.");
+  const head = content.slice(4, closing);
+  const tail = content.slice(closing);
+  const lines = head.split("\n");
+  const re = new RegExp(`^${key}:`);
+  let replaced = false;
+  const newLines = lines.map((line) => {
+    if (re.test(line) && !replaced) {
+      replaced = true;
+      return `${key}: ${value}`;
+    }
+    return line;
+  });
+  if (!replaced) {
+    newLines.push(`${key}: ${value}`);
+  }
+  return `---
+${newLines.join("\n")}${tail}`;
+}
+
+// src/commands/archive.ts
+import { execSync } 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";
+function runArchive(args2) {
+  const positional = args2.filter((a) => !a.startsWith("--"));
+  const id = positional[0];
+  const reasonIdx = args2.indexOf("--reason");
+  const reason = reasonIdx !== -1 ? args2[reasonIdx + 1] ?? "" : "";
+  if (!id) {
+    console.error("Usage: pnpm doc-gov archive <id> [--reason <text>]");
+    return 1;
+  }
+  if (!reason) {
+    console.error("--reason is required (one short sentence describing why this doc is retired).");
+    return 1;
+  }
+  const root = process.cwd();
+  const result = checkDocs(root);
+  if (!result.ok) {
+    console.error("doc-gov check currently fails; fix issues before archiving.");
+    return 1;
+  }
+  const record = result.records.find((r) => r.id === id);
+  if (!record) {
+    console.error(`No doc with id: ${id}`);
+    return 1;
+  }
+  if (record.pinned) {
+    console.error(
+      `${id} is pinned. A human must commit the archival with "Pinned-Override: ${id}".`
+    );
+    return 1;
+  }
+  if (record.type === "archive") {
+    console.error(`${id} is already archived.`);
+    return 1;
+  }
+  const oldPath = record.path;
+  const fileName = basename(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");
+  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 });
+  let movedByGit = false;
+  try {
+    execSync(`git mv "${oldPath}" "${newPath}"`, { cwd: root, stdio: "ignore" });
+    movedByGit = true;
+  } catch {
+    renameSync(absOld, absNew);
+  }
+  writeFileSync3(absNew, content);
+  console.log(
+    `Archived ${id}: ${oldPath} \u2192 ${newPath}${movedByGit ? " (git mv)" : " (fs rename)"}`
+  );
+  try {
+    writeManifest(root);
+    console.log("MANIFEST.yml regenerated.");
+  } catch (err) {
+    console.error(err.message);
+    return 1;
+  }
+  return 0;
+}
+
+// src/commands/audit.ts
+import { existsSync as existsSync5, readdirSync as readdirSync4 } 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";
+var CURRENT_MARKDOWN_ROOTS = ["AGENTS.md", "README.md", "docs"];
+var CURRENT_DOC_DIR_PREFIXES = [
+  "docs/canon/",
+  "docs/reference/",
+  "docs/plans/",
+  "docs/specs/",
+  "docs/decisions/",
+  "docs/policy/"
+];
+var LINK_PATTERN = /!??\[[^\]\n]*\]\(([^)\n]+)\)/g;
+function checkCurrentMarkdownLinks(rootDir = process.cwd()) {
+  const files = listCurrentMarkdownFiles(rootDir);
+  const issues = [];
+  let checkedLinks = 0;
+  for (const filePath of files) {
+    const content = readText(filePath);
+    let match;
+    while (match = LINK_PATTERN.exec(content)) {
+      const rawTarget = match[1]?.trim();
+      if (!rawTarget) continue;
+      const target = parseMarkdownLinkTarget(rawTarget);
+      if (!target || shouldIgnoreTarget(target)) continue;
+      checkedLinks += 1;
+      if (!localTargetExists(rootDir, filePath, target)) {
+        const file = toRepoPath(rootDir, filePath);
+        const line = lineNumberAt(content, match.index);
+        issues.push({
+          file,
+          line,
+          target,
+          message: `Broken current doc link: ${file}:${line} -> ${target}`
+        });
+      }
+    }
+  }
+  return {
+    ok: issues.length === 0,
+    checkedFiles: files.length,
+    checkedLinks,
+    issues
+  };
+}
+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;
+}
+function shouldSkipTree(repoPath) {
+  if (repoPath.startsWith("docs/archive/")) return true;
+  if (repoPath.startsWith("docs/governance/templates/")) return true;
+  if (repoPath === "docs/governance/MANIFEST.yml") return true;
+  return false;
+}
+function shouldIncludeSource(repoPath) {
+  if (repoPath.startsWith("docs/")) {
+    if (repoPath.startsWith("docs/governance/")) return true;
+    return CURRENT_DOC_DIR_PREFIXES.some((prefix) => repoPath.startsWith(prefix));
+  }
+  return false;
+}
+function parseMarkdownLinkTarget(rawTarget) {
+  const trimmed = rawTarget.trim();
+  if (trimmed.startsWith("<")) {
+    const closeIndex = trimmed.indexOf(">");
+    if (closeIndex > 0) return trimmed.slice(1, closeIndex);
+  }
+  return trimmed.split(/\s+/)[0] ?? "";
+}
+function shouldIgnoreTarget(target) {
+  if (target.startsWith("#")) return true;
+  if (target.startsWith("//")) return true;
+  return /^[a-z][a-z0-9+.-]*:/i.test(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 candidates = [resolved];
+  if (!extname(resolved)) {
+    candidates.push(`${resolved}.md`);
+  }
+  return candidates.some((candidate) => existsSync4(candidate));
+}
+function decodeTarget(target) {
+  try {
+    return decodeURIComponent(target);
+  } catch {
+    return target;
+  }
+}
+function lineNumberAt(content, index) {
+  let line = 1;
+  for (let i = 0; i < index; i += 1) {
+    if (content.charCodeAt(i) === 10) line += 1;
+  }
+  return line;
+}
+function readText(filePath) {
+  return readFileSync5(filePath, "utf8");
+}
+
+// src/commands/audit.ts
+function runAudit() {
+  const root = process.cwd();
+  const result = checkDocs(root);
+  let warnings = 0;
+  if (!result.ok) {
+    for (const issue of result.issues) {
+      console.error(`${issue.file}: ${issue.code}: ${issue.message}`);
+    }
+    return 1;
+  }
+  const migrationSource = join7(root, "Docs-for trans");
+  if (existsSync5(migrationSource)) {
+    const count = countFiles(migrationSource);
+    warnings += 1;
+    console.log(
+      `Migration source still exists: Docs-for trans (${count} files). This was a one-time migration shell; it should not be reintroduced.`
+    );
+  }
+  if (existsSync5(join7(root, "DocSystemStarter.md"))) {
+    warnings += 1;
+    console.log(
+      "Stray root-level DocSystemStarter.md exists. The original draft has been archived; remove or re-archive."
+    );
+  }
+  const rootEntries = new Set(readdirSync4(root));
+  if (rootEntries.has("Docs")) {
+    console.error(
+      "Old Docs/ directory still exists. Move remaining files into docs/ or archive them."
+    );
+    return 1;
+  }
+  const linkResult = checkCurrentMarkdownLinks(root);
+  if (!linkResult.ok) {
+    for (const issue of linkResult.issues) {
+      console.error(issue.message);
+    }
+    return 1;
+  }
+  console.log(`doc-gov audit completed with ${warnings} warning(s).`);
+  return 0;
+}
+function countFiles(dir) {
+  let count = 0;
+  for (const entry of readdirSync4(dir, { withFileTypes: true })) {
+    const path = join7(dir, entry.name);
+    if (entry.isDirectory()) count += countFiles(path);
+    if (entry.isFile() || entry.isSymbolicLink()) count += 1;
+  }
+  return count;
+}
+
+// src/commands/check.ts
+function runCheck() {
+  const result = checkDocs(process.cwd());
+  if (!result.ok) {
+    for (const issue of result.issues) {
+      console.error(`${issue.file}: ${issue.code}: ${issue.message}`);
+    }
+    return 1;
+  }
+  console.log(`doc-gov check passed (${result.records.length} docs).`);
+  return 0;
+}
+
+// src/commands/doctor.ts
+import { existsSync as existsSync7, readFileSync as readFileSync7 } from "node:fs";
+import { join as join9 } from "node:path";
+
+// src/core/router-integrity.ts
+import { existsSync as existsSync6, readdirSync as readdirSync5, readFileSync as readFileSync6 } from "node:fs";
+import { join as join8, relative as relative2 } from "node:path";
+var CENTRAL_REQUIRED_FILES = [
+  "AGENTS.md",
+  "README.md",
+  "docs/governance/boundary.md",
+  "docs/governance/ssot-v0.9.md",
+  "docs/governance/templates/adr.md",
+  "docs/governance/templates/spec.md",
+  "docs/governance/templates/plan.md",
+  "docs/governance/templates/canon-entry.md",
+  "docs/governance/templates/reference.md",
+  "docs/governance/templates/policy.md",
+  "docs/governance/templates/archive.md",
+  "docs/governance/agents-routing/engineering-runtime-v0.9.md",
+  "docs/governance/agents-routing/doc-only-v0.9.md",
+  "integrations/superpowers.md",
+  "integrations/directed-development.md",
+  "profiles/engineering-runtime/profile.md",
+  "profiles/engineering-runtime/manifest.yml",
+  "profiles/doc-only/profile.md",
+  "profiles/doc-only/manifest.yml",
+  "starter/AGENTS.template.md",
+  "starter/CLAUDE.template.md",
+  "starter/lefthook.template.yml",
+  "starter/.github/workflows/docs-check.yml",
+  "starter/docs/reference/execution/current-work.md",
+  "starter/docs/policy/best-practice-for-this-project.md",
+  "starter/docs/governance/boundary.md",
+  "starter/docs/governance/ssot-v0.9.md",
+  "starter/docs/governance/agents-routing/engineering-runtime-v0.9.md",
+  "starter/docs/governance/agents-routing/doc-only-v0.9.md",
+  "starter/docs/governance/doc-agent-rules.md",
+  "starter/docs/governance/doc-types.md",
+  "starter/docs/governance/templates/adr.md",
+  "starter/docs/governance/templates/spec.md",
+  "starter/docs/governance/templates/plan.md",
+  "starter/docs/governance/templates/canon-entry.md",
+  "starter/docs/governance/templates/reference.md",
+  "starter/docs/governance/templates/policy.md",
+  "starter/docs/governance/templates/archive.md"
+];
+var PROJECT_REQUIRED_FILES = [
+  "AGENTS.md",
+  "CLAUDE.md",
+  "docs/governance/boundary.md",
+  "docs/governance/ssot-v0.9.md",
+  "docs/governance/doc-agent-rules.md",
+  "docs/governance/doc-types.md",
+  "docs/reference/execution/current-work.md"
+];
+var PROJECT_AGENTS_ROUTING_FILES = [
+  "docs/governance/agents-routing/engineering-runtime-v0.9.md",
+  "docs/governance/agents-routing/doc-only-v0.9.md"
+];
+var FORBIDDEN_LEGACY_PATHS = [
+  "governance",
+  "docs-governance",
+  "routing",
+  "starter/governance",
+  "starter/docs-governance"
+];
+var FORBIDDEN_PROJECT_PATHS = [
+  "docs/policy/shared-rules/ssot.md",
+  "docs/policy/shared-rules/task-routing.md"
+];
+var FORBIDDEN_PROJECT_ROOTS = ["integrations"];
+var FORBIDDEN_CENTRAL_ROOTS = ["shared-rules"];
+var ROUTER_BLOCK_BEGIN = "<!-- PGS-ROUTER:BEGIN v0.9 -->";
+var ROUTER_BLOCK_END = "<!-- PGS-ROUTER:END -->";
+var EXTERNAL_ROUTER_MARKERS = [
+  "## gstack",
+  "## GStack",
+  "## Skill routing",
+  "## Superpowers"
+];
+var CENTRAL_REQUIRED_NEEDLES = [
+  {
+    file: "AGENTS.md",
+    needle: ROUTER_BLOCK_BEGIN,
+    message: "AGENTS.md must include the PGS router block."
+  },
+  {
+    file: "AGENTS.md",
+    needle: "docs/governance/boundary.md",
+    message: "AGENTS.md must mention docs/governance/boundary.md."
+  },
+  {
+    file: "AGENTS.md",
+    needle: "docs/governance/ssot-v0.9.md",
+    message: "AGENTS.md must mention docs/governance/ssot-v0.9.md."
+  },
+  {
+    file: "AGENTS.md",
+    needle: "starter/docs/governance/doc-agent-rules.md",
+    message: "AGENTS.md must mention starter/docs/governance/doc-agent-rules.md."
+  },
+  {
+    file: "AGENTS.md",
+    needle: "starter/docs/governance/doc-types.md",
+    message: "AGENTS.md must mention starter/docs/governance/doc-types.md."
+  },
+  {
+    file: "AGENTS.md",
+    needle: "docs/governance/agents-routing/engineering-runtime-v0.9.md",
+    message: "AGENTS.md must mention docs/governance/agents-routing/engineering-runtime-v0.9.md."
+  },
+  {
+    file: "AGENTS.md",
+    needle: "docs/governance/agents-routing/doc-only-v0.9.md",
+    message: "AGENTS.md must mention docs/governance/agents-routing/doc-only-v0.9.md."
+  },
+  {
+    file: "AGENTS.md",
+    needle: "integrations/superpowers.md",
+    message: "AGENTS.md must mention integrations/superpowers.md."
+  },
+  {
+    file: "AGENTS.md",
+    needle: "integrations/directed-development.md",
+    message: "AGENTS.md must mention integrations/directed-development.md."
+  },
+  {
+    file: "AGENTS.md",
+    needle: "profiles/engineering-runtime/",
+    message: "AGENTS.md must mention profiles/engineering-runtime/."
+  },
+  {
+    file: "AGENTS.md",
+    needle: "profiles/doc-only/",
+    message: "AGENTS.md must mention profiles/doc-only/."
+  },
+  {
+    file: "README.md",
+    needle: "docs/governance/agents-routing/",
+    message: "README.md must point readers to agents-routing under docs/governance/."
+  },
+  {
+    file: "docs/governance/agents-routing/engineering-runtime-v0.9.md",
+    needle: "Use matching Superpowers workflow if applicable",
+    message: "Engineering routing must delegate Superpowers only inside the selected lane."
+  },
+  {
+    file: "docs/governance/agents-routing/engineering-runtime-v0.9.md",
+    needle: "current-work.md",
+    message: "Engineering routing must separate routing from current-work.md."
+  },
+  {
+    file: "docs/governance/agents-routing/doc-only-v0.9.md",
+    needle: "does not use Superpowers TDD or Directed Development by default",
+    message: "Doc-only routing must exclude engineering Superpowers/DD by default."
+  },
+  {
+    file: "integrations/superpowers.md",
+    needle: "Agents routing classifies first",
+    message: "Superpowers integration must state that agents routing classifies first."
+  },
+  {
+    file: "integrations/superpowers.md",
+    needle: "Superpowers executes inside the selected lane",
+    message: "Superpowers integration must state that Superpowers executes inside the lane."
+  },
+  {
+    file: "integrations/superpowers.md",
+    needle: "does not vendor",
+    message: "Superpowers integration must preserve the external-plugin boundary."
+  },
+  {
+    file: "integrations/directed-development.md",
+    needle: "optional workflow",
+    message: "Directed Development integration must stay optional."
+  },
+  {
+    file: "profiles/engineering-runtime/manifest.yml",
+    needle: "docs/governance/agents-routing/engineering-runtime-v0.9.md",
+    message: "Engineering profile manifest must point to engineering routing."
+  },
+  {
+    file: "profiles/engineering-runtime/manifest.yml",
+    needle: "integrations/superpowers.md",
+    message: "Engineering profile manifest must include the Superpowers integration."
+  },
+  {
+    file: "profiles/doc-only/manifest.yml",
+    needle: "docs/governance/agents-routing/doc-only-v0.9.md",
+    message: "Doc-only profile manifest must point to doc-only routing."
+  },
+  {
+    file: "profiles/doc-only/manifest.yml",
+    needle: "superpowers: false",
+    message: "Doc-only profile manifest must keep Superpowers disabled by default."
+  },
+  {
+    file: "starter/AGENTS.template.md",
+    needle: ROUTER_BLOCK_BEGIN,
+    message: "Starter AGENTS template must include the PGS router block."
+  },
+  {
+    file: "starter/AGENTS.template.md",
+    needle: "adopted profile",
+    message: "Starter AGENTS template must make projects name their adopted profile."
+  },
+  {
+    file: "starter/AGENTS.template.md",
+    needle: "chosen agents-routing file",
+    message: "Starter AGENTS template must make projects name their chosen agents-routing file."
+  },
+  {
+    file: "starter/AGENTS.template.md",
+    needle: "docs/governance/boundary.md",
+    message: "Starter AGENTS template must point agents to docs/governance/boundary.md."
+  },
+  {
+    file: "starter/AGENTS.template.md",
+    needle: "docs/governance/ssot-v0.9.md",
+    message: "Starter AGENTS template must point agents to docs/governance/ssot-v0.9.md."
+  },
+  {
+    file: "starter/AGENTS.template.md",
+    needle: "docs/governance/agents-routing/",
+    message: "Starter AGENTS template must point agents to docs/governance/agents-routing/."
+  },
+  {
+    file: "starter/AGENTS.template.md",
+    needle: "docs/governance/doc-agent-rules.md",
+    message: "Starter AGENTS template must point agents to docs/governance/doc-agent-rules.md."
+  },
+  {
+    file: "starter/AGENTS.template.md",
+    needle: "docs/governance/doc-types.md",
+    message: "Starter AGENTS template must point agents to docs/governance/doc-types.md."
+  },
+  {
+    file: "starter/AGENTS.template.md",
+    needle: "docs/policy/",
+    message: "Starter AGENTS template must keep project AI development policy in docs/policy/."
+  },
+  {
+    file: "starter/lefthook.template.yml",
+    needle: "pnpm doc-gov router-check",
+    message: "Starter lefthook template must run doc-gov router-check."
+  },
+  {
+    file: "starter/lefthook.template.yml",
+    needle: "pnpm doc-gov links",
+    message: "Starter lefthook template must run doc-gov links."
+  },
+  {
+    file: "starter/.github/workflows/docs-check.yml",
+    needle: "pnpm doc-gov router-check",
+    message: "Starter docs-check workflow must run doc-gov router-check."
+  },
+  {
+    file: "starter/.github/workflows/docs-check.yml",
+    needle: "pnpm doc-gov links",
+    message: "Starter docs-check workflow must run doc-gov links."
+  }
+];
+var PROJECT_REQUIRED_NEEDLES = [
+  {
+    file: "AGENTS.md",
+    needle: ROUTER_BLOCK_BEGIN,
+    message: "AGENTS.md must include the PGS router block."
+  },
+  {
+    file: "AGENTS.md",
+    needle: "README.md",
+    message: "AGENTS.md must state how README.md is used."
+  },
+  {
+    file: "AGENTS.md",
+    needle: "docs/policy/",
+    message: "AGENTS.md must point agents to docs/policy/."
+  },
+  {
+    file: "AGENTS.md",
+    needle: "docs/governance/boundary.md",
+    message: "AGENTS.md must mention docs/governance/boundary.md."
+  },
+  {
+    file: "AGENTS.md",
+    needle: "docs/governance/ssot-v0.9.md",
+    message: "AGENTS.md must mention docs/governance/ssot-v0.9.md."
+  },
+  {
+    file: "AGENTS.md",
+    needle: "docs/governance/doc-agent-rules.md",
+    message: "AGENTS.md must mention docs/governance/doc-agent-rules.md."
+  },
+  {
+    file: "AGENTS.md",
+    needle: "docs/governance/doc-types.md",
+    message: "AGENTS.md must mention docs/governance/doc-types.md."
+  },
+  {
+    file: "AGENTS.md",
+    needle: "docs/governance/agents-routing/",
+    message: "AGENTS.md must point agents to docs/governance/agents-routing/."
+  },
+  {
+    file: "AGENTS.md",
+    needle: "docs/reference/execution/current-work.md",
+    message: "AGENTS.md must mention docs/reference/execution/current-work.md."
+  },
+  {
+    file: "docs/governance/boundary.md",
+    needle: "Product artifacts outside governed docs",
+    message: "Governance boundary must preserve the product artifact boundary."
+  },
+  {
+    file: "docs/governance/ssot-v0.9.md",
+    needle: "automatically govern every Markdown file",
+    message: "SSOT rule must state that not every Markdown file is governed."
+  },
+  {
+    file: "docs/governance/doc-agent-rules.md",
+    needle: "Doc-gov governs `docs/**` by default",
+    message: "Doc agent rules must keep the docs-only governed scope."
+  },
+  {
+    file: "docs/governance/doc-types.md",
+    needle: "Markdown outside `docs/**` is not a governed doc by default",
+    message: "Doc types must keep Markdown outside docs/** out of governance by default."
+  }
+];
+function checkRouterIntegrity(rootDir = process.cwd()) {
+  const issues = [];
+  const isCentral = isCentralRepository(rootDir);
+  const requiredFiles = isCentral ? CENTRAL_REQUIRED_FILES : PROJECT_REQUIRED_FILES;
+  const requiredNeedles = isCentral ? CENTRAL_REQUIRED_NEEDLES : PROJECT_REQUIRED_NEEDLES;
+  for (const file of requiredFiles) {
+    if (!existsSync6(join8(rootDir, file))) {
+      issues.push({
+        file,
+        code: "missing-router-file",
+        message: `Required router/integration file is missing: ${file}`
+      });
+    }
+  }
+  if (!isCentral) {
+    issues.push(...validateProjectAgentsRouting(rootDir));
+  }
+  for (const file of FORBIDDEN_LEGACY_PATHS) {
+    if (existsSync6(join8(rootDir, file))) {
+      issues.push({
+        file,
+        code: "legacy-governance-path",
+        message: `Legacy governance path must not exist: ${file}`
+      });
+    }
+  }
+  if (!isCentral) {
+    for (const file of FORBIDDEN_PROJECT_PATHS) {
+      if (existsSync6(join8(rootDir, file))) {
+        issues.push({
+          file,
+          code: "legacy-project-policy-path",
+          message: `Legacy project policy path must not exist: ${file}`
+        });
+      }
+    }
+    for (const file of FORBIDDEN_PROJECT_ROOTS) {
+      if (existsSync6(join8(rootDir, file))) {
+        issues.push({
+          file,
+          code: "project-root-integration-path",
+          message: `Project-level root integrations path must not exist: ${file}. Keep upstream integration docs in project-governance-system; use AGENTS.md or docs/reference/integrations/ only when project-specific guidance is needed.`
+        });
+      }
+    }
+  } else {
+    for (const file of FORBIDDEN_CENTRAL_ROOTS) {
+      if (existsSync6(join8(rootDir, file))) {
+        issues.push({
+          file,
+          code: "central-external-shared-rule-copy",
+          message: `Central repository must not keep external shared-rule copies at root path: ${file}. Link external shared rules from target projects under docs/policy/shared-rules/ instead.`
+        });
+      }
+    }
+  }
+  for (const file of findGovernedReadmes(rootDir)) {
+    issues.push({
+      file,
+      code: "non-root-readme",
+      message: `Governed README.md must not exist outside the repository root: ${file}`
+    });
+  }
+  for (const requirement of requiredNeedles) {
+    const path = join8(rootDir, requirement.file);
+    if (!existsSync6(path)) continue;
+    const content = readFileSync6(path, "utf8");
+    if (!content.includes(requirement.needle)) {
+      issues.push({
+        file: requirement.file,
+        code: "missing-router-reference",
+        message: requirement.message
+      });
+    }
+  }
+  const routerBlockFiles = isCentral ? ["AGENTS.md", "starter/AGENTS.template.md"] : ["AGENTS.md"];
+  for (const file of routerBlockFiles) {
+    issues.push(...validateRouterBlock(rootDir, file));
+  }
+  issues.push(...validateBacktickedLocalPaths(rootDir, "AGENTS.md"));
+  issues.push(...validateBacktickedLocalPaths(rootDir, "CLAUDE.md"));
+  issues.push(...validateBacktickedLocalPaths(rootDir, "README.md"));
+  if (isCentral) {
+    issues.push(...validateBacktickedLocalPaths(rootDir, "starter/AGENTS.template.md", "starter"));
+  }
+  const portableRouterFiles = isCentral ? [
+    "AGENTS.md",
+    "README.md",
+    "starter/AGENTS.template.md",
+    "starter/CLAUDE.template.md",
+    "docs/governance/agents-routing/engineering-runtime-v0.9.md",
+    "docs/governance/agents-routing/doc-only-v0.9.md"
+  ] : [
+    "AGENTS.md",
+    "CLAUDE.md",
+    "README.md",
+    "docs/governance/agents-routing/engineering-runtime-v0.9.md",
+    "docs/governance/agents-routing/doc-only-v0.9.md"
+  ];
+  for (const file of portableRouterFiles) {
+    issues.push(...validatePortableRouterText(rootDir, file));
+  }
+  return {
+    ok: issues.length === 0,
+    issues
+  };
+}
+function isCentralRepository(rootDir) {
+  const packageJsonPath = join8(rootDir, "package.json");
+  if (!existsSync6(packageJsonPath)) return false;
+  const packageJson = readFileSync6(packageJsonPath, "utf8");
+  return packageJson.includes('"name": "project-governance-system"') && existsSync6(join8(rootDir, "profiles")) && existsSync6(join8(rootDir, "starter")) && existsSync6(join8(rootDir, "integrations"));
+}
+function validateProjectAgentsRouting(rootDir) {
+  const issues = [];
+  const existingRoutes = PROJECT_AGENTS_ROUTING_FILES.filter(
+    (file) => existsSync6(join8(rootDir, file))
+  );
+  if (existingRoutes.length === 0) {
+    issues.push({
+      file: "docs/governance/agents-routing",
+      code: "missing-project-agents-routing",
+      message: "Project must install one agents-routing file under docs/governance/agents-routing/."
+    });
+    return issues;
+  }
+  const agentsPath = join8(rootDir, "AGENTS.md");
+  if (!existsSync6(agentsPath)) return issues;
+  const agents = readFileSync6(agentsPath, "utf8");
+  if (!existingRoutes.some((file) => agents.includes(file))) {
+    issues.push({
+      file: "AGENTS.md",
+      code: "missing-selected-agents-routing",
+      message: "AGENTS.md must name the selected agents-routing file under docs/governance/agents-routing/."
+    });
+  }
+  return issues;
+}
+function validateRouterBlock(rootDir, file) {
+  const path = join8(rootDir, file);
+  if (!existsSync6(path)) return [];
+  const content = readFileSync6(path, "utf8");
+  const begin = content.indexOf(ROUTER_BLOCK_BEGIN);
+  const end = content.indexOf(ROUTER_BLOCK_END);
+  const issues = [];
+  if (begin === -1 || end === -1 || end < begin) {
+    issues.push({
+      file,
+      code: "invalid-router-block",
+      message: `${file} must contain a valid ${ROUTER_BLOCK_BEGIN} block before external workflow routing.`
+    });
+    return issues;
+  }
+  for (const marker of EXTERNAL_ROUTER_MARKERS) {
+    const markerIndex = content.indexOf(marker);
+    if (markerIndex !== -1 && markerIndex < end) {
+      issues.push({
+        file,
+        code: "external-routing-before-pgs",
+        message: `${file} must place ${marker} after the PGS router block.`
+      });
+    }
+  }
+  return issues;
+}
+function validateBacktickedLocalPaths(rootDir, file, pathRoot = "") {
+  const path = join8(rootDir, file);
+  if (!existsSync6(path)) return [];
+  const content = readFileSync6(path, "utf8");
+  const issues = [];
+  const seen = /* @__PURE__ */ new Set();
+  const matches = content.matchAll(/`([^`]+)`/g);
+  for (const match of matches) {
+    const value = match[1]?.trim();
+    if (!value || seen.has(value)) continue;
+    seen.add(value);
+    if (!isLocalPathReference(value)) continue;
+    const normalized = value.endsWith("/") ? value.slice(0, -1) : value;
+    if (existsSync6(join8(rootDir, pathRoot, normalized)) || existsSync6(join8(rootDir, normalized))) {
+      continue;
+    }
+    issues.push({
+      file,
+      code: "missing-backticked-path",
+      message: `${file} references a local path that does not exist: ${value}`
+    });
+  }
+  return issues;
+}
+function isLocalPathReference(value) {
+  if (/\s/.test(value)) return false;
+  if (/^[a-z]+:\/\//i.test(value)) return false;
+  if (value.includes("*")) return false;
+  if (value.startsWith("<") || value.endsWith(">")) return false;
+  return value === "README.md" || value.endsWith(".md") || value.endsWith("/") || value.startsWith("docs/") || value.startsWith("starter/") || value.startsWith("profiles/") || value.startsWith("integrations/");
+}
+function validatePortableRouterText(rootDir, file) {
+  const path = join8(rootDir, file);
+  if (!existsSync6(path)) return [];
+  const content = readFileSync6(path, "utf8");
+  if (!hasNonPortablePath(content)) return [];
+  return [
+    {
+      file,
+      code: "non-portable-router-path",
+      message: `${file} must not contain machine-local or parent-escape paths. Use repository-relative paths or profile/starter references instead.`
+    }
+  ];
+}
+function hasNonPortablePath(content) {
+  return /(^|[\s`'"])(\/Users\/|~\/|\$HOME(?:\/|\b)|%USERPROFILE%|[A-Za-z]:\\|\.\.\/)/.test(
+    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);
+    }
+  }
+}
+
+// src/commands/doctor.ts
+function runDoctor(_args) {
+  const root = process.cwd();
+  const issues = collectDoctorIssues(root);
+  const errors = issues.filter((issue) => issue.severity === "error");
+  const warnings = issues.filter((issue) => issue.severity === "warning");
+  for (const issue of errors) {
+    console.error(`error ${issue.code}: ${issue.message}`);
+  }
+  for (const issue of warnings) {
+    console.log(`warning ${issue.code}: ${issue.message}`);
+  }
+  if (errors.length > 0) {
+    console.error(
+      `doc-gov doctor failed with ${errors.length} error(s) and ${warnings.length} warning(s).`
+    );
+    return 1;
+  }
+  console.log(`doc-gov doctor passed with ${warnings.length} warning(s).`);
+  return 0;
+}
+function collectDoctorIssues(rootDir = process.cwd()) {
+  const issues = [];
+  const router = checkRouterIntegrity(rootDir);
+  if (!router.ok) {
+    for (const issue of router.issues) {
+      issues.push({
+        severity: "error",
+        code: `router:${issue.code}`,
+        message: `${issue.file}: ${issue.message}`
+      });
+    }
+  }
+  const docs = checkDocs(rootDir);
+  if (!docs.ok) {
+    for (const issue of docs.issues) {
+      issues.push({
+        severity: "error",
+        code: `docs:${issue.code}`,
+        message: `${issue.file}: ${issue.message}`
+      });
+    }
+  }
+  if (!manifestInSync(rootDir)) {
+    issues.push({
+      severity: "error",
+      code: "manifest:out-of-sync",
+      message: "docs/governance/MANIFEST.yml is stale. Run pnpm doc-gov scan."
+    });
+  }
+  const links = checkCurrentMarkdownLinks(rootDir);
+  if (!links.ok) {
+    for (const issue of links.issues) {
+      issues.push({
+        severity: "error",
+        code: "links:broken-local-link",
+        message: issue.message
+      });
+    }
+  }
+  issues.push(...checkLefthook(rootDir));
+  issues.push(...checkDocsCheckWorkflow(rootDir));
+  return issues;
+}
+function checkLefthook(rootDir) {
+  const path = join9(rootDir, "lefthook.yml");
+  if (!existsSync7(path)) {
+    return [
+      {
+        severity: "warning",
+        code: "guardrail:missing-lefthook",
+        message: "lefthook.yml is missing; local commits do not have the standard doc-gov gate."
+      }
+    ];
+  }
+  const content = readFileSync7(path, "utf8");
+  const issues = [];
+  for (const command2 of [
+    "pnpm doc-gov router-check",
+    "pnpm doc-gov check",
+    "pnpm doc-gov scan --check",
+    "pnpm doc-gov links",
+    "pnpm doc-gov audit",
+    "pnpm doc-gov verify-commit-msg"
+  ]) {
+    if (!content.includes(command2)) {
+      issues.push({
+        severity: "error",
+        code: "guardrail:incomplete-lefthook",
+        message: `lefthook.yml must include: ${command2}`
+      });
+    }
+  }
+  const preCommit = join9(rootDir, ".git/hooks/pre-commit");
+  const commitMsg = join9(rootDir, ".git/hooks/commit-msg");
+  if (!hookCallsLefthook(preCommit)) {
+    issues.push({
+      severity: "error",
+      code: "guardrail:lefthook-not-installed",
+      message: "lefthook.yml exists, but .git/hooks/pre-commit is not installed for lefthook."
+    });
+  }
+  if (!hookCallsLefthook(commitMsg)) {
+    issues.push({
+      severity: "error",
+      code: "guardrail:lefthook-not-installed",
+      message: "lefthook.yml exists, but .git/hooks/commit-msg is not installed for lefthook."
+    });
+  }
+  return issues;
+}
+function checkDocsCheckWorkflow(rootDir) {
+  const path = join9(rootDir, ".github/workflows/docs-check.yml");
+  if (!existsSync7(path)) {
+    return [
+      {
+        severity: "warning",
+        code: "guardrail:missing-docs-check-workflow",
+        message: ".github/workflows/docs-check.yml is missing; CI does not have the standard doc-gov gate."
+      }
+    ];
+  }
+  const content = readFileSync7(path, "utf8");
+  const issues = [];
+  for (const command2 of [
+    "pnpm doc-gov router-check",
+    "pnpm doc-gov check",
+    "pnpm doc-gov scan --check",
+    "pnpm doc-gov links",
+    "pnpm doc-gov audit"
+  ]) {
+    if (!content.includes(command2)) {
+      issues.push({
+        severity: "error",
+        code: "guardrail:incomplete-docs-check-workflow",
+        message: `.github/workflows/docs-check.yml must include: ${command2}`
+      });
+    }
+  }
+  return issues;
+}
+function hookCallsLefthook(path) {
+  return existsSync7(path) && readFileSync7(path, "utf8").includes("lefthook");
+}
+
+// src/commands/find.ts
+function runFind(args2) {
+  const query = args2.join(" ").trim().toLowerCase();
+  if (!query) {
+    console.error("Usage: pnpm doc-gov find <topic>");
+    return 1;
+  }
+  const result = checkDocs(process.cwd());
+  if (!result.ok) {
+    console.error("doc-gov check currently fails; fix docs before relying on find.");
+    return 1;
+  }
+  const matches = result.records.filter((record) => {
+    const haystack = [
+      record.id,
+      record.title,
+      record.type,
+      record.status,
+      record.domain,
+      record.tags.join(" "),
+      record.path
+    ].join(" ").toLowerCase();
+    return haystack.includes(query);
+  });
+  if (matches.length === 0) {
+    console.log(`No docs found for: ${query}`);
+    return 0;
+  }
+  for (const record of matches) {
+    console.log(`${record.id}	${record.type}	${record.status}	${record.path}	${record.title}`);
+  }
+  return 0;
+}
+
+// src/commands/init.ts
+import { existsSync as existsSync9, mkdirSync as mkdirSync4, writeFileSync as writeFileSync5 } from "node:fs";
+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 { join as join10 } from "node:path";
+var TEMPLATE_FILES = {
+  decision: "adr.md",
+  spec: "spec.md",
+  plan: "plan.md",
+  canon: "canon-entry.md",
+  reference: "reference.md",
+  policy: "policy.md",
+  archive: "archive.md"
+};
+var DEFAULT_TEMPLATES = {
+  "adr.md": [
+    "---",
+    "id: REPLACE-ME",
+    "title: Replace Me",
+    "type: decision",
+    "status: proposed",
+    "canonical: true",
+    "owner: human",
+    "created: YYYY-MM-DD",
+    "last_reviewed: YYYY-MM-DD",
+    "domain: meta",
+    "tags:",
+    "  - replace-me",
+    "pinned: false",
+    "related: []",
+    "---",
+    "",
+    "# REPLACE-ME: Replace Me",
+    "",
+    "## Context",
+    "",
+    "## Decision",
+    "",
+    "## Consequences",
+    ""
+  ].join("\n"),
+  "spec.md": [
+    "---",
+    "id: REPLACE-ME",
+    "title: Replace Me",
+    "type: spec",
+    "status: draft",
+    "canonical: false",
+    "owner: human",
+    "created: YYYY-MM-DD",
+    "last_reviewed: YYYY-MM-DD",
+    "domain: meta",
+    "tags:",
+    "  - replace-me",
+    "pinned: false",
+    "related: []",
+    "---",
+    "",
+    "# REPLACE-ME: Replace Me",
+    "",
+    "## Problem",
+    "",
+    "## Requirements",
+    "",
+    "## Acceptance",
+    ""
+  ].join("\n"),
+  "plan.md": [
+    "---",
+    "id: REPLACE-ME",
+    "title: Replace Me",
+    "type: plan",
+    "status: draft",
+    "canonical: false",
+    "owner: ai-assisted",
+    "created: YYYY-MM-DD",
+    "last_reviewed: YYYY-MM-DD",
+    "domain: meta",
+    "tags:",
+    "  - replace-me",
+    "pinned: false",
+    "related: []",
+    "---",
+    "",
+    "# REPLACE-ME: Replace Me",
+    "",
+    "## Goal",
+    "",
+    "## Scope",
+    "",
+    "## Steps",
+    "",
+    "- [ ] Step 1",
+    "",
+    "## Acceptance",
+    "",
+    "- [ ] Verification completed",
+    "",
+    "## Closeout",
+    "",
+    "When complete, move this plan to `docs/plans/completed/` and set `status: completed`.",
+    ""
+  ].join("\n"),
+  "canon-entry.md": [
+    "---",
+    "id: REPLACE-ME",
+    "title: Replace Me",
+    "type: canon",
+    "status: draft",
+    "canonical: false",
+    "owner: human",
+    "created: YYYY-MM-DD",
+    "last_reviewed: YYYY-MM-DD",
+    "domain: canon",
+    "tags:",
+    "  - replace-me",
+    "pinned: false",
+    "related: []",
+    "---",
+    "",
+    "# REPLACE-ME: Replace Me",
+    "",
+    "## Current Truth",
+    "",
+    "## Source / Provenance",
+    "",
+    "## Open Questions",
+    ""
+  ].join("\n"),
+  "reference.md": [
+    "---",
+    "id: REPLACE-ME",
+    "title: Replace Me",
+    "type: reference",
+    "status: draft",
+    "canonical: false",
+    "owner: human",
+    "created: YYYY-MM-DD",
+    "last_reviewed: YYYY-MM-DD",
+    "domain: reference",
+    "tags:",
+    "  - replace-me",
+    "pinned: false",
+    "related: []",
+    "---",
+    "",
+    "# REPLACE-ME: Replace Me",
+    "",
+    "## Purpose",
+    "",
+    "## Details",
+    "",
+    "## Related Commands / Files",
+    ""
+  ].join("\n"),
+  "policy.md": [
+    "---",
+    "id: REPLACE-ME",
+    "title: Replace Me",
+    "type: policy",
+    "status: draft",
+    "canonical: false",
+    "owner: human",
+    "created: YYYY-MM-DD",
+    "last_reviewed: YYYY-MM-DD",
+    "domain: policy",
+    "tags:",
+    "  - replace-me",
+    "pinned: false",
+    "related: []",
+    "---",
+    "",
+    "# REPLACE-ME: Replace Me",
+    "",
+    "## Rule",
+    "",
+    "## Rationale",
+    "",
+    "## Examples",
+    ""
+  ].join("\n"),
+  "archive.md": [
+    "---",
+    "id: REPLACE-ME",
+    "title: Replace Me",
+    "type: archive",
+    "status: archived",
+    "canonical: false",
+    "owner: human",
+    "created: YYYY-MM-DD",
+    "last_reviewed: YYYY-MM-DD",
+    "domain: archive",
+    "tags:",
+    "  - replace-me",
+    "pinned: false",
+    "related: []",
+    "archive_reason: Replace me",
+    "---",
+    "",
+    "# REPLACE-ME: Replace Me (archived)",
+    "",
+    "## Archived Reason",
+    "",
+    "## Historical Notes",
+    ""
+  ].join("\n")
+};
+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");
+  const fallback = DEFAULT_TEMPLATES[file];
+  if (fallback) return fallback;
+  throw new Error(`Template file is missing: docs/governance/templates/${file}`);
+}
+function ensureDefaultTemplates(rootDir) {
+  const templatesDir = join10(rootDir, "docs/governance/templates");
+  mkdirSync3(templatesDir, { recursive: true });
+  let created = 0;
+  for (const [file, content] of Object.entries(DEFAULT_TEMPLATES)) {
+    const path = join10(templatesDir, file);
+    if (existsSync8(path)) continue;
+    writeFileSync4(path, content);
+    created++;
+  }
+  return created;
+}
+function renderTemplate(template, values) {
+  const closing = template.indexOf("\n---", 4);
+  if (closing === -1) throw new Error("Template is missing closing frontmatter marker.");
+  const body = template.slice(closing + 4).replace(/^\n/, "");
+  const tagsBlock = values.tags.length > 0 ? values.tags.map((t) => `  - ${t}`).join("\n") : "  - replace-me";
+  const frontmatter = [
+    "---",
+    `id: ${values.id}`,
+    `title: ${values.title}`,
+    `type: ${values.type}`,
+    `status: ${values.status}`,
+    `canonical: ${values.canonical}`,
+    `owner: ${values.owner}`,
+    `created: ${values.created}`,
+    `last_reviewed: ${values.lastReviewed}`,
+    `domain: ${values.domain}`,
+    "tags:",
+    tagsBlock,
+    `pinned: ${values.pinned}`,
+    "related: []",
+    "---",
+    ""
+  ].join("\n");
+  const replacedBody = body.replace(/^# REPLACE-ME: Replace Me/m, `# ${values.id}: ${values.title}`).replace(/^# Replace Me$/m, `# ${values.title}`).replace(/^# Replace Me \(archived\)$/m, `# ${values.title} (archived)`);
+  return frontmatter + replacedBody;
+}
+
+// src/commands/init.ts
+function runInit(args2) {
+  const force = args2.includes("--force");
+  const root = process.cwd();
+  const dirs = [
+    "docs",
+    "docs/governance",
+    "docs/governance/agents-routing",
+    "docs/governance/templates",
+    "docs/policy",
+    "docs/decisions",
+    "docs/specs/active",
+    "docs/specs/completed",
+    "docs/plans/active",
+    "docs/plans/completed",
+    "docs/canon",
+    "docs/reference",
+    "docs/reference/execution",
+    "docs/archive"
+  ];
+  let created = 0;
+  for (const dir of dirs) {
+    const abs = join11(root, dir);
+    if (!existsSync9(abs)) {
+      mkdirSync4(abs, { recursive: true });
+      created++;
+    } else if (!force) {
+    }
+  }
+  for (const dir of ["docs/specs/completed", "docs/plans/completed", "docs/archive"]) {
+    const keep = join11(root, dir, ".gitkeep");
+    if (!existsSync9(keep)) writeFileSync5(keep, "");
+  }
+  const templatesCreated = ensureDefaultTemplates(root);
+  console.log(
+    `doc-gov init: ${created} directories created, ${templatesCreated} templates created (existing files left untouched).`
+  );
+  console.log(`
+Next steps for a brand-new project:`);
+  console.log(`  1. Copy starter/AGENTS.template.md to AGENTS.md and fill the project name.`);
+  console.log(`     Copy starter/CLAUDE.template.md to CLAUDE.md as the Claude adapter.`);
+  console.log(`  2. Copy starter/docs/governance/boundary.md, ssot-v0.9.md,`);
+  console.log(`     doc-agent-rules.md, doc-types.md, and one agents-routing file.`);
+  console.log(`  3. Copy starter/docs/policy/best-practice-for-this-project.md and replace`);
+  console.log(`     placeholder policy with this project's real AI/development rules.`);
+  console.log(`  4. Copy starter/docs/reference/documentation-map.md and`);
+  console.log(`     starter/docs/reference/execution/current-work.md.`);
+  console.log(`     Current work is required, but it can stay very lightweight.`);
+  console.log(`  5. Pick a profile: profiles/engineering-runtime or profiles/doc-only.`);
+  console.log(`  6. Install the CLI: pnpm add -D @pieai/doc-gov`);
+  console.log(`     or run this built CLI directly during local development.`);
+  console.log(`  7. Optional hard guardrails: copy starter/lefthook.template.yml to`);
+  console.log(`     lefthook.yml, and starter/.github/workflows/docs-check.yml to`);
+  console.log(`     .github/workflows/docs-check.yml when the project is ready for gates.`);
+  console.log(`  8. Add the target project's doc-gov script or package bin wiring.`);
+  console.log(`  9. Validate the router: doc-gov router-check`);
+  console.log(`     Full health check: doc-gov doctor`);
+  console.log(`  10. Write your first ADR: doc-gov new decision adopt-doc-gov`);
+  return 0;
+}
+
+// src/commands/links.ts
+function runLinks() {
+  const result = checkCurrentMarkdownLinks(process.cwd());
+  if (!result.ok) {
+    for (const issue of result.issues) {
+      console.error(issue.message);
+    }
+    return 1;
+  }
+  console.log(
+    `doc-gov links passed (${result.checkedFiles} current files, ${result.checkedLinks} local links).`
+  );
+  return 0;
+}
+
+// src/commands/migrate.ts
+import { existsSync as existsSync10, readFileSync as readFileSync9 } from "node:fs";
+import { join as join12 } from "node:path";
+var PROFILE_ROUTES = {
+  "engineering-runtime": "docs/governance/agents-routing/engineering-runtime-v0.9.md",
+  "doc-only": "docs/governance/agents-routing/doc-only-v0.9.md"
+};
+function runMigrate(args2) {
+  const checkOnly = args2.includes("--check");
+  const apply = args2.includes("--apply");
+  const profile = parseProfile(args2);
+  if (!profile) {
+    console.error("Usage: doc-gov migrate --profile <engineering-runtime|doc-only> --check");
+    return 1;
+  }
+  if (apply) {
+    console.error("doc-gov migrate --apply is not implemented yet. Run --check first.");
+    return 1;
+  }
+  if (!checkOnly) {
+    console.error("doc-gov migrate currently supports --check only.");
+    return 1;
+  }
+  const issues = checkMigrationReadiness(process.cwd(), profile);
+  if (issues.length > 0) {
+    for (const issue of issues) console.error(issue);
+    console.error(`doc-gov migrate --check failed for profile: ${profile}`);
+    return 1;
+  }
+  console.log(`doc-gov migrate --check passed for profile: ${profile}`);
+  return 0;
+}
+function checkMigrationReadiness(rootDir, profile) {
+  const issues = [];
+  const router = checkRouterIntegrity(rootDir);
+  for (const issue of router.issues) {
+    issues.push(`${issue.file}: ${issue.code}: ${issue.message}`);
+  }
+  const route = PROFILE_ROUTES[profile];
+  if (!existsSync10(join12(rootDir, route))) {
+    issues.push(`missing selected profile route: ${route}`);
+  }
+  const agentsPath = join12(rootDir, "AGENTS.md");
+  if (existsSync10(agentsPath) && !readFileSync9(agentsPath, "utf8").includes(route)) {
+    issues.push(`AGENTS.md must name selected profile route: ${route}`);
+  }
+  return issues;
+}
+function parseProfile(args2) {
+  const index = args2.indexOf("--profile");
+  const value = index >= 0 ? args2[index + 1] : void 0;
+  if (value === "engineering-runtime" || value === "doc-only") return value;
+  return void 0;
+}
+
+// src/commands/list.ts
+function runList(args2) {
+  const type = readFlag(args2, "--type");
+  const status = readFlag(args2, "--status");
+  const pinnedOnly = args2.includes("--pinned");
+  const result = checkDocs(process.cwd());
+  if (!result.ok) {
+    console.error("doc-gov check currently fails; run `pnpm doc-gov check` to see issues.");
+    return 1;
+  }
+  let records = result.records;
+  if (type) records = records.filter((r) => r.type === type);
+  if (status) records = records.filter((r) => r.status === status);
+  if (pinnedOnly) records = records.filter((r) => r.pinned);
+  if (records.length === 0) {
+    console.log("No matching docs.");
+    return 0;
+  }
+  console.log("ID	TYPE	STATUS	CANONICAL	PINNED	PATH	TITLE");
+  for (const r of records) {
+    console.log(
+      `${r.id}	${r.type}	${r.status}	${r.canonical}	${r.pinned}	${r.path}	${r.title}`
+    );
+  }
+  console.log(`
+${records.length} doc(s).`);
+  return 0;
+}
+function readFlag(args2, name) {
+  const idx = args2.indexOf(name);
+  if (idx === -1) return void 0;
+  return args2[idx + 1];
+}
+
+// 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";
+function runNew(args2) {
+  const positional = args2.filter((a) => !a.startsWith("--"));
+  const owner = readFlag2(args2, "--owner") ?? "human";
+  const force = args2.includes("--force");
+  const titleOverride = readFlag2(args2, "--title");
+  const domainOverride = readFlag2(args2, "--domain") ?? "meta";
+  if (positional.length < 2) {
+    console.error(
+      "Usage: pnpm doc-gov new <type> <slug> [--owner <h|ai-assisted|team>] [--title <text>] [--domain <slug>] [--force]"
+    );
+    return 1;
+  }
+  const [type, slug] = positional;
+  if (!docTypes.includes(type)) {
+    console.error(`Invalid type: ${type}. Allowed: ${docTypes.join(", ")}`);
+    return 1;
+  }
+  const root = process.cwd();
+  let plan;
+  try {
+    plan = planPath(root, type, slug);
+  } catch (err) {
+    console.error(err.message);
+    return 1;
+  }
+  const absPath = join13(root, plan.filePath);
+  if (existsSync11(absPath) && !force) {
+    console.error(`File already exists: ${plan.filePath}. Use --force to overwrite.`);
+    return 1;
+  }
+  const template = loadTemplate(root, type);
+  const status = type === "decision" ? "proposed" : "draft";
+  const canonical = type === "decision";
+  const today = todayIso();
+  const title = titleOverride ?? slugToTitle(plan.slug);
+  const rendered = renderTemplate(template, {
+    id: plan.id,
+    title,
+    type,
+    status,
+    canonical,
+    owner,
+    created: today,
+    lastReviewed: today,
+    domain: domainOverride,
+    tags: [plan.slug.split("-")[0] ?? "replace-me"],
+    pinned: false
+  });
+  mkdirSync5(dirname4(absPath), { recursive: true });
+  writeFileSync6(absPath, rendered);
+  console.log(`Created ${plan.filePath} with id ${plan.id}.`);
+  try {
+    writeManifest(root);
+    console.log("MANIFEST.yml regenerated.");
+  } catch (err) {
+    console.error(
+      "Created file but MANIFEST regeneration failed (probably check errors). Fix the new file then run `pnpm doc-gov scan`."
+    );
+    console.error(err.message);
+    return 0;
+  }
+  console.log(`
+Next steps:`);
+  console.log(`  1. Edit ${plan.filePath} (replace placeholder content).`);
+  console.log(`  2. Run: pnpm doc-gov check`);
+  if (status === "draft") {
+    console.log(`  3. When ready: pnpm doc-gov approve ${plan.id}`);
+  }
+  return 0;
+}
+function readFlag2(args2, name) {
+  const idx = args2.indexOf(name);
+  if (idx === -1) return void 0;
+  return args2[idx + 1];
+}
+function slugToTitle(slug) {
+  return slug.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+
+// src/commands/router-check.ts
+function runRouterCheck() {
+  const result = checkRouterIntegrity(process.cwd());
+  if (!result.ok) {
+    for (const issue of result.issues) {
+      console.error(`${issue.file}: ${issue.code}: ${issue.message}`);
+    }
+    return 1;
+  }
+  console.log("doc-gov router-check passed.");
+  return 0;
+}
+
+// src/commands/scan.ts
+function runScan(args2) {
+  const checkOnly = args2.includes("--check");
+  if (checkOnly) {
+    if (!manifestInSync(process.cwd())) {
+      console.error("docs/governance/MANIFEST.yml is out of sync. Run: pnpm doc-gov scan");
+      return 1;
+    }
+    console.log("doc-gov scan --check passed.");
+    return 0;
+  }
+  writeManifest(process.cwd());
+  console.log("docs/governance/MANIFEST.yml regenerated.");
+  return 0;
+}
+
+// src/commands/supersede.ts
+import { readFileSync as readFileSync10, writeFileSync as writeFileSync7 } from "node:fs";
+import { join as join14 } from "node:path";
+function runSupersede(args2) {
+  const [oldId, newId] = args2;
+  if (!oldId || !newId) {
+    console.error("Usage: pnpm doc-gov supersede <old-id> <new-id>");
+    return 1;
+  }
+  const root = process.cwd();
+  const result = checkDocs(root);
+  if (!result.ok) {
+    console.error("doc-gov check currently fails; fix issues before superseding.");
+    return 1;
+  }
+  const oldRec = result.records.find((r) => r.id === oldId);
+  const newRec = result.records.find((r) => r.id === newId);
+  if (!oldRec) {
+    console.error(`No doc with id: ${oldId}`);
+    return 1;
+  }
+  if (!newRec) {
+    console.error(`No doc with id: ${newId}`);
+    return 1;
+  }
+  if (oldRec.type !== newRec.type) {
+    console.error(
+      `Cannot supersede across types: ${oldId}=${oldRec.type} vs ${newId}=${newRec.type}.`
+    );
+    return 1;
+  }
+  if (oldRec.pinned) {
+    console.error(
+      `${oldId} is pinned. Use commit message "Pinned-Override: ${oldId}" via human commit.`
+    );
+    return 1;
+  }
+  const today = todayIso();
+  const oldPath = join14(root, oldRec.path);
+  let oldContent = readFileSync10(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");
+  newContent = appendToFrontmatterList(newContent, "supersedes", newId === oldId ? "" : oldId);
+  newContent = updateFrontmatterField(newContent, "last_reviewed", today);
+  writeFileSync7(newPath, newContent);
+  console.log(`Superseded ${oldId} (${oldRec.path}) by ${newId} (${newRec.path}).`);
+  console.log(`  ${oldId}: status=superseded, canonical=false, superseded_by=${newId}`);
+  console.log(`  ${newId}: supersedes += [${oldId}]`);
+  try {
+    writeManifest(root);
+    console.log("MANIFEST.yml regenerated.");
+  } catch (err) {
+    console.error(err.message);
+    return 1;
+  }
+  return 0;
+}
+function appendToFrontmatterList(content, key, value) {
+  if (!value) return content;
+  if (!content.startsWith("---\n")) throw new Error("File has no frontmatter.");
+  const closing = content.indexOf("\n---", 4);
+  if (closing === -1) throw new Error("Frontmatter is unterminated.");
+  const head = content.slice(4, closing);
+  const tail = content.slice(closing);
+  const lines = head.split("\n");
+  const keyRe = new RegExp(`^${key}:\\s*(.*)$`);
+  const idx = lines.findIndex((l) => keyRe.test(l));
+  if (idx === -1) {
+    lines.push(`${key}:`);
+    lines.push(`  - ${value}`);
+    return `---
+${lines.join("\n")}${tail}`;
+  }
+  const inlineMatch = lines[idx]?.match(keyRe);
+  const existing = inlineMatch?.[1]?.trim() ?? "";
+  if (existing === "[]" || existing === "") {
+    lines[idx] = `${key}:`;
+    lines.splice(idx + 1, 0, `  - ${value}`);
+    return `---
+${lines.join("\n")}${tail}`;
+  }
+  let insertAt = idx + 1;
+  while (insertAt < lines.length && /^\s+-\s+/.test(lines[insertAt] ?? "")) insertAt++;
+  lines.splice(insertAt, 0, `  - ${value}`);
+  return `---
+${lines.join("\n")}${tail}`;
+}
+
+// src/commands/verify-commit-msg.ts
+import { execSync as execSync2 } from "node:child_process";
+import { existsSync as existsSync12, readFileSync as readFileSync11 } from "node:fs";
+function runVerifyCommitMsg(args2) {
+  const msgFile = args2[0];
+  if (!msgFile || !existsSync12(msgFile)) {
+    return 0;
+  }
+  const message = readFileSync11(msgFile, "utf8");
+  if (/^Merge\b/m.test(message) || /^Revert\b/m.test(message)) return 0;
+  let stagedFiles = [];
+  try {
+    stagedFiles = execSync2("git diff --cached --name-only --diff-filter=ACM", {
+      encoding: "utf8"
+    }).split("\n").filter(isGovernedMarkdownPath);
+  } catch {
+    return 0;
+  }
+  const failures = [];
+  for (const file of stagedFiles) {
+    if (!existsSync12(file)) continue;
+    const fm = readFrontmatterFile(file);
+    if (!fm) continue;
+    const id = stringValue(fm.data.id);
+    if (!id) continue;
+    const pinned = booleanValue(fm.data.pinned) === true;
+    if (pinned) {
+      const re = new RegExp(`^Pinned-Override:\\s*${escapeRegex(id)}\\b`, "m");
+      if (!re.test(message)) {
+        failures.push(
+          `Pinned doc ${id} (${file}) modified without "Pinned-Override: ${id}" in commit message.`
+        );
+      }
+    }
+    const previous = readHeadFrontmatter(file);
+    if (!previous) continue;
+    const oldStatus = stringValue(previous.status);
+    const newStatus = stringValue(fm.data.status);
+    const requiresApproval = oldStatus === "draft" && newStatus === "active" || oldStatus === "proposed" && newStatus === "accepted";
+    if (requiresApproval) {
+      const re = new RegExp(`^Approves:\\s*${escapeRegex(id)}\\b`, "m");
+      if (!re.test(message)) {
+        failures.push(
+          `Doc ${id} (${file}) changed status ${oldStatus}\u2192${newStatus} without "Approves: ${id}" in commit message.`
+        );
+      }
+    }
+  }
+  if (failures.length > 0) {
+    console.error("doc-gov verify-commit-msg failed:");
+    for (const f of failures) console.error("  - " + f);
+    console.error("\nAdd the required line(s) to your commit message and try again.");
+    return 1;
+  }
+  return 0;
+}
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function isGovernedMarkdownPath(path) {
+  if (!/\.md$/.test(path)) return false;
+  if (path.startsWith("docs/governance/templates/")) return false;
+  if (path === "docs/governance/MANIFEST.yml") return false;
+  if (path.startsWith("docs/")) return true;
+  return false;
+}
+function readHeadFrontmatter(file) {
+  try {
+    const content = execSync2(`git show HEAD:${shellQuote(file)}`, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    if (!content.startsWith("---\n")) return null;
+    const closing = content.indexOf("\n---", 4);
+    if (closing === -1) return null;
+    return parseFrontmatter(content.slice(4, closing).trimEnd());
+  } catch {
+    return null;
+  }
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+// src/cli.ts
+var COMMANDS = [
+  "check",
+  "scan",
+  "audit",
+  "links",
+  "router-check",
+  "doctor",
+  "migrate",
+  "find",
+  "list",
+  "new",
+  "approve",
+  "supersede",
+  "archive",
+  "init",
+  "verify-commit-msg"
+];
+var [command, ...args] = process.argv.slice(2);
+var exitCode = 0;
+if (command === "check") exitCode = runCheck();
+else if (command === "scan") exitCode = runScan(args);
+else if (command === "audit") exitCode = runAudit();
+else if (command === "links") exitCode = runLinks();
+else if (command === "router-check") exitCode = runRouterCheck();
+else if (command === "doctor") exitCode = runDoctor(args);
+else if (command === "migrate") exitCode = runMigrate(args);
+else if (command === "find") exitCode = runFind(args);
+else if (command === "list") exitCode = runList(args);
+else if (command === "new") exitCode = runNew(args);
+else if (command === "approve") exitCode = runApprove(args);
+else if (command === "supersede") exitCode = runSupersede(args);
+else if (command === "archive") exitCode = runArchive(args);
+else if (command === "init") exitCode = runInit(args);
+else if (command === "verify-commit-msg") exitCode = runVerifyCommitMsg(args);
+else if (!command || command === "--help" || command === "-h") {
+  printHelp();
+  exitCode = command ? 0 : 1;
+} else {
+  console.error(`Unknown command: ${command}`);
+  printHelp();
+  exitCode = 1;
+}
+process.exitCode = exitCode;
+function printHelp() {
+  console.log("doc-gov \u2014 cross-project AI-collaboration documentation governance");
+  console.log("");
+  console.log("Usage: pnpm doc-gov <command> [args...]");
+  console.log("");
+  console.log("Commands:");
+  console.log("  check                       Validate frontmatter, status, canonical, integrity");
+  console.log("  scan [--check]              Regenerate (or verify) docs/governance/MANIFEST.yml");
+  console.log("  audit                       Advisory health report");
+  console.log("  links                       Validate current-layer local Markdown links");
+  console.log("  router-check                Validate router/profile/Superpowers wiring");
+  console.log("  doctor                      Run the full governance health and guardrail check");
+  console.log("  migrate --profile X --check Check project readiness for a selected profile");
+  console.log("  find <topic>                Search canonical docs by id/title/tag/path");
+  console.log("  list [--type X] [--status Y] [--pinned]  List docs");
+  console.log(
+    "  new <type> <slug>           Create a doc from template (decision/spec/plan/canon/policy/reference)"
+  );
+  console.log("  approve <id>                draft\u2192active (or proposed\u2192accepted)");
+  console.log("  supersede <oldId> <newId>   Mark old as superseded by new (bidirectional link)");
+  console.log("  archive <id> --reason TEXT  Move doc to docs/archive/<quarter>-<type>/");
+  console.log("  init [--force]              Create directory skeleton in current project");
+  console.log(
+    "  verify-commit-msg <file>    Hook helper: enforce Pinned-Override / Approves markers"
+  );
+  console.log("");
+  console.log(`Available commands: ${COMMANDS.join(", ")}`);
+}