planr 1.7.0 → 1.7.2

package/README.md

@@ -24,7 +24,7 @@ Flat todo lists break down the moment real work has structure. Planr models work
 - **State survives sessions.** Markdown plans hold scope and acceptance criteria; the SQLite graph holds live status across handoffs, restarts, and agent switches.
 - **Failure is structured.** Stale picks, timeouts, and retries are detectable and recoverable (`planr recover sweep`).
 
-Three layers make that work: **Plans** (reviewable Markdown packages), the **Map** (live dependency graph with picks, reviews, logs), and **Agent loops** (skills, CLI, and MCP workflows for every major coding agent). Full model: [Task Graph Model](docs/TASK_GRAPH_MODEL.md) and [Operating Model](docs/OPERATING_MODEL.md).
+Three layers make that work: **Plans** (reviewable Markdown packages), the **Map** (live dependency graph with picks, reviews, logs), and **Agent loops** (skills, CLI, and MCP workflows for every major coding agent). Full model: [Task Graph Model](https://planr.so/docs/concepts/graph-and-readiness) and [Operating Model](https://planr.so/docs/guides/daily-worker-loop).
 
 ## Install
 
@@ -50,7 +50,7 @@ Then initialize a project. When selected, Claude Code and Cursor also receive st
 planr project init "My Product" --client all
 ```
 
-Manual downloads, from-source builds, and client wiring details: [Install Guide](docs/INSTALL.md).
+Manual downloads, from-source builds, and client wiring details: [Install Guide](https://planr.so/docs/getting-started/installation).
 
 ## Install The Plugin (Skills)
 
@@ -93,7 +93,7 @@ planr install cursor            # writes .cursor/mcp.json, .cursor/agents/, and
 planr install cursor --no-mcp   # project skills, subagents, and hooks; no MCP config
 ```
 
-The dry-run also prints a one-click `cursor://` deeplink for user-level MCP install. Marketplace listing is pending review. Multitasking with Cursor subagents: [Cursor guide](docs/CURSOR.md).
+The dry-run also prints a one-click `cursor://` deeplink for user-level MCP install. Marketplace listing is pending review. Multitasking with Cursor subagents: [Cursor guide](https://planr.so/docs/integrations/cursor).
 
 </details>
 
@@ -110,6 +110,28 @@ planr prompt cli
 
 </details>
 
+## Plugins
+
+Planr plugins extend coding-agent setup around the same local-first graph. They do not move ownership of Planr Core: maps, picks, logs, reviews, approvals, and closure evidence still live in Planr, while optional integrations own their own install, generated files, and uninstall lifecycle.
+
+Switchloom is an optional external routing plugin for repository-local model-routing declarations. Use the corrected current quickstart command with the exact verified package version:
+
+```bash
+npx switchloom@0.3.2 compile balanced --host codex-openai --integration planr --output balanced-planr-codex.json
+npx switchloom@0.3.2 apply balanced-planr-codex.json --repository .
+planr agents check
+planr agents list --json
+```
+
+Planr consumes the resulting `.planr/agents.toml`, `.planr/policy.toml`, and route evidence; Codex consumes generated native roles after the host reloads its repository config. Switchloom remains responsible for its external lifecycle, including uninstall:
+
+```bash
+npx switchloom@0.3.2 uninstall --repository .
+planr agents check
+```
+
+References: [Plugins docs](https://planr.so/docs/plugins/switchloom), [Switchloom v0.3.2 release](https://github.com/instructa/switchloom/releases/tag/v0.3.2), [current corrected Switchloom quickstart](https://github.com/instructa/switchloom#setup-from-the-website), [v0.3.2 tagged quickstart](https://github.com/instructa/switchloom/blob/v0.3.2/README.md#setup-from-the-website), and [v0.3.2 lifecycle docs](https://github.com/instructa/switchloom/blob/v0.3.2/docs/preset-composition.md#repository-lifecycle-commands). The tagged v0.3.2 README quickstart preserves stale `0.3.1` command examples, so use the explicit `switchloom@0.3.2` commands above for the verified Planr contract.
+
 ## Tell Your Agent
 
 Remember one public entry point: `$planr`. It routes ordinary planning and status work from live Planr state. For long autonomous runs, use the explicit two-step workflow: `$planr-goal` prepares durable state, then `$planr-loop` executes the resulting plan.
@@ -136,7 +158,7 @@ with log evidence, all reviews are closed complete, and a live verification log
 the feature working in the browser. Iteration budget: 10.
 ```
 
-Mid-project work (a new feature, refactor, or fix on an existing project) works the same — it gets its own feature-scoped plan and extends the existing map. Both journeys with example prompts: [Two Journeys](docs/SKILLS.md#two-journeys-new-project-vs-existing-project). Coding agents inspect progress with the compact default `planr map show` or, preferably, `planr map show --json`. The tree preserves exact dependency vocabulary while marking satisfied edges as `blocks✓`; active `blocks` stay red. The boxed `planr map show --view diagram` renderer is exclusively for human supervision and uses neutral `then` routes once those dependencies are satisfied. Agents must not invoke it. Humans can add `--full` for complete status, title, worker, critical-lane, and pressure details. Interactive map output colors states automatically; `--no-color` and `NO_COLOR` keep it plain.
+Mid-project work (a new feature, refactor, or fix on an existing project) works the same — it gets its own feature-scoped plan and extends the existing map. Both journeys with example prompts: [Prompt Recipes](https://planr.so/docs/agents/prompt-recipes). Coding agents inspect progress with the compact default `planr map show` or, preferably, `planr map show --json`. The tree preserves exact dependency vocabulary while marking satisfied edges as `blocks✓`; active `blocks` stay red. The boxed `planr map show --view diagram` renderer is exclusively for human supervision and uses neutral `then` routes once those dependencies are satisfied. Agents must not invoke it. Humans can add `--full` for complete status, title, worker, critical-lane, and pressure details. Interactive map output colors states automatically; `--no-color` and `NO_COLOR` keep it plain.
 
 To supervise an agent from a second terminal, leave the agent running in terminal A and watch its scoped graph in terminal B:
 
@@ -152,30 +174,33 @@ The watcher is likewise a human-only observer. It defaults to the condensed diag
 
 ## What's new
 
-- **1.6.0 — Human map observation:** Added a condensed boxed diagram, live two-terminal watching, accessible state colors, and clearer satisfied dependency routes. These views are intentionally for human supervision; agents keep using the default tree or JSON snapshots. See [Task Graph Model](docs/TASK_GRAPH_MODEL.md), [CLI Reference](docs/CLI_REFERENCE.md), and the [1.6.0 changelog](CHANGELOG.md#160---2026-07-21).
-- **1.5.2 — Standalone core, optional Switchloom:** Planr consumes provider-neutral repository declarations and route evidence only; it works without any routing files, and requested-only routing metadata is not execution proof. Optional model-routing lifecycle is external, with [Switchloom v0.2.1](https://github.com/instructa/switchloom/releases/tag/v0.2.1) verified as the repository-local handoff outside Planr. Start with [Model Routing](docs/MODEL_ROUTING.md), [Switchloom](https://switchloom.ai), the [Switchloom repository](https://github.com/instructa/switchloom), its tagged [setup quickstart](https://github.com/instructa/switchloom/blob/v0.2.1/README.md#setup-from-the-website) and [lifecycle docs](https://github.com/instructa/switchloom/blob/v0.2.1/docs/preset-composition.md#repository-lifecycle-commands), and the [Changelog](CHANGELOG.md).
+- **1.7.2 — Reproducible release candidates:** Locked the pnpm workspace inventory, made external eval fixtures self-contained, refreshed reviewed workflow runtimes, and made all four published architectures execute the exact tagged version before upload. Model-backed evaluation remains a local, candidate-bound maintainer gate; this patch makes no unmeasured speed or quality claim. See the [1.7.2 changelog](CHANGELOG.md#172---2026-07-25) and [release guidance](https://planr.so/docs/operations/release).
+- **1.7.1 — Leaner agent guidance and safer local releases:** Slimmed the hot-path Planr skills while preserving their execution and review contracts, moved maintainer benchmark inputs and results outside the public repository, added a fail-closed local release-evidence gate without API keys in CI, and verified the optional external Switchloom v0.3.2 integration. The public 1.7 eval CLI remains available in this patch. See the [1.7.1 changelog](CHANGELOG.md#171---2026-07-25) and [release guidance](https://planr.so/docs/operations/release).
+- **1.7.0 — Evidence-backed evaluations:** Added durable eval suites, runs, comparisons, invalidation and rescoring, correctness/quality/performance gates, cost per verified success, and effort recommendations. The complete workflow is available through the CLI; MCP only mirrors selected surfaces and is optional. Security gates now cover repository leaks, vulnerable dependencies, workflow hardening, privacy, and forbidden staged files. See the [Eval Contract](docs/contracts/EVAL_CONTRACT_V1.md), [CLI Reference](https://planr.so/docs/reference/cli), and the [1.7.0 changelog](CHANGELOG.md#170---2026-07-22).
+- **1.6.0 — Human map observation:** Added a condensed boxed diagram, live two-terminal watching, accessible state colors, and clearer satisfied dependency routes. These views are intentionally for human supervision; agents keep using the default tree or JSON snapshots. See [Task Graph Model](https://planr.so/docs/concepts/graph-and-readiness), [CLI Reference](https://planr.so/docs/reference/cli), and the [1.6.0 changelog](CHANGELOG.md#160---2026-07-21).
+- **1.5.2 — Standalone core, optional Switchloom:** Planr consumes provider-neutral repository declarations and route evidence only; it works without any routing files, and requested-only routing metadata is not execution proof. Optional model-routing lifecycle is external, with [Switchloom v0.3.2](https://github.com/instructa/switchloom/releases/tag/v0.3.2) verified as the current repository-local handoff outside Planr. Start with [Plugins](https://planr.so/docs/plugins), [Switchloom](https://switchloom.ai), the [Switchloom repository](https://github.com/instructa/switchloom), the [current corrected quickstart](https://github.com/instructa/switchloom#setup-from-the-website), the [v0.3.2 tagged quickstart](https://github.com/instructa/switchloom/blob/v0.3.2/README.md#setup-from-the-website), [v0.3.2 lifecycle docs](https://github.com/instructa/switchloom/blob/v0.3.2/docs/preset-composition.md#repository-lifecycle-commands), and the [Changelog](CHANGELOG.md). The tagged v0.3.2 README quickstart keeps stale `0.3.1` command examples; use explicit `switchloom@0.3.2` commands when following Planr's verified contract.
 - **1.4.0 — Verified presets:** Added policy-driven composition, evaluation, signed registry evidence, and the public catalog. See the [1.4.0 release notes](https://github.com/instructa/planr/releases/tag/v1.4.0).
-- **1.3.0 — Native host hooks:** Added automatic session-state injection and loop recovery for supported hosts. See the [Hooks guide](docs/HOOKS.md) and [1.3.0 release notes](https://github.com/instructa/planr/releases/tag/v1.3.0).
+- **1.3.0 — Native host hooks:** Added automatic session-state injection and loop recovery for supported hosts. See the [Integrations guide](https://planr.so/docs/integrations) and [1.3.0 release notes](https://github.com/instructa/planr/releases/tag/v1.3.0).
 
 For the complete release history, see the [Changelog](CHANGELOG.md).
 
 ## Docs
 
-- [Install](docs/INSTALL.md)
-- [Skills](docs/SKILLS.md)
-- [Long-Running Goals](docs/GOALS.md)
-- [Model Routing](docs/MODEL_ROUTING.md) · [Worked Example: Web App](docs/EXAMPLE_WEBAPP.md)
-- [Host Hooks](docs/HOOKS.md)
-- [CLI Reference](docs/CLI_REFERENCE.md)
-- [MCP Guide](docs/MCP_GUIDE.md)
-- [Codex](docs/CODEX.md) · [Claude Code](docs/CLAUDE_CODE.md) · [Cursor](docs/CURSOR.md)
-- [Operating Model](docs/OPERATING_MODEL.md)
-- [Task Graph Model](docs/TASK_GRAPH_MODEL.md)
-- [Architecture](docs/ARCHITECTURE.md)
-- [Testing](docs/TESTING.md)
-- [Troubleshooting](docs/TROUBLESHOOTING.md)
-- [Specification Package](docs/planr-spec/README.md)
-- More: [Changelog](CHANGELOG.md), [Import](docs/IMPORT.md), [Security](docs/SECURITY.md), [Handoffs And Stories](docs/HANDOFFS_AND_STORIES.md), [npm Package](docs/NPM.md)
+Full documentation lives at [planr.so/docs](https://planr.so/docs).
+
+- [Install](https://planr.so/docs/getting-started/installation)
+- [Skills](https://planr.so/docs/agents/skills) · [Prompt Recipes](https://planr.so/docs/agents/prompt-recipes)
+- [Plugins and Model Routing](https://planr.so/docs/plugins) · [Recipes](https://planr.so/docs/guides/recipes)
+- [Integrations and Host Hooks](https://planr.so/docs/integrations)
+- [CLI Reference](https://planr.so/docs/reference/cli) · [MCP Reference](https://planr.so/docs/reference/mcp)
+- [Codex](https://planr.so/docs/integrations/codex) · [Claude Code](https://planr.so/docs/integrations/claude-code) · [Cursor](https://planr.so/docs/integrations/cursor)
+- [Daily Worker Loop](https://planr.so/docs/guides/daily-worker-loop)
+- [Task Graph Model](https://planr.so/docs/concepts/graph-and-readiness)
+- [Architecture](https://planr.so/docs/contributing/architecture)
+- [Testing](https://planr.so/docs/contributing/testing)
+- [Troubleshooting](https://planr.so/docs/troubleshooting)
+- [Specification Package](.planr/plans/product/planr/README.md)
+- More: [Changelog](CHANGELOG.md), [Packages and Reuse](https://planr.so/docs/guides/packages-and-reuse), [Security and Privacy](https://planr.so/docs/contributing/security-and-privacy), [Handoff and Resume](https://planr.so/docs/guides/handoff-and-resume)
 
 ## License
 

package/docs/ARCHITECTURE.md

@@ -8,7 +8,8 @@ Planr V1 is a single Rust binary with explicit module ownership. The crate stays
 - `tests/e2e.rs`: real CLI, MCP, HTTP, import, review-gate, run-log, and concurrent-pick tests.
 - `plugins/planr/`: the installable plugin payload — all ten skills, independent Claude/Cursor worker and reviewer role assets, and the per-host plugin manifests. Planr does not ship model-pinned Codex roles.
 - `.agents/plugins/marketplace.json`, `.claude-plugin/marketplace.json`: marketplace manifests pointing Codex and Claude Code at `plugins/planr`.
-- `docs/`: user and contributor guides; `docs/planr-spec/` is the production specification package for Planr V1.
+- `docs/`: user and contributor guides; `docs/contracts/` holds the frozen product contracts that gate CI.
+- `.planr/plans/product/planr/`: the production specification package for Planr V1, stored as a normal Planr product plan package. It is the only committed `.planr` path; all other runtime state stays local.
 - `examples/real-world-flow.md`: executable real-world operator flow.
 - `scripts/`: installer and release packaging scripts.
 - `npm/`: the npm wrapper package.
@@ -51,7 +52,7 @@ Planr V1 is a single Rust binary with explicit module ownership. The crate stays
 
 ## Eval Contract V1/V1.1 Ownership
 
-The frozen product contract lives in `docs/planr-spec/EVAL_CONTRACT_V1.md` until implementation promotes it into code. Its V1.1 efficiency-evidence amendment is additive and keeps the same owner split:
+The frozen product contract lives in `docs/contracts/EVAL_CONTRACT_V1.md` until implementation promotes it into code. Its V1.1 efficiency-evidence amendment is additive and keeps the same owner split:
 
 - repository EvalSuite manifests and fixtures are authored inputs;
 - the suite loader owns validation, safe path resolution, normalization, canonical ordering, and digests;

package/docs/RELEASE.md

@@ -10,28 +10,72 @@ The v1 repository-owned public install order is:
 4. npm (`npm install -g planr`) with bundled platform binaries.
 5. Cargo/source builds for maintainers and contributors.
 
-Published npm versions bundle platform-native binaries; see `docs/NPM.md`.
+Published npm versions bundle platform-native binaries; see <https://planr.so/docs/operations/release>.
 
 ## Version Bump
 
-`scripts/release.sh` is the only supported release path. The version lives in one source (`Cargo.toml`) and four distribution manifests must carry it: `Cargo.toml`, `package.json`, `plugins/planr/.codex-plugin/plugin.json`, and `plugins/planr/.claude-plugin/plugin.json`. Manual tagging skips the manifest sync and ships stale plugin versions.
+`scripts/release.sh` is the only supported release path. The version lives in
+`Cargo.toml`; `package.json`, both plugin manifests under `plugins/planr/`, and
+`.cursor-plugin/plugin.json` must match it. Generated CLI and MCP references
+must match the currently committed version before the release branch merges.
+After bumping on clean `main`, the script refreshes pnpm's derived workspace
+metadata with the frozen lockfile and rejects any lockfile byte change. It then
+builds, regenerates, and strictly checks both references before staging them in
+the same atomic release commit as the six synchronized version files. Manual
+tagging or pre-generating a future version skips this ownership boundary and
+can ship stale references.
 
 ```bash
+export PLANR_RELEASE_EVAL_SUITE="$HOME/projects/planr-evals/suites/planr-lean-skills-dogfood.suite.json"
+export PLANR_RELEASE_EVAL_RECEIPT=/path/to/sanitized-release-eval-receipt.json
+export PLANR_RELEASE_EVAL_DB=/path/to/planr-evals/results/eval.sqlite
 scripts/release.sh 1.2.0 "one-line release summary"
 ```
 
+Maintainer benchmarks, baselines, model/effort runs, and results live outside
+the public repository in `~/projects/planr-evals`; that workspace and its exact
+layout are not a Planr runtime contract. All three paths above are explicit so a
+release cannot silently use the product repository's ordinary `.planr` database
+or a stale bundled suite. The receipt is a short-lived local pointer containing
+only `schema_version`, comparison and candidate-run identities, suite and
+candidate-revision digests, and creation/expiry timestamps. Prompts,
+completions, credentials, personal paths, raw runs, reports, databases, and the
+receipt itself are never committed to Planr.
+
+Fixture paths inside the private suite resolve relative to the suite file's
+directory. The external eval workspace must therefore contain its complete
+fixture tree; release verification does not read ignored files from the Planr
+checkout.
+
+Generate the candidate revision with
+`node scripts/verify-release-eval-receipt.mjs --print-candidate-revision`. At
+release time the candidate binary canonicalizes the explicitly supplied suite,
+requires a Planr-validated effective route observation (host report, telemetry
+receipt, process exit, or local observation), recomputes the comparison from its
+stored baseline/candidate/policy identities, and gates that fresh result.
+Requested-only values and policy or binding metadata are never
+effective-treatment proof.
+
 The script enforces, in order:
 
 1. branch is `main`, worktree is clean, `CHANGELOG.md` already has a committed `## [x.y.z]` section, and the tag does not exist;
-2. the version is written into all four manifests plus `Cargo.lock`;
-3. gates: `cargo test` (includes the manifest drift guard in `tests/e2e.rs`), `npm pack --dry-run`, and `scripts/security-local.sh` (betterleaks + trivy leak gate);
-4. one mechanical commit `release x.y.z: <summary>`, an annotated `vx.y.z` tag carrying that summary, and a single push of branch plus tag.
+2. the version is written into all synchronized manifests;
+3. `pnpm install --frozen-lockfile` refreshes installed workspace metadata, and any `pnpm-lock.yaml` byte change stops the release before build, references, gates, or Git mutation;
+4. the build synchronizes `Cargo.lock`, and the bumped candidate regenerates and strictly verifies both generated references before any later gate or Git mutation;
+5. the candidate binary validates the sanitized receipt, observed effective treatment, candidate binding, and existing Planr comparison/gate before any Git mutation;
+6. deterministic gates: `cargo test` (including manifest drift), `npm pack --dry-run`, and `scripts/security-local.sh` (betterleaks + trivy);
+7. one mechanical commit containing the six version files plus both generated references, an annotated `vx.y.z` tag carrying that summary, and a single push of branch plus tag.
 
 Two independent gates back the script:
 
 - `cargo test` fails on every push when any manifest version drifts from `Cargo.toml`.
 - The release workflow's `Verify release versions are consistent` step refuses the tag when the tag, any manifest, or the `CHANGELOG.md` section disagree.
 
+Public CI runs `npm run verify:release-eval-gate` with a synthetic suite, fake
+binary, and temporary database. It verifies the fail-closed mechanism without a
+provider call, private benchmark, API key, or release receipt. Model-backed
+quality decisions remain a local maintainer preflight.
+
 ## Alpha Channel (Pre-Releases)
 
 Pre-release versions use the same script and pipeline with a semver pre-release suffix:
@@ -55,7 +99,7 @@ Pushing a tag `vX.Y.Z` runs `.github/workflows/release.yml`:
 1. `create-release` verifies the tag against `Cargo.toml`, all distribution manifests, and the changelog section, then creates a draft GitHub Release.
 2. `build` compiles and packages `planr-<os>-<arch>.tar.gz` for `darwin-arm64`, `darwin-x86_64`, `linux-x86_64`, and `linux-arm64`, then uploads each asset to the draft release.
 3. `finalize` downloads all uploaded assets, writes one aggregated `SHA256SUMS` covering every tarball, uploads it, and publishes the release.
-4. `npm-publish` downloads the release assets, verifies them against `SHA256SUMS`, bundles the four platform binaries into `npm/native/`, smoke-tests the wrapper, and publishes to npm via Trusted Publishing (OIDC). Runs only when the repository variable `NPM_PUBLISH_ENABLED` is `true`; requires the one-time Trusted Publisher setup described in `docs/NPM.md`.
+4. `npm-publish` downloads the release assets, verifies them against `SHA256SUMS`, bundles the four platform binaries into `npm/native/`, smoke-tests the wrapper, and publishes to npm via Trusted Publishing (OIDC). Runs only when the repository variable `NPM_PUBLISH_ENABLED` is `true`; requires the one-time Trusted Publisher setup described at <https://planr.so/docs/operations/release>.
 5. `homebrew-tap` regenerates `Formula/planr.rb` with `scripts/generate-formula.sh` and pushes it to `instructa/homebrew-tap` (installed as `brew install instructa/tap/planr`).
 
 ## Changelog
@@ -115,7 +159,6 @@ The package must include:
 
 - `npm/bin/planr.js`
 - `docs/`
-- `docs/MCP_CONTRACT.md`
 - `docs/fixtures/mcp-contract.json`
 - `plugins/`
 - `README.md`

package/docs/SWITCHLOOM_COMPATIBILITY.md

@@ -0,0 +1,46 @@
+# Switchloom Compatibility
+
+This report records Planr-side compatibility evidence for the exact public `switchloom@0.3.2` package. It is intentionally narrow: Planr verifies the package identity, repository-local declaration boundary, and its own consumption/proof semantics. It does not turn Switchloom internals, generated semantic role names, routes, doctor output, or runtime telemetry into a future contract.
+
+## Exact v0.3.2 Behavior Verified
+
+- Public npm metadata for `switchloom@0.3.2` resolved from the npm registry:
+  - `dist.integrity`: `sha512-g96AZIFKXpG1toAO+Gri1sjD8q0SxFxtRSLAcRcSVRGDCZ/dUtERepsOB+cSHHH7hUsT0jSKZYPfNqiLvfKk9Q==`
+  - `dist.shasum`: `d7d72c74ac3ecd5a3e355edd8e297284cba04403`
+  - `dist.tarball`: `https://registry.npmjs.org/switchloom/-/switchloom-0.3.2.tgz`
+- `npm pack switchloom@0.3.2 --pack-destination /private/tmp --json` returned a 9-entry package with the expected native binaries, wrapper, provenance file, README, license, and package manifest.
+- The packed tarball at `/private/tmp/switchloom-0.3.2.tgz` had SHA256 `0c04e94fc4372845edf395b3ea51139b8a4b46f34404940e06b3f4ec3ce22d20`.
+- The reviewed oracle contract expects the v0.3.2 Planr integration bundle `balanced-codex-openai@1.0.0+2.0.0`, bundle SHA256 `bf48f502080ff444ccb67bc4eeacc9391e77dbf5f0f8f277814e9abc2443e6c8`, 10 managed artifacts, 7 Codex-native roles, and 5 Planr work-type routes.
+- Repository docs now document the safe external operator flow with explicit `switchloom@0.3.2` commands, no normal-guidance `apply --yes`, and a caveat that the v0.3.2 tagged README preserves stale `0.3.1` examples.
+- The immutable live oracle used isolated source clone `/private/tmp/planr-switchloom-source.6gbzx2/source` and completed with `SWITCHLOOM_SOURCE_ROOT=/private/tmp/planr-switchloom-source.6gbzx2/source SWITCHLOOM_TARBALL=/private/tmp/switchloom-0.3.2.tgz PLANR_ORACLE_TEMP_PARENT=/private/tmp npm run verify:switchloom-cross-product`, exit 0. The live root is `/private/tmp/planr-switchloom-cross-product-Lbluca`, with oracle receipt `/private/tmp/planr-switchloom-cross-product-Lbluca/oracle-receipt.json`.
+- The retained replay of the same root and isolated source clone exited 0 and wrote `/private/tmp/planr-switchloom-cross-product-Lbluca/replay-receipt.json`. Replay first asserts the current source fingerprint matches the retained live receipt, then separately verifies the source remains unchanged during replay.
+- The live and replay receipts bind the same Switchloom source fingerprint before and after each mode: HEAD `8ff05776085d3175211e080143c513c5173abaa4`, clean status SHA256 `e3b0c442...`, inventory SHA256 `790de1be...`, file-hash SHA256 `97a26b12...`, and 303 paths. The maintainer's original sibling Switchloom worktree was not modified for this proof.
+- The successful live oracle proves exact package tarball SHA256 `0c04e94fc4372845edf395b3ea51139b8a4b46f34404940e06b3f4ec3ce22d20`, bundle SHA256 `bf48f502080ff444ccb67bc4eeacc9391e77dbf5f0f8f277814e9abc2443e6c8`, 7 profiles, 5 routes, 10 managed artifacts, Planr declaration consumption, Planr audit, uninstall and unrouted Planr behavior, no-auth fail-closed behavior, requested-only rejection, global sentinel preservation, and routing ownership.
+- The successful live oracle proves separate native maker and reviewer execution: maker `model_routing_terra_high` on `gpt-5.6-terra` with high effort, reviewer `model_routing_sol_high` on `gpt-5.6-sol` with high effort. Hidden spawn messages are intentionally opaque; the proof is exact successful parent `agent_type`, `task_name`, and `fork_turns` metadata correlated with matching direct child role rollouts, repo-local skill reads, and item-specific Planr evidence. It does not claim plaintext hidden-message recovery.
+- One malformed parent `spawn_agent` attempt in the retained live root was retained as a diagnostic and not counted as a successful spawn. The oracle still requires exactly two successful routed spawns and still rejects default, wrong-role, missing-role, or extra successful child execution.
+- A separate fresh root, `/private/tmp/planr-switchloom-cross-product-gHtZQI`, was correctly rejected: Codex claimed `spawn_agent` was unavailable and directly handled the work, producing 0 successful routed spawns. That run is negative evidence for host stochastic failure detection, not a passing compatibility run.
+
+## Stable Planr Boundary
+
+- Planr Core is provider-neutral. It reads `.planr/agents.toml`, `.planr/policy.toml`, and route-audit evidence, but does not install, invoke, compile, apply, or uninstall Switchloom output.
+- `.planr/agents.toml` profiles, routes, model names, efforts, role names, and fallback chains are opaque data to Planr. Planr may place requested routing data in pick packets, but requested-only values are not effective execution proof.
+- `--profile` records the profile a worker reports for a run. Genuine runtime proof belongs in route-audit evidence that separates requested, host-resolved, and effective dimensions.
+- Missing effective host evidence remains explicitly unavailable. Planr must not infer it from generated declarations, policy files, or worker claims.
+- External lifecycle remains external: Switchloom owns compile, apply, generated host roles, host reload requirements, and uninstall. Planr validates its own consumption with `planr agents check` and records evidence through logs/reviews.
+- Planr works without routing declarations. After an external uninstall, unrouted Planr fallback behavior remains the stable Core contract.
+
+## Not Guaranteed For Future Switchloom Work
+
+Future Switchloom work, including thread `019f8a71-5b6c-7c41-9850-7050516fcee4`, may change semantic role names, route names, doctor output, generated artifacts, runtime telemetry, and host-specific evidence shape. Planr must not contract those as stable.
+
+The stable compatibility promise is limited to Planr's boundary: consume provider-neutral declarations when present, keep requested values separate from effective evidence, reject requested-only metadata as proof, avoid owning external lifecycle, and continue operating when routing files are absent.
+
+Any future mismatch in package identity, generated artifacts, Planr declaration parsing, route-audit semantics, host evidence, source-worktree mutation, or security posture should become a new finding or fix item rather than an optimistic compatibility claim.
+
+## Verification Notes
+
+- Rust formatting, clippy, full serial cargo tests, e2e, eval-contract, and routing-ownership tests passed when run outside the sandbox where HTTP/process tests are permitted.
+- Docs reference generation, typecheck, reference verification, maintenance verification, and Node 22 production build passed. Node 26 production docs builds hung in the optimized Next build phase and were terminated; the Node 22 build is the relevant repository runtime.
+- npm package dry-run passed using a temp npm cache because the user npm cache contains root-owned files.
+- Privacy checks passed. The docs app Next.js runtime was upgraded from `16.2.10` to `16.2.11` in `apps/docs/package.json` and `pnpm-lock.yaml`; the lockfile change is limited to Next core/env/SWC and mechanically recalculated peer snapshots. `npm run security:check` passed with BetterLeaks reporting no leaks and Trivy reporting 0 vulnerabilities for both `Cargo.lock` and `pnpm-lock.yaml`.
+- The immutable source clone proof supersedes earlier retained-replay-only evidence. Earlier concurrent external mutation and missing-receipt attempts were treated as real failures and are not counted as passing evidence.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "description": "Local-first planning and execution coordination for coding agents.",
   "license": "MIT",
   "repository": {
@@ -25,6 +25,10 @@
     "security:staged": "node scripts/hooks/block-forbidden-staged-files.mjs",
     "build:native": "cargo build --release",
     "test": "cargo test",
+    "verify:github-actions": "node scripts/verify-github-actions.mjs && node scripts/test-verify-github-actions.mjs",
+    "verify:pnpm-workspace": "node scripts/verify-pnpm-workspace.mjs",
+    "verify:release-eval-gate": "node scripts/test-release-eval-gate.mjs",
+    "verify:release-script": "node scripts/test-release-script.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.7.0",
+  "version": "1.7.2",
   "author": {
     "name": "instructa"
   },

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

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "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
 ---