@warpgogol/forge 4.2.3 → 5.1.0

package/docs/reference/forge-yaml.md

@@ -31,18 +31,18 @@ syncedVersion: 4.1.6
 
 ## project
 
-| Field | Type | Required | Description |
-| --- | --- | --- | --- |
-| `name` | string | yes | Project name, used in generated AGENTS.md and CI |
-| `stack` | string[] | yes | Stack identifiers (e.g. `[typescript]`, `[phaser]`) |
-| `packageManager` | string | yes | Package manager (`pnpm` only) |
+| Field            | Type     | Required | Description                                         |
+| ---------------- | -------- | -------- | --------------------------------------------------- |
+| `name`           | string   | yes      | Project name, used in generated AGENTS.md and CI    |
+| `stack`          | string[] | yes      | Stack identifiers (e.g. `[typescript]`, `[phaser]`) |
+| `packageManager` | string   | yes      | Package manager (`pnpm` only)                       |
 
 ## paths
 
-| Field | Default | Description |
-| --- | --- | --- |
-| `rfcsDir` | `docs/rfcs` | Directory for RFC files |
-| `adrsDir` | `docs/adrs` | Directory for ADR files |
+| Field       | Default          | Description                   |
+| ----------- | ---------------- | ----------------------------- |
+| `rfcsDir`   | `docs/rfcs`      | Directory for RFC files       |
+| `adrsDir`   | `docs/adrs`      | Directory for ADR files       |
 | `skillsDir` | `.agents/skills` | Directory for deployed skills |
 
 ## bindings.commands
