planr 1.6.0 → 1.7.1

package/docs/INSTALL.md

@@ -1,115 +0,0 @@
-# Install Planr
-
-## Recommended User Install
-
-Planr's canonical release source is:
-
-- https://github.com/instructa/planr/releases
-
-Install the current GitHub Release with the repo-owned installer:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/instructa/planr/main/scripts/install.sh | sh
-planr --version
-planr doctor --client all
-```
-
-The installer downloads `planr-<os>-<arch>.tar.gz` from the latest GitHub Release. Override the release source with:
-
-```bash
-PLANR_DOWNLOAD=1 PLANR_VERSION=v1.0.0 sh scripts/install.sh
-PLANR_DOWNLOAD=1 PLANR_REPO=your-org/planr PLANR_VERSION=v1.0.0 sh scripts/install.sh
-PLANR_DOWNLOAD=1 PLANR_TARGET=darwin-arm64 sh scripts/install.sh
-PLANR_DOWNLOAD=1 PLANR_RELEASE_BASE_URL=https://example.com/releases sh scripts/install.sh
-```
-
-Download installs verify `SHA256SUMS` from the same release location by default. Use `PLANR_SKIP_CHECKSUM=1` only for local development mirrors where the checksum file is intentionally unavailable.
-
-## Homebrew Tap
-
-Homebrew is the preferred day-to-day package-manager path:
-
-```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
-
-Download the matching asset from GitHub Releases:
-
-```bash
-tar -xzf planr-darwin-arm64.tar.gz
-PREFIX="$HOME/.local" PLANR_BIN="$PWD/planr" scripts/install.sh
-planr --version
-```
-
-Windows native release assets are not part of the current public install contract. Windows users should use WSL with the Linux release asset or build from source until a Windows asset is published.
-
-## Client Setup
-
-Planr does not edit global agent configuration during install. From a project, use:
-
-```bash
-planr doctor --client all
-planr install codex --dry-run
-planr install claude --dry-run
-planr install cursor --dry-run
-planr prompt mcp
-planr prompt cli --client codex
-planr prompt http
-```
-
-`planr install codex` writes a project MCP snippet and project hooks; its workflow skills come from the Codex plugin, and it writes no project roles or skills. `planr install claude` writes project `.mcp.json`, standalone worker/reviewer roles, and hooks; workflow skills come from the Claude Code plugin. `planr install cursor` writes project MCP, roles, all ten skills, and hooks, then prints an optional user-level MCP deeplink. Optional model pins come from repository-local routing declarations managed outside Planr. Dry-runs print the complete repository artifact and hook-reconciliation paths without writing them; no command silently edits global user configuration.
-
-`--no-mcp` skips only the project MCP artifact. Codex then reconciles hooks only; Claude Code writes standalone project roles and hooks but no project skills; Cursor writes project roles, skills, and hooks. Add `--no-hooks` to skip hooks as well. The Codex and Claude Code plugins remain the owners of their workflow skills.
-
-Runtime surfaces:
-
-```bash
-planr mcp                # stdio MCP server for any MCP-capable client
-planr serve --port 7526  # localhost HTTP/SSE
-```
-
-Open `http://127.0.0.1:7526/review` after `planr serve` for the local browser review workspace.
-
-## Agent Skills And Plugin
-
-The repository ships a plugin under `plugins/planr` for Codex and Claude Code that bundles all ten workflow skills; Claude Code additionally registers plugin worker/reviewer agents. The Codex plugin does not register project agents. Cursor receives the ten skills and both project agents through `planr install cursor` (or its plugin manifest). Model-specific role files are optional repository-local artifacts owned by external routing lifecycle. The CLI above must be installed separately. See [Skills](SKILLS.md).
-
-## From Source
-
-Use Cargo when developing Planr or building from a checked-out source tree:
-
-```bash
-cargo build --release
-PREFIX="$HOME/.local" scripts/install.sh
-planr --version
-planr doctor --client all
-```
-
-The install script copies the selected binary to `PREFIX/bin/planr`. It is idempotent and does not edit global shell or agent-client configuration.
-
-During development, run any command directly without installing: `cargo run -- <command>` (for example `cargo run -- map show`).
-
-## Release Artifact
-
-```bash
-scripts/build-release.sh
-cat dist/planr-*/SHA256SUMS
-cat dist/SHA256SUMS
-```
-
-Release builds include a local artifact directory plus a platform tarball named `planr-<os>-<arch>.tar.gz`.

