planr 0.0.1 → 1.1.15

package/docs/TASK_GRAPH_MODEL.md

@@ -0,0 +1,222 @@
+# Planr Task Graph Model
+
+Planr's map is a local dependency-aware graph for coding-agent work. It exists so agents can coordinate without relying on ad hoc chat history.
+
+## Core Objects
+
+- Project: repository-level Planr workspace.
+- Plan: Markdown product or build package.
+- Item: one unit of live work in the map.
+- Link: relationship between items.
+- Pick: atomic claim of a ready item by one worker session.
+- Log: durable proof of implementation, verification, review, or handoff.
+- Review: an item that blocks target closure until it is closed.
+- Context: searchable discovery or decision.
+- Recovery: explicit preview/apply operation for stale, timed-out, or retryable work.
+
+## State Authority
+
+The SQLite database is authoritative for:
+
+- item status;
+- links and readiness;
+- picks and ownership;
+- reviews and closure gates;
+- contexts and logs;
+- artifacts and events as they become public product surfaces.
+
+Markdown plans are authoritative for scope and acceptance criteria. They do not override map state.
+
+## Item Readiness
+
+Readiness is derived from state and links:
+
+- an item may become ready when its blocking upstream items are closed;
+- picked items are owned by one worker session;
+- requesting a review moves a picked or running item to `in_review` (ownership kept) so the wait state is visible instead of masquerading as active work;
+- closed items can unlock downstream items;
+- open review items block target closure;
+- cancelled items should not silently unlock unrelated work.
+
+The status lifecycle for work items is `pending -> ready -> picked -> running -> in_review -> closed` (with `blocked`, `failed`, `cancelled`, and `closed_partial` as branch states). `in_review` items still accept evidence logs and heartbeats from their owner, are excluded from new picks, and close either through `review close --verdict complete --close-target` or an explicit `planr close` after the review completes. Findings keep the target `in_review`: the follow-up review gates the same target until the chain settles.
+
+Use:
+
+```bash
+planr map show --json
+planr map lane --critical
+planr map pressure
+```
+
+## Links
+
+Create explicit order:
+
+```bash
+planr item create "Design API" --description "Define endpoints and data ownership."
+planr item create "Implement API" --description "Build endpoints after design is closed."
+planr link add <design-item> <implementation-item> --type blocks
+```
+
+Use `blocks` for hard ordering. Use softer link types only when the product contract for that type is documented and tested.
+
+## Picking
+
+Picking is the concurrency boundary:
+
+```bash
+planr pick --json
+```
+
+One ready item should be picked by one worker. The pick output is one flat work packet — item, links, logs, runtime, recovery, conditions, recall context, and a `remaining` progress snapshot, each fact exactly once; empty collections are omitted. Picked work records `worker_id`, `pick_token`, `picked_at`, and `last_heartbeat_at`. Worker identity is stable per client, host, and user, so heartbeats keep working across the many short-lived processes of an agent session. Agents should export `PLANR_WORKER_ID` (an explicit identity such as `maker-1` or `checker-1`) for the whole session, so picks, logs, and heartbeats attribute to the agent instead of `client:host:user`. Parallel workers on the same machine must set `PLANR_WORKER_ID` (or `PLANR_SESSION_ID`) to distinct values. Evidence written via `log add` or `done` by the owner refreshes the heartbeat automatically; the explicit runtime commands cover long silent stretches:
+
+```bash
+planr pick heartbeat [item-id]
+planr pick progress <item-id> --percent 42 --note "running focused tests"
+planr pick pause <item-id> --note "waiting for review input"
+planr pick resume <item-id>
+```
+
+If two workers race, the database must allow only one winner. If the owner disappears, inspect stale claims and reset intentionally:
+
+```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
+planr pick release <item-id> --force
+```
+
+Use forced release only when the operator intentionally transfers ownership. Use `recover sweep --apply` for the broader recovery path that also requeues timed-out picked work and retryable failed work.
+
+## Approvals
+
+Approvals are explicit human gates on an item:
+
+```bash
+planr approval request <item-id> --reason "needs release approval"
+planr approval deny <item-id> --by "qa" --comment "missing evidence"
+planr approval approve <item-id> --by "qa" --comment "evidence accepted"
+planr approval list --open
+```
+
+An item with `requested` or `denied` approval status cannot close. `map preview --close <item-id>` reports whether approval blocks closure before the mutation is attempted.
+
+## Reviews And Fix Chains
+
+Request review after evidence exists:
+
+```bash
+planr review request <item-id>
+```
+
+A clean review can close:
+
+```bash
+planr review close <review-id> --verdict complete
+```
+
+Findings create follow-up work:
+
+```bash
+planr review close <review-id> \
+  --verdict not-complete \
+  --findings "specific actionable finding"
+```
+
+The target item may close only when required review items are closed.
+
+Every `review close` records a derived `review_mode`: the closing reviewer identity is compared against the target item's lease holder and recorded as `single_agent` (same identity), `independent` (different identity), or `unattributed` (no recorded maker). The mode lands in the close response, review log, artifact, and event — independence is proven by recorded identity, not declared by a note.
+
+## Evidence
+
+Logs make closure auditable:
+
+```bash
+planr log add --item <item-id> \
+  --summary "Implemented parser hardening" \
+  --files src/parser.rs,tests/parser.rs \
+  --cmd "cargo test parser"
+```
+
+Use multiple `--cmd` or `--tests` values when more than one verification command matters. `--cmd` records what was executed; `--tests` records test commands/results specifically — both are evidence fields, not gates.
+
+Live verification evidence (browser runs, smoke tests against a running app) uses `--kind verification`:
+
+```bash
+planr log add --item <item-id> --kind verification \
+  --summary "Verified upload flow in browser: video plays after publish" \
+  --cmd "agent-browser snapshot http://localhost:3000/watch/1"
+```
+
+`plan audit` checks for verification logs when a goal contract exists. Log persistent evidence, not transient states: a failure that you immediately fix belongs in the final log's narrative, not as a standalone failure log.
+
+Settling commands (`done`, `close`, `review close`) report what they `unlocked` — every item that became ready because of that settlement — plus the item's `post_condition` and an evidence hint when downstream work depends on an item closed without `--cmd`/`--tests`.
+
+## Graph Inspection
+
+Use critical lane for ordering risk:
+
+```bash
+planr map lane --critical
+```
+
+Use pressure for bottlenecks:
+
+```bash
+planr map pressure
+```
+
+Use trace for handoff:
+
+```bash
+planr trace item <item-id>
+```
+
+The trace should be enough for a new agent to recover the current item, linked logs, and linked blockers.
+
+Use status, lookahead, and close preview before sequencing or closure:
+
+```bash
+planr map status
+planr map lookahead <item-id>
+planr map preview --close <item-id>
+```
+
+These commands expose readiness, downstream unlocks, closure blockers, approval requirements, open reviews, and manual conditions before mutating graph state.
+
+## Review Evidence
+
+Review evidence is item-scoped proof, not a dump of the whole repository:
+
+```bash
+planr review evidence <item-id>
+planr review evidence <item-id> --pr-url https://example.invalid/pr/123
+```
+
+Planr reports Git branch, commit, dirty state, files named by item logs/artifacts, unrelated dirty files, and optional PR URL context. It does not inline source file content by default.
+
+## Packages
+
+Packages preserve reusable graph context outside the live database:
+
+```bash
+planr export --include-plans --include-logs --template-name "Release checklist" --tag release --out planr-package.json
+planr import planr-package.json --preview
+planr import planr-package.json --confirm
+```
+
+Package import is preview-first and confirmed explicitly. Imported packages restore items, links, contexts, logs, plan file snapshots, and review artifacts into the current map.
+
+## Graph Adaptation
+
+Planr supports graph adaptation without relying on chat-only replanning:
+
+- use `item breakdown` for decomposition;
+- use `item insert --preview` before rewiring linked work and `--confirm` to apply;
+- use `item amend` for future-work context;
+- use `item replan --preview` before replacing pending child work and `--confirm` to apply;
+- use `link add` and `link remove` for dependency changes;
+- use `map preview --close`, `map unlocks`, `map lookahead`, and `map status` before closing or sequencing work;
+- use `item cancel --preview` before cancellation;
+- use `trace item` and logs for recovery.

