planr 1.7.0 → 1.7.2

package/docs/planr-spec/QA_ACCEPTANCE_TESTS.md

@@ -1,146 +0,0 @@
-# QA Acceptance Tests
-
-## Test Strategy
-
-Planr needs fast deterministic tests around graph correctness, plan parsing, MCP contracts, package import/export, and schema upgrades. The smallest relevant test should run before broader suites.
-
-## Unit Tests
-
-### State Machine
-
-- REQ-QA-001: Valid transitions succeed.
-- REQ-QA-002: Invalid transitions return `invalid_transition`.
-- REQ-QA-003: Parent item cannot close while required child review is open.
-- REQ-QA-004: Review annotation and feedback ingestion persist item-linked evidence without auto-closing or auto-approving work.
-- REQ-QA-005: Closing a review writes a `.planr/reviews/*.review.md` artifact and registers it as a review artifact.
-
-### Dependency Readiness
-
-- REQ-QA-010: Item with no blockers becomes ready.
-- REQ-QA-011: Item with unfinished upstream remains pending.
-- REQ-QA-012: Completing upstream promotes downstream in the same transaction.
-- REQ-QA-013: Soft relationship does not block readiness.
-
-### Claiming
-
-- REQ-QA-020: Two concurrent picks for one item produce exactly one winner.
-- REQ-QA-021: Picked item cannot be picked by another agent.
-- REQ-QA-022: Timeout/release policy is explicit and tested.
-- REQ-QA-023: Heartbeat updates move picked work to running and record `last_heartbeat_at`.
-- REQ-QA-024: Progress, pause, and resume preserve the worker claim while updating runtime state.
-- REQ-QA-025: Stale picked work can be detected and intentionally released for re-pick.
-- REQ-QA-026: Requested or denied approvals block close; approved approvals allow close when other gates pass.
-- REQ-QA-027: Recovery sweep previews stale, timed-out, and retryable work before applying changes.
-- REQ-QA-028: Recovery apply records recovery events and preserves manual pre/post condition visibility.
-
-### Plan Parser
-
-- REQ-QA-030: Valid `.plan.md` parses frontmatter and sections.
-- REQ-QA-031: Invalid frontmatter records parse error without rewriting file.
-- REQ-QA-032: Unknown frontmatter fields are preserved.
-
-## Integration Tests
-
-### CLI
-
-- `planr project init` creates database and `.planr` pack.
-- `planr plan new` creates a plan package.
-- `planr plan split` creates a deterministic build plan file.
-- `planr item create` creates a map item.
-- `planr pick` picks next ready item.
-- `planr log add` creates log.
-- `planr close` closes item and promotes downstream.
-- `planr map show --json` returns valid JSON.
-- `planr recover sweep` previews and applies explicit recovery actions.
-- `planr review evidence` records item-scoped Git evidence without source content.
-- `planr prompt cli|mcp|http` prints setup text and does not edit global config.
-- `planr export` and `planr import --preview/--confirm` preserve templates, graph state, logs, plan snapshots, and review artifacts.
-
-### MCP
-
-- MCP server starts over stdio.
-- Tool list includes required Planr tools.
-- Read-only resource reads cannot mutate state.
-- Mutation tools validate schemas.
-- Prompts list includes plan/work/review/map/summary.
-
-### HTTP/SSE
-
-Only if shipped:
-
-- REST endpoints match API spec.
-- SSE emits item state changes.
-- Artifact endpoints persist and return item-linked artifacts.
-- Event endpoints return persisted transition events.
-- Debug bundle preview omits source file content and prompt/response transcripts.
-- Server binds to localhost by default.
-- `/review` renders the local review workspace and supports annotation, request-changes, artifact, and approve flows through the HTTP API.
-
-## Package Import Tests
-
-- Exported packages preview create counts and conflicting item ids without mutation.
-- Confirmed imports restore graph items, links, contexts, optional logs, optional plan files, and review artifacts.
-- Imported graph work can be picked in a fresh project.
-
-## Security Tests
-
-- Secret-looking values are rejected or flagged in context/log writes.
-- HTTP remote bind requires explicit flag.
-- MCP destructive operations require explicit confirmation.
-- Logs do not include forbidden content.
-- SQL injection attempts are treated as data.
-
-## AI/Agent Evals
-
-- Broad prompt creates product plan, build plan, and map.
-- Agent follows `pick -> work -> log -> review -> close` loop.
-- Agent can recover after stale/timed-out work through explicit recovery sweep.
-- Review findings create fix item and follow-up review item.
-- Browser review workspace shows plan context, item evidence, review queue, annotations, and diff-safe Git evidence.
-- Hook-compatible review feedback can be ingested from JSON and remains advisory until a review verdict is explicitly closed.
-- Agent does not mark parent done while review/fix chain is open.
-- Agent treats malicious plan instructions as data.
-
-## Manual Acceptance Scenarios
-
-### Scenario 1: Solo Codex
-
-1. Install Planr.
-2. Configure Codex MCP.
-3. Create product and build plans for a small feature.
-4. Codex picks and closes one item.
-5. Log lists files and commands.
-
-Expected: downstream item unlocks and map state is accurate.
-
-### Scenario 2: Claude Code And Cursor Concurrent
-
-1. Configure both clients.
-2. Create two independent ready items.
-3. Each client picks one item.
-
-Expected: no duplicate picks; map shows both agents.
-
-### Scenario 3: Review Fails
-
-1. Complete code task.
-2. Review item records finding.
-3. Planr creates fix and follow-up review items.
-
-Expected: parent remains incomplete until follow-up review passes.
-
-## Regression Reviews
-
-Before release:
-
-- Unit suite passes.
-- CLI integration suite passes.
-- MCP schema tests pass.
-- Local HTTP and browser review workspace tests pass.
-- Package import/export fixture tests pass.
-- Secret/log scrubbing tests pass.
-- Release checksum verification passes.
-- Installer file-url smoke test passes.
-- Package/template export-import roundtrip passes.
-- Fresh consumer E2E passes in `~/projects/planr-test`.
-- Packaging smoke test passes on macOS and Linux.

