@llblab/pi-actors 0.42.3 → 0.43.1

package/docs/actor-messages.md

@@ -1,225 +0,0 @@
-# Actor Messages
-
-Protocol target for organic communication across pi-actors.
-
-## Contract
-
-Compress communication to three durable verbs:
-
-- `spawn`: create an addressable actor from a recipe, template, or tool.
-- `message`: send one typed message to one address.
-- `inspect`: intentionally observe state, logs, actor messages, or artifacts.
-
-Everything else is an adapter until proven otherwise.
-
-## Nouns
-
-- **Actor**: any addressable execution or coordination endpoint.
-- **Address**: stable route string for an actor or sub-actor.
-- **Message**: typed envelope flowing between addresses.
-- **Artifact**: durable result path declared by recipe or produced by actor.
-- **Inspection**: explicit diagnostic/read operation, not a coordination loop.
-
-## Addresses
-
-Initial address forms:
-
-```text
-run:<id>
-branch:<run>/<branch>
-coordinator
-session:<id>
-tool:<name>
-```
-
-Cross-branch communication adds one organic endpoint kind:
-
-```text
-room:<run>
-```
-
-A room is the task's single shared discussion channel: an addressable mailbox with an append-only message log and a compact member roster stored under the owning run state. It is not a broker or coordinator: it accepts normal actor-message envelopes, records shared timeline entries, tracks join/leave presence, and lets actors discover peers for direct messages. `room:<run>` is the public address; named subrooms are intentionally not exposed in 0.17.
-
-An alternate implementation shape is a dedicated non-LLM communication actor: a small script-backed service recipe, possibly singleton-scoped, that owns room timelines, rosters, subscriptions, and fanout. This is attractive when communication needs outgrow simple file-backed room state, but it should remain an implementation adapter behind the same `room:<run>` address and message envelope. The public model should not fork into a separate chat API.
-
-That actor-backed shape can also reduce direct file storage. Instead of every protocol feature owning JSON files as primary state, a helper actor can keep live room/roster structures in memory or another local structure and write files only as snapshots, audit logs, artifacts, or recovery checkpoints. The decision boundary is practical: keep files when durability and inspectability are the main value; prefer actor-owned structures when live coordination, subscriptions, fanout, unread state, or mutation consistency becomes the main value.
-
-Current backend decision: keep the file-backed adapter for now. The covered workload is append-heavy room coordination plus direct branch inbox queueing/claiming, where durable local files are still the useful source of truth for recovery and `inspect`. Live notification is a separate advisory wake layer: actors may subscribe to `wake.jsonl` changes through a cross-platform file notifier and still reconcile canonical mailbox files if a wake is missed. A communication helper should be introduced only when a real workflow needs long-lived subscriptions, live fanout policy, or shared mutable room state beyond the current lock/debounce/compaction safeguards.
-
-Package-specific endpoints may still exist, but the envelope stays the same.
-
-## Message Envelope
-
-One shape covers upward, downward, lateral, parent-to-branch, and branch-to-parent traffic:
-
-```json
-{
-  "to": "run:review",
-  "from": "coordinator",
-  "type": "control.approve",
-  "summary": "Approve checkpoint",
-  "body": "approve",
-  "reply_to": "msg_123",
-  "correlation_id": "task_456",
-  "metadata": {}
-}
-```
-
-Field rules:
-
-- `to`: required address.
-- `from`: optional address; runtime fills when known.
-- `type`: required semantic message type. Prefer compact dotted names such as `control.stop`, `task.claim`, or `player.next`, where the prefix is the interaction channel/domain and the suffix is the action. Many script-backed actors should be able to dispatch from `type` alone without requiring a structured body.
-- `summary`: short human-facing line for notifications/follow-ups.
-- `body`: optional string or JSON payload. Use it when extra context is needed: scripts may ignore it for action-only messages, while LLM-backed agents can accept free-form natural-language prompts without a rigid schema.
-- Routing/delivery is inferred from `to`, actor ownership, and coordinator runtime policy; recipes should not expose delivery knobs. When a coordinator session is known, addressed run/branch/control messages fail closed before controlling or emitting from runs owned by another session.
-- `reply_to`: optional message id for conversational checkpoints.
-- `correlation_id`: optional task/run/workflow id.
-- `metadata`: optional structured routing or domain hints.
-
-## Symmetry
-
-The same `message` primitive must represent:
-
-```text
-coordinator -> run
-run -> coordinator
-run -> run
-parent -> branch
-branch -> parent
-branch -> room
-room -> branch notification
-coordinator -> tool
-```
-
-Transports differ, but the public contract does not:
-
-- `to: run:<id>` routes through the run-local control channel selected by that recipe or runtime adapter.
-- `to: coordinator` routes to the runtime attention path when `from` names a run actor. `to: session:<id>` uses the same actor-message path only when the sender run is owned by that session, making explicit session-directed checkpoints possible without exposing runtime delivery knobs. Generic async-runner `command.done` messages and explicit coordinator/session-bound messages include the actor envelope fields alongside runtime metadata.
-- `to: branch:<run>/<branch>` currently routes through the parent run mailbox with the full envelope preserved so the run or recipe-specific worker protocol can dispatch branch-local control. It also persists a queued branch-local copy under `branches/<branch>/inbox.jsonl`, inspectable with `inspect branch:<run>/<branch> view=mailbox`; compact inspection includes the inbox message `id`, status, route, type, and timestamps so worker protocols can correlate claims/retries. Branch-local inbox append and status rewrites are guarded by a small lock so direct delivery and coordinator claims do not overwrite each other during bursts. Status transitions preserve active queued/claimed records and compact older handled/failed terminal records with bounded retention, so persistent runners do not accumulate unbounded completed inbox history. Coordinator claim handling also assigns an ID to older/manual queued records that do not have one so they can still transition to `handled` or `failed` instead of repeating forever. It is not a broadcast room and it does not make an arbitrary prompt process consume the message automatically. Target direction: direct branch messages should become initiating inbox work for long-lived branch runners, delivered into the recipient's next prompt/context as soon as the runner can accept work.
-- `to: room:<run>` appends the full envelope to the room timeline, updates room state for room-control types such as `actor.join` and `actor.leave`, and can route selected-recipient multicast when `metadata.recipients` contains same-run `branch:<run>/<branch>` addresses.
-- `to: tool:<name>` invokes an executable pi tool by name. Object bodies become tool parameters; primitive bodies are passed as `{ "input": body }`.
-
-Transport is not public API unless a recipe explicitly documents a custom endpoint.
-
-## Rooms and Rosters
-
-The task room is the discovery and shared-context layer for actors whose spawn-tree positions do not give them each other's addresses. The spawn tree remains the lifecycle/provenance structure; the task room describes the group communication graph. Direct messages and room messages can share the same semantic `type` such as `chat.message`; the route (`to: branch:*` versus `to: room:*`) determines whether delivery is private or group-wide.
-
-Use direct branch messages only when the receiving branch is backed by a worker or recipe that reads the parent run mailbox or branch inbox and dispatches branch-targeted envelopes. Room roster contacts are discovery hints, not a guarantee that an independent prompt process is subscribed to its branch address. The current branch inbox records queued mailbox work; runner-side claiming/handling turns direct messages into prompt work for the recipient branch, while room messages remain shared transcript entries. A direct message may ask the recipient to inspect room history when broader shared context is needed. For ad hoc or transcript-driven swarms without such a runner, prefer room-visible replies and mentions so every participant can inspect the shared timeline.
-
-Direct branch delivery is prompt steering for worker-backed branches, not a coordinator follow-up. Packaged coordinator flows claim queued branch inbox records immediately before launching the branch's next prompt, append a bounded "direct messages for you" section to that prompt, and then mark the claimed records `handled` or `failed` based on the prompt result. Generic one-shot `pi -p` children do not receive this injection automatically; a recipe must own the runner loop or use the packaged coordinator path for direct messages to become next-prompt work.
-
-Selected-recipient multicast stays route-based: send one `to: room:<run>` envelope with `metadata.recipients` set to same-run branch addresses. The room timeline keeps the original room-visible envelope, and the runtime also forwards branch-targeted copies to each listed recipient. This is not a subroom; it is a shared transcript plus explicit direct delivery for actors whose worker protocol consumes branch envelopes.
-
-A minimal join message:
-
-```json
-{
-  "to": "room:review",
-  "from": "branch:review/security",
-  "type": "actor.join",
-  "summary": "Security reviewer joined",
-  "body": {
-    "role": "reviewer",
-    "caps": ["security-review", "risk-analysis"],
-    "claim": "Review auth boundary risks"
-  }
-}
-```
-
-A leave message removes that actor from the roster while preserving the timeline entry:
-
-```json
-{
-  "to": "room:review",
-  "from": "branch:review/security",
-  "type": "actor.leave"
-}
-```
-
-Room messages require `from` so roster presence and provenance stay explicit. The sender must belong to the room's run (`run:<run>` or `branch:<run>/<branch>`), which prevents accidental cross-run roster pollution. Other room posts also refresh sender presence, defaulting the role hint to `actor` when no richer role is known.
-
-Roster entries should keep identity axes separate:
-
-- `address`: Stable route for direct messages.
-- `parent`: Spawn-tree parent for provenance and ownership checks.
-- `role`: Current task function; dynamic and prompt-dependent.
-- `caps`: Capabilities the actor can offer.
-- `claim`: Current work claim or focus.
-- `status` / `last_seen`: Presence and staleness hints.
-
-Compact roster inspection includes these hints when present so agents can discover direct-message targets without verbose JSON.
-
-Actors should receive a compact visible communication snapshot rather than a full global tree: self, parent/root, joined rooms, relevant sibling/member addresses, and role/capability hints. Current run actors get `communication.json` in their state dir, and async templates receive `{communication_file}`, `{actor_address}`, and `{default_room}` values. The snapshot includes `self`, `root`, optional `parent`, the default room, current default-room members, direct-message `contacts` derived from the room roster, and `updated_at`. Branch-local snapshots are refreshed when a branch joins or posts in the default room, so actors can discover peers without reading full timelines. Full timelines and rosters remain intentional inspection surfaces. For TUI and compact operator display, `view=previews` returns bounded message preview records with `timestamp`, `from`, `to`, `type`, optional `summary`, and optional `body_preview`.
-
-## Mailbox Declaration
-
-Recipes can declare their conversational surface:
-
-```json
-{
-  "mailbox": {
-    "accepts": [
-      "control.continue",
-      "control.revise",
-      "control.approve",
-      "control.kill"
-    ],
-    "emits": ["checkpoint.needs_scope", "branch.done", "run.done"]
-  }
-}
-```
-
-`mailbox.accepts` is a contract for coordinator-to-actor messages. `mailbox.emits` is a contract for actor-to-coordinator or actor-to-actor messages. Packaged interactive and message-producing recipes declare mailbox metadata so coordinators can discover semantic message types without reading transport details. Message-producing recipes produce actor-message-envelope-shaped records with `to`, `from`, `type`, `summary`, `body`, optional `correlation_id`/`reply_to`, and optional `metadata` fields. Coordinator follow-ups preserve bounded body previews and metadata so checkpoints do not lose their actionable payload. Deterministic pipelines should prefer `utility-actor-message` for this wrapping so message shape is validated and guaranteed instead of delegated to a prompt; its recipe args intentionally mirror the envelope field names.
-
-## Spawn
-
-`spawn` creates an actor and returns its address:
-
-```json
-{
-  "recipe": "subagents-prompts.json",
-  "as": "run:review",
-  "values": {},
-  "artifacts": { "report": "{state_dir}/report.md" }
-}
-```
-
-`spawn` creates detached `run:<id>` actors from a recipe file/name or inline command template. Public spawn state directories are runtime-owned so every actor remains addressable and retention cannot target a caller-selected directory; spawn metadata may include named `artifacts` for terminal follow-ups and inspection. Room rosters are durable but burst-safe: repeated messages that only update `last_seen` may be coalesced briefly, while semantic roster changes such as role/status/display still write immediately.
-
-## Inspect
-
-`inspect` reads state intentionally:
-
-```json
-{
-  "target": "run:review",
-  "view": "status"
-}
-```
-
-The implementation supports `status`, `tail`, `messages`, `artifacts`, `files`, `mailbox`, and `communication` for `run:<id>` actors, `status`, `messages`, `previews`, `roster`, and `contacts` for `room:<run>` actors, `status`/`runs` for `coordinator`, `session:<id>`, and `session:all` actors with optional status filtering, and `status`/`schema` for registered `tool:<name>` actors. Run mailbox inspection shows recipe-declared mailbox metadata plus recent durable run inbox entries; branch mailbox inspection shows branch-local queued/claimed/handled records. Room `status` returns compact message/roster counts plus `last_message_at`, `last_message_from`, `last_message_type`, and `last_message_summary` when available, without parsing the full timeline into actor envelopes. Use `messages` for actor-envelope inspection. `inspect target=coordinator` requires a current coordinator session; use `session:<id>` or `session:all` when the session is intentionally explicit. Direct `run:<id>` and `room:<run>` inspection respects coordinator-session ownership when the current session is known. Ownership denials use `reason=session_mismatch owner_session=<id> current_session=<id> hint=inspect_session:<id>`; recover by inspecting the hinted `session:<id>` instead of forcing cross-session control. `inspect` is for decision points and diagnosis only; examples must not teach sleep-then-inspect polling.
-
-## Runtime Direction
-
-Runtime operations use the actor/message vocabulary:
-
-```text
-create detached work -> spawn
-run-local control    -> message to run:<id>
-run force-kill       -> message type control.kill
-platform control     -> internal adapter selected from run state
-coordinator signal   -> message to coordinator/session
-tool execution       -> message to tool:<name>
-intentional observe  -> inspect
-```
-
-## Non-goals
-
-- No generic expression language in templates.
-- No public transport-path vocabulary in recipe args.
-- No polling-first examples.
-- No separate upward and downward message schemas.
-- No heavyweight chat/broker subsystem when an addressable room mailbox is enough.
-- No broad facade that hides artifacts, logs, or ownership checks.

