@warpgogol/forge 5.2.4 → 5.3.1

package/os/rfc/dna-trace.ts

@@ -15,14 +15,18 @@ entries from all RFCs, and builds a bidirectional trace matrix.
 </CHANGE_SUMMARY>
 */
 
-import { readFile } from "node:fs/promises";
 import { join } from "node:path";
+import { ambientIo, resolveIo } from "../../src/utils/io.ts";
 
 import { writeFileAtomic } from "../../src/utils/fs-atomic.ts";
 import { buildGeneratedHeader } from "../../src/utils/generated-marker.ts";
 import { stringify as yamlStringify } from "yaml";
 import { listRfcFiles, readAndParseRfc } from "./frontmatter-io.ts";
 import { RFC_DIR } 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 {
   Diagnostic,
   ForgeCommandInput,
@@ -56,7 +60,7 @@ export interface DnaTraceResult {
 async function parseDnaRegistry(workspaceRoot: string): Promise<Set<string>> {
   const ids = new Set<string>();
   try {
-    const src = await readFile(join(workspaceRoot, DNA_REGISTRY_PATH), "utf-8");
+    const src = await io.readFile(join(workspaceRoot, DNA_REGISTRY_PATH));
     for (const m of src.matchAll(DNA_HEADING_RE)) {
       ids.add(`DNA-${m[1]}`);
     }
@@ -186,6 +190,7 @@ export async function runRfcDnaTraceValidate(
   input: ForgeCommandInput,
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<DnaTraceResult>> {
+  const _io = resolveIo(context.io);
   const { workspaceRoot, logger, outputFormat } = context;
   const dnaFilter = input.flags["dna"] as string | undefined;
 
@@ -241,6 +246,7 @@ export async function runRfcDnaTraceGenerate(
   _input: ForgeCommandInput,
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<DnaTraceResult>> {
+  const _io = resolveIo(context.io);
   const { workspaceRoot, logger, outputFormat } = context;
 
   const { entries, diagnostics, registryIds } = await buildDnaTrace(workspaceRoot);

package/os/rfc/frontmatter-io.ts

@@ -22,7 +22,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 YAML from "yaml";
 
@@ -47,13 +47,13 @@ export async function listRfcFiles(rfcDirPath: 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("rfc-0000") &&
           !entry.name.endsWith(".generated.md") &&
@@ -84,7 +84,7 @@ export async function readAndParseRfc(
 ): Promise<ReadAndParseRfcResult | undefined> {
   try {
     const filePath = path.join(rfcDirPath, fileName);
-    const content = await fs.readFile(filePath, "utf-8");
+    const content = await fs.readFile(filePath);
     return { fileName, parsed: parseRfcFile(content) };
   } catch (e) {
     if (e instanceof Error) {

package/os/rfc/handlers/archive.ts

@@ -22,7 +22,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 { stringify as yamlStringify } from "yaml";
 import { listRfcFiles, readAndParseRfc } from "../frontmatter-io.ts";
@@ -137,7 +137,9 @@ export async function runRfcArchive(
       }
 
       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 {
@@ -145,7 +147,7 @@ export async function runRfcArchive(
       }
 
       if (!dryRun) {
-        await fs.mkdir(targetDir, { recursive: true });
+        await fs.mkdir(targetDir);
         try {
           await fs.rename(path.join(rfcDirPath, fileName), targetPath);
         } catch (err) {
@@ -184,7 +186,9 @@ export async function runRfcArchive(
       }
 
       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 {
@@ -269,7 +273,7 @@ export async function runRfcArchive(
         count: entries.length,
         entries,
       };
-      await fs.writeFile(path.join(workspaceRoot, outRel), `${yamlStringify(payload)}`, "utf-8");
+      await fs.writeFile(path.join(workspaceRoot, outRel), `${yamlStringify(payload)}`);
       indexRefreshed = true;
       if (outputFormat === "pretty") {
         logger.info(`rfc.archive: refreshed ${outRel} (${entries.length} entries)`);

package/os/rfc/handlers/check.ts

@@ -10,7 +10,7 @@
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs/promises";
+import { ambientIo as fs } from "../../../src/utils/io.ts";
 import path from "node:path";
 
 import { listRfcFiles, readAndParseRfc } from "../frontmatter-io.ts";
@@ -117,7 +117,7 @@ async function loadFeatureKeysForApps(
       "features.ts",
     );
     try {
-      const source = await fs.readFile(featuresPath, "utf-8");
+      const source = await fs.readFile(featuresPath);
       result.set(siteName, extractDefinedFeatureKeysFromSource(source));
     } catch {
       // features.ts not found for this app — skip
@@ -165,7 +165,9 @@ export async function runRfcCheck(
       if (!isLiteralFsPath(declaredPath)) continue;
       const absPath = path.join(workspaceRoot, declaredPath);
       try {
-        await fs.access(absPath);
+        await fs.exists(absPath).then((ok) => {
+          if (!ok) throw Object.assign(new Error("ENOENT"), { code: "ENOENT" });
+        });
       } catch {
         violations.push({
           rfcId,

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

@@ -25,8 +25,9 @@ Sweep batch 2: real KEY_DECISIONS on 10 files, expanded purposes (CONTRACT-02/PU
 </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";
@@ -43,6 +44,10 @@ import { evaluateAcceptanceCriteria } from "./validate-rules.ts";
 import { toIsoDate } from "./shared.ts";
 import { RFC_DIR, RFC_METADATA_CUTOFF, RFC_PROBE_BINDING_CUTOFF } from "../types.ts";
 import type { RfcStatus, RfcImplementStampViolation, RfcImplementStampResult } 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,
@@ -162,16 +167,15 @@ async function acquireRfcLock(
 ): Promise<{ acquired: boolean; lockPath: string }> {
   const lockPath = lockFilePath(workspaceRoot, rfcId);
   const lockDir = dirname(lockPath);
-  await mkdir(lockDir, { recursive: true });
+  await io.mkdir(lockDir);
 
   // Atomic lock acquisition via O_EXCL file creation
-  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 };
@@ -180,7 +184,7 @@ async function acquireRfcLock(
 
 async function releaseRfcLock(lockPath: string): Promise<void> {
   try {
-    await unlink(lockPath);
+    await io.rm(lockPath);
   } catch {
     // Lock file already removed — safe
   }
@@ -195,7 +199,7 @@ async function checkExistingEvidence(
   const slug = rfcId.toLowerCase();
   const evidencePath = join(workspaceRoot, VERIFICATION_DIR, `${slug}.generated.yaml`);
   try {
-    const content = await readFile(evidencePath, "utf-8");
+    const content = await io.readFile(evidencePath);
     const evidence = yamlParse(content) as { overall?: string };
     return { exists: true, overall: String(evidence.overall ?? "") };
   } catch {
@@ -239,6 +243,7 @@ export async function runRfcImplementStamp(
   input: ForgeCommandInput,
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<RfcImplementStampResult>> {
+  const io = resolveIo(context.io);
   const { workspaceRoot, logger, outputFormat, dryRun } = context;
   const rfcDirPath = join(workspaceRoot, RFC_DIR);
 
@@ -437,7 +442,7 @@ export async function runRfcImplementStamp(
   try {
     // ── Atomic mutation ──────────────────────────────────────────────────────
     const rfcFilePath = join(rfcDirPath, targetFile);
-    const rfcSource = await readFile(rfcFilePath, "utf-8");
+    const rfcSource = await io.readFile(rfcFilePath);
 
     const today = toIsoDate(new Date());
     const stampedAt = new Date().toISOString();

package/os/rfc/handlers/index-graph.ts

@@ -16,7 +16,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 yamlParse, stringify as yamlStringify } from "yaml";
 
@@ -78,7 +78,7 @@ export async function runRfcIndexGenerate(
       count: entries.length,
       entries,
     };
-    await fs.writeFile(path.join(workspaceRoot, outRel), `${yamlStringify(payload)}`, "utf-8");
+    await fs.writeFile(path.join(workspaceRoot, outRel), `${yamlStringify(payload)}`);
     written = outRel;
   }
 
@@ -166,7 +166,7 @@ export async function runRfcIndexValidate(
   // RFC-IDX-01: missing index file
   let indexContent: string;
   try {
-    indexContent = await fs.readFile(indexPath, "utf-8");
+    indexContent = await fs.readFile(indexPath);
   } catch {
     violations.push({
       rule: "RFC-IDX-01",

package/os/rfc/handlers/lifecycle.ts

@@ -18,8 +18,8 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 </CHANGE_SUMMARY>
 */
 
-import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { ambientIo, resolveIo } from "../../../src/utils/io.ts";
 import { parse as yamlParse } from "yaml";
 
 import type { CommandRegistry } from "../../../src/types.ts";
@@ -42,10 +42,14 @@ import type {
 import { RFC_DIR, RFC_METADATA_CUTOFF } from "../types.ts";
 import { commandBuckets } from "./shared.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;
+
 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 {
@@ -195,6 +199,7 @@ export async function runRfcCommandLifecycleValidate(
   input: ForgeCommandInput,
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<RfcCommandLifecycleValidationResult>> {
+  const _io = resolveIo(context.io);
   const { workspaceRoot, logger, outputFormat } = context;
   const rfcDirPath = path.join(workspaceRoot, RFC_DIR);
   const targetId = input.flags["id"] as string | undefined;

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

@@ -19,7 +19,8 @@ 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 { writeFileSync } from "../../../src/utils/sync-fs.ts";
 import path from "node:path";
 import { toKebabCase } from "../../../src/utils/string-utils.ts";
 import { listRfcFiles, readAndParseRfc } from "../frontmatter-io.ts";
@@ -190,7 +191,7 @@ export async function runRfcCreate(
   const templatePath = resolveRfcTemplate(workspaceRoot);
   let templateContent: string;
   try {
-    templateContent = await fs.readFile(templatePath, "utf-8");
+    templateContent = await fs.readFile(templatePath);
   } catch {
     throw new Error(`RFC template not found at ${templatePath}.`);
   }
@@ -250,14 +251,14 @@ export async function runRfcCreate(
     const claimPath = path.join(rfcDirPath, `${nextSlug}.claim`);
 
     try {
-      await fs.writeFile(claimPath, `${process.pid}\n`, { flag: "wx" });
+      writeFileSync(claimPath, `${process.pid}\n`, { flag: "wx" });
     } catch (err) {
       if ((err as NodeJS.ErrnoException).code === "EEXIST") {
         // Stale claim (crashed create) → reclaim and retry the same id.
         // Live claim → another create holds this id — move to the next.
         const st = await fs.stat(claimPath).catch(() => null);
         if (st && Date.now() - st.mtimeMs > CLAIM_STALE_MS) {
-          await fs.rm(claimPath, { force: true });
+          await fs.rm(claimPath);
         } else {
           candidate++;
         }
@@ -283,11 +284,11 @@ export async function runRfcCreate(
       content = content.replace(/^# RFC-0000: .+$/m, `# ${nextId}: ${title}`);
 
       const targetPath = path.join(rfcDirPath, fileName);
-      await fs.writeFile(targetPath, content, { flag: "wx" });
+      writeFileSync(targetPath, content, { flag: "wx" });
       relativeFile = path.join(RFC_DIR, fileName);
       allocated = true;
     } finally {
-      await fs.rm(claimPath, { force: true });
+      await fs.rm(claimPath);
     }
     if (allocated) break;
   }

package/os/rfc/handlers/shared.ts

@@ -10,8 +10,8 @@
 </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";
 
@@ -38,7 +38,7 @@ export async function loadInvariantIds(
   const re = new RegExp(`^##\\s+${prefix}-(\\d+)\\b`, "gm");
   for (const rel of relPaths) {
     try {
-      const src = await fs.readFile(path.join(workspaceRoot, rel), "utf-8");
+      const src = await fs.readFile(path.join(workspaceRoot, rel));
       for (const m of src.matchAll(re)) ids.add(parseInt(m[1]!, 10));
     } catch {
       // Doc not present at this path — try the next candidate.

package/os/rfc/handlers/supersede-propose.ts

@@ -20,8 +20,8 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 </CHANGE_SUMMARY>
 */
 
-import { readFile } from "node:fs/promises";
 import { join, basename } from "node:path";
+import { ambientIo, resolveIo } from "../../../src/utils/io.ts";
 
 import { toKebabCase } from "../../../src/utils/string-utils.ts";
 import { writeFileAtomic } from "../../../src/utils/fs-atomic.ts";
@@ -37,12 +37,16 @@ import type {
 } from "../../../src/types.ts";
 import { toIsoDate } from "./shared.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 DNA_REGISTRY_PATH = "docs/architecture-dna.md";
 const DNA_HEADING_RE = /^##\s+DNA-(\d+)\b/gm;
 
 async function validateDnaIds(workspaceRoot: string, ids: string[]): Promise<string[]> {
   const errors: string[] = [];
-  const registrySrc = await readFile(join(workspaceRoot, DNA_REGISTRY_PATH), "utf-8");
+  const registrySrc = await io.readFile(join(workspaceRoot, DNA_REGISTRY_PATH));
   const knownDna = new Set<string>();
   for (const m of registrySrc.matchAll(DNA_HEADING_RE)) {
     knownDna.add(`DNA-${m[1]}`);
@@ -68,6 +72,7 @@ export async function runRfcSupersedePropose(
   input: ForgeCommandInput,
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<RfcSupersedeProposeResult>> {
+  const io = resolveIo(context.io);
   const { workspaceRoot, logger, outputFormat } = context;
   const rfcDirPath = join(workspaceRoot, RFC_DIR);
 
@@ -147,7 +152,7 @@ export async function runRfcSupersedePropose(
   const templatePath = resolveRfcTemplate(workspaceRoot);
   let templateContent: string;
   try {
-    templateContent = await readFile(templatePath, "utf-8");
+    templateContent = await io.readFile(templatePath);
   } catch {
     throw new Error(`RFC template not found at ${templatePath}.`);
   }

package/os/rfc/handlers/validate-rules-rfc1006.test.ts

@@ -168,7 +168,10 @@ describe("V-38: document readiness completeness (RFC-1006)", () => {
     const body = BASE_BODY.replace(
       "DOCUMENT_READINESS_HERE",
       "## Document readiness\n\n- [ ] DR-1: alternatives listed",
-    ).replace("ACCEPTANCE_HERE", "- [x] AC-1: test (evidence: test.ts:1)\n- [x] AC-2: test2 (evidence: test.ts:2)\n- [x] AC-3: test3 (evidence: test.ts:3)");
+    ).replace(
+      "ACCEPTANCE_HERE",
+      "- [x] AC-1: test (evidence: test.ts:1)\n- [x] AC-2: test2 (evidence: test.ts:2)\n- [x] AC-3: test3 (evidence: test.ts:3)",
+    );
     const parsed = makeParsed("accepted", body);
     const violations = await runValidate(parsed);
     const v38 = filterRule(violations, "V-38");
@@ -180,7 +183,10 @@ describe("V-38: document readiness completeness (RFC-1006)", () => {
     const body = BASE_BODY.replace(
       "DOCUMENT_READINESS_HERE",
       "## Document readiness\n\n- [x] DR-1: alternatives listed (evidence: file: test.md:1)",
-    ).replace("ACCEPTANCE_HERE", "- [x] AC-1: test (evidence: test.ts:1)\n- [x] AC-2: test2 (evidence: test.ts:2)\n- [x] AC-3: test3 (evidence: test.ts:3)");
+    ).replace(
+      "ACCEPTANCE_HERE",
+      "- [x] AC-1: test (evidence: test.ts:1)\n- [x] AC-2: test2 (evidence: test.ts:2)\n- [x] AC-3: test3 (evidence: test.ts:3)",
+    );
     const parsed = makeParsed("accepted", body);
     const violations = await runValidate(parsed);
     const v38 = filterRule(violations, "V-38");
@@ -191,7 +197,10 @@ describe("V-38: document readiness completeness (RFC-1006)", () => {
     const body = BASE_BODY.replace(
       "DOCUMENT_READINESS_HERE",
       "## Document readiness\n\n- [ ] DR-1: alternatives listed",
-    ).replace("ACCEPTANCE_HERE", "- [x] AC-1: test (evidence: test.ts:1)\n- [x] AC-2: test2 (evidence: test.ts:2)\n- [x] AC-3: test3 (evidence: test.ts:3)");
+    ).replace(
+      "ACCEPTANCE_HERE",
+      "- [x] AC-1: test (evidence: test.ts:1)\n- [x] AC-2: test2 (evidence: test.ts:2)\n- [x] AC-3: test3 (evidence: test.ts:3)",
+    );
     const parsed = makeParsed("accepted", body, { createdAt: "2026-08-01" });
     const violations = await runValidate(parsed);
     const v38 = filterRule(violations, "V-38");
@@ -202,7 +211,10 @@ describe("V-38: document readiness completeness (RFC-1006)", () => {
     const body = BASE_BODY.replace(
       "DOCUMENT_READINESS_HERE",
       "## Document readiness\n\n- [ ] DR-1: alternatives listed",
-    ).replace("ACCEPTANCE_HERE", "- [x] AC-1: test (evidence: test.ts:1)\n- [x] AC-2: test2 (evidence: test.ts:2)\n- [x] AC-3: test3 (evidence: test.ts:3)");
+    ).replace(
+      "ACCEPTANCE_HERE",
+      "- [x] AC-1: test (evidence: test.ts:1)\n- [x] AC-2: test2 (evidence: test.ts:2)\n- [x] AC-3: test3 (evidence: test.ts:3)",
+    );
     const parsed = makeParsed("draft", body);
     const violations = await runValidate(parsed);
     const v38 = filterRule(violations, "V-38");
@@ -470,8 +482,8 @@ describe("Pre-cutoff exemption (RFC-1006)", () => {
     );
     const parsed = makeParsed("accepted", body, { createdAt: "2026-08-01" });
     const violations = await runValidate(parsed);
-    const newRules = violations.filter(
-      (v) => ["V-38", "V-39", "V-40", "V-41", "V-42"].includes(v.rule),
+    const newRules = violations.filter((v) =>
+      ["V-38", "V-39", "V-40", "V-41", "V-42"].includes(v.rule),
     );
     expect(newRules).toHaveLength(0);
   });

package/os/rfc/handlers/validate-rules.ts

@@ -20,8 +20,9 @@ Sweep batch 2: real KEY_DECISIONS on 10 files, expanded purposes (CONTRACT-02/PU
 */
 
 import path from "node:path";
-import { readFile, stat } from "node:fs/promises";
-import { execFile } from "node:child_process";
+import { ambientIo } from "../../../src/utils/io.ts";
+
+import { execFile } from "../../../src/utils/sync-fs.ts";
 
 import { parse as yamlParse } from "yaml";
 import { validateAcceptanceShape } from "../acceptance.ts";
@@ -43,6 +44,10 @@ import {
 import type { ProbeCoverageReport, AcceptanceProbe } from "../types.ts";
 import { DNA_DOCS, AP_DOCS } from "./shared.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 DNA_DOC = DNA_DOCS[0]!;
 const AP_DOC = AP_DOCS[0]!;
 
@@ -831,7 +836,7 @@ export async function validateSingleRfc(
           } else if (evidence.startsWith("test:")) {
             const testPath = evidence.slice("test:".length).trim();
             try {
-              await stat(path.join(workspaceRoot, testPath));
+              await io.stat(path.join(workspaceRoot, testPath));
             } catch {
               addViolation(
                 rfcId,
@@ -844,7 +849,7 @@ export async function validateSingleRfc(
             const lastColon = evidence.lastIndexOf(":");
             const filePath = evidence.slice(0, lastColon).trim();
             try {
-              await stat(path.join(workspaceRoot, filePath));
+              await io.stat(path.join(workspaceRoot, filePath));
             } catch {
               addViolation(
                 rfcId,
@@ -1110,7 +1115,7 @@ export async function validateSingleRfc(
     let evidenceOk = false;
     let evidenceOverall = "";
     try {
-      const evidenceContent = await readFile(evidenceAbsPath, "utf-8");
+      const evidenceContent = await io.readFile(evidenceAbsPath);
       const evidence = yamlParse(evidenceContent) as { overall?: string };
       evidenceOverall = String(evidence.overall ?? "");
       evidenceOk = evidenceOverall === "pass";

package/os/rfc/handlers/validate.test.ts

@@ -0,0 +1,71 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for runRfcValidate flag handling — the --id guard that
+rejects non-string values before file scanning.</purpose>
+<non-goals>
+  <item>Do not duplicate validate-rules coverage — V-rule behavior lives in validate-rules*.test.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial test — non-string --id (boolean/array from unvalidated flag input) throws a clear flag error instead of TypeError in rfcFileMatchesId.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect, describe } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { runRfcValidate } from "./validate.ts";
+import type {
+  ForgeCommandInput,
+  ForgeFlagValue,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+
+function makeContext(workspaceRoot: string): ForgeRuntimeContext {
+  return {
+    workspaceRoot,
+    logger: {
+      info: () => {},
+      success: () => {},
+      warn: () => {},
+      error: () => {},
+      section: () => {},
+    },
+    dryRun: false,
+    outputFormat: "json",
+  };
+}
+
+describe("runRfcValidate --id flag guard", () => {
+  test.each([
+    ["boolean true", true],
+    ["string array", ["rfc-0001", "rfc-0002"]],
+  ])("non-string --id (%s) throws a clear error", async (_label, id) => {
+    const dir = mkdtempSync(join(tmpdir(), "rfc-validate-id-"));
+    try {
+      const input: ForgeCommandInput = {
+        argv: [],
+        flags: { id: id as ForgeFlagValue },
+      };
+      await expect(runRfcValidate(input, makeContext(dir))).rejects.toThrow(
+        'Flag "--id" for command "rfc.validate" requires a single string value.',
+      );
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("missing --id runs the all-files path without throwing the guard", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "rfc-validate-noid-"));
+    try {
+      const result = await runRfcValidate(
+        { argv: [], flags: {} },
+        makeContext(dir),
+      );
+      expect(result.data?.status).toBe("pass");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/os/rfc/handlers/validate.ts

@@ -13,6 +13,7 @@ Mechanical v1 to v2 header migration across the workspace: 942 files rewritten
   <item>RFC-1097: sweep — werkstatt-engine clean
 
 Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
+  <item>Guard --id against non-string values (boolean/array from unvalidated flag input) — throws a clear flag error instead of TypeError in rfcFileMatchesId.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -48,7 +49,11 @@ export async function runRfcValidate(
   const { workspaceRoot, logger, outputFormat } = context;
   const rfcDirPath = path.join(workspaceRoot, RFC_DIR);
 
-  const targetId = input.flags["id"] as string | undefined;
+  const rawId = input.flags["id"];
+  if (rawId !== undefined && typeof rawId !== "string") {
+    throw new Error(`Flag "--id" for command "rfc.validate" requires a single string value.`);
+  }
+  const targetId = rawId as string | undefined;
 
   const allFiles = await listRfcFiles(rfcDirPath);
   const filesToValidate = targetId

package/os/rfc/rfc-create-concurrent.test.ts

@@ -77,7 +77,9 @@ describe("rfc.create — RFC-1138 concurrent id allocation", () => {
     const ids = results.map((r) => (r.data as { id: string }).id);
     expect(new Set(ids).size).toBe(5);
 
-    const files = (await fs.readdir(rfcDir)).filter((f) => f.startsWith("rfc-") && f !== "rfc-0000-template.md");
+    const files = (await fs.readdir(rfcDir)).filter(
+      (f) => f.startsWith("rfc-") && f !== "rfc-0000-template.md",
+    );
     expect(files).toHaveLength(5);
   });
 
@@ -94,7 +96,11 @@ describe("rfc.create — RFC-1138 concurrent id allocation", () => {
   test("AC-5: pre-existing highest id is respected after a collision", async () => {
     // Seed rfc-0001 so the first create takes 0002; a file racing in at 0002
     // forces the retry path to land on 0003.
-    await fs.writeFile(path.join(rfcDir, "rfc-0001-seeded.md"), "---\nid: RFC-0001\n---\n", "utf-8");
+    await fs.writeFile(
+      path.join(rfcDir, "rfc-0001-seeded.md"),
+      "---\nid: RFC-0001\n---\n",
+      "utf-8",
+    );
     const winner = runRfcCreate(makeInput("Winner"), makeContext(tmpDir));
     // Interleave a manual claim at the id the scan will compute.
     const claim = (async () => {
@@ -111,7 +117,9 @@ describe("rfc.create — RFC-1138 concurrent id allocation", () => {
     const id = (result.data as { id: string }).id;
     // Either the create won 0002 (interloper lost the wx race) or it retried to 0003.
     expect(["RFC-0002", "RFC-0003"]).toContain(id);
-    const files = (await fs.readdir(rfcDir)).filter((f) => f.startsWith("rfc-") && f !== "rfc-0000-template.md");
+    const files = (await fs.readdir(rfcDir)).filter(
+      (f) => f.startsWith("rfc-") && f !== "rfc-0000-template.md",
+    );
     // Seeded + interloper (if it won) + create output — never a silent overwrite.
     expect(files.length).toBeGreaterThanOrEqual(2);
   });