package/docs/TESTING.md

@@ -0,0 +1,87 @@
+# Testing
+
+Planr has two test layers plus a release-grade V1.1 verification ladder.
+
+## In-Repo Tests
+
+```bash
+cargo fmt --check
+cargo clippy --all-targets -- -D warnings
+cargo test
+```
+
+Focused V1.1 checks should be run when their surfaces change:
+
+```bash
+cargo test recovery_sweep -- --nocapture
+cargo test local_review_workspace -- --nocapture
+cargo test review_evidence -- --nocapture
+cargo test template_export_import -- --nocapture
+```
+
+## Consumer E2E Project
+
+The standalone consumer suite is a maintainer-local project that is not part of this repository. On maintainer machines it lives at:
+
+```bash
+~/projects/planr-test
+```
+
+Contributors without that project should rely on the in-repo suite (`cargo test`), which covers the same CLI, MCP, and HTTP surfaces.
+
+Run against the local native binary:
+
+```bash
+cd ~/projects/planr
+cargo build --release
+cd ~/projects/planr-test
+npm test
+```
+
+Run through the npm package wrapper:
+
+```bash
+cd ~/projects/planr
+npm link
+cd ~/projects/planr-test
+npm link planr
+npm run test:npm-planr
+```
+
+The consumer suite exercises every public command group and subcommand, MCP stdio, local HTTP/SSE, import/export, review gates, install helpers, and generated plan files.
+
+## V1.1 Release Verification
+
+Before calling V1.1 complete, run the full in-repo and consumer ladder:
+
+```bash
+cargo fmt --check
+cargo test
+cargo clippy --all-targets -- -D warnings
+scripts/build-release.sh
+(cd dist && shasum -a 256 -c SHA256SUMS)
+(cd dist/planr-1.0.0 && shasum -a 256 -c SHA256SUMS)
+npm pack --dry-run
+```
+
+Installer changes also require:
+
+```bash
+/Users/kregenrek/.agents/skills/shellck/scripts/run_shellck.sh scripts/install.sh
+PREFIX="$(mktemp -d)" PLANR_DOWNLOAD=1 PLANR_RELEASE_BASE_URL="file://$PWD/dist" scripts/install.sh
+```
+
+Live behavior must be proved with:
+
+- a fresh consumer project at `~/projects/planr-test`;
+- MCP stdio contract checks against `docs/fixtures/mcp-contract.json`;
+- localhost HTTP/SSE checks and the browser review workspace at `/review`;
+- recovery sweep checks for stale, timed-out, and retryable work;
+- Git/PR review evidence checks that do not inline source content;
+- package export/import checks for templates, logs, plan files, and review artifacts;
+- prompt output checks for CLI, MCP, and HTTP setup text;
+- a forbidden-reference scrub across public repo files.
+
+## Contract Fixtures
+
+`docs/fixtures/mcp-contract.json` is checked by the Rust E2E suite against live MCP stdio responses, install dry-runs, and the CLI reference. Update the fixture and `docs/MCP_CONTRACT.md` together when adding or removing MCP tools, resources, prompts, or install snippets.

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,26 @@
+# Troubleshooting
+
+## No Ready Items
+
+```bash
+planr map show --json
+planr map pressure
+planr trace item <item-id>
+```
+
+## MCP Client Cannot See Tools
+
+```bash
+planr doctor --client all
+planr install codex --dry-run
+planr install claude --dry-run
+planr install cursor --dry-run
+```
+
+## Database Or Import Issues
+
+```bash
+planr project show --json
+planr import /path/to/repo --json
+planr export --include-plans --include-logs --out planr-debug.json
+```

