@llblab/pi-actors 0.46.1 → 0.47.0

package/dist/skills/actors/references/runs.md

@@ -0,0 +1,39 @@
+# Runs
+
+Use a Run when execution may outlive the current turn, needs declared Control, produces retained artifacts/evidence, fans out, or must remain inspectable.
+
+## Launch
+
+```text
+spawn recipe=<skill>/<recipe> values={...} as=run:<id>
+```
+
+Use the owning capability Skill to choose the Recipe and capability-specific values. Retain the returned Run id. A spawn result reports `launch_kind: "spawn"`; it is never evidence of registered-tool invocation.
+
+## Observe
+
+Normally wait for terminal follow-up. Inspect only when requested, when meaningful attention arrives, or when the Run is overdue or blocked:
+
+```text
+inspect target=run:<id> view=recipe
+inspect target=run:<id> view=trace
+inspect target=run:<id> view=control
+```
+
+Trace is bounded retained observation, so read its completeness summary. Prove final outcomes with terminal status, result, declared artifacts, and execution evidence rather than assuming retained Trace is exhaustive.
+
+## Control
+
+Send an actor-local action only when the root Recipe declares and implements it:
+
+```text
+message target=run:<id> action=<declared-action> input={...}
+```
+
+Inspect Control when readiness, capacity, stale work, or saturation matters. Put large data in an artifact and send only a bounded reference or instruction. Use runtime-owned termination for a stuck Run rather than inventing undeclared service actions.
+
+Control is not actor chat, peer routing, or a task inbox. A Recipe import does not create a peer actor. Several actors/subagents require the `swarm` methodology in addition to these Run mechanics.
+
+## Safety
+
+Operate only on owned Runs and their active generation. Never edit Run state to force an outcome, bypass process identity checks, or signal processes directly from UI/instruction code. Restart creates new generation-local evidence; inspect the exact generation before destructive lifecycle action.

package/dist/skills/artifacts/SKILL.md

@@ -1,16 +1,33 @@
 ---
 name: artifacts
-description: Deterministic artifact writing, reporting, manifests, and bundles for reusable actor workflows.
+description: Use when an actor workflow must write reusable files, reports, manifests, or bundles with deterministic paths and declared outputs.
 ---
 
 # Artifacts
 
-Own reusable capabilities that turn bounded input or prior command output into declared files, reports, manifests, and artifact bundles.
+Use this Skill after the desired durable-output outcome is known. For generic Recipe execution, Runs, persistence, or diagnosis, follow `actors`; this Skill only selects artifact behavior.
 
-## Scope
+## Choose the outcome
 
-- Write or assemble caller-declared artifacts with explicit paths and overwrite policy.
-- Produce bounded human-readable reports and machine-readable manifests.
-- Compose validation evidence into artifact outputs without owning the validation policy.
+| Desired outcome | Recipe | Result |
+| --- | --- | --- |
+| Write one generated artifact and a machine-readable manifest, with optional validation first | `artifacts/bundle` | Primary artifact plus manifest |
+| Generate bounded normalized report content without committing a filesystem write | `artifacts/report` | Report content for review or later composition |
+| Generate and write one artifact | `artifacts/write` | Declared artifact path written with explicit mode |
+| Describe one existing or intended artifact | `artifacts/manifest` | Manifest JSON on stdout; no write |
+| Write prior pipeline output exactly | `artifacts/file-write` | Supporting stdin-to-file write; normally use inside composition |
 
-This Skill does not own repository workflow, multi-agent review methodology, Run lifecycle, retention policy, or transport delivery. Its Recipe identity is `artifacts/<filename stem>`; Recipe files have no top-level `name`. Cross-capability composition uses exact `<skill>/<recipe>` references; helper-backed Recipes use only this Skill's `scripts/` through `{skill_dir}`.
+Prefer `bundle` when both durable content and inventory evidence are required. Prefer `write` for one accepted file. Use `report` while content still needs review. Do not use `file-write` as a content generator. If one selected outcome should become a recurring named tool, use the persistent-capability workflow in `actors`; do not copy its graph.
+
+## Inputs and boundaries
+
+- Keep `input` bounded and evidence-based; choose the current model explicitly where the Recipe requires `model`.
+- Supply caller-owned `artifact_path` and, for `bundle`, a distinct `manifest_path`.
+- `write_mode=create` is the safe default and stops if the target exists. Use `overwrite` or `append` only when the requested mutation is explicit.
+- Parent directories are created by the writer. `~` is resolved for artifact paths.
+- `manifest` reports existence, size, and modification evidence; it does not validate artifact meaning.
+- Validation in `bundle` runs only when `run_validation=true` and uses the caller-supplied trusted command and scope.
+
+## Stop rules
+
+Stop rather than guessing when the target path, overwrite policy, accepted content, model, or validation command is unclear. Do not claim a durable artifact from `report` or `manifest` alone. After a Run starts, use the `actors` evidence and lifecycle protocol; this Skill does not redefine it.

