@llblab/pi-actors 0.22.2 → 0.22.4

package/AGENTS.md

@@ -49,6 +49,7 @@
 - `Communication direction`: The design target is an organic universal message layer across sync tasks, async runs, branches, tools, and coordinators. Breaking changes are allowed to compress concepts, remove accidental duplication, and make duplex communication symmetric where the domain is symmetric. | Trigger: Designing APIs or recipes that communicate | Action: Prefer a concentrated actor/message protocol (`spawn`, `message`, `inspect`, addressed endpoints, typed message envelopes, mailbox accepts/emits) over exposing FIFO/outbox/status mechanics directly; use one envelope for upward, downward, lateral, parent/branch, and branch/parent messages; absorb runtime async primitives into actor API instead of preserving parallel public concepts.
 - `Runtime IO discipline`: Tool stdout and temp state must stay bounded and local | Trigger: Changing execution, formatting, temp files, run state, logs, or artifacts | Action: Keep tail truncation/full-output temp files/failure formatting intact; keep extension-owned temp state under `~/.pi/agent/tmp/pi-actors` unless explicitly overridden
 - `Backlog is planning, not history`: `BACKLOG.md` should contain only completable future work with current task/scope/exit criteria; completed delivery history belongs in `CHANGELOG.md`, and durable or evergreen behavior belongs in `AGENTS.md`, README, docs, or skills | Trigger: Editing backlog or reconciling completed slices | Action: Remove historical progress narratives, version-scoped headings, watch-mode/monitoring principles, open-ended “continue evolving” items, and conditional “if usage proves” notes unless they are framed as a concrete gated task; keep priority order and prefer an 80/20 focus list when many remaining tasks compete for attention
+- `Changelog signal only`: Changelog bullets describe meaningful user/operator/developer changes, not release bookkeeping | Trigger: Preparing or editing release notes | Action: Do not add bullets that only say package, lockfile, or packaged skill metadata versions were bumped for this package; the version heading already carries that information. Mention dependency or package metadata changes only when the metadata change itself has user-visible or operational meaning
 - `Release artifact hygiene`: PR/release summaries become stale during active branch work and do not belong in the repository documentation tree | Trigger: Preparing release notes or PR bodies | Action: Create temporary/operator-facing artifacts outside the repo only during explicit release finalization; keep durable release evidence in `CHANGELOG.md` and open gates in `BACKLOG.md`
 - `Graceful actor retirement`: Coordinator/helper actors that exist only to supervise a bounded worker tree should have explicit retirement semantics instead of relying on the operator or LLM to remember cleanup | Trigger: Designing coordinator recipes, helper actors, worker fanout, locker-backed swarms, or auto-stop behavior | Action: Make retirement opt-in through recipe/run metadata, keep candidates blocked while active command-template branches or descendant `pi -p` workers are still running, retire only after observed child actors are terminal and outputs are flushed, prefer graceful control messages before process termination, record retirement events, and never infer retirement for persistent services or backlog implementers
 - `Persistent implementer workflows are recipe composition`: Backlog implementer scenarios should be launched through reusable component recipes, not one-off scripts or ad hoc shell orchestration | Trigger: Designing implementer swarms, backlog workers, coordinator-assigned task loops, or related recipes | Action: Compose cells such as `coordinator-locker`, subagent launchers, and actor-message utilities; preserve JSON envelope object shape across handoffs; add missing reusable component recipes only when needed; update the actors skill launcher map with supported scenarios

package/BACKLOG.md

@@ -1,74 +1,466 @@
 # Project Backlog
 
