planr 1.7.0 → 1.7.2

package/docs/planr-spec/BACKEND_IMPLEMENTATION_SPEC.md

@@ -1,178 +0,0 @@
-# Backend Implementation Specification
-
-## Backend Scope
-
-The backend is a local engine embedded in the `planr` binary. It owns map state, plan parsing, search, MCP tools, optional HTTP/SSE, and integration runners.
-
-## Language And Runtime
-
-Recommended default:
-
-- Rust 2021 or newer.
-- `rusqlite` or equivalent SQLite binding.
-- `clap` for CLI.
-- `serde` for JSON.
-- `tokio` and `axum` only if HTTP/SSE ships in V1.
-
-## Core Modules
-
-```text
-src/
-  core/
-    graph.rs
-    state_machine.rs
-    readiness.rs
-    log.rs
-    reviews.rs
-    search.rs
-  storage/
-    schema.rs
-    upgrades.rs
-    sqlite.rs
-  planpack/
-    markdown.rs
-    frontmatter.rs
-    project_pack.rs
-    packages.rs
-  cli/
-  mcp/
-  server/
-  agents/
-    codex.rs
-    claude_code.rs
-    cursor.rs
-  git/
-```
-
-## State Machine
-
-REQ-BE-001: State transitions must be centralized.
-
-Required transitions:
-
-```text
-pending -> ready
-ready -> picked
-picked -> running
-running -> picked
-running -> closed
-running -> blocked
-running -> failed
-failed -> ready
-running -> cancelled
-```
-
-Lenient single-agent convenience may allow `ready -> closed` only when no other active pick exists and the worker id is explicit.
-
-## Readiness Engine
-
-REQ-BE-010: Readiness must be recomputed transactionally after item creation, link changes, and closure.
-
-REQ-BE-011: An item is ready only when all blocking and feeds-into links are closed or closed_partial.
-
-REQ-BE-012: Parent item closure must check required children and reviews.
-
-## Atomic Picking
-
-REQ-BE-020: Picking must use an atomic update equivalent to:
-
-```sql
-UPDATE items
-SET status = 'picked',
-    worker_id = ?,
-    pick_token = ?,
-    picked_at = CURRENT_TIMESTAMP,
-    last_heartbeat_at = CURRENT_TIMESTAMP
-WHERE id = ? AND status = 'ready';
-```
-
-The caller succeeds only when exactly one row changes.
-
-REQ-BE-021: Heartbeat updates must require the same worker owner when an owner exists, move `picked` to `running`, and refresh `last_heartbeat_at`.
-
-REQ-BE-022: Progress, pause, and resume must preserve `worker_id` and `pick_token`.
-
-REQ-BE-023: Stale detection must compare `last_heartbeat_at`, `picked_at`, or `updated_at` against an explicit threshold and release only when the caller requests release.
-
-## Approval Gates
-
-REQ-BE-025: Approval request must store status `requested`, request time, and optional reason.
-
-REQ-BE-026: Approval approve and deny must store the decision maker and optional comment.
-
-REQ-BE-027: Close must reject items with approval status `requested` or `denied`.
-
-## Markdown Plan Parser
-
-REQ-BE-030: Parser must support YAML frontmatter and Markdown headings.
-
-REQ-BE-031: Parser must preserve files on parse errors and store a parse error record.
-
-REQ-BE-032: Parser must map headings to stable section ids using slug + heading depth + ordinal.
-
-REQ-BE-033: Parser must not execute instructions contained in plan files.
-
-## Search
-
-REQ-BE-040: Search must index:
-
-- item title/description;
-- context content;
-- plan title/manifest/frontmatter/headings;
-- log summary;
-- review findings summary.
-
-REQ-BE-041: Search results must identify source type and path/id.
-
-## MCP Server
-
-REQ-BE-050: MCP stdio server must start with `planr mcp`.
-
-REQ-BE-051: Tool schemas must validate all mutation inputs.
-
-REQ-BE-052: Tools must return compact JSON optimized for agent context.
-
-REQ-BE-053: Resources must expose read-only project, item, plan, and log data.
-
-REQ-BE-054: Prompts must expose Planr workflow prompts.
-
-## HTTP/SSE Server
-
-Optional V1:
-
-- `planr serve --port 7526`.
-- localhost default bind.
-- JSON REST API.
-- SSE stream for events.
-- no remote auth in V1 unless explicitly implemented.
-
-## Package Import
-
-REQ-BE-060: Import must consume Planr JSON packages created by `planr export`.
-
-REQ-BE-061: Import preview must report package metadata, create counts, and conflicting item ids without mutating state.
-
-REQ-BE-062: Confirmed import must restore package graph items, links, contexts, optional logs, optional plan file snapshots, and review artifacts.
-
-## Agent Runners
-
-Runner wrappers are optional but expected after core V1:
-
-- Codex: `codex exec`, `codex review`.
-- Claude Code: command runner or MCP-only guidance.
-- Cursor: `cursor-agent` where available or MCP-only guidance.
-
-REQ-BE-070: Runners must record run metadata and log.
-
-REQ-BE-071: Runners must not hide approval, sandbox, or command failures.
-
-## Verification
-
-Backend must include:
-
-- unit tests for state transitions;
-- integration tests for atomic pick races;
-- integration tests for heartbeat, progress, pause, resume, stale release, and approval-blocked closure;
-- parser tests for valid and invalid plan files;
-- MCP tool schema tests;
-- import fixture tests for existing `.planr` layouts.

