@llblab/pi-kit 0.1.0

package/node_modules/@llblab/pi-actors/docs/command-templates.md

@@ -0,0 +1,321 @@
+# Command Template Standard
+
+Command templates are the portable integration format for deterministic local automation.
+
+**Meta-contract:** transportable (bit-for-bit identical across projects), high-density (zero fluff), constant (evolve by crystallizing, not speculating), optimal minimum (add only when it hurts).
+
+**Scope:** portable synchronous command execution format — shell-free exec, composition/pipes, optional timeout, delay-before-start, bounded retry, failure propagation, recover cleanup, output artifact selection, and handler-level fallback. Single JSON standard; no platform lock-in.
+
+---
+
+Extensions may choose their own config files, selectors, placeholder sources, and examples, but should preserve this core contract.
+
+Layer boundary: command templates own only the synchronous execution graph. Recipe imports, import-reference expressions, Recipe lookup, `async: true`, Run ids, state dirs, Control, and Trace are host/Recipe/Run layers, not portable command-template syntax.
+
+## Layer Ownership
+
+Command-template standard owns:
+
+- Command string splitting, portable script-interpreter inference, and direct argv execution.
+- Placeholder resolution, typed public args, defaults, `??`, ternary string selection, and array-index placeholders.
+- Synchronous graph shape: sequence, `parallel`, `when`, `repeat`, stdin flow, stdout joins, and output selection.
+- Per-node execution controls: `timeout`, `delay`, `retry`, `failure`, and `recover`.
+
+Command-template standard does not own:
+
+- Where templates are stored or how they are named.
+- Recipe imports, import references, or file lookup.
+- Detached lifecycle, Run ids, state dirs, logs, cancellation, Control, or Trace.
+- Registry metadata such as tool descriptions, package install paths, or operator policy.
+
+## Shape
+
+A command template is either a command-line string or an ordered array of command-template leaves:
+
+```json
+{
+  "template": "/path/to/stt --file {file} --lang {lang=ru}"
+}
+```
+
+When the surrounding schema already implies a command template, the compact string form is equivalent:
+
+```json
+"/path/to/stt --file {file} --lang {lang=ru}"
+```
+
+There is no portable `command` field. The command is derived from `template`: after splitting, the first word is the executable and the remaining words are argv args. Templates do not infer flags: `{file}` is one positional arg; `--file {file}` is a flag arg plus its value.
+
+Common object fields:
+
+- `label`: Optional human label for diagnostics and parallel branch reports.
+- `parallel`: Optional boolean for array templates. Default is `false` for sequence; `true` runs children concurrently.
+- `concurrency`: Optional positive integer cap for a `parallel: true` node. Omit it to launch all children at once.
+- `min_successful`: Optional non-negative integer evidence threshold for a `parallel: true` node. Usable branches are successful branches with non-empty stdout; joins include a `parallel_status` header when this is set.
+- `when`: Optional node guard. A false guard skips the node; strings may be `flag`, `!flag`, or `{flag?yes:no}` style expressions.
+- `args`: Optional placeholder declarations. Untyped names remain valid; compact typed forms such as `file:path`, `request_timeout:int`, `speed:number`, `dry_run:bool`, `prompts:array`, and `mode:enum(check,fix)` are valid when the host supports typed tool schemas. `name:type=value` is an optional argument with an inline fallback. Hosts reject duplicate names and conflicting declared/placeholder types rather than selecting one silently.
+- `defaults`: Placeholder default values by name.
+- `timeout`: Optional execution timeout in milliseconds. Omit it, or set `0`, to leave the command unbounded. Set an explicit positive timeout when a tool must fail closed instead of waiting indefinitely. Numeric control fields may be literal numbers or placeholders such as `"{timeout_ms}"`.
+- `delay`: Optional wait in milliseconds before starting this node. Default is no delay. It may be a literal number or placeholder.
+- `accept_output`: Optional fail-closed semantic output contract. `review_evidence` requires successful stdout to begin with `ACTOR_REVIEW_RESULT`; missing markers become code-65 failures while rejected stdout remains visible in branch diagnostics.
+- `output`: Optional result selector. Default is `"stdout"`; runtime values such as `"ogg"` are valid.
+- `retry`: Optional max attempts including the first. Default is `1`.
+- `failure`: Optional failure propagation scope: `continue`, `branch`, or `root`. Default is `continue`.
+- `recover`: Optional command template run between failed retry attempts. Recovery output is ignored; recovery failure stops retries.
+- `template`: Required command string or ordered composition array.
+
+For object form, write `template` last. Read the node flags first, then the executable content. Storage paths, labels, selectors, descriptions, and registry-specific metadata belong to each extension's local schema.
+
+## Execution
+
+A runtime must:
+
+1. Split the template into shell-like words with simple single quotes, double quotes, and backslash escapes
+2. Substitute placeholders inside each split word
+3. Infer a first-word `.js` or `.mjs` script through the first available `node`, `bun`, or `deno run` runtime, infer `.sh` through `bash`, and otherwise execute command + args directly; explicit interpreters remain unchanged and no shell evaluates the resulting argv
+4. Treat exit code `0` as success and non-zero as failure
+5. Use stdout as the default result channel and stderr only for diagnostics
+
+Implementations may expand `~` in command position and may resolve relative command paths against the caller cwd.
+
+## Placeholders
+
+Supported forms:
+
+| Form               | Meaning                                          |
+| ------------------ | ------------------------------------------------ |
+| `{name}`           | Required value from runtime values or `defaults` |
+| `{name=default}`   | Inline default when no value is provided         |
+| `{name??fallback}` | Fallback when value is missing, null, or empty   |
+| `{name?yes:no}`    | Ternary string selected by truthiness of `name`  |
+| `{items[index]}`   | Array item selected by literal or repeat index   |
+
+Resolution order is runtime values → `defaults` → inline default → error. Nullish coalescing and ternary conditions treat missing, empty, `false`, `0`, and `no` as false. Use `??` for value fallback and ternaries for small string selection such as optional CLI flags; larger policy branches should stay in recipes, scripts, or separate template nodes. Default values that are themselves a single placeholder, such as `{prompt}` resolving to `{prompts[index]}`, are resolved recursively with a small depth guard. A repeat node may set `repeat` to `{items.length}` when an array arg should determine fanout width.
+
+```json
+{
+  "template": "/path/to/tts --text {text} --lang {lang=ru} --rate {rate=+30%}"
+}
+```
+
+With runtime values `{ "text": "hello" }`, argv is:
+
+```text
+["--text", "hello", "--lang", "ru", "--rate", "+30%"]
+```
+
+Use `defaults` for visible fallback configuration, `values` for composition binding, and inline defaults for compact local literals. Named resolution uses caller values before composition values, explicit defaults, and inline defaults; the final selected value is type/enum validated. Prefer flag-style examples such as `/path/to/tool --file {file} --lang {lang=ru}` for readability, but positional forms such as `/path/to/tool {file} {lang=ru}` are valid when the invoked script defines that CLI contract.
+
+Use `{env??dev}` for fallback values and `{all?--all:}` to map boolean args to optional text.
+
+Typed declarations annotate the public tool interface, not the shell command. They may live in `args` or inline placeholders such as `{request_timeout:int=60000}` and `{mode:enum(check,fix)=check}`. Use metadata-first authoring (`args` plus `defaults`) when long templates should stay visually short; use inline-first authoring when one self-contained `template` property is clearer. They do not sandbox or reinterpret the executable; they only let the host generate narrower input schemas and normalize runtime values before placeholder substitution. Untyped `args` and untyped placeholders continue to work unchanged.
+
+Node control fields can also read public args, for example `"timeout": "{timeout_ms}"`; use distinct names so execution controls stay visually separate from public inputs.
+
+## Quoting
+
+Placeholder values are not shell-escaped because no shell is used. A value containing spaces remains one argv item when it replaces one split word:
+
+```text
+template="echo {text}"
+text="hello world"
+args=["hello world"]
+```
+
+A placeholder may also be embedded inside one word:
+
+```text
+template="/path/to/tool --file={file}"
+file="/tmp/a b.ogg"
+args=["--file=/tmp/a b.ogg"]
+```
+
+Use quotes only for literal template words that should contain spaces before placeholder substitution:
+
+```text
+template="echo 'literal words' {text}"
+```
+
+## Composition
+
+Shell syntax warning: command-template placeholder parsing still sees braces inside shell snippets. Avoid inline Bash parameter expansion such as `${file%.md}` or `${name}` in recipe/template strings because `{file...}` can be parsed as a pi-actors placeholder. For non-trivial shell loops or parameter expansion, put the shell logic in a small trusted script and call that script from the template; keep the command template as the launch boundary.
+
+`template: [...]` means sequential composition by default; each leaf is a command template executed with one shared runtime value map:
+
+```json
+{
+  "template": [
+    "/path/to/tts --text {text} --lang {lang=ru} --out {mp3}",
+    "ffmpeg -y -i {mp3} -c:a libopus {ogg}"
+  ],
+  "output": "ogg"
+}
+```
+
+Composition rules:
+
+- Execute leaves in order when `parallel` is omitted or `false`
+- Execute child templates concurrently when `parallel` is `true`
+- Parallel composition uses soft-quorum semantics by default: failed children are reported as degraded branches unless failure propagation escalates
+- Non-critical failures are recorded and execution continues, while `failure: "branch"` stops the current branch and `failure: "root"` aborts the root composition
+- Treat the whole composition as one handler for selector matching and fallback
+- Top-level `args` and `defaults` apply to every leaf unless the leaf defines private values
+- Leaf `args` replace inherited `args`; leaf `defaults` merge over inherited defaults; `timeout` and `output` are not inherited into leaves
+- Timeout is disabled by default; configure a positive `timeout` for bounded commands that should fail closed
+- Child stdout and stderr are captured as raw bytes with independent bounded in-memory tails; streams that exceed the capture limit spill completely to byte-exact diagnostic files and return byte counts, truncation flags, and spill paths. Text tails align their start to a UTF-8 code-point boundary so chunking or truncation does not corrupt valid multibyte output. Async runs persist complete streams even below the capture limit under command- and retry-specific run-state paths
+- Each sequence leaf receives the previous leaf's complete stdout on stdin by default, reading the byte-complete spill when the model-facing capture is truncated; the final leaf stdout remains the bounded default composition result. Parallel joins likewise use complete branch spills for downstream stdin while branch details and returned output stay bounded. If a declared spill is unavailable, the pipeline fails closed instead of forwarding a partial tail
+- Skipped nodes preserve current stdin/stdout flow and do not execute commands
+- Each parallel child receives the same stdin, and child stdout values are joined in stable array order before flowing to the next sequence leaf
+- Parallel branch joins include branch label and status, and tool details include branch metadata plus coverage summary
+- `min_successful` adds a join header with `complete`, `degraded`, or `insufficient_data`; with `failure: "branch"` or `"root"`, an unmet threshold fails at that scope
+- Each leaf still applies its own inline defaults
+
+`output` selects the primary result channel. Omitted `output` means `"stdout"`, and explicitly writing `"output": "stdout"` is valid standard syntax. Artifact-producing handlers may instead name a runtime value or placeholder path, e.g. `"ogg"` or `"{ogg}"`. Do not use `artifacts` in command-template nodes; named artifact manifests belong to the template-recipe layer.
+
+### Repeat
+
+`repeat` expands one command-template node N times before execution. It works with both sequence and parallel nodes and is useful when many branches differ only by a number.
+
+```json
+{
+  "parallel": true,
+  "repeat": 8,
+  "template": "render page{_(index+1)}.html --prev page{_(prev+1)}.html --next page{_(next+1)}.html --zero page{_index}.html"
+}
+```
+
+Reserved repeat placeholders are injected into each repeated node:
+
+- `{index}`: current zero-based index, `0..repeat-1`
+- `{prev}` / `{next}`: wrapped zero-based neighbors
+- `{repeat}`: total repeat count
+
+Human 1-based numbering is intentionally expressed as limited arithmetic: `{index+1}`, `{prev+1}`, `{next+1}`.
+
+Leading underscores on repeat placeholders request zero padding. One underscore means width 2, two underscores mean width 3, and so on:
+
+```text
+{_index}      → 00, 01, ...
+{_(index+1)}  → 01, 02, ...
+{__(index+1)} → 001, 002, ...
+{_(prev+1)}   → wrapped previous page number, padded to width 2
+{_(next+1)}   → wrapped next page number, padded to width 2
+```
+
+Repeat expressions support only integers, `index`, `prev`, `next`, `repeat`, parentheses, and `+`, `-`, `*`, `/`, `%`. They are not JavaScript and cannot call functions or access properties.
+
+Repeat placeholders are local generated values. Call-time args should not use these reserved names to override the repeat index.
+
+Parallel children use the same object shape: flags come first and `template` stays last. A join remains usable when at least one branch succeeds and reports each branch label/status. Some local schemas may accept `pipe`, but the portable standard is `template: [...]`.
+
+## Failure Propagation
+
+By default, failed steps use `failure: "continue"`: record the failure, clear stdout for that step, and continue the current sequence. This preserves the fail-open profile.
+
+Use `failure` when a node should stop more aggressively:
+
+- `"continue"`: record the failure and continue the current sequence.
+- `"branch"`: stop the current sequence/subtree and return a failed branch to the nearest parent. In a parallel node, sibling branches keep running and the join becomes degraded. At the root, branch failure is still a tool failure.
+- `"root"`: abort the outermost composition.
+
+A branch failure skips the remainder of that branch while parallel siblings can finish; their join reports degraded coverage.
+
+## Retry
+
+Set `retry: N` to attempt execution up to `N` times including the first. The first successful attempt stops the retry loop.
+
+On leaf commands, retry repeats that command. On sequence or parallel nodes, retry repeats the whole node. A retried group only retries when the group returns a failure, so validator checkpoints normally pair group retry with `failure: "branch"` or `failure: "root"`.
+
+```json
+{
+  "failure": "branch",
+  "retry": 3,
+  "template": ["implement {scope}", "npm test", "git diff --check"]
+}
+```
+
+Here the whole group runs again when a validator fails. Without `failure: "branch"`, the failed validator would be logged and the group would continue by default.
+
+## Recover
+
+Set `recover` on a retried node to run cleanup after a failed attempt and before the next attempt. `recover` is another command template: it can be a string command, sequence, or parallel tree. Its output is ignored and the next retry receives the original stdin.
+
+```json
+{
+  "failure": "branch",
+  "retry": 3,
+  "recover": "git -C {work_dir} reset --hard HEAD",
+  "template": ["pi -p --tools read,edit,bash {scope_file}", "npm test"]
+}
+```
+
+`recover` is not a fallback success path. It is cleanup between attempts. Practical uses include resetting a worktree, removing temp files, clearing generated output, releasing a local lock, or stopping a helper process before trying the node again. If recovery fails, retries stop and the recovery failure is returned. Recovery uses fail-closed semantics by default; set an explicit `failure` inside a recover template only when a softer cleanup failure is intentional.
+
+## Conditional Nodes
+
+Set `when` to skip a node unless a boolean condition is true. This is node-level branching, not placeholder text selection. It is useful for optional validation, artifact, or reporting steps.
+
+```json
+{
+  "template": [
+    "prepare {target}",
+    { "when": "run_tests", "template": "npm test" },
+    { "when": "!run_tests", "template": "echo tests skipped" }
+  ]
+}
+```
+
+Falsy values are missing, empty, `false`, `0`, and `no`. In a sequence, a skipped node preserves the previous stdout for the next step. In a parallel branch, a skipped node succeeds with empty branch output.
+
+## Delay
+
+Set `delay` to wait before starting a node. The value is milliseconds. Delay is not inherited into child nodes, just like `timeout`.
+
+```json
+{
+  "template": [
+    "prepare {scope}",
+    { "delay": 1000, "template": "review {scope}" }
+  ]
+}
+```
+
+On a sequence node, `delay` waits before the sequence begins. On a parallel node, `delay` waits before launching its children. On a branch, `delay` waits before that branch starts, without blocking sibling branches.
+
+Use `delay` only for explicit backoff, rate pacing, or staged launch. Do not use it as a scheduler.
+
+## Progressive Disclosure
+
+The standard uses a single `template` field that grows with the user's needs:
+
+```text
+string           → leaf command
+string[]         → sequential composition
+{ template }     → leaf command object
+{ parallel, template } → sequence or parallel subtree
+{ parallel, concurrency, min_successful, when, args, defaults, delay, retry, failure, recover, accept_output, output, template } → full node
+```
+
+Start with a string. Add composition when needed. Add `parallel: true` when independent work can run concurrently. Add `when` when a node is conditional. Add delay when launch pacing matters. Add retry when flaky. Add `failure` when propagation scope matters. Add `recover` when a retried node needs cleanup before another attempt. Same contract, growing capability, no dead weight.
+
+`parallel: true` is the synchronous fanout shape. Saved JSON belongs to the separate [Template Recipe Standard](./template-recipes.md); detached lifecycle, logs, cancellation, and durable state belong to the separate [Async Run Standard](./async-runs.md).
+
+## Trust Boundary
+
+Command templates avoid shell interpolation by splitting the template into argv first and substituting placeholders per arg. A placeholder value containing spaces remains one argv value, not a shell fragment.
+
+This is not a sandbox. The executable still runs with the same user permissions as the host agent. Shells, interpreter eval modes, destructive filesystem commands, and local scripts remain trusted code. Examples that deserve extra operator attention:
+
+- `bash`, `sh`, `zsh`, or `fish`, especially with `-c`.
+- `node -e`, `python -c`, `ruby -e`, `perl -e`, or similar eval modes.
+- `rm`, `mv`, `cp`, or `rsync` over broad paths or placeholder-derived paths.
+
+Hosts may surface lightweight warnings for these obvious high-risk shapes. Warnings should inform review without blocking existing tools, because many trusted local wrappers intentionally use shells or filesystem mutation.
+
+## Tool Boundary
+
+Agent tools are a separate abstraction. A tool name is not a portable command template because the pi extension API exposes tool registration metadata, not a public extension-to-extension `executeTool(name, args)` contract. Until such an API exists, extensions should use command templates for deterministic local automation.
+
+## Compatibility
+
+Consumers should share this contract, not private registry fields or implementation details from any specific extension.

