@markjaquith/agency 3.13.0 → 3.15.0

package/README.md

@@ -710,7 +710,7 @@ external chooser continues to offer goals and **Browse items** through that choo
 | Split work                           | Add a phase / split this task; name the existing work's first phase                         | `split`                                                                                                                                            |
 | Work on a task or phase              | Work on this item                                                                           | `work`                                                                                                                                             |
 | Move from investigation to execution | Create implementation follow-up                                                             | `handoff`                                                                                                                                          |
-| Review someone else's work           | Review a PR, or a remote branch/commit                                                      | `review`, `review-ref`                                                                                                                             |
+| Review someone else's work           | Review a PR, or a remote branch/commit; finish a review                                     | `review`, `review-ref`, `finish-review`                                                                                                            |
 | Publish or update PR status          | Push without a PR, refresh provider state, create a PR, mark a GitHub PR ready, or close it | `push`, `sync`, `pr`, `pr-ready`, `pr-close`                                                                                                       |
 | Maintain review work                 | Fetch and repin a review task to its current source                                         | `review-refresh`                                                                                                                                   |
 | Organize work                        | Rename an item, move a task into/out of an epic, or add/remove a sibling dependency         | `rename`, `move-to-epic`, `remove-from-epic`, `dependency-add`, `dependency-remove`                                                                |
@@ -723,7 +723,9 @@ on the new item now** or **Finish**. Only choosing Work prepares checkouts and
 launches the configured runner; creation alone leaves the item for later.
 Investigation handoff creates a distinct implementation item with source and
 revision provenance. Completing a non-PR outcome requires a durable summary.
-PR-backed completion comes from provider reconciliation after merge.
+**Finish review** marks a review task done without a summary; review tasks offer
+it instead of non-PR completion. PR-backed completion comes from provider
+reconciliation after merge.
 
 **Refresh Agency state** reads the provider and reconciles local records. The
 explicit **GitHub PR ready/close** actions mutate the recorded GitHub URL, then
@@ -1060,6 +1062,7 @@ Create a pinned, read-only review task from the selected alias's origin:
 agency task create <id> --review <alias> --pull-request <url-or-number>
 agency task create <id> --review <alias> --ref <remote-ref>
 agency review refresh <id> [--if-revision <hash>] [--json]
