@warpgogol/forge 5.2.4 → 5.3.1

package/os/core/core.module.ts

@@ -6,8 +6,6 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-1088: register forge.file-size.lint command for portable SIZE-01 line-count validation.</item>
-  <item>RFC-1088 fix: add writes field to forge.file-size.lint registration per fo-review.</item>
   <item>RFC-1089: rename forge.file-size.lint to file.size.lint (domain validator, no forge. prefix).</item>
   <item>RFC-1097: step 6 — compass.migrate codemod run
 
@@ -15,7 +13,9 @@ Mechanical v1 to v2 header migration across the workspace: 942 files rewritten
   <item>RFC-1097: sweep — packages/forge + services clean
 
 Sweep batch 2: real KEY_DECISIONS on 10 files, expanded purposes (CONTRACT-02/PURPOSE-02), headers on mission/index + gen-upstreams, sanitizeItemText in summary.record (literal Compass tags corrupted history), excludedPaths for wrangler types, test-fixtures testPattern. forge+services now 0 diagnostics under --mode error.</item>
-  <history>ADR-0021, RFC-0374, RFC-0521, RFC-0539, RFC-0542, RFC-0543, RFC-0544, RFC-0546, RFC-0640, RFC-0662, RFC-0674, RFC-0678, RFC-0679, RFC-0680, RFC-0711, RFC-0733, RFC-0877, RFC-0940, RFC-1080</history>
+  <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>
+  <item>RFC-1173: fixup: flip mutatesState to true on 19 commands that declare writes/generates — the codemod's name-suffix rules misclassified leitstand.dev-deploy, leitstand.certify, coverage.report and peers as read-only; declared writes imply mutation</item>
+  <history>ADR-0021, RFC-0374, RFC-0521, RFC-0539, RFC-0542, RFC-0543, RFC-0544, RFC-0546, RFC-0640, RFC-0662, RFC-0674, RFC-0678, RFC-0679, RFC-0680, RFC-0711, RFC-0733, RFC-0877, RFC-0940, RFC-1080, RFC-1088</history>
 </CHANGE_SUMMARY>
 */
 
@@ -27,6 +27,7 @@ import type {
   ForgeRuntimeContext,
 } from "../../src/types.ts";
 import path from "node:path";
