planr 1.7.0 → 1.7.1

package/plugins/planr/skills/planr-loop/SKILL.md

@@ -1,119 +1,53 @@
 ---
 name: planr-loop
-description: Drive one feature or scope to verified completion without per-step human prompting. Use when the user says build until done, loop on this, or finish autonomously. Sequences plan, map, work, live verification, and independent review until the map is clean and evidence proves the feature actually runs.
+description: Drive one Planr feature or scope autonomously to audit-backed completion through scoped work, live verification, and independent review.
 ---
 
 # Planr Loop
 
-A closing loop: the agent prompts itself with Planr skills until a verifiable stop condition holds. The human supplies the goal at the start and reviews at the end; the map is the loop memory between iterations.
+This is the iteration protocol, not the re-prompting driver. Run one goal with a checkable stop condition and an iteration budget (default 10). Refuse multi-goal loops.
 
-This skill is the iteration protocol, not the driver. Whoever re-prompts the next iteration — a native loop primitive like Codex `/goal`, an automation, or a human re-dispatching `$planr-loop` — acts as the orchestrator and follows this protocol verbatim. The protocol is identical on every host; only the re-dispatch mechanism differs (see Loop Drivers).
+Evaluation subcommands run only when the user explicitly requests them, the selected item's acceptance criteria require them, or the maintainer release workflow invokes them. Never invoke them as routine or opportunistic goal, loop, or task-graph work.
 
-## Loop Contract
+## Contract And Iteration
 
-Before iterating, pin the contract:
+Recover the stored `GOAL CONTRACT <plan-id>` from Planr every iteration. If absent, store one that requires settled items with evidence, complete reviews, clear approvals, and a live oracle. Never weaken it.
 
-1. One goal: a single feature, fix scope, or build plan. Refuse multi-goal loops; split them first.
-2. A stop condition that a different agent can check from map state and evidence, not from the worker's claims.
-3. An iteration budget (default: 10 iterations). When exhausted, stop and report honestly instead of grinding.
+Each iteration follows the Planr stage protocols:
 
-Stop condition template:
+1. `planr plan audit <plan-id> --json`; `holds: true` exits.
+2. Use `$planr-plan` or `$planr-task-graph` only when scope or graph structure is missing.
+3. Dispatch `$planr-work` for exactly one ready item scoped to `<plan-id>`; makers must use `planr pick --work-type code --plan <plan-id>`, never an unscoped pick, and finish implementation with `planr done <item-id> ... --review`.
+4. Run the target-platform oracle and record `planr log add --item <id> --kind verification --summary ... --cmd ...`.
+5. Dispatch `$planr-review`; findings create fix work, while `complete --close-target` settles the target.
+6. Repeat from audit.
 
-```text
-DONE when: every in-scope map item is closed with log evidence,
-all reviews closed with verdict complete, no open approvals in scope,
-and a live verification log exists for the feature on its target platform.
-```
+One picked item per iteration. Use plain `done` only for low-signal setup/inspection work. Maker and checker stay separate when the host supports another agent; a maker never self-reviews when an independent checker is available, and never manufactures independence by changing worker identity. A worker may use `done --next`, which never returns its own review.
 
-Store the contract in Planr so it survives compaction, session loss, and host switches — chat memory is not loop memory:
+Pick packets explain null results and include `remaining`; follow their repair command. Destructive or out-of-repository effects require `planr approval request`. Two iterations without map movement must stop. On success or budget exhausted, finish with `$planr-summary`.
 
-```bash
-planr context add "GOAL CONTRACT <plan-id>: DONE when ... Iteration budget: 10." --tag goal-contract
-```
+## Provider-Neutral Dispatch
 