package/docs/planr-spec/CLIENT_IMPLEMENTATION_SPEC.md

@@ -1,119 +0,0 @@
-# Client Implementation Specification
-
-## Client Surfaces
-
-- CLI: primary V1 interface.
-- MCP client: primary agent integration.
-- Optional TUI/dashboard: local visual inspection.
-- Install helpers: client-specific setup for Codex, Claude Code, Cursor.
-
-## CLI Requirements
-
-- REQ-CLI-001: Every command that mutates state must support `--json`.
-- REQ-CLI-002: Human output must include next actions without hiding failure causes.
-- REQ-CLI-003: Commands must be composable in shell scripts.
-- REQ-CLI-004: `--db` or equivalent must allow alternate database paths.
-- REQ-CLI-005: Planr must derive a stable worker id automatically from client/session context where available.
-- REQ-CLI-006: `planr prompt` must print client-ready CLI, MCP, or HTTP instructions and report that global config was not edited.
-- REQ-CLI-007: Recovery, import, cancellation, and replan commands must support preview-first workflows before destructive mutations.
-
-## Command Groups
-
-```text
-planr project ...
-planr plan ...
-planr map ...
-planr item ...
-planr pick
-planr log ...
-planr review ...
-planr recover ...
-planr prompt cli|mcp|http
-planr close
-planr context ...
-planr search
-planr doctor
-planr mcp
-planr serve
-```
-
-## MCP Client Requirements
-
-- REQ-CLIENT-010: MCP tools must have stable names and JSON schemas.
-- REQ-CLIENT-011: MCP prompts must expose plan/work/review/map/summary workflows.
-- REQ-CLIENT-012: MCP resources must be read-only.
-- REQ-CLIENT-013: Mutation tools must return compact log summaries and next-action hints.
-
-## Codex Integration
-
-V1 must provide:
-
-- `planr install codex` or `planr doctor --client codex`.
-- MCP registration instructions compatible with Codex CLI.
-- Optional AGENTS.md snippet.
-- Optional `planr codex run` post-V1 wrapper for `codex exec`.
-
-Acceptance:
-
-- REQ-CLIENT-020: A Codex user can see Planr MCP registration command and verify it with `codex mcp list`.
-- REQ-CLIENT-021: Codex prompts must not assume Codex is the only agent in the project.
-
-## Claude Code Integration
-
-V1 must provide:
-
-- `.mcp.json` project-scoped config example.
-- `claude mcp add` command example where available.
-- Prompt/skill instructions that preserve Planr graph SSOT.
-
-Acceptance:
-
-- REQ-CLIENT-030: Claude Code install output must explain project vs user scope.
-- REQ-CLIENT-031: Claude Code prompt package must include plan/work/review/map/summary workflows.
-
-## Cursor Integration
-
-V1 must provide:
-
-- `.cursor/mcp.json` project config example.
-- Global `~/.cursor/mcp.json` example.
-- Cursor Agent usage notes.
-
-Acceptance:
-
-- REQ-CLIENT-040: Cursor install output must distinguish stdio, SSE, and streamable HTTP options when relevant.
-- REQ-CLIENT-041: Cursor prompts must avoid relying on Codex-only skill behavior.
-
-## Optional TUI/Dashboard
-
-If implemented:
-
-- read-only by default;
-- optional mutation actions behind confirmation;
-- graph and list views;
-- live event updates;
-- local-only server.
-
-The implemented local browser review workspace is served at `/review` with data from `/v1/review-workspace`.
-
-## Offline Behavior
-
-All V1 client flows must work without internet once the binary is installed.
-
-## Error Handling
-
-Errors must include:
-
-- machine-readable code;
-- plain-language message;
-- affected object id/path;
-- suggested next command when safe.
-
-## Client Tests
-
-- CLI golden output tests.
-- JSON schema output tests.
-- MCP tool discovery tests.
-- Config-generation fixture tests for Codex, Claude Code, and Cursor.
-- Prompt output tests for CLI, MCP, HTTP, and per-client wording.
-- Browser workspace smoke tests against localhost.

