@markjaquith/agency 2.40.0 → 2.40.1

package/README.md

@@ -569,7 +569,7 @@ Targeted commands accept `--epic`, `--task`, and `--phase` where those entity
 kinds apply. A phase selector requires a task selector. Entity selectors cannot
 be mixed with positional target IDs, and an epic selector cannot be mixed with
 task or phase selectors. This makes commands such as
-`agency phase status done --task ship --phase release --workbase primary --no-input`
+`agency phase status working --task ship --phase release --workbase primary --no-input`
 fully independent of process cwd and prompts.
 
 Inspect tasks:
@@ -577,7 +577,7 @@ Inspect tasks:
 ```text
 agency task list [filters] [--json]
 agency task show <id> [--json]
-agency task status <id> <open|done|dropped> [--json]
+agency task status <id> <open|working|dropped> [--json]
 agency task update <id> [metadata options] [--json]
 agency task rename <id> <new-id> [--json]
 agency task move <id> (--epic <epic-id> | --no-epic) [--json]
@@ -616,7 +616,7 @@ agency phase create <task-id> <phase-id>
 
 agency phase list <task-id> [filters] [--json]
 agency phase show <task-id> <phase-id> [--json]
-agency phase status <task-id> <phase-id> <open|done|dropped> [--json]
+agency phase status <task-id> <phase-id> <open|working|dropped> [--json]
 agency phase update <task-id> <phase-id> [metadata options] [--json]
 agency phase rename <task-id> <phase-id> <new-id> [--json]
 agency phase dependency <add|remove> <task-id> <phase-id> <dependency-id>
@@ -639,6 +639,8 @@ writing anything.
 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. Running `agency work` again can relaunch unclaimed `working` work.
+The `done` status is reserved for an authoritative merged pull request and is
+applied by `agency sync --apply`, not by task or phase status commands.
 Use explicit claims only when an external orchestrator needs coordinated
 ownership. The interactive work selector displays status markers before
 execution units. Existing working and delegated work may be released to `open`
@@ -672,11 +674,12 @@ agency finish <task-id> [phase-id] --session-id <id>
   --revision <sha256> --outcome <done|dropped> [--json]
 ```
 
-An active claim sets status to `working`. Release returns it to `open`; finish
-sets the terminal outcome. Released and finished ownership metadata remains in
-frontmatter. Conflicts return the current revision and complete ownership record
-in the machine error envelope rather than overwriting it. Expired claims may be
-replaced with a revision-guarded claim.
+An active claim sets status to `working`. Release returns it to `open`. Finish
+records the claim outcome and ownership history; a `done` claim outcome leaves
+the execution unit `working` until its pull request is merged, while `dropped`
+remains terminal. Conflicts return the current revision and complete ownership
+record in the machine error envelope rather than overwriting it. Expired claims
+may be replaced with a revision-guarded claim.
 
 `agency work` does not claim execution units. It refuses active explicit claims,
 marks open execution work `working`, and launches the runner. External

package/package.json

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

package/skills/agency/SKILL.md

@@ -118,11 +118,12 @@ independently meaningful tasks need coordination.
 
 1. Re-run `agency validate` and repository checks.
 2. Create a PR only when requested: `agency pr create <task> [phase]`.
-3. Record terminal state only when the requested outcome is true. A created PR
-   alone does not make work `done` if completion requires merge.
-4. If the session has a claim, use revision-guarded `agency finish`; otherwise
-   use the task or phase status command. Use `dropped` only for intentionally
-   abandoned work.
+3. Keep committed work `working` while its pull request is open. After the
+   authoritative pull request merges, use `agency sync --apply` to reconcile it
+   to `done`.
+4. If the session has a claim, use revision-guarded `agency finish`; a successful
+   claim outcome closes ownership without marking unmerged work `done`. Use
+   `dropped` only for intentionally abandoned work.
 5. Report the durable status and PR URL. Do not manually remove the worktree.
 
 ## Human Launch vs Active Agent

package/skills/agency/references/commands.md

@@ -89,7 +89,7 @@ agency task create <id> --multi-phase [--ticket-url <url>]
   [--description <text>] [--epic <id>] [--json]
 agency task list [filters] [--json]
 agency task show <id> [--json]