-`$planr-goal` does this during prep; if the loop starts without a stored contract, store it in iteration 1 before picking. Every iteration re-reads the contract from Planr (`planr context list --tag goal-contract` or `planr search "GOAL CONTRACT"`), never from chat history. `done`, `close`, and `review close` responses and the pick packet include a `remaining` progress snapshot (`counts` with explicit zeros for every status, `settled`, `total`) plus the list of items each settlement `unlocked`, so the orchestrator can evaluate the stop condition from the completion output without an extra `map status` call.
+The driver dispatches and audits; it does not implement when subagents are available. Pick packets expose provider-neutral `routing.profile`; they do not expose a host-owned `routing.agent_type`. If a generated repository role exactly matches that profile, dispatch that profile identifier as the host-native role/`agent_type`. If no matching repository role exists, keep the host's default dispatch contract and treat routing as advisory.
 
-The stop condition itself is one command: `planr plan audit <plan-id> --json` evaluates the contract clause by clause (items settled, reviews complete, approvals clear, verification logged) with evidence and answers `holds: true/false`. Use it at the top of every iteration and as the final audit — never hand-assemble the verdict from separate calls.
+Model, effort, profile, client, and fallback fields are advisory declarations and evidence labels only. Planr chooses none of them. Never infer effective model or effort from declarations. Workers report their actual profile and attach route observations when available.
 
-## Iteration Shape
+Dispatch messages stay minimal:
 
-Each iteration follows the Planr stage protocols — never a hand-written workflow prompt:
+- maker: `Use $planr-work on item <item-id>. Stop after requesting review.`
+- checker: `Use $planr-review on item <item-id>. Close the review with a verdict.`
 
-```text
-1. planr plan audit <plan-id> --json   contract holds -> exit loop ($planr-status for deeper reads)
-2. $planr-plan / $planr-task-graph   only if scope or map structure is missing
-3. $planr-work        pick exactly one ready item, implement, finish with planr done --review
-4. live verify        run the platform verification (below), log it with planr log add --kind verification
-5. $planr-review      independent audit; complete -> review close --close-target, findings -> Planr creates fix items
-6. repeat             fix items are just the next ready items
-```
+For generated Codex roles: The `spawn_agent` tool call itself must include `agent_type` set exactly to the matching `routing.profile`, `fork_turns: "none"`, a stable lowercase task name, and the maker/checker message. Read [host dispatch](references/host-dispatch.md) only when choosing host-specific wiring.
 
-The short path per item is three commands: `planr pick --json` (one flat work packet; makers add `--work-type code`), `planr done <item-id> --summary ... --cmd ... --review [--next]`, and the reviewer's `planr --json pick --work-type review` followed by `planr review close <review-id> --verdict complete --reviewer <id> --close-target` — run exactly once. Parent gates roll up automatically. When the loop runs against one plan (every `/goal` run does), add `--plan <plan-id>` to every pick so the lease never leaves the goal contract, even when other plans share the board. A null pick explains itself: when filters excluded ready work, `reason: "ready_items_excluded_by_filter"` names each excluded item, the cause (work_type or plan mismatch), and the exact `repair` pick command — run the repair instead of guessing.
+## Verification And Recovery
 
-`map build` chains created items in plan order with `blocks` links automatically and prints the created items and links. In step 2, verify that chain against real execution-order dependencies and adjust with `planr link add` only where document order and execution order differ. `item breakdown` works the same way: pass one `--into` per child title (or one value with newline-separated titles), and the output lists the chained children plus the next command.
+“Done” means the feature ran. For web dispatch `$planr-verify-web`; for CLI execute the built binary; for API use real requests; for iOS launch the simulator. Log the replayable command. If the capability is missing, record a blocker context, request approval, and pause—never fake proof.
 