package/docs/actors-deep-reference.md

@@ -1,66 +0,0 @@
-# Actors Deep Reference
-
-Use this document after `skills/actors/SKILL.md` when quick-start actor mechanics are not enough.
-
-## Recipe Navigator
-
-Use packaged recipes by name with `spawn file=<name>` for async actors, or register/call them as tools when repeated use deserves a stable shortcut. Start with the curated list below; use [`recipe-library.md`](recipe-library.md) for the full shipped inventory.
-
-### Top Recipes
-
-- [`pipeline-room-swarm`](../recipes/pipeline-room-swarm.json): room-visible swarm coordination with roles, rounds, optional locker, artifact synthesis, and `subagent_ttl_ms` for hard participant budgets.
-- [`pipeline-repo-health`](../recipes/pipeline-repo-health.json): git/doc/validation evidence to normalized repository health report.
-- [`pipeline-release-readiness`](../recipes/pipeline-release-readiness.json): changelog/package/skill/validation evidence to release review and artifact report.
-- [`actor-worker`](../recipes/actor-worker.json): canonical mailbox-backed branch worker reference for claim/handle/status/artifact patterns.
-- [`coordinator-locker`](../recipes/coordinator-locker.json): queue, lease locks, and journaled coordinator messages for multi-actor ownership.
-
-### Common Cells
-
-- Subagents: [`subagent-prompt`](../recipes/subagent-prompt.json), [`subagent-review-coordinator`](../recipes/subagent-review-coordinator.json), [`subagent-quorum`](../recipes/subagent-quorum.json), [`lens-swarm`](../recipes/lens-swarm.json).
-- Artifacts/messages: [`utility-artifact-manifest`](../recipes/utility-artifact-manifest.json), [`utility-artifact-write`](../recipes/utility-artifact-write.json), [`utility-actor-message`](../recipes/utility-actor-message.json).
-- Validation/state: [`utility-validation-wrapper`](../recipes/utility-validation-wrapper.json), [`utility-validate-recipe`](../recipes/utility-validate-recipe.json), [`utility-run-summary`](../recipes/utility-run-summary.json), [`utility-run-state-files`](../recipes/utility-run-state-files.json), [`utility-jsonl-tail`](../recipes/utility-jsonl-tail.json).
-
-## Operating Patterns
-
-- **Short deterministic command**: call a foreground registered tool or command template.
-- **Long job/service/fanout**: `spawn` an async recipe, then inspect messages and artifacts.
-- **One-off experiment**: use inline `template`; promote only useful repeats.
-- **Reusable workflow**: package a user or bundled recipe with public knobs, mailbox, artifacts, and docs.
-- **Subagent/swarm execution**: compose packaged recipes/pipelines from smaller recipe cells; add missing generic cells to the extension rather than creating one-off external orchestration scripts.
-- **Consensus-first build**: when many lenses should shape one artifact, have proposer subagents post room messages, then one named implementer writes, one QA reviewer checks, and one finalizer emits `run.done`.
-- **Coordinated workers**: spawn `coordinator-locker` when several actors need a shared queue, acquire/renew/release resource leases, or a journaled coordination point.
-- **Release/review pipeline**: pi-actors can prepare evidence, summaries, and artifacts; external actions such as commit, PR, merge, tag, and publish require the appropriate gated release workflow.
-
-## Complementary Methodology Engines
-
-pi-actors is the local execution engine for methodology skills. A methodology skill can define abstract patterns such as lens swarm, quorum, task cards, lock discipline, consensus-first build, or clean-context merge; pi-actors turns those patterns into concrete local actors, recipes, queues, leases, artifacts, and messages.
-
-Keep the split clean: methodology chooses coordination shape; pi-actors supplies addressable local machinery.
-
-## Lifecycle Discipline
-
-1. Choose an existing recipe/tool when available.
-2. Spawn with a stable actor id for observable work.
-3. Inspect `status` after launch.
-4. Use notifications and `inspect`; do not busy-poll.
-5. Read `messages` and `artifacts`, not only stdout.
-6. Use `message` for explicit control or domain commands; inspect `mailbox` before domain-specific messages.
-7. Promote repeated inline forms to recipes.
-8. Keep recipes small and shallow: files over 1 MiB or import chains deeper than 32 are rejected.
-9. Update docs/context when changing public behavior; if the change affects how agents operate this extension, update the bundled skill and prompt guidance too.
-
-## Common Pitfalls
-
-- Treating actor mechanics as multi-agent methodology.
-- Repeating inline templates instead of promoting recipes.
-- Creating task-specific external orchestration scripts when the scenario belongs in pi-actors as a reusable recipe/pipeline.
-- Embedding complex shell loops or Bash `${...}` parameter expansion directly in command templates; braces are pi-actors placeholders too.
-- Omitting stable run ids for work that needs follow-up.
-- Sending domain messages without checking `mailbox`.
-- Expecting current room messages to wake prompt-only subagents; use direct branch messages or a runner protocol for initiating work.
-- Reading only stdout and missing actor messages/artifacts.
-- Assuming every packaged message-controlled script is native-Windows-ready; core run control is platform-adapted, but Unix-tool scripts must be migrated recipe by recipe.
-- Baking local absolute paths into published docs or reusable recipes.
-- Creating recipes that perform external side effects without explicit operator gates.
-- Letting project insights live only in chat instead of updating BACKLOG/CHANGELOG/docs and, when agent behavior changes, the packaged skill or prompt guidance.
-- Preserving old runtime/event/FIFO vocabulary instead of `spawn`/`message`/`inspect` and actor messages.

package/docs/component-recipes.md

@@ -1,148 +0,0 @@
-# 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.
-
-## Boundary
-
-This is a weak abstract contract, not a hard dependency model.
-
-- `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.
-
-## Component Contract
-
-Every reusable component recipe should make the following clear:
-
-- **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.
-
-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.
-
-Keep components narrow. Higher-level recipes should own composition, not hidden behavior inside a leaf.
-
-## Spectrum of Components
-
-### Launchers
-
-Start one subagent or branch with a caller-provided prompt and model. Launchers do not judge or merge output.
-
-Examples: `recipes/subagent-prompt.json`, `recipes/subagent-tools.json`, and `recipes/subagents-prompts.json`.
-
-### 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.