package/docs/planr-spec/DESIGN_SYSTEM_SPEC.md

@@ -1,102 +0,0 @@
-# Design System Specification
-
-## Design Principles
-
-- Operational, not decorative.
-- Dense enough for repeated developer use.
-- Log-first: status, blockers, files, and verification are always scannable.
-- Calm hierarchy: avoid dashboards that obscure the next action.
-- Text remains copyable and useful in terminals.
-
-## Brand Tone
-
-Planr should sound precise, direct, and practical:
-
-- "picked i-api by codex-1"
-- "blocked: t-schema is not done"
-- "review found 2 issues"
-
-Avoid hype, gamification, and vague success language.
-
-## Visual Direction
-
-- CLI/TUI: high-contrast, compact, status-color restrained.
-- Web dashboard: work-focused, table/graph hybrid, no oversized hero sections.
-- Cards only for repeated items, log, and item summaries.
-- Radius: 6px maximum unless platform default requires otherwise.
-
-## Color System
-
-- Neutral background.
-- Status colors:
-  - ready: blue or cyan.
-  - running/picked: amber.
-  - done: green.
-  - blocked/failed: red.
-  - review: violet only as accent, not dominant palette.
-- Provide no-color output mode.
-
-## Typography
-
-- CLI: terminal default.
-- Dashboard: system UI font for text, monospace for ids/commands.
-- No viewport-scaled text.
-- Long ids and paths must wrap or truncate with copy affordance.
-
-## Spacing And Layout
-
-- Item rows must keep stable height in tables.
-- Graph nodes must have predictable min/max widths.
-- Side panels should show details without covering the primary queue.
-- Mobile dashboard, if implemented, uses stacked list/detail, not dense graph canvas.
-
-## Component System
-
-- Status badge.
-- Item row.
-- Dependency edge.
-- Plan link.
-- Log card.
-- Command log block.
-- Review finding row.
-- Agent run row.
-- Search result row.
-- Doctor diagnostic item.
-
-## Motion And Haptics
-
-- No required motion.
-- Dashboard transitions must respect reduced motion.
-- Live updates may pulse once but must not animate continuously.
-
-## Iconography And Illustration
-
-- Use simple icons only for status, actions, and diagnostics.
-- Do not use decorative illustrations in the product UI.
-
-## Data Visualization Rules
-
-- Graph view must distinguish containment from dependency edges.
-- Critical path must be visually separable from general edges.
-- Hidden nodes must be indicated with counts.
-- Graph view must have an equivalent text/table representation.
-
-## Accessibility Requirements
-
-- REQ-DES-001: All dashboard actions must be keyboard reachable.
-- REQ-DES-002: Color cannot be the only status indicator.
-- REQ-DES-003: Command blocks must be selectable and copyable.
-- REQ-DES-004: Graph state must be available as text for screen readers.
-
-## Platform-Specific UI Conventions
-
-- CLI follows Unix command conventions.
-- MCP prompt names are stable and descriptive.
-- Cursor/Claude/Codex instructions should use each client's standard config paths and avoid hidden global edits unless requested.
-
-## Do Not Do
-
-- Do not build a marketing landing page as the product surface.
-- Do not use a single purple gradient theme.
-- Do not hide blockers behind cheerful progress summaries.
-- Do not put UI cards inside cards.

