@markjaquith/agency 3.15.0 → 3.16.0

package/README.md

@@ -1229,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) {
@@ -729,6 +747,7 @@ Commands:
   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.15.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

@@ -958,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: "󰒡",
@@ -441,6 +459,9 @@ export const actionGroups = [
 			"sync-all",
 			"integration-status",
 			"integration-sync",
+			"auto-archive-show",
+			"auto-archive-enable",
+			"auto-archive-disable",
 		],
 	},
 	{
@@ -830,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 },
 				{

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"
 
@@ -33,6 +34,8 @@ export const review = (options: ReviewOptions) =>
 					? 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(

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,
@@ -467,6 +468,7 @@ export class ReviewService extends Effect.Service<ReviewService>()(
 						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 {
@@ -684,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

@@ -187,6 +187,16 @@ agent from an active agent session; creating a pull request; archiving, restorin
 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
 
 An explicit request for a new, separate, or follow-up item overrides reuse of

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 }),
 	),