@markjaquith/agency 2.61.3 → 2.63.0

package/README.md

@@ -508,6 +508,25 @@ agency validate
 
 ## Commands
 
+### Interactive Actions
+
+`agency act` opens a filterable work-item chooser followed by an action palette
+derived from the selected item's current state and readiness. It offers only
+actions that can use existing lifecycle semantics, such as working, creating a
+pull request, dropping, reopening, or archiving. Cancelling either chooser makes
+no changes, and the command refreshes the graph before dispatch so a stale
+selection cannot act on changed work.
+
+Use `--epic <id>`, `--task <id>`, or `--task <id> --phase <id>` to skip work-item
+selection. `--dry-run` still prompts for an action but prints the exact Agency
+command instead of executing it. `--json` never prompts or executes; it returns
+matching targets, status and readiness details, document revisions, and each
+available action's command argv. With no selector, JSON includes every active
+work item.
+
+`--auto` is included in generated or executed work commands, and `--draft` is
+included in generated or executed pull request commands.
+
 ### Target Context
 
 `agency context [target] --json` returns complete bootstrap context without
@@ -516,6 +535,10 @@ a discovery catalog of all epics, tasks, and phases, including frontmatter,
 paths, and document revisions. Elsewhere it returns context for an epic, task,
 or phase. The target defaults to the current directory; entity directories,
 document paths, checkout descendants, and bare task IDs are accepted.
+Archived entity paths and selectors are also accepted. Archived context is
+explicitly marked with `target.archived: true` and never grants writable
+document, repository checkout, or reference authority; restore the item before
+attempting mutation or execution.
 
 Root discovery is compact by default and includes a hint to run `agency context
 . --full --json` when document prose is needed. Entity context remains complete

package/cli-main.ts

