@markjaquith/agency 2.9.0 → 2.11.0

package/README.md

@@ -231,12 +231,56 @@ 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 Graph
+
+`agency graph --json` exports the complete workbase as graph contract version 1.
+Nodes use stable IDs (`epic:<id>`, `task:<id>`, `phase:<task>/<phase>`,
+`repository:<alias>`, and `execution-unit:<kind>/<id>`). Typed edges are `owns`,
+`depends_on`, `writes`, and `references`.
+
+Every work node includes status, readiness, blockers, reverse dependents, and
+aggregate progress. Only `done` satisfies a dependency. The graph summary counts
+the statuses of all execution units, independent of filters.
+
+```text
+agency graph [--json | --jsonl] [--ready | --blocked]
+  [--status <status>...] [--repository <alias>...] [--kind <kind>...]
+  [--include <bodies|workspace|git|pr>...]
+```
+
+Filters are applied after graph state is computed. Returned edges always have
+both endpoints in the filtered node set. Durable frontmatter and document hashes
+are always present; prose, absolute workspace paths, Git inspection, and live PR
+inspection are opt-in include layers.
+
+`--jsonl` emits a versioned `meta` record, one record per node and edge, then an
+`end` record with counts. Combining the metadata with the streamed node and edge
+records reconstructs the same result as `--json`.
+
 ### Workbase and Repositories
 
 ```text
@@ -257,7 +301,7 @@ repository. Alias names are then used by all documents and commands.
 
 Commands that print Agency-owned results accept `--json`, including initialization,
 integration inspection/sync, repository mutations, entity creation/list/show,
-status, validation, and PR creation.
+status, validation, graph export, and PR creation.
 
 ### Epics
 
@@ -459,14 +503,16 @@ recovery action. Version 1 defines these codes:
 | `ARCHIVE_ERROR`           | Archive operation failed                                 |
 | `WORKTREE_ERROR`          | Worktree operation failed                                |
 | `PULL_REQUEST_ERROR`      | Pull request operation failed                            |
+| `GRAPH_ERROR`             | Workbase graph construction failed                       |
 | `PROCESS_ERROR`           | A child process failed and may be retried                |
 | `PROTOCOL_OUTPUT_ERROR`   | A command violated the machine output contract           |
 | `COMMAND_FAILED`          | An otherwise unclassified command failure                |
 
 The Effect schemas are exported from `@markjaquith/agency` and
-`@markjaquith/agency/protocol`. The distributable JSON Schema is exported as
-`@markjaquith/agency/schemas/agency-envelope-v1.json`. Representative payloads
-are exported as `@markjaquith/agency/fixtures/protocol/success.json` and
+`@markjaquith/agency/protocol`. The distributable JSON Schemas are exported as
+`@markjaquith/agency/schemas/agency-envelope-v1.json` and
+`@markjaquith/agency/schemas/agency-graph-v1.json`. Representative envelope
+payloads are exported as `@markjaquith/agency/fixtures/protocol/success.json` and
 `@markjaquith/agency/fixtures/protocol/error.json`.
 
 ## Agent Skill

package/cli.ts

@@ -8,6 +8,8 @@ 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 { graph, help as graphHelp } from "./src/commands/graph"
 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 +30,8 @@ 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 { GraphService } from "./src/services/GraphService"
 import {
 	collectCommandResult,
 	errorEnvelope,
@@ -47,6 +51,8 @@ const CliLayer = Layer.mergeAll(
 	PullRequestService.Default,
 	ArchiveService.Default,
 	IntegrationService.Default,
+	ContextService.Default,
+	GraphService.Default,
 )
 
 /**
@@ -313,6 +319,45 @@ 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,
+				}),
+			)
+		},
+	},
+	graph: {
+		run: async (_args: string[], options: Record<string, any>) => {
+			if (options.help) {
+				console.log(graphHelp)
+				return
+			}
+			await runCommand(
+				graph({
+					json: options.json,
+					jsonl: options.jsonl,
+					ready: options.ready,
+					blocked: options.blocked,
+					statuses: options.status,
+					repositories: options.repository,
+					kinds: options.kind,
+					include: options.include,
+					silent: options.silent,
+					verbose: options.verbose,
+				}),
+			)
+		},
+	},
 }
 
 function showMainHelp() {
@@ -334,6 +379,8 @@ Commands:
   repo <subcommand>      Manage workbase repositories
   status                 Show status for the current workbase
   validate [path]        Validate a workbase
+  context [target]       Return complete target context
+  graph                  Export the complete workbase graph
 
 Global Options:
   -h, --help             Show help for a command
@@ -352,7 +399,9 @@ For more information about a command, run:
 	`)
 }
 
-const machineMode = process.argv.slice(2).includes("--json")
+const machineMode = process.argv
+	.slice(2)
+	.some((argument) => argument === "--json" || argument === "--jsonl")
 
 try {
 	const args = process.argv.slice(2)
@@ -380,11 +429,13 @@ try {
 		!values.json &&
 		!values["no-input"] &&
 		Boolean(process.stdin.isTTY && process.stderr.isTTY)
-	if (values.json) {
+	if (values.json || (values.jsonl && values.help)) {
 		const result = await collectCommandResult(() =>
 			command.run(commandArgs, { ...values, inputAllowed }),
 		)
 		writeEnvelope(successEnvelope(result))
+	} else if (values.jsonl) {
+		await command.run(commandArgs, { ...values, inputAllowed: false })
 	} else {
 		await command.run(commandArgs, { ...values, inputAllowed })
 	}

package/index.ts

@@ -1,2 +1,3 @@
 export * from "./src/workbase/schemas"
 export * from "./src/protocol"
+export * from "./src/graph-schema"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.9.0",
+  "version": "2.11.0",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",
@@ -41,6 +41,9 @@
     "./schemas/agency-envelope-v1.json": {
       "default": "./schemas/agency-envelope-v1.schema.json"
     },
+    "./schemas/agency-graph-v1.json": {
+      "default": "./schemas/agency-graph-v1.schema.json"
+    },
     "./fixtures/protocol/success.json": {
       "default": "./fixtures/protocol/success.json"
     },