@markjaquith/agency 2.10.0 → 2.12.0

package/README.md

@@ -255,6 +255,33 @@ 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, `blockedBy`, detailed blockers,
+terminal state, reverse dependents, and aggregate progress. Only `done` satisfies
+a dependency; `dropped` is terminal but does not satisfy dependents. 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
@@ -275,7 +302,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
 
@@ -364,7 +391,9 @@ Single-phase tasks and phases store status in YAML. New execution units start
 `open`, and `agency work` marks the selected execution unit `working` immediately
 before launch. Use the status subcommands to mark work `delegated`, `done`,
 `dropped`, or open it again. The interactive work selector displays status
-markers before execution units.
+markers before execution units. Open, working, and delegated work may transition
+to any status. Done and dropped work are terminal and may only remain unchanged
+or transition to open; reopen terminal work before changing its outcome.
 
 ### Archive
 
@@ -477,14 +506,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

@@ -9,6 +9,7 @@ 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"
@@ -30,6 +31,7 @@ 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,
@@ -50,6 +52,7 @@ const CliLayer = Layer.mergeAll(
 	ArchiveService.Default,
 	IntegrationService.Default,
 	ContextService.Default,
+	GraphService.Default,
 )
 
 /**
@@ -333,6 +336,28 @@ const commands: Record<string, Command> = {
 			)
 		},
 	},
+	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() {
@@ -355,6 +380,7 @@ Commands:
   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
@@ -373,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)
@@ -401,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,4 @@
 export * from "./src/workbase/schemas"
 export * from "./src/protocol"
+export * from "./src/graph-schema"
+export * from "./src/readiness"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.10.0",
+  "version": "2.12.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"
     },