planr 1.1.15 → 1.1.17

package/README.md

@@ -28,6 +28,12 @@ Three layers make that work: **Plans** (reviewable Markdown packages), the **Map
 brew install instructa/tap/planr
 ```
 
+Or via npm (ships platform-native binaries, no toolchain needed):
+
+```bash
+npm install -g planr
+```
+
 Or with the release installer:
 
 ```bash

package/docs/CLI_REFERENCE.md

@@ -22,7 +22,7 @@ planr map preview --close <item-id>
 planr map unlocks <item-id>
 planr map lookahead [--from <item-id>] [--limit 10]
 planr item create "title" --description "..." [--after <item-id>] [--timeout-seconds N] [--max-retries N] [--retry-backoff fixed|exponential] [--retry-delay-ms N] [--pre "..."] [--post "..."]
-planr item breakdown <item-id> --into "A, B, C"
+planr item breakdown <item-id> --into "A" --into "B" [--into "C"]
 planr item insert "title" --description "..." --after <item-id> [--before <item-id>] [--preview|--confirm]
 planr item amend <item-id> --note "..." [--tag amendment]
 planr item replan <parent-id> --into "A, B, C" [--preview|--confirm]
@@ -83,6 +83,8 @@ With `--json`, responses follow one convention so agents never guess where data
 
 `map build` chains the created items in plan order with `blocks` links — build plan steps are ordered, so the map inherits that order instead of leaving everything flat. The output lists every created item with its status, the created links, and the next command; adjust order with `planr link add` before picking if execution order differs from document order.
 
+`item breakdown` follows the same contract: each `--into` flag carries one child title (a single value may also pack newline- or comma-separated titles), children are chained with `blocks` links in the given order, and the parent parks as a blocked gate until they settle. The output lists every child with id and status, the chain links, and the next command — across CLI and MCP `planr_item_breakdown`.
+
 `review ingest` accepts hook-compatible JSON and records it as feedback only. It never closes review work and never approves an item by itself.
 
 ```json
@@ -101,17 +103,17 @@ With `--json`, responses follow one convention so agents never guess where data
 }
 ```
 
-`review request` (and `done --review`) moves a picked or running target to `in_review`: work is finished, evidence is logged, the item waits on its gate. The owner keeps the pick and can still log evidence; `in_review` items are never handed out by `pick`.
+`review request` (and `done --review`) moves a picked or running target to `in_review`: work is finished, evidence is logged, the item waits on its gate. The owner keeps the pick and can still log evidence; `in_review` items are never handed out by `pick`. Reviews are gates, so pre-attaching one to a pending or blocked item is legal (the target keeps its status and the gate holds the close later); requesting a review on a settled item fails with `invalid_transition`. `done` on a ready item that was never picked adopts it first — the lease is written retroactively under the current worker, so the completion always carries a maker identity and the `in_review` transition is never skipped. The `done --review` response names the target's resulting status and a plan-scoped reviewer pick command (`next: planr pick --plan <id> --work-type review --json`).
 