package/node_modules/@llblab/pi-actors/docs/recipe-library.md

@@ -0,0 +1,89 @@
+# Skill-Owned Recipe Components
+
+Active Skills provide maintained execution graphs and service definitions. Skill Recipe identity is `<active Skill name>/<Recipe filename stem>`. Recipe files have no top-level `name`; `SKILL.md` `name` remains Pi host metadata matching the Skill directory, and pi-actors introduces no additional Skill identity field. Skill components are outside user Recipe discovery and never become tools merely because a Skill is active.
+
+## Recommended Entry Points
+
+### Repository and delivery
+
+- `project-work/repo-health` — repository status, recent history, docs surface, trusted validation, and bounded report content.
+- `project-work/docs-maintenance` — documentation consistency evidence and a maintenance plan; it does not edit documentation.
+- `project-work/release-readiness` — multi-lens readiness verdict and blockers; it does not publish.
+- `project-work/release-summary` — evidence-only release summary and PR-body draft with no external release side effect.
+- `project-work/run-ops` — read-only report over existing Run state; it does not send Control.
+- `swarm/development-tasking` — bounded task-card and scope-critique pipeline.
+
+### Review and synthesis
+
+- `swarm/quorum-review` — parallel reviewers with quorum-oriented synthesis.
+- `swarm/review-readiness` — review plus readiness stages.
+- `swarm/research-synthesis` — evidence map, contradiction analysis, and risk-first research synthesis.
+- `swarm/lens-review` — different independent risk lenses for breadth.
+- `swarm/architect` — competing architecture directions and one validated smallest next slice.
+- `swarm/subagent-review-coordinator` — lower-level review/verify/merge/judge composition.
+
+Callers should own model, thinking, concurrency, quorum, and mission policy. Review pipelines preflight provider/model availability before expensive fanout.
+
+### Artifacts
+
+- `artifacts/report` — prepare normalized report content without committing a filesystem write.
+- `artifacts/write` — prepare and deterministically write one artifact with explicit create/overwrite/append policy.
+- `artifacts/bundle` — optional validation, artifact write, manifest generation, and manifest write.
+- `artifacts/file-write` — deterministic create/overwrite/append helper.
+- `artifacts/manifest` — artifact manifest generation.
+
+Artifact pipelines terminate in files/manifests and result evidence; they do not fabricate communication events.
+
+### Music playback and controlled services
+
+- `music-player/playback` — singleton playback service that resolves files, directories, URLs, explicit lists, and playlist files into one persistent queue; it exposes declared playback Controls including arbitrary absolute `volume` percentages, generation-fenced endpoint readiness, structured status, a player-owned continuity checkpoint, and playback Trace. Player selection is `player:enum(auto,mpv,afplay,ffplay,cvlc,play,wmp)=auto`.
+- `actors/resource-locker` — optional queue/lease-lock service with explicit owner/resource input, lock Trace, and a 512-record/1 MiB atomically retained journal.
+
+These Recipes declare actor-local Control. Ordinary one-shot Recipes omit it. Helper-backed Skill Recipes self-locate through runtime-owned `{skill_dir}`; callers do not pass package installation roots.
+
+## Component Recipes
+
+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.
+
+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.
+
+Recipes bundled under a Pi-active Skill are selected as `<skill-name>/<recipe-stem>` and receive runtime-owned `{skill_dir}` plus `{recipe_dir}`. Explicit `.json` / `.md` paths select exact files: entry paths are based at invocation `cwd`, while relative imports are based at the importing Recipe's directory. Active Skill components are library entries, never automatic tools; expose one intentionally through a user Recipe wrapper when a direct tool is desired.
+
+## Utility Recipes
+
+Utilities wrap deterministic local capabilities such as:
+
+- package and skill summaries;
+- artifact writes/manifests;
+- validation commands;
+- Run operations snapshots;
+- Recipe validation.
+
+Use utilities as imported cells or registered tools where their contract fits.
+
+## Selection Guidance
+
+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; Trace/Control quotas do not bound user artifacts or actor-owned workload state.
+
+## Installation Safety
+
+Do not bulk-copy bundled Recipes into the user Recipe root. Internal `recipe-memory/draft-review` and `recipe-memory/tool-review` components support fenced automatic review and must not become user-installed callable tools. Register or wrap only the specific public capability you intend to use.
+
+## Validation
+
+```bash
+npm run recipes:qa
+```
+
+Recipe QA recursively inventories direct Skill components and validates filesystem identity, syntax, imports, Control declarations, origin ownership, portable artifact paths, and `{skill_dir}` helper references. Nested files and JSON/Markdown stem collisions fail precisely. Recipe descriptions remain optional; QA requires zero capability diagnostics and zero warnings without enforcing style, documentation quotas, or architecture policy. Removed mailbox declarations fail with the migration diagnostic rather than receiving automatic conversion.
+
+## Related
+
+- [Template Recipes](./template-recipes.md)
+- [Command templates](./command-templates.md)
+- [Runs](./async-runs.md)

