@warpgogol/forge 2.14.0 → 2.17.0

package/dist/os/exploration/handlers/list.js

@@ -0,0 +1,64 @@
+/*
+<MODULE_CONTRACT>
+<purpose>exploration.list handler — list all exploration notes with metadata.</purpose>
+<non-goals>
+  <item>Do not validate frontmatter shape — listing is metadata-only.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0710: initial exploration.list handler.</item>
+</CHANGE_SUMMARY>
+*/
+import path from "node:path";
+import { listExplorationFiles, readAndParseExplorationNote, getExplorationsDir, } from "../frontmatter-io.js";
+export async function runExplorationList(input, context) {
+    const { workspaceRoot, logger, outputFormat } = context;
+    const explorationsDirPath = getExplorationsDir(workspaceRoot);
+    const filterStatus = input.flags["status"];
+    const files = await listExplorationFiles(explorationsDirPath);
+    const entries = [];
+    for (const fileName of files) {
+        const result = await readAndParseExplorationNote(explorationsDirPath, fileName);
+        if (!result)
+            continue;
+        const fm = result.parsed.frontmatter;
+        const status = String(fm["status"] ?? "");
+        if (filterStatus && status !== filterStatus)
+            continue;
+        entries.push({
+            id: String(fm["id"] ?? path.basename(fileName, ".md")),
+            title: String(fm["title"] ?? ""),
+            status,
+            createdAt: String(fm["createdAt"] ?? ""),
+        });
+    }
+    if (outputFormat === "pretty") {
+        if (entries.length === 0) {
+            logger.info("No exploration notes found.");
+        }
+        else {
+            logger.section(`Exploration notes (${entries.length})`);
+            for (const entry of entries) {
+                logger.info(`${entry.id}  ${entry.status.padEnd(10)} ${entry.createdAt.padEnd(12)} ${entry.title}`);
+            }
+        }
+    }
+    return {
+        data: {
+            command: "exploration.list",
+            status: "ok",
+            count: entries.length,
+            explorations: entries,
+        },
+        summary: `${entries.length} exploration note(s) found`,
+        nextSteps: entries.length === 0
+            ? [
+                {
+                    action: `Create an exploration note: pnpm exec forge run exploration.show --id <slug>`,
+                    kind: "optional",
+                },
+            ]
+            : undefined,
+    };
+}
+//# sourceMappingURL=list.js.map

package/dist/os/exploration/handlers/list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../../../../os/exploration/handlers/list.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;EAUE;AAEF,OAAO,IAAI,MAAM,WAAW,CAAC;AAM7B,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAG9B,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAwB,EACxB,OAA4B;IAE5B,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC;IACxD,MAAM,mBAAmB,GAAG,kBAAkB,CAAC,aAAa,CAAC,CAAC;IAE9D,MAAM,YAAY,GAAG,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAuB,CAAC;IAEjE,MAAM,KAAK,GAAG,MAAM,oBAAoB,CAAC,mBAAmB,CAAC,CAAC;IAC9D,MAAM,OAAO,GAA2B,EAAE,CAAC;IAE3C,KAAK,MAAM,QAAQ,IAAI,KAAK,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,MAAM,2BAA2B,CAAC,mBAAmB,EAAE,QAAQ,CAAC,CAAC;QAChF,IAAI,CAAC,MAAM;YAAE,SAAS;QAEtB,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC;QACrC,MAAM,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAsB,CAAC;QAE/D,IAAI,YAAY,IAAI,MAAM,KAAK,YAAY;YAAE,SAAS;QAEtD,OAAO,CAAC,IAAI,CAAC;YACX,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;YACtD,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YAChC,MAAM;YACN,SAAS,EAAE,MAAM,CAAC,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;SACzC,CAAC,CAAC;IACL,CAAC;IAED,IAAI,YAAY,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,MAAM,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;QAC7C,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,OAAO,CAAC,sBAAsB,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;YACxD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC5B,MAAM,CAAC,IAAI,CACT,GAAG,KAAK,CAAC,EAAE,KAAK,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,KAAK,CAAC,KAAK,EAAE,CACvF,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,IAAI,EAAE;YACJ,OAAO,EAAE,kBAAkB;YAC3B,MAAM,EAAE,IAAI;YACZ,KAAK,EAAE,OAAO,CAAC,MAAM;YACrB,YAAY,EAAE,OAAO;SACtB;QACD,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,4BAA4B;QACtD,SAAS,EACP,OAAO,CAAC,MAAM,KAAK,CAAC;YAClB,CAAC,CAAC;gBACE;oBACE,MAAM,EAAE,8EAA8E;oBACtF,IAAI,EAAE,UAAU;iBACjB;aACF;YACH,CAAC,CAAC,SAAS;KAChB,CAAC;AACJ,CAAC"}

