@markjaquith/agency 2.57.0 → 2.58.0

package/README.md

@@ -859,6 +859,7 @@ 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 tasks [--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]
@@ -866,12 +867,26 @@ 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. 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.
+listed tasks. A task can be archived only when its effective status is terminal
+(`done` or `dropped`). Multi-phase task status is derived from its phases, every
+phase must be terminal, and a task with no phases is not eligible.
+
+`archive tasks` plans the maximal safe cohort of terminal tasks and applies by
+default; `--dry-run` performs the same preflight without mutation. A dependency
+is work required by a candidate, while a dependent is work that requires the
+candidate. Dependencies within the selected cohort can be archived together,
+but a retained dependent excludes its dependency, including exclusions that
+propagate through a dependency chain. Active claims, dirty or otherwise unsafe
+managed checkouts, and occupied archive destinations are reported as per-task
+skips. Invalid workbase structure and infrastructure failures abort the command.
+
+Task and phase archiving update active parent documents. Agency removes
+registered worktrees before moving files, refuses dirty worktrees, and preserves
+branches. Bulk application updates shared parents once and archives the entire
+selected cohort in one rollback-capable transaction; it never archives an empty
+parent epic implicitly. Versioned lifecycle provenance preserves parent
+declarations and dependency edges for restoration. Archived IDs are reserved
+until restored.
 
 ### Work, Publication, and Pull Requests
 

package/package.json

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

package/src/cli-parser.test.ts

@@ -282,6 +282,7 @@ describe("strict CLI parsing", () => {
 			],
 			[["archive", "epic", "one", "two"], "agency archive epic"],
 			[["archive", "task", "one", "two"], "agency archive task"],
+			[["archive", "tasks", "one"], "agency archive tasks"],
 			[["archive", "phase", "one", "two", "three"], "agency archive phase"],
 			[["archive", "list", "extra"], "agency archive list"],
 			[
@@ -414,6 +415,13 @@ describe("strict CLI parsing", () => {
 				values: { "dry-run": true },
 			},
 		)
+		expect(parseCli(["archive", "tasks", "--dry-run", "--json"])).toMatchObject(
+			{
+				commandName: "archive",
+				args: ["tasks"],
+				values: { "dry-run": true, json: true },
+			},
+		)
 	})
 
 	test("validates revision-guarded claim operations", () => {

package/src/cli-parser.ts

@@ -691,7 +691,7 @@ const commands = {
 		},
 	},
 	archive: {
-		usage: "agency archive <list|show|epic|task|phase>",
+		usage: "agency archive <list|show|epic|task|tasks|phase>",
 		options: {
 			...outputOptions,
 			...entitySelectorOptions,
@@ -728,6 +728,12 @@ const commands = {
 				maxArgs: 1,
 				options: ["dry-run", "json", "task"],
 			},
+			tasks: {
+				usage: "agency archive tasks [--dry-run] [--json]",
+				minArgs: 0,
+				maxArgs: 0,
+				options: ["dry-run", "json"],
+			},
 			phase: {
 				usage: "agency archive phase <task-id> <phase-id> [--dry-run] [--json]",
 				minArgs: 2,

package/src/commands/archive.test.ts

@@ -36,6 +36,14 @@ describe("archive command", () => {
 				silent: true,
 			}),
 		)
+		await runTestEffect(
+			task({
+				subcommand: "status",
+				args: ["example", "dropped"],
+				cwd: root,
+				silent: true,
+			}),
+		)
 	})
 
 	afterEach(async () => cleanupTempDir(root))
@@ -85,10 +93,40 @@ describe("archive command", () => {
 		)
 	})
 
+	test("outputs one deterministic bulk archive object and a concise human summary", async () => {
+		const jsonLogs = await captureLogs(() =>
+			runTestEffect(
+				archive({
+					type: "tasks",
+					args: [],
+					cwd: root,
+					dryRun: true,
+					json: true,
+				}),
+			),
+		)
+		expect(jsonLogs).toHaveLength(1)
+		expect(JSON.parse(jsonLogs[0]!)).toMatchObject({
+			operation: "archive",
+			kind: "tasks",
+			dryRun: true,
+			tasks: [{ id: "example", disposition: "planned" }],
+		})
+
+		const humanLogs = await captureLogs(() =>
+			runTestEffect(
+				archive({ type: "tasks", args: [], cwd: root, dryRun: true }),
+			),
+		)
+		expect(humanLogs).toEqual([
+			"Would archive 1 task: example\nSkipped 0 tasks",
+		])
+	})
+
 	test("requires a supported work item type", async () => {
 		await expect(
 			runTestEffect(archive({ args: [], cwd: root, silent: true })),
-		).rejects.toThrow("Available: list, show, epic, task, phase")
+		).rejects.toThrow("Available: list, show, epic, task, tasks, phase")
 	})
 
 	test("rejects an extra archive show identifier", async () => {

package/src/commands/archive.ts

@@ -92,6 +92,11 @@ export const archive = (options: ArchiveOptions) =>
 					dryRun: options.dryRun,
 				})
 				break
+			case "tasks":
+				result = yield* archives.archiveTasks(cwd, {
+					dryRun: options.dryRun,
+				})
+				break
 			case "phase":
 				if (!id || !phaseId)
 					return yield* Effect.fail(
@@ -104,11 +109,28 @@ export const archive = (options: ArchiveOptions) =>
 			default:
 				return yield* Effect.fail(
 					new Error(
-						"Archive operation is required. Available: list, show, epic, task, phase",
+						"Archive operation is required. Available: list, show, epic, task, tasks, phase",
 					),
 				)
 		}
 
+		if (result.kind === "tasks") {
+			const selected = result.tasks.filter(
+				(task) => task.disposition !== "skipped",
+			)
+			const skipped = result.tasks.filter(
+				(task) => task.disposition === "skipped",
+			)
+			log(
+				options.json
+					? JSON.stringify(result, null, 2)
+					: [
+							`${result.dryRun ? "Would archive" : "Archived"} ${selected.length} task${selected.length === 1 ? "" : "s"}${selected.length ? `: ${selected.map((task) => task.id).join(", ")}` : ""}`,
+							`Skipped ${skipped.length} task${skipped.length === 1 ? "" : "s"}${skipped.length ? `: ${skipped.map((task) => `${task.id} (${task.reason!.code})`).join(", ")}` : ""}`,
+						].join("\n"),
+			)
+			return
+		}
 		log(
 			options.json
 				? JSON.stringify(result, null, 2)
@@ -119,7 +141,7 @@ export const archive = (options: ArchiveOptions) =>
 	})
 
 export const help = `
-Usage: agency archive <list|show|epic|task|phase>
+Usage: agency archive <list|show|epic|task|tasks|phase>
 
 Browse or archive work items after preflighting worktrees and graph references.
 
@@ -129,6 +151,7 @@ Commands:
   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
+  tasks                                 Archive all eligible terminal tasks
   phase <task-id> <phase-id>             Archive a phase
 
 Options:

package/src/commands/restore.test.ts

@@ -35,6 +35,14 @@ describe("restore command", () => {
 				silent: true,
 			}),
 		)
+		await runTestEffect(
+			task({
+				subcommand: "status",
+				args: ["example", "dropped"],
+				cwd: root,
+				silent: true,
+			}),
+		)
 		await runTestEffect(
 			archive({ type: "task", args: ["example"], cwd: root, silent: true }),
 		)