-Request reviews where they carry signal: implementation slices and anything user-facing finish with `done --review`. Trivial inspection, baseline, or setup items close with plain `done` (evidence still required) — a review that can only confirm "the repo was empty" adds ceremony, not safety. The goal contract's "all reviews closed" clause audits review items that exist; plain-`done` items satisfy it without a review gate, so skipping low-signal reviews never blocks `plan audit`. In a single-agent host this bar rises: a review you close yourself mostly re-runs your own commands, so reserve gates for the riskiest slices — the core implementation and the final live verification — and close the rest with plain `done`.
-
-The loop never closes its own reviews when the host supports a second agent. Maker and checker stay separate. One agent instance keeps one `PLANR_WORKER_ID` for the whole session — never export a second identity inside the same instance to make reviews look `independent`; an honest `single_agent` stamp beats a fake `independent` one.
-
-## Skills Are The Prompts
-
-When the host supports subagents, the driver never implements: it dispatches, audits, and synthesizes. Driver tokens go into `plan audit`, dispatch decisions, and conflict resolution — implementation and review run in host-native subagent roles (see the role files and `docs/GOALS.md` "Cost Tiering"). Pick packets expose provider-neutral `routing.profile`; they do not expose a host-owned `routing.agent_type`. If an external repository declaration has generated a host role whose identifier exactly matches `routing.profile`, dispatch that profile identifier as the host-native role/`agent_type` through the host's subagent wiring. If no matching repository role exists, keep the host's default dispatch contract and treat the profile as advisory evidence only. Model, effort, profile, client, and fallback fields are advisory declarations and evidence labels only; Planr does not choose a model, choose effort, choose a client, choose a fallback, or infer that a host honored any requested value. The host owns whether and how those declarations can be honored. As the dispatching driver, read the packet with `planr pick --peek [--plan <id>]` — it returns the same packet without leasing, so the worker picks under its own identity and the maker/checker audit stays clean (never pick-and-release as the driver). Workers report the profile they actually ran on (`done --profile <id>` or `PLANR_PROFILE`) and attach route observations when available, so host overrides show up in `planr trace item` as evidence instead of being inferred from declarations. Delegate with skill references plus an item id in the message body, nothing more; host-native dispatch arguments still carry the selected role/profile and isolation controls:
-
-- Worker dispatch: `Use $planr-work on item <item-id>. Stop after requesting review.`
-- Checker dispatch: `Use $planr-review on item <item-id>. Close the review with a verdict.`
-
-A worker subagent may take several items sequentially instead of being respawned per item: `done --next` hands it the next ready work packet, keeps its context warm, and never returns its own freshly created review — maker/checker separation survives long-lived workers.
-
-Host wiring:
-
-- When external repository declarations supply host roles matching pick-packet `routing.profile` values, pass the matching profile identifier as the native host role/`agent_type` and follow the generated role instructions exactly. Otherwise treat the profile in the pick packet as advisory and use the host's current dispatch contract. Never infer effective model or effort from a declaration alone.
-- Codex with native multi-agent roles (stable multi-agent or Multi-Agent v2): generated `.codex/config.toml` roles are matching repository roles. The `spawn_agent` tool call itself must include `agent_type` set exactly to the matching `routing.profile`, `fork_turns` set to `none`, a stable lowercase `task_name`, and the dispatch message above. A default-role maker/checker spawn without `agent_type` is invalid for a generated Codex role; do not wait on it or treat it as a fallback. Do not claim role binding is unavailable for generated Codex roles, and do not substitute the role name into `task_name`, prose, worker identity, or the message body as a replacement for `agent_type`; those are not native role-binding evidence.
-- Claude Code: subagents preload via the `skills:` frontmatter field. The Planr plugin registers `planr-worker` and `planr-reviewer` automatically from its `agents/` directory; standalone installs copy them to `.claude/agents/`. The reviewer subagent is read-only except for `planr review` commands.
-- Cursor: project subagents in `.cursor/agents/*.md` (Markdown templates in `agents/` next to this skill; `planr install cursor` provisions them). Dispatch explicitly: `/planr-worker implement item X`, `/planr-reviewer review item X`. Parallel dispatches are safe — the map's pick lease keeps one owner per item.
-- Single-agent hosts: run worker and checker as separate sequential dispatches with a fresh read of map state in between; never carry the worker's self-assessment into the review step. The mode is recorded automatically: `review close` derives `review_mode` (`single_agent`/`independent`) from worker identity.
-
-## Live Verification By Platform
-
-"Done" means the feature ran, not that it compiles. Pick the verification from the plan's platform (`planr plan new ... --platform <p>`), run it inside step 4, and log the exact command and outcome:
-
-| Platform | Verification |
-| --- | --- |
-| `web` | dispatch `$planr-verify-web`: discovers the host's browser capability, runs the changed flow against the dev server, logs a replayable command |
-| `ios` | build and launch in the simulator (`xcodebuild` + `xcrun simctl`), exercise the changed flow |
-| `cli` | execute the built binary with the real flags the feature added; assert on output |
-| `api`/`backend` | start the service, hit the changed endpoints with real requests, assert responses |
-
-```bash
-planr log add --item <item-id> --kind verification \
-  --summary "live verification on <platform>: <observed outcome>" \
-  --cmd "<exact command actually run>"
-```
-
-`--kind verification` is what `plan audit` checks for its `verification_logged` clause. Log the final passing run; a transient failure you immediately fixed belongs in the summary narrative, not as a separate failure log.
-
-If the needed capability is missing (no simulator, no browser tooling), do not fake it: log the gap as context, request human approval, and pause the loop:
-
-```bash
-planr context add "live verification blocked: <missing capability>" --item <item-id> --tag blocker
-planr approval request <item-id> --reason "manual live verification required"
-```
-
-## Loop Drivers
-
-Prefer the host's loop primitive over a bash while-loop so a separate model checks the stop condition. The driver supplies continuation pressure; Planr supplies everything else (state, evidence, reviews, recovery), so the loop works on every host:
-
-- Codex: `/goal Use $planr-loop on plan <plan-id>. The loop contract is stored in planr context (tag: goal-contract).` — or an Automation with the same prompt. Full workflow: `docs/GOALS.md` in the Planr repository.
-- Claude Code: `/goal` with the same prompt shape, or `/loop` for a fixed cadence.
-- Cursor: no /goal primitive; re-dispatch `Use $planr-loop on plan <plan-id> ...` manually or per session. Within a session the loop dispatches the provisioned `/planr-worker` and `/planr-reviewer` subagents per item.
-- Anywhere else (plain MCP clients, hosts without /goal): re-dispatch `Use $planr-loop on plan <plan-id> ...` manually or per session. Nothing is lost except automatic re-prompting.
-
-Recovery is the same in all cases: a fresh session starts at step 1 (`$planr-status`), reads the map and the stored goal-contract, and continues exactly where the last iteration stopped — zero chat context required.
+Recovery starts in a fresh session with audit, map state, the stored contract, and the next scoped pick. Read [recovery and platform details](references/recovery-and-verification.md) only when that branch is active.
 
 ## Hard Rules
 
