planr 1.6.0 → 1.7.1

package/docs/documentation/CONTRACT.md

@@ -4,16 +4,16 @@ Status: approved implementation contract for the Planr documentation site
 Last audited: 2026-07-17
 Scope owner: `apps/docs` (site and English product documentation)
 
-This contract turns the current product, runtime, and repository documentation into one maintainable public documentation system. It is intentionally separate from the product specification package: `docs/planr-spec/` remains the product source of truth, while the site explains the released product to users and contributors.
+This contract turns the current product, runtime, and repository documentation into one maintainable public documentation system. It is intentionally separate from the product specification package: `.planr/plans/product/planr/` remains the product source of truth, while the site explains the released product to users and contributors.
 
 ## Source hierarchy
 
 When sources disagree, authors must use this order and disclose the disagreement instead of silently choosing convenient copy:
 
-1. **Product intent and invariants:** `AGENTS.md` and `docs/planr-spec/`, especially `PRODUCT_SPEC.md`, `TECH_ARCHITECTURE.md`, and `API_AND_DATA_MODEL.md`.
+1. **Product intent and invariants:** `AGENTS.md` and `.planr/plans/product/planr/`, especially `PRODUCT_SPEC.md`, `TECH_ARCHITECTURE.md`, and `API_AND_DATA_MODEL.md`.
 2. **Released executable behavior:** compiled `planr --help` output, `src/cli.rs`, `src/app/mcp.rs`, `src/app/http.rs`, `src/model.rs`, and the tested fixture `docs/fixtures/mcp-contract.json`. Runtime sources decide whether a command, option, schema, endpoint, state, or error exists in the current release.
 3. **Distribution contract:** `Cargo.toml`, `package.json`, `pnpm-workspace.yaml`, release workflows, installers, and release tests. These decide supported versions, artifacts, operating systems, and install commands.
-4. **Existing explanatory material:** `README.md`, `docs/*.md`, `plugins/planr/skills/`, and examples. These are migration inputs, not independent sources of truth.
+4. **Existing explanatory material:** `README.md`, `plugins/planr/skills/`, and examples. These explain and point at the site; they are not independent sources of truth.
 5. **External references:** official upstream documentation and inspected local projects may influence structure and implementation, but never define Planr behavior.
 
 If product intent is ahead of runtime, the public page must label the behavior as planned or omit it from executable instructions. If runtime is ahead of an older specification sentence, the public page documents the tested runtime and the discrepancy is added to the conflict register below.
@@ -83,7 +83,7 @@ Do not use `latest`, caret, tilde, or wildcard ranges for direct docs dependenci
 
 ### DOC-ADR-001: One first-class workspace app
 
-Create one English documentation application at `apps/docs`. It owns the public landing page, guides, reference, search, metadata, and deployment. Existing `docs/*.md` files remain source/reference material during migration; once a topic has a canonical site page, the old file becomes either a concise pointer or a checked redirect source, not a second maintained copy.
+Create one English documentation application at `apps/docs`. It owns the public landing page, guides, reference, search, metadata, and deployment. The migration completed on 2026-07-25: the flat topic guides under `docs/` were removed once the site owned their topics, so no topic has a second maintained copy. `docs/` retains only non-site material — architecture ownership, the release runbook, frozen contracts, documentation governance, and test fixtures.
 
 ### DOC-ADR-002: Next.js App Router with local MDX
 
@@ -135,10 +135,10 @@ These findings are explicit inputs to implementation and content review.
 
 | ID | Finding | Resolution in the site |
 | --- | --- | --- |