@@ -54,6 +54,7 @@ import {
 import { review, help as reviewHelp } from "./src/commands/review"
 import { vcs, help as vcsHelp } from "./src/commands/vcs"
 import { VcsMigrationService } from "./src/services/VcsMigrationService"
+import { act, help as actHelp } from "./src/commands/act"
 import {
 	claimCommand,
 	claimHelp,
@@ -175,6 +176,26 @@ const VERSION = packageJson.version
 
 // Define commands
 const commands: Record<string, Command> = {
+	act: {
+		run: async (_args: string[], options: Record<string, any>) => {
+			if (options.help) return console.log(actHelp)
+			await runCommand(
+				act({
+					auto: options.auto,
+					draft: options.draft,
+					dryRun: options["dry-run"],
+					json: options.json,
+					epicId: options.epic,
+					taskId: options.task,
+					phaseId: options.phase,
+					inputAllowed: options.inputAllowed,
+					silent: options.silent,
+					verbose: options.verbose,
+					cwd: options.cwd,
+				}),
+			)
+		},
+	},
 	claim: {
 		run: async (args: string[], options: Record<string, any>) => {
 			if (options.help) return console.log(claimHelp)
@@ -753,6 +774,7 @@ agency v${VERSION}
 Usage: agency <command> [options]
 
 Commands:
+  act                    Interactively choose and act on work
   init [path]            Initialize an Agency workbase
   workbase <subcommand>  Manage registered workbases
   integration <command> Inspect or sync managed integration files

package/package.json

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

package/src/cli-parser.test.ts

@@ -7,6 +7,39 @@ const expectUsageError = (args: string[], usage: string) => {
 }
 
 describe("strict CLI parsing", () => {
+	test("parses act selectors, dry-run, and JSON options", () => {
+		expect(
+			parseCli([
+				"act",
+				"--task",
+				"example",
+				"--phase",
+				"build",
+				"--dry-run",
+				"--auto",
+				"--draft",
+			]),
+		).toMatchObject({
+			commandName: "act",
+			args: [],
+			values: {
+				task: "example",
+				phase: "build",
+				"dry-run": true,
+				auto: true,
+				draft: true,
+			},
+		})
+		expect(parseCli(["act", "--json"]).values.json).toBe(true)
+		expectUsageError(["act", "task-id"], "agency act")
+		expectUsageError(["act", "--phase", "build"], "agency act")
+		expectUsageError(
+			["act", "--epic", "roadmap", "--task", "example"],
+			"agency act",
+		)
+		expectUsageError(["act", "--dry-run", "--json"], "agency act")
+	})
+
 	test("accepts review creation and refresh while enforcing one source", () => {
 		expect(
 			parseCli([

package/src/cli-parser.ts

@@ -146,6 +146,29 @@ const commands = {
 			options: ["json"],
 		},
 	},
+	act: {
+		usage:
+			"agency act [--epic <id> | --task <id> [--phase <id>]] [--dry-run | --json] [--auto] [--draft]",
+		options: {
+			...outputOptions,
+			...entitySelectorOptions,
+			"dry-run": { type: "boolean" },
+			auto: { type: "boolean" },
+			draft: { type: "boolean" },
+		},
+		command: {
+			usage:
+				"agency act [--epic <id> | --task <id> [--phase <id>]] [--dry-run | --json] [--auto] [--draft]",
+			minArgs: 0,
+			maxArgs: 0,
+			options: ["epic", "task", "phase", "dry-run", "json", "auto", "draft"],
+			conflicts: [
+				["dry-run", "json"],
+				["epic", "task"],
+				["epic", "phase"],
+			],
+		},
+	},
 	workbase: {
 		usage: "agency workbase <init|add|list|show|name|remove|prune|default>",
 		options: {

package/src/cli.test.ts

@@ -497,10 +497,14 @@ describe("CLI", () => {
 			expect(result.stderr).toContain("task new requires interactive input")
 			expect(result.stderr).toContain("agency task create")
 		}
+		const actResult = await runCli(["act", "--no-input"])
+		expect(actResult.exitCode).toBe(1)
+		expect(actResult.stderr).toContain("agency act requires interactive input")
 	})
 
 	test("routes command help and global options on either side of commands", async () => {
 		const commands = [
+			["act", "Usage: agency act"],
 			["init", "Usage: agency init"],
 			["workbase", "Usage: agency workbase"],
 			["integration", "Usage: agency integration"],

package/src/commands/act.test.ts

@@ -0,0 +1,323 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { join } from "node:path"
+import {
+	captureLogs,
+	cleanupTempDir,
+	createTempDir,
+	runTestEffect,
+} from "../test-utils"
+import type { Choice } from "../utils/chooser"
+import { phase } from "./phase"
+import { task } from "./task"
+import { act, type ActInteraction } from "./act"
+
+const scriptedInteraction = (
+	selections: readonly (string | null)[],
+	onSelect?: (prompt: string, choices: readonly Choice<unknown>[]) => void,
+): ActInteraction => {
+	let index = 0
+	return {
+		select: (prompt, choices) => {
+			onSelect?.(prompt, choices)
+			const selection = selections[index++] ?? null
+			return Effect.succeed(
+				selection === null
+					? null
+					: (choices.find((choice) => choice.value === selection)?.value ??
+							null),
+			)
+		},
+	}
+}
+
+describe("act 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))
+		}
+	})
+
+	afterEach(async () => cleanupTempDir(root))
+
+	test("rejects non-interactive and empty invocations cleanly", async () => {
+		await expect(
+			runTestEffect(act({ cwd: root, inputAllowed: false })),
+		).rejects.toThrow("requires interactive input")
+		await expect(
+			runTestEffect(
+				act({ cwd: root, inputAllowed: true }, scriptedInteraction([])),
+			),
+		).rejects.toThrow("No active work items")
+	})
+
+	test("returns an empty target list as JSON without interactive input", async () => {
+		const logs = await captureLogs(() =>
+			runTestEffect(act({ cwd: root, inputAllowed: false, json: true })),
+		)
+		expect(JSON.parse(logs[0]!)).toEqual({ targets: [] })
+	})
+
+	test("cancellation exits without changing the selected item", async () => {
+		await createTask("example")
+		await runTestEffect(
+			act({ cwd: root, inputAllowed: true }, scriptedInteraction([null])),
+		)
+
+		expect(await readTaskStatus("example")).toBe("open")
+	})
+
+	test("offers state-aware actions and dispatches drop through lifecycle semantics", async () => {
+		await createTask("example")
+		const offered: string[][] = []
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				act(
+					{ cwd: root, inputAllowed: true },
+					scriptedInteraction(["task:example", "drop"], (_prompt, choices) => {
+						offered.push(choices.map((choice) => String(choice.value)))
+					}),
+				),
+			),
+		)
+
+		expect(offered[1]).toEqual(["work", "pr", "drop"])
+		expect(logs).toEqual(["Marked task 'example' as dropped"])
+		expect(await readTaskStatus("example")).toBe("dropped")
+	})
+
+	test("accepts an explicit selector and prints dry-run command without mutation", async () => {
+		await createTask("example")
+		const prompts: string[] = []
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				act(
+					{
+						cwd: root,
+						inputAllowed: true,
+						taskId: "example",
+						dryRun: true,
+					},
+					scriptedInteraction(["drop"], (prompt) => prompts.push(prompt)),
+				),
+			),
+		)
+
+		expect(prompts).toEqual(["Act on task example"])
+		expect(logs).toEqual(["agency task status example dropped"])
+		expect(await readTaskStatus("example")).toBe("open")
+	})
+
+	test("returns structured actions and argv for agents", async () => {
+		await createTask("example")
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				act({
+					cwd: root,
+					inputAllowed: false,
+					taskId: "example",
+					json: true,
+					auto: true,
+					draft: true,
+				}),
+			),
+		)
+
+		expect(JSON.parse(logs[0]!)).toMatchObject({
+			targets: [
+				{
+					kind: "task",
+					key: "example",
+					status: "open",
+					actions: [
+						{
+							id: "work",
+							command: ["agency", "work", "--task", "example", "--auto"],
+						},
+						{
+							id: "pr",
+							command: ["agency", "pr", "create", "example", "--draft"],
+						},
+						{
+							id: "drop",
+							command: ["agency", "task", "status", "example", "dropped"],
+						},
+					],
+				},
+			],
+		})
+	})
+
+	test("offers reopen and archive for terminal work", async () => {
+		await createTask("example")
+		await runTestEffect(
+			task({
+				subcommand: "status",
+				args: ["example", "dropped"],
+				cwd: root,
+				silent: true,
+			}),
+		)
+		let actions: string[] = []
+		await runTestEffect(
+			act(
+				{ cwd: root, inputAllowed: true },
+				scriptedInteraction(["task:example", null], (prompt, choices) => {
+					if (prompt.startsWith("Act on task")) {
+						actions = choices.map((choice) => String(choice.value))
+					}
+				}),
+			),
+		)
+
+		expect(actions).toEqual(["reopen", "archive"])
+	})
+
+	test("dispatches phase actions with the parent task identifier", async () => {
+		await runTestEffect(
+			task({
+				subcommand: "create",
+				args: ["multi"],
+				multiPhase: true,
+				cwd: root,
+				silent: true,
+			}),
+		)
+		await runTestEffect(
+			phase({
+				subcommand: "create",
+				args: ["multi", "build"],
+				repo: "agency",
+				branch: "task/multi-build",
+				base: "main",
+				cwd: root,
+				silent: true,
+			}),
+		)
+
+		let actions: string[] = []
+		await runTestEffect(
+			act(
+				{ cwd: root, inputAllowed: true, silent: true },
+				scriptedInteraction(
+					["phase:multi/build", "drop"],
+					(prompt, choices) => {
+						if (prompt.startsWith("Act on phase")) {
+							actions = choices.map((choice) => String(choice.value))
+						}
+					},
+				),
+			),
+		)
+
+		expect(actions).toEqual(["work", "pr", "drop"])
+		const content = await Bun.file(
+			join(root, "tasks/multi/phases/build/PHASE.md"),
+		).text()
+		expect(content).toContain("status: dropped")
+	})
+
+	test("dispatches work and pull request actions through their command handlers", async () => {
+		await createTask("example")
+		const workCalls: unknown[] = []
+		await runTestEffect(
+			act(
+				{ cwd: root, inputAllowed: true, auto: true },
+				scriptedInteraction(["task:example", "work"]),
+				((options) => {
+					workCalls.push(options)
+					return Effect.void
+				}) as Parameters<typeof act>[2],
+			),
+		)
+		expect(workCalls).toEqual([
+			expect.objectContaining({
+				taskId: "example",
+				auto: true,
+				cwd: root,
+			}),
+		])
+
+		let prActionSeen = false
+		await expect(
+			runTestEffect(
+				act(
+					{ cwd: root, inputAllowed: true },
+					{
+						select: (prompt, choices) => {
+							if (prompt.startsWith("Act on task")) {
+								prActionSeen = choices.some((choice) => choice.value === "pr")
+								return Effect.fail(new Error("stop before external PR command"))
+							}
+							return Effect.succeed(
+								choices.find((choice) => choice.value === "task:example")
+									?.value ?? null,
+							)
+						},
+					},
+				),
+			),
+		).rejects.toThrow("stop before external PR command")
+		expect(prActionSeen).toBe(true)
+	})
+
+	test("rejects a stale selection before dispatch", async () => {
+		await createTask("example")
+		let selection = 0
+		const interaction: ActInteraction = {
+			select: (_prompt, choices) => {
+				selection++
+				if (selection === 1) {
+					return Effect.succeed(
+						choices.find((choice) => choice.value === "task:example")?.value ??
+							null,
+					)
+				}
+				return Effect.promise(async () => {
+					await Bun.write(
+						join(root, "tasks/example/TASK.md"),
+						(
+							await Bun.file(join(root, "tasks/example/TASK.md")).text()
+						).replace("# Example", "# Example\n\nChanged after selection"),
+					)
+					return (
+						choices.find((choice) => choice.value === "drop")?.value ?? null
+					)
+				})
+			},
+		}
+
+		await expect(
+			runTestEffect(act({ cwd: root, inputAllowed: true }, interaction)),
+		).rejects.toThrow("Selected work item changed")
+		expect(await readTaskStatus("example")).toBe("open")
+	})
+
+	const createTask = (id: string) =>
+		runTestEffect(
+			task({
+				subcommand: "create",
+				args: [id],
+				repo: "agency",
+				branch: `task/${id}`,
+				base: "main",
+				cwd: root,
+				silent: true,
+			}),
+		)
+
+	const readTaskStatus = async (id: string) => {
+		const content = await Bun.file(join(root, `tasks/${id}/TASK.md`)).text()
+		return content.match(/^status: (.+)$/m)?.[1]
+	}
+})

package/src/commands/act.ts

@@ -0,0 +1,442 @@
+import { Effect } from "effect"
+import type { GraphNode } from "../graph-schema"
+import { isTerminalStatus } from "../readiness"
+import { GraphService } from "../services/GraphService"
+import { WorkbaseService } from "../services/WorkbaseService"
+import type { BaseCommandOptions } from "../utils/command"
+import { choose, type Choice } from "../utils/chooser"
+import { createLoggers } from "../utils/effect"
+import { macchiato } from "../utils/theme"
+import { archive as archiveCommand } from "./archive"
+import { phase as phaseCommand } from "./phase"
+import { prCreate as createPullRequest } from "./pr"
+import { task as taskCommand } from "./task"
+import { work as startWork, type StartWork } from "./work"
+
+type EntityNode = Extract<
+	GraphNode,
+	{ readonly kind: "epic" | "task" | "phase" }
+>
+
+type ActAction = "work" | "pr" | "reopen" | "drop" | "archive"
+
+export interface ActInteraction {
+	readonly select: <T>(
+		prompt: string,
+		choices: readonly Choice<T>[],
+		command?: readonly string[],
+	) => Effect.Effect<T | null, Error>
+}
+
+interface ActOptions extends BaseCommandOptions {
+	readonly auto?: boolean
+	readonly draft?: boolean
+	readonly dryRun?: boolean
+	readonly json?: boolean
+	readonly epicId?: string
+	readonly taskId?: string
+	readonly phaseId?: string
+}
+
+const defaultInteraction: ActInteraction = {
+	select: (prompt, choices, command) => choose(prompt, choices, command),
+}
+
+const entityKey = (node: EntityNode) => `${node.kind}:${node.key}`
+
+const entityDescription = (node: EntityNode) =>
+	"description" in node.data && node.data.description
+		? ` - ${node.data.description}`
+		: ""
+
+const entityChoices = (
+	nodes: readonly EntityNode[],
+): readonly Choice<string>[] =>
+	nodes.map((node, index) => ({
+		key: String(index),
+		label: `[${node.status}] ${node.kind} ${node.key}${entityDescription(node)}`,
+		depth: node.kind === "phase" ? 1 : 0,
+		segments: [
+			{ text: `[${node.status}] `, color: macchiato.overlay1 },
+			{ text: `${node.kind} `, color: macchiato.sapphire },
+			{ text: node.key },
+			...(entityDescription(node)
+				? [{ text: entityDescription(node), color: macchiato.overlay0 }]
+				: []),
+		],
+		value: entityKey(node),
+	}))
+
+const activeClaim = (node: EntityNode) =>
+	"claim" in node.data && node.data.claim?.state === "active"
+
+const executionNode = (
+	node: EntityNode,
+	nodes: readonly GraphNode[],
+): Extract<GraphNode, { readonly kind: "execution-unit" }> | undefined => {
+	if (node.kind === "epic") return undefined
+	if (node.kind === "task" && "phases" in node.data) return undefined
+	const phaseId =
+		node.kind === "phase"
+			? node.key.slice(node.key.indexOf("/") + 1)
+			: undefined
+	return nodes.find(
+		(
+			candidate,
+		): candidate is Extract<GraphNode, { readonly kind: "execution-unit" }> =>
+			candidate.kind === "execution-unit" &&
+			candidate.data.taskId ===
+				(node.kind === "task" ? node.key : node.key.split("/", 1)[0]) &&
+			(node.kind === "task" ||
+				("phaseId" in candidate.data && candidate.data.phaseId === phaseId)),
+	)
+}
+
+const canWork = (node: EntityNode, nodes: readonly GraphNode[]) => {
+	if (node.kind === "epic" || (node.kind === "task" && "phases" in node.data)) {
+		return node.readiness.ready
+	}
+	const execution = executionNode(node, nodes)
+	return Boolean(
+		execution &&
+		!activeClaim(node) &&
+		(execution.readiness.ready ||
+			(execution.status === "working" &&
+				execution.readiness.blockers.every(
+					(blocker) => blocker.kind !== "validation",
+				))),
+	)
+}
+
+const canCreatePr = (node: EntityNode, nodes: readonly GraphNode[]) => {
+	const execution = executionNode(node, nodes)
+	return Boolean(
+		execution &&
+		!execution.readiness.terminal &&
+		!("pr" in execution.data && execution.data.pr) &&
+		!execution.readiness.blockers.some(
+			(blocker) =>
+				blocker.kind === "dependency" || blocker.kind === "validation",
+		),
+	)
+}
+
+const actionChoices = (
+	node: EntityNode,
+	nodes: readonly GraphNode[],
+): readonly Choice<ActAction>[] => {
+	const choices: Choice<ActAction>[] = []
+	const execution = executionNode(node, nodes)
+	if (canWork(node, nodes)) {
+		choices.push({ key: "work", label: "Work on this item", value: "work" })
+	}
+	if (canCreatePr(node, nodes)) {
+		choices.push({ key: "pr", label: "Create pull request", value: "pr" })
+	}
+	if (execution && isTerminalStatus(node.status) && !activeClaim(node)) {
+		choices.push({ key: "reopen", label: "Reopen", value: "reopen" })
+	}
+	if (execution && !isTerminalStatus(node.status) && !activeClaim(node)) {
+		choices.push({ key: "drop", label: "Drop", value: "drop" })
+	}
+	if (node.readiness.terminal) {
+		choices.push({ key: "archive", label: "Archive", value: "archive" })
+	}
+	return choices
+}
+
+const entityParts = (node: EntityNode) => {
+	if (node.kind !== "phase") return { taskId: node.key }
+	const separator = node.key.indexOf("/")
+	return {
+		taskId: node.key.slice(0, separator),
+		phaseId: node.key.slice(separator + 1),
+	}
+}
+
+const actionCommand = (
+	node: EntityNode,
+	action: ActAction,
+	options: Pick<ActOptions, "auto" | "draft">,
+): readonly string[] => {
+	const { taskId, phaseId } = entityParts(node)
+	switch (action) {
+		case "work":
+			return [
+				"agency",
+				"work",
+				...(node.kind === "epic"
+					? ["--epic", node.key]
+					: ["--task", taskId, ...(phaseId ? ["--phase", phaseId] : [])]),
+				...(options.auto ? ["--auto"] : []),
+			]
+		case "pr":
+			return [
+				"agency",
+				"pr",
+				"create",
+				taskId,
+				...(phaseId ? [phaseId] : []),
+				...(options.draft ? ["--draft"] : []),
+			]
+		case "reopen":
+		case "drop": {
+			const status = action === "reopen" ? "open" : "dropped"
+			return phaseId
+				? ["agency", "phase", "status", taskId, phaseId, status]
+				: ["agency", "task", "status", taskId, status]
+		}
+		case "archive":
+			return node.kind === "phase"
+				? ["agency", "archive", "phase", taskId, phaseId!]
+				: ["agency", "archive", node.kind, node.key]
+	}
+}
+
+const shellCommand = (command: readonly string[]) =>
+	command
+		.map((argument) =>
+			/^[A-Za-z0-9_./:=+@%-]+$/.test(argument)
+				? argument
+				: `'${argument.replaceAll("'", `'\\''`)}'`,
+		)
+		.join(" ")
+
+const targetOutput = (
+	node: EntityNode,
+	nodes: readonly GraphNode[],
+	options: Pick<ActOptions, "auto" | "draft">,
+) => ({
+	kind: node.kind,
+	id: node.id,
+	key: node.key,
+	status: node.status,
+	readiness: node.readiness,
+	revision: node.data.sha256,
+	actions: actionChoices(node, nodes).map((choice) => ({
+		id: choice.value,
+		label: choice.label,
+		command: actionCommand(node, choice.value, options),
+	})),
+})
+
+const selectedEntityKey = (options: ActOptions) =>
+	options.epicId
+		? `epic:${options.epicId}`
+		: options.phaseId
+			? `phase:${options.taskId}/${options.phaseId}`
+			: options.taskId
+				? `task:${options.taskId}`
+				: undefined
+
+const sameActions = (
+	left: readonly Choice<ActAction>[],
+	right: readonly Choice<ActAction>[],
+) =>
+	left.map((choice) => choice.value).join("\0") ===
+	right.map((choice) => choice.value).join("\0")
+
+export const act = (
+	options: ActOptions = {},
+	interaction: ActInteraction = defaultInteraction,
+	work: StartWork = startWork,
+) =>
+	Effect.gen(function* () {
+		if (!options.json && options.inputAllowed === false) {
+			return yield* Effect.fail(
+				new Error(
+					"agency act requires interactive input; use --json to list actions for automation",
+				),
+			)
+		}
+		const cwd = options.cwd ?? process.cwd()
+		const workbase = yield* WorkbaseService
+		const graphs = yield* GraphService
+		const { log } = createLoggers(options)
+		const { config } = yield* workbase.loadConfig(cwd)
+		const graph = yield* graphs.get({ cwd })
+		const nodes = graph.nodes.filter(
+			(node): node is EntityNode =>
+				node.kind === "epic" || node.kind === "task" || node.kind === "phase",
+		)
+		if (nodes.length === 0) {
+			if (options.json) {
+				log(JSON.stringify({ targets: [] }, null, 2))
+				return
+			}
+			return yield* Effect.fail(
+				new Error("No active work items found in this workbase"),
+			)
+		}
+
+		const requestedKey = selectedEntityKey(options)
+		const matchingNodes = requestedKey
+			? nodes.filter((node) => entityKey(node) === requestedKey)
+			: nodes
+		if (requestedKey && matchingNodes.length === 0) {
+			return yield* Effect.fail(
+				new Error(`Selected work item '${requestedKey}' was not found`),
+			)
+		}
+		if (options.json) {
+			log(
+				JSON.stringify(
+					{
+						targets: matchingNodes.map((node) =>
+							targetOutput(node, graph.nodes, options),
+						),
+					},
+					null,
+					2,
+				),
+			)
+			return
+		}
+
+		const selectedKey =
+			requestedKey ??
+			(yield* interaction.select(
+				"Act on",
+				entityChoices(nodes),
+				config.chooserCommand,
+			))
+		if (selectedKey === null) return
+		const selected = nodes.find((node) => entityKey(node) === selectedKey)
+		if (!selected) {
+			return yield* Effect.fail(
+				new Error("Selected work item is no longer available"),
+			)
+		}
+		const offeredActions = actionChoices(selected, graph.nodes)
+		if (offeredActions.length === 0) {
+			return yield* Effect.fail(
+				new Error(
+					`No actions are currently available for ${selected.kind} '${selected.key}'`,
+				),
+			)
+		}
+		const action = yield* interaction.select(
+			`Act on ${selected.kind} ${selected.key}`,
+			offeredActions,
+			config.chooserCommand,
+		)
+		if (action === null) return
+
+		const refreshed = yield* graphs.get({ cwd })
+		const current = refreshed.nodes.find(
+			(node): node is EntityNode =>
+				(node.kind === "epic" ||
+					node.kind === "task" ||
+					node.kind === "phase") &&
+				entityKey(node) === selectedKey,
+		)
+		if (!current) {
+			return yield* Effect.fail(
+				new Error(
+					"Selected work item changed or was removed; run agency act again",
+				),
+			)
+		}
+		if (
+			current.data.sha256 !== selected.data.sha256 ||
+			!sameActions(offeredActions, actionChoices(current, refreshed.nodes))
+		) {
+			return yield* Effect.fail(
+				new Error("Selected work item changed; run agency act again"),
+			)
+		}
+		const { taskId, phaseId } = entityParts(current)
+		if (options.dryRun) {
+			log(shellCommand(actionCommand(current, action, options)))
+			return
+		}
+
+		switch (action) {
+			case "work":
+				yield* work({
+					...(current.kind === "epic"
+						? { epicId: current.key }
+						: { taskId, ...(phaseId ? { phaseId } : {}) }),
+					auto: options.auto,
+					cwd,
+					inputAllowed: options.inputAllowed,
+					silent: options.silent,
+					verbose: options.verbose,
+				})
+				return
+			case "pr":
+				yield* createPullRequest({
+					taskId,
+					phaseId,
+					draft: options.draft,
+					cwd,
+					silent: options.silent,
+					verbose: options.verbose,
+				})
+				return
+			case "reopen":
+				if (phaseId) {
+					yield* phaseCommand({
+						subcommand: "status",
+						args: [taskId, phaseId, "open"],
+						cwd,
+						silent: options.silent,
+						verbose: options.verbose,
+					})
+				} else {
+					yield* taskCommand({
+						subcommand: "status",
+						args: [taskId, "open"],
+						cwd,
+						silent: options.silent,
+						verbose: options.verbose,
+					})
+				}
+				return
+			case "drop":
+				if (phaseId) {
+					yield* phaseCommand({
+						subcommand: "status",
+						args: [taskId, phaseId, "dropped"],
+						cwd,
+						silent: options.silent,
+						verbose: options.verbose,
+					})
+				} else {
+					yield* taskCommand({
+						subcommand: "status",
+						args: [taskId, "dropped"],
+						cwd,
+						silent: options.silent,
+						verbose: options.verbose,
+					})
+				}
+				return
+			case "archive":
+				yield* archiveCommand({
+					type: current.kind,
+					args: current.kind === "phase" ? [taskId, phaseId!] : [current.key],
+					cwd,
+					silent: options.silent,
+					verbose: options.verbose,
+				})
+		}
+	})
+
+export const help = `
+Usage: agency act [--epic <id> | --task <id> [--phase <id>]] [--dry-run | --json] [--auto] [--draft]
+
+Interactively choose an active work item and a state-aware lifecycle action.
+Selectors skip work-item selection. --dry-run prints the selected action's exact
+Agency command without executing it. --json lists targets, available actions,
+and command argv without prompting or executing.
+
+Options:
+	--epic <id>           Select an epic
+	--task <id>           Select a task
+	--phase <id>          Select a phase; requires --task
+	--dry-run             Select an action and print its command without executing
+	--json                List available actions and command argv as JSON
+  --auto                Pass --auto when starting or continuing work
+  --draft               Create a draft pull request
+`

package/src/commands/context.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
-import { mkdir, rm } from "node:fs/promises"
+import { mkdir, rename, rm } from "node:fs/promises"
 import { dirname, join } from "node:path"
 import {
 	captureLogs,
@@ -342,6 +342,123 @@ status: dropped
 		expect(result.authority.writable.branch).toBe("foundations")
 	})
 
+	test("resolves archived tasks without granting mutation or execution authority", async () => {
+		await mkdir(join(root, "archive/tasks"), { recursive: true })
+		await rename(
+			join(root, "tasks/foundations"),
+			join(root, "archive/tasks/foundations"),
+		)
+
+		const result = await readContext(root, "foundations")
+
+		expect(result.target).toMatchObject({
+			kind: "task",
+			taskId: "foundations",
+			archived: true,
+			path: join(root, "archive/tasks/foundations/TASK.md"),
+		})
+		expect(result.documents.task.body).toContain("# Foundations")
+		expect(result.authority).toMatchObject({
+			mode: "orchestration",
+			writable: null,
+			references: [],
+			documents: { writable: [] },
+		})
+		expect(result.workspace).toMatchObject({
+			materialization: "absent",
+			writable: null,
+			references: [],
+		})
+		expect(result.graph.readiness).toMatchObject({
+			ready: false,
+			blocked: true,
+		})
+		expect(result.graph.readiness.blockers).toContainEqual({
+			kind: "status",
+			id: "foundations",
+			reason: "Target is archived; restore it before mutation or execution",
+		})
+		expect(result.pr).toMatchObject({
+			url: "https://github.com/example/agency/pull/1",
+			state: "open",
+		})
+	})
+
+	test("resolves archived phases with their active parent context", async () => {
+		await mkdir(join(root, "archive/tasks/agent-contract/phases"), {
+			recursive: true,
+		})
+		await rename(
+			join(root, "tasks/agent-contract/phases/context-command"),
+			join(root, "archive/tasks/agent-contract/phases/context-command"),
+		)
+
+		const result = await readContext(
+			root,
+			"archive/tasks/agent-contract/phases/context-command",
+		)
+
+		expect(result.target).toMatchObject({
+			kind: "phase",
+			taskId: "agent-contract",
+			phaseId: "context-command",
+			archived: true,
+			path: join(
+				root,
+				"archive/tasks/agent-contract/phases/context-command/PHASE.md",
+			),
+		})
+		expect(result.documents.task.body).toContain("Task prose.")
+		expect(result.documents.phase.body).toContain("Phase prose.")
+		expect(result.graph.parent).toEqual({ kind: "task", id: "agent-contract" })
+		expect(result.graph.readiness).toMatchObject({
+			ready: false,
+			blocked: true,
+		})
+		expect(result.authority).toMatchObject({
+			mode: "orchestration",
+			writable: null,
+			references: [],
+			documents: { writable: [] },
+		})
+	})
+
+	test("resolves archived epics with archived descendant graph context", async () => {
+		await mkdir(join(root, "archive/epics"), { recursive: true })
+		await mkdir(join(root, "archive/tasks"), { recursive: true })
+		await rename(
+			join(root, "epics/contract"),
+			join(root, "archive/epics/contract"),
+		)
+		for (const taskId of ["agent-contract", "foundations"]) {
+			await rename(
+				join(root, "tasks", taskId),
+				join(root, "archive/tasks", taskId),
+			)
+		}
+
+		const result = await readContext(root, "epics/contract")
+
+		expect(result.target).toMatchObject({
+			kind: "epic",
+			epicId: "contract",
+			archived: true,
+			path: join(root, "archive/epics/contract/EPIC.md"),
+		})
+		expect(result.documents.epic.body).toContain("# Contract")
+		expect(result.graph.aggregate).toMatchObject({ total: 3, done: 2, open: 1 })
+		expect(result.graph.readiness).toMatchObject({
+			ready: false,
+			blocked: true,
+		})
+		expect(result.authority).toMatchObject({
+			mode: "orchestration",
+			writable: null,
+			references: [],
+			documents: { writable: [] },
+		})
+	})
+
 	test("computes orchestration readiness from runnable descendants", async () => {
 		await write(
 			root,

package/src/commands/context.ts

@@ -23,7 +23,9 @@ Usage: agency context [target] [options]
 
 Return complete, read-only context for a workbase, epic, task, or phase. The
 target defaults to the current directory and may be the workbase root, an entity
-path, or a task ID. Workbase context catalogs all epics, tasks, and phases.
+path, or a task ID. Archived entities are inspectable but never receive mutation
+or execution authority. Workbase context catalogs all active epics, tasks, and
+phases.
 
 Options:
   --json              Output a versioned machine result

package/src/services/ContextService.ts

@@ -20,6 +20,11 @@ import {
 	type TaskFrontmatter as TaskData,
 	type WorkStatus,
 } from "../workbase/schemas"
+import {
+	archivedEpicDirectory,
+	archivedPhaseDirectory,
+	archivedTaskDirectory,
+} from "../workbase/archive"
 
 class ContextError extends Data.TaggedError("ContextError")<{
 	readonly message: string
@@ -36,6 +41,7 @@ interface Document<T> {
 
 interface Target {
 	readonly kind: "epic" | "task" | "phase"
+	readonly archived: boolean
 	readonly epicId?: string
 	readonly taskId?: string
 	readonly phaseId?: string
@@ -240,15 +246,45 @@ export class ContextService extends Effect.Service<ContextService>()(
 						if (!candidateExists && !suppliedTarget.includes(sep)) {
 							return {
 								kind: "task",
+								archived: false,
 								taskId: suppliedTarget,
 								path: join(root, "tasks", suppliedTarget, "TASK.md"),
 							}
 						}
 						if (!isWithin(root, candidate)) return null
 						const parts = relative(root, candidate).split(sep)
+						if (parts[0] === "archive" && parts[1] === "epics" && parts[2]) {
+							return {
+								kind: "epic",
+								archived: true,
+								epicId: parts[2],
+								path: join(archivedEpicDirectory(root, parts[2]), "EPIC.md"),
+							}
+						}
+						if (parts[0] === "archive" && parts[1] === "tasks" && parts[2]) {
+							if (parts[3] === "phases" && parts[4]) {
+								return {
+									kind: "phase",
+									archived: true,
+									taskId: parts[2],
+									phaseId: parts[4],
+									path: join(
+										archivedPhaseDirectory(root, parts[2], parts[4]),
+										"PHASE.md",
+									),
+								}
+							}
+							return {
+								kind: "task",
+								archived: true,
+								taskId: parts[2],
+								path: join(archivedTaskDirectory(root, parts[2]), "TASK.md"),
+							}
+						}
 						if (parts[0] === "epics" && parts[1]) {
 							return {
 								kind: "epic",
+								archived: false,
 								epicId: parts[1],
 								path: join(root, "epics", parts[1], "EPIC.md"),
 							}
@@ -257,6 +293,7 @@ export class ContextService extends Effect.Service<ContextService>()(
 							if (parts[2] === "phases" && parts[3]) {
 								return {
 									kind: "phase",
+									archived: false,
 									taskId: parts[1],
 									phaseId: parts[3],
 									path: join(
@@ -271,6 +308,7 @@ export class ContextService extends Effect.Service<ContextService>()(
 							}
 							return {
 								kind: "task",
+								archived: false,
 								taskId: parts[1],
 								path: join(root, "tasks", parts[1], "TASK.md"),
 							}
@@ -278,13 +316,32 @@ export class ContextService extends Effect.Service<ContextService>()(
 						return null
 					}
 
-					const target = inferTarget()
-					if (!target) {
+					const inferredTarget = inferTarget()
+					if (!inferredTarget) {
 						return yield* new ContextError({
 							target: suppliedTarget,
 							message: `Cannot infer an Agency target from ${candidate}`,
 						})
 					}
+					let target = inferredTarget
+					if (!target.archived && !(yield* fs.exists(target.path))) {
+						const archivedPath =
+							target.kind === "epic"
+								? join(archivedEpicDirectory(root, target.epicId!), "EPIC.md")
+								: target.kind === "phase"
+									? join(
+											archivedPhaseDirectory(
+												root,
+												target.taskId!,
+												target.phaseId!,
+											),
+											"PHASE.md",
+										)
+									: join(archivedTaskDirectory(root, target.taskId!), "TASK.md")
+						if (yield* fs.exists(archivedPath)) {
+							target = { ...target, archived: true, path: archivedPath }
+						}
+					}
 
 					const readDocument = <S extends Schema.Schema.AnyNoContext>(
 						id: string,
@@ -334,26 +391,22 @@ export class ContextService extends Effect.Service<ContextService>()(
 							return yield* readDocument(id, path, schema)
 						})
 
-					const task = target.taskId
-						? yield* readDocument(
-								target.taskId,
-								join(root, "tasks", target.taskId, "TASK.md"),
-								TaskFrontmatter,
-							)
+					const activeTaskPath = target.taskId
+						? join(root, "tasks", target.taskId, "TASK.md")
+						: null
+					const taskPath = target.taskId
+						? target.kind === "task"
+							? target.path
+							: activeTaskPath && (yield* fs.exists(activeTaskPath))
+								? activeTaskPath
+								: join(archivedTaskDirectory(root, target.taskId), "TASK.md")
 						: null
+					const task =
+						target.taskId && taskPath
+							? yield* readDocument(target.taskId, taskPath, TaskFrontmatter)
+							: null
 					const phase = target.phaseId
-						? yield* readDocument(
-								target.phaseId,
-								join(
-									root,
-									"tasks",
-									target.taskId!,
-									"phases",
-									target.phaseId,
-									"PHASE.md",
-								),
-								PhaseFrontmatter,
-							)
+						? yield* readDocument(target.phaseId, target.path, PhaseFrontmatter)
 						: null
 					const epicId =
 						target.epicId ??
@@ -361,7 +414,11 @@ export class ContextService extends Effect.Service<ContextService>()(
 					const epic = epicId
 						? yield* readOptionalDocument(
 								epicId,
-								join(root, "epics", epicId, "EPIC.md"),
+								target.kind === "epic"
+									? target.path
+									: (yield* fs.exists(join(root, "epics", epicId, "EPIC.md")))
+										? join(root, "epics", epicId, "EPIC.md")
+										: join(archivedEpicDirectory(root, epicId), "EPIC.md"),
 								EpicFrontmatter,
 							)
 						: null
@@ -374,8 +431,11 @@ export class ContextService extends Effect.Service<ContextService>()(
 
 					const taskDocuments = new Map<string, Document<TaskData>>()
 					const phaseDocuments = new Map<string, Document<PhaseData>>()
-					const taskRoot = join(root, "tasks")
-					if (yield* fs.isDirectory(taskRoot)) {
+					for (const taskRoot of [
+						join(root, "tasks"),
+						join(root, "archive", "tasks"),
+					]) {
+						if (!(yield* fs.isDirectory(taskRoot))) continue
 						const entries = (yield* fs.readDirectory(taskRoot))
 							.filter((entry) => entry.isDirectory)
 							.sort((a, b) => a.name.localeCompare(b.name))
@@ -455,14 +515,18 @@ export class ContextService extends Effect.Service<ContextService>()(
 							{ concurrency: "unbounded" },
 						)
 						for (const document of documents) {
-							if (document.taskDocument) {
+							if (
+								document.taskDocument &&
+								!taskDocuments.has(document.taskDocument.id)
+							) {
 								taskDocuments.set(
 									document.taskDocument.id,
 									document.taskDocument,
 								)
 							}
 							for (const [key, phaseDocument] of document.phaseDocuments) {
-								phaseDocuments.set(key, phaseDocument)
+								if (!phaseDocuments.has(key))
+									phaseDocuments.set(key, phaseDocument)
 							}
 						}
 					}
@@ -751,6 +815,18 @@ export class ContextService extends Effect.Service<ContextService>()(
 					const orchestrationTarget =
 						target.kind === "epic" ||
 						(target.kind === "task" && task !== null && "phases" in task.data)
+					if (target.archived) {
+						blockers.push({
+							kind: "status",
+							id:
+								target.phaseId ??
+								target.taskId ??
+								target.epicId ??
+								suppliedTarget,
+							reason:
+								"Target is archived; restore it before mutation or execution",
+						})
+					}
 					if (!orchestrationTarget && targetStatus !== "open") {
 						blockers.push({
 							kind: "status",
@@ -773,17 +849,22 @@ export class ContextService extends Effect.Service<ContextService>()(
 						})
 					}
 					const ready = orchestrationTarget
-						? descendantsReady &&
+						? !target.archived &&
+							descendantsReady &&
 							!blockers.some((blocker) => blocker.kind === "validation")
 						: targetStatus === "open" && blockers.length === 0
 
-					const executionData: ExecutionData | null = phase?.data
-						? phase.data
-						: task?.data && "repo" in task.data
-							? (task.data as ExecutionData)
-							: null
+					const executionData: ExecutionData | null = target.archived
+						? null
+						: phase?.data
+							? phase.data
+							: task?.data && "repo" in task.data
+								? (task.data as ExecutionData)
+								: null
 					const reviewData =
-						task?.data && "review" in task.data ? task.data.review : null
+						!target.archived && task?.data && "review" in task.data
+							? task.data.review
+							: null
 					const writableDocuments = reviewData
 						? task
 							? [task.path]
@@ -793,11 +874,13 @@ export class ContextService extends Effect.Service<ContextService>()(
 								? [task.path, phase.path]
 								: [task.path]
 							: []
-					const references: readonly RepositoryReference[] = reviewData
-						? [{ repo: reviewData.repo, ref: reviewData.commit }]
-						: executionData
-							? (executionData.repos ?? [])
-							: (epic?.data.repos ?? [])
+					const references: readonly RepositoryReference[] = target.archived
+						? []
+						: reviewData
+							? [{ repo: reviewData.repo, ref: reviewData.commit }]
+							: executionData
+								? (executionData.repos ?? [])
+								: (epic?.data.repos ?? [])
 					const entityDirectory = target.path.replace(
 						/\/(?:EPIC|TASK|PHASE)\.md$/,
 						"",
@@ -1035,6 +1118,9 @@ export class ContextService extends Effect.Service<ContextService>()(
 									}
 								: document
 							: null
+					const pullRequestData =
+						phase?.data ??
+						(task?.data && "repo" in task.data ? task.data : null)
 
 					return {
 						projection: options.compact ? "compact" : "complete",
@@ -1124,8 +1210,8 @@ export class ContextService extends Effect.Service<ContextService>()(
 									checkout: referenceCheckouts[0] ?? null,
 								}
 							: null,
-						pr: executionData?.pr
-							? normalizePullRequestRecord(executionData.pr)
+						pr: pullRequestData?.pr
+							? normalizePullRequestRecord(pullRequestData.pr)
 							: { url: null, state: "none" },
 						validation: {
 							valid: validation.valid,