planr 0.0.1 → 1.1.16

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 regenrek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,150 @@
+# Planr
+
+![Planr — turn chaotic agent work into a verified task graph](public/planr_banner1.webp)
+
+Planr is a local-first planning and execution coordination tool for coding agents. It combines reviewable Markdown plans with a dependency-aware work map so Codex, Claude Code, Cursor, generic MCP clients, and human operators can drive the same work safely — from idea to verified completion.
+
+```text
+idea -> product plan -> build plan -> map -> pick -> log -> review/evidence -> close
+```
+
+## Why Planr
+
+![Why Planr exists — without Planr vs with Planr](public/planr_banner2.webp)
+
+Flat todo lists break down the moment real work has structure. Planr models work as a dependency graph because that is what work actually is:
+
+- **Readiness is computed, not guessed.** An item becomes `ready` only when its blockers are closed; `planr pick` returns work that is actually startable.
+- **Parallel agents need atomic claims.** Picks are atomic claims enforced by the database — one item, one owner, no checklist races.
+- **"Done" is gated, not asserted.** Closure requires log-backed evidence (files, commands, tests) and open reviews block their target.
+- **State survives sessions.** Markdown plans hold scope and acceptance criteria; the SQLite graph holds live status across handoffs, restarts, and agent switches.
+- **Failure is structured.** Stale picks, timeouts, and retries are detectable and recoverable (`planr recover sweep`).
+
+Three layers make that work: **Plans** (reviewable Markdown packages), the **Map** (live dependency graph with picks, reviews, logs), and **Agent loops** (skills, CLI, and MCP workflows for every major coding agent). Full model: [Task Graph Model](docs/TASK_GRAPH_MODEL.md) and [Operating Model](docs/OPERATING_MODEL.md).
+
+## Install
+
+```bash
+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
+curl -fsSL https://raw.githubusercontent.com/instructa/planr/main/scripts/install.sh | sh
+```
+
+Then initialize a project (also provisions the worker/reviewer subagent roles for your client):
+
+```bash
+planr project init "My Product" --client all
+```
+
+Manual downloads, from-source builds, and client wiring details: [Install Guide](docs/INSTALL.md).
+
+## Install The Plugin (Skills)
+
+The plugin under `plugins/planr` carries the nine Planr skills plus the `planr-worker` and `planr-reviewer` subagent roles. The `planr` CLI (above) is required separately.
+
+<a id="install-plugin-codex"></a>
+<details>
+<summary><strong>Codex</strong></summary>
+
+```bash
+codex plugin marketplace add instructa/planr
+codex plugin add planr@planr
+```
+
+</details>
+
+<a id="install-plugin-claude-code"></a>
+<details>
+<summary><strong>Claude Code</strong></summary>
+
+Inside a Claude Code session:
+
+```text
+/plugin marketplace add instructa/planr
+/plugin install planr@planr
+```
+
+Restart Claude Code afterwards. Skills are namespaced (`/planr:planr`, `/planr:planr-loop`), and the plugin registers the `planr-worker` and `planr-reviewer` subagents automatically.
+
+</details>
+
+<a id="install-plugin-cursor"></a>
+<details>
+<summary><strong>Cursor</strong></summary>
+
+Pending marketplace review. Until the plugin is listed, wire Planr in via MCP and the CLI prompt:
+
+```bash
+planr install cursor        # writes .cursor/mcp.json
+planr prompt cli --client cursor
+```
+
+</details>
+
+<a id="install-plugin-opencode"></a>
+<details>
+<summary><strong>opencode</strong></summary>
+
+No plugin yet. Use Planr as an MCP server and paste the CLI prompt into your agent instructions:
+
+```bash
+planr mcp                   # stdio MCP server
+planr prompt cli
+```
+
+</details>
+
+## Tell Your Agent
+
+Two skills drive everything. `$planr` routes any request to the right stage skill from live map state; `$planr-loop` drives one feature through work, live verification, and independent review until the map is clean.
+
+Start a new product from an idea:
+
+```text
+Use $planr.
+
+Create a production-ready Habit Tracker web app plan. Create the product plan,
+split an MVP build plan, check it, then build the Planr map. Do not implement yet.
+```
+
+Ship one feature autonomously until verified:
+
+```text
+Use $planr-loop.
+
+Goal: ship the weekly overview feature. DONE when every in-scope map item is closed
+with log evidence, all reviews are closed complete, and a live verification log shows
+the feature working in the browser. Iteration budget: 10.
+```
+
+Mid-project work (a new feature, refactor, or fix on an existing project) works the same — it gets its own feature-scoped plan and extends the existing map. Both journeys with example prompts: [Two Journeys](docs/SKILLS.md#two-journeys-new-project-vs-existing-project). Watch progress anytime with `planr map show`.
+
+## Docs
+
+- [Install](docs/INSTALL.md)
+- [Skills](docs/SKILLS.md)
+- [Long-Running Goals](docs/GOALS.md)
+- [CLI Reference](docs/CLI_REFERENCE.md)
+- [MCP Guide](docs/MCP_GUIDE.md)
+- [Codex](docs/CODEX.md) · [Claude Code](docs/CLAUDE_CODE.md) · [Cursor](docs/CURSOR.md)
+- [Operating Model](docs/OPERATING_MODEL.md)
+- [Task Graph Model](docs/TASK_GRAPH_MODEL.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Testing](docs/TESTING.md)
+- [Troubleshooting](docs/TROUBLESHOOTING.md)
+- [Specification Package](docs/planr-spec/README.md)
+- More: [Changelog](CHANGELOG.md), [Import](docs/IMPORT.md), [Security](docs/SECURITY.md), [Handoffs And Stories](docs/HANDOFFS_AND_STORIES.md), [npm Package](docs/NPM.md)
+
+## License
+
+MIT. See `LICENSE.md`.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,75 @@
+# Planr Architecture
+
+Planr V1 is a single Rust binary with explicit module ownership. The crate stays small enough that a Cargo workspace would add more process overhead than value today, and there is only one deployable: the `planr` CLI. The source tree is split by ownership boundary inside that crate instead of using a premature workspace.
+
+## Repository Layout
+
+- `src/`: the Rust CLI (module ownership below).
+- `tests/e2e.rs`: real CLI, MCP, HTTP, import, review-gate, run-log, and concurrent-pick tests.
+- `plugins/planr/`: the installable plugin payload — all nine skills, the worker and reviewer subagent roles, and the per-host plugin manifests.
+- `.agents/plugins/marketplace.json`, `.claude-plugin/marketplace.json`: marketplace manifests pointing Codex and Claude Code at `plugins/planr`.
+- `docs/`: user and contributor guides; `docs/planr-spec/` is the production specification package for Planr V1.
+- `examples/real-world-flow.md`: executable real-world operator flow.
+- `scripts/`: installer and release packaging scripts.
+- `npm/`: the npm wrapper package.
+
+## Module Ownership
+
+- `src/main.rs`: process composition root. Owns top-level module wiring, process startup, database opening, error printing, and dispatch into `App`.
+- `src/cli.rs`: CLI contract boundary. Owns `clap` command definitions, option parsing types, value enums, and command DTOs used by app dispatch.
+- `src/app/mod.rs`: application composition boundary. Owns the `App` runtime state, top-level dispatch, shared app-local row helpers, and app submodule wiring.
+- `src/app/commands.rs`: CLI use-case orchestration. Owns project, plan, map, item, link, pick, approval, log, close, review, context, search, doctor, and install command handlers.
+- `src/app/flow.rs`: compound work-flow boundary. Owns evidence log writing (with heartbeat folding), the close transition core, review-request creation, the pick work packet, and the `done` command that chains them for CLI, HTTP, and MCP surfaces.
+- `src/app/git_review.rs`: Git and PR review evidence boundary. Owns worktree detection, scoped changed-file provenance, PR URL context, and dirty-worktree safety projections.
+- `src/app/mcp.rs`: MCP stdio boundary. Owns MCP protocol request routing, tool calls, resource reads, and prompt responses.
+- `src/app/packages.rs`: package import/export boundary. Owns reusable JSON templates, preview-before-import, review artifact package import, and local-first encrypted bundle metadata.
+- `src/app/http.rs`: localhost HTTP/SSE boundary. Owns HTTP request parsing, routes, SSE stream output, and HTTP response mapping.
+- `src/app/repository.rs`: application data access helpers. Owns Planr query/update helpers over projects, plans, graph items, links, runs, logs, artifacts, events, approvals, search, and map projections.
+- `src/app/lease.rs`: worker lease ownership. Owns the single pick query (`PickFilter`: exclude, work type, plan scope), worker ownership checks, runtime heartbeat/progress/pause state, and stale-pick detection.
+- `src/app/review.rs`: review-gate application logic. Owns review annotations, feedback ingestion, evidence artifacts, review closure, and review target lookup.
+- `src/app/recovery.rs`: recovery automation logic. Owns item retry policy configuration, task conditions, stale/timed-out sweeps, retry scheduling, and recovery result projections.
+- `src/app/review_workspace.rs`: local review workspace boundary. Owns the browser review HTML, workspace data projection, and privacy-minimized Git diff evidence.
+- `src/app/surfaces.rs`: non-CLI runtime surfaces. Owns trace, scrub, artifact, event, debug, export, and import command handlers.
+- `src/app/inspection.rs`: local inspection helpers. Owns debug bundles, context/link snapshots, pick context, secret scans, export value assembly, run recording, search results, and Planr-directory import parsing.
+- `src/app/audit.rs`: goal contract audit boundary. Owns the clause-by-clause `plan audit` verdict (items settled, reviews complete, approvals clear, verification logged) and its human rendering.
+- `src/model.rs`: JSON-facing data transfer types. Owns serializable Planr DTOs used by CLI JSON, MCP, HTTP, and tests.
+- `src/storage/mod.rs`: SQLite connection boundary. Owns default database path, connection setup, pragma configuration, and storage submodule exports.
+- `src/storage/schema.rs`: SQLite schema boundary. Owns DDL, additive schema upgrade helpers, and schema version recording.
+- `src/storage/rows.rs`: SQLite row mapping boundary. Owns row-to-DTO and row-to-JSON mapping functions.
+- `src/planpack.rs`: Markdown package generation. Owns project context templates and product/build plan file templates.
+- `src/integrations.rs`: agent-client integration descriptors. Owns Codex, Claude Code, Cursor, and MCP install metadata.
+- `src/util.rs`: small CLI-boundary utilities. Owns ids, timestamps, path helpers, output formatting, and safe file writes.
+
+## Boundary Rules
+
+- Command parsing belongs in `src/cli.rs`; process startup belongs in `src/main.rs`; command execution belongs under `src/app/`.
+- `src/main.rs` must stay small enough to be only a composition root. It must not own product use cases.
+- `src/app/mod.rs` must stay small enough to wire runtime state and dispatch. It must not absorb app submodule behavior.
+- SQLite schema belongs in `src/storage/schema.rs`; row mapping belongs in `src/storage/rows.rs`; app data access helpers belong in `src/app/repository.rs`.
+- Markdown templates belong in `planpack.rs`; command handlers should request generated file sets instead of embedding large template bodies.
+- Agent install metadata belongs in `integrations.rs`; client-specific strings should not drift across command handlers and docs.
+- DTO changes belong in `model.rs`; JSON response shapes should reuse those DTOs before adding ad hoc maps.
+- Utility code must stay narrow. If a helper starts owning product behavior, move it to the owning module instead of growing `util.rs`.
+- Do not add catch-all `common`, `shared`, or broad utility modules. New modules must name a durable ownership boundary.
+
+## Single-Crate Decision
+
+Planr remains a single crate for V1 because:
+
+- there is one deployable binary and no separate service or reusable library boundary;
+- the current behavior contract is tighter when CLI, MCP, HTTP, storage, and docs ship together;
+- module-level ownership now gives the needed architecture separation without duplicating Cargo settings or release packaging;
+- npm, release, and external consumer tests assume one native binary named `planr`.
+
+A Cargo workspace should be introduced only after a concrete deployable, reuse, compilation, or team ownership boundary exists and package/release scripts are updated in the same change.
+
+## Future Extract Points
+
+If Planr grows past the V1 binary shape, the first clean extraction path is:
+
+- `planr-core`: `model.rs`, graph invariants, plan package contracts, and pure use-case types.
+- `planr-storage`: `src/storage/*`, storage repositories, schema upgrades, and import/export packages.
+- `planr-cli`: `src/cli.rs`, human output, and install helpers.
+- `planr-server`: `src/app/http.rs`, `src/app/mcp.rs`, and runtime server adapters.
+
+Do not extract those crates until a real reuse, compile-time, or ownership boundary exists.

package/docs/CI.md

@@ -0,0 +1,54 @@
+# CI
+
+Planr CI is defined in `.github/workflows/ci.yml` and `.github/workflows/security.yml`.
+
+## Required Gates
+
+The main CI workflow runs:
+
+```bash
+cargo fmt --check
+cargo clippy --all-targets -- -D warnings
+cargo test
+shellcheck scripts/*.sh
+cargo build --release
+npm pack --dry-run
+node npm/bin/planr.js --version
+cargo audit --deny warnings
+```
+
+The security workflow runs a GitHub Actions security scan with pinned `zizmor`.
+
+## Local Reproduction
+
+Run the full local gate:
+
+```bash
+scripts/ci-local.sh
+```
+
+`scripts/ci-local.sh` also runs the external consumer E2E project when `/Users/kregenrek/projects/planr-test` exists:
+
+```bash
+cd /Users/kregenrek/projects/planr-test
+npm test
+npm run test:npm-planr
+```
+
+Run local security and leak checks:
+
+```bash
+scripts/security-local.sh
+```
+
+This uses BetterLeaks for secret history scanning and Trivy for filesystem vulnerability, secret, and misconfiguration scanning.
+
+## Supply Chain
+
+Dependabot is configured in `.github/dependabot.yml` for:
+
+- Cargo dependencies
+- npm dependencies
+- GitHub Actions
+
+GitHub Actions use read-only default permissions and pin checkout by commit SHA.

package/docs/CLAUDE_CODE.md

@@ -0,0 +1,33 @@
+# Claude Code Integration
+
+## Plugin (preferred for skills)
+
+The Planr repository is a Claude Code plugin. Install it to get the skills (namespaced as `/planr:planr`, `/planr:planr-loop`, ...) plus the `planr-worker` and `planr-reviewer` subagents:
+
+```text
+/plugin marketplace add instructa/planr
+/plugin install planr@planr
+```
+
+See [Skills](SKILLS.md) for the skill workflow. For autonomous goal runs with `/goal` or `/loop` on top of Planr state, see [Long-Running Goals](GOALS.md).
+
+## MCP
+
+```bash
+planr install claude --dry-run
+planr install claude
+planr doctor --client claude
+```
+
+Dry-run prints both project-scope `.mcp.json` content and the user-scope CLI form. The non-dry command writes only this repository's `.mcp.json`.
+
+Claude Code should treat Planr map state as authoritative and use Markdown plans as context.
+
+For repo-local review feedback, write JSON to a file and ingest it:
+
+```bash
+planr review ingest <item-id> --from .planr/tmp/claude-review.json
+planr review artifact <review-item-id>
+```
+
+Planr does not install shell hooks or edit global Claude Code configuration. The review item remains open until `planr review close` records the final verdict.

package/docs/CLI_REFERENCE.md

@@ -0,0 +1,126 @@
+# CLI Reference
+
+Generated from `planr --help` shape for V1.
+
+```text
+planr project init [--client codex|claude|cursor|all] [--force] [name]
+planr project show [--json]
+planr project list [--json]
+planr plan new "App idea" [--platform web] [--ai] [--backend]
+planr plan refine <plan-id> [--note "..."]
+planr plan split <plan-id> --slice "MVP backend"
+planr plan check <plan-id>
+planr plan audit <plan-id>
+planr plan show <plan-id>
+planr plan archive <plan-id>
+planr map show
+planr map build --from <plan-id>
+planr map lane --critical
+planr map pressure
+planr map status
+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" --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]
+planr link add <from-item> <to-item> --type blocks
+planr pick
+planr pick release <item-id> [--force]
+planr pick heartbeat [item-id]
+planr pick progress <item-id> --percent 0..100 [--note "..."]
+planr pick pause <item-id> [--note "..."]
+planr pick resume <item-id>
+planr pick stale [--older-than-seconds 900] [--release]
+planr recover sweep [--older-than-seconds 900] [--apply]
+planr approval request <item-id> [--reason "..."]
+planr approval approve <item-id> --by "name" [--comment "..."]
+planr approval deny <item-id> --by "name" [--comment "..."]
+planr approval list [--open]
+planr artifact add "name"|--name "name" [--item <item-id>] [--kind evidence] [--path file] [--content "..."] [--mime text/plain]
+planr artifact show <artifact-id>
+planr artifact list [--item <item-id>]
+planr event list [--item <item-id>] [--limit 50]
+planr debug bundle [--item <item-id>] --preview
+planr log add --item <item-id> --summary "..." [--files a --files b | --files a,b] [--cmd "..."] [--kind completion|progress|verification]
+planr review request <item-id>
+planr review annotate <item-id> --message "..." [--severity info|warning|blocking] [--file path] [--line N] [--author "..."]
+planr review ingest <item-id> (--from feedback.json|--stdin)
+planr review artifact <review-item-id> [--out .planr/reviews/custom.review.md]
+planr review evidence <item-id> [--pr-url https://...]
+planr review close <review-item-id> --verdict complete|not-complete|unclear [--close-target]
+planr close [item-id] --summary "..." [--next]
+planr done [item-id] --summary "..." [--files a --files b] [--cmd "..."] [--tests "..."] [--review] [--next]
+planr context add "text" [--item <item-id>] [--tag discovery]
+planr search "query"
+planr doctor [--client codex|claude|cursor|all]
+planr install codex|claude|cursor [--dry-run]
+planr prompt cli|mcp|http [--client codex|claude|cursor|all]
+planr mcp
+planr serve --port 7526
+planr import <file> [--preview] [--confirm]
+planr export --out planr.json [--include-plans] [--include-logs] [--template-name "..."] [--tag tag]
+```
+
+Global flags: `--db <path>`, `--json`, `--no-color`. They are valid in both positions: `planr --json pick` and `planr pick --json` behave identically.
+
+## JSON Envelope Convention
+
+With `--json`, responses follow one convention so agents never guess where data lives:
+
+- Errors: `{"error": {"code": "...", "message": "..."}}` with a non-zero exit code. Codes include `not_found`, `invalid_transition`, `already_closed`, `bad_request`, `locked`, `parse_error`, and `internal_error`. `invalid_transition` messages carry the exact repair command for the current state (e.g. which review to close, which approval to resolve, or that blockers must settle first) — the error is the instruction.
+- List fields on logs (`files`, `commands`, `tests`, `review_findings`) are always arrays — `[]` when empty, never `null`.
+- The affected single item is always available under the top-level `item` key (`pick`, `close`, `item create/update/cancel`, `pick release`, `item breakdown`, approval and runtime commands). Action-specific keys like `closed`, `cancelled`, or `released` carry the id and stay for context.
+- Collections use plural keys: `items`, `plans`, `logs`, `reviews`, `artifacts`, `approvals`, `events`.
+- Other single objects use their semantic key: `plan`, `log`, `review`, `artifact`, `context`.
+- Optional guidance appears under `hint` or `next` when a follow-up command is the expected move.
+
+`plan check` validates path, YAML frontmatter, and that required sections have content: build plans need `## Scope Decision`, `## Verification`, and `## Acceptance Criteria` filled; product plans need `## Problem`, `## Requirements`, and `## Success Criteria` filled in `PRODUCT_SPEC.md`. Each warning is structured — `{"file", "section", "message", "fix"}` — and names the exact file to edit plus the re-run command, so a failed check is a repair instruction, not a riddle.
+
+`plan audit <plan-id>` is the one-call contract verdict for a plan's map scope. It evaluates four clauses with evidence: `items_settled` (open items listed), `reviews_complete` (open review items listed), `approvals_clear` (requested/denied approvals listed), and `verification_logged` (logs with `--kind verification` on scope items). The stored goal contract (`planr context --tag goal-contract` mentioning the plan id) is included; the verification clause is binding only when such a contract exists. `holds: true` means the contract is satisfied — loop agents use this as their stop condition instead of stitching the verdict together from `map status`, `log list`, and `approval list`. Also available as MCP `planr_plan_audit`.
+
+`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
+{
+  "reviewer": "local-reviewer",
+  "verdict": "not-complete",
+  "findings": ["Add the missing failing-path test"],
+  "annotations": [
+    {
+      "message": "The close path needs regression coverage",
+      "severity": "blocking",
+      "file": "tests/e2e.rs",
+      "line": 42
+    }
+  ]
+}
+```
+
+`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 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.
+
+`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`). 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`, `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.
+
+`recover sweep` previews by default. With `--apply`, timed-out picked work that has a retry budget (`max_retries > 0`) is marked `failed` with an `item_timed_out` event; stale work and timeouts without a retry budget are released back to `ready`. Failed work re-enters `ready` once its retry delay has elapsed (`retry_delay_ms`, doubled per retry under `exponential` backoff) until the budget is exhausted. Every transition records a recovery event. Item pre/post conditions are visible in pick context, trace output, and close previews; post conditions are reported as manual verification gates instead of being guessed automatically.
+
+`serve` exposes the local review workspace at `/review` and its JSON projection at `/v1/review-workspace`.
+
+`prompt` prints ready-to-use agent instructions without editing global config. Use `prompt cli` for shell agents, `prompt mcp` for MCP setup text, and `prompt http` for localhost automation/review workspace usage.
+
+`export` writes a reusable Planr JSON package with package requirements metadata, graph state, contexts, optional logs, optional plan file snapshots, and review artifact snapshots. `import` previews JSON packages by default and mutates only with `--confirm`.

package/docs/CODEX.md

@@ -0,0 +1,48 @@
+# Codex Integration
+
+## Plugin (preferred for skills)
+
+The Planr repository is a Codex plugin. Install it to get the `$planr`, `$planr-loop`, and stage skills without copying folders:
+
+```bash
+codex plugin marketplace add instructa/planr
+codex plugin add planr@planr
+```
+
+See [Skills](SKILLS.md) for the skill workflow and subagent role templates.
+
+## Long-Running Goals With `/goal`
+
+Codex `/goal` is the recommended orchestrator for autonomous Planr runs: `/goal` supplies continuation pressure, Planr supplies durable state, evidence, reviews, and recovery. Prep once with `$planr-goal`, then start:
+
+```text
+$planr-goal <your goal>
+/goal Use $planr-loop on plan <plan-id>. The loop contract is stored in planr context (tag: goal-contract). Continue until the contract holds or the iteration budget is exhausted.
+```
+
+The stop condition lives in Planr (`--tag goal-contract`), so a dead session resumes with the same starter line from zero chat context. Full workflow, recovery, and per-host variants: [Long-Running Goals](GOALS.md).
+
+## MCP
+
+```bash
+planr install codex --dry-run
+planr doctor --client codex
+```
+
+The dry-run prints the MCP server snippet for `planr mcp`. Verify the client-side registration with the Codex CLI command shown by your local Codex installation.
+
+Codex should use the same public flow as every other client:
+
+```text
+map -> pick -> work -> log -> review -> close
+```
+
+Review hooks can feed Planr without changing global Codex settings:
+
+```bash
+codex review --json > .planr/tmp/codex-review.json
+planr review ingest <item-id> --from .planr/tmp/codex-review.json
+planr review annotate <item-id> --message "Needs regression coverage" --severity blocking
+```
+
+Ingested feedback is evidence only. A reviewer or agent must still close the review item explicitly with `planr review close`.

package/docs/CURSOR.md

@@ -0,0 +1,30 @@
+# Cursor Integration
+
+## Plugin
+
+The repository carries a Cursor plugin manifest (`.cursor-plugin/plugin.json`) bundling the Planr skills. Marketplace listing is pending review; until it is listed, use MCP plus the CLI prompt below. See [Skills](SKILLS.md) for the skill workflow and [Long-Running Goals](GOALS.md) for running goal loops without a native `/goal` primitive.
+
+## MCP
+
+```bash
+planr install cursor --dry-run
+planr install cursor
+planr doctor --client cursor
+```
+
+Dry-run prints `.cursor/mcp.json` content. The non-dry command writes the project-scoped config.
+
+Planr V1 defaults to MCP stdio. Local HTTP/SSE is available through:
+
+```bash
+planr serve --port 7526
+```
+
+Cursor tasks can attach review feedback through either MCP stdio or the local HTTP API:
+
+```bash
+planr review annotate <item-id> --message "Cursor review note" --severity warning
+planr review ingest <item-id> --from .planr/tmp/cursor-review.json
+```
+
+The project-scoped `.cursor/mcp.json` is the only file written by `planr install cursor`. Review ingestion does not auto-close or auto-approve work.