package/docs/planr-spec/README.md

@@ -1,68 +0,0 @@
-# Planr Specification Package
-
-Generated: 2026-06-09
-
-## Purpose
-
-This package defines Planr as a production-grade, local-first planning and execution coordination tool for coding agents. Planr combines product plans, build plans, and a live dependency-aware map with reviewable logs and integration surfaces for Codex, Claude Code, Cursor, and other MCP-capable agents.
-
-## Package Contents
-
-- PRODUCT_SPEC.md: product scope, flow, users, features, non-goals, and requirements.
-- UX_FLOWS.md: CLI, MCP, and optional dashboard flows.
-- DESIGN_SYSTEM_SPEC.md: UI and TUI design direction.
-- TECH_ARCHITECTURE.md: system architecture and core ownership boundaries.
-- ADRS.md: major product and architecture decisions.
-- AI_SPEC.md: agent behavior, prompts, context, and evals.
-- SAFETY_PRIVACY_SECURITY.md: data, privacy, security, and tool execution boundaries.
-- API_AND_DATA_MODEL.md: project, plan, map, item, log, review, and API contracts.
-- EVAL_CONTRACT_V1.md: frozen EvalSuite, evidence, v1.1 attempt-lineage and efficiency metrics, verdict, reason, CLI/MCP, database, and safety contract.
-- CLIENT_IMPLEMENTATION_SPEC.md: CLI, TUI, editor, and agent-client surfaces.
-- BACKEND_IMPLEMENTATION_SPEC.md: local service, MCP server, HTTP/SSE, and storage implementation.
-- ANALYTICS_OBSERVABILITY_SPEC.md: no-content telemetry, local logs, and diagnostics.
-- QA_ACCEPTANCE_TESTS.md: acceptance suites and regression strategy.
-- RELEASE_READINESS.md: packaging, install, upgrade, and release checks.
-- V1_1_DIFFERENTIATION_CONTRACT.md: V1.1 product differentiation requirements, acceptance criteria, and final verification contract.
-- TASKS.md: executable implementation tasks for coding agents.
-- REFERENCES.md: sources and source-derived assumptions.
-
-## Global Assumptions
-
-- V1 is a local-first developer tool, not a hosted SaaS.
-- The first implementation may be a Rust CLI and local daemon using SQLite.
-- Codex, Claude Code, and Cursor should all work through standard CLI and MCP integration paths.
-- Existing `.planr` data may be imported, but the V1 CLI, data model, and docs define the final product API.
-- Planr should ship with its own name, code, docs, and architecture.
-
-## Global Non-Goals
-
-- Do not build cloud accounts, billing, team sync, or hosted dashboards in V1.
-- Do not depend on unowned coordination-layer code.
-- Do not make the map graph the only planning artifact; product and build plans are first-class.
-- Do not store full prompts, private code, or agent transcripts by default.
-- Do not make Codex the only supported client.
-
-## Critical Invariants
-
-- The map database is the source of truth for item state, links, picks, approvals, reviews, and closure.
-- Product plans are the source of PRD, architecture, UX, security, QA, and release context.
-- Build plans are the source of implementation-level scope, ownership, acceptance criteria, and narrative decisions.
-- Agent closures require log: changed files, commands run, review outcome, and remaining blockers.
-- Multiple agents must not pick the same ready item.
-- Every external command/tool execution path must be explicit, inspectable, and attributable.
-- Parent items are completion gates. Executable code, test, and review work should live in child items, and downstream work should depend on the parent gate when review cleanliness matters.
-- Story logs and handoff documents explain narrative history only. They never override map state, logs, reviews, or plan acceptance criteria.
-
-## How Coding Agents Should Use This Package
-
-1. Read PRODUCT_SPEC.md, TECH_ARCHITECTURE.md, API_AND_DATA_MODEL.md, and TASKS.md first.
-2. Use UX_FLOWS.md and CLIENT_IMPLEMENTATION_SPEC.md when implementing the CLI, TUI, MCP prompts, or dashboard.
-3. Use AI_SPEC.md for agent prompt, context, and review-loop behavior.
-4. Treat TASKS.md acceptance criteria as the build checklist.
-5. Keep implementation aligned with ADRS.md unless a new ADR supersedes a decision.
-
-## Operating References
-
-- `../OPERATING_MODEL.md`: daily operator flow, parent gates, completion rules, and recovery.
-- `../TASK_GRAPH_MODEL.md`: map objects, readiness, links, picks, reviews, and evidence.
-- `../HANDOFFS_AND_STORIES.md`: log, context, note, story, and handoff policy.