-| GAP-001 | `docs/CLI_REFERENCE.md` says it is generated from help but omits current commands including `project delete`, `plan list`, `map export/import`, `item show/cancel`, `link remove`, `log show/list`, `review request/list/show`, `note`, and `scrub`. | Replace the list with generated/mechanically checked reference data; retain editorial detail around it. |
-| GAP-002 | `docs/planr-spec/PRODUCT_SPEC.md` still calls Rust and the HTTP server open decisions, but the repository ships a Rust binary and `planr serve`. | Document current released behavior; update product specs only in a separately scoped product-spec change. |
+| GAP-001 | Resolved on 2026-07-25: the flat `docs/CLI_REFERENCE.md` was removed after `/docs/reference/cli` plus the mechanically checked `/docs/reference/cli-generated` took over command coverage. | Keep command inventory generated from the binary; never reintroduce a hand-maintained command list. |
+| GAP-002 | `.planr/plans/product/planr/PRODUCT_SPEC.md` still calls Rust and the HTTP server open decisions, but the repository ships a Rust binary and `planr serve`. | Document current released behavior; update product specs only in a separately scoped product-spec change. |
 | GAP-003 | Resolved on 2026-07-18: `docs/ARCHITECTURE.md` now describes Planr as one Rust binary plus wrappers/docs, with provider-neutral routing declarations owned in Core and external routing lifecycle outside Planr. | Keep architecture ownership aligned with current runtime modules and do not reintroduce routing-package ownership wording. |
-| GAP-004 | README leads with Homebrew, while `docs/INSTALL.md` calls GitHub Releases/repo installer canonical and Homebrew preferred day-to-day. | Say “Homebrew recommended on macOS”; GitHub Releases are the canonical artifact source; npm is the cross-package-manager native-binary path. |
+| GAP-004 | Resolved on 2026-07-25: the flat install guide was removed, so `/docs/getting-started/installation` is the single install owner. | Say “Homebrew recommended on macOS”; GitHub Releases are the canonical artifact source; npm is the cross-package-manager native-binary path. |
 | GAP-005 | The CLI npm wrapper supports Node 18, while latest Fumadocs requires Node 22. | Keep separate requirement callouts: Planr CLI Node 18; docs contributors Node 22. |
 | GAP-006 | Product personas mention Gemini CLI and generic clients, but install helpers exist only for Codex, Claude Code, and Cursor. | Give the three supported clients first-class setup pages; route Gemini/opencode/other tools through clearly labeled generic CLI or stdio MCP instructions. Do not imply a native installer. |
 | GAP-007 | `planr install` uses the subcommand `claude`, while product prose often says “Claude Code”. | Use “Claude Code” in headings and `planr install claude` in commands. |

package/docs/documentation/COVERAGE.md

@@ -4,7 +4,7 @@ This is the canonical inventory that maps shipped public surfaces to repository
 
 ## Published route inventory
 
-The site currently owns 59 MDX routes. Next.js also emits the landing page and framework support routes during the production build.
+The site currently owns 61 MDX routes. Next.js also emits the landing page and framework support routes during the production build.
 
 | Section | Published routes |
 | --- | --- |
@@ -12,6 +12,7 @@ The site currently owns 59 MDX routes. Next.js also emits the landing page and f
 | Getting started | `/docs/getting-started`, `/docs/getting-started/why-planr`, `/docs/getting-started/installation`, `/docs/getting-started/quickstart`, `/docs/getting-started/full-lifecycle`, `/docs/getting-started/choose-your-interface` |
 | For Agents | `/docs/agents`, `/docs/agents/quickstart`, `/docs/agents/prompt-recipes`, `/docs/agents/skills` |
 | Integrations | `/docs/integrations`, `/docs/integrations/codex`, `/docs/integrations/claude-code`, `/docs/integrations/cursor`, `/docs/integrations/generic-mcp`, `/docs/integrations/cli-only` |