package/dist/os/exploration/handlers/show.d.ts

@@ -0,0 +1,4 @@
+import type { ForgeCommandInput, ForgeCommandResult, ForgeRuntimeContext } from "../../../src/types.ts";
+import type { ExplorationShowResult } from "../types.ts";
+export declare function runExplorationShow(input: ForgeCommandInput, context: ForgeRuntimeContext): Promise<ForgeCommandResult<ExplorationShowResult>>;
+//# sourceMappingURL=show.d.ts.map

package/dist/os/exploration/handlers/show.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"show.d.ts","sourceRoot":"","sources":["../../../../os/exploration/handlers/show.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAmB,qBAAqB,EAAqB,MAAM,aAAa,CAAC;AAS7F,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,qBAAqB,CAAC,CAAC,CAkFpD"}

package/dist/os/exploration/handlers/show.js

@@ -0,0 +1,97 @@
+/*
+<MODULE_CONTRACT>
+<purpose>exploration.show handler — return the full content of a single exploration note.</purpose>
+<non-goals>
+  <item>Do not validate frontmatter shape — show returns raw parsed content.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0710: initial exploration.show handler.</item>
+</CHANGE_SUMMARY>
+*/
+import { readAndParseExplorationNote, getExplorationsDir } from "../frontmatter-io.js";
+function parseRelatedArray(value) {
+    if (Array.isArray(value)) {
+        return value.filter((v) => typeof v === "string");
+    }
+    return [];
+}
+export async function runExplorationShow(input, context) {
+    const { workspaceRoot, logger, outputFormat } = context;
+    const explorationsDirPath = getExplorationsDir(workspaceRoot);
+    const slug = input.flags["id"];
+    if (!slug) {
+        return {
+            data: {
+                command: "exploration.show",
+                status: "error",
+                note: {
+                    id: "",
+                    title: "",
+                    createdAt: "",
+                    status: "open",
+                    related: [],
+                    body: "",
+                },
+            },
+            exitCode: 1,
+            summary: "exploration.show requires --id <slug>",
+        };
+    }
+    const fileName = `${slug}.md`;
+    const result = await readAndParseExplorationNote(explorationsDirPath, fileName);
+    if (!result) {
+        if (outputFormat === "pretty") {
+            logger.info(`Exploration note not found: ${slug}`);
+        }
+        return {
+            data: {
+                command: "exploration.show",
+                status: "error",
+                note: {
+                    id: slug,
+                    title: "",
+                    createdAt: "",
+                    status: "open",
+                    related: [],
+                    body: "",
+                },
+            },
+            exitCode: 1,
+            summary: `Exploration note not found: ${slug}`,
+        };
+    }
+    const fm = result.parsed.frontmatter;
+    const note = {
+        id: String(fm["id"] ?? slug),
+        title: String(fm["title"] ?? ""),
+        createdAt: String(fm["createdAt"] ?? ""),
+        status: String(fm["status"] ?? "open"),
+        related: parseRelatedArray(fm["related"]),
+        body: result.parsed.body,
+    };
+    if (outputFormat === "pretty") {
+        logger.section(`Exploration: ${note.title}`);
+        logger.info(`ID: ${note.id}  Status: ${note.status}  Created: ${note.createdAt}`);
+        if (note.related.length > 0) {
+            logger.info(`Related: ${note.related.join(", ")}`);
+        }
+        logger.info("");
+        logger.info(note.body.trim());
+    }
+    return {
+        data: {
+            command: "exploration.show",
+            status: "ok",
+            note,
+        },
+        summary: `Exploration note: ${note.id}`,
+        nextSteps: [
+            {
+                action: `Archive the note when done: pnpm exec forge run exploration.archive --id ${note.id}`,
+                kind: "optional",
+            },
+        ],
+    };
+}
+//# sourceMappingURL=show.js.map