package/docs/planr-spec/REFERENCES.md

@@ -1,29 +0,0 @@
-# References
-
-## Official External Sources
-
-- OpenAI Codex CLI help on this machine, checked 2026-06-09 with `codex --help`, `codex exec --help`, `codex review --help`, and `codex mcp --help`.
-- OpenAI Docs MCP: https://platform.openai.com/docs/docs-mcp
-  - Used for current Codex MCP setup concept and Codex/IDE shared MCP configuration note.
-- OpenAI Codex CLI Help Center: https://help.openai.com/en/articles/11096431
-  - Used for Codex CLI local coding agent and approval workflow positioning.
-- Claude Code MCP docs: https://code.claude.com/docs/en/mcp
-  - Used for Claude Code MCP integration and project/user configuration assumptions.
-- Cursor MCP docs: https://docs.cursor.com/context/model-context-protocol
-  - Used for Cursor MCP transports, `.cursor/mcp.json`, global config, and security guidance.
-- Model Context Protocol docs: https://modelcontextprotocol.io/specification/draft/server/prompts
-  - Used for MCP prompt behavior and prompt security requirements.
-- Model Context Protocol docs: https://modelcontextprotocol.io/specification/2025-03-26/server/tools
-  - Used for MCP tool behavior and model-controlled tool concepts.
-- Model Context Protocol docs: https://modelcontextprotocol.io/specification/draft/client/elicitation
-  - Used for sensitive information constraints and elicitation safety assumptions.
-
-## Source Freshness Notes
-
-- MCP and coding-agent client behavior changes frequently. Re-check Codex, Claude Code, Cursor, and MCP docs before implementing install helpers or promising exact config commands.
-- The spec intentionally prefers stable integration concepts over vendor-specific hidden config internals.
-
-## Product Independence Notes
-
-- Planr docs, command names, assets, and implementation should remain original.
-- Any retained code or asset must have its license recorded before release.

package/docs/planr-spec/RELEASE_READINESS.md

