@signalridge/pi-workflows 1.3.2 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,145 @@
 # Changelog
 
+## 1.5.0
+### Minor Changes
+
+- c1b1741: Protocol v4: workflows use the Agent-tier catalogue directly.
+  
+  The wire contract changes, so the three packages move together: `pi-workflows`
+  now declares `"@signalridge/pi-subagents": ">=1.9.0"`, and a peer outside that
+  range fails the startup handshake with a diagnostic naming both packages rather
+  than failing mid-run.
+  
+  The `small | medium | large` workflow-tier vocabulary and its mapping layer are
+  gone. A managed request names an Agent tier — a key in the host's own
+  `agentTiers` catalogue — and `resolveAgentTier()` is the single resolver for
+  every spawn path. Removed with it: the wire's mapped `agentTier` field, the
+  `workflow` settings key (retired with a warning naming it; `agentTiers.defaultTier`
+  replaces `workflow.defaultTier`), and the per-call `model`/`thinking` selectors,
+  which the validator now rejects rather than accepting and ignoring.
+  
+  Every v4 capability is required and every ping carries the host's tier catalogue,
+  so an incomplete peer fails one check instead of five optional ones. Fresh
+  installs ship `low`/`medium`/`high` profiles, all inheriting their model, and a
+  managed call that names no tier falls back to `medium`, so a workflow runs on an
+  unconfigured machine without this package choosing a vendor. Because `medium`
+  inherits, that fallback lands on the parent session's model — it commits to an
+  effort level, not to a vendor, so it does change the thinking level a managed
+  call runs at when the parent session is set higher, and it does not move the
+  work anywhere cheaper. What it buys is a named policy with a durable snapshot
+  and a scope check; a workspace that wants cheaper managed work names a
+  `defaultTier` whose profile pins a model. The fallback is scoped to calls that
+  cannot inherit a parent model rather than being installed as
+  `agentTiers.defaultTier`: a shipped catalogue default would have applied to
+  every ordinary `Agent` spawn as well, silencing `defaultModel` and pinning a
+  thinking level on machines that configured neither. The catalogue no longer
+  ships a `fast` profile; it was the same (model, thinking) pair as `low`, and the
+  one agent that named it (Explore) now names `low`. A user agent file that still
+  says `agentTier: fast` is reported by the existing unknown-reference check when
+  settings and agents load, rather than failing at its first spawn.
+  
+  `agentTiers.defaultTier` therefore has three states, and `/agents → Settings`
+  offers all three rather than rendering two of them as one word: a named tier,
+  `unset` (managed calls reach the shipped fallback), and `none` (recorded as
+  `noDefaultTier`, which withdraws the fallback so managed calls fail closed).
+  `setDefaultAgentTier` takes that choice as a tagged value, so a caller cannot
+  express "no default" without saying which of the two it means.
+  
+  `resolveAgentTier` gained `requireTier` for that fallback, and the two things
+  pre-resolution callers need are both answered by the resolver rather than
+  restated beside it: `agentTierApplies()` for "will a tier own this spawn's
+  model?", and `selectAgentTier()` for the tier key itself, which the managed
+  path needs to label a tombstone and the lifecycle events before the runner has
+  resolved anything.
+  
+  Because a tier now owns model resolution outright, the spawn paths stop
+  pre-resolving one — and with it they stopped producing the model name the agent
+  UI shows. The resolution callback carries that label back instead, so a tier
+  that pins a model still names it in the viewer and the agent list, and a profile
+  that inherits correctly shows none. The label rides beside the snapshot rather
+  than inside it: the snapshot is a durable policy record a managed tombstone
+  persists and revalidates, and a cosmetic string does not belong in it.
+  
+  Workflow resume now keys each cached call on the policy for that call's own tier
+  rather than on a whole-catalogue fingerprint, so defining or editing an unrelated
+  tier no longer forces a full re-execution — but only for a call that names its
+  tier. A call that names none keeps the whole-catalogue key, because the host
+  resolves those as `call > agent frontmatter > defaultTier` and frontmatter is
+  not on this wire: an agent reaches a managed caller as a name. Keyed on
+  `defaultTier`, such a call would be wrong twice over — replaying stale work
+  after an edit to the tier its agent actually declares, and re-executing after an
+  edit to a default it never reached. `agentTierPolicyIdentity()` therefore
+  requires a tier rather than accepting `undefined` and folding the default in, so
+  the wrong call cannot be written. Journal schema v4 and managed tombstone schema
+  v2 are quarantined from older facts rather than migrated.
+  
+  The tier catalogue belongs to the user, names included. The built-in workflows
+  and the ad-hoc script ship with this package, so a tier name they use that the
+  host does not define is dropped in favour of the host's default rather than
+  failing the run — they cannot assert which names exist on someone else's
+  machine. A script the user wrote still fails closed on an undefined tier, since
+  that is a typo in a catalogue they own. Shipped-ness travels with the script
+  rather than with the frame that called it, so a user script that reaches a
+  built-in through `workflow(name)` applies the built-in's rule to the built-in;
+  the authoring skill now says outright that `low`/`medium`/`high` are the shipped
+  profiles rather than names an authored script may assume.
+  
+  The managed routing policy published on the wire reports the default a managed
+  call will actually get, fallback included, so a peer's replay identity cannot
+  disagree with the host's selection; its sorts are code-unit rather than
+  locale-dependent, so the same catalogue fingerprints identically everywhere. The
+  workflow peer re-pings per start and resume instead of pinning the catalogue it
+  saw at session start, and reports the host-selected tier back through an
+  `onTierResolved` callback rather than by mutating the dispatch options.
+  
+  Fixes: a nested spawn no longer relabels an agent's frontmatter tier as
+  caller-requested, which had turned a `scopeModels` warning into a refusal and
+  misattributed the choice; the scheduler no longer freezes a frontmatter tier into
+  a job, so editing the agent file takes effect at fire time; retired managed spawn
+  keys are now bounded instead of growing for the life of a session; a
+  scope refusal for a tier whose profile inherits its model now names the model
+  that would have run instead of the literal `undefined`; and the retired
+  `workflow` key warns once per process rather than on every settings read and
+  every project write.
+  
+  The tier-key predicate and its length bound now have a single definition, in
+  `pi-subagents-protocol`, which `pi-subagents` re-exports. The wire is the
+  narrower of the two gates — a key one accepted and the other rejected could
+  never reach a peer — so a second copy could only ever be a way for them to
+  disagree. That one definition now also governs `blockedProfiles`, which was
+  being validated by a helper that trims first: `" low"` became `"low"` there
+  while the same value in `profiles` or `defaultTier` was refused outright. All
+  three reject.
+  
+  `/agents → Settings` no longer names the fallback tier in the `unset` row's
+  label. Which tier `unset` reaches depends on the catalogue, and a workspace that
+  edits or deletes the shipped `medium` profile leaves it reaching nothing — at
+  which point `unset` and `none` behave identically. The row's description asks
+  the resolver what `unset` would currently resolve to and says that, including
+  when the answer is "nothing".
+  
+  `pi-workflows` also gained the session-lifecycle handling this routing work
+  needed to sit on. The engine has an explicit dispose lifecycle, so a protocol
+  probe or a start that is in flight when a session ends rejects with a disposed
+  error instead of resolving against an engine nobody owns. The tool, command and
+  widget surfaces register exactly once and resolve the *current* engine on each
+  use, rather than closing over the one that existed when they were registered —
+  a session replacement previously left them pointing at a disposed engine. Tool
+  and command handlers report failures as results rather than throwing out of the
+  host's dispatch, and the lifecycle handler accepts `subagents:created` and
+  `subagents:started` so a spawn's identity is recorded from the first event that
+  carries it rather than only at completion.
+
+### Patch Changes
+
+- Updated dependencies [c1b1741]
+  - @signalridge/pi-subagents-protocol@1.4.0
+
+## 1.4.0
+### Minor Changes
+
+- 28c8aa1: Strengthen script orchestration with deterministic named dependency graphs, bounded task retries and failure policies, safer fan-out barriers, durable nested-workflow replay, and reliable pause/resume accounting. The natural-language `/workflows run` path now plans, executes, and synthesizes a bounded task graph, while expanded authoring/pattern guidance and the new `workflow-review` skill make routing, recovery, and publication constraints explicit.
+
 ## 1.3.2
 ### Patch Changes
 

