@markjaquith/agency 2.15.0 → 2.17.0

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,17 @@ 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,
+		remediation: "Resolve workbase validation errors before reconciling.",
+	},
 	ProcessError: { code: "PROCESS_ERROR", retryable: true },
 	ProtocolOutputError: {
 		code: "PROTOCOL_OUTPUT_ERROR",

package/src/services/ClaimService.ts

@@ -87,6 +87,23 @@ interface FinishInput extends OwnedClaimInput {
 	readonly outcome: "done" | "dropped"
 }
 
+interface ExpireClaimInput {
+	readonly taskId: string
+	readonly phaseId?: string
+	readonly revision: string
+	readonly now?: Date
+}
+
+interface ReconcileInput {
+	readonly taskId: string
+	readonly phaseId?: string
+	readonly revision: string
+	readonly pr?: string
+	readonly status?: "done"
+}
+
+const PR_URL = /^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/\d+\/?$/
+
 type SingleTaskData = Extract<TaskData, { readonly repo: string }>
 type ExecutionData = SingleTaskData | PhaseData
 
@@ -286,6 +303,83 @@ export class ClaimService extends Effect.Service<ClaimService>()(
 					}
 				}),
 
+			expire: (input: ExpireClaimInput, startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const service = yield* ClaimService
+					const inspected = yield* service.inspect(
+						input.taskId,
+						input.phaseId,
+						startPath,
+					)
+					return yield* operation(() =>
+						updateAtomically(
+							inspected.target,
+							input.revision,
+							(data, now) => {
+								if (
+									data.claim?.state !== "active" ||
+									data.claim.expiresAt === undefined ||
+									Date.parse(data.claim.expiresAt) > now.getTime() ||
+									(data.status !== "working" && data.status !== "delegated")
+								) {
+									throw new ClaimError({
+										target: inspected.target.label,
+										message: `${inspected.target.label} does not have an expired active claim`,
+									})
+								}
+								const claim: ClaimRecord = {
+									...data.claim,
+									state: "released",
+									releasedAt: now.toISOString(),
+								}
+								return { data: { ...data, status: "open", claim }, claim }
+							},
+							input.now ?? new Date(),
+						),
+					)
+				}),
+
+			reconcile: (input: ReconcileInput, startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					if (input.pr !== undefined && !PR_URL.test(input.pr)) {
+						return yield* new ClaimError({
+							message: `Invalid GitHub pull request URL: ${input.pr}`,
+						})
+					}
+					const service = yield* ClaimService
+					const inspected = yield* service.inspect(
+						input.taskId,
+						input.phaseId,
+						startPath,
+					)
+					return yield* operation(() =>
+						updateAtomically(
+							inspected.target,
+							input.revision,
+							(data) => {
+								if (input.status === "done" && data.claim?.state === "active") {
+									throw new ClaimConflictError({
+										target: inspected.target.label,
+										currentRevision: input.revision,
+										claim: data.claim,
+										message: `${inspected.target.label} has an active claim`,
+									})
+								}
+								return {
+									data: {
+										...data,
+										...(input.pr !== undefined ? { pr: input.pr } : {}),
+										...(input.status !== undefined
+											? { status: input.status }
+											: {}),
+									},
+								}
+							},
+							new Date(),
+						),
+					)
+				}),
+
 			claim: (input: ClaimInput, startPath: string = process.cwd()) =>
 				Effect.gen(function* () {
 					for (const [label, value] of [

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")
+	})
+})