planr 0.0.1 → 1.1.16

package/docs/planr-spec/CLIENT_IMPLEMENTATION_SPEC.md

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

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

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

package/docs/planr-spec/QA_ACCEPTANCE_TESTS.md

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

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

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