package/README.md

@@ -2,7 +2,7 @@
 
 JavaScript orchestration for Pi. A workflow is a raw JavaScript module executed
 in a determinism-guarded `node:vm` realm; the runtime supplies `agent()`,
-`parallel()`, `pipeline()`, `workflow()`, quality helpers (`verify`,
+`parallel()`, `pipeline()`, `orchestrate()`, `workflow()`, quality helpers (`verify`,
 `judgePanel`, `loopUntilDry`, `completenessCheck`, `retry`, `gate`), human
 `checkpoint()`, `phase()`, `log()`, `args`, `cwd`, restricted `process`, and
 `budget`. Every live `agent()` call is dispatched through the additive
@@ -12,8 +12,8 @@ isolation, retry, and session policy.
 
 ## Install
 
-`@signalridge/pi-workflows` requires `@signalridge/pi-subagents` `>=1.5.0`
-with protocol v3 managed-spawn, workflow-tier, and managed-policy support. They are separate Pi packages: the peer
+`@signalridge/pi-workflows` requires `@signalridge/pi-subagents` `>=1.9.0`
+with protocol v4 managed-spawn, Agent-tier, and managed-policy support. They are separate Pi packages: the peer
 dependency documents the requirement but intentionally does not auto-load or
 duplicate the subagent extension.
 
@@ -54,9 +54,9 @@ export const meta = {
 
 phase("scan");
 const findings = await parallel([
-  () => agent("Check for cross-package imports", { label: "imports", tier: "small" }),
-  () => agent("Check for secrets", { label: "secrets", tier: "small" }),
-  () => agent("Check for dead code", { label: "dead-code", tier: "small" }),
+  () => agent("Check for cross-package imports", { label: "imports", tier: "low" }),
+  () => agent("Check for secrets", { label: "secrets", tier: "low" }),
+  () => agent("Check for dead code", { label: "dead-code", tier: "low" }),
 ]);
 
 phase("synthesize");
@@ -69,29 +69,42 @@ return report;
 The meta statement must be the first statement and use only literals — spread,
 computed keys, methods, template interpolation, and the reserved keys
 `__proto__`/`constructor`/`prototype` are rejected. `Date.now()`,
-`Math.random()`, and no-argument `new Date()` are unavailable (a regex precheck
-plus in-realm stubs); pass timestamps and randomness through `args`. The vm is
+`Math.random()`, and no-argument `new Date()` are unavailable (an AST precheck
+plus in-realm stubs); prompt text containing those words remains valid. Pass
+timestamps and randomness through `args`. The vm is
 a determinism guardrail, not a security boundary — scripts are generated by the
 user's own LLM and run on the user's own machine.
 
 ### Runtime globals
 
-- `agent(prompt, { label, phase, schema, model, tier, isolation, thread, agentType, toolset, excludeTools, timeoutMs, retries })`
+- `agent(prompt, { label, phase, schema, tier, isolation, thread, agentType, toolset, excludeTools, timeoutMs, retries })`
   — dispatch one subagent through the managed spawn protocol. Returns text, a
-  schema-validated value, or recoverable `null` after retries. `schema` is a
+  schema-validated value, or recoverable `null` after retries. Replayed journal
+  calls consume no real-dispatch cap or token/phase budget. `schema` is a
   plain JSON Schema; the reply is parsed and validated client-side with bounded
   repair across attempts, and exhaustion throws `SCHEMA_NONCOMPLIANCE`.
-  Explicit `model` and `isolation: "worktree"` are resolved and enforced by pi-subagents; `tier` remains the provider-neutral route.
-  `tier`; see "Model routing"). `thread` chains sequential turns within a named
-  conversation thread.
+  `tier` is the provider-neutral workflow route; `thread` chains sequential turns
+  within a named conversation thread. A legacy programmatic `model` option may
+  still be accepted by non-managed callers, but workflow meta/phase model or
+  thinking fields are rejected and are never a workflow policy source. Pre-schema-v4
+  journal runs are quarantined and cannot be resumed.
 - `parallel(thunks)` — run thunks concurrently, preserve input order. Recoverable
   thunk failures become `null`; non-recoverable failures (token budget, agent
-  limit) halt the run. Fan-out that breaches `maxAgents` cancels only its own
-  batch.
+  limit) halt the run after the batch barrier settles. Fan-out that breaches
+  `maxAgents` cancels only its own batch; each call accepts at most 4096 thunks.
 - `pipeline(items, ...stages)` — items run concurrently, stages per item run