-- One picked item per iteration. Parallel work needs separate worktrees and separate loop instances.
-- Every iteration must move map state (a log, a review verdict, a closed item, or a recorded blocker). Two iterations without state movement -> stop and report.
-- Never weaken the stop condition mid-loop. Scope changes go through `$planr-plan` and the user.
-- Destructive or out-of-repo side effects (deploys, migrations, infra) always go behind `planr approval request`.
-- On exit — success or budget exhausted — finish with `$planr-summary` so the human gets an evidence-backed account.
+- Keep one active write item unless separate worktrees and loop instances were explicitly authorized.
+- Scope changes go through `$planr-plan` and the user.
+- Do not close your own review when independent review is available.
+- Keep final claims aligned with map, logs, approvals, reviews, and oracle evidence.

package/plugins/planr/skills/planr-loop/agents/planr-worker.md

@@ -3,7 +3,7 @@ name: planr-worker
 description: Implements exactly one picked Planr map item to evidence-backed completion, then requests review and stops. Dispatch with the item id.
 # Cost tiering: the pick packet bounds the worker's scope, so it can run on a
 # cheaper tier than the driver. Replace inherit with a cheaper Cursor model id
-# when dispatch cost matters. See docs/GOALS.md "Cost Tiering".
+# when dispatch cost matters. See https://planr.so/docs/agents/skills#cost-tiering.
 model: inherit
 ---
 

package/plugins/planr/skills/planr-loop/references/host-dispatch.md

