@markjaquith/agency 2.11.0 → 2.13.0

package/README.md

@@ -262,9 +262,10 @@ Nodes use stable IDs (`epic:<id>`, `task:<id>`, `phase:<task>/<phase>`,
 `repository:<alias>`, and `execution-unit:<kind>/<id>`). Typed edges are `owns`,
 `depends_on`, `writes`, and `references`.
 
-Every work node includes status, readiness, blockers, reverse dependents, and
-aggregate progress. Only `done` satisfies a dependency. The graph summary counts
-the statuses of all execution units, independent of filters.
+Every work node includes status, readiness, `blockedBy`, detailed blockers,
+terminal state, reverse dependents, and aggregate progress. Only `done` satisfies
+a dependency; `dropped` is terminal but does not satisfy dependents. The graph
+summary counts the statuses of all execution units, independent of filters.
 
 ```text
 agency graph [--json | --jsonl] [--ready | --blocked]
@@ -390,7 +391,9 @@ 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 the status subcommands to mark work `delegated`, `done`,
 `dropped`, or open it again. The interactive work selector displays status
-markers before execution units.
+markers before execution units. Open, working, and delegated work may transition
+to any status. Done and dropped work are terminal and may only remain unchanged
+or transition to open; reopen terminal work before changing its outcome.
 
 ### Archive
 
@@ -409,6 +412,7 @@ before moving files, refuses dirty worktrees, and preserves branches.
 
 ```text
 agency work [<directory> | --epic <epic-id>] [--opencode | --claude]
