@markjaquith/agency 2.16.0 → 2.17.0

package/README.md

@@ -304,6 +304,21 @@ inspection are opt-in include layers.
 `end` record with counts. Combining the metadata with the streamed node and edge
 records reconstructs the same result as `--json`.
 
+### Next Ready Work
+
+`agency next` lists ready execution units in descending unlock priority, with
+their epic and task context. `agency next --select` returns only the highest-
+priority ready unit in human output.
+
+`agency next --json` returns the same ranked `ready` set plus every `excluded`
+execution unit. Excluded entries retain status, terminal state, `blockedBy`, and
+detailed dependency, validation, or status blockers for orchestrators.
+
+`agency work` and `agency pr create` consult this shared readiness model before
+materializing or pushing. Blocked, done, and dropped targets are rejected unless
+`--force` is supplied explicitly. PR creation permits active `working` and
+`delegated` targets when they have no dependency or validation blocker.
+
 ### Reconciliation
 
 `agency sync` compares every execution declaration with local branch and worktree

package/cli.ts

@@ -10,6 +10,7 @@ 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"
 import { graph, help as graphHelp } from "./src/commands/graph"
+import { next, help as nextHelp } from "./src/commands/next"
 import { sync, help as syncHelp } from "./src/commands/sync"
 import { repo, help as repoHelp } from "./src/commands/repo"
 import { epic, help as epicHelp } from "./src/commands/epic"
@@ -35,6 +36,7 @@ import { ContextService } from "./src/services/ContextService"
 import { GraphService } from "./src/services/GraphService"
 import { ClaimService } from "./src/services/ClaimService"
 import { SyncService } from "./src/services/SyncService"
