@warpgogol/forge 4.2.4 → 5.1.1

package/skills/meta/forge-bootstrap/SKILL.md

@@ -15,6 +15,20 @@ knowledge:
   - project-narrative-template.md
   - milestone-gallery/
 ---
+<!--
+<MODULE_CONTRACT>
+<purpose>forge-bootstrap skill — Configure a freshly created forge project — greenfield or transplant — with a barrier-free, creator-facing onboarding experience.</purpose>
+<non-goals>
+  <item>Do not execute skill logic — this document instructs agents; it is not runnable code.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <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>
+</CHANGE_SUMMARY>
+-->
+
 
 # forge-bootstrap
 

package/skills/meta/port-to-forge/SKILL.md

@@ -10,6 +10,20 @@ bindings:
   requires: []
   optional: [paths.invariantsFile]
 ---
+<!--
+<MODULE_CONTRACT>
+<purpose>port-to-forge skill — Port reusable patterns from project work into forge — identify pattern, grill operator about portability boundaries, create RFC/ADR if needed, scaffold, implement, validate, and update registry.</purpose>
+<non-goals>
+  <item>Do not execute skill logic — this document instructs agents; it is not runnable code.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <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>
+</CHANGE_SUMMARY>
+-->
+
 
 # port-to-forge
 

package/skills/meta/skill-create/SKILL.md

@@ -7,6 +7,20 @@ concerns: document-only
 dependsOn: ['grilling', 'writing-great-skills']
 languagePolicy: ref(PREFERENCES.md)
 ---
+<!--
+<MODULE_CONTRACT>
+<purpose>skill-create skill — Guides an agent through creating a new forge-compliant skill — determines category, invocation, concerns, dependencies, generates frontmatter, calls port.scaffold, and validates.</purpose>
+<non-goals>
+  <item>Do not execute skill logic — this document instructs agents; it is not runnable code.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <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>
+</CHANGE_SUMMARY>
+-->
+
 
 # skill-create
 

package/skills/shared/grilling/SKILL.md

@@ -10,6 +10,20 @@ knowledge:
   - qa-log.md
   - learned-principles.md
 ---
+<!--
+<MODULE_CONTRACT>
+<purpose>grilling skill — Grill the user relentlessly about a plan or design. Use when the user wants to stress-test a plan before building, or uses any 'grill' trigger phrases.</purpose>
+<non-goals>
+  <item>Do not execute skill logic — this document instructs agents; it is not runnable code.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <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>
+</CHANGE_SUMMARY>
+-->
+
 
 Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
 

package/skills/shared/my-preferences/SKILL.md

@@ -7,6 +7,20 @@ concerns: document-only
 dependsOn: []
 languagePolicy: ref(PREFERENCES.md)
 ---
+<!--
+<MODULE_CONTRACT>
+<purpose>my-preferences skill — Read, create, or edit the operator's preferences file at the repository root. Run when the operator wants to change language settings for AI conversations, grilling, or project documentation.</purpose>
+<non-goals>
+  <item>Do not execute skill logic — this document instructs agents; it is not runnable code.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <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>
+</CHANGE_SUMMARY>
+-->
+
 
 # my-preferences
 

package/skills/shared/windows-ai-tooling/SKILL.md

@@ -7,6 +7,20 @@ concerns: code-mutation
 dependsOn: []
 languagePolicy: ref(PREFERENCES.md)
 ---
+<!--
+<MODULE_CONTRACT>
+<purpose>windows-ai-tooling skill — Bootstrap a Windows project for AI agents. Installs verified tools, generates .gitattributes, and emits a command allow-list for agent prompts. Run when starting a new project or when agents fail.</purpose>
+<non-goals>
+  <item>Do not execute skill logic — this document instructs agents; it is not runnable code.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <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>
+</CHANGE_SUMMARY>
+-->
+
 
 # Windows AI Tooling
 

package/skills/shared/writing-great-skills/SKILL.md

@@ -7,6 +7,20 @@ concerns: read-only
 dependsOn: []
 languagePolicy: ref(PREFERENCES.md)
 ---
+<!--
+<MODULE_CONTRACT>
+<purpose>writing-great-skills skill — Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable.</purpose>
+<non-goals>
+  <item>Do not execute skill logic — this document instructs agents; it is not runnable code.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <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>
+</CHANGE_SUMMARY>
+-->
+
 
 Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
 