-## Open Work
-
-### Native Windows Smoke and Runtime Notification Follow-up
-
-- Priority: High.
-- Target: Post-0.22.0 validation and hardening.
-- Goal: Validate the cross-platform actor wake/notification layer on native Windows without changing the public actor API or replacing file-backed actor state as the observable source of truth.
-- Decision:
-  - Keep files as durable truth: mailbox/state/event/room files remain canonical for `inspect`, observability, crash recovery, and replay.
-  - Treat runtime notification as an advisory wake layer, not as the queue itself.
-  - Preserve `spawn`, `message`, and `inspect` as the only public actor API; platform transport choices stay internal.
-- Progress:
-  - Prepared the cross-platform runtime notification layer for release with a file-backed runtime notifier boundary using `notify(actor)` / `subscribe(actor, onWake)`, persisted `wake.jsonl` records, `fs.watch` subscription, and periodic fallback coverage.
-  - Notifier subscriptions can now receive explicit reconciliation callbacks for initial scan, wake-triggered scans, and polling fallback.
-  - Run-local `message` delivery now records the durable run inbox entry and advisory wake before attempting the optional live control endpoint; successful endpoint delivery marks the inbox entry `sent`.
-  - Run mailbox inspection now shows recent durable inbox entries alongside recipe-declared mailbox metadata.
-  - Added run inbox claim/handle/fail helpers for runtime loops, including locked claims so reconciliation callbacks can safely dispatch queued mailbox work once.
-  - Added mailbox-only run control endpoints so runtimes can accept `message` through durable inbox/wake state without requiring FIFO or named-pipe delivery.
-  - Migrated the packaged music-player control path to queued mailbox commands as the first concrete script using the mailbox-only runtime direction.
-  - Added a native Windows `wmp` music-player backend using legacy Windows Media Player COM via `powershell.exe`, with `wmplayer.exe` detection in standard Program Files locations and mailbox-backed controls mapped to WMP play/pause/stop operations.
-  - Hardened the music-player mailbox loop to avoid repeated unchanged mailbox reads by combining advisory wake records, `fs.watch`, and inbox signature polling.
-  - Improved Unix-like playback support with the macOS-native `afplay` backend, broader audio extension scanning, and process-group signaling for child playback controls.
-  - Room timeline appends and branch inbox append/status transitions now emit advisory wake records for the addressed room or branch actor.
-- Direction:
-  - Continue wiring mailbox-only endpoints and notifier reconciliation callbacks into concrete packaged actor scripts where file-backed mailbox dispatch should replace transport-specific control loops.
-  - Ensure message delivery writes durable file-backed mailbox/state first, then emits a wake notification.
-  - Require actor runtimes to reconcile mailbox state on wake and also on a periodic fallback so missed notifications do not lose work.
-  - Provide a universal baseline backend using file-system change notification plus periodic reconcile across Linux, macOS, and Windows.
-  - Keep FIFO/named-pipe/socket style endpoints as optional fast wake backends or compatibility paths, not as required durable queues.
-  - Document the model as "wake, not queue": notification wakes a live actor; files remain the queue and audit trail.
-- Windows smoke focus:
-  - Run installed `@llblab/pi-actors@0.22.0` or newer on native Windows.
-  - Verify simple `spawn` / `message` / `inspect` actor communication.
-  - Verify small room-swarm/subagent communication, branch/direct messages, mailbox claim/handled transitions, graceful stop/cancel behavior, and opt-in retirement.
-  - If smoke passes, update docs/release notes from "adapter support" to "Windows smoke-tested subagent communication" for the next release.
-- Exit:
-  - Actor communication works through the cross-platform notifier layer with public API unchanged.
-  - Inspect/observability continue to read canonical file state and do not depend on a live notifier process.
-  - Missed wake notifications are recovered by mailbox reconciliation.
-  - Windows subagent communication smoke is documented with results and any remaining limitations.
+## Implementation Boundary
+
+Work only inside `pi-actors`: strengthen the current Pi extension and local actor kernel. Do not split work into an external transportable standard, do not design `mcp-actors`, and do not change public positioning.
+
+Current carrying contour:
+
+- `spawn`, `message`, and `inspect` stay the durable public verbs.
+- Async run state stays file-backed and inspectable.
+- Tool exposure stays recipe-based and location-derived from `~/.pi/agent/recipes`.
+- Durable inbox and outbox files remain canonical intent and message state.
+- Rooms, rosters, and branch inboxes remain local coordination memory.
+- Wake notifications remain advisory acceleration, not the queue.
+- Operator-facing observability stays explicit and bounded.
+
+Core invariant:
+
+```text
+Recipe = portable executable capability.
+Run = addressable lifecycle instance.
+Message = typed semantic envelope.
+Mailbox = durable intent queue.
+Wake = advisory acceleration.
+Room = shared local coordination memory.
+Inspect = intentional observation.
+Artifact = durable result.
+```
+
+Non-goals:
+
+- Distributed workers.
+- Generic scheduler DSL.
+- Cloud sync.
+- External transport standard.
+- MCP implementation.
+- Arbitrary subrooms.
+- Heavy broker abstraction.
+
+## Hotfix Backlog
+
+No open hotfix items.
+
+## Minor Backlog
+
+### M-01 Internal Protocol Contract Pack
+
+- Priority: Medium.
+- Goal: Add machine-readable internal schemas and fixtures for implementation, docs, tests, and inspector consistency.
+- Files:
+  - `schemas/actor-message.schema.json`.
+  - `schemas/actor-address.schema.json`.
+  - `schemas/run-state.schema.json`.
+  - `schemas/run-inbox-message.schema.json`.
+  - `schemas/run-outbox-event.schema.json`.
+  - `schemas/room-message.schema.json`.
+  - `schemas/room-roster.schema.json`.
+  - `schemas/communication-snapshot.schema.json`.
+  - `schemas/recipe.schema.json`.
+  - `fixtures/protocol/run-minimal.json`.
+  - `fixtures/protocol/message-branch.json`.
+  - `fixtures/protocol/message-room-join.json`.
+  - `fixtures/protocol/mailbox-contract.json`.
+- Acceptance:
+  - Normalization outputs validate.
+  - Docs examples validate.
+  - Fixtures are usable by tests.
+  - Schemas are versioned with package version.
 
