@markjaquith/agency 2.9.0 → 2.10.0

package/README.md

@@ -231,12 +231,30 @@ agency repo link backend ~/Dev/backend
 agency task new
 
 agency validate
+agency context tasks/refresh-copy --json
 agency work tasks/refresh-copy
 agency pr create refresh-copy
 ```
 
 ## Commands
 
+### Target Context
+
+`agency context [target] --json` returns the complete bootstrap context for an
+epic, task, or phase without modifying the workbase or fetching repositories.
+The target defaults to the current directory; entity directories, document
+paths, checkout descendants, and bare task IDs are accepted.
+
+The result includes workbase and target identity, ancestor frontmatter and prose
+with SHA-256 hashes, dependency and readiness state, aggregate status, writable
+and reference authority, local checkout and resolved-commit state, recorded PR
+state, and validation warnings. Only `done` satisfies a dependency; `dropped` is
+terminal but remains a blocker.
+
+Complete output is the default. Pass `--compact` explicitly to omit document
+prose and low-level Git details while retaining identity, hashes, authority,
+paths, graph state, materialization state, and validation warnings.
+
 ### Workbase and Repositories
 
 ```text

package/cli.ts

@@ -8,6 +8,7 @@ import { pr, help as prHelp } from "./src/commands/pr"
 import { work, help as workHelp } from "./src/commands/work"
 import { status, help as statusHelp } from "./src/commands/status"
 import { validate, help as validateHelp } from "./src/commands/validate"
+import { context, help as contextHelp } from "./src/commands/context"
 import { repo, help as repoHelp } from "./src/commands/repo"
 import { epic, help as epicHelp } from "./src/commands/epic"
 import { phase, help as phaseHelp } from "./src/commands/phase"
@@ -28,6 +29,7 @@ import { WorktreeService } from "./src/services/WorktreeService"
 import { PullRequestService } from "./src/services/PullRequestService"
 import { ArchiveService } from "./src/services/ArchiveService"
 import { IntegrationService } from "./src/services/IntegrationService"
