@markjaquith/agency 2.62.0 → 2.64.0

package/README.md

@@ -517,12 +517,13 @@ pull request, dropping, reopening, or archiving. Cancelling either chooser makes
 no changes, and the command refreshes the graph before dispatch so a stale
 selection cannot act on changed work.
 
-Use `--epic <id>`, `--task <id>`, or `--task <id> --phase <id>` to skip work-item
-selection. `--dry-run` still prompts for an action but prints the exact Agency
-command instead of executing it. `--json` never prompts or executes; it returns
-matching targets, status and readiness details, document revisions, and each
-available action's command argv. With no selector, JSON includes every active
-work item.
+Use an existing directory, a positional task ID, `--epic <id>`, `--task <id>`,
+or `--task <id> --phase <id>` to skip work-item selection. For example,
+`agency act .` selects the current task or phase. `--dry-run` still prompts for
+an action but prints the exact Agency command instead of executing it. `--json`
+never prompts or executes; it returns matching targets, status and readiness
+details, document revisions, and each available action's command argv. With no
+selector, JSON includes every active work item.
 
 `--auto` is included in generated or executed work commands, and `--draft` is
 included in generated or executed pull request commands.
@@ -535,6 +536,10 @@ a discovery catalog of all epics, tasks, and phases, including frontmatter,
 paths, and document revisions. Elsewhere it returns context for an epic, task,
 or phase. The target defaults to the current directory; entity directories,
 document paths, checkout descendants, and bare task IDs are accepted.
+Archived entity paths and selectors are also accepted. Archived context is
+explicitly marked with `target.archived: true` and never grants writable
+document, repository checkout, or reference authority; restore the item before
+attempting mutation or execution.
 
 Root discovery is compact by default and includes a hint to run `agency context
 . --full --json` when document prose is needed. Entity context remains complete

package/cli-main.ts