-### Consensus-First Build Recipe
+### M-02 Unified Actor Event Base
 
 - Priority: Medium.
-- Goal: Promote the proven proposer → implementer → QA → finalizer pattern into a generic packaged workflow instead of demo-specific scripts; pi-actors should grow its standard recipe/script library for recurring actor OS scenarios.
+- Goal: Add a shared base envelope for actor event-like records without forcing one storage file.
+- Target channels:
+  - `events`.
+  - `inbox`.
+  - `outbox`.
+  - `wake`.
+  - `room`.
+  - `branch`.
+- Acceptance:
+  - New append helpers generate ids consistently.
+  - Existing files remain readable.
+  - `inspect` can show id, correlation, and causation.
+  - No migration is forced.
+
+### M-03 Mailbox Contract v1
+
+- Priority: Medium.
+- Goal: Extend `mailbox.accepts` and `mailbox.emits` from string arrays to backward-compatible typed contracts.
 - Direction:
-  - Public inputs: mission, artifact paths/assertions, proposer role JSON, implementer prompt, QA prompt, model/thinking/tool knobs, and optional room/locker settings.
-  - Proposers should coordinate through room messages with no write tools.
-  - The implementer owns the first artifact write after inspecting room consensus.
-  - QA inspects artifacts and room evidence without mutating files.
-  - The finalizer applies QA-grounded fixes and emits `run.done` only after artifact assertions pass.
-  - Reuse packaged subagent/message/artifact components where practical; if a script is needed, make it a generic packaged helper in the extension, not a task-local demo script.
-- Exit:
-  - A packaged recipe can reproduce the interactive-music-instrument workflow shape for another single-artifact task without copying the demo script.
-  - Docs and skills point agents to the packaged recipe and explain when to choose it over a free-form room swarm.
+  - Keep string declarations valid.
+  - Normalize typed entries for inspection.
+  - Support fields such as body schema, ack requirement, idempotency, response requirement, level, and summary.
+- Acceptance:
+  - String declarations still work.
+  - `inspect view=mailbox` shows normalized contracts.
+  - Messages outside accepts produce advisory warnings by default, not hard blocks.
+  - Docs clarify advisory versus strict mode.
+
+### M-04 Actor Loop Helper SDK
+
+- Priority: Medium.
+- Goal: Provide reusable helpers for mailbox-consuming actors so recipe authors do not rewrite loops.
+- Files:
+  - `lib/actor-loop.ts`.
+  - `scripts/actor-loop.mjs`.
+- Capabilities:
+  - Initial reconciliation.
+  - Wake subscription.
+  - Polling fallback.
+  - Run and branch inbox claiming.
+  - Handled and failed status transitions.
+  - Outbox emission.
+  - Progress updates.
+  - Graceful stop handling.
+- Acceptance:
+  - A packaged demo recipe uses a mailbox-only control endpoint.
+  - Concurrent wake and poll paths do not double-process messages.
+  - Helper supports run inbox and branch inbox.
 