@@ -0,0 +1,10 @@
+# Host Dispatch
+
+Load this only when the loop has subagents and must bind a provider-neutral Planr profile to host-native dispatch.
+
+- Codex: generated `.codex/config.toml` roles are native roles. Bind the exact matching `routing.profile` as `agent_type` with `fork_turns: "none"`. Do not replace binding with prose, `task_name`, or worker identity, and do not wait on an invalid default-role spawn when a generated role is required.
+- Claude Code: plugin agents preload the worker/reviewer skills; standalone installs provision `.claude/agents/`.
+- Cursor: dispatch the provisioned `.cursor/agents/planr-worker.md` and `planr-reviewer.md` roles explicitly.
+- Single-agent hosts: use separate sequential maker/checker passes with a fresh map read; Planr records `single_agent` honestly.
+
+The driver should inspect routing with `planr pick --peek --plan <plan-id>` so the worker takes the actual lease. Host declarations are requests, never proof. Record observed profile/route evidence through worker completion metadata.

package/plugins/planr/skills/planr-loop/references/recovery-and-verification.md

@@ -0,0 +1,24 @@
+# Recovery And Verification
+
+Load this only for an interrupted item or the live-verification stage.
+
+Recovery:
+
+```bash
+planr plan audit <plan-id> --json
+planr trace item <item-id> --json
+planr log list --item <item-id> --json
+planr context list --item <item-id> --json
+```
+
+Use `planr pick stale --older-than-seconds 900` before releasing abandoned ownership. Pause a legitimate wait with `planr pick pause`; resume it with `planr pick resume`.
+
+Verification:
+
+```bash
+planr log add --item <item-id> --kind verification \
+  --summary "verified <flow>: <observed outcome>" \
+  --cmd "<exact replayable command>"
+```
+
+Use browser automation for web, the built binary for CLI, real requests for API/backend, and simulator launch plus exercised flow for iOS. If tooling is unavailable, store blocker context, request approval, and pause.

package/plugins/planr/skills/planr-task-graph/SKILL.md

@@ -1,22 +1,17 @@
 ---
 name: planr-task-graph
-description: Use Planr as the live local task graph for coding-agent coordination. Trigger when work needs project planning, build-plan splitting, map creation, dependency links, picking, log-backed closure, review gates, handoff context, interruption recovery, or multi-client coordination.
+description: Coordinate Planr plans, map dependencies, leases, evidence, approvals, reviews, handoffs, and interruption recovery.
 ---
 
 # Planr Task Graph
 
-Use `planr` as the canonical local coordination system for this repository.
+Use Planr as the canonical local coordinator. Markdown plans own scope and narrative; the map is the source of truth for live items, links, picks, approvals, logs, reviews, and closure.
 
-Planr has two first-class layers:
+Evaluation subcommands run only when the user explicitly requests them, the selected item's acceptance criteria require them, or the maintainer release workflow invokes them. Never invoke them as routine or opportunistic goal, loop, or task-graph work.
 
-- Markdown plans for product context, build scope, verification, and narrative decisions.
-- SQLite map state for items, links, picks, runtime heartbeats, approvals, contexts, logs, reviews, runs, and closure.
+## Inspect And Work
 
-The map is the source of truth for live state. Markdown explains scope and acceptance.
-
-## Start Here
-
-Inspect the project and map before changing work:
+Before changes:
 
 ```bash
 planr project show --json
@@ -25,206 +20,42 @@ planr map lane --critical
 planr map pressure
 ```
 
-If no project exists:
-
-```bash
-planr project init "Project Name" --client all
-planr doctor --client all
-```
-
-## Core Loop
+If missing, initialize the project and run `planr doctor --client all`.
 
