planr - npm Package Compare versions

Comparing version 1.5.2 to 1.6.0

docs/CLI_REFERENCE.md

@@ -16,3 +16,4 @@ # CLI Reference
 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>
@@ -81,3 +82,3 @@ planr map lane --critical
 
-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.
 
@@ -99,4 +100,8 @@ ## JSON Envelope Convention
 
-`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.
@@ -103,0 +108,0 @@

docs/TASK_GRAPH_MODEL.md

@@ -63,2 +63,8 @@ # Planr Task Graph Model
 
+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
@@ -159,2 +165,46 @@
 
+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:
@@ -161,0 +211,0 @@

package.json

 {
   "name": "planr",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "description": "Local-first planning and execution coordination for coding agents.",
@@ -5,0 +5,0 @@ "license": "MIT",

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

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

 {
   "name": "planr",
-  "version": "1.5.2",
+  "version": "1.6.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": {

README.md

@@ -139,6 +139,19 @@ # Planr
 
-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).
@@ -145,0 +158,0 @@ - **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).

No alert changes

Improved metrics

Total package byte prevSize

26291907

1.24%

Number of lines in readme file

183

7.65%

No dependency changes