+| Plugins | `/docs/plugins`, `/docs/plugins/switchloom` |
 | Concepts | `/docs/concepts`, `/docs/concepts/local-first-model`, `/docs/concepts/plans-and-map`, `/docs/concepts/graph-and-readiness`, `/docs/concepts/picks-and-leases`, `/docs/concepts/evidence-and-context`, `/docs/concepts/reviews-and-approvals`, `/docs/concepts/recovery-packages-and-closure` |
 | Guides | `/docs/guides`, `/docs/guides/daily-worker-loop`, `/docs/guides/parallel-coordination`, `/docs/guides/handoff-and-resume`, `/docs/guides/review-and-fix-loops`, `/docs/guides/recover-interrupted-work`, `/docs/guides/packages-and-reuse`, `/docs/guides/recipes` |
 | Reference | `/docs/reference`, `/docs/reference/cli`, `/docs/reference/cli-generated`, `/docs/reference/mcp`, `/docs/reference/mcp-schemas-generated`, `/docs/reference/http-api`, `/docs/reference/configuration-and-storage`, `/docs/reference/data-and-status`, `/docs/reference/outputs-and-errors`, `/docs/reference/support-matrix`, `/docs/reference/maintenance` |
@@ -23,7 +24,7 @@ The site currently owns 59 MDX routes. Next.js also emits the landing page and f
 
 | Surface | Canonical owner | Published route(s) |
 | --- | --- | --- |
-| Promise, users, non-goals | `docs/planr-spec/PRODUCT_SPEC.md` | `/docs/getting-started/why-planr` |
+| Promise, users, non-goals | `.planr/plans/product/planr/PRODUCT_SPEC.md` | `/docs/getting-started/why-planr` |
 | Install, first success, full lifecycle | manifests, installers, `src/cli.rs`, E2E tests | `/docs/getting-started/installation`, `/docs/getting-started/quickstart`, `/docs/getting-started/full-lifecycle` |
 | Agent setup, public routing, and prompt recipes | typed client/prompt contracts and installed Planr skills | `/docs/agents`, `/docs/agents/quickstart`, `/docs/agents/prompt-recipes`, `/docs/agents/skills` |
 | Local-first authority and boundaries | product/data specs, `src/storage/` | `/docs/concepts/local-first-model` |
@@ -59,6 +60,7 @@ The executable and schema sources decide exact inventory. Editorial pages explai
 | Homebrew, install script, npm, source build | release manifests, `scripts/install.sh`, npm wrapper | `/docs/getting-started/installation` |
 | Interface selection and client differences | integration descriptors and installers | `/docs/getting-started/choose-your-interface`, `/docs/integrations` |
 | Agent-led setup and autonomous handoff | typed onboarding prompts and Planr goal/loop contracts | `/docs/agents/quickstart`, `/docs/agents/prompt-recipes` |
+| Optional external plugins | external lifecycle documentation and provider-neutral routing boundaries | `/docs/plugins`, `/docs/plugins/switchloom` |
 | Codex | Codex manifest, generated role/install assets | `/docs/integrations/codex` |
 | Claude Code | Claude manifest, generated role/install assets | `/docs/integrations/claude-code` |
 | Cursor | Cursor manifest, role/skill/install assets | `/docs/integrations/cursor` |
@@ -84,7 +86,7 @@ The executable and schema sources decide exact inventory. Editorial pages explai
 
 ## Audit completion checklist
 
-- [x] All 59 current MDX routes are explicitly inventoried.
+- [x] All 61 current MDX routes are explicitly inventoried.
 - [x] Every public product, CLI, MCP, HTTP, data, client, contributor, and operations surface has a current target and canonical source owner.
 - [x] Generated CLI and MCP inventories are separated from editorial guidance and mechanically checked.
 - [x] Retired aliases are isolated in `apps/docs/redirects.mjs` and resolve to a current route.

package/docs/documentation/INFORMATION_ARCHITECTURE.md

@@ -13,13 +13,14 @@ This file records the implemented route and navigation contract. Routes are publ
 | worker/operator | `/docs/guides/daily-worker-loop` -> `/docs/guides/parallel-coordination` | Picks without collisions and records durable evidence. |
 | reviewer | `/docs/concepts/reviews-and-approvals` -> `/docs/guides/review-and-fix-loops` | Closes a complete gate or creates a bounded fix chain. |
 | client integrator | `/docs/integrations` -> one client page | Connects through a supported CLI or stdio MCP path. |