-`review close` writes `.planr/reviews/<review-item-id>.review.md` and registers it as a review artifact. A `not-complete` or `unclear` verdict creates fix and follow-up review work; the follow-up review gates the same target item, so the chain keeps working with `--close-target`. With `--close-target` (complete verdicts only) the reviewed item is closed in the same command, provided it already has a completion log; the artifact is rendered after the target transition, so it snapshots the final target status. `--close-target` is also available through MCP `planr_review_close` and HTTP `POST /v1/reviews/{id}/close` (`"close_target": true`). `review close` responses include the same `remaining` progress snapshot as `done` and `close`. `--reviewer <id>` records the checker's identity on the review log, artifact, and event (defaults to the worker id), keeping maker and checker distinguishable in the audit trail. Closing an already-settled review fails with error code `already_closed` instead of silently duplicating evidence logs. The maker/checker split is derived, not declared: `review_mode` compares the closing reviewer identity against the target item's lease holder and reports `single_agent`, `independent`, or `unattributed` in the response, review log, artifact, and event — no ceremony note required.
+`review close` writes `.planr/reviews/<review-item-id>.review.md` and registers it as a review artifact. A `not-complete` or `unclear` verdict creates fix and follow-up review work; the follow-up review gates the same target item, so the chain keeps working with `--close-target`. With `--close-target` (complete verdicts only) the reviewed item is closed in the same command, provided it already has a completion log; the artifact is rendered after the target transition, so it snapshots the final target status. `--close-target` is also available through MCP `planr_review_close` and HTTP `POST /v1/reviews/{id}/close` (`"close_target": true`). `review close` responses include the same `remaining` progress snapshot as `done` and `close`. `--reviewer <id>` records the checker's identity on the review log, artifact, and event (defaults to the worker id), keeping maker and checker distinguishable in the audit trail. Closing an already-settled review fails with error code `already_closed` instead of silently duplicating evidence logs. The maker/checker split is derived, not declared: `review_mode` compares the closing reviewer identity against the target item's lease holder and reports `single_agent`, `independent`, or `unattributed` in the response, review log, artifact, and event — no ceremony note required. An `unattributed` close explains itself in the output: it means the target has no recorded lease (work was never picked or its lease was released), not that the reviewer's identity was missing.
 
 `trace item` on a review item inlines the target item and its evidence logs under `target`, so a reviewer's first trace already contains what is being audited. The human (non-JSON) mode renders the packet: status, owner, links, logs.
 
-`done` is the compound worker command: it writes a completion log, then requests a review (`--review`) or closes the item, and optionally picks the next ready item (`--next`). It chains the same single-owner operations as `log add`, `review request`, `close`, and `pick` — identical evidence, fewer commands. `done`, `close`, and `review close` report what the settlement `unlocked` (id, title, work type of every item that became ready), `done` and `close` echo the item's `post_condition` at completion time, and a `hint` asks for `--cmd`/`--tests` evidence when downstream items depend on an item that closed without any. `done`, `close`, `review close`, and the pick packet include a `remaining` progress snapshot so loop agents can evaluate their stop condition without an extra `map status` call. `remaining.counts` always carries the full status vocabulary (`pending`, `ready`, `picked`, `running`, `in_review`, `blocked`, `failed`, `cancelled`, `closed`, `closed_partial`) with explicit zeros — a missing count never has to be inferred.
+`done` is the compound worker command: it writes a completion log, then requests a review (`--review`) or closes the item, and optionally picks the next ready item (`--next`). Without `--next`, the response's `next` field carries the exact follow-up command instead (`planr pick --work-type review --json` after a review request, `planr pick --json` after a close), so every settlement output ends in an action. It chains the same single-owner operations as `log add`, `review request`, `close`, and `pick` — identical evidence, fewer commands. `done`, `close`, and `review close` report what the settlement `unlocked` (id, title, work type of every item that became ready), `done` and `close` echo the item's `post_condition` at completion time, and a `hint` asks for `--cmd`/`--tests` evidence when downstream items depend on an item that closed without any. `done`, `close`, `review close`, and the pick packet include a `remaining` progress snapshot so loop agents can evaluate their stop condition without an extra `map status` call. `remaining.counts` always carries the full status vocabulary (`pending`, `ready`, `picked`, `running`, `in_review`, `blocked`, `failed`, `cancelled`, `closed`, `closed_partial`) with explicit zeros — a missing count never has to be inferred.
 
 `pick --json` returns one flat work packet in which every fact appears exactly once: `item`, `links`, `logs`, `runtime`, `recovery`, `conditions`, `approval`, recall context (`contexts`, `relevant_contexts`, `upstream_handoffs`, `review_history`, `source_links`, `possible_file_conflicts`), `close_effect`, `privacy`, `deeper_reads`, and `remaining`. Worker identity lives in `item.worker_id` and `runtime.worker_id`. Empty collections and inactive gates are omitted — a missing key means "empty". No separate `trace item` call is needed. Evidence written via `log add` or `done` by the pick owner refreshes the runtime heartbeat automatically. The same packet shape is returned by MCP `planr_pick_item`, HTTP `POST /v1/pick`, and `done --next`.
 
