@warpgogol/forge 4.2.4 → 5.1.1

package/os/compass/handlers/compass-inventory.ts

@@ -1,7 +1,7 @@
 /*
 <MODULE_CONTRACT>
-<purpose>Canonical Compass inventory scanning logic. Moved from @warpgogol/site-kernel
-to @warpgogol/forge for full autonomous mode (RFC-0556). Provides file collection,
+<purpose>Canonical Compass inventory scanning logic. Moved from the legacy site
+kernel package to @warpgogol/forge for full autonomous mode (RFC-0556). Provides file collection,
 workspace detection, layer classification, risk assessment, and compliance checking
 for Compass source-file inventory.</purpose>
 <non-goals>
@@ -9,82 +9,37 @@ for Compass source-file inventory.</purpose>
   <item>Do not register commands — this is a pure utility module.</item>
 </non-goals>
 </MODULE_CONTRACT>
+<KEY_DECISIONS>
+  <item>Authoring status is classified before compliance — generated, test, and excluded files never reach rule evaluation.</item>
+  <item>Risk class derives from layer rules plus high-risk globs — KEY_DECISIONS is required only on medium and high.</item>
+  <item>Policy literals come from resolveCompassPolicy — no stack- or consumer-specific values live in this module.</item>
+</KEY_DECISIONS>
 <CHANGE_SUMMARY>
-  <item>RFC-0348: collapsed to two-block contract (MODULE_CONTRACT + CHANGE_SUMMARY); removed MODULE_MAP, keywords, responsibilities, COMPASS_BLOCK anchors; coverage modes collapsed to standard/none.</item>
-  <item>Post-refactor hardening: exclude src/templates generation inputs from authored Compass requirements.</item>
-  <item>Post-refactor hardening: detect nested packages/os workspaces before deriving Compass layer and workspace name.</item>
-  <item>RFC-0556: moved canonical implementation from @warpgogol/site-kernel to @warpgogol/forge for autonomous mode.</item>
-  <item>Game extensions: added .cs, .tscn, .tres, .gd to SOURCE_EXTENSIONS; createCompassInventoryEntries now reads forge.yaml compass.fileExtensions at runtime and merges with hardcoded set.</item>
-  <item>Added .md to SOURCE_EXTENSIONS for SKILL.md Compass coverage; detectAuthoringStatus excludes non-SKILL.md markdown files.</item>
   <item>RFC-1094: v2 contract — KEY_DECISIONS/history parsing, new inventory fields, evaluateV2Rules, deriveFileTokens, resolveCompassMode, shared GOVERNANCE_ID_RE.</item>
+  <item>RFC-1095: compass.summary.record, trim repair rewrite, commit integration</item>
+  <item>RFC-1096: all policy literals externalized to resolveCompassPolicy — scan roots, extensions, ignored dirs/paths, layer/risk rules, governance-ID and boilerplate patterns come from generic defaults + profile + bindings.compass.</item>
+  <item>RFC-1097: sweep — SKILL.md headers + classification fixes
+
+Sweep batch 1: add Compass v2 headers to 45 SKILL.md files (purpose derived from frontmatter description). Fix non-skill-markdown exclusion to check filename not workspace-relative path (packages/AGENTS.md escaped it). Add .coverage to ignoredDirs.</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>
+  <history>RFC-0348, RFC-0556</history>
 </CHANGE_SUMMARY>
 */
 
 import { readdir, readFile } from "node:fs/promises";
