@markjaquith/agency 2.16.0 → 2.18.0

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/validate.test.ts

@@ -80,6 +80,7 @@ pr: null
 					: Effect.succeed(path)
 			},
 			listRegistered: () => Effect.succeed(["/first", "/selected"]),
+			getDefault: () => Effect.succeed(undefined),
 			validate: (path: string) =>
 				Effect.succeed({
 					root: path,
@@ -116,6 +117,7 @@ pr: null
 					message: "No Agency workbase found from /outside",
 				}),
 			listRegistered: () => Effect.succeed(["/selected"]),
+			getDefault: () => Effect.succeed(undefined),
 		}
 		const fs = {
 			runCommand: () => Effect.fail(new Error("unexpected fzf probe")),

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[]
@@ -94,6 +98,7 @@ const createHarness = (options: HarnessOptions = {}) => {
 					})
 				: Effect.succeed("/workbase"),
 		listRegistered: () => Effect.succeed(options.registeredWorkbases ?? []),
+		getDefault: () => Effect.succeed(undefined),
 		loadConfig: () =>
 			Effect.succeed({
 				root: "/workbase",
@@ -167,6 +172,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 +239,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 +261,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
@@ -275,9 +297,13 @@ export const workPrepare = (options: WorkOptions = {}) =>
 		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) {
+		let taskId = options.taskId
+		let phaseId = options.phaseId
+		if (taskId) {
+			const task = yield* tasks.show(taskId, root)
+			taskId = task.id
+			if (phaseId) phaseId = (yield* phases.show(task.id, phaseId, root)).id
+		} else if (options.directory && !isDirectory) {
 			const task = yield* tasks.show(options.directory, root)
 			taskId = task.id
 		} else {
@@ -331,11 +357,16 @@ 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
+  --epic <id>          Work on an epic
+  --task <id>          Work on a task
+  --phase <id>         Work on a phase selected with --task
+  --workbase <target>  Select a workbase by ID, name, or path
+  --cwd <path>         Resolve context from a specific directory
   --opencode           Require OpenCode
   --claude             Require Claude Code
-  --no-input          Never open an interactive selector
+  --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
-command from a workbase. Workbase and target selection otherwise fail.
+Without interactive input, provide an explicit workbase or cwd and an entity
+selector. Workbase and target selection otherwise fail.
 `

package/src/commands/workbase.test.ts

@@ -31,7 +31,7 @@ describe("workbase command", () => {
 				}),
 			),
 		)
-		const path = JSON.parse(added[0]!).path
+		const registration = JSON.parse(added[0]!)
 
 		const listed = await captureLogs(() =>
 			runTestEffect(
@@ -44,7 +44,68 @@ describe("workbase command", () => {
 			),
 		)
 
-		expect(JSON.parse(listed[0]!)).toEqual([path])
+		expect(JSON.parse(listed[0]!)).toEqual({
+			workbases: [registration],
+		})
+	})
+
+	test("sets, clears, and removes the default workbase", async () => {
+		const added = await captureLogs(() =>
+			runTestEffect(
+				workbase({
+					subcommand: "add",
+					args: [root],
+					name: "primary",
+					configDirectory,
+					json: true,
+				}),
+			),
+		)
+		const registration = JSON.parse(added[0]!)
+
+		await runTestEffect(
+			workbase({
+				subcommand: "default",
+				args: ["primary"],
+				configDirectory,
+				silent: true,
+			}),
+		)
+		const listed = await captureLogs(() =>
+			runTestEffect(
+				workbase({
+					subcommand: "list",
+					args: [],
+					configDirectory,
+					json: true,
+				}),
+			),
+		)
+		expect(JSON.parse(listed[0]!).defaultId).toBe(registration.id)
+		await runTestEffect(
+			workbase({
+				subcommand: "default",
+				args: [],
+				clear: true,
+				configDirectory,
+				silent: true,
+			}),
+		)
+		expect(
+			await Bun.file(join(configDirectory, "agency/workbases.json")).json(),
+		).toEqual({ version: 2, workbases: [registration] })
+
+		await runTestEffect(
+			workbase({
+				subcommand: "remove",
+				args: [registration.id],
+				configDirectory,
+				silent: true,
+			}),
+		)
+		expect(
+			await Bun.file(join(configDirectory, "agency/workbases.json")).json(),
+		).toEqual({ version: 2, workbases: [] })
 	})
 
 	test("requires an add path", async () => {

package/src/commands/workbase.ts

@@ -1,4 +1,5 @@
 import { Effect } from "effect"
+import { resolve } from "node:path"
 import type { BaseCommandOptions } from "../utils/command"
 import { WorkbaseService } from "../services/WorkbaseService"
 import { createLoggers } from "../utils/effect"
@@ -7,6 +8,8 @@ interface WorkbaseOptions extends BaseCommandOptions {
 	readonly subcommand?: string
 	readonly args: readonly string[]
 	readonly configDirectory?: string
+	readonly name?: string
+	readonly clear?: boolean
 }
 
 export const workbase = (options: WorkbaseOptions) =>
@@ -22,26 +25,85 @@ export const workbase = (options: WorkbaseOptions) =>
 						new Error("Usage: agency workbase add <path>"),
 					)
 				}
-				const root = yield* service.register(path, options.configDirectory)
+				const registration = yield* service.register(
+					resolve(options.cwd ?? process.cwd(), path),
+					options.configDirectory,
+					options.name,
+				)
 				log(
 					options.json
-						? JSON.stringify({ path: root }, null, 2)
-						: `Added workbase ${root}`,
+						? JSON.stringify(registration, null, 2)
+						: `Added workbase ${registration.name ?? registration.id} (${registration.path})`,
 				)
 				return
 			}
 			case "list": {
-				const workbases = yield* service.listRegistered(options.configDirectory)
+				const registrations = yield* service.listRegistrations(
+					options.configDirectory,
+				)
 				if (options.json) {
-					log(JSON.stringify(workbases, null, 2))
+					log(JSON.stringify(registrations, null, 2))
 				} else {
-					for (const path of workbases) log(path)
+					for (const entry of registrations.workbases) {
+						const marker = entry.id === registrations.defaultId ? "*" : " "
+						log(`${marker} ${entry.name ?? entry.id}\t${entry.path}`)
+					}
 				}
 				return
 			}
+			case "remove": {
+				const entry = yield* service.removeRegistered(
+					options.args[0]!,
+					options.configDirectory,
+					options.cwd,
+				)
+				log(
+					options.json
+						? JSON.stringify(entry, null, 2)
+						: `Removed workbase ${entry.name ?? entry.id}`,
+				)
+				return
+			}
+			case "prune": {
+				const removed = yield* service.pruneRegistered(options.configDirectory)
+				log(
+					options.json
+						? JSON.stringify(removed, null, 2)
+						: `Pruned ${removed.length} stale workbase${removed.length === 1 ? "" : "s"}`,
+				)
+				return
+			}
+			case "default": {
+				const selector = options.clear ? null : options.args[0]
+				if (selector === undefined) {
+					const entry = yield* service.getDefault(options.configDirectory)
+					log(
+						options.json
+							? JSON.stringify(entry ?? null, null, 2)
+							: entry
+								? `${entry.name ?? entry.id}\t${entry.path}`
+								: "No default workbase",
+					)
+					return
+				}
+				const entry = yield* service.setDefault(
+					selector,
+					options.configDirectory,
+				)
+				log(
+					options.json
+						? JSON.stringify(entry, null, 2)
+						: entry
+							? `Default workbase is ${entry.name ?? entry.id}`
+							: "Cleared default workbase",
+				)
+				return
+			}
 			default:
 				return yield* Effect.fail(
-					new Error("Subcommand is required. Available: add, list"),
+					new Error(
+						"Subcommand is required. Available: add, list, remove, prune, default",
+					),
 				)
 		}
 	})
@@ -50,9 +112,14 @@ export const help = `
 Usage: agency workbase <subcommand>
 
 Subcommands:
-  add <path>  Register an Agency workbase
-  list        List registered workbases
+  add <path>        Register an Agency workbase
+  list              List registered workbases
+  remove <selector> Remove a registered workbase
+  prune             Remove registrations whose paths no longer exist
+  default [selector] Show or set the default workbase
 
 Options:
-  --json      Output results as JSON
+  --name <name> Name a registered workbase
+  --clear       Clear the default workbase
+  --json        Output results as JSON
 `

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(