+agency review finish <id> [--if-revision <hash>] [--json]
 ```
 
 Review creation fetches the source and records its exact 40-character commit.
@@ -1069,7 +1072,10 @@ detached checkout and no writable branch. Source movement is observed separately
 from the pin and applied only by `review refresh`; sync, doctor, work, cleanup,
 and archive never move the pin implicitly. Dirty or structurally unexpected
 review checkouts block refresh and cleanup. Review tasks support the normal status
-lifecycle, but reject phase conversion and delivery PR operations.
+lifecycle, but reject phase conversion and delivery PR operations. Because a
+review has no delivery pull request, `review finish` marks an open, working, or
+delegated review done without the `--no-pull-request --summary` requirement
+that applies to other work.
 Each active or archived review task owns one internal task-scoped pin ref. A
 refresh advances that ref transactionally; failed creation removes it. Archiving
 retains the pin so a deleted source can still be restored and inspected.

package/cli-main.ts

@@ -726,7 +726,7 @@ Commands:
   next                   List or select ready execution units
   pr create / pr [...]  Create an Agency PR or run gh pr with repository focus
   push                   Validate and publish the current execution unit
-  review refresh         Explicitly refresh a pinned review task
+  review refresh|finish  Refresh or finish a pinned review task
   repo <subcommand>      Manage workbase repositories
   status                 Show status for the current workbase
   doctor                 Diagnose workbase health and integrations

package/package.json

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

package/src/cli-parser.ts

@@ -783,7 +783,8 @@ const commands = {
 		},
 	},
 	review: {
-		usage: "agency review refresh <task-id> [--if-revision <hash>] [--json]",
+		usage:
+			"agency review <refresh|finish> <task-id> [--if-revision <hash>] [--json]",
 		options: {
 			...outputOptions,
 			"if-revision": { type: "string" },
@@ -796,6 +797,12 @@ const commands = {
 				maxArgs: 1,
 				options: ["if-revision", "json"],
 			},
+			finish: {
+				usage: "agency review finish <task-id> [--if-revision <hash>] [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["if-revision", "json"],
+			},
 		},
 	},
 	worktree: {

package/src/commands/act-actions.ts

@@ -234,6 +234,11 @@ const actionPresentation: Record<
 		icon: "󰑐",
 		color: macchiato.sapphire,
 	},
+	"finish-review": {
+		description: "Mark this review done; no completion summary is required.",
+		icon: "󰄬",
+		color: macchiato.green,
+	},
 	reopen: {
 		description: "Return terminal work to open status.",
 		icon: "󰑓",
@@ -371,7 +376,7 @@ export const actionGroups = [
 		id: "review",
 		label: "Review someone else's work",
 		icon: "󰍉",
-		actions: ["review", "review-ref"],
+		actions: ["review", "review-ref", "finish-review"],
 	},
 	{
 		id: "split",
@@ -875,6 +880,7 @@ export const actActions = (
 	const purpose =
 		parent && "purpose" in parent.data ? parent.data.purpose : undefined
 	const terminal = node.status === "done" || node.status === "dropped"
+	const isReview = node.kind === "task" && "review" in node.data
 	const blockers = (execution ?? node).readiness.blockers
 	const validation = blockers.find(
 		(blocker) => blocker.kind === "validation",
@@ -1044,9 +1050,7 @@ export const actActions = (
 			details(
 				"review-refresh",
 				"Refresh review source",
-				node.kind === "task" && "review" in node.data
-					? null
-					: "Select a review task",
+				isReview ? null : "Select a review task",
 			),
 			{
 				command: [
@@ -1065,6 +1069,33 @@ export const actActions = (
 				}),
 			},
 		),
+		immediate(
+			details(
+				"finish-review",
+				"Finish review",
+				!isReview
+					? "Select a review task"
+					: terminal
+						? "Review is already terminal"
+						: null,
+			),
+			{
+				command: [
+					"agency",
+					"review",
+					"finish",
+					target.taskId,
+					"--if-revision",
+					node.data.sha256,
+				],
+				run: review({
+					...options,
+					subcommand: "finish",
+					taskId: target.taskId,
+					ifRevision: node.data.sha256,
+				}),
+			},
+		),
 		...(["reopen", "drop"] as const).map((id) => {
 			const status = id === "reopen" ? "open" : "dropped"
 			return immediate(
@@ -1300,11 +1331,13 @@ export const actActions = (
 					"complete",
 					"Complete without a pull request",
 					noExecution ??
-						(terminal
-							? "Item is already terminal"
-							: prUrl
-								? "Reconcile the recorded pull request instead"
-								: null),
+						(isReview
+							? "Use Finish review for review tasks"
+							: terminal
+								? "Item is already terminal"
+								: prUrl
+									? "Reconcile the recorded pull request instead"
+									: null),
 				),
 				inputs: [
 					input("summary", "Completed outcome summary", { multiline: true }),

package/src/commands/review.ts

@@ -12,17 +12,34 @@ interface ReviewOptions extends BaseCommandOptions {
 
 export const review = (options: ReviewOptions) =>
 	Effect.gen(function* () {
-		if (options.subcommand !== "refresh" || !options.taskId) {
+		if (
+			(options.subcommand !== "refresh" && options.subcommand !== "finish") ||
+			!options.taskId
+		) {
 			return yield* Effect.fail(
-				new Error("Usage: agency review refresh <task>"),
+				new Error("Usage: agency review <refresh|finish> <task>"),
 			)
 		}
-		const result = yield* (yield* ReviewService).refresh(
+		const service = yield* ReviewService
+		const { log } = createLoggers(options)
+		if (options.subcommand === "finish") {
+			const result = yield* service.finish(
+				options.taskId,
+				options.cwd,
+				options.ifRevision,
+			)
+			log(
+				options.json
+					? JSON.stringify(result, null, 2)
+					: `Finished review '${options.taskId}'`,
+			)
+			return
+		}
+		const result = yield* service.refresh(
 			options.taskId,
 			options.cwd,
 			options.ifRevision,
 		)
-		const { log } = createLoggers(options)
 		log(
 			options.json
 				? JSON.stringify(result, null, 2)
@@ -31,8 +48,12 @@ export const review = (options: ReviewOptions) =>
 	})
 
 export const help = `