package/dist/os/exploration/handlers/show.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"show.js","sourceRoot":"","sources":["../../../../os/exploration/handlers/show.ts"],"names":[],"mappings":"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"}

package/dist/os/exploration/index.d.ts

@@ -0,0 +1,7 @@
+export { forgeExplorationModule } from "./exploration.module.ts";
+export { runExplorationList } from "./handlers/list.ts";
+export { runExplorationShow } from "./handlers/show.ts";
+export { runExplorationArchive } from "./handlers/archive.ts";
+export type { ExplorationStatus, ExplorationNote, ExplorationListEntry, ExplorationListResult, ExplorationShowResult, ExplorationArchiveResult, } from "./types.ts";
+export { EXPLORATION_STATUSES, EXPLORATION_DIR, EXPLORATION_SLUG_PATTERN } from "./types.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/os/exploration/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../os/exploration/index.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC"}

package/dist/os/exploration/index.js

@@ -0,0 +1,17 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Barrel export for the exploration domain — types, constants, module, and handlers.</purpose>
+<non-goals>
+  <item>Do not implement exploration logic here; delegate to handlers/ and exploration.module.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0710: expose forgeExplorationModule and exploration types from the exploration domain.</item>
+</CHANGE_SUMMARY>
+*/
+export { forgeExplorationModule } from "./exploration.module.js";
+export { runExplorationList } from "./handlers/list.js";
+export { runExplorationShow } from "./handlers/show.js";
+export { runExplorationArchive } from "./handlers/archive.js";
+export { EXPLORATION_STATUSES, EXPLORATION_DIR, EXPLORATION_SLUG_PATTERN } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/os/exploration/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../os/exploration/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;EAUE;AAEF,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAS9D,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC"}

package/dist/os/exploration/types.d.ts

@@ -0,0 +1,38 @@
+export type ExplorationStatus = "open" | "explored" | "archived";
+export declare const EXPLORATION_STATUSES: readonly ExplorationStatus[];
+export interface ExplorationNote {
+    id: string;
+    title: string;
+    createdAt: string;
+    status: ExplorationStatus;
+    related: string[];
+    body: string;
+}
+export interface ExplorationListEntry {
+    id: string;
+    title: string;
+    status: ExplorationStatus;
+    createdAt: string;
+}
+export interface ExplorationListResult {
+    command: "exploration.list";
+    status: "ok";
+    count: number;
+    explorations: ExplorationListEntry[];
+}
+export interface ExplorationShowResult {
+    command: "exploration.show";
+    status: "ok" | "error";
+    note: ExplorationNote;
+}
+export interface ExplorationArchiveResult {
+    command: "exploration.archive";
+    status: "ok" | "error";
+    id: string;
+    previousStatus: string;
+    newStatus: "archived";
+    related: string[];
+}
+export declare const EXPLORATION_DIR = "docs/explorations";
+export declare const EXPLORATION_SLUG_PATTERN: RegExp;
+//# sourceMappingURL=types.d.ts.map

package/dist/os/exploration/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../os/exploration/types.ts"],"names":[],"mappings":"AAgBA,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;AAEjE,eAAO,MAAM,oBAAoB,EAAE,SAAS,iBAAiB,EAInD,CAAC;AAEX,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,iBAAiB,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,MAAM,EAAE,IAAI,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,oBAAoB,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;IACvB,IAAI,EAAE,eAAe,CAAC;CACvB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,qBAAqB,CAAC;IAC/B,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,UAAU,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,eAAO,MAAM,eAAe,sBAAsB,CAAC;AAEnD,eAAO,MAAM,wBAAwB,QAA+B,CAAC"}