package/docs/MCP_CONTRACT.md

@@ -1,73 +0,0 @@
-# MCP Contract
-
-Planr exposes a local stdio MCP server with a stable V1 contract for coding-agent clients.
-
-## Server
-
-```bash
-planr --db .planr/planr.sqlite mcp
-```
-
-The server supports:
-
-- `tools/list`
-- `tools/call`
-- `resources/list`
-- `resources/read`
-- `prompts/list`
-- `prompts/get`
-
-## Machine-Checkable Fixture
-
-The canonical fixture is:
-
-```text
-docs/fixtures/mcp-contract.json
-```
-
-Tests compare this fixture against live MCP stdio responses, install dry-run output, and CLI reference coverage.
-
-## Tool Contract
-
-Every tool declares a real JSON Schema: typed `properties`, explicit `required` fields, and `additionalProperties = false`. The only exception is `planr_review_ingest`, which keeps `additionalProperties = true` so arbitrary hook payload shapes can be ingested. Unknown tools return an `isError` MCP result containing a JSON error with code `not_found`.
-
-Required groups:
-
-- project and map reads
-- plan creation, refinement, split, check, and link
-- map build, preview, unlocks, lookahead, and pressure-oriented reads
-- item create, breakdown, insert, amend, and replan
-- pick, heartbeat, progress, pause, resume, stale inspection, and recovery sweep
-- approval request, approve, deny, and list
-- artifact add, list, and show
-- event list and debug bundle preview
-- trace item, log add, and log read (including three-stage route observations)
-- provider-neutral agent registry reads and route overrides
-- review annotate, ingest, artifact, evidence, and close
-- item close, context create, and search
-
-`planr_recover_sweep` mirrors `planr recover sweep`: it previews by default and only mutates state when `apply` is true. It returns stale picked work, timed-out work, retryable failed work, exhausted failures, and applied release/retry counts.
-
-## Review Contract
-
-Review feedback ingestion is advisory:
-
-- `planr_review_annotate` stores item-linked annotation context.
-- `planr_review_ingest` stores hook-compatible feedback and never auto-closes or auto-approves work.
-- `planr_review_artifact` writes a privacy-minimized review artifact.
-- `planr_review_evidence` returns Git/PR evidence scoped to files named by item logs or artifacts, and treats unrelated dirty files as non-owned.
-- `planr_review_close` records the final verdict, writes a review artifact, and creates fix/follow-up review work when the verdict is not clean.
-
-HTTP mirrors the same rule: `GET /v1/reviews/:id/artifact` is read-only; `POST /v1/reviews/:id/artifact` writes an artifact explicitly.
-
-## Install Contract
-
-`planr install <client> --dry-run` prints the complete client-owned MCP, role, skill, and hook-reconciliation paths for Codex, Claude Code, and Cursor without writing them. Non-dry install writes only repository-local files, with this ownership contract:
-
-- Codex: the CLI writes `.planr/integrations/codex-mcp.toml` and `.codex/hooks.json`; the plugin owns all ten workflow skills; neither path writes Planr project roles or project skills
-- Claude Code: the CLI writes `.mcp.json`, standalone `.claude/agents/` roles, and `.claude/settings.json` hooks, but no project skills; the plugin owns all ten workflow skills and its plugin agents
-- Cursor: the CLI writes `.cursor/mcp.json`, both `.cursor/agents/` roles, all ten `.cursor/skills/` skill copies, and `.cursor/hooks.json`
-
-The Cursor dry-run additionally prints a `cursor://anysphere.cursor-deeplink/mcp/install` link whose embedded config (`planr mcp`, no `--db`) is safe at user scope because each workspace resolves its own database. Planr does not edit global client configuration without a separate explicit operator action; the deeplink requires the operator to click it and confirm inside Cursor.
-
-`--no-mcp` skips only the project MCP artifact: Codex reconciles hooks only; Claude Code writes standalone roles and hooks but no project skills; Cursor writes roles, all ten skills, and hooks. `--no-hooks` is the independent hook opt-out and can be combined with `--no-mcp`.

