@markjaquith/agency 2.48.1 → 2.49.0

package/src/services/GraphMutationService.ts

@@ -374,6 +374,16 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 							message: `Task '${id}' has an active claim; release or finish it before changing execution metadata`,
 						})
 					}
+					if (
+						updates.pr &&
+						"completion" in record.data &&
+						record.data.completion
+					) {
+						return yield* new GraphMutationError({
+							message:
+								"Reopen non-PR completed work before recording a pull request",
+						})
+					}
 					if (
 						executionChange &&
 						(yield* fs.isDirectory(join(dirname(record.path), "code")))
@@ -504,6 +514,12 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 							message: `Phase '${id}' has an active claim; release or finish it before changing execution metadata`,
 						})
 					}
+					if (updates.pr && record.data.completion) {
+						return yield* new GraphMutationError({
+							message:
+								"Reopen non-PR completed work before recording a pull request",
+						})
+					}
 					const data: PhaseData = yield* decode(
 						PhaseFrontmatter,
 						{

package/src/services/IntegrationService.test.ts

@@ -261,7 +261,9 @@ describe("IntegrationService", () => {
 		expect(body).toContain("Only `done` satisfies a dependency")
 		expect(body).toContain("Require explicit user intent")
 		expect(body).toContain("changing repository")
-		expect(body).toMatch(/archiving, restoring,\s+dropping, or/)
+		expect(body).toMatch(
+			/archiving, restoring,\s+dropping, reopening, or completing work without a pull request/,
+		)
 		expect(body).toContain("Never invent entity IDs")
 		expect(body).toContain("Preserve parent backlinks")
 		expect(body).toContain("dirty-worktree, active-claim, revision")
@@ -281,6 +283,7 @@ describe("IntegrationService", () => {
 		expect(body).toContain("pausing or handing off")
 		expect(body).toContain("`agency finish`")
 		expect(body).toContain("`agency sync --apply`")
+		expect(body).toContain("`--no-pull-request --summary <text>`")
 		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

@@ -26,6 +26,10 @@ import {
 	type TransactionStep,
 } from "./LifecycleTransaction"
 import { withWorktreeLocks } from "./WorktreeLock"
+import {
+	buildNonPrCompletion,
+	type NonPrCompletionInput,
+} from "../workbase/completion"
 
 class PhaseError extends Data.TaggedError("PhaseError")<{
 	readonly message: string
@@ -221,6 +225,9 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 							pr: task.data.pr,
 							status: task.data.status,
 							...(task.data.claim ? { claim: task.data.claim } : {}),
+							...(task.data.completion
+								? { completion: task.data.completion }
+								: {}),
 						})
 						const firstTitle = firstPhaseId!
 							.split("-")
@@ -469,6 +476,7 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 				id: string,
 				status: string,
 				startPath: string = process.cwd(),
+				nonPrCompletion?: NonPrCompletionInput,
 			) =>
 				Effect.gen(function* () {
 					const fs = yield* FileSystemService
@@ -486,11 +494,41 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 							message: `Phase '${id}' has an active claim; use agency release or agency finish`,
 						})
 					}
-					if (!canTransitionStatus(record.data.status, validStatus)) {
+					if (nonPrCompletion && validStatus !== "done") {
+						return yield* new PhaseError({
+							message: "Non-PR completion is valid only with a done status",
+						})
+					}
+					if (nonPrCompletion && record.data.pr !== null) {
+						return yield* new PhaseError({
+							message:
+								"Cannot complete without a pull request while an authoritative pull request is recorded",
+						})
+					}
+					const completionResult = nonPrCompletion
+						? buildNonPrCompletion(nonPrCompletion, new Date())
+						: undefined
+					if (completionResult && "error" in completionResult) {
+						return yield* new PhaseError({ message: completionResult.error })
+					}
+					if (
+						completionResult &&
+						record.data.status !== "open" &&
+						record.data.status !== "working" &&
+						record.data.status !== "delegated"
+					) {
+						return yield* new PhaseError({
+							message: `Cannot transition phase '${id}' from ${record.data.status} to done; reopen it first`,
+						})
+					}
+					if (
+						!canTransitionStatus(record.data.status, validStatus) &&
+						!completionResult
+					) {
 						if (validStatus === "done") {
 							return yield* new PhaseError({
 								message:
-									"Work becomes done after its authoritative pull request is merged; run 'agency sync --apply'",
+									"Work becomes done after its authoritative pull request is merged; run 'agency sync --apply', or explicitly complete a non-PR outcome with '--no-pull-request --summary <text>'",
 							})
 						}
 						return yield* new PhaseError({
@@ -498,7 +536,16 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 						})
 					}
 					const parsed = yield* parseFrontmatter(record.content, record.path)
-					const data = { ...record.data, status: validStatus }
+					const { completion: _, ...withoutCompletion } = record.data
+					const data: PhaseData = completionResult
+						? {
+								...record.data,
+								status: "done",
+								completion: completionResult.value,
+							}
+						: validStatus === "open"
+							? { ...withoutCompletion, status: validStatus }
+							: { ...record.data, status: validStatus }
 					const content = formatMarkdownDocument(data, parsed.body)
 					yield* fs.writeFile(record.path, content)
 					return {

package/src/services/PullRequestService.test.ts

@@ -279,6 +279,26 @@ process.exit(${exitCode})
 		expect(await createPullRequest("example", undefined, false, true)).toBe(url)
 	})
 
+	test("requires reopening non-PR completed work even when forced", async () => {
+		await createTask()
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.setStatus("example", "done", root, {
+						summary: "Investigation completed without changes.",
+					}),
+				),
+			),
+		)
+
+		await expect(
+			createPullRequest("example", undefined, false, true),
+		).rejects.toThrow("Reopen non-PR completed work")
+		expect(
+			await Bun.file(join(root, "tasks/example/code/agency")).exists(),
+		).toBe(false)
+	})
+
 	test("updates only PHASE.md for a phase PR", async () => {
 		await runTestEffect(
 			TaskService.pipe(

package/src/services/PullRequestService.ts

@@ -58,6 +58,12 @@ export class PullRequestService extends Effect.Service<PullRequestService>()(
 										message: `Task '${taskId}' requires a phase ID`,
 									})
 							: task
+					if ("completion" in target.data && target.data.completion) {
+						return yield* new PullRequestError({
+							message:
+								"Reopen non-PR completed work before recording a pull request",
+						})
+					}
 					const parsed = yield* parseFrontmatter(target.content, target.path)
 					yield* fs.writeFile(
 						target.path,
@@ -99,6 +105,21 @@ export class PullRequestService extends Effect.Service<PullRequestService>()(
 					const worktrees = yield* WorktreeService
 					const readiness = yield* ReadinessService
 					const workbase = yield* WorkbaseService
+					const task = yield* tasks.show(taskId, startPath)
+					const target =
+						"phases" in task.data
+							? phaseId
+								? yield* phases.show(taskId, phaseId, startPath)
+								: yield* new PullRequestError({
+										message: `Task '${taskId}' requires a phase ID`,
+									})
+							: task
+					if ("completion" in target.data && target.data.completion) {
+						return yield* new PullRequestError({
+							message:
+								"Reopen non-PR completed work before creating a pull request",
+						})
+					}
 					yield* readiness.guard(
 						"pr",
 						taskId,
@@ -112,11 +133,11 @@ export class PullRequestService extends Effect.Service<PullRequestService>()(
 						startPath,
 						options,
 					)
-					const task = yield* tasks.show(taskId, workspace.root)
+					const workspaceTask = yield* tasks.show(taskId, workspace.root)
 					const execution =
-						"phases" in task.data
+						"phases" in workspaceTask.data
 							? (yield* phases.show(taskId, phaseId!, workspace.root)).data
-							: task.data
+							: workspaceTask.data
 					const { config } = yield* workbase.loadConfig(workspace.root)
 					const remote = config.delivery?.remote ?? "origin"
 

package/src/services/SyncService.test.ts

@@ -8,6 +8,7 @@ import { PullRequestService } from "./PullRequestService"
 import { SyncService } from "./SyncService"
 import { TaskService } from "./TaskService"
 import { WorktreeService } from "./WorktreeService"
+import { WorkbaseService } from "./WorkbaseService"
 
 const git = async (args: string[], cwd?: string) => {
 	const process = Bun.spawn(["git", ...args], {
@@ -663,4 +664,69 @@ process.stdout.write(${JSON.stringify(JSON.stringify(record))})
 		)
 		expect(task.data).toMatchObject({ status: "open" })
 	})
+
+	test("leaves non-PR completion unchanged when a matching PR is discoverable", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "non-pr",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "feat/example",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.setStatus("non-pr", "done", root, {
+						summary: "Investigation completed without changes.",
+					}),
+				),
+			),
+		)
+
+		for (let attempt = 0; attempt < 2; attempt += 1) {
+			const applied = await runTestEffect(
+				SyncService.pipe(
+					Effect.flatMap((service) =>
+						service.reconcile({ cwd: root, apply: true }),
+					),
+				),
+			)
+			expect(
+				applied.changes.some(
+					(change) =>
+						change.kind === "record-pr" || change.kind === "mark-done",
+				),
+			).toBe(false)
+		}
+
+		const task = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) => service.show("non-pr", root)),
+			),
+		)
+		expect(task.data).toMatchObject({
+			status: "done",
+			pr: null,
+			completion: {
+				mode: "non-pr",
+				summary: "Investigation completed without changes.",
+			},
+		})
+		expect(
+			await runTestEffect(
+				WorkbaseService.pipe(
+					Effect.flatMap((service) => service.validate(root)),
+				),
+			),
+		).toMatchObject({ valid: true, issues: [] })
+	})
 })

