@llblab/pi-actors 0.42.2 → 0.43.0

package/docs/component-recipes.md

@@ -1,148 +1,45 @@
 # Component Recipes
 
-Component recipes are small saved recipe definitions that expose one coordination capability each. They are the construction kit for higher-level subagent coordinators: a coordinator composes components instead of embedding one large orchestration DSL.
+Component Recipes are weakly coupled command-template cells used inside higher-level Recipes. They do not create a social protocol or become independently addressable peers.
 
-## Boundary
+## Contract
 
-This is a weak abstract contract, not a hard dependency model.
+A useful component has:
 
-- `pi-actors` provides root `recipes/` actor component definitions and runtime bindings.
-- Portable coordination skills should target capabilities, not this extension by name.
-- Local adapters bind abstract components to concrete recipes, command templates, async runs, model aliases, files, and tool registries.
-- A component should be replaceable by another implementation with the same capability contract.
+- explicit typed inputs and caller-owned policy knobs;
+- one narrow responsibility;
+- deterministic output shape or declared artifact;
+- bounded failure behavior;
+- no hidden model/provider assumption;
+- no actor-local Control unless it owns a real service loop.
 
-## Component Contract
+## Families
 
-Every reusable component recipe should make the following clear:
+- normalization and prompt shaping;
+- planning and task-card generation;
+- evidence maps, contradiction maps, and criticism;
+- review, verification, merge, judge, and quorum stages;
+- artifact generation, manifesting, and deterministic writes;
+- validation and package/skill summaries.
 
-- **Capability**: the one operation it performs.
-- **Args**: caller-controlled prompts, scopes, paths, models, and policy knobs.
-- **Output**: the expected shape of stdout or artifact paths.
-- **Messages**: optional actor-message envelopes for checkpoints, questions, progress, or findings.
-- **Failure policy**: whether failures stop the root, only fail a branch, or are recoverable.
-- **Non-goals**: coordination behavior the component intentionally does not own.
+## Composition
 
-Reusable components should expose common policy knobs instead of baking in local choices: `model`, `thinking`, `tools`, `output_format`, `evidence_policy`, `risk_policy`, source policy, continuity/resume policy, handoff format, merge mode, model pools, and stage-specific models. Higher-level recipes may pass these knobs through so the same component can run as a safe no-tools reviewer, a file-reading reviewer, a release gate, a research synthesizer, a task-card author, or a high-thinking merger.
+Import components by alias and call named nodes in a template array/object. Parent command-template flags own sequence, parallelism, concurrency, retries, failure scope, recovery, repetition, and output acceptance.
 
-Keep components narrow. Higher-level recipes should own composition, not hidden behavior inside a leaf.
+Variable branch output should converge into stable JSON, Markdown, artifacts, or command results before downstream stages. Large evidence belongs in artifacts or complete captures; concise milestones belong in Trace.
 
-## Spectrum of Components
+## Boundaries
 
-### Launchers
+- Imports are definitions inside one Run.
+- One-shot components omit Control.
+- Components never infer caller identity or lifecycle authority.
+- A parent may declare artifacts that imported cells write.
+- A child failure follows explicit parent failure/recovery policy.
 
-Start one subagent or branch with a caller-provided prompt and model. Launchers do not judge or merge output.
+Use the packaged Recipe library before creating a new component. Add one only when at least two stable compositions need the same narrow behavior.
 
-Examples: `recipes/subagent-prompt.json`, `recipes/subagent-tools.json`, and `recipes/subagents-prompts.json`.
+## Related
 