+| plugin operator | `/docs/plugins` -> one plugin page | Uses an optional external lifecycle without confusing it with Planr Core ownership. |
 | API toolsmith | `/docs/reference/mcp` or `/docs/reference/http-api` | Uses the current schema and transport boundary. |
 | contributor | `/docs/contributing` -> setup/architecture/testing | Places and verifies a change without tribal knowledge. |
 | maintainer | `/docs/operations` | Can release, deploy, diagnose, roll back, and review freshness. |
 
 ## Implemented route tree
 
-The 59 MDX files below are the current page tree and must agree with every `meta.json` file and `COVERAGE.md`.
+The 61 MDX files below are the current page tree and must agree with every `meta.json` file and `COVERAGE.md`.
 
 ```text
 /docs
@@ -39,6 +40,8 @@ The 59 MDX files below are the current page tree and must agree with every `meta
 │   ├── cursor
 │   ├── generic-mcp
 │   └── cli-only
+├── plugins
+│   └── switchloom
 ├── concepts
 │   ├── local-first-model
 │   ├── plans-and-map
@@ -142,6 +145,6 @@ The inventory covers these retired route families:
 | `/docs/reference/routing-bundles` | `/docs/reference/configuration-and-storage` |
 | `/docs/reference/platform-support` | `/docs/reference/support-matrix` |
 
-Repository files such as `docs/INSTALL.md` are not former website URLs. They remain GitHub-readable source material and must link to the current site rather than pretending a Next.js redirect can intercept a repository path.
+Repository Markdown files are not former website URLs, so a Next.js redirect can never intercept a repository path. The flat topic guides that once duplicated site pages were removed on 2026-07-25; `README.md` and the remaining repository files link to the current site instead of restating it. `docs/` now keeps only what the site does not own: `docs/ARCHITECTURE.md`, `docs/RELEASE.md`, `docs/contracts/`, `docs/documentation/`, and `docs/fixtures/`.
 
 To retire another route: add exactly one alias, choose the closest current outcome page, update this table, repair internal links, run the maintenance and browser gates, and retain the redirect while supported inbound links may exist. Never redirect an unknown path to a generic landing page merely to hide a 404.

package/docs/fixtures/mcp-contract.json

@@ -42,6 +42,14 @@
     "planr_artifact_show",
     "planr_event_list",
     "planr_debug_bundle",
+    "planr_eval_suite_check",
+    "planr_eval_run",
+    "planr_eval_show",
+    "planr_eval_compare",
+    "planr_eval_gate",
+    "planr_eval_invalidate",
+    "planr_eval_rescore",
+    "planr_eval_evidence_ref",
     "planr_log_add",
     "planr_review_annotate",
     "planr_review_ingest",
@@ -100,6 +108,10 @@
     "planr review artifact",
     "planr review evidence",
     "planr review close",
