planr 1.7.0 → 1.7.1

package/docs/HANDOFFS_AND_STORIES.md

@@ -1,121 +0,0 @@
-# Handoffs And Stories
-
-Planr separates live state from narrative memory.
-
-- Live state belongs in the map.
-- Completion proof belongs in logs.
-- Searchable decisions belong in contexts.
-- Long-form narrative belongs in story logs.
-
-## Handoff Logs
-
-Use `planr log add` whenever another agent, reviewer, or future session must know what happened:
-
-```bash
-planr log add --item <item-id> \
-  --summary "Implemented release dry-run checks" \
-  --files scripts/build-release.sh,docs/RELEASE.md \
-  --cmd "scripts/build-release.sh" \
-  --cmd "cargo test"
-```
-
-A useful handoff log names:
-
-- changed files;
-- commands run;
-- test results;
-- assumptions kept;
-- decisions made;
-- known remaining risk.
-
-Do not paste private source files, secrets, tokens, or full transcripts into logs.
-
-## Context Entries
-
-Use context for durable discoveries:
-
-```bash
-planr context add "Release dry-runs must not edit global agent configuration." --tag constraint
-planr context add "Use project-scoped MCP config for client examples." --tag decision
-```
-
-Prefer context when the fact may influence multiple future items.
-
-## Task Notes
-
-Use notes for local item discussion:
-
-```bash
-planr note add "Reviewer asked for an extra npm pack dry-run before closure." --item <item-id>
-```
-
-Prefer notes when the fact is not project-wide and should stay near one item.
-
-## Story Logs
-
-Use story logs only when map items, contexts, and logs are too thin to preserve the decision chain.
-
-Create a story log for:
-
-- a large architecture or ownership change;
-- a multi-round review/fix sequence;
-- a discovery that invalidates earlier assumptions;
-- a release or schema-upgrade path that future agents must understand;
-- interruption-prone work where the "why" matters as much as the status.
-
-Recommended location for repo-versioned product stories:
-
-```text
-.planr/stories/
-```
-
-Recommended location for private operator-only stories:
-
-```text
-~/.planr/<project>/stories/
-```
-
-Do not create `todo`, `in-progress`, or `finished` story folders. Status belongs to the map.
-
-## Story Template
-
-```markdown
-# <Story Title>
-
-Project: <project name>
-Related items: <item ids>
-Updated: <YYYY-MM-DD>
-
-## Problem
-
-## Current State
-
-## Key Discoveries
-
-## Decisions
-
-## Rejected Alternatives
-
-## Implementation Or Review History
-
-## Verification
-
-## Open Risks
-
-## Next Likely Steps
-```
-
-Keep the story focused on narrative. Do not duplicate the full map.
-
-## Recovery Order
-
-When resuming work:
-
-1. `git status --short`
-2. `planr map show --json`
-3. `planr trace item <item-id>`
-4. `planr log list --item <item-id>`
-5. `planr context list --item <item-id>`
-6. read a relevant story log only if the trace and logs do not explain why the work exists
-
-The story log may explain direction, but it must not override the map.

package/docs/HOOKS.md

