planr - npm Package Compare versions

Comparing version 1.6.0 to 1.7.0

docs/ARCHITECTURE.md

@@ -52,2 +52,12 @@ # Planr Architecture
 
+## 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:
+
+- repository EvalSuite manifests and fixtures are authored inputs;
+- the suite loader owns validation, safe path resolution, normalization, canonical ordering, and digests;
+- SQLite owns immutable suite snapshots, runs, case results, samples, attempt lineage, metering-basis provenance, comparisons, invalidations, rescoring provenance, and eval evidence references;
+- the comparison engine owns verdicts, reason codes, matched effective-treatment compatibility, and derived failure-inclusive efficiency metrics;
+- existing map/log/review/approval state remains authoritative for work closure, so eval evidence may support a review but must never close or reopen items by itself.
+
 ## Boundary Rules
@@ -54,0 +64,0 @@

docs/CI.md

@@ -30,6 +30,7 @@ # CI
 
-`scripts/ci-local.sh` also runs the external consumer E2E project when `/Users/kregenrek/projects/planr-test` exists:
+`scripts/ci-local.sh` also runs the external consumer E2E project when the sibling `planr-test` checkout exists. Override its location with `PLANR_TEST_DIR`:
 
 ```bash
-cd /Users/kregenrek/projects/planr-test
+PLANR_TEST_DIR=/path/to/planr-test scripts/ci-local.sh
+cd /path/to/planr-test
 npm test
@@ -42,6 +43,6 @@ npm run test:npm-planr
 ```bash
