planr 1.5.2 → 1.7.0

package/README.md

@@ -136,10 +136,23 @@ 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). Watch progress anytime with `planr map show`.
+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.
+
+To supervise an agent from a second terminal, leave the agent running in terminal A and watch its scoped graph in terminal B:
+
+```bash
+planr map watch --plan <plan-id>
+# optional: exit after every scoped item settles
+planr map watch --plan <plan-id> --until-settled
+# optional: inspect complete node details
+planr map watch --plan <plan-id> --full
+```
+
+The watcher is likewise a human-only observer. It defaults to the condensed diagram view, polls the local SQLite graph once per second, and redraws only when state changes. Coding agents must not invoke `map watch`; they should use `map show --json` snapshots or the `/v1/events/stream` SSE endpoint instead. Use Ctrl-C to stop.
 
 ## 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.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).

package/docs/ARCHITECTURE.md

@@ -49,6 +49,16 @@ Planr V1 is a single Rust binary with explicit module ownership. The crate stays
 - `src/rolefiles.rs`: static host workflow roles and Cursor skill payloads. It does not select or pin models; externally generated routing artifacts stay outside Planr ownership.
 - `src/util.rs`: small CLI-boundary utilities. Owns ids, timestamps, path helpers, output formatting, and safe file writes.
 
+## 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
 
 - Command parsing belongs in `src/cli.rs`; process startup belongs in `src/main.rs`; command execution belongs under `src/app/`.

package/docs/CI.md

@@ -27,10 +27,11 @@ Run the full local gate:
 scripts/ci-local.sh
 ```
 
-`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
 npm run test:npm-planr
 ```
@@ -38,10 +39,10 @@ npm run test:npm-planr
 Run local security and leak checks:
 
 ```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.
 
 ## Supply Chain
 

package/docs/CLI_REFERENCE.md

@@ -13,7 +13,8 @@ planr plan check <plan-id>
 planr plan audit <plan-id>
 planr plan show <plan-id>
 planr plan archive <plan-id>
-planr map show [--plan <plan-id>]
+planr map show [--plan <plan-id>] [--view tree|diagram] [--full]
+planr map watch [--plan <plan-id>] [--view tree|diagram] [--full] [--interval-ms 1000] [--no-clear] [--until-settled]
 planr map build --from <plan-id>
 planr map lane --critical
 planr map pressure
@@ -58,6 +59,14 @@ planr review ingest <item-id> (--from feedback.json|--stdin)
 planr review artifact <review-item-id> [--out .planr/reviews/custom.review.md]
 planr review evidence <item-id> [--pr-url https://...]
 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]
 planr done [item-id] --summary "..." [--files a --files b] [--cmd "..."] [--tests "..."] [--review] [--next] [--profile <id>]
 planr context add "text" [--item <item-id>] [--tag discovery]