package/dist/os/exploration/types.js

@@ -0,0 +1,23 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Defines types and constants for managing exploration notes: statuses,
+frontmatter shape, list/show/archive result types.
+</purpose>
+<non-goals>
+  <item>Do not implement exploration processing logic here.</item>
+  <item>Do not handle user input or command execution.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0710: initial exploration types and constants.</item>
+</CHANGE_SUMMARY>
+*/
+export const EXPLORATION_STATUSES = [
+    "open",
+    "explored",
+    "archived",
+];
+export const EXPLORATION_DIR = "docs/explorations";
+export const EXPLORATION_SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+//# sourceMappingURL=types.js.map

package/dist/os/exploration/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../os/exploration/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;EAcE;AAIF,MAAM,CAAC,MAAM,oBAAoB,GAAiC;IAChE,MAAM;IACN,UAAU;IACV,UAAU;CACF,CAAC;AAwCX,MAAM,CAAC,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAEnD,MAAM,CAAC,MAAM,wBAAwB,GAAG,4BAA4B,CAAC"}

package/dist/os/mission/handlers/archive.d.ts

@@ -0,0 +1,4 @@
+import type { ForgeCommandInput, ForgeCommandResult, ForgeRuntimeContext } from "../../../src/types.ts";
+import { type MissionArchiveResult } from "../types.ts";
+export declare function runMissionArchive(input: ForgeCommandInput, context: ForgeRuntimeContext): Promise<ForgeCommandResult<MissionArchiveResult>>;
+//# sourceMappingURL=archive.d.ts.map

package/dist/os/mission/handlers/archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../../../os/mission/handlers/archive.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAML,KAAK,oBAAoB,EAC1B,MAAM,aAAa,CAAC;AA8GrB,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,oBAAoB,CAAC,CAAC,CA0SnD"}

package/dist/os/mission/handlers/archive.js

