@markjaquith/agency 2.27.0 → 2.28.1

package/README.md

@@ -73,9 +73,14 @@ workbase/
 Agency keeps discovery and other observational commands read-only. Run
 `agency integration status` to inspect `AGENTS.md` and
 `.opencode/opencode.jsonc`, then `agency integration sync` to create missing
-files or refresh checksum-safe managed files. The OpenCode config grants
-external-directory access to task and epic references. Customized files are
-reported but never overwritten.
+files or refresh checksum-safe managed files. Customized files are reported but
+never overwritten.
+
+The OpenCode config advertises only the task and epic directories as documented
+references. OpenCode automatically grants those references scoped
+external-directory access, so Agency does not add blanket permission rules that
+could hide missing tool permissions. References provide context and never expand
+the write authority reported by `agency context`.
 
 Repository metadata comes directly from Git under `repos/{alias}`. Workbase
 configuration may provide a custom writable-worktree creation command.
@@ -707,27 +712,34 @@ Every error contains a stable `code`, human-readable `message`, structured
 `fields`, and `retryable`. `remediation` is included when Agency knows a specific
 recovery action. Version 1 defines these codes:
 
-| Code                      | Meaning                                                  |
-| ------------------------- | -------------------------------------------------------- |
-| `CLI_USAGE`               | Invalid command, option, argument, or option combination |
-| `WORKBASE_NOT_FOUND`      | No workbase could be resolved                            |
-| `WORKBASE_CONFIG_INVALID` | Invalid workbase configuration                           |
-| `WORKBASE_REGISTRY_ERROR` | Invalid or inaccessible workbase registry                |
-| `FILE_NOT_FOUND`          | A required path does not exist                           |
-| `FILESYSTEM_ERROR`        | A filesystem operation failed                            |
-| `FRONTMATTER_INVALID`     | A durable document has invalid frontmatter               |
-| `VALIDATION_FAILED`       | Workbase validation reported issues                      |
-| `REPOSITORY_ERROR`        | Repository operation failed                              |
-| `EPIC_ERROR`              | Epic operation failed                                    |
-| `TASK_ERROR`              | Task operation failed                                    |
-| `PHASE_ERROR`             | Phase operation failed                                   |
-| `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                |
+| Code                      | Meaning                                                   |
+| ------------------------- | --------------------------------------------------------- |
+| `CLI_USAGE`               | Invalid command, option, argument, or option combination  |
+| `WORKBASE_NOT_FOUND`      | No workbase could be resolved                             |
+| `WORKBASE_CONFIG_INVALID` | Invalid workbase configuration                            |
+| `WORKBASE_REGISTRY_ERROR` | Invalid or inaccessible workbase registry                 |
+| `FILE_NOT_FOUND`          | A required path does not exist                            |
+| `FILESYSTEM_ERROR`        | A filesystem operation failed                             |
+| `FRONTMATTER_INVALID`     | A durable document has invalid frontmatter                |
+| `VALIDATION_FAILED`       | Workbase validation reported issues                       |
+| `REPOSITORY_ERROR`        | Repository operation failed                               |
+| `EPIC_ERROR`              | Epic operation failed                                     |
+| `TASK_ERROR`              | Task operation failed                                     |
+| `PHASE_ERROR`             | Phase operation failed                                    |
+| `CLAIM_ERROR`             | Claim input or lifecycle state is invalid                 |
+| `CLAIM_CONFLICT`          | Active or legacy ownership conflicts with an operation    |
+| `REVISION_CONFLICT`       | A durable document changed since inspection               |
+| `CLAIM_OWNERSHIP`         | The session does not own the active claim                 |
+| `ARCHIVE_ERROR`           | Archive operation failed                                  |
+| `WORKTREE_ERROR`          | Worktree operation failed                                 |
+| `PULL_REQUEST_ERROR`      | Pull request operation failed                             |
+| `CONTEXT_ERROR`           | A context target or required document is invalid          |
+| `GRAPH_ERROR`             | Workbase graph construction failed                        |
+| `EXECUTION_BLOCKED`       | Readiness or lifecycle blockers prevent execution         |
+| `SYNC_ERROR`              | Reconciliation validation, inspection, or provider 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 Schemas are exported as
@@ -736,6 +748,12 @@ The Effect schemas are exported from `@markjaquith/agency` and
 payloads are exported as `@markjaquith/agency/fixtures/protocol/success.json` and
 `@markjaquith/agency/fixtures/protocol/error.json`.
 
+Success, help, and version output exit `0`; usage and command failures exit `1`.
+There are no error-specific exit statuses. `graph --jsonl` streams versioned
+records on success instead of wrapping them in an envelope; JSONL failures still
+use one error envelope. See `skills/agency/references/contracts.md` for revision,
+selector, projection, retry, and capability details.
+
 ## Agent Skill
 
 `skills/agency/SKILL.md` contains an agent-oriented operating guide for Agency.

package/cli.ts

@@ -9,6 +9,7 @@ import { pr, help as prHelp } from "./src/commands/pr"
 import { work, workPrepare, help as workHelp } from "./src/commands/work"
 import { worktree, help as worktreeHelp } from "./src/commands/worktree"
 import { status, help as statusHelp } from "./src/commands/status"
+import { doctor, help as doctorHelp } from "./src/commands/doctor"
 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"
@@ -41,6 +42,7 @@ import { ClaimService } from "./src/services/ClaimService"
 import { SyncService } from "./src/services/SyncService"
 import { ReadinessService } from "./src/services/ReadinessService"
 import { GraphMutationService } from "./src/services/GraphMutationService"
+import { DoctorService } from "./src/services/DoctorService"
 import {
 	claimCommand,
 	claimHelp,
@@ -72,6 +74,7 @@ const CliLayer = Layer.mergeAll(
 	SyncService.Default,
 	ReadinessService.Default,
 	GraphMutationService.Default,
+	DoctorService.Default,
 )
 
 /**
@@ -524,6 +527,22 @@ const commands: Record<string, Command> = {
 			)
 		},
 	},
+	doctor: {
+		run: async (_args: string[], options: Record<string, any>) => {
+			if (options.help) {
+				console.log(doctorHelp)
+				return
+			}
+			await runCommand(
+				doctor({
+					silent: options.silent,
+					verbose: options.verbose,
+					json: options.json,
+					cwd: options.cwd,
+				}),
+			)
+		},
+	},
 	validate: {
 		run: async (args: string[], options: Record<string, any>) => {
 			if (options.help) {
@@ -632,6 +651,7 @@ Commands:
   pr create              Create a pull request for an execution unit
   repo <subcommand>      Manage workbase repositories
   status                 Show status for the current workbase
+  doctor                 Diagnose workbase health and integrations
   validate [path]        Validate a workbase
   context [target]       Return complete target context
   graph                  Export the complete workbase graph

package/fixtures/protocol/orchestration-recipes.json

@@ -0,0 +1,59 @@
+[
+  ["context", "--task", "checkout", "--phase", "ui", "--json"],
+  ["worktree", "inspect", "checkout", "ui", "--json"],
+  ["next", "--json"],
+  ["graph", "--ready", "--json"],
+  [
+    "claim",
+    "checkout",
+    "ui",
+    "--claimant",
+    "orchestrator-1",
+    "--runner",
+    "opencode",
+    "--session-id",
+    "session-123",
+    "--revision",
+    "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "--json"
+  ],
+  [
+    "work",
+    "prepare",
+    "--task",
+    "checkout",
+    "--phase",
+    "ui",
+    "--dry-run",
+    "--json"
+  ],
+  ["work", "prepare", "--task", "checkout", "--phase", "ui", "--json"],
+  ["work", "tasks/checkout/phases/ui", "--runner", "opencode"],
+  ["sync", "--dry-run", "--json"],
+  ["sync", "--apply", "--json"],
+  ["pr", "create", "checkout", "ui", "--json"],
+  [
+    "finish",
+    "checkout",
+    "ui",
+    "--session-id",
+    "session-123",
+    "--revision",
+    "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "--outcome",
+    "done",
+    "--json"
+  ],
+  ["doctor", "--json"],
+  ["worktree", "repair", "checkout", "ui", "--dry-run", "--json"],
+  [
+    "release",
+    "checkout",
+    "ui",
+    "--session-id",
+    "session-123",
+    "--revision",
+    "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "--json"
+  ]
+]

package/package.json

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