-Usage: agency review refresh <task-id> [--if-revision <hash>] [--json]
+Usage: agency review <refresh|finish> <task-id> [--if-revision <hash>] [--json]
 
-Fetch the review source explicitly and replace the pinned commit and any clean,
-detached review checkout. Review sources never move implicitly.
+Subcommands:
+  refresh    Fetch the review source explicitly and replace the pinned commit
+             and any clean, detached review checkout. Review sources never
+             move implicitly.
+  finish     Mark an open, working, or delegated review task done. Reviews
+             have no delivery pull request and need no completion summary.
 `

package/src/commands/sync.ts

@@ -138,6 +138,7 @@ Options:
 
 Sync may materialize declared repositories and unambiguous missing checkouts,
 adopt legacy repositories with portable origins, record a uniquely matched PR,
-and mark merged work done. Dirty, stale, or
+adopt a recorded PR's retargeted base or renamed head branch, and mark merged
+work done. Dirty, stale, or
 conflicting checkouts are always left unresolved.
 `

package/src/services/ReviewService.ts

@@ -424,6 +424,51 @@ export class ReviewService extends Effect.Service<ReviewService>()(
 						}),
 					)
 				}),
+
+			finish: (
+				taskId: string,
+				startPath: string = process.cwd(),
+				ifRevision?: string,
+			) =>
+				Effect.gen(function* () {
+					const workbase = yield* WorkbaseService
+					const tasks = yield* TaskService
+					const root = yield* workbase.discover(startPath)
+					const task = yield* tasks.show(taskId, root)
+					if (!("review" in task.data)) {
+						return yield* new ReviewError({
+							message: `Task '${taskId}' is not a review task`,
+						})
+					}
+					if (ifRevision && task.revision !== ifRevision) {
+						return yield* new RevisionConflictError({
+							path: task.path,
+							target: `task '${taskId}'`,
+							expectedRevision: ifRevision,
+							currentRevision: task.revision,
+							message: `Revision conflict for task '${taskId}'`,
+						})
+					}
+					if (task.data.status === "done" || task.data.status === "dropped") {
+						return yield* new ReviewError({
+							message: `Cannot finish review task '${taskId}' from ${task.data.status}; reopen it first`,
+						})
+					}
+					const parsed = yield* parseFrontmatter(task.content, task.path)
+					const data = { ...task.data, status: "done" as const }
+					const content = formatMarkdownDocument(data, parsed.body)
+					yield* runLifecycleTransaction({
+						root,
+						preconditions: [{ path: task.path, revision: task.revision }],
+						steps: [documentWriteStep(root, [{ path: task.path, content }])],
+					})
+					return {
+						id: taskId,
+						path: task.path,
+						revision: documentRevision(content),
+						data,
+					}
+				}),
 		}),
 	},
 ) {}

package/src/services/SyncService.ts