-### Reviewers
-
-Inspect a scope through a declared lens and return evidence-grounded findings.
-
-Seed example: `recipes/subagent-review.json`.
-
-### Critics
-
-Attack assumptions, edge cases, and failure modes. Critics should not rewrite the plan unless asked.
-
-Seed example: `recipes/subagent-critic.json`.
-
-### Planners
-
-Turn a goal into bounded slices, validation gates, risks, and stop conditions.
-
-Seed example: `recipes/subagent-plan.json`.
-
-### Verifiers
-
-Check a claim, artifact, or proposed result against evidence. Verifiers should separate proven, disproven, and unknown.
-
-Seed example: `recipes/subagent-verify.json`.
-
-### Evidence and Contradiction Mappers
-
-Map source support, weak evidence, contradictions, unresolved assumptions, and missing source classes before synthesis.
-
-Seed examples: `recipes/subagent-evidence-map.json` and `recipes/subagent-contradiction-map.json`.
-
-### Mergers
-
-Combine multiple branch outputs into a single synthesis. Mergers preserve minority findings and mark unsupported additions.
-
-Seed example: `recipes/subagent-merge.json`.
-
-### Normalizers, Artifacts, and Events
-
-Convert variable branch output into stable JSON, Markdown sections, file artifacts, or actor-message records for downstream recipes.
-
-Seed examples: `recipes/subagent-normalize.json`, `recipes/subagent-artifact.json`, and `recipes/subagent-message.json`.
-
-### Quorum Operators
-
-Run the same task across several independent models or instances and preserve vote shape for a later merger.
-
-Seed example: `recipes/subagent-quorum.json`.
-
-### Tasking and Conflict Handoffs
-
-Produce bounded task cards or conflict reports for development swarms and integrator workflows.
-
-Seed examples: `recipes/subagent-task-card.json` and `recipes/subagent-conflict-report.json`.
-
-### Checkpoint Emitters
-
-Emit bounded coordinator questions, partial state, or branch decisions as coordinator-bound actor messages. Checkpoint components should not pretend same-context resume exists unless the adapter can prove it.
-
-Seed example: `recipes/subagent-checkpoint.json`.
-
-### Follow-up Continuations
-
-Resume or continue a branch with a bounded reply. If same-context continuation is unavailable, the component must declare a degraded mode such as creating a new branch with the checkpoint artifact included.
-
-Seed example: `recipes/subagent-followup.json`.
-
-### Judges
-
-Evaluate report quality, evidence preservation, severity calibration, consensus purity, and internal consistency. Judges should not silently become another domain reviewer.
-
-Seed example: `recipes/subagent-judge.json`.
-
-## Composition Shape
-
-A coordinator recipe can stay small by composing components:
-
-```text
-launch/review fanout → verify claims → merge → judge → final synthesis
-```
-
-Seed example: `recipes/subagent-review-coordinator.json` composes reviewer fanout, verification, merge, judge, and normalization.
-
-Higher-level examples:
-
-- `recipes/pipeline-review-readiness.json`: Release/readiness gate over selected lenses.
-- `recipes/pipeline-quorum-review.json`: Same prompt across a model pool, then merge, judge, and normalize vote shape.
-- `recipes/pipeline-architect-coordinator.json`: Architecture direction synthesis with lens fanout, critique, verification, merge, and next-slice output.
-- `recipes/pipeline-research-synthesis.json`: Plan, evidence map, contradiction map, verification, merge, and normalized research synthesis.
-- `recipes/pipeline-checkpoint-continuation.json`: Checkpoint artifact, follow-up continuation, and normalized handoff with explicit degraded-mode handling.
-- `recipes/pipeline-development-tasking.json`: Plan, task card, critique, and normalized integrator handoff for bounded implementation work.
-- `recipes/pipeline-artifact-report.json`: Normalized report → durable artifact-shaped output → actor-message-shaped record.
-
-For high-risk work, split breadth and confidence:
-
-```text
-lens swarm → quorum per lens → merger → post-merge judge
-```
-
-For implementation work, combine coordination with local ownership policy:
-
-```text
-task cards → scoped branch agents → conflict reports → integrator merge → review
-```
-
-## Design Rules
-
-- Prefer public args/defaults over baked-in local policy.
-- Use `failure: "branch"` for independent fanout branches unless one failure invalidates the whole run.
-- Keep model pools and provider aliases configurable.
-- Use artifacts or actor messages for intermediate outputs that must survive compaction.
-- Do not hide broad coordinator behavior inside a component named like a leaf.
-- Do not introduce scheduler, goto, or workflow-only syntax; compose saved recipes and command templates.
+- [Recipe library](./recipe-library.md)
+- [Template Recipes](./template-recipes.md)
+- [Command templates](./command-templates.md)

package/docs/recipe-library.md

@@ -1,212 +1,87 @@
-# Recipe Library
+# Packaged Recipe Library
 
-The root `recipes/` directory is the packaged standard actor recipe library for pi-actors. These recipes are reusable building blocks, not automatically installed operator policy. Copy or reference them from local tool registrations when the operator wants a durable callable tool.
+Packaged Recipes provide maintained execution graphs and service definitions. User Recipes with the same name shadow packaged definitions; invalid shadowing fails closed.
 
-Helper scripts that belong to library recipes live in root `scripts/`. The music player standard uses the executable Node.js wrapper only: `scripts/music-player.mjs`.
+## Recommended Entry Points
 
-## Layout
+### Repository and delivery
 