package/node_modules/@llblab/pi-actors/docs/releasing.md

@@ -0,0 +1,28 @@
+# Release Operations
+
+Stable releases use one immutable tag workflow. The workflow runs normal product validation on Ubuntu, macOS, and Windows plus the dependency audit before any publication, publishes and verifies the exact npm package through Trusted Publisher, then creates or converges the GitHub Release from the matching changelog section. Architecture review uses the project-local Domain DAG Skill during architecture-affecting development; release automation does not run policy, line-count, source-style, or Domain DAG gates.
+
+## One-time npm Trusted Publisher setup
+
+Configure the existing public package `@llblab/pi-actors` on npmjs.com with a GitHub Actions Trusted Publisher using these exact values:
+
+- **Owner:** `llblab`
+- **Repository:** `pi-actors`
+- **Workflow filename:** `release.yml`
+- **Environment:** Leave empty unless the workflow and npm configuration later adopt the same named GitHub environment in one reviewed change.
+
+The binding must target `.github/workflows/release.yml`; npm asks for the filename rather than the repository-relative path. npm does not verify this identity when the setting is saved, so the first tagged publication provides the decisive proof.
+
+Do not create `NPM_TOKEN`, `NODE_AUTH_TOKEN`, or another long-lived npm publish secret. The publication job runs on a GitHub-hosted Ubuntu runner with `id-token: write`, Node 24, npm 11.5.1 or newer, the public npm registry, and package-manager caching disabled at the credential-bearing boundary.
+
+## Release sequence
+
+1. Merge the validated release tree through the repository's guarded `dev` to `main` flow.
+2. Create one immutable `v<package.version>` tag on the verified `main` commit.
+3. Let `.github/workflows/release.yml` invoke the reusable `npm run validate` and dependency-audit workflow.
+4. Let the publication job verify the tag commit, package manifests, and non-empty changelog section.
+5. Publish the exact public npm package through OIDC when the version does not exist.
+6. Verify npm version, `gitHead`, Pi extension/skill metadata, and packed runtime manifests.
+7. Create or update the GitHub Release only after npm verification succeeds.
+
+A rerun skips `npm publish` only when the exact existing version reports the same tagged `gitHead`; contradictory identity fails closed because npm versions are immutable. Registry lookup retries remain bounded. A missing or mismatched Trusted Publisher usually surfaces as npm authentication or not-found failure and must be corrected in npm package settings—never by adding a token fallback.

