@allocator-one/harness-cli 1.13.0 → 1.14.0

package/README.md

@@ -58,20 +58,47 @@ numbering, `ALL-` numbers up to the import ceiling came from Linear, and
 ## Daily workflow
 
 ```sh
-harness ready --claim --all                     # pick and claim the top uncontested issue
+harness ready --claim                           # claim the team's next ready, unassigned issue
 harness show CLI-12                             # read it, including attached screenshots
 # … do the work …
 harness close CLI-12 --reason "Implemented in 1a2b3c4"
 ```
 
 **Queue.** `harness ready` lists open, unblocked issues, highest priority
-first. Blocked issues, `hold`-labeled issues, and parents with open children
-are excluded. `--claim` claims the first issue in that ranking that nobody
-else holds. It tries up to 10 issues and exits `1` with "No claimable
-ready issues" when none can be claimed. Pass `--all` so that the ranking
-covers the whole ready set rather than just the first page. `harness
-blocked` lists issues that are waiting on a blocker. Both commands take
-`--team`.
+first. Blocked issues, `hold`-labeled issues, and parents with sub-issues
+that are not completed are excluded. Only a completed blocker resolves: a
+cancelled or archived one still blocks until it is completed or the
+dependency is removed or re-pointed. An issue that is waiting on a wait
+condition (see [Plans](#plans)) is not ready either. `harness blocked` lists
+issues that are waiting on a blocker.
+Both commands take `--team`. `ready` marks agent steps, the plan steps
+Operator runs, with `[agent]` before the title and a legend under the table,
+and `--json` gives every issue an `agent_step` flag. Only the plan driver
+claims an agent step. The issue payload carries no executor, so the CLI
+goes by the team: agent steps are filed in the organization's Operator team
+(named Operator, keyed `OPERATOR`, or `OPERATOR2` and so on). That is a
+heuristic. A step handed back to a person keeps its team and stays marked,
+and the claim itself is the authority.
+
+**Claim the next issue.** `harness ready --claim` is a single request: the
+server picks the team's most important ready issue that has no assignee
+(urgent, high, medium, low, then none; oldest first, then by id), assigns
+you, and moves it to the team's first started state, all in one transaction.
+Concurrent callers get different issues, and the CLI does no paging, sorting,
+or retrying of its own.
+
+- It needs a team: `--team`, then `HARNESS_TEAM`, then the repo config. With
+  none of them it is a usage error, and the claim is never sent.
+- `--all`, `--limit`, and `--page` are refused with `--claim`, because the
+  server already ranks the whole ready set.
+- An empty queue is a normal outcome: it prints "Nothing to claim: team CLI
+  has no unassigned ready issues." (`null` with `--json`) and exits `0`.
+- A rate limit, server error, or unreadable response exits `1`, and an
+  unreachable API exits `3`. None of these is reported as an empty queue.
+  The CLI never retries the claim. When an unreadable response or a lost
+  connection leaves it unknown whether the claim landed, the error says to
+  check `harness list --team <key> --assignee me --status in_progress`
+  before claiming again.
 
 **Read.** `harness show <id>` prints the fields, relations, children, and
 comments. It also downloads the images attached to the issue's description,
@@ -79,7 +106,13 @@ design, acceptance criteria, notes, and comments (up to 20, cached locally)
 and prints their paths. Screenshots are often the reproduction, so read
 them. `--no-images` skips the downloads. If a download fails, a stderr
 notice says so and the command still succeeds. `harness comments <id>`
-prints the full, untruncated comment thread with comment ids.
+prints the full, untruncated comment thread with comment ids. The
+`Blocked:` line names a cancelled or archived blocker as such
+(`yes, by CLI-3 (cancelled), CLI-4 (archived), CLI-5`). When the issue has
+wait conditions, `Waiting:` says how many still hold it, and a
+`Wait conditions:` section lists each one (`[ ] gate "Finance sign-off" · <id>`,
+`[x] not before … (satisfied …)`, `system event`) with the id
+`harness gate satisfy` takes.
 `harness activity <id>` prints the issue's activity timeline: comments,
 creation, and state and assignee changes. It shows the newest 20 entries
 (`--limit` accepts 1–100), and `--all` reads further back.
@@ -110,8 +143,13 @@ harness create --title "Fix login redirect" --type bug --priority high \
 **Update.** `harness update <id>` with:
 
 - `--claim`: atomic. It assigns you and moves the issue to the team's first
-  started state. A conflict means someone else holds the issue. It cannot be
-  combined with `--assignee`.
+  started state. A conflict (exit `1`, HTTP 409) names its reason: someone
+  else holds the issue, or it is not claimable yet. Two reasons come with a
+  next step: `agent_step` (Operator runs it; to do it yourself, set its
+  executor to `none` with `harness plan edit <plan-id>` and release the plan
+  again) and `waiting_on_condition` (`harness show` lists what it waits on;
+  tick a gate with `harness gate satisfy`). It cannot be combined with
+  `--assignee`.
 - `--state <name-or-type>`: moves the issue to the workflow state whose name
   or type matches.
 - `--title`, `--description`, `--design`, `--acceptance`, `--priority`,
@@ -136,7 +174,13 @@ duplicate-of form records a duplicate relation and cannot be combined with
 `--cancel`. `--reason` records why the issue is done. The output lists the
 issues each closure unblocked
 (`Closed CLI-12 — unblocked: CLI-13, CLI-14`); act on them instead of
-leaving them in the queue. With several ids, each one is closed on its own.
+leaving them in the queue. Only completing releases dependents: a canceled
+issue still blocks them. A duplicate close moves its blocking edges to the
+canonical issue, and any edge that cannot move stays on the duplicate. When
+the closed issue still blocks anything, an indented line names those
+dependents (`Still blocking: CLI-13 (a cancelled issue still blocks its
+dependents)`) so you can remove or re-point those dependencies. With
+several ids, each one is closed on its own.
 A failure prints `FAILED <id>: …`, and the command exits `1` after trying
 the rest. `harness archive <id>…` archives issues, `--restore` brings them
 back, and `harness list --scope archived` lists them.
@@ -167,8 +211,12 @@ comments. Comment ids are UUIDs from `harness comments`.
 `--parent <id>` (children of an epic), and `--scope all|archived`.
 
 **Overview.** `harness stats` prints per-team and total counts.
-`harness prime` prints those counts, the top of the ready queue, and a
-short workflow reminder. It is meant for the start of an agent session.
+`harness prime` prints those counts, the organization's ten most important
+ready issues across every team (urgent first and priority none last, ranked
+the way `harness ready --claim` ranks, though that claims only unassigned
+issues on one team), and a short workflow reminder. It is meant for the
+start of an agent session. Against a server older than this read it shows
+the ten newest ready issues instead.
 
 ### Text from a file
 
@@ -193,7 +241,9 @@ git log -1 --format=%B | harness close CLI-12 --reason-file -
 | `comment`, `comment edit` | `--body-file` |
 
 Other commands (`project`, `milestone`, `doc`, `link`, and so on) take inline
-values only. `-` reads from stdin, and only one option per invocation can do
+values only. `plan create` and `plan edit` read a whole JSON or YAML
+document with `--file` (see [Plans](#plans)), under the same stdin and
+UTF-8 rules, up to 8 MB (the API's request limit). `-` reads from stdin, and only one option per invocation can do
 that. stdin must not be a terminal. Passing both the inline and the file form
 of a field is a usage error, and so is a file that produces an empty title,
 reason, or comment. Conflicting options are caught before anything is read,
@@ -201,6 +251,119 @@ so a rejected command never consumes your pipe. A file must be valid UTF-8
 and at most 1 MB, and one trailing newline is dropped, as with
 `$(cat file)`.
 
+## Plans
+
+A plan is a root issue and its steps, created in one request: their
+parents, `blocked_by` dependencies, executors, teams and wait conditions.
+Either the whole plan is created or nothing is. Plans start held, so
+nothing runs until a person releases one.
+
+```sh
+harness plan create --file plan.yaml --team IO --idempotency-key q3-report
+harness plan show <plan-id>
+harness plan release <plan-id> --collaborator grace@example.com
+harness gate satisfy IO-121 "Finance sign-off"
+```
+
+**The plan file** is the API's request body, as JSON (`.json`) or YAML
+(anything else, and stdin with `--file -`). YAML is read as YAML 1.2 and
+held to what JSON can carry: dates stay strings, and a duplicate key, an
+explicit tag such as `!!timestamp`, or `.inf`/`.nan` is refused. The
+root's fields sit at the top level, and each step has a `key` that other
+steps refer to:
+
+```yaml
+title: Ship the Q3 LP report
+spend_budget_cents: 5000        # needed to release Operator steps
+steps:
+  - key: gather
+    title: Gather the fund data
+    executor: operator          # Operator runs it; the description is its instruction
+    description: Pull the Q3 NAVs for every fund in the portfolio
+  - key: review
+    title: Review the numbers
+    team: IO                    # a person's step; defaults to --team
+    blocked_by: [gather]
+    conditions:
+      - kind: gate
+        label: Finance sign-off
+  - key: send
+    title: Send the report
+    blocked_by: [review]
+    conditions:
+      - kind: not_before
+        not_before: "2026-10-15T09:00:00Z"
+```
+
+- A step takes the issue fields (`title`, `description`, `priority` as a
+  number from 0 for none to 4 for low, `assignee`, `label_ids`, …) plus
+  `key`, `parent` (the key of the step that contains it), `blocked_by`
+  (keys), `executor` (`none`, the default, or `operator`), `team`, and
+  `conditions`. Operator steps are filed in the Operator team. Only steps
+  without sub-steps carry an executor, edges, or conditions.
+- Wait conditions: `not_before` (a UTC instant), `gate` (a `label` a person
+  ticks), and `event` (`event`, `subject_id`, and for a stage change
+  `target_id`). The allowed events are `deal_stage_changed`,
+  `opportunity_stage_changed`, `form_submitted`, and `investment_executed`.
+  Every condition must hold before the step is ready.
+- A plan has at most 100 steps, its root included.
+- `--team` (or `HARNESS_TEAM` or the repo config) is the root's team and the
+  default team for people's steps. `--idempotency-key` works as it does for
+  `create`: if a create times out, run it again with the same key to get
+  the same plan back.
+
+**Validation.** The server checks the whole graph and an invalid plan
+creates nothing. The command exits `1`, and stderr lists every violation by
+the step key it is about:
+
+```text
+harness: The plan is not valid; nothing was changed (HTTP 422)
+  step "review" (steps[1]): parent names no step of this plan, or no issue in this organization (parent: nope) [unknown_parent]
+  plan: A plan with Operator steps needs a positive spend budget [spend_budget_required]
+```
+
+**Show.** `harness plan show <plan-id>` prints the plan's status, budgets,
+revision, and spend estimate, then every step in tree order (indented by
+depth) with its key, executor, state, and status. The status is `ready`,
+`held` (edited since the release), `not in revision` (added after it),
+`waiting` (on a wait condition), `container`, `done`, `cancelled`,
+`archived`, or `-`. The edges and each step's wait conditions come after
+the steps.
+
+**Edit.** `harness plan edit <plan-id> --file edits.yaml` changes step
+executors and keys, naming each step by its `step` key or `issue`
+identifier, and the budgets (`retry_budget`, `spend_budget_cents`):
+
+```yaml
+steps:
+  - step: gather
+    executor: none              # hand the step to a person
+```
+
+Editing a released step holds it until the plan is released again. A
+budget change needs the plan held first. Descriptions, parents, and edges
+are edited with the issue commands (`update`, `dep`). Conditions are set
+when the plan is created. Editing them later goes through the API's issue
+condition endpoints, which have no command yet; `gate satisfy` ticks a
+gate.
+
+**Release and hold.** `harness plan release <plan-id>` releases the plan as
+you: it freezes the next revision and lets ready steps run.
+`--collaborator <id-or-email>` (repeatable) adds people to the plan room
+where its Operator steps run, and `--retry-budget` and
+`--spend-budget-cents` set the budgets. `harness plan hold <plan-id>`
+pauses every step until the plan is released again.
+
+**Gates.** `harness gate satisfy <issue> <gate>` ticks a gate and
+`harness gate unsatisfy <issue> <gate>` unticks it. `<gate>` is the gate's
+label or its condition id from `harness show`. A label matches exactly
+first, then ignoring case, and a label that more than one gate carries is
+refused with their ids. Ticking a gate requires staff standing in the
+organization.
+
+A server without the plan API answers the plan commands with a 404, and the
+error says that the server may predate plans.
+
 ## Uploads
 
 `harness upload <path>` uploads a file and prints a markdown reference to
@@ -290,7 +453,7 @@ can read.
   - The `activity`, `search`, and `show` notices described above.
   - The update notice (see [Staying current](#staying-current)).
 - **Pagination.** `ready`, `blocked`, `list`, `project list`, and `doc list`
-  return 50 records per page by default. `--limit` changes the page size,
+  return 50 records per page by default (`ready --claim` has no pages). `--limit` changes the page size,
   `--page` selects a page, and `--all` follows every page (pass `--all` or
   `--page`, not both). The truncation notice goes to stderr only, so a
   script that reads just the `--json` output cannot tell a full page from a
@@ -299,8 +462,8 @@ can read.
 
   | Code | Meaning |
   | --- | --- |
-  | `0` | Success. |
-  | `1` | The command failed. Causes include an API error (the message gives the HTTP status), a failure such as nothing being claimable, a partial failure across several ids, or a local refusal such as an unreadable or oversized upload. |
+  | `0` | Success, including `ready --claim` finding nothing to claim. |
+  | `1` | The command failed. Causes include an API error (the message gives the HTTP status, followed by any per-field errors or plan violations, one per line), a response the CLI cannot interpret, a partial failure across several ids, or a local refusal such as an unreadable or oversized upload. |
   | `2` | Usage or configuration error, including "not signed in" outside a terminal. Nothing was sent. |
   | `3` | The API was unreachable (DNS, TLS, connection refused, or timeout). Retry with backoff, and if the API stays down, say so instead of dropping tracked work. |
 
@@ -319,7 +482,7 @@ With a global install, `harness mcp` works as the command instead of the
 { "mcpServers": { "harness": { "command": "npx", "args": ["-y", "@allocator-one/harness-cli", "mcp"] } } }
 ```
 
-The server exposes 52 tools:
+The server exposes 58 tools:
 
 | Area | Tools |
 | --- | --- |
@@ -331,6 +494,7 @@ The server exposes 52 tools:
 | Labels | `label_list`, `label_create`, `label_update`, `label_delete` |
 | Teams and states | `team_list`, `team_create`, `team_rename`, `team_set_default`, `workflow_states`, `state_add`, `state_update`, `state_order`, `state_delete` |
 | People | `member_list`, `member_add`, `member_set_role`, `user_list` |
+| Plans and gates | `plan_create`, `plan_show`, `plan_edit`, `plan_release`, `plan_hold`, `gate_set` |
 | Other | `stats`, `upload` |
 
 The tools cover the issue workflow and the admin surface. Some commands are
@@ -343,8 +507,22 @@ Some tools behave differently from their commands:
 
 - `issue_list` with `ready: true` or `blocked: true` accepts every list
   filter. The CLI's `ready` and `blocked` take only `--team`.
+- `issue_list` only lists. Claiming the team's next issue (`ready --claim`)
+  is CLI-only; over MCP, claim a specific issue with `issue_claim`.
 - `issue_show` downloads images only when you pass `images: true`.
 - `state_delete` and `label_delete` don't need the CLI's `--yes`.
+- `plan_create` takes the plan as an object (`plan`), with `team` and
+  `idempotency_key` beside it, instead of a file. Its schema describes the
+  steps and conditions, and keys inside `plan` that the schema does not
+  know are still sent, so the server reports them. `plan_edit` takes
+  `steps`, `retry_budget`, and `spend_budget_cents` directly. As with every
+  tool, a top-level argument the tool does not declare is dropped.
+  `gate_set` takes `issue`, `gate`, and `satisfied`.
+- An API error's details come back in the tool error text: a validation
+  error's fields, and an invalid plan's violations, one per line by step
+  key.
+- `issue_list` with `ready: true` gives every issue an `agent_step` flag,
+  read from its team as `ready` does.
 
 For example, `issue_list` with `{"ready": true, "team": "CLI"}` returns the
 ready queue, and `issue_claim` with `{"id": "CLI-12"}` claims an issue