-Use one item at a time. The short path is two commands per step:
+Work one item at a time:
 
 ```bash
 planr pick --json
-planr done <item-id> --summary "what changed" --files a --files b --cmd "exact verification command" --tests "exact test command" --review [--next]
-```
-
-`pick --json` returns one flat work packet (item, links, logs, runtime, recovery, conditions, recall context, `remaining` progress); empty collections are omitted. `done` writes the completion log (test runs belong in `--tests`, build/serve commands in `--cmd`), requests review (`--review`, which moves the item to `in_review`) or closes directly, and `--next` picks the following item. Evidence logs refresh the heartbeat automatically.
-
-For longer work, keep the live claim visible:
-
-```bash
-planr pick progress <item-id> --percent 50 --note "tests running"
-planr pick pause <item-id> --note "waiting for human input"
-planr pick resume <item-id>
+planr done <item-id> --summary "<outcome and decisive result>" \
+  --files <path> --cmd "<build or live command>" \
+  --tests "<test command>" --review
 ```
 
-Capture decisions and discoveries another agent may need:
+Every closure must be evidence-backed: changed files through `--files`, commands through `--cmd`, tests through `--tests`, remaining risk through context or findings, and review outcome through `planr review`. Use plain `done` only when review has no signal. Keep longer work current with `planr pick progress`, `pause`, and `resume`.
 
-```bash
-planr context add "decision or discovery" --item <item-id> --tag discovery
-```
+## Plans And Dependencies
 
-Record evidence before review:
+Create/refine/check the plan, expand it into independently verifiable tasks, then `planr map build --from <plan-id>`. Annotate routed work types before mapping or retag afterward.
 
-```bash
-planr log add --item <item-id> \
-  --summary "what changed" \
-  --files file-a,file-b \
-  --cmd "exact verification command"
-```
+Create ordering explicitly with `planr link add <earlier> <later> --type blocks`; readiness comes from graph state, not Markdown checkboxes. Validate generated order and remove only incorrect links. Use `planr item breakdown <parent> --into <child>...` for a parent gate; later top-level work depends on the parent, which rolls up after children settle.
 
-Granular alternative: request review, close review, then close the item:
+## Reviews And Approvals
 
-```bash
-planr review request <item-id>
-planr review close <review-id> --verdict complete --close-target
-planr close <item-id> --summary "Verified with evidence"
-```
+Request review after completion evidence. A complete review may use `planr review close <review-id> --verdict complete --close-target`. Findings use `--verdict not-complete`; Planr creates fix and follow-up review work.
 
-`--close-target` closes the reviewed item together with the review when the verdict is complete and a completion log exists; the separate `planr close` is then unnecessary.
+Human gates use `planr approval request <item-id> --reason <reason>`. Never close with an open or denied approval.
 
-If human approval is part of the gate, request it and do not close until it is approved:
+## Handoff And Recovery
 
-```bash
-planr approval request <item-id> --reason "release approval"
-planr approval list --open
-```
+Use item notes for nearby handoff and contexts for reusable decisions. Logs are evidence, not chat summaries.
 