-- `recipes/subagent-*.json`: Atomic subagent components such as prompt launchers, reviewers, critics, planners, verifiers, mergers, checkpoints, follow-ups, judges, and normalizers.
-- `recipes/pipeline-*.json`: Higher-level composed recipes built from component imports.
-- `recipes/music-player.json`: Async local music player recipe backed by `scripts/music-player.mjs`.
-- `recipes/utility-*.json`: Small operator utility recipes that are not subagent coordinators.
+- `pipeline-repo-health.json` — repository inspection and bounded health artifact.
+- `pipeline-docs-maintenance.json` — documentation analysis and artifact preparation.
+- `pipeline-release-readiness.json` — release checks and readiness artifact.
+- `pipeline-release-summary.json` — release-summary artifact.
+- `pipeline-development-tasking.json` — task-card and implementation planning pipeline.
 
-## Install Locally
+### Review and synthesis
 
-Select only the operator-facing recipe or wrapper you intend to own locally. For example:
+- `pipeline-quorum-review.json` — parallel reviewers with quorum-oriented synthesis.
+- `pipeline-review-readiness.json` — review plus readiness stages.
+- `pipeline-research-synthesis.json` — evidence-oriented research synthesis.
+- `lens-swarm.json` — configurable repeated review lenses.
+- `subagent-review-coordinator.json` — lower-level review/verify/merge/judge composition.
 
-```bash
-mkdir -p ~/.pi/agent/recipes
-cp <repo>/recipes/pipeline-review-readiness.json ~/.pi/agent/recipes/
-```
-
-Do not bulk-copy `recipes/*.json`. The packaged library also contains internal composition stages, including `draft-review.json` and `tool-review.json`; the automatic-review runtime launches those selectors with fenced inputs and they must not become user-installed callable tools.
-
-A registered tool can instead point at one selected recipe path when a durable operator-facing name is useful. Prefer a thin wrapper for public defaults or policy rather than copying the wrapper's internal imports.
-
-## Async Subagent Components
-
-Core subagent recipes:
-
-- `recipes/subagent-prompt.json`: Start one prompt-driven subagent.
-- `recipes/subagent-tools.json`: Start a subagent with an explicit tool allowlist.
-- `recipes/subagents-prompts.json`: Run prompt fanout with one imported subagent component.
-- `recipes/subagent-preflight.json`: Tiny model/thinking/tool-policy smoke check before expensive fanout; failures surface `ACTOR_PREFLIGHT_FAILED` with stage, selected policy, provider error class, prompt file, and override args.
-- Packaged reviewer, verifier, merger, judge, and normalizer stages use `accept_output: review_evidence` and require `ACTOR_REVIEW_RESULT` as the exact first non-whitespace output line. Marker prefixes, format acknowledgements, and input requests therefore remain rejected branch diagnostics rather than usable quorum evidence.
-- `recipes/subagent-review.json`: Evidence-grounded review lens.
-- `recipes/draft-review.json`: Internal no-tools selector for one immutable automatic draft batch. It receives an attached value-free structural projection with batch-local opaque occurrence/content-group identities, counts, risk labels, and usage—not canonical names, draft basenames, raw hashes, recipe bodies, template text, defaults, authored prose, or filesystem paths—then emits one terminal `DRAFT_REVIEW_RESULT` with quota-free promote/discard decisions. The executor derives any promotion from the separate trusted captured source.
-- `recipes/tool-review.json`: Internal no-tools selector for one immutable 36-tool portfolio. It receives the same identity-opaque value-free structural projection and may recommend quota-free keep, unchanged-source rename (`evolve`), unchanged-source demote, or identical-source merge decisions. `replace`, `split`, and returned recipe content fail mechanically; deterministic executors alone read trusted captured recipes and own validated safe-boundary activation.
-- `recipes/subagent-critic.json`: Assumption and failure-mode critique.
-- `recipes/subagent-plan.json`: Bounded plan slices and validation gates.
-- `recipes/subagent-evidence-map.json`: Evidence and confidence map.
-- `recipes/subagent-contradiction-map.json`: Contradiction and missing-evidence map.
-- `recipes/subagent-verify.json`: Claim verification.
-- `recipes/subagent-merge.json`: Consensus/risk-first synthesis.
-- `recipes/subagent-normalize.json`: Stable output shaping.
-- `recipes/subagent-artifact.json`: Durable artifact-shaped output for a target path. It prepares content and write guidance; it does not write files unless the caller deliberately grants write tools or uses a deterministic writer.
-- `recipes/subagent-message.json`: Prompted actor-message-envelope-shaped coordinator message record with envelope-aligned args.
-- `recipes/subagent-quorum.json`: Same prompt across a model pool.
-- `recipes/subagent-task-card.json`: Bounded implementation task card.
-- `recipes/subagent-conflict-report.json`: Integrator-oriented conflict report.
-- `recipes/subagent-checkpoint.json`: Coordinator checkpoint artifact.
-- `recipes/subagent-followup.json`: Same-context or degraded continuation.
-- `recipes/subagent-judge.json`: Post-merge/report quality judge.
-
-Most atoms expose policy knobs such as `model`, `thinking`, `tools`, `output_format`, `evidence_policy`, `risk_policy`, source policy, continuity policy, handoff format, or model pools. Packaged recipes intentionally do not ship concrete model-version defaults: review-oriented subagent and lens-swarm recipes default model/thinking args through `{current_model}` and `{current_thinking}` so they inherit the selected Pi session policy, and callers can still pass explicit values when a run should diverge. Recipe inspection marks these inherited policy defaults as `current_policy`, and run status/progress records whether launch policy was inherited, explicit, mixed, or unresolved. Generic prompt launchers, including `subagent-tools` and `subagents-prompts`, expose the same core model/thinking/tool/output knobs so callers do not need separate recipe families for policy tuning. Interactive async atoms also declare mailbox metadata for their basic control, completion, and domain-result message surface. Higher-level recipes pass these knobs through instead of hard-coding local policy.
-
-For one-off packaged subagent reviews, launch the recipe directly with `spawn file="subagent-review" values={...}` or `spawn file="pipeline-review-readiness" values={...}`. Do not copy the underlying `pi -p` command or wrap the recipe unless you are creating a durable operator tool with a narrower interface.
-
-For build-oriented swarms, prefer a consensus-first shape over parallel writers: proposer roles coordinate in a room with message/inspect tools, a named implementer owns the first artifact write, a QA reviewer inspects the result, and a finalizer applies review-grounded fixes before `run.done`. This pattern keeps creative/lens diversity while preserving one coherent artifact and gives recipes concrete artifact assertions instead of treating room discussion as success.
-
-Register one atom:
-
-```text
-register_tool name=subagent_prompt \
-  description="Start an async no-tools pi subagent" \
-  template="subagent-prompt.json"
-```
-
-Start it:
+Callers should own model, thinking, concurrency, quorum, and mission policy. Review pipelines preflight provider/model availability before expensive fanout.
 
