planr 0.0.1 → 1.1.15

package/docs/GOALS.md

@@ -0,0 +1,155 @@
+# 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.
+```
+
+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 reports `reason: "no_ready_item_in_plan"` instead of silently widening.
+
+`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.
+
+### 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`
+
+The recommended combination. Install the plugin and provision the subagent roles once:
+
+```bash
+codex plugin marketplace add instructa/planr
+codex plugin add planr@planr
+planr project init "My Product" --client codex   # writes .codex/agents/planr-worker.toml + planr-reviewer.toml
+```
+
+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).
+```
+
+The `/goal` PM dispatches `spawn the planr_worker agent for item <id>` and `spawn the planr_reviewer agent for item <id>` — the role files preload `$planr-work` and `$planr-review`, so dispatches stay one line. Codex Automations work the same way: set the automation prompt to the 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.
+
+### Cursor and hosts without a loop primitive
+
+Identical protocol; the human (or a background agent) 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 within the session under its own budget. If the session ends before the contract holds, dispatch the same line again — recovery is identical to the `/goal` case.
+
+### 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.
+
+## 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`.
+
+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).

package/docs/HANDOFFS_AND_STORIES.md

@@ -0,0 +1,121 @@
+# 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/IMPORT.md

@@ -0,0 +1,21 @@
+# 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 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.
+
+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

@@ -0,0 +1,98 @@
+# 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 after the tap is published. The expected command is `brew install instructa/tap/planr`.
+
+Until the tap is published, use the GitHub Release installer or manual release asset download.
+
+## 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 claude` writes a project `.mcp.json`; `planr install cursor` writes `.cursor/mcp.json`; `planr install codex` writes a project MCP snippet. All install commands also provision the `planr-worker` and `planr-reviewer` subagent role files (`.codex/agents/`, `.claude/agents/`) without overwriting existing edits; `planr project init --client <client|all>` does the same at init time. Dry-runs print the exact config and scope notes first.
+
+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, Claude Code, and Cursor that bundles the Planr skills (`$planr`, `$planr-loop`, stage and capability skills) and the subagent roles. The plugin carries skills and roles only; the CLI above must be installed separately. See [Skills](SKILLS.md) for plugin install commands and the skill workflow.
+
+## 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

@@ -0,0 +1,70 @@
+# 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
+- log add and read
+- 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 project-scoped configuration for Codex, Claude Code, and Cursor. Non-dry install writes only repository-local files:
+
+- Codex: `.planr/integrations/codex-mcp.toml`
+- Claude Code: `.mcp.json`
+- Cursor: `.cursor/mcp.json`
+
+Planr does not edit global client configuration without a separate explicit operator action.

package/docs/MCP_GUIDE.md

@@ -0,0 +1,40 @@
+# 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/NPM.md

@@ -0,0 +1,40 @@
+# 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
+```