@markjaquith/agency 2.27.0 → 2.28.1

package/skills/agency/references/contracts.md

@@ -0,0 +1,288 @@
+# Agency Data Contracts
+
+Use Agency JSON output instead of scraping human tables. Entity IDs are directory
+names; they are not duplicated in frontmatter.
+
+## Context Contract
+
+`agency context . --json` returns a versioned success envelope whose result
+contains:
+
+- `projection`: `complete` or explicitly requested `compact`;
+- `workbase`: root, config path, and config version;
+- `target`: resolved epic, task, or phase identity;
+- `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,
+  and read-only references;
+- `workspace`: code path, materialization and registration state, commits, and
+  inspection warnings;
+- `pr`: recorded URL and state; and
+- `validation`: validity and issues.
+
+Compact context retains identity, revisions, authority, paths, graph state,
+materialization, and warnings while omitting prose and low-level Git details.
+
+## Frontmatter Shapes
+
+### Epic
+
+```yaml
+---
+ticketUrl: https://example.com/tickets/checkout
+description: Coordinate checkout delivery.
+repos:
+  - repo: frontend
+    ref: main
+tasks:
+  - id: api
+  - id: ui
+    dependsOn:
+      - api
+---
+```
+
+Epics have read-only `repos`, never a writable `repo`. Their `tasks` list owns
+task ordering and task dependencies.
+
+### Single-Phase Task
+
+```yaml
+---
+ticketUrl: null
+description: Refresh checkout copy.
+epic: checkout
+repo: frontend
+repos:
+  - repo: backend
+    ref: main
+branch: task/refresh-copy
+base: main
+pr: null
+status: open
+---
+```
+
+### Multi-Phase Task
+
+```yaml
+---
+ticketUrl: null
+description: Deliver checkout.
+epic: checkout
+phases:
+  - id: api
+  - id: ui
+    dependsOn:
+      - api
+---
+```
+
+The task's `phases` list owns phase ordering and dependencies. Execution fields
+belong in each phase document.
+
+### Phase
+
+```yaml
+---
+description: Build the checkout UI.
+repo: frontend
+repos:
+  - repo: backend
+    ref: main
+branch: task/checkout-ui
+base: task/checkout-api
+pr: null
+status: open
+---
+```
+
+`ticketUrl` belongs to tasks and epics, not phases. `description` is optional but
+must be non-empty when present. `pr` is a GitHub PR URL or `null`. Status is
+`open`, `working`, `delegated`, `done`, or `dropped`; `delegated` is readable
+legacy state but cannot be newly assigned.
+
+## Structural Invariants
+
+- An execution unit has one writable `repo`; plural `repos` are read-only
+  `{ repo, ref }` entries and cannot repeat the writable alias.
+- A writable `(repo, branch)` pair belongs to exactly one active execution unit.
+- Only `done` satisfies dependencies. `dropped` is terminal but blocks dependents.
+- Epic task dependencies live in `EPIC.md`; phase dependencies live in `TASK.md`.
+- IDs remain stable; use `dependsOn`, not numeric directory prefixes, for order.
+- YAML duplicate keys, anchors, aliases, and custom tags are invalid.
+- Use a commit SHA as a reference `ref` when reproducibility is required.
+
+## Graph Contract
+
+`agency graph --json` emits graph contract version 1. Stable node IDs are
+`epic:<id>`, `task:<id>`, `phase:<task>/<phase>`,
+`repository:<alias>`, and `execution-unit:<kind>/<id>`. Edge types are `owns`,
+`depends_on`, `writes`, and `references`.
+
+Every work node includes status, readiness, `blockedBy`, detailed blockers,
+terminal state, reverse dependents, and aggregate progress. Filters run after
+state computation. `--jsonl` emits a versioned `meta` record, node and edge
+records, then an `end` record; together they reconstruct the JSON result.
+
+## Machine Envelope
+
+The published success fixture is normalized from
+`agency init /work/agency --json`:
+
+```json
+{
+	"version": 1,
+	"ok": true,
+	"result": {
+		"root": "/work/agency"
+	}
+}
+```
+
+The published error fixture is the output of `agency unknown --json`:
+
+```json
+{
+	"version": 1,
+	"ok": false,
+	"error": {
+		"code": "CLI_USAGE",
+		"message": "Unknown command 'unknown'.\n\nUsage: agency <command> [options]",
+		"fields": {
+			"detail": "Unknown command 'unknown'.",
+			"usage": "agency <command> [options]"
+		},
+		"retryable": false,
+		"remediation": "Correct the arguments using the usage value in error.fields."
+	}
+}
+```
+
+These examples are exported from `fixtures/protocol/` and tested against real
+CLI subprocess output. The Effect schemas are exported by the package and by
+`@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`.
+
+Only the envelope and graph result have published JSON Schemas. The envelope's
+`result` is intentionally unconstrained. Context, next, claim, prepare, sync,
+and PR result shapes are exercised by CLI tests but do not have independent
+published schemas.
+
+### Output And Exit Guarantees
+
+- `--json` writes exactly one newline-terminated envelope to stdout on success
+  or failure. It disables interactive selection and takes precedence over
+  `--silent`; explicit entity selectors remain valid.
+- Human output is not a machine contract. Do not parse tables, progress text, or
+  diagnostic wording.
+- Progress and verbose diagnostics use stderr. Structured command warnings stay
+  inside the stdout result. Successful JSON mode does not promise empty stderr
+  when `--verbose` is requested.
+- Success, help, and version output exit `0`. Usage errors and every command
+  failure exit `1`. Version 1 has no error-specific exit statuses; branch on
+  `error.code`.
+- `graph --jsonl` is the one streaming exception. On success it writes a `meta`
+  record, node and edge records, and an `end` record rather than an envelope. A
+  JSONL failure still writes one error envelope and exits `1`.
+- A command that emits zero machine results succeeds with `result: null`.
+  Multiple results are a `PROTOCOL_OUTPUT_ERROR`.
+
+### Error Codes
+
+| Code                      | Meaning                                                        |
+| ------------------------- | -------------------------------------------------------------- |
+| `CLI_USAGE`               | Invalid command, option, argument, or 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`     | Durable document frontmatter is invalid                        |
+| `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 or restore 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`             | Graph construction or filtering failed                         |
+| `EXECUTION_BLOCKED`       | Readiness or lifecycle blockers prevent execution              |
+| `SYNC_ERROR`              | Reconciliation validation, inspection, or provider data failed |
+| `PROCESS_ERROR`           | A child process failed                                         |
+| `PROTOCOL_OUTPUT_ERROR`   | A command violated the one-result machine contract             |
+| `COMMAND_FAILED`          | An otherwise unclassified failure                              |
+
+`CLAIM_CONFLICT`, `REVISION_CONFLICT`, and `PROCESS_ERROR` are retryable in the
+v1 metadata. Retryable means new evidence may change the result, not that blind
+or non-idempotent retries are safe. Inspect `fields` and apply `remediation`
+before retrying.
+
+## Revisions And Concurrency
+
+A document revision is the lowercase SHA-256 hash of the complete Markdown file,
+including frontmatter and prose. It is per document, not a workbase-wide graph
+revision. Context, graph, and entity reads expose revisions.
+
+`claim`, `release`, and `finish` require `--revision <sha256>`. They lock and
+recheck the execution document before an atomic replacement, then return
+`previousRevision` and the new `revision`. Use the returned revision or inspect
+again before the next mutation. Claim conflicts include the current revision and
+ownership evidence in `error.fields`; revision conflicts include ownership only
+when claim evidence applies.
+
+Structural update, rename, move, and dependency commands accept optional
+`--if-revision <sha256>`. Machine orchestrators should provide it. Multi-document
+mutations recheck every affected file while holding the graph mutation lock.
+
+## Selectors And Projections
+
+`--workbase <id|name|path>` selects a registered workbase. `--cwd <path>` asks
+Agency to perform target inference as if invoked there. They are mutually
+exclusive. Targeted commands accept `--epic`, `--task`, and `--phase` where
+applicable; phase requires task, and entity selectors cannot be combined with a
+positional target ID. Non-target positional values, such as a status outcome,
+remain valid where the command syntax requires them.
+
+`--json`, `--no-input`, and non-TTY execution disable interactive prompts and
+selection. Supply every required value or explicit entity selector. The current
+`next` implementation uses the process cwd even when global `--cwd` or
+`--workbase` parses successfully; run `next --json` from the intended workbase
+until that routing gap is fixed.
+
+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`,
+`--status`, `--repository`, and `--kind` are applied after readiness and graph
+state are computed; returned edges always have both endpoints in the filtered
+node set.
+
+## Capability Boundaries
+
+- There is no atomic find-ready-and-claim operation. `next` is observational,
+  and `claim` does not enforce dependency readiness. Inspect readiness, then
+  claim with the observed revision and handle conflicts.
+- There is no `assign` command, remote queue, scheduler, heartbeat, claim renewal,
+  runner monitor, or cancellation API. `work` can claim and launch one local
+  configured runner, but it is a process-launching, non-JSON flow rather than a
+  machine assignment API. External orchestrators claim with claimant and runner
+  IDs, then manage their runner themselves.
+- Agency does not edit code, create commits, run repository checks, wait for PR
+  checks, merge PRs, or verify that a requested completion condition is true.
+  `finish` records the caller's asserted outcome after ownership checks.
+- Reconciliation never discards changes, switches branches, resets reference
+  commits, moves conflicting worktrees, chooses among multiple PRs, or bypasses
+  active claims. Such conditions remain unresolved for a human or orchestrator.
+- `delegated` is readable legacy state but cannot be newly assigned. `--force`
+  only overrides readiness for `work` and `pr create`; it is not general
+  reconciliation authority.

package/skills/agency/references/recipes.md

@@ -0,0 +1,219 @@
+# Agency Recipes
+
+For an entity target, run `agency context . --json` before selecting a recipe.
+At the workbase root, use `agency next --json` or `agency graph --json` to choose
+a target, then inspect that explicit target with `agency context <target> --json`.
+
+The machine-orchestration forms in the inspect-through-recover recipes are
+captured in `fixtures/protocol/orchestration-recipes.json` and tested against the
+real CLI parser. Their lifecycle behavior is covered by CLI and service fixtures.
+Replace angle-bracket placeholders with values from context or a prior machine
+result; never scrape them from human output.
+
+## Inspect A Target
+
+```bash
+agency context --task <task-id> --phase <phase-id> --json
+agency worktree inspect <task-id> <phase-id> --json
+```
+
+Confirm the target, current document revision, readiness, authority, checkout,
+claim, PR, and validation state. Use `--compact` only when prose and detailed Git
+evidence are not needed.
+
+## Find Ready Work
+
+Run this from the intended workbase:
+
+```bash
+agency next --json
+agency graph --ready --json
+```
+
+`next` ranks ready execution units and explains every excluded unit. It does not
+reserve work. Another orchestrator may claim the same candidate before you do,
+so always handle `CLAIM_CONFLICT` or `REVISION_CONFLICT`.
+
+## Human: Create And Launch Work
+
+```bash
+agency task create refresh-copy --repo frontend --branch task/refresh-copy --base main
+agency validate
+agency work tasks/refresh-copy
+```
+
+For a multi-PR outcome:
+
+```bash
+agency task create checkout --multi-phase
+agency phase create checkout api --repo backend --branch task/checkout-api --base main
+agency phase create checkout ui --repo frontend --branch task/checkout-ui \
+  --base main --reference backend:main --depends-on api
+agency validate
+agency work tasks/checkout/phases/api
+```
+
+`agency work` is intentionally last: it checks readiness, materializes
+worktrees, creates a claim, marks the execution unit working, and launches the
+runner.
+
+## Active Agent: Execute Assigned Work
+
+```bash
+agency context . --json
+```
+
+1. Verify context reports the expected execution target, no blockers, valid
+   structure, and the current checkout as `authority.writable.checkoutPath`.
+2. Read `TASK.md`, and `PHASE.md` for phase work.
+3. Implement only in the writable checkout; treat all reference checkouts as
+   read-only.
+4. Run repository formatting, checks, build, and focused tests.
+5. Review and commit the diff.
+6. If requested, run `agency validate`, then
+   `agency pr create <task-id> [phase-id]`.
+7. Finish the current claim only after its completion condition is true.
+
+Never invoke `agency work` merely because an execution checkout already exists;
+that would start another agent rather than continue the current assignment.
+
+## Claim Ready Work
+
+Get the current document revision from context. Use stable claimant, runner, and
+session IDs:
+
+```bash
+agency claim checkout ui \
+  --claimant orchestrator-1 --runner opencode --session-id session-123 \
+  --revision <sha256> --json
+```
+
+Claim records ownership and sets status to `working`; it does not launch a runner
+or recheck dependency readiness. A machine orchestrator must launch and monitor
+its runner separately. There is no atomic find-and-claim or `assign` command.
+
+## Prepare Checkouts
+
+Preview and then materialize without claiming, launching, or changing status:
+
+```bash
+agency work prepare --task checkout --phase ui --dry-run --json
+agency work prepare --task checkout --phase ui --json
+```
+
+Use the returned checkout paths and resolved commits. Do not create or move
+worktrees manually.
+
+## Assign A Runner
+
+For a human-operated local launch, Agency combines readiness checks, prepare,
+claim, status mutation, and runner launch:
+
+```bash
+agency work tasks/checkout/phases/ui --runner opencode
+```
+
+This is not a JSON assignment API. An external orchestrator instead claims with
+its own `claimant`, `runner`, and `session-id`, starts the runner outside Agency,
+and passes it the target and claim result. Agency has no queue, heartbeat,
+monitoring, cancellation, or automatic claim-renewal service.
+
+## Reconcile Durable And Local State
+
+```bash
+agency sync --dry-run --json
+agency sync --apply --json
+```
+
+The first command is observational. Apply may materialize an unconflicted missing
+checkout, release an expired claim, record one unambiguous matching PR, or mark
+unclaimed work done after its authoritative PR merges. Review `warnings` and
+`unresolved`; apply never discards or resets work and never chooses among
+ambiguous PRs.
+
+## Release Interrupted Work
+
+After every claim mutation, use the returned revision or inspect again. Release
+interrupted work back to open:
+
+```bash
+agency release checkout ui --session-id session-123 \
+  --revision <current-sha256> --json
+```
+
+## Finish Verified Work
+
+Only after the assigned completion condition is true:
+
+```bash
+agency finish checkout ui --session-id session-123 \
+  --revision <current-sha256> --outcome done --json
+```
+
+Do not substitute `phase status done` for `finish` when an active claim exists;
+`finish` preserves ownership history and revision safety.
+
+## Create A Pull Request
+
+```bash
+agency validate
+agency pr create checkout ui --json
+```
+
+The writable worktree must be clean. Agency pushes the declared branch, invokes
+the configured delivery provider's create command or falls back to
+`gh pr create --fill`, and records the returned URL. Do not manually write a URL
+if creation fails. A PR being open is not equivalent to completion when the
+assigned outcome requires merge.
+
+Agency does not create commits, run tests, wait for checks, merge the PR, or
+verify completion. Those remain orchestrator responsibilities.
+
+## Convert A Task To Phases
+
+Name the phase that inherits the existing task's execution metadata:
+
+```bash
+agency phase create refresh-copy verification \
+  --first-phase implementation \
+  --repo frontend --branch task/refresh-copy-verification --base main \
+  --depends-on implementation
+agency validate
+```
+
+Agency converts the task shape, creates both phase documents, and relocates
+materialized worktrees. Do not perform those moves manually.
+
+## Recover From Interrupted State
+
+Inspect before applying changes:
+
+```bash
+agency doctor --json
+agency sync --dry-run --json
+agency worktree inspect <task-id> [phase-id] --json
+agency worktree repair <task-id> [phase-id] --dry-run --json
+```
+
+Use `agency sync --apply` only with explicit user intent. It may safely
+materialize an unconflicted missing checkout, release an expired claim, record a
+single matching PR, or mark work done after its authoritative PR merged and no
+claim remains. It never modifies dirty checkouts, switches branches, resets
+references, chooses among PRs, or bypasses active claims.
+
+For a worktree-specific issue, use `worktree repair --dry-run` before repair.
+Repair is conservative and never discards work. Use remove or rebuild only after
+reviewing the dry run and confirming every checkout is clean.
+
+## Archive Or Restore
+
+```bash
+agency archive phase checkout ui --dry-run --json
+agency archive phase checkout ui
+agency restore phase checkout ui --dry-run --json
+agency restore phase checkout ui
+```
+
+Archive only terminal work and only with explicit intent. Agency preserves the
+branch and lifecycle provenance while enforcing graph, worktree, and destination
+safety. Never move archived directories by hand.

package/src/cli-parser.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test"
+import orchestrationRecipes from "../fixtures/protocol/orchestration-recipes.json"
 import { parseCli } from "./cli-parser"
 
 const expectUsageError = (args: string[], usage: string) => {
@@ -6,6 +7,12 @@ const expectUsageError = (args: string[], usage: string) => {
 }
 
 describe("strict CLI parsing", () => {
+	test("accepts every documented orchestration recipe command", () => {
+		for (const args of orchestrationRecipes) {
+			expect(() => parseCli(args)).not.toThrow()
+		}
+	})
+
 	test("rejects misspelled and command-inapplicable options", () => {
 		expectUsageError(["task", "list", "--josn"], "agency task")
 		expectUsageError(
@@ -123,6 +130,7 @@ describe("strict CLI parsing", () => {
 
 	test("parses addressable resource maintenance commands", () => {
 		for (const args of [
+			["doctor", "--json"],
 			["repo", "show", "agency", "--json"],
 			["repo", "fetch", "agency"],
 			["repo", "remove", "agency"],

package/src/cli-parser.ts

@@ -804,6 +804,16 @@ const commands = {
 			conflicts: viewConflicts,
 		},
 	},
+	doctor: {
+		usage: "agency doctor [--json]",
+		options: outputOptions,
+		command: {
+			usage: "agency doctor [--json]",
+			minArgs: 0,
+			maxArgs: 0,
+			options: ["json"],
+		},
+	},
 	validate: {
 		usage: "agency validate [path] [--json] [--no-input]",
 		options: {

package/src/cli.test.ts

@@ -1,6 +1,8 @@
 import { afterEach, describe, expect, test } from "bun:test"
 import { access, mkdir, realpath } from "node:fs/promises"
 import { join } from "node:path"
+import errorFixture from "../fixtures/protocol/error.json"
+import successFixture from "../fixtures/protocol/success.json"
 import { cleanupTempDir, createTempDir } from "./test-utils"
 
 const projectRoot = join(import.meta.dir, "..")
@@ -65,6 +67,28 @@ describe("CLI", () => {
 		expect(help.stderr).toBe("")
 	})
 
+	test("keeps the published protocol fixtures synchronized with CLI output", async () => {
+		const parent = await createTempDir()
+		tempDirs.push(parent)
+		const root = join(parent, "workbase")
+		const success = await runCli(["init", root, "--json"], parent)
+		expect(success.exitCode).toBe(0)
+		expect(success.stderr).toBe("")
+		expect(success.stdout.endsWith("\n")).toBe(true)
+		const successEnvelope = JSON.parse(success.stdout)
+		expect(successEnvelope.result.root).toBe(root)
+		expect({
+			...successEnvelope,
+			result: { ...successEnvelope.result, root: "/work/agency" },
+		}).toEqual(successFixture)
+
+		const failure = await runCli(["unknown", "--json"])
+		expect(failure.exitCode).toBe(1)
+		expect(failure.stderr).toBe("")
+		expect(failure.stdout.endsWith("\n")).toBe(true)
+		expect(JSON.parse(failure.stdout)).toEqual(errorFixture)
+	})
+
 	test("reports unknown commands and preserves tagged error messages", async () => {
 		const unknown = await runCli(["unknown"])
 		expect(unknown.exitCode).toBe(1)
@@ -432,16 +456,16 @@ describe("CLI", () => {
 			await runCli(["integration", "status", "--json"], root),
 		)
 		expect(before.files).toMatchObject([
-			{ name: "agents", state: "missing" },
-			{ name: "opencode", state: "missing" },
+			{ name: "agents", state: "managed" },
+			{ name: "opencode", state: "managed" },
 		])
 
 		const synced = parseJson(
 			await runCli(["integration", "sync", "--json"], root),
 		)
 		expect(synced.files).toMatchObject([
-			{ name: "agents", state: "managed", changed: true },
-			{ name: "opencode", state: "managed", changed: true },
+			{ name: "agents", state: "managed", changed: false },
+			{ name: "opencode", state: "managed", changed: false },
 		])
 	})
 
@@ -935,6 +959,15 @@ status: open
 			valid: true,
 			issues: [],
 		})
+		const doctor = parseJson(await runCli(["doctor", "--json"], root))
+		expect(doctor).toMatchObject({
+			version: 1,
+			root: workbaseRoot,
+			checks: expect.arrayContaining([
+				expect.objectContaining({ id: "tool.git", status: "pass" }),
+				expect.objectContaining({ id: "workbase.validation", status: "pass" }),
+			]),
+		})
 
 		const validation = parseJson(
 			await runCli(["validate", root, "--json"], parent),