@markjaquith/agency 3.14.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.14.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/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/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):