-`pick --work-type <type>` restricts the lease to one work type, so checker agents pick only `review` items and makers only work items. `pick --plan <plan-id>` restricts the lease to one plan's items, so plan-scoped goal runs never pick work outside their contract even when other plans share the board; an unknown plan id is an error, never a silent unscoped pick. Both filters are available on MCP `planr_pick_item` and HTTP `POST /v1/pick` (`work_type`, `plan`). A null pick is never blind: `{"item": null}` carries a `reason` (`empty_map`, `all_settled`, `nothing_ready`, `no_ready_item_in_plan`, `no_ready_item_of_work_type`, `ready_items_not_pickable`) and the `remaining` snapshot. On a review item, `close_effect` previews the full `--close-target` cascade: it lists the work that closing the review (and with it the reviewed item) would unlock.
+`pick --work-type <type>` restricts the lease to one work type, so checker agents pick only `review` items and makers only work items. `pick --plan <plan-id>` restricts the lease to one plan's items, so plan-scoped goal runs never pick work outside their contract even when other plans share the board; an unknown plan id is an error, never a silent unscoped pick. Both filters are available on MCP `planr_pick_item` and HTTP `POST /v1/pick` (`work_type`, `plan`). A null pick is never blind: `{"item": null}` carries a `reason` (`empty_map`, `all_settled`, `nothing_ready`, `ready_items_excluded_by_filter`) and the `remaining` snapshot. When ready work exists but the active filters rejected all of it, `excluded` lists each ready item with the cause (`work_type` mismatch, outside the `--plan` scope, or just requested by this worker) and `repair` carries the exact pick commands that would lease that work — across CLI, MCP, and HTTP. On a review item, `close_effect` previews the full `--close-target` cascade: it lists the work that closing the review (and with it the reviewed item) would unlock.
 
 `review evidence` reports Git worktree status scoped to files named by item logs or artifacts. Dirty files without item provenance are listed as unrelated and are not treated as agent-owned evidence. `--pr-url` records an item-scoped PR reference before returning the evidence package.
 

package/docs/GOALS.md