-```text
-subagent_prompt prompt="Review docs/async-runs.md for unclear wording." run_id=docs_review
-inspect target=run:docs_review view=status
-inspect target=run:docs_review view=tail
-```
-
-## Composed Pipelines
-
-Pipeline recipes demonstrate second-order composition:
-
-- `recipes/coordinator-locker.json`: Long-lived coordinator cell with queue, acquire/renew/release lease locks, journal, actor messages for worker coordination, and platform-adapted control metadata.
-- `recipes/subagent-review-coordinator.json`: Model/tool preflight with compact provider diagnostics → quorum-aware lens reviewers → verifier → merger → judge → normalizer. Review pipelines expose `subagent_ttl_ms`, `reviewer_concurrency`, `min_successful_reviewers`, and `merge_policy` knobs; reviewer joins preserve partial evidence and mark `complete`, `degraded`, or `insufficient_data`. `npm run conformance` includes a fake-`pi` review-readiness dogfood fixture for this packaged path.
-- `recipes/pipeline-release-readiness.json`: Task-first release cell: changelog section → package summary → packaged skill summary → validation → release review → artifact report.
-- `recipes/pipeline-release-summary.json`: Evidence-only release summary cell: changelog section → package summary → packaged skill summary → validation → release summary / risks / PR body draft artifact. It does not commit, open a PR, merge, tag, publish, or perform external release side effects.
-- `recipes/pipeline-repo-health.json`: Task-first repository-health cell: git status/log → docs index → validation → normalized artifact report.
-- `recipes/pipeline-async-run-ops.json`: Task-first async-run operations cell: run summary → actor-message tail → normalized operations report → artifact report.
-- `recipes/pipeline-review-readiness.json`: Release/readiness gate over selected lenses.
-- `recipes/pipeline-quorum-review.json`: Quorum vote shape → merge → judge → normalize.
-- `recipes/pipeline-architect-coordinator.json`: Architecture lens fanout → critique → verification → synthesis → next slice.
-- `recipes/pipeline-research-synthesis.json`: Plan → evidence map → contradiction map → verification → synthesis.
-- `recipes/pipeline-checkpoint-continuation.json`: Checkpoint → follow-up → normalized handoff.
-- `recipes/pipeline-development-tasking.json`: Plan → task card → critique → integrator handoff.
-- `recipes/pipeline-docs-maintenance.json`: Docs index → documentation review → maintenance plan → artifact report.
-- `recipes/pipeline-media-library.json`: Playlist build → media-library artifact report.
-- `recipes/pipeline-room-swarm.json`: Room participants join `room:<run>`, coordinate over repeated room-visible rounds, leave cleanly, and synthesize the room transcript into a caller-provided artifact path. Supported coordinator modes are `consensus`, `pipeline`, `fanout`, and `pool`; unknown modes fail closed instead of silently running consensus. Keep model/thinking/mission policy caller-owned. Custom roles can be supplied with `roles_path` as a JSON array of `{ "name", "persona" }` objects; `name` stays ASCII-safe for `branch:<run>/<name>` addresses and debugger output remains plain and name-driven. The packaged swarm uses contacts for peer awareness but does not rely on direct branch delivery unless a caller-specific worker protocol consumes branch envelopes. Set `subagent_ttl_ms` to a positive millisecond budget when participant `pi -p` processes must be killed instead of awaited indefinitely. Set `locker=true` to compose a local `coordinator-locker` cell under `{state_dir}/locker` for artifact ownership, resource lease locks, and a decision journal without merging locker policy into the room-participant script.
-- `recipes/pipeline-artifact-report.json`: Normalize → artifact-shaped output → actor-message-shaped record. This pipeline prepares a candidate artifact and emits `artifact.prepared`/`artifact.blocked`; the `artifact_path` is a target path, not a guarantee that the file was written.
-- `recipes/pipeline-artifact-write.json`: Normalize → artifact-shaped output → deterministic artifact write → actor-message-shaped record. Use only when the caller explicitly wants filesystem writes; `write_mode` is `create`, `overwrite`, or `append`.
-- `recipes/pipeline-artifact-bundle.json`: Optional validation → deterministic artifact write → machine-readable manifest generation → deterministic manifest write → actor-message-shaped record. Use when the caller explicitly wants a filesystem handoff bundle with both artifact and manifest paths.
-
-These are examples of library composition, not a workflow DSL. Pipeline recipes declare mailbox metadata for their high-level completion, artifact, and control message surface. The recipe layer owns imports and saved defaults; command templates own execution shape; async runs own lifecycle.
-
-## Utility Recipes
-
-Utility recipes cover local operator workflows that do not need subagents:
-
-- `recipes/utility-markdown-index.json`: List Markdown files in a directory as input for README/docs index maintenance.
-- `recipes/utility-jsonl-tail.json`: Tail a JSONL message/log file with a configurable line count.
-- `recipes/utility-validation-wrapper.json`: Run a caller-supplied validation command in a scoped directory with a bounded timeout. This intentionally crosses a trusted shell boundary; discovery surfaces it as a diagnostic, and callers should pass explicit validation commands only.
-- `recipes/utility-git-status.json`: Read concise branch/worktree state for a repo.
-- `recipes/utility-git-log.json`: Read recent decorated commit history for a repo.
-- `recipes/utility-run-state-files.json`: List run-state files such as `run.json` under an async run state root.
-- `recipes/utility-coordinator-lock-snapshot.json`: Summarize a coordinator-locker actor state directory with queue depth, locks, and recent journal entries.
-- `recipes/utility-changelog-head.json`: Read the top slice of a changelog for release summary prep.
-- `recipes/utility-playlist-scan.json`: List local media files as playlist-building input.
-- `recipes/utility-run-summary.json`: Use `scripts/recipe-utils.mjs` to summarize async run state files as JSON.
-- `recipes/utility-run-ops-snapshot.json`: Combine async run summaries, recent actor messages for a selected `run_id`, and stale/terminal recommendations into one structured operations snapshot.
-- `recipes/utility-playlist-build.json`: Use `scripts/recipe-utils.mjs` to build a filtered playlist listing as newline paths, M3U, or inline `|`-separated source.
-- `recipes/utility-changelog-section.json`: Use `scripts/recipe-utils.mjs` to extract one changelog release section.
-- `recipes/utility-artifact-manifest.json`: Use `scripts/recipe-utils.mjs` to emit a machine-readable JSON manifest for an artifact path.
-- `recipes/utility-artifact-write.json`: Deterministically write prepared artifact content from stdin to `artifact_path` with explicit `create`, `overwrite`, or `append` mode.
-- `recipes/utility-actor-message.json`: Deterministically wrap stdin as a validated addressed actor-message envelope with the same public names as the envelope: `to`, `from`, `type`, `summary`, `body`, optional `correlation_id`/`reply_to`, and `metadata`.
-- `recipes/utility-package-summary.json`: Use `scripts/recipe-utils.mjs` to emit bounded package metadata such as name, version, files, scripts, and dependency counts.
-- `recipes/utility-skill-summary.json`: Use `scripts/recipe-utils.mjs` to summarize packaged skill frontmatter, body shape, formatter-safe scalar lines, and package-version alignment.
-- `recipes/utility-validate-recipe.json`: Use `scripts/validate-recipe.mjs` to validate one template recipe file, or all packaged recipes in a directory with `all: true`.
-
-Packaged QA is available through the `recipes:qa` npm script. It reports description warnings and fails exact diagnostics for async mailbox contracts, termination vocabulary, artifact paths, platform scope, helper script paths, and missing helper scripts.
-
-These recipes are intentionally small. Register them only for trusted local commands and prefer narrow scopes. Discovery diagnostics flag obvious trust-boundary shapes such as shell/eval/destructive commands; those warnings are operator review aids, not a sandbox. The helper-backed utilities share `scripts/recipe-utils.mjs` so repeated parsing/listing logic stays out of recipe strings.
-
-## Actor OS Smoke Matrix
-
-The repeatable smoke surface is the normal validation suite:
-
-```text
-npm test
-```
+### Artifacts
 