+agency work prepare [target] [--dry-run] [--json]
 agency pr create <task-id> [phase-id] [--draft] [--json]
 ```
 
@@ -418,6 +422,12 @@ workbase, Agency first presents the registered workbases, then the selected
 workbase's hierarchy. If `fzf` is not installed, Agency prints the available
 choices and asks for an explicit directory.
 
+`agency work prepare` resolves an execution unit and creates or reuses its
+writable and reference worktrees without launching an agent or changing status.
+Its JSON result includes document and checkout paths, resolved commits, actions,
+and Git operations. Use `--dry-run` to report planned fetch, branch, and worktree
+changes without applying them.
+
 Epic and multi-phase task targets launch orchestration agents beside their
 documents. Single-phase tasks and phases fetch repositories, create or reuse
 worktrees under `code/`, and launch an execution agent in the writable checkout

package/cli.ts

@@ -5,7 +5,7 @@ import { parseCli } from "./src/cli-parser"
 import { init, help as initHelp } from "./src/commands/init"
 import { task, help as taskHelp } from "./src/commands/task"
 import { pr, help as prHelp } from "./src/commands/pr"
-import { work, help as workHelp } from "./src/commands/work"
+import { work, workPrepare, help as workHelp } from "./src/commands/work"
 import { status, help as statusHelp } from "./src/commands/status"
 import { validate, help as validateHelp } from "./src/commands/validate"
 import { context, help as contextHelp } from "./src/commands/context"
@@ -274,10 +274,13 @@ const commands: Record<string, Command> = {
 				console.log(workHelp)
 				return
 			}
+			const preparing = args[0] === "prepare"
 			await runCommand(
-				work({
-					directory: args[0],
+				(preparing ? workPrepare : work)({
+					directory: args[preparing ? 1 : 0],
 					epicId: options.epic,
+					json: options.json,
+					dryRun: options["dry-run"],
 					silent: options.silent,
 					verbose: options.verbose,
 					opencode: options.opencode,

package/index.ts

@@ -1,3 +1,4 @@
 export * from "./src/workbase/schemas"
 export * from "./src/protocol"
 export * from "./src/graph-schema"
+export * from "./src/readiness"

package/package.json

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

package/schemas/agency-graph-v1.schema.json

@@ -125,10 +125,15 @@
     "readiness": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["ready", "blocked", "blockers"],
+      "required": ["ready", "blocked", "blockedBy", "terminal", "blockers"],
       "properties": {
         "ready": { "type": "boolean" },
         "blocked": { "type": "boolean" },
+        "blockedBy": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "terminal": { "type": "boolean" },
         "blockers": {
           "type": "array",
           "items": { "$ref": "#/$defs/blocker" }

package/src/cli-parser.test.ts

@@ -155,6 +155,22 @@ describe("strict CLI parsing", () => {
 		expectUsageError(["status", "--compact"], "agency status")
 	})
 
+	test("accepts work preparation options only for the prepare subcommand", () => {
+		expect(
+			parseCli(["work", "prepare", "tasks/example", "--dry-run", "--json"]),
+		).toMatchObject({
+			commandName: "work",
+			args: ["prepare", "tasks/example"],
+			values: { "dry-run": true, json: true },
+		})
+		expect(() => parseCli(["work", "example", "--dry-run"])).toThrow(
+			"only valid with 'agency work prepare'",
+		)
+		expect(() => parseCli(["work", "prepare", "--opencode"])).toThrow(
+			"cannot be combined",
+		)
+	})
+
 	test("accepts repeatable graph filters and rejects output conflicts", () => {
 		expect(
 			parseCli([

package/src/cli-parser.ts

@@ -283,18 +283,22 @@ const commands = {
 		},
 	},
 	work: {
-		usage: "agency work [<directory-or-task-id> | --epic <epic-id>]",
+		usage:
+			"agency work [<directory-or-task-id> | --epic <epic-id>] | agency work prepare [target] [--dry-run] [--json]",
 		options: {
 			...commonOptions,
+			json: { type: "boolean" },
+			"dry-run": { type: "boolean" },
 			epic: { type: "string" },
 			opencode: { type: "boolean" },
 			claude: { type: "boolean" },
 		},
 		command: {
-			usage: "agency work [<directory-or-task-id> | --epic <epic-id>]",
+			usage:
+				"agency work [<directory-or-task-id> | --epic <epic-id>] | agency work prepare [target] [--dry-run] [--json]",
 			minArgs: 0,
-			maxArgs: 1,
-			options: ["epic", "opencode", "claude"],
+			maxArgs: 2,
+			options: ["json", "dry-run", "epic", "opencode", "claude"],
 			conflicts: [
 				["opencode", "claude"],
 				["epic", "$positional"],
@@ -649,6 +653,27 @@ export function parseCli(args: readonly string[]): ParsedCli {
 	if (commandName === "graph") {
 		validateGraphOptions(parsed.values, spec)
 	}
+	if (commandName === "work") {
+		const preparing = commandPositionals[0] === "prepare"
+		if (
+			(!preparing && commandPositionals.length > 1) ||
+			(preparing &&
+				(parsed.values.epic || parsed.values.opencode || parsed.values.claude))
+		) {
+			throw usageError(
+				preparing
+					? "Work preparation cannot be combined with agent or epic options."
+					: "The work command accepts at most one target.",
+				spec.usage,
+			)
+		}
+		if (!preparing && (parsed.values.json || parsed.values["dry-run"])) {
+			throw usageError(
+				"Options '--json' and '--dry-run' are only valid with 'agency work prepare'.",
+				spec.usage,
+			)
+		}
+	}
 
 	return {
 		commandName: commandName as keyof typeof commands,

package/src/cli.test.ts

@@ -301,6 +301,76 @@ status: open
 		})
 	})
 
+	test("prepares a workspace and reports a non-mutating dry-run", async () => {
+		const parent = await createTempDir()
+		tempDirs.push(parent)
+		const root = join(parent, "workbase")
+		const source = join(parent, "source")
+		expect(
+			Bun.spawnSync(["git", "init", "--initial-branch=main", source]).exitCode,
+		).toBe(0)
+		await Bun.write(join(source, "README.md"), "example\n")
+		for (const args of [
+			["config", "user.email", "test@example.com"],
+			["config", "user.name", "Test"],
+			["add", "README.md"],
+			["-c", "commit.gpgsign=false", "commit", "-m", "initial"],
+		]) {
+			expect(Bun.spawnSync(["git", "-C", source, ...args]).exitCode).toBe(0)
+		}
+
+		parseJson(await runCli(["init", root, "--json"], parent))
+		parseJson(await runCli(["repo", "link", "agency", source, "--json"], root))
+		parseJson(
+			await runCli(
+				[
+					"task",
+					"create",
+					"example",
+					"--repo",
+					"agency",
+					"--branch",
+					"feat/example",
+					"--base",
+					"main",
+					"--json",
+				],
+				root,
+			),
+		)
+
+		const planned = parseJson(
+			await runCli(["work", "prepare", "example", "--dry-run", "--json"], root),
+		)
+		const workbaseRoot = await realpath(root)
+		expect(planned).toMatchObject({
+			dryRun: true,
+			taskPath: join(workbaseRoot, "tasks/example/TASK.md"),
+			phasePath: null,
+			checkouts: [
+				{
+					repo: "agency",
+					kind: "writable",
+					action: "created",
+					resolvedCommit: expect.stringMatching(/^[0-9a-f]{40}$/),
+				},
+			],
+		})
+		await expect(access(join(root, "tasks/example/code"))).rejects.toThrow()
+
+		const prepared = parseJson(
+			await runCli(["work", "prepare", "example", "--json"], root),
+		)
+		expect(prepared).toMatchObject({
+			dryRun: false,
+			checkouts: [{ action: "created", kind: "writable" }],
+		})
+		const task = parseJson(
+			await runCli(["task", "show", "example", "--json"], root),
+		)
+		expect(task.data.status).toBe("open")
+	})
+
 	test("envelopes help and version output in machine mode", async () => {
 		const help = await runCli(["status", "--help", "--json"])
 		expect(parseJson(help)).toContain("Usage: agency status")

package/src/commands/work.test.ts

@@ -7,7 +7,7 @@ import { TaskService } from "../services/TaskService"
 import { PhaseService } from "../services/PhaseService"
 import { WorktreeService } from "../services/WorktreeService"
 import { captureErrors, captureLogs } from "../test-utils"
-import { work } from "./work"
+import { work, workPrepare } from "./work"
 import type { PickWorkTarget } from "../workbase/work-target"
 import type { PickWorkbase } from "../workbase/workbase-choice"
 import type { Progress } from "../utils/progress"
@@ -24,6 +24,9 @@ const singlePhaseWorkspace: ExecutionWorkspace = {
 	writablePath: "/workbase/tasks/example/code/agency",
 	repo: "agency",
 	repos: [],
+	dryRun: false,
+	checkouts: [],
+	operations: [],
 }
 
 const multiPhaseWorkspace: ExecutionWorkspace = {
@@ -34,6 +37,9 @@ const multiPhaseWorkspace: ExecutionWorkspace = {
 	writablePath: "/workbase/tasks/example/phases/implementation/code/agency",
 	repo: "agency",
 	repos: [],
+	dryRun: false,
+	checkouts: [],
+	operations: [],
 }
 
 interface HarnessOptions {
@@ -167,6 +173,16 @@ const createHarness = (options: HarnessOptions = {}) => {
 				Effect.provideService(PhaseService, phases as never),
 			) as Effect.Effect<void, unknown, never>,
 		)
+	const runPrepare = (commandOptions: Parameters<typeof workPrepare>[0]) =>
+		Effect.runPromise(
+			workPrepare(commandOptions).pipe(
+				Effect.provideService(WorktreeService, worktrees as never),
+				Effect.provideService(FileSystemService, fs as never),
+				Effect.provideService(WorkbaseService, workbase as never),
+				Effect.provideService(TaskService, tasks as never),
+				Effect.provideService(PhaseService, phases as never),
+			) as Effect.Effect<void, unknown, never>,
+		)
 
 	return {
 		events,
@@ -177,10 +193,32 @@ const createHarness = (options: HarnessOptions = {}) => {
 		shownTasks,
 		progressUpdates,
 		run,
+		runPrepare,
 	}
 }
 
 describe("work command", () => {
+	test("prepares without launching or changing lifecycle status", async () => {
+		const harness = createHarness({ existingDirectories: [] })
+
+		await captureLogs(() =>
+			harness.runPrepare({
+				cwd: "/workbase",
+				directory: "example",
+				json: true,
+				dryRun: true,
+			}),
+		)
+
+		expect(harness.events).toEqual(["materialize"])
+		expect(harness.launches).toEqual([])
+		expect(harness.statusUpdates).toEqual([])
+		expect(harness.materializeOptions[0]).toMatchObject({
+			json: true,
+			dryRun: true,
+		})
+	})
+
 	test("launches an epic agent from an epic directory", async () => {
 		const harness = createHarness()
 

package/src/commands/work.ts

@@ -243,14 +243,74 @@ export const work = (
 		launch(cli, [cli, ...args], launchPath)
 	})
 
+export const workPrepare = (options: WorkOptions = {}) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const workbase = yield* WorkbaseService
+		const tasks = yield* TaskService
+		const phases = yield* PhaseService
+		const worktrees = yield* WorktreeService
+		const { log } = createLoggers(options)
+		const cwd = options.cwd ?? process.cwd()
+		const targetPath = options.directory ? resolve(cwd, options.directory) : cwd
+		const isDirectory = yield* fs.isDirectory(targetPath)
+		const root = yield* workbase.discover(isDirectory ? targetPath : cwd)
+
+		let taskId: string | undefined
+		let phaseId: string | undefined
+		if (options.directory && !isDirectory) {
+			const task = yield* tasks.show(options.directory, root)
+			taskId = task.id
+		} else {
+			const path = relative(root, targetPath)
+			const parts =
+				!path || isAbsolute(path) || path.startsWith(`..${sep}`)
+					? []
+					: path.split(sep)
+			if (parts[0] === "tasks" && parts[1]) {
+				const task = yield* tasks.show(parts[1], root)
+				taskId = task.id
+				if (parts[2] === "phases" && parts[3]) {
+					const phase = yield* phases.show(task.id, parts[3], root)
+					phaseId = phase.id
+				}
+			}
+		}
+
+		if (!taskId) {
+			return yield* Effect.fail(
+				new Error(
+					"Work preparation requires a task ID or a path inside an execution unit",
+				),
+			)
+		}
+
+		const workspace = yield* worktrees.materialize(taskId, phaseId, root, {
+			...options,
+			dryRun: options.dryRun,
+		})
+		if (options.json) {
+			log(JSON.stringify(workspace, null, 2))
+		} else {
+			log(
+				`${workspace.dryRun ? "Workspace plan" : "Workspace ready"}: ${workspace.writablePath}`,
+			)
+		}
+	})
+
 export const help = `
 Usage: agency work [<directory-or-task-id> | --epic <epic-id>]
