@markjaquith/agency 2.38.1 → 2.39.0

package/README.md

@@ -358,10 +358,16 @@ agency validate
 
 ### 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.
+`agency context [target] --json` returns complete bootstrap context without
+modifying the workbase or fetching repositories. At the workbase root it returns
+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.
+
+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
+by default. `--compact` explicitly requests compact entity context.
 
 The result includes workbase and target identity, ancestor frontmatter and prose
 with SHA-256 hashes, dependency and readiness state, aggregate status, writable
@@ -369,9 +375,10 @@ 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.
+Complete output is the default for entity targets. 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 Graph
 

package/cli.ts

@@ -601,6 +601,7 @@ const commands: Record<string, Command> = {
 								? join("tasks", options.task)
 								: args[0],
 					compact: options.compact,
+					full: options.full,
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,

package/package.json

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

package/skills/agency/references/commands.md

@@ -8,7 +8,7 @@ Commands that return Agency-owned data accept `--json` unless noted otherwise.
 ## Discovery And Health
 
 ```text
-agency context [target] [--json] [--compact]
+agency context [target] [--json] [--compact | --full]
 agency graph [--json | --jsonl] [--ready | --blocked]
   [--status <status>...] [--repository <alias>...] [--kind <kind>...]
   [--include <bodies|workspace|git|pr>...]
@@ -21,11 +21,13 @@ agency integration status [--json]
 agency integration sync [--json]
 ```
 
-`context` defaults to cwd and accepts entity directories, document paths,
-checkout descendants, or a task ID. Complete output includes prose and Git
-details; `--compact` intentionally omits them. `graph` computes readiness before
-applying filters. `doctor` discovers required tools, integrations, repositories,
-refs, worktrees, permissions, drift, and optional runner capabilities. `sync` is
+`context` defaults to cwd and accepts the workbase root, entity directories,
+document paths, checkout descendants, or a task ID. Root context catalogs all
+epics, tasks, and phases in compact form and hints that `--full` includes prose.
+Entity context is complete by default; `--compact` intentionally omits prose and
+low-level Git details. `graph` computes readiness before applying filters.
+`doctor` discovers required tools, integrations, repositories, refs, worktrees,
+permissions, drift, and optional runner capabilities. `sync` is
 observational unless `--apply` is explicit. Integration status includes safe
 remediation when customized OpenCode config prevents Agency from guaranteeing
 whole-workbase access.

package/skills/agency/references/contracts.md

@@ -8,9 +8,11 @@ names; they are not duplicated in frontmatter.
 `agency context . --json` returns a versioned success envelope whose result
 contains:
 
-- `projection`: `complete` or explicitly requested `compact`;
+- `projection`: `compact` for root discovery by default, otherwise `complete`
+  unless compact entity context was explicitly requested;
 - `workbase`: root, config path, and config version;
-- `target`: resolved epic, task, or phase identity;
+- `target`: resolved workbase, epic, task, or phase identity;
+- `discovery`: at the workbase root, all valid epic, task, and phase documents;
 - `documents`: ancestor frontmatter, paths, SHA-256 revisions, and prose;
 - `graph`: parent, dependencies, dependents, readiness blockers, and progress;
 - `authority`: `orchestration` or `execution`, one writable checkout or none,
@@ -283,9 +285,11 @@ selection. Supply every required value or explicit entity selector. Global
 `--cwd` and `--workbase` selectors apply to `next` as they do to other discovery
 commands.
 
-Context defaults to the `complete` projection. `--compact` omits prose and
-low-level Git details but retains identity, document hashes, authority, paths,
-graph state, materialization, and validation warnings.
+At a workbase root, context defaults to a compact discovery catalog of epics,
+tasks, and phases, includes no writable authority, and provides a hint for
+requesting `--full`. Entity context defaults to the `complete` projection.
+`--compact` omits prose and low-level Git details but retains identity, document
+hashes, authority, paths, graph state, materialization, and validation warnings.
 
 Graph projections are opt-in with repeatable
 `--include <bodies|workspace|git|pr>`. Filters such as `--ready`, `--blocked`,

package/src/cli-parser.test.ts

@@ -403,6 +403,13 @@ describe("strict CLI parsing", () => {
 			values: { json: true, compact: true },
 		})
 		expectUsageError(["status", "--compact"], "agency status")
+		expect(parseCli(["context", ".", "--json", "--full"])).toMatchObject({
+			commandName: "context",
+			args: ["."],
+			values: { json: true, full: true },
+		})
+		expectUsageError(["context", ".", "--compact", "--full"], "agency context")
+		expectUsageError(["status", "--full"], "agency status")
 	})
 
 	test("accepts work preparation options only for the prepare subcommand", () => {

package/src/cli-parser.ts

@@ -891,17 +891,19 @@ const commands = {
 		},
 	},
 	context: {
-		usage: "agency context [target] [--json] [--compact]",
+		usage: "agency context [target] [--json] [--compact | --full]",
 		options: {
 			...outputOptions,
 			...entitySelectorOptions,
 			compact: { type: "boolean" },
+			full: { type: "boolean" },
 		},
 		command: {
-			usage: "agency context [target] [--json] [--compact]",
+			usage: "agency context [target] [--json] [--compact | --full]",
 			minArgs: 0,
 			maxArgs: 1,
-			options: ["json", "compact", "epic", "task", "phase"],
+			options: ["json", "compact", "full", "epic", "task", "phase"],
+			conflicts: [["compact", "full"]],
 		},
 	},
 	graph: {

package/src/commands/context.test.ts

@@ -28,9 +28,10 @@ const readContext = async (
 	root: string,
 	target: string | undefined,
 	compact = false,
+	full = false,
 ) => {
 	const logs = await captureLogs(() =>
-		runTestEffect(context({ cwd: root, target, compact, json: true })),
+		runTestEffect(context({ cwd: root, target, compact, full, json: true })),
 	)
 	expect(logs).toHaveLength(1)
 	return JSON.parse(logs[0]!)
@@ -267,7 +268,7 @@ status: dropped
 		})
 	})
 