@@ -77,7 +86,7 @@ planr import <file> [--preview] [--confirm]
 planr export --out planr.json [--include-plans] [--include-logs] [--template-name "..."] [--tag tag]
 ```
 
-Global flags: `--db <path>`, `--json`, `--no-color`. They are valid in both positions: `planr --json pick` and `planr pick --json` behave identically.
+Global flags: `--db <path>`, `--json`, `--no-color`. They are valid in both positions: `planr --json pick` and `planr pick --json` behave identically. Human map output uses ANSI status colors only when stdout is an interactive terminal. `--no-color`, `NO_COLOR` (even when empty), `TERM=dumb`, redirected stdout, and JSON disable color; `PLANR_FORCE_COLOR=1` is available for compatible terminal wrappers and tests, but never overrides an explicit opt-out.
 
 ## JSON Envelope Convention
 
@@ -94,7 +103,11 @@ With `--json`, responses follow one convention so agents never guess where data
 
 `plan audit <plan-id>` is the one-call contract verdict for a plan's map scope. JSON shape for machine consumers: top-level `holds` (bool) and `clauses[]` with `clause` (name) and `pass` (bool) — e.g. `planr plan audit <id> --json | jq '.holds, (.clauses[] | {clause, pass})'`. It evaluates four clauses with evidence: `items_settled` (open items listed), `reviews_complete` (open review items listed), `approvals_clear` (requested/denied approvals listed), and `verification_logged` (logs with `--kind verification` on scope items). The stored goal contract (`planr context --tag goal-contract` mentioning the plan id) is included; the verification clause is binding only when such a contract exists. `holds: true` means the contract is satisfied — loop agents use this as their stop condition instead of stitching the verdict together from `map status`, `log list`, and `approval list`. When the contract is open, `next` carries the exact next command derived from the first actionable gap: build the map, pick the ready review or work item (plan-scoped), resolve the blocking approval, inspect stalled leases, or log the missing verification. Also available as MCP `planr_plan_audit`.
 
-`map show --plan <plan-id>` narrows the map to one plan's items and the links among them, with plan-scoped counts — plan-scoped goal runs on shared boards audit their slice, not the whole board. An unknown plan id is an error, never a silent unscoped view. Also available on MCP `planr_map_show` (`plan`) and HTTP `GET /v1/projects/{id}/map?plan=<plan-id>`.
+`map show` defaults to the compact `tree` view used by agents and existing terminal workflows; coding agents should prefer `map show --json` when they need structured state. The tree keeps the canonical edge vocabulary visible: active dependencies render as red `blocks`, while an edge satisfied by a `closed` or `closed_partial` upstream renders as dim `blocks✓`. `map show --view diagram` is exclusively a human-supervision view and coding agents must not invoke it. It provides fixed-width boxes with at most two content lines in `ICON ITEM-ID → TITLE` form, translating satisfied `blocks` edges to neutral `then` while active or cancelled blockers remain `blocks`; `hands_to`, joins, disconnected components, and cycle warnings remain explicit. Humans can add `--full` for verbose nodes with status words, complete wrapped titles, active workers, critical-lane markers, and downstream pressure. `--full` is rejected with tree view. This is a read-only presentation over the same canonical map projection; JSON/MCP/HTTP always retain the stored `kind: "blocks"` and are identical across diagram detail choices.
+
+`map show --plan <plan-id>` narrows either human view to one plan's items and the links among them, with plan-scoped counts — plan-scoped goal runs on shared boards audit their slice, not the whole board. An unknown plan id is an error, never a silent unscoped view. Also available on MCP `planr_map_show` (`plan`) and HTTP `GET /v1/projects/{id}/map?plan=<plan-id>`.
+
+`map watch` is the read-only live companion for a second human terminal. Coding agents must not invoke it; they should use `map show --json` snapshots or `planr serve` plus `/v1/events/stream`. Watch defaults to the condensed `--view diagram`, polls every 1000 ms, compares the canonical scoped projection, and clears/redraws an interactive terminal only when graph state changes. `--full`, `--view tree`, `--plan <plan-id>`, `--interval-ms <n>` (minimum 100), `--no-clear`, and `--until-settled` control presentation and lifetime; Ctrl-C uses normal process interruption. JSON mode remains rejected because watch is intentionally human-only.
 
 `context list --tag <tag>` filters notes by the tag they were stored with (`context add --tag`), so e.g. the goal contract is recoverable with `planr context list --tag goal-contract` instead of scanning all notes.
 
@@ -124,6 +137,8 @@ With `--json`, responses follow one convention so agents never guess where data
 
 `review close` writes `.planr/reviews/<review-item-id>.review.md` and registers it as a review artifact. A `not-complete` or `unclear` verdict creates fix and follow-up review work; the follow-up review gates the same target item, so the chain keeps working with `--close-target`. With `--close-target` (complete verdicts only) the reviewed item is closed in the same command, provided it already has a completion log; the artifact is rendered after the target transition, so it snapshots the final target status. `--close-target` is also available through MCP `planr_review_close` and HTTP `POST /v1/reviews/{id}/close` (`"close_target": true`). `review close` responses include the same `remaining` progress snapshot as `done` and `close`. `--reviewer <id>` records the checker's identity on the review log, artifact, and event (defaults to the worker id), keeping maker and checker distinguishable in the audit trail. Closing an already-settled review fails with error code `already_closed` instead of silently duplicating evidence logs. The maker/checker split is derived, not declared: `review_mode` compares the closing reviewer identity against the target item's lease holder and reports `single_agent`, `independent`, or `unattributed` in the response, review log, artifact, and event — no ceremony note required. An `unattributed` close explains itself in the output: it means the target has no recorded lease (work was never picked or its lease was released), not that the reviewer's identity was missing.
 
+`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.
 
 `doctor` also reports the agent registry in all states without ever failing: absent (informational hint), degraded (parse error with line context), or loaded with profile/route counts, validation warnings, and per-artifact drift — a rendered role file whose content no longer matches what the current registry would render is flagged `drifted` with a `planr install <client> --force` hint, while files without the generated-from header are the user's (`manual`) and never flagged.