package/node_modules/@llblab/pi-actors/docs/template-recipes.md

@@ -0,0 +1,175 @@
+# Template Recipes
+
+A Recipe stores a reusable command-template definition as JSON or Markdown.
+
+## JSON
+
+```json
+{
+  "async": true,
+  "description": "Create a repository health artifact",
+  "args": ["repo:path", "artifact_path:path", "model:string"],
+  "defaults": { "artifact_path": "{state_dir}/health.md" },
+  "imports": { "review": "swarm/quorum-review" },
+  "artifacts": { "report": "{artifact_path}" },
+  "template": {
+    "name": "review",
+    "values": { "input": "Inspect {repo}", "model": "{model}" }
+  }
+}
+```
+
+## Markdown
+
+Markdown Recipes use YAML frontmatter and one executable fence:
+
+````markdown
+---
+description: Summarize one file
+args:
+  - file:path
+---
+
+Human notes remain advisory.
+
+```template
+summarize {file}
+```
+````
+
+Fences marked `template`, `command-template`, `json`, or `recipe` can define execution. Frontmatter supports Recipe metadata and command-template flags.
+
+Skill Recipe identity is `<active Skill name>/<Recipe filename stem>`. Recipe files have no top-level `name`; both JSON and Markdown fail with migration guidance when that removed field is present. `SKILL.md` `name` remains Pi host metadata and matches the Skill directory; pi-actors introduces no additional Skill identity field. The `name` field on a command-template node still selects an imported alias and is not Recipe self-identity.
+
+## Fields
+
+Common Recipe fields:
+
+- `description`, `disabled`;
+- `args`, typed arg declarations, inline defaults, `defaults`, and composition `values`;
+- `imports` with optional binding defaults/values;
+- `template`;
+- `async`;
+- `singleton: true` for one explicit Skill-owned async service slot;
+- `artifacts`;
+- `control` for actual controlled services;
+- command-template flags such as `parallel`, `concurrency`, `min_successful`, `when`, `timeout`, `delay`, `retry`, `failure`, `recover`, `repeat`, `accept_output`, and `output`;
+- `retire_when: "children_terminal"` for opt-in supervisor retirement.
+
+## Imports
+
+```json
+{
+  "imports": {
+    "review": "swarm/quorum-review",
+    "report": {
+      "from": "../shared/report.md",
+      "defaults": { "thinking": "medium" }
+    }
+  },
+  "template": [
+    { "name": "review", "values": { "input": "{input}" } },
+    { "name": "report", "values": { "input": "Use prior output" } }
+  ]
+}
+```
+
+Imports are local definitions. Named nodes call imported templates inside the same execution graph and Run. Effective values follow `caller > node/import/Recipe values > defaults > inline arg default > missing-value error`, then the selected value is checked against its declared type or enum.
+
+Imports accept exactly `<skill>/<recipe>` or an explicit `.json` / `.md` file path. A Skill reference selects one direct filename stem under the exact Skill currently active through Pi resource discovery; duplicate active Skill identities and JSON/Markdown stem collisions fail closed. Explicit paths may be relative (`./local-review.json`, `../shared/report.md`) or absolute (`/absolute/path/to/recipe.json`). An entry file path resolves from invocation `cwd`; a relative import resolves from the importing Recipe's directory. No bare or ambient lookup remains.
+
+Direct delegation can use another Recipe as the entire template. The delegated Recipe remains the source of truth while the wrapper may narrow args/defaults or override selected lifecycle metadata.
+
+A launched Run captures each entry/import role, filename-derived stem, logical reference, Skill identity when owned, and import alias ancestry. Private physical source paths remain execution provenance; Inspector and child-agent context expose logical identities rather than machine-local Skill locations.
+
+## Migration from pre-0.46 references
+
+```text
+std:foo              -> owning-skill/foo
+skill:foo/bar        -> foo/bar
+root packaged foo    -> owning-skill/new-file-stem
+Recipe name field    -> delete; filename is identity
+nested skill path    -> flatten filename or use explicit file path
+```
+
+Removed `std:` and `skill:` forms fail with migration guidance; they are not aliases. Root packaged Recipes no longer exist. Flatten a maintained Skill component to a direct filename, or reference a nested/local file explicitly when it is intentionally outside the Skill component namespace.
+
+## Singleton Services
+
+`singleton: true` is valid only for an async Skill Recipe, and one Skill may declare at most one singleton Recipe. The runtime derives `run:<skill>` and the canonical `<skill>/<recipe>` identity, then rejects a conflicting caller-supplied Run id. A compatible repeated launch returns the healthy active generation; contradictory Recipe identity, ownership, startup values, or Control fails closed. A terminal result is never reused even during runner exit; retry after that process exits starts a fresh `run_instance_id` under the same logical Run id. Actor-owned workload continuity requires a validated state artifact that restart cleanup deliberately preserves; singleton identity alone never proves restored state.
+
+Direct Recipe delegation inherits the original singleton Run and Recipe identities, so registered tools and explicit wrappers cannot retarget the service or create parallel aliases.
+
+## Control
+
+Only a process that consumes actor-local input declares actions:
+
+```json
+{
+  "async": true,
+  "control": ["pause", "resume", "stop"],
+  "template": "{skill_dir}/scripts/service.mjs --state-dir {state_dir}"
+}
+```
+
+Actions must be lowercase ASCII, unique, non-reserved, and at most 64 characters. Serialized Control input is at most 380 bytes so every admitted wire record remains within 512 bytes on FIFO and named pipe. One-shot Recipes omit Control. Larger data belongs in a declared artifact/path; outputs belong in Trace, artifacts, execution evidence, or the command result.
+
+## Artifacts
+
+```json
+{
+  "artifacts": {
+    "report": "{state_dir}/report.md",
+    "manifest": "{state_dir}/manifest.json"
+  }
+}
+```
+
+Artifact paths resolve under containment policy and appear in Run inspection. Recipes should write declared artifacts deterministically and fail when the requested write policy cannot be honored.
+
+## File Origins
+
+Every file-backed Recipe receives immutable `{recipe_dir}`. A Recipe under an active Skill also receives `{skill_dir}`, resolved to the directory containing that Skill's `SKILL.md`; using `{skill_dir}` elsewhere fails clearly. These runtime values cannot be declared in `args`, `defaults`, or `values`, and caller input cannot override them. They expand in templates, recursive defaults/values, imports, and artifacts while existing `./` executable behavior remains relative to invocation `cwd`.
+
+## Context and Provenance
+
+File-backed Runs capture Recipe context records for the entry and imports. File identity is the filename stem; a direct Recipe under an active Skill has the logical identity `<skill>/<stem>`. The captured bundle explains composition identity and remains generation-local evidence. Runtime origin paths remain in local Run provenance but are omitted from model-facing launch values. It does not override the authored task prompt.
+
+Recipes that need a minimal child prompt may opt out of injected Recipe context through the documented `actor_context` launch option.
+
+## Current Policy
+
+Defaults can inherit current Pi policy:
+
+```json
+{
+  "defaults": {
+    "model": "{current_model}",
+    "thinking": "{current_thinking}"
+  }
+}
+```
+
+Resolution fails before launch when required current policy is unavailable. The Run persists whether values were inherited or explicit.
+
+## Resolution Context
+
+User Recipes under `~/.pi/agent/recipes` remain intentionally registered tools, not an ambient import namespace. Each session receives one immutable resolution context from Pi's loaded Skill metadata; spawn, user-Recipe admission, registration, schema derivation, live inspection, and watcher reconciliation consume that same context rather than scanning ambient Skill roots or keeping a process-global mutable namespace. A launch captures its resolved graph, so later Skill changes affect only future launches. An invalid or missing exact target fails without fallback. Disabled Recipes cannot launch. Registry watchers converge after atomic changes without executing partial definitions.
+
+Active-Skill catalog inventory is fail-soft diagnostic state, not exact-resolution authority. Invalid components are reported individually and make the catalog partial while unrelated valid `<skill>/<recipe>` references remain exactly resolvable.
+
+## Validation
+
+```bash
+node skills/actors/scripts/validate-recipe.mjs path/to/recipe.json --qa
+node skills/actors/scripts/validate-recipe.mjs skills --skills --qa --summary
+```
+
+Skill validation recursively inventories every direct `<skill>/recipes/*.json|*.md` component, rejects nested files and duplicate stems, and checks filename identity, JSON/Markdown compilation, origins, imports, Control, artifacts, portable paths, helper targets, and platform notes. Files exceeding 1 MiB or import depth 32 fail closed.
+
+## Related
+
+- [Command templates](./command-templates.md)
+- [Runs](./async-runs.md)
+- [Recipe library](./recipe-library.md)
+- [Tool registry](./tool-registry.md)