-If review finds issues:
-
-```bash
-planr review close <review-id> \
-  --verdict not-complete \
-  --findings "specific actionable finding"
-planr map show --json
-planr pick --json
-```
-
-Planr creates fix and follow-up review work instead of pretending the parent item is done.
-
-## Planning Flow
-
-For broad app or product work:
-
-```bash
-planr plan new "App idea" --platform web --ai --backend
-planr plan refine <plan-id> --note "Assumption or decision"
-planr plan split <plan-id> --slice "MVP implementation"
-planr plan check <build-plan-id>
-planr map build --from <build-plan-id>
-```
-
-Product plan work lists are candidates. They become live commitments only after `planr map build --from ...`.
-
-`map build` creates items without ordering: everything starts ready. Linking is mandatory before the first pick — add a `blocks` link for every real execution dependency:
-
-```bash
-planr link add <earlier-item> <later-item> --type blocks
-planr map lane --critical
-```
-
-Do not pick from a freshly built map that has zero links unless the items are genuinely independent.
-
-When `planr agents list --json` shows routes with use-case `work_type` selectors (e.g. `frontend`, `backend`), retag freshly built items to match their work (`planr item update <id> --work-type frontend`) so pick packets carry the declared profile, model, and paired skill. This is the agent's job — never the user's; items matching no route keep `code` and fall to the default route.
-
-## Parent Gate Pattern
-
-Model material changes as parent gates. The parent is the completion gate; linked children do the work.
-
-Default shape:
-
-```text
-parent gate
-`- implementation or test child
-   `- review item linked to that child
-      |- pass -> child can close -> parent gate auto-closes
-      `- findings -> fix item -> follow-up review -> ...
-```
-
-Rules:
-
-- create a parent item for the change;
-- use `planr item breakdown <parent-id> --into "Implement" --into "Verify"` (one `--into` per child; a single value may also pack newline- or comma-separated titles) to create chained child work under that parent — the output lists every child with id and status plus the next pick command;
-- request review on the implementation or test child after evidence exists;
-- if review finds issues, let Planr create fix and follow-up review work from the review verdict;
-- make later top-level work depend on the parent gate, not only the first child.
-
-Parent gates roll up on their own: when every child is settled, the gate auto-closes unless a review or approval on the gate itself is still open. Do not pick a parent gate as work; `planr pick` skips them.
-
-## Dependencies
-
-Create ordering explicitly:
-
-```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
-```
-
-Readiness comes from graph links and item state, not Markdown checkboxes.
-
-Use:
-
-```bash
-planr item breakdown <item-id> --into "Trace owner" --into "Implement" --into "Verify"
-planr link remove <from-item> <to-item> --type blocks
-```
-
-## Handoff Evidence
-
-Every closure must be evidence-backed:
-
-- changed files through `--files`;
-- commands through `--cmd`;
-- tests through `--tests`;
-- remaining risks through context, notes, or findings;
-- review outcome through `planr review ...`.
-
-Use task-local notes for nearby handoff:
-
-```bash
-planr note add "Reviewer asked for an extra package dry-run before closure." --item <item-id>
-```
-
-Use contexts for reusable project knowledge:
-
-```bash
-planr context add "Do not edit global client config without explicit operator approval." --tag constraint
-```
-
-Use a story log only when map state, logs, and contexts are too thin to preserve the decision chain. Story logs are narrative memory, not status authority.
-
-## Recovery
-
-After interruption or handoff:
-
-```bash
-git status --short
-planr project show --json
-planr map show --json
-planr map lane --critical
-planr map pressure
-```
-
-Then inspect the item:
+After interruption inspect Git status, map state, then:
 
 ```bash
 planr trace item <item-id>
 planr log list --item <item-id>
 planr context list --item <item-id>
-```
-
-If a stale pick must be reset:
-
-```bash
 planr pick stale --older-than-seconds 900