-scripts/security-local.sh
+npm run security:check
 ```
 
-This uses BetterLeaks for secret history scanning and Trivy for filesystem vulnerability, secret, and misconfiguration scanning.
+This checks tracked files for machine-specific home paths, rejects forbidden staged paths, uses BetterLeaks for secret history scanning, and runs Trivy for filesystem vulnerability, secret, and misconfiguration scanning. If Lefthook is installed, run `lefthook install` once to activate the staged-path guard for commits and pushes.
 
@@ -48,0 +49,0 @@ ## Supply Chain

docs/CLI_REFERENCE.md

@@ -62,2 +62,10 @@ # CLI Reference
 planr review close <review-item-id> --verdict complete|not-complete|unclear [--close-target]
+planr eval suite-check --input suite.json
+planr eval run --input run.json
+planr eval show suite|run|comparison|invalidation <id>
+planr eval compare <baseline-run-id> <candidate-run-id> [--policy-digest default]
+planr eval gate <comparison-id>
+planr eval invalidate run|comparison <target-id> --reason "..." [--reason-code code] [--replacement-hint "..."]
+planr eval rescore <run-id> [--id <new-run-id>]
+planr eval evidence-ref run|comparison <target-id> log|review|artifact <attachment-id> --item <item-id>
 planr close [item-id] --summary "..." [--next]
@@ -133,2 +141,4 @@ planr done [item-id] --summary "..." [--files a --files b] [--cmd "..."] [--tests "..."] [--review] [--next] [--profile <id>]
 
+`eval` exposes the same stored evaluation services to CLI and MCP. Every eval JSON response is one document with the frozen envelope `ok`, `command`, `object`, `warnings`, `reasons`, and `error`; MCP tools return the same envelope inside the text content, including `isError` tool results. `suite-check` reports command `eval.suite.check`, stores or verifies an immutable suite snapshot, `run` starts a run from a JSON envelope and can record cases/samples plus a terminal status, `compare` persists a verdict from two stored runs, and `gate` exits non-zero for `regressed` or `insufficient_evidence` while still printing the verdict, blocker, effects, uncertainty, coverage/freshness gates, and deeper-read commands. Eval exit codes are fixed: `0` for accepted command outcomes, `1` for regression or promotion-gate failure, `2` for insufficient evidence, `3` for invalid or unsafe input, and `4` for infrastructure errors such as missing stored runs. Error objects include `code`, `message`, `reasons`, and `field`. `invalidate` records invalidation evidence for a run or comparison, and `rescore` starts a new run linked back to the source run. `evidence-ref` attaches a run or comparison to an existing log, review item, or artifact for audit/package portability; it is never closure authority and never changes map item status. MCP mirrors these operations as `planr_eval_suite_check`, `planr_eval_run`, `planr_eval_show`, `planr_eval_compare`, `planr_eval_gate`, `planr_eval_invalidate`, `planr_eval_rescore`, and `planr_eval_evidence_ref`. A repository-owned smoke suite lives at `examples/eval/planr-lifecycle-smoke.suite.json`; recalculate fixture digests before using it outside repo-local examples.
+
 `trace item` on a review item inlines the target item and its evidence logs under `target`, so a reviewer's first trace already contains what is being audited. The human (non-JSON) mode renders the packet: status, owner, links, logs. When the item has a declared route, a run profile, or a route observation, the trace gains a `routing` section — the declared route next to every run's actual client/profile and, when supplied, its independent requested → resolved → effective model/effort/context-fork stages, transition reason, policy/binding provenance, and per-dimension metering confidence. Unknown effective host values remain `null`/`unavailable`; requested values are never copied forward as proof. MCP `planr_trace_item` returns the identical JSON shape.
@@ -135,0 +145,0 @@

docs/fixtures/mcp-contract.json

@@ -45,2 +45,10 @@ {
     "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",
@@ -104,2 +112,6 @@ "planr_review_annotate",
     "planr review close",
+    "planr eval suite-check",
+    "planr eval compare",
+    "planr eval gate",
+    "planr eval evidence-ref",
     "planr recover sweep",
@@ -106,0 +118,0 @@ "planr agents list",

docs/IMPORT.md

@@ -10,6 +10,8 @@ # Planr Packages
 
-Planr packages are local-first JSON files created by `planr export`. They carry graph items, links, contexts, optional logs, optional plan file snapshots, and review artifacts.
+Planr packages are local-first JSON files created by `planr export`. They carry graph items, links, contexts, optional logs, optional eval evidence refs, optional plan file snapshots, and review artifacts.
 
 Imports are preview-first. Preview reports package metadata, create counts, and conflicting item ids before mutating the current project.
 
+Eval evidence exports only when logs are included. Packages carry immutable eval suite snapshots, runs, case results, raw samples, comparisons, invalidations, and evidence refs so imported refs resolve to local eval records and comparison verdicts can be reproduced from restored run evidence. Import preflights the whole eval graph before inserting package rows: duplicate immutable ids inside the package must be byte/field-identical, suite/run/comparison/invalidation/ref dependencies must resolve, case sample ids must match nested samples, and eval refs must have `closure_authority: false`. Existing immutable eval ids are accepted only when their stored content exactly matches the package, and imported eval timestamps/provenance are preserved. Review refs must point at a real `work_type=review` item linked to the claimed item. Restoring audit provenance never closes work or changes map ownership.
+
 Planr packages are local-first JSON. For encrypted sharing, review the JSON locally and encrypt the file with your team's standard tool, for example:
@@ -16,0 +18,0 @@

docs/MCP_CONTRACT.md

@@ -44,2 +44,3 @@ # MCP Contract
 - event list and debug bundle preview
+- eval suite check, run, show, compare, gate, invalidate, rescore, and evidence refs
 - trace item, log add, and log read (including three-stage route observations)
@@ -64,2 +65,6 @@ - provider-neutral agent registry reads and route overrides
 
+## Eval Evidence Contract
+
+`planr_eval_evidence_ref` mirrors `planr eval evidence-ref`: it attaches an eval run or comparison id to an existing log, review item, or artifact. The returned eval envelope records `closure_authority: false`; eval verdicts are audit evidence only and never close, approve, or otherwise mutate map item status.
+
 ## Install Contract
@@ -66,0 +71,0 @@

docs/planr-spec/API_AND_DATA_MODEL.md

 # API And Data Model
 
+Eval Contract v1, including the additive v1.1 efficiency-evidence amendment, is frozen in [EVAL_CONTRACT_V1.md](EVAL_CONTRACT_V1.md). That document owns the canonical eval manifest fields, normalized snapshot, stored objects, attempt lineage, metering basis, effective treatment identity, derived efficiency metrics, status values, reason codes, evidence identities, response examples, exit codes, database rules, and safety constraints. This file keeps the higher-level product API summary.
+
 ## Storage Locations
@@ -4,0 +6,0 @@

docs/planr-spec/README.md

@@ -19,2 +19,3 @@ # Planr Specification Package
 - API_AND_DATA_MODEL.md: project, plan, map, item, log, review, and API contracts.
+- EVAL_CONTRACT_V1.md: frozen EvalSuite, evidence, v1.1 attempt-lineage and efficiency metrics, verdict, reason, CLI/MCP, database, and safety contract.
 - CLIENT_IMPLEMENTATION_SPEC.md: CLI, TUI, editor, and agent-client surfaces.
@@ -21,0 +22,0 @@ - BACKEND_IMPLEMENTATION_SPEC.md: local service, MCP server, HTTP/SSE, and storage implementation.

docs/planr-spec/TECH_ARCHITECTURE.md

 # Technical Architecture
 
+Eval Contract v1 is frozen in [EVAL_CONTRACT_V1.md](EVAL_CONTRACT_V1.md). Eval implementation work must preserve its ownership split: repository manifests are authored inputs, SQLite owns immutable eval evidence, and Planr map state remains authoritative for work closure.
+
 ## Architecture Goals
@@ -4,0 +6,0 @@

docs/release-candidates/planr-v1.5.2.md

@@ -5,8 +5,8 @@ # Planr v1.5.2 Release Candidate Evidence
 
-- Workspace: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2`
-- Source clone: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/release-candidate-src`
-- Local bare remote: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/local-origin.git`
-- Config-proof rerun source clone: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/release-candidate-src`
-- Config-proof rerun local bare remote: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/local-origin.git`
-- Config-proof hash snapshots: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/evidence`
+- Workspace: `$HOME/projects/planr-dogfood/release-v1.5.2`
+- Source clone: `$HOME/projects/planr-dogfood/release-v1.5.2/release-candidate-src`
+- Local bare remote: `$HOME/projects/planr-dogfood/release-v1.5.2/local-origin.git`
+- Config-proof rerun source clone: `$HOME/projects/planr-dogfood/release-v1.5.2/config-proof/release-candidate-src`
+- Config-proof rerun local bare remote: `$HOME/projects/planr-dogfood/release-v1.5.2/config-proof/local-origin.git`
+- Config-proof hash snapshots: `$HOME/projects/planr-dogfood/release-v1.5.2/config-proof/evidence`
 - Public side effects: none. The candidate clone's `origin` points to the local bare remote, and the public `origin` check from this repository returned no `v1.5.2` tag.
@@ -76,11 +76,11 @@
   - `scripts/security-local.sh`: betterleaks found no leaks; Trivy reported 0 vulnerabilities for `Cargo.lock` and `pnpm-lock.yaml`.
-  - Pushed `main` and `v1.5.2` only to `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/local-origin.git`.
+  - Pushed `main` and `v1.5.2` only to `$HOME/projects/planr-dogfood/release-v1.5.2/local-origin.git`.
 - `scripts/build-release.sh`: built `dist/planr-darwin-arm64.tar.gz`.
 - `npm pack`: created `planr-1.5.2.tgz` locally; no npm publish was run.
 - Config-proof rerun:
-  - `scripts/release.sh 1.5.2 'standalone Planr core with optional Switchloom handoff'`: 71 unit tests, 67 e2e tests, and 3 routing ownership tests passed; betterleaks found no leaks; Trivy reported 0 vulnerabilities; pushed only to `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/local-origin.git`.
+  - `scripts/release.sh 1.5.2 'standalone Planr core with optional Switchloom handoff'`: 71 unit tests, 67 e2e tests, and 3 routing ownership tests passed; betterleaks found no leaks; Trivy reported 0 vulnerabilities; pushed only to `$HOME/projects/planr-dogfood/release-v1.5.2/config-proof/local-origin.git`.
   - `scripts/build-release.sh`: built `dist/planr-darwin-arm64.tar.gz`.
   - `npm pack`: created `planr-1.5.2.tgz` locally; no npm publish was run.
   - `target/release/planr --version` and `node npm/bin/planr.js --version`: both reported `planr 1.5.2`.
-- `git tag -l v1.5.2`: returned no local tag in `/Users/kregenrek/projects/planr`.
+- `git tag -l v1.5.2`: returned no local tag in `$HOME/projects/planr`.
 - `git ls-remote --heads --tags origin 'v1.5.2'`: returned no public remote ref.
@@ -94,21 +94,16 @@ - Candidate clone artifact inventory: no Switchloom files, no legacy routing-owner directories, and no routing manifests were present.
 - `scripts/release.sh`
-  - Before: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-before-release-sh.txt`
-  - After: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-after-release-sh.txt`
-  - Equality proof: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-release-sh-equality.txt` records `config hashes unchanged across scripts/release.sh`.
+  - Before: `$HOME/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-before-release-sh.txt`
+  - After: `$HOME/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-after-release-sh.txt`
+  - Equality proof: `$HOME/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-release-sh-equality.txt` records `config hashes unchanged across scripts/release.sh`.
 - `scripts/build-release.sh`