package/src/config/forge-config.ts

@@ -6,21 +6,16 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0391: initial forge-config module with zod schema, loadForgeConfig, resolveForgeRoot.</item>
-  <item>RFC-0393: added ForgeBindings schema, resolveBinding with placeholder substitution.</item>
-  <item>RFC-0538: added optional compass binding section (fileExtensions, testPatterns).</item>
-  <item>RFC-0537: added sessionsDir to paths and bindings.paths schemas.</item>
-  <item>RFC-0539: added ForgeSkillPack schema and skillPacks to forge config for project-declared skill packs.</item>
-  <item>RFC-0540: added implementStamp to bindings schema, FORGE_CLI_BINDING_DEFAULTS, PM_RUNNER_MAP, resolvePmRunner, applyCliBindingDefaults.</item>
-  <item>RFC-0540 fix: eliminated type casts — applyCliBindingDefaults returns ForgeBindings["commands"] directly, resolvePackageManager validates pm against enum.</item>
-  <item>RFC-0543: added optional forge.syncedVersion field to forgeConfigSchema and defaultForgeConfig for consumer upgrade tracking.</item>
-  <item>RFC-0546: added optional migrationAdapters field to forgeConfigSchema for migration-adapter registry discovery.</item>
-  <item>RFC-0639: added 5 semantic command keys (validate, produce, verify, preview, lint), terminology promoted from .optional() to .default({}), resolveTerminology function.</item>
-  <item>RFC-0640: added optional domain field to project section for domain-aware bootstrapping and health checks.</item>
-  <item>RFC-0643: added optional profile field to forgeConfigSchema and ForgeConfig; loadForgeConfig loads profiles/<id>.yaml when present.</item>
   <item>RFC-0661: added optional knowledge.budgets binding for hot/warm layer character budget overrides.</item>
   <item>RFC-0662: added optional knowledge.retentionDays and knowledge.staleDays bindings for compaction overrides.</item>
   <item>RFC-0704: added optional independentVersionPackages field to forgeConfigSchema for packages with autonomous npm versions.</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-0391, RFC-0393, RFC-0537, RFC-0538, RFC-0539, RFC-0540, RFC-0543, RFC-0546, RFC-0639, RFC-0640, RFC-0643</history>
 </CHANGE_SUMMARY>
 */
 
@@ -28,7 +23,11 @@ import fs from "node:fs";
 import path from "node:path";
 import { z } from "zod";
 import { parse as parseYaml } from "yaml";
-import { TERMINOLOGY_DEFAULTS } from "../profiles/profile-schema.ts";
+import {
+  TERMINOLOGY_DEFAULTS,
+  compassPolicyOverridesSchema,
+  type CompassPolicyOverrides,
+} from "../profiles/profile-schema.ts";
 import { listStackProfiles, type StackProfile } from "../profiles/stack-profile.ts";
 
 // ---------------------------------------------------------------------------
@@ -61,12 +60,9 @@ export const forgeBindingsSchema = z.object({
     sessionsDir: z.string().nullable().default(null),
   }),
   terminology: z.record(z.string(), z.string()).default({}),
-  compass: z
-    .object({
-      fileExtensions: z.array(z.string()).optional(),
-      testPatterns: z.array(z.string()).optional(),
-    })
-    .optional(),
+  // RFC-1096: consumer-level Compass policy overrides (same shape as the
+  // stack profile `compass:` section).
+  compass: compassPolicyOverridesSchema.optional(),
   // RFC-0661: optional knowledge layer character budget overrides
   // RFC-0662: optional retention/stale day overrides
   knowledge: z
@@ -115,10 +111,7 @@ export interface ForgeBindings {
     sessionsDir: string | null;
   };
   terminology: Record<string, string>;
-  compass?: {
-    fileExtensions?: string[];
-    testPatterns?: string[];
-  };
+  compass?: CompassPolicyOverrides;
   // RFC-0661: optional knowledge layer character budget overrides
   // RFC-0662: optional retention/stale day overrides
   knowledge?: {
@@ -440,6 +433,30 @@ export function resolveForgeRoot(workspaceRoot: string): string {
   );
 }
 