+import { ContextService } from "./src/services/ContextService"
 import {
 	collectCommandResult,
 	errorEnvelope,
@@ -47,6 +49,7 @@ const CliLayer = Layer.mergeAll(
 	PullRequestService.Default,
 	ArchiveService.Default,
 	IntegrationService.Default,
+	ContextService.Default,
 )
 
 /**
@@ -313,6 +316,23 @@ const commands: Record<string, Command> = {
 			)
 		},
 	},
+	context: {
+		run: async (args: string[], options: Record<string, any>) => {
+			if (options.help) {
+				console.log(contextHelp)
+				return
+			}
+			await runCommand(
+				context({
+					target: args[0],
+					compact: options.compact,
+					json: options.json,
+					silent: options.silent,
+					verbose: options.verbose,
+				}),
+			)
+		},
+	},
 }
 
 function showMainHelp() {
@@ -334,6 +354,7 @@ Commands:
   repo <subcommand>      Manage workbase repositories
   status                 Show status for the current workbase
   validate [path]        Validate a workbase
+  context [target]       Return complete target context
 
 Global Options:
   -h, --help             Show help for a command

package/package.json

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

package/src/cli-parser.test.ts

@@ -139,11 +139,21 @@ describe("strict CLI parsing", () => {
 			[["pr", "create", "one", "two", "three"], "agency pr create"],
 			[["status", "extra"], "agency status"],
 			[["validate", "one", "two"], "agency validate"],
+			[["context", "one", "two"], "agency context"],
 		] as const) {
 			expectUsageError([...args], usage)
 		}
 	})
 
+	test("accepts context projections and keeps compact command-local", () => {
+		expect(parseCli(["context", ".", "--json", "--compact"])).toMatchObject({
+			commandName: "context",
+			args: ["."],
+			values: { json: true, compact: true },
+		})
+		expectUsageError(["status", "--compact"], "agency status")
+	})
+
 	test("reports unknown subcommands with parent usage", () => {
 		expect(() => parseCli(["task", "crate"])).toThrow(
 			"Unknown subcommand 'crate'",

package/src/cli-parser.ts

@@ -338,6 +338,19 @@ const commands = {
 			options: ["json"],
 		},
 	},
+	context: {
+		usage: "agency context [target] [--json] [--compact]",
+		options: {
+			...outputOptions,
+			compact: { type: "boolean" },
+		},
+		command: {
+			usage: "agency context [target] [--json] [--compact]",
+			minArgs: 0,
+			maxArgs: 1,
+			options: ["json", "compact"],
+		},
+	},
 } satisfies Readonly<Record<string, CommandDefinition>>
 
 const rootOptions = commonOptions

package/src/cli.test.ts

@@ -158,6 +158,7 @@ describe("CLI", () => {
 			["pr", "Usage: agency pr"],
 			["status", "Usage: agency status"],
 			["validate", "Usage: agency validate"],
+			["context", "Usage: agency context"],
 		] as const) {
 			const result = await runCli([command, "--help"])
 			expect(result.exitCode).toBe(0)

package/src/commands/context.test.ts

@@ -0,0 +1,379 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { mkdir, rm } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import {
+	captureLogs,
+	cleanupTempDir,
+	createTempDir,
+	runTestEffect,
+} from "../test-utils"
+import { context } from "./context"
+
+const write = async (root: string, path: string, content: string) => {
+	const fullPath = join(root, path)
+	await mkdir(dirname(fullPath), { recursive: true })
+	await Bun.write(fullPath, content)
+}
+
+const run = async (cwd: string, args: string[]) => {
+	const process = Bun.spawn(args, { cwd, stdout: "pipe", stderr: "pipe" })
+	const [exitCode, stderr] = await Promise.all([
+		process.exited,
+		new Response(process.stderr).text(),
+	])
+	if (exitCode !== 0) throw new Error(`${args.join(" ")}: ${stderr}`)
+}
+
+const readContext = async (
+	root: string,
+	target: string | undefined,
+	compact = false,
+) => {
+	const logs = await captureLogs(() =>
+		runTestEffect(context({ cwd: root, target, compact, json: true })),
+	)
+	expect(logs).toHaveLength(1)
+	return JSON.parse(logs[0]!)
+}
+
+describe("context", () => {
+	let root: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		await write(root, "agency.json", '{"version":2}\n')
+		for (const repo of ["agency", "docs"]) {
+			const path = join(root, "repos", repo)
+			await mkdir(path, { recursive: true })
+			await run(root, ["git", "init", "--initial-branch=main", path])
+			await run(path, ["git", "config", "user.email", "test@example.com"])
+			await run(path, ["git", "config", "user.name", "Test"])
+			await Bun.write(join(path, "README.md"), `${repo}\n`)
+			await run(path, ["git", "add", "README.md"])
+			await run(path, ["git", "commit", "-m", "initial"])
+		}
+
+		await write(
+			root,
+			"epics/contract/EPIC.md",
+			`---
+ticketUrl: https://example.com/contract
+repos:
+  - repo: agency
+    ref: main
+tasks:
+  - id: foundations
+  - id: agent-contract
+    dependsOn: [foundations]
+---
+
+# Contract
+`,
+		)
+		await write(
+			root,
+			"tasks/foundations/TASK.md",
+			`---
+ticketUrl: null
+epic: contract
+repo: agency
+branch: foundations
+base: main
+pr: https://github.com/example/agency/pull/1
+status: done
+---
+
+# Foundations
+`,
+		)
+		await write(
+			root,
+			"tasks/agent-contract/TASK.md",
+			`---
+ticketUrl: null
+epic: contract
+phases:
+  - id: schema
+  - id: context-command
+    dependsOn: [schema]
+---
+
+# Agent contract
+Task prose.
+`,
+		)
+		await write(
+			root,
+			"tasks/agent-contract/phases/schema/PHASE.md",
+			`---
+repo: agency
+branch: schema
+base: main
+pr: https://github.com/example/agency/pull/2
+status: done
+---
+
+# Schema
+`,
+		)
+		await write(
+			root,
+			"tasks/agent-contract/phases/context-command/PHASE.md",
+			`---
+repo: agency
+repos:
+  - repo: docs
+    ref: main
+branch: feat/context
+base: main
+pr: null
+status: open
+---
+
+# Context command
+Phase prose.
+`,
+		)
+
+		const code = join(root, "tasks/agent-contract/phases/context-command/code")
+		await mkdir(code, { recursive: true })
+		await run(join(root, "repos/agency"), [
+			"git",
+			"worktree",
+			"add",
+			"-b",
+			"feat/context",
+			join(code, "agency"),
+			"main",
+		])
+		await run(join(root, "repos/docs"), [
+			"git",
+			"worktree",
+			"add",
+			"--detach",
+			join(code, "docs"),
+			"main",
+		])
+	})
+
+	afterEach(async () => {
+		await cleanupTempDir(root)
+	})
+
+	test("returns complete phase context with graph, authority, Git, and validation state", async () => {
+		const target = "tasks/agent-contract/phases/context-command"
+		const result = await readContext(root, target)
+
+		expect(result).toMatchObject({
+			projection: "complete",
+			workbase: { root, version: 2 },
+			target: {
+				kind: "phase",
+				taskId: "agent-contract",
+				phaseId: "context-command",
+			},
+			graph: {
+				parent: { kind: "task", id: "agent-contract" },
+				dependencies: ["schema"],
+				readiness: { ready: true, blocked: false, blockers: [] },
+				aggregate: { status: "open", total: 1, open: 1 },
+			},
+			authority: {
+				mode: "execution",
+				writable: { repo: "agency", branch: "feat/context", base: "main" },
+				references: [{ repo: "docs", ref: "main" }],
+			},
+			workspace: {
+				materialization: "complete",
+				writable: {
+					materialized: true,
+					registered: true,
+					checkoutBranch: "feat/context",
+					detached: false,
+				},
+				references: [
+					{
+						repo: "docs",
+						materialized: true,
+						registered: true,
+						detached: true,
+					},
+				],
+			},
+			pr: { url: null, state: "none" },
+			validation: { valid: true, warnings: [] },
+		})
+		expect(result.documents.epic.body).toContain("# Contract")
+		expect(result.documents.task.body).toContain("Task prose.")
+		expect(result.documents.phase.body).toContain("Phase prose.")
+		expect(result.documents.phase.sha256).toMatch(/^[a-f0-9]{64}$/)
+		expect(result.workspace.writable.branchCommit).toMatch(/^[a-f0-9]{40}$/)
+		expect(result.workspace.writable.baseCommit).toMatch(/^[a-f0-9]{40}$/)
+		expect(result.workspace.references[0].resolvedCommit).toMatch(
+			/^[a-f0-9]{40}$/,
+		)
+	})
+
+	test("makes compact projection explicit without omitting essential identity", async () => {
+		const result = await readContext(
+			root,
+			"tasks/agent-contract/phases/context-command/code/agency",
+			true,
+		)
+
+		expect(result.projection).toBe("compact")
+		expect(result.target.kind).toBe("phase")
+		expect(result.documents.phase.body).toBeUndefined()
+		expect(result.documents.phase.data.branch).toBe("feat/context")
+		expect(result.documents.phase.sha256).toMatch(/^[a-f0-9]{64}$/)
+		expect(result.workspace.writable).toEqual({
+			materialized: true,
+			registered: true,
+		})
+		expect(result.authority.writable.checkoutPath).toContain("code/agency")
+	})
+
+	test("reports dependency and validation blockers deterministically", async () => {
+		await write(
+			root,
+			"tasks/agent-contract/phases/schema/PHASE.md",
+			`---
+repo: missing
+branch: schema
+base: main
+pr: null
+status: dropped
+---
+
+# Schema
+`,
+		)
+		const result = await readContext(
+			root,
+			"tasks/agent-contract/phases/context-command",
+		)
+
+		expect(result.graph.readiness.ready).toBe(false)
+		expect(result.graph.readiness.blockers).toContainEqual({
+			kind: "dependency",
+			id: "schema",
+			status: "dropped",
+			reason: "Phase dependency is dropped",
+		})
+		expect(result.validation.valid).toBe(false)
+		expect(result.validation.warnings).toContainEqual({
+			path: "tasks/agent-contract/phases/schema/PHASE.md",
+			message: "Unknown repository alias 'missing'",
+		})
+	})
+
+	test("resolves a bare task ID and rejects a root target", async () => {
+		const task = await readContext(root, "agent-contract")
+		expect(task.target).toMatchObject({
+			kind: "task",
+			taskId: "agent-contract",
+		})
+		expect(task.graph.parent).toEqual({ kind: "epic", id: "contract" })
+
+		await expect(readContext(root, ".")).rejects.toThrow(
+			"Cannot infer an Agency target",
+		)
+	})
+
+	test("resolves bare task IDs from inside another target", async () => {
+		const cwd = join(
+			root,
+			"tasks/agent-contract/phases/context-command/code/agency",
+		)
+		const logs = await captureLogs(() =>
+			runTestEffect(context({ cwd, target: "foundations", json: true })),
+		)
+		const result = JSON.parse(logs[0]!)
+		expect(result.target).toMatchObject({ kind: "task", taskId: "foundations" })
+		expect(result.authority.writable.branch).toBe("foundations")
+	})
+
+	test("computes orchestration readiness from runnable descendants", async () => {
+		await write(
+			root,
+			"tasks/agent-contract/TASK.md",
+			`---
+ticketUrl: null
+epic: contract
+phases:
+  - id: schema
+  - id: context-command
+    dependsOn: [schema]
+  - id: parallel
+---
+
+# Agent contract
+`,
+		)
+		await write(
+			root,
+			"tasks/agent-contract/phases/schema/PHASE.md",
+			`---
+repo: agency
+branch: schema
+base: main
+pr: null
+status: working
+---
+
+# Schema
+`,
+		)
+		await write(
+			root,
+			"tasks/agent-contract/phases/parallel/PHASE.md",
+			`---
+repo: docs
+branch: parallel
+base: main
+pr: null
+status: open
+---
+
+# Parallel
+`,
+		)
+
+		const task = await readContext(root, "agent-contract")
+		expect(task.graph.readiness).toMatchObject({ ready: true, blocked: false })
+		expect(task.graph.aggregate).toMatchObject({
+			status: "working",
+			total: 3,
+			open: 2,
+			working: 1,
+		})
+
+		const epic = await readContext(root, "epics/contract")
+		expect(epic.graph.readiness).toMatchObject({ ready: true, blocked: false })
+		expect(epic.graph.aggregate).toMatchObject({
+			status: "working",
+			total: 4,
+			done: 1,
+			open: 2,
+			working: 1,
+		})
+	})
+
+	test("reports stale worktree registration independently of materialization", async () => {
+		const checkout = join(
+			root,
+			"tasks/agent-contract/phases/context-command/code/agency",
+		)
+		await rm(checkout, { recursive: true, force: true })
+
+		const result = await readContext(
+			root,
+			"tasks/agent-contract/phases/context-command",
+		)
+		expect(result.workspace.writable).toMatchObject({
+			materialized: false,
+			registered: true,
+		})
+		expect(result.workspace.materialization).toBe("partial")
+	})
+})

package/src/commands/context.ts

@@ -0,0 +1,29 @@
+import { Effect } from "effect"
+import type { BaseCommandOptions } from "../utils/command"
+import { ContextService } from "../services/ContextService"
+import { createLoggers } from "../utils/effect"
+
+interface ContextOptions extends BaseCommandOptions {
+	readonly target?: string
+	readonly compact?: boolean
+	readonly json?: boolean
+}
+
+export const context = (options: ContextOptions = {}) =>
+	Effect.gen(function* () {
+		const service = yield* ContextService
+		const { log } = createLoggers(options)
+		const result = yield* service.get(options)
+		log(JSON.stringify(result, null, 2))
+	})
+
+export const help = `
+Usage: agency context [target] [options]
+
+Return the complete, read-only context for an epic, task, or phase. The target
+defaults to the current directory and may be an entity path or task ID.
+
+Options:
+  --json              Output a versioned machine result
+  --compact           Omit prose bodies and low-level Git details
+`

package/src/commands/read-only.test.ts

@@ -11,6 +11,7 @@ import { repo } from "./repo"
 import { status } from "./status"
 import { task } from "./task"
 import { validate } from "./validate"
+import { context } from "./context"
 
 const write = async (root: string, path: string, content: string) => {
 	const fullPath = join(root, path)
@@ -135,6 +136,13 @@ status: open
 		)
 		await runTestEffect(status({ cwd: root, silent: true }))
 		await runTestEffect(validate({ path: root, silent: true }))
+		await runTestEffect(
+			context({
+				target: "tasks/example-task/phases/implementation",
+				cwd: root,
+				silent: true,
+			}),
+		)
 
 		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
 		expect(

package/src/protocol.ts

@@ -84,6 +84,12 @@ const errorMetadata: Readonly<Record<string, ErrorMetadata>> = {
 	ArchiveError: { code: "ARCHIVE_ERROR", retryable: false },
 	WorktreeError: { code: "WORKTREE_ERROR", retryable: false },
 	PullRequestError: { code: "PULL_REQUEST_ERROR", retryable: false },
+	ContextError: {
+		code: "CONTEXT_ERROR",
+		retryable: false,
+		remediation:
+			"Run the command from an Agency entity or provide a valid target.",
+	},
 	ProcessError: { code: "PROCESS_ERROR", retryable: true },
 	ProtocolOutputError: {
 		code: "PROTOCOL_OUTPUT_ERROR",