@warpgogol/forge 5.3.4 → 6.0.0

package/os/compass/compass.module.ts

@@ -6,14 +6,19 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0556: removed dynamic import of @warpgogol/site-kernel-checks, all handlers now inlined in forge/os/compass/handlers/.</item>
-  <item>RFC-1095: compass.summary.record, trim repair rewrite, commit integration</item>
   <item>RFC-1097: steps 1-4 — compass.migrate codemod
 
 Add the v1 to v2 Compass header codemod: migrateFile pure transform (collapse, strip, seed, reorder, purpose-flag actions), migrateWorkspace walker, runCompassMigrate handler with dirty-tree refusal and --force/--files/--dry-run flags, module registration, and 15 unit tests.</item>
   <item>RFC-1173: declare mutatesState on all kernel commands — collectDeclarationDiagnostics emits error-severity MUTATES-STATE-DECLARED, command.manifest.validate is the blocking consumer in packages.check, sweep declares the flag on every command definition (factories hardcode false for read-only check specs)</item>
   <item>KERNEL-FLAG-02: Declare compass --root as kind "string[]" — resolveScanRoots reads it as multi-value via getFlagValues, so repeated --root stays legal now that repeated kind-"string" flags are rejected at flag resolution.</item>
-  <history>RFC-0374, RFC-0538</history>
+  <item>RFC-1231: step 1 — rename supportsAllSites to acceptsAllFlag
+
+Mechanical sweep: the field only ever gated --all argv acceptance; fan-out
+follows the parsed selector. Guard renamed assertAllSitesAllowed ->
+assertAllFlagAccepted, message updated. 417 declaration sites + type
+surfaces (KernelCommandMetadata, ForgeCommandMetadata) in one atomic pass.</item>
+  <item>RFC-1248: VITE-CLIENT-DEP-02 lazy-import gate + SCAN-02 validator reads-root existence check (RFC-1248)</item>
+  <history>RFC-0374, RFC-0538, RFC-0556, RFC-1095, RFC-1242</history>
 </CHANGE_SUMMARY>
 */
 