+       agency work prepare [target] [--dry-run] [--json]
 
 Launch an agent for an epic, task, or phase. With no directory, select one
 with fzf. A positional argument resolves as a directory first, then as a task
 ID. Use '.' for the current directory. Outside a workbase, select a registered
 workbase first.
 
+The prepare subcommand resolves and materializes an execution workspace without
+launching an agent or changing lifecycle status. --dry-run reports planned Git
+changes without fetching, creating branches, or creating worktrees.
+
 Options:
   --epic <id>         Work on an epic
   --opencode           Require OpenCode

package/src/graph-schema.test.ts

@@ -14,6 +14,13 @@ describe("graph contract", () => {
 			required: ["ready", "blocked", "statuses", "repositories", "kinds"],
 		})
 		expect(jsonSchema.$defs.node.allOf).toHaveLength(5)
+		expect(jsonSchema.$defs.readiness.required).toEqual([
+			"ready",
+			"blocked",
+			"blockedBy",
+			"terminal",
+			"blockers",
+		])
 		expect(jsonSchema.$defs.node.allOf[3]?.then?.properties).toMatchObject({
 			status: { type: "null" },
 			readiness: { type: "null" },

package/src/graph-schema.ts

@@ -46,6 +46,8 @@ export const GraphProgress = Schema.Struct({
 export const GraphReadiness = Schema.Struct({
 	ready: Schema.Boolean,
 	blocked: Schema.Boolean,
+	blockedBy: Schema.Array(Schema.String),
+	terminal: Schema.Boolean,
 	blockers: Schema.Array(GraphBlocker),
 })
 

package/src/readiness.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, test } from "bun:test"
+import {
+	aggregateProgress,
+	canTransitionStatus,
+	isDependencySatisfied,
+	readinessState,
+} from "./readiness"
+
+describe("readiness model", () => {
+	test("only done satisfies dependencies and terminal states remain distinct", () => {
+		expect(isDependencySatisfied("done")).toBe(true)
+		expect(isDependencySatisfied("dropped")).toBe(false)
+		expect(readinessState("done", [{ id: "task:one" }])).toEqual({
+			ready: false,
+			blocked: true,
+			blockedBy: ["task:one"],
+			terminal: true,
+		})
+		expect(readinessState("working", [{ id: "claim:self" }])).toEqual({
+			ready: false,
+			blocked: true,
+			blockedBy: ["claim:self"],
+			terminal: false,
+		})
+	})
+
+	test("rolls child statuses into deterministic aggregate progress", () => {
+		expect(aggregateProgress(["done", "dropped"])).toEqual({
+			status: "dropped",
+			total: 2,
+			open: 0,
+			working: 0,
+			delegated: 0,
+			done: 1,
+			dropped: 1,
+			terminal: 2,
+		})
+	})
+
+	test("requires terminal work to reopen before changing its outcome", () => {
+		expect(canTransitionStatus("open", "done")).toBe(true)
+		expect(canTransitionStatus("working", "delegated")).toBe(true)
+		expect(canTransitionStatus("done", "dropped")).toBe(false)
+		expect(canTransitionStatus("dropped", "done")).toBe(false)
+		expect(canTransitionStatus("done", "open")).toBe(true)
+	})
+})

package/src/readiness.ts

@@ -0,0 +1,58 @@
+import type { WorkStatus } from "./workbase/schemas"
+
+export interface ReadinessBlocker {
+	readonly id: string
+}
+
+export const WORK_STATUS_TRANSITIONS = {
+	open: ["open", "working", "delegated", "done", "dropped"],
+	working: ["open", "working", "delegated", "done", "dropped"],
+	delegated: ["open", "working", "delegated", "done", "dropped"],
+	done: ["open", "done"],
+	dropped: ["open", "dropped"],
+} as const satisfies Record<WorkStatus, readonly WorkStatus[]>
+
+export const isTerminalStatus = (status: WorkStatus) =>
+	status === "done" || status === "dropped"
+
+export const isDependencySatisfied = (status: WorkStatus | undefined) =>
+	status === "done"
+
+export const canTransitionStatus = (from: WorkStatus, to: WorkStatus) =>
+	(WORK_STATUS_TRANSITIONS[from] as readonly WorkStatus[]).includes(to)
+
+export const aggregateProgress = (statuses: readonly WorkStatus[]) => {
+	const counts = {
+		total: statuses.length,
+		open: statuses.filter((status) => status === "open").length,
+		working: statuses.filter((status) => status === "working").length,
+		delegated: statuses.filter((status) => status === "delegated").length,
+		done: statuses.filter((status) => status === "done").length,
+		dropped: statuses.filter((status) => status === "dropped").length,
+		terminal: statuses.filter(isTerminalStatus).length,
+	}
+	const status: WorkStatus =
+		statuses.length === 0
+			? "open"
+			: statuses.every((value) => value === "done")
+				? "done"
+				: statuses.every(isTerminalStatus)
+					? "dropped"
+					: statuses.includes("working")
+						? "working"
+						: statuses.includes("delegated")
+							? "delegated"
+							: "open"
+	return { status, ...counts }
+}
+
+export const readinessState = (
+	status: WorkStatus,
+	blockers: readonly ReadinessBlocker[],
+	ready = status === "open" && blockers.length === 0,
+) => ({
+	ready,
+	blocked: !ready && blockers.length > 0,
+	blockedBy: [...new Set(blockers.map((blocker) => blocker.id))].sort(),
+	terminal: isTerminalStatus(status),
+})

package/src/services/ContextService.ts

@@ -4,6 +4,7 @@ import { join, relative, resolve, sep } from "node:path"
 import { FileSystemService } from "./FileSystemService"
 import { WorkbaseService } from "./WorkbaseService"
 import { RepositoryService } from "./RepositoryService"
+import { aggregateProgress, readinessState } from "../readiness"
 import { parseFrontmatter } from "../workbase/frontmatter"
 import {
 	EpicFrontmatter,
@@ -63,29 +64,6 @@ interface ReferenceCheckout extends CheckoutInspection {
 	readonly resolvedCommit: string | null
 }
 
-const statusCounts = (statuses: readonly WorkStatus[]) => ({
-	total: statuses.length,
-	open: statuses.filter((status) => status === "open").length,
-	working: statuses.filter((status) => status === "working").length,
-	delegated: statuses.filter((status) => status === "delegated").length,
-	done: statuses.filter((status) => status === "done").length,
-	dropped: statuses.filter((status) => status === "dropped").length,
-	terminal: statuses.filter(
-		(status) => status === "done" || status === "dropped",
-	).length,
-})
-
-const aggregateStatus = (statuses: readonly WorkStatus[]): WorkStatus => {
-	if (statuses.length === 0) return "open"
-	if (statuses.every((status) => status === "done")) return "done"
-	if (statuses.every((status) => status === "done" || status === "dropped")) {
-		return "dropped"
-	}
-	if (statuses.includes("working")) return "working"
-	if (statuses.includes("delegated")) return "delegated"
-	return "open"
-}
-
 const decode = <S extends Schema.Schema.AnyNoContext>(
 	schema: S,
 	input: unknown,
@@ -337,13 +315,13 @@ export class ContextService extends Effect.Service<ContextService>()(
 							return (record.data as PhaseData).status
 						const data = record.data as TaskData
 						if (!("phases" in data)) return data.status
-						return aggregateStatus(
+						return aggregateProgress(
 							data.phases.map(
 								(item) =>
 									phaseDocuments.get(`${record.taskId}/${item.id}`)?.data
 										.status ?? "open",
 							),
-						)
+						).status
 					}
 
 					const taskDependencyEntries = (
@@ -551,7 +529,7 @@ export class ContextService extends Effect.Service<ContextService>()(
 									)
 								: [child.data.status]
 						})
-						targetStatus = aggregateStatus(aggregateStatuses)
+						targetStatus = aggregateProgress(aggregateStatuses).status
 						descendantsReady = epic.data.tasks.some((item: Dependency) =>
 							taskReady(item.id),
 						)
@@ -832,14 +810,10 @@ export class ContextService extends Effect.Service<ContextService>()(
 							dependencies,
 							dependents,
 							readiness: {
-								ready,
-								blocked: !ready && blockers.length > 0,
+								...readinessState(targetStatus, blockers, ready),
 								blockers,
 							},
-							aggregate: {
-								status: aggregateStatus(aggregateStatuses),
-								...statusCounts(aggregateStatuses),
-							},
+							aggregate: aggregateProgress(aggregateStatuses),
 						},
 						authority: {
 							mode: executionData ? "execution" : "orchestration",