package/dist/skills/media/SKILL.md

@@ -1,16 +1,44 @@
 ---
 name: media
-description: Local media discovery, playlist construction, and controllable playback capabilities.
+description: Use for local media discovery, filtering, library summaries, playlist construction, or controllable playback.
 ---
 
 # Media
 
-Own reusable local media workflows and services.
+Use this Skill for caller-selected local media. For generic Recipe execution, persistent-tool setup, Run lifecycle, or diagnosis, follow `actors`; this Skill only selects media behavior.
 
-## Scope
+## Choose the operation
 
-- Scan caller-selected media sources and build bounded playlists.
-- Run controllable playback when the local player implements declared actions.
-- Emit canonical Trace and consume canonical Control without inventing media-specific runtime nouns.
+| Intent | Recipe | Use when |
+| --- | --- | --- |
+| Start or control playback | `media/player` | A local file, directory, or playlist should become a controlled service |
+| Build a library summary | `media/library` | A filtered playlist should feed bounded report content |
+| Build a filtered playlist | `media/playlist-build` | Extension filtering and `paths`, `m3u`, or `inline` output are required |
+| Scan a directory for raw file paths | `media/playlist-scan` | A shallow unfiltered inventory is intentionally sufficient |
 
-This Skill does not own the Run kernel, user media, transport delivery, or general artifact policy. Its Recipe identity is `media/<filename stem>`; Recipe files have no top-level `name`. Helper-backed Recipes locate only co-located scripts through `{skill_dir}`, and cross-capability composition uses exact `<skill>/<recipe>` references.
+Use `playlist-build` rather than `playlist-scan` for normal media selection. `library` composes playlist output into report content; its `artifact_path` identifies the intended report target but does not by itself prove a durable write.
+
+## Controlled playback
+
+`media/player` is an async controlled service. Start one owned Run, then use only its declared actions: `play`, `pause`, `resume`, `toggle`, `next`, `previous`, `stop`, and `status`.
+
+```text
+spawn recipe=media/player as=run:music values={"source":"~/Music","player":"auto"}
+message target=run:music action=pause
+inspect target=run:music view=control
+```
+
+For recurring playback as a persistent callable tool, use the persistent-capability workflow in `actors` with `from=media/player`; do not copy the player contract.
+
+## Paths and selection
+
+- `source` for playback must name caller-approved local media; do not broaden it to unrelated directories.
+- `source_dir` must be an intended readable directory. `~` is accepted by maintained media helpers.
+- Keep `max_depth` bounded. Use explicit comma-separated extensions for `playlist-build` and `library`.
+- Choose `output_mode=m3u` only when playlist text is wanted; it does not create a playlist file.
+- Choose an explicit `artifact_path` and model for `library` report generation.
+- `player=auto` selects an available supported backend; do not install or substitute a player silently.
+
+## Stop rules
+
+Stop if the source is missing, unreadable, contains no selected media, or no supported player is available. Do not claim playback from process start alone; confirm through Run evidence or `status`. Prefer the declared `stop` action for a responsive player. If the service is unresponsive, return to `actors` for bounded Run recovery rather than shell process control.

package/dist/skills/project-work/SKILL.md

@@ -1,16 +1,37 @@
 ---
 name: project-work
-description: Repository inspection, documentation maintenance, release preparation, and project health workflows.
+description: Use for repository health inspection, project summaries, documentation maintenance, release-readiness evidence, or bounded run-operation reports.
 ---
 
 # Project Work
 
-Own reusable workflows for inspecting and maintaining software projects.
+Use this Skill to produce bounded project evidence and plans. For generic Recipe execution, Run lifecycle, persistence, or multi-actor methodology, follow `actors` and, when applicable, `swarm`; this Skill only selects project workflows.
 
-## Scope
+## Choose the primary workflow
 
-- Summarize Git, package, Skill, changelog, and documentation state.
-- Compose repository health, documentation maintenance, and release-readiness evidence.
-- Keep project-level orchestration separate from lower-level artifact and actor utilities.
+| Intended result | Recipe | Boundary |
+| --- | --- | --- |
+| Repository status, recent history, docs surface, validation, and risks | `project-work/repo-health` | Runs the caller-supplied trusted validation command |
+| Documentation consistency review and maintenance plan | `project-work/docs-maintenance` | Evidence and plan only; does not edit documentation |
+| Multi-lens release verdict with blockers and degraded-confidence evidence | `project-work/release-readiness` | Readiness only; does not publish |
+| Evidence-only release summary and PR-body draft | `project-work/release-summary` | No commit, PR, merge, tag, publish, or external release action |
+| Bounded report over existing actor Run state | `project-work/run-ops` | Read-only report; does not send Control or mutate Runs |
 