@@ -0,0 +1,356 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Mission archive handler — moves terminal-state mission directories (state: closed
+or state: aborted in mission.yaml) into status-specific subdirectories under
+missions/archive/<state>/ and moves non-terminal (open) directories found in
+archive subdirectories back to missions/.
+</purpose>
+<non-goals>
+  <item>Does not validate mission manifest schema — reads only the state field.</item>
+  <item>Does not change mission.yaml — only moves directories on disk.</item>
+  <item>Does not import from @warpgogol/* packages — uses node:fs, node:child_process, and yaml only.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0573: implement mission.archive command.</item>
+  <item>RFC-0573: extract moveMissionDir helper to eliminate Phase 1/2 duplication.</item>
+  <item>RFC-0801: add service-folder cleanup (node_modules, dist, .astro, .wrangler, .cache, .turbo) before archive move.</item>
+  <item>RFC-0733: add pinned-files pre-check — skip pinned mission directories with warning instead of moving them.</item>
+  <item>RFC-0804: auto-refresh pnpm-lock.yaml after directory moves.</item>
+</CHANGE_SUMMARY>
+*/
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { execSync } from "node:child_process";
+import { parse as parseYaml } from "yaml";
+import { trashPath } from "../../../src/utils/fs-trash.js";
+import { MISSIONS_DIR, ARCHIVE_DIR_NAME, MISSION_TERMINAL_STATUSES, } from "../types.js";
+import { loadPinnedManifest, isPinned, isIntraDirMove } from "../../core/handlers/pinned-check.js";
+const SERVICE_FOLDERS = [
+    "node_modules",
+    "dist",
+    ".astro",
+    ".wrangler",
+    ".cache",
+    ".turbo",
+];
+async function cleanServiceFolders(workpieceDir) {
+    const removed = [];
+    for (const folder of SERVICE_FOLDERS) {
+        const target = path.join(workpieceDir, folder);
+        if (existsSync(target)) {
+            await fs.rm(target, { recursive: true, force: true });
+            removed.push(folder);
+        }
+    }
+    return removed;
+}
+async function readMissionState(missionDir) {
+    const manifestPath = path.join(missionDir, "mission.yaml");
+    try {
+        const raw = await fs.readFile(manifestPath, "utf8");
+        const parsed = parseYaml(raw);
+        const state = parsed?.state;
+        if (typeof state === "string")
+            return state.trim();
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+async function moveMissionDir(sourcePath, targetPath, targetParentDir, missionId, state, sourceRel, targetRel, direction, dryRun, logger) {
+    if (existsSync(targetPath)) {
+        return { moved: null, skip: { missionId, dir: sourceRel, reason: "destination exists" } };
+    }
+    if (!dryRun) {
+        if (targetParentDir) {
+            await fs.mkdir(targetParentDir, { recursive: true });
+        }
+        // RFC-0801: Clean service folders from workpiece before move.
+        // node_modules/, dist/, .astro/, .wrangler/, .cache/, .turbo/ contain
+        // broken symlinks and stale build artifacts that waste disk space in archive.
+        // Aborted missions may not have a workpiece/ directory — skip gracefully.
+        const workpieceDir = path.join(sourcePath, "workpiece");
+        if (existsSync(workpieceDir)) {
+            try {
+                const removed = await cleanServiceFolders(workpieceDir);
+                if (removed.length > 0 && logger) {
+                    logger.info(`    cleaned service folders: ${removed.join(", ")}`);
+                }
+            }
+            catch (cleanupErr) {
+                // Non-fatal: log warning and continue with move
+                if (logger) {
+                    logger.warn(`  Warning: service folder cleanup failed for ${missionId}: ${cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)}`);
+                }
+            }
+        }
+        try {
+            await fs.rename(sourcePath, targetPath);
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                return {
+                    moved: null,
+                    skip: { missionId, dir: sourceRel, reason: "already moved by another process" },
+                };
+            }
+            throw err;
+        }
+        // Post-rename cleanup: a watcher or IDE may recreate stale cache
+        // directories (e.g. .astro/) at the source path after the rename.
+        // Remove the resurrected source so it doesn't leave orphan directories.
+        if (existsSync(sourcePath)) {
+            await trashPath(sourcePath);
+        }
+    }
+    return {
+        moved: { missionId, state, from: sourceRel, to: targetRel, direction },
+        skip: null,
+    };
+}
+export async function runMissionArchive(input, context) {
+    const { workspaceRoot, logger, outputFormat } = context;
+    const missionsPath = path.join(workspaceRoot, MISSIONS_DIR);
+    const dryRun = context.dryRun || input.flags["dry-run"] === true;
+    const statusFilter = input.flags["status"];
+    if (statusFilter && !MISSION_TERMINAL_STATUSES.includes(statusFilter)) {
+        throw new Error(`Invalid --status "${statusFilter}". Must be one of: ${MISSION_TERMINAL_STATUSES.join(", ")}`);
+    }
+    const moved = [];
+    const skipped = [];
+    // RFC-0733: Load pinned manifest once per invocation
+    let pinnedManifest = null;
+    try {
+        pinnedManifest = await loadPinnedManifest(workspaceRoot);
+    }
+    catch {
+        // Malformed manifest — skip pre-check
+    }
+    if (!existsSync(missionsPath)) {
+        if (outputFormat === "pretty") {
+            if (dryRun) {
+                logger.info("[dry-run] mission.archive: no missions/ directory — nothing to do");
+            }
+            else {
+                logger.info("mission.archive: no missions/ directory — nothing to do");
+            }
+        }
+        return {
+            data: { command: "mission.archive", status: "ok", moved, skipped, dryRun },
+            summary: dryRun
+                ? "[dry-run] No missions/ directory — nothing to do"
+                : "No missions/ directory — nothing to do",
+        };
+    }
+    // Phase 1: Scan missions/ for terminal-state missions to move into archive
+    const rootEntries = await fs.readdir(missionsPath, { withFileTypes: true });
+    // 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) {
+            const symlinkPath = path.join(missionsPath, e.name);
+            const sourceRel = `${MISSIONS_DIR}/${e.name}`;
+            if (!dryRun) {
+                await trashPath(symlinkPath);
+            }
+            skipped.push({
+                missionId: e.name,
+                dir: sourceRel,
+                reason: "stale symlink — trashed",
+            });
+            if (outputFormat === "pretty") {
+                logger.warn(`  stale symlink: trashed ${sourceRel}`);
+            }
+        }
+    }
+    const rootDirs = rootEntries
+        .filter((e) => e.isDirectory() && !e.isSymbolicLink() && e.name !== ARCHIVE_DIR_NAME)
+        .map((e) => e.name);
+    for (const missionId of rootDirs) {
+        const missionDir = path.join(missionsPath, missionId);
+        const state = await readMissionState(missionDir);
+        if (state === null) {
+            skipped.push({
+                missionId,
+                dir: `${MISSIONS_DIR}/${missionId}`,
+                reason: "unreadable manifest",
+            });
+            continue;
+        }
+        const isTerminal = MISSION_TERMINAL_STATUSES.includes(state);
+        if (!isTerminal) {
+            skipped.push({
+                missionId,
+                dir: `${MISSIONS_DIR}/${missionId}`,
+                reason: `state ${state} is non-terminal`,
+            });
+            continue;
+        }
+        if (statusFilter && state !== statusFilter) {
+            skipped.push({
+                missionId,
+                dir: `${MISSIONS_DIR}/${missionId}`,
+                reason: `state ${state} does not match --status ${statusFilter}`,
+            });
+            continue;
+        }
+        const targetDir = path.join(missionsPath, ARCHIVE_DIR_NAME, state);
+        const targetPath = path.join(targetDir, missionId);
+        const targetRel = `${MISSIONS_DIR}/${ARCHIVE_DIR_NAME}/${state}/${missionId}`;
+        const sourceRel = `${MISSIONS_DIR}/${missionId}`;
+        // RFC-0733: Check if mission directory is pinned before moving
+        // Gap fix: exempt intra-directory moves (dir stays within the same pinned parent)
+        if (pinnedManifest &&
+            isPinned(pinnedManifest, sourceRel) &&
+            !isIntraDirMove(pinnedManifest, sourceRel, targetRel)) {
+            skipped.push({
+                missionId,
+                dir: sourceRel,
+                reason: "pinned (protected by .forge/pinned.yaml)",
+            });
+            if (outputFormat === "pretty") {
+                logger.warn(`  pinned: skipping ${sourceRel} (protected)`);
+            }
+            continue;
+        }
+        const result = await moveMissionDir(missionDir, targetPath, targetDir, missionId, state, sourceRel, targetRel, "into-archive", dryRun, logger);
+        if (result.skip) {
+            skipped.push(result.skip);
+            continue;
+        }
+        if (result.moved)
+            moved.push(result.moved);
+    }
+    // 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);
+        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);
+            for (const missionId of archivedDirNames) {
+                const archivedMissionDir = path.join(stateDirPath, missionId);
+                const state = await readMissionState(archivedMissionDir);
+                if (state === null) {
+                    skipped.push({
+                        missionId,
+                        dir: `${MISSIONS_DIR}/${ARCHIVE_DIR_NAME}/${stateDirName}/${missionId}`,
+                        reason: "unreadable manifest",
+                    });
+                    continue;
+                }
+                const isTerminal = MISSION_TERMINAL_STATUSES.includes(state);
+                if (isTerminal) {
+                    skipped.push({
+                        missionId,
+                        dir: `${MISSIONS_DIR}/${ARCHIVE_DIR_NAME}/${stateDirName}/${missionId}`,
+                        reason: `already archived (${state})`,
+                    });
+                    continue;
+                }
+                // Non-terminal in archive — move back to missions/
+                const targetPath = path.join(missionsPath, missionId);
+                const targetRel = `${MISSIONS_DIR}/${missionId}`;
+                const sourceRel = `${MISSIONS_DIR}/${ARCHIVE_DIR_NAME}/${stateDirName}/${missionId}`;
+                // RFC-0733: Check if mission directory is pinned before moving
+                // Gap fix: exempt intra-directory moves (dir stays within the same pinned parent)
+                if (pinnedManifest &&
+                    isPinned(pinnedManifest, sourceRel) &&
+                    !isIntraDirMove(pinnedManifest, sourceRel, targetRel)) {
+                    skipped.push({
+                        missionId,
+                        dir: sourceRel,
+                        reason: "pinned (protected by .forge/pinned.yaml)",
+                    });
+                    if (outputFormat === "pretty") {
+                        logger.warn(`  pinned: skipping ${sourceRel} (protected)`);
+                    }
+                    continue;
+                }
+                const result = await moveMissionDir(archivedMissionDir, targetPath, "", missionId, state, sourceRel, targetRel, "out-of-archive", dryRun, logger);
+                if (result.skip) {
+                    skipped.push(result.skip);
+                    continue;
+                }
+                if (result.moved)
+                    moved.push(result.moved);
+            }
+        }
+    }
+    if (outputFormat === "pretty") {
+        if (dryRun) {
+            logger.info(`[dry-run] mission.archive: would move ${moved.length} mission(s), skip ${skipped.length}`);
+        }
+        else {
+            logger.success(`mission.archive: moved ${moved.length} mission(s), skipped ${skipped.length}`);
+        }
+        for (const m of moved) {
+            logger.info(`  ${m.direction}: ${m.missionId} (${m.state}) ${m.from} → ${m.to}`);
+        }
+    }
+    // RFC-0804: Post-move lockfile refresh
+    if (!dryRun && moved.length > 0) {
+        try {
+            execSync("pnpm install", {
+                cwd: workspaceRoot,
+                stdio: ["pipe", "pipe", "pipe"],
+                timeout: 120_000,
+            });
+            const lockfileStatus = execSync("git status --porcelain pnpm-lock.yaml", {
+                cwd: workspaceRoot,
+                encoding: "utf-8",
+                stdio: ["pipe", "pipe", "pipe"],
+            }).trim();
+            if (lockfileStatus) {
+                execSync("git add pnpm-lock.yaml", {
+                    cwd: workspaceRoot,
+                    stdio: ["pipe", "pipe", "pipe"],
+                });
+                for (const m of moved) {
+                    execSync(`git add -A ${JSON.stringify(m.to)}`, {
+                        cwd: workspaceRoot,
+                        stdio: ["pipe", "pipe", "pipe"],
+                    });
+                    if (existsSync(m.from))
+                        continue;
+                    execSync(`git rm -r --cached --ignore-unmatch ${JSON.stringify(m.from)}`, {
+                        cwd: workspaceRoot,
+                        stdio: ["pipe", "pipe", "pipe"],
+                    });
+                }
+                execSync(`git commit -m ${JSON.stringify(`chore: refresh pnpm-lock.yaml after mission.archive (${moved.length} moved)`)}`, { cwd: workspaceRoot, stdio: ["pipe", "pipe", "pipe"] });
+                logger.info(`  Committed pnpm-lock.yaml refresh (${moved.length} missions archived)`);
+            }
+        }
+        catch (refreshErr) {
+            logger.warn(`  Lockfile refresh failed after archive — lockfile may be stale. Run 'pnpm install' manually: ${refreshErr instanceof Error ? refreshErr.message : String(refreshErr)}`);
+        }
+    }
+    return {
+        data: {
+            command: "mission.archive",
+            status: "ok",
+            moved,
+            skipped,
+            dryRun,
+        },
+        summary: dryRun
+            ? `[dry-run] Would move ${moved.length} mission(s), skip ${skipped.length}`
+            : `Moved ${moved.length} mission(s), skipped ${skipped.length}`,
+        nextSteps: [
+            {
+                action: "Run: pnpm exec werkstatt run mission.list --json to verify active missions",
+                kind: "optional",
+            },
+        ],
+    };
+}
+//# sourceMappingURL=archive.js.map