@warpgogol/forge 4.2.4 → 5.1.1

package/src/onboarding/upgrade.ts

@@ -11,12 +11,16 @@ With --update-npm, also updates @warpgogol/forge from npm before syncing (skippe
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0543: initial forge.upgrade handler — 7-step additive sync flow.</item>
   <item>RFC-0611: added nested AGENTS.md generation after skill sync.</item>
   <item>RFC-0663: added syncSharedKnowledge step to sync shared knowledge layer to .agents/skills/shared-knowledge/.</item>
   <item>RFC-0664: added scaffoldMemoryLayer step to scaffold .agents/memory/ and .gitignore block.</item>
-  <item>Added --update-npm flag: updates @warpgogol/forge from npm before syncing (skipped in monorepo).</item>
-  <item>Added npm latest-version check: warns when a newer @warpgogol/forge is available on npm.</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>
+  <history>RFC-0543</history>
 </CHANGE_SUMMARY>
 */
 

package/src/profiles/profile-schema.ts

@@ -7,17 +7,16 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0638: initial domain-neutral profile schema extensions with six optional fields.</item>
-  <item>RFC-0674: add profileDevServerSchema and devServer field for lifecycle commands.</item>
-  <item>RFC-0675: add profileInvariantCheckSchema and check field to profileInvariantSchema for enforcement.</item>
-  <item>RFC-0679: add profileAssetSchema and assets field for asset management commands.</item>
-  <item>RFC-0680: add profileReleaseSchema and release field for release lifecycle commands.</item>
   <item>RFC-0694: replace html-attribute-pattern with attribute-pattern (elements array) for HTML+JSX support.</item>
-  <item>Add prerequisites field for profile-declared system dependency checks (e.g. FFmpeg).</item>
-  <item>Add templates field for multi-template profiles (e.g. React + HTML).</item>
   <item>ADR-0043: add scriptDir field for agent-generated script directory convention.</item>
   <item>RFC-0808: add link-resolution, frontmatter-required, path-exclusion check kinds for note vault validation.</item>
-  <item>Add gitignore-entry and secret-scan check kinds for godot-csharp profile.</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>RFC-0638, RFC-0674, RFC-0675, RFC-0679, RFC-0680</history>
 </CHANGE_SUMMARY>
 */
 
@@ -317,6 +316,39 @@ export interface ProfileTemplate {
 // Stack profile domain fields
 // ---------------------------------------------------------------------------
 
+// RFC-1096: shared Compass policy override shape — used by both the stack
+// profile `compass:` section and the consumer `bindings.compass` section.
+export const compassPolicyOverridesSchema = z.object({
+  fileExtensions: z.array(z.string()).optional(),
+  testPatterns: z.array(z.string()).optional(),
+  scanRoots: z.array(z.string()).optional(),
+  ignoredDirs: z.array(z.string()).optional(),
+  ignoredDirPrefixes: z.array(z.string()).optional(),
+  highRiskPaths: z.array(z.string()).optional(),
+  idPattern: z.string().optional(),
+  purposeBoilerplatePatterns: z.array(z.string()).optional(),
+  layerRules: z
+    .array(
+      z.object({
+        pattern: z.string().min(1),
+        layer: z.string().min(1),
+        risk: z.enum(["high", "medium", "low"]),
+      }),
+    )
+    .optional(),
+  workspaceKinds: z.record(z.string(), z.enum(["app", "package", "service"])).optional(),
+  excludedPaths: z
+    .array(
+      z.object({
+        pattern: z.string().min(1),
+        reason: z.string().min(1),
+      }),
+    )
+    .optional(),
+});
+
+export type CompassPolicyOverrides = z.infer<typeof compassPolicyOverridesSchema>;
+
 export const stackProfileDomainFieldsSchema = z.object({
   domain: z.string().optional(),
   terminology: z.record(z.string(), z.string()).optional(),
@@ -331,12 +363,7 @@ export const stackProfileDomainFieldsSchema = z.object({
   templates: z.array(profileTemplateSchema).optional(),
   scriptDir: z.string().min(1).optional(),
   rootAgentsMdTemplate: z.string().optional(),
-  compass: z
-    .object({
-      fileExtensions: z.array(z.string()).optional(),
-      testPatterns: z.array(z.string()).optional(),
-    })
-    .optional(),
+  compass: compassPolicyOverridesSchema.optional(),
 });
 
 export interface StackProfileDomainFields {
@@ -353,8 +380,5 @@ export interface StackProfileDomainFields {
   templates?: ProfileTemplate[];
   scriptDir?: string;
   rootAgentsMdTemplate?: string;
-  compass?: {
-    fileExtensions?: string[];
-    testPatterns?: string[];
-  };
+  compass?: CompassPolicyOverrides;
 }

package/src/profiles/stack-profile.ts

@@ -7,12 +7,16 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0392: initial stack profile module with zod schema, listStackProfiles, detectStack.</item>
-  <item>RFC-0638: extended stackProfileSchema with optional domain-neutral fields (domain, terminology, artifacts, workspaceTypes, invariants, register).</item>
-  <item>RFC-0674: add devServer field to stackProfileSchema for lifecycle commands.</item>
   <item>RFC-0679: add assets field to stackProfileSchema for asset management commands.</item>
   <item>RFC-0680: add release field to stackProfileSchema for release lifecycle commands.</item>
   <item>ADR-0043: add scriptDir field for agent-generated script directory convention.</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>RFC-0392, RFC-0638, RFC-0674</history>
 </CHANGE_SUMMARY>
 */
 

package/src/registry.ts

@@ -6,18 +6,16 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0374: initial ForgeSkillEntry interface and FORGE_SKILLS registry (17 migrated + 3 meta = 20).</item>
-  <item>Added fo-add-tests skill (11th fo skill) — absorbs tdd + PBT conventions from RFC-0347.</item>
-  <item>Skill consolidation: added fo-architecture, fo-handoff, fo-triage, fo-qa (15 fo skills). Removed handoff, improve-codebase-architecture, to-spec from shared (absorbed into fo-). Shared skills reduced to 4 (grilling, my-preferences, windows-ai-tooling, writing-great-skills).</item>
-  <item>Renamed skill prefix wg- → fo- across all skills, paths, and categories. Added fo-idea-status, fo-idea-i-just-want-to-see-the-plan, fo-idea-i-just-want-to-see-the-result (18 fo skills total).</item>
-  <item>Added fo-doc-audit skill (19th fo skill) — centralized documentation audit replacing inline AGENTS/README update steps in fo-fix and fo-idea-implement.</item>
-  <item>RFC-0395: added fo-spec-ingest skill (20th fo skill) — spec package ingest/authoring with validation, grilling, and acceptance gate.</item>
-  <item>Added fo-session-retro skill (21st fo skill) — session-end insight triage, categorizes discoveries and routes to AGENTS.md / ADR / DNA / forge / memory.</item>
-  <item>RFC-0523: expanded concerns enum from binary (document-only | implementation) to four-level taxonomy (read-only | document-only | content-mutation | code-mutation). All 30 skills reclassified.</item>
-  <item>RFC-0524: added optional knowledge?: string[] field for cumulative knowledge system. Added knowledge arrays to fo-site-scan and grilling.</item>
   <item>RFC-0538: added fo-compass-annotate skill (22nd fo skill) — full-lifecycle Compass header management replacing removed compass.annotate, compass.clear, compass.markup.migrate, compass.invariant.add kernel commands.</item>
   <item>RFC-0539: added discoverPackSkills helper and PackSkillEntry interface for project-declared skill packs. Removed mission-complete and fo-site-scan entries (relocated to warpgogol-skills as wg- pack skills).</item>
   <item>RFC-0941: discoverPackSkills now requires forge.plugin.yaml manifest at each pack root — throws on missing or invalid manifest (fail-fast).</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>RFC-0374, RFC-0395, RFC-0523, RFC-0524</history>
 </CHANGE_SUMMARY>
 */
 

package/src/tests/agents-generate-domain.test.ts

@@ -147,7 +147,7 @@ test("creative template contains {{dynamicSections}} marker", () => {
 
 test("selectRootTemplate with profile rootAgentsMdTemplate loads profile template", () => {
   const profile = {
-    id: "godot-csharp",
+    id: "godot-game",
     rootAgentsMdTemplate: "root-agents-godot.md",
   } as StackProfile;
   const content = selectRootTemplate("creative", profile);
@@ -301,8 +301,8 @@ test("agents-generate with creative register uses creative template", async () =
   expect(rootDetail?.register).toBe("creative");
 });
 
-test("agents-generate with godot-csharp profile generates Godot-specific AGENTS.md", async () => {
-  await makeForgeYaml(tempDir, "profile: godot-csharp");
+test("agents-generate with godot-game profile generates Godot-specific AGENTS.md", async () => {
+  await makeForgeYaml(tempDir, "profile: godot-game");
   const ctx = makeContext(tempDir);
   ctx.dryRun = true;
 

package/src/tests/agents-generate.test.ts

@@ -417,7 +417,7 @@ test("agents-generate nested separates workspace and external dependencies", asy
     JSON.stringify({
       name: "@test/my-pkg",
       dependencies: {
-        "@warpgogol/werkstatt-shared/share": "workspace:*",
+        "@warpgogol/werkstatt-shared": "workspace:*",
         zod: "^4.4.3",
       },
     }),
@@ -428,7 +428,7 @@ test("agents-generate nested separates workspace and external dependencies", asy
 
   const nested = await readFile(join(tempDir, "packages", "my-pkg", "AGENTS.md"), "utf8");
   expect(nested).toContain("**Workspace:**");
-  expect(nested).toContain("- `@warpgogol/werkstatt-shared/share`");
+  expect(nested).toContain("- `@warpgogol/werkstatt-shared`");
   expect(nested).toContain("**External:**");
   expect(nested).toContain("- `zod` `^4.4.3`");
 });

package/src/tests/create.test.ts

@@ -290,9 +290,9 @@ test("forge create --in-place derives name from folder name when --name omitted"
   expect(pkgJson.name).toBe("my-derived-project");
 }, 120000);
 
-test("forge create --profile godot-csharp writes compass.fileExtensions into forge.yaml", async () => {
+test("forge create --profile godot-game writes compass.fileExtensions into forge.yaml", async () => {
   const result = await runCreate(
-    { argv: [], flags: { "in-place": true, profile: "godot-csharp", name: "my-game" } },
+    { argv: [], flags: { "in-place": true, profile: "godot-game", name: "my-game" } },
     makeContext(tempDir),
   );
   expect(result.exitCode).toBe(0);
@@ -346,9 +346,9 @@ test("forge create --in-place pins pre-user-prompt-wrapper.mjs in pinned.yaml (R
   expect(pinnedYaml).toContain("pre-user-prompt-wrapper.mjs");
 }, 120000);
 
-test("forge create --profile phaser-turborepo writes compass.fileExtensions into forge.yaml", async () => {
+test("forge create --profile phaser-game writes compass.fileExtensions into forge.yaml", async () => {
   const result = await runCreate(
-    { argv: [], flags: { "in-place": true, profile: "phaser-turborepo", name: "my-phaser-game" } },
+    { argv: [], flags: { "in-place": true, profile: "phaser-game", name: "my-phaser-game" } },
     makeContext(tempDir),
   );
   expect(result.exitCode).toBe(0);

package/src/tests/forge-autonomy-validate.test.ts

@@ -94,7 +94,7 @@ describe("forge.autonomy.validate", () => {
   test("passes when @warpgogol/werkstatt-shared is imported (exempt)", async () => {
     writeFileSync(
       join(workspace, "packages", "forge", "os", "core", "handlers", "shared.ts"),
-      `import { scanDirectoryForImports } from "@warpgogol/werkstatt-shared/share/import-scan";\nexport function bar() { return scanDirectoryForImports; }\n`,
+      `import { scanDirectoryForImports } from "@warpgogol/werkstatt-shared/node/import-scan";\nexport function bar() { return scanDirectoryForImports; }\n`,
     );
 
     const result = await runForgeAutonomyValidate({ argv: [], flags: {} }, makeContext(workspace));

package/src/tests/package-files.test.ts

@@ -10,8 +10,18 @@ but are missing from the published package.</purpose>
 */
 
 import { test, expect } from "vitest";
-import { readFileSync, readdirSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { resolveForgePackageRoot } from "../config/forge-config.ts";
 
 const PACKAGE_ROOT = join(import.meta.dirname, "..", "..");
 
@@ -52,3 +62,45 @@ test("root AGENTS.md templates exist and are readable", () => {
     expect(content.length).toBeGreaterThan(0);
   }
 });
+
+// Regression: published 5.1.0 resolved templates/profiles via import.meta.dirname,
+// which points at dist/src/onboarding/ in the compiled package — tsc never copies
+// .md assets into dist/, so lookups silently failed. resolveForgePackageRoot must
+// find the package root from both source and compiled layouts.
+test("resolveForgePackageRoot finds package root from compiled dist layout", () => {
+  const tmp = mkdtempSync(join(tmpdir(), "forge-pkgroot-"));
+  try {
+    writeFileSync(join(tmp, "package.json"), JSON.stringify({ name: "@warpgogol/forge" }));
+    const distOnboarding = join(tmp, "dist", "src", "onboarding");
+    mkdirSync(distOnboarding, { recursive: true });
+    const srcTemplates = join(tmp, "src", "onboarding", "templates");
+    mkdirSync(srcTemplates, { recursive: true });
+
+    const root = resolveForgePackageRoot(distOnboarding);
+    expect(root).toBe(tmp);
+    expect(existsSync(join(root, "src", "onboarding", "templates"))).toBe(true);
+    expect(existsSync(join(root, "profiles"))).toBe(false);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test("resolveForgePackageRoot finds package root from source layout", () => {
+  const tmp = mkdtempSync(join(tmpdir(), "forge-pkgroot-"));
+  try {
+    writeFileSync(join(tmp, "package.json"), JSON.stringify({ name: "@warpgogol/forge" }));
+    const srcOnboarding = join(tmp, "src", "onboarding");
+    mkdirSync(srcOnboarding, { recursive: true });
+
+    expect(resolveForgePackageRoot(srcOnboarding)).toBe(tmp);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test("resolveForgePackageRoot resolves the real package root from src/onboarding", () => {
+  const root = resolveForgePackageRoot(join(PACKAGE_ROOT, "src", "onboarding"));
+  expect(root).toBe(PACKAGE_ROOT);
+  expect(existsSync(join(root, "src", "onboarding", "templates"))).toBe(true);
+  expect(existsSync(join(root, "profiles"))).toBe(true);
+});

package/src/tests/profile-schema.test.ts

@@ -162,16 +162,16 @@ test("all shipped profiles parse without changes", () => {
     expect(profile.id).toBeDefined();
     expect(profile.workspace.dirs.length).toBeGreaterThan(0);
     // Domain fields should be undefined for existing software-domain profiles
-    if (profile.id !== "godot-csharp") {
+    if (profile.id !== "godot-game") {
       expect(profile.domain).toBeUndefined();
       expect(profile.register).toBeUndefined();
     }
   }
 });
 
-test("shipped phaser-turborepo profile loads via loadStackProfile", () => {
-  const profile = loadStackProfile(join(FORGE_ROOT, "profiles", "phaser-turborepo.yaml"));
-  expect(profile.id).toBe("phaser-turborepo");
+test("shipped phaser-game profile loads via loadStackProfile", () => {
+  const profile = loadStackProfile(join(FORGE_ROOT, "profiles", "phaser-game.yaml"));
+  expect(profile.id).toBe("phaser-game");
 });
 
 test("UNIVERSAL_TERMINOLOGY_KEYS contains the 7 documented keys", () => {

package/src/tests/scaffold-project.test.ts

@@ -73,7 +73,7 @@ test("forge.scaffold fails on missing --profile", async () => {
 
 test("forge.scaffold derives name from folder when --name omitted", async () => {
   const result = await runScaffoldProject(
-    { argv: [], flags: { profile: "phaser-turborepo" } },
+    { argv: [], flags: { profile: "phaser-game" } },
     { ...makeContext(tempDir), forgeRoot: FORGE_ROOT },
   );
   // Name is now derived from the folder name (consistent with forge.create)
@@ -89,7 +89,7 @@ test("forge.scaffold derives name from folder when --name omitted", async () =>
 
 test("forge.scaffold fails on non-kebab-case name", async () => {
   const result = await runScaffoldProject(
-    { argv: [], flags: { profile: "phaser-turborepo", name: "MySite" } },
+    { argv: [], flags: { profile: "phaser-game", name: "MySite" } },
     { ...makeContext(tempDir), forgeRoot: FORGE_ROOT },
   );
   expect(result.exitCode).toBe(1);
@@ -129,7 +129,7 @@ test("forge.init --from detects stack from existing project", async () => {
   const result = runInit({ flags: { from: fakeProject } }, { workspaceRoot: WORKSPACE_ROOT });
   expect(result.status).toBe("pass");
   expect(result.detection).toBeDefined();
-  expect(result.detection?.profile).toBe("phaser-turborepo");
+  expect(result.detection?.profile).toBe("phaser-game");
 });
 
 test("forge.init --from reports null when stack undetectable", async () => {

package/src/tests/stack-profile.test.ts

@@ -139,31 +139,31 @@ test("detectStack matches on exact filename", async () => {
   expect(match?.id).toBe("ts");
 });
 
-test("shipped phaser-turborepo profile validates", () => {
-  const profile = loadStackProfile(join(FORGE_ROOT, "profiles", "phaser-turborepo.yaml"));
-  expect(profile.id).toBe("phaser-turborepo");
+test("shipped phaser-game profile validates", () => {
+  const profile = loadStackProfile(join(FORGE_ROOT, "profiles", "phaser-game.yaml"));
+  expect(profile.id).toBe("phaser-game");
   expect(profile.workspace.dirs.length).toBeGreaterThan(0);
 });
 
-test("shipped godot-csharp profile validates", () => {
-  const profile = loadStackProfile(join(FORGE_ROOT, "profiles", "godot-csharp.yaml"));
-  expect(profile.id).toBe("godot-csharp");
+test("shipped godot-game profile validates", () => {
+  const profile = loadStackProfile(join(FORGE_ROOT, "profiles", "godot-game.yaml"));
+  expect(profile.id).toBe("godot-game");
   expect(profile.workspace.dirs.length).toBeGreaterThan(0);
 });
 
 test("listStackProfiles finds all shipped profiles", () => {
   const profiles = listStackProfiles(FORGE_ROOT);
   const ids = profiles.map((p) => p.id).sort();
-  expect(ids).toContain("phaser-turborepo");
-  expect(ids).toContain("godot-csharp");
+  expect(ids).toContain("phaser-game");
+  expect(ids).toContain("godot-game");
   expect(ids).toContain("forge-shell");
 });
 
 test("all shipped profiles include @warpgogol/forge in install steps or package.json template", () => {
   const profiles = listStackProfiles(FORGE_ROOT);
   for (const profile of profiles) {
-    // knowledge-typescript-turborepo uses @warpgogol/werkstatt-knowledge plugin, not forge
-    if (profile.id === "knowledge-typescript-turborepo") continue;
+    // knowledge uses @warpgogol/werkstatt-knowledge plugin, not forge
+    if (profile.id === "knowledge") continue;
     const hasForgeInInstall = profile.install.some((cmd) => cmd.includes("@warpgogol/forge"));
     const pkgFile = profile.workspace.files.find((f) => f.path === "package.json");
     const hasForgeInPkg = pkgFile?.content.includes("@warpgogol/forge") ?? false;
@@ -174,8 +174,8 @@ test("all shipped profiles include @warpgogol/forge in install steps or package.
 test("all shipped profiles include operator-profile.md in .gitignore content", () => {
   const profiles = listStackProfiles(FORGE_ROOT);
   for (const profile of profiles) {
-    // knowledge-typescript-turborepo uses a different plugin and gitignore template
-    if (profile.id === "knowledge-typescript-turborepo") continue;
+    // knowledge uses a different plugin and gitignore template
+    if (profile.id === "knowledge") continue;
     const gitignoreFile = profile.workspace.files.find((f) => f.path === ".gitignore");
     expect(gitignoreFile).toBeDefined();
     expect(gitignoreFile?.content).toContain("operator-profile.md");

package/src/types.ts

@@ -9,8 +9,13 @@ can be registered in a Warpgogol kernel without direct dependency.</purpose>
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Initial canonical forge types: ForgeCommandInput, ForgeCommandResult, ForgeRuntimeContext, ForgeFlagSpec, Diagnostic, CommandRegistry, ForgeLogger.</item>
   <item>RFC-0518: add GateMetadata, GateSeverity, GatePhase, GateConditional types and optional gate field to ForgeCommandMetadata (structurally compatible with @warpgogol/site-kernel).</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/src/utils/fs-atomic.ts

@@ -7,8 +7,20 @@ file then renames, with bounded retry for Windows EPERM/EBUSY.</purpose>
   <item>Do not fall back to non-atomic writes — fail loudly.</item>
 </non-goals>
 </MODULE_CONTRACT>
+<KEY_DECISIONS>
+  <item>Writes go through temp-file plus rename so readers never observe partial content.</item>
+  <item>Bounded retry covers only Windows EPERM/EBUSY — every other failure is loud and immediate.</item>
+</KEY_DECISIONS>
 <CHANGE_SUMMARY>
-  <item>Moved from @warpgogol/site-kernel/fs-atomic to forge as canonical source (dependency inversion).</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>
+  <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/src/utils/fs-idempotent.ts

@@ -8,9 +8,22 @@ Reduces unnecessary disk writes and git churn in Compass and Werkstatt commands.
   <item>Do not fall back to non-atomic writes — fail loudly.</item>
 </non-goals>
 </MODULE_CONTRACT>
+<KEY_DECISIONS>
+  <item>Content is compared before writing — unchanged files cost zero disk I/O and zero git churn.</item>
+  <item>Idempotency composes on writeFileAtomic rather than reimplementing atomic writes.</item>
+</KEY_DECISIONS>
 <CHANGE_SUMMARY>
   <item>RFC-0556: moved from @warpgogol/site-kernel/fs-idempotent to forge as canonical source (dependency inversion).</item>
   <item>RFC-0603: extended to accept Uint8Array (Buffer) content for idempotent binary file writes — PNG preview images.</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>
+  <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/src/utils/fs-trash-sync.ts

@@ -8,8 +8,20 @@ code paths that cannot use the async `trash` npm package.</purpose>
   <item>Requires `trash-put` (trash-cli) installed on Linux/macOS. On Windows, uses PowerShell Recycle Bin API (no external binary needed).</item>
 </non-goals>
 </MODULE_CONTRACT>
+<KEY_DECISIONS>
+  <item>A synchronous shell-out exists only for call sites that cannot await — sync is a constraint, not a preference.</item>
+  <item>Windows goes through the PowerShell Recycle Bin API so no external binary is required there.</item>
+</KEY_DECISIONS>
 <CHANGE_SUMMARY>
-  <item>Initial implementation: sync wrapper for `trash-put` (Linux/macOS) and PowerShell Recycle Bin (Windows).</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>
+  <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/src/utils/fs-trash.ts

@@ -10,8 +10,20 @@ Windows.</purpose>
   <item>Do not use for ephemeral cleanup (lock files, temp files, atomic write leftovers) — those are system-internal and should use fs.unlink directly.</item>
 </non-goals>
 </MODULE_CONTRACT>
+<KEY_DECISIONS>
+  <item>Deletion targets the OS trash or recycle bin — recoverability is the contract, never permanent unlink.</item>
+  <item>The trash npm package is preferred over shelling out to trash-put on Linux.</item>
+</KEY_DECISIONS>
 <CHANGE_SUMMARY>
-  <item>Initial implementation: wraps npm `trash` package with glob disabled for safe path handling.</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>
+  <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/src/utils/fs.ts

@@ -1,13 +1,24 @@
 /*
 <MODULE_CONTRACT>
-<purpose>Trivial filesystem utilities — inlined from @warpgogol/share to avoid dependency.</purpose>
+<purpose>Trivial fs filesystem utilities — inlined from @warpgogol/share to avoid dependency.</purpose>
 <non-goals>
   <item>Do not add non-filesystem utilities here — use dedicated utility modules.</item>
   <item>Do not introduce @warpgogol/* imports — this package must remain dependency-free.</item>
 </non-goals>
 </MODULE_CONTRACT>
+<KEY_DECISIONS>
+  <item>Helpers are inlined copies, not imports — dependency-free beats sharing a package for trivial functions.</item>
+</KEY_DECISIONS>
 <CHANGE_SUMMARY>
-  <item>Initial inline of collectFiles, fileExists from @warpgogol/werkstatt-shared/share/fs.</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>
+  <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>
 */
 
@@ -32,7 +43,7 @@ export async function collectFiles(
   const results: string[] = [];
 
   // fs.walk.lint: allow — this is the canonical collectFiles implementation,
-  // inlined from @warpgogol/werkstatt-shared/share/fs to keep @warpgogol/forge dependency-free (RFC-0303).
+  // inlined from @warpgogol/werkstatt-shared/node/fs to keep @warpgogol/forge dependency-free (RFC-0303).
   async function walk(dir: string): Promise<void> {
     let entries;
     try {

package/src/utils/hash.ts

@@ -6,8 +6,19 @@
   <item>Do not introduce @warpgogol/* imports — this package must remain dependency-free.</item>
 </non-goals>
 </MODULE_CONTRACT>
+<KEY_DECISIONS>
+  <item>The hash helper is an inlined copy — one function does not justify a package dependency.</item>
+</KEY_DECISIONS>
 <CHANGE_SUMMARY>
-  <item>Initial inline of byteHash from @warpgogol/fingerprint/primitives.</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>
+  <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/src/utils/index.ts

@@ -1,13 +1,24 @@
 /*
 <MODULE_CONTRACT>
-<purpose>Barrel export for forge utilities — canonical, autonomous, no @warpgogol/* dependencies.</purpose>
+<purpose>Barrel index export for forge utilities — canonical, autonomous, no @warpgogol/* dependencies.</purpose>
 <non-goals>
   <item>Do not add non-utility exports here — use the appropriate forge module.</item>
   <item>Do not re-export from @warpgogol/* packages — this package must remain dependency-free.</item>
 </non-goals>
 </MODULE_CONTRACT>
+<KEY_DECISIONS>
+  <item>The barrel only re-exports — no logic lives here, so import cost stays flat.</item>
+</KEY_DECISIONS>
 <CHANGE_SUMMARY>
-  <item>Initial utility barrel: fs-atomic, generated-marker, string-utils, fs, hash.</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>
+  <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/src/utils/string-utils.ts

@@ -6,8 +6,19 @@
   <item>Do not introduce @warpgogol/* imports — this package must remain dependency-free.</item>
 </non-goals>
 </MODULE_CONTRACT>
+<KEY_DECISIONS>
+  <item>Helpers are inlined copies, not imports — dependency-free beats sharing a package for trivial functions.</item>
+</KEY_DECISIONS>
 <CHANGE_SUMMARY>
-  <item>Initial inline of toKebabCase from @warpgogol/werkstatt-shared/share/string-utils.</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>
+  <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>
 */