@warpgogol/forge 4.2.4 → 5.1.1

package/os/compass/handlers/tests/compass-policy.test.ts

@@ -0,0 +1,249 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for RFC-1096 Compass policy externalization — generic
+defaults, profile overlay, bindings.compass overrides, merge semantics, and
+the named-config-error contract.</purpose>
+<non-goals>
+  <item>Do not test v2 rule diagnostics — covered by compass-v2-contract.test.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1096: initial coverage for resolveCompassPolicy (AC-1..AC-5).</item>
+</CHANGE_SUMMARY>
+*/
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+import {
+  resolveCompassPolicy,
+  CompassPolicyConfigError,
+  parseGovernanceIdParts,
+} from "../../policy.ts";
+import { runCompassInventory } from "../compass-inventory-handler.ts";
+import type { ForgeRuntimeContext } from "../../../../src/types.ts";
+
+// packages/forge — real forge root so `profile:` resolution finds shipped profiles.
+const FORGE_ROOT = fileURLToPath(new URL("../../../../", import.meta.url));
+// os/compass directory — scanned by the AC-4 literal check.
+const COMPASS_DIR = fileURLToPath(new URL("../../", import.meta.url));
+
+const FORGE_YAML = (bindings: string) => `
+schema: forge/config@1
+project:
+  name: test-ws
+  stack: [typescript]
+  packageManager: pnpm
+paths:
+  rfcsDir: docs/rfcs
+  adrsDir: docs/adrs
+  plansDir: docs/plans
+  auditsDir: docs/audits
+  specsDir: docs/specs
+  skillsDir: .agents/skills
+bindings:
+  schema: forge/bindings@1
+  commands: {}
+  paths: {}
+${bindings}`;
+
+const FORGE_YAML_WITH_PROFILE = `
+schema: forge/config@1
+profile: godot-game
+project:
+  name: test-ws
+  stack: [godot]
+  packageManager: pnpm
+paths:
+  rfcsDir: docs/rfcs
+  adrsDir: docs/adrs
+  plansDir: docs/plans
+  auditsDir: docs/audits
+  specsDir: docs/specs
+  skillsDir: .agents/skills
+`;
+
+function makeContext(workspaceRoot: string): ForgeRuntimeContext {
+  return {
+    workspaceRoot,
+    forgeRoot: FORGE_ROOT,
+    dryRun: true,
+    logger: { info: () => {}, warn: () => {}, error: () => {} },
+  } as unknown as ForgeRuntimeContext;
+}
+
+function collectTsFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const abs = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...collectTsFiles(abs));
+    else if (entry.isFile() && entry.name.endsWith(".ts")) out.push(abs);
+  }
+  return out;
+}
+
+describe("resolveCompassPolicy (RFC-1096)", () => {
+  let root: string;
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "compass-policy-"));
+  });
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("AC-1: bindings.compass.scanRoots replaces the generic scan roots", () => {
+    writeFileSync(join(root, "forge.yaml"), FORGE_YAML("  compass:\n    scanRoots: [src]\n"));
+    const policy = resolveCompassPolicy(root, FORGE_ROOT);
+    expect(policy.scanRoots).toEqual(["src"]);
+    expect(policy.source.overriddenKeys).toContain("scanRoots");
+  });
+
+  it("AC-1b: union keys merge and `!` subtracts", () => {
+    writeFileSync(
+      join(root, "forge.yaml"),
+      FORGE_YAML(
+        '  compass:\n    fileExtensions: [.ts, .svelte, "!.astro"]\n    ignoredDirs: [spec, "!coverage"]\n',
+      ),
+    );
+    const policy = resolveCompassPolicy(root, FORGE_ROOT);
+    expect(policy.fileExtensions.has(".svelte")).toBe(true);
+    expect(policy.fileExtensions.has(".ts")).toBe(true);
+    expect(policy.fileExtensions.has(".astro")).toBe(false);
+    expect(policy.ignoredDirs.has("spec")).toBe(true);
+    expect(policy.ignoredDirs.has("coverage")).toBe(false);
+    expect(policy.ignoredDirs.has("node_modules")).toBe(true);
+  });
+
+  it("AC-1c: consumer layerRules replace the generic set wholesale", () => {
+    writeFileSync(
+      join(root, "forge.yaml"),
+      FORGE_YAML(
+        "  compass:\n    layerRules:\n      - pattern: src/pages/**\n        layer: route\n        risk: high\n",
+      ),
+    );
+    const policy = resolveCompassPolicy(root, FORGE_ROOT);
+    expect(policy.matchLayer("src/pages/index.astro")?.layer).toBe("route");
+    expect(policy.matchLayer("src/pages/index.astro")?.risk).toBe("high");
+    // Replace semantics: generic rules are gone when the consumer sets the key.
+    expect(policy.matchLayer("src/components/x.ts")).toBeUndefined();
+    expect(policy.layerRules).toHaveLength(1);
+  });
+
+  it("AC-2: profile compass section applies when forge.yaml declares `profile`", () => {
+    writeFileSync(join(root, "forge.yaml"), FORGE_YAML_WITH_PROFILE);
+    const policy = resolveCompassPolicy(root, FORGE_ROOT);
+    expect(policy.source.profile).toBe("godot-game");
+    for (const ext of [".cs", ".tscn", ".tres", ".gd"]) {
+      expect(policy.fileExtensions.has(ext), `missing ${ext}`).toBe(true);
+    }
+    expect(policy.source.overriddenKeys).toEqual([]);
+  });
+
+  it("AC-3: non-compilable idPattern throws CompassPolicyConfigError naming the key", () => {
+    writeFileSync(join(root, "forge.yaml"), FORGE_YAML('  compass:\n    idPattern: "([invalid"\n'));
+    expect(() => resolveCompassPolicy(root, FORGE_ROOT)).toThrow(CompassPolicyConfigError);
+    try {
+      resolveCompassPolicy(root, FORGE_ROOT);
+      expect.unreachable();
+    } catch (err) {
+      expect(err).toBeInstanceOf(CompassPolicyConfigError);
+      expect((err as CompassPolicyConfigError).key).toBe("idPattern");
+      expect((err as Error).message).toContain("idPattern");
+    }
+  });
+
+  it("AC-3b: idPattern that fails the NAMESPACE-NUMBER probe is rejected", () => {
+    writeFileSync(join(root, "forge.yaml"), FORGE_YAML('  compass:\n    idPattern: "^\\\\d+$"\n'));
+    expect(() => resolveCompassPolicy(root, FORGE_ROOT)).toThrow(CompassPolicyConfigError);
+  });
+
+  it("AC-4: no consumer- or stack-specific path literals under os/compass", () => {
+    // Constructed dynamically so this test file does not itself carry the literals.
+    // Path-literal forms only — historical `@warpgogol/<pkg>` specifiers in
+    // CHANGE_SUMMARY comments are package names, not path literals.
+    const bannedPathLiterals = [
+      "apps/" + "main",
+      "DEFAULT_" + "SCAN_" + "ROOTS",
+      "werk" + "statt",
+      "packages/" + "os/",
+      "site-" + "kernel/",
+    ];
+    // AC-4 names `site-kernel` (bare) as banned inside compass-inventory.ts.
+    const bannedInInventory = [...bannedPathLiterals, "site-" + "kernel"];
+    const inventoryFile = join(COMPASS_DIR, "handlers", "compass-inventory.ts");
+
+    const offenders: string[] = [];
+    for (const file of collectTsFiles(COMPASS_DIR)) {
+      const source = readFileSync(file, "utf8");
+      const banned = file === inventoryFile ? bannedInInventory : bannedPathLiterals;
+      for (const literal of banned) {
+        if (source.includes(literal)) {
+          offenders.push(`${file}: ${literal}`);
+        }
+      }
+    }
+    expect(offenders, `banned literals found:\n${offenders.join("\n")}`).toEqual([]);
+  });
+
+  it("AC-5: highRiskPaths from bindings mark matching entries riskClass=high", async () => {
+    writeFileSync(
+      join(root, "forge.yaml"),
+      FORGE_YAML(
+        '  compass:\n    scanRoots: [packages]\n    highRiskPaths: ["packages/fixture-pkg/src/kernel/**"]\n',
+      ),
+    );
+    const fixture = join(root, "packages", "fixture-pkg", "src", "kernel");
+    mkdirSync(fixture, { recursive: true });
+    const body = Array.from({ length: 25 }, (_, i) => `export const line${i} = ${i};`).join("\n");
+    writeFileSync(
+      join(fixture, "engine.ts"),
+      `/*\n<MODULE_CONTRACT>\n<purpose>Fixture kernel engine file for the compass policy high-risk test.</purpose>\n<non-goals>\n  <item>No production logic.</item>\n</non-goals>\n</MODULE_CONTRACT>\n*/\n${body}\n`,
+    );
+
+    const result = await runCompassInventory({ flags: {} } as never, makeContext(root));
+    const entry = result.data?.entries.find((e) => e.path.endsWith("kernel/engine.ts"));
+    expect(entry, "fixture entry must be inventoried").toBeDefined();
+    expect(entry!.riskClass).toBe("high");
+    expect(result.data?.policySource.overriddenKeys).toContain("highRiskPaths");
+  });
+
+  it("excludedPaths mark matching files excluded with the configured reason", async () => {
+    writeFileSync(
+      join(root, "forge.yaml"),
+      FORGE_YAML(
+        "  compass:\n    scanRoots: [packages]\n    excludedPaths:\n      - pattern: src/templates/**\n        reason: template-source\n",
+      ),
+    );
+    const dir = join(root, "packages", "fixture-pkg", "src", "templates");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "widget.ts"), "export const t = 1;\n");
+
+    const result = await runCompassInventory({ flags: {} } as never, makeContext(root));
+    const entry = result.data?.entries.find((e) => e.path.endsWith("templates/widget.ts"));
+    expect(entry).toBeDefined();
+    expect(entry!.authoringStatus).toBe("excluded");
+    expect(entry!.exclusionReason).toBe("template-source");
+  });
+
+  it("missing forge.yaml yields the generic policy", () => {
+    const policy = resolveCompassPolicy(root, FORGE_ROOT);
+    expect(policy.source.profile).toBeNull();
+    expect(policy.source.overriddenKeys).toEqual([]);
+    expect(policy.fileExtensions.has(".ts")).toBe(true);
+    expect(policy.scanRoots).toEqual(["src", "apps", "packages", "services"]);
+    expect(policy.idPattern.test("RFC-1096")).toBe(true);
+  });
+
+  it("parseGovernanceIdParts splits on the last dash", () => {
+    expect(parseGovernanceIdParts("RFC-1095")).toEqual({ namespace: "RFC", numeric: 1095 });
+    expect(parseGovernanceIdParts("COMPASS-CS-07")).toEqual({
+      namespace: "COMPASS-CS",
+      numeric: 7,
+    });
+    expect(parseGovernanceIdParts("no-number")).toBeNull();
+  });
+});