package/src/services/SyncService.ts

@@ -580,6 +580,19 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 						})
 					}
 
+					if (data.completion) {
+						executions.push({
+							target: record.key,
+							status: data.status,
+							branch: data.branch,
+							base: data.base,
+							claim: data.claim ?? null,
+							checkouts: checkoutStates,
+							pr: { url: null, state: "none" },
+						})
+						continue
+					}
+
 					const existing = data.pr ? normalizePullRequestRecord(data.pr) : null
 					let current: PullRequestRecord | null = existing
 					let pr: Record<string, unknown> = existing ?? {

package/src/services/TaskPhaseService.test.ts

@@ -283,6 +283,66 @@ describe("task and phase services", () => {
 		})
 	})
 
+	test("preserves non-PR completion when converting a task to phases", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "completed",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/completed",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.setStatus("completed", "done", root, {
+						summary: "Investigation completed without changes.",
+					}),
+				),
+			),
+		)
+		await runTestEffect(
+			PhaseService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							taskId: "completed",
+							id: "follow-up",
+							firstPhase: "investigation",
+							repo: "agency",
+							branch: "task/completed-follow-up",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+
+		const firstPhase = await runTestEffect(
+			PhaseService.pipe(
+				Effect.flatMap((service) =>
+					service.show("completed", "investigation", root),
+				),
+			),
+		)
+		expect(firstPhase.data).toMatchObject({
+			status: "done",
+			completion: {
+				mode: "non-pr",
+				summary: "Investigation completed without changes.",
+			},
+		})
+	})
+
 	test("updates status on execution units", async () => {
 		const createdTask = await runTestEffect(
 			TaskService.pipe(
@@ -327,6 +387,50 @@ describe("task and phase services", () => {
 				),
 			),
 		).rejects.toThrow("authoritative pull request is merged")
+		const completedTask = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.setStatus("single-status", "done", root, {
+						summary: "Investigation completed without repository changes.",
+						evidenceUrl: "https://example.com/investigation",
+					}),
+				),
+			),
+		)
+		expect(completedTask.data).toMatchObject({
+			status: "done",
+			completion: {
+				mode: "non-pr",
+				summary: "Investigation completed without repository changes.",
+				evidenceUrl: "https://example.com/investigation",
+			},
+		})
+		expect(completedTask.data.completion?.completedAt).toMatch(
+			/^\d{4}-\d{2}-\d{2}T/,
+		)
+		await expect(
+			runTestEffect(
+				PullRequestService.pipe(
+					Effect.flatMap((service) =>
+						service.setUrl(
+							"single-status",
+							undefined,
+							"https://github.com/example/agency/pull/1",
+							root,
+						),
+					),
+				),
+			),
+		).rejects.toThrow("Reopen non-PR completed work")
+		const reopenedTask = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.setStatus("single-status", "open", root),
+				),
+			),
+		)
+		expect(reopenedTask.data.status).toBe("open")
+		expect("completion" in reopenedTask.data).toBe(false)
 		const droppedTask = await runTestEffect(
 			TaskService.pipe(
 				Effect.flatMap((service) =>
@@ -335,6 +439,17 @@ describe("task and phase services", () => {
 			),
 		)
 		expect(droppedTask.data.status).toBe("dropped")
+		await expect(
+			runTestEffect(
+				TaskService.pipe(
+					Effect.flatMap((service) =>
+						service.setStatus("single-status", "done", root, {
+							summary: "Cannot bypass reopening.",
+						}),
+					),
+				),
+			),
+		).rejects.toThrow("reopen it first")
 
 		await runTestEffect(
 			TaskService.pipe(
@@ -407,6 +522,73 @@ describe("task and phase services", () => {
 				),
 			),
 		).rejects.toThrow("authoritative pull request is merged")
+		await expect(
+			runTestEffect(
+				PhaseService.pipe(
+					Effect.flatMap((service) =>
+						service.setStatus("multi-status", "implementation", "done", root, {
+							summary: "   ",
+						}),
+					),
+				),
+			),
+		).rejects.toThrow("summary must not be empty")
+		const completedPhase = await runTestEffect(
+			PhaseService.pipe(
+				Effect.flatMap((service) =>
+					service.setStatus("multi-status", "implementation", "done", root, {
+						summary: "Operational work completed outside the repository.",
+					}),
+				),
+			),
+		)
+		expect(completedPhase.data).toMatchObject({
+			status: "done",
+			completion: {
+				mode: "non-pr",
+				summary: "Operational work completed outside the repository.",
+			},
+		})
+
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "recorded-pr",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/recorded-pr",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await runTestEffect(
+			PullRequestService.pipe(
+				Effect.flatMap((service) =>
+					service.setUrl(
+						"recorded-pr",
+						undefined,
+						"https://github.com/example/agency/pull/1",
+						root,
+					),
+				),
+			),
+		)
+		await expect(
+			runTestEffect(
+				TaskService.pipe(
+					Effect.flatMap((service) =>
+						service.setStatus("recorded-pr", "done", root, {
+							summary: "Attempted bypass",
+						}),
+					),
+				),
+			),
+		).rejects.toThrow("authoritative pull request is recorded")
 		await expect(
 			runTestEffect(
 				TaskService.pipe(

package/src/services/TaskService.ts

@@ -19,6 +19,10 @@ import {
 import { canTransitionStatus } from "../readiness"
 import { documentRevision } from "../workbase/document-revision"
 import { archivedTaskDirectory } from "../workbase/archive"
+import {
+	buildNonPrCompletion,
+	type NonPrCompletionInput,
+} from "../workbase/completion"
 import {
 	documentWriteStep,
 	runLifecycleTransaction,
@@ -247,6 +251,7 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 			id: string,
 			status: string,
 			startPath: string = process.cwd(),
+			nonPrCompletion?: NonPrCompletionInput,
 		) =>
 			Effect.gen(function* () {
 				const fs = yield* FileSystemService
@@ -269,11 +274,41 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 						message: `Task '${id}' has an active claim; use agency release or agency finish`,
 					})
 				}
-				if (!canTransitionStatus(record.data.status, validStatus)) {
+				if (nonPrCompletion && validStatus !== "done") {
+					return yield* new TaskError({
+						message: "Non-PR completion is valid only with a done status",
+					})
+				}
+				if (nonPrCompletion && record.data.pr !== null) {
+					return yield* new TaskError({
+						message:
+							"Cannot complete without a pull request while an authoritative pull request is recorded",
+					})
+				}
+				const completionResult = nonPrCompletion
+					? buildNonPrCompletion(nonPrCompletion, new Date())
+					: undefined
+				if (completionResult && "error" in completionResult) {
+					return yield* new TaskError({ message: completionResult.error })
+				}
+				if (
+					completionResult &&
+					record.data.status !== "open" &&
+					record.data.status !== "working" &&
+					record.data.status !== "delegated"
+				) {
+					return yield* new TaskError({
+						message: `Cannot transition task '${id}' from ${record.data.status} to done; reopen it first`,
+					})
+				}
+				if (
+					!canTransitionStatus(record.data.status, validStatus) &&
+					!completionResult
+				) {
 					if (validStatus === "done") {
 						return yield* new TaskError({
 							message:
-								"Work becomes done after its authoritative pull request is merged; run 'agency sync --apply'",
+								"Work becomes done after its authoritative pull request is merged; run 'agency sync --apply', or explicitly complete a non-PR outcome with '--no-pull-request --summary <text>'",
 						})
 					}
 					return yield* new TaskError({
@@ -281,7 +316,16 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 					})
 				}
 				const parsed = yield* parseFrontmatter(record.content, record.path)
-				const data = { ...record.data, status: validStatus }
+				const { completion: _, ...withoutCompletion } = record.data
+				const data: TaskData = completionResult
+					? {
+							...record.data,
+							status: "done",
+							completion: completionResult.value,
+						}
+					: validStatus === "open"
+						? { ...withoutCompletion, status: validStatus }
+						: { ...record.data, status: validStatus }
 				const content = formatMarkdownDocument(data, parsed.body)
 				yield* fs.writeFile(record.path, content)
 				return {

package/src/services/WorkbaseService.test.ts

@@ -73,6 +73,64 @@ pr: null
 		expect(report.issues).toEqual([])
 	})
 
+	test("validates non-PR completion invariants without rejecting legacy done work", async () => {
+		await write(
+			root,
+			"agency.json",
+			JSON.stringify({
+				version: 2,
+				repositories: {
+					agency: { remote: "https://example.com/agency.git" },
+				},
+			}),
+		)
+		await write(
+			root,
+			"tasks/invalid/TASK.md",
+			`---
+ticketUrl: null
+repo: agency
+branch: task/invalid
+base: main
+pr: https://github.com/example/agency/pull/1
+status: working
+completion:
+  mode: non-pr
+  completedAt: 2026-07-23T18:00:00.000Z
+  summary: Investigation completed.
+---
+`,
+		)
+		await write(
+			root,
+			"tasks/legacy/TASK.md",
+			`---
+ticketUrl: null
+repo: agency
+branch: task/legacy
+base: main
+pr: null
+status: done
+---
+`,
+		)
+
+		const report = await runTestEffect(
+			WorkbaseService.pipe(Effect.flatMap((service) => service.validate(root))),
+		)
+		expect(report.issues).toContainEqual({
+			path: "tasks/invalid/TASK.md",
+			message: "Non-PR completion requires status 'done'",
+		})
+		expect(report.issues).toContainEqual({
+			path: "tasks/invalid/TASK.md",
+			message: "Non-PR completion cannot have a recorded pull request",
+		})
+		expect(
+			report.issues.some((issue) => issue.path === "tasks/legacy/TASK.md"),
+		).toBe(false)
+	})
+
 	test("registers canonical workbase paths without duplicates", async () => {
 		const workbaseRoot = join(root, "workbase")
 		const nested = join(workbaseRoot, "nested")