@markjaquith/agency 2.48.1 → 2.50.0

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

@@ -8,6 +8,7 @@ import {
 	EntityId,
 	TaskFrontmatter,
 	type RepositoryReference,
+	type ReviewRecord,
 	type TaskFrontmatter as TaskData,
 	WorkStatus,
 } from "../workbase/schemas"
@@ -19,9 +20,14 @@ 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,
+	type TransactionStep,
 } from "./LifecycleTransaction"
 
 class TaskError extends Data.TaggedError("TaskError")<{
@@ -46,6 +52,7 @@ export interface CreateTaskInput {
 	readonly repos?: readonly RepositoryReference[]
 	readonly branch?: string
 	readonly base?: string
+	readonly review?: ReviewRecord
 }
 
 const decodeTask = (input: unknown) => {
@@ -74,6 +81,50 @@ const decodeStatus = (status: string) => {
 		: Effect.succeed(result.right)
 }
 
+const reviewPinRef = (taskId: string) =>
+	`refs/agency/reviews/${Buffer.from(taskId).toString("hex")}`
+
+const reviewPinStep = (
+	root: string,
+	taskId: string,
+	review: ReviewRecord,
+): TransactionStep => {
+	const repositoryPath = join(root, "repos", review.repo)
+	const ref = reviewPinRef(taskId)
+	const run = async (args: readonly string[]) => {
+		const child = Bun.spawn([...args], { stdout: "pipe", stderr: "pipe" })
+		const [exitCode, stderr] = await Promise.all([
+			child.exited,
+			new Response(child.stderr).text(),
+		])
+		if (exitCode !== 0) throw new Error(stderr.trim() || args.join(" "))
+	}
+	return {
+		label: `retain review pin for ${taskId}`,
+		apply: () =>
+			run([
+				"git",
+				"-C",
+				repositoryPath,
+				"update-ref",
+				ref,
+				review.commit,
+				"0".repeat(40),
+			]),
+		rollback: () =>
+			run([
+				"git",
+				"-C",
+				repositoryPath,
+				"update-ref",
+				"-d",
+				ref,
+				review.commit,
+			]),
+		manualRecovery: `Delete ${ref} from repository '${review.repo}'`,
+	}
+}
+
 export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 	sync: () => ({
 		create: (input: CreateTaskInput, startPath: string = process.cwd()) =>
@@ -98,7 +149,28 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 				}
 
 				let data: TaskData
-				if (input.multiPhase) {
+				if (input.review) {
+					if (
+						input.multiPhase ||
+						input.repo !== undefined ||
+						input.repos !== undefined ||
+						input.branch !== undefined ||
+						input.base !== undefined
+					) {
+						return yield* new TaskError({
+							message:
+								"Review tasks cannot include writable or multi-phase fields",
+						})
+					}
+					data = yield* decodeTask({
+						ticketUrl: input.ticketUrl,
+						...(input.description !== undefined
+							? { description: input.description }
+							: {}),
+						...(input.epic ? { epic: input.epic } : {}),
+						review: input.review,
+					})
+				} else if (input.multiPhase) {
 					data = yield* decodeTask({
 						ticketUrl: input.ticketUrl,
 						...(input.description !== undefined
@@ -128,12 +200,14 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 				}
 
 				const referencedRepos =
-					"repo" in data
-						? [
-								data.repo,
-								...(data.repos ?? []).map((reference) => reference.repo),
-							]
-						: []
+					"review" in data
+						? [data.review.repo]
+						: "repo" in data
+							? [
+									data.repo,
+									...(data.repos ?? []).map((reference) => reference.repo),
+								]
+							: []
 				if (new Set(referencedRepos).size !== referencedRepos.length) {
 					return yield* new TaskError({
 						message:
@@ -188,7 +262,10 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 					preconditions: parentEpic
 						? [{ path: parentEpic.path, revision: parentEpic.revision }]
 						: [],
-					steps: [documentWriteStep(root, writes)],
+					steps: [
+						...(input.review ? [reviewPinStep(root, id, input.review)] : []),
+						documentWriteStep(root, writes),
+					],
 				})
 
 				return {
@@ -247,6 +324,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 +347,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 && "pr" in record.data && 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 +389,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")

package/src/services/WorkbaseService.ts

@@ -712,7 +712,8 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 							)
 						}
 
-						const all = [writable, ...referenceAliases].filter(
+						const reviewAlias = "review" in data ? data.review.repo : undefined
+						const all = [writable, reviewAlias, ...referenceAliases].filter(
 							(alias): alias is string => alias !== undefined,
 						)
 						for (const alias of new Set(all)) {
@@ -746,6 +747,24 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 						}
 					}
 
+					const validateCompletion = (
+						record: DocumentRecord<TaskData | PhaseData>,
+					) => {
+						if (!("repo" in record.data) || !record.data.completion) return
+						if (record.data.status !== "done") {
+							issue(record.path, "Non-PR completion requires status 'done'")
+						}
+						if (record.data.pr !== null) {
+							issue(
+								record.path,
+								"Non-PR completion cannot have a recorded pull request",
+							)
+						}
+						if (record.data.claim?.state === "active") {
+							issue(record.path, "Completed work cannot have an active claim")
+						}
+					}
+
 					for (const epic of epics.values()) {
 						validateRepositories(epic)
 						const ids = new Set(epic.data.tasks.map((task) => task.id))
@@ -776,6 +795,7 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 					for (const task of tasks.values()) {
 						validateRepositories(task)
 						validateBranchOwnership(task)
+						validateCompletion(task)
 						if (task.data.epic) {
 							const parent = epics.get(task.data.epic)
 							if (!parent) {
@@ -828,6 +848,7 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 					for (const phase of phases.values()) {
 						validateRepositories(phase)
 						validateBranchOwnership(phase)
+						validateCompletion(phase)
 					}
 
 					issues.sort((a, b) =>

package/src/services/WorktreeService.test.ts

@@ -81,13 +81,13 @@ describe("WorktreeService", () => {
 		)
 
 		expect(
-			await Bun.file(join(workspace.writablePath, "README.md")).text(),
+			await Bun.file(join(workspace.writablePath!, "README.md")).text(),
 		).toBe("example\n")
 		expect(
 			await Bun.file(join(workspace.codePath, "effect/README.md")).text(),
 		).toBe("example\n")
 		const branch = Bun.spawnSync(
-			["git", "-C", workspace.writablePath, "branch", "--show-current"],
+			["git", "-C", workspace.writablePath!, "branch", "--show-current"],
 			{ stdout: "pipe" },
 		)
 		expect(new TextDecoder().decode(branch.stdout).trim()).toBe("task/example")
@@ -272,7 +272,7 @@ describe("WorktreeService", () => {
 			),
 		)
 		expect(
-			await Bun.file(join(workspace.writablePath, "README.md")).text(),
+			await Bun.file(join(workspace.writablePath!, "README.md")).text(),
 		).toBe("example\n")
 	})
 
@@ -599,7 +599,7 @@ pr: null
 
 		expect(
 			await Bun.file(
-				join(originalWorkspace.writablePath, "README.md"),
+				join(originalWorkspace.writablePath!, "README.md"),
 			).exists(),
 		).toBe(false)
 		const movedWorkspace = await runTestEffect(
@@ -613,10 +613,10 @@ pr: null
 			join(root, "tasks/promoted/phases/implementation/code/agency"),
 		)
 		expect(
-			await Bun.file(join(movedWorkspace.writablePath, "README.md")).text(),
+			await Bun.file(join(movedWorkspace.writablePath!, "README.md")).text(),
 		).toBe("example\n")
 		const status = Bun.spawnSync(
-			["git", "-C", movedWorkspace.writablePath, "status", "--porcelain"],
+			["git", "-C", movedWorkspace.writablePath!, "status", "--porcelain"],
 			{ stdout: "pipe", stderr: "pipe" },
 		)
 		expect(status.exitCode).toBe(0)
@@ -1072,7 +1072,7 @@ pr: null
 			),
 		)
 		await Bun.write(
-			join(workspace.writablePath, "uncommitted.txt"),
+			join(workspace.writablePath!, "uncommitted.txt"),
 			"keep me\n",
 		)
 
@@ -1084,7 +1084,7 @@ pr: null
 			),
 		).rejects.toThrow("Failed to remove worktree for 'agency'")
 		expect(
-			await Bun.file(join(workspace.writablePath, "uncommitted.txt")).text(),
+			await Bun.file(join(workspace.writablePath!, "uncommitted.txt")).text(),
 		).toBe("keep me\n")
 	})
 
@@ -1131,7 +1131,7 @@ pr: null
 			"--porcelain",
 		])
 		expect(new TextDecoder().decode(worktrees.stdout)).not.toContain(
-			workspace.writablePath,
+			workspace.writablePath!,
 		)
 		expect(
 			Bun.spawnSync([
@@ -1325,7 +1325,7 @@ pr: null
 			),
 		).rejects.toThrow("multiple Agency owners")
 		expect(
-			await Bun.file(join(workspace.writablePath, "README.md")).exists(),
+			await Bun.file(join(workspace.writablePath!, "README.md")).exists(),
 		).toBe(true)
 	})
 
@@ -1371,7 +1371,7 @@ pr: null
 			]),
 		)
 		expect(
-			await Bun.file(join(original.writablePath, "README.md")).exists(),
+			await Bun.file(join(original.writablePath!, "README.md")).exists(),
 		).toBe(true)
 
 		const rebuilt = await runTestEffect(
@@ -1383,7 +1383,7 @@ pr: null
 		)
 		expect(rebuilt.inspection.conflicts).toEqual([])
 		expect(
-			await Bun.file(join(original.writablePath, "README.md")).exists(),
+			await Bun.file(join(original.writablePath!, "README.md")).exists(),
 		).toBe(true)
 	})
 
