@llblab/pi-actors 0.45.1 → 0.46.1

package/dist/skills/project-work/recipes/skill-summary.json

@@ -0,0 +1,11 @@
+{
+  "args": [
+    "skill:path",
+    "package_json:path"
+  ],
+  "defaults": {
+    "skill": "skills/actors/SKILL.md",
+    "package_json": "package.json"
+  },
+  "template": "{skill_dir}/scripts/project-utils.mjs skill-summary {skill} {package_json}"
+}

package/dist/skills/project-work/scripts/project-utils.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+/** Project-work metadata and changelog helpers. */
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+function pathOf(value) {
+  return resolve(String(value).replace(/^~(?=\/|$)/, process.env.HOME ?? "~"));
+}
+
+function readJson(file) {
+  if (!existsSync(file)) return undefined;
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+function packageSummary(fileValue = "package.json") {
+  const pkg = readJson(pathOf(fileValue));
+  if (!pkg) fail(`Package JSON not found or invalid: ${fileValue}`);
+  const dependencies = Object.keys(pkg.dependencies ?? {}).sort();
+  const devDependencies = Object.keys(pkg.devDependencies ?? {}).sort();
+  console.log(JSON.stringify({
+    name: pkg.name ?? "",
+    version: pkg.version ?? "",
+    type: pkg.type ?? "",
+    private: Boolean(pkg.private),
+    packageManager: pkg.packageManager ?? "",
+    files: Array.isArray(pkg.files) ? pkg.files : [],
+    bin: pkg.bin ?? null,
+    main: pkg.main ?? "",
+    exports: pkg.exports ?? null,
+    scripts: Object.keys(pkg.scripts ?? {}).sort(),
+    dependencyCount: dependencies.length,
+    devDependencyCount: devDependencies.length,
+    dependencies,
+    devDependencies,
+  }, null, 2));
+}
+
+function skillSummary(skillValue, packageValue = "package.json") {
+  const content = readFileSync(pathOf(skillValue), "utf8");
+  const pkg = readJson(pathOf(packageValue)) ?? {};
+  const frontmatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1] ?? "";
+  const fields = Object.fromEntries(frontmatter.split(/\r?\n/).flatMap((line) => {
+    const match = line.match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
+    return match ? [[match[1], match[2].trim()]] : [];
+  }));
+  const version = fields.version ?? frontmatter.match(/^\s+version:\s*([^\n]+)$/m)?.[1]?.trim() ?? "";
+  const body = content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "");
+  console.log(JSON.stringify({
+    path: skillValue,
+    name: fields.name ?? "",
+    description: fields.description ?? "",
+    version,
+    packageVersion: pkg.version ?? "",
+    versionMatchesPackage: version === pkg.version,
+    frontmatterExtraColonLines: frontmatter.split(/\r?\n/).filter((line) =>
+      /^\w+:\s*\S/.test(line) && (line.match(/:/g) ?? []).length > 1),
+    bodyLineCount: body.split(/\r?\n/).length,
+    headings: body.split(/\r?\n/).filter((line) => /^#{1,6}\s/.test(line)),
+  }, null, 2));
+}
+
+function changelogSection(fileValue, version) {
+  const lines = readFileSync(pathOf(fileValue), "utf8").split(/\r?\n/);
+  const start = lines.findIndex((line) => line.startsWith("## ") && line.includes(version));
+  if (start < 0) fail(`Version section not found: ${version}`);
+  const next = lines.findIndex((line, index) => index > start && line.startsWith("## "));
+  console.log(lines.slice(start, next < 0 ? lines.length : next).join("\n").trimEnd());
+}
+
+const [command, ...args] = process.argv.slice(2);
+try {
+  if (command === "package-summary") packageSummary(args[0]);
+  else if (command === "skill-summary") skillSummary(args[0], args[1]);
+  else if (command === "changelog-section") changelogSection(args[0] ?? "CHANGELOG.md", args[1] ?? "Unreleased");
+  else fail(`Unknown project command: ${command ?? ""}`);
+} catch (error) {
+  fail(error instanceof Error ? error.message : String(error));
+}

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