-agency task status <id> <open|done|dropped> [--json]
+agency task status <id> <open|working|dropped> [--json]
 agency task update <id> [metadata options] [--if-revision <hash>] [--json]
 agency task rename <id> <new-id> [--if-revision <hash>] [--json]
 agency task move <id> (--epic <epic-id> | --no-epic)
@@ -102,7 +102,7 @@ agency phase create <task-id> <phase-id> --repo <alias> --branch <name>
   [--depends-on <phase-id>...] [--first-phase <phase-id>] [--json]
 agency phase list <task-id> [filters] [--json]
 agency phase show <task-id> <phase-id> [--json]
-agency phase status <task-id> <phase-id> <open|done|dropped> [--json]
+agency phase status <task-id> <phase-id> <open|working|dropped> [--json]
 agency phase update <task-id> <phase-id> [metadata options]
   [--if-revision <hash>] [--json]
 agency phase rename <task-id> <phase-id> <new-id>

package/skills/agency/references/contracts.md

@@ -137,6 +137,8 @@ readable legacy state but cannot be newly assigned.
 - An execution unit has one writable `repo`; plural `repos` are read-only
   `{ repo, ref }` entries and cannot repeat the writable alias.
 - A writable `(repo, branch)` pair belongs to exactly one active execution unit.
+- `done` represents an authoritative merged pull request and is reconciled by
+  `agency sync --apply`; committed or review-ready work remains `working`.
 - Only `done` satisfies dependencies. `dropped` is terminal but blocks dependents.
 - Epic task dependencies live in `EPIC.md`; phase dependencies live in `TASK.md`.
 - IDs remain stable; use `dependsOn`, not numeric directory prefixes, for order.

package/skills/agency/references/recipes.md

@@ -184,15 +184,17 @@ agency release checkout ui --session-id session-123 \
 
 ## Finish Verified Work
 
-Only after the assigned completion condition is true:
+After the claimed run completes successfully:
 
 ```bash
 agency finish checkout ui --session-id session-123 \
   --revision <current-sha256> --outcome done --json
 ```
 
-Do not substitute `phase status done` for `finish` when an active claim exists;
-`finish` preserves ownership history and revision safety.
+Do not substitute a phase status mutation for `finish`; `finish` preserves
+ownership history and revision safety. A `done` claim outcome leaves unmerged
+execution work `working`. After the authoritative pull request merges, use
+`agency sync --apply` to reconcile the execution unit to `done`.
 
 ## Create A Pull Request
 

package/src/cli.test.ts

@@ -244,6 +244,10 @@ describe("CLI", () => {
 			),
 		)
 		expect(finished.claim).toMatchObject({ state: "finished", outcome: "done" })