package/docs/planr-spec/PRODUCT_SPEC.md

@@ -1,193 +0,0 @@
-# Product Specification
-
-## Vision
-
-Planr is the planning and coordination layer coding agents are missing: a local-first system that turns an app idea into a production plan, narrows it into a build plan, and runs the work on a dependency-aware map with log-backed review.
-
-## Product Promise
-
-Planr turns broad product ideas and coding work into a coherent flow: product plan -> build plan -> map -> pick -> log -> review/evidence -> recovery/package -> close. It prevents duplicate work through atomic picks and makes closure auditable through logs, reviews, verification, and explicit recovery.
-
-## Target Users
-
-- Individual developers running one or more coding agents locally.
-- Power users coordinating Codex, Claude Code, Cursor, Gemini CLI, or custom MCP agents in the same repo.
-- Teams that want repo-local planning artifacts before adopting a hosted workflow.
-- Agent builders who need a small coordination primitive for local or CI-based agent workers.
-
-## Problems Solved
-
-- Agents lose context across sessions, compaction, and handoffs.
-- Flat todo lists cannot model dependency order or safe parallelism.
-- Markdown plans have rich context but weak live status and no atomic picking unless connected to a map.
-- Issue trackers are too human-centric for fast, mid-flight agent replanning.
-- Agent completions often lack proof: no files, commands, review, or blocked-state record.
-
-## Product Principles
-
-- Local first: the repository plus a local database should be enough.
-- Product plans capture intent, build plans capture implementation context, and the map coordinates live work.
-- Log over optimism: completion is proven, not declared.
-- Cross-agent by default: Codex, Claude Code, Cursor, and MCP clients are peers.
-- Hard-cut bias: avoid duplicate sources of truth and transitional shells.
-- Human-readable artifacts: all important plans and decisions must be inspectable without a proprietary UI.
-
-## V1 Scope
-
-- A `planr` CLI.
-- A local SQLite map graph with items, links, picks, contexts, artifacts, logs, reviews, runs, and events.
-- A `.planr/` repo pack for plans, project context, review artifacts, and skill/prompt templates.
-- MCP server exposing tools, resources, and prompts for Claude Code, Cursor, Codex, and compatible clients.
-- Optional HTTP/SSE local server for dashboard and automation clients.
-- Codex, Claude Code, and Cursor install/config helpers.
-- Import of existing `.planr` data.
-- Export/import of map graph and Markdown plan packs.
-- Explicit recovery sweeps for stale, timed-out, and retryable work.
-- Scoped Git/PR review evidence and a local browser review workspace.
-- Reusable template packages with preview-first import.
-- Prompt output for CLI, MCP, and HTTP agent setup without hidden global config edits.
-
-## Explicit Non-Goals
-
-- REQ-PROD-001: V1 must not require a cloud account, hosted database, or network service.
-- REQ-PROD-002: V1 must not depend on unowned coordination-layer packages or hosted services.
-- REQ-PROD-003: V1 must not be a general project management SaaS.
-- REQ-PROD-004: V1 must not store full agent transcripts by default.
-- REQ-PROD-005: V1 must not privilege one vendor as the only supported workflow.
-
-## User Personas
-
-- Solo operator: runs Codex and Claude Code in one repo and wants clean handoffs.
-- Multi-agent power user: launches several workers and wants atomic picking plus conflict visibility.
-- Reviewer: audits whether an item is actually closed against a plan, diff, log, and tests.
-- Toolsmith: wants MCP/HTTP primitives to embed Planr in another agent system.
-
-## Product Flow
-
-The canonical Planr flow is:
-
-```text
-idea -> product plan -> build plan -> map -> pick -> log -> review/evidence -> recovery/package -> close
-```
-
-- Idea: raw user request, startup concept, feature request, bug, refactor, or product slice.
-- Product plan: broad product/spec package for app ideas and major initiatives.
-- Build plan: focused implementation contract for a buildable slice.
-- Map: live dependency graph of executable items.
-- Pick: atomic assignment of one ready item to one agent.
-- Log: proof bundle for implementation, verification, review, or handoff.
-- Review: approval or audit condition that blocks closure until satisfied.
-- Evidence: scoped Git, PR URL, file, command, test, and artifact proof attached to the item.
-- Recovery: explicit preview/apply operation for stale, timed-out, retryable, or condition-gated work.
-- Package: reusable local export/import bundle for graph state, plans, logs, contexts, and review artifacts.
-- Close: log-backed completion of an item or parent slice.
-
-## Core Objects And Vocabulary
-
-- Project: one repository or multi-root project tracked by Planr.
-- Plan: Markdown artifact under `.planr/plans/` with an internal stage such as `product`, `build`, or `review`.
-- Map: live graph for work items, links, picks, reviews, log, and status.
-- Item: graph node with status, work type, owner, acceptance summary, and optional plan links.
-- Link: directed relationship between items; blocking or non-blocking.
-- Context: project-wide discovery, decision, constraint, or pattern.
-- Log: proof bundle produced when an agent implements, verifies, reviews, or hands off work.
-- Run: one agent execution attempt against an item.
-- Review: approval node or policy requiring log before closure.
-
-## Core User Journeys
-
-- Initialize Planr in a repo and configure Codex, Claude Code, and Cursor.
-- Create a plan from a broad app idea or PRD request.
-- Convert product plan slices into build plans.
-- Seed map items from a plan.
-- Pick and execute the next ready item.
-- Run multiple agents concurrently without duplicate picks.
-- Add log with files, commands, tests, and result summary.
-- Review an item against its plan and create fix/review follow-up items when needed.
-- Inspect item-scoped Git evidence and optional PR URL context before approving work.
-- Recover safely after interruption with explicit stale-pick and retry sweeps.
-- Export a reusable package/template and preview import before mutating a project.
-- Resume after interruption and see the current map, active plans, and blockers.
-
-## Feature Requirements
-
-### Initialization
-
-- REQ-PROD-010: `planr project init` must create `.planr/`, `.planr/project/`, `.planr/plans/`, `.planr/reviews/`, and a local database without overwriting user content unless `--force` is provided.
-- REQ-PROD-011: `planr project init --client codex|claude|cursor|all` must print or apply integration instructions for the selected client.
-- REQ-PROD-012: Initialization must detect existing `.planr` data and offer import commands.
-
-### Product Plans
-
-- REQ-PROD-020: Product plans must support PRD/product spec, UX flows, design system plan, technical architecture, ADRs, AI spec where relevant, safety/privacy/security, API/data model, implementation specs, QA, release readiness, executable task checklist, and references.
-- REQ-PROD-021: Product plan generation must ask only blocking questions and mark assumptions explicitly.
-- REQ-PROD-022: Product plan requirements must use stable IDs and testable language.
-- REQ-PROD-023: Product plan work lists must be convertible into build plans or map candidate items, but must not automatically become live map commitments without user/agent selection.
-
-### Build Plans
-
-- REQ-PROD-030: Build plans must support frontmatter, source, scope decision, ownership target, existing leverage, phases, verification, acceptance criteria, out-of-scope, and notes.
-- REQ-PROD-031: A build plan may be linked to one or more map items.
-- REQ-PROD-032: The project context pack must preserve product, ownership, flows, state SSOT, constraints, and quality checks.
-- REQ-PROD-033: Plan closure claims must be reconciled against map item state and log.
-
-### Map Planning
-
-- REQ-PROD-040: Map items must support statuses: pending, ready, picked, running, in_review, blocked, closed, closed_partial, failed, cancelled.
-- REQ-PROD-041: Links must support hard blocking order and soft contextual relationships.
-- REQ-PROD-042: Item readiness must be computed from map graph state, not from Markdown checkboxes.
-- REQ-PROD-043: Picking a ready item must be atomic across concurrent agents.
-- REQ-PROD-044: Parent items must not close until required child code, fix, and review items are closed.
-
-### Agent Execution
-
-- REQ-PROD-050: Planr must provide agent-specific prompts or MCP prompts for Codex, Claude Code, and Cursor.
-- REQ-PROD-051: Runs must record worker id, client, model/profile when available, item id, command surface, start/end time, and result status.
-- REQ-PROD-052: Item closure must require or allow a log entry with files changed, tests run, commands run, result summary, and blocked/unverified items.
-- REQ-PROD-053: Review findings must create fix items rather than failing ordinary code items.
-- REQ-PROD-054: `planr prompt` must expose CLI, MCP, and HTTP operating instructions without editing global configuration.
-
-### Search And Recall
-
-- REQ-PROD-060: Planr must search items, plans, contexts, logs, and review artifacts.
-- REQ-PROD-061: Picking an item must surface relevant upstream context and linked plan sections.
-- REQ-PROD-062: Recovery sweep must preview stale, timed-out, retryable, and condition-gated work before applying mutations.
-- REQ-PROD-063: Review evidence must distinguish item-scoped changed files from unrelated dirty worktree files.
-- REQ-PROD-064: Package import must be preview-first and confirmed explicitly.
-
-## Plans, Tiers, Monetization
-
-- V1 is an open-source local tool.
-- Commercial hosted sync, team dashboards, or enterprise policy packs are explicitly post-V1.
-
-## Integrations
-
-- Codex CLI and Codex MCP configuration.
-- Claude Code MCP project/user configuration.
-- Cursor MCP project/global configuration.
-- Generic MCP clients via stdio and optional streamable HTTP.
-- Git worktrees and Git diff logs.
-- Optional CI invocation for verification tasks.
-
-## Content, Moderation, And Safety Boundaries
-
-Planr handles developer artifacts and may reference private code. It must minimize stored content and avoid collecting prompts, responses, source file contents, secrets, or private transcripts unless the user explicitly enables retention.
-
-## Success Metrics
-
-- A broad request can become a product plan, build plan, and map items without manual file editing.
-- Two or more agents can pick independent items without collision.
-- A reviewer can determine what changed, why, what was verified, and what remains.
-- A repo can be resumed after interruption using only Planr state and Git state.
-- A fresh consumer project can prove CLI, MCP, HTTP, review workspace, recovery, package, and installer behavior without relying on maintainer-only state.
-
-## Analytics Constraints
-
-- V1 analytics are local diagnostics only.
-- No source code, prompt text, response text, file contents, secrets, or private plan body text may be sent to analytics.
-
-## Open Decisions
-
-- OD-PROD-001: Final implementation language: Rust is assumed, but Go remains viable.
-- OD-PROD-002: Whether the local HTTP server ships in V1 or behind a feature flag.
-- OD-PROD-003: Whether Codex-specific worker orchestration is V1 or V1.1.