package/docs/fixtures/mcp-contract.json

@@ -0,0 +1,92 @@
+{
+  "tools": [
+    "planr_project_show",
+    "planr_map_show",
+    "planr_map_status",
+    "planr_map_preview",
+    "planr_map_unlocks",
+    "planr_map_lookahead",
+    "planr_plan_create",
+    "planr_plan_refine",
+    "planr_plan_split",
+    "planr_plan_check",
+    "planr_plan_audit",
+    "planr_plan_link",
+    "planr_map_build",
+    "planr_item_create",
+    "planr_item_breakdown",
+    "planr_item_insert",
+    "planr_item_amend",
+    "planr_item_replan",
+    "planr_pick_item",
+    "planr_pick_heartbeat",
+    "planr_pick_progress",
+    "planr_pick_pause",
+    "planr_pick_resume",
+    "planr_pick_stale",
+    "planr_recover_sweep",
+    "planr_approval_request",
+    "planr_approval_approve",
+    "planr_approval_deny",
+    "planr_approval_list",
+    "planr_artifact_add",
+    "planr_artifact_list",
+    "planr_artifact_show",
+    "planr_event_list",
+    "planr_debug_bundle",
+    "planr_log_add",
+    "planr_review_annotate",
+    "planr_review_ingest",
+    "planr_review_artifact",
+    "planr_review_evidence",
+    "planr_review_close",
+    "planr_close_item",
+    "planr_context_create",
+    "planr_search",
+    "planr_log_read"
+  ],
+  "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"
+  ],
+  "unknown_tool_error": "unknown Planr MCP tool",
+  "install_fragments": {
+    "codex": [
+      "[mcp_servers.planr]",
+      "command = \"planr\"",
+      "args = [\"--db\""
+    ],
+    "claude": [
+      "claude mcp add planr",
+      "\"mcpServers\"",
+      "\"planr\""
+    ],
+    "cursor": [
+      ".cursor/mcp.json",
+      "\"mcpServers\"",
+      "\"planr\""
+    ]
+  },
+  "cli_reference_commands": [
+    "planr install codex|claude|cursor",
+    "planr prompt cli|mcp|http",
+    "planr mcp",
+    "planr review annotate",
+    "planr review ingest",
+    "planr review artifact",
+    "planr review evidence",
+    "planr review close",
+    "planr recover sweep",
+    "planr serve --port"
+  ]
+}

