@markjaquith/agency 2.62.0 → 2.63.0

package/README.md

@@ -535,6 +535,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/package.json

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

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,