-  - Before: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-before-build-release.txt`
-  - After: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-after-build-release.txt`
-  - Equality proof: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-build-release-equality.txt` records `config hashes unchanged across scripts/build-release.sh`.
+  - Before: `$HOME/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-before-build-release.txt`
+  - After: `$HOME/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-after-build-release.txt`
+  - Equality proof: `$HOME/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-build-release-equality.txt` records `config hashes unchanged across scripts/build-release.sh`.
 - `npm pack`
-  - Before: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-before-npm-pack.txt`
-  - After: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-after-npm-pack.txt`
-  - Equality proof: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-npm-pack-equality.txt` records `config hashes unchanged across npm pack`.
+  - Before: `$HOME/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-before-npm-pack.txt`
+  - After: `$HOME/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-after-npm-pack.txt`
+  - Equality proof: `$HOME/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-npm-pack-equality.txt` records `config hashes unchanged across npm pack`.
 
-Every before/after snapshot contains the same hashes:
+Every before/after snapshot contains matching hashes. Machine-specific paths and fingerprints are intentionally omitted from this public evidence file.
 
-- `/Users/kregenrek/.codex/config.toml`: `82224997e7d4d5147f892a8aa12f7f5f04e77c38267da6ba1274a9267b23f040`
-- `/Users/kregenrek/.claude/settings.json`: `99a0eb17993d0dd0c952df03bec38d284fd119a9b0ed928f3201b1792224049f`
-- `/Users/kregenrek/.claude.json`: `a5f901ce3b38943ed2591333b4cb6dbab0cab101f8d02ea348fc476021f55afb`
-- `/Users/kregenrek/.cursor/mcp.json`: `cf7217adfcb48b532dfdbced62ca68eab4c60996ef38d510a8efb3d286ce5baf`
-
 ## Switchloom v0.2.1 Optional Dogfood Evidence
