pmx-canvas 0.11.0 → 0.12.1

package/docs/node-types.md

@@ -17,7 +17,7 @@ see [MCP tools](mcp.md), [HTTP API](http-api.md), and [SDK](sdk.md).
 | Type | Purpose |
 |------|---------|
 | `markdown` | Rich markdown with rendered preview |
-| `status` | Compact status indicator (phase, message, elapsed time) |
+| `status` | Authored work card, or a compact phase/message status indicator |
 | `context` | Context cards, token usage, workspace grounding |
 | `ledger` | Execution ledger summary |
 | `trace` | Agent trace pills (tool calls, subagent activity) |
@@ -48,6 +48,48 @@ response warns about the distinction.
 Thread node types `prompt` and `response` exist internally for agent
 conversation rendering and are not created through public APIs.
 
+## Work cards
+
+Choose **New work card** in the canvas background menu, then **Edit** inside the card.
+Title, work state, detail and optional progress save together. Cancel (or Escape inside
+the form) discards the draft. Editing grows the card locally without resizing its saved
+frame. A refused or stale save keeps the draft; Cancel returns to the latest saved state.
+Drafts, refused saves and pending saves survive opening and closing focus mode in the
+same browser tab. Unsaved drafts are not persisted across a page reload.
+
+Agents use ordinary status-node creation/update with `data.workState`: `todo`,
+`in-progress`, `blocked`, `done` or `cancelled`. `data.detail` is a string;
+`data.progress` is an optional number from 0 to 100, or `null` to clear it.
+State and progress are independent: Done does not invent 100%.
+
+```json
+{"type":"status","title":"3. Verify","data":{"workState":"in-progress","detail":"Run the browser checks.","progress":60}}
+```
+
+These are deliberately authored plans, not a task feed. They create no session, task,
+approval or execution. Connect them with existing relations, including intentional loops.
+Status nodes without `workState` or `workItemId` keep their existing phase/tool display.
+
+### Read-only live task cards
+
+Choose **Show on board** on a session task row to present that existing task. **Show card**
+focuses its existing presentation. No task or session automatically creates a card.
+Agents use ordinary status creation with `data: { workItemId: "<existing-task-id>" }` on
+the active board. The immutable reference includes `workItemBoardId`, defaulting to the
+active board. Moving the presentation to another board preserves that original task owner;
+an ordinary planning card cannot be converted by patching it.
+
+Title, detail, work state and attribution are derived from the task record, not independently
+editable card fields. Do not supply those fields or progress when creating a live card.
+The persisted display cache is refreshed on task changes, Undo and reload. Update the task
+through the existing work-item API, not a card PATCH. Geometry, pins and relations remain editable.
+Ending a session preserves its task cards; removing a card does not cancel the task.
+A missing task displays **Task unavailable**, never an actionable control. Static exports
+label live cards as read-only snapshots. No progress percentage or approval controls are added.
+Selective board copies become independent authored work cards, without a task reference or task attribution.
+
+## Shared node behavior
+
 The spatial board and its content scale proportionally at every zoom, without
 switching layouts. Iframe previews mount automatically near the viewport and
 remain mounted to preserve arbitrary app state. There is no lifetime preview cap;
@@ -407,6 +449,22 @@ Read the settled node geometry after mounting rather than treating requested
 dimensions as final. Prefer targeted node reads or the CLI's projected layout
 fields over fetching full content merely to check spacing.
 
