@markjaquith/agency 3.14.0 → 3.16.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.
@@ -1223,6 +1229,35 @@ parent epic implicitly. Versioned lifecycle provenance preserves parent
 declarations and dependency edges for restoration. Archived IDs are reserved
 until restored.
 
+#### Automatic archiving
+
+```text
+agency config auto-archive                 # show the effective setting
+agency config auto-archive on              # enable for this workbase
+agency config auto-archive off             # disable
+```
+
+The boolean `autoArchive` setting in the workbase's `agency.json` defaults to
+`false`. Enabling it authorizes automatic task archiving on future terminal
+transitions; it does not sweep existing terminal work. `agency act --json`
+lists these configuration commands, and context/status JSON includes the
+effective setting.
+
+Explicit `task status` / `phase status` changes to `done` or `dropped`, non-PR
+completion, `review finish`, and merged-PR reconciliation automatically
+attempt to archive the owning task. A multi-phase task waits until every phase
+is terminal; individual phases and epics are never auto-archived. Sync defers
+cleanup until its reconciliation pass finishes, and `sync --dry-run` never
+archives anything.
+
+Automatic cleanup uses the same preflight as `archive task --dry-run`, without
+forcing past dirty checkouts, retained dependents, or other safety
+failures. A blocked attempt leaves the terminal status intact and the task
+unarchived, with the reason reported in human output and the triggering command's
+JSON `autoArchive` result (`sync` returns an array). After resolving the blocker,
+use explicit `archive` to retry safely. Successful automatic archiving removes
+clean managed checkouts, so paths inside the task may cease to exist.
+
 ### Work, Publication, and Pull Requests
 
 ```text

package/cli-main.ts

@@ -10,6 +10,7 @@ import { push, help as pushHelp } from "./src/commands/push"
 import { work, workPrepare, help as workHelp } from "./src/commands/work"
 import { worktree, help as worktreeHelp } from "./src/commands/worktree"
 import { status, help as statusHelp } from "./src/commands/status"
+import { config, help as configHelp } from "./src/commands/config"
 import { doctor, help as doctorHelp } from "./src/commands/doctor"
 import { validate, help as validateHelp } from "./src/commands/validate"
 import { context, help as contextHelp } from "./src/commands/context"
@@ -579,6 +580,23 @@ const commands: Record<string, Command> = {
 			)
 		},
 	},
+	config: {
+		async run(args: string[], options: Record<string, any>) {
+			if (options.help) {
+				console.log(configHelp)
+				return
+			}
+			await runCommand(
+				config({
+					silent: options.silent,
+					verbose: options.verbose,
+					json: options.json,
+					cwd: options.cwd,
+					args,
+				}),
+			)
+		},
+	},
 	status: {
 		run: async (_args: string[], options: Record<string, any>) => {
 			if (options.help) {
@@ -726,9 +744,10 @@ 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
+  config                 Show or change workbase settings
   doctor                 Diagnose workbase health and integrations
   validate [path]        Validate a workbase
   context [target]       Return complete target context

package/package.json

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

package/src/act-schema.ts

@@ -64,6 +64,7 @@ export const ActDiscovery = Schema.Struct({
 	}),
 	workbase: Schema.Struct({
 		root: Schema.String,
+		autoArchive: Schema.optional(Schema.Boolean),
 		repositories: Argv,
 		actions: Schema.Array(Action),
 	}),

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: {
@@ -951,6 +958,18 @@ const commands = {
 			options: ["select", "json"],
 		},
 	},
+	config: {
+		usage: "agency config auto-archive [on|off] [--json]",
+		options: outputOptions,
+		subcommands: {
+			"auto-archive": {
+				usage: "agency config auto-archive [on|off] [--json]",
+				minArgs: 0,
+				maxArgs: 1,
+				options: ["json"],
+			},
+		},
+	},
 	status: {
 		usage: "agency status [filters] [--json]",
 		options: { ...outputOptions, ...viewOptions },

package/src/commands/act-actions.ts

@@ -14,6 +14,7 @@ import { phase } from "./phase"
 import { push } from "./push"
 import { sync } from "./sync"
 import { status } from "./status"
+import { config } from "./config"
 import { pr, prCreate } from "./pr"
 import { validate } from "./validate"
 import { work as startWork, type StartWork } from "./work"
@@ -33,6 +34,7 @@ type NativeOperation =
 	| ReturnType<typeof push>
 	| ReturnType<typeof sync>
 	| ReturnType<typeof status>
+	| ReturnType<typeof config>
 	| ReturnType<typeof doctor>
 	| ReturnType<typeof integration>
 	| ReturnType<typeof validate>
@@ -188,6 +190,22 @@ const actionPresentation: Record<
 		icon: "󰄬",
 		color: macchiato.green,
 	},
+	"auto-archive-show": {
+		description: "Show the effective automatic archive setting.",
+		icon: "",
+		color: macchiato.blue,
+	},
+	"auto-archive-enable": {
+		description:
+			"Automatically archive tasks on future terminal transitions, subject to safety checks.",
+		icon: "",
+		color: macchiato.green,
+	},
+	"auto-archive-disable": {
+		description: "Leave terminal tasks active until explicitly archived.",
+		icon: "",
+		color: macchiato.yellow,
+	},
 	doctor: {
 		description: "Diagnose workbase, repository, and integration health.",
 		icon: "󰒡",
@@ -234,6 +252,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 +394,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",
@@ -436,6 +459,9 @@ export const actionGroups = [
 			"sync-all",
 			"integration-status",
 			"integration-sync",
+			"auto-archive-show",
+			"auto-archive-enable",
+			"auto-archive-disable",
 		],
 	},
 	{
@@ -825,6 +851,25 @@ export const actActions = (
 					}),
 				),
 			),
+			...(["show", "enable", "disable"] as const).map((operation) => {
+				const args = [
+					"auto-archive",
+					...(operation === "show"
+						? []
+						: [operation === "enable" ? "on" : "off"]),
+				]
+				return immediate(
+					{
+						id: `auto-archive-${operation}`,
+						label: `${operation === "show" ? "Show" : operation === "enable" ? "Enable" : "Disable"} auto archive`,
+						blockedReason: null,
+					},
+					{
+						command: ["agency", "config", ...args],
+						run: config({ ...options, args }),
+					},
+				)
+			}),
 			immediate(
 				{ id: "validate", label: "Validate workbase", blockedReason: null },
 				{
@@ -875,6 +920,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 +1090,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 +1109,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 +1371,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/act.ts

@@ -481,6 +481,7 @@ const actStep = (
 						creationDefaults: creationDefaults(config),
 						workbase: {
 							root,
+							autoArchive: config.autoArchive ?? false,
 							repositories: graph.nodes
 								.filter((node) => node.kind === "repository")
 								.map((node) => node.key),
@@ -790,6 +791,7 @@ A workbase path opens Workbase actions. Otherwise the positional value is a
 task ID. Selectors skip item selection.
 JSON discovery includes creation defaults identifying when callers should omit
 --branch so the workbase branchNameCommand can choose it.
+JSON discovery also includes the effective auto-archive setting and its commands.
 
 Options:
   --action <id>         Start an action or filter discovery (IDs from --json)

package/src/commands/config.ts

@@ -0,0 +1,43 @@
+import { Effect } from "effect"
+import { WorkbaseService } from "../services/WorkbaseService"
+import type { BaseCommandOptions } from "../utils/command"
+import { createLoggers } from "../utils/effect"
+
+export const config = (
+	options: BaseCommandOptions & { readonly args: readonly string[] },
+) =>
+	Effect.gen(function* () {
+		const [setting, value] = options.args
+		if (
+			setting !== "auto-archive" ||
+			(value !== undefined && value !== "on" && value !== "off")
+		) {
+			return yield* Effect.fail(
+				new Error("Usage: agency config auto-archive [on|off]"),
+			)
+		}
+		const workbase = yield* WorkbaseService
+		const { log } = createLoggers(options)
+		const result =
+			value === undefined
+				? yield* workbase.loadConfig(options.cwd).pipe(
+						Effect.map(({ root, config }) => ({
+							root,
+							autoArchive: config.autoArchive ?? false,
+						})),
+					)
+				: yield* workbase.setAutoArchive(value === "on", options.cwd)
+		log(
+			options.json
+				? JSON.stringify(result, null, 2)
+				: `Auto archive: ${result.autoArchive ? "on" : "off"}`,
+		)
+	})
+
+export const help = `
+Usage: agency config auto-archive [on|off] [--json]
+
+Show, enable, or disable automatic archiving in this workbase.
+Defaults to off. Enabling applies to future terminal transitions, not existing
+terminal work. Archive safety checks are never bypassed.
+`

package/src/commands/phase.ts

@@ -1,4 +1,5 @@
 import { Effect } from "effect"
+import { autoArchiveMessage } from "../services/auto-archive"
 import type { BaseCommandOptions } from "../utils/command"
 import { PhaseService } from "../services/PhaseService"
 import { createLoggers } from "../utils/effect"
@@ -199,6 +200,8 @@ export const phase = (options: PhaseOptions, work: StartWork = startWork) =>
 						? JSON.stringify(output, null, 2)
 						: `Marked phase '${phaseId}' as ${record.data.status}`,
 				)
+				const notice = autoArchiveMessage(record.autoArchive)
+				if (!options.json && notice) log(notice)
 				return
 			}
 			case "update": {

package/src/commands/review.ts

@@ -1,5 +1,6 @@
 import { Effect } from "effect"
 import { ReviewService } from "../services/ReviewService"
+import { autoArchiveMessage } from "../services/auto-archive"
 import type { BaseCommandOptions } from "../utils/command"
 import { createLoggers } from "../utils/effect"
 
@@ -12,17 +13,36 @@ 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}'`,
+			)
+			const notice = autoArchiveMessage(result.autoArchive)
+			if (!options.json && notice) log(notice)
+			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 +51,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/status.ts

