@llblab/pi-actors 0.46.0 → 0.47.0

package/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/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/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.