@markjaquith/agency 2.61.2 → 2.62.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
@@ -527,6 +546,12 @@ and reference authority, local checkout and resolved-commit state, recorded PR
 state, and validation warnings. Only `done` satisfies a dependency; `dropped` is
 terminal but remains a blocker.
 
+`authority.writable` identifies the writable repository checkout, while
+`authority.documents.writable` lists the absolute paths of Agency documents the
+target may maintain. A single-phase task lists its `TASK.md`; a phase lists its
+owning `TASK.md` and active `PHASE.md`; orchestration targets list none. Use
+Agency commands rather than direct edits for structural frontmatter mutations.
+
 Complete output is the default for entity targets. Pass `--compact` explicitly
 to omit document prose and low-level Git details while retaining identity,
 hashes, authority, paths, graph state, materialization state, and validation

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.2",
+  "version": "2.62.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

@@ -208,6 +208,10 @@ Phase prose.
 		expect(result.documents.task.body).toContain("Task prose.")
 		expect(result.documents.phase.body).toContain("Phase prose.")
 		expect(result.documents.phase.sha256).toMatch(/^[a-f0-9]{64}$/)
+		expect(result.authority.documents.writable).toEqual([
+			join(root, "tasks/agent-contract/TASK.md"),
+			join(root, "tasks/agent-contract/phases/context-command/PHASE.md"),
+		])
 		expect(result.workspace.writable.branchCommit).toMatch(/^[a-f0-9]{40}$/)
 		expect(result.workspace.writable.baseCommit).toMatch(/^[a-f0-9]{40}$/)
 		expect(result.workspace.references[0].resolvedCommit).toMatch(
@@ -232,6 +236,10 @@ Phase prose.
 			registered: true,
 		})
 		expect(result.authority.writable.checkoutPath).toContain("code/agency")
+		expect(result.authority.documents.writable).toEqual([
+			join(root, "tasks/agent-contract/TASK.md"),
+			join(root, "tasks/agent-contract/phases/context-command/PHASE.md"),
+		])
 	})
 
 	test("reports dependency and validation blockers deterministically", async () => {
@@ -275,6 +283,12 @@ status: dropped
 			taskId: "agent-contract",
 		})
 		expect(task.graph.parent).toEqual({ kind: "epic", id: "contract" })
+		expect(task.authority.documents.writable).toEqual([])
+
+		const executionTask = await readContext(root, "foundations")
+		expect(executionTask.authority.documents.writable).toEqual([
+			join(root, "tasks/foundations/TASK.md"),
+		])
 
 		const workbase = await readContext(root, ".")
 		expect(workbase).toMatchObject({

package/src/services/ContextService.ts

@@ -784,6 +784,15 @@ export class ContextService extends Effect.Service<ContextService>()(
 							: null
 					const reviewData =
 						task?.data && "review" in task.data ? task.data.review : null
+					const writableDocuments = reviewData
+						? task
+							? [task.path]
+							: []
+						: executionData && task
+							? phase
+								? [task.path, phase.path]
+								: [task.path]
+							: []
 					const references: readonly RepositoryReference[] = reviewData
 						? [{ repo: reviewData.repo, ref: reviewData.commit }]
 						: executionData
@@ -1078,7 +1087,7 @@ export class ContextService extends Effect.Service<ContextService>()(
 								checkoutPath: reference.checkoutPath,
 							})),
 							documents: {
-								writable: reviewData && task ? [task.path] : [],
+								writable: writableDocuments,
 							},
 						},
 						workspace: options.compact

package/src/services/IntegrationService.test.ts

@@ -418,6 +418,7 @@ describe("IntegrationService", () => {
 		expect(body).toContain("agency next --json")
 		expect(body).toContain("agency <command> --help")
 		expect(body).toContain("authority.writable.checkoutPath")
+		expect(body).toContain("authority.documents.writable")
 		expect(body).toContain("Only `done` satisfies a dependency")
 		expect(body).toContain("Require explicit user intent")
 		expect(body).toContain(

package/src/workbase/AGENTS.md

@@ -48,10 +48,11 @@ agency validate --json
 - A single-phase task or phase is an execution unit with one writable `repo` and
   optional read-only `repos`. Only `done` satisfies a dependency; `dropped` is
   terminal but leaves dependents blocked.
-- For an execution unit, write code only at
+- For an execution unit, write repository content only at
   `authority.writable.checkoutPath`. Every `authority.references` checkout is
   read-only, even if filesystem permissions allow writes.
-- Keep task-wide decisions in `TASK.md` and phase-specific delivery context in
+- Maintain only the Agency documents listed in `authority.documents.writable`:
+  keep task-wide decisions in `TASK.md` and phase-specific delivery context in
   `PHASE.md`. Use Agency commands for structural frontmatter mutations.
 
 ## Consent Boundaries