@@ -63,9 +63,9 @@ planr done <item-id> --summary "..." --cmd "..." --review --next
 planr review close <review-id> --verdict complete --reviewer <id> --close-target
 ```
 
-`--plan` keeps the lease inside the goal contract: when several plans share the board (a parallel feature, leftovers from an aborted prep run), a plan-scoped goal run never picks work outside its own plan. A pick that finds nothing in scope reports `reason: "no_ready_item_in_plan"` instead of silently widening.
+`--plan` keeps the lease inside the goal contract: when several plans share the board (a parallel feature, leftovers from an aborted prep run), a plan-scoped goal run never picks work outside its own plan. A pick that finds nothing in scope never widens silently: it reports `reason: "nothing_ready"` when nothing is ready at all, or `reason: "ready_items_excluded_by_filter"` with the excluded items, the cause per item, and the exact `repair` pick commands when ready work exists outside the filter.
 
-`done`/`close`/`review close` responses and the pick packet include a `remaining` snapshot (`counts` with explicit zeros for every status, `settled`, `total`), so the orchestrator evaluates the stop condition straight from the completion output — no extra `map status` round-trip. The same responses list what each settlement `unlocked`, so the loop sees its next work without re-reading the map. `--next` never hands a worker its own freshly created review, so maker and checker stay separate even in compact loops. The review verdict records `review_mode` (`single_agent` or `independent`) automatically from worker identity — no ceremony note needed.
+`done`/`close`/`review close` responses and the pick packet include a `remaining` snapshot (`counts` with explicit zeros for every status, `settled`, `total`), so the orchestrator evaluates the stop condition straight from the completion output — no extra `map status` round-trip. The same responses list what each settlement `unlocked`, so the loop sees its next work without re-reading the map. `--next` never hands a worker its own freshly created review, so maker and checker stay separate even in compact loops. The review verdict records `review_mode` (`single_agent` or `independent`) automatically from worker identity — no ceremony note needed. The contract's "all reviews closed" clause audits review items that exist; an item closed with plain `done` satisfies the contract without a review gate, so low-signal reviews can be skipped without blocking `plan audit`.
 
 ### 3. Finish
 

package/docs/INSTALL.md

@@ -27,9 +27,24 @@ Download installs verify `SHA256SUMS` from the same release location by default.
 
 ## Homebrew Tap
 
-Homebrew is the preferred day-to-day package-manager path after the tap is published. The expected command is `brew install instructa/tap/planr`.
+Homebrew is the preferred day-to-day package-manager path:
 
-Until the tap is published, use the GitHub Release installer or manual release asset download.
+```bash
+brew install instructa/tap/planr
+```
+
+The tap formula is regenerated automatically on every release.
+
+## npm
+
+Published npm versions bundle platform-native binaries (`darwin-arm64`, `darwin-x86_64`, `linux-x86_64`, `linux-arm64`), so no Rust toolchain is needed and nothing is downloaded at install time:
+
+```bash
+npm install -g planr
+planr --version
+```
+
+Details and publishing flow: [npm Package](NPM.md).
 
 ## Manual GitHub Release Install
 

package/docs/TASK_GRAPH_MODEL.md

@@ -126,7 +126,7 @@ planr review close <review-id> \
 
 The target item may close only when required review items are closed.
 
-Every `review close` records a derived `review_mode`: the closing reviewer identity is compared against the target item's lease holder and recorded as `single_agent` (same identity), `independent` (different identity), or `unattributed` (no recorded maker). The mode lands in the close response, review log, artifact, and event — independence is proven by recorded identity, not declared by a note.
+Every `review close` records a derived `review_mode`: the closing reviewer identity is compared against the target item's lease holder and recorded as `single_agent` (same identity), `independent` (different identity), or `unattributed` (no recorded maker). The mode lands in the close response, review log, artifact, and event — independence is proven by recorded identity, not declared by a note. `unattributed` should be rare: `done` adopts a never-picked ready item (the lease is written retroactively under the current worker), so every completion path records a maker. When it does appear, the close output explains that the target carried no lease.
 
 ## Evidence
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.1.15",
+  "version": "1.1.17",
   "description": "Local-first planning and execution coordination for coding agents.",
   "license": "MIT",
   "repository": {

package/plugins/planr/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "planr",
   "description": "Skill-driven planning and execution loop for coding agents: one planr entry point, an autonomous planr-loop, and evidence-backed task graph skills powered by the planr CLI.",
-  "version": "1.1.15",
+  "version": "1.1.17",
   "author": {
     "name": "instructa"
   },

package/plugins/planr/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.1.15",
+  "version": "1.1.17",
   "description": "Skill-driven planning and execution loop for coding agents: one $planr entry point, an autonomous $planr-loop, and evidence-backed task graph skills powered by the planr CLI.",
   "author": {
     "name": "instructa",

package/plugins/planr/skills/planr-goal/SKILL.md

@@ -50,6 +50,8 @@ planr context add "GOAL CONTRACT <plan-id>: DONE when every in-scope map item is
 
 One contract per plan scope. Any agent on any host can recover it with `planr context list` or `planr search "GOAL CONTRACT"`. Never weaken a stored contract mid-run; scope changes go through `$planr-plan` and the user. During the run, workers lease with `planr pick --plan <plan-id>` so the loop never picks items outside this contract, even when other plans share the board. The loop checks the contract with `planr plan audit <plan-id>`, which evaluates exactly these clauses with evidence and answers `holds: true/false`.
 
+"All reviews closed" audits review items that exist — it does not require a review gate on every item. An item closed with plain `done` (evidence still required) satisfies the contract without one; request reviews where they carry signal (implementation slices, user-facing work), not on trivial inspection or scaffold steps.
+
 ## Hand Off
 
 Print the starter command, then stop. Do not start execution yourself; ask whether to start now, refine the plan, or stop.

package/plugins/planr/skills/planr-loop/SKILL.md

@@ -48,11 +48,13 @@ Each iteration is one dispatch through the routing skill — never a hand-writte
 6. repeat             fix items are just the next ready items
 ```
 