+import { execSync } from "../../src/utils/sync-fs.ts";
 import {
   FORGE_SKILLS,
   discoverPackSkills,
@@ -212,6 +213,9 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
     commands: [
       {
         name: "forge.doctor",
+        mutatesState: true,
+        writes: [".agents/memory/**"],
+        generates: [],
         description: "Diagnose forge state in an existing project.",
         scope: "workspace",
         supportsAllSites: false,
@@ -230,6 +234,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
       },
       {
         name: "forge.port.scaffold",
+        mutatesState: true,
         description: "Generate a skeleton for a new forge skill or command.",
         scope: "workspace",
         supportsAllSites: false,
@@ -242,6 +247,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
       },
       {
         name: "forge.skill.validate",
+        mutatesState: false,
         contract: "forge",
         rules: [],
         description:
@@ -254,6 +260,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
       },
       {
         name: "forge.skill.list",
+        mutatesState: false,
         description: "List all registered forge skills.",
         scope: "workspace",
         supportsAllSites: false,
@@ -263,6 +270,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
       },
       {
         name: "forge.port.validate",
+        mutatesState: false,
         contract: "forge",
         rules: [],
         description:
@@ -277,16 +285,20 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
       },
       {
         name: "forge.agents.generate",
+        mutatesState: true,
         description:
           "Regenerate AGENTS.md deterministically from forge.yaml and the skill registry.",
         scope: "workspace",
         supportsAllSites: false,
         flags: {},
+        writes: ["AGENTS.md", "**/AGENTS.md"],
+        generates: [],
         cacheable: false,
         execute: runAgentsGenerate,
       },
       {
         name: "memory.compact",
+        mutatesState: true,
         description:
           "Enforce the MEMORY.md character budget by removing oldest Environment notes bullets (RFC-1151).",
         scope: "workspace",
@@ -297,6 +309,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
       },
       {
         name: "forge.upgrade",
+        mutatesState: true,
         description:
           "Additive sync for npm consumers: refresh .agents/skills/ from installed forge, add missing binding defaults, update forge.syncedVersion, run doctor.",
         scope: "workspace",
@@ -313,12 +326,14 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
           },
         },
         writes: [".agents/skills/**", "forge.yaml"],
+        generates: [],
         reads: ["forge.yaml", "packages/forge/skills/**", "packages/forge/package.json"],
         cacheable: false,
         execute: runUpgrade,
       },
       {
         name: "forge.scaffold",
+        mutatesState: true,
         description:
           "Create a working pnpm + Turborepo monorepo from a stack profile in an empty directory. Required flags: `--profile`, `--name`.",
         scope: "workspace",
@@ -341,6 +356,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
       },
       {
         name: "forge.create",
+        mutatesState: true,
         description:
           "Create a forge project in-place: scaffold + init + binding defaults. The target directory must be empty (only .git/ tolerated). Usage: forge create --in-place --profile <profile-id> [--name <name>] [--package-manager pnpm]",
         scope: "workspace",
@@ -376,6 +392,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
       },
       {
         name: "forge.init",
+        mutatesState: true,
         description:
           "Deploy forge into a project: create forge.yaml, PREFERENCES.md, copy skills, create docs dirs. Hidden recovery command — normally called by forge.create.",
         scope: "workspace",
@@ -397,6 +414,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
       },
       {
         name: "forge.profile.validate",
+        mutatesState: false,
         contract: "forge",
         rules: [],
         description:
@@ -415,6 +433,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
       },
       {
         name: "forge.dev",
+        mutatesState: true,
         description:
           "Start the dev/preview server declared in the active stack profile. Use --dry-run to print the resolved command without executing.",
         scope: "workspace",
@@ -436,6 +455,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
       },
       {
         name: "forge.build",
+        mutatesState: true,
         description:
           "Execute produce commands for all artifacts declared in the active stack profile. Use --dry-run to print resolved commands.",
         scope: "workspace",
@@ -456,6 +476,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
       },
       {
         name: "forge.validate",
+        mutatesState: false,
         contract: "forge",
         rules: [],
         description:
@@ -482,6 +503,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
       },
       {
         name: "forge.determinism.check",
+        mutatesState: true,
         contract: "forge",
         rules: [],
         description:
@@ -504,11 +526,13 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
         },
         reads: ["forge.yaml", "packages/forge/profiles/*.yaml", "dist/.determinism-cache.json"],
         writes: ["dist/.determinism-cache.json"],
+        generates: [],
         cacheable: false,
         execute: runDeterminismCheck,
       },
       {
         name: "forge.assets.list",
+        mutatesState: false,
         description:
           "List all assets declared in the active stack profile, grouped by type. Use --dry-run to skip hashing, --type to filter by asset type.",
         scope: "workspace",
@@ -533,6 +557,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
       },
       {
         name: "forge.assets.check",
+        mutatesState: false,
         contract: "forge",
         rules: [],
         description:
@@ -559,6 +584,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
       },
       {
         name: "forge.release.prepare",
+        mutatesState: true,
         description:
           "Bundle built artifacts into a release package with a manifest. Use --dry-run to preview without writing.",
         scope: "workspace",
@@ -575,11 +601,13 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
         },
         reads: ["forge.yaml", "packages/forge/profiles/*.yaml", "dist/**"],
         writes: ["release/**"],
+        generates: [],
         cacheable: false,
         execute: runReleasePrepare,
       },
       {
         name: "forge.release.publish",
+        mutatesState: true,
         description:
           "Publish a prepared release to the declared target (local, R2, S3). Use --dry-run to preview without uploading.",
         scope: "workspace",
@@ -596,11 +624,13 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
         },
         reads: ["forge.yaml", "packages/forge/profiles/*.yaml", "release/**"],
         writes: ["release/published/**"],
+        generates: [],
         cacheable: false,
         execute: runReleasePublish,
       },
       {
         name: "forge.skill.knowledge.compact",
+        mutatesState: true,
         description:
           "Compact skill knowledge files: archive expired/superseded/aged L0 entries, mark stale L2 principles. " +
           "Usage: forge.skill.knowledge.compact --all-skills [--dry-run] [--json] | --skill <name> [--dry-run] [--json]",
@@ -636,6 +666,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
           },
         },
         writes: ["packages/forge/skills/**/*.md", "packages/forge/skills/**/*.archive.md"],