-This Skill does not own the Run kernel, publication authority, multi-agent methodology, or artifact-writing mechanics. Its Recipe identity is `project-work/<filename stem>`; Recipe files have no top-level `name`. It composes other capabilities only through exact `<skill>/<recipe>` references and keeps project-specific helper behavior under its own `scripts/` directory.
+Choose `release-readiness` when independent review and a release verdict are needed. Choose `release-summary` when the evidence is already sufficient and only a concise operator-gated summary is wanted. If one primary workflow should become a recurring named tool, use the persistent-capability workflow in `actors`; do not copy its composition.
+
+## Inputs and evidence
+
+- Scope every workflow to the caller-selected repository, docs directory, or Run state.
+- Treat `validation_command` as trusted executable input. Do not invent or broaden it.
+- Select current model policy explicitly for workflows that request a model; release-readiness reviewer roles inherit only the values supplied by the caller.
+- Artifact paths identify intended report targets. Confirm actual declared artifact evidence before claiming a durable file.
+- Preserve degraded or insufficient review status. Never turn partial reviewer output into consensus.
+- Release outputs are evidence, not publication authority.
+
+## Supporting Recipes
+
+`git-status`, `git-log`, `changelog-head`, `changelog-section`, `markdown-index`, `package-summary`, and `skill-summary` support the primary workflows. Use one directly only when its narrow deterministic output is the requested result; otherwise start from a primary workflow and avoid rebuilding its composition manually.
+
+## Stop rules
+
+Stop when repository scope, version, validation command, model policy, or write target is ambiguous. Do not edit docs from a `docs-maintenance` plan, publish from release evidence, or send Run Controls from `run-ops`. Hand those operations to their owning protocol after explicit authorization.

package/dist/skills/recipe-memory/SKILL.md

@@ -1,16 +1,36 @@
 ---
 name: recipe-memory
-description: Package-owned structural review components for safe persistent Recipe capability memory.
+description: Use only for internal automatic Recipe-memory review, diagnosis, or recovery; do not use for normal Recipe creation, registration, or invocation.
 ---
 
 # Recipe Memory
 
-Own the executable reviewer components used by automatic draft and active-tool Recipe evolution.
+Use this Skill only when automatic draft-memory or active-tool review needs diagnosis or bounded recovery. Normal agents must not spawn, register, specialize, or invoke `recipe-memory/draft-review` or `recipe-memory/tool-review`; they are package-owned internal reviewer components.
 
-## Scope
+## Diagnose first
 
-- Review value-free structural projections rather than executable content or machine-local paths.
-- Return bounded decisions for deterministic package-owned executors.
-- Remain package-owned so user Recipes cannot shadow or redirect automatic review.
+```text
+inspect target=recipes view=reviews
+inspect target=runtime view=triage
+```
 
-This Skill does not own registry mutation, CAS, journaling, quarantine, lineage, retry, reset, or safe-boundary activation. Those remain Run-kernel and registry responsibilities. Its direct Recipe identities are `recipe-memory/<filename stem>`; Recipe files have no top-level `name`. They are internal components, never automatic user tools.
+Use the review view to distinguish `draft` and `tool` scope, current phase, failed stage, bounded error, preserved transaction evidence, and the recorded next action. Use runtime triage only when the reviewer Run itself needs Run-level diagnosis. Follow `actors` for generic Inspect, Run, and Control semantics.
+
+## Recovery Controls
+
+Use runtime Controls only when the review evidence names the matching recovery action:
+
+```text
+message target=runtime action=review.retry input={"scope":"draft"}
+message target=runtime action=review.retry input={"scope":"tool"}
+message target=runtime action=review.reset input={"scope":"draft"}
+message target=runtime action=review.reset input={"scope":"tool"}
+```
+
+- `review.retry` resumes the selected failed review scope while preserving authenticated transaction recovery.
+- `review.reset` clears disposable failure state only. It must reject evidence that requires roll-forward recovery.
+- Re-inspect `view=reviews` after one recovery Control; do not loop retries or resets without changed evidence.
+
+## Stop rules
+
+Stop when the phase is healthy or idle, the requested scope does not match the failure, recovery evidence requires deterministic roll-forward, or the reported next action is not retry/reset. Never edit review state, lineage, journals, quarantine, drafts, or persisted Recipes directly. Never bypass automatic review by running its internal Recipes as ordinary capabilities.