planr 1.7.0 → 1.7.1

package/docs/CLI_REFERENCE.md

@@ -1,170 +0,0 @@
-# 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 [--plan <plan-id>] [--view tree|diagram] [--full]
-planr map watch [--plan <plan-id>] [--view tree|diagram] [--full] [--interval-ms 1000] [--no-clear] [--until-settled]
-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 item update <item-id> [--title "..."] [--description "..."] [--work-type <type>]
-# plan task lists can declare work types inline: `### TASK-001 (backend): ...` / `- [ ] (frontend) ...` seed map build directly
-planr item route <item-id> [--set <profile>|--clear]
-planr link add <from-item> <to-item> --type blocks
-planr prime [--hook-json]
-planr pick [--work-type <type>] [--plan <plan-id>] [--peek]
-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]
-# --kind is free-form vocabulary; common values: evidence, screenshot, video, recording, report, review
-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 trace item <item-id>
-planr log add --item <item-id> --summary "..." [--files a --files b | --files a,b] [--cmd "..."] [--kind completion|progress|verification] [--profile <id>] [--route-audit <observation.json>]
-# machine consumers: --cmd writes the `commands` field in log JSON; --tests writes `tests`
-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 eval suite-check --input suite.json
-planr eval run --input run.json
-planr eval show suite|run|comparison|invalidation <id>
-planr eval compare <baseline-run-id> <candidate-run-id> [--policy-digest default]
-planr eval gate <comparison-id>
-planr eval invalidate run|comparison <target-id> --reason "..." [--reason-code code] [--replacement-hint "..."]
-planr eval rescore <run-id> [--id <new-run-id>]
-planr eval evidence-ref run|comparison <target-id> log|review|artifact <attachment-id> --item <item-id>
-planr close [item-id] --summary "..." [--next]
-planr done [item-id] --summary "..." [--files a --files b] [--cmd "..."] [--tests "..."] [--review] [--next] [--profile <id>]
-planr context add "text" [--item <item-id>] [--tag discovery]
-planr context list [--item <item-id>] [--tag <tag>]
-planr search "query"
-planr agents init [--force]
-planr agents init --profile|--skill|--route|--default-route|--interactive
-planr agents list [--json]
-planr agents check
-planr doctor [--client codex|claude|cursor|all]
-planr install codex|claude|cursor [--dry-run] [--no-mcp] [--force] [--no-hooks]
-planr prompt cli|mcp|http [--client codex|claude|cursor|all]
-planr prompt routing [--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. Human map output uses ANSI status colors only when stdout is an interactive terminal. `--no-color`, `NO_COLOR` (even when empty), `TERM=dumb`, redirected stdout, and JSON disable color; `PLANR_FORCE_COLOR=1` is available for compatible terminal wrappers and tests, but never overrides an explicit opt-out.
-
-## 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`. It also flags a task list that still contains only the scaffold placeholder (or no work specs at all) — `map build` would turn that into a single coarse item, so the fix names the granularity contract: one `### TASK-00n:` heading (or `- [ ]` line) per verifiable slice, typically 4-8, in execution order. 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. JSON shape for machine consumers: top-level `holds` (bool) and `clauses[]` with `clause` (name) and `pass` (bool) — e.g. `planr plan audit <id> --json | jq '.holds, (.clauses[] | {clause, pass})'`. 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`. When the contract is open, `next` carries the exact next command derived from the first actionable gap: build the map, pick the ready review or work item (plan-scoped), resolve the blocking approval, inspect stalled leases, or log the missing verification. Also available as MCP `planr_plan_audit`.
-
-`map show` defaults to the compact `tree` view used by agents and existing terminal workflows; coding agents should prefer `map show --json` when they need structured state. The tree keeps the canonical edge vocabulary visible: active dependencies render as red `blocks`, while an edge satisfied by a `closed` or `closed_partial` upstream renders as dim `blocks✓`. `map show --view diagram` is exclusively a human-supervision view and coding agents must not invoke it. It provides fixed-width boxes with at most two content lines in `ICON ITEM-ID → TITLE` form, translating satisfied `blocks` edges to neutral `then` while active or cancelled blockers remain `blocks`; `hands_to`, joins, disconnected components, and cycle warnings remain explicit. Humans can add `--full` for verbose nodes with status words, complete wrapped titles, active workers, critical-lane markers, and downstream pressure. `--full` is rejected with tree view. This is a read-only presentation over the same canonical map projection; JSON/MCP/HTTP always retain the stored `kind: "blocks"` and are identical across diagram detail choices.
-
-`map show --plan <plan-id>` narrows either human view to one plan's items and the links among them, with plan-scoped counts — plan-scoped goal runs on shared boards audit their slice, not the whole board. An unknown plan id is an error, never a silent unscoped view. Also available on MCP `planr_map_show` (`plan`) and HTTP `GET /v1/projects/{id}/map?plan=<plan-id>`.
-
-`map watch` is the read-only live companion for a second human terminal. Coding agents must not invoke it; they should use `map show --json` snapshots or `planr serve` plus `/v1/events/stream`. Watch defaults to the condensed `--view diagram`, polls every 1000 ms, compares the canonical scoped projection, and clears/redraws an interactive terminal only when graph state changes. `--full`, `--view tree`, `--plan <plan-id>`, `--interval-ms <n>` (minimum 100), `--no-clear`, and `--until-settled` control presentation and lifetime; Ctrl-C uses normal process interruption. JSON mode remains rejected because watch is intentionally human-only.
-
-`context list --tag <tag>` filters notes by the tag they were stored with (`context add --tag`), so e.g. the goal contract is recoverable with `planr context list --tag goal-contract` instead of scanning all notes.
-
-`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`. 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. 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.
-
-`eval` exposes the same stored evaluation services to CLI and MCP. Every eval JSON response is one document with the frozen envelope `ok`, `command`, `object`, `warnings`, `reasons`, and `error`; MCP tools return the same envelope inside the text content, including `isError` tool results. `suite-check` reports command `eval.suite.check`, stores or verifies an immutable suite snapshot, `run` starts a run from a JSON envelope and can record cases/samples plus a terminal status, `compare` persists a verdict from two stored runs, and `gate` exits non-zero for `regressed` or `insufficient_evidence` while still printing the verdict, blocker, effects, uncertainty, coverage/freshness gates, and deeper-read commands. Eval exit codes are fixed: `0` for accepted command outcomes, `1` for regression or promotion-gate failure, `2` for insufficient evidence, `3` for invalid or unsafe input, and `4` for infrastructure errors such as missing stored runs. Error objects include `code`, `message`, `reasons`, and `field`. `invalidate` records invalidation evidence for a run or comparison, and `rescore` starts a new run linked back to the source run. `evidence-ref` attaches a run or comparison to an existing log, review item, or artifact for audit/package portability; it is never closure authority and never changes map item status. MCP mirrors these operations as `planr_eval_suite_check`, `planr_eval_run`, `planr_eval_show`, `planr_eval_compare`, `planr_eval_gate`, `planr_eval_invalidate`, `planr_eval_rescore`, and `planr_eval_evidence_ref`. A repository-owned smoke suite lives at `examples/eval/planr-lifecycle-smoke.suite.json`; recalculate fixture digests before using it outside repo-local examples.
-
-`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. When the item has a declared route, a run profile, or a route observation, the trace gains a `routing` section — the declared route next to every run's actual client/profile and, when supplied, its independent requested → resolved → effective model/effort/context-fork stages, transition reason, policy/binding provenance, and per-dimension metering confidence. Unknown effective host values remain `null`/`unavailable`; requested values are never copied forward as proof. MCP `planr_trace_item` returns the identical JSON shape.
-
-`doctor` also reports the agent registry in all states without ever failing: absent (informational hint), degraded (parse error with line context), or loaded with profile/route counts, validation warnings, and per-artifact drift — a rendered role file whose content no longer matches what the current registry would render is flagged `drifted` with a `planr install <client> --force` hint, while files without the generated-from header are the user's (`manual`) and never flagged.
-
-`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.
-
-`prime` prints the compact state block host hooks inject at session start and after context compaction (project, map counts, held items with log status, goal contract, registry presence, next command); `--hook-json` emits the Claude Code SessionStart envelope. In a repo without a Planr database it exits silently and creates nothing — hooks must never break a session. Installs wire it into the host's hook system by default (`--no-hooks` skips; existing hook files are merged additively, never overwritten). Full guide: [Host Hooks](HOOKS.md).
-
-`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 --peek` (MCP: `"peek": true`) returns the same packet for the next pickable item *without* leasing it — no lease, heartbeat, or pick event is written, and the packet carries `"peek": true` with the item still `ready`. Built for dispatching drivers: read the routing block, dispatch the worker, and let the worker take the lease under its own identity — replacing the pick → `pick release --force` → re-pick sequence.
-
-`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.
-
-`policy show` and `policy check` inspect the provider-neutral Usage Policy v1 file (`.planr/policy.toml`). A missing policy is an explicit successful state that preserves existing advisory routing; a malformed or unsafe policy fails `check` with parser/field diagnostics and leaves enforcement unavailable. Usage Policy v1 fixes delegation depth at one and keeps retry, availability fallback, quality escalation, quota downgrade, and safety stop as distinct transition contracts. Its separate `execution` section declares bounded per-role filesystem, network, tool/MCP, structured command, environment, hook, secret-reference, and approval grants. `policy admit <request.json>` requires the picked item's current `item_id` and `pick_token`, authorizes the current worker as lease owner, evaluates a bounded task contract before delegation, previews any permission addition, records the decision and lease generation, rejects unclassified commands and destructive or out-of-scope work, permits overlapping readers, and admits concurrent writers only for disjoint scopes isolated in distinct worktrees. Released or recovered leases never inherit historical admitted scopes. MCP `planr_policy_show`, `planr_policy_check`, and `planr_policy_admit`, plus HTTP `POST /v1/policy/admit`, call the same admission service and return the same decision shape.
-
-`agents init` writes a provider-neutral `.planr/agents.toml` scaffold or compiles explicit profile and route flags. `agents list` and `agents check` inspect it, while pick packets carry the resolved opaque profile, host, model, effort, tier, skill, route chain, and matched selector. Full guide: [Model Routing](MODEL_ROUTING.md).
-
-`log add` and `done` accept `--profile <id>` — the registry profile the run actually executed on (`PLANR_PROFILE` env is the fallback, so rendered role files can export it). They also accept `--route-audit <observation.json>` for the strict three-stage observation contract. A route audit records each stage's model, effort, and context-fork value with enforcement state (`verified`, `requested_only`, `estimated`, or `unavailable`), an evidence-source enum, typed transition plus reason, policy/binding ids and versions, and wall-time/tool/token/credit values with independent confidence. It is stored in run metadata, projected into its durable log and trace, and emits local route-stage/transition events. The profile remains backward compatible: when it differs from the item's declared route, Planr emits advisory `route_mismatch_observed`. Runs without commands/tests record neither a run nor a route observation. MCP `planr_log_add` and HTTP item log accept the same optional `route_observation` object.
-
-`artifact add` infers the mime type from the file extension when `--path` is given without `--mime` (PNG screenshots land as `image/png`, not `text/plain`); inline `--content` defaults to `text/plain`. The same inference applies on MCP `planr_artifact_add` and HTTP `POST /v1/artifacts`.
-
-`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. `prompt routing` emits a paste-ready model-prioritization block for the driver session: the route table from `.planr/agents.toml` (every route, profile, and fallback), native Codex `agent_type` plus explicit fork guidance referring to the generated repository role TOMLs, the Claude `CLAUDE_CODE_SUBAGENT_MODEL` env preemption, Cursor's silent plan/policy/Max-Mode overrides, and process-dispatch snippets (`pi`, `opencode run`) only for hosts without role files. `--json` carries the same content structured, and a missing or unreadable registry still prints the host guidance with a pointer instead of failing.
-
-`export` writes a reusable Planr JSON package with package requirements metadata, graph state, contexts, optional logs, optional plan file snapshots, review artifact snapshots, and — when present — the agent registry (`.planr/agents.toml`) as a raw snapshot. `import` previews JSON packages by default and mutates only with `--confirm`; the preview names the registry with its exact action (`create`, `identical`, or `conflict`), and an existing registry that differs is never overwritten — the conflict is reported with a hint to remove the local file first. Packages without a registry import unchanged.

package/docs/CODEX.md

@@ -1,56 +0,0 @@
-# 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. You are operating autonomously: the user is not watching, so never end a turn on a plan, a question, or a promise — proceed until the contract holds or you are blocked on input only the user can provide.
-```
-
-The stop condition lives in Planr (`--tag goal-contract`), so a dead session resumes with the same starter line from zero chat context.
-
-Optionally prepare repository-local routing declarations before starting the driver. Planr reads `.planr/agents.toml` and `.planr/policy.toml`; external tools such as [Switchloom v0.2.1](https://github.com/instructa/switchloom/releases/tag/v0.2.1) own any generated roles, application, or uninstall lifecycle:
-
-```bash
-planr agents check
-```
-
-Follow any externally generated repository role instructions outside Planr, restart after role changes when your host requires it, and confirm child metadata reports the expected model, effort, role path, and context-fork behavior. Full workflow: [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

@@ -1,114 +0,0 @@
-# Cursor Integration
-
-Cursor is a first-class Planr client. One command wires a project completely — MCP tools, the worker/reviewer subagents, and the full skill set:
-
-```bash
-planr install cursor
-```
-
-This writes only repository-local files (never global Cursor config):
-
-| Path | Purpose |
-| --- | --- |
-| `.cursor/mcp.json` | project-scoped stdio MCP server (`planr mcp`) with the 44 Planr tools |
-| `.cursor/agents/planr-worker.md` | worker subagent: implements exactly one picked item, then requests review and stops |
-| `.cursor/agents/planr-reviewer.md` | reviewer subagent: audits evidence and closes the review with a verdict |
-| `.cursor/skills/planr*/SKILL.md` | all ten Planr skills (`planr`, `planr-goal`, `planr-loop`, stage and capability skills) |
-
-Re-running the command refreshes `.cursor/mcp.json` but never overwrites edited agent or skill files. `planr project init "My Product" --client cursor` (or `--client all`) provisions the same subagent roles at init time. Verify with `planr doctor --client cursor`.
-
-## Skills And Agents Only (No MCP)
-
-The skills are CLI-first — they drive the `planr` binary directly through the terminal — so MCP is optional. To install project subagents, skills, and the default hooks without MCP:
-
-```bash
-planr install cursor --no-mcp
-```
-
-This writes `.cursor/agents/`, `.cursor/skills/`, and the default project hooks, but no `.cursor/mcp.json` or deeplink. Add `--no-hooks` when hooks must also be skipped. Everything below works in this mode because the skills call the Planr CLI directly. `--no-mcp --dry-run` lists the roles and skills and states whether the non-dry run would reconcile hooks. For Claude Code the flag writes standalone project roles and hooks but no project skills; for Codex it writes hooks only. Their workflow skills come from their respective plugins.
-
-## One-Click MCP Install
-
-For user-level setup (all projects, no repo files), the dry-run prints a Cursor deeplink:
-
-```bash
-planr install cursor --dry-run
-```
-
-```text
-cursor://anysphere.cursor-deeplink/mcp/install?name=planr&config=eyJhcmdzIjpbIm1jcCJdLCJjb21tYW5kIjoicGxhbnIifQ==
-```
-
-Open the link (or paste it into a browser) and Cursor prompts to install the server. The embedded config is `{"command": "planr", "args": ["mcp"]}` with no `--db` path on purpose: Cursor starts the server in the workspace directory, so every project resolves its own `.planr/planr.sqlite`.
-
-## Plugin
-
-The repository carries a Cursor plugin manifest (`.cursor-plugin/plugin.json`) bundling the skills and both subagents. Marketplace listing is pending review; until it is listed:
-
-- `planr install cursor` (above) provides the identical component set per project, or
-- install the plugin locally: copy the repository to `~/.cursor/plugins/local/planr` and reload Cursor.
-
-## Multitasking With Cursor's Built-In Features
-
-Cursor's subagents, background execution, and parallel agents map directly onto Planr's maker/checker loop. The Planr map is the shared state, so concurrent Cursor agents coordinate through `planr pick` leases instead of stepping on each other.
-
-### Subagent dispatch (maker/checker)
-
-The installed subagents are dispatched from any Agent chat with `/name` or by mention:
-
-```text
-/planr-worker implement item <item-id>
-/planr-reviewer review item <item-id>
-```
-
-The worker preloads the `planr-work` protocol (implement one item, log evidence, request review, stop); the reviewer preloads `planr-review` (audit the diff, rerun logged commands, close with a verdict). Because each subagent runs in its own context window, the driving chat stays focused on `plan audit`, dispatch decisions, and synthesis — the same division of labor as Codex `/goal` and Claude Code (see [Long-Running Goals](GOALS.md)).
-
-Cost tiering: the worker file ships with `model: inherit`; edit its frontmatter to pin a cheaper Cursor model id when dispatch cost matters. Leave the reviewer on `inherit` — make workers cheap, not the verdict.
-
-### Parallel and background work
-
-- **Parallel subagents:** ask the driver to dispatch several workers at once ("implement items A, B, and C in parallel with planr-worker subagents"). Each worker calls `planr pick` (or is handed its item id); the map's single-owner lease guarantees no two agents hold the same item, and `planr recover sweep` reclaims work from any that die.
-- **Background subagents:** long items can run as background subagents; evidence logging doubles as the liveness heartbeat, so `planr pick stale` shows honestly stuck work.
-- **Cloud agents (`/in-cloud`):** cloud VMs do not share your local `.planr` database or local MCP config. Give cloud agents the CLI workflow instead (`planr prompt cli --client cursor`) and let them commit evidence through normal Planr CLI calls in their own checkout.
-
-### Parallel agents in worktrees
-
-Cursor's parallel agents run in separate git worktrees, and each worktree would otherwise get its own copy of `.planr/planr.sqlite` — forking the map. Keep one authoritative map by pointing every worktree at a shared absolute database path:
-
-```json
-{
-  "mcpServers": {
-    "planr": {"command": "planr", "args": ["--db", "/absolute/path/to/main-checkout/.planr/planr.sqlite", "mcp"]}
-  }
-}
-```
-
-`planr install cursor` already writes the absolute path of the current checkout, so worktrees created from an installed project inherit the right value — verify with `planr project show --json` from each worktree. One picked item per agent instance stays the rule (`plugins/planr/skills/planr-loop/SKILL.md`, Hard Rules).
-
-### Goal loops
-
-Cursor has no `/goal` primitive; the human (or an automation) is the re-dispatcher:
-
-```text
-Use $planr-goal: <your goal>
-Use $planr-loop on plan <plan-id>. The loop contract is stored in planr context (tag: goal-contract).
-```
-
-`$planr-loop` iterates inside the session, dispatching `/planr-worker` and `/planr-reviewer` per item. If the session ends before `planr plan audit <plan-id>` holds, send the same starter line in a fresh session — the map, the stored contract, and open reviews carry the run, not chat history.
-
-## HTTP And Review Feedback
-
-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
-```
-
-Review ingestion does not auto-close or auto-approve work.

package/docs/EXAMPLE_WEBAPP.md

@@ -1,103 +0,0 @@
-# Worked Example: Routing a Small Web App
-
-This provider-neutral example routes a todo web app by work type. Planr Core treats every profile field as opaque data and does not select a host or model.
-
-## 1. Create the project and registry
-
-```bash
-planr project init "Todo Webapp"
-planr agents init
-```
-
-Edit the repository-local `.planr/agents.toml` with profiles owned by your team or routing package:
-
-```toml
-[profiles.frontend-worker]
-client = "your-host"
-model = "your-fast-model"
-effort = "medium"
-cost_tier = "budget"
-skill = "planr-work"
-
-[profiles.backend-worker]
-client = "your-host"
-model = "your-engineering-model"
-effort = "high"
-cost_tier = "standard"
-skill = "planr-work"
-
-[profiles.independent-reviewer]
-client = "your-host"
-model = "your-review-model"
-effort = "high"
-cost_tier = "premium"
-skill = "planr-review"
-
-[[routes]]
-match = { work_type = "frontend" }
-profile = "frontend-worker"
-
-[[routes]]
-match = { work_type = "backend" }
-profile = "backend-worker"
-
-[[routes]]
-match = { work_type = "review" }
-profile = "independent-reviewer"
-```
-
-Validate without contacting a provider:
-
-```bash
-planr agents check
-planr agents list
-```
-
-Alternatively, an external routing tool such as [Switchloom v0.2.1](https://github.com/instructa/switchloom/releases/tag/v0.2.1) can manage repository-local declarations and host roles outside Planr. After that external lifecycle step, Planr still sees only provider-neutral declarations:
-
-```bash
-planr agents check
-planr agents list --json
-```
-
-## 2. Tag items by use case
-
-```bash
-planr item create "API: task CRUD endpoints" \
-  --description "GET/POST/PATCH/DELETE /api/tasks with sqlite store" \
-  --work-type backend
-
-planr item create "UI: task list and add form" \
-  --description "List view and optimistic add form" \
-  --work-type frontend
-```
-
-## 3. Pick and dispatch
-
-```bash
-planr pick --work-type backend --json
-```
-
-The pick packet contains the selected opaque profile, client, model, effort, skill, and selector. The host remains responsible for dispatching it; Planr never claims that the requested model actually ran.
-
-## 4. Close with evidence
-
-```bash
-planr done <item-id> \
-  --summary "CRUD endpoints implemented; 8 tests green" \
-  --files server/routes/tasks.ts \
-  --tests "vitest --run: 8 passed" \
-  --profile backend-worker
-```
-
-`--profile` records the run's claimed profile. For stronger evidence, attach a route observation that keeps requested, host-resolved, and effective values separate.
-
-## 5. Trace declared versus actual
-
-```bash
-planr trace item <item-id>
-```
-
-A mismatch is recorded as advisory evidence instead of silently rewritten. Missing effective-host evidence stays unavailable and is never inferred from the registry.
-
-One-off exceptions use `planr item route <id> --set <profile>`; `--clear` restores policy resolution. See [Model Routing](MODEL_ROUTING.md) and [External Routing Declarations](ROUTING_BUNDLES.md).

package/docs/GOALS.md

@@ -1,175 +0,0 @@
-# Long-Running Goals
-
-Planr makes long-running, autonomous goal runs durable. A loop driver — Codex `/goal`, Claude Code `/goal` or `/loop`, an automation, or a human re-dispatching a skill — supplies continuation pressure: "do not stop until the goal holds." Planr supplies everything such a run loses between sessions: the plan, the task map, picks, evidence logs, review gates, approvals, and recovery.
-
-This is complementary, not competing. `/goal` stays the orchestrator; Planr is the state layer underneath it. Without a native loop primitive you lose only automatic re-prompting — never state, evidence, or recovery.
-
-## Division Of Labor
-
-| Concern | Owner |
-| --- | --- |
-| Continuation pressure, re-prompting, session autonomy | loop driver (`/goal`, automation, human) |
-| Scope, acceptance criteria, verification contract | Planr plan (`planr plan new/check`) |
-| Task state, dependencies, what is next | Planr map (`planr map`, `planr pick`) |
-| Stop condition that survives compaction | Planr context (`--tag goal-contract`) |
-| Proof the work happened and runs | Planr logs (`planr log`, `planr done`) |
-| Maker/checker separation | Planr reviews (`planr review`) + subagent roles |
-| Recovery after session loss or host switch | Planr map + stored contract, from zero chat context |
-
-## The Workflow
-
-### 1. Prep — `$planr-goal` (once, interactive)
-
-```text
-$planr-goal Add CSV export to the reports page, should work in the browser
-```
-
-The skill compiles the goal and stops — no implementation:
-
-- creates and checks a feature-scoped plan (`planr plan new` -> `plan check`; strict, empty sections fail),
-- builds the map and links execution order (`planr map build` is idempotent; `planr link add ... --type blocks`),
-- stores the goal contract durably in Planr:
-
-```bash
-planr context add "GOAL CONTRACT pl-csv-export: DONE when every in-scope map item is closed with log evidence, all reviews closed with verdict complete, no open approvals in scope, and a live browser verification log exists for the export flow. Iteration budget: 10." --tag goal-contract
-```
-
-- prints the exact starter command for your host.
-
-### 2. Execute — the loop driver runs `$planr-loop`
-
-```text
-/goal Use $planr-loop on plan pl-csv-export. The loop contract is stored in planr context (tag: goal-contract). Continue until the contract holds or the iteration budget is exhausted. You are operating autonomously: the user is not watching, so never end a turn on a plan, a question, or a promise — proceed until the contract holds or you are blocked on input only the user can provide.
-```
-
-The autonomy clause matters on long runs: deep into a session, frontier models occasionally end a turn with a statement of intent instead of the corresponding action, or pause to ask permission they already have. Stating the operating mode up front prevents both.
-
-Each iteration follows the `$planr-loop` protocol:
-
-```text
-1. planr plan audit <plan-id>   one-call contract verdict; holds -> exit
-2. $planr-work     pick exactly one ready item, implement, finish with planr done --review
-3. live verify     run the platform verification, log it with planr log add --kind verification --cmd
-4. $planr-review   independent audit; complete -> review close --close-target,
-                   findings -> fix items become the next ready items
-5. repeat
-```
-
-`plan audit` replaces the hand-rolled final audit: it checks `items_settled`, `reviews_complete`, `approvals_clear`, and `verification_logged` clause by clause with evidence, includes the stored goal contract, and answers `holds: true/false` in one command.
-
-The per-item path is three commands since v1.1.6:
-
-```bash
-planr pick --json --plan <plan-id>                           # flat work packet, leased only from the goal's plan
-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 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. 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
-
-When the contract holds, the loop exits through `$planr-summary`: an evidence-backed account of what shipped, which commands proved it, and what (if anything) stayed blocked.
-
-## Recovery
-
-The defining property of a long-running goal: the session will die before the goal does. With Planr that costs nothing. Start a new session — same host or a different one — with the same starter line:
-
-```text
-/goal Use $planr-loop on plan pl-csv-export. The loop contract is stored in planr context (tag: goal-contract).
-```
-
-Iteration 1 reads the map and the stored contract: items already settled stay settled, open reviews stay open, the next ready item is picked. No chat history needed. `planr recover sweep` handles stale picks from interrupted workers.
-
-## Per-Host Setup
-
-### Codex with `/goal`
-
-Install the plugin and initialize the repository. Optional routing declarations are repository-local and may be edited directly or managed by an external tool such as [Switchloom v0.2.1](https://github.com/instructa/switchloom/releases/tag/v0.2.1) before the run:
-
-```bash
-codex plugin marketplace add instructa/planr
-codex plugin add planr@planr
-planr project init "My Product"
-planr agents check
-```
-
-Then:
-
-```text
-$planr-goal <your goal>          # prep: plan, map, contract, starter command
-/goal Use $planr-loop on plan <plan-id>. The loop contract is stored in planr context (tag: goal-contract).
-```
-
-When repository routing declarations exist, the `/goal` PM treats them as advisory dispatch input. The external routing owner decides exact models, effort, role names, fallback policy, and lifecycle; Planr only carries the resulting opaque route in pick packets and records observed evidence when workers provide it. Codex Automations use the same starter line.
-
-### Claude Code
-
-Same shape via the plugin (`/plugin install planr@planr`), which registers the `planr-worker` and `planr-reviewer` subagents automatically:
-
-```text
-/planr:planr-goal <your goal>
-/goal Use $planr-loop on plan <plan-id>. The loop contract is stored in planr context (tag: goal-contract).
-```
-
-`/loop` works for fixed-cadence runs instead of goal-conditioned ones. The registered worker subagent pins a cheaper model tier; see [Cost Tiering](#cost-tiering).
-
-### Cursor
-
-No `/goal` primitive, but full subagent support. Install once:
-
-```bash
-planr install cursor   # writes .cursor/mcp.json, .cursor/agents/planr-worker.md + planr-reviewer.md, and the skills
-```
-
-Then run the identical protocol with the human (or an automation) as the re-dispatcher:
-
-```text
-Use $planr-goal: <your goal>
-Use $planr-loop on plan <plan-id>. The loop contract is stored in planr context (tag: goal-contract).
-```
-
-`$planr-loop` iterates within the session under its own budget, dispatching `/planr-worker` and `/planr-reviewer` per item — the provisioned subagents preload the work and review protocols, so dispatches stay one line. If the session ends before the contract holds, dispatch the same line again — recovery is identical to the `/goal` case. Parallelism, background subagents, and worktree caveats: [Cursor](CURSOR.md).
-
-### Hosts without a loop primitive
-
-Identical protocol; the human (or a background agent) is the re-dispatcher, and worker/reviewer run as separate sequential dispatches when the host has no subagents.
-
-### Plain MCP clients
-
-Any MCP-capable agent uses the same flow over `planr mcp`. Every session starts with map state, so the loop is resumable by construction.
-
-## Cost Tiering
-
-A goal run has distinct roles with different intelligence needs. Planr represents those decisions as opaque profiles and routes; it does not choose providers, models, effort levels, fallback chains, or host-native role names.
-
-An optional external routing tool can map planning, exploration, implementation, mechanical work, and independent review onto different cost or quality tiers. If [Switchloom v0.2.1](https://github.com/instructa/switchloom/releases/tag/v0.2.1) or another repository-local process writes routing declarations or host roles, follow that tool's generated instructions outside Planr and verify effective child metadata because declarations alone are not proof. The Core contract is documented in [Model Routing](MODEL_ROUTING.md).
-
-## Coming From Other Goal Tools
-
-If you already run goal workflows with other tools, the concepts map directly:
-
-| Elsewhere | In Planr |
-| --- | --- |
-| Goal charter file (`goal.md`) | product/build plan (`planr plan new`, rich scope + verification) |
-| Board/state file (`state.yaml`) | the map (`planr map show`, authoritative item state) |
-| One active task | `planr pick` (single owner, heartbeat, stale recovery) |
-| Task receipts | `planr log` / `planr done` (files, commands, results) |
-| Goal oracle / completion proof | goal contract + live verification log |
-| Scout/Judge/Worker roles | worker/reviewer subagents + `$planr-status` for honest reads |
-| Final audit before done | `$planr-review` with `review close --verdict complete` |
-
-Using such tools for intake or visualization alongside Planr is fine — keep one rule: the Planr map stays the single source of truth for item status, links, picks, reviews, approvals, and completion.
-
-## Rules That Keep Goal Runs Honest
-
-- Never weaken a stored goal contract mid-run; scope changes go through `$planr-plan` and the user.
-- "Done" means the feature ran (live verification log), not that it compiles.
-- The maker never closes its own review; single-agent hosts record `review-mode` honestly.
-- Two iterations without map-state movement -> stop and report instead of grinding.
-- Destructive or out-of-repo side effects always go behind `planr approval request`.
-- Lessons that should outlive the iteration (a confirmed approach, a correction, a dead end) go into `planr context add "..." --tag lesson` — the next iteration or a fresh session recovers them with `planr context list --tag lesson`, not from chat history.
-
-See also: [Skills](SKILLS.md), [Operating Model](OPERATING_MODEL.md), [Task Graph Model](TASK_GRAPH_MODEL.md), [Codex](CODEX.md), [Claude Code](CLAUDE_CODE.md), [Cursor](CURSOR.md).