package/docs/MCP_GUIDE.md

@@ -1,40 +0,0 @@
-# MCP Guide
-
-Planr exposes one stdio MCP server:
-
-```bash
-planr mcp
-```
-
-Core tools include project/map reads, map status/preview/unlocks/lookahead, plan creation/refinement/splitting, map build, item create/breakdown/insert/amend/replan, pick, runtime heartbeat/progress/pause/resume/stale inspection, recovery sweep, approval request/approve/deny/list, artifact add/list/show, event list, debug bundle preview, log, review annotate/ingest/artifact/evidence/close, close, context create, search, and log read.
-
-Review feedback tools:
-
-- `planr_review_annotate`: add item-linked review feedback with severity, optional file, line, and author.
-- `planr_review_ingest`: ingest hook-compatible JSON feedback without auto-closing or auto-approving work.
-- `planr_review_artifact`: write a privacy-minimized `.planr/reviews/*.review.md` artifact.
-- `planr_review_evidence`: return scoped Git/PR review evidence without source contents.
-- `planr_review_close`: close a review item, write a review artifact, and create fix/follow-up review work when the verdict is not clean.
-
-Resources:
-
-- `planr://project/map`
-- `planr://project/context`
-- `planr://item/{id}`
-- `planr://plan/{id}`
-- `planr://log/{id}`
-
-Prompts:
-
-- `planr-plan`
-- `planr-work`
-- `planr-review`
-- `planr-map`
-- `planr-summary`
-
-Use `planr install <client> --dry-run` to print project-scoped config.
-
-The stable V1 contract and checked fixture live in:
-
-- `docs/MCP_CONTRACT.md`
-- `docs/fixtures/mcp-contract.json`

package/docs/MODEL_ROUTING.md

