@warpgogol/forge 4.2.4 → 5.1.1

package/os/compass/policy.ts

@@ -0,0 +1,350 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Compass policy resolution — generic defaults overlaid by the stack
+profile's compass section (forge.yaml `profile` field, RFC-0643) and the
+consumer's bindings.compass overrides. Single source of truth for which files
+are authored, how risky they are, and what counts as a governance ID
+(RFC-1096).</purpose>
+<non-goals>
+  <item>Do not scan files or classify entries — that lives in handlers/compass-inventory.ts.</item>
+  <item>Do not register commands — this is a pure policy module.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1096: initial policy resolver — generic defaults + profile compass section + bindings.compass overrides.</item>
+</CHANGE_SUMMARY>
+*/
+
+import picomatch from "picomatch";
+import { loadForgeConfig } from "../../src/config/forge-config.ts";
+import type { CompassPolicyOverrides } from "../../src/profiles/profile-schema.ts";
+
+export type CompassRiskClass = "high" | "medium" | "low";
+export type CompassWorkspaceKind = "app" | "package" | "service";
+
+export interface CompassLayerRule {
+  pattern: string;
+  layer: string;
+  risk: CompassRiskClass;
+}
+
+export interface CompassExcludedPath {
+  pattern: string;
+  reason: string;
+}
+
+export interface CompassPolicySource {
+  /** Stack profile id that contributed a `compass:` section, or null. */
+  profile: string | null;
+  /** Keys the consumer's bindings.compass overrode. */
+  overriddenKeys: string[];
+}
+
+export interface CompassPolicy {
+  fileExtensions: ReadonlySet<string>;
+  testPatterns: readonly string[];
+  scanRoots: readonly string[];
+  ignoredDirs: ReadonlySet<string>;
+  ignoredDirPrefixes: readonly string[];
+  /** picomatch globs on the root-relative path that force riskClass=high. */
+  highRiskPaths: readonly string[];
+  /** Governance-ID detection pattern (unanchored, as configured). */
+  idPattern: RegExp;
+  /** `^(?:idPattern)$` — full-string governance-ID match. */
+  idPatternFull: RegExp;
+  /** `^(?:idPattern)` — leading governance-ID match. */
+  idPatternPrefix: RegExp;
+  purposeBoilerplatePatterns: readonly RegExp[];
+  /** Ordered first-match layer rules on the workspace-relative path. */
+  layerRules: readonly CompassLayerRule[];
+  workspaceKinds: Readonly<Record<string, CompassWorkspaceKind>>;
+  /** Workspace-relative globs that mark a file excluded with a reason. */
+  excludedPaths: readonly CompassExcludedPath[];
+  source: CompassPolicySource;
+  /** First-match layer rule for a workspace-relative path. */
+  matchLayer(workspaceRelativePath: string): CompassLayerRule | undefined;
+  /** Whether a root-relative path is forced high-risk. */
+  isHighRisk(pathFromRoot: string): boolean;
+  /** Whether a workspace-relative path is a test file. */
+  isTestPath(workspaceRelativePath: string): boolean;
+  /** Exclusion reason for a workspace-relative path, if any. */
+  excludedReason(workspaceRelativePath: string): string | undefined;
+}
+
+export class CompassPolicyConfigError extends Error {
+  readonly key: string;
+  constructor(key: string, detail: string) {
+    super(`[compass.policy] invalid compass policy key "${key}": ${detail}`);
+    this.name = "CompassPolicyConfigError";
+    this.key = key;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Generic defaults — stack-neutral values only. Consumer- or stack-specific
+// literals are forbidden here (RFC-1096 AC-4); they live in profiles or
+// forge.yaml bindings.compass.
+// ---------------------------------------------------------------------------
+
+const GENERIC_FILE_EXTENSIONS = [
+  ".ts",
+  ".tsx",
+  ".astro",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".mts",
+  ".css",
+  ".cs",
+  ".tscn",
+  ".tres",
+  ".gd",
+  ".md",
+];
+
+const GENERIC_IGNORED_DIRS = [
+  ".git",
+  ".turbo",
+  ".astro",
+  ".wrangler",
+  ".vscode",
+  ".cache",
+  "coverage",
+  "dist",
+  "node_modules",
+];
+
+const GENERIC_SCAN_ROOTS = ["src", "apps", "packages", "services"];
+
+const GENERIC_TEST_PATTERNS = [
+  "test/**",
+  "**/*.test.ts",
+  "**/*.test.js",
+  "**/*.spec.ts",
+  "**/*.spec.js",
+];
+
+const GENERIC_ID_PATTERN = "\\b([A-Z][A-Z0-9]*-)+\\d+\\b";
+
+const GENERIC_PURPOSE_BOILERPLATE = [
+  "^(this file|the file|a file|this module|a module)\\b",
+  "^(utility|utilities|helper|helpers|misc)\\b",
+  "^(todo|placeholder|fixme)\\b",
+];
+
+const GENERIC_LAYER_RULES: CompassLayerRule[] = [
+  { pattern: "bin/**", layer: "bin", risk: "low" },
+  { pattern: "src/middleware.ts", layer: "middleware", risk: "low" },
+  { pattern: "src/middleware/**", layer: "middleware", risk: "high" },
+  { pattern: "src/pages/**", layer: "page", risk: "medium" },
+  { pattern: "src/components/**", layer: "component", risk: "medium" },
+  { pattern: "src/content/schemas/**", layer: "schema", risk: "medium" },
+  { pattern: "src/content/**", layer: "content", risk: "low" },
+  { pattern: "src/styles/**", layer: "style", risk: "low" },
+  { pattern: "src/scripts/**", layer: "script", risk: "medium" },
+  { pattern: "src/layouts/**", layer: "layout", risk: "high" },
+  { pattern: "src/utils/**", layer: "utility", risk: "medium" },
+  { pattern: "src/configure/**", layer: "config", risk: "low" },
+  { pattern: "test/**", layer: "test", risk: "low" },
+  { pattern: "src/tests/**", layer: "test", risk: "low" },
+  { pattern: "**/*.test.ts", layer: "test", risk: "low" },
+  { pattern: "**/*.spec.ts", layer: "test", risk: "low" },
+  { pattern: "src/**", layer: "source", risk: "low" },
+  { pattern: "**/SKILL.md", layer: "skill", risk: "low" },
+];
+
+const GENERIC_WORKSPACE_KINDS: Record<string, CompassWorkspaceKind> = {
+  apps: "app",
+  packages: "package",
+  services: "service",
+};
+
+// ---------------------------------------------------------------------------
+// Merge semantics (RFC-1096): union keys merge with `!entry` subtraction
+// (fileExtensions, testPatterns, ignoredDirs, ignoredDirPrefixes, highRiskPaths,
+// excludedPaths — matched by `pattern`); scanRoots, idPattern,
+// purposeBoilerplatePatterns, layerRules, and workspaceKinds replace wholesale
+// (bindings > profile > generic).
+// ---------------------------------------------------------------------------
+
+function mergeStringList(
+  generic: readonly string[],
+  ...overrides: Array<readonly string[] | undefined>
+): string[] {
+  const result = new Set(generic);
+  for (const list of overrides) {
+    for (const item of list ?? []) {
+      if (item.startsWith("!")) {
+        result.delete(item.slice(1));
+      } else {
+        result.add(item);
+      }
+    }
+  }
+  return [...result];
+}
+
+function mergeExcludedPaths(
+  generic: readonly CompassExcludedPath[],
+  ...overrides: Array<readonly CompassExcludedPath[] | undefined>
+): CompassExcludedPath[] {
+  const byPattern = new Map<string, string>();
+  for (const entry of generic) {
+    byPattern.set(entry.pattern, entry.reason);
+  }
+  for (const list of overrides) {
+    for (const entry of list ?? []) {
+      if (entry.pattern.startsWith("!")) {
+        byPattern.delete(entry.pattern.slice(1));
+      } else {
+        byPattern.set(entry.pattern, entry.reason);
+      }
+    }
+  }
+  return [...byPattern.entries()].map(([pattern, reason]) => ({ pattern, reason }));
+}
+
+function compilePattern(key: string, pattern: string, flags?: string): RegExp {
+  try {
+    return new RegExp(pattern, flags);
+  } catch {
+    throw new CompassPolicyConfigError(key, `not a compilable regex: ${pattern}`);
+  }
+}
+
+/** Split a `NAMESPACE-NUMBER` governance ID on its last dash. */
+export function parseGovernanceIdParts(id: string): { namespace: string; numeric: number } | null {
+  const match = id.match(/^(.*)-(\d+)$/);
+  if (!match) return null;
+  return { namespace: match[1]!, numeric: Number(match[2]) };
+}
+
+/**
+ * Resolve the effective Compass policy for a workspace: generic defaults,
+ * overlaid by the stack profile `compass:` section (when forge.yaml declares
+ * `profile`), then by `bindings.compass`. Missing or unreadable forge.yaml
+ * yields the generic policy. Invalid regexes throw CompassPolicyConfigError
+ * naming the offending key.
+ */
+export function resolveCompassPolicy(workspaceRoot: string, forgeRoot?: string): CompassPolicy {
+  let profileCompass: CompassPolicyOverrides | undefined;
+  let bindingsCompass: CompassPolicyOverrides | undefined;
+  let profileId: string | null = null;
+  try {
+    const config = loadForgeConfig(workspaceRoot, forgeRoot);
+    profileCompass = config.profile?.compass;
+    bindingsCompass = config.bindings?.compass;
+    profileId = config.profile?.id ?? null;
+  } catch {
+    // No forge.yaml or unreadable config — generic policy only.
+  }
+
+  const overriddenKeys = Object.keys(bindingsCompass ?? {}).filter(
+    (key) => (bindingsCompass as Record<string, unknown>)[key] !== undefined,
+  );
+
+  const fileExtensions = mergeStringList(
+    GENERIC_FILE_EXTENSIONS,
+    profileCompass?.fileExtensions,
+    bindingsCompass?.fileExtensions,
+  );
+  const testPatterns = mergeStringList(
+    GENERIC_TEST_PATTERNS,
+    profileCompass?.testPatterns,
+    bindingsCompass?.testPatterns,
+  );
+  const ignoredDirs = mergeStringList(
+    GENERIC_IGNORED_DIRS,
+    profileCompass?.ignoredDirs,
+    bindingsCompass?.ignoredDirs,
+  );
+  const ignoredDirPrefixes = mergeStringList(
+    [],
+    profileCompass?.ignoredDirPrefixes,
+    bindingsCompass?.ignoredDirPrefixes,
+  );
+  const highRiskPaths = mergeStringList(
+    [],
+    profileCompass?.highRiskPaths,
+    bindingsCompass?.highRiskPaths,
+  );
+  const excludedPaths = mergeExcludedPaths(
+    [],
+    profileCompass?.excludedPaths,
+    bindingsCompass?.excludedPaths,
+  );
+  const layerRules =
+    bindingsCompass?.layerRules ?? profileCompass?.layerRules ?? GENERIC_LAYER_RULES;
+  const workspaceKinds: Record<string, CompassWorkspaceKind> =
+    bindingsCompass?.workspaceKinds ?? profileCompass?.workspaceKinds ?? GENERIC_WORKSPACE_KINDS;
+  const scanRoots = bindingsCompass?.scanRoots ?? profileCompass?.scanRoots ?? GENERIC_SCAN_ROOTS;
+
+  const idPatternRaw =
+    bindingsCompass?.idPattern ?? profileCompass?.idPattern ?? GENERIC_ID_PATTERN;
+  const idPattern = compilePattern("idPattern", idPatternRaw);
+  if (!idPattern.test("ABC-123")) {
+    throw new CompassPolicyConfigError(
+      "idPattern",
+      `must match NAMESPACE-NUMBER governance ids (probe "ABC-123" failed): ${idPatternRaw}`,
+    );
+  }
+  const idPatternFull = new RegExp(`^(?:${idPattern.source})$`);
+  const idPatternPrefix = new RegExp(`^(?:${idPattern.source})`);
+
+  const boilerplateRaw =
+    bindingsCompass?.purposeBoilerplatePatterns ??
+    profileCompass?.purposeBoilerplatePatterns ??
+    GENERIC_PURPOSE_BOILERPLATE;
+  // Boilerplate detectors match English prose — always case-insensitive.
+  const purposeBoilerplatePatterns = boilerplateRaw.map((pattern) =>
+    compilePattern("purposeBoilerplatePatterns", pattern, "i"),
+  );
+
+  const layerMatchers = layerRules.map((rule) => ({
+    rule,
+    is: picomatch(rule.pattern, { dot: true }),
+  }));
+  const highRiskMatchers = highRiskPaths.map((pattern) => picomatch(pattern, { dot: true }));
+  const testMatchers = testPatterns.map((pattern) => picomatch(pattern, { dot: true }));
+  const excludedMatchers = excludedPaths.map((entry) => ({
+    reason: entry.reason,
+    is: picomatch(entry.pattern, { dot: true }),
+  }));
+
+  // Shallow freeze: the Readonly* types are the real immutability contract —
+  // do not mutate the nested Sets/arrays after resolution.
+  return Object.freeze({
+    fileExtensions: new Set(fileExtensions),
+    testPatterns,
+    scanRoots,
+    ignoredDirs: new Set(ignoredDirs),
+    ignoredDirPrefixes,
+    highRiskPaths,
+    idPattern,
+    idPatternFull,
+    idPatternPrefix,
+    purposeBoilerplatePatterns,
+    layerRules,
+    workspaceKinds,
+    excludedPaths,
+    source: { profile: profileId, overriddenKeys },
+    matchLayer(workspaceRelativePath: string): CompassLayerRule | undefined {
+      for (const { rule, is } of layerMatchers) {
+        if (is(workspaceRelativePath)) return rule;
+      }
+      return undefined;
+    },
+    isHighRisk(pathFromRoot: string): boolean {
+      return highRiskMatchers.some((is) => is(pathFromRoot));
+    },
+    isTestPath(workspaceRelativePath: string): boolean {
+      return testMatchers.some((is) => is(workspaceRelativePath));
+    },
+    excludedReason(workspaceRelativePath: string): string | undefined {
+      for (const { reason, is } of excludedMatchers) {
+        if (is(workspaceRelativePath)) return reason;
+      }
+      return undefined;
+    },
+  });
+}

package/os/core/core.module.ts

@@ -6,30 +6,16 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0374: initial forgeCoreModule registering 4 forge commands.</item>
-  <item>RFC-0521: register docs.archive umbrella command dispatching to rfc/adr/plan/audit archive commands.</item>
-  <item>RFC-0539: extended forge.skill.list to include pack skills with pack column.</item>
-  <item>RFC-0542: populate nextSteps in forge.init, forge.scaffold, forge.doctor, forge.port.scaffold results.</item>
-  <item>RFC-0543: register forge.upgrade command for additive consumer sync.</item>
-  <item>RFC-0544: register forge.create command composing scaffold + init.</item>
-  <item>RFC-0544 fix: simplify createWrapper — runCreate already populates nextSteps.</item>
-  <item>RFC-0546: remove forge.init CLI registration; runInit() remains as internal primitive called by forge.create.</item>
-  <item>RFC-0640: register forge.profile.validate command, add --strict flag to forge.doctor.</item>
-  <item>RFC-0662: register forge.skill.knowledge.compact command for skill knowledge lifecycle compaction.</item>
-  <item>RFC-0674: register forge.dev, forge.build, forge.validate lifecycle commands.</item>
-  <item>RFC-0678: register forge.determinism.check lifecycle command.</item>
-  <item>RFC-0679: register forge.assets.list, forge.assets.check commands.</item>
-  <item>RFC-0680: register forge.release.prepare, forge.release.publish commands.</item>
-  <item>ADR-0021: profile-driven video lifecycle — all lifecycle commands read behavior from profile YAML, zero domain-specific code in Forge source.</item>
-  <item>RFC-0711: docs.archive post-loop step calls spec.live.merge for implemented RFCs with liveSpec field; skips rejected RFCs.</item>
-  <item>RFC-0733: register forge pinned.validate and forge pinned.init commands for pinned-files protection system.</item>
-  <item>Lockfile safety net: docs.archive post-loop refreshes pnpm-lock.yaml after mission workpiece moves.</item>
-  <item>RFC-0877: forge.create --in-place required, --profile required, --name optional (derived from folder), strict empty-directory check (only .git/ tolerated).</item>
-  <item>RFC-0940: register forge.autonomy.validate command enforcing FORGE-AUTONOMY-01 (no @warpgogol/werkstatt-engine imports outside os/werkstatt/).</item>
-  <item>RFC-1080: register forge.public-surface.validate command for README/package.json consistency checks (SURFACE-01..05).</item>
   <item>RFC-1088: register forge.file-size.lint command for portable SIZE-01 line-count validation.</item>
   <item>RFC-1088 fix: add writes field to forge.file-size.lint registration per fo-review.</item>
   <item>RFC-1089: rename forge.file-size.lint to file.size.lint (domain validator, no forge. prefix).</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 — 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>ADR-0021, RFC-0374, RFC-0521, RFC-0539, RFC-0542, RFC-0543, RFC-0544, RFC-0546, RFC-0640, RFC-0662, RFC-0674, RFC-0678, RFC-0679, RFC-0680, RFC-0711, RFC-0733, RFC-0877, RFC-0940, RFC-1080</history>
 </CHANGE_SUMMARY>
 */
 
@@ -326,7 +312,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
           profile: {
             kind: "string",
             required: true,
-            description: "Stack profile id (e.g. phaser-turborepo).",
+            description: "Stack profile id (e.g. phaser-game).",
           },
           name: { kind: "string", required: true, description: "Project name (kebab-case)." },
           template: {
@@ -354,7 +340,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
             kind: "string",
             required: true,
             description:
-              "Stack profile id. Required. Available: forge-shell, phaser-turborepo, godot-csharp, knowledge-typescript-turborepo, typescript-turborepo.",
+              "Stack profile id. Required. Available: forge-shell, phaser-game, godot-game, knowledge, typescript.",
           },
           name: {
             kind: "string",
@@ -743,6 +729,8 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
           "Check consistency between README.md, package.json, and docs/ structure. " +
           "Enforces SURFACE-01..05 rules: README length, Node version match, " +
           "no .tgz in root, docs/ structure, required root files (RFC-1080).",
+        contract: "forge",
+        rules: ["SURFACE-01", "SURFACE-02", "SURFACE-03", "SURFACE-04", "SURFACE-05"],
         scope: "workspace",
         supportsAllSites: false,
         reads: ["README.md", "package.json", "docs/**"],

package/os/core/handlers/forge-autonomy-validate.ts

@@ -4,7 +4,7 @@
 @warpgogol/werkstatt-engine imports outside os/werkstatt/. Enforces FORGE-AUTONOMY-01
 (RFC-0940, DNA-64). @warpgogol/werkstatt-shared is exempt (shared infrastructure).
 Type-only imports (import type) are exempt.</purpose>
-<keywords>autonomy, guard, RFC-0940, DNA-64, forge, import boundary</keywords>
+
 <non-goals>
   <item>Does not scan test files — .test.ts and .spec.ts are always excluded.</item>
   <item>Does not scan os/werkstatt/ — the adapter directory may import @warpgogol/werkstatt-engine.</item>
@@ -15,6 +15,12 @@ Type-only imports (import type) are exempt.</purpose>
 <CHANGE_SUMMARY>
   <item>RFC-0940: initial forge.autonomy.validate handler implementing FORGE-AUTONOMY-01.</item>
   <item>ADR-0019: inlined scanDirectoryForImports to make forge dependency-free.</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 — werkstatt-engine 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. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 

package/os/core/handlers/package-health.ts

@@ -7,8 +7,13 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Initial: forge.package.health validator — engines, CI workflow, extract config, devDeps completeness.</item>
   <item>PKG-HEALTH-05: reject any versionBump in extract.config.yaml — version in package.json is source of truth.</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 — werkstatt-engine 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. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 

package/os/core/handlers/pinned-check.ts

@@ -12,7 +12,12 @@ per invocation — loadPinnedManifest is called once and the result is reused.</
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0733: initial pinned-check utility — loadPinnedManifest, isPinned, checkFilesForPinned.</item>
-  <item>Gap fix: add isIntraDirMove to exempt moves within the same pinned directory (e.g. rfc.archive moves docs/rfcs/x.md → docs/rfcs/archive/implemented/x.md).</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 — werkstatt-engine 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. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 

package/os/core/handlers/pinned-validate.ts

@@ -12,7 +12,12 @@ pinned files. Supports --allow-pinned-override for audited escape hatch,
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0733: initial pinned.validate handler with staged/ci modes, override, audit log, manifest integrity check.</item>
-  <item>Gap fix: read FORGE_PINNED_OVERRIDE env var for pre-commit hook override support.</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 — werkstatt-engine 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. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 

package/os/core/handlers/validate.ts

@@ -9,7 +9,12 @@
 <CHANGE_SUMMARY>
   <item>RFC-0674: initial forge.validate handler with profile resolution, --dry-run, and per-artifact execution.</item>
   <item>RFC-0677: extended with --artifact filtering, violation parsing (outputFormat: json/plain), passed/allPassed fields.</item>
-  <item>Integrated compass.validate as in-process step after artifact validations for automatic Compass enforcement.</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 — werkstatt-engine 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. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */