@warpgogol/forge 5.2.4 → 5.3.0

package/os/adr/adr.module.ts

@@ -9,154 +9,158 @@
   <item>RFC-0366: register adr.create, adr.validate, and adr.list commands.</item>
   <item>RFC-0521: migrated from packages/os/site-kernel/src/adr/ to packages/forge/os/adr/ as forgeAdrModule.</item>
   <item>RFC-0727: register adr.implement.stamp command for atomic ADR status transition.</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>
 </CHANGE_SUMMARY>
 */
 
 import type { ForgeModule } from "../../src/forge-module.ts";
 
 export async function createForgeAdrModule(): Promise<ForgeModule> {
-const { runAdrList, runAdrCreate } = await import("./handlers/list-create.ts");
-    const { runAdrValidate } = await import("./handlers/validate.ts");
-    const { runAdrArchive } = await import("./handlers/archive.ts");
-    const { runAdrImplementStamp } = await import("./handlers/implement-stamp.ts");
+  const { runAdrList, runAdrCreate } = await import("./handlers/list-create.ts");
+  const { runAdrValidate } = await import("./handlers/validate.ts");
+  const { runAdrArchive } = await import("./handlers/archive.ts");
+  const { runAdrImplementStamp } = await import("./handlers/implement-stamp.ts");
   return {
-  name: "forge-adr",
-  version: "0.1.0",
-  runtime: "autonomous",
+    name: "forge-adr",
+    version: "0.1.0",
+    runtime: "autonomous",
 
     declarations: [],
-  commands: [
-    {
-      name: "adr.list",
-      description:
-        "List all ADRs. Filter with --status, --scope, --decider flags. " +
-        "Use --json for machine-readable output. " +
-        "Parses frontmatter on the fly — no index file needed.",
-      scope: "workspace",
-      flags: {
-        status: {
-          kind: "string",
-          description: "Filter by ADR status (e.g. proposed, accepted, superseded).",
+    commands: [
+      {
+        name: "adr.list",
+        mutatesState: false,
+        description:
+          "List all ADRs. Filter with --status, --scope, --decider flags. " +
+          "Use --json for machine-readable output. " +
+          "Parses frontmatter on the fly — no index file needed.",
+        scope: "workspace",
+        flags: {
+          status: {
+            kind: "string",
+            description: "Filter by ADR status (e.g. proposed, accepted, superseded).",
+          },
+          scope: {
+            kind: "string",
+            description: "Filter by ADR scope (package, app, workspace).",
+          },
+          decider: { kind: "string", description: "Filter by decider string." },
         },
-        scope: {
-          kind: "string",
-          description: "Filter by ADR scope (package, app, workspace).",
-        },
-        decider: { kind: "string", description: "Filter by decider string." },
+        reads: ["docs/adrs/**/*.md"],
+        execute: runAdrList,
       },
-      reads: ["docs/adrs/**/*.md"],
-      execute: runAdrList,
-    },
-    {
-      name: "adr.create",
-      description:
-        "Create a new ADR draft from the template. " +
-        'Pass --title "Short title" (required). ' +
-        "Optional: --scope, --decider, --status, --related. " +
-        "Always creates status: proposed unless overridden. " +
-        "AI agents are allowed to use this command.",
-      scope: "workspace",
-      mutatesState: true,
-      writes: ["docs/adrs/adr-*.md"],
-      reads: ["docs/adrs/**/*.md"],
-      cacheable: false,
-      flags: {
-        title: { kind: "string", required: true, description: "Short imperative ADR title." },
-        scope: {
-          kind: "string",
-          default: "package",
-          description: "ADR scope: package | app | workspace.",
-        },
-        decider: {
-          kind: "string",
-          default: "architecture",
-          description: "ADR decider, e.g. architecture or human:<handle>.",
-        },
-        status: {
-          kind: "string",
-          default: "proposed",
-          description: "ADR status: proposed | accepted | superseded | rejected.",
+      {
+        name: "adr.create",
+        description:
+          "Create a new ADR draft from the template. " +
+          'Pass --title "Short title" (required). ' +
+          "Optional: --scope, --decider, --status, --related. " +
+          "Always creates status: proposed unless overridden. " +
+          "AI agents are allowed to use this command.",
+        scope: "workspace",
+        mutatesState: true,
+        writes: ["docs/adrs/adr-*.md"],
+        generates: [],
+        reads: ["docs/adrs/**/*.md"],
+        cacheable: false,
+        flags: {
+          title: { kind: "string", required: true, description: "Short imperative ADR title." },
+          scope: {
+            kind: "string",
+            default: "package",
+            description: "ADR scope: package | app | workspace.",
+          },
+          decider: {
+            kind: "string",
+            default: "architecture",
+            description: "ADR decider, e.g. architecture or human:<handle>.",
+          },
+          status: {
+            kind: "string",
+            default: "proposed",
+            description: "ADR status: proposed | accepted | superseded | rejected.",
+          },
+          related: {
+            kind: "string",
+            description: "Comma-separated list of related RFC/ADR ids (e.g. RFC-0365,RFC-0001).",
+          },
         },
-        related: {
-          kind: "string",
-          description: "Comma-separated list of related RFC/ADR ids (e.g. RFC-0365,RFC-0001).",
-        },
-      },
-      execute: runAdrCreate,
-    },
-    {
-      name: "adr.validate",
-      contract: "adr",
-      rules: [],
-      description:
-        "Validate ADR frontmatter schema, required markdown sections, " +
-        "referential integrity (supersedes/supersededBy), and id/filename consistency. " +
-        "Pass --id to validate a single file, or run without arguments for all.",
-      scope: "workspace",
-      flags: {
-        id: { kind: "string", description: "Target a single ADR by id (e.g. ADR-0003)." },
+        execute: runAdrCreate,
       },
-      reads: ["docs/adrs/**/*.md"],
-      execute: runAdrValidate,
-    },
-    {
-      name: "adr.archive",
-      description:
-        "Move terminal-status ADR files (implemented, rejected, superseded) into " +
-        "docs/adrs/archive/<status>/ subdirectories. Bidirectional: moves non-terminal " +
-        "files found in subdirectories back to root. Use --dry-run to preview. " +
-        "Use --status to filter to a single terminal status. " +
-        "Prefer the docs.archive umbrella command unless you need to archive only ADRs.",
-      scope: "workspace",
-      mutatesState: true,
-      writes: ["docs/adrs/*.md", "docs/adrs/archive/**"],
-      reads: ["docs/adrs/**/*.md"],
-      cacheable: false,
-      flags: {
-        "dry-run": {
-          kind: "boolean",
-          description: "Preview what would be moved without touching the filesystem.",
-        },
-        status: {
-          kind: "string",
-          description: "Filter to a single terminal status (implemented, rejected, superseded).",
+      {
+        name: "adr.validate",
+        mutatesState: false,
+        contract: "adr",
+        rules: [],
+        description:
+          "Validate ADR frontmatter schema, required markdown sections, " +
+          "referential integrity (supersedes/supersededBy), and id/filename consistency. " +
+          "Pass --id to validate a single file, or run without arguments for all.",
+        scope: "workspace",
+        flags: {
+          id: { kind: "string", description: "Target a single ADR by id (e.g. ADR-0003)." },
         },
+        reads: ["docs/adrs/**/*.md"],
+        execute: runAdrValidate,
       },
-      execute: runAdrArchive,
-    },
-    {
-      name: "adr.implement.stamp",
-      description:
-        "Atomically transition an ADR from accepted/proposed to implemented. " +
-        "Validates preconditions (status, implementation commit, file cleanliness, " +
-        "concurrent safety) and mutates frontmatter in one atomic write. " +
-        "Use --dry-run to preview without mutating. Required flags: `--id`, `--implementation-commit`.",
-      scope: "workspace",
-      mutatesState: true,
-      writes: ["docs/adrs/*.md"],
-      reads: ["docs/adrs/**/*.md"],
-      cacheable: false,
-      flags: {
-        id: {
-          kind: "string",
-          required: true,
-          description: "Target ADR id (e.g. ADR-0003).",
-        },
-        "implementation-commit": {
-          kind: "string",
-          required: true,
-          description: "SHA of the implementation commit.",
+      {
+        name: "adr.archive",
+        description:
+          "Move terminal-status ADR files (implemented, rejected, superseded) into " +
+          "docs/adrs/archive/<status>/ subdirectories. Bidirectional: moves non-terminal " +
+          "files found in subdirectories back to root. Use --dry-run to preview. " +
+          "Use --status to filter to a single terminal status. " +
+          "Prefer the docs.archive umbrella command unless you need to archive only ADRs.",
+        scope: "workspace",
+        mutatesState: true,
+        writes: ["docs/adrs/*.md", "docs/adrs/archive/**"],
+        generates: [],
+        reads: ["docs/adrs/**/*.md"],
+        cacheable: false,
+        flags: {
+          "dry-run": {
+            kind: "boolean",
+            description: "Preview what would be moved without touching the filesystem.",
+          },
+          status: {
+            kind: "string",
+            description: "Filter to a single terminal status (implemented, rejected, superseded).",
+          },
         },
-        "dry-run": {
-          kind: "boolean",
-          description: "Preview without mutating the ADR file.",
+        execute: runAdrArchive,
+      },
+      {
+        name: "adr.implement.stamp",
+        description:
+          "Atomically transition an ADR from accepted/proposed to implemented. " +
+          "Validates preconditions (status, implementation commit, file cleanliness, " +
+          "concurrent safety) and mutates frontmatter in one atomic write. " +
+          "Use --dry-run to preview without mutating. Required flags: `--id`, `--implementation-commit`.",
+        scope: "workspace",
+        mutatesState: true,
+        writes: ["docs/adrs/*.md"],
+        generates: [],
+        reads: ["docs/adrs/**/*.md"],
+        cacheable: false,
+        flags: {
+          id: {
+            kind: "string",
+            required: true,
+            description: "Target ADR id (e.g. ADR-0003).",
+          },
+          "implementation-commit": {
+            kind: "string",
+            required: true,
+            description: "SHA of the implementation commit.",
+          },
+          "dry-run": {
+            kind: "boolean",
+            description: "Preview without mutating the ADR file.",
+          },
         },
+        execute: runAdrImplementStamp,
       },
-      execute: runAdrImplementStamp,
-    }
-  ],
-  pipelines: [
-
-  ]};
+    ],
+    pipelines: [],
+  };
 }
-;

package/os/adr/frontmatter-io.ts

@@ -14,7 +14,7 @@ without validating the shape.
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs/promises";
+import { ambientIo as fs } from "../../src/utils/io.ts";
 import path from "node:path";
 import YAML from "yaml";
 
@@ -39,13 +39,13 @@ export async function listAdrFiles(adrDirPath: string): Promise<string[]> {
 
   async function scanDir(dirPath: string, relativePrefix: string): Promise<void> {
     try {
-      const entries = await fs.readdir(dirPath, { withFileTypes: true });
+      const entries = await fs.readdir(dirPath);
       for (const entry of entries) {
         const relativePath = relativePrefix ? `${relativePrefix}/${entry.name}` : entry.name;
-        if (entry.isDirectory()) {
+        if (entry.isDirectory) {
           await scanDir(path.join(dirPath, entry.name), relativePath);
         } else if (
-          entry.isFile() &&
+          entry.isFile &&
           entry.name.endsWith(".md") &&
           !entry.name.startsWith("adr-0000") &&
           entry.name !== "README.md"
@@ -72,7 +72,7 @@ export async function readAndParseAdr(
 ): Promise<{ fileName: string; parsed: ParsedAdr } | undefined> {
   try {
     const filePath = path.join(adrDirPath, fileName);
-    const content = await fs.readFile(filePath, "utf-8");
+    const content = await fs.readFile(filePath);
     return { fileName, parsed: parseAdrFile(content) };
   } catch {
     return undefined;

package/os/adr/handlers/archive.ts

@@ -17,7 +17,7 @@ in subdirectories back to the root.
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs/promises";
+import { ambientIo as fs } from "../../../src/utils/io.ts";
 import path from "node:path";
 import { listAdrFiles, readAndParseAdr } from "../frontmatter-io.ts";
 import type {
@@ -129,7 +129,9 @@ export async function runAdrArchive(
       }
 
       try {
-        await fs.access(targetPath);
+        await fs.exists(targetPath).then((ok) => {
+          if (!ok) throw Object.assign(new Error("ENOENT"), { code: "ENOENT" });
+        });
         skipped.push({ id, file: relFile, reason: "destination exists" });
         continue;
       } catch {
@@ -137,7 +139,7 @@ export async function runAdrArchive(
       }
 
       if (!dryRun) {
-        await fs.mkdir(targetDir, { recursive: true });
+        await fs.mkdir(targetDir);
         try {
           await fs.rename(path.join(adrDirPath, fileName), targetPath);
         } catch (err) {
@@ -176,7 +178,9 @@ export async function runAdrArchive(
       }
 
       try {
-        await fs.access(targetPath);
+        await fs.exists(targetPath).then((ok) => {
+          if (!ok) throw Object.assign(new Error("ENOENT"), { code: "ENOENT" });
+        });
         skipped.push({ id, file: relFile, reason: "destination exists" });
         continue;
       } catch {

package/os/adr/handlers/implement-stamp.ts

@@ -17,8 +17,9 @@ and atomically mutates ADR frontmatter.
 </CHANGE_SUMMARY>
 */
 
-import { execFile } from "node:child_process";
-import { readFile, unlink, mkdir } from "node:fs/promises";
+import { execFile, writeFileSync } from "../../../src/utils/sync-fs.ts";
+import { ambientIo, resolveIo } from "../../../src/utils/io.ts";
+
 import { join, dirname } from "node:path";
 
 import { writeFileAtomic } from "../../../src/utils/fs-atomic.ts";
@@ -27,6 +28,10 @@ import { listAdrFiles, readAndParseAdr, adrFileMatchesId } from "../frontmatter-
 import { evaluateAcceptanceCriteria } from "../../rfc/handlers/validate-rules.ts";
 import { ADR_DIR, ADR_ACCEPTANCE_CRITERIA_CUTOFF } from "../types.ts";
 import type { AdrStatus, AdrImplementStampViolation, AdrImplementStampResult } from "../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;
 import type {
   ForgeCommandInput,
   ForgeCommandResult,
@@ -98,15 +103,14 @@ async function acquireAdrLock(
 ): Promise<{ acquired: boolean; lockPath: string }> {
   const lockPath = lockFilePath(workspaceRoot, adrId);
   const lockDir = dirname(lockPath);
-  await mkdir(lockDir, { recursive: true });
+  await io.mkdir(lockDir);
 
-  const { open } = await import("node:fs/promises");
   try {
-    const handle = await open(lockPath, "wx");
-    await handle.writeFile(
+    writeFileSync(
+      lockPath,
       JSON.stringify({ pid: process.pid, acquiredAt: new Date().toISOString() }),
+      { flag: "wx" },
     );
-    await handle.close();
     return { acquired: true, lockPath };
   } catch {
     return { acquired: false, lockPath };
@@ -115,7 +119,7 @@ async function acquireAdrLock(
 
 async function releaseAdrLock(lockPath: string): Promise<void> {
   try {
-    await unlink(lockPath);
+    await io.rm(lockPath);
   } catch {
     // Lock file already removed — safe
   }
@@ -157,6 +161,7 @@ export async function runAdrImplementStamp(
   input: ForgeCommandInput,
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<AdrImplementStampResult>> {
+  const io = resolveIo(context.io);
   const { workspaceRoot, logger, outputFormat, dryRun } = context;
   const adrDirPath = join(workspaceRoot, ADR_DIR);
 
@@ -276,7 +281,7 @@ export async function runAdrImplementStamp(
   try {
     // ── Atomic mutation ──────────────────────────────────────────────────────
     const adrFilePath = join(adrDirPath, targetFile);
-    const adrSource = await readFile(adrFilePath, "utf-8");
+    const adrSource = await io.readFile(adrFilePath);
 
     const today = toIsoDate(new Date());
     const stampedAt = new Date().toISOString();

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

@@ -14,8 +14,8 @@ Sweep batch 2: real KEY_DECISIONS on 10 files, expanded purposes (CONTRACT-02/PU
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { ambientIo as fs } from "../../../src/utils/io.ts";
+import { existsSync } from "../../../src/utils/sync-fs.ts";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { toKebabCase } from "../../../src/utils/string-utils.ts";
@@ -152,7 +152,7 @@ export async function runAdrCreate(
   const templatePath = resolveAdrTemplate(workspaceRoot);
   let templateContent: string;
   try {
-    templateContent = await fs.readFile(templatePath, "utf-8");
+    templateContent = await fs.readFile(templatePath);
   } catch {
     throw new Error(
       `ADR template not found at ${templatePath}. Ensure docs/adrs/ contains the template.`,
@@ -190,13 +190,13 @@ export async function runAdrCreate(
   }
 
   try {
-    await fs.mkdir(adrDirPath, { recursive: true });
+    await fs.mkdir(adrDirPath);
   } catch {
     // ignore
   }
 
   const targetPath = path.join(adrDirPath, fileName);
-  await fs.writeFile(targetPath, content, "utf-8");
+  await fs.writeFile(targetPath, content);
 
   const relativeFile = path.join(ADR_DIR, fileName);
 

package/os/adr/handlers/validate.ts

@@ -19,7 +19,7 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 */
 
 import path from "node:path";
-import { execFile } from "node:child_process";
+import { execFile } from "../../../src/utils/sync-fs.ts";
 import {
   listAdrFiles,
   readAndParseAdr,

package/os/audit/audit.module.ts

@@ -13,42 +13,41 @@
 import type { ForgeModule } from "../../src/forge-module.ts";
 
 export async function createForgeAuditModule(): Promise<ForgeModule> {
-const { runAuditArchive } = await import("./handlers/archive.ts");
+  const { runAuditArchive } = await import("./handlers/archive.ts");
   return {
-  name: "forge-audit",
-  version: "0.1.0",
-  runtime: "autonomous",
+    name: "forge-audit",
+    version: "0.1.0",
+    runtime: "autonomous",
     declarations: [],
-  commands: [
-    {
-      name: "audit.archive",
-      description:
-        "Move audit files whose parent RFC has terminal status " +
-        "(implemented, rejected, superseded) into docs/audits/archive/<status>/ " +
-        "subdirectories. Bidirectional: moves non-terminal files found in " +
-        "subdirectories back to root. Use --dry-run to preview. " +
-        "Use --status to filter to a single terminal status. " +
-        "Prefer the docs.archive umbrella command unless you need to archive only audits.",
-      scope: "workspace",
-      mutatesState: true,
-      writes: ["docs/audits/*.md", "docs/audits/archive/**"],
-      reads: ["docs/audits/**/*.md", "docs/rfcs/**/*.md"],
-      cacheable: false,
-      flags: {
-        "dry-run": {
-          kind: "boolean",
-          description: "Preview what would be moved without touching the filesystem.",
-        },
-        status: {
-          kind: "string",
-          description: "Filter to a single terminal status (implemented, rejected, superseded).",
+    commands: [
+      {
+        name: "audit.archive",
+        description:
+          "Move audit files whose parent RFC has terminal status " +
+          "(implemented, rejected, superseded) into docs/audits/archive/<status>/ " +
+          "subdirectories. Bidirectional: moves non-terminal files found in " +
+          "subdirectories back to root. Use --dry-run to preview. " +
+          "Use --status to filter to a single terminal status. " +
+          "Prefer the docs.archive umbrella command unless you need to archive only audits.",
+        scope: "workspace",
+        mutatesState: true,
+        writes: ["docs/audits/*.md", "docs/audits/archive/**"],
+        generates: [],
+        reads: ["docs/audits/**/*.md", "docs/rfcs/**/*.md"],
+        cacheable: false,
+        flags: {
+          "dry-run": {
+            kind: "boolean",
+            description: "Preview what would be moved without touching the filesystem.",
+          },
+          status: {
+            kind: "string",
+            description: "Filter to a single terminal status (implemented, rejected, superseded).",
+          },
         },
+        execute: runAuditArchive,
       },
-      execute: runAuditArchive,
-    }
-  ],
-  pipelines: [
-
-  ]};
+    ],
+    pipelines: [],
+  };
 }
-;

package/os/audit/frontmatter-io.ts

@@ -15,7 +15,7 @@ are silently excluded.
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs/promises";
+import { ambientIo as fs } from "../../src/utils/io.ts";
 import path from "node:path";
 import YAML from "yaml";
 import { AUDIT_RFC_FILE_PATTERN } from "./types.ts";
@@ -41,13 +41,13 @@ export async function listAuditFiles(auditDirPath: string): Promise<string[]> {
 
   async function scanDir(dirPath: string, relativePrefix: string): Promise<void> {
     try {
-      const entries = await fs.readdir(dirPath, { withFileTypes: true });
+      const entries = await fs.readdir(dirPath);
       for (const entry of entries) {
         const relativePath = relativePrefix ? `${relativePrefix}/${entry.name}` : entry.name;
-        if (entry.isDirectory()) {
+        if (entry.isDirectory) {
           await scanDir(path.join(dirPath, entry.name), relativePath);
         } else if (
-          entry.isFile() &&
+          entry.isFile &&
           entry.name.endsWith(".md") &&
           !entry.name.startsWith("audit-0000") &&
           entry.name !== "README.md" &&
@@ -71,7 +71,7 @@ export async function readAndParseAudit(
 ): Promise<{ fileName: string; parsed: ParsedAudit } | undefined> {
   try {
     const filePath = path.join(auditDirPath, fileName);
-    const content = await fs.readFile(filePath, "utf-8");
+    const content = await fs.readFile(filePath);
     return { fileName, parsed: parseAuditFile(content) };
   } catch {
     return undefined;

package/os/audit/handlers/archive.ts

@@ -17,7 +17,7 @@ files (not matching audit-rfc-XXXX-*) are silently excluded.
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs/promises";
+import { ambientIo as fs } from "../../../src/utils/io.ts";
 import path from "node:path";
 import { listAuditFiles, extractRfcIdFromAuditFile } from "../frontmatter-io.ts";
 import { loadRfcStatusMap } from "../../rfc/frontmatter-io.ts";
@@ -116,7 +116,9 @@ export async function runAuditArchive(
       }
 
       try {
-        await fs.access(targetPath);
+        await fs.exists(targetPath).then((ok) => {
+          if (!ok) throw Object.assign(new Error("ENOENT"), { code: "ENOENT" });
+        });
         skipped.push({ id: rfcId, file: relFile, reason: "destination exists" });
         continue;
       } catch {
@@ -124,7 +126,7 @@ export async function runAuditArchive(
       }
 
       if (!dryRun) {
-        await fs.mkdir(targetDir, { recursive: true });
+        await fs.mkdir(targetDir);
         try {
           await fs.rename(path.join(auditDirPath, fileName), targetPath);
         } catch (err) {
@@ -167,7 +169,9 @@ export async function runAuditArchive(
       }
 
       try {
-        await fs.access(targetPath);
+        await fs.exists(targetPath).then((ok) => {
+          if (!ok) throw Object.assign(new Error("ENOENT"), { code: "ENOENT" });
+        });
         skipped.push({ id: rfcId, file: relFile, reason: "destination exists" });
         continue;
       } catch {