+    "planr eval suite-check",
+    "planr eval compare",
+    "planr eval gate",
+    "planr eval evidence-ref",
     "planr recover sweep",
     "planr agents list",
     "planr agents check",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "description": "Local-first planning and execution coordination for coding agents.",
   "license": "MIT",
   "repository": {
@@ -20,8 +20,12 @@
     "docs"
   ],
   "scripts": {
+    "security:check": "sh scripts/security-local.sh",
+    "security:privacy": "sh scripts/check-repository-privacy.sh",
+    "security:staged": "node scripts/hooks/block-forbidden-staged-files.mjs",
     "build:native": "cargo build --release",
     "test": "cargo test",
+    "verify:release-eval-gate": "node scripts/test-release-eval-gate.mjs",
     "pack:check": "npm pack --dry-run",
     "docs:dev": "pnpm --filter @planr/docs dev",
     "docs:alchemy:dev": "pnpm --filter @planr/docs alchemy:dev",

package/plugins/planr/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "planr",
   "description": "Skill-driven planning and execution loop for coding agents: one planr entry point, an autonomous planr-loop, and evidence-backed task graph skills powered by the planr CLI.",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "author": {
     "name": "instructa"
   },

package/plugins/planr/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "description": "Skill-driven planning and execution loop for coding agents: one $planr entry point, an autonomous $planr-loop, and evidence-backed task graph skills powered by the planr CLI.",
   "author": {
     "name": "instructa",

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

@@ -6,7 +6,7 @@ skills:
 # Cost tiering: the pick packet bounds the worker's scope, so it runs on a
 # cheaper tier than the driver. Aliases track the current generation; pin a
 # full model id (e.g. claude-opus-4-8) only if you need determinism. Budget
-# alternative: model: sonnet. See docs/GOALS.md "Cost Tiering".
+# alternative: model: sonnet. See https://planr.so/docs/agents/skills#cost-tiering.
 model: opus
 effort: medium
 ---

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

@@ -1,75 +1,47 @@
 ---
 name: planr-goal
-description: Prepare a long-running goal for autonomous execution on Planr. Use when the user states a broad goal, wants to start a /goal run, or asks to set up a goal. Compiles intent into a checked plan, a linked map, and a durable goal contract, then prints the starter command for the host's loop driver without implementing anything.
+description: Prepare a long-running Planr goal as a checked plan, linked map, durable contract, and loop handoff without implementing it.
 ---
 
 # Planr Goal
 
-Prep only. This skill compiles a goal into durable Planr state and stops. Execution belongs to the host's loop driver — Codex or Claude Code `/goal`, an automation, or repeated `$planr-loop` dispatches. This boundary is strict: goal prep is a board compiler, not a lightweight loop.
+Prep only. Compile intent into durable Planr state, then stop. During goal prep, do not implement, refactor, verify, or touch product code. Allowed work is reading Planr state, clarifying material ambiguity, creating/refining/checking plans, building/linking the map, storing the contract, and printing the loop handoff.
 
-## Boundary
-
-During a goal-prep turn, do not implement, refactor, verify, or touch product code — even when the work looks read-only or obviously useful. That work belongs to the loop run. Allowed actions: read Planr state, ask intake questions, create/refine/check plans, build and link the map, store the goal contract, print the starter command.
+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.
 
 ## Intake
 
-Classify the input before creating anything:
-
-- specific: outcome and proof are clear -> compile directly.
-- vague: ask at most two material questions (which outcome matters most? what proof would convince you it works?), then proceed with labeled assumptions recorded as `plan refine` notes.
-- existing plan: preserve user-provided steps, files, and constraints as `plan refine` notes; validate them, do not rediscover from scratch, and do not discard them.
-- recovery: read `planr map show --json` and `planr recover sweep` first — the board may already exist. Repair state instead of duplicating it.
-
-Always capture the goal oracle: the observable signal that proves the outcome actually runs — a test run, a live browser flow, an executed CLI binary, real API responses. Weak proof creates weak goals. The oracle becomes the live-verification half of the stop condition and maps to the loop's platform verification (`$planr-verify-web` for web, simulator for ios, executed binary for cli, real requests for api).
-
-## Compile The Board
+Classify the request:
 
-```bash
-planr project show --json                 # init only if no project exists
-planr plan new "<goal>" --platform <p>
-planr plan refine <plan-id> --note "constraint, assumption, or user-provided plan fact"
-planr plan check <plan-id>                # strict: empty required sections fail
-planr map build --from <plan-id>          # idempotent: safe to re-run
-```
+- specific: compile directly;
+- vague: ask at most two questions about outcome and proof, then record labeled assumptions;
+- existing plan: preserve its steps, files, and constraints as refinement notes;
+- recovery: inspect `planr map show --json` and `planr recover sweep` before creating anything.
 
-`plan refine` appends notes; the plan body is yours to edit. When `plan check` fails, each warning names the exact file and section — edit that file directly, fill the section with real content, and re-run the check. Scaffold sections (`## Scope Decision`, `## Verification`, `## Acceptance Criteria`) are filled by editing the plan markdown, not by more `refine` notes.
+Capture a goal oracle: the observable test, browser flow, executed CLI, or real API response that proves the outcome runs.
 
-Before `map build`, expand the plan's task list: the scaffold ships a single placeholder task, and mapping it produces one coarse item that forces the worker to guess the breakdown later. Replace the placeholder with one `### TASK-00n: <slice>` heading (or `- [ ]` line) per verifiable slice — typically 4-8, in execution order, each one closeable with its own evidence. Derive the slices from the acceptance criteria; `plan check` flags the unexpanded placeholder.
-
-`map build` creates one item per plan step and chains them in plan order with `blocks` links; the output lists the created items and links. Review that chain and adjust it only where execution order differs from document order:
+## Compile
 
 ```bash
-planr link add <earlier-item> <later-item> --type blocks
+planr project show --json
+planr plan new "<goal>" --platform <platform>
+planr plan refine <plan-id> --note "<constraint or assumption>"
+planr plan check <plan-id>
+planr map build --from <plan-id>
 ```
 
-If `planr agents list --json` shows routes with use-case `work_type` selectors (e.g. `frontend`, `backend`), declare them in the plan's task list before building — `### TASK-00n (backend): ...` headings and `- [ ] (frontend) ...` items seed with that work type directly. For maps already built without annotations, retag (`planr item update <id> --work-type frontend`). Either way this is prep-agent work, never a question for the user.
+Fill required plan sections directly. Replace the placeholder task with typically 4-8 independently verifiable `TASK-00n` slices before `planr map build`. Preserve real execution order with `blocks` links. When registry routes use `work_type`, annotate tasks before mapping or retag them afterward; this is prep work, not a user question.
 
-## Store The Goal Contract
+## Durable Contract
 
-The contract must survive compaction, session loss, and host switches, so it lives in Planr, not in chat:
+Store one contract per plan:
 
 ```bash
-planr context add "GOAL CONTRACT <plan-id>: 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 <oracle>. Iteration budget: 10." --tag goal-contract
+planr context add "GOAL CONTRACT <plan-id>: DONE when every in-scope item is closed with log evidence, all reviews are complete, approvals are clear, and a live verification log proves <goal oracle>. Iteration budget: 10." --tag goal-contract
 ```
 
-One contract per plan scope. Any agent on any host can recover it with `planr context list --tag goal-contract` or `planr search "GOAL CONTRACT"`. Never weaken a stored contract mid-run; scope changes go through `$planr-plan` and the user. During the run, workers lease with `planr pick --plan <plan-id>` so the loop never picks items outside this contract, even when other plans share the board. The loop checks the contract with `planr plan audit <plan-id>`, which evaluates exactly these clauses with evidence and answers `holds: true/false`.
-
-"All reviews closed" audits review items that exist — it does not require a review gate on every item. An item closed with plain `done` (evidence still required) satisfies the contract without one; request reviews where they carry signal (implementation slices, user-facing work), not on trivial inspection or scaffold steps.
+Never weaken it mid-run. Workers use `planr pick --plan <plan-id>`; termination uses `planr plan audit <plan-id> --json`. Reviews are required only where they add signal; evidence-backed setup work may close directly.
 
 ## Hand Off
 
-Print the starter command, then stop. Do not start execution yourself; ask whether to start now, refine the plan, or stop.
-
-With a native loop driver (Codex `/goal`, Claude Code `/goal` or `/loop`):
-
-```text
-/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.
-```
-
-Without one (Cursor, plain MCP clients, Codex without /goal):
-
-```text
-Use $planr-loop on plan <plan-id>. The loop contract is stored in planr context (tag: goal-contract). You are operating autonomously: 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.
-```
-
-Re-dispatch the same line after any session ends. The map, logs, and stored contract make every iteration resumable from zero context — nothing about the goal lives only in chat.
+Print: `Use $planr-loop on plan <plan-id>. Recover the goal-contract from Planr and continue until its audit holds or the iteration budget is exhausted.` Ask whether to start, refine, or stop; then stop. Execution belongs to the loop driver.

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.