+		expect(
+			parseJson(await runCli(["task", "show", "claimed", "--json"], root)).data
+				.status,
+		).toBe("working")
 	})
 
 	test("routes graph mutations through structured output", async () => {
@@ -476,7 +480,7 @@ describe("CLI", () => {
 			)
 		}
 		parseJson(
-			await runCli(["task", "status", "finished", "done", "--json"], root),
+			await runCli(["task", "status", "finished", "dropped", "--json"], root),
 		)
 
 		const human = await runCli(["next"], root)
@@ -490,9 +494,9 @@ describe("CLI", () => {
 		expect(result.excluded).toMatchObject([
 			{
 				key: "task/finished",
-				status: "done",
+				status: "dropped",
 				terminal: true,
-				blockers: [{ kind: "status", reason: "Task status is done" }],
+				blockers: [{ kind: "status", reason: "Task status is dropped" }],
 			},
 		])
 
@@ -504,8 +508,8 @@ describe("CLI", () => {
 			error: {
 				code: "EXECUTION_BLOCKED",
 				fields: {
-					status: "done",
-					blockers: [{ kind: "status", reason: "Task status is done" }],
+					status: "dropped",
+					blockers: [{ kind: "status", reason: "Task status is dropped" }],
 				},
 			},
 		})
@@ -1131,18 +1135,18 @@ status: open
 			}
 
 			parseJson(
-				await runCli(["task", "status", "example", "done", "--json"], root),
+				await runCli(["task", "status", "example", "dropped", "--json"], root),
 			)
 			const blocked = await runCli(
 				["work", "--task", "example", "--runner", "noop"],
 				root,
 			)
 			expect(blocked.exitCode).toBe(1)
-			expect(blocked.stderr).toContain("Task status is done")
+			expect(blocked.stderr).toContain("Task status is dropped")
 			expect(
 				parseJson(await runCli(["task", "show", "example", "--json"], root))
 					.data.status,
-			).toBe("done")
+			).toBe("dropped")
 
 			const resumedTask = await runCli(
 				["work", "--task", "example", "--runner", "noop", "--force"],
@@ -1150,7 +1154,7 @@ status: open
 			)
 			expect(resumedTask).toMatchObject({ exitCode: 0, stderr: "" })
 			expect(resumedTask.stdout).toContain(
-				"Reopened task/example from done as working",
+				"Reopened task/example from dropped as working",
 			)
 			expect(
 				parseJson(await runCli(["task", "show", "example", "--json"], root))

package/src/commands/claim.ts

@@ -93,5 +93,6 @@ Release an execution unit owned by the session.
 export const finishHelp = `
 Usage: agency finish <task-id> [phase-id] --session-id <id> --revision <sha256> --outcome <done|dropped>
 
-Finish an execution unit owned by the session.
+Finish a claim owned by the session. A done claim outcome leaves unmerged work
+working; agency sync --apply marks the execution unit done after merge.
 `

package/src/commands/phase.ts

@@ -275,7 +275,7 @@ Subcommands:
   list <task>           List task phases
   show <task> <phase>   Show a phase
   status <task> <phase> <status>
-                        Set open, working, done, or dropped
+                        Set open, working, or dropped
   update <task> <phase> Update phase metadata
   rename <task> <phase> <new-id>
                         Rename a phase and update dependencies

package/src/commands/status.test.ts

@@ -74,7 +74,7 @@ describe("status command", () => {
 		await runTestEffect(
 			task({
 				subcommand: "status",
-				args: ["finished", "done"],
+				args: ["finished", "dropped"],
 				cwd: root,
 				silent: true,
 			}),

package/src/commands/task-phase.test.ts

@@ -239,13 +239,13 @@ describe("task and phase command JSON output", () => {
 			runTestEffect(
 				phase({
 					subcommand: "status",
-					args: ["multi", "first", "done"],
+					args: ["multi", "first", "working"],
 					cwd: root,
 					json: true,
 				}),
 			),
 		)
-		expect(JSON.parse(phaseLogs[0]!).data.status).toBe("done")
+		expect(JSON.parse(phaseLogs[0]!).data.status).toBe("working")
 
 		await runTestEffect(
 			task({
@@ -263,13 +263,13 @@ describe("task and phase command JSON output", () => {
 			runTestEffect(
 				task({
 					subcommand: "status",
-					args: ["single-status", "done"],
+					args: ["single-status", "working"],
 					cwd: root,
 					json: true,
 				}),
 			),
 		)
-		expect(JSON.parse(taskLogs[0]!).data.status).toBe("done")
+		expect(JSON.parse(taskLogs[0]!).data.status).toBe("working")
 	})
 
 	test("converts a single-phase task with an explicit first phase ID", async () => {

package/src/commands/task.ts

@@ -423,7 +423,7 @@ Subcommands:
   create <id>           Create a task without prompting
   list                  List tasks
   show <id>             Show a task
-  status <id> <status>  Set open, working, done, or dropped
+  status <id> <status>  Set open, working, or dropped
   update <id>           Update task metadata
   rename <id> <new-id>  Rename a task and update graph references
   move <id>             Move a task with --epic or --no-epic

package/src/readiness.ts

@@ -5,9 +5,9 @@ export interface ReadinessBlocker {
 }
 
 export const WORK_STATUS_TRANSITIONS = {
-	open: ["open", "working", "delegated", "done", "dropped"],
-	working: ["open", "working", "delegated", "done", "dropped"],
-	delegated: ["open", "working", "delegated", "done", "dropped"],
+	open: ["open", "working", "delegated", "dropped"],
+	working: ["open", "working", "delegated", "dropped"],
+	delegated: ["open", "working", "delegated", "dropped"],
 	done: ["open", "done"],
 	dropped: ["open", "dropped"],
 } as const satisfies Record<WorkStatus, readonly WorkStatus[]>

package/src/services/ClaimService.test.ts

@@ -139,7 +139,7 @@ describe("claim service", () => {
 				),
 			),
 		)
-		expect(finished.data.status).toBe("done")
+		expect(finished.data.status).toBe("working")
 		expect(finished.claim).toMatchObject({
 			state: "finished",
 			finishedAt: "2026-07-17T12:45:00.000Z",

package/src/services/ClaimService.ts

@@ -538,7 +538,11 @@ export class ClaimService extends Effect.Service<ClaimService>()(
 									outcome: input.outcome,
 								}
 								return {
-									data: { ...data, status: input.outcome, claim },
+									data: {
+										...data,
+										status: input.outcome === "done" ? "working" : "dropped",
+										claim,
+									},
 									claim,
 								}
 							},

package/src/services/IntegrationService.test.ts

@@ -80,14 +80,15 @@ describe("IntegrationService", () => {
 		expect(body).toContain("External orchestrators claim before launching")
 		expect(body).toContain("Run `agency validate`")
 		expect(body).toContain("only with explicit user intent")
-		expect(body).toContain("An execution unit is `working`")
+		expect(body).toContain("An execution unit remains `working`")
 		expect(body).toContain("It becomes `done`")
-		expect(body).toContain("solely because its PR")
+		expect(body).toContain("Do not mark committed")
 		expect(body).toContain("creating or updating a PR")
 		expect(body).toContain("marking it ready")
 		expect(body).toMatch(/completing\s+a refinement loop/)
 		expect(body).toContain("pausing or handing off")
-		expect(body).toContain("`agency task status` or `agency phase status`")
+		expect(body).toContain("`agency finish`")
+		expect(body).toContain("`agency sync --apply`")
 		expect(body).toContain("`TASK.md` or `PHASE.md`")
 		expect(body).toContain("PR state, current head, diff summary")
 		expect(body).toContain("Run `agency validate` before reporting completion")

package/src/services/PhaseService.ts

@@ -487,6 +487,12 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 						})
 					}
 					if (!canTransitionStatus(record.data.status, validStatus)) {
+						if (validStatus === "done") {
+							return yield* new PhaseError({
+								message:
+									"Work becomes done after its authoritative pull request is merged; run 'agency sync --apply'",
+							})
+						}
 						return yield* new PhaseError({
 							message: `Cannot transition phase '${id}' from ${record.data.status} to ${validStatus}; reopen it first`,
 						})

package/src/services/PullRequestService.test.ts

@@ -263,11 +263,13 @@ process.exit(${exitCode})
 		await createTask()
 		await runTestEffect(
 			TaskService.pipe(
-				Effect.flatMap((service) => service.setStatus("example", "done", root)),
+				Effect.flatMap((service) =>
+					service.setStatus("example", "dropped", root),
+				),
 			),
 		)
 
-		await expect(createPullRequest()).rejects.toThrow("Task status is done")
+		await expect(createPullRequest()).rejects.toThrow("Task status is dropped")
 		expect(
 			await Bun.file(join(root, "tasks/example/code/agency")).exists(),
 		).toBe(false)

package/src/services/SyncService.test.ts

@@ -390,6 +390,99 @@ process.stdout.write(${JSON.stringify(JSON.stringify(record))})
 		expect("pr" in task.data && task.data.pr).toEqual(record)
 	})
 
+	test("marks a successfully finished claim done only after merge", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "finished-claim",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "feat/example",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("finished-claim", undefined, root),
+				),
+			),
+		)
+		await git(
+			["remote", "set-url", "origin", "git@github.com:example/agency.git"],
+			join(root, "repos/agency"),
+		)
+		const initial = await runTestEffect(
+			ClaimService.pipe(
+				Effect.flatMap((service) =>
+					service.inspect("finished-claim", undefined, root),
+				),
+			),
+		)
+		const claimed = await runTestEffect(
+			ClaimService.pipe(
+				Effect.flatMap((service) =>
+					service.claim(
+						{
+							taskId: "finished-claim",
+							claimant: "orchestrator",
+							runner: "agent",
+							sessionId: "session-1",
+							revision: initial.revision,
+						},
+						root,
+					),
+				),
+			),
+		)
+		const finished = await runTestEffect(
+			ClaimService.pipe(
+				Effect.flatMap((service) =>
+					service.finish(
+						{
+							taskId: "finished-claim",
+							sessionId: "session-1",
+							revision: claimed.revision,
+							outcome: "done",
+						},
+						root,
+					),
+				),
+			),
+		)
+		expect(finished.data).toMatchObject({
+			status: "working",
+			claim: { state: "finished", outcome: "done" },
+		})
+
+		const synced = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) =>
+					service.reconcile({ cwd: root, apply: true }),
+				),
+			),
+		)
+		expect(synced.changes.map((change) => change.kind)).toContain("mark-done")
+		expect(
+			await runTestEffect(
+				TaskService.pipe(
+					Effect.flatMap((service) => service.show("finished-claim", root)),
+				),
+			),
+		).toMatchObject({
+			data: {
+				status: "done",
+				claim: { state: "finished", outcome: "done" },
+			},
+		})
+	})
+
 	test("materializes missing workspaces but leaves branch conflicts unresolved", async () => {
 		for (const [id, branch] of [
 			["missing", "feat/missing"],

package/src/services/TaskPhaseService.test.ts

@@ -318,22 +318,23 @@ describe("task and phase services", () => {
 				),
 			),
 		).rejects.toThrow("Delegation requires explicit ownership")
-		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),
+						service.setStatus("single-status", "done", root),
 					),
 				),
 			),