@@ -1,34 +0,0 @@
-# Host Hooks
-
-`planr install codex|claude|cursor` wires Planr into the host's native hook system **by default** — skip it with `--no-hooks`. The hooks solve one problem: loop state must survive the moments context is created or destroyed. Every new session and every context compaction gets the map state injected automatically via `planr prime`, so recovery stops being discipline and becomes mechanism.
-
-## What gets installed
-
-| Host | File | Events | Runs |
-| --- | --- | --- | --- |
-| Cursor | `.cursor/hooks.json` | `sessionStart` | `planr prime --cursor-json` |
-| | | `subagentStop` | `.cursor/hooks/planr-evidence-guard.sh` |
-| Claude Code | `.claude/settings.json` | `SessionStart` (matcher `startup\|resume\|compact`) | `planr prime --hook-json` |
-| Codex CLI | `.codex/hooks.json` | `SessionStart` | `planr prime` |
-
-`planr prime` prints one compact, bounded state block (project, map counts, your held items with log status, the goal contract, registry presence, and the next command) — deterministic and read-only. `--hook-json` wraps it in the Claude Code SessionStart envelope (`hookSpecificOutput.additionalContext`); `--cursor-json` emits Cursor's `additional_context` shape.
-
-Only session-start events are wired, deliberately: they are the one place all three hosts inject hook output as context, and Claude's `compact` source plus post-compaction session starts cover the compaction case. Pre/post-compaction events (`preCompact`, `PreCompact`, `PostCompact`) cannot restore model context and are not used.
-
-The evidence guard is advisory and identity-scoped: a Cursor subagent that stops while *its own* pick (matched via `PLANR_WORKER_ID`/`PLANR_SESSION_ID`) has no completion log gets one follow-up message naming the item and the two ways out (`planr done ...` or `planr pick release ...`). Without an explicit worker identity it stays silent rather than steering the wrong agent toward foreign items. It never blocks.
-
-## Design rules
-
-- **Fail open, always.** Every hook command ends in `|| true` with a 10-second timeout; a missing, broken, or uninitialized planr never blocks a session. In a repo without a Planr database, `planr prime` exits silently and creates nothing.
-- **Additive merge, planr owns only its own entries.** Existing hook files keep every foreign entry; planr entries are reconciled on re-install (current ones untouched, outdated ones upgraded in place, entries under retired events removed) — so `planr install <client>` after an update also refreshes the hooks. A file planr cannot parse as a JSON object is left untouched with a note in the install output — add the snippet manually in that case.
-- **Default, not mandatory.** `--no-hooks` skips hook installation entirely; deleting the planr entries from the hook files removes the behavior with no other effect.
-
-## Codex trust model
-
-Codex requires reviewing hooks before they run: after installing, open `/hooks` in the Codex TUI once and trust the planr entries. Codex records trust against the hook definition's hash, so if a future planr version changes the hook commands, Codex will ask again — that is the host working as intended.
-
-## Removing hooks
-
-Delete the planr entries from `.cursor/hooks.json` / `.claude/settings.json` / `.codex/hooks.json` (and `.cursor/hooks/planr-evidence-guard.sh`). Nothing else depends on them.
-
-See also: [Model Routing](MODEL_ROUTING.md), [Goals](GOALS.md), [CLI Reference](CLI_REFERENCE.md).

package/docs/IMPORT.md

@@ -1,23 +0,0 @@
-# Planr Packages
-
-```bash
-planr project init "New Project"
-planr export --include-plans --include-logs --template-name "API backend slice" --tag api --out planr-package.json
-planr import planr-package.json --preview
-planr import planr-package.json --confirm
-```
-
-Planr packages are local-first JSON files created by `planr export`. They carry graph items, links, contexts, optional logs, optional eval evidence refs, optional plan file snapshots, and review artifacts.
-
-Imports are preview-first. Preview reports package metadata, create counts, and conflicting item ids before mutating the current project.
-
-Eval evidence exports only when logs are included. Packages carry immutable eval suite snapshots, runs, case results, raw samples, comparisons, invalidations, and evidence refs so imported refs resolve to local eval records and comparison verdicts can be reproduced from restored run evidence. Import preflights the whole eval graph before inserting package rows: duplicate immutable ids inside the package must be byte/field-identical, suite/run/comparison/invalidation/ref dependencies must resolve, case sample ids must match nested samples, and eval refs must have `closure_authority: false`. Existing immutable eval ids are accepted only when their stored content exactly matches the package, and imported eval timestamps/provenance are preserved. Review refs must point at a real `work_type=review` item linked to the claimed item. Restoring audit provenance never closes work or changes map ownership.
-
-Planr packages are local-first JSON. For encrypted sharing, review the JSON locally and encrypt the file with your team's standard tool, for example:
-
-```bash
-age -o planr-backup.json.age -r <recipient> planr-backup.json
-gpg -c planr-backup.json
-```
-
-Planr does not require a hosted share service for V1.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,78 +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
-- eval suite check, run, show, compare, gate, invalidate, rescore, and evidence refs
-- 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.
-
-## Eval Evidence Contract
-
-`planr_eval_evidence_ref` mirrors `planr eval evidence-ref`: it attaches an eval run or comparison id to an existing log, review item, or artifact. The returned eval envelope records `closure_authority: false`; eval verdicts are audit evidence only and never close, approve, or otherwise mutate map item status.
-
-## 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
-```