-The short path per item is three commands: `planr pick --json` (one flat work packet; makers add `--work-type code`), `planr done <item-id> --summary ... --cmd ... --review [--next]`, and the reviewer's `planr --json pick --work-type review` followed by `planr review close <review-id> --verdict complete --reviewer <id> --close-target` — run exactly once. Parent gates roll up automatically. When the loop runs against one plan (every `/goal` run does), add `--plan <plan-id>` to every pick so the lease never leaves the goal contract, even when other plans share the board; an empty scope reports `reason: "no_ready_item_in_plan"`.
+The short path per item is three commands: `planr pick --json` (one flat work packet; makers add `--work-type code`), `planr done <item-id> --summary ... --cmd ... --review [--next]`, and the reviewer's `planr --json pick --work-type review` followed by `planr review close <review-id> --verdict complete --reviewer <id> --close-target` — run exactly once. Parent gates roll up automatically. When the loop runs against one plan (every `/goal` run does), add `--plan <plan-id>` to every pick so the lease never leaves the goal contract, even when other plans share the board. A null pick explains itself: when filters excluded ready work, `reason: "ready_items_excluded_by_filter"` names each excluded item, the cause (work_type or plan mismatch), and the exact `repair` pick command — run the repair instead of guessing.
 
-`map build` chains created items in plan order with `blocks` links automatically and prints the created items and links. In step 2, verify that chain against real execution-order dependencies and adjust with `planr link add` only where document order and execution order differ.
+`map build` chains created items in plan order with `blocks` links automatically and prints the created items and links. In step 2, verify that chain against real execution-order dependencies and adjust with `planr link add` only where document order and execution order differ. `item breakdown` works the same way: pass one `--into` per child title (or one value with newline-separated titles), and the output lists the chained children plus the next command.
 
-The loop never closes its own reviews when the host supports a second agent. Maker and checker stay separate.
+Request reviews where they carry signal: implementation slices and anything user-facing finish with `done --review`. Trivial inspection, baseline, or setup items close with plain `done` (evidence still required) — a review that can only confirm "the repo was empty" adds ceremony, not safety. The goal contract's "all reviews closed" clause audits review items that exist; plain-`done` items satisfy it without a review gate, so skipping low-signal reviews never blocks `plan audit`.
+
+The loop never closes its own reviews when the host supports a second agent. Maker and checker stay separate. One agent instance keeps one `PLANR_WORKER_ID` for the whole session — never export a second identity inside the same instance to make reviews look `independent`; an honest `single_agent` stamp beats a fake `independent` one.
 
 ## Skills Are The Prompts
 

package/plugins/planr/skills/planr-review/SKILL.md

@@ -41,7 +41,9 @@ planr review close <review-id> --verdict not-complete --reviewer <your-id> --fin
 
 ## Single-Agent Mode
 
-When no independent reviewer instance is available (single-agent host), do not pretend a second instance reviewed the work. Re-read the diff, logs, and evidence with fresh eyes, then close normally. The review mode is recorded automatically: `review close` compares your identity against the maker's lease and stamps `review_mode: single_agent | independent | unattributed` on the close response, review log, artifact, and event. No extra context note is needed — honesty is derived from recorded identity. To run an honest independent review on a multi-instance host, export a distinct `PLANR_WORKER_ID` before picking.
+When no independent reviewer instance is available (single-agent host), do not pretend a second instance reviewed the work. Re-read the diff, logs, and evidence with fresh eyes, then close normally. The review mode is recorded automatically: `review close` compares your identity against the maker's lease and stamps `review_mode: single_agent | independent | unattributed` on the close response, review log, artifact, and event. No extra context note is needed — honesty is derived from recorded identity.
+
+Identity honesty rule: one agent instance keeps one `PLANR_WORKER_ID` for its whole session. Never export a second identity (e.g. `maker-x` and `checker-x`) inside the same instance to make a review look independent — that stamps `independent` on a review that was not, which is worse than an honest `single_agent`. `independent` is only real when a separate agent process (a subagent, another terminal, another client) picks the review under its own identity.
 
 ## Completion Rule
 

