@warpgogol/forge 5.3.4 → 6.0.0

package/os/compass/handlers/summary-record.ts

@@ -28,11 +28,13 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 
 compass-migrate-handler hint used a consumer-specific run command — switched to generic 'pnpm exec forge run' convention. Reworded recorded CHANGE_SUMMARY items in 3 handlers to drop the consumer-specific literal. compass-policy AC-4 test green (65/65).</item>
   <item>RFC-1220: step 2 — fail-closed guards in history paths</item>
+  <item>RFC-1233: stripGitTrailers at the record point + sanitizeItemText star-slash guard — commit-message trailers (Token: value / Token #value, plus markdown-link attribution lines like "Generated with [X](url)") no longer pollute injected items.</item>
+  <item>Session-retro 2026-10-08: id-in-diff dedup — auto-inject skips when the worktree diff already carries a same-ID item (HEAD-vs-worktree via git show HEAD:path), closing the descriptive+generic duplicate class seen on RFC-1237.</item>
   <history>RFC-1095</history>
 </CHANGE_SUMMARY>
 */
 
-import { existsSync } from "../../../src/utils/sync-fs.ts";
+import { execFile, existsSync } from "../../../src/utils/sync-fs.ts";
 import { ambientIo, resolveIo } from "../../../src/utils/io.ts";
 
 import { resolve, relative } from "node:path";
@@ -69,7 +71,7 @@ export interface SummaryRecordInput {
   workpiece?: string;
 }
 
-export type SummaryRecordSkipReason = "no-block" | "duplicate" | "unparseable";
+export type SummaryRecordSkipReason = "no-block" | "duplicate" | "unparseable" | "id-in-diff";
 
 export interface SummaryRecordResult {
   command: "compass.summary.record";
@@ -167,6 +169,41 @@ export function stripConventionalPrefix(subject: string): string {
   return subject.replace(CONVENTIONAL_PREFIX_RE, "").trim();
 }
 
+// RFC-1233: git-trailer tail block — strict `Token: value` / `Token #value`
+// lines (interpret-trailers shape, empty value allowed), plus lines ending
+// in a markdown link (the observed "Generated with [X](url)" attribution
+// boilerplate has no separator). A link-shaped line is admitted only when
+// the block also contains at least one strict trailer line — a lone link
+// tail is prose.
+const TRAILER_LINE_RE = /^[A-Za-z0-9-]+(:| #)\s*.*$/;
+const MARKDOWN_LINK_TAIL_RE = /^.*\[[^\]]*\]\([^)]+\)\s*$/;
+
+/**
+ * Remove a trailing git-trailer block: the contiguous tail of strict
+ * trailer lines and admitted markdown-link lines. A blank line ends the
+ * tail paragraph. Returns the message without the block; when the tail
+ * holds no strict trailer line the message is returned unchanged.
+ */
+export function stripGitTrailers(message: string): string {
+  const lines = message.trimEnd().split("\n");
+  let start = lines.length;
+  let sawStrict = false;
+  while (start > 0) {
+    const line = lines[start - 1]!.trim();
+    if (line === "") break;
+    if (TRAILER_LINE_RE.test(line)) {
+      sawStrict = true;
+      start--;
+    } else if (MARKDOWN_LINK_TAIL_RE.test(line)) {
+      start--;
+    } else {
+      break;
+    }
+  }
+  if (!sawStrict || start === lines.length) return message;
+  return lines.slice(0, start).join("\n").trimEnd();
+}
+
 // Literal Compass block tags inside an item corrupt block parsing — a commit
 // message saying "collapsed into history" would be matched by HISTORY_RE and
 // produce phantom non-ID tokens (CS-07). Strip the angle brackets on record.
@@ -174,7 +211,14 @@ const COMPASS_TAG_LITERAL_RE =
   /<\/?(?:CHANGE_SUMMARY|MODULE_CONTRACT|KEY_DECISIONS|history|item|purpose|non-goals)>/g;
 
 export function sanitizeItemText(text: string): string {
-  return text.replace(COMPASS_TAG_LITERAL_RE, (tag) => tag.replace(/[<>]/g, ""));
+  return (
+    text
+      .replace(COMPASS_TAG_LITERAL_RE, (tag) => tag.replace(/[<>]/g, ""))
+      // RFC-1233: a literal star-slash sequence would terminate the
+      // surrounding block comment when the item lands in /* ... */ headers.
+      // ∕ (U+2215) is visually near-identical, idempotent, and never re-forms.
+      .replace(/\*\//g, "*\u2215")
+  );
 }
 
 export function isValidGovernanceId(id: string, policy: CompassPolicy): boolean {
@@ -190,6 +234,8 @@ interface RecordOutcome {
 /**
  * Append `ID: text` to one file's CHANGE_SUMMARY and collapse the window.
  * Returns the outcome; writes the file only when mutated and not dry-run.
+ * `headSource` is the file's content at HEAD (when resolvable) — it enables
+ * the id-in-diff dedup; pass undefined outside git workspaces.
  */
 export async function recordSummaryItem(
   absPath: string,
@@ -198,6 +244,7 @@ export async function recordSummaryItem(
   text: string,
   dryRun: boolean,
   policy: CompassPolicy,
+  headSource?: string,
 ): Promise<RecordOutcome> {
   const source = await io.readFile(absPath);
   const blockMatch = source.match(CHANGE_SUMMARY_BLOCK_RE);
@@ -228,6 +275,22 @@ export async function recordSummaryItem(
     return { recorded: false, collapsed: false, skipReason: "duplicate" };
   }
 
+  // A same-ID item already in the worktree but absent from HEAD means the
+  // pending change already carries a hand-authored record for this governance
+  // ID — the auto-injected subject-derived item would duplicate it at lower
+  // specificity (observed 2026-10-08: 27 files carried descriptive + generic
+  // RFC-1237 items). HEAD-resident same-ID items do NOT suppress: consecutive
+  // commits under one RFC legitimately stack step items.
+  if (headSource !== undefined) {
+    const headBlock = headSource.match(CHANGE_SUMMARY_BLOCK_RE);
+    const headItems = headBlock ? parseChangeSummary(headBlock[0]).items : [];
+    const idInWorktree = items.some((item) => leadingGovernanceId(item, policy) === id);
+    const idInHead = headItems.some((item) => leadingGovernanceId(item, policy) === id);
+    if (idInWorktree && !idInHead) {
+      return { recorded: false, collapsed: false, skipReason: "id-in-diff" };
+    }
+  }
+
   const nextItems = [...items, newItem];
   const collapsedIds: string[] = [];
   while (nextItems.length > CHANGE_SUMMARY_WINDOW) {
@@ -246,6 +309,27 @@ export async function recordSummaryItem(
   return { recorded: true, collapsed };
 }
 
+function execGit(cwd: string, args: string[]): Promise<string | null> {
+  return new Promise((resolve) => {
+    execFile("git", args, { cwd, timeout: 5000 }, (err, stdout) => {
+      resolve(err ? null : stdout);
+    });
+  });
+}
+
+/**
+ * Read `path`'s content at HEAD — the baseline for the id-in-diff dedup.
+ * Returns undefined when the file is untracked or the workspace is not a git
+ * repo (the dedup then falls back to exact-text matching only).
+ */
+async function readHeadSource(gitTop: string | null, absPath: string): Promise<string | undefined> {
+  if (!gitTop) return undefined;
+  const rel = relative(gitTop, absPath).replace(/\\/g, "/");
+  if (rel === "" || rel.startsWith("..")) return undefined;
+  const source = await execGit(gitTop, ["show", `HEAD:${rel}`]);
+  return source ?? undefined;
+}
+
 function riskReminderNeeded(relPath: string, source: string, policy: CompassPolicy): boolean {
   const segments = relPath.split("/").filter(Boolean);
   const workspaceRel = getWorkspaceRelativeSegments(segments, policy).join("/");
@@ -278,7 +362,10 @@ export async function runCompassSummaryRecord(
       : [];
 
   const rawText = input.flags["text"];
-  const text = typeof rawText === "string" && rawText.trim().length > 0 ? rawText.trim() : id;
+  // RFC-1233: strip the git-trailer block at the single injection point —
+  // ecosystem.commit and mission.git.commit both pipe the raw message here.
+  const stripped = typeof rawText === "string" ? stripGitTrailers(rawText).trim() : "";
+  const text = stripped.length > 0 ? stripped : id;
 
   const result: SummaryRecordResult = {
     command: "compass.summary.record",
@@ -289,6 +376,9 @@ export async function runCompassSummaryRecord(
     keyDecisionsReminders: [],
   };
 
+  const gitTopRaw = await execGit(baseRoot, ["rev-parse", "--show-toplevel"]);
+  const gitTop = gitTopRaw?.trim() || null;
+
   for (const file of files) {
     const absPath = resolve(baseRoot, file);
     const relPath = relative(baseRoot, absPath).replace(/\\/g, "/");
@@ -298,7 +388,16 @@ export async function runCompassSummaryRecord(
       continue;
     }
     try {
-      const outcome = await recordSummaryItem(absPath, relPath, id, text, context.dryRun, policy);
+      const headSource = await readHeadSource(gitTop, absPath);
+      const outcome = await recordSummaryItem(
+        absPath,
+        relPath,
+        id,
+        text,
+        context.dryRun,
+        policy,
+        headSource,
+      );
       if (outcome.skipReason) {
         result.skipped.push({ file, reason: outcome.skipReason });
         continue;

package/os/compass/handlers/tests/compass-audit-record.test.ts

@@ -16,6 +16,7 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { parse as yamlParse } from "yaml";
 import { runCompassAuditRecord } from "../compass-audit-handler.ts";
+import { ambientIo } from "../../../../src/utils/io.ts";
 import type { ForgeCommandInput, ForgeRuntimeContext } from "../../../../src/types.ts";
 
 const execFileAsync = promisify(execFile);
@@ -42,7 +43,7 @@ function makeContext(workspaceRoot: string): ForgeRuntimeContext {
     logger: logger as never,
     dryRun: false,
     outputFormat: "json",
-    io: {} as never,
+    io: ambientIo,
     actualState: undefined as never,
     fileIntents: [],
   } as unknown as ForgeRuntimeContext;

package/os/compass/handlers/tests/compass-audit-validate.test.ts

@@ -16,6 +16,7 @@ import { join } from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { runCompassAuditValidate } from "../compass-audit-handler.ts";
+import { ambientIo } from "../../../../src/utils/io.ts";
 import type { ForgeCommandInput, ForgeRuntimeContext } from "../../../../src/types.ts";
 
 const execFileAsync = promisify(execFile);
@@ -31,15 +32,15 @@ const logger = {
   },
 };
 
-function makeContext(workspaceRoot: string): ForgeRuntimeContext {
+function makeContext(workspaceRoot: string, dryRun = false): ForgeRuntimeContext {
   return {
     workspaceRoot,
     site: undefined,
     siteExplicit: false,
     logger: logger as never,
-    dryRun: false,
+    dryRun,
     outputFormat: "json",
-    io: {} as never,
+    io: ambientIo,
     actualState: undefined as never,
     fileIntents: [],
   } as unknown as ForgeRuntimeContext;
@@ -131,3 +132,91 @@ describe("compass.audit.validate — RFC-1143 ledger-ineligible skips", () => {
     expect(data.skippedIneligible).toBeGreaterThan(0);
   });
 });
+
+// RFC-1242 AC-5/AC-6: --prune drops ledger entries for paths that no longer
+// exist while preserving every surviving entry's verdict fields.
+const DEAD_PATH = "packages/gone/deleted.ts";
+const LEDGER_ENTRY = (path: string) =>
+  `  - path: ${path}\n    entityId: "eid-${path}"\n    auditedRevision: 7\n    auditedHash: "hash-${path}"\n    auditedAt: "2026-01-01T00:00:00Z"\n    verdict: pass\n    agent: human:test\n`;
+
+describe("compass.audit.validate --prune — RFC-1242", () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "compass-prune-"));
+    await mkdir(join(root, "packages", "foo"), { recursive: true });
+    await mkdir(join(root, "docs"), { recursive: true });
+    await writeFile(join(root, "packages", "foo", "index.ts"), "export const x = 1;\n", "utf8");
+    await writeFile(
+      join(root, "docs", "compass-audit-ledger.generated.yaml"),
+      `entries:\n${LEDGER_ENTRY(ELIGIBLE_FILE)}${LEDGER_ENTRY(DEAD_PATH)}`,
+      "utf8",
+    );
+    await execFileAsync("git", ["init"], { cwd: root });
+    await execFileAsync("git", ["config", "user.email", "test@test.com"], { cwd: root });
+    await execFileAsync("git", ["config", "user.name", "Test"], { cwd: root });
+    await execFileAsync("git", ["add", "."], { cwd: root });
+    await execFileAsync("git", ["commit", "-m", "init"], { cwd: root });
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it("AC-5: ledger contains no entry whose path does not exist after prune", async () => {
+    const result = await runCompassAuditValidate(
+      makeInput({ prune: true, root: ["packages"] }),
+      makeContext(root),
+    );
+    const data = result.data as { pruned: number; prunedPaths: string[] };
+    expect(data.pruned).toBe(1);
+    expect(data.prunedPaths).toEqual([DEAD_PATH]);
+    const { readFile } = await import("node:fs/promises");
+    const ledgerText = await readFile(
+      join(root, "docs", "compass-audit-ledger.generated.yaml"),
+      "utf8",
+    );
+    expect(ledgerText).not.toContain(DEAD_PATH);
+    expect(ledgerText).toContain(ELIGIBLE_FILE);
+  });
+
+  it("AC-6: surviving entries keep their verdict fields unchanged", async () => {
+    await runCompassAuditValidate(
+      makeInput({ prune: true, root: ["packages"] }),
+      makeContext(root),
+    );
+    const { readFile } = await import("node:fs/promises");
+    const { parse } = await import("yaml");
+    const ledger = parse(
+      await readFile(join(root, "docs", "compass-audit-ledger.generated.yaml"), "utf8"),
+    ) as { entries: Array<Record<string, unknown>> };
+    const survivor = ledger.entries.find((e) => e.path === ELIGIBLE_FILE);
+    expect(
+      survivor,
+      "surviving ledger entry must keep its verdict fields — check the keep/drop partition",
+    ).toMatchObject({
+      entityId: `eid-${ELIGIBLE_FILE}`,
+      auditedRevision: 7,
+      auditedHash: `hash-${ELIGIBLE_FILE}`,
+      auditedAt: "2026-01-01T00:00:00Z",
+      verdict: "pass",
+      agent: "human:test",
+    });
+  });
+
+  it("--prune --dry-run reports the drop set without rewriting the ledger", async () => {
+    const { readFile } = await import("node:fs/promises");
+    const ledgerPath = join(root, "docs", "compass-audit-ledger.generated.yaml");
+    const before = await readFile(ledgerPath, "utf8");
+    const result = await runCompassAuditValidate(
+      makeInput({ prune: true, root: ["packages"] }),
+      makeContext(root, true),
+    );
+    const data = result.data as { pruned: number };
+    expect(data.pruned).toBe(1);
+    expect(
+      await readFile(ledgerPath, "utf8"),
+      "dry-run must not rewrite the ledger — writes must route through context.io honoring context.dryRun",
+    ).toBe(before);
+  });
+});

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

@@ -0,0 +1,203 @@
+/*
+<MODULE_CONTRACT>
+  <purpose>
+    RFC-1242 AC-1..AC-4: compass.docs.validate scans the docs/*.xml corpus and
+    must fail on unresolvable <path> entries (COMPASS-DOC-01) and dead workspace
+    ids (COMPASS-DOC-02), warn on unresolvable link targets (COMPASS-DOC-03),
+    and flag malformed XML (COMPASS-DOC-00). A green corpus exits 0 with
+    status-shaped data.
+  </purpose>
+</MODULE_CONTRACT>
+*/
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runCompassDocsValidate } from "../compass-docs-validate.ts";
+import { ambientIo } from "../../../../src/utils/io.ts";
+import type { Diagnostic, ForgeCommandInput, ForgeRuntimeContext } from "../../../../src/types.ts";
+
+const logger = {
+  section() {},
+  info() {},
+  warn() {},
+  error() {},
+  success() {},
+  getEvents() {
+    return [];
+  },
+};
+
+function makeContext(workspaceRoot: string): ForgeRuntimeContext {
+  return {
+    workspaceRoot,
+    site: undefined,
+    siteExplicit: false,
+    logger: logger as never,
+    dryRun: false,
+    outputFormat: "json",
+    io: ambientIo,
+    actualState: undefined as never,
+    fileIntents: [],
+  } as unknown as ForgeRuntimeContext;
+}
+
+function makeInput(): ForgeCommandInput {
+  return { argv: [], flags: {} } as unknown as ForgeCommandInput;
+}
+
+const GREEN_DOC = `<root>
+  <path>\`docs/other.xml\`</path>
+  <workspace id="pkg-foo"><path>\`packages/foo\`</path></workspace>
+  <node id="packages.foo" type="package"><path>\`packages/foo\`</path></node>
+  <node id="root.a" type="compass-doc"><link rel="binds-to" target="root.b" /></node>
+  <node id="root.b" type="compass-doc" />
+</root>
+`;
+
+describe("compass.docs.validate — RFC-1242", () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "compass-docs-"));
+    await mkdir(join(root, "docs"), { recursive: true });
+    await mkdir(join(root, "packages", "foo"), { recursive: true });
+    await writeFile(join(root, "packages", "foo", "index.ts"), "export {};\n", "utf8");
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it("AC-2: green corpus exits 0 and reports scanned counts", async () => {
+    await writeFile(join(root, "docs", "a.xml"), GREEN_DOC, "utf8");
+    await writeFile(join(root, "docs", "other.xml"), "<root/>", "utf8");
+    const result = await runCompassDocsValidate(makeInput(), makeContext(root));
+    expect(result.exitCode).toBe(0);
+    const data = result.data as {
+      scanned: { xmlFiles: number; pathsChecked: number; idsChecked: number };
+      diagnostics: Diagnostic[];
+    };
+    expect(data.scanned.xmlFiles).toBe(2);
+    expect(data.diagnostics).toEqual([]);
+  });
+
+  it("AC-3: dead <path> emits COMPASS-DOC-01 error", async () => {
+    await writeFile(
+      join(root, "docs", "a.xml"),
+      `<root><path>\`packages/gone\`</path></root>`,
+      "utf8",
+    );
+    const result = await runCompassDocsValidate(makeInput(), makeContext(root));
+    const diagnostics = (result.data as { diagnostics: Diagnostic[] }).diagnostics;
+    expect(
+      diagnostics.some((d) => d.ruleId === "COMPASS-DOC-01" && d.severity === "error"),
+      "dead <path> must emit COMPASS-DOC-01 — check pathTokens/pathCheckTarget resolution",
+    ).toBe(true);
+  });
+
+  it("AC-4: dead <path> produces a non-zero exit", async () => {
+    await writeFile(
+      join(root, "docs", "a.xml"),
+      `<root><path>\`packages/gone\`</path></root>`,
+      "utf8",
+    );
+    const result = await runCompassDocsValidate(makeInput(), makeContext(root));
+    expect(result.exitCode).toBe(1);
+  });
+
+  it("dead workspace id emits COMPASS-DOC-02 error", async () => {
+    await writeFile(join(root, "docs", "a.xml"), `<root><workspace id="pkg-gone"/></root>`, "utf8");
+    const result = await runCompassDocsValidate(makeInput(), makeContext(root));
+    const diagnostics = (result.data as { diagnostics: Diagnostic[] }).diagnostics;
+    expect(
+      diagnostics.some((d) => d.ruleId === "COMPASS-DOC-02" && d.message.includes("pkg-gone")),
+      "dead workspace id must emit COMPASS-DOC-02 — check workspaceIdTarget mapping",
+    ).toBe(true);
+    expect(result.exitCode).toBe(1);
+  });
+
+  it("glob-tail <path> resolves against the parent directory", async () => {
+    await writeFile(
+      join(root, "docs", "a.xml"),
+      `<root><path>\`packages/*\`</path></root>`,
+      "utf8",
+    );
+    const result = await runCompassDocsValidate(makeInput(), makeContext(root));
+    expect(result.exitCode).toBe(0);
+  });
+
+  it("unresolvable link target emits COMPASS-DOC-03 warning, never an error", async () => {
+    await writeFile(
+      join(root, "docs", "a.xml"),
+      `<root><node id="x"><link rel="binds-to" target="docs.rfcs.rfc-9999" /></node></root>`,
+      "utf8",
+    );
+    const result = await runCompassDocsValidate(makeInput(), makeContext(root));
+    const diagnostics = (result.data as { diagnostics: Diagnostic[] }).diagnostics;
+    expect(
+      diagnostics.some((d) => d.ruleId === "COMPASS-DOC-03" && d.severity === "warning"),
+      "dangling link target must warn via COMPASS-DOC-03",
+    ).toBe(true);
+    expect(result.exitCode).toBe(0);
+  });
+
+  it("link target resolving to an archived RFC file passes", async () => {
+    await mkdir(join(root, "docs", "rfcs", "archive"), { recursive: true });
+    await writeFile(join(root, "docs", "rfcs", "archive", "rfc-0097-old.md"), "x", "utf8");
+    await writeFile(
+      join(root, "docs", "a.xml"),
+      `<root><node id="x"><link rel="binds-to" target="docs.rfcs.rfc-0097" /></node></root>`,
+      "utf8",
+    );
+    const result = await runCompassDocsValidate(makeInput(), makeContext(root));
+    expect(result.exitCode).toBe(0);
+  });
+
+  it("malformed XML emits COMPASS-DOC-00 and skips ref checks for that file", async () => {
+    await writeFile(join(root, "docs", "a.xml"), `<root><name>oops</root>`, "utf8");
+    const result = await runCompassDocsValidate(makeInput(), makeContext(root));
+    const diagnostics = (result.data as { diagnostics: Diagnostic[] }).diagnostics;
+    expect(diagnostics.some((d) => d.ruleId === "COMPASS-DOC-00")).toBe(true);
+    expect(diagnostics.some((d) => d.ruleId === "COMPASS-DOC-01")).toBe(false);
+    expect(result.exitCode).toBe(1);
+  });
+
+  it("quoted attribute value ending in / is not misread as self-closing", async () => {
+    await writeFile(
+      join(root, "docs", "a.xml"),
+      `<root><node id="x" type="compass-doc" path="docs/"><link rel="binds-to" target="x" /></node></root>`,
+      "utf8",
+    );
+    const result = await runCompassDocsValidate(makeInput(), makeContext(root));
+    const diagnostics = (result.data as { diagnostics: Diagnostic[] }).diagnostics;
+    expect(diagnostics.some((d) => d.ruleId === "COMPASS-DOC-00")).toBe(false);
+    expect(result.exitCode).toBe(0);
+  });
+
+  it("docs.plans.plan-rfc-* link target resolves to a plan-*.md basename", async () => {
+    await mkdir(join(root, "docs", "plans"), { recursive: true });
+    await writeFile(join(root, "docs", "plans", "plan-rfc-1242-x.md"), "x", "utf8");
+    await writeFile(
+      join(root, "docs", "a.xml"),
+      `<root><node id="x"><link rel="binds-to" target="docs.plans.plan-rfc-1242-x" /></node></root>`,
+      "utf8",
+    );
+    const result = await runCompassDocsValidate(makeInput(), makeContext(root));
+    const diagnostics = (result.data as { diagnostics: Diagnostic[] }).diagnostics;
+    expect(diagnostics.some((d) => d.ruleId === "COMPASS-DOC-03")).toBe(false);
+  });
+
+  it("AC-1: result data carries command-shaped payload fields", async () => {
+    await writeFile(join(root, "docs", "a.xml"), GREEN_DOC, "utf8");
+    await writeFile(join(root, "docs", "other.xml"), "<root/>", "utf8");
+    const result = await runCompassDocsValidate(makeInput(), makeContext(root));
+    const data = result.data as Record<string, unknown>;
+    expect(data).toHaveProperty("command", "compass.docs.validate");
+    expect(data).toHaveProperty("status", "pass");
+    expect(data).toHaveProperty("scanned");
+    expect(data).toHaveProperty("diagnostics");
+    expect(Array.isArray(data.diagnostics)).toBe(true);
+  });
+});

package/os/compass/handlers/tests/compass-ledger-scope.test.ts

@@ -16,6 +16,7 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { parse as yamlParse } from "yaml";
 import { runCompassAuditBaseline } from "../compass-audit-handler.ts";
+import { ambientIo } from "../../../../src/utils/io.ts";
 import type { ForgeCommandInput, ForgeRuntimeContext } from "../../../../src/types.ts";
 
 const execFileAsync = promisify(execFile);
@@ -39,7 +40,7 @@ function makeContext(workspaceRoot: string): ForgeRuntimeContext {
     logger: logger as never,
     dryRun: false,
     outputFormat: "json",
-    io: {} as never,
+    io: ambientIo,
     actualState: undefined as never,
     fileIntents: [],
   } as unknown as ForgeRuntimeContext;