-The scenario coverage is intentionally local-first and bounded: shared room coordination and roster snapshots (`rooms` / `tools` tests), direct branch delivery and claim/handle transitions (`tools` and coordinator tests), inspector navigation (`inspector` tests), recipe context injection (`recipes-context` / async-runs tests), compact terminal follow-up delivery (`observability` tests), and opt-in retirement candidate/execution smoke (`observability` / async-runs tests). These scenarios exercise public `spawn` / `message` / `inspect` behavior or the packaged script surfaces rather than relying on manual swarm demos.
+- `pipeline-artifact-report.json` — prepare one artifact body.
+- `pipeline-artifact-write.json` — prepare and deterministically write an artifact.
+- `pipeline-artifact-bundle.json` — optional validation, artifact write, manifest generation, and manifest write.
+- `utility-artifact-write.json` — deterministic create/overwrite/append helper.
+- `utility-artifact-manifest.json` — artifact manifest generation.
 
-## Music Player
+Artifact pipelines terminate in files/manifests and result evidence; they do not fabricate communication events.
 
-Files:
+### Controlled services
 
-- `recipes/music-player.json`
-- `scripts/music-player.mjs`
+- `music-player.json` — playback service with declared playback actions, `controls.jsonl`, generation-fenced endpoint readiness, state artifact, and playback Trace. Player selection is `player:enum(auto,mpv,afplay,ffplay,cvlc,play,wmp)=auto`.
+- `resource-locker.json` — optional queue/lease-lock service with explicit owner/resource input and lock Trace.
 