@@ -118,6 +113,6 @@
 
-- Receipt: `/private/tmp/planr-switchloom-cross-product-QEvWps/oracle-receipt.json`
+- Receipt: `/private/tmp/planr-switchloom-cross-product-<run>/oracle-receipt.json`
 - Receipt SHA-256: `c01f4b980977a15028f7a82cc6fc237aa50fb4b35310871ba3ad245ec1c699ee`
 - Mode/result: `live`, `ok=true`
-- Fresh root: `/private/tmp/planr-switchloom-cross-product-QEvWps`
+- Fresh root: `/private/tmp/planr-switchloom-cross-product-<run>`
 
@@ -127,3 +122,3 @@ Replayable command:
 ```bash
-PLANR_WORKER_ID=switchloom_optional_dogfood PLANR_BIN=/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/release-candidate-src/target/release/planr SWITCHLOOM_TARBALL=/private/tmp/switchloom-public-0.2.1.MN008L/switchloom-0.2.1.tgz PLANR_ORACLE_TEMP_PARENT=/private/tmp node scripts/verify-switchloom-cross-product.mjs
+PLANR_WORKER_ID=switchloom_optional_dogfood PLANR_BIN=$HOME/projects/planr-dogfood/release-v1.5.2/release-candidate-src/target/release/planr SWITCHLOOM_TARBALL=/path/to/switchloom-0.2.1.tgz PLANR_ORACLE_TEMP_PARENT=/private/tmp node scripts/verify-switchloom-cross-product.mjs
 ```
@@ -134,3 +129,3 @@
 - Package: `switchloom@0.2.1`
-- Tarball: `/private/tmp/switchloom-public-0.2.1.MN008L/switchloom-0.2.1.tgz`
+- Tarball: `/path/to/switchloom-0.2.1.tgz`
 - npm SHA-1 shasum: `e813283f54d0d64b5fd4835e17687aaaf3b0a6cb`
