@markjaquith/agency 2.23.0 → 2.25.0

package/README.md

@@ -574,15 +574,24 @@ runner environment documented above for a later release or finish operation.
 ### Archive
 
 ```text
-agency archive epic <epic-id> [--json]
-agency archive task <task-id> [--json]
-agency archive phase <task-id> <phase-id> [--json]
+agency archive list [--kind <kind>] [--status <status>] [--repository <alias>]
+agency archive show <epic|task> <id>
+agency archive show phase <task-id> <phase-id>
+agency archive epic <epic-id> [--dry-run] [--json]
+agency archive task <task-id> [--dry-run] [--json]
+agency archive phase <task-id> <phase-id> [--dry-run] [--json]
+agency restore epic <epic-id> [--dry-run] [--json]
+agency restore task <task-id> [--dry-run] [--json]
+agency restore phase <task-id> <phase-id> [--dry-run] [--json]
 ```
 
 Archived work keeps its hierarchy under `archive/`. Epic archiving includes its
 listed tasks. Task and phase archiving update the active parent document and
 reject items that active siblings depend on. Agency removes registered worktrees
-before moving files, refuses dirty worktrees, and preserves branches.
+before moving files, refuses dirty worktrees, and preserves branches. Archive and
+restore preflight all destinations and graph references before changing files.
+Versioned lifecycle provenance preserves parent declarations and dependency edges
+for restoration. Archived IDs are reserved until restored.
 
 ### Work and Pull Requests
 

package/cli.ts

@@ -17,6 +17,7 @@ import { repo, help as repoHelp } from "./src/commands/repo"
 import { epic, help as epicHelp } from "./src/commands/epic"
 import { phase, help as phaseHelp } from "./src/commands/phase"
 import { archive, help as archiveHelp } from "./src/commands/archive"
