@signalridge/pi-workflows 1.2.0 → 1.3.1

package/skills/workflow-authoring/references/capability-details.md

@@ -0,0 +1,294 @@
+<!-- GENERATED from WORKFLOW_CAPABILITY_CONTRACT; do not edit by hand. -->
+# Exhaustive workflow capability facts
+
+Contract format: `1.0.0`<br>
+Contract content / skill / extension: `1.3.1`
+
+Every exact fact below is projected from the installed extension's capability contract. Explanatory judgment belongs in the hand-written references next to this file.
+
+<!-- BEGIN GENERATED WORKFLOW CAPABILITY FACTS -->
+<a id="runtime-global-agent"></a>
+## agent
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `agent(prompt, options?) => Promise<string \| structured value \| null>`
+- `label`: string (optional); default: derived from phase and call count
+- `phase`: string (optional); default: current phase
+- `schema`: plain JSON Schema (optional)
+- `model`: string (optional); default: pi-subagents model resolver
+- `tier`: small\|medium\|large (optional); default: pi-subagents workflow tier
+- `isolation`: "worktree" (optional); default: pi-subagents worktree policy
+- `thread`: string (optional); default: fresh session per call
+- `toolset`: string (optional); default: configured host/agent toolset hint
+- `excludeTools`: string[] (optional)
+- `agentType`: string (optional); default: general-purpose
+- `timeoutMs`: number \| null (optional); default: 300000 (5min); null disables
+- `retries`: number (optional); default: run retry count
+- Constraint: recoverable failures return null after retries; nonrecoverable failures throw
+- Constraint: schema noncompliance after bounded repair attempts is nonrecoverable
+- Constraint: resume replays only the longest unchanged prefix; the first miss and every later call execute live
+- Constraint: spawnKeys rotate by generation on resume so pi-subagents never raises a fingerprint conflict
+- Constraint: explicit model is resolved and scope-checked by pi-subagents; unavailable selectors fail closed
+- Constraint: same-thread calls must be sequential and preserve a stable workflow thread name
+- Constraint: threads cannot be combined with worktree isolation
+
+<a id="runtime-global-parallel"></a>
+## parallel
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `parallel(thunks) => Promise<Array<unknown \| null>>`
+- Constraint: requires functions rather than promises
+- Constraint: result order matches input order
+- Constraint: recoverable thunk failures become null; nonrecoverable failures throw
+- Constraint: a breached agent cap cancels only its own batch
+
+<a id="runtime-global-pipeline"></a>
+## pipeline
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `pipeline(items, ...stages) => Promise<Array<unknown \| null>>`
+- Constraint: items run concurrently while stages per item run sequentially
+- Constraint: each stage receives previousValue, originalItem, and zero-based index
+- Constraint: a null stage result is passed to the next stage
+
+<a id="runtime-global-workflow"></a>
+## workflow
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `workflow(savedName, childArgs?) => Promise<unknown>`
+- Constraint: one nested level
+- Constraint: shares limiter, counters, token accounting, and store
+- Constraint: nested runs get unique runIds via nestedCallSeq
+
+<a id="runtime-global-verify"></a>
+## verify
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `verify(item, options?) => Promise<{ real, realCount, total, votes }>`
+- `reviewers`: number (optional); default: 2
+- `threshold`: number (optional); default: 0.5
+- `lens`: string \| string[] (optional)
+- Constraint: threshold comparison is inclusive; real is false when no reviewer succeeds
+
+<a id="runtime-global-judgepanel"></a>
+## judgePanel
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `judgePanel(attempts, options?) => Promise<{ index, attempt, score, judgments } \| undefined>`
+- `judges`: number (optional); default: 3
+- `rubric`: string (optional); default: overall quality and correctness
+- Constraint: highest mean score wins with stable input index as the tie-break; empty input returns undefined
+
+<a id="runtime-global-loopuntildry"></a>
+## loopUntilDry
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `loopUntilDry({ round, key?, consecutiveEmpty?, maxRounds? }) => Promise<unknown[]>`
+- `round`: (roundIndex) => unknown[]; default: required
+- `key`: (item) => string (optional); default: JSON.stringify
+- `consecutiveEmpty`: number (optional); default: 2
+- `maxRounds`: number (optional); default: 50
+- Constraint: budget/agent-limit exhaustion returns the partial array instead of throwing
+
+<a id="runtime-global-completenesscheck"></a>
+## completenessCheck
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `completenessCheck(taskArgs, results) => Promise<{ complete, missing? } \| null>`
+- Constraint: only the first 4,000 characters of serialized result evidence are sent to the critic
+
+<a id="runtime-global-retry"></a>
+## retry
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `retry(thunk, options?) => Promise<unknown>`
+- `attempts`: number (optional); default: 3
+- `until`: (result) => boolean (optional); default: accept first result
+- Constraint: until must be synchronous
+
+<a id="runtime-global-gate"></a>
+## gate
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `gate(thunk, validator, options?) => Promise<{ ok, value, attempts }>`
+- `attempts`: number (optional); default: 3
+- Constraint: a value is accepted only when the validator returns an object with a truthy ok
+
+<a id="runtime-global-checkpoint"></a>
+## checkpoint
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `checkpoint(prompt, options?) => Promise<unknown>`
+- `default`: unknown (optional); default: true when no UI and omitted
+- `headless`: "default" \| "abort" (optional); default: "default"
+- `kind`: "confirm" \| "input" \| "select" (optional); default: "confirm"
+- `choices`: string[] (optional)
+- `timeoutMs`: number (optional)
+- Constraint: consumes one agent slot and no tokens
+- Constraint: journaled answers replay only within an unchanged resume prefix
+
+<a id="runtime-global-log"></a>
+## log
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `log(message) => void`
+
+<a id="runtime-global-console"></a>
+## console
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `console: { log, info, warn, error }`
+- Constraint: compatibility only — new workflows should use log()
+
+<a id="runtime-global-phase"></a>
+## phase
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `phase(title, options?) => void`
+- `budget`: number (optional); default: positive soft pre-call token gate
+- Constraint: phase budgets are soft pre-call gates
+
+<a id="runtime-global-args"></a>
+## args
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `args: unknown`
+
+<a id="runtime-global-cwd"></a>
+## cwd
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `cwd: string`
+
+<a id="runtime-global-process"></a>
+## process
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `process: { cwd(): string }`
+- Constraint: restricted: only cwd() is exposed
+
+<a id="runtime-global-budget"></a>
+## budget
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `budget: { total, spent(), remaining() }`
+- Constraint: frozen view over shared soft token accounting; nested workflows share the same accounting
+
+<a id="workflow-tool-input-script"></a>
+## script
+
+- Classification: `workflow-tool-input`
+- Support: `supported`
+- Signature: `script?: string`
+- Constraint: required raw JavaScript workflow source unless `name` is given
+
+<a id="workflow-tool-input-name"></a>
+## name
+
+- Classification: `workflow-tool-input`
+- Support: `supported`
+- Signature: `name?: string`
+- Constraint: resolves a saved workflow first, then one of the 5 built-in patterns
+- Constraint: mutually exclusive with script and resumeFromRunId
+
+<a id="workflow-tool-input-args"></a>
+## args
+
+- Classification: `workflow-tool-input`
+- Support: `supported`
+- Signature: `args?: unknown`
+
+<a id="workflow-tool-input-background"></a>
+## background
+
+- Classification: `workflow-tool-input`
+- Support: `supported`
+- Signature: `background?: boolean = true`
+- Constraint: background workflows are headless; use background false when checkpoint must show foreground confirmation
+
+<a id="workflow-tool-input-maxagents"></a>
+## maxAgents
+
+- Classification: `workflow-tool-input`
+- Support: `supported`
+- Signature: `maxAgents?: number = 1000`
+
+<a id="workflow-tool-input-concurrency"></a>
+## concurrency
+
+- Classification: `workflow-tool-input`
+- Support: `supported`
+- Signature: `concurrency?: number`
+- Constraint: runtime clamps to 1..16
+
+<a id="workflow-tool-input-agentretries"></a>
+## agentRetries
+
+- Classification: `workflow-tool-input`
+- Support: `supported`
+- Signature: `agentRetries?: number = 0`
+- Constraint: floored and clamped to 0..3
+
+<a id="workflow-tool-input-agenttimeoutms"></a>
+## agentTimeoutMs
+
+- Classification: `workflow-tool-input`
+- Support: `supported`
+- Signature: `agentTimeoutMs?: number = 300000`
+- Constraint: null disables the hard timeout; default 300000ms (5min)
+
+<a id="workflow-tool-input-tokenbudget"></a>
+## tokenBudget
+
+- Classification: `workflow-tool-input`
+- Support: `supported`
+- Signature: `tokenBudget?: number`
+- Constraint: soft pre-call gate; in-flight work can overshoot
+
+<a id="workflow-tool-input-resumefromrunid"></a>
+## resumeFromRunId
+
+- Classification: `workflow-tool-input`
+- Support: `supported`
+- Signature: `resumeFromRunId?: string`
+- Constraint: resumes a prior incomplete run with an edited script
+- Constraint: unchanged positional calls replay from cache until the first changed call
+- Constraint: always runs in the background
+
+<a id="script-contract-export-const-meta"></a>
+## export const meta
+
+- Classification: `script-contract`
+- Support: `supported`
+- Signature: `export const meta = { name, description, phases? }`
+- Constraint: must be the first statement
+- Constraint: name and description must be nonblank literals
+- Constraint: spread, computed keys, methods, template interpolation, and __proto__/constructor/prototype are rejected
+
+<a id="script-contract-determinism"></a>
+## determinism
+
+- Classification: `script-contract`
+- Support: `supported`
+- Signature: `Date.now(), Math.random(), no-argument new Date() unavailable`
+- Constraint: pass timestamps and randomness through args
+
+<!-- END GENERATED WORKFLOW CAPABILITY FACTS -->