@@ -0,0 +1,16 @@
+---
+name: recipe-memory
+description: Package-owned structural review components for safe persistent Recipe capability memory.
+---
+
+# Recipe Memory
+
+Own the executable reviewer components used by automatic draft and active-tool Recipe evolution.
+
+## Scope
+
+- 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.
+
+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.

package/dist/skills/swarm/SKILL.md

@@ -9,7 +9,7 @@ Subagent orchestration: delegated review, quorum consensus, scoped locks, clean-
 
 ## Purpose
 
-Run subagents safely and predictably through reusable orchestration contracts.
+Run subagents safely and predictably through reusable orchestration contracts. Skill Recipe identity is `<active Skill name>/<Recipe filename stem>`; Recipe files have no top-level `name`. Components are direct files under `recipes/` and use exact `swarm/<recipe>` identities, including `swarm/lens-review`, `swarm/quorum-review`, `swarm/research-synthesis`, and `swarm/development-tasking`; they remain components rather than automatic tools.
 
 Activation rule: load this skill before launching multiple independent actors or subagents, even when the work is creative artifact generation rather than code review. The coordinator owns decomposition, disjoint scopes, launch correctness, result integration, and final validation; participants may choose local content or implementation details independently inside their assigned boundaries.
 
@@ -31,7 +31,7 @@ Maintain this skill as a living orchestration standard. When real swarm work exp
 - `Lens`: A deliberately narrow cognitive role assigned to one subagent, such as security, tests, architecture, economics, or operator UX.
 - `Task Card`: A bounded implementation assignment with goal, allowed files, avoided files, expected output, and validation gates.
 - `Component Capability`: An abstract adapter operation such as launcher, reviewer, verifier, merger, quorum, checkpoint, follow-up, judge, or normalizer. Swarm may target these capabilities, but local adapters bind them to concrete tools, recipes, draft recipes, command templates, async runs, or services.
-- `Draft Recipe`: A reusable but non-registered recipe captured from a successful inline actor spawn under `~/.pi/agent/recipes/drafts`. It can be replayed by explicit file path and later promoted into the active tool recipe root after enough dogfood.
+- `Draft Recipe`: A reusable but non-registered recipe captured from a successful inline actor spawn under `~/.pi/agent/recipes/drafts`. It can be replayed by an explicit `.json` / `.md` path (relative entry paths use invocation `cwd`) and later promoted into the active tool Recipe root after enough dogfood.
 - `Coordinator Checkpoint`: A deliberate subagent pause where the subagent preserves its working context, sends a bounded question or status to the orchestrator, receives a coordinator reply, and continues in the same subagent context.
 - `Evidence Checkpoint`: A deliberate stop where a subagent records sources, assumptions, confidence, contradictions, or blocking evidence gaps before synthesis.
 - `Integrator`: The human or agent that merges isolated branches/worktrees into the shared target and owns conflict resolution.
@@ -162,7 +162,7 @@ Use [`references/development-swarm.md`](./references/development-swarm.md) for c
 
 Purpose: turn one result into many risk lenses and a decision-grade verdict.
 
-Use lens swarm for broad coverage, quorum for confidence on one critical judgement, or both for high-stakes releases. In adapters that expose current session model/thinking policy, default ordinary same-policy review swarms to that current policy and require explicit args only when intentionally varying models or thinking levels. Run a cheap model/tool preflight before launching expensive reviewer fanout; if it fails, use the `ACTOR_PREFLIGHT_FAILED` stage/model/error-class/prompt-file diagnostic to choose explicit override args instead of rerunning blindly. For packaged review swarms, tune `min_successful_reviewers`, `reviewer_concurrency`, `subagent_ttl_ms`, and `merge_policy` instead of manual reruns; preserve partial reports and label the outcome `complete`, `degraded`, or `insufficient_data`. The final report should separate consensus findings, minority findings, merger findings, risks, and recommended next actions.
+Use lens swarm for broad coverage, quorum for confidence on one critical judgement, or both for high-stakes releases. In adapters that expose current session model/thinking policy, default ordinary same-policy review swarms to that current policy and require explicit args only when intentionally varying models or thinking levels. Run a cheap model/tool preflight before launching expensive reviewer fanout; if it fails, use the `ACTOR_PREFLIGHT_FAILED` stage/model/error-class/prompt-file diagnostic to choose explicit override args instead of rerunning blindly. For Skill-owned review swarms, tune `min_successful_reviewers`, `reviewer_concurrency`, `subagent_ttl_ms`, and `merge_policy` instead of manual reruns; preserve partial reports and label the outcome `complete`, `degraded`, or `insufficient_data`. The final report should separate consensus findings, minority findings, merger findings, risks, and recommended next actions.
 
 A review swarm synthesis must not fabricate claims. Every final finding should trace to a reviewer note, checked artifact, command output, source, or explicit merger rationale. Devil's Advocate critical findings must be preserved or explicitly disproved with evidence.
 