@@ -58,7 +58,12 @@ interface RegisteredWorktree {
 }
 
 interface SyncChange {
-	readonly kind: "materialize-workspace" | "record-pr" | "mark-done"
+	readonly kind:
+		| "materialize-workspace"
+		| "adopt-pr-branch"
+		| "adopt-pr-base"
+		| "record-pr"
+		| "mark-done"
 	readonly target: string
 	readonly message: string
 	readonly status: "planned" | "applied"
@@ -162,14 +167,34 @@ interface PullRequestQuery {
 		| undefined
 }
 
+const canonicalRecord = (record: PullRequestRecord | null) =>
+	record
+		? JSON.stringify(
+				Object.entries(record)
+					.filter(([, value]) => value !== undefined)
+					.sort(([a], [b]) => a.localeCompare(b)),
+			)
+		: null
+
+const samePullRequestRecord = (
+	current: PullRequestRecord,
+	existing: PullRequestRecord | null,
+) => canonicalRecord(current) === canonicalRecord(existing)
+
+const belongsToWritableRepository = (
+	current: PullRequestRecord,
+	remoteRepository: string,
+) =>
+	current.headRepository?.toLowerCase() === remoteRepository.toLowerCase() &&
+	current.baseRepository?.toLowerCase() === current.repository.toLowerCase()
+
 const mergedPullRequestFromGitHub = (
 	data: ExecutionData,
 	query: PullRequestQuery | undefined,
 	details: readonly PullRequestRecord[] | undefined,
 ) => {
 	if (!query?.result || query.result.exitCode !== 0 || !details) return null
-	const existing = data.pr ? normalizePullRequestRecord(data.pr) : null
-	const matches = existing
+	const matches = data.pr
 		? details
 		: details.filter(
 				(item) =>
@@ -177,18 +202,10 @@ const mergedPullRequestFromGitHub = (
 			)
 	if (matches.length !== 1) return null
 	const current = matches[0]!
-	if (
-		current.merged !== true ||
-		current.headRepository?.toLowerCase() !==
-			query.remoteRepository.toLowerCase() ||
-		current.headBranch !== data.branch ||
-		current.baseRepository?.toLowerCase() !==
-			current.repository.toLowerCase() ||
-		current.baseBranch !== data.base
-	) {
-		return null
-	}
-	return current
+	return current.merged === true &&
+		belongsToWritableRepository(current, query.remoteRepository)
+		? current
+		: null
 }
 
 const mutateExecution = (
@@ -650,6 +667,22 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 					{ concurrency: 8 },
 				)
 
+				const branchOwners = new Map<string, string>()
+				const branchKey = (repo: string, branch: string) =>
+					JSON.stringify([repo, branch])
+				for (const task of allTaskRecords) {
+					if ("repo" in task.data)
+						branchOwners.set(
+							branchKey(task.data.repo, task.data.branch),
+							`task:${task.id}`,
+						)
+					for (const phase of documents.phasesByTask.get(task.id) ?? [])
+						branchOwners.set(
+							branchKey(phase.data.repo, phase.data.branch),
+							`phase:${task.id}/${phase.id}`,
+						)
+				}
+
 				for (const record of records.sort((a, b) =>
 					a.key.localeCompare(b.key),
 				)) {
@@ -662,6 +695,126 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 					const githubDetails = githubResponse?.ok
 						? githubResponse.details
 						: undefined
+					let renamedFrom: string | null = null
+					let adoptionConflict = false
+					const recordedPr =
+						!config.delivery && data.pr ? githubDetails?.[0] : undefined
+					if (
+						query &&
+						recordedPr?.headBranch &&
+						recordedPr.baseBranch &&
+						belongsToWritableRepository(recordedPr, query.remoteRepository) &&
+						(recordedPr.headBranch !== data.branch ||
+							recordedPr.baseBranch !== data.base)
+					) {
+						const previous = { branch: data.branch, base: data.base }
+						const adopted = {
+							branch: recordedPr.headBranch,
+							base: recordedPr.baseBranch,
+						}
+						const repositoryPath = join(root, "repos", data.repo)
+						let renameLocal = false
+						if (adopted.branch !== previous.branch) {
+							const owner = branchOwners.get(
+								branchKey(data.repo, adopted.branch),
+							)
+							const [previousLocal, adoptedLocal] = yield* Effect.all([
+								backend.resolveRevision(
+									repositoryPath,
+									`refs/heads/${previous.branch}`,
+								),
+								backend.resolveRevision(
+									repositoryPath,
+									`refs/heads/${adopted.branch}`,
+								),
+							])
+							if (owner && owner !== record.key) {
+								adoptionConflict = true
+								unresolved.push({
+									kind: "pr-branch-conflict",
+									target: record.key,
+									message: `Recorded PR head '${adopted.branch}' is declared by '${owner}'`,
+									action:
+										"Correct the recorded PR URL or the other declaration",
+								})
+							} else if (previousLocal && adoptedLocal) {
+								adoptionConflict = true
+								unresolved.push({
+									kind: "pr-branch-conflict",
+									target: record.key,
+									message: `Cannot rename local branch '${previous.branch}' to recorded PR head '${adopted.branch}' because it already exists`,
+									action: `Reconcile or delete local branch '${adopted.branch}' manually`,
+								})
+							} else {
+								renameLocal = previousLocal !== null
+							}
+						}
+						if (!adoptionConflict && apply) {
+							const renameBranch = (from: string, to: string) =>
+								runExternal(["git", "branch", "-m", from, to], {
+									cwd: repositoryPath,
+								})
+							const renamed = renameLocal
+								? yield* renameBranch(previous.branch, adopted.branch)
+								: null
+							if (renamed && renamed.exitCode !== 0) {
+								adoptionConflict = true
+								unresolved.push({
+									kind: "pr-branch-rename-failed",
+									target: record.key,
+									message: `Could not rename local branch '${previous.branch}' to '${adopted.branch}': ${commandErrorSummary(renamed.stderr, "git branch failed")}`,
+									action: "Rename the local branch manually",
+								})
+							} else {
+								const updated = yield* mutateExecution(root, record, revision, {
+									...data,
+									...adopted,
+								}).pipe(
+									Effect.tapError(() =>
+										renamed
+											? renameBranch(adopted.branch, previous.branch)
+											: Effect.void,
+									),
+								)
+								data = updated.data
+								revision = updated.revision
+								const cached = registeredByRepository.get(repositoryPath)
+								for (const [index, item] of (cached ?? []).entries()) {
+									if (item.branch === `refs/heads/${previous.branch}`)
+										cached![index] = {
+											...item,
+											branch: `refs/heads/${adopted.branch}`,
+										}
+								}
+							}
+						} else if (!adoptionConflict) {
+							data = { ...data, ...adopted }
+							if (renameLocal) renamedFrom = previous.branch
+						}
+						if (!adoptionConflict) {
+							if (adopted.branch !== previous.branch) {
+								branchOwners.delete(branchKey(data.repo, previous.branch))
+								branchOwners.set(
+									branchKey(data.repo, adopted.branch),
+									record.key,
+								)
+								changes.push({
+									kind: "adopt-pr-branch",
+									target: record.key,
+									message: `Adopt pull request head '${adopted.branch}' (was '${previous.branch}')`,
+									status: apply ? "applied" : "planned",
+								})
+							}
+							if (adopted.base !== previous.base) {
+								changes.push({
+									kind: "adopt-pr-base",
+									target: record.key,
+									message: `Adopt pull request base '${adopted.base}' (was '${previous.base}')`,
+									status: apply ? "applied" : "planned",
+								})
+							}
+						}
+					}
 					const remoteMergedPr = config.delivery
 						? null
 						: mergedPullRequestFromGitHub(data, query, githubDetails)
@@ -838,7 +991,12 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 								action: "Review and preserve or discard local changes manually",
 							})
 						}
