@warpgogol/forge 5.2.3 → 5.3.0

package/os/compass/compass.module.ts

@@ -6,13 +6,14 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <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>
+  <item>RFC-1173: declare mutatesState on all kernel commands — collectDeclarationDiagnostics emits error-severity MUTATES-STATE-DECLARED, command.manifest.validate is the blocking consumer in packages.check, sweep declares the flag on every command definition (factories hardcode false for read-only check specs)</item>
+  <history>RFC-0374</history>
 </CHANGE_SUMMARY>
 */
 
@@ -59,6 +60,7 @@ export const forgeCompassModule: ForgeModule = {
   commands: [
     {
       name: "compass.inventory",
+      mutatesState: true,
       description: "Generate the repository-wide Compass source inventory XML report.",
       scope: "workspace",
       supportsAllSites: true,
@@ -72,6 +74,7 @@ export const forgeCompassModule: ForgeModule = {
     },
     {
       name: "compass.validate",
+      mutatesState: false,
       contract: "compass",
       rules: [],
       description:
@@ -99,6 +102,7 @@ export const forgeCompassModule: ForgeModule = {
         "packages/**/*.{astro,ts,tsx,js,mjs,css,cs,tscn,tres,gd,md}",
         "services/**/*.{ts,tsx,js,mjs,css,cs,tscn,tres,gd,md}",
       ],
+      generates: [],
       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}",
@@ -137,6 +141,7 @@ export const forgeCompassModule: ForgeModule = {
         "packages/**/*.{astro,ts,tsx,js,mjs,css,cs,tscn,tres,gd,md}",
         "services/**/*.{ts,tsx,js,mjs,css,cs,tscn,tres,gd,md}",
       ],
+      generates: [],
       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}",
@@ -164,6 +169,7 @@ export const forgeCompassModule: ForgeModule = {
         "packages/**/*.{astro,ts,tsx,js,mjs,css,cs,tscn,tres,gd,md}",
         "services/**/*.{ts,tsx,js,mjs,css,cs,tscn,tres,gd,md}",
       ],
+      generates: [],
       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}",
@@ -189,6 +195,8 @@ export const forgeCompassModule: ForgeModule = {
     },
     {
       name: "compass.audit.plan",
+      mutatesState: false,
+      execOnReadOnly: true,
       description:
         "Emit a deterministic work-order of files whose revision has advanced past the threshold since their last Compass audit (RFC-0352). Read-only, no LLM.",
       scope: "workspace",
@@ -210,12 +218,14 @@ export const forgeCompassModule: ForgeModule = {
     },
     {
       name: "compass.audit.record",
+      modulePath: "packages/forge/os/compass/compass.module.ts",
       description:
         "Stamp a file's audit verdict and current revision into the compass-audit ledger (RFC-0352). Mutating. Required flags: `--file`, `--verdict`.",
       scope: "workspace",
       mutatesState: true,
       supportsAllSites: true,
       writes: ["docs/compass-audit-ledger.generated.yaml"],
+      generates: [{ path: "docs/compass-audit-ledger.generated.yaml", phase: "on-demand" }],
       reads: ["docs/compass-audit-ledger.generated.yaml"],
       cacheable: false,
       flags: {
@@ -231,12 +241,16 @@ export const forgeCompassModule: ForgeModule = {
     },
     {
       name: "compass.audit.baseline",
+      modulePath: "packages/forge/os/compass/compass.module.ts",
       description:
         "Seed the compass-audit ledger for every authored file at its current revision with verdict=baseline (RFC-0352). One-time bootstrap.",
       scope: "workspace",
       mutatesState: true,
       supportsAllSites: true,
       writes: ["docs/compass-audit-ledger.generated.yaml"],
+      // Artifact ownership is claimed by compass.audit.record (GENERATES-PATH-
+      // COLLISION forbids two owners on a non-glob path); baseline only writes it.
+      generates: [],
       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}",
@@ -248,6 +262,8 @@ export const forgeCompassModule: ForgeModule = {
     },
     {
       name: "compass.audit.validate",
+      mutatesState: false,
+      execOnReadOnly: true,
       contract: "compass",
       rules: [],
       description:

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

@@ -18,9 +18,9 @@ mode (RFC-0556). Drives per-file semantic-truth auditing on a revision cadence (
 </CHANGE_SUMMARY>
 */
 
-import { mkdir, readFile } from "node:fs/promises";
 import { resolve, relative } from "node:path";
-import { execFile, execFileSync } from "node:child_process";
+import { ambientIo, resolveIo } from "../../../src/utils/io.ts";
+import { execFile, execFileSync } from "../../../src/utils/sync-fs.ts";
 import { promisify } from "node:util";
 import { createCompassInventoryEntries } from "./compass-inventory.ts";
 import { resolveCompassPolicy } from "../policy.ts";
@@ -36,6 +36,10 @@ import type {
 } from "../../../src/types.ts";
 import { parse as yamlParse, stringify as yamlStringify } from "yaml";
 
+// Ambient default for helper fns without a context param — handlers override
+// with `const io = resolveIo(context.io)` inside their own scope.
+const io = ambientIo;
+
 const execFileAsync = promisify(execFile);
 const LEDGER_PATH = "docs/compass-audit-ledger.generated.yaml";
 const DEFAULT_THRESHOLD = 30;
@@ -93,7 +97,7 @@ function withLedgerAdvisory(ledger: Partial<CompassAuditLedger>): CompassAuditLe
 async function loadLedger(workspaceRoot: string): Promise<CompassAuditLedger> {
   const abs = resolve(workspaceRoot, LEDGER_PATH);
   try {
-    const content = await readFile(abs, "utf8");
+    const content = await io.readFile(abs);
     return withLedgerAdvisory(yamlParse(content) as Partial<CompassAuditLedger>);
   } catch {
     return withLedgerAdvisory({});
@@ -104,7 +108,7 @@ async function saveLedger(workspaceRoot: string, ledger: CompassAuditLedger): Pr
   const normalized = withLedgerAdvisory(ledger);
   normalized.entries.sort((a, b) => a.path.localeCompare(b.path));
   const abs = resolve(workspaceRoot, LEDGER_PATH);
-  await mkdir(resolve(abs, ".."), { recursive: true });
+  await io.mkdir(resolve(abs, ".."));
   const header = buildGeneratedHeader({
     ownerCommand: "compass.audit.record",
     filePath: LEDGER_PATH,
@@ -194,6 +198,7 @@ export async function runCompassAuditPlan(
     skippedIneligible: number;
   }>
 > {
+  const io = resolveIo(context.io);
   const scanRoot = resolveCompassScanRoot(input, context);
   const policy = resolveCompassPolicy(context.workspaceRoot, context.forgeRoot);
   const entries = await createCompassInventoryEntries(
@@ -238,7 +243,7 @@ export async function runCompassAuditPlan(
     }
 
     const absPath = resolve(context.workspaceRoot, entry.path);
-    const source = await readFile(absPath, "utf8");
+    const source = await io.readFile(absPath);
     const moduleContract = extractBlock(source, "MODULE_CONTRACT");
     const keyDecisions = extractBlock(source, "KEY_DECISIONS");
     const changeSummary = extractBlock(source, "CHANGE_SUMMARY");
@@ -285,6 +290,7 @@ export async function runCompassAuditRecord(
     action: "recorded";
   }>
 > {
+  const _io = resolveIo(context.io);
   const rawFilePath = input.flags["file"] as string | undefined;
   const verdict = input.flags["verdict"] as CompassAuditVerdict | undefined;
   const agentFlag = input.flags["agent"] as string | undefined;
@@ -366,6 +372,7 @@ export async function runCompassAuditBaseline(
     total: number;
   }>
 > {
+  const _io = resolveIo(context.io);
   const scanRoot = resolveCompassScanRoot(input, context);
   const policy = resolveCompassPolicy(context.workspaceRoot, context.forgeRoot);
   const entries = await createCompassInventoryEntries(
@@ -444,6 +451,7 @@ export async function runCompassAuditValidate(
     skippedPaths: string[];
   }>
 > {
+  const _io = resolveIo(context.io);
   const strict = input.flags["strict"] === true;
   const scanRoot = resolveCompassScanRoot(input, context);
   const policy = resolveCompassPolicy(context.workspaceRoot, context.forgeRoot);

package/os/compass/handlers/compass-change-summary-handler.ts

@@ -20,7 +20,8 @@
 */
 
 import { resolve } from "node:path";
-import { readFile } from "node:fs/promises";
+import { resolveIo } from "../../../src/utils/io.ts";
+
 import { createCompassInventoryEntries } from "./compass-inventory.ts";
 import { resolveCompassPolicy } from "../policy.ts";
 import { resolveCompassScanRoot } from "./resolve-scan-root.ts";
@@ -49,6 +50,7 @@ export async function runCompassSummaryTrim(
     files: Array<{ path: string; removed: string[]; kept: number }>;
   }>
 > {
+  const io = resolveIo(context.io);
   const mode = input.flags["mode"];
   if (mode !== undefined && mode !== "repair") {
     context.logger.error(
@@ -83,7 +85,7 @@ export async function runCompassSummaryTrim(
     }
 
     const absPath = resolve(context.workspaceRoot, entry.path);
-    const source = await readFile(absPath, "utf8");
+    const source = await io.readFile(absPath);
     const blockMatch = source.match(CHANGE_SUMMARY_BLOCK_RE);
     if (!blockMatch) continue;
 

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

@@ -26,7 +26,8 @@ Sweep batch 2: real KEY_DECISIONS on 10 files, expanded purposes (CONTRACT-02/PU
 */
 
 import { resolve } from "node:path";
-import { readFile } from "node:fs/promises";
+import { resolveIo } from "../../../src/utils/io.ts";
+
 import {
   createCompassInventoryEntries,
   evaluateV2Rules,
@@ -267,6 +268,7 @@ export async function runCompassInventory(
     policySource: CompassPolicySource;
   }>
 > {
+  const _io = resolveIo(context.io);
   const scanRoot = resolveCompassScanRoot(input, context) ?? context.workspaceRoot;
   const policy = resolveCompassPolicy(scanRoot, context.forgeRoot);
   const entries = await createCompassInventoryEntries(scanRoot, input, undefined, policy);
@@ -332,6 +334,7 @@ export async function runCompassValidation(
     }>;
   }>
 > {
+  const io = resolveIo(context.io);
   const scanRoot = resolveCompassScanRoot(input, context);
   let mode: ReturnType<typeof resolveCompassMode>;
   try {
@@ -383,7 +386,7 @@ export async function runCompassValidation(
   );
   for (const entry of authoredEntries) {
     const absPath = resolve(context.workspaceRoot, entry.path);
-    const source = getEntrySource(entry) ?? (await readFile(absPath, "utf8"));
+    const source = getEntrySource(entry) ?? (await io.readFile(absPath));
     for (const v2 of evaluateV2Rules(entry, source, policy)) {
       if (!V2_VALIDATE_RULE_PREFIXES.some((prefix) => v2.ruleId.startsWith(prefix))) {
         continue;
@@ -449,7 +452,7 @@ export async function runCompassValidation(
     }
 
     const absPath = resolve(context.workspaceRoot, entry.path);
-    const source = await readFile(absPath, "utf8");
+    const source = await io.readFile(absPath);
     if (TODO_COMPASS_RE.test(source)) {
       context.logger.error(
         `[compass.validate] COMPASS-TODO-01: ${entry.path}: unfilled ${compassTodoLabel} sentinel in Compass block`,
@@ -496,7 +499,7 @@ export async function runCompassValidation(
       if (applicableSpecs.length === 0) continue;
 
       const absPath = resolve(context.workspaceRoot, entry.path);
-      const source = await readFile(absPath, "utf8");
+      const source = await io.readFile(absPath);
 
       for (const spec of applicableSpecs) {
         const blockMarker = `<${spec.blockId.toUpperCase().replace(/-/g, "_")}>`;

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

@@ -29,10 +29,14 @@ Sweep batch 2: real KEY_DECISIONS on 10 files, expanded purposes (CONTRACT-02/PU
 
 */
 
-import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
+import { ambientIo } from "../../../src/utils/io.ts";
 import type { ForgeCommandInput } from "../../../src/types.ts";
 import { hasGeneratedMarker } from "../../../src/utils/generated-marker.ts";
+
+// Ambient default for helper fns without a context param — handlers override
+// with `const io = resolveIo(context.io)` inside their own scope.
+const io = ambientIo;
 import {
   parseGovernanceIdParts,
   resolveCompassPolicy,
@@ -158,19 +162,18 @@ function hasRelevantExtension(filePath: string, policy: CompassPolicy): boolean
 async function collectSourceFiles(targetPath: string, policy: CompassPolicy): Promise<string[]> {
   let stat;
   try {
-    const { stat: fsStat } = await import("node:fs/promises");
-    stat = await fsStat(targetPath);
+    stat = await io.stat(targetPath);
   } catch {
     return [];
   }
 
-  if (stat.isFile()) {
+  if (stat.isFile) {
     return hasRelevantExtension(targetPath, policy) ? [targetPath] : [];
   }
 
   let entries;
   try {
-    entries = await readdir(targetPath, { withFileTypes: true });
+    entries = await io.readdir(targetPath);
   } catch {
     return [];
   }
@@ -179,7 +182,7 @@ async function collectSourceFiles(targetPath: string, policy: CompassPolicy): Pr
   for (const entry of entries) {
     const absolutePath = join(targetPath, entry.name);
 
-    if (entry.isDirectory()) {
+    if (entry.isDirectory) {
       if (shouldIgnoreDirectory(entry.name, policy)) {
         continue;
       }
@@ -188,7 +191,7 @@ async function collectSourceFiles(targetPath: string, policy: CompassPolicy): Pr
       continue;
     }
 
-    if (entry.isFile() && hasRelevantExtension(absolutePath, policy)) {
+    if (entry.isFile && hasRelevantExtension(absolutePath, policy)) {
       files.push(absolutePath);
     }
   }
@@ -722,7 +725,7 @@ export async function createCompassInventoryEntries(
   const entries: CompassInventoryEntry[] = [];
 
   for (const filePath of files.sort()) {
-    const source = await readFile(filePath, "utf8");
+    const source = await io.readFile(filePath);
     const pathFromRoot = relative(workspaceRoot, filePath).replace(/\\/g, "/");
     const segments = getRelativeSegments(filePath, workspaceRoot);
     const relativePathWithinWorkspace = leafWorkspaceRoot

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

@@ -25,7 +25,7 @@ compass-migrate-handler hint used a consumer-specific run command — switched t
 </CHANGE_SUMMARY>
 */
 
-import { execFileSync } from "node:child_process";
+import { execFileSync } from "../../../src/utils/sync-fs.ts";
 import { migrateWorkspace, type MigrateResult } from "./compass-migrate.ts";
 import { resolveCompassScanRoot } from "./resolve-scan-root.ts";
 import { resolveCompassPolicy } from "../policy.ts";

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

@@ -26,8 +26,8 @@ Add the v1 to v2 Compass header codemod: migrateFile pure transform (collapse, s
 </CHANGE_SUMMARY>
 */
 
-import { readFile } from "node:fs/promises";
 import { relative, resolve } from "node:path";
+import { ambientIo } from "../../../src/utils/io.ts";
 import {
   createCompassInventoryEntries,
   detectRiskClass,
@@ -46,6 +46,10 @@ import { writeFileIfChanged } from "../../../src/utils/fs-idempotent.ts";
 import type { CompassPolicy } from "../policy.ts";
 import type { ForgeCommandInput } from "../../../src/types.ts";
 
+// Ambient default for helper fns without a context param — handlers override
+// with `const io = resolveIo(context.io)` inside their own scope.
+const io = ambientIo;
+
 export type MigrateAction =
   | "collapsed"
   | "stripped"
@@ -324,7 +328,7 @@ export async function migrateWorkspace(
       const target = toTarget(workspaceRoot, absPath, policy);
       let source: string;
       try {
-        source = await readFile(absPath, "utf8");
+        source = await io.readFile(absPath);
       } catch {
         result.files.push({ path: file, actions: ["unparseable"] });
         continue;
@@ -354,7 +358,7 @@ export async function migrateWorkspace(
     if (entry.authoringStatus !== "authored") continue;
     result.scanned += 1;
     const absPath = resolve(workspaceRoot, entry.path);
-    const source = getEntrySource(entry) ?? (await readFile(absPath, "utf8"));
+    const source = getEntrySource(entry) ?? (await io.readFile(absPath));
     const segments = getRelativeSegments(absPath, workspaceRoot);
     const workspaceRelativePath = getWorkspaceRelativeSegments(segments, policy).join("/");
     const migrated = migrateFile(source, policy, entry.path, workspaceRelativePath);

package/os/compass/handlers/git-revision.ts

@@ -14,12 +14,17 @@ with integrity-registry lookup and git-history fallback, plus getFileRevisionFro
 </CHANGE_SUMMARY>
 */
 
-import { execFile } from "node:child_process";
+import { execFile } from "../../../src/utils/sync-fs.ts";
+import { ambientIo } from "../../../src/utils/io.ts";
 import { promisify } from "node:util";
 import { createHash } from "node:crypto";
-import { readFile } from "node:fs/promises";
+
 import { resolve, join } from "node:path";
 
+// Ambient default for helper fns without a context param — handlers override
+// with `const io = resolveIo(context.io)` inside their own scope.
+const io = ambientIo;
+
 const execFileAsync = promisify(execFile);
 const DEFAULT_GIT_TIMEOUT_MS = 15_000;
 
@@ -73,7 +78,7 @@ type PathsCurrent = Record<string, string>;
 async function loadEntitiesById(cwd: string): Promise<EntitiesById> {
   const filePath = join(cwd, ".integrity", "index", "entities.by-id.json");
   try {
-    const content = await readFile(filePath, "utf8");
+    const content = await io.readFile(filePath);
     return JSON.parse(content) as EntitiesById;
   } catch {
     return {};
@@ -83,7 +88,7 @@ async function loadEntitiesById(cwd: string): Promise<EntitiesById> {
 async function loadPathsCurrent(cwd: string): Promise<PathsCurrent> {
   const filePath = join(cwd, ".integrity", "index", "paths.current.json");
   try {
-    const content = await readFile(filePath, "utf8");
+    const content = await io.readFile(filePath);
     return JSON.parse(content) as PathsCurrent;
   } catch {
     return {};
@@ -110,7 +115,7 @@ export async function getRevisionByPath(
       let contentHash = entity.contentHash;
       try {
         const abs = resolve(cwd, repoPath);
-        const content = await readFile(abs, "utf8");
+        const content = await io.readFile(abs);
         contentHash = "sha256-" + createHash("sha256").update(content).digest("hex");
       } catch {
         // keep registry hash
@@ -127,7 +132,7 @@ export async function getRevisionByPath(
   let contentHash = "";
   try {
     const abs = resolve(cwd, repoPath);
-    const content = await readFile(abs, "utf8");
+    const content = await io.readFile(abs);
     contentHash = "sha256-" + createHash("sha256").update(content).digest("hex");
   } catch {
     // file may not exist

package/os/compass/handlers/resolve-scan-root.ts

@@ -23,7 +23,7 @@ compass-migrate-handler hint used a consumer-specific run command — switched t
 </CHANGE_SUMMARY>
 */
 
-import { existsSync } from "node:fs";
+import { existsSync } from "../../../src/utils/sync-fs.ts";
 import { resolve } from "node:path";
 import type { ForgeCommandInput, ForgeRuntimeContext } from "../../../src/types.ts";
 

package/os/compass/handlers/summary-record.ts

@@ -32,13 +32,18 @@ compass-migrate-handler hint used a consumer-specific run command — switched t
 </CHANGE_SUMMARY>
 */
 
-import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
+import { existsSync } from "../../../src/utils/sync-fs.ts";
+import { ambientIo, resolveIo } from "../../../src/utils/io.ts";
+
 import { resolve, relative } from "node:path";
 import { detectRiskClass, getWorkspaceRelativeSegments } from "./compass-inventory.ts";
 import { parseGovernanceIdParts, resolveCompassPolicy, type CompassPolicy } from "../policy.ts";
 import { resolveCompassScanRoot } from "./resolve-scan-root.ts";
 import { writeFileIfChanged } from "../../../src/utils/fs-idempotent.ts";
+
+// Ambient default for helper fns without a context param — handlers override
+// with `const io = resolveIo(context.io)` inside their own scope.
+const io = ambientIo;
 import type {
   ForgeCommandInput,
   ForgeCommandResult,
@@ -185,7 +190,7 @@ export async function recordSummaryItem(
   dryRun: boolean,
   policy: CompassPolicy,
 ): Promise<RecordOutcome> {
-  const source = await readFile(absPath, "utf8");
+  const source = await io.readFile(absPath);
   const blockMatch = source.match(CHANGE_SUMMARY_BLOCK_RE);
   // Header-region guard: a CHANGE_SUMMARY is a header only when it sits at the
   // top of the file. Blocks deeper in the source are examples inside template
@@ -243,6 +248,7 @@ export async function runCompassSummaryRecord(
   input: ForgeCommandInput,
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<SummaryRecordResult>> {
+  const io = resolveIo(context.io);
   const scanRoot = resolveCompassScanRoot(input, context);
   const baseRoot = scanRoot ?? context.workspaceRoot;
   const policy = resolveCompassPolicy(baseRoot, context.forgeRoot);
@@ -291,7 +297,7 @@ export async function runCompassSummaryRecord(
       if (outcome.recorded) {
         result.recorded.push(relPath);
         if (outcome.collapsed) result.collapsed.push(relPath);
-        const source = await readFile(absPath, "utf8");
+        const source = await io.readFile(absPath);
         if (riskReminderNeeded(relPath, source, policy)) {
           result.keyDecisionsReminders.push(relPath);
           context.logger.warn(`[compass.summary.record] review KEY_DECISIONS in ${relPath}`);

package/os/compass/handlers/tests/compass-audit-plan.test.ts

@@ -16,6 +16,7 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { runCompassAuditPlan } from "../compass-audit-handler.ts";
 import type { ForgeCommandInput, ForgeRuntimeContext } from "../../../../src/types.ts";
+import { ambientIo } from "../../../../src/utils/io.ts";
 
 const execFileAsync = promisify(execFile);
 
@@ -38,7 +39,7 @@ function makeContext(workspaceRoot: string): ForgeRuntimeContext {
     logger: logger as never,
     dryRun: false,
     outputFormat: "json",
-    io: {} as never,
+    io: ambientIo,
     actualState: undefined as never,
     fileIntents: [],
   } as unknown as ForgeRuntimeContext;