@warpgogol/forge 4.2.4 → 5.1.1

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

@@ -0,0 +1,313 @@
+/*
+<MODULE_CONTRACT>
+<purpose>compass.summary.record — commit-time append of governance-referencing
+items to CHANGE_SUMMARY blocks per RFC-1095. Collapses the 5-item window into
+<history>, dedupes by ID+text, and reminds about KEY_DECISIONS on risk files.</purpose>
+<non-goals>
+  <item>Do not create CHANGE_SUMMARY blocks — headers are authored by fo-compass-annotate.</item>
+  <item>Do not validate semantic quality of item text — record writes what the commit declares.</item>
+  <item>Do not import @warpgogol/* packages — this handler is autonomous (FORGE-AUTONOMY-01).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<KEY_DECISIONS>
+  <item>The 5-item window collapses oldest-first into history — history holds IDs only, never prose.</item>
+  <item>Recording is header-region guarded — a CHANGE_SUMMARY deeper than 120 lines is a doc example, not a header.</item>
+  <item>Item text is sanitized on record — literal Compass tags would corrupt history parsing.</item>
+</KEY_DECISIONS>
+<CHANGE_SUMMARY>
+  <item>RFC-1095: header-region guard in summary.record, restore test fixture with dynamic tags</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-1097: sweep — packages/forge + services clean
+
+Sweep batch 2: real KEY_DECISIONS on 10 files, expanded purposes (CONTRACT-02/PURPOSE-02), headers on mission/index + gen-upstreams, sanitizeItemText in summary.record (literal Compass tags corrupted history), excludedPaths for wrangler types, test-fixtures testPattern. forge+services now 0 diagnostics under --mode error.</item>
+  <item>RFC-1097: sweep — engine package clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. engine package now 0 diagnostics.</item>
+  <item>RFC-1097: AC-4 banned literal in os/compass handlers
+
+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>
+  <history>RFC-1095</history>
+</CHANGE_SUMMARY>
+*/
+
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { resolve, relative } from "node:path";
+import { detectRiskClass, getWorkspaceRelativeSegments } from "./compass-inventory.ts";
+import { parseGovernanceIdParts, resolveCompassPolicy, type CompassPolicy } from "../policy.ts";
+import { resolveCompassScanRoot } from "./resolve-scan-root.ts";
+import { writeFileIfChanged } from "../../../src/utils/fs-idempotent.ts";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+
+const CHANGE_SUMMARY_BLOCK_RE = /<CHANGE_SUMMARY>[\s\S]*?<\/CHANGE_SUMMARY>/;
+const ITEM_RE = /<item>([\s\S]*?)<\/item>/g;
+const HISTORY_RE = /<history>([\s\S]*?)<\/history>/;
+const CONVENTIONAL_PREFIX_RE = /^[a-z]+(\([^)]*\))?!?:\s*/i;
+
+export const CHANGE_SUMMARY_WINDOW = 5;
+
+// A CHANGE_SUMMARY block is a file header only when it starts within this many
+// lines from the top. Deeper matches are examples inside template literals or
+// fenced doc sections, not headers.
+const HEADER_SCAN_LINES = 120;
+
+export interface SummaryRecordInput {
+  id: string;
+  files: string[];
+  text?: string;
+  workpiece?: string;
+}
+
+export type SummaryRecordSkipReason = "no-block" | "duplicate" | "unparseable";
+
+export interface SummaryRecordResult {
+  command: "compass.summary.record";
+  status: "pass";
+  recorded: string[];
+  collapsed: string[];
+  skipped: Array<{ file: string; reason: SummaryRecordSkipReason }>;
+  keyDecisionsReminders: string[];
+}
+
+interface ParsedChangeSummary {
+  items: string[];
+  historyIds: string[];
+}
+
+export function parseChangeSummary(block: string): ParsedChangeSummary {
+  const items: string[] = [];
+  let m: RegExpExecArray | null;
+  const re = new RegExp(ITEM_RE.source, "g");
+  while ((m = re.exec(block)) !== null) {
+    items.push(m[1]!.trim());
+  }
+  const historyMatch = block.match(HISTORY_RE);
+  const historyIds = historyMatch
+    ? historyMatch[1]!
+        .split(",")
+        .map((t) => t.trim())
+        .filter(Boolean)
+    : [];
+  return { items, historyIds };
+}
+
+function normalizeItemText(text: string): string {
+  return text.trim().replace(/\s+/g, " ");
+}
+
+function leadingGovernanceId(item: string, policy: CompassPolicy): string | null {
+  const match = item.match(policy.idPattern);
+  return match && match.index === 0 ? match[0] : null;
+}
+
+/** Merge existing + new history IDs: dedupe, per-namespace ascending numeric order. */
+export function mergeHistoryIds(
+  existing: string[],
+  incoming: string[],
+  policy: CompassPolicy,
+): string[] {
+  const all = [...new Set([...existing, ...incoming])].filter((id) =>
+    policy.idPatternFull.test(id),
+  );
+  return all.sort((a, b) => {
+    const pa = parseGovernanceIdParts(a)!;
+    const pb = parseGovernanceIdParts(b)!;
+    const ns = pa.namespace.localeCompare(pb.namespace);
+    return ns !== 0 ? ns : pa.numeric - pb.numeric;
+  });
+}
+
+export function getLineCommentPrefix(filePath: string): string | null {
+  if (filePath.endsWith(".gd")) return "# ";
+  if (filePath.endsWith(".tscn") || filePath.endsWith(".tres")) return "; ";
+  return null;
+}
+
+export function buildChangeSummaryBlock(
+  items: string[],
+  historyIds: string[],
+  filePath: string,
+): string {
+  const prefix = getLineCommentPrefix(filePath);
+  const lines = ["<CHANGE_SUMMARY>"];
+  for (const item of items) {
+    lines.push(`  <item>${item}</item>`);
+  }
+  if (historyIds.length > 0) {
+    lines.push(`  <history>${historyIds.join(", ")}</history>`);
+  }
+  lines.push("</CHANGE_SUMMARY>");
+  if (prefix) {
+    return lines.map((line, i) => (i === 0 ? line : prefix + line)).join("\n");
+  }
+  return lines.join("\n");
+}
+
+export function stripConventionalPrefix(subject: string): string {
+  return subject.replace(CONVENTIONAL_PREFIX_RE, "").trim();
+}
+
+// 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.
+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, ""));
+}
+
+export function isValidGovernanceId(id: string, policy: CompassPolicy): boolean {
+  return policy.idPatternFull.test(id);
+}
+
+interface RecordOutcome {
+  recorded: boolean;
+  collapsed: boolean;
+  skipReason?: SummaryRecordSkipReason;
+}
+
+/**
+ * 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.
+ */
+export async function recordSummaryItem(
+  absPath: string,
+  relPath: string,
+  id: string,
+  text: string,
+  dryRun: boolean,
+  policy: CompassPolicy,
+): Promise<RecordOutcome> {
+  const source = await readFile(absPath, "utf8");
+  const blockMatch = source.match(CHANGE_SUMMARY_BLOCK_RE);
+  // Header-region guard: a CHANGE_SUMMARY is a header only when it sits at the
+  // top of the file. Blocks deeper in the source are examples inside template
+  // literals or fenced doc sections — recording into them corrupts the file.
+  const inHeaderRegion =
+    blockMatch !== null &&
+    blockMatch.index !== undefined &&
+    source.slice(0, blockMatch.index).split("\n").length <= HEADER_SCAN_LINES;
+  if (!blockMatch || !inHeaderRegion) {
+    return {
+      recorded: false,
+      collapsed: false,
+      skipReason: source.includes("<CHANGE_SUMMARY>") ? "unparseable" : "no-block",
+    };
+  }
+
+  const { items, historyIds } = parseChangeSummary(blockMatch[0]);
+  // Avoid "RFC-1095: RFC-1095 ..." when the text already leads with the same ID;
+  // a text equal to the bare ID collapses to the bare-ID item form.
+  const strippedText = text.startsWith(id)
+    ? text.slice(id.length).replace(/^\s*[:—-]?\s*/, "")
+    : text;
+  const newItem = strippedText.length > 0 ? `${id}: ${sanitizeItemText(strippedText)}` : id;
+  const normalizedNew = normalizeItemText(newItem);
+  if (items.some((item) => normalizeItemText(item) === normalizedNew)) {
+    return { recorded: false, collapsed: false, skipReason: "duplicate" };
+  }
+
+  const nextItems = [...items, newItem];
+  const collapsedIds: string[] = [];
+  while (nextItems.length > CHANGE_SUMMARY_WINDOW) {
+    const oldest = nextItems.shift()!;
+    const oldId = leadingGovernanceId(oldest, policy);
+    if (oldId) collapsedIds.push(oldId);
+  }
+  const collapsed = collapsedIds.length > 0;
+  const nextHistory = mergeHistoryIds(historyIds, collapsedIds, policy);
+
+  const newBlock = buildChangeSummaryBlock(nextItems, nextHistory, relPath);
+  const transformed = source.replace(CHANGE_SUMMARY_BLOCK_RE, newBlock);
+  if (!dryRun && transformed !== source) {
+    await writeFileIfChanged(absPath, transformed);
+  }
+  return { recorded: true, collapsed };
+}
+
+function riskReminderNeeded(relPath: string, source: string, policy: CompassPolicy): boolean {
+  const segments = relPath.split("/").filter(Boolean);
+  const workspaceRel = getWorkspaceRelativeSegments(segments, policy).join("/");
+  const risk = detectRiskClass(relPath, workspaceRel, policy);
+  return risk === "medium" || risk === "high" || source.includes("<KEY_DECISIONS>");
+}
+
+export async function runCompassSummaryRecord(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<SummaryRecordResult>> {
+  const scanRoot = resolveCompassScanRoot(input, context);
+  const baseRoot = scanRoot ?? context.workspaceRoot;
+  const policy = resolveCompassPolicy(baseRoot, context.forgeRoot);
+
+  const id = input.flags["id"];
+  if (typeof id !== "string" || !isValidGovernanceId(id, policy)) {
+    context.logger.error(
+      `[compass.summary.record] --id is required and must be a governance ID (e.g. RFC-1095), got: ${String(id)}`,
+    );
+    return { exitCode: 1, summary: "invalid or missing --id" };
+  }
+
+  const rawFiles = input.flags["files"];
+  const files = Array.isArray(rawFiles)
+    ? rawFiles
+    : typeof rawFiles === "string"
+      ? rawFiles.split(/\s+/).filter(Boolean)
+      : [];
+
+  const rawText = input.flags["text"];
+  const text = typeof rawText === "string" && rawText.trim().length > 0 ? rawText.trim() : id;
+
+  const result: SummaryRecordResult = {
+    command: "compass.summary.record",
+    status: "pass",
+    recorded: [],
+    collapsed: [],
+    skipped: [],
+    keyDecisionsReminders: [],
+  };
+
+  for (const file of files) {
+    const absPath = resolve(baseRoot, file);
+    const relPath = relative(baseRoot, absPath).replace(/\\/g, "/");
+    if (!existsSync(absPath)) {
+      result.skipped.push({ file, reason: "unparseable" });
+      context.logger.warn(`[compass.summary.record] skipped ${file}: file not found`);
+      continue;
+    }
+    try {
+      const outcome = await recordSummaryItem(absPath, relPath, id, text, context.dryRun, policy);
+      if (outcome.skipReason) {
+        result.skipped.push({ file, reason: outcome.skipReason });
+        continue;
+      }
+      if (outcome.recorded) {
+        result.recorded.push(relPath);
+        if (outcome.collapsed) result.collapsed.push(relPath);
+        const source = await readFile(absPath, "utf8");
+        if (riskReminderNeeded(relPath, source, policy)) {
+          result.keyDecisionsReminders.push(relPath);
+          context.logger.warn(`[compass.summary.record] review KEY_DECISIONS in ${relPath}`);
+        }
+      }
+    } catch (err) {
+      result.skipped.push({ file, reason: "unparseable" });
+      context.logger.warn(
+        `[compass.summary.record] skipped ${file}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  return {
+    data: result,
+    exitCode: 0,
+    summary: `[compass.summary.record] recorded=${result.recorded.length}, collapsed=${result.collapsed.length}, skipped=${result.skipped.length}`,
+  };
+}

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

@@ -0,0 +1,291 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { migrateFile, type MigrateAction } from "../compass-migrate.ts";
+import { runCompassMigrate } from "../compass-migrate-handler.ts";
+import { resolveCompassPolicy, type CompassPolicy } from "../../policy.ts";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../../src/types.ts";
+
+function dataOf<T>(result: ForgeCommandResult<T>): T {
+  if (!result.data) throw new Error("command returned no data payload");
+  return result.data;
+}
+
+function makeContext(workspaceRoot: string, dryRun = false): ForgeRuntimeContext {
+  return {
+    workspaceRoot,
+    site: undefined,
+    siteExplicit: false,
+    dryRun,
+    logger: { info: () => {}, warn: () => {}, error: () => {} },
+  } as unknown as ForgeRuntimeContext;
+}
+
+function makeInput(flags: Record<string, unknown> = {}): ForgeCommandInput {
+  return { flags } as ForgeCommandInput;
+}
+
+// Dynamic tags: literal CHANGE_SUMMARY blocks 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 MC = (purpose: string) =>
+  `<MODULE_CONTRACT>\n<purpose>${purpose}</purpose>\n<non-goals>\n  <item>Do not perform real validation — fixtures only.</item>\n</non-goals>\n</MODULE_CONTRACT>`;
+const KD = (items: string[]) =>
+  `<KEY_DECISIONS>\n${items.map((i) => `  <item>${i}</item>`).join("\n")}\n</KEY_DECISIONS>`;
+const CS = (items: string[], history?: string) =>
+  `${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 = "Validates mission widget fixtures for the compass migrate test suite.";
+const KD_ITEM = "Fixtures live in a temp workspace so tests never touch the real repository.";
+
+// Medium-risk: packages/<pkg>/src/components/** → workspace-relative src/components/** → layer component.
+const MEDIUM_ROOT = "packages/fixture-pkg/src/components/mission-widget.ts";
+const MEDIUM_WS = "src/components/mission-widget.ts";
+// Low-risk: bare src/** → layer source.
+const LOW_ROOT = "packages/fixture-pkg/src/mission-notes.ts";
+const LOW_WS = "src/mission-notes.ts";
+
+const BODY = Array.from({ length: 25 }, (_, i) => `export const fixtureLine${i} = ${i};`).join(
+  "\n",
+);
+
+let policy: CompassPolicy;
+
+function migrate(source: string, root = MEDIUM_ROOT, ws = MEDIUM_WS) {
+  return migrateFile(`${source}\n\n${BODY}\n`, policy, root, ws);
+}
+
+describe("compass.migrate codemod (RFC-1097)", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "compass-migrate-test-"));
+    policy = resolveCompassPolicy(tempDir);
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("no-header: file without any Compass block is skipped", () => {
+    const result = migrateFile(`export const x = 1;\n`, policy, MEDIUM_ROOT, MEDIUM_WS);
+    expect(result.actions).toEqual(["no-header"]);
+    expect(result.source).toBe("export const x = 1;\n");
+  });
+
+  it("unparseable: open tag without close is skipped", () => {
+    const broken = `/*\n<MODULE_CONTRACT>\n<purpose>${PURPOSE}</purpose>\n`;
+    const result = migrateFile(broken, policy, MEDIUM_ROOT, MEDIUM_WS);
+    expect(result.actions).toEqual(["unparseable"]);
+    expect(result.source).toBe(broken);
+  });
+
+  it("collapsed: 8 items keep newest 5, overflow IDs merge into sorted history, ID-less items drop", () => {
+    const items = [
+      "RFC-1001: first.",
+      "no-id item that must be dropped.",
+      "RFC-1002: second.",
+      "RFC-1003: third.",
+      "RFC-1004: fourth.",
+      "RFC-1005: fifth.",
+      "RFC-1006: sixth.",
+      "RFC-1007: seventh.",
+      "RFC-1008: eighth.",
+    ];
+    const result = migrate(wrap(MC(PURPOSE), KD([KD_ITEM]), CS(items, "ADR-0001, RFC-0999")));
+    expect(result.actions).toContain("collapsed");
+    const csBlock = result.source.match(
+      new RegExp(
+        `${CS_OPEN.replace(/[<>]/g, "\\$&")}[\\s\\S]*?${CS_CLOSE.replace(/[<>/]/g, "\\$&")}`,
+      ),
+    );
+    const kept = csBlock?.[0].match(/<item>([^<]+)<\/item>/g) ?? [];
+    // 5 newest CS items survive inside the block.
+    expect(kept.length).toBe(5);
+    expect(result.source).toContain("RFC-1008: eighth.");
+    expect(result.source).not.toContain("no-id item");
+    const historyMatch = result.source.match(/<history>([^<]+)<\/history>/);
+    expect(historyMatch, "collapsed IDs must land in history").toBeTruthy();
+    expect(historyMatch![1]).toBe("ADR-0001, RFC-0999, RFC-1001, RFC-1002, RFC-1003");
+  });
+
+  it("stripped: MODULE_MAP, keywords, responsibilities and COMPASS_BLOCK anchors are removed", () => {
+    const mm = "<" + "MODULE_MAP" + ">\n  <item>x</item>\n</" + "MODULE_MAP" + ">";
+    const kw = "<keywords>a, b</keywords>";
+    const resp = "<responsibilities>\n  <item>y</item>\n</responsibilities>";
+    const anchorOpen = "<" + "COMPASS_BLOCK" + ">";
+    const anchorClose = "</" + "COMPASS_BLOCK" + ">";
+    const source = wrap(
+      anchorOpen,
+      MC(PURPOSE),
+      mm,
+      kw,
+      resp,
+      KD([KD_ITEM]),
+      CS(["RFC-1094: fixture."]),
+      anchorClose,
+    );
+    const result = migrate(source);
+    expect(result.actions).toContain("stripped");
+    expect(result.source).not.toContain("MODULE_MAP");
+    expect(result.source).not.toContain("keywords");
+    expect(result.source).not.toContain("responsibilities");
+    expect(result.source).not.toContain("COMPASS_BLOCK");
+  });
+
+  it("reordered: KEY_DECISIONS after CHANGE_SUMMARY moves to canonical order", () => {
+    const result = migrate(wrap(MC(PURPOSE), CS(["RFC-1094: fixture."]), KD([KD_ITEM])));
+    expect(result.actions).toContain("reordered");
+    const mcIdx = result.source.indexOf("<MODULE_CONTRACT>");
+    const kdIdx = result.source.indexOf("<KEY_DECISIONS>");
+    const csIdx = result.source.indexOf(CS_OPEN);
+    expect(mcIdx).toBeLessThan(kdIdx);
+    expect(kdIdx).toBeLessThan(csIdx);
+  });
+
+  it("seeded: medium-risk file with @ai-invariant comments gets real KEY_DECISIONS, ID prefix stripped", () => {
+    const source = `${wrap(MC(PURPOSE), CS(["RFC-1094: fixture."]))}\n// @ai-invariant RFC-0020: Widget tokens must stay deterministic.\n// @ai-invariant Widget tokens must stay deterministic.\n\n${BODY}\n`;
+    const result = migrateFile(source, policy, MEDIUM_ROOT, MEDIUM_WS);
+    expect(result.actions).toContain("seeded");
+    const kdMatch = result.source.match(/<KEY_DECISIONS>([\s\S]*?)<\/KEY_DECISIONS>/);
+    expect(kdMatch, "seeded file must carry a KEY_DECISIONS block").toBeTruthy();
+    expect(kdMatch![1]).toContain("Widget tokens must stay deterministic.");
+    // Deduped (two identical invariants → one item) and ID prefix stripped (KD-05).
+    expect(kdMatch![1]).not.toContain("RFC-0020");
+    expect((kdMatch![1].match(/<item>/g) ?? []).length).toBe(1);
+  });
+
+  it("todo: medium-risk file without @ai-invariant gets the TODO placeholder", () => {
+    const result = migrate(wrap(MC(PURPOSE), CS(["RFC-1094: fixture."])));
+    expect(result.actions).toContain("todo");
+    expect(result.source).toContain("TODO: record current design decisions");
+  });
+
+  it("low-risk file without KEY_DECISIONS is not seeded", () => {
+    const result = migrateFile(
+      `${wrap(MC(PURPOSE), CS(["RFC-1094: fixture."]))}\n\n${BODY}\n`,
+      policy,
+      LOW_ROOT,
+      LOW_WS,
+    );
+    expect(result.actions).not.toContain("seeded");
+    expect(result.actions).not.toContain("todo");
+    expect(result.source).not.toContain("<KEY_DECISIONS>");
+  });
+
+  it("purpose-flagged: boilerplate purpose is reported without rewriting", () => {
+    const result = migrate(
+      wrap(
+        MC("This file provides various reusable capabilities for the wider workspace ecosystem."),
+        KD([KD_ITEM]),
+        CS(["RFC-1094: fixture."]),
+      ),
+    );
+    expect(result.actions).toEqual(["purpose-flagged"]);
+  });
+
+  it("unchanged: fully compliant v2 file reports unchanged and is idempotent", () => {
+    const v2 = wrap(MC(PURPOSE), KD([KD_ITEM]), CS(["RFC-1094: fixture."], "RFC-0348"));
+    const first = migrate(v2);
+    expect(first.actions).toEqual(["unchanged"]);
+    const second = migrateFile(first.source, policy, MEDIUM_ROOT, MEDIUM_WS);
+    expect(second.actions).toEqual(["unchanged"]);
+    expect(second.source).toBe(first.source);
+  });
+
+  it("idempotent: a migrated file migrates to unchanged on the second pass", () => {
+    const items = Array.from({ length: 8 }, (_, i) => `RFC-100${i}: item ${i}.`);
+    const first = migrate(wrap(MC(PURPOSE), CS(items)));
+    expect(first.actions.length).toBeGreaterThan(0);
+    const second = migrateFile(first.source, policy, MEDIUM_ROOT, MEDIUM_WS);
+    expect(
+      second.actions,
+      `second pass must be a no-op, got ${JSON.stringify(second.actions)}`,
+    ).toEqual(["unchanged"]);
+  });
+});
+
+describe("runCompassMigrate handler (RFC-1097)", () => {
+  let tempDir: string;
+
+  function git(...args: string[]): void {
+    execFileSync("git", args, { cwd: tempDir, stdio: "ignore", timeout: 10000 });
+  }
+
+  function writeFixture(relPath: string, header: string): void {
+    const abs = join(tempDir, relPath);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, `${header}\n\n${BODY}\n`);
+  }
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "compass-migrate-handler-"));
+    policy = resolveCompassPolicy(tempDir);
+    git("init", "-q");
+    git("config", "user.email", "test@test.com");
+    git("config", "user.name", "Test");
+    git("commit", "-q", "--allow-empty", "-m", "init");
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("refuses a dirty git tree without --force and lists dirty paths", async () => {
+    writeFixture(MEDIUM_ROOT, wrap(MC(PURPOSE), CS(["RFC-1094: fixture."])));
+
+    const result = await runCompassMigrate(makeInput(), makeContext(tempDir));
+    expect(result.exitCode).toBe(1);
+    expect(result.summary).toContain("dirty");
+  });
+
+  it("--force overrides the dirty-tree refusal", async () => {
+    writeFixture(MEDIUM_ROOT, wrap(MC(PURPOSE), CS(["RFC-1094: fixture."])));
+
+    const result = await runCompassMigrate(makeInput({ force: true }), makeContext(tempDir));
+    expect(result.exitCode).toBe(0);
+    const data = dataOf(result);
+    expect(data.scanned).toBeGreaterThan(0);
+  });
+
+  it("dry-run reports actions without writing", async () => {
+    const items = Array.from({ length: 8 }, (_, i) => `RFC-100${i}: item ${i}.`);
+    writeFixture(MEDIUM_ROOT, wrap(MC(PURPOSE), KD([KD_ITEM]), CS(items)));
+    git("add", "-A");
+    git("commit", "-q", "-m", "fixture");
+
+    const before = (await import("node:fs/promises")).readFile;
+    const original = await before(join(tempDir, MEDIUM_ROOT), "utf8");
+    const result = await runCompassMigrate(makeInput({ "dry-run": true }), makeContext(tempDir));
+    expect(result.exitCode).toBe(0);
+    const data = dataOf(result);
+    const entry = data.files.find((f) => f.path === MEDIUM_ROOT);
+    expect(entry?.actions).toContain("collapsed");
+    const after = await before(join(tempDir, MEDIUM_ROOT), "utf8");
+    expect(after, "dry-run must not write").toBe(original);
+  });
+
+  it("--files bypasses scan roots and processes the explicit list", async () => {
+    const outside = "custom-dir/widget.ts";
+    writeFixture(outside, wrap(MC(PURPOSE), CS(["RFC-1094: fixture."])));
+    git("add", "-A");
+    git("commit", "-q", "-m", "fixture");
+
+    const result = await runCompassMigrate(makeInput({ files: [outside] }), makeContext(tempDir));
+    expect(result.exitCode).toBe(0);
+    const data = dataOf(result);
+    expect(data.files).toHaveLength(1);
+    expect(data.files[0]!.path).toBe(outside);
+    const actions: MigrateAction[] = data.files[0]!.actions;
+    // custom-dir/widget.ts is low-risk (no layer match) → no seeding, v1 file is already clean.
+    expect(actions).toEqual(["unchanged"]);
+  });
+});