-						if (atPath && branchRef && atPath.branch !== branchRef) {
+						if (
+							atPath &&
+							branchRef &&
+							atPath.branch !== branchRef &&
+							!(renamedFrom && atPath.branch === `refs/heads/${renamedFrom}`)
+						) {
 							unresolved.push({
 								kind: "wrong-branch",
 								target: record.key,
@@ -1022,21 +1180,26 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 							if (githubDetails) {
 								current = githubDetails[0]!
 								pr = current
-								if (
-									current.headRepository?.toLowerCase() !==
-										remoteRepository.toLowerCase() ||
-									current.headBranch !== data.branch ||
-									current.baseRepository?.toLowerCase() !==
-										current.repository.toLowerCase() ||
-									current.baseBranch !== data.base
-								) {
+								if (!belongsToWritableRepository(current, remoteRepository)) {
 									prConflict = true
 									unresolved.push({
 										kind: "pr-repository-conflict",
 										target: record.key,
-										message: `Recorded PR head does not match '${remoteRepository}:${data.branch}' or base '${current.repository}:${data.base}'`,
+										message: `Recorded PR repositories do not match writable repository '${remoteRepository}' and base '${current.repository}'`,
 										action: "Correct the declaration or recorded PR URL",
 									})
+								} else if (
+									current.headBranch !== data.branch ||
+									current.baseBranch !== data.base
+								) {
+									prConflict = true
+									if (!adoptionConflict)
+										unresolved.push({
+											kind: "pr-branch-conflict",
+											target: record.key,
+											message: `Recorded PR head '${current.headBranch ?? "unknown"}' or base '${current.baseBranch ?? "unknown"}' could not be adopted`,
+											action: "Correct the declaration or recorded PR URL",
+										})
 								}
 							}
 						} else {
@@ -1092,7 +1255,7 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 						}
 					}
 
-					if (current && JSON.stringify(current) !== JSON.stringify(existing)) {
+					if (current && !samePullRequestRecord(current, existing)) {
 						if (apply) {
 							const recorded = yield* mutateExecution(root, record, revision, {
 								...data,

package/src/services/TaskService.ts

@@ -652,6 +652,15 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 					!canTransitionStatus(record.data.status, validStatus) &&
 					!completionResult
 				) {
+					if (
+						validStatus === "done" &&
+						"review" in record.data &&
+						record.data.status !== "dropped"
+					) {
+						return yield* new TaskError({
+							message: `Finish review task '${id}' with 'agency review finish ${id}'; reviews do not require a completion summary`,
+						})
+					}
 					if (validStatus === "done") {
 						return yield* new TaskError({
 							message:

package/src/workbase/AGENTS.md

@@ -108,6 +108,8 @@ retain `--if-revision` guards when shown, and do not add flags that are not show
     `agency context <new-task> --json`. Do not prepare or start it unless requested.
 15. Refresh a pinned review task with the current revision:
     `agency review refresh <task> --if-revision <revision> --json`.
+16. Finish a review task with the current revision; no summary is required:
+    `agency review finish <task> --if-revision <revision> --json`.
 
 Never pass `--work` or `--auto` to `agency task create`. Do not run separate
 `agency validate`, `agency worktree prepare`, `agency graph`, `agency task list`,
@@ -182,8 +184,8 @@ agency validate --json
 Require explicit user intent before initializing a workbase; changing repository
 aliases or applying repository setup or workbase sync changes; launching another
 agent from an active agent session; creating a pull request; archiving, restoring,
-dropping, reopening, or completing work without a pull request; or using `--force`
-to override readiness.
+dropping, reopening, finishing a review, or completing work without a pull
+request; or using `--force` to override readiness.
 
 ## Investigation Handoffs
 
@@ -272,7 +274,9 @@ 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. A genuine investigation, operational action,
 or no-change result may complete without a pull request only with explicit user
-intent, `--no-pull-request`, and a durable outcome summary.
+intent, `--no-pull-request`, and a durable outcome summary. A review task has no
+delivery pull request; with explicit user intent, finish it with
+`agency review finish` instead, which requires no summary.
 
 At each closeout trigger (creating or updating a PR, marking it ready, completing
 a refinement loop, or pausing or handing off completed implementation work):