@markjaquith/agency 2.11.0 → 2.12.0

package/README.md

@@ -262,9 +262,10 @@ Nodes use stable IDs (`epic:<id>`, `task:<id>`, `phase:<task>/<phase>`,
 `repository:<alias>`, and `execution-unit:<kind>/<id>`). Typed edges are `owns`,
 `depends_on`, `writes`, and `references`.
 
-Every work node includes status, readiness, blockers, reverse dependents, and
-aggregate progress. Only `done` satisfies a dependency. The graph summary counts
-the statuses of all execution units, independent of filters.
+Every work node includes status, readiness, `blockedBy`, detailed blockers,
+terminal state, reverse dependents, and aggregate progress. Only `done` satisfies
+a dependency; `dropped` is terminal but does not satisfy dependents. The graph
+summary counts the statuses of all execution units, independent of filters.
 
 ```text
 agency graph [--json | --jsonl] [--ready | --blocked]
@@ -390,7 +391,9 @@ Single-phase tasks and phases store status in YAML. New execution units start
 `open`, and `agency work` marks the selected execution unit `working` immediately
 before launch. Use the status subcommands to mark work `delegated`, `done`,
 `dropped`, or open it again. The interactive work selector displays status
-markers before execution units.
+markers before execution units. Open, working, and delegated work may transition
+to any status. Done and dropped work are terminal and may only remain unchanged
+or transition to open; reopen terminal work before changing its outcome.
 
 ### Archive
 

package/index.ts

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

package/package.json

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

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

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

package/src/graph-schema.test.ts

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

package/src/graph-schema.ts

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

package/src/readiness.test.ts

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

package/src/readiness.ts

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

package/src/services/ContextService.ts

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

package/src/services/GraphService.test.ts

@@ -154,12 +154,33 @@ describe("GraphService", () => {
 		)!
 		const verify = graph.nodes.find((node) => node.id === "phase:ship/verify")!
 		expect(prepare.dependents).toEqual(["task:ship"])
-		expect(ship.readiness).toMatchObject({ ready: true, blocked: false })
+		expect(prepare.readiness).toMatchObject({
+			ready: false,
+			terminal: true,
+		})
+		expect(ship.readiness).toMatchObject({
+			ready: true,
+			blocked: false,
+			terminal: false,
+		})
+		expect(ship.aggregate).toMatchObject({ total: 2, open: 2, terminal: 0 })
 		expect(implement.dependents).toEqual(["phase:ship/verify"])
 		expect(implement.readiness).toMatchObject({ ready: true, blocked: false })
+		expect(
+			graph.nodes.find(
+				(node) => node.id === "execution-unit:phase/ship/implement",
+			)?.readiness,
+		).toMatchObject({
+			ready: true,
+			blocked: false,
+			blockedBy: [],
+			terminal: false,
+		})
 		expect(verify.readiness).toMatchObject({
 			ready: false,
 			blocked: true,
+			blockedBy: ["phase:ship/implement"],
+			terminal: false,
 			blockers: [
 				{
 					kind: "dependency",
@@ -168,6 +189,8 @@ describe("GraphService", () => {
 				},
 			],
 		})
+		const epic = graph.nodes.find((node) => node.id === "epic:delivery")!
+		expect(epic.aggregate).toMatchObject({ total: 3, done: 1, open: 2 })
 		expect(graph.summary).toEqual({
 			status: "open",
 			total: 3,
@@ -181,6 +204,36 @@ describe("GraphService", () => {
 		expect(await getGraph(root)).toEqual(graph)
 	})
 
+	test("never reports claimed or terminal execution units as ready", async () => {
+		const root = await createWorkbase()
+		roots.push(root)
+		const path = "tasks/ship/phases/implement/PHASE.md"
+
+		for (const status of ["working", "delegated", "done", "dropped"]) {
+			await write(
+				root,
+				path,
+				`---
+repo: agency
+branch: feat/implement
+base: main
+pr: null
+status: ${status}
+---
+
+# Implement
+`,
+			)
+			const graph = await getGraph(root, {
+				kinds: ["execution-unit"],
+				ready: true,
+			})
+			expect(graph.nodes.map((node) => node.key)).not.toContain(
+				"phase/ship/implement",
+			)
+		}
+	})
+
 	test("applies filters after computing graph state", async () => {
 		const root = await createWorkbase()
 		roots.push(root)
@@ -235,6 +288,7 @@ status: open
 					reason: "Unlisted phase 'orphan'",
 				},
 			],
+			blockedBy: ["tasks/ship/TASK.md"],
 		})
 	})
 

package/src/services/GraphService.ts

@@ -12,9 +12,13 @@ import {
 	type GraphNode,
 	type GraphNodeKind,
 	type GraphPr,
-	type GraphProgress,
 	type GraphRepositoryGit,
 } from "../graph-schema"
+import {
+	aggregateProgress,
+	isDependencySatisfied,
+	readinessState,
+} from "../readiness"
 import { parseFrontmatter } from "../workbase/frontmatter"
 import {
 	EpicFrontmatter,
@@ -69,33 +73,6 @@ const taskExecutionNodeId = (taskId: string) => `execution-unit:task/${taskId}`
 const phaseExecutionNodeId = (taskId: string, phaseId: string) =>
 	`execution-unit:phase/${taskId}/${phaseId}`
 
-const progress = (statuses: readonly WorkStatus[]): GraphProgress => {
-	const counts = {
-		total: statuses.length,
-		open: statuses.filter((status) => status === "open").length,
-		working: statuses.filter((status) => status === "working").length,
-		delegated: statuses.filter((status) => status === "delegated").length,
-		done: statuses.filter((status) => status === "done").length,
-		dropped: statuses.filter((status) => status === "dropped").length,
-		terminal: statuses.filter(
-			(status) => status === "done" || status === "dropped",
-		).length,
-	}
-	const status: WorkStatus =
-		statuses.length === 0
-			? "open"
-			: statuses.every((value) => value === "done")
-				? "done"
-				: statuses.every((value) => value === "done" || value === "dropped")
-					? "dropped"
-					: statuses.includes("working")
-						? "working"
-						: statuses.includes("delegated")
-							? "delegated"
-							: "open"
-	return { status, ...counts }
-}
-
 const hash = (content: string) =>
 	new Bun.CryptoHasher("sha256").update(content).digest("hex")
 
@@ -256,7 +233,7 @@ export class GraphService extends Effect.Service<GraphService>()(
 							: [task.data.status]
 					}
 					const taskStatus = (taskId: string) =>
-						progress(taskLeafStatuses(taskId)).status
+						aggregateProgress(taskLeafStatuses(taskId)).status
 					const dependencyBlockers = (
 						dependencies: readonly string[],
 						toId: (id: string) => string,
@@ -265,7 +242,7 @@ export class GraphService extends Effect.Service<GraphService>()(
 					): GraphBlocker[] =>
 						dependencies.flatMap((dependency) => {
 							const value = status(dependency)
-							return value === "done"
+							return isDependencySatisfied(value)
 								? []
 								: [
 										{
@@ -336,10 +313,9 @@ export class GraphService extends Effect.Service<GraphService>()(
 						}
 						return {
 							status,
-							aggregate: progress([status]),
+							aggregate: aggregateProgress([status]),
 							readiness: {
-								ready: status === "open" && blockers.length === 0,
-								blocked: status === "open" && blockers.length > 0,
+								...readinessState(status, blockers),
 								blockers: uniqueBlockers(blockers),
 							},
 						}
@@ -348,7 +324,7 @@ export class GraphService extends Effect.Service<GraphService>()(
 					const taskState = (taskId: string) => {
 						const task = tasks.get(taskId)
 						const statuses = taskLeafStatuses(taskId)
-						const aggregate = progress(statuses)
+						const aggregate = aggregateProgress(statuses)
 						const descendantPaths = task
 							? [
 									relative(root, task.path),
@@ -410,8 +386,7 @@ export class GraphService extends Effect.Service<GraphService>()(
 							status: aggregate.status,
 							aggregate,
 							readiness: {
-								ready,
-								blocked: !ready && taskBlockers.length > 0,
+								...readinessState(aggregate.status, taskBlockers, ready),
 								blockers: taskBlockers,
 							},
 						}
@@ -422,7 +397,7 @@ export class GraphService extends Effect.Service<GraphService>()(
 						const statuses =
 							epic?.data.tasks.flatMap((item) => taskLeafStatuses(item.id)) ??
 							[]
-						const aggregate = progress(statuses)
+						const aggregate = aggregateProgress(statuses)
 						const paths = epic
 							? [
 									relative(root, epic.path),
@@ -467,8 +442,7 @@ export class GraphService extends Effect.Service<GraphService>()(
 							status: aggregate.status,
 							aggregate,
 							readiness: {
-								ready,
-								blocked: !ready && epicBlockers.length > 0,
+								...readinessState(aggregate.status, epicBlockers, ready),
 								blockers: epicBlockers,
 							},
 						}
@@ -874,7 +848,7 @@ export class GraphService extends Effect.Service<GraphService>()(
 						includes,
 						nodes: filteredNodes,
 						edges: filteredEdges,
-						summary: progress(leafStatuses),
+						summary: aggregateProgress(leafStatuses),
 						validation: {
 							valid: validation.valid,
 							issues: validation.issues,

package/src/services/PhaseService.ts

@@ -15,6 +15,7 @@ import {
 	formatMarkdownDocument,
 	parseFrontmatter,
 } from "../workbase/frontmatter"
+import { canTransitionStatus } from "../readiness"
 
 class PhaseError extends Data.TaggedError("PhaseError")<{
 	readonly message: string
@@ -340,6 +341,11 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 					const service = yield* PhaseService
 					const validStatus = yield* decodeStatus(status)
 					const record = yield* service.show(taskId, id, startPath)
+					if (!canTransitionStatus(record.data.status, validStatus)) {
+						return yield* new PhaseError({
+							message: `Cannot transition phase '${id}' from ${record.data.status} to ${validStatus}; reopen it first`,
+						})
+					}
 					const parsed = yield* parseFrontmatter(record.content, record.path)
 					const data = { ...record.data, status: validStatus }
 					const content = formatMarkdownDocument(data, parsed.body)

package/src/services/TaskPhaseService.test.ts

@@ -244,6 +244,22 @@ describe("task and phase services", () => {
 		expect(task.data.status).toBe("delegated")
 		expect(task.content).toContain("status: delegated")
 		expect(task.content).toContain("Describe the task outcome.")
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.setStatus("single-status", "done", root),
+				),
+			),
+		)
+		await expect(
+			runTestEffect(
+				TaskService.pipe(
+					Effect.flatMap((service) =>
+						service.setStatus("single-status", "dropped", root),
+					),
+				),
+			),
+		).rejects.toThrow("reopen it first")
 
 		await runTestEffect(
 			TaskService.pipe(
@@ -283,6 +299,33 @@ describe("task and phase services", () => {
 			),
 		)
 		expect(phase.data.status).toBe("dropped")
+		await expect(
+			runTestEffect(
+				PhaseService.pipe(
+					Effect.flatMap((service) =>
+						service.setStatus("multi-status", "implementation", "done", root),
+					),
+				),
+			),
+		).rejects.toThrow("reopen it first")
+		await runTestEffect(
+			PhaseService.pipe(
+				Effect.flatMap((service) =>
+					service.setStatus("multi-status", "implementation", "open", root),
+				),
+			),
+		)
+		expect(
+			(
+				await runTestEffect(
+					PhaseService.pipe(
+						Effect.flatMap((service) =>
+							service.setStatus("multi-status", "implementation", "done", root),
+						),
+					),
+				)
+			).data.status,
+		).toBe("done")
 		await expect(
 			runTestEffect(
 				TaskService.pipe(

package/src/services/TaskService.ts

@@ -15,6 +15,7 @@ import {
 	formatMarkdownDocument,
 	parseFrontmatter,
 } from "../workbase/frontmatter"
+import { canTransitionStatus } from "../readiness"
 
 class TaskError extends Data.TaggedError("TaskError")<{
 	readonly message: string
@@ -212,6 +213,11 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 						message: `Task '${id}' has multiple phases; set status on a phase instead`,
 					})
 				}
+				if (!canTransitionStatus(record.data.status, validStatus)) {
+					return yield* new TaskError({
+						message: `Cannot transition task '${id}' from ${record.data.status} to ${validStatus}; reopen it first`,
+					})
+				}
 				const parsed = yield* parseFrontmatter(record.content, record.path)
 				const data = { ...record.data, status: validStatus }
 				const content = formatMarkdownDocument(data, parsed.body)