@warpgogol/forge 5.2.4 → 5.3.1

package/os/rfc/verification-evidence.ts

@@ -17,8 +17,9 @@ a JSON evidence envelope to docs/rfcs/verification/<slug>.generated.yaml.
 </CHANGE_SUMMARY>
 */
 
-import { execFile } from "node:child_process";
-import { readFile, mkdir } from "node:fs/promises";
+import { execFile } from "../../src/utils/sync-fs.ts";
+import { ambientIo, resolveIo } from "../../src/utils/io.ts";
+
 import { join } from "node:path";
 import { performance } from "node:perf_hooks";
 import { byteHash } from "../../src/utils/hash.ts";
@@ -29,6 +30,10 @@ import { writeFileAtomic } from "../../src/utils/fs-atomic.ts";
 import { buildGeneratedHeader } from "../../src/utils/generated-marker.ts";
 import { stringify as yamlStringify } from "yaml";
 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 {
   AcceptanceProbe,
   RfcStatus,
@@ -74,7 +79,7 @@ export async function captureGitContext(
 export async function getKernelVersion(workspaceRoot: string): Promise<string> {
   try {
     const pkgPath = join(workspaceRoot, "packages", "os", "site-kernel", "package.json");
-    const pkg = JSON.parse(await readFile(pkgPath, "utf-8"));
+    const pkg = JSON.parse(await io.readFile(pkgPath));
     return String(pkg.version ?? "unknown");
   } catch {
     return "unknown";
@@ -120,6 +125,7 @@ export async function runRfcVerificationEmit(
   input: ForgeCommandInput,
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<RfcVerificationEmitResult>> {
+  const io = resolveIo(context.io);
   const { workspaceRoot, logger, outputFormat } = context;
   const rfcDirPath = join(workspaceRoot, RFC_DIR);
   const targetId = input.flags["id"] as string | undefined;
@@ -155,7 +161,7 @@ export async function runRfcVerificationEmit(
   }
   const kernelVersion = await getKernelVersion(workspaceRoot);
   const verificationDirAbs = join(workspaceRoot, VERIFICATION_DIR);
-  await mkdir(verificationDirAbs, { recursive: true });
+  await io.mkdir(verificationDirAbs);
 
   for (const fileName of allFiles) {
     const parsedFile = await readAndParseRfc(rfcDirPath, fileName);
@@ -176,7 +182,7 @@ export async function runRfcVerificationEmit(
     const probes = acceptance as AcceptanceProbe[];
     const probeRecords: VerificationEvidenceProbeRecord[] = [];
     const rfcFilePath = join(rfcDirPath, fileName);
-    const rfcMarkdown = await readFile(rfcFilePath, "utf-8");
+    const rfcMarkdown = await io.readFile(rfcFilePath);
     const emittedAt = new Date().toISOString();
 
     for (const probe of probes) {

package/os/rfc/verification-refresh.ts

@@ -17,8 +17,8 @@ lastRefreshedAt, replaces probes[] with fresh results. Supports --id,
 </CHANGE_SUMMARY>
 */
 
-import { readFile } from "node:fs/promises";
 import { join } from "node:path";
+import { resolveIo } from "../../src/utils/io.ts";
 import { performance } from "node:perf_hooks";
 import { parse as yamlParse } from "yaml";
 
@@ -52,6 +52,7 @@ export async function runRfcVerificationRefresh(
   input: ForgeCommandInput,
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<RfcVerificationRefreshResult>> {
+  const io = resolveIo(context.io);
   const { workspaceRoot, logger, outputFormat } = context;
   const rfcDirPath = join(workspaceRoot, RFC_DIR);
   const targetId = input.flags["id"] as string | undefined;
@@ -103,7 +104,7 @@ export async function runRfcVerificationRefresh(
 
     let existingEnvelope: VerificationEvidence | null = null;
     try {
-      const raw = await readFile(evidenceAbsPath, "utf-8");
+      const raw = await io.readFile(evidenceAbsPath);
       const parsed = yamlParse(raw) as VerificationEvidence;
       if (parsed && typeof parsed === "object" && parsed.rfcId) {
         existingEnvelope = parsed;
@@ -126,7 +127,7 @@ export async function runRfcVerificationRefresh(
     const probes = acceptance as AcceptanceProbe[];
     const probeRecords: VerificationEvidenceProbeRecord[] = [];
     const rfcFilePath = join(rfcDirPath, fileName);
-    const rfcMarkdown = await readFile(rfcFilePath, "utf-8");
+    const rfcMarkdown = await io.readFile(rfcFilePath);
     const now = new Date().toISOString();
 
     for (const probe of probes) {

package/os/session/frontmatter-io.ts

@@ -14,7 +14,7 @@ subdirectories from the main file list.
 </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 { SESSION_FILE_PATTERN, SESSION_RAW_SUBDIR, SESSION_ARCHIVE_SUBDIR } from "./types.ts";
@@ -43,9 +43,9 @@ export async function listSessionFiles(sessionDirPath: string): Promise<string[]
   const results: string[] = [];
 
   async function scanDir(dirPath: string, relativePrefix: string): Promise<void> {
-    let entries: import("node:fs").Dirent[];
+    let entries: Awaited<ReturnType<typeof fs.readdir>>;
     try {
-      entries = await fs.readdir(dirPath, { withFileTypes: true });
+      entries = await fs.readdir(dirPath);
     } catch {
       return;
     }
@@ -54,10 +54,10 @@ export async function listSessionFiles(sessionDirPath: string): Promise<string[]
         continue;
       }
       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 !== "README.md" &&
         SESSION_FILE_PATTERN.test(entry.name)
@@ -80,18 +80,18 @@ export async function listArchivedSessionFiles(sessionDirPath: string): Promise<
   const results: string[] = [];
 
   async function scanDir(dirPath: string, relativePrefix: string): Promise<void> {
-    let entries: import("node:fs").Dirent[];
+    let entries: Awaited<ReturnType<typeof fs.readdir>>;
     try {
-      entries = await fs.readdir(dirPath, { withFileTypes: true });
+      entries = await fs.readdir(dirPath);
     } catch {
       return;
     }
     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") &&
         SESSION_FILE_PATTERN.test(entry.name)
       ) {
@@ -110,7 +110,7 @@ export async function readAndParseSession(
 ): Promise<{ fileName: string; parsed: ParsedSession } | undefined> {
   try {
     const filePath = path.join(sessionDirPath, fileName);
-    const content = await fs.readFile(filePath, "utf-8");
+    const content = await fs.readFile(filePath);
     return { fileName, parsed: parseSessionFile(content) };
   } catch {
     return undefined;
@@ -125,10 +125,10 @@ export async function readAndParseSession(
 export async function listNonMarkdownSessionFiles(sessionDirPath: string): Promise<string[]> {
   const results: string[] = [];
   try {
-    const entries = await fs.readdir(sessionDirPath, { withFileTypes: true });
+    const entries = await fs.readdir(sessionDirPath);
     for (const entry of entries) {
       if (
-        entry.isFile() &&
+        entry.isFile &&
         !entry.name.endsWith(".md") &&
         entry.name !== ".gitkeep" &&
         entry.name !== "README.md"
@@ -150,9 +150,9 @@ export async function listRawFiles(sessionDirPath: string): Promise<string[]> {
   const rawDirPath = path.join(sessionDirPath, SESSION_RAW_SUBDIR);
   const results: string[] = [];
   try {
-    const entries = await fs.readdir(rawDirPath, { withFileTypes: true });
+    const entries = await fs.readdir(rawDirPath);
     for (const entry of entries) {
-      if (entry.isFile()) {
+      if (entry.isFile) {
         results.push(entry.name);
       }
     }

package/os/session/handlers/archive.ts

@@ -16,7 +16,7 @@ younger than threshold are moved back to docs/sessions/.
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs/promises";
+import { ambientIo as fs } from "../../../src/utils/io.ts";
 import path from "node:path";
 import {
   listSessionFiles,
@@ -131,7 +131,9 @@ export async function runSessionArchive(
       }
 
       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 {
@@ -139,7 +141,7 @@ export async function runSessionArchive(
       }
 
       if (!dryRun) {
-        await fs.mkdir(archiveDirPath, { recursive: true });
+        await fs.mkdir(archiveDirPath);
         try {
           await fs.rename(path.join(sessionDirPath, fileName), targetPath);
         } catch (err) {
@@ -217,7 +219,9 @@ export async function runSessionArchive(
       }
 
       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: archRelFile, reason: "destination exists" });
         continue;
       } catch {

package/os/session/handlers/metrics-aggregate.ts

@@ -16,16 +16,30 @@ result when no metrics files exist.
 </CHANGE_SUMMARY>
 */
 
-import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
+import { ambientIo, resolveIo } from "../../../src/utils/io.ts";
 import { parse as yamlParse } from "yaml";
 
-import { METRICS_DIR, type MetricsAggregateResult, type SkillAggregate, type RfcMetrics, type SessionMetrics } from "../types.ts";
-import type { ForgeCommandInput, ForgeCommandResult, ForgeRuntimeContext } from "../../../src/types.ts";
+import {
+  METRICS_DIR,
+  type MetricsAggregateResult,
+  type SkillAggregate,
+  type RfcMetrics,
+  type SessionMetrics,
+} from "../types.ts";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+
+// Ambient default for helper fns without a context param — handlers override
+// with `const io = resolveIo(context.io)` inside their own scope.
+const io = ambientIo;
 
 async function readYamlFile<T>(filePath: string): Promise<T | null> {
   try {
-    const content = await readFile(filePath, "utf-8");
+    const content = await io.readFile(filePath);
     return yamlParse(content) as T;
   } catch {
     return null;
@@ -36,6 +50,7 @@ export async function runMetricsAggregate(
   input: ForgeCommandInput,
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<MetricsAggregateResult>> {
+  const io = resolveIo(context.io);
   const { workspaceRoot, outputFormat } = context;
   const skillFilter = input.flags["skill"] as string | undefined;
   const since = input.flags["since"] as string | undefined;
@@ -48,13 +63,13 @@ export async function runMetricsAggregate(
   let sessionFiles: string[] = [];
 
   try {
-    rfcFiles = await readdir(rfcMetricsDir);
+    rfcFiles = (await io.readdir(rfcMetricsDir)).map((e) => e.name);
   } catch {
     // No RFC metrics directory yet
   }
 
   try {
-    sessionFiles = await readdir(sessionMetricsDir);
+    sessionFiles = (await io.readdir(sessionMetricsDir)).map((e) => e.name);
   } catch {
     // No session metrics directory yet
   }
@@ -109,11 +124,14 @@ export async function runMetricsAggregate(
     }
   >();
 
-  function recordSkill(skill: string, data: Partial<{
-    findings: number;
-    fixIterations: number;
-    durationMs: number;
-  }>) {
+  function recordSkill(
+    skill: string,
+    data: Partial<{
+      findings: number;
+      fixIterations: number;
+      durationMs: number;
+    }>,
+  ) {
     let entry = skillData.get(skill);
     if (!entry) {
       entry = {
@@ -173,7 +191,8 @@ export async function runMetricsAggregate(
       skill,
       invocations: data.invocations,
       avgFindings: data.findingsCount > 0 ? data.findingsSum / data.findingsCount : null,
-      avgFixIterations: data.fixIterationsCount > 0 ? data.fixIterationsSum / data.fixIterationsCount : null,
+      avgFixIterations:
+        data.fixIterationsCount > 0 ? data.fixIterationsSum / data.fixIterationsCount : null,
       avgDurationMs: data.durationCount > 0 ? data.durationSum / data.durationCount : null,
     });
   }
@@ -197,7 +216,9 @@ export async function runMetricsAggregate(
   };
 
   if (outputFormat === "pretty") {
-    context.logger.info(`[metrics.aggregate] ${perSkill.length} skill(s), ${filteredRfcs.length} RFC(s), ${filteredSessions.length} session(s)`);
+    context.logger.info(
+      `[metrics.aggregate] ${perSkill.length} skill(s), ${filteredRfcs.length} RFC(s), ${filteredSessions.length} session(s)`,
+    );
   }
 
   return {

package/os/session/handlers/metrics-rfc.ts

@@ -17,13 +17,18 @@ Writes to docs/metrics/rfcs/<rfc-id>.metrics.yaml via writeFileAtomic.
 </CHANGE_SUMMARY>
 */
 
-import { execFile } from "node:child_process";
-import { readFile, readdir, mkdir } from "node:fs/promises";
+import { execFile } from "../../../src/utils/sync-fs.ts";
+import { ambientIo } from "../../../src/utils/io.ts";
+
 import { join, dirname } from "node:path";
 
 import { writeFileAtomic } from "../../../src/utils/fs-atomic.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 {
   METRICS_DIR,
   type RfcMetrics,
@@ -111,7 +116,7 @@ async function findReviewReport(workspaceRoot: string, rfcId: string): Promise<s
   const reviewDir = join(workspaceRoot, "docs", "reviews", "code");
   let files: string[];
   try {
-    files = await readdir(reviewDir, { recursive: true });
+    files = await io.glob("**/*", { cwd: reviewDir });
   } catch {
     return null;
   }
@@ -121,7 +126,7 @@ async function findReviewReport(workspaceRoot: string, rfcId: string): Promise<s
     if (!file.endsWith(".md")) continue;
     if (file.toLowerCase().includes(rfcLower)) {
       try {
-        const content = await readFile(join(reviewDir, file), "utf-8");
+        const content = await io.readFile(join(reviewDir, file));
         return content;
       } catch {
         continue;
@@ -177,7 +182,7 @@ async function parseVerificationEvidence(
   );
   let content: string;
   try {
-    content = await readFile(evidencePath, "utf-8");
+    content = await io.readFile(evidencePath);
   } catch {
     return null;
   }
@@ -208,7 +213,7 @@ async function parseAcceptanceCriteria(
   const rfcDir = join(workspaceRoot, "docs", "rfcs");
   let files: string[];
   try {
-    files = await readdir(rfcDir);
+    files = (await io.readdir(rfcDir)).map((e) => e.name);
   } catch {
     return { acceptanceCriteriaTotal: 0, acceptanceCriteriaMet: 0 };
   }
@@ -223,7 +228,7 @@ async function parseAcceptanceCriteria(
 
   let content: string;
   try {
-    content = await readFile(join(rfcDir, rfcFile), "utf-8");
+    content = await io.readFile(join(rfcDir, rfcFile));
   } catch {
     return { acceptanceCriteriaTotal: 0, acceptanceCriteriaMet: 0 };
   }
@@ -332,7 +337,7 @@ export async function generateRfcMetrics(
     "rfcs",
     `${rfcId.toLowerCase()}.metrics.yaml`,
   );
-  await mkdir(dirname(metricsFilePath), { recursive: true });
+  await io.mkdir(dirname(metricsFilePath));
   await writeFileAtomic(metricsFilePath, yamlContent);
 
   return `${METRICS_DIR}/rfcs/${rfcId.toLowerCase()}.metrics.yaml`;

package/os/session/handlers/metrics-session.ts

@@ -17,8 +17,8 @@ docs/metrics/sessions/<session-id>.metrics.yaml via writeFileAtomic.
 </CHANGE_SUMMARY>
 */
 
-import { readdir, mkdir } from "node:fs/promises";
 import { join, dirname } from "node:path";
+import { ambientIo } from "../../../src/utils/io.ts";
 
 import { writeFileAtomic } from "../../../src/utils/fs-atomic.ts";
 import { stringify as yamlStringify } from "yaml";
@@ -32,6 +32,10 @@ import {
 } from "../types.ts";
 import type { AtifMessage } from "../atif-parser.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;
+
 // ─── Skill name extraction ───────────────────────────────────────────────────
 
 const SKILL_PATTERN = /\b(fo-[a-z]+(?:-[a-z]+)*)\b/g;
@@ -116,7 +120,7 @@ async function extractDocumentRefs(
 
   let existingMetricsFiles: string[] = [];
   try {
-    existingMetricsFiles = await readdir(metricsRfcDir);
+    existingMetricsFiles = (await io.readdir(metricsRfcDir)).map((e) => e.name);
   } catch {
     // No metrics directory yet
   }
@@ -203,7 +207,7 @@ export async function generateSessionMetrics(
 
   const yamlContent = yamlStringify(metrics, { lineWidth: 120 });
   const metricsFilePath = join(workspaceRoot, METRICS_DIR, "sessions", `${sessionId}.metrics.yaml`);
-  await mkdir(dirname(metricsFilePath), { recursive: true });
+  await io.mkdir(dirname(metricsFilePath));
   await writeFileAtomic(metricsFilePath, yamlContent);
 
   return `${METRICS_DIR}/sessions/${sessionId}.metrics.yaml`;

package/os/session/handlers/save.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 { createHash } from "node:crypto";
 import YAML from "yaml";
@@ -182,7 +182,9 @@ export async function runSessionSave(
       ? rawFileFlag
       : path.join(workspaceRoot, rawFileFlag);
     try {
-      await fs.access(resolvedPath);
+      await fs.exists(resolvedPath).then((ok) => {
+        if (!ok) throw Object.assign(new Error("ENOENT"), { code: "ENOENT" });
+      });
     } catch {
       throw new Error(`Raw file not found: ${rawFileFlag}`);
     }
@@ -193,8 +195,8 @@ export async function runSessionSave(
     ];
   } else {
     try {
-      const entries = await fs.readdir(rawDirPath, { withFileTypes: true });
-      rawFiles = entries.filter((e) => e.isFile()).map((e) => e.name);
+      const entries = await fs.readdir(rawDirPath);
+      rawFiles = entries.filter((e) => e.isFile).map((e) => e.name);
     } catch {
       rawFiles = [];
     }
@@ -234,7 +236,7 @@ export async function runSessionSave(
     const rawFilePath = path.join(rawDirPath, rawFileName);
     let rawContent: string;
     try {
-      rawContent = await fs.readFile(rawFilePath, "utf-8");
+      rawContent = await fs.readFile(rawFilePath);
     } catch (err) {
       if ((err as NodeJS.ErrnoException).code === "ENOENT") {
         skipped.push({ rawFile: rawFileName, reason: "already processed by another process" });
@@ -267,7 +269,9 @@ export async function runSessionSave(
     const outputRel = path.join(SESSION_DIR, outputFileName);
 
     try {
-      await fs.access(outputPath);
+      await fs.exists(outputPath).then((ok) => {
+        if (!ok) throw Object.assign(new Error("ENOENT"), { code: "ENOENT" });
+      });
       skipped.push({ rawFile: rawFileName, reason: "already converted" });
       if (outputFormat === "pretty") {
         logger.info(`Skipped ${rawFileName}: already converted to ${outputRel}`);
@@ -298,8 +302,8 @@ export async function runSessionSave(
 
     let metricsPath: string | undefined;
     if (!dryRun) {
-      await fs.mkdir(sessionDirPath, { recursive: true });
-      await fs.writeFile(outputPath, markdown, "utf-8");
+      await fs.mkdir(sessionDirPath);
+      await fs.writeFile(outputPath, markdown);
 
       // ── RFC-1053: Generate session metrics from ATIF messages (non-fatal) ──
       try {

package/os/session/session.module.ts

@@ -8,6 +8,7 @@
 <CHANGE_SUMMARY>
   <item>RFC-0537: initial forgeSessionModule registering session.save, session.archive, session.validate, session.list commands.</item>
   <item>RFC-1053: register metrics.aggregate command for skill effectiveness metrics aggregation.</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>
 */
 
@@ -35,6 +36,7 @@ export async function createForgeSessionModule(): Promise<ForgeModule> {
         scope: "workspace",
         mutatesState: true,
         writes: ["docs/sessions/*.md"],
+        generates: [],
         reads: ["docs/sessions/.raw/*"],
         cacheable: false,
         flags: {
@@ -65,6 +67,7 @@ export async function createForgeSessionModule(): Promise<ForgeModule> {
         scope: "workspace",
         mutatesState: true,
         writes: ["docs/sessions/*.md", "docs/sessions/archive/**"],
+        generates: [],
         reads: ["docs/sessions/**/*.md"],
         cacheable: false,
         flags: {
@@ -81,6 +84,7 @@ export async function createForgeSessionModule(): Promise<ForgeModule> {
       },
       {
         name: "session.validate",
+        mutatesState: false,
         contract: "session",
         rules: [],
         description:
@@ -98,6 +102,7 @@ export async function createForgeSessionModule(): Promise<ForgeModule> {
       },
       {
         name: "session.list",
+        mutatesState: false,
         description:
           "List all sessions. Filter with --date-from, --date-to, --rfc, --type flags. " +
           "Use --json for machine-readable output. Parses frontmatter on the fly. " +
@@ -127,6 +132,7 @@ export async function createForgeSessionModule(): Promise<ForgeModule> {
       },
       {
         name: "metrics.aggregate",
+        mutatesState: true,
         description:
           "Query and aggregate skill effectiveness metrics from docs/metrics/ files. " +
           "Returns per-skill statistics (invocations, avgFindings, avgFixIterations, avgDurationMs). " +

package/os/spec/live-spec-list.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 YAML from "yaml";
 import type {
@@ -33,11 +33,11 @@ export async function runSpecLiveList(
   const entries: SpecLiveListEntry[] = [];
 
   if (existsSync(liveSpecsDir)) {
-    const files = await fs.readdir(liveSpecsDir);
+    const files = (await fs.readdir(liveSpecsDir)).map((e) => e.name);
     for (const file of files) {
       if (!file.endsWith(".md") || file === "README.md") continue;
       const filePath = path.join(liveSpecsDir, file);
-      const content = await fs.readFile(filePath, "utf-8");
+      const content = await fs.readFile(filePath);
       const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
       if (!match) continue;
       const fm = (YAML.parse(match[1]!) ?? {}) as Record<string, unknown>;

package/os/spec/live-spec-merge.ts

@@ -14,8 +14,8 @@ headings, and writes atomically (RFC-0711).</purpose>
 </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 YAML from "yaml";
 import type {
@@ -223,7 +223,7 @@ export async function runSpecLiveMerge(
     };
   }
 
-  const rfcContent = await fs.readFile(path.join(rfcDir, rfcFile), "utf-8");
+  const rfcContent = await fs.readFile(path.join(rfcDir, rfcFile));
   const parsed = parseRfcFile(rfcContent);
   const fm = parsed.frontmatter;
 
@@ -282,7 +282,7 @@ export async function runSpecLiveMerge(
 
   let existingSpec: LivingSpec | null = null;
   if (existsSync(specFilePath)) {
-    const specContent = await fs.readFile(specFilePath, "utf-8");
+    const specContent = await fs.readFile(specFilePath);
     existingSpec = parseLivingSpec(specContent);
   }
 
@@ -311,7 +311,7 @@ export async function runSpecLiveMerge(
     };
 
     if (!dryRun) {
-      await fs.mkdir(liveSpecsDir, { recursive: true });
+      await fs.mkdir(liveSpecsDir);
       await writeFileIfChanged(specFilePath, serializeLivingSpec(newSpec));
     }
 

package/os/spec/live-spec-show.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 YAML from "yaml";
 import type {
@@ -68,7 +68,7 @@ export async function runSpecLiveShow(
     };
   }
 
-  const content = await fs.readFile(specFilePath, "utf-8");
+  const content = await fs.readFile(specFilePath);
   const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
   if (!match) {
     return {

package/os/spec/live-spec-validate.ts

@@ -11,8 +11,8 @@ with rules V-LS-01..05 (RFC-0711).</purpose>
 </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 YAML from "yaml";
 import type {
@@ -75,13 +75,13 @@ export async function runSpecLiveValidate(
     };
   }
 
-  const files = await fs.readdir(liveSpecsDir);
+  const files = (await fs.readdir(liveSpecsDir)).map((e) => e.name);
   const specFiles = files.filter((f) => f.endsWith(".md") && f !== "README.md");
 
   for (const file of specFiles) {
     specsChecked++;
     const filePath = path.join(liveSpecsDir, file);
-    const content = await fs.readFile(filePath, "utf-8");
+    const content = await fs.readFile(filePath);
     const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
     if (!match) {
       violations.push({ rule: "V-LS-01", message: `${file}: no valid frontmatter block`, domain: file });