-import { readFileSync, existsSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
-import { parse as parseYaml } from "yaml";
 import type { ForgeCommandInput } from "../../../src/types.ts";
 import { hasGeneratedMarker } from "../../../src/utils/generated-marker.ts";
+import {
+  parseGovernanceIdParts,
+  resolveCompassPolicy,
+  type CompassPolicy,
+  type CompassRiskClass,
+  type CompassWorkspaceKind,
+} from "../policy.ts";
 
-function loadCompassExtensionsFromForgeYaml(workspaceRoot: string): Set<string> {
-  const forgeYamlPath = join(workspaceRoot, "forge.yaml");
-  if (!existsSync(forgeYamlPath)) {
-    return new Set();
-  }
-  try {
-    const raw = readFileSync(forgeYamlPath, "utf8");
-    const parsed = parseYaml(raw) as Record<string, unknown> | null;
-    const bindings = parsed?.bindings as Record<string, unknown> | undefined;
-    const compass = bindings?.compass as Record<string, unknown> | undefined;
-    const extensions = compass?.fileExtensions;
-    if (Array.isArray(extensions)) {
-      return new Set(extensions.filter((e: unknown) => typeof e === "string"));
-    }
-  } catch {
-    // forge.yaml not parseable or missing compass section — fall back to hardcoded set
-  }
-  return new Set();
-}
-
-const SOURCE_EXTENSIONS = new Set([
-  ".ts",
-  ".tsx",
-  ".astro",
-  ".js",
-  ".jsx",
-  ".mjs",
-  ".mts",
-  ".css",
-  ".cs",
-  ".tscn",
-  ".tres",
-  ".gd",
-  ".md",
-]);
-const IGNORED_DIRECTORY_NAMES = new Set([
-  ".git",
-  ".turbo",
-  ".astro",
-  ".wrangler",
-  ".vscode",
-  ".cache",
-  "coverage",
-  "dist",
-  "node_modules",
-  "spec",
-  "todo",
-]);
-const DEFAULT_SCAN_ROOTS = ["apps", "packages", "services"];
-const HIGH_RISK_EXACT_RELATIVE_PATHS = new Set([
-  "apps/main/src/content/config.ts",
-  "apps/main/src/middleware.ts",
-  "packages/os/site-kernel/src/cli/index.ts",
-  "packages/os/site-kernel/src/discovery.ts",
-  "packages/os/site-kernel/src/registry.ts",
-  "packages/os/site-kernel/src/runtime.ts",
-  "packages/os/site-kernel/src/types.ts",
-]);
 function forbiddenMarkerPattern(tagName: string): RegExp {
   return new RegExp(`<${tagName}\\b`);
 }
@@ -96,12 +51,7 @@ const FORBIDDEN_PATTERNS: Array<{ name: string; regex: RegExp }> = [
   { name: "COMPASS_BLOCK", regex: new RegExp(`</?${"COMPASS_BLOCK"}\\b`) },
 ];
 
-// RFC-1094: v2 contract constants. GOVERNANCE_ID_RE is the canonical
-// governance-ID pattern shared with the change-summary handler.
-export const GOVERNANCE_ID_RE = /\b([A-Z][A-Z0-9]*-)+\d+\b/;
-const GOVERNANCE_ID_PREFIX_RE = /^([A-Z][A-Z0-9]*-)+\d+\b/;
-const HISTORY_ID_RE = /^([A-Z][A-Z0-9]*-)+\d+$/;
-const HISTORY_ID_PARTS_RE = /^(([A-Z][A-Z0-9]*-)+)(\d+)$/;
+// RFC-1096: governance-ID regexes are policy-derived (policy.idPattern*).
 const TODO_PLACEHOLDER_RE = /^TODO\b/i;
 
 const GENERIC_STEMS = new Set([
@@ -120,12 +70,6 @@ const SYMBOL_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".mts"]
 const EXPORTED_SYMBOL_RE =
   /export\s+(?:async\s+)?(?:function|const|let|class|interface|type|enum)\s+(\w+)/g;
 
-const PURPOSE_BOILERPLATE_PATTERNS: RegExp[] = [
-  /^(this file|the file|a file|this module|a module)\b/i,
-  /^(utility|utilities|helper|helpers|misc)\b/i,
-  /^(todo|placeholder|fixme)\b/i,
-];
-
 const KEY_DECISIONS_MAX_ITEMS = 7;
 const KEY_DECISIONS_MAX_WORDS = 20;
 const CHANGE_SUMMARY_MAX_ITEMS = 5;
@@ -145,8 +89,6 @@ export function resolveCompassMode(input: ForgeCommandInput): CompassValidationM
   throw new Error(`--mode must be "warning" or "error", got "${String(raw)}"`);
 }
 
-type CompassWorkspaceKind = "app" | "package" | "service";
-type CompassRiskClass = "high" | "medium" | "low";
 type CompassComplexity = "non-trivial" | "trivial";
 type CompassScaffoldingMode = "standard" | "none";
 type CompassAuthoringStatus = "authored" | "excluded";
@@ -186,45 +128,33 @@ function getFlagValues(input: ForgeCommandInput, key: string): string[] {
   return typeof value === "string" ? [value] : [];
 }
 
-function resolveScanRoots(workspaceRoot: string, input: ForgeCommandInput): string[] {
+function resolveScanRoots(
+  workspaceRoot: string,
+  input: ForgeCommandInput,
+  policy: CompassPolicy,
+): string[] {
   const values = getFlagValues(input, "root");
-  const roots = values.length > 0 ? values : DEFAULT_SCAN_ROOTS;
+  const roots = values.length > 0 ? values : policy.scanRoots;
   return roots.map((value) => resolve(workspaceRoot, value));
 }
 
-function shouldIgnoreDirectory(name: string): boolean {
-  if (IGNORED_DIRECTORY_NAMES.has(name)) {
+function shouldIgnoreDirectory(name: string, policy: CompassPolicy): boolean {
+  if (policy.ignoredDirs.has(name)) {
     return true;
   }
-  if (name.startsWith("old-")) {
-    return true;
-  }
-  if (name.startsWith("-")) {
-    return true;
-  }
-  return false;
+  return policy.ignoredDirPrefixes.some((prefix) => name.startsWith(prefix));
 }
 
-function hasRelevantExtension(filePath: string, extraExtensions?: Set<string>): boolean {
-  for (const extension of SOURCE_EXTENSIONS) {
+function hasRelevantExtension(filePath: string, policy: CompassPolicy): boolean {
+  for (const extension of policy.fileExtensions) {
     if (filePath.endsWith(extension)) {
       return true;
     }
   }
-  if (extraExtensions) {
-    for (const extension of extraExtensions) {
-      if (filePath.endsWith(extension)) {
-        return true;
-      }
-    }
-  }
   return false;
 }
 
-async function collectSourceFiles(
-  targetPath: string,
-  extraExtensions?: Set<string>,
-): Promise<string[]> {
+async function collectSourceFiles(targetPath: string, policy: CompassPolicy): Promise<string[]> {
   let stat;
   try {
     const { stat: fsStat } = await import("node:fs/promises");
@@ -234,7 +164,7 @@ async function collectSourceFiles(
   }
 
   if (stat.isFile()) {
-    return hasRelevantExtension(targetPath, extraExtensions) ? [targetPath] : [];
+    return hasRelevantExtension(targetPath, policy) ? [targetPath] : [];
   }
 
   let entries;
@@ -249,25 +179,15 @@ async function collectSourceFiles(
     const absolutePath = join(targetPath, entry.name);
 
     if (entry.isDirectory()) {
-      if (shouldIgnoreDirectory(entry.name)) {
+      if (shouldIgnoreDirectory(entry.name, policy)) {
         continue;
       }
 
-      const normalizedPath = absolutePath.replace(/\\/g, "/");
-      if (
-        normalizedPath.endsWith("/src/assets") ||
-        normalizedPath.endsWith("/src/icons/gen") ||
-        normalizedPath.includes("/public/_video") ||
-        normalizedPath.includes("/public/_img")
-      ) {
-        continue;
-      }
-
-      files.push(...(await collectSourceFiles(absolutePath, extraExtensions)));
+      files.push(...(await collectSourceFiles(absolutePath, policy)));
       continue;
     }
 
-    if (entry.isFile() && hasRelevantExtension(absolutePath, extraExtensions)) {
+    if (entry.isFile() && hasRelevantExtension(absolutePath, policy)) {
       files.push(absolutePath);
     }
   }
@@ -275,77 +195,48 @@ async function collectSourceFiles(
   return files;
 }
 
-function getRelativeSegments(filePath: string, workspaceRoot: string): string[] {
+export function getRelativeSegments(filePath: string, workspaceRoot: string): string[] {
   return relative(workspaceRoot, filePath).replace(/\\/g, "/").split("/").filter(Boolean);
 }
 
-function detectWorkspaceKind(segments: string[]): CompassWorkspaceKind {
-  if (segments[0] === "services") return "service";
-  return segments[0] === "packages" ? "package" : "app";
+function isWorkspaceDir(segment: string | undefined, policy: CompassPolicy): boolean {
+  return segment !== undefined && segment in policy.workspaceKinds;
 }
 
-function detectWorkspaceName(segments: string[]): string {
-  if (segments[0] === "packages" && segments[1] === "os") {
-    return segments[2] ?? "unknown";
-  }
-  return segments[1] ?? "unknown";
+function detectWorkspaceKind(segments: string[], policy: CompassPolicy): CompassWorkspaceKind {
+  const first = segments[0];
+  return (first !== undefined && policy.workspaceKinds[first]) || "app";
 }
 
-function getWorkspaceRelativeSegments(segments: string[]): string[] {
-  if (segments[0] === "packages" && segments[1] === "os") {
-    return segments.slice(3);
+function detectWorkspaceName(segments: string[], policy: CompassPolicy): string {
+  if (isWorkspaceDir(segments[0], policy)) {
+    return segments[1] ?? "unknown";
   }
-  return segments.slice(2);
+  // Files outside any workspace dir (e.g. tools/*) report "root" rather than
+  // leaking a filename into the workspace-name slot.
+  return "root";
 }
 
-function detectLayer(relativePath: string): string {
-  if (relativePath.startsWith("bin/")) return "bin";
-  if (relativePath === "tools/kernel.config.ts") return "tool-config";
-  if (relativePath.startsWith("tools/modules/")) return "tool-module";
-  if (relativePath.startsWith("tools/runtime/")) return "tool-runtime";
-  if (relativePath.startsWith("src/middleware/")) return "middleware";
-  if (relativePath === "src/middleware.ts") return "middleware";
-  if (relativePath.startsWith("src/pages/")) return "page";
-  if (relativePath.startsWith("src/components/")) return "component";
-  if (relativePath.startsWith("src/content/schemas/")) return "schema";
-  if (relativePath.startsWith("src/content/")) return "content";
-  if (relativePath.startsWith("src/styles/")) return "style";
-  if (relativePath.startsWith("src/scripts/")) return "script";
-  if (relativePath.startsWith("src/layouts/")) return "layout";
-  if (relativePath.startsWith("src/utils/")) return "utility";
-  if (relativePath.startsWith("src/configure/")) return "config";
-  if (
-    relativePath.startsWith("test/") ||
-    relativePath.startsWith("src/tests/") ||
-    relativePath.endsWith(".test.ts") ||
-    relativePath.endsWith(".spec.ts")
-  )
-    return "test";
-  if (relativePath.startsWith("src/")) return "source";
-  if (relativePath.endsWith("SKILL.md")) return "skill";
-  return "other";
-}
-
-function detectRiskClass(pathFromRoot: string, layer: string): CompassRiskClass {
-  if (HIGH_RISK_EXACT_RELATIVE_PATHS.has(pathFromRoot)) {
-    return "high";
-  }
-  if (pathFromRoot.includes("/src/scripts/layout-scroll/")) {
-    return "high";
-  }
-  if (pathFromRoot.includes("/src/layouts/")) {
-    return "high";
+export function getWorkspaceRelativeSegments(segments: string[], policy: CompassPolicy): string[] {
+  if (isWorkspaceDir(segments[0], policy)) {
+    return segments.slice(2);
   }
-  if (pathFromRoot.includes("/src/middleware/")) {
+  return segments;
+}
+
+export function detectLayer(relativePath: string, policy: CompassPolicy): string {
+  return policy.matchLayer(relativePath)?.layer ?? "other";
+}
+
+export function detectRiskClass(
+  pathFromRoot: string,
+  workspaceRelativePath: string,
+  policy: CompassPolicy,
+): CompassRiskClass {
+  if (policy.isHighRisk(pathFromRoot)) {
     return "high";
   }
-  if (layer === "tool-runtime" || layer === "tool-config" || layer === "schema") {
-    return "medium";
-  }
-  if (layer === "page" || layer === "component" || layer === "utility" || layer === "script") {
-    return "medium";
-  }
-  return "low";
+  return policy.matchLayer(workspaceRelativePath)?.risk ?? "low";
 }
 
 function detectComplexity(source: string): CompassComplexity {
@@ -356,20 +247,11 @@ function detectComplexity(source: string): CompassComplexity {
   return "non-trivial";
 }
 
-function isSimpleSvgLogoComponent(segments: string[]): boolean {
-  return (
-    segments.length >= 4 &&
-    segments[0] === "apps" &&
-    segments[2] === "src" &&
-    segments[3] === "components" &&
-    segments[4] === "logo"
-  );
-}
-
 function detectAuthoringStatus(
   segments: string[],
   relativePath: string,
   source: string,
+  policy: CompassPolicy,
 ): {
   authoringStatus: CompassAuthoringStatus;
   exclusionReason?: string;
@@ -381,24 +263,11 @@ function detectAuthoringStatus(
     };
   }
 
-  if (relativePath.startsWith("src/icons/gen/")) {
+  const policyExclusion = policy.excludedReason(relativePath);
+  if (policyExclusion !== undefined) {
     return {
       authoringStatus: "excluded",
-      exclusionReason: "generated-icon-tree",
-    };
-  }
-
-  if (relativePath.startsWith("src/assets/")) {
-    return {
-      authoringStatus: "excluded",
-      exclusionReason: "assets-directory",
-    };
-  }
-
-  if (isSimpleSvgLogoComponent(segments)) {
-    return {
-      authoringStatus: "excluded",
-      exclusionReason: "svg-component",
+      exclusionReason: policyExclusion,
     };
   }
 
@@ -416,20 +285,7 @@ function detectAuthoringStatus(
     };
   }
 
-  if (relativePath.startsWith("src/templates/")) {
-    return {
-      authoringStatus: "excluded",
-      exclusionReason: "template-source",
-    };
-  }
-
-  if (
-    relativePath.startsWith("test/") ||
-    relativePath.endsWith(".test.ts") ||
-    relativePath.endsWith(".test.js") ||
-    relativePath.endsWith(".spec.ts") ||
-    relativePath.endsWith(".spec.js")
-  ) {
+  if (policy.isTestPath(relativePath)) {
     return {
       authoringStatus: "excluded",
       exclusionReason: "test-file",
@@ -443,7 +299,11 @@ function detectAuthoringStatus(
     };
   }
 
-  if (relativePath.endsWith(".md") && !relativePath.endsWith("SKILL.md")) {
+  // Check the filename, not the workspace-relative path: files directly under
+  // a workspace dir (packages/AGENTS.md) get an empty workspace-relative path
+  // and would otherwise escape the markdown exclusion.
+  const fileName = segments[segments.length - 1] ?? relativePath;
+  if (fileName.endsWith(".md") && !fileName.endsWith("SKILL.md")) {
     return {
       authoringStatus: "excluded",
       exclusionReason: "non-skill-markdown",
@@ -642,9 +502,9 @@ export function deriveFileTokens(pathFromRoot: string, source: string): Set<stri
   return tokens;
 }
 
-function validateHistoryIds(historyIds: string[]): string | null {
+function validateHistoryIds(historyIds: string[], policy: CompassPolicy): string | null {
   for (const token of historyIds) {
-    if (!HISTORY_ID_RE.test(token)) {
+    if (!policy.idPatternFull.test(token)) {
       return `<history> contains a non-ID token: "${token}"`;
     }
   }
@@ -653,14 +513,12 @@ function validateHistoryIds(historyIds: string[]): string | null {
   }
   const lastSeenByNamespace = new Map<string, number>();
   for (const token of historyIds) {
-    const parts = token.match(HISTORY_ID_PARTS_RE)!;
-    const namespace = parts[1]!.replace(/-$/, "");
-    const numeric = Number(parts[3]);
-    const last = lastSeenByNamespace.get(namespace);
-    if (last !== undefined && numeric <= last) {
-      return `<history> IDs are not in per-namespace ascending numeric order (${token} after ${namespace}-${last})`;
+    const parts = parseGovernanceIdParts(token)!;
+    const last = lastSeenByNamespace.get(parts.namespace);
+    if (last !== undefined && parts.numeric <= last) {
+      return `<history> IDs are not in per-namespace ascending numeric order (${token} after ${parts.namespace}-${last})`;
     }
-    lastSeenByNamespace.set(namespace, numeric);
+    lastSeenByNamespace.set(parts.namespace, parts.numeric);
   }
   return null;
 }
@@ -668,6 +526,7 @@ function validateHistoryIds(historyIds: string[]): string | null {
 export function evaluateV2Rules(
   entry: Pick<CompassInventoryEntry, "path" | "keyDecisionsRequired">,
   source: string,
+  policy: CompassPolicy,
 ): CompassV2Diagnostic[] {
   const parse = parseCompassBlocks(source);
   const diagnostics: CompassV2Diagnostic[] = [];
@@ -715,7 +574,7 @@ export function evaluateV2Rules(
           fix: "fix: compress the item to a single decision statement",
         });
       }
-      if (GOVERNANCE_ID_PREFIX_RE.test(item)) {
+      if (policy.idPatternPrefix.test(item)) {
         diagnostics.push({
           ruleId: "COMPASS-KD-05",
           message:
@@ -734,7 +593,7 @@ export function evaluateV2Rules(
   }
 
   if (parse.purposeText.length > 0) {
-    if (PURPOSE_BOILERPLATE_PATTERNS.some((pattern) => pattern.test(parse.purposeText))) {
+    if (policy.purposeBoilerplatePatterns.some((pattern) => pattern.test(parse.purposeText))) {
       diagnostics.push({
         ruleId: "COMPASS-PURPOSE-01",
         message: "<purpose> matches a boilerplate pattern",
@@ -767,7 +626,7 @@ export function evaluateV2Rules(
       });
     }
     for (const item of parse.changeSummaryItems) {
-      if (!GOVERNANCE_ID_RE.test(item)) {
+      if (!policy.idPattern.test(item)) {
         diagnostics.push({
           ruleId: "COMPASS-CS-06",
           message: `CHANGE_SUMMARY item lacks a governance-ID reference: "${item.slice(0, 60)}"`,
@@ -776,7 +635,7 @@ export function evaluateV2Rules(
       }
     }
     if (parse.historyRaw !== null) {
-      const historyError = validateHistoryIds(parse.historyIds);
+      const historyError = validateHistoryIds(parse.historyIds, policy);
       if (historyError) {
         diagnostics.push({
           ruleId: "COMPASS-CS-07",
@@ -839,11 +698,12 @@ export async function createCompassInventoryEntries(
   workspaceRoot: string,
   input: ForgeCommandInput,
   scanRoot?: string,
+  policy?: CompassPolicy,
 ): Promise<CompassInventoryEntry[]> {
-  const roots = scanRoot ? [scanRoot] : resolveScanRoots(workspaceRoot, input);
-  const extraExtensions = loadCompassExtensionsFromForgeYaml(workspaceRoot);
+  const resolvedPolicy = policy ?? resolveCompassPolicy(workspaceRoot);
+  const roots = scanRoot ? [scanRoot] : resolveScanRoots(workspaceRoot, input, resolvedPolicy);
   const files = (
-    await Promise.all(roots.map((root) => collectSourceFiles(root, extraExtensions)))
+    await Promise.all(roots.map((root) => collectSourceFiles(root, resolvedPolicy)))
   ).flat();
   const entries: CompassInventoryEntry[] = [];
 
@@ -851,14 +711,17 @@ export async function createCompassInventoryEntries(
     const source = await readFile(filePath, "utf8");
     const pathFromRoot = relative(workspaceRoot, filePath).replace(/\\/g, "/");
     const segments = getRelativeSegments(filePath, workspaceRoot);
-    const relativePathWithinWorkspace = getWorkspaceRelativeSegments(segments).join("/");
-    const layer = detectLayer(relativePathWithinWorkspace);
-    const riskClass = detectRiskClass(pathFromRoot, layer);
+    const relativePathWithinWorkspace = getWorkspaceRelativeSegments(segments, resolvedPolicy).join(
+      "/",
+    );
+    const layer = detectLayer(relativePathWithinWorkspace, resolvedPolicy);
+    const riskClass = detectRiskClass(pathFromRoot, relativePathWithinWorkspace, resolvedPolicy);
     const complexity = detectComplexity(source);
     const { authoringStatus, exclusionReason } = detectAuthoringStatus(
       segments,
       relativePathWithinWorkspace,
       source,
+      resolvedPolicy,
     );
     const requiredScaffolding = detectRequiredScaffolding(authoringStatus);
     const markup = detectMarkup(source);
@@ -869,8 +732,8 @@ export async function createCompassInventoryEntries(
     const nonEmptyLineCount = source.split(/\r?\n/).filter((line) => line.trim().length > 0).length;
     const candidate: CompassInventoryEntry = {
       path: pathFromRoot,
-      workspaceKind: detectWorkspaceKind(segments),
-      workspaceName: detectWorkspaceName(segments),
+      workspaceKind: detectWorkspaceKind(segments, resolvedPolicy),
+      workspaceName: detectWorkspaceName(segments, resolvedPolicy),
       layer,
       extension:
         segments.length > 0

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

@@ -0,0 +1,122 @@
+/*
+<MODULE_CONTRACT>
+<purpose>compass.migrate kernel handler (RFC-1097). Resolves scan root and
+policy, enforces the dirty-tree refusal before any write, then delegates to
+the migrateWorkspace codemod and returns the per-file action manifest.</purpose>
+<non-goals>
+  <item>Do not implement transform logic — that lives in compass-migrate.ts.</item>
+  <item>Do not scaffold headers — no-header files are reported, not written.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1097: initial handler — dirty-tree refusal with --force, --files bypass, dry-run manifest.</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: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</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>
+</CHANGE_SUMMARY>
+*/
+
+import { execFileSync } from "node:child_process";
+import { migrateWorkspace, type MigrateResult } from "./compass-migrate.ts";
+import { resolveCompassScanRoot } from "./resolve-scan-root.ts";
+import { resolveCompassPolicy } from "../policy.ts";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+
+const DIRTY_LIST_CAP = 20;
+
+function listDirtyPaths(repoRoot: string): string[] | null {
+  try {
+    const out = execFileSync("git", ["-C", repoRoot, "status", "--porcelain"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 15000,
+    });
+    return out
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .map((line) => line.slice(3));
+  } catch {
+    // Not a git repository — nothing to protect, skip the check.
+    return null;
+  }
+}
+
+export async function runCompassMigrate(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<MigrateResult>> {
+  const scanRoot = resolveCompassScanRoot(input, context);
+  const baseRoot = scanRoot ?? context.workspaceRoot;
+  const policy = resolveCompassPolicy(baseRoot, context.forgeRoot);
+
+  const dryRun = context.dryRun || input.flags["dry-run"] === true;
+  const force = input.flags["force"] === true;
+
+  const rawFiles = input.flags["files"];
+  const files = (
+    Array.isArray(rawFiles)
+      ? rawFiles.filter((entry): entry is string => typeof entry === "string")
+      : typeof rawFiles === "string"
+        ? [rawFiles]
+        : []
+  )
+    .flatMap((entry) => entry.split(","))
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  const explicitFiles = files.length > 0 ? files : undefined;
+
+  // Dirty-tree refusal guards the write only — a dry-run writes nothing and
+  // stays useful as a pre-commit preview on a dirty tree.
+  if (!dryRun && !force) {
+    const dirty = listDirtyPaths(baseRoot);
+    if (dirty && dirty.length > 0) {
+      const shown = dirty.slice(0, DIRTY_LIST_CAP);
+      const suffix =
+        dirty.length > shown.length ? ` … and ${dirty.length - shown.length} more` : "";
+      context.logger.error(
+        `[compass.migrate] refusing to run on a dirty git tree (${dirty.length} uncommitted path(s)):\n${shown.map((p) => `  ${p}`).join("\n")}${suffix}\nCommit or stash first, or pass --force to override.`,
+      );
+      return { exitCode: 1, summary: "dirty git tree — refused" };
+    }
+  }
+
+  const result = await migrateWorkspace(context.workspaceRoot, input, scanRoot, policy, {
+    files: explicitFiles,
+    dryRun,
+  });
+
+  const counts = new Map<string, number>();
+  for (const file of result.files) {
+    for (const action of file.actions) {
+      counts.set(action, (counts.get(action) ?? 0) + 1);
+    }
+  }
+  const tally = [...counts.entries()].map(([k, v]) => `${k}=${v}`).join(", ");
+
+  return {
+    data: result,
+    exitCode: 0,
+    summary: `[compass.migrate] scanned=${result.scanned} ${tally}${dryRun ? " (dry-run)" : ""}`,
+    nextSteps: [
+      {
+        action:
+          "Run `pnpm exec forge run compass.inventory --json` to list todo/purpose-flagged files for the agent sweep.",
+        kind: "optional",
+      },
+    ],
+  };
+}