-  sequentially with `(previousValue, originalItem, index)`.
+  sequentially with `(previousValue, originalItem, index)`; each call accepts at
+  most 4096 items and waits for the batch before surfacing fatal failures.
+- `orchestrate(tasks, { onError })` — execute a named dependency graph in
+  deterministic declaration-order layers. Each task is `{ id, dependsOn?, phase?,
+  retries?, run }`; its callback receives `{ id, attempt, results, statuses }`.
+  `onError` is `skip-dependents` (default), `continue`, or `fail-fast`. Results
+  are keyed by task id, and task lifecycle events are observable through
+  `onRuntimeEvent`.
 - `workflow(savedName, childArgs?)` — run a saved workflow inline; one nested
-  level, sharing the limiter, counters, token accounting, and store.
+  level, sharing the limiter, counters, token accounting, and store. The child
+  result is journaled as one parent call with a generation-scoped namespace, so
+  unchanged nested work replays without spawning again after resume.
 - `verify(item, { reviewers, threshold, lens })`, `judgePanel(attempts,
   { judges, rubric })`, `loopUntilDry({ round, key, consecutiveEmpty,
   maxRounds })`, `completenessCheck(taskArgs, results)`, `retry(thunk,
@@ -107,17 +120,35 @@ user's own LLM and run on the user's own machine.
 ### Resume
 
 A script edit replays the longest unchanged prefix from the journal and runs
-live from the first changed or inserted `agent()`/`checkpoint()` call. Pass
-`resumeFromRunId` with the edited script; unchanged calls report zero tokens,
+live from the first changed or inserted `agent()`/`checkpoint()` call. The
+original invocation `args` and execution limits are frozen and reused on manual
+or automatic resume. Pass `resumeFromRunId` with the edited script; unchanged
+calls report zero tokens,
 and edited calls rotate their managed spawn key generation so pi-subagents
 never raises a fingerprint conflict.
 
+## Skills
+
+The package ships three model-routable skills:
+
+- `workflow-authoring` — design, review, and debug custom JavaScript workflows;
+  it teaches topology selection, stable work IDs, bounded failure handling, and
+  resume-safe authoring.
+- `workflow-patterns` — choose and invoke a reviewed built-in for research,
+  adversarial review, code review, multi-perspective analysis, or codebase audit.
+- `workflow-review` — audit an existing workflow for topology, data flow,
+  recovery, resume safety, and publication readiness without editing it.
+
+Use the pattern skill for a standard task, the authoring skill for a custom
+workflow, and the review skill before accepting a topology or recovery change.
+
 ## Tools and commands
 
 - `workflow`: run a script (`script`) or a saved/built-in workflow (`name`),
   with `args`, `background` (default true), `maxAgents`, `concurrency`,
   `agentRetries`, `tokenBudget`, `agentTimeoutMs`, and `resumeFromRunId`.
 - `workflow_control`: `list`, `get`, `pause`, `resume`, `stop`, or `rm` a run; `rm` writes a durable removal tombstone.
+- `pi.events` emits `pi-workflows:runtime` snapshots (`{ runId, event }`) for phase, task, quality, retry, and nested-workflow progress; observer failures are contained.
 - `/workflows`: TUI navigator plus `run`, `status`, `watch`, `stop`, `pause`,
   `resume`, `rm`, and `save <name> [runId]` subcommands.
 - `/workflows-models`: points at pi-subagents' `/agents → Model tiers` — there
@@ -155,12 +186,52 @@ written atomically with a backup.
 
 ## Model routing
 
-The managed protocol carries semantic tiers plus optional exact model/thinking, toolset, denylist, thread, and worktree requests. pi-subagents resolves model references, validates scope, creates/cleans worktrees, and owns tool/session policy. Workflows fail closed with a diagnostic when the peer does not advertise managed-policy support; explicit selectors otherwise fail closed when unavailable, and workflows never bypass the companion's policy.
+`tier` names a key in the host's own `agentTiers` catalogue — the same catalogue an
+ordinary `Agent` call uses. There is no separate workflow-tier vocabulary and no
+mapping layer: a workflow that wants cheap work asks for the tier the user defined
+for cheap work.
+
+```js
+await agent("summarize this diff", { tier: "low" })
+await agent("design the migration", { tier: "high" })
+```
+
+The host's catalogue arrives with the protocol handshake, so a tier this host does
+not define is rejected before any dispatch, naming the ones it does. Resolution
+itself is entirely pi-subagents' `resolveAgentTier()`: it owns the final model,
+thinking level, clamping, availability checks, and the immutable resolution
+snapshot.
+
+The catalogue belongs to whoever runs the workflow — the names included. The
+built-in workflows and the ad-hoc script ship with this package, so they cannot
+assert that `low` exists on a machine whose tiers are called `cheap` and `deep`:
+a name they use that the host does not define is dropped, with a log line, and
+the host's own default applies. A script you wrote names tiers from your own
+catalogue, so an undefined one there is a typo and fails closed instead.
+
+There is no per-call `model` or `thinking`, and `meta`/phase metadata may not carry
+them either — both are rejected explicitly rather than accepted and ignored. A tier
+is the only model policy a workflow can express, which is what keeps a script from
+pinning a vendor the host did not choose.
+
+Omitting `tier` uses the agent's own tier, then `agentTiers.defaultTier`. Fresh
+installs ship `low`/`medium`/`high` profiles, all inheriting their model, and a
+managed call that still names no tier falls back to `medium` — so the built-ins run
+on a new machine without any configuration. That fallback is scoped to managed
+calls: it is not the catalogue's `defaultTier`, so an ordinary `Agent` spawn on the
+same machine keeps falling through to `defaultModel` and the parent session. A host
+whose default has been cleared (`noDefaultTier`) rejects an untiered managed call
+rather than quietly inheriting the parent session's model.
+
+The managed wire, invocation record, journal, tombstone, and resume state all carry
+the one resolved tier — including one the host defaulted to, so a run's record says
+what actually ran. Resume keys each cached call on the policy for *that call's*
+tier: editing an unrelated tier does not invalidate work that never used it.
 
 ## Intentional adaptations from upstream
 
 - **No host-side web tools.** Agents reach the web through configured pi-web-access/MCP tools or an agent type's tool policy.
-- **Agent registry and tier catalogue ownership.** `agentType` and `small|medium|large` profiles resolve in pi-subagents, avoiding a second registry/config schema.
+- **Agent registry and tier catalogue ownership.** `agentType` and the tier catalogue resolve in pi-subagents; the workflow package supplies only a tier key, avoiding a second model/thinking policy.
 - **Schema validation is client-side.** The managed request does not assume a structured-output tool; the runtime asks for JSON, parses, validates (including `additionalProperties`), and repairs across bounded attempts.
 
-State is persisted as `pi.appendEntry("pi-workflows:journal", ...)` custom entries (schema v3), including script revisions and durable removals. Interrupted/provider-limited runs replay from the journal; schema-v2 declarative journals are quarantined rather than replayed. Foreground `AbortSignal`s stop owned children through explicit owner-scoped stop/quiescence, and dispose/branch replacement reject stale waiters.
+State is persisted as `pi.appendEntry("pi-workflows:journal", ...)` custom entries (schema v4), including frozen invocation args, resolved tier identity, terminal result previews, script revisions, named nested-workflow result boundaries, and durable removals. Interrupted/provider-limited runs replay from the journal; pre-schema-v4 journals are quarantined rather than replayed. Foreground `AbortSignal`s stop owned children through explicit owner-scoped stop/quiescence, and dispose/branch replacement reject stale waiters.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-workflows",
-  "version": "1.3.2",
+  "version": "1.5.0",
   "description": "Deterministic JavaScript orchestration workflows backed by pi-subagents managed spawning.",
   "type": "module",
   "license": "MIT",
@@ -17,10 +17,10 @@
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.0",
     "@earendil-works/pi-tui": "^0.84.0",
-    "@signalridge/pi-subagents": ">=1.5.0"
+    "@signalridge/pi-subagents": ">=1.9.0"
   },
   "dependencies": {
-    "@signalridge/pi-subagents-protocol": "^1.3.0",
+    "@signalridge/pi-subagents-protocol": "^1.4.0",
     "@sinclair/typebox": "^0.34.50",
     "acorn": "^8.16.0"
   },
@@ -30,7 +30,8 @@
     ],
     "skills": [
       "skills/workflow-authoring",
-      "skills/workflow-patterns"
+      "skills/workflow-patterns",
+      "skills/workflow-review"
     ]
   },
   "repository": {

package/skills/workflow-authoring/SKILL.md

@@ -1,30 +1,183 @@
 ---
 name: workflow-authoring
-description: Guidance for writing, editing, reviewing, and debugging JavaScript workflow code for @signalridge/pi-workflows. Use when authoring or changing workflow scripts; not for merely running an existing workflow.
+description: Design, write, review, and debug Pi JavaScript workflows that coordinate multiple subagents. Use when a request needs named dependencies, bounded fan-out, per-item pipelines, quality gates, saved or nested workflows, pause/resume, or workflow progress; do not use it merely to run an existing named workflow.
 metadata:
-  version: "1.2.1"
+  version: "1.5.0"
 ---
 
 # Workflow authoring
 
-Load this skill when workflow JavaScript changes. Running an existing workflow needs no authoring reference.
+A workflow is a small program that coordinates subagents; it is not a long prompt
+that asks one agent to do every step. Keep semantic work in agents and keep
+identity, ordering, bounds, failure handling, and aggregation deterministic in
+JavaScript.
 
-## Choose a branch
+## Operating contract
 
-Read only what the task needs:
+- Use a workflow only when the task benefits from multiple agents, explicit
+  stages, independent coverage, or a quality/recovery loop. One or two simple
+  delegations should use the ordinary agent surface.
+- Start every script with literal `export const meta = { name, description,
+  phases? }`. Return plain JSON data explicitly.
+- Use `orchestrate()` for named dependencies, `parallel()` for a small
+  independent barrier, and `pipeline()` for independent items that each need a
+  sequential stage chain. Do not encode a dependency graph only in comments.
+- Give every work unit a stable ID and every agent call a short unique label.
+  Keep IDs beside results before filtering; `null` is missing coverage, not a
+  successful finding.
+- Bound graph tasks, fan-out items, loops, retries, agents, concurrency, and
+  evidence size. Invocation-level token and time caps are user constraints, not
+  substitutes for algorithmic bounds.
+- Route an agent call with `tier: "<key>"`, naming a tier the destination host
+  defines. Omitting `tier` uses the agent's own tier, then the host's configured
+  default; a host whose default has been cleared rejects the call rather than
+  inheriting the parent model. There is no per-call `model`/`thinking`, and
+  neither may appear in workflow meta or phase profiles. Never guess a tier or
+  agent-type name—use names supplied by the current environment and follow
+  [registry ownership](references/registry-ownership.md).
+- Workflows have no imports, filesystem/network APIs, timers, or unrestricted
+  Node APIs. Pass timestamps, randomness, and external decisions through `args`.
 
-- **Write or edit:** start with [runtime](references/runtime.md). Add [pattern selection](references/pattern-selection.md) for topology, [lifecycle](references/lifecycle.md) for limits or resume, and [focused recipes](references/focused-recipes.md) for the matching concern.
-- **Helper task:** read [quality helpers](references/quality-helpers.md) only for `verify` or `judgePanel`, the [retry helper](references/retry-helper.md) only for `retry`, and [specialized helpers](references/specialized-helpers.md) only for `completenessCheck`, `loopUntilDry`, `gate`, or `checkpoint`.
-- **Review:** use the [review checklist](references/review.md), plus only the matching [quality](references/quality-helpers.md) or [specialized](references/specialized-helpers.md) helper contracts.
-- **Debug:** use the [debugging map](references/debugging.md).
-- **Routing:** read [registry ownership](references/registry-ownership.md) before using `model`, `tier`, phase models, or `agentType`; use environment-specific names only when context supplies them.
-- **Exact lookup or portability:** start with the generated [capability index](references/capabilities.md). Follow its exhaustive-facts pointer only for constraints or support boundaries. Use [versions](references/versions.md) when moving scripts between installations.
+## The authoring pass
 
-## Invariants
+1. **Classify the topology.** Decide whether the work is direct, a named DAG,
+   homogeneous fan-out, a per-item pipeline, iterative discovery, or a quality
+   gate. Read [pattern selection](references/pattern-selection.md) only for the
+   chosen shape.
+2. **Declare inputs and bounds.** Read `args` once, normalize the input, reject
+   or cap untrusted cardinality, and decide what incomplete coverage means.
+3. **Write the envelope.** Declare only phases that are actually entered. Use
+   `phase(title, { budget })` for a soft token sub-budget, not as a scheduler.
+4. **Build the smallest work ledger.** Store `{ id, status, result, error }`
+   (or an equivalent object) for each intended unit. Do not lose identity when
+   applying `.filter(Boolean)`.
+5. **Dispatch with the right primitive.** Await every batch. For a dependent
+   prompt, include both the dependency ID and its actual result; do not assume
+   the child can see the parent conversation.
+6. **Add quality only where it changes a decision.** Use a schema before reading
+   structured fields, then use `verify`, `judgePanel`, `gate`, or
+   `completenessCheck` with explicit bounds.
+7. **Aggregate and report.** Return a bounded JSON result containing the answer,
+   coverage, and important failures. If the workflow runs in the background,
+   the run ID is the handle for later control/resume.
+8. **Review the script.** Use [the review checklist](references/review.md), then
+   test with deterministic fake agents when changing topology or recovery.
 
-- Start with literal `export const meta = { name, description }`; declare phases as an array of used `{ title }` objects and enter each named phase.
-- Call `agent()` at least once, give every call a short unique `label`, and return plain JSON data explicitly.
-- Pair ordered results with stable work IDs before filtering. When one agent consumes another's selected result, include both its stable ID and actual data in the downstream prompt. Treat recoverable `null` as missing coverage and report it.
-- Bound fan-out, loops, retries, agents, and concurrency to the task. Treat invocation-level token and time caps as opt-in user constraints, not defaults.
-- Use `log()` for new code; `console` is compatibility-only.
-- Write plain JavaScript without imports or filesystem modules. Pass nondeterminism through `args`; `Date.now()`, `Math.random()`, and no-argument `new Date()` are unavailable.
+## Topology rules
+
+### Named dependencies: `orchestrate`
+
+Use a task graph when a later step consumes a named earlier step:
+
+```js
+const graph = await orchestrate([
+  { id: "scan", run: () => agent("Inspect the target", { label: "scan" }) },
+  { id: "security", run: () => agent("Check security risks", { label: "security" }) },
+  {
+    id: "report",
+    dependsOn: ["scan", "security"],
+    run: ({ results, statuses }) =>
+      agent(
+        "Synthesize the named findings; mention unavailable coverage.\n\n" +
+          JSON.stringify({ results, statuses }),
+        { label: "report" },
+      ),
+  },
+]);
+return graph;
+```
+
+`orchestrate()` validates IDs, missing dependencies, duplicate edges, and
+cycles before callbacks run. It executes ready tasks in declaration-order
+layers with a barrier between layers and returns `{ results, tasks }`. Each task
+callback receives detached `{ id, attempt, results, statuses }` snapshots.
+`retries` retries ordinary task-callback failures up to three times. The default
+`onError: "skip-dependents"` prevents a failed dependency from feeding a stale
+prompt; use `onError: "continue"` only when the dependent explicitly handles
+failed statuses. `fail-fast` stops discovery of later layers after the current
+layer settles.
+
+### Independent fan-out: `parallel`
+
+Pass thunks, not already-started promises. Results preserve input order and a
+recoverable item failure becomes `null`; fatal errors surface after the whole
+batch barrier settles. Keep a ledger with IDs before filtering:
+
+```js
+const work = items.map((item) => ({ id: item.id, item }));
+const outputs = await parallel(work.map(({ item }) => () =>
+  agent("Handle item " + item.id, { label: "item-" + item.id }),
+));
+const ledger = work.map(({ id }, index) => ({ id, result: outputs[index] }));
+```
+
+Each `parallel()` call accepts at most 4096 thunks. It is a barrier: do not
+start synthesis until the returned array is complete.
+
+### Per-item stages: `pipeline`
+
+Use `pipeline(items, ...stages)` when every item follows the same chain. Items
+run concurrently, but stages for one item are sequential and receive
+`(previousValue, originalItem, index)`. A stage failure drops that item to
+`null`; guard missing values before the next stage. There is no cross-item
+barrier between stages, and each call accepts at most 4096 items.
+
+### Saved or nested workflows
+
+`workflow(name, childArgs)` resolves a context-supplied saved workflow and runs
+it inline with the parent's limiter, agent accounting, token accounting, and
+store. One nested level is allowed; concurrent siblings are allowed. An
+unchanged child is replayed as one parent journal call, while a changed or
+interrupted child receives a generation-scoped managed identity. Do not use
+nesting as an unbounded recursion mechanism.
+
+## Prompt and result discipline
+
+Every child prompt must be self-contained: state the role, exact task, relevant
+inputs, expected output shape, and what the child must not do. Prefer a small
+`schema` for values JavaScript will inspect. When a child consumes another
+child's output, include the stable ID and actual bounded data, for example:
+
+```js
+const prompt = "Review result " + JSON.stringify({ id: "scan", result: scan });
+```
+
+Do not pass whole transcripts when a summary or structured fields are enough.
+Use `log()` for progress and return a result that distinguishes completed work,
+missing coverage, and failed/skipped work.
+
+## Failure, limits, and recovery
+
+- Recoverable child failures return `null` after agent retries. Fatal workflow
+  errors (invalid hooks, exhausted hard limits, unsupported selectors, and
+  schema exhaustion) throw and must not be dissolved into a normal result.
+- Runtime `agent({ retries })` retries execution failures. `orchestrate` task
+  `retries` retries the callback. Semantic `retry()`/`gate()` attempts are a
+  third, intentional layer. Bound and ledger every layer separately.
+- `agent()` schema repair includes concrete validation feedback in the next
+  attempt. Do not read fields from an unvalidated text response.
+- `checkpoint()` is headless by default for background runs. Use
+  `background: false` only when a human decision must be shown.
+- `budget` and phase budgets are soft pre-call gates; concurrent work may
+  overshoot. Do not promise an exact token ceiling unless the caller supplied
+  and accepted that policy.
+
+## Resume and publication gate
+
+Resume replays the longest unchanged prefix of journaled calls. Keep call order,
+labels, prompts, routing options, and inputs stable. `orchestrate` layer order
+and named dependency results make dynamic plans easier to replay, but arbitrary
+branch/loop call counts can still invalidate the positional prefix. Never use
+`Date.now()`, `Math.random()`, or no-argument `new Date()` in a script.
+
+Before shipping a workflow change:
+
+- read [lifecycle](references/lifecycle.md) for pause, stop, budget, and resume;
+- read [debugging](references/debugging.md) when reproducing a failure;
+- read [the review checklist](references/review.md) before accepting topology;
+- read [the generated capability index](references/capabilities.md) when a
+  signature, default, or support boundary is disputed; remember that a tier
+  names a key in the host catalogue while model/thinking resolution stays in
+  pi-subagents;
+- ensure every package-relative example/reference link remains inside the
+  publishable package.

package/skills/workflow-authoring/examples/named-task-graph.js

@@ -0,0 +1,34 @@
+export const meta = {
+  name: "named-task-graph",
+  description: "Run independent research and synthesize it through named dependencies",
+  phases: [{ title: "research" }, { title: "synthesis" }],
+};
+
+const graph = await orchestrate([
+  {
+    id: "architecture",
+    phase: "research",
+    description: "Inspect the architecture",
+    run: () => agent("Inspect the architecture and report concrete design constraints", { label: "architecture" }),
+  },
+  {
+    id: "risk",
+    phase: "research",
+    description: "Find operational risks",
+    run: () => agent("Find operational and recovery risks", { label: "risk" }),
+  },
+  {
+    id: "synthesis",
+    phase: "synthesis",
+    dependsOn: ["architecture", "risk"],
+    description: "Combine the named findings",
+    run: ({ results, statuses }) =>
+      agent(
+        "Combine these findings. Mention any unavailable dependency explicitly.\n\n" +
+          JSON.stringify({ results, statuses }),
+        { label: "synthesis" },
+      ),
+  },
+]);
+
+return graph;

package/skills/workflow-authoring/references/capabilities.md

@@ -1,8 +1,8 @@
 <!-- GENERATED from WORKFLOW_CAPABILITY_CONTRACT; do not edit by hand. -->
 # Workflow capability index
 
-Contract format: `1.0.0`<br>
-Contract content / skill / extension: `1.3.2`
+Contract format: `2.0.0`<br>
+Contract content / skill / extension: `1.5.0`
 
 This compact generated index covers supported runtime globals and workflow-tool inputs. For constraints, compatibility behavior, internal boundaries, and dynamic-reference ownership, follow the [exhaustive generated facts](capability-details.md).
 
@@ -11,9 +11,10 @@ This compact generated index covers supported runtime globals and workflow-tool
 <!-- BEGIN GENERATED SUPPORTED WORKFLOW CAPABILITIES -->
 | Name | Classification | Signature | Options and defaults |
 | --- | --- | --- | --- |
-| agent | runtime-global | `agent(prompt, options?) => Promise<string \| structured value \| null>` | `label`: string (optional); default: derived from phase and call count<br>`phase`: string (optional); default: current phase<br>`schema`: plain JSON Schema (optional)<br>`model`: string (optional); default: pi-subagents model resolver<br>`tier`: small\|medium\|large (optional); default: pi-subagents workflow tier<br>`isolation`: "worktree" (optional); default: pi-subagents worktree policy<br>`thread`: string (optional); default: fresh session per call<br>`toolset`: string (optional); default: configured host/agent toolset hint<br>`excludeTools`: string[] (optional)<br>`agentType`: string (optional); default: general-purpose<br>`timeoutMs`: number \| null (optional); default: 300000 (5min); null disables<br>`retries`: number (optional); default: run retry count |
+| agent | runtime-global | `agent(prompt, options?) => Promise<string \| structured value \| null>` | `label`: string (optional); default: derived from phase and call count<br>`phase`: string (optional); default: current phase<br>`schema`: plain JSON Schema (optional)<br>`tier`: agent tier key (optional); default: the agent's own tier, else agentTiers.defaultTier<br>`isolation`: "worktree" (optional); default: pi-subagents worktree policy<br>`thread`: string (optional); default: fresh session per call<br>`toolset`: string (optional); default: configured host/agent toolset hint<br>`excludeTools`: string[] (optional)<br>`agentType`: string (optional); default: general-purpose<br>`timeoutMs`: number \| null (optional); default: 300000 (5min); null disables<br>`retries`: number (optional); default: run retry count |
 | parallel | runtime-global | `parallel(thunks) => Promise<Array<unknown \| null>>` | — |
 | pipeline | runtime-global | `pipeline(items, ...stages) => Promise<Array<unknown \| null>>` | — |
+| orchestrate | runtime-global | `orchestrate(tasks, options?) => Promise<{ results, tasks }>` | `onError`: "skip-dependents"\|"continue"\|"fail-fast" (optional); default: "skip-dependents" |
 | workflow | runtime-global | `workflow(savedName, childArgs?) => Promise<unknown>` | — |
 | verify | runtime-global | `verify(item, options?) => Promise<{ real, realCount, total, votes }>` | `reviewers`: number (optional); default: 2<br>`threshold`: number (optional); default: 0.5<br>`lens`: string \| string[] (optional) |
 | judgePanel | runtime-global | `judgePanel(attempts, options?) => Promise<{ index, attempt, score, judgments } \| undefined>` | `judges`: number (optional); default: 3<br>`rubric`: string (optional); default: overall quality and correctness |