-		).rejects.toThrow("reopen it first")
+		).rejects.toThrow("authoritative pull request is merged")
+		const droppedTask = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.setStatus("single-status", "dropped", root),
+				),
+			),
+		)
+		expect(droppedTask.data.status).toBe("dropped")
 
 		await runTestEffect(
 			TaskService.pipe(
@@ -389,7 +390,7 @@ describe("task and phase services", () => {
 					),
 				),
 			),
-		).rejects.toThrow("reopen it first")
+		).rejects.toThrow("authoritative pull request is merged")
 		await runTestEffect(
 			PhaseService.pipe(
 				Effect.flatMap((service) =>
@@ -397,17 +398,15 @@ describe("task and phase services", () => {
 				),
 			),
 		)
-		expect(
-			(
-				await runTestEffect(
-					PhaseService.pipe(
-						Effect.flatMap((service) =>
-							service.setStatus("multi-status", "implementation", "done", root),
-						),
+		await expect(
+			runTestEffect(
+				PhaseService.pipe(
+					Effect.flatMap((service) =>
+						service.setStatus("multi-status", "implementation", "done", root),
 					),
-				)
-			).data.status,
-		).toBe("done")
+				),
+			),
+		).rejects.toThrow("authoritative pull request is merged")
 		await expect(
 			runTestEffect(
 				TaskService.pipe(

package/src/services/TaskService.ts

@@ -270,6 +270,12 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 					})
 				}
 				if (!canTransitionStatus(record.data.status, validStatus)) {
+					if (validStatus === "done") {
+						return yield* new TaskError({
+							message:
+								"Work becomes done after its authoritative pull request is merged; run 'agency sync --apply'",
+						})
+					}
 					return yield* new TaskError({
 						message: `Cannot transition task '${id}' from ${record.data.status} to ${validStatus}; reopen it first`,
 					})

package/src/workbase/AGENTS.md

@@ -48,17 +48,19 @@ reason to edit `agency.json` or `repos/` by hand.
 
 ## Closeout
 
-An execution unit is `working` while implementation or requested delivery work
-remains. It becomes `done` when both are complete, even if its PR remains open
-for review or merge. Do not leave a task or phase `working` solely because its PR
-is open; if merge was requested, merge remains delivery work.
+An execution unit remains `working` after implementation is committed and while
+its pull request is open. It becomes `done` only after its authoritative pull
+request is merged and Agency reconciles that state. Do not mark committed or
+review-ready work `done` manually.
 
 At each closeout trigger (creating or updating a PR, marking it ready, completing
 a refinement loop, or pausing or handing off completed implementation work):
 
-- Finish an active claim with the current revision via `agency finish`.
-  Otherwise use `agency task status` or `agency phase status` to set the
-  execution unit's current status.
+- Finish an active claim with the current revision via `agency finish`; a
+  successful claim outcome leaves unmerged work `working`. For unclaimed work,
+  keep the execution unit `working` through review and merge.
+- After merge, run `agency sync --apply` to reconcile the execution unit to
+  `done`.
 - Refresh durable delivery context in `TASK.md` or `PHASE.md`, including recorded
   PR state, current head, diff summary, and verification results after later
   pushes when those details are maintained there.