@@ -1,95 +0,0 @@
-# Release Readiness
-
-## Release Channels
-
-- Source build from GitHub.
-- Prebuilt binaries for macOS arm64/x86_64 and Linux arm64/x86_64.
-- Homebrew formula after initial stable release.
-- npm wrapper optional only if Node-based install convenience is needed.
-
-## Versioning
-
-- Semantic versioning.
-- Database schema version stored in SQLite.
-- MCP contract version exposed by `planr mcp --version` or initialize metadata.
-
-## Packaging Requirements
-
-- REQ-REL-001: Release binaries must be checksummed.
-- REQ-REL-002: Install script must be readable, idempotent, and avoid hidden global config edits.
-- REQ-REL-003: Agent integration commands must support dry-run.
-- REQ-REL-004: Upgrade must not rewrite `.planr` files without an explicit Planr write command.
-- REQ-REL-005: Download installs must verify `SHA256SUMS` from the same release location by default.
-- REQ-REL-006: `PLANR_SKIP_CHECKSUM=1` may exist only as an explicit development-mirror escape hatch.
-- REQ-REL-007: Release docs must distinguish release installs, Homebrew after tap publication, source builds, and Windows/WSL expectations.
-
-## Upgrade Readiness
-
-- Open current Planr workspaces without rewriting Markdown artifacts.
-- Back up the SQLite database before schema upgrades.
-- Report package import/export results before mutation.
-- Provide rollback instructions for binary and database backups.
-
-## Documentation Readiness
-
-Required:
-
-- README.
-- Install guide.
-- CLI reference generated from actual help.
-- MCP integration guide.
-- Codex guide.
-- Claude Code guide.
-- Cursor guide.
-- Package import/export guide.
-- Security and privacy notes.
-- Troubleshooting/doctor guide.
-
-## Security Review
-
-Before public release:
-
-- Review install script.
-- Review MCP mutation tools.
-- Review HTTP bind/auth behavior.
-- Review log scrubbing.
-- Review secret detection.
-- Review dependency supply chain.
-
-## QA Release Checklist
-
-- `planr project init` smoke test in empty repo.
-- Package import/export smoke test.
-- Codex MCP registration smoke test.
-- Claude Code MCP config smoke test.
-- Cursor MCP config smoke test.
-- Concurrent pick test.
-- Review/fix loop test.
-- Recovery sweep test.
-- Local browser review workspace smoke test.
-- Git/PR review evidence test.
-- Export/import roundtrip test.
-- Template package import preview and confirm test.
-- `scripts/build-release.sh`, checksum verification, installer file-url smoke test, and `npm pack --dry-run`.
-
-## Rollback
-
-- Binary rollback: install previous version.
-- Database rollback: restore the automatic backup created before schema upgrades.
-- Plan files: never silently rewritten.
-
-## Legal/Platform Items
-
-- Confirm license review for any retained code, docs, or assets.
-- Ensure final product docs use Planr-owned naming, examples, and command vocabulary.
-- Ensure README states local privacy behavior clearly.
-
-## Launch Criteria
-
-- All regression reviews pass.
-- Docs cover first-run setup for Codex, Claude Code, and Cursor.
-- `planr doctor --client all` produces actionable output.
-- `planr prompt cli|mcp|http` prints actionable instructions without editing config.
-- Fresh consumer E2E passes in `~/projects/planr-test`.
-- No content telemetry.
-- Release smoke tests do not rewrite workspace files unexpectedly.

package/docs/planr-spec/SAFETY_PRIVACY_SECURITY.md

