@markjaquith/agency 2.15.0 → 2.17.0

package/README.md

@@ -304,6 +304,40 @@ 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
+registration, writable and reference checkout dirtiness, resolved reference
+commits, claim expiry, and GitHub pull request and merge state. It reports
+structured `changes`, `warnings`, `unresolved`, and per-execution evidence. The
+default and `--dry-run` modes are observational.
+
+`agency sync --apply` performs only these safe transitions:
+
+- materialize missing checkouts when no registration, branch, or path conflicts;
+- release an active claim only after its declared expiry has passed;
+- record a single PR whose head and base match the declaration; and
+- mark work done after its authoritative PR is merged and no active claim remains.
+
+Apply never modifies dirty checkouts, moves worktrees, switches branches, resets
+reference commits, chooses among multiple PRs, or bypasses active claims. Those
+conditions remain visible in `warnings` or `unresolved` with a suggested action.
+
 ### Workbase and Repositories
 
 ```text
@@ -324,7 +358,7 @@ repository. Alias names are then used by all documents and commands.
 
 Commands that print Agency-owned results accept `--json`, including initialization,
 integration inspection/sync, repository mutations, entity creation/list/show,
-status, validation, graph export, and PR creation.
+status, validation, graph export, reconciliation, and PR creation.
 
 ### Epics
 

package/cli.ts

@@ -10,6 +10,8 @@ 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"
 import { phase, help as phaseHelp } from "./src/commands/phase"
@@ -33,6 +35,8 @@ import { IntegrationService } from "./src/services/IntegrationService"
 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,
@@ -61,6 +65,8 @@ const CliLayer = Layer.mergeAll(
 	ContextService.Default,
 	GraphService.Default,
 	ClaimService.Default,
+	SyncService.Default,
+	ReadinessService.Default,
 )
 
 /**
@@ -210,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,
@@ -348,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) {
@@ -424,6 +445,23 @@ const commands: Record<string, Command> = {
 			)
 		},
 	},
+	sync: {
+		run: async (_args: string[], options: Record<string, any>) => {
+			if (options.help) {
+				console.log(syncHelp)
+				return
+			}
+			await runCommand(
+				sync({
+					apply: options.apply,
+					dryRun: options["dry-run"],
+					json: options.json,
+					silent: options.silent,
+					verbose: options.verbose,
+				}),
+			)
+		},
+	},
 }
 
 function showMainHelp() {
@@ -444,12 +482,14 @@ 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
   validate [path]        Validate a workbase
   context [target]       Return complete target context
   graph                  Export the complete workbase graph
+  sync                   Reconcile declarations with external state
 
 Global Options:
   -h, --help             Show help for a command

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.15.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,8 @@ 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"],
 			[
 				[
 					"claim",
@@ -191,6 +193,38 @@ 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",
+			values: { "dry-run": true, json: true },
+		})
+		expect(parseCli(["sync", "--apply"])).toMatchObject({
+			commandName: "sync",
+			values: { apply: true },
+		})
+		expect(() => parseCli(["sync", "--dry-run", "--apply"])).toThrow(
+			"cannot be combined",
+		)
+	})
+
 	test("validates revision-guarded claim operations", () => {
 		const revision = "0".repeat(64)
 		expect(

package/src/cli-parser.ts

@@ -319,6 +319,21 @@ const commands = {
 			required: ["session-id", "revision", "outcome"],
 		},
 	},
+	sync: {
+		usage: "agency sync [--dry-run | --apply] [--json]",
+		options: {
+			...outputOptions,
+			"dry-run": { type: "boolean" },
+			apply: { type: "boolean" },
+		},
+		command: {
+			usage: "agency sync [--dry-run | --apply] [--json]",
+			minArgs: 0,
+			maxArgs: 0,
+			options: ["dry-run", "apply", "json"],
+			conflicts: [["dry-run", "apply"]],
+		},
+	},
 	archive: {
 		usage: "agency archive <epic|task|phase>",
 		options: outputOptions,
@@ -353,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"],
@@ -371,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,
@@ -729,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/sync.ts

@@ -0,0 +1,36 @@
+import { Effect } from "effect"
+import { SyncService } from "../services/SyncService"
+import type { BaseCommandOptions } from "../utils/command"
+import { createLoggers } from "../utils/effect"
+
+interface SyncCommandOptions extends BaseCommandOptions {
+	readonly apply?: boolean
+	readonly dryRun?: boolean
+}
+
+export const sync = (options: SyncCommandOptions = {}) =>
+	Effect.gen(function* () {
+		const service = yield* SyncService
+		const { log } = createLoggers(options)
+		const result = yield* service.reconcile({
+			cwd: options.cwd,
+			apply: options.apply === true,
+		})
+		log(JSON.stringify(result, null, 2))
+	})
+
+export const help = `
+Usage: agency sync [--dry-run | --apply] [--json]
+
+Compare declared execution state with Git worktrees, branches, references, claims,
+and GitHub pull requests. Dry-run is the default.
+
+Options:
+  --dry-run                 Report planned safe transitions without changing state
+  --apply                   Apply safe reconciliation transitions
+  --json                    Output one versioned machine result
+
+Apply may materialize unambiguous missing checkouts, release expired claims,
+record a uniquely matched PR, and mark merged work done. Dirty, stale, or
+conflicting checkouts are always left unresolved.
+`

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: [] })