+import { ReadinessService } from "./src/services/ReadinessService"
 import {
 	claimCommand,
 	claimHelp,
@@ -64,6 +66,7 @@ const CliLayer = Layer.mergeAll(
 	GraphService.Default,
 	ClaimService.Default,
 	SyncService.Default,
+	ReadinessService.Default,
 )
 
 /**
@@ -213,6 +216,7 @@ const commands: Record<string, Command> = {
 					taskId: args[1],
 					phaseId: args[2],
 					draft: options.draft,
+					force: options.force,
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
@@ -351,11 +355,25 @@ const commands: Record<string, Command> = {
 					verbose: options.verbose,
 					opencode: options.opencode,
 					claude: options.claude,
+					force: options.force,
 					inputAllowed: options.inputAllowed,
 				}),
 			)
 		},
 	},
+	next: {
+		run: async (_args: string[], options: Record<string, any>) => {
+			if (options.help) return console.log(nextHelp)
+			await runCommand(
+				next({
+					select: options.select,
+					json: options.json,
+					silent: options.silent,
+					verbose: options.verbose,
+				}),
+			)
+		},
+	},
 	status: {
 		run: async (_args: string[], options: Record<string, any>) => {
 			if (options.help) {
@@ -464,6 +482,7 @@ Commands:
   archive <type>         Archive a work item
   task <subcommand>      Manage tasks
   work [directory|task]  Work on an epic, task, or phase
+  next                   List or select ready execution units
   pr create              Create a pull request for an execution unit
   repo <subcommand>      Manage workbase repositories
   status                 Show status for the current workbase

package/package.json

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

package/src/cli-parser.test.ts

@@ -141,6 +141,7 @@ describe("strict CLI parsing", () => {
 			[["validate", "one", "two"], "agency validate"],
 			[["context", "one", "two"], "agency context"],
 			[["graph", "extra"], "agency graph"],
+			[["next", "extra"], "agency next"],
 			[["sync", "extra"], "agency sync"],
 			[
 				[
@@ -192,6 +193,24 @@ describe("strict CLI parsing", () => {
 		}
 	})
 
+	test("parses readiness selection and explicit guard overrides", () => {
+		expect(parseCli(["next", "--select", "--json"])).toMatchObject({
+			commandName: "next",
+			values: { select: true, json: true },
+		})
+		expect(parseCli(["work", "example", "--force"])).toMatchObject({
+			commandName: "work",
+			values: { force: true },
+		})
+		expect(parseCli(["pr", "create", "example", "--force"])).toMatchObject({
+			commandName: "pr",
+			values: { force: true },
+		})
+		expect(() => parseCli(["work", "prepare", "example", "--force"])).toThrow(
+			"cannot be combined",
+		)
+	})
+
 	test("parses reconciliation modes and rejects conflicting modes", () => {
 		expect(parseCli(["sync", "--dry-run", "--json"])).toMatchObject({
 			commandName: "sync",

package/src/cli-parser.ts

@@ -368,13 +368,14 @@ const commands = {
 			epic: { type: "string" },
 			opencode: { type: "boolean" },
 			claude: { type: "boolean" },
+			force: { type: "boolean" },
 		},
 		command: {
 			usage:
 				"agency work [<directory-or-task-id> | --epic <epic-id>] | agency work prepare [target] [--dry-run] [--json]",
 			minArgs: 0,
 			maxArgs: 2,
-			options: ["json", "dry-run", "epic", "opencode", "claude"],
+			options: ["json", "dry-run", "epic", "opencode", "claude", "force"],
 			conflicts: [
 				["opencode", "claude"],
 				["epic", "$positional"],
@@ -386,16 +387,31 @@ const commands = {
 		options: {
 			...outputOptions,
 			draft: { type: "boolean" },
+			force: { type: "boolean" },
 		},
 		subcommands: {
 			create: {
-				usage: "agency pr create <task-id> [phase-id] [--draft] [--json]",
+				usage:
+					"agency pr create <task-id> [phase-id] [--draft] [--force] [--json]",
 				minArgs: 1,
 				maxArgs: 2,
-				options: ["draft", "json"],
+				options: ["draft", "force", "json"],
 			},
 		},
 	},
+	next: {
+		usage: "agency next [--select] [--json]",
+		options: {
+			...outputOptions,
+			select: { type: "boolean" },
+		},
+		command: {
+			usage: "agency next [--select] [--json]",
+			minArgs: 0,
+			maxArgs: 0,
+			options: ["select", "json"],
+		},
+	},
 	status: {
 		usage: "agency status [--json]",
 		options: outputOptions,
@@ -744,7 +760,10 @@ export function parseCli(args: readonly string[]): ParsedCli {
 		if (
 			(!preparing && commandPositionals.length > 1) ||
 			(preparing &&
-				(parsed.values.epic || parsed.values.opencode || parsed.values.claude))
+				(parsed.values.epic ||
+					parsed.values.opencode ||
+					parsed.values.claude ||
+					parsed.values.force))
 		) {
 			throw usageError(
 				preparing

package/src/cli.test.ts

@@ -245,6 +245,7 @@ describe("CLI", () => {
 			["validate", "Usage: agency validate"],
 			["context", "Usage: agency context"],
 			["graph", "Usage: agency graph"],
+			["next", "Usage: agency next"],
 		] as const) {
 			const result = await runCli([command, "--help"])
 			expect(result.exitCode).toBe(0)
@@ -264,6 +265,55 @@ describe("CLI", () => {
 
 		const after = await runCli(["status", "--silent"], root)
 		expect(after).toEqual({ exitCode: 0, stdout: "", stderr: "" })
+	}, 10_000)
+
+	test("lists ready work and exposes excluded blockers through one result", async () => {
+		const root = await createTempDir()
+		tempDirs.push(root)
+		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
+		await mkdir(join(root, "repos/agency"), { recursive: true })
+		for (const id of ["ready", "finished"]) {
+			parseJson(
+				await runCli(
+					["task", "create", id, "--repo", "agency", "--json"],
+					root,
+				),
+			)
+		}
+		parseJson(
+			await runCli(["task", "status", "finished", "done", "--json"], root),
+		)
+
+		const human = await runCli(["next"], root)
+		expect(human).toMatchObject({ exitCode: 0, stderr: "" })
+		expect(human.stdout).toContain("1. task/ready")
+		expect(human.stdout).not.toContain("task/finished")
+
+		const result = parseJson(await runCli(["next", "--select", "--json"], root))
+		expect(result.selected).toMatchObject({ key: "task/ready", rank: 1 })
+		expect(result.ready.map((item: any) => item.key)).toEqual(["task/ready"])
+		expect(result.excluded).toMatchObject([
+			{
+				key: "task/finished",
+				status: "done",
+				terminal: true,
+				blockers: [{ kind: "status", reason: "Task status is done" }],
+			},
+		])
+
+		const blockedPr = await runCli(["pr", "create", "finished", "--json"], root)
+		expect(blockedPr.exitCode).toBe(1)
+		expect(blockedPr.stderr).toBe("")
+		expect(JSON.parse(blockedPr.stdout)).toMatchObject({
+			ok: false,
+			error: {
+				code: "EXECUTION_BLOCKED",
+				fields: {
+					status: "done",
+					blockers: [{ kind: "status", reason: "Task status is done" }],
+				},
+			},
+		})
 	})
 
 	test("reports and synchronizes managed integration files", async () => {

package/src/commands/next.ts

@@ -0,0 +1,64 @@
+import { Effect } from "effect"
+import { ReadinessService } from "../services/ReadinessService"
+import type { BaseCommandOptions } from "../utils/command"
+import { createLoggers } from "../utils/effect"
+
+interface NextOptions extends BaseCommandOptions {
+	readonly select?: boolean
+}
+
+const context = (item: {
+	readonly parent: { readonly taskId?: string; readonly epicId?: string }
+}) =>
+	[
+		item.parent.epicId ? `epic ${item.parent.epicId}` : undefined,
+		item.parent.taskId ? `task ${item.parent.taskId}` : undefined,
+	]
+		.filter(Boolean)
+		.join(" / ")
+
+export const next = (options: NextOptions = {}) =>
+	Effect.gen(function* () {
+		const readiness = yield* ReadinessService
+		const { log } = createLoggers(options)
+		const result = yield* readiness.getNext(
+			options.cwd ?? process.cwd(),
+			options.select,
+		)
+		if (options.json) {
+			log(JSON.stringify(result, null, 2))
+			return
+		}
+		if (options.select) {
+			if (!result.selected) {
+				log("No execution units are ready.")
+				return
+			}
+			const parent = context(result.selected)
+			log(
+				`${result.selected.key}${parent ? ` (${parent})` : ""} - priority ${result.selected.priority.dependentCount}`,
+			)
+			return
+		}
+		if (result.ready.length === 0) {
+			log("No execution units are ready.")
+			return
+		}
+		for (const item of result.ready) {
+			const parent = context(item)
+			log(
+				`${item.rank}. ${item.key}${parent ? ` (${parent})` : ""} - priority ${item.priority.dependentCount}`,
+			)
+		}
+	})
+
+export const help = `
+Usage: agency next [--select] [--json]
+
+List ready execution units in priority order or select the highest-priority unit.
+Structured output also includes excluded units and their blockers.
+
+Options:
+  --select            Return only the highest-priority ready unit in human output
+  --json              Output ready and excluded execution units as JSON
+`

package/src/commands/pr.ts

@@ -8,6 +8,7 @@ interface PrOptions extends BaseCommandOptions {
 	readonly taskId?: string
 	readonly phaseId?: string
 	readonly draft?: boolean
+	readonly force?: boolean
 }
 
 export const pr = (options: PrOptions) =>
@@ -37,5 +38,6 @@ task or phase document.
 
 Options:
   --draft             Create a draft pull request
+  --force             Override readiness and terminal-state guards
   --json              Output the pull request URL as JSON
 `

package/src/commands/read-only.test.ts

@@ -13,6 +13,7 @@ import { task } from "./task"
 import { validate } from "./validate"
 import { context } from "./context"
 import { graph } from "./graph"
+import { next } from "./next"
 
 const write = async (root: string, path: string, content: string) => {
 	const fullPath = join(root, path)
@@ -145,6 +146,7 @@ status: open
 			}),
 		)
 		await runTestEffect(graph({ cwd: root, silent: true }))
+		await runTestEffect(next({ cwd: root, silent: true }))
 
 		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
 		expect(

package/src/commands/work.test.ts

@@ -7,6 +7,7 @@ import { TaskService } from "../services/TaskService"
 import { PhaseService } from "../services/PhaseService"
 import { WorktreeService } from "../services/WorktreeService"
 import { ClaimService } from "../services/ClaimService"
+import { ReadinessService } from "../services/ReadinessService"
 import { captureErrors, captureLogs } from "../test-utils"
 import { work, workPrepare } from "./work"
 import type { PickWorkTarget } from "../workbase/work-target"
@@ -55,6 +56,8 @@ interface HarnessOptions {
 	readonly outsideWorkbase?: boolean
 	readonly registeredWorkbases?: readonly string[]
 	readonly existingDirectories?: readonly string[]
+	readonly guardError?: Error
+	readonly readyTargetIds?: readonly string[]
 }
 
 const createHarness = (options: HarnessOptions = {}) => {
@@ -63,6 +66,7 @@ const createHarness = (options: HarnessOptions = {}) => {
 	const statusUpdates: string[] = []
 	const shownTasks: string[] = []
 	const progressUpdates: string[] = []
+	const guards: Array<{ target: string; override?: boolean }> = []
 	const launches: Array<{
 		cli: string
 		args: readonly string[]
@@ -167,6 +171,34 @@ const createHarness = (options: HarnessOptions = {}) => {
 			return Effect.succeed({ revision: "1".repeat(64) })
 		},
 	}
+	const readiness = {
+		getReadyWorkTargetIds: () =>
+			Effect.succeed(
+				new Set(
+					options.readyTargetIds ?? [
+						...(options.epicRecords ?? []).map(
+							(record: any) => `epic:${record.id}`,
+						),
+						...(options.taskRecords ?? []).map((record: any) =>
+							"phases" in record.data
+								? `task:${record.id}`
+								: `execution-unit:task/${record.id}`,
+						),
+						...(options.phaseRecords ?? []).map(
+							(record: any) =>
+								`execution-unit:phase/${record.taskId}/${record.id}`,
+						),
+					],
+				),
+			),
+		guardWorkTarget: (target: string, _root: string, override?: boolean) => {
+			if (options.guardError || override) events.push("guard")
+			guards.push({ target, override })
+			return options.guardError && !override
+				? Effect.fail(options.guardError)
+				: Effect.void
+		},
+	}
 	const fs = {
 		isDirectory: (path: string) =>
 			Effect.succeed(options.existingDirectories?.includes(path) ?? true),
@@ -206,6 +238,7 @@ const createHarness = (options: HarnessOptions = {}) => {
 				Effect.provideService(TaskService, tasks as never),
 				Effect.provideService(PhaseService, phases as never),
 				Effect.provideService(ClaimService, claims as never),
+				Effect.provideService(ReadinessService, readiness as never),
 			) as Effect.Effect<void, unknown, never>,
 		)
 	const runPrepare = (commandOptions: Parameters<typeof workPrepare>[0]) =>
@@ -227,12 +260,63 @@ const createHarness = (options: HarnessOptions = {}) => {
 		statusUpdates,
 		shownTasks,
 		progressUpdates,
+		guards,
 		run,
 		runPrepare,
 	}
 }
 
 describe("work command", () => {
+	test("guards execution targets before materialization and honors --force", async () => {
+		const blocked = createHarness({ guardError: new Error("blocked") })
+		await expect(
+			blocked.run({ taskId: "example", opencode: true }),
+		).rejects.toThrow("blocked")
+		expect(blocked.events).toEqual(["guard"])
+		expect(blocked.guards).toEqual([
+			{ target: "execution-unit:task/example", override: undefined },
+		])
+
+		const forced = createHarness({ guardError: new Error("blocked") })
+		await forced.run({ taskId: "example", opencode: true, force: true })
+		expect(forced.events).toEqual([
+			"guard",
+			"materialize",
+			"probe:opencode",
+			"launch:opencode",
+		])
+		expect(forced.guards[0]).toEqual({
+			target: "execution-unit:task/example",
+			override: true,
+		})
+	})
+
+	test("offers only graph-ready targets to the interactive chooser", async () => {
+		const harness = createHarness({
+			taskRecords: [
+				{
+					id: "ready",
+					path: "/workbase/tasks/ready/TASK.md",
+					data: { status: "open" },
+				},
+				{
+					id: "blocked",
+					path: "/workbase/tasks/blocked/TASK.md",
+					data: { status: "open" },
+				},
+			],
+			readyTargetIds: ["execution-unit:task/ready"],
+		})
+		let labels: readonly string[] = []
+		const pick: PickWorkTarget = (choices) => {
+			labels = choices.map((choice) => choice.plainLabel)
+			return Effect.succeed(null)
+		}
+
+		await harness.run({ cwd: "/workbase" }, pick)
+		expect(labels).toEqual(["[open] task ready"])
+	})
+
 	test("prepares without launching or changing lifecycle status", async () => {
 		const harness = createHarness({ existingDirectories: [] })
 

package/src/commands/work.ts

@@ -8,6 +8,7 @@ import { EpicService } from "../services/EpicService"
 import { TaskService } from "../services/TaskService"
 import { PhaseService } from "../services/PhaseService"
 import { ClaimService } from "../services/ClaimService"
+import { ReadinessService } from "../services/ReadinessService"
 import { createLoggers } from "../utils/effect"
 import { execvp } from "../utils/exec"
 import { createProgress, type Progress } from "../utils/progress"
@@ -30,6 +31,7 @@ interface WorkOptions extends BaseCommandOptions {
 	readonly epicId?: string
 	readonly opencode?: boolean
 	readonly claude?: boolean
+	readonly force?: boolean
 }
 
 type LaunchAgent = (cli: string, args: readonly string[], cwd: string) => void
@@ -48,6 +50,16 @@ const launchAgent: LaunchAgent = (cli, args, cwd) => {
 	execvp(cli, [...args])
 }
 
+const targetNodeId = (target: WorkTarget) => {
+	if (target.kind === "epic") return `epic:${target.epicId}`
+	if (target.kind === "phase") {
+		return `execution-unit:phase/${target.taskId}/${target.phaseId}`
+	}
+	return target.multiPhase
+		? `task:${target.taskId}`
+		: `execution-unit:task/${target.taskId}`
+}
+
 export const work = (
 	options: WorkOptions = {},
 	launch: LaunchAgent = launchAgent,
@@ -79,6 +91,7 @@ export const work = (
 		const tasks = yield* TaskService
 		const phases = yield* PhaseService
 		const claims = yield* ClaimService
+		const readiness = yield* ReadinessService
 		const { log, verboseLog } = createLoggers(options)
 		const cwd = options.cwd ?? process.cwd()
 		const directoryPath = options.directory
@@ -168,20 +181,29 @@ export const work = (
 					phaseRecords.push(...(yield* phases.list(task.id, root)))
 				}
 			}
-			const choices = buildWorkTargetChoices(
+			const allChoices = buildWorkTargetChoices(
 				epicRecords,
 				taskRecords,
 				phaseRecords,
 			)
+			const readyTargetIds = options.force
+				? null
+				: yield* readiness.getReadyWorkTargetIds(root)
+			const choices = options.force
+				? allChoices
+				: allChoices.filter((choice) =>
+						readyTargetIds!.has(targetNodeId(choice.target)),
+					)
 			if (choices.length === 0) {
 				return yield* Effect.fail(
-					new Error("No epics, tasks, or phases found in this workbase"),
+					new Error("No ready work targets found in this workbase"),
 				)
 			}
 			const { config } = yield* workbase.loadConfig(root)
 			target = yield* pick(choices, config.chooserCommand)
 			if (!target) return
 		}
+		yield* readiness.guardWorkTarget(targetNodeId(target), root, options.force)
 
 		let prompt: string
 		let launchPath: string
@@ -334,6 +356,7 @@ Options:
   --epic <id>         Work on an epic
   --opencode           Require OpenCode
   --claude             Require Claude Code
+  --force              Override readiness and terminal-state guards
   --no-input          Never open an interactive selector
 
 Without interactive input, provide a directory, task ID, or --epic and run the

package/src/protocol.ts

@@ -111,6 +111,12 @@ const errorMetadata: Readonly<Record<string, ErrorMetadata>> = {
 		retryable: false,
 		remediation: "Correct the workbase graph data or filters and retry.",
 	},
+	ExecutionGuardError: {
+		code: "EXECUTION_BLOCKED",
+		retryable: false,
+		remediation:
+			"Resolve the reported blockers or retry intentionally with --force.",
+	},
 	SyncError: {
 		code: "SYNC_ERROR",
 		retryable: false,

package/src/services/GraphService.test.ts

@@ -292,6 +292,42 @@ status: open
 		})
 	})
 
+	test("inherits parent epic validation blockers", async () => {
+		const root = await createWorkbase()
+		roots.push(root)
+		await write(
+			root,
+			"tasks/unlisted/TASK.md",
+			`---
+ticketUrl: null
+epic: delivery
+repo: agency
+branch: feat/unlisted
+base: main
+pr: null
+status: open
+---
+
+# Unlisted
+`,
+		)
+
+		const graph = await getGraph(root)
+		const execution = graph.nodes.find(
+			(node) => node.id === "execution-unit:task/unlisted",
+		)
+
+		expect(execution?.readiness).toMatchObject({
+			ready: false,
+			blockers: [
+				{
+					kind: "validation",
+					reason: "Epic does not list child task 'unlisted'",
+				},
+			],
+		})
+	})
+
 	test("adds body, workspace, git, and PR details only when requested", async () => {
 		const root = await createWorkbase()
 		roots.push(root)

package/src/services/GraphService.ts

@@ -279,6 +279,9 @@ export class GraphService extends Effect.Service<GraphService>()(
 					const phaseState = (taskId: string, phaseId: string) => {
 						const task = tasks.get(taskId)
 						const phase = phases.get(`${taskId}/${phaseId}`)
+						const parentEpic = task?.data.epic
+							? epics.get(task.data.epic)
+							: undefined
 						const declaration =
 							task && "phases" in task.data
 								? task.data.phases.find((item) => item.id === phaseId)
@@ -297,7 +300,7 @@ export class GraphService extends Effect.Service<GraphService>()(
 								"Parent task",
 							),
 							...validationBlockers(
-								[phase?.path, task?.path]
+								[phase?.path, task?.path, parentEpic?.path]
 									.filter((path): path is string => Boolean(path))
 									.map((path) => relative(root, path)),
 							),
@@ -323,11 +326,15 @@ export class GraphService extends Effect.Service<GraphService>()(
 
 					const taskState = (taskId: string) => {
 						const task = tasks.get(taskId)
+						const parentEpic = task?.data.epic
+							? epics.get(task.data.epic)
+							: undefined
 						const statuses = taskLeafStatuses(taskId)
 						const aggregate = aggregateProgress(statuses)
 						const descendantPaths = task
 							? [
 									relative(root, task.path),
+									...(parentEpic ? [relative(root, parentEpic.path)] : []),
 									...[...phases.entries()]
 										.filter(([key]) => key.startsWith(`${taskId}/`))
 										.map(([, phase]) => relative(root, phase.path)),

package/src/services/PullRequestService.test.ts

@@ -67,11 +67,12 @@ describe("PullRequestService", () => {
 		taskId = "example",
 		phaseId?: string,
 		draft = false,
+		force = false,
 	) =>
 		runTestEffect(
 			PullRequestService.pipe(
 				Effect.flatMap((service) =>
-					service.create(taskId, phaseId, draft, root),
+					service.create(taskId, phaseId, draft, root, { force }),
 				),
 			),
 		)
@@ -249,6 +250,24 @@ process.exit(${exitCode})
 		])
 	})
 
+	test("guards terminal targets before materializing unless forced", async () => {
+		await createTask()
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) => service.setStatus("example", "done", root)),
+			),
+		)
+
+		await expect(createPullRequest()).rejects.toThrow("Task status is done")
+		expect(
+			await Bun.file(join(root, "tasks/example/code/agency")).exists(),
+		).toBe(false)
+
+		const url = "https://github.com/example/agency/pull/49"
+		await writeFakeGh({ stdout: url })
+		expect(await createPullRequest("example", undefined, false, true)).toBe(url)
+	})
+
 	test("updates only PHASE.md for a phase PR", async () => {
 		await runTestEffect(
 			TaskService.pipe(

package/src/services/PullRequestService.ts

@@ -5,6 +5,7 @@ import { WorktreeService } from "./WorktreeService"
 import type { BaseCommandOptions } from "../utils/command"
 import { TaskService } from "./TaskService"
 import { PhaseService } from "./PhaseService"
+import { ReadinessService } from "./ReadinessService"
 import {
 	formatMarkdownDocument,
 	parseFrontmatter,
@@ -16,6 +17,10 @@ class PullRequestError extends Data.TaggedError("PullRequestError")<{
 
 const PR_URL = /^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/\d+\/?$/
 
+interface PullRequestOptions extends BaseCommandOptions {
+	readonly force?: boolean
+}
+
 export class PullRequestService extends Effect.Service<PullRequestService>()(
 	"PullRequestService",
 	{
@@ -60,7 +65,7 @@ export class PullRequestService extends Effect.Service<PullRequestService>()(
 				phaseId?: string,
 				draft = false,
 				startPath: string = process.cwd(),
-				options: BaseCommandOptions = {},
+				options: PullRequestOptions = {},
 			) =>
 				Effect.gen(function* () {
 					const service = yield* PullRequestService
@@ -68,6 +73,14 @@ export class PullRequestService extends Effect.Service<PullRequestService>()(
 					const tasks = yield* TaskService
 					const phases = yield* PhaseService
 					const worktrees = yield* WorktreeService
+					const readiness = yield* ReadinessService
+					yield* readiness.guard(
+						"pr",
+						taskId,
+						phaseId,
+						startPath,
+						options.force,
+					)
 					const workspace = yield* worktrees.materialize(
 						taskId,
 						phaseId,

package/src/services/ReadinessService.test.ts

@@ -0,0 +1,223 @@
+import { afterEach, describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { mkdir } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
+import { ReadinessService } from "./ReadinessService"
+
+const write = async (root: string, path: string, content: string) => {
+	const fullPath = join(root, path)
+	await mkdir(dirname(fullPath), { recursive: true })
+	await Bun.write(fullPath, content)
+}
+
+const execution = (status: string, branch: string) => `---
+repo: agency
+branch: ${branch}
+base: main
+pr: null
+status: ${status}
+---
+
+# Execution
+`
+
+const createWorkbase = async () => {
+	const root = await createTempDir()
+	await write(root, "agency.json", '{"version":2}\n')
+	await mkdir(join(root, "repos/agency"), { recursive: true })
+	await write(
+		root,
+		"epics/delivery/EPIC.md",
+		`---
+ticketUrl: https://example.com/delivery
+repos:
+  - repo: agency
+    ref: main
+tasks:
+  - id: prepare
+  - id: ship
+    dependsOn: [prepare]
+  - id: deploy
+    dependsOn: [ship]
+---
+
+# Delivery
+`,
+	)
+	await write(
+		root,
+		"tasks/prepare/TASK.md",
+		`---
+ticketUrl: null
+epic: delivery
+repo: agency
+branch: feat/prepare
+base: main
+pr: null
+status: done
+---
+
+# Prepare
+`,
+	)
+	await write(
+		root,
+		"tasks/ship/TASK.md",
+		`---
+ticketUrl: null
+description: Ship the feature.
+epic: delivery
+phases:
+  - id: implement
+  - id: verify
+    dependsOn: [implement]
+---
+
+# Ship
+`,
+	)
+	await write(
+		root,
+		"tasks/ship/phases/implement/PHASE.md",
+		execution("open", "feat/implement"),
+	)
+	await write(
+		root,
+		"tasks/ship/phases/verify/PHASE.md",
+		execution("open", "feat/verify"),
+	)
+	await write(
+		root,
+		"tasks/abandoned/TASK.md",
+		`---
+ticketUrl: null
+repo: agency
+branch: feat/abandoned
+base: main
+pr: null
+status: dropped
+---
+
+# Abandoned
+`,
+	)
+	await write(
+		root,
+		"tasks/deploy/TASK.md",
+		`---
+ticketUrl: null
+epic: delivery
+repo: agency
+branch: feat/deploy
+base: main
+pr: null
+status: open
+---
+
+# Deploy
+`,
+	)
+	return root
+}
+
+const service = <A>(
+	run: (readiness: ReadinessService) => Effect.Effect<A, unknown, any>,
+) => runTestEffect(ReadinessService.pipe(Effect.flatMap(run)))
+
+describe("ReadinessService", () => {
+	const roots: string[] = []
+
+	afterEach(async () => {
+		await Promise.all(roots.splice(0).map(cleanupTempDir))
+	})
+
+	test("ranks ready work and explains every excluded execution unit", async () => {
+		const root = await createWorkbase()
+		roots.push(root)
+
+		const result = await service((readiness) => readiness.getNext(root, true))
+
+		expect(result.ready.map((item) => item.key)).toEqual([
+			"phase/ship/implement",
+		])
+		expect(result.selected).toMatchObject({
+			key: "phase/ship/implement",
+			parent: { epicId: "delivery", taskId: "ship" },
+			priority: { dependentCount: 1 },
+		})
+		expect(result.excluded.map((item) => item.key)).toEqual([
+			"task/prepare",
+			"phase/ship/verify",
+			"task/abandoned",
+			"task/deploy",
+		])
+		expect(
+			result.excluded.find((item) => item.key === "phase/ship/verify"),
+		).toMatchObject({
+			ready: false,
+			terminal: false,
+			blockedBy: ["phase:ship/implement"],
+			blockers: [
+				{
+					kind: "dependency",
+					status: "open",
+					reason: "Phase dependency is open",
+				},
+			],
+		})
+		expect(
+			result.excluded.find((item) => item.key === "task/abandoned"),
+		).toMatchObject({ status: "dropped", terminal: true })
+	})
+
+	test("includes cross-task unlocks in final-phase priority", async () => {
+		const root = await createWorkbase()
+		roots.push(root)
+		await Bun.write(
+			join(root, "tasks/ship/phases/implement/PHASE.md"),
+			execution("done", "feat/implement"),
+		)
+
+		const result = await service((readiness) => readiness.getNext(root, true))
+
+		expect(result.selected).toMatchObject({
+			key: "phase/ship/verify",
+			priority: { dependentCount: 1 },
+		})
+	})
+
+	test("uses the same readiness for work and PR guards", async () => {
+		const root = await createWorkbase()
+		roots.push(root)
+
+		await service((readiness) =>
+			readiness.guard("work", "ship", "implement", root),
+		)
+		await expect(
+			service((readiness) => readiness.guard("work", "ship", "verify", root)),
+		).rejects.toThrow("Phase dependency is open")
+		await expect(
+			service((readiness) => readiness.guard("pr", "ship", "verify", root)),
+		).rejects.toThrow("Phase dependency is open")
+		await service((readiness) =>
+			readiness.guard("work", "ship", "verify", root, true),
+		)
+	})
+
+	test("allows active PR targets but rejects terminal outcomes", async () => {
+		const root = await createWorkbase()
+		roots.push(root)
+		const path = join(root, "tasks/ship/phases/implement/PHASE.md")
+		await Bun.write(path, execution("working", "feat/implement"))
+
+		await service((readiness) =>
+			readiness.guard("pr", "ship", "implement", root),
+		)
+
+		await Bun.write(path, execution("done", "feat/implement"))
+		await expect(
+			service((readiness) => readiness.guard("pr", "ship", "implement", root)),
+		).rejects.toThrow("Phase status is done")
+	})
+})

package/src/services/ReadinessService.ts

@@ -0,0 +1,230 @@
+import { Data, Effect } from "effect"
+import type { AgencyGraph, GraphBlocker, GraphNode } from "../graph-schema"
+import type { WorkStatus } from "../workbase/schemas"
+import { GraphService } from "./GraphService"
+
+type ExecutionNode = Extract<GraphNode, { readonly kind: "execution-unit" }>
+
+interface NextItem {
+	readonly rank: number
+	readonly key: string
+	readonly taskId: string
+	readonly phaseId?: string
+	readonly description?: string
+	readonly parent: {
+		readonly taskId?: string
+		readonly epicId?: string
+	}
+	readonly status: WorkStatus
+	readonly repositories: readonly string[]
+	readonly priority: {
+		readonly dependentCount: number
+	}
+	readonly ready: boolean
+	readonly terminal: boolean
+	readonly blockedBy: readonly string[]
+	readonly blockers: readonly GraphBlocker[]
+}
+
+interface NextResult {
+	readonly ready: readonly NextItem[]
+	readonly excluded: readonly NextItem[]
+	readonly selected?: NextItem
+}
+
+class ExecutionGuardError extends Data.TaggedError("ExecutionGuardError")<{
+	readonly message: string
+	readonly action: "work" | "pr"
+	readonly target: string
+	readonly status: WorkStatus
+	readonly blockedBy: readonly string[]
+	readonly blockers: readonly GraphBlocker[]
+}> {}
+
+const executionNodeId = (taskId: string, phaseId?: string) =>
+	phaseId
+		? `execution-unit:phase/${taskId}/${phaseId}`
+		: `execution-unit:task/${taskId}`
+
+const itemFor = (
+	node: ExecutionNode,
+	graph: AgencyGraph,
+	rank: number,
+): NextItem => {
+	const task = graph.nodes.find(
+		(candidate) =>
+			candidate.kind === "task" && candidate.key === node.data.taskId,
+	)
+	const epicId =
+		task?.kind === "task" && typeof task.data.epic === "string"
+			? task.data.epic
+			: undefined
+	const dependentIds = new Set(node.dependents)
+	if (node.data.phaseId) {
+		const siblings = graph.nodes.filter(
+			(candidate): candidate is ExecutionNode =>
+				candidate.kind === "execution-unit" &&
+				candidate.data.taskId === node.data.taskId &&
+				candidate.id !== node.id,
+		)
+		if (siblings.every((sibling) => sibling.status === "done")) {
+			for (const dependent of task?.dependents ?? [])
+				dependentIds.add(dependent)
+		}
+	}
+	return {
+		rank,
+		key: node.key,
+		taskId: node.data.taskId,
+		...(node.data.phaseId ? { phaseId: node.data.phaseId } : {}),
+		...(node.data.description ? { description: node.data.description } : {}),
+		parent: {
+			...(node.data.phaseId ? { taskId: node.data.taskId } : {}),
+			...(epicId ? { epicId } : {}),
+		},
+		status: node.status,
+		repositories: node.repositories,
+		priority: { dependentCount: dependentIds.size },
+		ready: node.readiness.ready,
+		terminal: node.readiness.terminal,
+		blockedBy: node.readiness.blockedBy,
+		blockers: node.readiness.blockers,
+	}
+}
+
+const rankedItems = (graph: AgencyGraph) =>
+	graph.nodes
+		.filter((node): node is ExecutionNode => node.kind === "execution-unit")
+		.map((node) => itemFor(node, graph, 0))
+		.sort(
+			(left, right) =>
+				right.priority.dependentCount - left.priority.dependentCount ||
+				left.key.localeCompare(right.key),
+		)
+		.map((item, index) => ({ ...item, rank: index + 1 }))
+
+const guardMessage = (
+	action: "work" | "pr",
+	item: Pick<NextItem, "key" | "status" | "blockers">,
+) => {
+	const reasons = item.blockers.map((blocker) => blocker.reason)
+	return `Cannot ${action === "work" ? "work on" : "create a pull request for"} '${item.key}': ${reasons.length > 0 ? reasons.join("; ") : `status is ${item.status}`}. Use --force to override.`
+}
+
+export class ReadinessService extends Effect.Service<ReadinessService>()(
+	"ReadinessService",
+	{
+		sync: () => ({
+			getReadyWorkTargetIds: (cwd: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const graphs = yield* GraphService
+					const graph = yield* graphs.get({ cwd })
+					return new Set(
+						graph.nodes
+							.filter((node) => node.readiness?.ready)
+							.map((node) => node.id),
+					)
+				}),
+
+			getNext: (cwd: string = process.cwd(), select = false) =>
+				Effect.gen(function* () {
+					const graphs = yield* GraphService
+					const graph = yield* graphs.get({ cwd })
+					const items = rankedItems(graph)
+					const ready = items
+						.filter((item) => item.ready)
+						.map((item, index) => ({ ...item, rank: index + 1 }))
+					const excluded = items
+						.filter((item) => !item.ready)
+						.map((item, index) => ({ ...item, rank: index + 1 }))
+					return {
+						ready,
+						excluded,
+						...(select && ready[0] ? { selected: ready[0] } : {}),
+					} satisfies NextResult
+				}),
+
+			guardWorkTarget: (
+				target: string,
+				cwd: string = process.cwd(),
+				override = false,
+			) =>
+				Effect.gen(function* () {
+					if (override) return
+					const graphs = yield* GraphService
+					const graph = yield* graphs.get({ cwd })
+					const node = graph.nodes.find((candidate) => candidate.id === target)
+					if (!node || !node.readiness) {
+						return yield* new ExecutionGuardError({
+							message: `Work target '${target}' was not found in the work graph.`,
+							action: "work",
+							target,
+							status: "open",
+							blockedBy: [],
+							blockers: [],
+						})
+					}
+					if (!node.readiness.ready) {
+						const item = {
+							key: node.key,
+							status: node.status!,
+							blockers: node.readiness.blockers,
+						}
+						return yield* new ExecutionGuardError({
+							message: guardMessage("work", item),
+							action: "work",
+							target,
+							status: node.status!,
+							blockedBy: node.readiness.blockedBy,
+							blockers: node.readiness.blockers,
+						})
+					}
+				}),
+
+			guard: (
+				action: "work" | "pr",
+				taskId: string,
+				phaseId?: string,
+				cwd: string = process.cwd(),
+				override = false,
+			) =>
+				Effect.gen(function* () {
+					if (override) return
+					const graphs = yield* GraphService
+					const graph = yield* graphs.get({ cwd })
+					const items = rankedItems(graph)
+					const key = phaseId ? `phase/${taskId}/${phaseId}` : `task/${taskId}`
+					const item = items.find((candidate) => candidate.key === key)
+					if (!item) {
+						return yield* new ExecutionGuardError({
+							message: `Execution unit '${key}' was not found in the work graph.`,
+							action,
+							target: executionNodeId(taskId, phaseId),
+							status: "open",
+							blockedBy: [],
+							blockers: [],
+						})
+					}
+					const actionable =
+						action === "work"
+							? item.ready
+							: !item.terminal &&
+								!item.blockers.some(
+									(blocker) =>
+										blocker.kind === "dependency" ||
+										blocker.kind === "validation",
+								)
+					if (!actionable) {
+						return yield* new ExecutionGuardError({
+							message: guardMessage(action, item),
+							action,
+							target: executionNodeId(taskId, phaseId),
+							status: item.status,
+							blockedBy: item.blockedBy,
+							blockers: item.blockers,
+						})
+					}
+				}),
+		}),
+	},
+) {}

package/src/services/WorktreeService.test.ts

@@ -206,6 +206,18 @@ describe("WorktreeService", () => {
 		expect(
 			await Bun.file(join(root, "tasks", "valid-target", "code")).exists(),
 		).toBe(false)
+
+		await expect(
+			runTestEffect(
+				WorktreeService.pipe(
+					Effect.flatMap((service) =>
+						service.materialize("valid-target", undefined, root, {
+							force: true,
+						}),
+					),
+				),
+			),
+		).resolves.toMatchObject({ repo: "agency" })
 	})
 
 	test("uses a configured worktree creation command", async () => {

package/src/services/WorktreeService.ts

@@ -84,6 +84,10 @@ const isCommitId = (ref: string) => /^[0-9a-f]{40,64}$/i.test(ref)
 const originRef = (ref: string) =>
 	ref.replace(/^refs\/remotes\/origin\//, "").replace(/^origin\//, "")
 
+interface MaterializeOptions extends BaseCommandOptions {
+	readonly force?: boolean
+}
+
 export class WorktreeService extends Effect.Service<WorktreeService>()(
 	"WorktreeService",
 	{
@@ -92,7 +96,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 				taskId: string,
 				phaseId?: string,
 				startPath: string = process.cwd(),
-				options: BaseCommandOptions = {},
+				options: MaterializeOptions = {},
 			) =>
 				Effect.gen(function* () {
 					const fs = yield* FileSystemService
@@ -105,7 +109,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 					const { root, config } = yield* workbase.loadConfig(startPath)
 					const report = yield* workbase.validate(root)
 					const validationIssue = report.issues[0]
-					if (validationIssue) {
+					if (validationIssue && !options.force) {
 						return yield* new WorktreeError({
 							message: `${validationIssue.path}: ${validationIssue.message}`,
 						})

package/src/test-utils.ts

@@ -17,6 +17,7 @@ import { ContextService } from "./services/ContextService"
 import { GraphService } from "./services/GraphService"
 import { ClaimService } from "./services/ClaimService"
 import { SyncService } from "./services/SyncService"
+import { ReadinessService } from "./services/ReadinessService"
 
 export const createTempDir = () => mkdtemp(join(tmpdir(), "agency-test-"))
 
@@ -38,6 +39,7 @@ const TestLayer = Layer.mergeAll(
 	GraphService.Default,
 	ClaimService.Default,
 	SyncService.Default,
+	ReadinessService.Default,
 )
 
 export async function runTestEffect<A, E>(