@@ -1435,7 +1435,7 @@ pr: null
 			),
 		).rejects.toThrow("original worktrees were restored")
 		expect(
-			await Bun.file(join(workspace.writablePath, "README.md")).exists(),
+			await Bun.file(join(workspace.writablePath!, "README.md")).exists(),
 		).toBe(true)
 	})
 
@@ -1473,7 +1473,7 @@ pr: null
 			),
 		)
 		expect(plan.actions.join("\n")).toContain("worktree prune --expire now")
-		expect(plan.actions).toContain(`prepare ${workspace.writablePath}`)
+		expect(plan.actions).toContain(`prepare ${workspace.writablePath!}`)
 
 		const repaired = await runTestEffect(
 			WorktreeService.pipe(
@@ -1484,7 +1484,7 @@ pr: null
 		)
 		expect(repaired.inspection.conflicts).toEqual([])
 		expect(
-			await Bun.file(join(workspace.writablePath, "README.md")).exists(),
+			await Bun.file(join(workspace.writablePath!, "README.md")).exists(),
 		).toBe(true)
 		expect(
 			Bun.spawnSync([
@@ -1648,7 +1648,7 @@ pr: null
 			),
 		)
 		expect(
-			await Bun.file(join(workspace.writablePath, "README.md")).text(),
+			await Bun.file(join(workspace.writablePath!, "README.md")).text(),
 		).toBe("example\n")
 	})
 })