-Purpose: start a local or URL audio source as an async run so the agent can continue working while playback runs in the background. The running script exposes a run-local mailbox, so addressed `message` calls can control playback without a second recipe.
+These are the packaged Recipes that declare actor-local Control. Ordinary one-shot Recipes omit it.
 
-Requirements: Node.js and one playback backend. Supported backends are `mpv`, macOS `afplay`, `ffplay`, `cvlc`, SoX `play`, or `wmp` on native Windows through the legacy Windows Media Player COM control exposed by `powershell.exe`. The `wmp` backend validates `wmplayer.exe` under `Program Files/Windows Media Player` or `Program Files (x86)/Windows Media Player`; it does not target the newer UWP/Store Media Player. Playback format support depends on the selected player; the actor control path itself uses the portable mailbox/wake runtime layer.
+## Component Recipes
 
-The required `source` arg accepts:
+Subagent components provide reusable command-template cells for normalization, planning, evidence mapping, contradiction analysis, criticism, review, verification, merging, judging, quorum work, task cards, checkpoint prompts, and artifact generation.
 
-- A single local file or URL.
-- A directory containing audio files; the wrapper scans `.aac`, `.aif`, `.aiff`, `.flac`, `.m4a`, `.mp3`, `.ogg`, and `.wav` files.
-- An `.m3u`, `.m3u8`, or `.txt` playlist file.
-- A `|`-separated inline list of local files or URLs.
+Imports compose these definitions inside one parent Run. They are not independently addressable peers. Parent template flags control sequencing, parallelism, retries, failure scope, recovery, and repeated execution.
 
-Install locally:
-
-```bash
-mkdir -p ~/.pi/agent/recipes
-cp <repo>/recipes/music-player.json ~/.pi/agent/recipes/music-player.json
-```
+## Utility Recipes
 
-Register playback:
+Utilities wrap deterministic local capabilities such as:
 