@@ -177,10 +177,11 @@ const VERSION = packageJson.version
 // Define commands
 const commands: Record<string, Command> = {
 	act: {
-		run: async (_args: string[], options: Record<string, any>) => {
+		run: async (args: string[], options: Record<string, any>) => {
 			if (options.help) return console.log(actHelp)
 			await runCommand(
 				act({
+					directory: args[0],
 					auto: options.auto,
 					draft: options.draft,
 					dryRun: options["dry-run"],

package/package.json

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

package/src/cli-parser.test.ts

@@ -31,7 +31,10 @@ describe("strict CLI parsing", () => {
 			},
 		})
 		expect(parseCli(["act", "--json"]).values.json).toBe(true)
-		expectUsageError(["act", "task-id"], "agency act")
+		expect(parseCli(["act", "task-id"]).args).toEqual(["task-id"])
+		expect(parseCli(["act", "."]).args).toEqual(["."])
+		expectUsageError(["act", "one", "two"], "agency act")
+		expectUsageError(["act", ".", "--task", "example"], "agency act")
 		expectUsageError(["act", "--phase", "build"], "agency act")
 		expectUsageError(
 			["act", "--epic", "roadmap", "--task", "example"],

package/src/cli-parser.ts

@@ -148,7 +148,7 @@ const commands = {
 	},
 	act: {
 		usage:
-			"agency act [--epic <id> | --task <id> [--phase <id>]] [--dry-run | --json] [--auto] [--draft]",
+			"agency act [<directory-or-task-id> | --epic <id> | --task <id> [--phase <id>]] [--dry-run | --json] [--auto] [--draft]",
 		options: {
 			...outputOptions,
 			...entitySelectorOptions,
@@ -158,9 +158,9 @@ const commands = {
 		},
 		command: {
 			usage:
-				"agency act [--epic <id> | --task <id> [--phase <id>]] [--dry-run | --json] [--auto] [--draft]",
+				"agency act [<directory-or-task-id> | --epic <id> | --task <id> [--phase <id>]] [--dry-run | --json] [--auto] [--draft]",
 			minArgs: 0,
-			maxArgs: 0,
+			maxArgs: 1,
 			options: ["epic", "task", "phase", "dry-run", "json", "auto", "draft"],
 			conflicts: [
 				["dry-run", "json"],
@@ -1198,7 +1198,7 @@ function applyEntitySelectors(
 			spec.usage,
 		)
 	}
-	if (commandName === "work" || commandName === "context") {
+	if (["act", "work", "context"].includes(commandName)) {
 		if (
 			positionals.length >
 			(commandName === "work" && positionals[0] === "prepare" ? 1 : 0)

package/src/commands/act.test.ts

@@ -1,5 +1,6 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
+import { mkdir } from "node:fs/promises"
 import { join } from "node:path"
 import {
 	captureLogs,
@@ -118,6 +119,100 @@ describe("act command", () => {
 		expect(await readTaskStatus("example")).toBe("open")
 	})
 
+	test("resolves a positional path and task ID without prompting for an item", async () => {
+		await createTask("example")
+		await mkdir(join(root, "tasks/example/code/agency"), { recursive: true })
+		for (const options of [
+			{ cwd: join(root, "tasks/example"), directory: "." },
+			{ cwd: join(root, "tasks/example"), directory: "code/agency" },
+			{ cwd: root, directory: "example" },
+		]) {
+			const prompts: string[] = []
+			await runTestEffect(
+				act(
+					{ ...options, inputAllowed: true, dryRun: true, silent: true },
+					scriptedInteraction(["drop"], (prompt) => prompts.push(prompt)),
+				),
+			)
+			expect(prompts).toEqual(["Act on task example"])
+		}
+	})
+
+	test("resolves a positional phase path without prompting for an item", async () => {
+		await runTestEffect(
+			task({
+				subcommand: "create",
+				args: ["multi"],
+				multiPhase: true,
+				cwd: root,
+				silent: true,
+			}),
+		)
+		await runTestEffect(
+			phase({
+				subcommand: "create",
+				args: ["multi", "build"],
+				repo: "agency",
+				branch: "task/multi-build",
+				base: "main",
+				cwd: root,
+				silent: true,
+			}),
+		)
+		const prompts: string[] = []
+		await runTestEffect(
+			act(
+				{
+					cwd: join(root, "tasks/multi/phases/build"),
+					directory: ".",
+					inputAllowed: true,
+					dryRun: true,
+					silent: true,
+				},
+				scriptedInteraction(["drop"], (prompt) => prompts.push(prompt)),
+			),
+		)
+
+		expect(prompts).toEqual(["Act on phase multi/build"])
+	})
+
+	test("orders owned items hierarchically and omits items without actions", async () => {
+		await runTestEffect(
+			task({
+				subcommand: "create",
+				args: ["multi"],
+				multiPhase: true,
+				cwd: root,
+				silent: true,
+			}),
+		)
+		await runTestEffect(
+			phase({
+				subcommand: "create",
+				args: ["multi", "build"],
+				repo: "agency",
+				branch: "task/multi-build",
+				base: "main",
+				cwd: root,
+				silent: true,
+			}),
+		)
+		let choices: readonly Choice<unknown>[] = []
+		await runTestEffect(
+			act(
+				{ cwd: root, inputAllowed: true },
+				scriptedInteraction([null], (_prompt, offered) => {
+					choices = offered
+				}),
+			),
+		)
+
+		expect(choices.map((choice) => [choice.value, choice.depth])).toEqual([
+			["task:multi", 0],
+			["phase:multi/build", 1],
+		])
+	})
+
 	test("returns structured actions and argv for agents", async () => {
 		await createTask("example")
 		const logs = await captureLogs(() =>

package/src/commands/act.ts

@@ -1,6 +1,8 @@
 import { Effect } from "effect"
+import { isAbsolute, relative, resolve, sep } from "node:path"
 import type { GraphNode } from "../graph-schema"
 import { isTerminalStatus } from "../readiness"
+import { FileSystemService } from "../services/FileSystemService"
 import { GraphService } from "../services/GraphService"
 import { WorkbaseService } from "../services/WorkbaseService"
 import type { BaseCommandOptions } from "../utils/command"
@@ -29,6 +31,7 @@ export interface ActInteraction {
 }
 
 interface ActOptions extends BaseCommandOptions {
+	readonly directory?: string
 	readonly auto?: boolean
 	readonly draft?: boolean
 	readonly dryRun?: boolean
@@ -49,13 +52,49 @@ const entityDescription = (node: EntityNode) =>
 		? ` - ${node.data.description}`
 		: ""
 
+const orderedEntities = (
+	nodes: readonly EntityNode[],
+	edges: readonly {
+		readonly kind: string
+		readonly from: string
+		readonly to: string
+	}[],
+) => {
+	const byId = new Map(nodes.map((node) => [node.id, node]))
+	const children = new Map<string, EntityNode[]>()
+	const owned = new Set<string>()
+	for (const edge of edges) {
+		if (edge.kind !== "owns") continue
+		const parent = byId.get(edge.from)
+		const child = byId.get(edge.to)
+		if (!parent || !child) continue
+		children.set(edge.from, [...(children.get(edge.from) ?? []), child])
+		owned.add(child.id)
+	}
+
+	const ordered: { readonly node: EntityNode; readonly depth: number }[] = []
+	const append = (node: EntityNode, depth: number) => {
+		ordered.push({ node, depth })
+		for (const child of children.get(node.id) ?? []) append(child, depth + 1)
+	}
+	for (const node of nodes) {
+		if (!owned.has(node.id)) append(node, 0)
+	}
+	return ordered
+}
+
 const entityChoices = (
 	nodes: readonly EntityNode[],
+	edges: readonly {
+		readonly kind: string
+		readonly from: string
+		readonly to: string
+	}[],
 ): readonly Choice<string>[] =>
-	nodes.map((node, index) => ({
+	orderedEntities(nodes, edges).map(({ node, depth }, index) => ({
 		key: String(index),
 		label: `[${node.status}] ${node.kind} ${node.key}${entityDescription(node)}`,
-		depth: node.kind === "phase" ? 1 : 0,
+		depth,
 		segments: [
 			{ text: `[${node.status}] `, color: macchiato.overlay1 },
 			{ text: `${node.kind} `, color: macchiato.sapphire },
@@ -229,6 +268,26 @@ const selectedEntityKey = (options: ActOptions) =>
 				? `task:${options.taskId}`
 				: undefined
 
+const pathEntityKey = (
+	directory: string | undefined,
+	isDirectory: boolean,
+	root: string,
+	startPath: string,
+) => {
+	if (!directory) return undefined
+	if (!isDirectory) return `task:${directory}`
+	const path = relative(root, startPath)
+	const parts =
+		!path || isAbsolute(path) || path.startsWith(`..${sep}`)
+			? []
+			: path.split(sep)
+	if (parts[0] === "epics" && parts[1]) return `epic:${parts[1]}`
+	if (parts[0] !== "tasks" || !parts[1]) return undefined
+	return parts[2] === "phases" && parts[3]
+		? `phase:${parts[1]}/${parts[3]}`
+		: `task:${parts[1]}`
+}
+
 const sameActions = (
 	left: readonly Choice<ActAction>[],
 	right: readonly Choice<ActAction>[],
@@ -250,11 +309,19 @@ export const act = (
 			)
 		}
 		const cwd = options.cwd ?? process.cwd()
+		const fs = yield* FileSystemService
 		const workbase = yield* WorkbaseService
 		const graphs = yield* GraphService
 		const { log } = createLoggers(options)
-		const { config } = yield* workbase.loadConfig(cwd)
-		const graph = yield* graphs.get({ cwd })
+		const directoryPath = options.directory
+			? resolve(cwd, options.directory)
+			: undefined
+		const isDirectory = directoryPath
+			? yield* fs.isDirectory(directoryPath)
+			: false
+		const startPath = isDirectory && directoryPath ? directoryPath : cwd
+		const { root, config } = yield* workbase.loadConfig(startPath)
+		const graph = yield* graphs.get({ cwd: root })
 		const nodes = graph.nodes.filter(
 			(node): node is EntityNode =>
 				node.kind === "epic" || node.kind === "task" || node.kind === "phase",
@@ -269,7 +336,9 @@ export const act = (
 			)
 		}
 
-		const requestedKey = selectedEntityKey(options)
+		const requestedKey =
+			selectedEntityKey(options) ??
+			pathEntityKey(options.directory, isDirectory, root, startPath)
 		const matchingNodes = requestedKey
 			? nodes.filter((node) => entityKey(node) === requestedKey)
 			: nodes
@@ -293,11 +362,21 @@ export const act = (
 			return
 		}
 
+		const selectableNodes = nodes.filter(
+			(node) => actionChoices(node, graph.nodes).length > 0,
+		)
+		if (!requestedKey && selectableNodes.length === 0) {
+			return yield* Effect.fail(
+				new Error(
+					"No work items with available actions found in this workbase",
+				),
+			)
+		}
 		const selectedKey =
 			requestedKey ??
 			(yield* interaction.select(
 				"Act on",
-				entityChoices(nodes),
+				entityChoices(selectableNodes, graph.edges),
 				config.chooserCommand,
 			))
 		if (selectedKey === null) return
@@ -424,10 +503,12 @@ export const act = (
 	})
 
 export const help = `
-Usage: agency act [--epic <id> | --task <id> [--phase <id>]] [--dry-run | --json] [--auto] [--draft]
+Usage: agency act [<directory-or-task-id> | --epic <id> | --task <id> [--phase <id>]] [--dry-run | --json] [--auto] [--draft]
 
 Interactively choose an active work item and a state-aware lifecycle action.
-Selectors skip work-item selection. --dry-run prints the selected action's exact
+An existing positional directory selects its containing epic, task, or phase;
+otherwise the positional value is a task ID. Selectors skip work-item selection.
+--dry-run prints the selected action's exact
 Agency command without executing it. --json lists targets, available actions,
 and command argv without prompting or executing.
 

package/src/commands/context.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
-import { mkdir, rm } from "node:fs/promises"
+import { mkdir, rename, rm } from "node:fs/promises"
 import { dirname, join } from "node:path"
 import {
 	captureLogs,
@@ -342,6 +342,123 @@ status: dropped
 		expect(result.authority.writable.branch).toBe("foundations")
 	})
 
+	test("resolves archived tasks without granting mutation or execution authority", async () => {
+		await mkdir(join(root, "archive/tasks"), { recursive: true })
+		await rename(
+			join(root, "tasks/foundations"),
+			join(root, "archive/tasks/foundations"),
+		)
+
+		const result = await readContext(root, "foundations")
+
+		expect(result.target).toMatchObject({
+			kind: "task",
+			taskId: "foundations",
+			archived: true,
+			path: join(root, "archive/tasks/foundations/TASK.md"),
+		})
+		expect(result.documents.task.body).toContain("# Foundations")
+		expect(result.authority).toMatchObject({
+			mode: "orchestration",
+			writable: null,
+			references: [],
+			documents: { writable: [] },
+		})
+		expect(result.workspace).toMatchObject({
+			materialization: "absent",
+			writable: null,
+			references: [],
+		})
+		expect(result.graph.readiness).toMatchObject({
+			ready: false,
+			blocked: true,
+		})
+		expect(result.graph.readiness.blockers).toContainEqual({
+			kind: "status",
+			id: "foundations",
+			reason: "Target is archived; restore it before mutation or execution",
+		})
+		expect(result.pr).toMatchObject({
+			url: "https://github.com/example/agency/pull/1",
+			state: "open",
+		})
+	})
+
+	test("resolves archived phases with their active parent context", async () => {
+		await mkdir(join(root, "archive/tasks/agent-contract/phases"), {
+			recursive: true,
+		})
+		await rename(
+			join(root, "tasks/agent-contract/phases/context-command"),
+			join(root, "archive/tasks/agent-contract/phases/context-command"),
+		)
+
+		const result = await readContext(
+			root,
+			"archive/tasks/agent-contract/phases/context-command",
+		)
+
+		expect(result.target).toMatchObject({
+			kind: "phase",
+			taskId: "agent-contract",
+			phaseId: "context-command",
+			archived: true,
+			path: join(
+				root,
+				"archive/tasks/agent-contract/phases/context-command/PHASE.md",
+			),
+		})
+		expect(result.documents.task.body).toContain("Task prose.")
+		expect(result.documents.phase.body).toContain("Phase prose.")
+		expect(result.graph.parent).toEqual({ kind: "task", id: "agent-contract" })
+		expect(result.graph.readiness).toMatchObject({
+			ready: false,
+			blocked: true,
+		})
+		expect(result.authority).toMatchObject({
+			mode: "orchestration",
+			writable: null,
+			references: [],
+			documents: { writable: [] },
+		})
+	})
+
+	test("resolves archived epics with archived descendant graph context", async () => {
+		await mkdir(join(root, "archive/epics"), { recursive: true })
+		await mkdir(join(root, "archive/tasks"), { recursive: true })
+		await rename(
+			join(root, "epics/contract"),
+			join(root, "archive/epics/contract"),
+		)
+		for (const taskId of ["agent-contract", "foundations"]) {
+			await rename(
+				join(root, "tasks", taskId),
+				join(root, "archive/tasks", taskId),
+			)
+		}
+
+		const result = await readContext(root, "epics/contract")
+
+		expect(result.target).toMatchObject({
+			kind: "epic",
+			epicId: "contract",
+			archived: true,
+			path: join(root, "archive/epics/contract/EPIC.md"),
+		})
+		expect(result.documents.epic.body).toContain("# Contract")
+		expect(result.graph.aggregate).toMatchObject({ total: 3, done: 2, open: 1 })
+		expect(result.graph.readiness).toMatchObject({
+			ready: false,
+			blocked: true,
+		})
+		expect(result.authority).toMatchObject({
+			mode: "orchestration",
+			writable: null,
+			references: [],
+			documents: { writable: [] },
+		})
+	})
+
 	test("computes orchestration readiness from runnable descendants", async () => {
 		await write(
 			root,

package/src/commands/context.ts

@@ -23,7 +23,9 @@ Usage: agency context [target] [options]
 
 Return complete, read-only context for a workbase, epic, task, or phase. The
 target defaults to the current directory and may be the workbase root, an entity
-path, or a task ID. Workbase context catalogs all epics, tasks, and phases.
+path, or a task ID. Archived entities are inspectable but never receive mutation
+or execution authority. Workbase context catalogs all active epics, tasks, and
+phases.
 
 Options:
   --json              Output a versioned machine result

package/src/services/ContextService.ts

@@ -20,6 +20,11 @@ import {
 	type TaskFrontmatter as TaskData,
 	type WorkStatus,
 } from "../workbase/schemas"
+import {
+	archivedEpicDirectory,
+	archivedPhaseDirectory,
+	archivedTaskDirectory,
+} from "../workbase/archive"
 
 class ContextError extends Data.TaggedError("ContextError")<{
 	readonly message: string
@@ -36,6 +41,7 @@ interface Document<T> {
 
 interface Target {
 	readonly kind: "epic" | "task" | "phase"
+	readonly archived: boolean
 	readonly epicId?: string
 	readonly taskId?: string
 	readonly phaseId?: string
@@ -240,15 +246,45 @@ export class ContextService extends Effect.Service<ContextService>()(
 						if (!candidateExists && !suppliedTarget.includes(sep)) {
 							return {
 								kind: "task",
+								archived: false,
 								taskId: suppliedTarget,
 								path: join(root, "tasks", suppliedTarget, "TASK.md"),
 							}
 						}
 						if (!isWithin(root, candidate)) return null
 						const parts = relative(root, candidate).split(sep)
+						if (parts[0] === "archive" && parts[1] === "epics" && parts[2]) {
+							return {
+								kind: "epic",
+								archived: true,
+								epicId: parts[2],
+								path: join(archivedEpicDirectory(root, parts[2]), "EPIC.md"),
+							}
+						}
+						if (parts[0] === "archive" && parts[1] === "tasks" && parts[2]) {
+							if (parts[3] === "phases" && parts[4]) {
+								return {
+									kind: "phase",
+									archived: true,
+									taskId: parts[2],
+									phaseId: parts[4],
+									path: join(
+										archivedPhaseDirectory(root, parts[2], parts[4]),
+										"PHASE.md",
+									),
+								}
+							}
+							return {
+								kind: "task",
+								archived: true,
+								taskId: parts[2],
+								path: join(archivedTaskDirectory(root, parts[2]), "TASK.md"),
+							}
+						}
 						if (parts[0] === "epics" && parts[1]) {
 							return {
 								kind: "epic",
+								archived: false,
 								epicId: parts[1],
 								path: join(root, "epics", parts[1], "EPIC.md"),
 							}
@@ -257,6 +293,7 @@ export class ContextService extends Effect.Service<ContextService>()(
 							if (parts[2] === "phases" && parts[3]) {
 								return {
 									kind: "phase",
+									archived: false,
 									taskId: parts[1],
 									phaseId: parts[3],
 									path: join(
@@ -271,6 +308,7 @@ export class ContextService extends Effect.Service<ContextService>()(
 							}
 							return {
 								kind: "task",
+								archived: false,
 								taskId: parts[1],
 								path: join(root, "tasks", parts[1], "TASK.md"),
 							}
@@ -278,13 +316,32 @@ export class ContextService extends Effect.Service<ContextService>()(
 						return null
 					}
 
-					const target = inferTarget()
-					if (!target) {
+					const inferredTarget = inferTarget()
+					if (!inferredTarget) {
 						return yield* new ContextError({
 							target: suppliedTarget,
 							message: `Cannot infer an Agency target from ${candidate}`,
 						})
 					}
+					let target = inferredTarget
+					if (!target.archived && !(yield* fs.exists(target.path))) {
+						const archivedPath =
+							target.kind === "epic"
+								? join(archivedEpicDirectory(root, target.epicId!), "EPIC.md")
+								: target.kind === "phase"
+									? join(
+											archivedPhaseDirectory(
+												root,
+												target.taskId!,
+												target.phaseId!,
+											),
+											"PHASE.md",
+										)
+									: join(archivedTaskDirectory(root, target.taskId!), "TASK.md")
+						if (yield* fs.exists(archivedPath)) {
+							target = { ...target, archived: true, path: archivedPath }
+						}
+					}
 
 					const readDocument = <S extends Schema.Schema.AnyNoContext>(
 						id: string,
@@ -334,26 +391,22 @@ export class ContextService extends Effect.Service<ContextService>()(
 							return yield* readDocument(id, path, schema)
 						})
 
-					const task = target.taskId
-						? yield* readDocument(
-								target.taskId,
-								join(root, "tasks", target.taskId, "TASK.md"),
-								TaskFrontmatter,
-							)
+					const activeTaskPath = target.taskId
+						? join(root, "tasks", target.taskId, "TASK.md")
+						: null
+					const taskPath = target.taskId
+						? target.kind === "task"
+							? target.path
+							: activeTaskPath && (yield* fs.exists(activeTaskPath))
+								? activeTaskPath
+								: join(archivedTaskDirectory(root, target.taskId), "TASK.md")
 						: null
+					const task =
+						target.taskId && taskPath
+							? yield* readDocument(target.taskId, taskPath, TaskFrontmatter)
+							: null
 					const phase = target.phaseId
-						? yield* readDocument(
-								target.phaseId,
-								join(
-									root,
-									"tasks",
-									target.taskId!,
-									"phases",
-									target.phaseId,
-									"PHASE.md",
-								),
-								PhaseFrontmatter,
-							)
+						? yield* readDocument(target.phaseId, target.path, PhaseFrontmatter)
 						: null
 					const epicId =
 						target.epicId ??
@@ -361,7 +414,11 @@ export class ContextService extends Effect.Service<ContextService>()(
 					const epic = epicId
 						? yield* readOptionalDocument(
 								epicId,
-								join(root, "epics", epicId, "EPIC.md"),
+								target.kind === "epic"
+									? target.path
+									: (yield* fs.exists(join(root, "epics", epicId, "EPIC.md")))
+										? join(root, "epics", epicId, "EPIC.md")
+										: join(archivedEpicDirectory(root, epicId), "EPIC.md"),
 								EpicFrontmatter,
 							)
 						: null
@@ -374,8 +431,11 @@ export class ContextService extends Effect.Service<ContextService>()(
 
 					const taskDocuments = new Map<string, Document<TaskData>>()
 					const phaseDocuments = new Map<string, Document<PhaseData>>()
-					const taskRoot = join(root, "tasks")
-					if (yield* fs.isDirectory(taskRoot)) {
+					for (const taskRoot of [
+						join(root, "tasks"),
+						join(root, "archive", "tasks"),
+					]) {
+						if (!(yield* fs.isDirectory(taskRoot))) continue
 						const entries = (yield* fs.readDirectory(taskRoot))
 							.filter((entry) => entry.isDirectory)
 							.sort((a, b) => a.name.localeCompare(b.name))
@@ -455,14 +515,18 @@ export class ContextService extends Effect.Service<ContextService>()(
 							{ concurrency: "unbounded" },
 						)
 						for (const document of documents) {
-							if (document.taskDocument) {
+							if (
+								document.taskDocument &&
+								!taskDocuments.has(document.taskDocument.id)
+							) {
 								taskDocuments.set(
 									document.taskDocument.id,
 									document.taskDocument,
 								)
 							}
 							for (const [key, phaseDocument] of document.phaseDocuments) {
-								phaseDocuments.set(key, phaseDocument)
+								if (!phaseDocuments.has(key))
+									phaseDocuments.set(key, phaseDocument)
 							}
 						}
 					}
@@ -751,6 +815,18 @@ export class ContextService extends Effect.Service<ContextService>()(
 					const orchestrationTarget =
 						target.kind === "epic" ||
 						(target.kind === "task" && task !== null && "phases" in task.data)
+					if (target.archived) {
+						blockers.push({
+							kind: "status",
+							id:
+								target.phaseId ??
+								target.taskId ??
+								target.epicId ??
+								suppliedTarget,
+							reason:
+								"Target is archived; restore it before mutation or execution",
+						})
+					}
 					if (!orchestrationTarget && targetStatus !== "open") {
 						blockers.push({
 							kind: "status",
@@ -773,17 +849,22 @@ export class ContextService extends Effect.Service<ContextService>()(
 						})
 					}
 					const ready = orchestrationTarget
-						? descendantsReady &&
+						? !target.archived &&
+							descendantsReady &&
 							!blockers.some((blocker) => blocker.kind === "validation")
 						: targetStatus === "open" && blockers.length === 0
 
-					const executionData: ExecutionData | null = phase?.data
-						? phase.data
-						: task?.data && "repo" in task.data
-							? (task.data as ExecutionData)
-							: null
+					const executionData: ExecutionData | null = target.archived
+						? null
+						: phase?.data
+							? phase.data
+							: task?.data && "repo" in task.data
+								? (task.data as ExecutionData)
+								: null
 					const reviewData =
-						task?.data && "review" in task.data ? task.data.review : null
+						!target.archived && task?.data && "review" in task.data
+							? task.data.review
+							: null
 					const writableDocuments = reviewData
 						? task
 							? [task.path]
@@ -793,11 +874,13 @@ export class ContextService extends Effect.Service<ContextService>()(
 								? [task.path, phase.path]
 								: [task.path]
 							: []
-					const references: readonly RepositoryReference[] = reviewData
-						? [{ repo: reviewData.repo, ref: reviewData.commit }]
-						: executionData
-							? (executionData.repos ?? [])
-							: (epic?.data.repos ?? [])
+					const references: readonly RepositoryReference[] = target.archived
+						? []
+						: reviewData
+							? [{ repo: reviewData.repo, ref: reviewData.commit }]
+							: executionData
+								? (executionData.repos ?? [])
+								: (epic?.data.repos ?? [])
 					const entityDirectory = target.path.replace(
 						/\/(?:EPIC|TASK|PHASE)\.md$/,
 						"",
@@ -1035,6 +1118,9 @@ export class ContextService extends Effect.Service<ContextService>()(
 									}
 								: document
 							: null
+					const pullRequestData =
+						phase?.data ??
+						(task?.data && "repo" in task.data ? task.data : null)
 
 					return {
 						projection: options.compact ? "compact" : "complete",
@@ -1124,8 +1210,8 @@ export class ContextService extends Effect.Service<ContextService>()(
 									checkout: referenceCheckouts[0] ?? null,
 								}
 							: null,
-						pr: executionData?.pr
-							? normalizePullRequestRecord(executionData.pr)
+						pr: pullRequestData?.pr
+							? normalizePullRequestRecord(pullRequestData.pr)
 							: { url: null, state: "none" },
 						validation: {
 							valid: validation.valid,

package/src/services/IntegrationService.test.ts

@@ -174,6 +174,18 @@ describe("IntegrationService", () => {
 		expect(managedWorkbaseOpencodePlugin).toContain(
 			"Do not invoke agency work for this target",
 		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"as the default implementation directory",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"Set each tool's working directory to that checkout when supported",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"Run Agency lifecycle and context commands from the task or phase directory",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"reference checkouts reported by Agency context are read-only",
+		)
 		expect(managedWorkbaseOpencodePlugin).toContain(
 			".map((path) => `${path}${sep}.`)",
 		)
@@ -187,23 +199,39 @@ describe("IntegrationService", () => {
 		).toBe(false)
 	})
 
-	test("binds validated worker identity to an OpenCode session", async () => {
+	const testWorkerIdentity = async ({
+		target,
+		launchTarget,
+		phase,
+	}: {
+		readonly target:
+			| { readonly kind: "task"; readonly taskId: string }
+			| {
+					readonly kind: "phase"
+					readonly taskId: string
+					readonly phaseId: string
+			  }
+		readonly launchTarget: string
+		readonly phase?: string
+	}) => {
 		const path = join(root, "agency-repository-skills.ts")
+		const checkoutPath = join(root, "code/agency")
 		const contextResponse = JSON.stringify({
 			version: 1,
 			ok: true,
 			result: {
 				workbase: { root },
 				target: {
-					kind: "task",
-					taskId: "example",
-					path: join(root, "TASK.md"),
+					...target,
+					path: join(root, phase ? "PHASE.md" : "TASK.md"),
 				},
 				authority: {
 					mode: "execution",
-					writable: { checkoutPath: join(root, "tasks/example/code/agency") },
+					writable: { checkoutPath },
 				},
-				documents: { task: { data: { status: "working" } } },
+				documents: phase
+					? { phase: { data: { status: "working" } } }
+					: { task: { data: { status: "working" } } },
 				validation: { valid: true, warnings: [] },
 			},
 		})
@@ -225,27 +253,28 @@ describe("IntegrationService", () => {
 			}) as ReturnType<typeof Bun.spawn>) as typeof Bun.spawn
 		try {
 			const generated = await import(
-				`${pathToFileURL(path).href}?worker-identity`
+				`${pathToFileURL(path).href}?worker-identity=${encodeURIComponent(launchTarget)}`
 			)
 			expect(
 				generated.workerLaunchTarget([
 					{
 						type: "text",
-						text: "Agency worker launch target: execution-unit:task/example. Start the task.",
+						text: `Agency worker launch target: ${launchTarget}. Start the task.`,
 					},
 				]),
-			).toBe("execution-unit:task/example")
+			).toBe(launchTarget)
 			expect(generated.workerLaunchTarget(undefined)).toBeUndefined()
 			expect(
 				generated.contextTarget({
-					target: { kind: "task", taskId: "example" },
+					target,
 					authority: { mode: "execution" },
 				}),
-			).toBe("execution-unit:task/example")
+			).toBe(launchTarget)
 			expect(await generated.agencyContext(root)).toMatchObject({
 				root,
-				target: "execution-unit:task/example",
+				target: launchTarget,
 				task: "example",
+				phase,
 			})
 			const hooks = await generated.default({ directory: root } as never)
 			await hooks["chat.message"]!(
@@ -254,7 +283,7 @@ describe("IntegrationService", () => {
 					parts: [
 						{
 							type: "text",
-							text: "Agency worker launch target: execution-unit:task/example. Start the task.",
+							text: `Agency worker launch target: ${launchTarget}. Start the task.`,
 						},
 					],
 				} as never,
@@ -276,11 +305,17 @@ describe("IntegrationService", () => {
 				{ sessionID: "worker-session" } as never,
 				system,
 			)
-			expect(system.system).toEqual([
-				expect.stringContaining(
-					"active worker for execution-unit:task/example",
-				),
-			])
+			expect(system.system).toHaveLength(1)
+			expect(system.system[0]).toContain(`active worker for ${launchTarget}`)
+			expect(system.system[0]).toContain(
+				`${checkoutPath} as the default implementation directory`,
+			)
+			expect(system.system[0]).toContain(
+				"Run Agency lifecycle and context commands from the task or phase directory",
+			)
+			expect(system.system[0]).toContain(
+				"reference checkouts reported by Agency context are read-only",
+			)
 			const mismatchedSystem = { system: [] as string[] }
 			await hooks["experimental.chat.system.transform"]!(
 				{ sessionID: "mismatched-session" } as never,
@@ -292,15 +327,29 @@ describe("IntegrationService", () => {
 			await hooks["shell.env"]!({ sessionID: "worker-session" } as never, shell)
 			expect(shell.env).toMatchObject({
 				AGENCY_SESSION_ID: "worker-session",
-				AGENCY_TARGET: "execution-unit:task/example",
+				AGENCY_TARGET: launchTarget,
 				AGENCY_WORKBASE: root,
 				AGENCY_TASK_ID: "example",
-				AGENCY_WRITABLE_CHECKOUT: join(root, "tasks/example/code/agency"),
+				AGENCY_WRITABLE_CHECKOUT: checkoutPath,
 			})
+			if (phase) expect(shell.env.AGENCY_PHASE_ID).toBe(phase)
 		} finally {
 			Bun.spawn = originalSpawn
 		}
-	})
+	}
+
+	test("binds validated task worker identity to an OpenCode session", () =>
+		testWorkerIdentity({
+			target: { kind: "task", taskId: "example" },
+			launchTarget: "execution-unit:task/example",
+		}))
+
+	test("binds validated phase worker identity to an OpenCode session", () =>
+		testWorkerIdentity({
+			target: { kind: "phase", taskId: "example", phaseId: "build" },
+			launchTarget: "execution-unit:phase/example/build",
+			phase: "build",
+		}))
 
 	test("registers a TUI-only /agency-debug diagnostic", async () => {
 		const config = JSON.parse(managedBody(managedWorkbaseOpencodeTui))

package/src/workbase/opencode-plugin-file.ts

@@ -164,7 +164,12 @@ const plugin: Plugin = async ({ directory }) => {
       const context = workerSessions.get(sessionID)
       if (!context?.target) return
       output.system.push(
-        \`Agency verified this OpenCode session as the active worker for \${context.target}. Perform the assigned work directly. Do not invoke agency work for this target or launch a replacement worker.\`,
+        [
+          \`Agency verified this OpenCode session as the active worker for \${context.target}. Perform the assigned work directly. Do not invoke agency work for this target or launch a replacement worker.\`,
+          context.checkout
+            ? \`OpenCode remains rooted in the task or phase directory for Agency instructions and context. Treat \${context.checkout} as the default implementation directory: use it for source reads, edits, repository status, builds, tests, formatting, and other repository-local commands. Set each tool's working directory to that checkout when supported; otherwise use absolute paths. Run Agency lifecycle and context commands from the task or phase directory. Any reference checkouts reported by Agency context are read-only.\`
+            : undefined,
+        ].filter(Boolean).join(" "),
       )
     },
     "shell.env": async ({ sessionID }, output) => {