+### Move original cards between boards
+
+Use **Move to new board** from the selection bar or a group's **⋯** menu. Name the
+destination, preview the expanded selection and its pins/README/history effects, then
+choose **Move and open**. Groups include all descendants. The source receives a working
+portal; the destination contains the same card identities, not copies. A late reply never
+overrides a newer board choice. If the reply is interrupted, **Retry move** reuses the same
+request without creating a duplicate destination.
+
+Save or cancel local drafts first. Runtime sessions, streams, authority-bearing controls,
+partial imports and unsupported cross-board references can refuse the whole move with a
+reason. Read-only live task cards keep their original owner; moving never starts or cancels
+a task. Board-space annotations stay on the source. Pre-move Undo/Redo clears on affected
+boards; older snapshots remain inspectable, but cannot restore across that boundary.
+See the [move contract](http-api.md#move-original-cards-to-a-new-board) for agent access.
+
 ## HTML nodes
 
 `html` nodes render a normal self-contained HTML/JS document in a sandboxed iframe.
@@ -570,6 +628,10 @@ as dashed-border frames with a title bar and optional accent color.
   its children stay as independent nodes (one undo step); `canvas_group { action: "ungroup" }`
   does exactly the same
 - Collapsing a group hides children and shows a summary
+- **Open group** in the frame menu, or Enter on the focused frame, drills into its
+  original cards. Breadcrumbs and Escape restore the parent camera and selection.
+  Outside-link stubs navigate to the actual cards. This view creates no boards or
+  copies and does not change context pins or what agents can read.
 - By default, group creation preserves the children's current positions and
   expands the frame around them
 - Pass `childLayout` to auto-pack children (`grid`, `column`, `flow`)
@@ -584,6 +646,14 @@ canvas_group({ action: 'create', title: 'Auth Module', childIds: ['node-1', 'nod
 
 All edges support labels, styles (solid/dashed/dotted), and animation.
 
+Select an edge to edit its kind, label or reason inline, or delete it. Parallel
+links show their pair count. Dependency counts report cyclic clusters and cards
+affected downstream of the selected cards; `loop` and `if-fails` remain inert flow
+illustrations. Qualified dependency/source warnings carry a separate amber mark.
+In a card's Relations panel, **Show lineage** highlights its local dependency and
+derivation component; **Show on canvas** highlights its direct connections. Remote
+targets remain accessible through their named references.
+
 Native edges optionally carry `toBoardId`: `from` belongs to the open source
 board and `to` identifies a card on that target board. These connections appear
 in the visible source card footer with readable board/card titles; missing

package/docs/plans/plan-009-tech-debt-backlog.md

@@ -124,7 +124,7 @@ Logs: `/tmp/pmx-w3-debt-baseline.zPoaEM/log` and `/tmp/pmx-w3-debt-after.iXN2fq/
 |---|---|
 | Before larger-library scaling | `lifecycle-status.ts` reads every board and each card's full review history even for one-card requests. `KnowledgeSync` reloads workspace qualifications after board changes. Bound narrow reads to the dependency closure, batch/index review summaries, and separate folder aggregates from card detail when scaling this path. Measure populated review histories and long dependency chains as well as empty history. Avoid a TTL cache: cadence, sessions, retirement and source changes have different invalidation clocks. |
 | Wave 4, frame host | **Implemented locally in the 0.11 candidate:** `ViewerHost` owns preview admission and `RefreshingViewerFrame` owns loading, painted replacement and Retry. `ExtAppFrame` is the protocol adapter, without its former recovery ladder. Draft/refresh, stacking and gesture regressions are covered. Native WebKit acceptance and the self-contained MCP document's additional Mermaid bytes remain explicit limits, not a second deferred recovery implementation. |
-| Wave 5, groups and agent output | Keep board-qualified relation/provenance identities when moving cards into or out of a board. Review records currently outlive snapshots and are keyed by board + card; define their move semantics before adding make-board/inline-board. Do not clone validation as if a new claim had been checked. |
+| Wave 5, groups and work planning | **Scope revised 2026-10-27:** only Move to new board, leaving a portal; no reverse move. Keep board-qualified relation/provenance identities and audit access across the move. Review records outlive snapshots and are keyed by board + card; [plan 020](plan-020-wave-5-work-planning.md) requires atomic persistence/retries, an explicit Undo/snapshot boundary and runtime-binding checks. A move never renews validation. Ordinary planning cards do not require session records. |
 | Journal and shared/hosted stages | The due evaluator still reads the local `canvasState` singleton. Separate runtime acquisition from qualification when a second runtime needs it, not by speculative package splitting now. Filter authorized sources before summaries, titles and lifecycle reasons are computed. Categories are not permissions. Keep validation audit distinct from an undoable content journal and finish the authoritative mutation-path decision before event sourcing. |
 | Test maintenance | Large integration files remain (`server-api.test.ts`, `canvas.pw.ts`). Split by owning domain when those domains next change, preserving isolation and race cases. Do not replace human browser or real transport checks with source-string assertions to make the suite cheaper. |
 

package/docs/plans/plan-019-post-0.9-roadmap.md

@@ -5,6 +5,13 @@ with fresh post-push reviews and all five CI jobs passing. The maintainer author
 release of 0.11.0; release metadata and publication gates follow the checkpoint below.
 Versions after 0.11 remain proposals, not publication approval; every release must pass
 the [release gates](../RELEASE.md).
+**Wave 5 planning update (2026-10-27):** the owner settled deliberate work presentation,
+ordinary planning cards independent of Sessions, unchanged ghost feedback, and **Move to new
+board** with a portal. Agents also gain the human pen, text and eraser capabilities for
+questions and emphasis alongside existing board tools. No reverse move or general `ask` card in this wave. See the detailed
+[implementation plan](plan-020-wave-5-work-planning.md); implementation has started with
+annotation parity. Work-card authoring, live-task views, relations/group navigation and
+board moves remain planned.
 **Sources:** [product vision](../product-vision-2026-09.md) (moves and the 2026-10-19 sequence),
 [design.md build plan](../design.md#build-plan) (Waves 4, 5, Later),
 [plan 009](plan-009-tech-debt-backlog.md) (open debt),
@@ -24,7 +31,7 @@ measured; the maintainer carries that risk rather than reinstating an earlier ga
 | 1 | 0.9.3 | Cleanup: tour debt, large-board costs, bounded due evaluator, MCP reconnect, lint | 12, 1 | S–M |
 | 2 | 0.10 | MCP hardening, operation help and bounded discovery-schema reduction | 6a, 1 | M |
 | 3 | 0.11 | One frame host, proportional spatial zoom, Wave-0 design pass | 5, 9 | M–L |
-| 4 | 0.12 | Wave 5: agent output as nodes, make/inline board, group drill-in, relations sketch parity | 3, 0 | L |
+| 4 | 0.12 | Wave 5: deliberate work planning, Move to new board with a portal, group drill-in, relations sketch parity | 3, 0 | L |
 | 5 | later | Trust (M half), journal, concurrent boards, binary | 7, 4, 8 | L–XL |
 | 6 | end | Curation-effect baseline and reruns; skill-prompt benchmark | Part 1 item 4 | S–M |
 
@@ -566,26 +573,43 @@ responses even when writes already persisted.
 ## Step 4: 0.12 Wave 5 and relations sketch parity
 
 [Vision move 3](../product-vision-2026-09.md#3-the-agents-output-moves-onto-the-board-m), move 0's
-make board / inline board, [design.md Wave 5](../design.md#build-plan) and the remaining
-Relations/Flows/Uses sketch parity.
-
-**Before building:** decide how board-qualified relations, provenance and review records move
-when a card moves into or out of a board (plan 009 "Wave 5, groups and agent output"), and the
-move 3 open questions (decision 3).
-
-- Work items as `status` nodes; gates, elicitations and mode requests as one `ask` node with an
-  attributed answer (new node type: follow the "Adding New Node Types" checklist in `CLAUDE.md`).
-- Make board / inline board; group drill-in with breadcrumbs and outside endpoint stubs.
-- Relations sketch parity: inline edge editor, amber stale-lineage strokes, pair/cycle/affected
-  badges, Show lineage / Show on canvas.
+board extraction, [design.md Wave 5](../design.md#build-plan) and the remaining
+Relations/Flows/Uses sketch parity. The owner reaffirmed the drawings and revised the behavior
+on 2026-10-27. [Plan 020](plan-020-wave-5-work-planning.md) owns implementation slices,
+code ownership, transport parity, move invariants and acceptance cases.
+
+- Ordinary cards and relations let humans and agents plan steps, show progress, compare options
+  and illustrate loops. Presentation is deliberate, never an automatic card per work item/event.
+- Agents can draw, write questions and erase whole marks through the same annotation layer
+  as humans, without Sessions. These supplement existing tools and ghost feedback; a mark
+  does not create an approval gate or interpret a human's response automatically.
+- Nodes/edges own the authored plan. Existing session records own running session work; an
+  explicitly linked card presents the same live state. Starting a session does not convert plans.
+- Native-agent approvals stay in the host; existing PMX session controls/protections remain.
+  Defer the general `ask` card. Keep the policy, host capability, command registry, fleet and
+  current explicit/automatic ghost behavior unchanged.
+- **Move to new board** from multi-selection or a group's **⋯** menu moves cards and leaves a
+  portal. No reverse move or inline-board operation in this wave.
+- Open a group within the existing board with breadcrumbs and outside endpoint stubs; navigation
+  creates no board. Complete inline edge editing, stale-lineage warnings, pair/cycle/affected
+  badges and Show lineage / Show on canvas. Intentional flow loops do not execute themselves.
+
+**Before the move implementation:** resolve plan 020's engineering checkpoints for historical
+board-qualified references, old snapshots/Undo, runtime-bound cards and atomic multi-board
+persistence. Any restore restriction or unsupported live move needs explicit review; product
+agreement is not approval to drop data or expand into the journal/concurrent-board roadmap.
 
 **Done when**
-- design.md's Wave 5 check: agent output uses the same shell and tokens; a group opened as a
-  board shows its outside stubs.
-- Moving a card preserves its outside links and audit identity; copying a claim does not
-  copy its validation.
-- A changed source turns downstream edges amber on the board, not only the card footer.
-- The `ask` node renders in a live browser board (DOM check), not only in unit tests.
+- Human and agent can author and revise the illustrated plan without Sessions; no implicit
+  work records, approvals or loop execution arise from drawing it.
+- Human and agent annotations share rendering, persistence and erase behavior, with transport
+  parity and inspected browser coverage for questions, pointing and reciprocal erasing.
+- Explicit live-task views agree with session state, while unrelated planning cards stay ordinary.
+- Group drill-in retains outside connections without changing board count or ownership.
+- Moving cards preserves identity, outside links, pins and audit meaning through interruption,
+  retry and restart; it does not renew validation or lose viewer/attachment content.
+- Dependency/source warnings and relation controls match the drawings and semantic tokens in
+  the inspected browser cases. The acceptance manifest and public transport docs cover the flow.
 
 ## Step 5: later
 
@@ -639,7 +663,7 @@ before the hosted second writer. Decision 6 must be settled before accounts and
 |---|---|---|---|
 | 1 | MCP hardening before the frame host | Steps 2–3 order | **Decided 2026-10-19:** yes, MCP is the agent half. A narrow WebKit fix can still ship as a patch |
 | 2 | Version numbers and batch size | Every release | One minor per step, as above |
-| 3 | Keep the `policy` singleton, `host-capability`, the command registry; ghost intents opt-in? | Step 4 | Decide before Wave 5 |
+| 3 | Session mechanisms and ghost intents | Step 4 | **Decided 2026-10-27:** keep policy, host capability, named commands and fleet behavior; preserve explicit and automatic ghost feedback. Ordinary planning is independent of Sessions; work presentation is deliberate. See plan 020 |
 | 4 | Gate a release on native Copilot/WebKit, Windows, the Amp context pill or npm-installed execution? | Steps 2–3 | None gates 0.10; revisit for the hosted version |
 | 5 | File-confinement default | Step 5.1 | Per-board allow-root list |
 | 6 | Context vision: personal- or team-first wiki, personal-space owner, who publishes, default wiki entry, assistant defaults | Hosted accounts and scopes | Decide before hosted accounts |