+        generates: [],
         reads: [
           "packages/forge/skills/**/*.md",
           "packages/forge/skills/**/*.archive.md",
@@ -646,6 +677,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
       },
       {
         name: "pinned.validate",
+        mutatesState: true,
         contract: "pinned",
         rules: [],
         description:
@@ -656,6 +688,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
         scope: "workspace",
         reads: [".forge/pinned.yaml", ".forge/pinned-audit.log"],
         writes: [".forge/pinned-audit.log"],
+        generates: [],
         cacheable: false,
         flags: {
           "allow-pinned-override": {
@@ -690,6 +723,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
           ".gitignore",
           ".github/workflows/pinned-check.yml",
         ],
+        generates: [],
         reads: [".forge/pinned.yaml", ".git/hooks/pre-commit", ".gitignore"],
         cacheable: false,
         flags: {
@@ -702,6 +736,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
       },
       {
         name: "forge.package.health",
+        mutatesState: false,
         description:
           "Validate all published packages (private: false) for standalone extraction readiness. " +
           "Checks engines.node, embedded .github/workflows/ci.yml, extract.config.yaml, " +
@@ -725,6 +760,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
       },
       {
         name: "forge.autonomy.validate",
+        mutatesState: false,
         contract: "forge",
         rules: [],
         description:
@@ -740,6 +776,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
       },
       {
         name: "forge.public-surface.validate",
+        mutatesState: false,
         description:
           "Check consistency between README.md, package.json, and docs/ structure. " +
           "Enforces SURFACE-01..05 rules: README length, Node version match, " +
@@ -755,6 +792,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
       },
       {
         name: "file.size.lint",
+        mutatesState: true,
         contract: "file",
         rules: ["SIZE-01"],
         description:
@@ -763,6 +801,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
         supportsAllSites: false,
         reads: ["packages/*/src/**/*.ts", "packages/*/src/**/*.tsx"],
         writes: ["file-size-lint.baseline.yaml"],
+        generates: [],
         cacheable: false,
         flags: {
           "write-baseline": {
@@ -801,6 +840,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
           "missions/*",
           "missions/archive/**",
         ],
+        generates: [],
         reads: [
           "docs/rfcs/**/*.md",
           "docs/adrs/**/*.md",
@@ -942,7 +982,6 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
           // so the caller (or the next commit) includes it.
           if (!dryRun && totalMoved > 0) {
             try {
-              const { execSync } = await import("node:child_process");
               const lockfileStatus = execSync("git status --porcelain pnpm-lock.yaml", {
                 cwd: context.workspaceRoot,
                 encoding: "utf-8",

package/os/core/handlers/assets-helpers.ts

@@ -11,11 +11,15 @@
 </CHANGE_SUMMARY>
 */
 
-import { readFile, stat } from "node:fs/promises";
 import { join, relative, extname } from "node:path";
+import { ambientIo } from "../../../src/utils/io.ts";
 import { loadWorkspaceDeps } from "../../werkstatt/handlers/workspace-deps.ts";
 import type { ProfileAsset, ProfileAssetType } from "../../../src/profiles/profile-schema.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 interface AssetEntry {
   path: string;
   type: string;
@@ -63,7 +67,7 @@ export async function scanAssets(
     let hash = "";
 
     if (!options.dryRun) {
-      const stats = await stat(absPath);
+      const stats = await io.stat(absPath);
       size = stats.size;
       hash = await byteHashFile(absPath);
     }
@@ -103,7 +107,7 @@ export async function extractReferences(
   for (const absPath of allFiles) {
     const relPath = relative(workspaceRoot, absPath);
     try {
-      const content = await readFile(absPath, "utf8");
+      const content = await io.readFile(absPath);
 
       for (const assetType of assetsConfig.types) {
         if (!assetType.referencePattern) continue;

package/os/core/handlers/build.ts

@@ -11,7 +11,7 @@
 </CHANGE_SUMMARY>
 */
 
-import { exec } from "node:child_process";
+import { exec } from "../../../src/utils/sync-fs.ts";
 import { promisify } from "node:util";
 import type {
   ForgeCommandInput,

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

@@ -11,10 +11,11 @@
 </CHANGE_SUMMARY>
 */
 
-import { exec } from "node:child_process";
+import { exec } from "../../../src/utils/sync-fs.ts";
+import { ambientIo, resolveIo } from "../../../src/utils/io.ts";
 import { promisify } from "node:util";
-import { readFile, writeFile, mkdir } from "node:fs/promises";
-import { existsSync } from "node:fs";
+
+import { existsSync } from "../../../src/utils/sync-fs.ts";
 import { join, relative, dirname } from "node:path";
 import { createHash } from "node:crypto";
 import { loadWorkspaceDeps } from "../../werkstatt/handlers/workspace-deps.ts";
@@ -25,6 +26,10 @@ import type {
 } from "../../../src/types.ts";
 import { resolveActiveProfile, resolveLifecycleFlags } from "./profile-resolve.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;
+
 const execAsync = promisify(exec);
 
 export interface DeterminismCheckResult {
@@ -119,7 +124,7 @@ async function computeInputHash(workspaceRoot: string, inputPatterns: string[]):
 
 async function readCache(cachePath: string): Promise<CacheFile> {
   try {
-    const content = await readFile(cachePath, "utf8");
+    const content = await io.readFile(cachePath);
     return JSON.parse(content) as CacheFile;
   } catch {
     return { entries: {} };
@@ -129,15 +134,16 @@ async function readCache(cachePath: string): Promise<CacheFile> {
 async function writeCache(cachePath: string, cache: CacheFile): Promise<void> {
   const dir = dirname(cachePath);
   if (!existsSync(dir)) {
-    await mkdir(dir, { recursive: true });
+    await io.mkdir(dir);
   }
-  await writeFile(cachePath, JSON.stringify(cache, null, 2) + "\n", "utf8");
+  await io.writeFile(cachePath, JSON.stringify(cache, null, 2) + "\n");
 }
 
 export async function runDeterminismCheck(
   input: ForgeCommandInput,
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<ForgeDeterminismCheckResult>> {
+  const _io = resolveIo(context.io);
   const { workspaceRoot, logger } = context;
   const { dryRun, profileIdOverride } = resolveLifecycleFlags(input, context);
   const artifactFilter =

package/os/core/handlers/dev.ts

@@ -11,7 +11,7 @@
 </CHANGE_SUMMARY>
 */
 
-import { spawn } from "node:child_process";
+import { spawn } from "../../../src/utils/sync-fs.ts";
 import type {
   ForgeCommandInput,
   ForgeCommandResult,

package/os/core/handlers/file-size-lint.ts

@@ -17,9 +17,13 @@ collectFiles and diagnosticsResult. Ratcheted baseline at workspace root.
 </CHANGE_SUMMARY>
 */
 
-import { readdir, readFile, writeFile } from "node:fs/promises";
 import { join, relative } from "node:path";
+import { ambientIo, resolveIo } from "../../../src/utils/io.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;
 import type {
   CheckResult,
   Diagnostic,
@@ -52,25 +56,26 @@ async function collectSourceFiles(root: string): Promise<string[]> {
   async function walk(dir: string): Promise<void> {
     let entries;
     try {
-      entries = await readdir(dir, { withFileTypes: true });
+      entries = await io.readdir(dir);
     } catch {
       return;
     }
 
     for (const entry of entries) {
       if (entry.name.startsWith("-") || entry.name.startsWith("old-")) continue;
-      if (entry.name === "tests" || entry.name === "node_modules" || entry.name === "dist") continue;
+      if (entry.name === "tests" || entry.name === "node_modules" || entry.name === "dist")
+        continue;
       if (entry.name === ".astro" || entry.name.endsWith(".d.ts")) continue;
       if (entry.name.endsWith(".generated.yaml")) continue;
 
       const full = join(dir, entry.name);
 
-      if (entry.isDirectory()) {
+      if (entry.isDirectory) {
         await walk(full);
         continue;
       }
 
-      if (!entry.isFile()) continue;
+      if (!entry.isFile) continue;
       if (!entry.name.endsWith(".ts") && !entry.name.endsWith(".tsx")) continue;
 
       results.push(full);
@@ -86,7 +91,7 @@ async function readBaseline(
   baselinePath: string,
 ): Promise<FileSizeLintBaseline | undefined> {
   try {
-    const raw = await readFile(join(workspaceRoot, baselinePath), "utf8");
+    const raw = await io.readFile(join(workspaceRoot, baselinePath));
     return yamlParse(raw) as FileSizeLintBaseline;
   } catch {
     return undefined;
@@ -107,7 +112,7 @@ async function findOversizedFiles(workspaceRoot: string): Promise<Map<string, nu
   for (const filePath of files) {
     let source: string;
     try {
-      source = await readFile(filePath, "utf8");
+      source = await io.readFile(filePath);
     } catch {
       continue;
     }
@@ -134,7 +139,8 @@ function diagnosticsResult(
     summary.error > 0 ? "fail" : summary.warning > 0 ? "warn" : "pass";
   const counts: string[] = [];
   if (summary.error > 0) counts.push(`${summary.error} error${summary.error === 1 ? "" : "s"}`);
-  if (summary.warning > 0) counts.push(`${summary.warning} warning${summary.warning === 1 ? "" : "s"}`);
+  if (summary.warning > 0)
+    counts.push(`${summary.warning} warning${summary.warning === 1 ? "" : "s"}`);
   const summaryStr = counts.length > 0 ? `[${command}] ${counts.join(", ")}` : `[${command}]`;
   return {
     data: { command, status, diagnostics, summary },
@@ -156,6 +162,7 @@ export async function runFileSizeLint(
   input: ForgeCommandInput,
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<CheckResult | { file: string; files: number }>> {
+  const io = resolveIo(context.io);
   const { workspaceRoot } = context;
   const baselinePath =
     (input.flags["baseline-path"] as string | undefined) ?? DEFAULT_BASELINE_PATH;
@@ -164,7 +171,7 @@ export async function runFileSizeLint(
   if (input.flags["write-baseline"] === true) {
     const ceilings: Record<string, number> = {};
     for (const [file, lines] of oversized) ceilings[file] = lines;
-    await writeFile(join(workspaceRoot, baselinePath), renderBaseline(ceilings), "utf8");
+    await io.writeFile(join(workspaceRoot, baselinePath), renderBaseline(ceilings));
     return {
       data: { file: baselinePath, files: oversized.size },
       exitCode: 0,

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

@@ -24,8 +24,12 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 </CHANGE_SUMMARY>
 */
 
-import { readdir, readFile } from "node:fs/promises";
 import { join, relative } from "node:path";
+import { ambientIo, resolveIo } from "../../../src/utils/io.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,
@@ -51,19 +55,19 @@ async function scanDirectoryForImports(
 ): Promise<{ violations: { file: string; specifier: string }[]; scannedFiles: number }> {
   let scannedFiles = 0;
   const violations: { file: string; specifier: string }[] = [];
-  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+  const entries = await io.readdir(dir).catch(() => []);
 
   for (const entry of entries) {
     const fullPath = join(dir, entry.name);
 
-    if (entry.isDirectory()) {
+    if (entry.isDirectory) {
       if (EXCLUDE_DIRS.has(entry.name)) continue;
       const subResult = await scanDirectoryForImports(fullPath, workspaceRoot, specifierFilter);
       scannedFiles += subResult.scannedFiles;
       violations.push(...subResult.violations);
     } else if (entry.name.endsWith(".ts") && !shouldExcludeFile(entry.name)) {
       scannedFiles++;
-      const content = await readFile(fullPath, "utf8").catch(() => "");
+      const content = await io.readFile(fullPath).catch(() => "");
       let match: RegExpExecArray | null;
       const pattern = new RegExp(IMPORT_PATTERN.source, "g");
       while ((match = pattern.exec(content)) !== null) {
@@ -110,6 +114,7 @@ export async function runForgeAutonomyValidate(
   _input: ForgeCommandInput,
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<ForgeAutonomyValidateResult>> {
+  const io = resolveIo(context.io);
   const workspaceRoot = context.workspaceRoot;
   const forgeOsDir = join(workspaceRoot, "packages", "forge", "os");
 
@@ -124,7 +129,7 @@ export async function runForgeAutonomyValidate(
     if (v.file.startsWith(ADAPTER_DIR_PREFIX)) continue;
 
     const fullPath = join(workspaceRoot, v.file);
-    const content = await readFile(fullPath, "utf8").catch(() => "");
+    const content = await io.readFile(fullPath).catch(() => "");
     if (!isTypeOnlyImport(content, v.specifier)) {
       violations.push({
         ruleId: "FORGE-AUTONOMY-01",

package/os/core/handlers/knowledge-compact.ts

@@ -11,7 +11,7 @@
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../../../src/utils/sync-fs.ts";
 import path from "node:path";
 import type {
   ForgeCommandInput,

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

@@ -17,7 +17,7 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../../../src/utils/sync-fs.ts";
 import path from "node:path";
 import type {
   ForgeCommandInput,

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

@@ -21,7 +21,7 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs/promises";
+import { ambientIo as fs } from "../../../src/utils/io.ts";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import type { PinnedEntry, PinnedManifest, PinnedMode, PinnedViolation } from "./pinned-types.ts";
@@ -55,7 +55,7 @@ export async function loadPinnedManifest(repoRoot: string): Promise<PinnedManife
 
   let content: string;
   try {
-    content = await fs.readFile(manifestPath, "utf8");
+    content = await fs.readFile(manifestPath);
   } catch {
     return null;
   }

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

@@ -13,7 +13,8 @@ generates CI workflow. Idempotent: re-running merges defaults with existing entr
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs/promises";
+import { ambientIo as fs } from "../../../src/utils/io.ts";
+import { chmodSync } from "../../../src/utils/sync-fs.ts";
 import path from "node:path";
 import { stringify as stringifyYaml } from "yaml";
 import type {
@@ -184,12 +185,12 @@ async function installPreCommitHook(
 
   let existingContent: string;
   try {
-    existingContent = await fs.readFile(hookPath, "utf8");
+    existingContent = await fs.readFile(hookPath);
   } catch {
     // No existing hook — create new
-    await fs.mkdir(path.dirname(hookPath), { recursive: true });
+    await fs.mkdir(path.dirname(hookPath));
     await writeFileIfChanged(hookPath, PRE_COMMIT_HOOK_SCRIPT);
-    await fs.chmod(hookPath, 0o755);
+    chmodSync(hookPath, 0o755);
     return "created";
   }
 
@@ -201,7 +202,7 @@ async function installPreCommitHook(
   // Append forge hook to existing hook
   const mergedContent = existingContent + "\n" + PRE_COMMIT_HOOK_SCRIPT;
   await writeFileIfChanged(hookPath, mergedContent);
-  await fs.chmod(hookPath, 0o755);
+  chmodSync(hookPath, 0o755);
   return "updated";
 }
 
@@ -214,7 +215,7 @@ async function addToGitignore(repoRoot: string): Promise<"created" | "updated" |
 
   let existingContent: string;
   try {
-    existingContent = await fs.readFile(gitignorePath, "utf8");
+    existingContent = await fs.readFile(gitignorePath);
   } catch {
     // No .gitignore — create new
     await writeFileIfChanged(gitignorePath, entry + "\n");
@@ -238,7 +239,7 @@ async function addToGitignore(repoRoot: string): Promise<"created" | "updated" |
  */
 async function generateCiWorkflow(repoRoot: string): Promise<"created" | "unchanged"> {
   const workflowPath = path.join(repoRoot, ".github", "workflows", "pinned-check.yml");
-  await fs.mkdir(path.dirname(workflowPath), { recursive: true });
+  await fs.mkdir(path.dirname(workflowPath));
   await writeFileIfChanged(workflowPath, CI_WORKFLOW_TEMPLATE);
   return "created";
 }
@@ -283,7 +284,7 @@ export async function runPinnedInit(
 
   // Write manifest
   const manifestFullPath = path.join(workspaceRoot, PINNED_MANIFEST_PATH);
-  await fs.mkdir(path.dirname(manifestFullPath), { recursive: true });
+  await fs.mkdir(path.dirname(manifestFullPath));
   const manifestContent = stringifyYaml(merged);
   await writeFileIfChanged(manifestFullPath, manifestContent);