@@ -29,6 +34,7 @@ import {
 import { runCompassSummaryTrim } from "./handlers/compass-change-summary-handler.ts";
 import { runCompassSummaryRecord } from "./handlers/summary-record.ts";
 import { runCompassMigrate } from "./handlers/compass-migrate-handler.ts";
+import { runCompassDocsValidate } from "./handlers/compass-docs-validate.ts";
 
 const compassScanFlags = {
   packages: {
@@ -68,7 +74,7 @@ export const forgeCompassModule: ForgeModule = {
       mutatesState: true,
       description: "Generate the repository-wide Compass source inventory XML report.",
       scope: "workspace",
-      supportsAllSites: true,
+      acceptsAllFlag: true,
       flags: { ...compassScanFlags },
       reads: [
         "packages/**/*.{ts,tsx,astro,js,mjs,css,cs,tscn,tres,gd,md}",
@@ -85,11 +91,11 @@ export const forgeCompassModule: ForgeModule = {
       description:
         "Validate authored source files against current Compass scaffolding requirements.",
       scope: "workspace",
-      supportsAllSites: true,
+      acceptsAllFlag: true,
       flags: { ...compassScanFlags, mode: compassModeFlag },
       reads: [
         "packages/**/*.{ts,tsx,astro,js,mjs,css,cs,tscn,tres,gd,md}",
-        "apps/**/*.{ts,tsx,astro,js,mjs,css,cs,tscn,tres,gd,md}",
+        "apps/**/*.{ts,tsx,astro,js,mjs,css,cs,tscn,tres,gd,md}", // scan-coverage: consumer-workshop root — apps/ exists in consumer workshops, not this monorepo
         "services/**/*.{ts,tsx,astro,js,mjs,css,cs,tscn,tres,gd,md}",
         "docs/source-markup.xml",
       ],
@@ -97,11 +103,12 @@ export const forgeCompassModule: ForgeModule = {
     },
     {
       name: "compass.summary.record",
+      coverage: "operator" as const,
       description:
         "Append a governance-referencing item to each target file's CHANGE_SUMMARY and collapse the 5-item window into <history> (RFC-1095). Invoked by commit commands when a commit carries an RFC/ADR reference. Required flags: `--id`.",
       scope: "workspace",
       mutatesState: true,
-      supportsAllSites: true,
+      acceptsAllFlag: true,
       writes: [
         "apps/**/*.{astro,ts,tsx,js,mjs,css,cs,tscn,tres,gd,md}",
         "packages/**/*.{astro,ts,tsx,js,mjs,css,cs,tscn,tres,gd,md}",
@@ -136,11 +143,12 @@ export const forgeCompassModule: ForgeModule = {
     },
     {
       name: "compass.summary.trim",
+      coverage: "operator" as const,
       description:
         "Repair CHANGE_SUMMARY blocks to the v2 shape: collapse described items past 5 into <history>, remove ID-less items, normalize <history> (RFC-1095).",
       scope: "workspace",
       mutatesState: true,
-      supportsAllSites: true,
+      acceptsAllFlag: true,
       writes: [
         "apps/**/*.{astro,ts,tsx,js,mjs,css,cs,tscn,tres,gd,md}",
         "packages/**/*.{astro,ts,tsx,js,mjs,css,cs,tscn,tres,gd,md}",
@@ -168,7 +176,7 @@ export const forgeCompassModule: ForgeModule = {
         "Rewrite authored file headers to the Compass v2 shape (RFC-1097): collapse CHANGE_SUMMARY into <history>, strip forbidden v1 blocks, seed KEY_DECISIONS from @ai-invariant comments, reorder blocks canonically. Refuses a dirty git tree unless --force.",
       scope: "workspace",
       mutatesState: true,
-      supportsAllSites: true,
+      acceptsAllFlag: true,
       writes: [
         "apps/**/*.{astro,ts,tsx,js,mjs,css,cs,tscn,tres,gd,md}",
         "packages/**/*.{astro,ts,tsx,js,mjs,css,cs,tscn,tres,gd,md}",
@@ -200,12 +208,13 @@ export const forgeCompassModule: ForgeModule = {
     },
     {
       name: "compass.audit.plan",
+      coverage: "operator" as const,
       mutatesState: false,
       execOnReadOnly: true,
       description:
         "Emit a deterministic work-order of files whose revision has advanced past the threshold since their last Compass audit (RFC-0352). Read-only, no LLM.",
       scope: "workspace",
-      supportsAllSites: true,
+      acceptsAllFlag: true,
       flags: {
         ...compassScanFlags,
         threshold: {
@@ -223,12 +232,13 @@ export const forgeCompassModule: ForgeModule = {
     },
     {
       name: "compass.audit.record",
+      coverage: "operator" as const,
       modulePath: "packages/forge/os/compass/compass.module.ts",
       description:
         "Stamp a file's audit verdict and current revision into the compass-audit ledger (RFC-0352). Mutating. Required flags: `--file`, `--verdict`.",
       scope: "workspace",
       mutatesState: true,
-      supportsAllSites: true,
+      acceptsAllFlag: true,
       writes: ["docs/compass-audit-ledger.generated.yaml"],
       generates: [{ path: "docs/compass-audit-ledger.generated.yaml", phase: "on-demand" }],
       reads: ["docs/compass-audit-ledger.generated.yaml"],
@@ -251,7 +261,7 @@ export const forgeCompassModule: ForgeModule = {
         "Seed the compass-audit ledger for every authored file at its current revision with verdict=baseline (RFC-0352). One-time bootstrap.",
       scope: "workspace",
       mutatesState: true,
-      supportsAllSites: true,
+      acceptsAllFlag: true,
       writes: ["docs/compass-audit-ledger.generated.yaml"],
       // Artifact ownership is claimed by compass.audit.record (GENERATES-PATH-
       // COLLISION forbids two owners on a non-glob path); baseline only writes it.
@@ -268,23 +278,29 @@ export const forgeCompassModule: ForgeModule = {
     {
       name: "compass.audit.validate",
       mutatesState: false,
+      mutatingFlags: ["prune"],
       execOnReadOnly: true,
       contract: "compass",
       rules: [],
       description:
-        "Validate that no authored file is audit-overdue per the revision threshold (RFC-0352). Warns by default, fails with --strict.",
+        "Validate that no authored file is audit-overdue per the revision threshold (RFC-0352). Warns by default, fails with --strict. --prune drops ledger entries for paths that no longer exist (RFC-1242).",
       scope: "workspace",
-      supportsAllSites: true,
+      acceptsAllFlag: true,
       flags: {
         ...compassScanFlags,
         strict: {
           kind: "boolean",
           description: "Fail when audit-overdue authored files are found.",
         },
+        prune: {
+          kind: "boolean",
+          description:
+            "Drop ledger entries whose path no longer exists (RFC-1242). Mutating; honors --dry-run.",
+        },
       },
       reads: [
         "packages/**/*.{ts,tsx,astro,js,mjs,css,cs,tscn,tres,gd,md}",
-        "apps/**/*.{ts,tsx,astro,js,mjs,css,cs,tscn,tres,gd,md}",
+        "apps/**/*.{ts,tsx,astro,js,mjs,css,cs,tscn,tres,gd,md}", // scan-coverage: consumer-workshop root — apps/ exists in consumer workshops, not this monorepo
         "services/**/*.{ts,tsx,astro,js,mjs,css,cs,tscn,tres,gd,md}",
         "docs/compass-audit-ledger.generated.yaml",
       ],
@@ -299,6 +315,24 @@ export const forgeCompassModule: ForgeModule = {
         },
       },
     },
+    {
+      name: "compass.docs.validate",
+      modulePath: "packages/forge/os/compass/compass.module.ts",
+      mutatesState: false,
+      contract: "compass",
+      rules: ["COMPASS-DOC-00", "COMPASS-DOC-01", "COMPASS-DOC-02", "COMPASS-DOC-03"],
+      description:
+        "Validate that the live docs/*.xml corpus resolves every path, workspace id, and knowledge-graph link target it references (RFC-1242). Read-only.",
+      scope: "workspace",
+      acceptsAllFlag: true,
+      flags: {},
+      reads: ["docs/*.xml", "docs/command-manifest.generated.yaml", "docs/architecture-dna.md"],
+      execute: runCompassDocsValidate,
+      gate: {
+        severity: "mixed",
+        phase: "workspace",
+      },
+    },
   ],
   pipelines: [],
 };

package/os/compass/handlers/compass-audit-handler.ts

@@ -10,6 +10,7 @@ mode (RFC-0556). Drives per-file semantic-truth auditing on a revision cadence (
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
+  <item>RFC-1242: compass.audit.validate --prune — drops ledger entries whose path no longer exists via mutatingFlags upgrade; saveLedger routes writes through the injected io adapter so dry-run recording intercepts them.</item>
   <item>RFC-0352: initial implementation of compass.audit.plan, compass.audit.record, compass.audit.baseline, compass.audit.validate.</item>
   <item>RFC-0556: moved from @warpgogol/site-kernel-checks to @warpgogol/forge for autonomous mode.</item>
   <item>RFC-1094: audit work orders now carry the KEY_DECISIONS block alongside MODULE_CONTRACT and CHANGE_SUMMARY.</item>
@@ -27,12 +28,13 @@ import { resolveCompassPolicy } from "../policy.ts";
 import { resolveCompassScanRoot } from "./resolve-scan-root.ts";
 import { getRevisionByPath } from "./git-revision.ts";
 import type { CompassInventoryEntry } from "./compass-inventory.ts";
-import { writeFileAtomic } from "../../../src/utils/fs-atomic.ts";
+
 import { buildGeneratedHeader } from "../../../src/utils/generated-marker.ts";
 import type {
   ForgeCommandInput,
   ForgeCommandResult,
   ForgeRuntimeContext,
+  WorkspaceIO,
 } from "../../../src/types.ts";
 import { parse as yamlParse, stringify as yamlStringify } from "yaml";
 
@@ -104,17 +106,30 @@ async function loadLedger(workspaceRoot: string): Promise<CompassAuditLedger> {
   }
 }
 
-async function saveLedger(workspaceRoot: string, ledger: CompassAuditLedger): Promise<void> {
+function serializeLedger(ledger: CompassAuditLedger): string {
   const normalized = withLedgerAdvisory(ledger);
   normalized.entries.sort((a, b) => a.path.localeCompare(b.path));
-  const abs = resolve(workspaceRoot, LEDGER_PATH);
-  await io.mkdir(resolve(abs, ".."));
   const header = buildGeneratedHeader({
     ownerCommand: "compass.audit.record",
     filePath: LEDGER_PATH,
   });
-  const yaml = header + yamlStringify(normalized) + "\n";
-  await writeFileAtomic(abs, yaml);
+  return header + yamlStringify(normalized) + "\n";
+}
+
+// RFC-1242: writes route through the injected adapter so --dry-run recording
+// IO (mutatingFlags: ["prune"]) intercepts them — ambient writeFileAtomic would
+// bypass the recording adapter entirely (DNA-110). The param is named `io` so
+// the workspace-write-boundary lint recognizes the io.writeFile port call
+// (WS-WRITE-02 matches io.writeFile/context.io.writeFile member expressions).
+// Callers under a mutating-flag gate (compass.audit.validate --prune) write
+// via io.writeFile directly inside the gated block — registry-integrity sees
+// mutations in shared callees but not the caller's flag condition.
+async function saveLedger(
+  workspaceRoot: string,
+  ledger: CompassAuditLedger,
+  io: WorkspaceIO = ambientIo,
+): Promise<void> {
+  await io.writeFile(resolve(workspaceRoot, LEDGER_PATH), serializeLedger(ledger));
 }
 
 function extractBlock(source: string, tagName: string): string {
@@ -343,7 +358,7 @@ export async function runCompassAuditRecord(
   }
 
   if (!context.dryRun) {
-    await saveLedger(context.workspaceRoot, ledger);
+    await saveLedger(context.workspaceRoot, ledger, _io);
   }
 
   context.logger.info(
@@ -419,7 +434,7 @@ export async function runCompassAuditBaseline(
   ledger.entries.sort((a, b) => a.path.localeCompare(b.path));
 
   if (!context.dryRun) {
-    await saveLedger(context.workspaceRoot, ledger);
+    await saveLedger(context.workspaceRoot, ledger, _io);
   }
 
   context.logger.info(
@@ -449,10 +464,13 @@ export async function runCompassAuditValidate(
     }>;
     skippedIneligible: number;
     skippedPaths: string[];
+    pruned: number;
+    prunedPaths: string[];
   }>
 > {
-  const _io = resolveIo(context.io);
+  const io = resolveIo(context.io);
   const strict = input.flags["strict"] === true;
+  const prune = input.flags["prune"] === true;
   const scanRoot = resolveCompassScanRoot(input, context);
   const policy = resolveCompassPolicy(context.workspaceRoot, context.forgeRoot);
   const entries = await createCompassInventoryEntries(
@@ -465,6 +483,27 @@ export async function runCompassAuditValidate(
   const authored = getAuthoredEntries(entries);
   const ledger = await loadLedger(context.workspaceRoot);
 
+  // RFC-1242: --prune drops ledger entries whose path no longer exists.
+  // Opt-in only — verdict history for live paths is preserved untouched.
+  const prunedPaths: string[] = [];
+  if (prune) {
+    const kept: CompassAuditLedgerEntry[] = [];
+    for (const entry of ledger.entries) {
+      if (await io.exists(resolve(context.workspaceRoot, entry.path))) {
+        kept.push(entry);
+      } else {
+        prunedPaths.push(entry.path);
+      }
+    }
+    ledger.entries = kept;
+    if (prunedPaths.length > 0 && !context.dryRun) {
+      await io.writeFile(resolve(context.workspaceRoot, LEDGER_PATH), serializeLedger(ledger));
+    }
+    context.logger.info(
+      `[compass.audit.validate] pruned=${prunedPaths.length} ledger entr${prunedPaths.length === 1 ? "y" : "ies"} for non-existent paths${context.dryRun ? " (dry-run — not written)" : ""}`,
+    );
+  }
+
   // RFC-1143: drop ledger-ineligible authored paths (missions/, gitignored)
   // before the per-entry revision loop — baseline is forbidden to seed them,
   // so demanding entries is a guaranteed false-positive (COMPASS-AUDIT-01).
@@ -532,6 +571,8 @@ export async function runCompassAuditValidate(
       diagnostics,
       skippedIneligible,
       skippedPaths: skippedPaths.slice(0, SKIPPED_PATHS_CAP),
+      pruned: prunedPaths.length,
+      prunedPaths: prunedPaths.slice(0, SKIPPED_PATHS_CAP),
     },
     exitCode: hasErrors ? 1 : 0,
     summary: dueCount > 0 ? undefined : `[compass.audit.validate] OK (0 files overdue)`,

package/os/compass/handlers/compass-docs-validate.ts

@@ -0,0 +1,359 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-1242: validate that the live root docs/*.xml corpus describes the repository as it exists — every path token, workspace id, and knowledge-graph link target must resolve to a real file, directory, or declared node.</purpose>
+<non-goals>
+  <item>Do not scan archived trees, vendored specs, sessions/metrics, or authored RFC/ADR/plan bodies — frozen history and forward-looking prose legitimately name paths that do not exist.</item>
+  <item>Do not validate markdown link targets — only the XML semantic layer is gated (markdown sweep is manual).</item>
+  <item>Do not mutate anything — this handler is read-only; pruning lives on compass.audit.validate --prune.</item>
+</non-goals>
+<KEY_DECISIONS>
+  <item>Tag-stack tokenizer instead of an XML dependency — the corpus is small authored XML; a balance check catches the literal-tag breakage class (COMPASS-DOC-00) without pulling fast-xml-parser.</item>
+  <item>DOC-03 link targets resolve to declared node ids OR file/dir conventions — dangling-by-convention stays a warning, never an error.</item>
+</KEY_DECISIONS>
+<CHANGE_SUMMARY>
+  <item>RFC-1242: review fixes — self-close detection strips quoted attr values first (a="foo/" no longer fakes a self-close), non-backticked path tokens get the same ellipsis strip, docs.* link slugs keep their basename prefix (docs.plans.plan-rfc-* resolves).</item>
+  <item>RFC-1242: created — scan docs/*.xml for unresolvable paths, workspace ids, and link targets (COMPASS-DOC-00..03).</item>
+</CHANGE_SUMMARY>
+*/
+
+import { resolve } from "node:path";
+import { resolveIo } from "../../../src/utils/io.ts";
+import type { Diagnostic, WorkspaceIO } from "../../../src/types.ts";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+
+const DOCS_GLOB = "*.xml";
+
+// Well-formedness: minimal tag-stack check. Skips comments, CDATA, PIs and
+// declarations; a literal `<name` inside prose opens a tag that never balances
+// → COMPASS-DOC-00. The corpus is authored XML without < in attribute values.
+function checkWellFormed(file: string, source: string): { line: number; message: string } | null {
+  const stack: Array<{ name: string; line: number }> = [];
+  let i = 0;
+  let line = 1;
+  const advanceLine = (chunk: string) => {
+    for (const c of chunk) if (c === "\n") line++;
+  };
+  while (i < source.length) {
+    const open = source.indexOf("<", i);
+    if (open === -1) break;
+    advanceLine(source.slice(i, open));
+    const rest = source.slice(open);
+    // comments / CDATA / PI / declarations
+    if (rest.startsWith("<!--")) {
+      const end = source.indexOf("-->", open + 4);
+      if (end === -1) return { line, message: "unterminated comment" };
+      advanceLine(source.slice(open, end + 3));
+      i = end + 3;
+      continue;
+    }
+    if (rest.startsWith("<![CDATA[")) {
+      const end = source.indexOf("]]>", open + 9);
+      if (end === -1) return { line, message: "unterminated CDATA" };
+      advanceLine(source.slice(open, end + 3));
+      i = end + 3;
+      continue;
+    }
+    if (rest.startsWith("<?")) {
+      const end = source.indexOf("?>", open + 2);
+      if (end === -1) return { line, message: "unterminated processing instruction" };
+      advanceLine(source.slice(open, end + 2));
+      i = end + 2;
+      continue;
+    }
+    if (rest.startsWith("<!")) {
+      const end = source.indexOf(">", open + 2);
+      if (end === -1) return { line, message: "unterminated declaration" };
+      advanceLine(source.slice(open, end + 1));
+      i = end + 1;
+      continue;
+    }
+    const tagMatch = /^<(\/?)([A-Za-z_][\w:.-]*)((?:"[^"]*"|'[^']*'|[^>"'])*)?(\/?)>/.exec(rest);
+    if (!tagMatch) {
+      // `<` not starting a tag — literal text, tolerated.
+      advanceLine(source.slice(open, open + 1));
+      i = open + 1;
+      continue;
+    }
+    const [, closing, name, attrs = "", selfClose] = tagMatch;
+    advanceLine(tagMatch[0]);
+    i = open + tagMatch[0].length;
+    if (closing === "/") {
+      const top = stack.pop();
+      if (!top || top.name !== name) {
+        return {
+          line,
+          message: `mismatched closing tag </${name}>${top ? ` — expected </${top.name}> opened at line ${top.line}` : " — no open tag"}`,
+        };
+      }
+      continue;
+    }
+    const attrsUnquoted = attrs.replace(/"[^"]*"|'[^']*'/g, "");
+    if (selfClose !== "/" && !attrsUnquoted.trimEnd().endsWith("/")) {
+      stack.push({ name, line });
+    }
+  }
+  if (stack.length > 0) {
+    const top = stack[stack.length - 1]!;
+    return { line: top.line, message: `unclosed tag <${top.name}>` };
+  }
+  return null;
+}
+
+interface ExtractedRefs {
+  paths: Array<{ value: string; line: number }>;
+  workspaceIds: Array<{ id: string; line: number }>;
+  linkTargets: Array<{ target: string; line: number }>;
+}
+
+function extractRefs(source: string): ExtractedRefs {
+  const refs: ExtractedRefs = { paths: [], workspaceIds: [], linkTargets: [] };
+  const lineOf = (index: number) => source.slice(0, index).split("\n").length;
+  for (const m of source.matchAll(/<path>([\s\S]*?)<\/path>/g)) {
+    refs.paths.push({ value: m[1] ?? "", line: lineOf(m.index) });
+  }
+  for (const m of source.matchAll(/<workspace\s[^>]*?id="([^"]+)"/g)) {
+    refs.workspaceIds.push({ id: m[1]!, line: lineOf(m.index) });
+  }
+  for (const m of source.matchAll(/<node\s[^>]*>/g)) {
+    // DOC-02 only applies to ids that claim a workspace: <workspace> entries
+    // and workspace-typed nodes. Layer/symbolic ids (apps.rules,
+    // packages.rules, changelog.*) name semantic handles, not directories.
+    const id = /\bid="([^"]+)"/.exec(m[0])?.[1];
+    const type = /\btype="([^"]+)"/.exec(m[0])?.[1];
+    if (id && type === "workspace") {
+      refs.workspaceIds.push({ id, line: lineOf(m.index) });
+    }
+  }
+  for (const m of source.matchAll(/<link\s[^>]*?target="([^"]+)"/g)) {
+    refs.linkTargets.push({ target: m[1]!, line: lineOf(m.index) });
+  }
+  return refs;
+}
+
+// Normalize a <path> payload into checkable path tokens. Each backticked
+// fragment is one candidate — splitting on commas inside would shred brace
+// expansions (`{a,b}`) and ellipsis ranges (`docs/x/…` … `leaf`). A bare tail
+// fragment after an `…` outside the backticks resolves under the previous
+// fragment's directory (range shorthand for two versions of the same dir).
+function pathTokens(raw: string): string[] {
+  const tokens: string[] = [];
+  const fragments = [...raw.matchAll(/`([^`]*)`/g)].map((m) => m[1]!.trim());
+  if (fragments.length === 0) {
+    return raw
+      .split(/[\s,]+/)
+      .map((t) =>
+        t
+          .trim()
+          .replace(/(?:…|\.\.\.).*$/, "")
+          .replace(/\/+$/, ""),
+      )
+      .filter((t) => t.length > 0 && !t.startsWith("<") && t !== "…" && t !== "+");
+  }
+  const joinsWithEllipsis = raw.replace(/`[^`]*`/g, "").includes("…");
+  let parentDir: string | null = null;
+  for (const frag of fragments) {
+    const cleaned = frag.replace(/(?:…|\.\.\.).*$/, "").replace(/\/+$/, "");
+    if (!cleaned || cleaned === "+") continue;
+    if (joinsWithEllipsis && !cleaned.includes("/") && parentDir) {
+      tokens.push(`${parentDir}/${cleaned}`);
+      continue;
+    }
+    tokens.push(cleaned);
+    parentDir = cleaned.split("/").slice(0, -1).join("/") || parentDir;
+  }
+  return tokens;
+}
+
+/** Directory prefix that must exist for a path token (glob tails trimmed). */
+function pathCheckTarget(token: string): string {
+  const globIdx = token.search(/[*{[]/);
+  if (globIdx === -1) return token;
+  const prefix = token.slice(0, globIdx);
+  return prefix.replace(/\/[^/]*$/, "") || ".";
+}
+
+/** Resolve a workspace-style id to the package/service directory it names. */
+function workspaceIdTarget(id: string): string | null {
+  const pkg = /^pkg-([a-z0-9-]+)$/.exec(id);
+  if (pkg) return `packages/${pkg[1]}`;
+  const svc = /^svc-([a-z0-9-]+)$/.exec(id);
+  if (svc) return `services/${svc[1]}`;
+  const app = /^app-([a-z0-9-]+)$/.exec(id);
+  if (app) return `apps/${app[1]}`;
+  const dotted = /^(packages|apps|services)\.([a-z0-9-]+)/.exec(id);
+  if (dotted) return `${dotted[1]}/${dotted[2]}`;
+  return null;
+}
+
+/**
+ * DOC-03 resolution for dotted link targets: declared node id (checked by the
+ * caller) or a file/dir convention — docs.<dir>.<slug> → docs/<dir>/<slug>*,
+ * packages./apps./services. → workspace dir, spec.<x> → docs/specs/<x>*,
+ * dna-N → docs/architecture-dna.md, dotted command names → command manifest.
+ */
+async function linkTargetResolves(
+  target: string,
+  declaredIds: Set<string>,
+  io: WorkspaceIO,
+  docsDir: string,
+  commandNames: Set<string>,
+): Promise<"node" | "file" | "none"> {
+  if (declaredIds.has(target)) return "node";
+  if (commandNames.has(target)) return "file";
+  if (/^dna-\d+$/.test(target)) {
+    return (await io.exists(resolve(docsDir, "architecture-dna.md"))) ? "file" : "none";
+  }
+  const docsId = /^docs\.([a-z-]+)\.(.+)$/.exec(target);
+  if (docsId) {
+    const [, dir, slug] = docsId;
+    const hits = await io.glob(`${dir}/**/*${slug}*.md`, { cwd: docsDir }).catch(() => []);
+    if (hits.length > 0) return "file";
+    // generic fallback: any file whose basename contains the slug under docs/
+    const broad = await io.glob(`**/*${slug}*`, { cwd: docsDir }).catch(() => []);
+    if (broad.length > 0) return "file";
+    return "none";
+  }
+  const ws = workspaceIdTarget(target);
+  if (ws) return (await io.exists(ws)) ? "file" : "none";
+  const spec = /^spec\.([a-z0-9-]+)$/.exec(target);
+  if (spec) {
+    const hits = await io.glob(`specs/${spec[1]}*/**`, { cwd: docsDir }).catch(() => []);
+    const dirs = await io.glob(`specs/${spec[1]}*`, { cwd: docsDir }).catch(() => []);
+    return hits.length + dirs.length > 0 ? "file" : "none";
+  }
+  return "none";
+}
+
+export async function runCompassDocsValidate(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<
+  ForgeCommandResult<{
+    command: "compass.docs.validate";
+    status: "pass" | "fail";
+    scanned: { xmlFiles: number; pathsChecked: number; idsChecked: number };
+    diagnostics: Diagnostic[];
+  }>
+> {
+  const io = resolveIo(context.io);
+  const docsDir = resolve(context.workspaceRoot, "docs");
+  const diagnostics: Diagnostic[] = [];
+  let pathsChecked = 0;
+  let idsChecked = 0;
+
+  // Command-name convention for DOC-03: dotted targets like ratgeber.hub.validate
+  // resolve when the command registry lists them.
+  const commandNames = new Set<string>();
+  const manifestPath = resolve(docsDir, "command-manifest.generated.yaml");
+  if (await io.exists(manifestPath)) {
+    const manifest = await io.readFile(manifestPath);
+    for (const m of manifest.matchAll(/^\s*- name: ([\w.-]+)\s*$/gm)) {
+      commandNames.add(m[1]!);
+    }
+  }
+
+  const xmlFiles = (await io.glob(DOCS_GLOB, { cwd: docsDir })).sort();
+  const declaredNodeIds = new Set<string>();
+
+  // Pass 1: collect declared node ids so link targets can resolve across files.
+  const sources = new Map<string, string>();
+  for (const rel of xmlFiles) {
+    const abs = resolve(docsDir, rel);
+    const source = await io.readFile(abs);
+    sources.set(rel, source);
+    for (const m of source.matchAll(/<node\s[^>]*?id="([^"]+)"/g)) {
+      declaredNodeIds.add(m[1]!);
+    }
+  }
+
+  for (const rel of xmlFiles) {
+    const file = `docs/${rel}`;
+    const source = sources.get(rel)!;
+
+    const malformed = checkWellFormed(file, source);
+    if (malformed) {
+      diagnostics.push({
+        ruleId: "COMPASS-DOC-00",
+        severity: "error",
+        file,
+        line: malformed.line,
+        message: `file is not well-formed XML: ${malformed.message}`,
+      });
+      continue; // refs from a broken file are noise
+    }
+
+    const refs = extractRefs(source);
+
+    for (const { value, line } of refs.paths) {
+      for (const token of pathTokens(value)) {
+        pathsChecked++;
+        const target = pathCheckTarget(token);
+        if (!(await io.exists(resolve(context.workspaceRoot, target)))) {
+          diagnostics.push({
+            ruleId: "COMPASS-DOC-01",
+            severity: "error",
+            file,
+            line,
+            message: `<path> references '${token}' — does not exist under the workspace root`,
+            fixHint: "Repoint to the live path or remove the stale reference",
+          });
+        }
+      }
+    }
+
+    for (const { id, line } of refs.workspaceIds) {
+      const target = workspaceIdTarget(id);
+      if (!target) continue;
+      idsChecked++;
+      if (!(await io.exists(resolve(context.workspaceRoot, target)))) {
+        diagnostics.push({
+          ruleId: "COMPASS-DOC-02",
+          severity: "error",
+          file,
+          line,
+          message: `id '${id}' names workspace path '${target}' — does not exist`,
+          fixHint: "Repoint to the live package or remove the stale entry",
+        });
+      }
+    }
+
+    for (const { target, line } of refs.linkTargets) {
+      idsChecked++;
+      const resolved = await linkTargetResolves(target, declaredNodeIds, io, docsDir, commandNames);
+      if (resolved === "none") {
+        diagnostics.push({
+          ruleId: "COMPASS-DOC-03",
+          severity: "warning",
+          file,
+          line,
+          message: `link target '${target}' resolves to no declared node and no file`,
+        });
+      }
+    }
+  }
+
+  const errors = diagnostics.filter((d) => d.severity === "error");
+  for (const d of diagnostics) {
+    context.logger[d.severity === "error" ? "error" : "warn"](
+      `[compass.docs.validate] ${d.ruleId}: ${d.file}${d.line ? `:${d.line}` : ""}: ${d.message}`,
+    );
+  }
+
+  return {
+    data: {
+      command: "compass.docs.validate",
+      status: errors.length === 0 ? "pass" : "fail",
+      scanned: { xmlFiles: xmlFiles.length, pathsChecked, idsChecked },
+      diagnostics,
+    },
+    exitCode: errors.length > 0 ? 1 : 0,
+    summary:
+      errors.length === 0
+        ? `[compass.docs.validate] OK (${xmlFiles.length} files, ${pathsChecked} paths, ${idsChecked} ids)`
+        : `[compass.docs.validate] ${errors.length} error(s)`,
+  };
+}