+/**
+ * Resolve the forge package root from inside the package's own modules.
+ * Handles both source layout (`src/<dir>/` → package root is two levels up)
+ * and compiled layout (`dist/src/<dir>/` → package root is three levels up)
+ * by walking up from `startDir` until a `package.json` is found.
+ *
+ * Use this for resolving package-shipped assets (templates, profiles) —
+ * `src/` and `profiles/` are both listed in package.json `files`, so they
+ * exist at the package root in the published tarball even though `tsc`
+ * never copies them into `dist/`.
+ */
+export function resolveForgePackageRoot(startDir: string): string {
+  let dir = startDir;
+  for (let i = 0; i < 6; i += 1) {
+    if (fs.existsSync(path.join(dir, "package.json"))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return startDir;
+}
+
 // ---------------------------------------------------------------------------
 // Binding resolver — RFC-0393
 // ---------------------------------------------------------------------------

package/src/forge-module.ts

@@ -8,8 +8,13 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0374: initial ForgeModule, ForgeModuleRegistry, ForgeCommandDefinition, ForgePipelineStep interfaces.</item>
-  <item>Forge autonomy refactor: ForgeCommandDefinition and ForgeCommandResult now reference canonical types from types.ts.</item>
   <item>RFC-0940: add optional runtime field to ForgeModule for autonomy declaration.</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/index.ts

@@ -1,13 +1,21 @@
 /*
 <MODULE_CONTRACT>
-<purpose>Public entrypoint for @warpgogol/forge — exports ForgeModule types, canonical types, utilities, skill schema, registry, validators, onboarding, and OS modules.</purpose>
+<purpose>Public index entrypoint for @warpgogol/forge — exports ForgeModule types, canonical types, utilities, skill schema, registry, validators, onboarding, and OS modules.</purpose>
 <non-goals>
   <item>Do not export internal implementation details — only public API.</item>
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0374: initial public exports for forge package.</item>
-  <item>Forge autonomy refactor: add canonical types and utils exports.</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/migration-adapters/git-utils.ts

@@ -8,8 +8,12 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0547: extract shared postSetup git logic from duplicated adapter implementations.</item>
-  <item>Replace fs.rmSync with trashSync for patch directory cleanup (trash bin for LLM-initiated deletions).</item>
-  <item>Use --initial-branch=main for all git init calls so new repos default to main instead of master.</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/migration-adapters/ignored-files.ts

@@ -7,7 +7,12 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Initial: discoverIgnoredFiles function that scans source for git-ignored files, categorizes them by type (config, data, runtime-state, cache, other), and returns sized categories for operator selection.</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/migration-adapters/index.ts

@@ -1,12 +1,15 @@
 /*
 <MODULE_CONTRACT>
-<purpose>Barrel export for migration-adapter module (RFC-0546).</purpose>
+<purpose>Barrel export for the migration-adapters module — public types and registry functions only (RFC-0546).</purpose>
 <non-goals>
   <item>Do not re-export implementation details — only public types and registry functions.</item>
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0546: initial barrel export for migration-adapters.</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>
 </CHANGE_SUMMARY>
 */
 

package/src/migration-adapters/types.ts

@@ -9,8 +9,12 @@
 <CHANGE_SUMMARY>
   <item>RFC-0546: initial migration-adapter type contracts (MigrationAdapter, AdapterAnalysis, MigrationResult, Conflict).</item>
   <item>RFC-0547: remove .git from DEFAULT_EXCLUDE_PATTERNS — git history handled by postSetup via format-patch + git am.</item>
-  <item>Re-add .git to DEFAULT_EXCLUDE_PATTERNS — copyDirectory copies into apps/<appName>/, not the project root; copying .git there creates a nested repo. Git history is handled by postSetup at the project root.</item>
-  <item>Add .env* to untracked-file transfer guarantee — the adapter copies ALL files on disk (including git-ignored), not just git-tracked files.</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/onboarding/agents-generate.ts

@@ -7,23 +7,23 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0391: initial forge.agents.generate handler.</item>
-  <item>RFC-0393: added Capabilities section rendered from resolved bindings.</item>
-  <item>RFC-0548: added Core behavioral layer section with intent-to-skill routing table from triggers, fixed policy text, and conditional extended layer (RFC-0549) based on register.</item>
-  <item>RFC-0549: replaced extended layer stub with full nine-section content from extended-behavioral-layer.ts.</item>
-  <item>RFC-0551: added register-conditional commit policy to core behavioral layer.</item>
-  <item>RFC-0611: added nested AGENTS.md generation for workspace directories + dryRun support.</item>
   <item>RFC-0640: load workspaceTypes from stack profile and pass to generateNestedAgentsMd for profile-driven workspace detection.</item>
   <item>RFC-0643: terminology substitution on final content, root template selection by register, details field in result.</item>
   <item>RFC-0664: added project memory layer read discipline section to generated AGENTS.md.</item>
-  <item>Profile-driven root AGENTS.md template via rootAgentsMdTemplate field — profiles can now provide stack-specific root templates instead of generic business/creative templates.</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-0391, RFC-0393, RFC-0548, RFC-0549, RFC-0551, RFC-0611</history>
 </CHANGE_SUMMARY>
 */
 
 import fs from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
-import { loadForgeConfig, resolveBinding, resolveForgeRoot } from "../config/forge-config.ts";
+import { loadForgeConfig, resolveBinding, resolveForgePackageRoot, resolveForgeRoot } from "../config/forge-config.ts";
 import { resolveAllTerminology } from "../profiles/terminology-utils.ts";
 import { FORGE_SKILLS } from "../registry.ts";
 import { buildGeneratedHeader, hasGeneratedMarker, writeFileIfChanged } from "../utils/index.ts";
@@ -58,13 +58,22 @@ export interface TemplateContext {
   workspaceType?: string;
 }
 
-// RFC-0643: Root template paths
-const BUSINESS_ROOT_TEMPLATE = path.join(import.meta.dirname, "templates", "root-agents-business.md");
-const CREATIVE_ROOT_TEMPLATE = path.join(import.meta.dirname, "templates", "root-agents-creative.md");
+// RFC-0643: Root template paths.
+// Templates ship in the tarball under src/onboarding/templates/ but tsc never
+// copies .md files into dist/ — resolve via the package root so both the source
+// layout (src/onboarding/) and compiled layout (dist/src/onboarding/) work.
+const TEMPLATES_DIR = path.join(
+  resolveForgePackageRoot(import.meta.dirname),
+  "src",
+  "onboarding",
+  "templates",
+);
+const BUSINESS_ROOT_TEMPLATE = path.join(TEMPLATES_DIR, "root-agents-business.md");
+const CREATIVE_ROOT_TEMPLATE = path.join(TEMPLATES_DIR, "root-agents-creative.md");
 
 // Behavioral layer template paths
-const BEHAVIORAL_LAYER_CORE_TEMPLATE = path.join(import.meta.dirname, "templates", "behavioral-layer-core.md");
-const BEHAVIORAL_LAYER_EXTENDED_TEMPLATE = path.join(import.meta.dirname, "templates", "behavioral-layer-extended.md");
+const BEHAVIORAL_LAYER_CORE_TEMPLATE = path.join(TEMPLATES_DIR, "behavioral-layer-core.md");
+const BEHAVIORAL_LAYER_EXTENDED_TEMPLATE = path.join(TEMPLATES_DIR, "behavioral-layer-extended.md");
 
 export function selectRootTemplate(
   register: BehavioralRegister,
@@ -75,7 +84,7 @@ export function selectRootTemplate(
     const templateRel = profile.rootAgentsMdTemplate;
     // Path traversal guard: reject absolute paths and ..
     if (!path.isAbsolute(templateRel) && !templateRel.includes("..")) {
-      const forgeRoot = path.resolve(import.meta.dirname, "..", "..");
+      const forgeRoot = resolveForgePackageRoot(import.meta.dirname);
       const profilesDir = path.join(forgeRoot, "profiles");
       const templatePath = path.resolve(profilesDir, templateRel);
       // Ensure resolved path is within profiles directory

package/src/onboarding/create.ts

@@ -9,15 +9,16 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0544: initial forge.create handler composing scaffold + init.</item>
-  <item>RFC-0544 fix: replace double cast on runInit return with proper InitResult typing.</item>
-  <item>RFC-0548: auto-run forge.agents.generate after init, update nextSteps to remove manual AGENTS.md step.</item>
-  <item>RFC-0550: write NEXT_STEPS.md into project root with creator-facing guidance (greenfield vs transplant via LLM).</item>
-  <item>RFC-0640: load profile domain fields and pass them to runInit for domain-aware bootstrapping.</item>
   <item>RFC-0643: pass profileId to runInit so forge.yaml gets a `profile` field.</item>
   <item>RFC-0664: scaffold memory layer (.agents/memory/) after init.</item>
   <item>RFC-0877: in-place mode only — --in-place flag required, no subdirectory creation, name derived from folder, strict empty-directory check (only .git/ tolerated).</item>
-  <item>Initialize git repo with --initial-branch=main if .git does not exist (hard guard for main branch default).</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-0544, RFC-0548, RFC-0550, RFC-0640</history>
 </CHANGE_SUMMARY>
 */
 

package/src/onboarding/doctor.ts

@@ -8,22 +8,16 @@ Checks for forge.yaml, AGENTS.md, PREFERENCES.md, .agents/skills/, docs/rfcs/,
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Initial forge.doctor handler for autonomy refactor.</item>
-  <item>RFC-0391: added @warpgogol/* forbidden-imports autonomy guard.</item>
-  <item>RFC-0393: added bindings validation — resolved/absent/invalid reporting.</item>
-  <item>RFC-0524: added stale knowledge file detection — compares source and .agents/ copies.</item>
-  <item>RFC-0539: extended knowledge file check to iterate pack skills via discoverPackSkills. Added pack-skills check for stale/missing copies and skillPacks config validation.</item>
-  <item>RFC-0540: added defaultable-binding-null notices for forge-CLI-backed bindings.</item>
-  <item>RFC-0611: added nested AGENTS.md checks — missing, stale (dryRun comparison), hand-written improvement.</item>
-  <item>RFC-0640: added domain reporting, invariant listing (reported-only), terminology resolution, --strict flag, and software-specific check skipping for non-software domains.</item>
-  <item>RFC-0675: upgraded domain-invariants check from advisory to enforcement using invariant engine.</item>
-  <item>RFC-0660: added legacy-section count reporting for structured knowledge files.</item>
-  <item>RFC-0661: added knowledge-budgets check — validates override shape, computes per-skill budget reports, reports summary with headroom %.</item>
-  <item>RFC-0663: added knowledge-duplicates check (cross-skill L2 duplicate detection) and shared-knowledge-file check (schema/id uniqueness for the shared layer).</item>
   <item>RFC-0664: added memory-layer health check (budget usage, gitignore coverage, daily-file leak risk).</item>
   <item>RFC-0704: added independent-version-packages check — validates that paths in independentVersionPackages exist and contain package.json.</item>
   <item>RFC-0941: added pack-manifests advisory check — validates forge.plugin.yaml existence and schema for each declared skill pack.</item>
-  <item>Added git-branch check — warns when current branch is 'master' instead of 'main'.</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-0391, RFC-0393, RFC-0524, RFC-0539, RFC-0540, RFC-0611, RFC-0640, RFC-0660, RFC-0661, RFC-0663, RFC-0675</history>
 </CHANGE_SUMMARY>
 */
 

package/src/onboarding/init.ts

@@ -7,21 +7,16 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0374: initial forge.init handler.</item>
-  <item>RFC-0391: reworked to be config-driven — creates forge.yaml, uses resolveForgeRoot, creates docs/plans/ and docs/audits/ directories.</item>
-  <item>RFC-0392: added --from flag for stack detection from existing project or spec folder.</item>
-  <item>RFC-0393: defaultForgeConfig now includes default bindings section (all commands null, default paths).</item>
-  <item>RFC-0524: extended skill sync to copy declared knowledge files alongside SKILL.md.</item>
-  <item>RFC-0539: extended skill sync to also copy declared pack skills from skillPacks config.</item>
-  <item>RFC-0543: write forge.syncedVersion on first init (set to installed forge version).</item>
-  <item>RFC-0544: accept optional context.forgeRoot to support composition from forge.create.</item>
-  <item>RFC-0544 fix: export InitResult interface for type-safe consumption by forge.create.</item>
-  <item>RFC-0552: add skippedSkills to InitResult, detect Forge-vs-pack skill name conflicts.</item>
-  <item>RFC-0640: accept optional domain fields from profile (register, domain, terminology, semanticBindings) and write them into PREFERENCES.md and forge.yaml.</item>
-  <item>RFC-0643: accept optional profileId and write it to forge.yaml as the `profile` field.</item>
   <item>RFC-0663: added syncSharedKnowledge step to sync shared knowledge layer to .agents/skills/shared-knowledge/.</item>
   <item>RFC-0941: create forge.plugin.yaml manifests for skill packs that lack them before calling discoverPackSkills.</item>
   <item>RFC-1019: extend PREFERENCES.md with formOfAddress, session-end protocol, skill invocation tracking, plan confirmation vs implementation, commit granularity rules.</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-0391, RFC-0392, RFC-0393, RFC-0524, RFC-0539, RFC-0543, RFC-0544, RFC-0552, RFC-0640, RFC-0643</history>
 </CHANGE_SUMMARY>
 */
 

package/src/onboarding/invariant-engine.ts

@@ -7,11 +7,16 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0675: initial invariant enforcement engine with three check kinds.</item>
   <item>RFC-0691: add html-attribute-pattern check kind for HTML attribute value validation.</item>
   <item>RFC-0694: replace html-attribute-pattern with attribute-pattern (elements array) for HTML+JSX support.</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 — 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-0675</history>
 </CHANGE_SUMMARY>
 */
 

package/src/onboarding/nested-agents-generate.ts

@@ -10,11 +10,16 @@ runAgentsGenerate, runUpgrade, and runDoctor (staleness check via dryRun).</purp
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0611: initial shared nested generation function with dryRun support.</item>
-  <item>Enriched template: read package.json metadata and pass to buildNestedAgentsMd for content-rich output.</item>
   <item>RFC-0640: accept optional workspaceTypes from profile and pass to discoverWorkspaces for profile-driven detection.</item>
   <item>RFC-0643: return workspaceTypeMap for per-file workspace type metadata in details field.</item>
   <item>RFC-0643: use selectNestedTemplate for profile-driven nested templates with terminology substitution.</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-0611</history>
 </CHANGE_SUMMARY>
 */
 

package/src/onboarding/nested-agents-templates.ts

@@ -9,12 +9,18 @@ content-rich AGENTS.md for a workspace from its package.json metadata. No I/O.</
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0611: initial minimal stub template for app, package, service workspaces.</item>
-  <item>Enriched template: render package name, description, entry points, scripts, and dependencies from package.json metadata instead of a minimal stub.</item>
   <item>RFC-0643: selectNestedTemplate() for profile-driven template selection with path traversal guard.</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>
 */
 
 import { buildGeneratedHeader } from "../utils/index.ts";
+import { resolveForgePackageRoot } from "../config/forge-config.ts";
 import type { ForgeConfig } from "../config/forge-config.ts";
 import type { WorkspaceDir, WorkspaceType } from "./workspace-discovery.ts";
 import type { ProfileWorkspaceType } from "../profiles/profile-schema.ts";
@@ -146,8 +152,10 @@ export function selectNestedTemplate(
     return fallback;
   }
 
-  // Resolve relative to profiles/ directory (where profile YAMLs live)
-  const forgeRoot = path.resolve(import.meta.dirname, "..", "..");
+  // Resolve relative to profiles/ directory (where profile YAMLs live).
+  // import.meta.dirname points at dist/src/onboarding/ in the compiled package —
+  // resolve the package root so profiles/ is found in both src and dist layouts.
+  const forgeRoot = resolveForgePackageRoot(import.meta.dirname);
   const profilesDir = path.join(forgeRoot, "profiles");
   const templatePath = path.resolve(profilesDir, templateRel);
 

package/src/onboarding/scaffold-project.ts

@@ -9,7 +9,12 @@
 <CHANGE_SUMMARY>
   <item>RFC-0392: initial forge.scaffold handler.</item>
   <item>RFC-0542: populate nextSteps in forge.scaffold result.</item>
-  <item>Add __PROJECT_NAME__ placeholder replacement for workspace files; profiles now include root package.json with scripts (clean, format, test, upgrade-packages) and scripts/clean.mjs.</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>
 */