package/plugins/planr/skills/planr-task-graph/SKILL.md

@@ -135,7 +135,7 @@ parent gate
 Rules:
 
 - create a parent item for the change;
-- use `planr item breakdown <parent-id> --into "Implement, Verify"` to create child work under that parent;
+- use `planr item breakdown <parent-id> --into "Implement" --into "Verify"` (one `--into` per child; a single value may also pack newline- or comma-separated titles) to create chained child work under that parent — the output lists every child with id and status plus the next pick command;
 - request review on the implementation or test child after evidence exists;
 - if review finds issues, let Planr create fix and follow-up review work from the review verdict;
 - make later top-level work depend on the parent gate, not only the first child.
@@ -157,7 +157,7 @@ Readiness comes from graph links and item state, not Markdown checkboxes.
 Use:
 
 ```bash
-planr item breakdown <item-id> --into "Trace owner, Implement, Verify"
+planr item breakdown <item-id> --into "Trace owner" --into "Implement" --into "Verify"
 planr link remove <from-item> <to-item> --type blocks
 ```
 

package/plugins/planr/skills/planr-work/SKILL.md

@@ -16,13 +16,13 @@ export PLANR_WORKER_ID=maker-1
 planr pick --json
 ```
 
-The pick output is one flat work packet — item, links, logs, runtime, recovery, conditions, recall context (`upstream_handoffs`, `relevant_contexts`, `review_history`), and `remaining` progress. Each fact appears once; a missing key means "empty". No separate `trace item` call needed. Add `--work-type code` to skip review items when checker agents work the same board, and `--plan <plan-id>` when your dispatch names a plan so the lease stays inside that scope. A null pick explains itself: `{"item": null}` carries a `reason` (`all_settled`, `nothing_ready`, `no_ready_item_in_plan`, ...) plus the `remaining` snapshot. Read the linked plan/context, implement the smallest correct slice, then finish the step in one command:
+The pick output is one flat work packet — item, links, logs, runtime, recovery, conditions, recall context (`upstream_handoffs`, `relevant_contexts`, `review_history`), and `remaining` progress. Each fact appears once; a missing key means "empty". No separate `trace item` call needed. Add `--work-type code` to skip review items when checker agents work the same board, and `--plan <plan-id>` when your dispatch names a plan so the lease stays inside that scope. A null pick explains itself: `{"item": null}` carries a `reason` (`all_settled`, `nothing_ready`, `ready_items_excluded_by_filter`) plus the `remaining` snapshot; when filters excluded ready work, `excluded` names each item and cause and `repair` carries the exact pick command to run instead. Read the linked plan/context, implement the smallest correct slice, then finish the step in one command:
 
 ```bash
 planr done <item-id> --summary "what changed" --files path-a --files path-b --cmd "exact verification command" --tests "exact test command" --review
 ```
 
-Put build/serve commands in `--cmd` and test runs in `--tests` — both are recorded as evidence. `done --review` writes the completion log, requests the review, and moves the item to `in_review` (you keep ownership; it is waiting on the gate, not abandoned); add `--next` to pick the following item in the same call. Without `--review` it closes the item directly (only for items that need no review gate). The response reports what your settlement `unlocked`, echoes the item's post condition, and hints when downstream work depends on an item closed without command/test evidence.
+Put build/serve commands in `--cmd` and test runs in `--tests` — both are recorded as evidence. Single-quote `--files` values that contain `$` (route files like `watch.$videoId.tsx`), or the shell expands them before planr sees them. `done --review` writes the completion log, requests the review, and moves the item to `in_review` (you keep ownership; it is waiting on the gate, not abandoned) — the response names the target's new status and the plan-scoped reviewer pick command; add `--next` to pick the following item in the same call. Without `--review` it closes the item directly (only for items that need no review gate). Running `done` on a ready item you never picked adopts it: the lease is written retroactively under your worker id so the review always has a maker. The response reports what your settlement `unlocked`, echoes the item's post condition, and hints when downstream work depends on an item closed without command/test evidence.
 
 Live verification (browser flow, executed binary, real requests) gets its own log kind so `plan audit` can find it: