@markjaquith/agency 2.22.0 → 2.24.0

package/README.md

@@ -400,6 +400,8 @@ repository. Alias names are then used by all documents and commands.
 Commands that print Agency-owned results accept `--json`, including initialization,
 integration inspection/sync, repository mutations, entity creation/list/show,
 status, validation, graph export, reconciliation, and PR creation.
+Entity create, list, and show results include a stable SHA-256 `revision` of the
+complete Markdown document.
 
 ### Epics
 
@@ -515,6 +517,13 @@ references as one rollback-capable mutation and refuse when a materialized
 worktree would make the directory move unsafe. Mutation JSON includes changed
 paths and the focused validation scope.
 
+Epic, task, and phase update, rename, move, and dependency mutations accept
+`--if-revision <hash>`. The option is optional for interactive human use. When
+provided, Agency fails with a structured `REVISION_CONFLICT` containing the
+expected and current revisions if the target changed. Multi-document mutations
+also recheck every affected document after taking the mutation lock and before
+writing anything.
+
 Single-phase tasks and phases store status in YAML. New execution units start
 `open`, and `agency work` marks the selected execution unit `working` immediately
 before launch. Use claims for coordinated ownership and the status subcommands
@@ -565,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,
@@ -238,6 +239,7 @@ const commands: Record<string, Command> = {
 					ticketUrl: options["ticket-url"],
 					description: options.description,
 					clearDescription: options["clear-description"],
+					ifRevision: options["if-revision"],
 					repos: options.repo,
 					json: options.json,
 					statuses: options.status,
@@ -289,6 +291,7 @@ const commands: Record<string, Command> = {
 					clearReferences: options["clear-references"],
 					prUrl: options["pr-url"],
 					clearPr: options["clear-pr"],
+					ifRevision: options["if-revision"],
 					dependsOn: options["depends-on"],
 					firstPhase: options["first-phase"],
 					json: options.json,
@@ -315,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,
@@ -399,6 +425,7 @@ const commands: Record<string, Command> = {
 					clearReferences: options["clear-references"],
 					prUrl: options["pr-url"],
 					clearPr: options["clear-pr"],
+					ifRevision: options["if-revision"],
 					noEpic: options["no-epic"],
 					multiPhase: options["multi-phase"],
 					json: options.json,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.22.0",
+  "version": "2.24.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"],
@@ -296,6 +328,31 @@ describe("strict CLI parsing", () => {
 		).toThrow("must be 'done' or 'dropped'")
 	})
 
+	test("accepts valid mutation revisions and rejects malformed hashes", () => {
+		const revision = "a".repeat(64)
+		expect(
+			parseCli([
+				"task",
+				"move",
+				"example",
+				"--no-epic",
+				"--if-revision",
+				revision,
+			]),
+		).toMatchObject({ values: { "if-revision": revision } })
+		expect(() =>
+			parseCli([
+				"phase",
+				"rename",
+				"task",
+				"phase",
+				"renamed",
+				"--if-revision",
+				"stale",
+			]),
+		).toThrow("64-character SHA-256 hash")
+	})
+
 	test("accepts context projections and keeps compact command-local", () => {
 		expect(parseCli(["context", ".", "--json", "--compact"])).toMatchObject({
 			commandName: "context",

package/src/cli-parser.ts

@@ -91,6 +91,7 @@ const phaseCreateOptions = {
 } satisfies OptionConfig
 
 const mutationOptions = {
+	"if-revision": { type: "string" },
 	"clear-description": { type: "boolean" },
 	"clear-ticket": { type: "boolean" },
 	"clear-references": { type: "boolean" },
@@ -249,6 +250,7 @@ const commands = {
 					"clear-description",
 					"ticket-url",
 					"repo",
+					"if-revision",
 					"json",
 				],
 				repeatable: ["repo"],
@@ -258,7 +260,7 @@ const commands = {
 				usage: "agency epic rename <id> <new-id> [--json]",
 				minArgs: 2,
 				maxArgs: 2,
-				options: ["json"],
+				options: ["if-revision", "json"],
 			},
 		},
 	},
@@ -344,6 +346,7 @@ const commands = {
 					"base",
 					"pr-url",
 					"clear-pr",
+					"if-revision",
 					"json",
 				],
 				repeatable: ["reference"],
@@ -358,13 +361,13 @@ const commands = {
 				usage: "agency task rename <id> <new-id> [--json]",
 				minArgs: 2,
 				maxArgs: 2,
-				options: ["json"],
+				options: ["if-revision", "json"],
 			},
 			move: {
 				usage: "agency task move <id> (--epic <id> | --no-epic) [--json]",
 				minArgs: 1,
 				maxArgs: 1,
-				options: ["epic", "no-epic", "json"],
+				options: ["epic", "no-epic", "if-revision", "json"],
 				conflicts: [["epic", "no-epic"]],
 			},
 			dependency: {
@@ -372,7 +375,7 @@ const commands = {
 					"agency task dependency <add|remove> <task-id> <dependency-id> [--json]",
 				minArgs: 3,
 				maxArgs: 3,
-				options: ["json"],
+				options: ["if-revision", "json"],
 			},
 		},
 	},
@@ -441,6 +444,7 @@ const commands = {
 					"base",
 					"pr-url",
 					"clear-pr",
+					"if-revision",
 					"json",
 				],
 				repeatable: ["reference"],
@@ -454,14 +458,14 @@ const commands = {
 				usage: "agency phase rename <task-id> <phase-id> <new-id> [--json]",
 				minArgs: 3,
 				maxArgs: 3,
-				options: ["json"],
+				options: ["if-revision", "json"],
 			},
 			dependency: {
 				usage:
 					"agency phase dependency <add|remove> <task-id> <phase-id> <dependency-id> [--json]",
 				minArgs: 4,
 				maxArgs: 4,
-				options: ["json"],
+				options: ["if-revision", "json"],
 			},
 		},
 	},
@@ -539,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"],
 			},
 		},
 	},
@@ -785,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 []
 }
@@ -1125,16 +1181,28 @@ export function parseCli(args: readonly string[]): ParsedCli {
 		["epic", "task", "phase"].includes(commandName) &&
 		subcommand === "update"
 	) {
-		const mutationNames = (spec.options ?? []).filter((name) => name !== "json")
+		const mutationNames = (spec.options ?? []).filter(
+			(name) => name !== "json" && name !== "if-revision",
+		)
 		if (!mutationNames.some((name) => parsed.values[name] !== undefined)) {
 			throw usageError("At least one update option is required.", spec.usage)
 		}
 	}
+	if (
+		typeof parsed.values["if-revision"] === "string" &&
+		!/^[a-f0-9]{64}$/.test(parsed.values["if-revision"])
+	) {
+		throw usageError(
+			"Option '--if-revision' must be a 64-character SHA-256 hash.",
+			spec.usage,
+		)
+	}
 	if (commandName === "graph") {
 		validateGraphOptions(parsed.values, spec)
 	}
 	if (
 		commandName === "status" ||
+		(commandName === "archive" && subcommand === "list") ||
 		(["epic", "task", "phase"].includes(commandName) && subcommand === "list")
 	) {
 		validateViewOptions(parsed.values, spec)

package/src/cli.test.ts

@@ -203,6 +203,41 @@ describe("CLI", () => {
 				),
 			)
 		}
+		const observed = parseJson(
+			await runCli(["task", "show", "second", "--json"], root),
+		)
+		const taskPath = join(root, "tasks/second/TASK.md")
+		await Bun.write(
+			taskPath,
+			`${await Bun.file(taskPath).text()}\nConcurrent edit.\n`,
+		)
+		const conflict = await runCli(
+			[
+				"task",
+				"update",
+				"second",
+				"--description",
+				"Stale update",
+				"--if-revision",
+				observed.revision,
+				"--json",
+			],
+			root,
+		)
+		expect(conflict.exitCode).toBe(1)
+		expect(JSON.parse(conflict.stdout)).toMatchObject({
+			ok: false,
+			error: {
+				code: "REVISION_CONFLICT",
+				retryable: true,
+				fields: {
+					path: "tasks/second/TASK.md",
+					expectedRevision: observed.revision,
+					currentRevision: expect.stringMatching(/^[a-f0-9]{64}$/),
+				},
+			},
+		})
+		expect(await Bun.file(taskPath).text()).toContain("Concurrent edit.")
 
 		const updated = parseJson(
 			await runCli(
@@ -310,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,36 @@ 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("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,114 @@ 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" : "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
 `