@@ -146,6 +141,6 @@ - SHA-512 integrity: `sha512-vUKHxYXHt7Sx7MkYQz5MRZ0Ll544iHoadHGCgvJPUYkpUzQWtzjt1o3xhyeQwExCA6tuLQ5vZnLPz+fO5uMiXg==`
 - `fork_turns_all_used`: `false`
-- Public Codex JSONL: `/private/tmp/planr-switchloom-cross-product-QEvWps/codex-live.jsonl`
-- Parent rollout: `/Users/kregenrek/.codex/sessions/2026/07/20/rollout-2026-07-20T20-05-19-019f80b4-2e89-7470-a432-6937ddcbc7ac.jsonl`
-- Maker rollout: `/Users/kregenrek/.codex/sessions/2026/07/20/rollout-2026-07-20T20-05-50-019f80b4-a7d3-73d1-bf34-9762ad7d9474.jsonl`
-- Reviewer rollout: `/Users/kregenrek/.codex/sessions/2026/07/20/rollout-2026-07-20T20-06-37-019f80b5-5d7f-7441-97f3-c743d97e0a8c.jsonl`
+- Public Codex JSONL: `/private/tmp/planr-switchloom-cross-product-<run>/codex-live.jsonl`
+- Parent rollout: local Codex session (path omitted)
+- Maker rollout: local Codex session (path omitted)
+- Reviewer rollout: local Codex session (path omitted)
 
@@ -158,11 +153,8 @@ Fresh Planr audit and uninstall evidence:
 - Post-uninstall result: Switchloom uninstall removed only managed files and unrouted Planr still worked; the script reran the Planr audit after uninstall and required `holds=true`.
-- Requested-only routing metadata was rejected as effective proof: `/private/tmp/planr-switchloom-cross-product-QEvWps/requested-only-route-audit.json`.
+- Requested-only routing metadata was rejected as effective proof: `/private/tmp/planr-switchloom-cross-product-<run>/requested-only-route-audit.json`.
 
 Protected configuration and source inventory proof:
 
-- `/Users/kregenrek/.codex/config.toml`: `82224997e7d4d5147f892a8aa12f7f5f04e77c38267da6ba1274a9267b23f040`
-- `/Users/kregenrek/.claude/settings.json`: `99a0eb17993d0dd0c952df03bec38d284fd119a9b0ed928f3201b1792224049f`
-- `/Users/kregenrek/.claude.json`: `a5f901ce3b38943ed2591333b4cb6dbab0cab101f8d02ea348fc476021f55afb`
-- `/Users/kregenrek/.cursor/mcp.json`: `cf7217adfcb48b532dfdbced62ca68eab4c60996ef38d510a8efb3d286ce5baf`
-- Switchloom source root: `/Users/kregenrek/projects/model-routing`
+- User configuration: unchanged; machine-specific paths and fingerprints omitted
+- Switchloom source root: sibling `model-routing` checkout (or `SWITCHLOOM_SOURCE_ROOT`)
 - Switchloom source HEAD: `191f6aac91ff0f73fcae68ab269eb2d89c9e76e9`
@@ -169,0 +161,0 @@ - Switchloom source status SHA-256: `2ca939e3e14ba8971210e93152120323641d21b0ac465b02a85335860b01758c`

docs/TESTING.md

@@ -70,3 +70,3 @@ # Testing
 ```bash
-/Users/kregenrek/.agents/skills/shellck/scripts/run_shellck.sh scripts/install.sh
+$HOME/.agents/skills/shellck/scripts/run_shellck.sh scripts/install.sh
 PREFIX="$(mktemp -d)" PLANR_DOWNLOAD=1 PLANR_RELEASE_BASE_URL="file://$PWD/dist" scripts/install.sh
@@ -73,0 +73,0 @@ ```

package.json

 {
   "name": "planr",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Local-first planning and execution coordination for coding agents.",
@@ -23,2 +23,5 @@ "license": "MIT",
   "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",
@@ -25,0 +28,0 @@ "test": "cargo test",

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

 {
   "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.0",
   "author": {
@@ -6,0 +6,0 @@ "name": "instructa"

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

 {
   "name": "planr",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "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.",
@@ -5,0 +5,0 @@ "author": {

No alert changes

Improved metrics

Total package byte prevSize

30622977

16.47%

Number of package files

71

1.43%

Lines of code

205

6.22%

No dependency changes