-### Persistent Backlog Implementer Workflow
+### M-05 Branch Delivery Unification
 
 - Priority: Medium.
-- Goal: Express persistent front/back backlog implementers as reusable extension-level recipe composition instead of bespoke workflow scripts.
+- Goal: Route direct branch messages and room multicast branch copies through one internal helper.
+- Target helper:
+  - `routeBranchEnvelope(stateDir, runId, message, { source })`.
+- Acceptance:
+  - Direct branch messages and room multicast produce the same durable branch inbox shape.
+  - Parent run dispatch envelope is consistent.
+  - Tests cover both paths.
+
+### M-06 Attention Semantics v1
+
+- Priority: Medium.
+- Goal: Formalize coordinator attention behavior through semantic metadata rather than transport knobs.
 - Direction:
-  - Use existing coordination cells such as `coordinator-locker` for queue/assignment/locking semantics.
-  - Compose existing subagent launcher recipes for execution slices rather than adding dedicated implementer scripts.
-  - Add missing reusable component recipes only when an implementer scenario cannot be expressed with the existing library.
-  - Update `skills/actors/SKILL.md` whenever a new implementer/coordinator recipe is added so agents know which scenario to launch and which packaged recipes to use.
-  - Preserve the protocol insight: implementers report `task.result` / `awaiting_assignment`, stay alive between assignments, and stop only after coordinator-issued control.
-- Exit:
-  - A packaged workflow, if added, is described by recipes and existing helper cells; no one-off backlog-implementer scripts are required.
-  - The actors skill documents the supported launch scenarios and the concrete packaged recipes for each.
+  - Support attention metadata such as `requires_response=true` and reason.
+  - Map response-required messages to follow-up.
+  - Keep progress/info messages inspectable or notify-only.
+  - Preserve existing internal `delivery` behavior.
+- Acceptance:
+  - `requires_response=true` becomes coordinator follow-up.
+  - Progress info stays log or notification.
+  - Explicit stop and kill controls do not create duplicate terminal follow-up.
+
+### M-07 Recipe Doctor
+
+- Priority: Medium.
+- Goal: Add intentional recipe health inspection.
+- Surface:
+  - `inspect target=recipes view=doctor`.
+  - `inspect target=recipes view=doctor verbose=true`.
+- Checks:
+  - Import graph health.
+  - Shadowing and blockers.
+  - Invalid or disabled recipes.
+  - Risky command templates.
+  - Absolute path portability.
+  - OS compatibility.
+  - Root permissions.
+  - Mailbox completeness.
+  - Artifact placeholder resolution.
+  - Stale or unused usage.
+- Acceptance:
+  - Compact output is grouped by severity.
+  - Verbose output is structured.
+  - No automatic cleanup happens.
+  - Every diagnostic has reason and suggested actions.
+
+### M-08 Artifact Manifest v1
+
+- Priority: Medium.
+- Goal: Extend recipe artifacts from string paths to backward-compatible artifact metadata.
+- Direction:
+  - Keep string artifact paths valid.
+  - Add optional object fields such as path, kind, media type, and required.
+  - Resolve manifests with existence, size, and optional hash.
+- Acceptance:
+  - String artifacts remain valid.
+  - Runtime resolves manifest with `exists`, `size`, and optional `sha256`.
+  - Terminal follow-ups group named artifacts.
+  - Missing required artifacts are visible in result and inspect output.
+
+### M-09 Lifecycle Retention Policy
+
+- Priority: Medium.
+- Goal: Add explicit archive and prune behavior for terminal run state.
+- Messages:
+  - `control.archive`.
+  - `control.prune`.
+- Direction:
+  - Only terminal runs can be archived or pruned.
+  - Active runs fail closed.
+  - Archive moves or compresses state with a tombstone.
+  - Prune deletes terminal state after ownership checks, optionally preserving artifacts.
+- Acceptance:
+  - Terminal cleanup candidates are inspectable.
+  - Artifacts can be preserved.
+  - Active run deletion is impossible.
+
+### M-10 Inspector v2 For Unread Mentions And Needs Response
+
+- Priority: Medium.
+- Goal: Strengthen the TUI inspector as the operator membrane for multi-actor sessions.
+- Direction:
+  - Add stable event ids in previews.
+  - Add unread cursor per session, run, and room.
+  - Preserve mention filtering.
+  - Add needs-response marker from attention semantics.
+  - Distinguish room timeline rows from branch inbox rows.
+- Acceptance:
+  - `/actors-inspector-filter unread` works.
+  - `/actors-inspector-filter mention <text>` works.
+  - `/actors-inspect <number>` marks the item read for the current session.
+  - Unread state stays UI/session metadata, not protocol truth.
+
+### M-11 Run State Index
+
+- Priority: Medium.
+- Goal: Add a rebuildable run-state index to reduce recursive scans and improve observability performance.
+- Target file:
+  - `~/.pi/agent/tmp/pi-actors/runs/index.json`.
+- Contents:
+  - State dir.
+  - Run id.
+  - Owner id.
+  - Status.
+  - Updated time.
+  - Recipe or tool.
+- Acceptance:
+  - Index accelerates list and summarize.
+  - Corruption falls back to scan.
+  - Rebuild helper exists.
+  - Nested runs are represented without id collision.
+
+### M-12 Internal Conformance Runner
+
+- Priority: Medium.
+- Goal: Add a CI-ready internal conformance runner for pi-actors protocol behavior.
+- Script:
+  - `npm run conformance`.
+- Suites:
+  - Recipe discovery.
+  - Register, update, and delete.
+  - Spawn lifecycle.
+  - Message routing.
+  - Room roster.
+  - Branch inbox.
+  - Ownership checks.
+  - Artifacts.
+  - Attention semantics.
+- Acceptance:
+  - Runs without Pi UI where possible.
+  - Outputs compact report.
+  - Fixtures live in the repository.
+  - CI can run it.
+
+### M-13 Packaged Actor Worker Recipe Template
+
+- Priority: Medium.
+- Goal: Add a canonical packaged recipe or template for a long-lived worker-backed branch actor.
+- Direction:
+  - Worker joins room.
+  - Worker declares mailbox accepts and emits.
+  - Worker claims branch inbox messages.
+  - Worker posts `task.claim`, `task.result`, and `awaiting_assignment`.
+  - Worker handles `control.stop`.
+- Acceptance:
+  - Recipe demonstrates correct mailbox loop semantics.
+  - It is a recipe-authoring example, not a product feature.
+
+### M-14 Recipe Usage Integrity Improvements
+
+- Priority: Medium.
+- Goal: Make recipe usage tracking more explainable.
+- Direction:
+  - Add fingerprint diff reason.
+  - Add reset reason.
+  - Consider optional last error.
+  - Split launch counts by tool, spawn, and direct recipe.
+- Acceptance:
+  - `inspect recipes view=summary verbose=true` shows whether usage refers to current recipe content.
+  - Doctor can flag unused current meaning instead of stale old recipe history.
+
+### M-15 Safer Command Warning Policy
+
+- Priority: Medium.
+- Goal: Unify command-template diagnostics by severity and make warnings actionable without startup spam.
+- Severity:
+  - `info`: portability.
+  - `warning`: broad mutation, shell, or eval.
+  - `error`: impossible, invalid, or unsafe repeat.
+- Direction:
+  - Treat legitimate `bash` wrappers as expected trusted boundaries when already packaged or explicitly registered.
+  - Keep routine shell wrapper notes out of startup warning blocks.
+  - Surface shell/eval/destructive diagnostics through register-time warnings, doctor, and verbose recipe inspection.
+- Acceptance:
+  - Command-template warnings include command label, reason, and suggested mitigation.
+  - `register_tool` shows relevant warnings.
+  - Recipe doctor aggregates warning policy.
+  - Startup no longer emits large warning blocks only because recipes wrap `bash`.
+
+### M-16 Output And Log Size Governance
+
+- Priority: Medium.
+- Goal: Keep stdout, stderr, result, outbox, and actor-message previews bounded in agent context.
+- Direction:
+  - Centralize constants for body preview, outbox preview, inspector preview, and tail lines.
+  - Keep verbose output opt-in.
+  - Prefer files or artifacts for large bodies.
+- Acceptance:
+  - Actor messages and previews share consistent caps.
+  - Verbose mode is explicit.
+  - Large bodies do not flood normal tool output.
+
+### M-17 Windows And Nix Portability Pass
+
+- Priority: Medium.
+- Goal: Strengthen current portability around FIFO, named-pipe, and mailbox-only paths without adding a new backend.
+- Direction:
+  - Doctor flags FIFO-only recipes on native Windows.
+  - Keep mailbox-only demo cross-platform.
+  - Document platform matrix.
+  - Cover named-pipe adapter with injected sender where practical.
+- Acceptance:
+  - Native Windows limitations are visible before launch.
+  - Mailbox-only recipe works cross-platform.
+  - Docs and tests cover the adapter split.
+
+### M-18 State Corruption Recovery
+
+- Priority: Medium.
+- Goal: Add resilient JSON and JSONL state readers.
+- Direction:
+  - Malformed JSONL lines should not kill entire inspect paths.
+  - Corrupt JSON files should report diagnostics with paths.
+  - Consider optional `.corrupt` quarantine helper.
+- Acceptance:
+  - Inspect remains useful when partial state survives.
+  - Corrupt paths are reported clearly.
+  - Canonical state is not silently rewritten without explicit action.
+
+### M-19 Recipe Import Graph Inspector
+
+- Priority: Medium.
+- Goal: Add focused inspection for recipe import graphs.
+- Surface:
+  - `inspect target=recipes view=imports`.
+  - `inspect target=recipes view=imports verbose=true`.
+- Acceptance:
+  - Shows import graph, aliases, resolved paths, and shadowed imports.
+  - Shows cyclic and depth diagnostics.
+  - Helps debug packaged and user recipe composition.
+
+### M-20 Spawn Preflight Mode
+
+- Priority: Medium.
+- Goal: Add dry-run launch planning for `spawn` and async recipe tool invocation.
+- Direction:
+  - Resolve recipe, imports, args, artifacts, state dir, command graph, and mailbox metadata.
+  - Do not start a process.
+  - Return warnings and resolved launch plan.
+- Acceptance:
+  - `preflight=true` returns a resolved plan.
+  - No process is spawned.
+  - Missing args and risky commands are reported before launch.
+
+### M-21 Run Restart And Reattach Policy
+
+- Priority: Medium.
+- Goal: Clarify and implement safe behavior for reused `run_id` and `state_dir`.
+- Direction:
+  - Active reuse fails closed.
+  - Terminal restart with same id is allowed under explicit semantics.
+  - Record generation or restarted time.
+  - Preserve previous terminal-state policy.
+- Acceptance:
+  - Active reuse remains blocked.
+  - Terminal restart records generation or `restartedAt`.
+  - Inspect shows restart semantics.
+  - Docs are updated.
+
+### M-22 Actor Address Helper CLI And Tooling
+
+- Priority: Medium.
+- Goal: Improve address normalization and diagnostics for recipe authors and tests.
+- Direction:
+  - Add helper functions or inspect view for address validation.
+  - Improve invalid-address diagnostics.
+- Acceptance:
+  - Diagnostics include expected forms.
+  - Examples cover branch, room, run, session, and tool addresses.
+  - No new public address kinds are added.
+
+### M-23 Room Compaction Metadata Improvements
+
+- Priority: Medium.
+- Goal: Record richer room compaction metadata.
+- Direction:
+  - Track dropped count.
+  - Track first and last kept timestamps.
+  - Track configured max.
+- Acceptance:
+  - `inspect room:<run> view=status verbose=true` shows compaction info.
+  - Compaction never corrupts JSONL.
+  - Tests cover low `PI_ACTORS_ROOM_MAX_MESSAGES`.
+
+### M-24 Coordinator Follow-Up Deduplication
+
+- Priority: Medium.
+- Goal: Suppress duplicate terminal transitions and outbox follow-ups across watcher reloads, session restarts, or line-counter resets.
+- Direction:
+  - Use event id and stateDir for deduplication where available.
+  - Preserve terminal handled semantics.
+  - Simulate watcher restart in tests.
+- Acceptance:
+  - Duplicate follow-up is suppressed after reasonable watcher reset.
+  - Terminal handled state remains effective.
+  - Tests cover restart and line-counter reset scenarios.
+
+### M-25 Documentation Refactor Runtime Contracts First
+
+- Priority: Medium.
+- Goal: Reorganize docs so implementation agents find stable contracts before examples.
+- Target order:
+  - `docs/runtime-contracts.md`.
+  - `docs/actor-messages.md`.
+  - `docs/async-runs.md`.
+  - `docs/tool-registry.md`.
+  - `docs/template-recipes.md`.
+  - `docs/command-templates.md`.
+  - `docs/recipe-authoring.md`.
+  - `docs/troubleshooting.md`.
+- Acceptance:
+  - No polling-first examples.
+  - Every example matches fixtures.
+  - Docs distinguish protocol semantics from Pi UI commands.
+  - No external standard or MCP work is introduced.
+
+## Suggested Milestone Order
+
+```text
+Patch release:
+  H-01..H-12
+
+Minor 0.23 — Contract consolidation:
+  M-01, M-02, M-03, M-12, M-25
+
+Minor 0.24 — Runtime/message reliability:
+  M-04, M-05, M-06, M-13, M-24
+
+Minor 0.25 — Operator hygiene:
+  M-07, M-08, M-09, M-14, M-15, M-16
+
+Minor 0.26 — Inspector and state scaling:
+  M-10, M-11, M-18, M-19, M-23
+
+Minor 0.27 — Portability and lifecycle polish:
+  M-17, M-20, M-21, M-22
+```
+
+## Blocked Or Opportunistic Carry-Over
 
 ### Branch-Local Checkpoint Semantics
 