-```text
-register_tool name=music_player \
-  description="Start async music player playback through the Node.js wrapper" \
-  template="music-player.json" \
-  args="source:string,loop:bool=true,volume:int=70,player:enum(auto,mpv,afplay,ffplay,cvlc,play,wmp)=auto"
-```
+- package and skill summaries;
+- artifact writes/manifests;
+- validation commands;
+- Run operations snapshots;
+- Recipe validation.
 
-Start playback:
+Use utilities as imported cells or registered tools where their contract fits.
 
-```text
-music_player source="~/Music" volume=55 run_id=music
-```
+## Selection Guidance
 
-Control it through addressed actor messages. This is the canonical reactive pattern for long-lived recipes: the run emits actor messages upward, and the coordinator sends explicit commands downward instead of polling on a timer.
+1. Prefer the highest-level maintained pipeline matching the task.
+2. Use component Recipes when building a new stable pipeline.
+3. Use inline templates for genuinely one-off trusted work.
+4. Declare artifacts for outputs that callers must retain.
+5. Declare Control only when a service process actually consumes it.
+6. Keep large semantic evidence in artifacts or execution captures, not Trace summaries.
 
-```text
-message to=run:music type=player.pause body=pause
-message to=run:music type=player.play body=play
-message to=run:music type=player.next body=next
-message to=run:music type=player.previous body=previous
-message to=run:music type=player.stop body=stop
-```
+## Installation Safety
 
-Use `inspect target=run:music view=status` only when an actor message or operator decision requires inspection.
+Do not bulk-copy `recipes/*.json` into the user Recipe root. Internal `draft-review.json` and `tool-review.json` support fenced automatic review and must not become user-installed callable tools. Register or wrap only the specific public capability you intend to use.
 
-The wrapper also accepts control commands directly when a caller already has the run state dir:
+## Validation
 
-```text
-scripts/music-player.mjs next ~/.pi/agent/tmp/pi-actors/runs/music
+```bash
+npm run recipes:qa
 ```
 
-Message body is queued in the recipe's run-local mailbox and reconciled by the player loop. The loop treats `wake.jsonl` and `fs.watch` as advisory signals, then verifies the durable inbox signature before taking the inbox lock so unchanged mailboxes are not reread on every tick. Backend players stay inside the async run process group so `control.kill` terminates active playback with the run instead of leaving detached player children alive; player-local pause/resume/next/stop controls still signal the current backend pid or process group when available. The script writes `status.txt`, `player.json`, and track-change actor messages in the same state dir. Track-change messages stay diagnostic by default; interactive recipes should define a small command vocabulary for addressed messages, emit semantic actor messages for decision points, and let the coordinator react to messages rather than sleep-polling state.
-
-Cross-platform smoke checklist:
-
-- Linux: install one backend such as `mpv` or `ffplay`; start `music_player source="~/Music" run_id=music`, send `pause`, `play`, `next`, and `stop`, then inspect `run:music` status/mailbox.
-- macOS: verify `player=auto` selects `afplay` when no preferred CLI backend is installed, then run the same addressed message controls.
-- Native Windows: verify `player=wmp` detects `wmplayer.exe`, starts playback through Windows Media Player COM, handles `pause`/`play`/`next`/`previous`/`stop`, and leaves handled mailbox records visible through `inspect target=run:music view=mailbox`.
-- All hosts: confirm missed wake resilience by checking that queued mailbox commands are eventually claimed without relying on a transport-specific endpoint.
+Recipe QA validates syntax, imports, Control declarations, artifact paths, helper references, and platform documentation. Removed mailbox declarations fail with the migration diagnostic rather than receiving automatic conversion.
 
-## Safety Notes
+## Related
 
-- Only play trusted local files or URLs.
-- Volume is clamped to `0..100` by the wrapper.
-- Prefer a stable `run_id` such as `music` when the operator expects to control the run by name.
-- Use `message type=control.kill` for runtime termination; `control.stop` is a player-domain pause/stop command, not a generic run-kill alias.
+- [Template Recipes](./template-recipes.md)
+- [Command templates](./command-templates.md)
+- [Runs](./async-runs.md)
+- [Component Recipes](./component-recipes.md)
+- [Task-first design](./task-first-recipes.md)

package/docs/task-first-recipes.md

@@ -13,7 +13,7 @@ For each high-level recipe candidate:
 3. Sketch the recipe pipeline at the highest useful abstraction.
 4. Identify missing component cells.
 5. Decide which cells are subagent components, local utilities, or helper-backed transforms.
-6. Keep domain policy knobs public: models, tools, paths, evidence/risk policy, output shape, mailbox contract, and validation gates.
+6. Keep domain policy knobs public: models, tools, paths, evidence/risk policy, output shape, actual Control actions, and validation gates.
 7. Add only the next smallest recipe/helper slice that validates the design.
 
 ## High-Level Recipe Cells
@@ -88,27 +88,26 @@ Purpose: inspect, summarize, and decide actions for local async runs.
 Pipeline:
 
 ```text
