@warpgogol/forge 5.2.4 → 5.3.1

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

@@ -21,8 +21,8 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs/promises";
-import { exec } from "node:child_process";
+import { ambientIo as fs } from "../../../src/utils/io.ts";
+import { exec } from "../../../src/utils/sync-fs.ts";
 import { promisify } from "node:util";
 import path from "node:path";
 import type {
@@ -141,7 +141,7 @@ async function appendAuditLog(
 ): Promise<void> {
   const logPath = path.join(repoRoot, AUDIT_LOG_PATH);
   const line = JSON.stringify(entry) + "\n";
-  await fs.appendFile(logPath, line, "utf8");
+  await fs.appendFile(logPath, line);
 }
 
 export async function runPinnedValidate(

package/os/core/handlers/profile-resolve.ts

@@ -11,7 +11,7 @@
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../../../src/utils/sync-fs.ts";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { resolveForgeRoot } from "../../../src/config/forge-config.ts";

package/os/core/handlers/public-surface.ts

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

package/os/core/handlers/release-prepare.ts

@@ -14,8 +14,8 @@
 </CHANGE_SUMMARY>
 */
 
-import { readFile, copyFile, mkdir, stat } from "node:fs/promises";
 import { join, basename } from "node:path";
+import { ambientIo, resolveIo } from "../../../src/utils/io.ts";
 import { createHash } from "node:crypto";
 import type {
   ForgeCommandInput,
@@ -27,6 +27,10 @@ import { loadWorkspaceDeps } from "../../werkstatt/handlers/workspace-deps.ts";
 import { writeFileIfChanged } from "../../../src/utils/fs-idempotent.ts";
 import type { ProfileRelease } from "../../../src/profiles/profile-schema.ts";
 
+// Ambient default for helper fns without a context param — handlers override
+// with `const io = resolveIo(context.io)` inside their own scope.
+const io = ambientIo;
+
 export interface ReleaseManifest {
   schemaVersion: string;
   releaseId: string;
@@ -58,7 +62,7 @@ function generateReleaseId(profileId: string, shortHash: string): string {
 
 async function readVersionFromPackageJson(workspaceRoot: string): Promise<string> {
   try {
-    const raw = await readFile(join(workspaceRoot, "package.json"), "utf8");
+    const raw = await io.readFile(join(workspaceRoot, "package.json"));
     const pkg = JSON.parse(raw) as { version?: string };
     return pkg.version ?? "0.0.0";
   } catch {
@@ -79,7 +83,7 @@ async function findBuiltArtifacts(
     if (!isGlob) {
       const fullPath = join(workspaceRoot, produceOutput);
       try {
-        const _s = await stat(fullPath);
+        const _s = await io.stat(fullPath);
         return [fullPath];
       } catch {
         return [];
@@ -110,6 +114,7 @@ export async function runReleasePrepare(
   input: ForgeCommandInput,
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<ForgeReleasePrepareResult>> {
+  const io = resolveIo(context.io);
   const { workspaceRoot, logger } = context;
   const { dryRun, profileIdOverride } = resolveLifecycleFlags(input, context);
 
@@ -212,7 +217,7 @@ export async function runReleasePrepare(
       if (!dryRun) {
         const { byteHashFile } = await loadWorkspaceDeps();
         hash = await byteHashFile(builtFile);
-        const stats = await stat(builtFile);
+        const stats = await io.stat(builtFile);
         size = stats.size;
         allHashes += hash;
       }
@@ -268,12 +273,12 @@ export async function runReleasePrepare(
     };
   }
 
-  await mkdir(releaseDir, { recursive: true });
+  await io.mkdir(releaseDir);
 
   for (const a of manifestArtifacts) {
     const srcPath = join(workspaceRoot, a.path);
     const dstPath = join(releaseDir, basename(a.path));
-    await copyFile(srcPath, dstPath);
+    await io.copyFile(srcPath, dstPath);
   }
 
   const manifestPath = join(releaseDir, releaseConfig.manifestName);

package/os/core/handlers/release-publish.ts

@@ -14,8 +14,8 @@
 </CHANGE_SUMMARY>
 */
 
-import { readFile, copyFile, mkdir } from "node:fs/promises";
 import { join, basename } from "node:path";
+import { resolveIo } from "../../../src/utils/io.ts";
 import type {
   ForgeCommandInput,
   ForgeCommandResult,
@@ -46,6 +46,7 @@ export async function runReleasePublish(
   input: ForgeCommandInput,
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<ForgeReleasePublishResult>> {
+  const io = resolveIo(context.io);
   const { workspaceRoot, logger } = context;
   const { dryRun, profileIdOverride } = resolveLifecycleFlags(input, context);
 
@@ -87,7 +88,7 @@ export async function runReleasePublish(
 
   let manifest: ReleaseManifest;
   try {
-    const raw = await readFile(manifestPath, "utf8");
+    const raw = await io.readFile(manifestPath);
     manifest = JSON.parse(raw) as ReleaseManifest;
   } catch {
     return {
@@ -155,15 +156,14 @@ export async function runReleasePublish(
 
   if (target === "local") {
     const publishedDir = join(releaseDir, "published");
-    await mkdir(publishedDir, { recursive: true });
+    await io.mkdir(publishedDir);
     for (const f of filesToPublish) {
       const dst = join(publishedDir, basename(f));
-      await copyFile(f, dst);
+      await io.copyFile(f, dst);
       publishedFiles.push({ path: f, targetPath: dst });
     }
   } else if (target === "r2" || target === "s3") {
     const { S3Client, PutObjectCommand } = await import("@aws-sdk/client-s3");
-    const { readFile: fsReadFile } = await import("node:fs/promises");
 
     const endpoint =
       target === "r2"
@@ -185,7 +185,7 @@ export async function runReleasePublish(
 
     for (const f of filesToPublish) {
       const key = prefix ? `${prefix}/${basename(f)}` : basename(f);
-      const body = await fsReadFile(f);
+      const body = await io.readFile(f);
       await client.send(
         new PutObjectCommand({
           Bucket: bucket,

package/os/core/handlers/validate.ts

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

package/os/exploration/exploration.module.ts

@@ -74,6 +74,7 @@ export async function createForgeExplorationModule(): Promise<ForgeModule> {
         scope: "workspace",
         mutatesState: true,
         writes: ["docs/explorations/*.md"],
+        generates: [],
         reads: ["docs/explorations/*.md"],
         cacheable: false,
         flags: {

package/os/exploration/frontmatter-io.ts

@@ -13,7 +13,7 @@ their YAML frontmatter 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";
 import { EXPLORATION_DIR } from "./types.ts";
@@ -38,9 +38,9 @@ export async function listExplorationFiles(explorationsDirPath: string): Promise
   const results: string[] = [];
 
   try {
-    const entries = await fs.readdir(explorationsDirPath, { withFileTypes: true });
+    const entries = await fs.readdir(explorationsDirPath);
     for (const entry of entries) {
-      if (entry.isFile() && entry.name.endsWith(".md") && entry.name !== "README.md") {
+      if (entry.isFile && entry.name.endsWith(".md") && entry.name !== "README.md") {
         results.push(entry.name);
       }
     }
@@ -57,7 +57,7 @@ export async function readAndParseExplorationNote(
 ): Promise<{ fileName: string; parsed: ParsedExplorationNote } | undefined> {
   try {
     const filePath = path.join(explorationsDirPath, fileName);
-    const content = await fs.readFile(filePath, "utf-8");
+    const content = await fs.readFile(filePath);
     return { fileName, parsed: parseExplorationFile(content) };
   } catch {
     return undefined;

package/os/exploration/handlers/archive.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 type {
   ForgeCommandInput,
@@ -110,7 +110,7 @@ export async function runExplorationArchive(
         related,
       };
       const updatedContent = serializeExplorationNote(updatedFrontmatter, result.parsed.body);
-      await fs.writeFile(filePath, updatedContent, "utf-8");
+      await fs.writeFile(filePath, updatedContent);
     }
     if (outputFormat === "pretty") {
       logger.info(`Exploration note ${slug} is already archived (no-op).`);
@@ -136,7 +136,7 @@ export async function runExplorationArchive(
   };
 
   const updatedContent = serializeExplorationNote(updatedFrontmatter, result.parsed.body);
-  await fs.writeFile(filePath, updatedContent, "utf-8");
+  await fs.writeFile(filePath, updatedContent);
 
   if (outputFormat === "pretty") {
     logger.success(`Archived exploration note: ${slug} (${previousStatus} → archived)`);

package/os/mission/handlers/archive.test.ts

@@ -318,8 +318,14 @@ describe("mission.archive", () => {
   });
 
   test("RFC-0801: service folders deleted before move", async () => {
-    await writeMissionManifest(missionsDir, "test-m014", "closed");
+    // Mission carries a releaseId — already released, so the deferred-release
+    // guard does not apply and all service folders are cleaned.
     const missionDir = path.join(missionsDir, "test-m014");
+    await fs.mkdir(missionDir, { recursive: true });
+    await fs.writeFile(
+      path.join(missionDir, "mission.yaml"),
+      `missionId: test-m014\nstate: closed\nreleaseId: test-r000014\n`,
+    );
     const workpieceDir = path.join(missionDir, "workpiece");
     await fs.mkdir(workpieceDir, { recursive: true });
 
@@ -341,6 +347,37 @@ describe("mission.archive", () => {
     }
   });
 
+  test("deferred-release guard: closed mission without releaseId → node_modules preserved", async () => {
+    await writeMissionManifest(missionsDir, "test-m014b", "closed");
+    const missionDir = path.join(missionsDir, "test-m014b");
+    const workpieceDir = path.join(missionDir, "workpiece");
+    await fs.mkdir(workpieceDir, { recursive: true });
+
+    for (const folder of ["node_modules", "dist", ".astro"]) {
+      const folderPath = path.join(workpieceDir, folder);
+      await fs.mkdir(folderPath, { recursive: true });
+      await fs.writeFile(path.join(folderPath, "dummy.txt"), `content of ${folder}\n`);
+    }
+
+    const data = unwrap(await runMissionArchive(makeInput(), makeContext(tmpDir)));
+
+    expect(data.moved).toHaveLength(1);
+    const archivedWorkpiece = path.join(
+      missionsDir,
+      "archive",
+      "closed",
+      "test-m014b",
+      "workpiece",
+    );
+    // node_modules preserved so release.prepare can still run on the archived
+    // workpiece — archived dirs fall outside the pnpm-workspace glob.
+    expect(existsSync(path.join(archivedWorkpiece, "node_modules"))).toBe(true);
+    expect(existsSync(path.join(archivedWorkpiece, "node_modules", "dummy.txt"))).toBe(true);
+    // Other service folders still cleaned.
+    expect(existsSync(path.join(archivedWorkpiece, "dist"))).toBe(false);
+    expect(existsSync(path.join(archivedWorkpiece, ".astro"))).toBe(false);
+  });
+
   test("RFC-0801: mission without workpiece — cleanup skipped gracefully", async () => {
     await writeMissionManifest(missionsDir, "test-m015", "closed");
     // No workpiece/ directory created — simulates aborted mission

package/os/mission/handlers/archive.ts

@@ -22,14 +22,15 @@ Mechanical v1 to v2 header migration across the workspace: 942 files rewritten
 
 Sweep batch 2: real KEY_DECISIONS on 10 files, expanded purposes (CONTRACT-02/PURPOSE-02), headers on mission/index + gen-upstreams, sanitizeItemText in summary.record (literal Compass tags corrupted history), excludedPaths for wrangler types, test-fixtures testPattern. forge+services now 0 diagnostics under --mode error.</item>
   <item>RFC-1138: pipeline hygiene — module-scoped exempt entries, archive gitignore guard, dns upsert to deploy phases, promote auto-sync, rfc.create claim protocol, siteHasRuntime filter</item>
+  <item>warpgogol-m000175 fo-fix: deferred-release guard — closed missions without releaseId keep workpiece node_modules on archive (archived dirs fall outside the pnpm-workspace glob, so deps cannot be reinstalled in place and release.prepare would fail on WORKPIECE-IMPORTS-01); released missions still get full service-folder cleanup.</item>
   <history>RFC-0573, RFC-0733, RFC-0801</history>
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { ambientIo as fs } from "../../../src/utils/io.ts";
+import { existsSync, lstatSync } from "../../../src/utils/sync-fs.ts";
 import path from "node:path";
-import { execSync } from "node:child_process";
+import { execSync } from "../../../src/utils/sync-fs.ts";
 import { parse as parseYaml } from "yaml";
 import type {
   ForgeCommandInput,
@@ -56,12 +57,16 @@ const SERVICE_FOLDERS = [
   ".turbo",
 ] as const;
 
-async function cleanServiceFolders(workpieceDir: string): Promise<string[]> {
+async function cleanServiceFolders(
+  workpieceDir: string,
+  keep: readonly string[] = [],
+): Promise<string[]> {
   const removed: string[] = [];
   for (const folder of SERVICE_FOLDERS) {
+    if (keep.includes(folder)) continue;
     const target = path.join(workpieceDir, folder);
     if (existsSync(target)) {
-      await fs.rm(target, { recursive: true, force: true });
+      await fs.rm(target);
       removed.push(folder);
     }
   }
@@ -76,7 +81,7 @@ function isCacheEntry(name: string): boolean {
 async function readMissionReleaseId(missionDir: string): Promise<string | null> {
   const manifestPath = path.join(missionDir, "mission.yaml");
   try {
-    const raw = await fs.readFile(manifestPath, "utf8");
+    const raw = await fs.readFile(manifestPath);
     const parsed = parseYaml(raw) as Record<string, unknown>;
     const releaseId = parsed?.releaseId;
     if (typeof releaseId === "string" && releaseId.trim()) return releaseId.trim();
@@ -89,7 +94,7 @@ async function readMissionReleaseId(missionDir: string): Promise<string | null>
 async function readMissionState(missionDir: string): Promise<string | null> {
   const manifestPath = path.join(missionDir, "mission.yaml");
   try {
-    const raw = await fs.readFile(manifestPath, "utf8");
+    const raw = await fs.readFile(manifestPath);
     const parsed = parseYaml(raw) as Record<string, unknown>;
     const state = parsed?.state;
     if (typeof state === "string") return state.trim();
@@ -106,7 +111,7 @@ async function readMissionState(missionDir: string): Promise<string | null> {
   const workpieceDir = path.join(missionDir, "workpiece");
   if (existsSync(workpieceDir)) {
     const entries = await fs.readdir(workpieceDir);
-    const nonCacheEntries = entries.filter((e) => !isCacheEntry(e));
+    const nonCacheEntries = entries.filter((e) => !isCacheEntry(e.name));
     if (nonCacheEntries.length === 0) {
       return "closed";
     }
@@ -125,17 +130,17 @@ async function isOrphanedRemnant(missionDir: string): Promise<boolean> {
   if (!existsSync(workpieceDir)) return true;
 
   const entries = await fs.readdir(workpieceDir);
-  const nonCacheEntries = entries.filter((e) => !isCacheEntry(e));
+  const nonCacheEntries = entries.filter((e) => !isCacheEntry(e.name));
   return nonCacheEntries.length === 0;
 }
 
 // RFC-0982: Check if a mission directory has non-cache content (source files,
 // configs, etc.) that warrants manual inspection rather than auto-cleanup.
 async function hasNonCacheContent(missionDir: string): Promise<boolean> {
-  const entries = await fs.readdir(missionDir, { withFileTypes: true });
+  const entries = await fs.readdir(missionDir);
   for (const entry of entries) {
     if (entry.name === "workpiece") continue;
-    if (entry.isDirectory() && isCacheEntry(entry.name)) {
+    if (entry.isDirectory && isCacheEntry(entry.name)) {
       continue;
     }
     // Any file or non-cache directory at mission root is content
@@ -146,7 +151,7 @@ async function hasNonCacheContent(missionDir: string): Promise<boolean> {
   const workpieceDir = path.join(missionDir, "workpiece");
   if (existsSync(workpieceDir)) {
     const wpEntries = await fs.readdir(workpieceDir);
-    const nonCacheEntries = wpEntries.filter((e) => !isCacheEntry(e));
+    const nonCacheEntries = wpEntries.filter((e) => !isCacheEntry(e.name));
     if (nonCacheEntries.length > 0) return true;
   }
 
@@ -176,7 +181,7 @@ async function moveMissionDir(
 
   if (!dryRun) {
     if (targetParentDir) {
-      await fs.mkdir(targetParentDir, { recursive: true });
+      await fs.mkdir(targetParentDir);
     }
 
     // RFC-0801: Clean service folders from workpiece before move.
@@ -185,11 +190,27 @@ async function moveMissionDir(
     // Aborted missions may not have a workpiece/ directory — skip gracefully.
     const workpieceDir = path.join(sourcePath, "workpiece");
     if (existsSync(workpieceDir)) {
+      // Deferred-release guard: a closed mission without a releaseId still
+      // needs release.prepare (ADR-0085 closed-workpiece rebuild path), and
+      // archived dirs fall outside the pnpm-workspace `missions/*/workpiece`
+      // glob — node_modules cannot be reinstalled in place. Keep it so the
+      // archived workpiece stays release-ready.
+      const keepFolders =
+        direction === "into-archive" &&
+        state === "closed" &&
+        !(await readMissionReleaseId(sourcePath))
+          ? ["node_modules"]
+          : [];
       try {
-        const removed = await cleanServiceFolders(workpieceDir);
+        const removed = await cleanServiceFolders(workpieceDir, keepFolders);
         if (removed.length > 0 && logger) {
           logger.info(`    cleaned service folders: ${removed.join(", ")}`);
         }
+        if (keepFolders.length > 0 && logger) {
+          logger.info(
+            "    kept node_modules — mission has no releaseId; release.prepare can still run on the archived workpiece",
+          );
+        }
       } catch (cleanupErr) {
         // Non-fatal: log warning and continue with move
         if (logger) {
@@ -271,14 +292,17 @@ export async function runMissionArchive(
   }
 
   // Phase 1: Scan missions/ for terminal-state missions to move into archive
-  const rootEntries = await fs.readdir(missionsPath, { withFileTypes: true });
+  const rootEntries = await fs.readdir(missionsPath);
 
   // Stale symlink cleanup: IDEs or file watchers may recreate symlinks to
   // archived mission directories after mission.archive has moved them.
   // These symlinks break pnpm workspace resolution and mission number derivation.
   // Trash them before they can cause downstream issues.
   for (const e of rootEntries) {
-    if (e.isSymbolicLink() && e.name !== ARCHIVE_DIR_NAME) {
+    if (
+      lstatSync(path.join(missionsPath, e.name)).isSymbolicLink() &&
+      e.name !== ARCHIVE_DIR_NAME
+    ) {
       const symlinkPath = path.join(missionsPath, e.name);
       const sourceRel = `${MISSIONS_DIR}/${e.name}`;
       if (!dryRun) {
@@ -296,7 +320,12 @@ export async function runMissionArchive(
   }
 
   const rootDirs = rootEntries
-    .filter((e) => e.isDirectory() && !e.isSymbolicLink() && e.name !== ARCHIVE_DIR_NAME)
+    .filter(
+      (e) =>
+        e.isDirectory &&
+        !lstatSync(path.join(missionsPath, e.name)).isSymbolicLink() &&
+        e.name !== ARCHIVE_DIR_NAME,
+    )
     .map((e) => e.name);
 
   for (const missionId of rootDirs) {
@@ -356,12 +385,14 @@ export async function runMissionArchive(
 
     // Warn when archiving a closed mission without a release — operator likely
     // forgot to run release.prepare before archiving. Non-blocking: some missions
-    // (e.g. aborted, content-only) legitimately have no release.
+    // (e.g. aborted, content-only) legitimately have no release. The workpiece
+    // node_modules are preserved in this case so the archived mission stays
+    // release-ready (see deferred-release guard in moveMissionDir).
     if (state === "closed" && !dryRun) {
       const releaseId = await readMissionReleaseId(missionDir);
       if (!releaseId && outputFormat === "pretty") {
         logger.warn(
-          `  ⚠ ${missionId}: closed mission has no releaseId — run release.prepare before archiving if this mission needs deployment`,
+          `  ⚠ ${missionId}: closed mission has no releaseId — keeping workpiece node_modules so release.prepare can still run on the archived workpiece`,
         );
       }
     }
@@ -410,13 +441,13 @@ export async function runMissionArchive(
   // Phase 2: Scan missions/archive/<state>/ for non-terminal missions to move back
   const archivePath = path.join(missionsPath, ARCHIVE_DIR_NAME);
   if (existsSync(archivePath)) {
-    const stateDirs = await fs.readdir(archivePath, { withFileTypes: true });
-    const stateDirNames = stateDirs.filter((e) => e.isDirectory()).map((e) => e.name);
+    const stateDirs = await fs.readdir(archivePath);
+    const stateDirNames = stateDirs.filter((e) => e.isDirectory).map((e) => e.name);
 
     for (const stateDirName of stateDirNames) {
       const stateDirPath = path.join(archivePath, stateDirName);
-      const archivedMissions = await fs.readdir(stateDirPath, { withFileTypes: true });
-      const archivedDirNames = archivedMissions.filter((e) => e.isDirectory()).map((e) => e.name);
+      const archivedMissions = await fs.readdir(stateDirPath);
+      const archivedDirNames = archivedMissions.filter((e) => e.isDirectory).map((e) => e.name);
 
       for (const missionId of archivedDirNames) {
         const archivedMissionDir = path.join(stateDirPath, missionId);

package/os/mission/mission.module.ts

@@ -14,47 +14,46 @@
 import type { ForgeModule } from "../../src/forge-module.ts";
 
 export async function createForgeMissionModule(): Promise<ForgeModule> {
-const { runMissionArchive } = await import("./handlers/archive.ts");
+  const { runMissionArchive } = await import("./handlers/archive.ts");
   return {
-  name: "forge-mission",
-  version: "0.1.0",
-  runtime: "autonomous",
+    name: "forge-mission",
+    version: "0.1.0",
+    runtime: "autonomous",
     declarations: [],
-  commands: [
-    {
-      name: "mission.archive",
-      description:
-        "Move terminal-state mission directories (state: closed or aborted in " +
-        "mission.yaml) into missions/archive/<state>/<missionId>/ subdirectories. " +
-        "Bidirectional: moves open missions found in archive subdirectories back " +
-        "to missions/. Use --dry-run to preview. Use --status to filter to a " +
-        "single terminal status (closed, aborted). " +
-        "Prefer the docs.archive umbrella command unless you need to archive only missions.",
-      scope: "workspace",
-      mutatesState: true,
-      writes: ["missions/*", "missions/archive/**"],
-      reads: ["missions/**"],
-      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 (closed, aborted).",
-        },
-        "clean-orphans": {
-          kind: "boolean",
-          description:
-            "Trash orphaned directories (no mission.yaml, only cache files) instead of archiving them.",
+    commands: [
+      {
+        name: "mission.archive",
+        description:
+          "Move terminal-state mission directories (state: closed or aborted in " +
+          "mission.yaml) into missions/archive/<state>/<missionId>/ subdirectories. " +
+          "Bidirectional: moves open missions found in archive subdirectories back " +
+          "to missions/. Use --dry-run to preview. Use --status to filter to a " +
+          "single terminal status (closed, aborted). " +
+          "Prefer the docs.archive umbrella command unless you need to archive only missions.",
+        scope: "workspace",
+        mutatesState: true,
+        writes: ["missions/*", "missions/archive/**"],
+        generates: [],
+        reads: ["missions/**"],
+        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 (closed, aborted).",
+          },
+          "clean-orphans": {
+            kind: "boolean",
+            description:
+              "Trash orphaned directories (no mission.yaml, only cache files) instead of archiving them.",
+          },
         },
+        execute: runMissionArchive,
       },
-      execute: runMissionArchive,
-    }
-  ],
-  pipelines: [
-
-  ]};
+    ],
+    pipelines: [],
+  };
 }
-;

package/os/naming/naming-convention.ts

@@ -13,9 +13,14 @@ uses kebab-case (lowercase letters, digits, hyphens only), with documented exemp
 */
 
 import { basename, join, relative } from "node:path";
-import { readFile } from "node:fs/promises";
-import { readdirSync, type Dirent } from "node:fs";
+import { ambientIo, resolveIo } from "../../src/utils/io.ts";
+
+import { readdirSync, type Dirent } from "../../src/utils/sync-fs.ts";
 import { collectFiles } from "../../src/utils/fs.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,
@@ -168,7 +173,7 @@ function hasNamingViolation(fileName: string): boolean {
 async function readSimpleIgnorePatterns(filePath: string): Promise<Set<string>> {
   const patterns = new Set<string>();
   try {
-    const content = await readFile(filePath, "utf8");
+    const content = await io.readFile(filePath);
     for (const rawLine of content.split("\n")) {
       const line = rawLine.trim();
       if (!line || line.startsWith("#")) continue;
@@ -270,6 +275,7 @@ export async function runNamingConventionLint(
     unknownTopLevelDirs?: string[];
   }>
 > {
+  const _io = resolveIo(context.io);
   const workspaceRoot = context.workspaceRoot;
   const includeIgnored = input.flags["include-ignored"] === true;