@yycholla/pi-dynamic-workflows 3.3.0

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

@@ -0,0 +1,357 @@
+<!-- GENERATED from WORKFLOW_CAPABILITY_CONTRACT; do not edit by hand. -->
+# Exhaustive workflow capability facts
+
+Contract format: `1.0.0`<br>
+Contract content / skill / extension: `3.3.0`
+
+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.
+
+<a id="agent"></a>
+## agent
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `agent(prompt, options?) => Promise<string \| structured value \| null>`
+- Option shape: `agent-options`
+- `label`: string (optional; default: derived from phase and call count)
+- `phase`: string (optional; default: current phase)
+- `schema`: plain JSON Schema (optional)
+- `model`: string (optional; highest-priority exact model selector)
+- `tier`: string (optional; configured route name; dynamic reference: model-routes)
+- `isolation`: "worktree" (optional)
+- `agentType`: string (optional; must come from provided context; dynamic reference: agent-types)
+- `timeoutMs`: number | null (optional; default: run timeout; null disables)
+- `retries`: number (optional; default: run retry count; finite values are floored and clamped to 0..3)
+- Constraint: recoverable failures return null after retries; nonrecoverable failures throw
+- Constraint: schema noncompliance after bounded structured-output repair is nonrecoverable and bypasses agent retries
+- Constraint: per-agent retries override invocation retries; retries are floored and clamped to 0..3
+- Constraint: resume replays only the longest unchanged prefix; the first miss and every later call execute live
+- Constraint: selector priority is explicit model > agentType model > tier > phase model > metadata model > implicit medium > session default
+- Constraint: if the selected model or route is unavailable, execution falls directly to the session default rather than trying lower-priority selectors
+- Constraint: worktree isolation is best-effort; failure logs that isolation was ignored and continues without an isolated working directory
+
+<a id="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
+
+<a id="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; authors must guard missing coverage explicitly
+- Constraint: recoverable stage failures become null; nonrecoverable failures throw
+
+<a id="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 workflows do not reuse the parent resume journal
+
+<a id="verify"></a>
+## verify
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `verify(item: unknown, options?: { reviewers?: number; threshold?: number; lens?: string \| string[] }) => Promise<{ real: boolean; realCount: number; total: number; votes: Array<{ real: boolean; reason?: string }> }>`
+- Option shape: `verify-options`
+- `reviewers`: number (optional; default: 2; authors should provide a finite integer; runtime clamps below 1)
+- `threshold`: number (optional; default: 0.5)
+- `lens`: string | string[] (optional)
+- Constraint: reviewer failures are omitted; successful votes form the denominator in realCount / total
+- Constraint: threshold comparison is inclusive and real is false when no reviewer succeeds
+- Constraint: multiple lenses cycle across reviewers
+
+<a id="judgepanel"></a>
+## judgePanel
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `judgePanel(attempts: unknown[], options?: { judges?: number; rubric?: string }) => Promise<{ index: number; attempt: unknown; score: number; judgments: Array<{ score: number; reason?: string }> } \| undefined>`
+- Option shape: `judge-panel-options`
+- `judges`: number (optional; default: 3; authors should provide a finite integer; runtime clamps below 1)
+- `rubric`: string (optional; default: "overall quality and correctness")
+- Constraint: failed judgments are omitted and each candidate score averages successful judgments only
+- Constraint: a candidate with no successful judgments scores 0
+- Constraint: highest mean score wins with stable input index as the tie-break; empty input returns undefined
+
+<a id="loopuntildry"></a>
+## loopUntilDry
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `loopUntilDry(options: { round: (roundIndex: number) => unknown[] \| Promise<unknown[]>; key?: (item: unknown) => string; consecutiveEmpty?: number; maxRounds?: number }) => Promise<unknown[]>`
+- Option shape: `loop-until-dry-options`
+- `round`: (roundIndex: number) => unknown[] | Promise<unknown[]> (required)
+- `key`: (item: unknown) => string (optional; default: JSON.stringify)
+- `consecutiveEmpty`: number (optional; default: 2; authors should provide a finite integer; runtime clamps below 1)
+- `maxRounds`: number (optional; default: 50; authors should provide a finite positive integer)
+- Constraint: roundIndex is zero-based; null, non-array, or duplicate-only round results count as empty
+- Constraint: token-budget or agent-limit capacity exhaustion returns the accumulated partial array instead of throwing
+- Constraint: the returned array does not report whether termination came from dryness, maxRounds, or capacity exhaustion
+- Constraint: authors must retain failed-round identity and truthful termination state outside the helper
+
+<a id="completenesscheck"></a>
+## completenessCheck
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `completenessCheck(taskArgs: unknown, results: unknown) => Promise<{ complete: boolean; missing?: string[] } \| null>`
+- Constraint: only the first 4,000 characters of serialized result evidence are sent to the critic
+- Constraint: missing is optional and recoverable critic failure returns null
+- Constraint: large evidence sets must be chunked or summarized before relying on the advisory verdict
+
+<a id="retry"></a>
+## retry
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `retry(thunk: (attempt: number) => unknown \| Promise<unknown>, options?: { attempts?: number; until?: (result: unknown) => boolean }) => Promise<unknown>`
+- Option shape: `retry-options`
+- `attempts`: number (optional; default: 3; authors must provide a finite integer; runtime clamps values below 1 to 1)
+- `until`: (result: unknown) => boolean (optional; default: accept first result when omitted; must be synchronous; use gate for asynchronous validation)
+- Constraint: attempt is zero-based and attempts counts total thunk calls
+- Constraint: until is synchronous; returning a Promise is truthy and accepts the first result
+- Constraint: omitting until accepts the first result regardless of attempts
+- Constraint: stops when until(result) is true; exhaustion returns only the last result without attempt metadata
+- Constraint: authors must supply a finite attempts bound when overriding the default
+
+<a id="gate"></a>
+## gate
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `gate(thunk: (feedback: string \| undefined, attempt: number) => unknown \| Promise<unknown>, validator: (value: unknown) => { ok: boolean; feedback?: string } \| Promise<{ ok: boolean; feedback?: string }>, options?: { attempts?: number }) => Promise<{ ok: boolean; value: unknown; attempts: number }>`
+- Option shape: `gate-options`
+- `attempts`: number (optional; default: 3; authors must provide a finite integer; runtime clamps values below 1 to 1)
+- Constraint: feedback is undefined on the first thunk call and then receives the previous validator feedback string
+- Constraint: attempt is zero-based for the thunk while the returned attempts count is one-based
+- Constraint: a value is accepted when the validator returns an object with a truthy ok property; a bare boolean is not accepted
+- Constraint: exhaustion returns ok false with the last value and the bounded attempts count
+- Constraint: authors must supply a finite attempts bound when overriding the default
+
+<a id="checkpoint"></a>
+## checkpoint
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `checkpoint(prompt, options?) => Promise<unknown>`
+- Option shape: `checkpoint-options`
+- `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: foreground confirm and headless behavior are implemented; input/select/timeout are declared-only
+- Constraint: consumes one agent slot and no tokens
+- Constraint: journaled answers replay only within an unchanged resume prefix
+
+<a id="log"></a>
+## log
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `log(message) => void`
+
+<a id="phase"></a>
+## phase
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `phase(title, options?) => void`
+- Option shape: `phase-options`
+- `budget`: number (optional; positive soft pre-call token gate)
+- Constraint: phase budgets are soft pre-call gates
+
+<a id="args"></a>
+## args
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `args: unknown`
+
+<a id="cwd"></a>
+## cwd
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `cwd: string`
+
+<a id="process"></a>
+## process
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `process: { cwd(): string }`
+
+<a id="budget"></a>
+## budget
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `budget: { total, spent(), remaining() }`
+- Constraint: frozen view over shared soft token accounting
+- Constraint: spend accrues after agents finish, so in-flight work can overshoot
+- Constraint: nested workflows share the same accounting
+
+<a id="console"></a>
+## console
+
+- Classification: `runtime-global`
+- Support: `compatibility`
+- Signature: `console: { log, info, warn, error }`
+- Constraint: new workflows should use log()
+
+<a id="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="tool-input-name"></a>
+## name
+
+- Classification: `workflow-tool-input`
+- Support: `supported`
+- Signature: `name?: string`
+- Constraint: resolves a project/user saved workflow first, then one of the 5 built-in patterns
+- Constraint: mutually exclusive with resumeFromRunId
+
+<a id="tool-input-args"></a>
+## args
+
+- Classification: `workflow-tool-input`
+- Support: `supported`
+- Signature: `args?: unknown`
+
+<a id="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="tool-input-maxagents"></a>
+## maxAgents
+
+- Classification: `workflow-tool-input`
+- Support: `supported`
+- Signature: `maxAgents?: number = 1000`
+- Constraint: default, not a hard product maximum
+
+<a id="tool-input-concurrency"></a>
+## concurrency
+
+- Classification: `workflow-tool-input`
+- Support: `supported`
+- Signature: `concurrency?: number`
+- Constraint: runtime clamps to 1..16
+
+<a id="tool-input-agentretries"></a>
+## agentRetries
+
+- Classification: `workflow-tool-input`
+- Support: `supported`
+- Signature: `agentRetries?: number = configured value or 0`
+- Constraint: floored and clamped to 0..3
+
+<a id="tool-input-agenttimeoutms"></a>
+## agentTimeoutMs
+
+- Classification: `workflow-tool-input`
+- Support: `supported`
+- Signature: `agentTimeoutMs?: number = configured default or unbounded`
+
+<a id="tool-input-tokenbudget"></a>
+## tokenBudget
+
+- Classification: `workflow-tool-input`
+- Support: `supported`
+- Signature: `tokenBudget?: number = configured default or unlimited`
+- Constraint: soft pre-call gate; in-flight work can overshoot
+
+<a id="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 agent calls replay from cache until the first changed or inserted call
+- Constraint: always runs in the background
+
+<a id="metadata"></a>
+## export const meta
+
+- Classification: `script-contract`
+- Support: `supported`
+- Signature: `export const meta = { name: string, description: string, phases?: Array<{ title: string; detail?: string; model?: string }>, model?: string }`
+- Constraint: must be the first statement
+- Constraint: name and description must be nonblank strings
+- Constraint: metadata must use literal values; expressions such as string concatenation and template interpolation are rejected
+- Constraint: the meta declaration is the only legal export because the remaining body executes inside an async function
+
+<a id="return-value"></a>
+## workflow return value
+
+- Classification: `script-contract`
+- Support: `supported`
+- Signature: `return JSON-serializable data`
+- Constraint: do not return functions, promises, cyclic objects, BigInt, or runtime handles
+
+<a id="determinism"></a>
+## deterministic script execution
+
+- Classification: `script-contract`
+- Support: `supported`
+- Signature: —
+- Constraint: Date.now(), Math.random(), and no-argument new Date() are unavailable
+- Constraint: pass timestamps and randomness through args
+
+<a id="compatibility"></a>
+## whole-script Markdown fence stripping
+
+- Classification: `compatibility-behavior`
+- Support: `compatibility`
+- Signature: —
+- Constraint: accepted for compatibility but not recommended
+
+<a id="model-routes"></a>
+## model routes
+
+- Classification: `dynamic-reference`
+- Support: `supported`
+- Signature: —
+- Constraint: live values must not be copied into static contract data
+- Dynamic reference owner: `model-tier-config`
+- Item shape: `{ name: string; description?: string }`
+- Future lookup connection: `loadModelTierConfig`
+- Live values are intentionally absent from this static reference.
+
+<a id="agent-types"></a>
+## agent types
+
+- Classification: `dynamic-reference`
+- Support: `supported`
+- Signature: —
+- Constraint: live values must not be copied into static contract data
+- Dynamic reference owner: `agent-registry`
+- Item shape: `{ name: string; description?: string }`
+- Future lookup connection: `loadAgentRegistry`
+- Live values are intentionally absent from this static reference.

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,27 @@
+# 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) |
+| 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,11 @@
+# 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) |

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,33 @@
+# Lifecycle, limits, and resume
+
+## Bounds and budget
+
+Set finite bounds that match the work: `maxAgents`, `concurrency`, `agentRetries`, `agentTimeoutMs`, and `tokenBudget` at invocation time; loop and semantic-retry bounds inside the script. 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.
+
+## 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.
+
+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`.

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,15 @@
+# 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 model-tier configuration owns route names. Standard routes are `small`, `medium`, and `big`; 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`.
+
+## 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` > `agentType` model > `tier` > phase model > metadata model > implicit `medium` > session default. Higher priority means selection, not "try this then fall back to the next selector." If the selected model or route is unavailable, execution falls directly to the session default; it does not try lower-priority selectors. Avoid specifying competing selectors unless deliberately overriding a lower-priority default.

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,27 @@
+# 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.
+
+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` > `agentType` model > `tier` > phase model > metadata model > implicit `medium` > session default. An unavailable selected route falls directly to the session default. Use exact `model`, nonstandard `tier`, or `agentType` only when context supplies its name and purpose. Worktree isolation is best-effort. 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.