@@ -90,30 +482,13 @@
 - Exit:
   - Deleting a recipe file removes the corresponding runtime tool definition and active-tool entry without session restart.
 
-### Recipe Discovery Expansion
-
-- Priority: Low.
-- Goal: Support larger recipe libraries without confusing recipe identity or priority.
-- Direction:
-  - Add nested recipe directories only after flat `recipes/*.json` discovery semantics are stable.
-  - Keep same-id priority and invalid-blocking behavior explicit if nested ids are introduced.
-
 ### Actor Recipe Feedback Loop
 
 - Priority: Low.
 - Goal: Turn actor recipe-context awareness into a practical improvement loop for packaged recipes and operator-owned recipe memory.
 - Direction:
   - After real multi-agent runs, capture whether child actors report that recipe/import/mailbox/role boundaries fit the task.
-  - Keep the loop advisory and operator-gated: feedback may suggest recipe edits or copying into `~/.pi/agent/recipes`, but must not auto-save or rewrite durable recipes without confirmation.
-  - Prefer small recipe/readme/skill refinements over adding scenario catalogs; recurring patterns should become packaged recipes only after repeated use.
+  - Keep the loop advisory and operator-gated.
+  - Prefer small recipe, README, and skill refinements over scenario catalogs.
 - Exit:
-  - At least one real run produces recipe-boundary feedback that is either applied to a recipe/docs change or explicitly rejected with rationale.
-
-### Recipe Usage Telemetry Evolution
-
-- Priority: Low.
-- Goal: Improve long-term operator insight into recipe usefulness without making telemetry noisy.
-- Direction:
-  - Consider sidecar stats sync/backup policy after inline user-owned `usage.calls` / `usage.last_called` proves useful.
-  - Consider an operator-approved recipe promotion workflow that turns successful package/ad hoc/direct spawn suggestions into a reviewed `~/.pi/agent/recipes` entry with provenance and diff, without auto-saving.
-  - Do not add failure counters as primary usefulness evidence unless there is a strong operator-facing need.
+  - At least one real run produces recipe-boundary feedback that is applied or explicitly rejected with rationale.