-planr pick stale --older-than-seconds 900 --release
-planr pick release <item-id> --force
 ```
 
-## Completion Rule
-
-Do not call work complete until:
-
-- required child and review items are closed;
-- approval gates are approved or absent;
-- log evidence exists;
-- verification commands were actually run;
-- review findings are closed or converted into follow-up work;
-- `planr map show --json` shows no in-scope blocker;
-- the user-facing summary matches map, logs, and review state.
-
-For release-grade scopes, rerun the full verification ladder from the repository testing guide.
+Release stale ownership only after inspection. Do not claim completion until children and reviews are closed, approvals are clear, verification commands ran, findings became settled follow-up work, and the user-facing summary matches Planr state.

package/docs/CI.md

@@ -1,55 +0,0 @@
-# CI
-
-Planr CI is defined in `.github/workflows/ci.yml` and `.github/workflows/security.yml`.
-
-## Required Gates
-
-The main CI workflow runs:
-
-```bash
-cargo fmt --check
-cargo clippy --all-targets -- -D warnings
-cargo test
-shellcheck scripts/*.sh
-cargo build --release
-npm pack --dry-run
-node npm/bin/planr.js --version
-cargo audit --deny warnings
-```
-
-The security workflow runs a GitHub Actions security scan with pinned `zizmor`.
-
-## Local Reproduction
-
-Run the full local gate:
-
-```bash
-scripts/ci-local.sh
-```
-
-`scripts/ci-local.sh` also runs the external consumer E2E project when the sibling `planr-test` checkout exists. Override its location with `PLANR_TEST_DIR`:
-
-```bash
-PLANR_TEST_DIR=/path/to/planr-test scripts/ci-local.sh
-cd /path/to/planr-test
-npm test
-npm run test:npm-planr
-```
-
-Run local security and leak checks:
-
-```bash
-npm run security:check
-```
-
-This checks tracked files for machine-specific home paths, rejects forbidden staged paths, uses BetterLeaks for secret history scanning, and runs Trivy for filesystem vulnerability, secret, and misconfiguration scanning. If Lefthook is installed, run `lefthook install` once to activate the staged-path guard for commits and pushes.
-
-## Supply Chain
-
-Dependabot is configured in `.github/dependabot.yml` for:
-
-- Cargo dependencies
-- npm dependencies
-- GitHub Actions
-
-GitHub Actions use read-only default permissions and pin checkout by commit SHA.

package/docs/CLAUDE_CODE.md

@@ -1,52 +0,0 @@
-# Claude Code Integration
-
-## Plugin (preferred for skills)
-
-The Planr repository is a Claude Code plugin. Install it to get the skills (namespaced as `/planr:planr`, `/planr:planr-loop`, ...) plus the `planr-worker` and `planr-reviewer` subagents:
-
-```text
-/plugin marketplace add instructa/planr
-/plugin install planr@planr
-```
-
-See [Skills](SKILLS.md) for the skill workflow. For autonomous goal runs with `/goal` or `/loop` on top of Planr state, see [Long-Running Goals](GOALS.md).
-
-## Long-Running Goals With `/goal`
-
-Claude Code `/goal` drives autonomous Planr runs the same way Codex does: `/goal` supplies continuation pressure, Planr supplies durable state, evidence, reviews, and recovery. Run the driver session on your strongest model (`/model fable`, `/effort high`), prep once, then start:
-
-```text
-/planr:planr-goal <your goal>
-/goal Use $planr-loop on plan <plan-id>. The loop contract is stored in planr context (tag: goal-contract). Continue until the contract holds or the iteration budget is exhausted. You are operating autonomously: the user is not watching, so never end a turn on a plan, a question, or a promise — proceed until the contract holds or you are blocked on input only the user can provide.
-```
-
-The plugin registers the `planr-worker` and `planr-reviewer` subagents automatically. The worker pins a cheaper tier in its frontmatter; the reviewer deliberately inherits the driver's model:
-
-```yaml
-# planr-worker.md frontmatter
-model: opus      # alias tracks the current generation; budget alternative: sonnet
-effort: medium
-```
-
-Verify the pin once: `CLAUDE_CODE_SUBAGENT_MODEL` must be unset (it silently overrides all subagent frontmatter), then dispatch the worker on a trivial item and confirm the subagent's messages in `~/.claude/projects/<project>/*.jsonl` carry the worker model. Full workflow, recovery, and the tiering rationale: [Long-Running Goals](GOALS.md).
-
-## MCP
-
-```bash
-planr install claude --dry-run
-planr install claude
-planr doctor --client claude
-```
-
-Dry-run prints both project-scope `.mcp.json` content and the optional user-scope CLI form. The non-dry command writes this repository's `.mcp.json`, standalone worker/reviewer roles, and additive fail-open session hooks. Workflow skills and plugin agents come from the Claude Code plugin. Use `--no-mcp` to omit `.mcp.json`, or `--no-hooks` to omit hook reconciliation.
-
-Claude Code should treat Planr map state as authoritative and use Markdown plans as context.
-
-For repo-local review feedback, write JSON to a file and ingest it:
-
-```bash
-planr review ingest <item-id> --from .planr/tmp/claude-review.json
-planr review artifact <review-item-id>
-```
-
-Planr does not edit global Claude Code configuration. Project hooks live in `.claude/settings.json`, preserve foreign entries, and can be omitted with `--no-hooks`. The review item remains open until `planr review close` records the final verdict.