package/docs/planr-spec/ADRS.md

@@ -0,0 +1,160 @@
+# ADRs
+
+## ADR-001: Build Planr As A Self-Owned Product
+
+Status: Accepted
+
+### Context
+
+Planr needs to combine durable Markdown planning with executable graph coordination under one owned product surface.
+
+### Decision
+
+Planr will be a new codebase and brand. Implementation, docs, assets, command names, and product vocabulary must be original unless explicitly retained under compatible license obligations.
+
+### Alternatives Considered
+
+- Build only Markdown plans: preserves readable context but lacks graph concurrency.
+- Build only a graph engine: strong execution state but weak product and implementation context.
+- Build hosted SaaS first: too much scope for V1.
+
+### Consequences
+
+- More initial engineering work.
+- Cleaner product ownership.
+- Better ability to design graph + Markdown as one system.
+
+### Risks
+
+- Rebuilding core graph behavior can introduce bugs.
+- Public contracts must be explicit before release.
+
+### Follow-Up Tasks
+
+- TASK-FND-001
+- TASK-DATA-001
+
+## ADR-002: Graph State In SQLite, Rich Context In Markdown
+
+Status: Accepted
+
+### Context
+
+Map item state needs atomic picks and link-based readiness. Human and agent context needs readable, versionable documents.
+
+### Decision
+
+Use SQLite as the authoritative graph state store and `.planr/*.md` as the rich context layer.
+
+### Alternatives Considered
+
+- Markdown only: simple, but no atomic concurrent picks.
+- Database only: robust state, but poor narrative handoff.
+- Hosted database: not local-first.
+
+### Consequences
+
+- Requires reconciliation between graph state and plan documents.
+- Gives users both machine reliability and readable context.
+
+### Risks
+
+- Agents may treat Markdown checkboxes as state unless prompts and APIs are explicit.
+
+### Follow-Up Tasks
+
+- TASK-DATA-001
+- TASK-FND-003
+
+## ADR-003: MCP Is The Primary Cross-Agent Integration Surface
+
+Status: Accepted
+
+### Context
+
+Codex, Claude Code, and Cursor all have MCP integration paths, while their native skill/plugin systems differ.
+
+### Decision
+
+Expose Planr through MCP tools, resources, and prompts first. Add client-specific wrappers where useful.
+
+### Alternatives Considered
+
+- Separate plugin per client: more native but higher maintenance.
+- CLI-only: universal but too prompt-dependent.
+
+### Consequences
+
+- MCP schema design becomes part of the stable product contract.
+- Prompts can expose Planr workflows as user-invoked commands.
+
+### Risks
+
+- MCP clients vary in supported capabilities and approval behavior.
+
+### Follow-Up Tasks
+
+- TASK-BE-003
+- TASK-AI-002
+
+## ADR-004: Review/Fix Loop Is A Product Primitive
+
+Status: Accepted
+
+### Context
+
+Agent work needs scoped review, logs, and honest status. Map graphs can encode this as child items and reviews.
+
+### Decision
+
+Every material change should be modelable as a parent gate with implementation or test child work and linked review, fix, and follow-up review work.
+
+### Alternatives Considered
+
+- Close code items immediately after implementation.
+- Use external PR review only.
+
+### Consequences
+
+- Better completion quality.
+- More graph nodes, but they encode real work.
+
+### Risks
+
+- Small items may feel over-modeled unless lightweight defaults exist.
+
+### Follow-Up Tasks
+
+- TASK-DATA-002
+- TASK-AI-003
+
+## ADR-005: No Cloud Or Account System In V1
+
+Status: Accepted
+
+### Context
+
+The product must be useful locally and not create privacy or deployment complexity.
+
+### Decision
+
+V1 has no Planr cloud account, billing, or hosted sync.
+
+### Alternatives Considered
+
+- Hosted dashboard first.
+- Optional sync in V1.
+
+### Consequences
+
+- Simpler security model.
+- Users own their data.
+
+### Risks
+
+- Team collaboration beyond shared Git remains limited.
+
+### Follow-Up Tasks
+
+- TASK-SEC-001
+- TASK-REL-001