@warpgogol/forge 5.2.4 → 5.3.1

package/os/program/program.module.ts

@@ -8,210 +8,215 @@ kernel registry (RFC-0856).</purpose>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0856: initial program module registration.</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 createForgeProgramModule(): Promise<ForgeModule> {
-const { runValidate } = await import("./handlers/validate.ts");
-    const { runSeal } = await import("./handlers/seal.ts");
-    const { runLease } = await import("./handlers/lease.ts");
-    const { runComplete } = await import("./handlers/complete.ts");
+  const { runValidate } = await import("./handlers/validate.ts");
+  const { runSeal } = await import("./handlers/seal.ts");
+  const { runLease } = await import("./handlers/lease.ts");
+  const { runComplete } = await import("./handlers/complete.ts");
   return {
-  name: "forge-program",
-  version: "0.1.0",
-  runtime: "autonomous",
+    name: "forge-program",
+    version: "0.1.0",
+    runtime: "autonomous",
 
     declarations: [],
-  commands: [
-    {
-      name: "program.packet.validate",
-      contract: "program",
-      rules: [],
-      description:
-        "Validate a program packet against schema, source hashes, branch/head, " +
-        "and state machine rules. Read-only. " +
-        "Usage: program.packet.validate --program=RFC-XXXX --packet=NNN-foo --phase=draft --json",
-      scope: "workspace",
-      supportsAllSites: false,
-      flags: {
-        program: {
-          kind: "string",
-          required: true,
-          description: "Program RFC id (e.g. RFC-0855).",
-        },
-        packet: {
-          kind: "string",
-          required: true,
-          description: "Packet id (e.g. 010-node-24).",
-        },
-        phase: {
-          kind: "string",
-          description: "Validation phase: draft, sealed, active, or completion.",
-        },
-        json: {
-          kind: "boolean",
-          description: "Machine-readable JSON output.",
-        },
+    commands: [
+      {
+        name: "program.packet.validate",
+        mutatesState: false,
+        execOnReadOnly: true,
+        contract: "program",
+        rules: [],
+        description:
+          "Validate a program packet against schema, source hashes, branch/head, " +
+          "and state machine rules. Read-only. " +
+          "Usage: program.packet.validate --program=RFC-XXXX --packet=NNN-foo --phase=draft --json",
+        scope: "workspace",
+        supportsAllSites: false,
+        flags: {
+          program: {
+            kind: "string",
+            required: true,
+            description: "Program RFC id (e.g. RFC-0855).",
+          },
+          packet: {
+            kind: "string",
+            required: true,
+            description: "Packet id (e.g. 010-node-24).",
+          },
+          phase: {
+            kind: "string",
+            description: "Validation phase: draft, sealed, active, or completion.",
+          },
+          json: {
+            kind: "boolean",
+            description: "Machine-readable JSON output.",
+          },
+        },
+        reads: ["docs/plans/**/program.yaml", "docs/plans/**/*.md"],
+        cacheable: false,
+        execute: runValidate,
       },
-      reads: ["docs/plans/**/program.yaml", "docs/plans/**/*.md"],
-      cacheable: false,
-      execute: runValidate,
-    },
-    {
-      name: "program.packet.seal",
-      description:
-        "Steward finalizes a packet against the predecessor's completion commit, " +
-        "updates packet state from draft to sealed, and records the seal in the " +
-        "program manifest. Does not commit — use ecosystem.commit after. " +
-        "Usage: program.packet.seal --program=RFC-XXXX --packet=NNN-foo " +
-        "--steward=human:id --idempotency-key=<key> --json",
-      scope: "workspace",
-      supportsAllSites: false,
-      mutatesState: true,
-      flags: {
-        program: {
-          kind: "string",
-          required: true,
-          description: "Program RFC id.",
-        },
-        packet: {
-          kind: "string",
-          required: true,
-          description: "Packet id to seal.",
-        },
-        steward: {
-          kind: "string",
-          required: true,
-          description: "Steward actor id (human:<id> or agent:<id>).",
-        },
-        "idempotency-key": {
-          kind: "string",
-          description: "Idempotency key for retry-safe sealing.",
-        },
-        json: {
-          kind: "boolean",
-          description: "Machine-readable JSON output.",
-        },
+      {
+        name: "program.packet.seal",
+        description:
+          "Steward finalizes a packet against the predecessor's completion commit, " +
+          "updates packet state from draft to sealed, and records the seal in the " +
+          "program manifest. Does not commit — use ecosystem.commit after. " +
+          "Usage: program.packet.seal --program=RFC-XXXX --packet=NNN-foo " +
+          "--steward=human:id --idempotency-key=<key> --json",
+        scope: "workspace",
+        supportsAllSites: false,
+        mutatesState: true,
+        flags: {
+          program: {
+            kind: "string",
+            required: true,
+            description: "Program RFC id.",
+          },
+          packet: {
+            kind: "string",
+            required: true,
+            description: "Packet id to seal.",
+          },
+          steward: {
+            kind: "string",
+            required: true,
+            description: "Steward actor id (human:<id> or agent:<id>).",
+          },
+          "idempotency-key": {
+            kind: "string",
+            description: "Idempotency key for retry-safe sealing.",
+          },
+          json: {
+            kind: "boolean",
+            description: "Machine-readable JSON output.",
+          },
+        },
+        writes: ["docs/plans/**/program.yaml", "docs/plans/**/*.md"],
+        generates: [],
+        reads: ["docs/plans/**/program.yaml", "docs/plans/**/*.md"],
+        cacheable: false,
+        execute: runSeal,
       },
-      writes: ["docs/plans/**/program.yaml", "docs/plans/**/*.md"],
-      reads: ["docs/plans/**/program.yaml", "docs/plans/**/*.md"],
-      cacheable: false,
-      execute: runSeal,
-    },
-    {
-      name: "program.packet.lease",
-      description:
-        "Manage the exclusive local executor lease for a sealed packet. " +
-        "Actions: start, heartbeat, release, recover. " +
-        "Raw lease tokens are never persisted — only the SHA-256 hash. " +
-        "Usage: program.packet.lease --program=RFC-XXXX --packet=NNN-foo " +
-        "--action=start --executor=agent:id --json",
-      scope: "workspace",
-      supportsAllSites: false,
-      flags: {
-        program: {
-          kind: "string",
-          required: true,
-          description: "Program RFC id.",
-        },
-        packet: {
-          kind: "string",
-          required: true,
-          description: "Packet id.",
-        },
-        action: {
-          kind: "string",
-          required: true,
-          description: "Lease action: start, heartbeat, release, or recover.",
-        },
-        executor: {
-          kind: "string",
-          description: "Executor actor id (required for --action=start).",
-        },
-        steward: {
-          kind: "string",
-          description: "Steward actor id (required for --action=recover).",
-        },
-        "lease-token": {
-          kind: "string",
-          description: "Opaque lease token (required for heartbeat and release).",
-        },
-        reason: {
-          kind: "string",
-          description: "Recovery reason (required for --action=recover).",
-        },
-        json: {
-          kind: "boolean",
-          description: "Machine-readable JSON output.",
-        },
+      {
+        name: "program.packet.lease",
+        mutatesState: true,
+        description:
+          "Manage the exclusive local executor lease for a sealed packet. " +
+          "Actions: start, heartbeat, release, recover. " +
+          "Raw lease tokens are never persisted — only the SHA-256 hash. " +
+          "Usage: program.packet.lease --program=RFC-XXXX --packet=NNN-foo " +
+          "--action=start --executor=agent:id --json",
+        scope: "workspace",
+        supportsAllSites: false,
+        flags: {
+          program: {
+            kind: "string",
+            required: true,
+            description: "Program RFC id.",
+          },
+          packet: {
+            kind: "string",
+            required: true,
+            description: "Packet id.",
+          },
+          action: {
+            kind: "string",
+            required: true,
+            description: "Lease action: start, heartbeat, release, or recover.",
+          },
+          executor: {
+            kind: "string",
+            description: "Executor actor id (required for --action=start).",
+          },
+          steward: {
+            kind: "string",
+            description: "Steward actor id (required for --action=recover).",
+          },
+          "lease-token": {
+            kind: "string",
+            description: "Opaque lease token (required for heartbeat and release).",
+          },
+          reason: {
+            kind: "string",
+            description: "Recovery reason (required for --action=recover).",
+          },
+          json: {
+            kind: "boolean",
+            description: "Machine-readable JSON output.",
+          },
+        },
+        writes: [".forge/program-leases/**"],
+        generates: [],
+        reads: ["docs/plans/**/program.yaml", "docs/plans/**/*.md"],
+        cacheable: false,
+        execute: runLease,
       },
-      writes: [".forge/program-leases/**"],
-      reads: ["docs/plans/**/program.yaml", "docs/plans/**/*.md"],
-      cacheable: false,
-      execute: runLease,
-    },
-    {
-      name: "program.packet.complete",
-      description:
-        "Steward validates the implementation range, writes the completion report, " +
-        "and updates the program manifest. Supports --bootstrap for packet 000. " +
-        "Does not commit — use ecosystem.commit after. " +
-        "Usage: program.packet.complete --program=RFC-XXXX --packet=NNN-foo " +
-        "--steward=human:id --lease-token=<token> --implementation-head=<sha> --json",
-      scope: "workspace",
-      supportsAllSites: false,
-      mutatesState: true,
-      flags: {
-        program: {
-          kind: "string",
-          required: true,
-          description: "Program RFC id.",
-        },
-        packet: {
-          kind: "string",
-          required: true,
-          description: "Packet id to complete.",
-        },
-        steward: {
-          kind: "string",
-          required: true,
-          description: "Steward actor id (must differ from executor).",
-        },
-        "lease-token": {
-          kind: "string",
-          description: "Lease token (required for non-bootstrap).",
-        },
-        "implementation-head": {
-          kind: "string",
-          description: "SHA of the implementation head commit (required for non-bootstrap).",
-        },
-        "idempotency-key": {
-          kind: "string",
-          description: "Idempotency key for retry-safe completion.",
-        },
-        bootstrap: {
-          kind: "boolean",
-          description: "Bootstrap completion (packet 000 only).",
-        },
-        "seal-commit": {
-          kind: "string",
-          description: "Seal commit SHA (required for --bootstrap).",
-        },
-        json: {
-          kind: "boolean",
-          description: "Machine-readable JSON output.",
-        },
+      {
+        name: "program.packet.complete",
+        description:
+          "Steward validates the implementation range, writes the completion report, " +
+          "and updates the program manifest. Supports --bootstrap for packet 000. " +
+          "Does not commit — use ecosystem.commit after. " +
+          "Usage: program.packet.complete --program=RFC-XXXX --packet=NNN-foo " +
+          "--steward=human:id --lease-token=<token> --implementation-head=<sha> --json",
+        scope: "workspace",
+        supportsAllSites: false,
+        mutatesState: true,
+        flags: {
+          program: {
+            kind: "string",
+            required: true,
+            description: "Program RFC id.",
+          },
+          packet: {
+            kind: "string",
+            required: true,
+            description: "Packet id to complete.",
+          },
+          steward: {
+            kind: "string",
+            required: true,
+            description: "Steward actor id (must differ from executor).",
+          },
+          "lease-token": {
+            kind: "string",
+            description: "Lease token (required for non-bootstrap).",
+          },
+          "implementation-head": {
+            kind: "string",
+            description: "SHA of the implementation head commit (required for non-bootstrap).",
+          },
+          "idempotency-key": {
+            kind: "string",
+            description: "Idempotency key for retry-safe completion.",
+          },
+          bootstrap: {
+            kind: "boolean",
+            description: "Bootstrap completion (packet 000 only).",
+          },
+          "seal-commit": {
+            kind: "string",
+            description: "Seal commit SHA (required for --bootstrap).",
+          },
+          json: {
+            kind: "boolean",
+            description: "Machine-readable JSON output.",
+          },
+        },
+        writes: ["docs/plans/**/completions/**", "docs/plans/**/program.yaml"],
+        generates: [],
+        reads: ["docs/plans/**/program.yaml", "docs/plans/**/*.md"],
+        cacheable: false,
+        execute: runComplete,
       },
-      writes: ["docs/plans/**/completions/**", "docs/plans/**/program.yaml"],
-      reads: ["docs/plans/**/program.yaml", "docs/plans/**/*.md"],
-      cacheable: false,
-      execute: runComplete,
-    }
-  ],
-  pipelines: [
-
-  ]};
+    ],
+    pipelines: [],
+  };
 }
-;

package/os/queue/index.ts

@@ -1,6 +1,6 @@
 /*
 <MODULE_CONTRACT>
-<purpose>Barrel export for the forge queue module (RFC-1140).</purpose>
+<purpose>Barrel export for the forge queue module — re-exports queue.validate and its helpers (RFC-1140).</purpose>
 <non-goals>
   <item>Do not add logic here — re-exports only.</item>
 </non-goals>

package/os/queue/manifest.ts

@@ -16,7 +16,7 @@ Extract pipeline-status derivation into packages/forge/src/pipeline-status.ts, r
 </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";
 
@@ -51,16 +51,12 @@ export async function loadQueueManifest(
 ): Promise<LoadedQueueManifest> {
   const errors: Diagnostic[] = [];
   const warnings: Diagnostic[] = [];
-  const absolutePath = path.isAbsolute(filePath)
-    ? filePath
-    : path.join(workspaceRoot, filePath);
-  const displayPath = path.isAbsolute(filePath)
-    ? path.relative(workspaceRoot, filePath)
-    : filePath;
+  const absolutePath = path.isAbsolute(filePath) ? filePath : path.join(workspaceRoot, filePath);
+  const displayPath = path.isAbsolute(filePath) ? path.relative(workspaceRoot, filePath) : filePath;
 
   let source: string;
   try {
-    source = await fs.readFile(absolutePath, "utf-8");
+    source = await fs.readFile(absolutePath);
   } catch (e) {
     errors.push(
       diag(
@@ -125,7 +121,12 @@ export async function loadQueueManifest(
     const id = item.id.trim();
     if (!QUEUE_ITEM_ID_PATTERN.test(id)) {
       errors.push(
-        diag("QUEUE-03", "error", `Item id "${item.id}" does not match ^(RFC|ADR)-\\d{4}$`, displayPath),
+        diag(
+          "QUEUE-03",
+          "error",
+          `Item id "${item.id}" does not match ^(RFC|ADR)-\\d{4}$`,
+          displayPath,
+        ),
       );
       continue;
     }

package/os/queue/queue-validate.test.ts

@@ -119,9 +119,9 @@ describe("loadQueueManifest — validation rules (RFC-1140)", () => {
 
 describe("runQueueValidate — command contract (RFC-1140)", () => {
   test("throws without --file", async () => {
-    await expect(
-      runQueueValidate({ argv: [], flags: {} }, testContext()),
-    ).rejects.toThrow("--file");
+    await expect(runQueueValidate({ argv: [], flags: {} }, testContext())).rejects.toThrow(
+      "--file",
+    );
   });
 
   test("valid manifest → pass, items + next in JSON output", async () => {
@@ -132,10 +132,7 @@ describe("runQueueValidate — command contract (RFC-1140)", () => {
       "id: block-h\ncreatedAt: 2026-09-23\nitems:\n  - id: RFC-1400\n  - id: RFC-1401\n",
     );
 
-    const result = await runQueueValidate(
-      { argv: [], flags: { file } },
-      testContext(),
-    );
+    const result = await runQueueValidate({ argv: [], flags: { file } }, testContext());
 
     expect(result?.data?.status).toBe("pass");
     expect(result?.data?.queue).toBe("block-h");
@@ -152,10 +149,7 @@ describe("runQueueValidate — command contract (RFC-1140)", () => {
       "id: block-i\ncreatedAt: 2026-09-23\nitems:\n  - id: RFC-9999\n",
     );
 
-    const result = await runQueueValidate(
-      { argv: [], flags: { file } },
-      testContext(),
-    );
+    const result = await runQueueValidate({ argv: [], flags: { file } }, testContext());
 
     expect(result?.data?.status).toBe("fail");
     expect(result?.exitCode).toBe(1);
@@ -165,10 +159,7 @@ describe("runQueueValidate — command contract (RFC-1140)", () => {
   test("empty items → pass with next null", async () => {
     const file = await writeManifest("block-j", "id: block-j\ncreatedAt: 2026-09-23\nitems: []\n");
 
-    const result = await runQueueValidate(
-      { argv: [], flags: { file } },
-      testContext(),
-    );
+    const result = await runQueueValidate({ argv: [], flags: { file } }, testContext());
 
     expect(result?.data?.status).toBe("pass");
     expect(result?.data?.items).toEqual([]);

package/os/rfc/acceptance.ts

@@ -18,8 +18,9 @@ prose checklist.
 </CHANGE_SUMMARY>
 */
 
-import { spawn } from "node:child_process";
-import { stat, readFile } from "node:fs/promises";
+import { spawn } from "../../src/utils/sync-fs.ts";
+import { ambientIo, resolveIo } from "../../src/utils/io.ts";
+
 import path from "node:path";
 import { parse as yamlParse } from "yaml";
 import { Ajv } from "ajv";
@@ -40,12 +41,16 @@ import { RFC_DIR, RFC_PROBE_BINDING_CUTOFF } from "./types.ts";
 import { listRfcFiles, readAndParseRfc } from "./frontmatter-io.ts";
 import { evaluateAcceptanceCriteria, computeProbeCoverage } from "./handlers/validate-rules.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 RUN_PROBE_ALLOWED_PREFIX = "werkstatt ";
 
 async function loadManifestCommandNames(workspaceRoot: string): Promise<Set<string>> {
   const manifestPath = path.join(workspaceRoot, "docs", "command-manifest.generated.yaml");
   try {
-    const raw = await readFile(manifestPath, "utf-8");
+    const raw = await io.readFile(manifestPath);
     const manifest = yamlParse(raw) as { commands?: Array<{ name: string }> };
     return new Set((manifest.commands ?? []).map((c) => c.name));
   } catch {
@@ -290,7 +295,7 @@ export async function runProbe(
     }
     case "file-exists": {
       try {
-        await stat(path.join(workspaceRoot, probe.path));
+        await io.stat(path.join(workspaceRoot, probe.path));
         return { probe, ok: true, detail: "exists" };
       } catch {
         return { probe, ok: false, detail: "does not exist" };
@@ -298,7 +303,7 @@ export async function runProbe(
     }
     case "file-contains": {
       try {
-        const content = await readFile(path.join(workspaceRoot, probe.path), "utf8");
+        const content = await io.readFile(path.join(workspaceRoot, probe.path));
         const re = new RegExp(probe.pattern, "m");
         const ok = re.test(content);
         return { probe, ok, detail: ok ? "pattern found" : "pattern not found" };
@@ -336,7 +341,7 @@ export async function runProbe(
       const artifactPath = path.join(workspaceRoot, probe.artifact);
       let raw: string;
       try {
-        raw = await readFile(artifactPath, "utf8");
+        raw = await io.readFile(artifactPath);
       } catch {
         return { probe, ok: false, detail: "artifact file not found" };
       }
@@ -373,6 +378,7 @@ export async function runRfcAcceptanceRun(
   input: ForgeCommandInput,
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<RfcAcceptanceRunResult>> {
+  const _io = resolveIo(context.io);
   const { workspaceRoot } = context;
   const rfcDirPath = path.join(workspaceRoot, RFC_DIR);
   const targetId = input.flags["id"] as string | undefined;

package/os/rfc/decision-log.ts

@@ -15,8 +15,8 @@ keywords for rfc.create consultation, and generate/validate projections.
 </CHANGE_SUMMARY>
 */
 
-import { readFile } from "node:fs/promises";
 import { join } from "node:path";
+import { resolveIo } from "../../src/utils/io.ts";
 
 import { writeFileAtomic } from "../../src/utils/fs-atomic.ts";
 import { buildGeneratedHeader } from "../../src/utils/generated-marker.ts";
@@ -209,6 +209,7 @@ export async function runRfcDecisionLogGenerate(
   input: ForgeCommandInput,
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<DecisionLogResult>> {
+  const io = resolveIo(context.io);
   const { workspaceRoot, logger, outputFormat } = context;
   const checkMode = Boolean(input.flags["check"]);
   const rfcDirPath = join(workspaceRoot, RFC_DIR);
@@ -223,7 +224,7 @@ export async function runRfcDecisionLogGenerate(
     let drift = false;
 
     try {
-      const existingJson = await readFile(join(workspaceRoot, jsonRelPath), "utf-8");
+      const existingJson = await io.readFile(join(workspaceRoot, jsonRelPath));
       const expectedJson = `${buildGeneratedHeader({ filePath: jsonRelPath, ownerCommand: "rfc.decision-log.generate" })}${yamlStringify({ command: "rfc.decision-log.generate", status: "ok", count: entries.length, entries })}\n`;
       if (existingJson !== expectedJson) {
         drift = true;
@@ -245,7 +246,7 @@ export async function runRfcDecisionLogGenerate(
     }
 
     try {
-      const existingMd = await readFile(join(workspaceRoot, mdRelPath), "utf-8");
+      const existingMd = await io.readFile(join(workspaceRoot, mdRelPath));
       const expectedMd = renderMarkdown(entries);
       if (existingMd !== expectedMd) {
         drift = true;