-run-state summary → actor-message tail → stale/active classification → recommended action → optional stop/control message
+Run summary → Trace tail → stale/active classification → recommended Inspect or Control action
 ```
 
 Likely needed cells:
 
 - Run summary helper
-- JSONL actor-message tailer
+- bounded Trace tail reader
 - Stale-run classifier
-- Control-message recommender
+- Inspect/Control action recommender
 - Run report artifact
 
 Existing seeds:
 
 - `utility-run-summary`
 - `utility-jsonl-tail`
-- `subagent-message`
 - `pipeline-artifact-report`
 
 Implemented seed:
 
-- `pipeline-async-run-ops`: structured run operations snapshot → normalized operations report → artifact report. The snapshot combines run summary, actor-message tail, and recommended inspect/control messages before the LLM normalization step.
+- `pipeline-async-run-ops`: structured run operations snapshot → normalized operations report → artifact report. The snapshot combines Run summary, Trace tail, and recommended Inspect/Control actions before the LLM normalization step.
 
 ### Research Brief Cell
 
@@ -147,19 +146,18 @@ Pipeline:
 mission → lens proposers in room → consensus transcript → named implementer writes artifact → QA reviewer checks artifact + transcript → finalizer applies fixes → artifact assertions
 ```
 
-Use this for creative demos, single-file artifacts, specs, docs, prompt packs, and product/UX deliverables where broad input matters but one owner should shape the final file. Proposers should have message/inspect tools only. The implementer should be the first role with write tools. QA should inspect/read but not mutate. The finalizer may write only after reading QA evidence.
+Use this for creative demos, single-file artifacts, specs, docs, prompt packs, and product/UX deliverables where broad input matters but one owner should shape the final file. Proposers remain read-only. The implementer becomes the first stage with write tools. QA inspects without mutation, and the finalizer writes only after reading immutable QA evidence.
 
 Required gates:
 
 - Artifact path, report path, and minimum acceptance checks are explicit inputs.
 - The workflow fails if the requested artifact is missing, too small, or not self-contained enough for the task.
-- `run.done` is emitted only after QA/finalizer passes, not merely after room discussion.
+- The Run completes only after QA/finalizer acceptance, not merely after proposal generation.
 
 Existing seeds:
 
-- `pipeline-room-swarm` for room-visible discussion and rosters.
-- `subagent-message` for explicit room handoffs.
-- `subagent-review` / `subagent-verify` for QA roles.
+- `subagent-review` / `subagent-verify` for QA stages.
+- `pipeline-quorum-review` for independent proposals and synthesis.
 - `pipeline-artifact-write` or a small helper script for deterministic artifact assertion.
 
 Next recipe direction:
@@ -257,7 +255,7 @@ Good next candidates for the standard library after the first task-first wave:
 
 1. Package/release metadata enrichment: implemented in `pipeline-release-readiness` by adding `utility-package-summary` and `utility-skill-summary` between changelog extraction and validation, making release-readiness reports more evidence-rich without adding publish automation.
 2. Evidence-only release summary: implemented as `pipeline-release-summary`, which composes changelog/package/skill/validation evidence into a release summary, risk checklist, and PR body draft artifact while leaving commit, PR, merge, tag, and publish actions to explicit release gates.
-3. Artifact packaging and manifesting: implemented as `pipeline-artifact-bundle`, which composes optional validation, `pipeline-artifact-write`, `utility-artifact-manifest`, deterministic manifest writing, and an actor-message handoff when the caller explicitly requests filesystem writes.
+3. Artifact packaging and manifesting: implemented as `pipeline-artifact-bundle`, which composes optional validation, `pipeline-artifact-write`, `utility-artifact-manifest`, deterministic manifest writing, and final artifact evidence when the caller explicitly requests filesystem writes.
 4. Async run cleanup planning: extend async-run operations with stale-run classification and recommended `message`, `cancel`, or `kill` controls, keeping actual control execution operator-gated.
 
 Each candidate should land with the minimum missing cells rather than a broad one-shot framework. Already implemented task-first seeds include `pipeline-release-readiness`, `pipeline-release-summary`, `pipeline-repo-health`, `pipeline-async-run-ops`, `pipeline-docs-maintenance`, `pipeline-media-library`, and `pipeline-artifact-bundle`.