@@ -1,33 +0,0 @@
-# Model routing
-
-Planr Core treats routing as optional, advisory repository data. `.planr/agents.toml` declares opaque profiles and routes; Planr resolves them into pick packets but never calls a provider or claims that a requested model actually ran.
-
-```toml
-[profiles.worker]
-client = "host-a"
-model = "model-id"
-agent_type = "repository-role"
-effort = "high"
-skill = "planr-work"
-
-[[routes]]
-match = { work_type = "code" }
-profile = "worker"
-```
-
-Create a neutral scaffold or an explicit registry:
-
-```bash
-planr agents init
-planr agents init --profile worker=host-a/model-id@high#standard --route code=worker
-planr agents check
-planr agents list --json
-```
-
-Resolution order is per-item override, work type, plan, then default route. Unknown profiles fail open to the next applicable route. Host names, model ids, role selectors, effort values, and fallback behavior are opaque to Core.
-
-Workers may report observed routing with logs and route-audit evidence. Requested-only values never become effective proof; missing effective evidence remains explicitly unavailable.
-
-Host-specific model policies, generated repository roles, and uninstall/application lifecycle are external to Planr. [Switchloom](https://switchloom.ai) [v0.2.1](https://github.com/instructa/switchloom/releases/tag/v0.2.1) can manage repository-local routing artifacts from its [repository](https://github.com/instructa/switchloom), [setup quickstart](https://github.com/instructa/switchloom/blob/v0.2.1/README.md#setup-from-the-website), and [repository lifecycle docs](https://github.com/instructa/switchloom/blob/v0.2.1/docs/preset-composition.md#repository-lifecycle-commands), but Planr does not install, invoke, compile, apply, or uninstall Switchloom output. After an external tool or operator changes `.planr/agents.toml` or `.planr/policy.toml`, run `planr agents check` and capture observed route evidence through `planr log add` or `planr done`.
-
-The hard boundary is provider-neutral: Planr consumes declarations and evidence; hosts and external routing tools decide whether any requested model, effort, role, or fallback actually ran. See [External Routing Declarations](ROUTING_BUNDLES.md).

package/docs/NPM.md

@@ -1,40 +0,0 @@
-# npm Package
-
-The npm package name is `planr`. Published versions bundle platform-native binaries under `npm/native/<os>-<arch>/planr`, so installing from npm requires no Rust toolchain:
-
-```bash
-npm install -g planr
-planr --version
-```
-
-Supported platforms: `darwin-arm64`, `darwin-x86_64`, `linux-x86_64`, `linux-arm64`. There is no postinstall script and no network download at install time; the binaries ship inside the tarball and are checksum-verified against the GitHub Release `SHA256SUMS` before publish.
-
-## Publishing
-
-Publishing happens only from the `npm-publish` job in `.github/workflows/release.yml` via npm Trusted Publishing (OIDC, no long-lived token). The job runs when the repository variable `NPM_PUBLISH_ENABLED` is `true` and requires a one-time Trusted Publisher configuration on npmjs.com: package `planr` -> Settings -> Publishing access -> GitHub Actions publisher with repository `instructa/planr` and workflow `release.yml`.
-
-## Binary Resolution
-
-The wrapper looks for a native binary in this order:
-
-1. `PLANR_NATIVE_BIN`;
-2. `npm/native/<os>-<arch>/planr` (published package);
-3. `target/release/planr` then `target/debug/planr` (repository checkout).
-
-## Local Development
-
-The repository checkout contains no `npm/native/` binaries; the wrapper falls back to local cargo builds:
-
-```bash
-cargo build --release
-npm link
-planr --version
-```
-
-For consumer E2E testing:
-
-```bash
-cd ~/projects/planr-test
-npm link ../planr
-npm run test:npm-planr
-```

package/docs/OPERATING_MODEL.md

@@ -1,250 +0,0 @@
-# Planr Operating Model
-
-Planr coordinates coding-agent work through two durable surfaces:
-
-- the Markdown plan package for product, build, architecture, verification, and narrative context;
-- the SQLite map for item state, links, picks, reviews, logs, contexts, and closure.
-
-The map is the source of truth for live state. Markdown explains why the work exists and what good completion means.
-
-## Operator Start
-
-Start every session by reading the current project and graph state:
-
-```bash
-planr project show --json
-planr map show --json
-planr map lane --critical
-planr map pressure
-```
-
-If the repository has no Planr project yet:
-
-```bash
-planr project init "Project Name" --client all
-planr doctor --client all
-```
-
-Use `--db <path>` for isolated runs and tests.
-
-## Canonical Flow
-
-The default product flow is:
-
-```text
-idea -> product plan -> build plan -> map -> pick -> log -> review/evidence -> recovery/package -> close
-```
-
-Use product and build plans for broad scope:
-
-```bash
-planr plan new "App idea" --platform web --ai --backend
-planr plan refine <plan-id> --note "decision or assumption"
-planr plan split <plan-id> --slice "MVP implementation"
-planr plan check <build-plan-id>
-planr map build --from <build-plan-id>
-```
-
-Product-plan task lists are candidates. Work becomes a live commitment only after it is in the map.
-
-## Daily Agent Loop
-
-Agents should work one map item at a time. The short path is:
-
-```bash
-planr pick --json
-planr done <item-id> --summary "what changed" --files a --files b --cmd "exact verification command" --review [--next]
-```
-
-`pick --json` returns one flat work packet (item, links, logs, runtime, recovery, conditions, recall context, `remaining` progress), so no separate `trace item` call is needed. `pick --work-type review` (or `code`) keeps checker and maker leases separate, and a null pick always carries a `reason` plus the `remaining` snapshot. `done` writes the completion log, then requests review (`--review`) or closes directly, and `--next` picks the following item. Evidence logging refreshes the heartbeat, so explicit `pick heartbeat` calls are only needed during long silent stretches.
-
-For longer work, update runtime state instead of relying on chat history:
-
-```bash
-planr pick progress <item-id> --percent 50 --note "implementation done, tests running"
-planr pick pause <item-id> --note "waiting for human decision"
-planr pick resume <item-id>
-```
-
-If a previous worker disappears, inspect stale picks before taking over:
-
-```bash
-planr pick stale --older-than-seconds 900
-planr pick stale --older-than-seconds 900 --release
-planr recover sweep --older-than-seconds 900
-planr recover sweep --older-than-seconds 900 --apply
-```
-
-Use `pick stale --release` for a targeted stale-claim reset. Use `recover sweep --apply` when you also want timed-out work and retryable failed work handled in the same explicit recovery pass.
-
-Record discoveries that future work needs:
-
-```bash
-planr context add "decision or discovery" --item <item-id> --tag discovery
-```
-
-Record completion evidence before asking for review:
-
-```bash
-planr log add --item <item-id> \
-  --summary "what changed" \
-  --files path-a,path-b \
-  --cmd "exact verification command"
-```
-
-Request and close review:
-
-```bash
-planr review request <item-id>
-planr review annotate <item-id> --message "review note" --severity warning
-planr review evidence <item-id> --pr-url https://example.invalid/pr/123
-planr review ingest <item-id> --from .planr/tmp/review-feedback.json
-planr review close <review-id> --verdict complete --close-target
-```
-
-With `--close-target` a complete verdict also closes the reviewed item (it must already carry a completion log); otherwise finish with `planr close <item-id> --summary "Verified with evidence"`.
-
-`review evidence` records Git branch, commit, dirty state, item-scoped changed-file provenance, and optional PR URL context without treating unrelated dirty files as proof. Review ingestion records hook-compatible JSON feedback as contexts and logs only. It does not close the review, approve the item, or unblock downstream work.
-
-For a browser-based local review pass:
-
-```bash
-planr serve --port 7526
-open http://127.0.0.1:7526/review
-```
-
-The review workspace shows review queues, linked plans, item evidence, diff-safe Git evidence, annotations, and approve/request-changes actions over the same local HTTP API.
-
-Use approvals when a human decision must block closure:
-
-```bash
-planr approval request <item-id> --reason "release approval"
-planr approval approve <item-id> --by "human reviewer"
-```
-
-Pending or denied approval blocks `planr close`; use `planr map preview --close <item-id>` to inspect the gate before mutating state.
-
-If review finds issues:
-
-```bash
-planr review close <review-id> \
-  --verdict not-complete \
-  --findings "specific actionable finding"
-planr review artifact <review-id>
-planr map show --json
-planr pick --json
-```
-
-Review findings create follow-up work and write a `.planr/reviews/*.review.md` artifact. Do not mark the original item complete by summarizing the finding away.
-
-## Parent Gate Pattern
-
-Model material changes as parent gates. The parent is not the work package; its linked children are.
-
-```text
-parent gate
-`- implementation or test child
-   `- review item linked to that child
-      |- pass -> child can close -> parent gate auto-closes
-      `- findings -> fix item -> follow-up review -> ...
-```
-
-Rules:
-
-- create one parent item for the change;
-- use `planr item breakdown <parent-id> --into "Implement, Verify"` to create child work under the parent;
-- 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;
-- downstream top-level work should depend on the parent gate, not on the first implementation child.
-
-This keeps later work blocked until review is actually clean.
-
-Parent gates roll up automatically: once every child is closed or cancelled, the gate becomes ready and auto-closes when no review or approval on the gate itself is open (a cancelled or partially closed child rolls up as `closed_partial`). Parent gates are never returned by `planr pick`; the children are the work.
-
-## Notes, Contexts, Logs, And Stories
-
-Use the smallest durable surface that fits the information:
-
-- `planr log add`: proof that work happened, including files, commands, tests, review results, and handoff facts.
-- `planr context add`: a project or item discovery that another future item may need.
-- `planr note add`: a short task-local note when a human or agent needs nearby context.
-- Story logs: longer narrative history when graph state and short contexts are too thin.
-
-Story logs are narrative memory, not status authority. The map remains authoritative for state.
-
-See [HANDOFFS_AND_STORIES.md](HANDOFFS_AND_STORIES.md) for file placement and contents.
-
-## Recovery
-
-After interruption, compaction, or agent handoff:
-
-```bash
-git status --short
-planr project show --json
-planr map show --json
-planr map lane --critical
-planr map pressure
-```
-
-Then inspect the current item:
-
-```bash
-planr trace item <item-id>
-planr log list --item <item-id>
-planr context list --item <item-id>
-```
-
-If ownership must be reset:
-
-```bash
-planr pick stale --older-than-seconds 900
-planr pick release <item-id> --force
-```
-
-Use force only when the prior owner is gone or the operator intentionally resets the claim.
-
-For broad interruption recovery, prefer the explicit sweeper:
-
-```bash
-planr recover sweep --older-than-seconds 900
-planr recover sweep --older-than-seconds 900 --apply
-```
-
-The preview reports stale picks, timed-out work, retryable failures, retry delays, and manual pre/post conditions. The apply mode mutates only the listed recoverable work and records recovery events.
-
-## Packages And Sharing
-
-Use packages for local backups and reusable templates:
-
-```bash
-planr export --include-plans --include-logs --template-name "Backend slice" --tag api --out planr-package.json
-planr import planr-package.json --preview
-planr import planr-package.json --confirm
-```
-
-Import is preview-first. Confirmed import restores graph items, links, contexts, logs, plan file snapshots, and review artifacts into the current project. Encrypted sharing can wrap the JSON package with a local tool such as `age` or `gpg`; Planr does not require a hosted share service.
-
-## Agent Prompts
-
-Use prompt output when configuring agents without editing global config:
-
-```bash
-planr prompt cli --client codex
-planr prompt mcp --client all
-planr prompt http
-```
-
-Prompt commands print ready-to-use setup and operating instructions and report that global config was not edited.
-
-## Completion Rule
-
-Do not call a scope complete until all of these are true:
-
-- required child and review items are closed;
-- log evidence records exact files and commands;
-- verification commands were actually run;
-- review findings are closed or converted into follow-up work;
-- `planr map show --json` has no in-scope blocker;
-- the summary matches the map, logs, and review state.
-
-For release-grade scopes, rerun the full verification ladder in [TESTING.md](TESTING.md).

package/docs/ROUTING_BUNDLES.md

@@ -1,15 +0,0 @@
-# External routing declarations
-
-Planr Core is provider-neutral. It parses `.planr/agents.toml`, resolves routes into pick packets, records declared-versus-observed evidence, and checks `.planr/policy.toml`. It does not own a bundle format, catalog, compiler, signer, installer, or uninstaller.
-
-The current boundary is repository-local declaration plus evidence:
-
-```bash
-planr agents init
-planr agents check
-planr agents list --json
-```
-
-External tools, including Switchloom v0.2.1, may create, update, apply, or uninstall repository-local routing artifacts. Those lifecycle operations happen outside Planr. Planr only consumes the resulting provider-neutral declarations and the route observations workers attach to logs.
-
-Because declarations are advisory, requested model values never become proof by themselves. Strong evidence keeps requested, host-resolved, and effective execution separate in route observations, with `unavailable` used when the host cannot prove what ran.

package/docs/SECURITY.md

@@ -1,8 +0,0 @@
-# Security And Privacy
-
-- Planr is local-first and stores V1 data in the configured SQLite database and `.planr` files.
-- No content telemetry is emitted by default.
-- Shell commands are not run by Planr unless the user explicitly runs them outside Planr or records them as evidence.
-- HTTP binds to `127.0.0.1`.
-- Destructive operations require confirmation or preview flags.
-- Logs, contexts, and inline artifact content are checked by `planr scrub` for common secret-looking patterns. `planr scrub --confirm` rewrites flagged values in place with `[REDACTED]` markers, updates the search index, and records a `secret_scrubbed` event per rewritten row.