package/skills/workflow-authoring/references/common-helpers.md

@@ -0,0 +1,4 @@
+# Common helper index
+
+- Read [quality helpers](quality-helpers.md) for `verify()` or `judgePanel()`.
+- Read the [retry helper](retry-helper.md) for `retry()`.

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

@@ -0,0 +1,29 @@
+# Workflow debugging map
+
+Start from the symptom, then reproduce through the real workflow runtime with deterministic fake agents.
+
+| Symptom | Likely authoring cause | Check |
+| --- | --- | --- |
+| Parser says metadata is missing | `export const meta` is not the first statement or is nonliteral | [runtime](runtime.md#script-envelope) |
+| `parallel()` rejects input | Promises were passed instead of thunks | [runtime](runtime.md#topology) |
+| Synthesis starts early | Fan-out was not awaited as one complete result set | [pattern selection](pattern-selection.md#fan-out-and-synthesize) |
+| Coverage silently disappears | `null` results were filtered before IDs were ledgered | [lifecycle](lifecycle.md#retry-and-recoverable-failure) |
+| Wrong model is used | A higher-priority selector overrides the expected route | [registry ownership](registry-ownership.md#priority) |
+| Unknown `agentType` log | A live registry name was guessed or is unavailable | [registry ownership](registry-ownership.md#agent-types) |
+| Budget exceeds the number shown | The budget is a soft pre-call gate and work was in flight | [lifecycle](lifecycle.md#bounds-and-budget) |
+| Later calls rerun on resume | An earlier call missed or changed, ending the replayable prefix | [lifecycle](lifecycle.md#resume) |
+| Resume reruns a call that already "succeeded" once before | Its only prior attempt(s) ended in a recoverable failure (e.g. `AGENT_EMPTY_OUTPUT`) and were never journaled | [lifecycle](lifecycle.md#resume) |
+| A field read off `agent()`'s result is `undefined` | No `schema` was set; the prompt asking for JSON does not change that `agent()` returns raw text | [lifecycle](lifecycle.md#serialization) |
+| Nested workflow fails | Nesting exceeded one level or shared limits were exhausted | [lifecycle](lifecycle.md#nesting-and-shared-state) |
+| Checkpoint does not show a form | Input/select/timeout behavior is declared-only | [lifecycle](lifecycle.md#checkpoints) |
+| Returned result cannot cross boundary | It contains a function, promise, cycle, `BigInt`, or runtime object | [lifecycle](lifecycle.md#serialization) |
+| `Date.now()`/randomness is rejected | Resume requires deterministic call structure | [lifecycle](lifecycle.md#resume) |
+
+## Debugging procedure
+
+1. Reduce to the smallest script that preserves metadata, labels, work IDs, and the failing topology.
+2. Replace provider calls with deterministic, schema-aware fake agents.
+3. Record call order, labels, phases, prompts, results, and `null` entries.
+4. When the failure turns on a disputed signature or default, compare it with the compact [capability index](capabilities.md); follow its exhaustive-facts pointer only when needed.
+5. Separate runtime defects from unsupported authoring assumptions and compatibility-only behavior.
+6. Fix only the demonstrated authoring issue; do not rely on known out-of-scope gaps in nested persistence, resume accounting, checkpoint forms/timeouts, metadata validation, or budget overshoot.

package/skills/workflow-authoring/references/focused-recipes.md

@@ -0,0 +1,12 @@
+# Focused recipes
+
+Read only the recipe matching the concern. Change task prompts, schemas, bounds, and context-supplied inputs; preserve the listed contract.
+
+| Concern | Preserve when adapting | Tested recipe |
+| --- | --- | --- |
+| Phased budgets | Phase and run budgets are soft pre-call gates; active work can overshoot. Report shared spend and bound calls independently. | [Phased budgets](../examples/phased-budgets.js) |
+| Saved workflows | Use a context-supplied name, await jobs sequentially, nest one level, and treat shared limits, counters, tokens, limiter, and store as parent capacity. | [Saved nested workflows](../examples/saved-nested-workflows.js) |
+| Semantic retry | Separate it from recoverable runtime retries. Use a new unique label per bounded attempt and return the attempt ledger plus exhausted outcome. | [Bounded semantic retry](../examples/bounded-semantic-retry.js) |
+| Validator feedback | Follow the exact `gate()` callbacks in [specialized helpers](specialized-helpers.md). Return the gate outcome and attempt ledger so feedback and exhaustion remain visible. | [Validated gate](../examples/validated-gate.js) |
+| Structured fields | Pass a small plain JSON Schema before reading fields. Ledger recoverable `null`; treat exhausted schema repair as a nonrecoverable failure. | [Structured output](../examples/structured-output.js) |
+| Defensive text parsing | Without `schema`, `agent()` always resolves to raw text, even when the prompt asks for JSON. Parse and validate shape before reading fields; ledger unparseable text separately from recoverable `null`. Prefer `schema` when the shape matters. | [Defensive JSON parsing](../examples/defensive-json-parsing.js) |

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

@@ -0,0 +1,9 @@
+# Helper reference index
+
+Use a helper only when it expresses the task's policy. Preserve candidate or work identity outside helper results that may omit failed agents.
+
+- Read [quality helpers](quality-helpers.md) for `verify()` or `judgePanel()`.
+- Read the [retry helper](retry-helper.md) for `retry()`.
+- Read [specialized helpers](specialized-helpers.md) for `completenessCheck()`, `loopUntilDry()`, `gate()`, or `checkpoint()`.
+
+Runtime agent retries repeat recoverable execution failures; helper attempts are new semantic calls. Bound both layers and ledger exhaustion.

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

@@ -0,0 +1,37 @@
+# Lifecycle, limits, and resume
+
+## Bounds and budget
+
+Set finite bounds that match the work for `maxAgents`, `concurrency`, and `agentRetries`; bound loops and semantic retries inside the script. Treat invocation-level `agentTimeoutMs` and `tokenBudget` as opt-in user constraints, not precautionary defaults. Omit `tokenBudget` unless the user supplies a cap or explicitly asks you to choose one. If asked to choose, allow for every planned agent call, retry, synthesis, and verification pass, with headroom. A tight gate can terminate coverage; it does not reduce work already in flight. An omitted `agentTimeoutMs` uses the configured `defaultAgentTimeoutMs` and is otherwise unbounded. An omitted `tokenBudget` uses the configured `defaultTokenBudget` and is otherwise unlimited.
+
+Enter a phase budget with `phase("Name", { budget: N })`; phase metadata does not carry budgets. `N` is a token allowance, not a call or round count: size it for the intended agent work instead of copying a small iteration limit. Token and phase budgets are soft pre-call gates. Spend lands after agents finish, so concurrent work can overshoot. A phase budget gates later calls in that phase; it neither reserves tokens nor cancels active calls. `budget.spent()` and `budget.remaining()` include nested work.
+
+## Checkpoints
+
+A checkpoint consumes an agent slot but no tokens. A workflow invocation is backgrounded by default, and background workflows are headless: they cannot display checkpoint confirmation. Use `background: false` when a checkpoint must reach the foreground host confirmation interface. Without a UI, a checkpoint returns the declared default (or `true` when omitted) unless `headless: "abort"` is selected. Confirm is implemented. Input, select, and timeout fields are declared for compatibility/future behavior but are not authoring promises.
+
+Checkpoint answers are journaled and can replay during an unchanged resume prefix. Do not describe checkpoints as guaranteed arbitrary forms or as remote steering.
+
+## Retry and recoverable failure
+
+Recoverable execution failures retry according to the per-agent option or invocation-time tool input, then return `null`. Nonrecoverable failures throw without becoming `null`. The logical `retry()` combinator is separate: it performs new agent calls and returns its last result when exhausted unless the script records and handles that outcome.
+
+Always retain `{ id, status, result }` or an equivalent ledger for each intended work unit. Filtering `null` before recording identity turns an execution failure into invisible missing coverage.
+
+`AGENT_EMPTY_OUTPUT` (whitespace-only text from a schema-less call) is recoverable and retries like any other transient failure. Some models occasionally produce it on an otherwise-working first attempt; a fleet built on such a model should set `agentRetries: 1-2` rather than treat one occurrence as a failed run. A `schema` call never trips this check — schema noncompliance is its own, nonrecoverable failure (see [serialization](#serialization)).
+
+## Resume
+
+Resume replays only the longest unchanged prefix of journaled calls. Once one call is new, changed, or unusable, that call and all later calls execute live. Stable lexical call ordering, prompts, labels, routing options, and inputs therefore matter. Retry chains can cascade after an upstream miss. Nested workflows do not reuse the parent's resume journal.
+
+Only a call that finishes with a real result is journaled. A call whose every attempt was recoverable (including one that only ever produced `AGENT_EMPTY_OUTPUT`) contributes no journal entry, so resuming that run reruns exactly that call and everything lexically after it live; the earlier, already-succeeded prefix still replays from cache.
+
+The runtime blocks common accidental nondeterminism, but this is not a security boundary. Pass timestamps, randomness, and external decisions through `args`.
+
+## Nesting and shared state
+
+`workflow(savedName, childArgs)` runs sequentially inline, allows one nested level, and shares limiter, counters, token accounting, and shared store with the parent. It is not independent capacity. Use only a saved-workflow name provided by context; do not guess registry entries or pass raw scripts as a new authoring pattern even where compatibility behavior accepts them.
+
+## Serialization
+
+The workflow's explicit return value crosses the tool boundary. Keep it JSON-serializable and preserve coverage ledgers in the returned data. Structured agent schemas must be plain JSON Schema. Schema success guarantees the downstream field shape expected by JavaScript; without a schema, treat output as text or `null`. A prompt that asks the model to "return JSON" does not change this — without `schema`, parse and validate that text defensively before reading a field, and ledger an unparseable result instead of reading `undefined` off it (see [defensive text parsing](focused-recipes.md)).

package/skills/workflow-authoring/references/pattern-selection.md

@@ -0,0 +1,15 @@
+# Pattern selection
+
+Choose from data dependencies, then read only the matching example. JavaScript owns enumeration, identity, ordering, deduplication, bounds, stopping, brackets, and failure ledgers. Agents own semantic work.
+
+<a id="fan-out-and-synthesize"></a>
+| Dependency shape | Pattern | Preserve when adapting | Example |
+| --- | --- | --- | --- |
+| Heterogeneous items need different handling | Classify and act | Finish all classification before routed action; ledger classification and action failures by item ID | [Adapt](../examples/classify-and-act.js) |
+| Independent work needs whole-set judgment | Fan out and synthesize | Pass thunks; await the full set; give synthesis every intended ID, including `null` | [Adapt](../examples/fan-out-and-synthesize.js) |
+| Claims need skeptical checks | Adversarial verification | Use separate producer and skeptic calls; start skepticism after production; ledger both failures | [Adapt](../examples/adversarial-verification.js) |
+| Exploration should diverge before one rubric | Generate and filter | Finish generation; deterministically deduplicate and bound candidates before filter calls | [Adapt](../examples/generate-and-filter.js) |
+| Pairwise comparison beats absolute scoring | Tournament | Let JavaScript run the bounded bracket and byes; agents compare one pair; ledger match failures | [Adapt](../examples/tournament.js) |
+| Work cardinality is unknown | Loop until done | Deduplicate by stable key; count only successful empty rounds as dry; cap rounds; retain failed rounds | [Adapt](../examples/loop-until-done.js) |
+
+For every pattern, validate and bound input before fan-out, use stable IDs and unique labels, preserve missing coverage, and return plain JSON data. Combine patterns only when the task has both dependency shapes. Direct work needs no orchestration.

package/skills/workflow-authoring/references/quality-helpers.md

@@ -0,0 +1,8 @@
+# Verify and judge
+
+Keep work IDs outside helper results that may omit failed agents.
+
+| Call | Contract |
+| --- | --- |
+| `verify(item, { reviewers: number, threshold: number, lens: string | string[] })` | Defaults: 2 reviewers, inclusive `0.5`, one lens or a cycled array. Returns `{ real, realCount, total, votes }`. Failed reviewers are omitted; successful votes are the denominator; zero survivors means `real: false`. |
+| `judgePanel(attempts, { judges: number, rubric: string })` | Defaults: 3 judges and `"overall quality and correctness"`. Failed judgments are omitted. Returns the highest mean `{ index, attempt, score, judgments }`; input order wins ties; empty input returns `undefined`. |

package/skills/workflow-authoring/references/registry-ownership.md

@@ -0,0 +1,17 @@
+# Dynamic registry ownership
+
+Model routes and agent types are dynamic references. Their shape and owner are documented, but available names depend on active user/project configuration and are intentionally absent from static skill files.
+
+## Model routes
+
+The `pi-subagents` workflow-tier settings own route names. Standard routes are `small`, `medium`, and `large`; use another route only when its name and purpose are supplied in context. A route is selected with `tier`. An exact user-requested model is selected with `model` and is resolved/scope-checked by pi-subagents.
+
+## Agent types
+
+The agent registry owns agent-type names and their bound instructions, tools, model, and isolation policy. Use `agentType` only when context supplies both its name and purpose. Do not infer an agent type from a role-like label.
+
+## Priority
+
+Routing priority is explicit `model` > named `tier` > phase/run model > pi-subagents agent configuration > parent session. Higher priority means selection, not "try this then fall back to the next selector." Avoid specifying competing selectors unless deliberately overriding a lower-priority default.
+
+Unavailability is fail-closed for explicit `model` and named tiers: pi-subagents reports the selector and does not silently run a different model. An omitted selector may inherit the parent session according to the companion's current settings.

package/skills/workflow-authoring/references/retry-helper.md

@@ -0,0 +1,5 @@
+# Retry
+
+`retry(thunk, { attempts, until })` takes exactly these 2 arguments; `until` belongs in the options object. It calls `thunk(attempt)` with a zero-based index and defaults to 3 attempts. `until` is synchronous—a Promise or omitted predicate accepts the first result. Exhaustion returns only the last result, so keep an attempt ledger.
+
+Always `await retry()`. A thunk containing `await` must be `async`; await `agent()` before adding its resolved value to the ledger. Runtime retries repeat recoverable execution failures; helper attempts are new semantic calls. Bound both layers and ledger exhaustion.

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

@@ -0,0 +1,43 @@
+# Workflow review checklist
+
+Review author-visible behavior, not formatting preferences. When behavior depends on a quality or control combinator, consult only its exact [quality](quality-helpers.md) or [specialized](specialized-helpers.md) helper contract before correcting the script.
+
+## Envelope and contract
+
+- Is literal `export const meta` the first statement, with a short unique name and useful description?
+- Are only used phases declared, and does each named phase begin at the intended boundary?
+- Does the script call at least one agent and explicitly return JSON-serializable data?
+- Are imports and nondeterministic APIs absent?
+
+## Topology and identity
+
+- Does topology match dependencies: thunks for independent parallel work, stages for per-item pipelines, barriers before whole-set synthesis?
+- Is cardinality bounded before fan-out?
+- Is every agent label short and unique?
+- Are stable work-unit IDs retained beside ordered results?
+- Are failed/null identities recorded before any filtering?
+
+## Data and routing
+
+- Does JavaScript consume structured fields only after a small plain JSON Schema guarantees them?
+- Does synthesis receive complete coverage and failure ledgers?
+- Are `model`, `tier`, and `agentType` used according to selector priority?
+- Did every nonstandard route or agent type come from context with a name and purpose?
+
+## Lifecycle
+
+- Are runtime retries and semantic retries separately bounded?
+- Are loops, agents, concurrency, timeout, and token spend bounded appropriately?
+- Are budget claims honest about soft gates and in-flight overshoot?
+- Are checkpoints limited to implemented confirmation/headless behavior?
+- Does nesting stay one level and account for shared limits/store?
+- Would lexical call order remain stable under resume?
+
+## Compatibility and publication
+
+- Does new code use `log()` rather than compatibility-only `console`?
+- Is compatibility behavior clearly distinguished from supported authoring behavior and VM substrate?
+- Do package, skill, and generated contract versions match?
+- Do all relative links resolve within the publishable package?
+
+Use [lifecycle](lifecycle.md) for lifecycle reasoning. Open the compact [capability index](capabilities.md) only when the review turns on a disputed signature, default, support boundary, or installed version; follow its exhaustive-facts pointer only when the index is insufficient.

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

@@ -0,0 +1,29 @@
+# Runtime authoring
+
+Use this page for routine scripts. Open the generated capability index only when a signature, default, support boundary, or installed-version fact is missing here.
+
+## Script envelope
+
+Start with the only legal export: `export const meta = { name, description, phases?: [{ title, detail?, model? }] }`. Values are nonblank literals; declare only used phases and call `phase()` before each phase's work. The remaining body already runs inside an async function: write helpers as ordinary declarations; `export default` and other exports are invalid. Return the result explicitly.
+
+The runtime supplies `agent`, `parallel`, `pipeline`, `workflow`, quality/control helpers, `phase`, `log`, `args`, `cwd`, restricted `process.cwd()`, and `budget`. Imports, `require()`, filesystem modules, `Date.now()`, `Math.random()`, and no-argument `new Date()` are unavailable. The Node VM realm is implementation substrate, not a security boundary or public API.
+
+## Topology
+
+- `parallel()` takes thunks, runs independent work, and preserves input order. Await the whole array before whole-set synthesis.
+- `pipeline()` runs stages sequentially per item while items proceed concurrently. Each stage receives `(previousValue, originalItem, index)` and forwards `null` to the next stage, so guard missing coverage first.
+- `workflow(name, childArgs?)` runs a context-supplied saved workflow. Nesting is one level and shares limits, counters, tokens, and store.
+
+## Data and failure
+
+Call `agent(prompt, { label, schema? })`; it returns text, a schema-validated value, or recoverable `null`. Nonrecoverable limit, validation, and budget failures throw. Record each intended work ID before filtering. A `null` means missing coverage, never a negative finding.
+
+Use `agent(prompt, { thread: "implementer" })` when the same managed subagent must receive a later follow-up with its complete conversation intact. Reuse a thread name sequentially; never put same-thread calls in one `parallel()` batch. Threads are scoped to one workflow run/session and cannot use worktree isolation. A pause or process restart may require a fresh thread session.
+
+When JavaScript reads fields, pass a small plain JSON Schema. Schema noncompliance after repair throws and bypasses agent retries. Catch it only to return an explicit incomplete outcome without reading missing fields. Return objects, arrays, strings, numbers, booleans, and `null`—not functions, promises, cycles, `BigInt`, or runtime handles.
+
+## Routing and support
+
+Selector priority is explicit `model` > named `tier` > phase/run model > pi-subagents agent configuration > parent session. An unavailable explicit selector fails closed rather than silently choosing another model. Worktree isolation is also fail-closed and remains owned by pi-subagents. See [registry ownership](registry-ownership.md).
+
+Generated entries marked `supported` are authoring API. `console` and whole-script Markdown fences are compatibility-only. VM realm facilities are internal. Active model routes and agent types are dynamic. Use `log()` in new scripts.

package/skills/workflow-authoring/references/specialized-helpers.md

@@ -0,0 +1,19 @@
+# Specialized helpers
+
+Preserve candidate or work identity outside helper results that may omit failed agents.
+
+## Quality
+
+| Helper | Authoring contract |
+| --- | --- |
+| `completenessCheck(args, results)` | Returns `{ complete, missing? }` or recoverable `null`. The critic sees only the first 4,000 serialized characters, so chunk or summarize larger evidence. Treat the verdict as advisory. |
+| `loopUntilDry({ round, key, consecutiveEmpty, maxRounds })` | `round(index)` is zero-based. Defaults: `JSON.stringify` key, two dry rounds, 50 rounds. Null, non-array, and duplicate-only rounds are dry. Token-budget or agent-limit exhaustion returns the partial array without a termination reason; keep failed-round identity and stopping state outside the helper. |
+
+## Control
+
+| Helper | Authoring contract |
+| --- | --- |
+| `gate(thunk, validator, { attempts })` | Calls `thunk(feedback, attempt)` with initial `undefined` feedback and a zero-based attempt. `validator(value)` returns `{ ok, feedback? }`, synchronously or asynchronously; a bare boolean is not accepted. Three attempts by default. Returns `{ ok, value, attempts }`, including the last value on exhaustion. See [validated gate](../examples/validated-gate.js). |
+| `checkpoint(prompt, options?)` | Journals a human/default decision. Only foreground confirm and documented headless behavior work; input, select, and timeout are declared-only. |
+
+Always `await gate()`. A thunk containing `await` must itself be declared `async`; await `agent()` before adding its resolved value to a ledger. Runtime agent retries repeat recoverable execution failures; helper attempts are new semantic calls. Bound both layers and ledger exhaustion.

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

@@ -0,0 +1,13 @@
+# Version compatibility
+
+The installed package, capability-contract content, and this skill must describe the same extension version. Read the version line generated at the top of [capabilities](capabilities.md); the skill's frontmatter version and package version must match it.
+
+`present-at` means a capability is confirmed in the recorded version. It is an honest baseline, not a claim about the first historical release that introduced the capability. The contract format has its own version because descriptor shape can evolve separately from extension content.
+
+When copying a workflow between installations:
+
+1. Check the destination's generated version and exact capability facts.
+2. Re-check every supported global, option, and constraint used by the script.
+3. Treat compatibility entries as preservation aids, not portable recommendations.
+4. Re-resolve dynamic model routes and agent types from destination context; static docs intentionally contain no live entries.
+5. Prefer runtime behavior when prose and execution disagree, and report the documentation mismatch rather than changing behavior during an authoring fix.

package/skills/workflow-patterns/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: workflow-patterns
+description: Argument shapes for the 5 built-in workflow patterns — deep-research, adversarial-review, code-review, multi-perspective, codebase-audit — runnable via the `workflow` tool's `name` input, without slash-command syntax. Use for requests like "research X", "fact-check/adversarially review this", "review this diff/PR", "analyze from multiple perspectives", or "audit the codebase for Y". Not for authoring a new workflow script — see workflow-authoring.
+metadata:
+  version: "1.2.1"
+---
+
+# Built-in workflow patterns
+
+@signalridge/pi-workflows ships 5 curated, tested workflow patterns. Each is also a
+slash command (`/deep-research`, `/adversarial-review`, `/code-review`,
+`/multi-perspective`, `/codebase-audit`), but they are equally reachable from
+the `workflow` tool directly: call it with `name` set to the pattern name
+below and `args` matching its shape, instead of writing an equivalent script
+from scratch. Prefer this over authoring a new script whenever the request
+fits one of these shapes — the curated version is already reviewed and tested.
+
+A project or user saved workflow of the same name always takes precedence
+over a built-in of that name — on the slash command, too.
+
+These 5 names are reachable only at the `workflow` tool's top-level `name`
+input, not via the in-script `await workflow(savedName, childArgs)` helper —
+that helper resolves saved workflows only. Calling `workflow('deep-research')`
+from inside a script fails as an unknown saved workflow; use the top-level
+`name` input instead.
+
+## Patterns
+
+| `name` | When to reach for it | `args` |
+| --- | --- | --- |
+| `deep-research` | Research a question across the web with cross-checked sources | `{ question: string, angles?: number, minSupport?: number }` — `angles` (default 4) is the number of distinct search queries; `minSupport` (default 2) is the minimum distinct sources required for a claim to survive cross-checking |
+| `adversarial-review` | Investigate a task/claim, then cross-check each finding with skeptical reviewers | `{ task: string, reviewers?: number, threshold?: number }` |
+| `code-review` | Multi-angle review of a diff (correctness, reuse, simplification, efficiency, altitude) | `{ diff: string, diffSource?: string }` — get `diff` yourself first (e.g. `git diff`, `gh pr diff <n>`); this path does not fetch it for you |
+| `multi-perspective` | Analyze a topic from several independent perspectives in parallel, then synthesize | `{ topic: string, perspectives?: string[] }` — omit or give fewer than 2 to use the default set (technical, product, security, user experience, maintainability) |
+| `codebase-audit` | Audit a codebase for health, risk, and debt across dimensions | `{ scope?: string, root?: string, focus?: string, checks?: string[] }` — `scope`/`root` chooses the directory and `focus`/`checks` refines what the agents inspect |
+
+## Example
+
+```json
+{ "name": "deep-research", "args": { "question": "What are the tradeoffs of X vs Y?" } }
+```
+
+This is a `workflow` tool call, not a script — omit `script` entirely. The run
+starts in the background exactly like the slash-command form; `background`,
+`maxAgents`, `concurrency`, `agentRetries`, `agentTimeoutMs`, and `tokenBudget`
+all still apply.
+
+## Writing a new workflow instead
+
+If the request doesn't fit one of these 5 shapes, author a script with
+`script` as usual — see the workflow-authoring skill.