@@ -345,7 +345,7 @@ Locks prevent subagents from interfering with shared scopes. Locks are optional
 
 ## Validation
 
-After changing Swarm adapter contracts or packaged documentation, validate the local distribution with whatever checks the host project provides. At minimum, review the text for boundary drift:
+After changing Swarm adapter contracts or Skill documentation, validate the local distribution with whatever checks the host project provides. At minimum, review the text for boundary drift:
 
 - no dependency on a specific extension, actor runtime, registry, recipe store, or CLI runner;
 - no bundled broad coordinator or lock runtime as portable Swarm core;

package/{recipes/pipeline-architect-coordinator.json → dist/skills/swarm/recipes/architect.json}

@@ -1,11 +1,11 @@
 {
   "async": true,
   "imports": {
-    "reviewer": "subagent-review.json",
-    "critic": "subagent-critic.json",
-    "verifier": "subagent-verify.json",
-    "merger": "subagent-merge.json",
-    "normalizer": "subagent-normalize.json"
+    "reviewer": "swarm/subagent-review",
+    "critic": "swarm/subagent-critic",
+    "verifier": "swarm/subagent-verify",
+    "merger": "swarm/subagent-merge",
+    "normalizer": "swarm/subagent-normalize"
   },
   "args": [
     "problem:string",

package/{recipes/pipeline-checkpoint-continuation.json → dist/skills/swarm/recipes/checkpoint-continuation.json}

@@ -1,9 +1,9 @@
 {
   "async": true,
   "imports": {
-    "checkpoint": "subagent-checkpoint.json",
-    "followup": "subagent-followup.json",
-    "normalizer": "subagent-normalize.json"
+    "checkpoint": "swarm/subagent-checkpoint",
+    "followup": "swarm/subagent-followup",
+    "normalizer": "swarm/subagent-normalize"
   },
   "args": [
     "state:string",

package/dist/{recipes/pipeline-development-tasking.json → skills/swarm/recipes/development-tasking.json}

@@ -1,10 +1,10 @@
 {
   "async": true,
   "imports": {
-    "planner": "subagent-plan.json",
-    "task_card": "subagent-task-card.json",
-    "critic": "subagent-critic.json",
-    "normalizer": "subagent-normalize.json"
+    "planner": "swarm/subagent-plan",
+    "task_card": "swarm/subagent-task-card",
+    "critic": "swarm/subagent-critic",
+    "normalizer": "swarm/subagent-normalize"
   },
   "args": [
     "goal:string",

package/dist/{recipes/lens-swarm.json → skills/swarm/recipes/lens-review.json}

@@ -2,7 +2,7 @@
   "description": "General-purpose multi-lens review swarm. Launches independent reviewers by lens, then verifies, merges, judges, and normalizes the result.",
   "async": true,
   "imports": {
-    "coordinator": "subagent-review-coordinator.json"
+    "coordinator": "swarm/subagent-review-coordinator"
   },
   "args": [
     "scope:string",

package/dist/{recipes/pipeline-quorum-review.json → skills/swarm/recipes/quorum-review.json}

@@ -1,10 +1,10 @@
 {
   "async": true,
   "imports": {
-    "subagent": "subagent-prompt.json",
-    "merger": "subagent-merge.json",
-    "judge": "subagent-judge.json",
-    "normalizer": "subagent-normalize.json"
+    "subagent": "swarm/subagent-prompt",
+    "merger": "swarm/subagent-merge",
+    "judge": "swarm/subagent-judge",
+    "normalizer": "swarm/subagent-normalize"
   },
   "args": [
     "prompt:string",

package/{recipes/pipeline-research-synthesis.json → dist/skills/swarm/recipes/research-synthesis.json}

@@ -1,12 +1,12 @@
 {
   "async": true,
   "imports": {
-    "planner": "subagent-plan.json",
-    "evidence": "subagent-evidence-map.json",
-    "contradictions": "subagent-contradiction-map.json",
-    "verifier": "subagent-verify.json",
-    "merger": "subagent-merge.json",
-    "normalizer": "subagent-normalize.json"
+    "planner": "swarm/subagent-plan",
+    "evidence": "swarm/subagent-evidence-map",
+    "contradictions": "swarm/subagent-contradiction-map",
+    "verifier": "swarm/subagent-verify",
+    "merger": "swarm/subagent-merge",
+    "normalizer": "swarm/subagent-normalize"
   },
   "args": [
     "question:string",

package/{recipes/pipeline-review-readiness.json → dist/skills/swarm/recipes/review-readiness.json}

@@ -1,7 +1,7 @@
 {
   "async": true,
   "imports": {
-    "coordinator": "subagent-review-coordinator.json"
+    "coordinator": "swarm/subagent-review-coordinator"
   },
   "args": [
     "scope:string",

package/{recipes/subagents-prompts.json → dist/skills/swarm/recipes/subagent-prompts.json}

@@ -1,7 +1,7 @@
 {
   "async": true,
   "imports": {
-    "subagent": "subagent-prompt.json"
+    "subagent": "swarm/subagent-prompt"
   },
   "args": [
     "prompts:array",

package/{recipes → dist/skills/swarm/recipes}/subagent-quorum.json

@@ -1,7 +1,7 @@
 {
   "async": true,
   "imports": {
-    "subagent": "subagent-prompt.json"
+    "subagent": "swarm/subagent-prompt"
   },
   "args": [
     "prompt:string",

package/dist/{recipes → skills/swarm/recipes}/subagent-review-coordinator.json

@@ -1,12 +1,12 @@
 {
   "async": true,
   "imports": {
-    "preflight": "subagent-preflight.json",
-    "reviewer": "subagent-review.json",
-    "verifier": "subagent-verify.json",
-    "merger": "subagent-merge.json",
-    "judge": "subagent-judge.json",
-    "normalizer": "subagent-normalize.json"
+    "preflight": "swarm/subagent-preflight",
+    "reviewer": "swarm/subagent-review",
+    "verifier": "swarm/subagent-verify",
+    "merger": "swarm/subagent-merge",
+    "judge": "swarm/subagent-judge",
+    "normalizer": "swarm/subagent-normalize"
   },
   "args": [
     "scope:string",

package/docs/actor-inspector.md

@@ -12,13 +12,14 @@ The Inspector follows the kernel directly. It shows Runs owned by the current Pi
 
 Shows captured execution provenance:
 
-- Recipe name and source path;
+- file-derived Recipe stem and logical reference;
+- source kind (`user_registry_capability`, `active_skill_component`, or `explicit_file_recipe`) and Skill identity when owned;
 - resolved template and values;
-- imports/context records;
+- root/import roles plus alias ancestry;
 - declared artifacts and actor-local actions;
 - model/thinking policy and launch source.
 
-Captured Recipe evidence belongs to the Run generation and does not change when an active Recipe file later changes. Non-empty object values render as indented brace-delimited property lists rather than flattened inline strings.
+Captured Recipe evidence belongs to the Run generation and does not change when an active Recipe file later changes. Skill components display logical identities such as `artifacts/report`; private physical `source_file`, `skill_dir`, and `recipe_dir` stay out of Inspector and model-facing views. Non-empty object values render as indented brace-delimited property lists rather than flattened inline strings.
 
 ## Trace
 

package/docs/async-runs.md

@@ -123,8 +123,8 @@ Archive and prune apply only to terminal Runs and enforce path containment. Rete
 
 Packaged controlled services demonstrate the endpoint protocol:
 
-- `music-player` consumes playback Controls and emits playback Trace;
-- `resource-locker` consumes queue/lease actions, emits lock Trace, and atomically retains at most 512 valid journal records within 1 MiB.
+- `media/player` consumes playback Controls and emits playback Trace;
+- `actors/resource-locker` consumes queue/lease actions, emits lock Trace, and atomically retains at most 512 valid journal records within 1 MiB.
 
 Shared archive/prune evidence similarly retains at most 256 valid records within 1 MiB under its canonical lock. The obsolete advisory `wake.jsonl` notifier was removed; filesystem watchers and bounded reconciliation observe authoritative state directly.
 

package/docs/recipe-library.md

@@ -1,43 +1,43 @@
-# Packaged Recipe Library
+# Skill-Owned Recipe Components
 
-Packaged Recipes provide maintained execution graphs and service definitions. User Recipes with the same name shadow packaged definitions; invalid shadowing fails closed.
+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
 
-- `pipeline-repo-health.json` — repository inspection and bounded health artifact.
-- `pipeline-docs-maintenance.json` — documentation analysis and artifact preparation.
-- `pipeline-release-readiness.json` — release checks and readiness artifact.
-- `pipeline-release-summary.json` — release-summary artifact.
-- `pipeline-development-tasking.json` — task-card and implementation planning pipeline.
+- `project-work/repo-health` — repository inspection and bounded health artifact.
+- `project-work/docs-maintenance` — documentation analysis and artifact preparation.
+- `project-work/release-readiness` — release checks and readiness artifact.
+- `project-work/release-summary` — release-summary artifact.
+- `swarm/development-tasking` — task-card and implementation planning pipeline.
 
 ### Review and synthesis
 
-- `pipeline-quorum-review.json` — parallel reviewers with quorum-oriented synthesis.
-- `pipeline-review-readiness.json` — review plus readiness stages.
-- `pipeline-research-synthesis.json` — evidence-oriented research synthesis.
-- `lens-swarm.json` — configurable repeated review lenses.
-- `subagent-review-coordinator.json` — lower-level review/verify/merge/judge composition.
+- `swarm/quorum-review` — parallel reviewers with quorum-oriented synthesis.
+- `swarm/review-readiness` — review plus readiness stages.
+- `swarm/research-synthesis` — evidence-oriented research synthesis.
+- `swarm/lens-review` — configurable repeated review lenses.
+- `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
 
-- `pipeline-artifact-report.json` — prepare one artifact body.
-- `pipeline-artifact-write.json` — prepare and deterministically write an artifact.
-- `pipeline-artifact-bundle.json` — optional validation, artifact write, manifest generation, and manifest write.
-- `utility-artifact-write.json` — deterministic create/overwrite/append helper.
-- `utility-artifact-manifest.json` — artifact manifest generation.
+- `artifacts/report` — prepare one artifact body.
+- `artifacts/write` — prepare and deterministically write an artifact.
+- `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.
 
 ### Controlled services
 
-- `music-player.json` — playback service with declared playback actions, `controls.jsonl`, generation-fenced endpoint readiness, state artifact, and playback Trace. Player selection is `player:enum(auto,mpv,afplay,ffplay,cvlc,play,wmp)=auto`.
-- `resource-locker.json` — optional queue/lease-lock service with explicit owner/resource input, lock Trace, and a 512-record/1 MiB atomically retained journal.
+- `media/player` — playback service with declared playback actions, `controls.jsonl`, generation-fenced endpoint readiness, state artifact, and playback Trace. Player selection is `player:enum(auto,mpv,afplay,ffplay,cvlc,play,wmp)=auto`.
+- `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 are the packaged Recipes that declare actor-local Control. Ordinary one-shot Recipes omit it. Helper-backed packaged Recipes self-locate their installed package root when `repo` is omitted; an explicit caller value still wins for development or custom layouts.
+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
 
@@ -45,7 +45,7 @@ Subagent components provide reusable command-template cells for normalization, p
 
 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.
 
-Packaged components can be selected exactly as `std:<recipe-name>`. Recipes bundled under a Pi-active Skill are selected as `skill:<skill-name>/<recipe-path>` and receive runtime-owned `{skill_dir}` plus `{recipe_dir}`. Active Skill components are namespaced library entries, never automatic tools; expose one intentionally through a user Recipe wrapper when a direct tool is desired.
+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
 
@@ -70,7 +70,7 @@ Use utilities as imported cells or registered tools where their contract fits.
 
 ## Installation Safety
 
-Do not bulk-copy `recipes/*.json` into the user Recipe root. Internal `draft-review.json` and `tool-review.json` support fenced automatic review and must not become user-installed callable tools. Register or wrap only the specific public capability you intend to use.
+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
 
@@ -78,7 +78,7 @@ Do not bulk-copy `recipes/*.json` into the user Recipe root. Internal `draft-rev
 npm run recipes:qa
 ```
 
-Recipe QA validates syntax, imports, Control declarations, artifact paths, helper references, and platform documentation. Recipe descriptions are optional because discovery supplies stable fallback tool copy; internal component Recipes do not need boilerplate. The packaged baseline requires zero diagnostics and zero warnings, and any future warning is release-blocking with its concrete file and repair. Removed mailbox declarations fail with the migration diagnostic rather than receiving automatic conversion.
+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
 

package/docs/releasing.md

@@ -1,6 +1,6 @@
 # Release Operations
 
-Stable releases use one immutable tag workflow. The workflow runs the complete reusable Ubuntu, macOS, Windows, and dependency-audit boundary 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.
+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
 
@@ -19,7 +19,7 @@ Do not create `NPM_TOKEN`, `NODE_AUTH_TOKEN`, or another long-lived npm publish
 
 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 complete reusable validation workflow.
+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.

package/docs/template-recipes.md

@@ -10,7 +10,7 @@ A Recipe stores a reusable command-template definition as JSON or Markdown.
   "description": "Create a repository health artifact",
   "args": ["repo:path", "artifact_path:path", "model:string"],
   "defaults": { "artifact_path": "{state_dir}/health.md" },
-  "imports": { "review": "subagent-review.json" },
+  "imports": { "review": "swarm/quorum-review" },
   "artifacts": { "report": "{artifact_path}" },
   "template": {
     "name": "review",
@@ -39,11 +39,13 @@ 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:
 
-- `name`, `description`, `disabled`;
+- `description`, `disabled`;
 - `args`, typed arg declarations, inline defaults, `defaults`, and composition `values`;
 - `imports` with optional binding defaults/values;
 - `template`;
@@ -58,25 +60,39 @@ Common Recipe fields:
 ```json
 {
   "imports": {
-    "review": "subagent-review.json",
-    "verify": {
-      "from": "subagent-verify.json",
+    "review": "swarm/quorum-review",
+    "report": {
+      "from": "../shared/report.md",
       "defaults": { "thinking": "medium" }
     }
   },
   "template": [
     { "name": "review", "values": { "input": "{input}" } },
-    { "name": "verify", "values": { "input": "Use prior output" } }
+    { "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.
 
-Bare references preserve user → adjacent → packaged resolution. `std:<name>` selects a packaged Recipe exactly. `skill:<skill-name>/<recipe-path>` selects a component under the `recipes/` tree of a Skill currently active through Pi resource discovery. Skill Recipes never become tools merely by existing, and duplicate active Skill names fail as ambiguous rather than shadowing silently.
+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.
+
 ## Control
 
 Only a process that consumes actor-local input declares actions:
@@ -85,7 +101,7 @@ Only a process that consumes actor-local input declares actions:
 {
   "async": true,
   "control": ["pause", "resume", "stop"],
-  "template": "{repo}/scripts/service.mjs --state-dir {state_dir}"
+  "template": "{skill_dir}/scripts/service.mjs --state-dir {state_dir}"
 }
 ```
 
@@ -110,7 +126,7 @@ Every file-backed Recipe receives immutable `{recipe_dir}`. A Recipe under an ac
 
 ## Context and Provenance
 
-File-backed Runs capture Recipe context records for the entry and imports, including qualified `std:` or `skill:` identity when applicable. 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.
+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.
 
@@ -129,18 +145,20 @@ Defaults can inherit current Pi policy:
 
 Resolution fails before launch when required current policy is unavailable. The Run persists whether values were inherited or explicit.
 
-## Resolution and Shadowing
+## 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.
 
-User Recipes under `~/.pi/agent/recipes` take priority over adjacent and packaged Recipes for compatible bare lookup. Exact `std:` and `skill:` references bypass that ambiguous space. The active Skill namespace converges from Pi's loaded Skill metadata on startup/reload; pi-actors does not scan ambient Skill roots independently. An invalid active file blocks fallback and reports both paths. 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 scripts/validate-recipe.mjs recipes/example.json --qa
-node scripts/validate-recipe.mjs recipes --all --qa --summary
+node skills/actors/scripts/validate-recipe.mjs path/to/recipe.json --qa
+node skills/actors/scripts/validate-recipe.mjs skills --skills --qa --summary
 ```
 
-Validation checks JSON/Markdown compilation, imports, Control, artifacts, helper paths, and platform notes. Files exceed 1 MiB or import depth 32 fail closed.
+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
 

package/docs/tool-registry.md

@@ -6,7 +6,7 @@
 ~/.pi/agent/recipes/*.json
 ```
 
-Each active valid Recipe becomes an agent-callable tool. `register_tool` creates, updates, promotes, or deletes these files through fenced mutation paths.
+Each valid Recipe admitted against the current session context can become an agent-callable tool. `register_tool` creates, updates, promotes, or deletes these files through fenced mutation paths and reports the resulting activation state.
 
 ## Registration
 
@@ -20,9 +20,13 @@ Register a typed/defaulted template or Recipe-backed definition when reuse justi
 
 Promote an immutable captured draft only with its draft path and explicit target name. Name collisions require `update=true`. Invalid content fails before active mutation.
 
+Registration resolves the effective delegated contract before persistence, then reports distinct `persisted`, `registry_active`, `host_registered`, `active_tool`, and `callable_now` states. Treat the tool as callable in the current session only when `callable_now` is true; persistence alone is not activation proof.
+
 ## Resolution
 
-User Recipes take priority over packaged Recipes. Active invalid or disabled shadowing blocks fallback and reports both paths. Runtime reload watches the Recipe root and converges after atomic changes; stale watcher generations cannot replace current registration state.
+User Recipes are the only file-discovered tool source. Invalid or disabled user entries fail closed. Active Skill Recipes remain exact components outside tool discovery. Spawn, registration, registry admission, schema derivation, and live inspection resolve against one immutable session context containing the current working directory and active Skills. Runtime reload watches the user Recipe root using that current context and converges after atomic changes; stale watcher generations cannot replace current registration state.
+
+Skill component inventory is diagnostic and fail-soft: valid components remain listed and exactly resolvable when an unrelated component is rejected. Recipe inspection reports rejected components and marks the catalog partial instead of treating one bad component as an empty catalog.
 
 Inspect registry state with:
 
@@ -31,7 +35,9 @@ inspect target=recipes view=status
 inspect target=tool:<name> view=status
 ```
 
-Recipe inspection reports active, shadowed, invalid, disabled, diagnostic, risk, usage, and review evidence. Tool inspection reports the current capability definition/schema; a registered tool is not a running actor.
+Recipe inspection reports generation, scan/watch state, active, shadowed, invalid, disabled, component rejection, diagnostic, risk, usage, and review evidence. Tool status reports current activation plus separate `tool_calls` and `spawn_calls`; tool schema reports the caller-owned capability contract. A registered tool is not a running actor.
+
+`spawn recipe=<name>` executes a Recipe and reports `launch_kind: "spawn"`; it does not prove that a registered tool was exposed or invoked. Registered-tool execution reports `launch_kind: "tool"`.
 
 ## Automatic Review
 
@@ -61,7 +67,7 @@ Usage and lineage live in locked metadata ledgers rather than authored Recipe fi
 
 ## Wrapping Existing Recipes
 
-Prefer a small user-root wrapper that imports a maintained Recipe by exact `std:<recipe>` or `skill:<skill>/<recipe-path>` identity and delegates by alias. Skill Recipes remain components and are never exposed merely because their Skill is active. Do not duplicate executable templates, defaults, Control declarations, artifacts, or runtime-owned `{recipe_dir}`/`{skill_dir}`. Install only specific capabilities; internal automatic-review Recipes must not become user-callable tools.
+Prefer a small user-root wrapper that imports a maintained Recipe by exact `<skill>/<recipe>` identity and delegates by alias. Skill Recipes remain components and are never exposed merely because their Skill is active. Do not duplicate executable templates, defaults, Control declarations, artifacts, or runtime-owned `{recipe_dir}`/`{skill_dir}`. Install only specific capabilities; internal automatic-review Recipes must not become user-callable tools.
 
 ## Safety