+import { restore, help as restoreHelp } from "./src/commands/restore"
 import { workbase, help as workbaseHelp } from "./src/commands/workbase"
 import {
 	integration,
@@ -317,6 +318,29 @@ const commands: Record<string, Command> = {
 					type: args[0],
 					args: args.slice(1),
 					json: options.json,
+					dryRun: options["dry-run"],
+					kinds: options.kind,
+					statuses: options.status,
+					repositories: options.repository,
+					silent: options.silent,
+					verbose: options.verbose,
+					cwd: options.cwd,
+				}),
+			)
+		},
+	},
+	restore: {
+		run: async (args: string[], options: Record<string, any>) => {
+			if (options.help) {
+				console.log(restoreHelp)
+				return
+			}
+			await runCommand(
+				restore({
+					type: args[0],
+					args: args.slice(1),
+					json: options.json,
+					dryRun: options["dry-run"],
 					silent: options.silent,
 					verbose: options.verbose,
 					cwd: options.cwd,
@@ -659,6 +683,7 @@ try {
 	}
 	if (error instanceof Error) {
 		let message = error.message
+		let details: any = error
 
 		// Handle Effect FiberFailure errors that wrap tagged errors
 		// When the message is generic "An error has occurred", try to extract the actual error
@@ -671,6 +696,7 @@ try {
 				const cause = (error as any)[causeSymbol]
 				if (cause && cause._tag === "Fail" && cause.failure) {
 					const failure = cause.failure
+					details = failure
 					// Try common error message patterns
 					message =
 						failure.message ||
@@ -681,6 +707,14 @@ try {
 				}
 			}
 		}
+		for (const [field, label] of [
+			["completed", "Completed"],
+			["rolledBack", "Rolled back"],
+			["manualRecovery", "Manual recovery"],
+		] as const) {
+			if (Array.isArray(details[field]) && details[field].length > 0)
+				message += `\n${label}: ${details[field].join("; ")}`
+		}
 
 		console.error(`ⓘ ${message}`)
 	} else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.23.0",
+  "version": "2.25.0",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",

package/skills/agency/SKILL.md

@@ -248,14 +248,22 @@ agency finish <task-id> [phase-id] --session-id <id> --revision <sha256> --outco
 ## Archive Completed Work
 
 ```bash
+agency archive list
+agency archive show <epic|task> <id>
 agency archive epic <epic-id>
 agency archive task <task-id>
 agency archive phase <task-id> <phase-id>
+agency restore epic <epic-id>
+agency restore task <task-id>
+agency restore phase <task-id> <phase-id>
 ```
 
 Use these commands instead of moving work item folders manually. Agency mirrors
 their hierarchy under `archive/`, removes registered worktrees first, and keeps
-branches. It refuses dirty worktrees and active sibling dependencies.
+branches. It refuses dirty worktrees and active sibling dependencies. Use
+`--dry-run` to preflight archive or restore. Restore uses lifecycle provenance to
+recreate parent declarations and rejects ID, backlink, dependency, and destination
+conflicts. Archived IDs remain reserved until restored.
 
 ## Validate Every Structural Change
 

package/src/cli-parser.test.ts

@@ -75,6 +75,27 @@ describe("strict CLI parsing", () => {
 			reference: ["two:main", "three:main"],
 			"depends-on": ["first", "second"],
 		})
+		expect(
+			parseCli([
+				"archive",
+				"list",
+				"--kind",
+				"task",
+				"--kind",
+				"phase",
+				"--status",
+				"done",
+				"--repository",
+				"agency",
+			]).values,
+		).toMatchObject({
+			kind: ["task", "phase"],
+			status: ["done"],
+			repository: ["agency"],
+		})
+		expect(
+			parseCli(["restore", "task", "example", "--dry-run"]).values,
+		).toMatchObject({ "dry-run": true })
 	})
 
 	test("parses composable view filters", () => {
@@ -110,6 +131,9 @@ describe("strict CLI parsing", () => {
 		expect(() => parseCli(["status", "--pr", "--no-pr"])).toThrow(
 			"cannot be combined",
 		)
+		expect(() => parseCli(["archive", "list", "--status", "invalid"])).toThrow(
+			"Invalid '--status' value",
+		)
 	})
 
 	test("enforces exact maximum positional arity for every leaf command", () => {
@@ -170,6 +194,14 @@ describe("strict CLI parsing", () => {
 			[["archive", "epic", "one", "two"], "agency archive epic"],
 			[["archive", "task", "one", "two"], "agency archive task"],
 			[["archive", "phase", "one", "two", "three"], "agency archive phase"],
+			[["archive", "list", "extra"], "agency archive list"],
+			[
+				["archive", "show", "task", "one", "extra", "more"],
+				"agency archive show",
+			],
+			[["restore", "epic", "one", "two"], "agency restore epic"],
+			[["restore", "task", "one", "two"], "agency restore task"],
+			[["restore", "phase", "one", "two", "three"], "agency restore phase"],
 			[["work", "one", "two"], "agency work"],
 			[["pr", "create", "one", "two", "three"], "agency pr create"],
 			[["status", "extra"], "agency status"],
@@ -260,6 +292,15 @@ describe("strict CLI parsing", () => {
 		)
 	})
 
+	test("accepts archive dry-run", () => {
+		expect(parseCli(["archive", "task", "example", "--dry-run"])).toMatchObject(
+			{
+				commandName: "archive",
+				values: { "dry-run": true },
+			},
+		)
+	})
+
 	test("validates revision-guarded claim operations", () => {
 		const revision = "0".repeat(64)
 		expect(

package/src/cli-parser.ts

@@ -543,26 +543,76 @@ const commands = {
 		},
 	},
 	archive: {
-		usage: "agency archive <epic|task|phase>",
-		options: { ...outputOptions, ...entitySelectorOptions },
+		usage: "agency archive <list|show|epic|task|phase>",
+		options: {
+			...outputOptions,
+			...entitySelectorOptions,
+			"dry-run": { type: "boolean" },
+			kind: { type: "string", multiple: true },
+			status: { type: "string", multiple: true },
+			repository: { type: "string", multiple: true },
+		},
 		subcommands: {
+			list: {
+				usage:
+					"agency archive list [--kind <kind>] [--status <status>] [--repository <alias>] [--json]",
+				minArgs: 0,
+				maxArgs: 0,
+				options: ["kind", "status", "repository", "json"],
+				repeatable: ["kind", "status", "repository"],
+			},
+			show: {
+				usage:
+					"agency archive show <epic|task> <id> | phase <task-id> <phase-id> [--json]",
+				minArgs: 2,
+				maxArgs: 3,
+				options: ["json"],
+			},
 			epic: {
-				usage: "agency archive epic <epic-id> [--json]",
+				usage: "agency archive epic <epic-id> [--dry-run] [--json]",
 				minArgs: 1,
 				maxArgs: 1,
-				options: ["json", "epic"],
+				options: ["dry-run", "json", "epic"],
 			},
 			task: {
-				usage: "agency archive task <task-id> [--json]",
+				usage: "agency archive task <task-id> [--dry-run] [--json]",
 				minArgs: 1,
 				maxArgs: 1,
-				options: ["json", "task"],
+				options: ["dry-run", "json", "task"],
 			},
 			phase: {
-				usage: "agency archive phase <task-id> <phase-id> [--json]",
+				usage: "agency archive phase <task-id> <phase-id> [--dry-run] [--json]",
 				minArgs: 2,
 				maxArgs: 2,
-				options: ["json", "task", "phase"],
+				options: ["dry-run", "json", "task", "phase"],
+			},
+		},
+	},
+	restore: {
+		usage: "agency restore <epic|task|phase>",
+		options: {
+			...outputOptions,
+			...entitySelectorOptions,
+			"dry-run": { type: "boolean" },
+		},
+		subcommands: {
+			epic: {
+				usage: "agency restore epic <epic-id> [--dry-run] [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["dry-run", "json", "epic"],
+			},
+			task: {
+				usage: "agency restore task <task-id> [--dry-run] [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["dry-run", "json", "task"],
+			},
+			phase: {
+				usage: "agency restore phase <task-id> <phase-id> [--dry-run] [--json]",
+				minArgs: 2,
+				maxArgs: 2,
+				options: ["dry-run", "json", "task", "phase"],
 			},
 		},
 	},
@@ -789,12 +839,14 @@ const targetSlots = (
 		return subcommand === "list" ? ["task"] : ["task", "phase"]
 	if (["claim", "release", "finish"].includes(commandName))
 		return ["task", "phase"]
-	if (commandName === "archive")
+	if (["archive", "restore"].includes(commandName))
 		return subcommand === "epic"
 			? ["epic"]
 			: subcommand === "task"
 				? ["task"]
-				: ["task", "phase"]
+				: subcommand === "phase"
+					? ["task", "phase"]
+					: []
 	if (commandName === "pr" && subcommand === "create") return ["task", "phase"]
 	return []
 }
@@ -1150,6 +1202,7 @@ export function parseCli(args: readonly string[]): ParsedCli {
 	}
 	if (
 		commandName === "status" ||
+		(commandName === "archive" && subcommand === "list") ||
 		(["epic", "task", "phase"].includes(commandName) && subcommand === "list")
 	) {
 		validateViewOptions(parsed.values, spec)

package/src/cli.test.ts

@@ -345,6 +345,7 @@ describe("CLI", () => {
 			["task", "Usage: agency task"],
 			["phase", "Usage: agency phase"],
 			["archive", "Usage: agency archive"],
+			["restore", "Usage: agency restore"],
 			["work", "Usage: agency work"],
 			["pr", "Usage: agency pr"],
 			["status", "Usage: agency status"],

package/src/commands/archive.test.ts

@@ -52,18 +52,58 @@ describe("archive command", () => {
 			),
 		)
 
-		expect(JSON.parse(logs[0]!)).toEqual({
+		expect(JSON.parse(logs[0]!)).toMatchObject({
+			operation: "archive",
 			kind: "task",
 			id: "example",
 			path: join(root, "archive/tasks/example"),
-			archivedPaths: [join(root, "archive/tasks/example")],
+			affectedPaths: [join(root, "archive/tasks/example")],
 			removedWorktrees: [],
+			dryRun: false,
 		})
 	})
 
+	test("preflights an archive without moving the task", async () => {
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				archive({
+					type: "task",
+					args: ["example"],
+					cwd: root,
+					dryRun: true,
+					json: true,
+				}),
+			),
+		)
+
+		expect(JSON.parse(logs[0]!).dryRun).toBe(true)
+		expect(await Bun.file(join(root, "tasks/example/TASK.md")).exists()).toBe(
+			true,
+		)
+		expect(await Bun.file(join(root, "archive/tasks/example")).exists()).toBe(
+			false,
+		)
+	})
+
 	test("requires a supported work item type", async () => {
 		await expect(
 			runTestEffect(archive({ args: [], cwd: root, silent: true })),
-		).rejects.toThrow("Available: epic, task, phase")
+		).rejects.toThrow("Available: list, show, epic, task, phase")
+	})
+
+	test("rejects an extra archive show identifier", async () => {
+		await runTestEffect(
+			archive({ type: "task", args: ["example"], cwd: root, silent: true }),
+		)
+		await expect(
+			runTestEffect(
+				archive({
+					type: "show",
+					args: ["task", "example", "extra"],
+					cwd: root,
+					silent: true,
+				}),
+			),
+		).rejects.toThrow("Usage: agency archive show")
 	})
 })

package/src/commands/archive.ts

@@ -7,6 +7,15 @@ interface ArchiveOptions extends BaseCommandOptions {
 	readonly type?: string
 	readonly args: readonly string[]
 	readonly json?: boolean
+	readonly dryRun?: boolean
+	readonly kinds?: readonly string[]
+	readonly statuses?: readonly string[]
+	readonly repositories?: readonly string[]
+}
+
+const archiveKind = (value: string | undefined) => {
+	if (value === "epic" || value === "task" || value === "phase") return value
+	return undefined
 }
 
 export const archive = (options: ArchiveOptions) =>
@@ -16,55 +25,116 @@ export const archive = (options: ArchiveOptions) =>
 		const cwd = options.cwd ?? process.cwd()
 		const [id, phaseId] = options.args
 
+		if (options.type === "list") {
+			const records = yield* archives.list(
+				{
+					kinds: options.kinds,
+					statuses: options.statuses,
+					repositories: options.repositories,
+				},
+				cwd,
+			)
+			log(
+				options.json
+					? JSON.stringify(records, null, 2)
+					: records
+							.map((record) =>
+								record.kind === "phase"
+									? `phase\t${record.taskId}/${record.id}`
+									: `${record.kind}\t${record.id}`,
+							)
+							.join("\n"),
+			)
+			return
+		}
+
+		if (options.type === "show") {
+			const [kindValue, firstId, secondId] = options.args
+			const kind = archiveKind(kindValue)
+			if (
+				!kind ||
+				!firstId ||
+				(kind === "phase" ? !secondId : secondId !== undefined)
+			) {
+				return yield* Effect.fail(
+					new Error(
+						"Usage: agency archive show <epic|task> <id> | phase <task-id> <phase-id>",
+					),
+				)
+			}
+			const record = yield* archives.show(
+				kind,
+				kind === "phase" ? secondId! : firstId,
+				kind === "phase" ? firstId : undefined,
+				cwd,
+			)
+			log(options.json ? JSON.stringify(record, null, 2) : record.content)
+			return
+		}
+
 		let result
 		switch (options.type) {
 			case "epic":
-				if (!id) {
+				if (!id)
 					return yield* Effect.fail(
 						new Error("Usage: agency archive epic <epic-id>"),
 					)
-				}
-				result = yield* archives.archiveEpic(id, cwd)
+				result = yield* archives.archiveEpic(id, cwd, {
+					dryRun: options.dryRun,
+				})
 				break
 			case "task":
-				if (!id) {
+				if (!id)
 					return yield* Effect.fail(
 						new Error("Usage: agency archive task <task-id>"),
 					)
-				}
-				result = yield* archives.archiveTask(id, cwd)
+				result = yield* archives.archiveTask(id, cwd, {
+					dryRun: options.dryRun,
+				})
 				break
 			case "phase":
-				if (!id || !phaseId) {
+				if (!id || !phaseId)
 					return yield* Effect.fail(
 						new Error("Usage: agency archive phase <task-id> <phase-id>"),
 					)
-				}
-				result = yield* archives.archivePhase(id, phaseId, cwd)
+				result = yield* archives.archivePhase(id, phaseId, cwd, {
+					dryRun: options.dryRun,
+				})
 				break
 			default:
 				return yield* Effect.fail(
-					new Error("Work item type is required. Available: epic, task, phase"),
+					new Error(
+						"Archive operation is required. Available: list, show, epic, task, phase",
+					),
 				)
 		}
 
 		log(
 			options.json
 				? JSON.stringify(result, null, 2)
-				: `Archived ${result.kind} '${result.id}' to ${result.path}`,
+				: result.dryRun
+					? `Would archive ${result.kind} '${result.id}' to ${result.path}`
+					: `Archived ${result.kind} '${result.id}' to ${result.path}`,
 		)
 	})
 
 export const help = `
-Usage: agency archive <type> <id>
+Usage: agency archive <list|show|epic|task|phase>
 
-Archive a work item after removing its worktrees. Branches are preserved.
+Browse or archive work items after preflighting worktrees and graph references.
 
-Types:
-  epic <epic-id>                Archive an epic and its tasks
-  task <task-id>                Archive a task
-  phase <task-id> <phase-id>    Archive a phase
+Commands:
+  list [filters]                         List archived work
+  show <type> <id>                       Show an archived epic or task
+  show phase <task-id> <phase-id>        Show an archived phase
+  epic <epic-id>                         Archive an epic and its tasks
+  task <task-id>                         Archive a task
+  phase <task-id> <phase-id>             Archive a phase
 
 Options:
-  --json                        Output results as JSON
+  --kind <kind>                          Filter list by kind (repeatable)
+  --status <status>                      Filter list by status (repeatable)
+  --repository <alias>                   Filter list by repository (repeatable)
+  --dry-run                              Preflight without changing files
+  --json                                 Output results as JSON
 `

package/src/commands/restore.test.ts

@@ -0,0 +1,98 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { join } from "node:path"
+import {
+	captureLogs,
+	cleanupTempDir,
+	createTempDir,
+	runTestEffect,
+} from "../test-utils"
+import { archive } from "./archive"
+import { restore } from "./restore"
+import { task } from "./task"
+
+describe("restore command", () => {
+	let root: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
+		const initialized = Bun.spawnSync([
+			"git",
+			"init",
+			"--bare",
+			join(root, "repos/agency"),
+		])
+		if (initialized.exitCode !== 0)
+			throw new Error(new TextDecoder().decode(initialized.stderr))
+		await runTestEffect(
+			task({
+				subcommand: "create",
+				args: ["example"],
+				repo: "agency",
+				branch: "task/example",
+				base: "main",
+				cwd: root,
+				silent: true,
+			}),
+		)
+		await runTestEffect(
+			archive({ type: "task", args: ["example"], cwd: root, silent: true }),
+		)
+	})
+
+	afterEach(async () => cleanupTempDir(root))
+
+	test("dry-runs then restores an archived task", async () => {
+		const preview = await captureLogs(() =>
+			runTestEffect(
+				restore({
+					type: "task",
+					args: ["example"],
+					cwd: root,
+					dryRun: true,
+				}),
+			),
+		)
+		expect(preview[0]).toContain("Would restore task 'example'")
+		expect(await Bun.file(join(root, "tasks/example/TASK.md")).exists()).toBe(
+			false,
+		)
+
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				restore({ type: "task", args: ["example"], cwd: root, json: true }),
+			),
+		)
+		expect(JSON.parse(logs[0]!)).toMatchObject({
+			operation: "restore",
+			kind: "task",
+			id: "example",
+			dryRun: false,
+		})
+		expect(await Bun.file(join(root, "tasks/example/TASK.md")).exists()).toBe(
+			true,
+		)
+	})
+
+	test("lists and shows archived work", async () => {
+		const listed = await captureLogs(() =>
+			runTestEffect(
+				archive({
+					type: "list",
+					args: [],
+					kinds: ["task"],
+					repositories: ["agency"],
+					cwd: root,
+				}),
+			),
+		)
+		expect(listed).toEqual(["task\texample"])
+
+		const shown = await captureLogs(() =>
+			runTestEffect(
+				archive({ type: "show", args: ["task", "example"], cwd: root }),
+			),
+		)
+		expect(shown[0]).toContain("# Example")
+	})
+})