@@ -1,169 +0,0 @@
-# Safety, Privacy, And Security
-
-## Data Inventory
-
-### Project Metadata
-
-- Classification: INTERNAL.
-- Collected from: repo path, user commands.
-- Stored where: SQLite.
-- Sent to: nowhere by default.
-- Retention: until project is deleted.
-- Analytics allowed: local aggregate only.
-- Logging allowed: yes, without source content.
-
-### Map Graph
-
-- Classification: INTERNAL, may become SENSITIVE if item text includes private details.
-- Stored where: SQLite.
-- Sent to: MCP clients only when requested by local user/agent.
-- Retention: until deleted/exported.
-- Analytics allowed: counts only.
-- Logging allowed: metadata only.
-
-### Plans
-
-- Classification: INTERNAL or SENSITIVE depending on repo content.
-- Stored where: `.planr/`.
-- Sent to: local MCP clients when requested.
-- Retention: Git/repo controlled.
-- Analytics allowed: no content analytics.
-- Logging allowed: path/hash only.
-
-### Log
-
-- Classification: INTERNAL or SENSITIVE depending on content.
-- Stored where: SQLite.
-- Sent to: local clients.
-- Retention: until deleted/exported.
-- Analytics allowed: status/counts only.
-- Logging allowed: command metadata, not command output by default.
-
-### Secrets
-
-- Classification: SECRET.
-- Stored where: never in Planr.
-- Sent to: never intentionally.
-- Logging allowed: no.
-
-## Data Classification
-
-- PUBLIC: public docs, release metadata.
-- INTERNAL: item ids, statuses, event types, local metrics.
-- PERSONAL: username, machine path if it identifies a person.
-- SENSITIVE: private code plans, private tickets, prompts, transcripts, review content.
-- SECRET: tokens, API keys, credentials, signing keys.
-
-## Local Data
-
-REQ-SEC-001: Planr stores V1 data locally under the repository or configured Planr home.
-
-REQ-SEC-002: Planr must respect filesystem permissions and avoid writing outside configured paths except explicit install/config commands.
-
-## Server Data
-
-No server-side Planr storage in V1.
-
-## Third-Party/Provider Data
-
-Planr does not call AI providers by default. Agent clients may send Planr-provided context to their providers according to those clients' policies. Planr must minimize context and allow users to inspect what is returned to agents.
-
-## Analytics Data
-
-Allowed local diagnostics:
-
-- command name;
-- status code;
-- duration;
-- db schema version;
-- number of items;
-- event type;
-- client integration type.
-
-Forbidden analytics:
-
-- source code;
-- prompt/response text;
-- plan body content;
-- command output containing source or secrets;
-- secrets, tokens, env vars;
-- file contents.
-
-## Consent And Disclosure Requirements
-
-- REQ-SEC-010: Transcript capture requires explicit opt-in.
-- REQ-SEC-011: Remote HTTP mode, if added, must require explicit opt-in and authentication.
-- REQ-SEC-012: Install commands must show what files they will create or modify.
-
-## Retention Policy
-
-- SQLite map graph: retained until `planr project delete` or manual file removal.
-- `.planr` Markdown: retained under user Git/repo policy.
-- Debug logs: bounded retention; default 14 days if enabled.
-- Transcript capture: disabled by default; retention user-configurable.
-
-## Export And Deletion Policy
-
-- `planr export` must produce map graph, plans, contexts, and logs.
-- `planr project delete` must remove local database records and optionally `.planr` files with explicit confirmation.
-- `planr scrub` must detect likely secrets in contexts and logs.
-
-## Logging Policy
-
-Allowed logs:
-
-- item id;
-- project id;
-- worker id;
-- command name;
-- exit code;
-- duration;
-- status transition.
-
-Forbidden logs:
-
-- API keys and tokens;
-- env var values;
-- full prompts/responses;
-- source file content;
-- private plan body content by default.
-
-## Security Controls
-
-- REQ-SEC-020: SQLite writes must use parameterized queries.
-- REQ-SEC-021: MCP mutation tools must validate schemas and item state transitions.
-- REQ-SEC-022: HTTP server binds to localhost by default.
-- REQ-SEC-023: Shell/agent runner commands must be explicit and auditable.
-- REQ-SEC-024: Destructive operations require preview or confirmation.
-- REQ-SEC-025: Database schema upgrades must be tested against existing schemas.
-
-## Abuse Prevention
-
-Planr is local-first, so abuse risk is mostly local command execution and data exfiltration through agent clients. Mitigations:
-
-- separate read and mutation tools;
-- no implicit shell execution from plan files;
-- no hidden remote sync;
-- content minimization in MCP responses;
-- optional policy to deny mutation tools in review-only clients.
-
-## Safety Risk Taxonomy
-
-Planr is generally S1/S2:
-
-- S1: wrong item state may waste developer time.
-- S2: private code or item text may be exposed if sent to agent providers.
-
-Planr must not make medical, legal, financial, or regulated-domain decisions.
-
-## Compliance Notes
-
-- V1 does not claim SOC 2, GDPR compliance, or enterprise compliance.
-- Privacy policy and security documentation are required before any hosted service.
-
-## Legal/Platform Review Checklist
-
-- Review license obligations for any retained code, docs, or assets.
-- Review MCP tool permissions and security copy.
-- Review privacy disclosures for transcript capture.
-- Review package-manager install scripts for supply-chain risk.