@@ -77,6 +77,35 @@ bindings:
     invariants: DNA
 ```
 
+## bindings.compass
+
+Optional. Consumer-level Compass policy overrides (RFC-1096). The same shape is available to stack profiles via their `compass:` section — resolution order is generic defaults → profile `compass:` → `bindings.compass`.
+
+```yaml
+bindings:
+  compass:
+    fileExtensions: [.ts, .tsx, ".svelte", "!.astro"]
+    testPatterns: ["**/*.test.ts", "test/**"]
+    scanRoots: [packages, services]
+    ignoredDirs: [spec, todo]
+    ignoredDirPrefixes: ["old-", "-"]
+    highRiskPaths: ["packages/engine/src/kernel/**"]
+    idPattern: "\\b([A-Z][A-Z0-9]*-)+\\d+\\b"
+    purposeBoilerplatePatterns: ["^(this file|the file)\\b"]
+    layerRules:
+      - { pattern: "src/pages/**", layer: page, risk: medium }
+    workspaceKinds: { apps: app, packages: package, services: service }
+    excludedPaths:
+      - { pattern: "src/templates/**", reason: template-source }
+```
+
+Merge semantics per key:
+
+- **Union-merge** (`fileExtensions`, `testPatterns`, `ignoredDirs`, `ignoredDirPrefixes`, `highRiskPaths`, `excludedPaths`): values merge with the generic defaults; an entry prefixed with `!` removes it (for `excludedPaths`, `!` matches on `pattern`).
+- **Replace** (`scanRoots`, `idPattern`, `purposeBoilerplatePatterns`, `layerRules`, `workspaceKinds`): the consumer value replaces the whole list — repeat generic entries you still need.
+
+`idPattern` must compile and match the `NAMESPACE-NUMBER` probe `ABC-123`, otherwise `resolveCompassPolicy` throws `CompassPolicyConfigError` naming the key. `layerRules` are evaluated first-match on the workspace-relative path; `highRiskPaths` are picomatch globs on the root-relative path that force `riskClass: high`. `excludedPaths` mark matching files `authoringStatus: excluded` with the given `reason` (they are still inventoried).
+
 ## skillPacks
 
 Optional. Declares project-local skill packs:

package/os/adr/handlers/list-create.ts

@@ -1,6 +1,6 @@
 /*
 <MODULE_CONTRACT>
-<purpose>ADR list and create handlers mirroring the RFC domain.</purpose>
+<purpose>ADR list and create command handlers mirroring the RFC domain lifecycle for architecture decision records.</purpose>
 <non-goals>
   <item>Do not introduce app-specific runtime composition or deployment behavior.</item>
 </non-goals>
@@ -8,6 +8,9 @@
 <CHANGE_SUMMARY>
   <item>RFC-0366: create ADR list and create handlers mirroring the RFC domain.</item>
   <item>RFC-0521: migrated from packages/os/site-kernel/src/adr/ to packages/forge/os/adr/.</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/os/adr/handlers/validate.ts

@@ -7,9 +7,14 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0366: implement fail-hard ADR validation for the new adrModule.</item>
-  <item>Post-refactor hardening: allow ADRs to be superseded by existing RFC decisions.</item>
   <item>RFC-0521: migrated from packages/os/site-kernel/src/adr/ to packages/forge/os/adr/.</item>
   <item>RFC-0722: add ADR-DIR-01 directory structure warning rule for unsanctioned subdirectories.</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/adr/types.ts

@@ -11,12 +11,16 @@ statuses, scopes, frontmatter shape, validation results, and list output.
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0366: introduce ADR types and constants mirroring the RFC domain contract.</item>
-  <item>RFC-0367: extend AdrStatus with reviewing and implemented; add implementedAt, closedAt, reviewers fields.</item>
-  <item>Post-refactor hardening: document that an ADR may be superseded by a broader RFC.</item>
   <item>RFC-0521: migrated from packages/os/site-kernel/src/adr/ to packages/forge/os/adr/.</item>
   <item>RFC-0727: add AdrImplementStamp types for atomic ADR status transition.</item>
   <item>RFC-0996: add AV-17 acceptance criteria completeness check for implemented post-cutoff ADRs.</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-0366, RFC-0367</history>
 </CHANGE_SUMMARY>
 */
 

package/os/compass/compass.module.ts

@@ -9,6 +9,10 @@
   <item>RFC-0374: initial forgeCompassModule registering 12 compass commands.</item>
   <item>RFC-0538: renamed compass.changesummary.tidy to compass.summary.trim, removed compass.annotate, compass.clear, compass.markup.migrate, compass.invariant.add.</item>
   <item>RFC-0556: removed dynamic import of @warpgogol/site-kernel-checks, all handlers now inlined in forge/os/compass/handlers/.</item>
+  <item>RFC-1095: compass.summary.record, trim repair rewrite, commit integration</item>
+  <item>RFC-1097: steps 1-4 — compass.migrate codemod
+
+Add the v1 to v2 Compass header codemod: migrateFile pure transform (collapse, strip, seed, reorder, purpose-flag actions), migrateWorkspace walker, runCompassMigrate handler with dirty-tree refusal and --force/--files/--dry-run flags, module registration, and 15 unit tests.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -21,10 +25,9 @@ import {
   runCompassAuditBaseline,
   runCompassAuditValidate,
 } from "./handlers/compass-audit-handler.ts";
-import {
-  runCompassChangeSummaryValidate,
-  runCompassSummaryTrim,
-} from "./handlers/compass-change-summary-handler.ts";
+import { runCompassSummaryTrim } from "./handlers/compass-change-summary-handler.ts";
+import { runCompassSummaryRecord } from "./handlers/summary-record.ts";
+import { runCompassMigrate } from "./handlers/compass-migrate-handler.ts";
 
 const compassScanFlags = {
   packages: {
@@ -33,7 +36,7 @@ const compassScanFlags = {
   },
   package: {
     kind: "string",
-    description: "With --packages, scan one package by directory/name.",
+    description: "Scan one package by directory/name (implies --packages).",
   },
   workpiece: {
     kind: "string",
@@ -85,25 +88,47 @@ export const forgeCompassModule: ForgeModule = {
       execute: runCompassValidation,
     },
     {
-      name: "compass.changesummary.validate",
-      contract: "compass",
-      rules: [],
+      name: "compass.summary.record",
       description:
-        "Validate CHANGE_SUMMARY blocks for boilerplate items and over-cap unprotected items (RFC-0349).",
+        "Append a governance-referencing item to each target file's CHANGE_SUMMARY and collapse the 5-item window into <history> (RFC-1095). Invoked by commit commands when a commit carries an RFC/ADR reference.",
       scope: "workspace",
+      mutatesState: true,
       supportsAllSites: true,
-      flags: { ...compassScanFlags, mode: compassModeFlag },
+      writes: [
+        "apps/**/*.{astro,ts,tsx,js,mjs,css,cs,tscn,tres,gd,md}",
+        "packages/**/*.{astro,ts,tsx,js,mjs,css,cs,tscn,tres,gd,md}",
+        "services/**/*.{ts,tsx,js,mjs,css,cs,tscn,tres,gd,md}",
+      ],
       reads: [
         "packages/**/*.{ts,tsx,astro,js,mjs,css,cs,tscn,tres,gd,md}",
         "apps/**/*.{ts,tsx,astro,js,mjs,css,cs,tscn,tres,gd,md}",
         "services/**/*.{ts,tsx,astro,js,mjs,css,cs,tscn,tres,gd,md}",
       ],
-      execute: runCompassChangeSummaryValidate,
+      cacheable: false,
+      flags: {
+        ...compassScanFlags,
+        id: {
+          kind: "string",
+          required: true,
+          description: "Governance ID to record (e.g. RFC-1095, ADR-0042).",
+        },
+        files: {
+          kind: "string[]",
+          description:
+            "Target files (repo-relative, or workpiece-relative with --workpiece). Commit integrations pass the commit's changed-file set.",
+        },
+        text: {
+          kind: "string",
+          description:
+            "Item description. Default: commit subject minus conventional prefix; bare ID outside commit context.",
+        },
+      },
+      execute: runCompassSummaryRecord,
     },
     {
       name: "compass.summary.trim",
       description:
-        "Deterministically trim CHANGE_SUMMARY blocks: remove boilerplate, cap total items to 30, preserve protected items (RFC-0538).",
+        "Repair CHANGE_SUMMARY blocks to the v2 shape: collapse described items past 5 into <history>, remove ID-less items, normalize <history> (RFC-1095).",
       scope: "workspace",
       mutatesState: true,
       supportsAllSites: true,
@@ -118,9 +143,50 @@ export const forgeCompassModule: ForgeModule = {
         "services/**/*.{ts,tsx,astro,js,mjs,css,cs,tscn,tres,gd,md}",
       ],
       cacheable: false,
-      flags: { ...compassScanFlags },
+      flags: {
+        ...compassScanFlags,
+        mode: {
+          kind: "string",
+          description: "Repair mode: repair (default, only mode — reserved for future modes).",
+        },
+      },
       execute: runCompassSummaryTrim,
     },
+    {
+      name: "compass.migrate",
+      description:
+        "Rewrite authored file headers to the Compass v2 shape (RFC-1097): collapse CHANGE_SUMMARY into <history>, strip forbidden v1 blocks, seed KEY_DECISIONS from @ai-invariant comments, reorder blocks canonically. Refuses a dirty git tree unless --force.",
+      scope: "workspace",
+      mutatesState: true,
+      supportsAllSites: true,
+      writes: [
+        "apps/**/*.{astro,ts,tsx,js,mjs,css,cs,tscn,tres,gd,md}",
+        "packages/**/*.{astro,ts,tsx,js,mjs,css,cs,tscn,tres,gd,md}",
+        "services/**/*.{ts,tsx,js,mjs,css,cs,tscn,tres,gd,md}",
+      ],
+      reads: [
+        "packages/**/*.{ts,tsx,astro,js,mjs,css,cs,tscn,tres,gd,md}",
+        "apps/**/*.{ts,tsx,astro,js,mjs,css,cs,tscn,tres,gd,md}",
+        "services/**/*.{ts,tsx,astro,js,mjs,css,cs,tscn,tres,gd,md}",
+      ],
+      cacheable: false,
+      flags: {
+        ...compassScanFlags,
+        files: {
+          kind: "string[]",
+          description: "Explicit root-relative file list — bypasses scan-root filtering entirely.",
+        },
+        "dry-run": {
+          kind: "boolean",
+          description: "Print the action manifest without writing any file.",
+        },
+        force: {
+          kind: "boolean",
+          description: "Override the dirty-tree refusal.",
+        },
+      },
+      execute: runCompassMigrate,
+    },
     {
       name: "compass.audit.plan",
       description:

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

@@ -21,6 +21,7 @@ import { resolve, relative } from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { createCompassInventoryEntries } from "./compass-inventory.ts";
+import { resolveCompassPolicy } from "../policy.ts";
 import { resolveCompassScanRoot } from "./resolve-scan-root.ts";
 import { getRevisionByPath } from "./git-revision.ts";
 import type { CompassInventoryEntry } from "./compass-inventory.ts";
@@ -139,7 +140,13 @@ export async function runCompassAuditPlan(
   }>
 > {
   const scanRoot = resolveCompassScanRoot(input, context);
-  const entries = await createCompassInventoryEntries(context.workspaceRoot, input, scanRoot);
+  const policy = resolveCompassPolicy(context.workspaceRoot, context.forgeRoot);
+  const entries = await createCompassInventoryEntries(
+    context.workspaceRoot,
+    input,
+    scanRoot,
+    policy,
+  );
   const authored = getAuthoredEntries(entries);
   const ledger = await loadLedger(context.workspaceRoot);
 
@@ -283,7 +290,13 @@ export async function runCompassAuditBaseline(
   }>
 > {
   const scanRoot = resolveCompassScanRoot(input, context);
-  const entries = await createCompassInventoryEntries(context.workspaceRoot, input, scanRoot);
+  const policy = resolveCompassPolicy(context.workspaceRoot, context.forgeRoot);
+  const entries = await createCompassInventoryEntries(
+    context.workspaceRoot,
+    input,
+    scanRoot,
+    policy,
+  );
   const authored = getAuthoredEntries(entries);
   const ledger = await loadLedger(context.workspaceRoot);
 
@@ -347,7 +360,13 @@ export async function runCompassAuditValidate(
 > {
   const strict = input.flags["strict"] === true;
   const scanRoot = resolveCompassScanRoot(input, context);
-  const entries = await createCompassInventoryEntries(context.workspaceRoot, input, scanRoot);
+  const policy = resolveCompassPolicy(context.workspaceRoot, context.forgeRoot);
+  const entries = await createCompassInventoryEntries(
+    context.workspaceRoot,
+    input,
+    scanRoot,
+    policy,
+  );
   const authored = getAuthoredEntries(entries);
   const ledger = await loadLedger(context.workspaceRoot);