-	test("resolves a bare task ID and rejects a root target", async () => {
+	test("resolves a bare task ID and returns root discovery context", async () => {
 		const task = await readContext(root, "agent-contract")
 		expect(task.target).toMatchObject({
 			kind: "task",
@@ -275,9 +276,43 @@ status: dropped
 		})
 		expect(task.graph.parent).toEqual({ kind: "epic", id: "contract" })
 
-		await expect(readContext(root, ".")).rejects.toThrow(
-			"Cannot infer an Agency target",
-		)
+		const workbase = await readContext(root, ".")
+		expect(workbase).toMatchObject({
+			projection: "compact",
+			workbase: { root, version: 2 },
+			target: { kind: "workbase", path: root },
+			hint: "Run agency context . --full --json to include document prose.",
+			authority: {
+				mode: "orchestration",
+				writable: null,
+				references: [],
+			},
+			validation: { valid: true, warnings: [] },
+		})
+		expect(
+			workbase.discovery.epics.map((item: { id: string }) => item.id),
+		).toEqual(["contract"])
+		expect(
+			workbase.discovery.tasks.map((item: { id: string }) => item.id),
+		).toEqual(["agent-contract", "foundations"])
+		expect(
+			workbase.discovery.phases.map(
+				(item: { taskId: string; id: string }) => `${item.taskId}/${item.id}`,
+			),
+		).toEqual(["agent-contract/context-command", "agent-contract/schema"])
+		expect(workbase.discovery.tasks[0].body).toBeUndefined()
+		expect(workbase.discovery.phases[0].data.status).toBe("open")
+		expect(workbase.discovery.phases[0].sha256).toMatch(/^[a-f0-9]{64}$/)
+	})
+
+	test("includes discovery prose only in full root context", async () => {
+		const workbase = await readContext(root, ".", false, true)
+		expect(workbase.projection).toBe("complete")
+		expect(workbase.hint).toBeNull()
+		expect(workbase.discovery.epics[0].body).toContain("# Contract")
+		expect(workbase.discovery.tasks[0].body).toContain("Task prose.")
+		expect(workbase.discovery.tasks[0].data.phases).toBeDefined()
+		expect(workbase.discovery.phases[0].taskId).toBe("agent-contract")
 	})
 
 	test("resolves bare task IDs from inside another target", async () => {

package/src/commands/context.ts

@@ -6,6 +6,7 @@ import { createLoggers } from "../utils/effect"
 interface ContextOptions extends BaseCommandOptions {
 	readonly target?: string
 	readonly compact?: boolean
+	readonly full?: boolean
 	readonly json?: boolean
 }
 
@@ -20,12 +21,14 @@ export const context = (options: ContextOptions = {}) =>
 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.
+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.
 
 Options:
   --json              Output a versioned machine result
   --compact           Omit prose bodies and low-level Git details
+  --full              Include prose bodies in root workbase context
   --epic <id>         Select an epic
   --task <id>         Select a task
   --phase <id>        Select a phase together with --task

package/src/services/ContextService.ts

@@ -108,6 +108,7 @@ export class ContextService extends Effect.Service<ContextService>()(
 				readonly target?: string
 				readonly cwd?: string
 				readonly compact?: boolean
+				readonly full?: boolean
 			}) =>
 				Effect.gen(function* () {
 					const fs = yield* FileSystemService
@@ -121,6 +122,103 @@ export class ContextService extends Effect.Service<ContextService>()(
 						candidateExists ? candidate : cwd,
 					)
 
+					if (relative(root, candidate) === "") {
+						const compact = !options.full
+						const discover = <S extends Schema.Schema.AnyNoContext>(
+							id: string,
+							path: string,
+							schema: S,
+							extra: Record<string, string> = {},
+						) =>
+							Effect.gen(function* () {
+								if (!(yield* fs.exists(path))) return null
+								const content = yield* fs.readFile(path)
+								const parsed = yield* Effect.either(
+									parseFrontmatter(content, path),
+								)
+								if (Either.isLeft(parsed)) return null
+								const decoded = decode(schema, parsed.right.data)
+								if (!decoded.ok) return null
+								return {
+									...extra,
+									id,
+									path,
+									sha256: documentRevision(content),
+									data: decoded.value,
+									...(compact ? {} : { body: parsed.right.body }),
+								}
+							})
+
+						const epics: unknown[] = []
+						const tasks: unknown[] = []
+						const phases: unknown[] = []
+						const epicRoot = join(root, "epics")
+						if (yield* fs.isDirectory(epicRoot)) {
+							for (const entry of (yield* fs.readDirectory(epicRoot))
+								.filter((item) => item.isDirectory)
+								.sort((a, b) => a.name.localeCompare(b.name))) {
+								const document = yield* discover(
+									entry.name,
+									join(epicRoot, entry.name, "EPIC.md"),
+									EpicFrontmatter,
+								)
+								if (document) epics.push(document)
+							}
+						}
+
+						const taskRoot = join(root, "tasks")
+						if (yield* fs.isDirectory(taskRoot)) {
+							for (const entry of (yield* fs.readDirectory(taskRoot))
+								.filter((item) => item.isDirectory)
+								.sort((a, b) => a.name.localeCompare(b.name))) {
+								const document = yield* discover(
+									entry.name,
+									join(taskRoot, entry.name, "TASK.md"),
+									TaskFrontmatter,
+								)
+								if (document) tasks.push(document)
+
+								const phaseRoot = join(taskRoot, entry.name, "phases")
+								if (!(yield* fs.isDirectory(phaseRoot))) continue
+								for (const phaseEntry of (yield* fs.readDirectory(phaseRoot))
+									.filter((item) => item.isDirectory)
+									.sort((a, b) => a.name.localeCompare(b.name))) {
+									const phase = yield* discover(
+										phaseEntry.name,
+										join(phaseRoot, phaseEntry.name, "PHASE.md"),
+										PhaseFrontmatter,
+										{ taskId: entry.name },
+									)
+									if (phase) phases.push(phase)
+								}
+							}
+						}
+
+						const validation = yield* workbase.validate(root)
+						return {
+							projection: compact ? "compact" : "complete",
+							workbase: {
+								root,
+								configPath: join(root, "agency.json"),
+								version: config.version,
+							},
+							target: { kind: "workbase", path: root },
+							hint: compact
+								? "Run agency context . --full --json to include document prose."
+								: null,
+							discovery: { epics, tasks, phases },
+							authority: {
+								mode: "orchestration",
+								writable: null,
+								references: [],
+							},
+							validation: {
+								valid: validation.valid,
+								warnings: validation.issues,
+							},
+						}
+					}
+
 					const inferTarget = (): Target | null => {
 						if (!candidateExists && !suppliedTarget.includes(sep)) {
 							return {