@markjaquith/agency 2.28.0 → 2.28.1

package/skills/agency/references/commands.md

@@ -0,0 +1,161 @@
+# Agency Command Reference
+
+Use this reference after `agency context . --json` identifies the target. Run
+`agency <command> --help` for the exact options supported by the installed CLI.
+Commands that return Agency-owned data accept `--json` unless noted otherwise.
+
+## Discovery And Health
+
+```text
+agency context [target] [--json] [--compact]
+agency graph [--json | --jsonl] [--ready | --blocked]
+  [--status <status>...] [--repository <alias>...] [--kind <kind>...]
+  [--include <bodies|workspace|git|pr>...]
+agency next [--select] [--json]
+agency status [filters] [--json]
+agency validate [path] [--json]
+agency doctor [--json]
+agency sync [--dry-run | --apply] [--json]
+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
+observational unless `--apply` is explicit.
+
+`next` currently resolves only the process cwd. Although global `--cwd` and
+`--workbase` are accepted by the parser, run `next` from the intended workbase.
+
+## Workbase And Repositories
+
+```text
+agency init [path] [--json]
+agency workbase add <path> [--name <name>] [--json]
+agency workbase list [--json]
+agency workbase show <id|name|path> [--json]
+agency workbase name <id|name|path> (<name> | --clear) [--json]
+agency workbase default [<id|name|path> | --clear] [--json]
+agency workbase remove <id|name|path> [--json]
+agency workbase prune [--json]
+agency repo add <alias> <remote> [--json]
+agency repo link <alias> <path> [--json]
+agency repo list [--json]
+agency repo show <alias> [--json]
+agency repo fetch <alias> [--json]
+agency repo remote <alias> [remote] [--json]
+agency repo verify <alias> [--json]
+agency repo rename <alias> <new-alias> [--json]
+agency repo remove <alias> [--json]
+agency repo unlink <alias> [--json]
+```
+
+`repo add` creates a bare clone; `repo link` creates a symlink to an existing
+repository. Removal, unlink, and rename refuse active references or linked
+worktree conflicts.
+
+## Epics, Tasks, And Phases
+
+```text
+agency epic create <id> --ticket-url <url> [--description <text>]
+  --repo <alias>:<ref>... [--json]
+agency epic list [filters] [--json]
+agency epic show <id> [--json]
+agency epic update <id> [metadata options] [--if-revision <hash>] [--json]
+agency epic rename <id> <new-id> [--if-revision <hash>] [--json]
+
+agency task new [id]
+agency task create <id> --repo <alias> [--ticket-url <url>]
+  [--description <text>] [--epic <id>] [--reference <alias>:<ref>...]
+  [--branch <name>] [--base <name>] [--json]
+agency task create <id> --multi-phase [--ticket-url <url>]
+  [--description <text>] [--epic <id>] [--json]
+agency task list [filters] [--json]
+agency task show <id> [--json]
+agency task status <id> <open|done|dropped> [--json]
+agency task update <id> [metadata options] [--if-revision <hash>] [--json]
+agency task rename <id> <new-id> [--if-revision <hash>] [--json]
+agency task move <id> (--epic <epic-id> | --no-epic)
+  [--if-revision <hash>] [--json]
+agency task dependency <add|remove> <task-id> <dependency-id>
+  [--if-revision <hash>] [--json]
+
+agency phase create <task-id> <phase-id> --repo <alias> --branch <name>
+  --base <name> [--description <text>] [--reference <alias>:<ref>...]
+  [--depends-on <phase-id>...] [--first-phase <phase-id>] [--json]
+agency phase list <task-id> [filters] [--json]
+agency phase show <task-id> <phase-id> [--json]
+agency phase status <task-id> <phase-id> <open|done|dropped> [--json]
+agency phase update <task-id> <phase-id> [metadata options]
+  [--if-revision <hash>] [--json]
+agency phase rename <task-id> <phase-id> <new-id>
+  [--if-revision <hash>] [--json]
+agency phase dependency <add|remove> <task-id> <phase-id> <dependency-id>
+  [--if-revision <hash>] [--json]
+```
+
+`task new` is interactive and requires a TTY. Agents and scripts use
+noninteractive `task create`. Mutation commands that accept `--if-revision`
+return a revision conflict instead of overwriting changed documents.
+
+## Ownership And Lifecycle
+
+```text
+agency claim <task-id> [phase-id] --claimant <id> --runner <id>
+  --session-id <id> --revision <sha256> [--expires-at <timestamp>] [--json]
+agency release <task-id> [phase-id] --session-id <id>
+  --revision <sha256> [--json]
+agency finish <task-id> [phase-id] --session-id <id>
+  --revision <sha256> --outcome <done|dropped> [--json]
+
+agency archive list [--kind <kind>] [--status <status>]
+  [--repository <alias>]
+agency archive show <epic|task> <id>
+agency archive show phase <task-id> <phase-id>
+agency archive epic <epic-id> [--dry-run] [--json]
+agency archive task <task-id> [--dry-run] [--json]
+agency archive phase <task-id> <phase-id> [--dry-run] [--json]
+agency restore epic <epic-id> [--dry-run] [--json]
+agency restore task <task-id> [--dry-run] [--json]
+agency restore phase <task-id> <phase-id> [--dry-run] [--json]
+```
+
+Claim mutations require the current execution-document revision. Archive and
+restore preflight graph and destination safety, remove registered clean
+worktrees when needed, preserve branches, and retain lifecycle provenance.
+
+## Worktrees, Launch, And Pull Requests
+
+```text
+agency work [<directory> | --epic <id>] [--runner <name>] [--print-command]
+agency work prepare [target] [--dry-run] [--json]
+agency worktree list [--json]
+agency worktree inspect <task-id> [phase-id] [--json]
+agency worktree prepare <task-id> [phase-id] [--dry-run] [--json]
+agency worktree remove <task-id> [phase-id] [--dry-run] [--json]
+agency worktree rebuild <task-id> [phase-id] [--dry-run] [--json]
+agency worktree repair <task-id> [phase-id] [--dry-run] [--json]
+agency pr create <task-id> [phase-id] [--draft] [--force] [--json]
+```
+
+`work` is a launch flow, not an active-agent step. `work prepare` materializes
+without launching or changing status. Destructive remove and rebuild operations
+refuse dirty or conflicting state. Conservative repair may correct registration
+while preserving dirty files, but never discards changes. `pr create` requires a
+clean writable checkout, pushes the declared branch, invokes the configured
+delivery provider or falls back to `gh pr create --fill`, and records the
+returned URL.
+
+## Noninteractive Selection
+
+Use global `--workbase <id|name|path>` outside a workbase, or `--cwd <path>` to
+perform cwd inference elsewhere. Targeted commands accept `--epic`, `--task`,
+and, with a task, `--phase`. `--json`, `--no-input`, or non-TTY execution disables
+prompts; provide all selectors and required inputs explicitly.
+
+Selectors are only a resolution mechanism; they do not make discovery and claim
+atomic. There is no `assign` command. Use `work` for a local human launch, or use
+`claim` and manage an external runner separately.

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(