@markjaquith/agency 2.74.0 → 3.1.0

package/README.md

@@ -9,7 +9,6 @@ read or write.
 
 - [Bun](https://bun.sh) 1.0 or newer
 - Git
-- [Jujutsu](https://jj-vcs.github.io/jj/) is preferred when available
 - [GitHub CLI](https://cli.github.com/) for `agency pr`
 - OpenCode, Claude Code, or a configured agent for `agency work`
 
@@ -151,15 +150,16 @@ the writable checkout's `.claude/skills`, `.agents/skills`,
 `.opencode/{skill,skills}`, and `.pi/skills` directories. `agency context`
 remains the authority for writes; reference checkouts remain read-only.
 
-Repository aliases, the version-control backend, and canonical fetch remotes are
-declared in tracked `agency.json`; local clones and symlinks remain ignored under
-`repos/{alias}`. A declaration contains no local path, symlink target, checkout,
-or credential:
+Repository aliases and canonical fetch remotes are declared in tracked
+`agency.json`; local Git clones and symlinks remain ignored under
+`repos/{alias}`. A declaration contains no local path, symlink target, worktree,
+or credential. The optional `vcs` field accepts only `"git"`; omitting it also
+selects Git:
 
 ```json
 {
 	"version": 2,
-	"vcs": "jj",
+	"vcs": "git",
 	"repositories": {
 		"frontend": {
 			"remote": "git@example.com:team/frontend.git"
@@ -168,39 +168,9 @@ or credential:
 }
 ```
 
-New workbases select `"jj"` when the `jj` executable is available and otherwise
-select `"git"`. Existing version 2 workbases without `vcs` remain Git workbases.
-The selected backend is a workbase-level invariant: jj workbases create
-non-colocated managed clones and jj workspaces, while Git workbases continue to
-use bare repositories and Git worktrees. Existing colocated jj repositories are
-also supported.
-
-Agency uses jj-native commands for repository validity, workspace registration,
-working-copy state, revisions, bookmarks, ancestry, fetch, and push. Raw Git is
-limited to backing-store plumbing such as durable review refs and integrations
-that require Git, including GitHub CLI commit discovery. For those operations,
-Agency obtains the backing repository with `jj git root` and supplies it as
-`GIT_DIR`; it does not use raw Git to infer jj workspace state.
-
-Inspect the current backend and migration readiness with:
-
-```bash
-agency vcs status
-agency vcs migrate jj          # dry-run
-agency vcs migrate jj --apply
-agency vcs migrate git --apply
-```
-
-Migration is workbase-wide and transactional. Agency locks every execution
-unit, requires clean registered workspaces, blocks active claims and working or
-delegated units, converts repository metadata, recreates checkout paths with the
-target backend, and updates `agency.json` last. Migration from jj to Git also
-blocks jj-only heads that are not preserved by a bookmark or workspace. Failed
-migrations restore the source repositories and workspaces when rollback is
-possible and report explicit manual recovery paths otherwise.
-Converting a non-colocated jj workbase to Git is currently blocked before any
-mutation because its backing Git object store is inside `.jj`; first convert the
-repositories to colocated jj so the Git store survives metadata removal.
+Agency materializes declared remotes as bare Git repositories and creates
+managed Git worktrees for execution units. Linked aliases remain symlinks to
+existing Git repositories.
 
 Existing version 2 workbases without `repositories` remain valid. Run
 `agency repo setup` to preview deterministic adoption of legacy local aliases;
@@ -274,63 +244,13 @@ Agency also reconciles known tool-owned artifacts such as Worktrunk's
 new and existing managed worktrees clean without changing the repository's
 tracked ignore configuration or overwriting user-maintained local excludes.
 
-The configured command applies only to the writable checkout of a Git workbase.
+The configured command applies only to the writable checkout.
 Supplemental read-only repositories remain detached Git worktrees at their
-declared refs so they do not acquire writable branches. Jj workbases always use
-jj workspaces and ignore this Git-specific customization.
-
-### Custom Jj Workspace Command
-
-Jj workbases normally create managed workspaces with `jj workspace add`. Set
-`workspaceCreateCommand` to an argv template when another tool should create or
-adopt a prepared workspace directly at Agency's destination:
-
-```json
-{
-	"version": 2,
-	"vcs": "jj",
-	"workspaceCreateCommand": [
-		"my-prewarm-tool",
-		"adopt",
-		"--repo",
-		"{repo}",
-		"--destination",
-		"{workspace}",
-		"--name",
-		"{name}",
-		"--revision",
-		"{revision}"
-	]
-}
-```
-
-Available placeholders are:
-
-- `{repo}`: absolute repository alias path under `repos/`
-- `{workspace}`: absolute managed workspace path Agency requires
-- `{name}`: unique jj workspace name Agency requires
-- `{revision}`: exact commit the new working copy must be based on
-- `{kind}`: `writable` or `reference`
-- `{requestedRef}`: configured branch, reference, or review commit
-
-`{repo}`, `{workspace}`, `{name}`, and `{revision}` are required. Agency invokes
-the command directly without a shell and sets matching `AGENCY_REPO`,
-`AGENCY_WORKSPACE`, `AGENCY_WORKSPACE_NAME`, `AGENCY_REVISION`,
-`AGENCY_CHECKOUT_KIND`, and `AGENCY_REQUESTED_REF` environment variables. The
-command applies to each new jj checkout and must leave `{workspace}` registered
-under `{name}` with its working-copy parent at `{revision}`. This lets a prewarm
-tool move or adopt a prepared workspace without first paying for Agency's normal
-full checkout.
-
-Agency validates the registration, name, path, and revision before running any
-`postCheckoutCommand`. A failed command or validation removes a partially
-created workspace when possible and otherwise reports manual recovery. Resume
-restoration continues to use Agency's built-in exact-target recovery path.
-Git workbases ignore this jj-specific customization.
+declared refs so they do not acquire writable branches.
 
 ### Post-checkout Commands
 
-Each repository declaration may provide a VCS-neutral `postCheckoutCommand` argv
+Each repository declaration may provide a `postCheckoutCommand` argv
 template for repository-specific setup. Agency invokes it directly, without a
 shell, with the new checkout as its working directory:
 
@@ -346,11 +266,10 @@ shell, with the new checkout as its working directory:
 }
 ```
 
-The hook runs for each newly created managed checkout, including writable and
-reference checkouts, after Git worktree or jj workspace creation has completed
-and Agency has validated the checkout. It does not run for a reused checkout or
-for inspection-only commands. A custom `worktreeCreateCommand` or
-`workspaceCreateCommand` completes and is validated before this hook runs.
+The hook runs for each newly created managed Git worktree, including writable
+and reference worktrees, after Agency has validated it. It does not run for a
+reused worktree or for inspection-only commands. A custom
+`worktreeCreateCommand` completes and is validated before this hook runs.
 
 Available placeholders and matching environment variables are:
 
@@ -362,7 +281,7 @@ Available placeholders and matching environment variables are:
 | `{checkoutKind}`   | `AGENCY_CHECKOUT_KIND`   | `writable` or `reference`                      |
 | `{requestedRef}`   | `AGENCY_REQUESTED_REF`   | Requested branch, reference, or review commit  |
 | `{base}`           | `AGENCY_BASE`            | Configured execution base                      |
-| `{vcs}`            | `AGENCY_VCS`             | `git` or `jj`                                  |
+| `{vcs}`            | `AGENCY_VCS`             | `git`                                          |
 | `{workbaseRoot}`   | `AGENCY_WORKBASE_ROOT`   | Absolute workbase root                         |
 | `{taskId}`         | `AGENCY_TASK_ID`         | Task ID                                        |
 | `{phaseId}`        | `AGENCY_PHASE_ID`        | Phase ID                                       |
@@ -1076,12 +995,17 @@ agency archive epic <epic-id> [--dry-run] [--json]
 agency archive task <task-id> [--dry-run] [--json]
 agency archive tasks [--dry-run] [--json]
 agency archive phase <task-id> <phase-id> [--dry-run] [--json]
+agency archive <path> [--dry-run] [--json]
 agency restore epic <epic-id> [--dry-run] [--json]
 agency restore task <task-id> [--dry-run] [--json]
 agency restore phase <task-id> <phase-id> [--dry-run] [--json]
 ```
 
-Archived work keeps its hierarchy under `archive/`. Epic archiving includes its
+An existing path within an active epic or task infers that work item, so
+`agency archive .` works from its directory. Collection roots are ambiguous,
+phase paths require the explicit `archive phase` form, and paths outside active
+epic or task trees are rejected. Archived work keeps its hierarchy under
+`archive/`. Epic archiving includes its
 listed tasks. A task can be archived only when its effective status is terminal
 (`done` or `dropped`). Multi-phase task status is derived from its phases, every
 phase must be terminal, and a task with no phases is not eligible.
@@ -1162,15 +1086,6 @@ conflicting worktrees. Repair is deliberately conservative: it repairs safe Git
 registration issues and materializes missing checkouts, but never switches a
 branch, resets a commit, or discards uncommitted work.
 
-For jj, explicit removal is a suspend operation. Agency records each workspace's
-exact `@` commit and stable change ID in `.agency-jj-resume.json`, roots that
-commit with an internal local bookmark, and only then forgets the workspace.
-The next `work prepare` validates all three identities, restores the workspace by
-editing the recorded commit, and consumes the resume metadata and bookmarks.
-Missing, ambiguous, or conflicting resume state stops instead of falling back to
-the declared delivery bookmark, `@-`, or the base. Unknown checkout cleanliness
-also stops removal. Git worktree removal and preparation are unchanged.
-
 Agency launches every agent beside its epic or task document. Single-phase tasks
 and phases first fetch repositories and create or reuse worktrees under `code/`,
 then launch the execution agent from the task directory with absolute context
@@ -1195,18 +1110,11 @@ that the declared base is in the publication history, validates every outgoing
 commit's description, author, and conflict state, and refuses non-fast-forward
 updates.
 
-For Git, YAML `branch` must exactly match the checked-out local branch, the
-worktree must be clean, and `HEAD` is pushed with upstream tracking. For jj, YAML
-`branch` is the authoritative delivery bookmark and need not exist before
-publication. Agency publishes `@` unless it is the canonical empty, undescribed
-post-commit working copy, in which case it publishes `@-`; described empty
-changes remain intentional publication tips. Missing descriptions or authors
-stop with exact change IDs and remediation commands. Agency creates or safely
-advances only the declared bookmark and never invents a `push-*` bookmark.
-If the fetched remote base advanced outside the local stack, Agency prints the
-exact `jj rebase` command needed to move the stack onto `<base>@<remote>`. Push
-reports deterministic fetch, inspection, validation, and publication progress
-on stderr, including while `--json` reserves stdout for one machine result.
+YAML `branch` must exactly match the checked-out local branch, the worktree must
+be clean, and `HEAD` is pushed with upstream tracking. Missing commit descriptions
+or authors stop publication with exact commits and remediation commands. Push
+reports deterministic fetch, inspection, validation, and publication progress on
+stderr, including while `--json` reserves stdout for one machine result.
 
 Task-aware `agency pr create <task-id> [phase-id]` uses Agency's delivery flow,
 including readiness checks and durable PR recording. It accepts draft, title,
@@ -1216,8 +1124,7 @@ Other `agency pr`
 invocations forward every argument to `gh pr`. From an execution task or phase
 directory, including descendants, passthrough runs in that execution unit's
 authoritative writable checkout. Otherwise it runs in the caller's current
-directory. In jj workbases, Agency also supplies the repository and the work
-item's declared branch to subcommands that would otherwise infer Git context.
+directory.
 
 ### Status and Validation
 

package/cli-main.ts

@@ -48,12 +48,9 @@ import { DoctorService } from "./src/services/DoctorService"
 import { ReviewService } from "./src/services/ReviewService"
 import {
 	GitVersionControlService,
-	JjVersionControlService,
 	VersionControlService,
 } from "./src/services/VersionControlService"
 import { review, help as reviewHelp } from "./src/commands/review"
-import { vcs, help as vcsHelp } from "./src/commands/vcs"
-import { VcsMigrationService } from "./src/services/VcsMigrationService"
 import { act, help as actHelp } from "./src/commands/act"
 import {
 	claimCommand,
@@ -74,9 +71,7 @@ const CliLayer = Layer.mergeAll(
 	FileSystemService.Default,
 	WorkbaseService.Default,
 	GitVersionControlService.Default,
-	JjVersionControlService.Default,
 	VersionControlService.Default,
-	VcsMigrationService.Default,
 	RepositoryService.Default,
 	EpicService.Default,
 	TaskService.Default,
@@ -401,10 +396,18 @@ const commands: Record<string, Command> = {
 				console.log(archiveHelp)
 				return
 			}
+			const explicitType = [
+				"list",
+				"show",
+				"epic",
+				"task",
+				"tasks",
+				"phase",
+			].includes(args[0] ?? "")
 			await runCommand(
 				archive({
-					type: args[0],
-					args: args.slice(1),
+					type: explicitType ? args[0] : undefined,
+					args: explicitType ? args.slice(1) : args,
 					json: options.json,
 					dryRun: options["dry-run"],
 					kinds: options.kind,
@@ -623,26 +626,6 @@ const commands: Record<string, Command> = {
 			)
 		},
 	},
-	vcs: {
-		run: async (args: string[], options: Record<string, any>) => {
-			if (options.help) {
-				console.log(vcsHelp)
-				return
-			}
-			await runCommand(
-				vcs({
-					subcommand: args[0],
-					target: args[1],
-					apply: options.apply,
-					dryRun: options["dry-run"],
-					json: options.json,
-					silent: options.silent,
-					verbose: options.verbose,
-					cwd: options.cwd,
-				}),
-			)
-		},
-	},
 	next: {
 		run: async (_args: string[], options: Record<string, any>) => {
 			if (options.help) return console.log(nextHelp)
@@ -802,7 +785,6 @@ Commands:
   task <subcommand>      Manage tasks
   work [directory|task]  Work on an epic, task, or phase
   worktree <subcommand>  Inspect and maintain managed workspaces
-  vcs <subcommand>       Inspect or migrate the version-control backend
   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

package/cli.ts

@@ -1,19 +1,3 @@
 #!/usr/bin/env bun
 
-const args = Bun.argv.slice(2)
-const fastVcsStatus =
-	args[0] === "vcs" &&
-	args[1] === "status" &&
-	(args.length === 2 || (args.length === 3 && args[2] === "--json"))
-
-if (fastVcsStatus) {
-	try {
-		const { runVcsStatusFast } = await import("./src/vcs-status-fast")
-		if (!(await runVcsStatusFast(args[2] === "--json")))
-			await import("./cli-main")
-	} catch {
-		await import("./cli-main")
-	}
-} else {
-	await import("./cli-main")
-}
+await import("./cli-main")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.74.0",
+  "version": "3.1.0",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",
@@ -83,7 +83,6 @@
     "benchmark:graph": "bun scripts/benchmark-graph.ts",
     "benchmark:push": "bun scripts/benchmark-push.ts",
     "benchmark:archive": "bun scripts/benchmark-archive.ts",
-    "benchmark:vcs": "bun scripts/benchmark-vcs.ts",
     "benchmark:sync": "bun scripts/benchmark-sync.ts",
     "benchmark:task": "bun scripts/benchmark-task.ts",
     "benchmark:validate": "bun scripts/benchmark-validate.ts",

package/schemas/agency-graph-v1.schema.json

@@ -22,7 +22,7 @@
       "required": ["version"],
       "properties": {
         "version": { "const": 2 },
-        "vcs": { "enum": ["git", "jj"] },
+        "vcs": { "enum": ["git"] },
         "root": { "type": "string" }
       }
     },

package/src/cli-parser.test.ts

@@ -478,6 +478,11 @@ describe("strict CLI parsing", () => {
 	})
 
 	test("accepts archive dry-run", () => {
+		expect(parseCli(["archive", ".", "--dry-run"])).toMatchObject({
+			commandName: "archive",
+			args: ["."],
+			values: { "dry-run": true },
+		})
 		expect(parseCli(["archive", "task", "example", "--dry-run"])).toMatchObject(
 			{
 				commandName: "archive",
@@ -674,25 +679,6 @@ describe("strict CLI parsing", () => {
 		)
 	})
 
-	test("parses VCS status and migration commands", () => {
-		expect(parseCli(["vcs", "status", "--json"])).toMatchObject({
-			commandName: "vcs",
-			args: ["status"],
-			values: { json: true },
-		})
-		expect(
-			parseCli(["vcs", "migrate", "jj", "--apply", "--json"]),
-		).toMatchObject({
-			commandName: "vcs",
-			args: ["migrate", "jj"],
-			values: { apply: true, json: true },
-		})
-		expectUsageError(["vcs", "migrate"], "agency vcs migrate")
-		expect(() =>
-			parseCli(["vcs", "migrate", "jj", "--dry-run", "--apply"]),
-		).toThrow("cannot be combined")
-	})
-
 	test("parses push without accepting an alternate target", () => {
 		expect(parseCli(["push", "--json"])).toMatchObject({
 			commandName: "push",

package/src/cli-parser.ts

@@ -763,7 +763,7 @@ const commands = {
 		},
 	},
 	archive: {
-		usage: "agency archive <list|show|epic|task|tasks|phase>",
+		usage: "agency archive <path|list|show|epic|task|tasks|phase>",
 		options: {
 			...outputOptions,
 			...entitySelectorOptions,
@@ -772,6 +772,12 @@ const commands = {
 			status: { type: "string", multiple: true },
 			repository: { type: "string", multiple: true },
 		},
+		command: {
+			usage: "agency archive <path> [--dry-run] [--json]",
+			minArgs: 1,
+			maxArgs: 1,
+			options: ["dry-run", "json"],
+		},
 		subcommands: {
 			list: {
 				usage:
@@ -908,29 +914,6 @@ const commands = {
 			},
 		},
 	},
-	vcs: {
-		usage: "agency vcs <status|migrate>",
-		options: {
-			...outputOptions,
-			apply: { type: "boolean" },
-			"dry-run": { type: "boolean" },
-		},
-		subcommands: {
-			status: {
-				usage: "agency vcs status [--json]",
-				minArgs: 0,
-				maxArgs: 0,
-				options: ["json"],
-			},
-			migrate: {
-				usage: "agency vcs migrate <git|jj> [--dry-run | --apply] [--json]",
-				minArgs: 1,
-				maxArgs: 1,
-				options: ["apply", "dry-run", "json"],
-				conflicts: [["apply", "dry-run"]],
-			},
-		},
-	},
 	work: {
 		usage:
 			"agency work [<directory-or-task-id> | --epic <epic-id>] [--agent <name>] [--auto] | agency work prepare [target] [--dry-run] [--json]",
@@ -1497,9 +1480,8 @@ export function parseCli(args: readonly string[]): ParsedCli {
 			values: parsed.values,
 		}
 	}
-	const spec = definition.subcommands
-		? definition.subcommands[subcommand ?? ""]
-		: definition.command
+	const selectedSubcommand = definition.subcommands?.[subcommand ?? ""]
+	const spec = selectedSubcommand ?? definition.command
 	if (!spec) {
 		const message = subcommand
 			? `Unknown subcommand '${subcommand}' for 'agency ${commandName}'.`
@@ -1507,7 +1489,7 @@ export function parseCli(args: readonly string[]): ParsedCli {
 		throw usageError(message, definition.usage)
 	}
 
-	let commandPositionals = definition.subcommands
+	let commandPositionals = selectedSubcommand
 		? parsed.positionals.slice(1)
 		: parsed.positionals
 	const allowed = new Set([...commonOptionNames, ...(spec.options ?? [])])
@@ -1558,7 +1540,7 @@ export function parseCli(args: readonly string[]): ParsedCli {
 
 	commandPositionals = applyEntitySelectors(
 		commandName,
-		subcommand,
+		selectedSubcommand ? subcommand : undefined,
 		commandPositionals,
 		parsed.values,
 		spec,
@@ -1731,7 +1713,7 @@ export function parseCli(args: readonly string[]): ParsedCli {
 
 	return {
 		commandName: commandName as keyof typeof commands,
-		args: definition.subcommands
+		args: selectedSubcommand
 			? [subcommand!, ...commandPositionals]
 			: commandPositionals,
 		values: parsed.values,

package/src/cli.test.ts

@@ -531,9 +531,9 @@ status: dropped
 `,
 		)
 
-		expect((await runCli(["archive", "task", "example"], root)).exitCode).toBe(
-			0,
-		)
+		expect(
+			(await runCli(["archive", "."], join(root, "tasks/example"))).exitCode,
+		).toBe(0)
 		const result = await runCli(["archive", "task", "example", "--json"], root)
 
 		expect(result.exitCode).toBe(1)
@@ -1929,9 +1929,9 @@ status: open
 				alias: "agency",
 				status: "applied",
 			})
-			expect(
-				(await stat(join(restored, "repos/agency/.jj"))).isDirectory(),
-			).toBe(true)
+			expect((await stat(join(restored, "repos/agency/HEAD"))).isFile()).toBe(
+				true,
+			)
 
 			const prepared = parseJson(
 				await runCli(["work", "prepare", "portable", "--json"], restored),

package/src/commands/archive.test.ts

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { mkdir } from "node:fs/promises"
 import { join } from "node:path"
 import {
 	captureLogs,
@@ -93,6 +94,75 @@ describe("archive command", () => {
 		)
 	})
 
+	test("infers a task from a filesystem path", async () => {
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				archive({
+					args: ["."],
+					cwd: join(root, "tasks/example"),
+					dryRun: true,
+					json: true,
+				}),
+			),
+		)
+
+		expect(JSON.parse(logs[0]!)).toMatchObject({
+			operation: "archive",
+			kind: "task",
+			id: "example",
+			dryRun: true,
+		})
+	})
+
+	test("infers an epic from a filesystem path", async () => {
+		const directory = join(root, "epics/delivery")
+		await mkdir(directory, { recursive: true })
+		await Bun.write(
+			join(directory, "EPIC.md"),
+			`---
+ticketUrl: https://example.com/epic
+repos:
+  - repo: agency
+    ref: main
+tasks: []
+---
+
+# Delivery
+`,
+		)
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				archive({ args: ["."], cwd: directory, dryRun: true, json: true }),
+			),
+		)
+
+		expect(JSON.parse(logs[0]!)).toMatchObject({
+			operation: "archive",
+			kind: "epic",
+			id: "delivery",
+			dryRun: true,
+		})
+	})
+
+	test("rejects ambiguous and unsupported archive paths", async () => {
+		await expect(
+			runTestEffect(archive({ args: ["."], cwd: root, silent: true })),
+		).rejects.toThrow("Archive path is ambiguous")
+		await expect(
+			runTestEffect(
+				archive({ args: ["repos/agency"], cwd: root, silent: true }),
+			),
+		).rejects.toThrow("Archive path must be within an active epic or task")
+
+		const phaseDirectory = join(root, "tasks/example/phases/build")
+		await mkdir(phaseDirectory, { recursive: true })
+		await expect(
+			runTestEffect(
+				archive({ args: ["."], cwd: phaseDirectory, silent: true }),
+			),
+		).rejects.toThrow("Archive path identifies a phase")
+	})
+
 	test("reports an already archived task", async () => {
 		await runTestEffect(
 			archive({ type: "task", args: ["example"], cwd: root, silent: true }),
@@ -143,7 +213,9 @@ describe("archive command", () => {
 	test("requires a supported work item type", async () => {
 		await expect(
 			runTestEffect(archive({ args: [], cwd: root, silent: true })),
-		).rejects.toThrow("Available: list, show, epic, task, tasks, phase")
+		).rejects.toThrow(
+			"Provide a path or use: list, show, epic, task, tasks, phase",
+		)
 	})
 
 	test("rejects an extra archive show identifier", async () => {

package/src/commands/archive.ts

@@ -24,6 +24,14 @@ export const archive = (options: ArchiveOptions) =>
 		const { log } = createLoggers(options)
 		const cwd = options.cwd ?? process.cwd()
 		const [id, phaseId] = options.args
+		let archiveType = options.type
+		let archiveId = id
+
+		if (!archiveType && id) {
+			const target = yield* archives.resolvePathTarget(id, cwd)
+			archiveType = target.kind
+			archiveId = target.id
+		}
 
 		if (options.type === "list") {
 			const records = yield* archives.list(
@@ -73,22 +81,22 @@ export const archive = (options: ArchiveOptions) =>
 		}
 
 		let result
-		switch (options.type) {
+		switch (archiveType) {
 			case "epic":
-				if (!id)
+				if (!archiveId)
 					return yield* Effect.fail(
 						new Error("Usage: agency archive epic <epic-id>"),
 					)
-				result = yield* archives.archiveEpic(id, cwd, {
+				result = yield* archives.archiveEpic(archiveId, cwd, {
 					dryRun: options.dryRun,
 				})
 				break
 			case "task":
-				if (!id)
+				if (!archiveId)
 					return yield* Effect.fail(
 						new Error("Usage: agency archive task <task-id>"),
 					)
-				result = yield* archives.archiveTask(id, cwd, {
+				result = yield* archives.archiveTask(archiveId, cwd, {
 					dryRun: options.dryRun,
 				})
 				break
@@ -109,7 +117,7 @@ export const archive = (options: ArchiveOptions) =>
 			default:
 				return yield* Effect.fail(
 					new Error(
-						"Archive operation is required. Available: list, show, epic, task, tasks, phase",
+						"Archive target is required. Provide a path or use: list, show, epic, task, tasks, phase",
 					),
 				)
 		}
@@ -141,11 +149,14 @@ export const archive = (options: ArchiveOptions) =>
 	})
 
 export const help = `
-Usage: agency archive <list|show|epic|task|tasks|phase>
+Usage: agency archive <path|list|show|epic|task|tasks|phase>
 
 Browse or archive work items after preflighting worktrees and graph references.
 
+An existing path within an active epic or task infers that work item.
+
 Commands:
+  <path>                                 Archive the containing epic or task
   list [filters]                         List archived work
   show <type> <id>                       Show an archived epic or task
   show phase <task-id> <phase-id>        Show an archived phase