@@ -34,7 +34,13 @@ export const status = (options: StatusOptions = {}) =>
 					pr: options.pr,
 				})).executionRows
 			: []
-		const data = { ...report, repositories: repos, work: executionRows }
+		const { config } = yield* workbase.loadConfig(cwd)
+		const data = {
+			...report,
+			autoArchive: config.autoArchive ?? false,
+			repositories: repos,
+			work: executionRows,
+		}
 
 		if (options.json) {
 			log(JSON.stringify(data, null, 2))

package/src/commands/sync.ts

@@ -1,5 +1,6 @@
 import { Effect } from "effect"
 import { SyncService } from "../services/SyncService"
+import { autoArchiveMessage } from "../services/auto-archive"
 import type { BaseCommandOptions } from "../utils/command"
 import { createLoggers } from "../utils/effect"
 import { createProgress, type Progress } from "../utils/progress"
@@ -87,6 +88,10 @@ export const sync = (
 				`${change.status === "applied" ? "Applied" : "Planned"} ${change.kind} '${change.target}': ${change.message}`,
 			)
 		}
+		for (const archive of result.autoArchive) {
+			const notice = autoArchiveMessage(archive)
+			if (notice) log(notice)
+		}
 		for (const { notice: warning, targets } of groupedNotices(
 			result.warnings,
 		)) {

package/src/commands/task.ts

@@ -1,4 +1,5 @@
 import { Effect } from "effect"
+import { autoArchiveMessage } from "../services/auto-archive"
 import type { BaseCommandOptions } from "../utils/command"
 import { TaskService } from "../services/TaskService"
 import { EpicService } from "../services/EpicService"
@@ -491,6 +492,8 @@ export const task = (
 						? JSON.stringify(output, null, 2)
 						: `Marked task '${id}' as ${record.data.status}`,
 				)
+				const notice = autoArchiveMessage(record.autoArchive)
+				if (!options.json && notice) log(notice)
 				return
 			}
 			case "update": {

package/src/services/ContextService.ts

@@ -329,6 +329,7 @@ export class ContextService extends Effect.Service<ContextService>()(
 								root,
 								configPath: join(root, "agency.json"),
 								version: config.version,
+								autoArchive: config.autoArchive ?? false,
 								vcs: "git",
 							},
 							target: { kind: "workbase", path: root },
@@ -1174,6 +1175,7 @@ export class ContextService extends Effect.Service<ContextService>()(
 							root,
 							configPath: join(root, "agency.json"),
 							version: config.version,
+							autoArchive: config.autoArchive ?? false,
 							vcs: "git",
 						},
 						target,

package/src/services/PhaseService.ts

@@ -17,7 +17,8 @@ import {
 	formatWorkDocumentBody,
 	parseFrontmatter,
 } from "../workbase/frontmatter"
-import { canTransitionStatus } from "../readiness"
+import { canTransitionStatus, isTerminalStatus } from "../readiness"
+import { autoArchiveTask, type AutoArchiveResult } from "./auto-archive"
 import { documentRevision } from "../workbase/document-revision"
 import { archivedPhaseDirectory } from "../workbase/archive"
 import {
@@ -43,6 +44,7 @@ export interface PhaseRecord {
 	readonly content: string
 	readonly revision: string
 	readonly data: PhaseData
+	readonly autoArchive?: AutoArchiveResult
 }
 
 export interface CreatePhaseInput {
@@ -573,11 +575,15 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 							: { ...record.data, status: validStatus }
 					const content = formatMarkdownDocument(data, parsed.body)
 					yield* fs.writeFile(record.path, content)
+					const autoArchive = isTerminalStatus(data.status)
+						? yield* autoArchiveTask(taskId, startPath)
+						: undefined
 					return {
 						...record,
 						content,
 						revision: documentRevision(content),
 						data,
+						...(autoArchive ? { autoArchive } : {}),
 					} satisfies PhaseRecord
 				}),
 		}),