package/os/compass/handlers/tests/compass-v2-contract.test.ts

@@ -3,7 +3,6 @@ import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { tmpdir } from "node:os";
 import { runCompassValidation, runCompassInventory } from "../compass-inventory-handler.ts";
-import { runCompassChangeSummaryValidate } from "../compass-change-summary-handler.ts";
 import type {
   ForgeCommandInput,
   ForgeCommandResult,
@@ -34,8 +33,12 @@ const MC = (purpose: string) =>
 const KD = (items: string[]) =>
   `<KEY_DECISIONS>\n${items.map((i) => `  <item>${i}</item>`).join("\n")}\n</KEY_DECISIONS>`;
 const KD_EMPTY = `<KEY_DECISIONS>\n</KEY_DECISIONS>`;
+// Dynamic tags: a literal CHANGE_SUMMARY block in this file would be matched
+// by compass.summary.record itself and rewritten at commit time.
+const CS_OPEN = "<" + "CHANGE_SUMMARY>";
+const CS_CLOSE = "</" + "CHANGE_SUMMARY>";
 const CS = (items: string[], history?: string) =>
-  `<CHANGE_SUMMARY>\n${items.map((i) => `  <item>${i}</item>`).join("\n")}${history ? `\n  <history>${history}</history>` : ""}\n</CHANGE_SUMMARY>`;
+  `${CS_OPEN}\n${items.map((i) => `  <item>${i}</item>`).join("\n")}\n${history ? `  <history>${history}</history>\n` : ""}${CS_CLOSE}`;
 const wrap = (...blocks: string[]) => `/*\n${blocks.join("\n")}\n*/`;
 
 const PURPOSE_WITH_TOKEN =
@@ -100,7 +103,8 @@ describe("compass v2 contract (RFC-1094)", () => {
     const items = [1, 2, 3, 4, 5, 6].map((n) => `RFC-10${n}0: change number ${n}.`);
     writeFixture(MEDIUM_FILE, wrap(MC(PURPOSE_WITH_TOKEN), KD([KD_ITEM]), CS(items)));
 
-    const result = await runCompassChangeSummaryValidate(makeInput(), makeContext(tempDir));
+    // RFC-1095: CS rules are covered by compass.validate via shared evaluateV2Rules.
+    const result = await runCompassValidation(makeInput(), makeContext(tempDir));
     const diag = dataOf(result).diagnostics.find((d) => d.ruleId === "COMPASS-CS-05");
     expect(diag, "CS-05 must fire when CHANGE_SUMMARY exceeds 5 items").toBeDefined();
     expect(diag!.severity).toBe("warning");
@@ -113,7 +117,7 @@ describe("compass v2 contract (RFC-1094)", () => {
       wrap(MC(PURPOSE_WITH_TOKEN), KD([KD_ITEM]), CS(["fixed a bug in the widget"])),
     );
 
-    const result = await runCompassChangeSummaryValidate(makeInput(), makeContext(tempDir));
+    const result = await runCompassValidation(makeInput(), makeContext(tempDir));
     const diag = dataOf(result).diagnostics.find((d) => d.ruleId === "COMPASS-CS-06");
     expect(diag, "CS-06 must fire for items lacking a governance ID").toBeDefined();
   });
@@ -203,7 +207,7 @@ describe("compass v2 contract (RFC-1094)", () => {
       wrap(MC(PURPOSE_WITH_TOKEN), KD([KD_ITEM]), CS([CS_ITEM], "RFC-0350, RFC-0348")),
     );
 
-    const result = await runCompassChangeSummaryValidate(makeInput(), makeContext(tempDir));
+    const result = await runCompassValidation(makeInput(), makeContext(tempDir));
     expect(
       dataOf(result).diagnostics.find((d) => d.ruleId === "COMPASS-CS-07"),
       "CS-07 must fire on descending per-namespace order",
@@ -214,13 +218,9 @@ describe("compass v2 contract (RFC-1094)", () => {
     writeFixture(MEDIUM_FILE, wrap(MC(PURPOSE_WITH_TOKEN), KD([KD_ITEM]), CS([])));
 
     const warnResult = await runCompassValidation(makeInput(), makeContext(tempDir));
-    const csResult = await runCompassChangeSummaryValidate(makeInput(), makeContext(tempDir));
     expect(
       dataOf(warnResult).diagnostics.filter((d) => d.ruleId.startsWith("COMPASS-CS-")),
     ).toHaveLength(0);
-    expect(
-      dataOf(csResult).diagnostics.filter((d) => d.ruleId.startsWith("COMPASS-CS-")),
-    ).toHaveLength(0);
   });
 
   it("fully compliant v2 file produces zero v2 diagnostics", async () => {

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

@@ -0,0 +1,224 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, mkdir, writeFile, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  runCompassSummaryRecord,
+  parseChangeSummary,
+  mergeHistoryIds,
+  buildChangeSummaryBlock,
+  stripConventionalPrefix,
+  isValidGovernanceId,
+  CHANGE_SUMMARY_WINDOW,
+} from "../summary-record.ts";
+import { resolveCompassPolicy } from "../../policy.ts";
+import type { ForgeRuntimeContext } from "../../../../src/types.ts";
+
+// Generic policy — this path has no forge.yaml, so resolution falls back to
+// GENERIC defaults.
+const policy = resolveCompassPolicy(join(tmpdir(), "summary-record-no-forge-yaml"));
+
+const logger = {
+  section() {},
+  info() {},
+  warn() {},
+  error() {},
+  success() {},
+  getEvents() {
+    return [];
+  },
+};
+
+function makeContext(workspaceRoot: string, dryRun = false): ForgeRuntimeContext {
+  return {
+    workspaceRoot,
+    logger: logger as never,
+    dryRun,
+    outputFormat: "pretty",
+  };
+}
+
+function makeInput(flags: Record<string, unknown>) {
+  return { argv: [], flags: flags as never };
+}
+
+// Dynamic tags: a literal CHANGE_SUMMARY block in this file would be matched
+// by compass.summary.record itself and rewritten at commit time.
+const CS_OPEN = "<" + "CHANGE_SUMMARY>";
+const CS_CLOSE = "</" + "CHANGE_SUMMARY>";
+const CS_BLOCK_RE = new RegExp(`${CS_OPEN}[\\s\\S]*?${CS_CLOSE}`);
+
+const TS_HEADER = (items: string[], history?: string[]) => `/*
+<MODULE_CONTRACT>
+<purpose>Test fixture file for summary record coverage.</purpose>
+<non-goals><item>No production logic.</item></non-goals>
+</MODULE_CONTRACT>
+${CS_OPEN}
+${items.map((i) => `  <item>${i}</item>`).join("\n")}
+${history && history.length > 0 ? `  <history>${history.join(", ")}</history>\n` : ""}${CS_CLOSE}
+*/
+export const x = 1;
+`;
+
+describe("compass.summary.record", () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "summary-record-"));
+    await mkdir(join(root, "src"), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it("appends an ID-prefixed item to CHANGE_SUMMARY (AC-1)", async () => {
+    await writeFile(join(root, "src", "a.ts"), TS_HEADER(["RFC-0001: existing item."]));
+    const result = await runCompassSummaryRecord(
+      makeInput({ id: "RFC-1095", files: ["src/a.ts"], text: "added record command" }),
+      makeContext(root),
+    );
+    expect(result.exitCode).toBe(0);
+    const source = await readFile(join(root, "src", "a.ts"), "utf8");
+    expect(source).toContain("<item>RFC-1095: added record command</item>");
+    expect(result.data?.recorded).toEqual(["src/a.ts"]);
+  });
+
+  it("skips duplicate items with identical ID+text (AC-2)", async () => {
+    await writeFile(join(root, "src", "a.ts"), TS_HEADER(["RFC-1095: added record command"]));
+    const result = await runCompassSummaryRecord(
+      makeInput({ id: "RFC-1095", files: ["src/a.ts"], text: "added record command" }),
+      makeContext(root),
+    );
+    expect(result.data?.skipped).toEqual([{ file: "src/a.ts", reason: "duplicate" }]);
+    expect(result.data?.recorded).toEqual([]);
+  });
+
+  it("collapses the oldest item into <history> past the 5-item window (AC-3)", async () => {
+    const items = Array.from(
+      { length: CHANGE_SUMMARY_WINDOW },
+      (_, i) => `RFC-000${i}: item ${i}.`,
+    );
+    await writeFile(join(root, "src", "a.ts"), TS_HEADER(items));
+    const result = await runCompassSummaryRecord(
+      makeInput({ id: "RFC-1095", files: ["src/a.ts"], text: "overflow item" }),
+      makeContext(root),
+    );
+    const source = await readFile(join(root, "src", "a.ts"), "utf8");
+    const parsed = parseChangeSummary(source.match(CS_BLOCK_RE)![0]);
+    expect(parsed.items).toHaveLength(CHANGE_SUMMARY_WINDOW);
+    expect(parsed.items.at(-1)).toBe("RFC-1095: overflow item");
+    expect(parsed.historyIds).toContain("RFC-0000");
+    expect(result.data?.collapsed).toEqual(["src/a.ts"]);
+  });
+
+  it("merges collapsed IDs into existing history deduped and per-namespace ascending (AC-4)", async () => {
+    const items = Array.from(
+      { length: CHANGE_SUMMARY_WINDOW },
+      (_, i) => `RFC-000${i}: item ${i}.`,
+    );
+    await writeFile(join(root, "src", "a.ts"), TS_HEADER(items, ["RFC-0000", "ADR-0002"]));
+    await runCompassSummaryRecord(
+      makeInput({ id: "RFC-1095", files: ["src/a.ts"], text: "overflow" }),
+      makeContext(root),
+    );
+    const source = await readFile(join(root, "src", "a.ts"), "utf8");
+    const parsed = parseChangeSummary(source.match(CS_BLOCK_RE)![0]);
+    // RFC-0000 deduped; ADR-0002 sorts before RFC namespace.
+    expect(parsed.historyIds).toEqual(["ADR-0002", "RFC-0000"]);
+  });
+
+  it("skips files without a CHANGE_SUMMARY block (AC-5)", async () => {
+    await writeFile(join(root, "src", "plain.ts"), "export const y = 2;\n");
+    const result = await runCompassSummaryRecord(
+      makeInput({ id: "RFC-1095", files: ["src/plain.ts"], text: "x" }),
+      makeContext(root),
+    );
+    expect(result.data?.skipped).toEqual([{ file: "src/plain.ts", reason: "no-block" }]);
+  });
+
+  it("skips missing files as unparseable without failing (AC-5)", async () => {
+    const result = await runCompassSummaryRecord(
+      makeInput({ id: "RFC-1095", files: ["src/ghost.ts"], text: "x" }),
+      makeContext(root),
+    );
+    expect(result.exitCode).toBe(0);
+    expect(result.data?.skipped).toEqual([{ file: "src/ghost.ts", reason: "unparseable" }]);
+  });
+
+  it("rejects a missing or malformed --id", async () => {
+    const bad = await runCompassSummaryRecord(
+      makeInput({ id: "not-an-id", files: ["src/a.ts"] }),
+      makeContext(root),
+    );
+    expect(bad.exitCode).toBe(1);
+    const missing = await runCompassSummaryRecord(
+      makeInput({ files: ["src/a.ts"] }),
+      makeContext(root),
+    );
+    expect(missing.exitCode).toBe(1);
+  });
+
+  it("defaults item text to the bare ID when --text is absent", async () => {
+    await writeFile(join(root, "src", "a.ts"), TS_HEADER([]));
+    await runCompassSummaryRecord(
+      makeInput({ id: "ADR-0042", files: ["src/a.ts"] }),
+      makeContext(root),
+    );
+    const source = await readFile(join(root, "src", "a.ts"), "utf8");
+    expect(source).toContain("<item>ADR-0042</item>");
+  });
+
+  it("does not write files in dry-run mode", async () => {
+    const original = TS_HEADER(["RFC-0001: existing."]);
+    await writeFile(join(root, "src", "a.ts"), original);
+    const result = await runCompassSummaryRecord(
+      makeInput({ id: "RFC-1095", files: ["src/a.ts"], text: "dry run item" }),
+      makeContext(root, true),
+    );
+    expect(result.data?.recorded).toEqual(["src/a.ts"]);
+    expect(await readFile(join(root, "src", "a.ts"), "utf8")).toBe(original);
+  });
+
+  it("strips a duplicated leading ID from --text", async () => {
+    await writeFile(join(root, "src", "a.ts"), TS_HEADER([]));
+    await runCompassSummaryRecord(
+      makeInput({ id: "RFC-1095", files: ["src/a.ts"], text: "RFC-1095 — record command" }),
+      makeContext(root),
+    );
+    const source = await readFile(join(root, "src", "a.ts"), "utf8");
+    expect(source).toContain("<item>RFC-1095: record command</item>");
+    expect(source).not.toContain("RFC-1095: RFC-1095");
+  });
+});
+
+describe("summary-record helpers", () => {
+  it("stripConventionalPrefix removes conventional commit prefixes", () => {
+    expect(stripConventionalPrefix("implement: RFC-1095 — record")).toBe("RFC-1095 — record");
+    expect(stripConventionalPrefix("fix(scope)!: bug")).toBe("bug");
+    expect(stripConventionalPrefix("plain subject")).toBe("plain subject");
+  });
+
+  it("isValidGovernanceId accepts RFC/ADR/ticket shapes only", () => {
+    expect(isValidGovernanceId("RFC-1095", policy)).toBe(true);
+    expect(isValidGovernanceId("ADR-0042", policy)).toBe(true);
+    expect(isValidGovernanceId("PROJ-123", policy)).toBe(true);
+    expect(isValidGovernanceId("rfc-1095", policy)).toBe(false);
+    expect(isValidGovernanceId("RFC1095", policy)).toBe(false);
+    expect(isValidGovernanceId("RFC-1095 extra", policy)).toBe(false);
+  });
+
+  it("mergeHistoryIds dedupes and sorts per-namespace ascending", () => {
+    expect(mergeHistoryIds(["RFC-0005"], ["RFC-0002", "ADR-0001", "RFC-0005"], policy)).toEqual([
+      "ADR-0001",
+      "RFC-0002",
+      "RFC-0005",
+    ]);
+  });
+
+  it("buildChangeSummaryBlock omits <history> when empty", () => {
+    const block = buildChangeSummaryBlock(["RFC-1: a"], [], "x.ts");
+    expect(block).not.toContain("<history>");
+    expect(block).toContain("<item>RFC-1: a</item>");
+  });
+});

package/os/compass/index.ts

@@ -7,6 +7,11 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0374: initial compass module barrel.</item>
+  <item>RFC-1095: compass.summary.record, trim repair rewrite, commit integration</item>
+  <item>RFC-1095: review findings: execFileSync git add, drop speculative barrel exports</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>
 </CHANGE_SUMMARY>
 */
 
@@ -25,9 +30,22 @@ export {
   runCompassAuditValidate,
   isAuditDue,
 } from "./handlers/compass-audit-handler.ts";
+export { runCompassSummaryTrim } from "./handlers/compass-change-summary-handler.ts";
+export { runCompassMigrate } from "./handlers/compass-migrate-handler.ts";
+export {
+  migrateFile,
+  migrateWorkspace,
+  type MigrateAction,
+  type MigrateResult,
+} from "./handlers/compass-migrate.ts";
 export {
-  runCompassChangeSummaryValidate,
-  runCompassSummaryTrim,
-  classifyChangeSummaryItem,
-  type ChangeSummaryItemClass,
-} from "./handlers/compass-change-summary-handler.ts";
+  runCompassSummaryRecord,
+  parseChangeSummary,
+  mergeHistoryIds,
+  buildChangeSummaryBlock,
+  stripConventionalPrefix,
+  isValidGovernanceId,
+  CHANGE_SUMMARY_WINDOW,
+  type SummaryRecordResult,
+  type SummaryRecordSkipReason,
+} from "./handlers/summary-record.ts";