package/docs/IMPORT.md

@@ -7,10 +7,12 @@ planr import planr-package.json --preview
 planr import planr-package.json --confirm
 ```
 
-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:
 
 ```bash

package/docs/MCP_CONTRACT.md

@@ -41,6 +41,7 @@ Required groups:
 - approval request, approve, deny, and list
 - artifact add, list, and show
 - 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)
 - provider-neutral agent registry reads and route overrides
 - review annotate, ingest, artifact, evidence, and close
@@ -60,6 +61,10 @@ Review feedback ingestion is advisory:
 
 HTTP mirrors the same rule: `GET /v1/reviews/:id/artifact` is read-only; `POST /v1/reviews/:id/artifact` writes an artifact explicitly.
 
+## 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
 
 `planr install <client> --dry-run` prints the complete client-owned MCP, role, skill, and hook-reconciliation paths for Codex, Claude Code, and Cursor without writing them. Non-dry install writes only repository-local files, with this ownership contract:

package/docs/TASK_GRAPH_MODEL.md

@@ -60,6 +60,12 @@ planr link add <design-item> <implementation-item> --type blocks
 
 Use `blocks` for hard ordering. Use softer link types only when the product contract for that type is documented and tested.
 
+Structured output always keeps that canonical `blocks` kind. Human rendering adds
+current satisfaction state without mutating it: an upstream `closed` or
+`closed_partial` item renders as dim `blocks✓` in the compact tree and neutral `then`
+in the human-only diagram. Open, failed, and cancelled upstream items still render as
+red `blocks`; cancellation does not satisfy readiness.
+
 ## Picking
 
 Picking is the concurrency boundary:
@@ -155,6 +161,50 @@ Settling commands (`done`, `close`, `review close`) report what they `unlocked`
 
 ## Graph Inspection
 
+Coding agents use the compact default tree or `map show --json`. They must not
+invoke the diagram renderer. The boxed workflow diagram is exclusively for a
+person scanning the graph shape and current state:
+
+```bash
+planr map show
+planr map show --view diagram
+planr map show --plan <plan-id> --view diagram
+planr map show --plan <plan-id> --view diagram --full
+```
+
+The default diagram keeps every box to at most two content lines in
+`ICON ITEM-ID → TITLE` form. It still labels readiness-blocking routes, joins,
+disconnected components, and cycles. Active dependencies use `blocks`; satisfied
+dependencies use neutral `then`. Add `--full` for the previous verbose node
+layout with status words, complete wrapped titles, critical items, downstream
+pressure, and active workers. It is only a human renderer: coding agents do not
+invoke it, the SQLite map
+remains authoritative, the default `map show` view stays `tree`, and `--json`
+returns the same projection regardless of diagram detail.
+
+Human map states are colorized automatically on an interactive terminal while
+retaining their symbols and words. `--no-color`, `NO_COLOR`, `TERM=dumb`, pipes,
+and JSON stay plain.
+
+For a person to observe an agent live, use a second terminal:
+
+```bash
+# terminal A: agent/worker continues to pick, log, review, and close work
+# terminal B:
+planr map watch --plan <plan-id>
+planr map watch --plan <plan-id> --until-settled
+planr map watch --plan <plan-id> --full
+```
+
+`map watch` is human-only; coding agents must not invoke it. Watch defaults to
+the condensed diagram, polls once per second, and redraws only
+after a canonical graph change. `--full`, `--view tree`, `--interval-ms`, and
+`--no-clear` are available for detailed, compact-tree, or append-only
+observation. It records no graph events. Agents use `map show --json` or the
+local `/v1/events/stream` SSE endpoint instead.
+Machine consumers should use JSON snapshots or the local
+`/v1/events/stream` SSE endpoint.
+
 Use critical lane for ordering risk:
 
 ```bash

package/docs/TESTING.md

@@ -67,7 +67,7 @@ npm pack --dry-run
 Installer changes also require:
 
 ```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
 ```
 

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/docs/planr-spec/API_AND_DATA_MODEL.md

@@ -1,5 +1,7 @@
 # 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
 
 - SQLite: authoritative map graph state, picks, contexts, logs, runs, events, search indexes.