package/src/services/ReviewService.ts

@@ -7,6 +7,7 @@ import { PhaseService } from "./PhaseService"
 import { RepositoryService } from "./RepositoryService"
 import { TaskService } from "./TaskService"
 import { WorkbaseService } from "./WorkbaseService"
+import { autoArchiveTask } from "./auto-archive"
 import {
 	WorktreeService,
 	type WorktreeRemovalSnapshot,
@@ -424,6 +425,52 @@ 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,
+						autoArchive: yield* autoArchiveTask(taskId, root),
+					}
+				}),
 		}),
 	},
 ) {}

package/src/services/SyncService.ts

@@ -31,6 +31,7 @@ import {
 	type RepositorySetupResult,
 } from "./RepositoryService"
 import { VersionControlService } from "./VersionControlService"
+import { autoArchiveTask, type AutoArchiveResult } from "./auto-archive"
 
 class SyncError extends Data.TaggedError("SyncError")<{
 	readonly message: string
@@ -111,6 +112,7 @@ interface SyncResult {
 	readonly unresolved: readonly SyncNotice[]
 	readonly executions: readonly ExecutionSyncState[]
 	readonly repositories: RepositorySetupResult
+	readonly autoArchive: readonly AutoArchiveResult[]
 }
 
 export interface SyncProgress {
@@ -370,6 +372,7 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 
 				const apply = options.apply === true
 				const changes: SyncChange[] = []
+				const completedTasks = new Set<string>()
 				const warnings: SyncNotice[] = []
 				const unresolved: SyncNotice[] = []
 				for (const issue of repositorySetup.unresolved) {
@@ -1285,6 +1288,7 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 							})
 							data = completed.data
 							revision = completed.revision
+							completedTasks.add(record.taskId)
 						}
 						changes.push({
 							kind: "mark-done",
@@ -1372,6 +1376,11 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 					reportExecution(`task:${task.id}`)
 				}
 
+				const autoArchive: AutoArchiveResult[] = []
+				if (apply && config.autoArchive) {
+					for (const taskId of completedTasks)
+						autoArchive.push(yield* autoArchiveTask(taskId, root))
+				}
 				return {
 					root,
 					mode: apply ? "apply" : "dry-run",
@@ -1380,6 +1389,7 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 					unresolved,
 					executions,
 					repositories: repositorySetup,
+					autoArchive,
 				} satisfies SyncResult
 			}),
 	}),

package/src/services/TaskService.ts

@@ -22,7 +22,8 @@ import {
 	parseFrontmatter,
 	parseFrontmatterSync,
 } from "../workbase/frontmatter"
-import { canTransitionStatus } from "../readiness"
+import { canTransitionStatus, isTerminalStatus } from "../readiness"
+import { autoArchiveTask, type AutoArchiveResult } from "./auto-archive"
 import { documentRevision } from "../workbase/document-revision"
 import { archivedTaskDirectory } from "../workbase/archive"
 import {
@@ -47,6 +48,7 @@ export interface TaskRecord {
 	readonly content: string
 	readonly revision: string
 	readonly data: TaskData
+	readonly autoArchive?: AutoArchiveResult
 }
 
 export interface CreateTaskInput {
@@ -652,6 +654,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:
@@ -675,11 +686,15 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 						: { ...record.data, status: validStatus }
 				const content = formatMarkdownDocument(data, parsed.body)
 				yield* fs.writeFile(record.path, content)
+				const autoArchive = isTerminalStatus(data.status)
+					? yield* autoArchiveTask(id, startPath)
+					: undefined
 				return {
 					...record,
 					content,
 					revision: documentRevision(content),
 					data,
+					...(autoArchive ? { autoArchive } : {}),
 				} satisfies TaskRecord
 			}),
 	}),

package/src/services/WorkbaseService.ts

@@ -416,6 +416,19 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 					return { root, config: decoded.value }
 				}),
 
+			setAutoArchive: (enabled: boolean, startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const service = yield* WorkbaseService
+					const fs = yield* FileSystemService
+					const { root, config } = yield* service.loadConfig(startPath)
+					const updated = { ...config, autoArchive: enabled }
+					yield* fs.writeFile(
+						join(root, "agency.json"),
+						`${JSON.stringify(updated, null, 2)}\n`,
+					)
+					return { root, autoArchive: enabled }
+				}),
+
 			repositoryAliases: (startPath: string = process.cwd()) =>
 				Effect.gen(function* () {
 					const service = yield* WorkbaseService

package/src/services/auto-archive.ts

@@ -0,0 +1,82 @@
+import { Effect } from "effect"
+import type {
+	GitVersionControlService,
+	VersionControlService,
+} from "./VersionControlService"
+import type { ArchiveService } from "./ArchiveService"
+import { WorkbaseService } from "./WorkbaseService"
+import type { FileSystemService } from "./FileSystemService"
+import { TaskService } from "./TaskService"
+import { PhaseService } from "./PhaseService"
+import type { EpicService } from "./EpicService"
+import type { WorktreeService } from "./WorktreeService"
+import { aggregateProgress, isTerminalStatus } from "../readiness"
+
+export interface AutoArchiveResult {
+	readonly taskId: string
+	readonly status: "disabled" | "non-terminal" | "archived" | "skipped"
+	readonly path?: string
+	readonly reason?: string
+}
+
+// A terminal transition is durable even when archive safety checks reject cleanup.
+// Explicit typing also keeps the lazy service references free of inference cycles.
+export const autoArchiveTask = (
+	taskId: string,
+	startPath: string,
+): Effect.Effect<
+	AutoArchiveResult,
+	never,
+	| WorkbaseService
+	| ArchiveService
+	| FileSystemService
+	| TaskService
+	| PhaseService
+	| EpicService
+	| WorktreeService
+	| GitVersionControlService
+	| VersionControlService
+> =>
+	Effect.gen(function* () {
+		const workbase = yield* WorkbaseService
+		const { root, config } = yield* workbase.loadConfig(startPath)
+		if (!config.autoArchive) return { taskId, status: "disabled" as const }
+		const tasks = yield* TaskService
+		const task = yield* tasks.show(taskId, root)
+		let status
+		if ("phases" in task.data) {
+			const phases = yield* PhaseService
+			const records = yield* Effect.forEach(task.data.phases, (phase) =>
+				phases.show(taskId, phase.id, root),
+			)
+			status = aggregateProgress(
+				records.map((phase) => phase.data.status),
+			).status
+		} else status = task.data.status
+		if (!isTerminalStatus(status))
+			return { taskId, status: "non-terminal" as const }
+		// ArchiveService uses TaskService for preflight; resolve it only after the
+		// terminal write to avoid an eager module initialization cycle.
+		const { ArchiveService } = yield* Effect.promise(
+			() => import("./ArchiveService"),
+		)
+		const archives = yield* ArchiveService
+		// archiveTask always performs the same preflight as --dry-run before applying.
+		const result = yield* archives.archiveTask(taskId, root)
+		return { taskId, status: "archived" as const, path: result.path }
+	}).pipe(
+		Effect.catchAll((error) =>
+			Effect.succeed({
+				taskId,
+				status: "skipped" as const,
+				reason: error.message,
+			}),
+		),
+	)
+
+export const autoArchiveMessage = (result: AutoArchiveResult | undefined) =>
+	result?.status === "archived"
+		? `Auto-archived task '${result.taskId}' to ${result.path}`
+		: result?.status === "skipped"
+			? `Auto-archive skipped for task '${result.taskId}': ${result.reason}`
+			: undefined

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,18 @@ 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.
+
+The workbase's `autoArchive` setting defaults to off. Enabling it with
+`agency config auto-archive on` is standing consent for automatic task archiving
+on terminal transitions, including merged-PR sync and explicit non-PR completion.
+Show or disable it with `agency config auto-archive [off]`; context/status JSON
+reports its effective value. Multi-phase tasks wait until every phase is terminal.
+Archive preflight safeguards still apply: inspect the triggering command's
+`autoArchive` result for skips, resolve their reasons, and never force cleanup.
+Successful auto-archive can remove the current task directory and clean checkouts;
+continue lifecycle commands from the workbase root rather than a removed path.
 
 ## Investigation Handoffs
 
@@ -272,7 +284,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):

package/src/workbase/schemas.ts

@@ -103,6 +103,7 @@ const DeliveryProvider = Schema.Struct({
 export const WorkbaseConfig = Schema.Struct({
 	version: Schema.Literal(2),
 	vcs: Schema.optional(Schema.Literal("git")),
+	autoArchive: Schema.optional(Schema.Boolean),
 	repositories: Schema.optional(
 		Schema.Record({ key: RepositoryAlias, value: RepositoryDeclaration }),
 	),