@signalridge/pi-workflows 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,119 @@
 # Changelog
 
+## 1.6.0
+### Minor Changes
+
+- fabe89a: A workflow now speaks one routing word of its own: **strength**.
+  
+  `agent({ tier })` is gone. A script names `strength: "low" | "medium" | "high"` —
+  this package's own word for how much effort a step deserves — and the new
+  `strengths` setting is the only thing that binds one to an Agent tier. A strength
+  no table defines dispatches with **no tier at all** and takes the agent's ordinary
+  default, so nothing is inferred from spelling at dispatch: the binding is always a
+  table entry.
+  
+  That inference was the bug. The built-ins ask for `low`, and so does the `Explore`
+  agent and everything that names no tier of its own, so pointing `low` at a cheaper
+  model to make a 26-agent fan-out affordable dragged every ordinary search spawn
+  with it. Pointing a *strength* elsewhere does not.
+  
+  A host that has configured nothing gets a shipped default table rather than no
+  mappings: each strength on the catalogue tier of the same name, wherever the host
+  defines one — identity on a stock install, empty on a host whose tiers are called
+  `cheap`/`deep`. It is computed against the live catalogue, so it is never an
+  assertion about someone else's tier names and never complains at run start about
+  configuration nobody wrote. Without it every shipped script's `low`/`medium`
+  distinction would collapse onto pi-subagents' managed `medium` fallback — the
+  *more* expensive rung — and an unconfigured machine would run its fan-outs dearer
+  than before this change.
+  
+  The distinction that makes that safe is that it is a **table, not a fallback
+  rule**. A rule would be unremovable, and re-pricing a fan-out would again mean
+  editing the shared tier. A table is replaced by writing one, a written table that
+  omits `low` leaves it unmapped even where a tier called `low` exists, and `{}` is
+  a real table meaning "map nothing".
+  
+  This is not the retired `workflow.tiers` key. That one carried its own `model` and
+  `thinking`, making it a second model policy behind a second resolver. A value here
+  is a key in the host's one catalogue: pi-subagents still owns every model, every
+  thinking level, and the only `resolveAgentTier()`, and cannot tell a mapped call
+  apart from a spawn that named the key itself. No protocol change.
+  
+  The vocabulary is closed, which buys back what the passthrough used to provide.
+  A word outside the three is a typo, not a strength nobody configured, so it fails
+  before dispatch. With no way for a script name to reach the catalogue, the
+  shipped-vs-user tier rule (`shippedScript`) had nothing left to decide and is
+  removed, along with its `run_created` journal field.
+  
+  The same argument applies one level up, so `agent()` and `checkpoint()` now
+  reject any option name they do not read instead of ignoring it. `tier`, `model`,
+  and `thinking` answer by naming their replacement; anything else lists the legal
+  keys, and a non-object options value is refused rather than reaching a bare
+  `TypeError`. An unknown key is dropped before the call hash is built, so it moves
+  neither the dispatch nor the resume identity: `agent({ strenght: "low" })` would
+  have run every step untiered and replayed that way, and
+  `checkpoint({ headles: "abort" })` would have auto-approved in headless mode
+  instead of aborting. Neither leaves a log line. A script is plain JavaScript
+  authored against this contract, so nothing else was going to catch it. Both key
+  lists are pinned to their interfaces by a `satisfies Record<keyof …>` clause, in
+  both directions.
+  
+  There is deliberately no default strength: a call that names none dispatches with
+  no tier, exactly as an unmapped one does, and the host resolves it the way it
+  resolves every other spawn. A default was tried and is wrong — a tier a call
+  requests outranks the agent type's own, so on a stock install (`medium → medium`)
+  every unlabelled dispatch would have pinned `medium` over whatever the agent
+  declared, overruling `Explore`'s shipped `tier: low` and re-pricing in the wrong
+  direction the one agent this indirection exists to leave alone. Nothing is lost:
+  a script that named no strength stated no opinion, and pi-subagents' ordinary
+  precedence is still user-owned policy.
+  
+  What the table must reach is every call a script did label, and the shipped
+  scripts label all of theirs. The three helpers that dispatch on the script's
+  behalf — `verify`, `judgePanel`, `completenessCheck` — took no strength at all
+  and so could never be re-routed; they now accept one, defaulting to `low`, `low`,
+  and `medium`.
+  
+  Those defaults are an opinion where there was none, and an opinion outranks the
+  host's: a tier a call requests beats `agentTiers.defaultTier`, so on a machine
+  whose default is `high` a `completenessCheck` now runs at whatever `medium` maps
+  to rather than at `high`. That is the price of making the helpers steerable at
+  all — a helper that names no tier can never be pointed anywhere — and the new
+  option is how a script takes it back.
+  
+  Fixes a re-spend bug: `strengths` is deliberately never frozen onto a run, but the
+  resumes the engine starts itself (`/workflows resume`, the provider-limit retry)
+  passed no table, and since a call's identity keys on the tier it requested, every
+  finished call missed its journal entry and re-ran untabled. The engine now reads
+  the current table for those.
+  
+  `/workflows-models` is gone; the table is edited with `/workflows strength`
+  (`[<low|medium|high> <tier>|off]`), which also prints the effective table and the
+  tiers this host defines — the one place both halves are visible. It validates the
+  strength and the target before writing and reports the resolved result rather than
+  echoing the write, so it can no longer claim a change the settings layer dropped.
+  `off` yields to a real host tier of that name, and says so when it does, since a
+  user who typed the documented keyword and got a mapping has to be told which
+  reading won. The view also names where a machine-wide table lives, and — while
+  the shipped default is in force — that the default is identity, so workflow work
+  is still sharing the tiers ordinary spawns use until a tier is defined for it.
+  
+  Settings commands now write project scope instead of the merged view. Previously
+  the first `/effort` or `/workflows-progress` in a project copied every global value
+  and default into the project file, after which that project stopped tracking the
+  global one.
+  
+  `strengths` needs the opposite treatment, because it replaces rather than merges at
+  each level, so `/workflows strength` seeds its write from the table a run would
+  actually use — project, else global, else the shipped default. Built on project
+  scope alone, setting one entry would have discarded an inherited global table, and
+  `off` against an entry the project never wrote would have written nothing and left
+  the mapping standing.
+  
+  One caution the docs now carry: the provider-limit retry resumes on a timer with
+  nobody watching, so a table edited while a run is rate-limit-paused is charged the
+  re-spend above without being asked. Stop the run first if that is not worth it.
+
 ## 1.5.0
 ### Minor Changes
 

package/README.md

@@ -54,9 +54,9 @@ export const meta = {
 
 phase("scan");
 const findings = await parallel([
-  () => 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" }),
+  () => agent("Check for cross-package imports", { label: "imports", strength: "low" }),
+  () => agent("Check for secrets", { label: "secrets", strength: "low" }),
+  () => agent("Check for dead code", { label: "dead-code", strength: "low" }),
 ]);
 
 phase("synthesize");
@@ -77,13 +77,13 @@ user's own LLM and run on the user's own machine.
 
 ### Runtime globals
 
-- `agent(prompt, { label, phase, schema, tier, isolation, thread, agentType, toolset, excludeTools, timeoutMs, retries })`
+- `agent(prompt, { label, phase, schema, strength, 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. 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`.
-  `tier` is the provider-neutral workflow route; `thread` chains sequential turns
+  `strength` 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
@@ -150,9 +150,12 @@ workflow, and the review skill before accepting a topology or recovery change.
 - `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
-  is deliberately no second tier configuration file.
+  `resume`, `rm`, `save <name> [runId]`, and `strength` subcommands.
+- `/workflows strength`: `[<low|medium|high> <tier>|off]` — which Agent tier each
+  workflow strength runs on, and the tiers this host defines. Unconfigured hosts
+  start on a shipped default table (identity, where the host defines the name).
+  The tiers themselves are still configured only in pi-subagents'
+  `/agents → Model tiers`; there is deliberately no second tier configuration file.
 - `/effort` and `/ultracode`: standing `off|high|ultra` effort guidance that auto-arms substantive messages.
 - `/workflows-progress`: `compact|detailed|status|max <N>` controls the persisted live panel.
 - `/deep-research`, `/adversarial-review`, `/code-review`,
@@ -186,52 +189,185 @@ written atomically with a backup.
 
 ## Model routing
 
-`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.
+A workflow speaks one word about cost: **strength**, this package's own name for
+how much effort a step deserves. `low`, `medium`, `high` — that is the whole
+vocabulary, and a script may name nothing else.
 
 ```js
-await agent("summarize this diff", { tier: "low" })
-await agent("design the migration", { tier: "high" })
+await agent("summarize this diff", { strength: "low" })
+await agent("design the migration", { strength: "high" })
+await agent("the ordinary case")                          // no strength: see below
 ```
 
-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.
+There is no default strength. A call that names none dispatches with **no tier**,
+exactly as an unmapped strength does, and pi-subagents resolves it the way it
+resolves any other spawn: the agent type's own frontmatter tier, then
+`agentTiers.defaultTier`. That matters because a tier a call requests outranks
+the agent type's own — so a default strength would have pinned every unlabelled
+call to whatever it mapped to, overruling `Explore`'s shipped `tier: low` and
+re-pricing the one agent this indirection exists to leave alone. Label the calls
+whose cost you mean to steer; leave the rest to the host.
+
+A strength is not an Agent tier. A `strengths` table is the only thing that
+binds one to a tier:
+
+```jsonc
+// <agent dir>/workflows/settings.json, or the per-project settings file
+{ "strengths": { "low": "cheap-search", "high": "deep" } }
+```
+
+**An unmapped strength dispatches with no tier at all** and takes the agent's
+ordinary default — the agent's own frontmatter tier, then the host's configured
+default. `{}` is a real table meaning exactly that for every strength.
+
+### The default table
+
+A host that has configured nothing does not get "no mappings". It gets a table
+this package ships: each strength on the catalogue tier of the same name,
+**wherever the host defines one**. On a stock install that is
+`low → low, medium → medium, high → high`; on a host whose tiers are called
+`cheap` and `deep` it is empty, and every strength is unmapped. It is computed
+against the live catalogue rather than hardcoded, so it is never an assertion
+about someone else's tier names and never produces a start-up complaint about
+configuration you did not write.
+
+Without it, every shipped script's `low`/`medium` distinction would collapse
+onto pi-subagents' managed default — which is the *more* expensive rung, so an
+unconfigured machine would run its fan-outs dearer, not cheaper.
+
+That it is a **table and not a fallback rule** is the whole design. A rule
+saying "an unmapped strength runs on the tier of the same name" would be
+unremovable, so making a 26-agent fan-out cheaper would still mean editing tier
+`low` itself — dragging the `Explore` agent and everything else that names it. A
+table is replaced by writing one, and a written table that omits `low` leaves it
+unmapped even on a host that defines a tier called `low`. Nothing is ever
+inferred from spelling at dispatch: the binding is always a table entry.
+
+So `low → low` in a written table is a real entry and not a no-op — a table you
+write replaces the default outright, so the entries you leave out are unmapped,
+not inherited.
+
+### Editing it
+
+`/workflows strength` edits the table and also prints the tiers this host
+defines — the one place both halves are visible, since the strengths come from
+this package and the tiers from pi-subagents:
+
+```
+/workflows strength              # show the effective table and the host's tiers
+/workflows strength low cheap    # run workflow strength `low` on Agent tier `cheap`
+/workflows strength low off      # unmapped; back to the agent's own default
+```
+
+Edits land in **this project's** settings, like every other setting this package
+owns. Because the table replaces rather than merges at each level, the command
+seeds the write from the table a run would actually use — the project file, else
+global, else the shipped default — so setting one entry cannot silently discard
+the rest, and `off` clears a mapping this project never wrote. The write is
+therefore a full copy of the current table into the project; edit
+`<agent dir>/workflows/settings.json` by hand for a machine-wide table.
+
+Any key the host's catalogue defines is a legal target — an existing tier, or a
+profile added for exactly this purpose. There is no shortlist and no naming
+convention: the target is checked against the live catalogue at run start, so a
+profile added to `subagents.json` is usable the moment it exists. One hop, never
+chained. An entry whose tier the host does not define is reported once at run
+start and ignored, leaving that strength unmapped — a stale entry costs the
+redirect, not every workflow on the machine.
+
+This is not the retired `workflow.tiers` key and must not become it. That one
+carried its own `model` and `thinking` values, which made it a second model
+policy resolved by a second resolver. A value here is a **key in the host's one
+catalogue**: pi-subagents still owns every model, every thinking level, and the
+only `resolveAgentTier()`, and cannot tell a mapped call apart from a spawn that
+named the key itself.
+
+There is no per-call `model`, `thinking`, or `tier`, and `meta`/phase metadata
+may not carry them either. A strength is the only model policy a workflow can
+express, which is what keeps a script from pinning a vendor the host did not
+choose.
+
+The vocabulary is closed so that a word outside it is a *typo* rather than a
+strength nobody configured: `agent({ strength: "lowe" })` fails before any
+dispatch instead of silently running at the default.
+
+The same argument applies one level up, to the option *name*. `agent()` and
+`checkpoint()` reject any key they do not read, rather than ignoring it:
+
+```js
+await agent("x", { tier: "low" })      // → name a strength instead: one of low, medium, high
+await agent("x", { model: "…" })       // → a strength is the only model policy a workflow can express
+await agent("x", { strenght: "low" })  // → valid options are: label, phase, schema, strength, …
+```
+
+An unknown key is dropped before the call hash is built, so it changes neither
+the dispatch nor the resume identity — the run would simply spend at a policy
+nobody chose, and a resume would replay it without noticing. A script is plain
+JavaScript authored against this contract, so there is no other gate: a
+misspelled option would run every step untiered, and a misspelled
+`checkpoint({ headles: "abort" })` would auto-approve in headless mode instead
+of aborting.
+
+### Helpers that dispatch for you
+
+`verify()`, `judgePanel()`, and `completenessCheck()` spawn agents on the
+script's behalf, so the script cannot label those calls. Each carries a
+documented default and takes an override, which keeps every dispatch inside the
+vocabulary:
+
+```js
+await verify(finding)                              // reviewers run at "low"
+await verify(finding, { strength: "high" })        // unless you say otherwise
+await completenessCheck(args, results)             // one open-ended read: "medium"
+```
+
+These defaults are an opinion, and an opinion outranks the host's: a tier a call
+requests beats `agentTiers.defaultTier`, so on a machine whose default is `high`
+a `completenessCheck` now runs at whatever `medium` maps to rather than at
+`high`. That is the trade for making the helpers re-routable at all — they
+previously named no tier and could never be steered — and the override above is
+how a script takes it back.
+
+### Resume
+
+The table is read fresh at each start and resume — including the resumes the
+engine starts itself, `/workflows resume` and the provider-limit retry — never
+frozen onto a run.
+
+Resume identity keys a call on the tier it will actually request, so editing the
+table and resuming re-routes the calls that have not run — and **also re-runs
+the finished calls whose strength moved**, plus everything after the first such
+miss, because their cached answers came from a different tier. Re-routing
+mid-run is therefore a re-spend; if the point of the edit was to spend less,
+start a new run instead of resuming one that is mostly done. The provider-limit
+retry resumes on a timer with no one watching, so a table edited while a run is
+rate-limit-paused is charged the same way without being asked — stop that run
+before editing if the re-spend is not worth it. A nested
+`workflow()` boundary folds the table into its own key for the same reason: the
+value it caches for the whole child frame would otherwise survive a change that
+re-routes the child.
+
+Fresh installs of pi-subagents ship `low`/`medium`/`high` tier profiles, all
+inheriting their model — which is what the default table above resolves against,
+so the built-ins run on a new machine, at their own strengths, with no
+configuration. A managed call that still names no tier falls back to `medium`;
+that is where an unmapped strength lands. The 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 — which
+an unmapped strength can reach.
+
+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 the tier catalogue resolve in pi-subagents; the workflow package supplies only a tier key, avoiding a second model/thinking policy.
+- **Agent registry and tier catalogue ownership.** `agentType` and the tier catalogue resolve in pi-subagents; the workflow package supplies only a tier key its own `strengths` table chose, 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 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.5.0",
+  "version": "1.6.0",
   "description": "Deterministic JavaScript orchestration workflows backed by pi-subagents managed spawning.",
   "type": "module",
   "license": "MIT",

package/skills/workflow-authoring/SKILL.md

@@ -2,7 +2,7 @@
 name: workflow-authoring
 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.5.0"
+  version: "1.6.0"
 ---
 
 # Workflow authoring
@@ -28,12 +28,21 @@ JavaScript.
 - 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
+- Route an agent call with `strength: "low" | "medium" | "high"` — this
+  package's own word for how much effort a step deserves, and the only routing
+  word a workflow has. It is **not** an agent-tier key: a `strengths` table
+  alone binds a strength to a tier — the user's, or the shipped default on a
+  host that configured none — and a strength no table defines dispatches with no
+  tier and takes the agent's own default. So name the effort the step deserves
+  and never reach for a catalogue name; a word outside the three is rejected
+  before dispatch, as is `tier:` itself. There is no default: omitting
+  `strength` dispatches with no tier and lets the agent type's own tier stand,
+  so label the calls whose cost you mean to steer and leave the rest alone.
+  There is no per-call `model`/`thinking`/`tier`, and none may
+  appear in workflow meta or phase profiles. `agent()` and `checkpoint()` reject
+  any option name they do not read rather than ignoring it, so pass only the
+  documented keys. Never guess an 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`.
@@ -56,7 +65,9 @@ JavaScript.
    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.
+   `completenessCheck` with explicit bounds. These dispatch on your behalf, so
+   pass `strength` when the default (`low`, or `medium` for
+   `completenessCheck`) is not the effort that gate deserves.
 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.
@@ -176,8 +187,8 @@ Before shipping a workflow change:
 - 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;
+  signature, default, or support boundary is disputed; remember that a strength
+  is this package's own vocabulary, bound to a host tier only by the user's
+  `strengths` table, while model/thinking resolution stays in pi-subagents;
 - ensure every package-relative example/reference link remains inside the
   publishable package.

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

@@ -2,7 +2,7 @@
 # Workflow capability index
 
 Contract format: `2.0.0`<br>
-Contract content / skill / extension: `1.5.0`
+Contract content / skill / extension: `1.6.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,15 +11,15 @@ 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>`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 |
+| 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>`strength`: "low" \| "medium" \| "high" (optional); default: no tier is sent; 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 |
+| 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)<br>`strength`: "low" \| "medium" \| "high" (optional); default: "low" |
+| 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<br>`strength`: "low" \| "medium" \| "high" (optional); default: "low" |
 | loopUntilDry | runtime-global | `loopUntilDry({ round, key?, consecutiveEmpty?, maxRounds? }) => Promise<unknown[]>` | `round`: (roundIndex) => unknown[]; default: required<br>`key`: (item) => string (optional); default: JSON.stringify<br>`consecutiveEmpty`: number (optional); default: 2<br>`maxRounds`: number (optional); default: 50 |
-| completenessCheck | runtime-global | `completenessCheck(taskArgs, results) => Promise<{ complete, missing? } \| null>` | — |
+| completenessCheck | runtime-global | `completenessCheck(taskArgs, results, options?) => Promise<{ complete, missing? } \| null>` | `strength`: "low" \| "medium" \| "high" (optional); default: "medium" |
 | retry | runtime-global | `retry(thunk, options?) => Promise<unknown>` | `attempts`: number (optional); default: 3<br>`until`: (result) => boolean (optional); default: accept first result |
 | gate | runtime-global | `gate(thunk, validator, options?) => Promise<{ ok, value, attempts }>` | `attempts`: number (optional); default: 3 |
 | checkpoint | runtime-global | `checkpoint(prompt, options?) => Promise<unknown>` | `default`: unknown (optional); default: true when no UI and omitted<br>`headless`: "default" \| "abort" (optional); default: "default"<br>`kind`: "confirm" \| "input" \| "select" (optional); default: "confirm"<br>`choices`: string[] (optional)<br>`timeoutMs`: number (optional) |

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

@@ -2,7 +2,7 @@
 # Exhaustive workflow capability facts
 
 Contract format: `2.0.0`<br>
-Contract content / skill / extension: `1.5.0`
+Contract content / skill / extension: `1.6.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.
 
@@ -16,7 +16,7 @@ Every exact fact below is projected from the installed extension's capability co
 - `label`: string (optional); default: derived from phase and call count
 - `phase`: string (optional); default: current phase
 - `schema`: plain JSON Schema (optional)
-- `tier`: agent tier key (optional); default: the agent's own tier, else agentTiers.defaultTier
+- `strength`: "low" \| "medium" \| "high" (optional); default: no tier is sent; the agent's own tier, else agentTiers.defaultTier
 - `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
@@ -29,11 +29,15 @@ Every exact fact below is projected from the installed extension's capability co
 - Constraint: resume replays only the longest unchanged prefix; the first miss and every later call execute live
 - Constraint: replayed calls do not consume the real-dispatch maxAgents or token/phase budgets
 - Constraint: spawnKeys rotate by generation on resume so pi-subagents never raises a fingerprint conflict
-- Constraint: tier names a key in the host's agentTiers catalogue; a key it does not define is rejected before dispatch
+- Constraint: strength is this package's own vocabulary, not an agentTiers key; a word outside low/medium/high is rejected before dispatch
+- Constraint: a strengths table alone binds a strength to an agent tier; an unmapped strength dispatches with no tier and takes the agent's own default
+- Constraint: a call that names no strength also dispatches with no tier; there is no default strength, so an unlabelled call never outranks the agent type's own tier
+- Constraint: an unconfigured host uses a shipped default table: each strength on the catalogue tier of the same name, where the host defines one
 - Constraint: resolveAgentTier in pi-subagents owns model, thinking, clamping, availability, and the resolution snapshot
-- Constraint: there is no per-call model or thinking: a tier is the only model policy a workflow can express
+- Constraint: there is no per-call model, thinking, or tier: a strength is the only model policy a workflow can express
 - Constraint: same-thread calls must be sequential and preserve a stable workflow thread name
 - Constraint: threads cannot be combined with worktree isolation
+- Constraint: an option name outside this list is rejected before dispatch, not ignored; tier, model, and thinking name their replacement
 
 <a id="runtime-global-parallel"></a>
 ## parallel
@@ -91,6 +95,7 @@ Every exact fact below is projected from the installed extension's capability co
 - `reviewers`: number (optional); default: 2
 - `threshold`: number (optional); default: 0.5
 - `lens`: string \| string[] (optional)
+- `strength`: "low" \| "medium" \| "high" (optional); default: "low"
 - Constraint: threshold comparison is inclusive; real is false when no reviewer succeeds
 
 <a id="runtime-global-judgepanel"></a>
@@ -101,6 +106,7 @@ Every exact fact below is projected from the installed extension's capability co
 - Signature: `judgePanel(attempts, options?) => Promise<{ index, attempt, score, judgments } \| undefined>`
 - `judges`: number (optional); default: 3
 - `rubric`: string (optional); default: overall quality and correctness
+- `strength`: "low" \| "medium" \| "high" (optional); default: "low"
 - Constraint: highest mean score wins with stable input index as the tie-break; empty input returns undefined
 
 <a id="runtime-global-loopuntildry"></a>
@@ -120,7 +126,8 @@ Every exact fact below is projected from the installed extension's capability co
 
 - Classification: `runtime-global`
 - Support: `supported`
-- Signature: `completenessCheck(taskArgs, results) => Promise<{ complete, missing? } \| null>`
+- Signature: `completenessCheck(taskArgs, results, options?) => Promise<{ complete, missing? } \| null>`
+- `strength`: "low" \| "medium" \| "high" (optional); default: "medium"
 - Constraint: only the first 4,000 characters of serialized result evidence are sent to the critic
 
 <a id="runtime-global-retry"></a>
@@ -155,6 +162,7 @@ Every exact fact below is projected from the installed extension's capability co
 - `timeoutMs`: number (optional)
 - Constraint: consumes one agent slot and no tokens
 - Constraint: journaled answers replay only within an unchanged resume prefix
+- Constraint: an option name outside this list is rejected rather than ignored, since a dropped headless silently auto-approves
 
 <a id="runtime-global-log"></a>
 ## log

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

@@ -8,7 +8,7 @@ Start from the symptom, then reproduce through the real workflow runtime with de
 | `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 or thinking is used | The call named no tier and fell to a default, or named one whose profile is not what you expected | [registry ownership](registry-ownership.md#priority) |
+| Wrong model or thinking is used | The call's strength is unmapped and fell to the agent's default, or the active `strengths` table — the user's, or the shipped default — points it at a profile that is not what you expected | [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) |

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

@@ -4,5 +4,5 @@ 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`. |
+| `verify(item, { reviewers: number, threshold: number, lens: string | string[], strength })` | Defaults: 2 reviewers, inclusive `0.5`, one lens or a cycled array, and `strength: "low"` — reviewers are numerous and narrow, and the vote carries the gate rather than any one reviewer's depth. 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, strength })` | Defaults: 3 judges, `"overall quality and correctness"`, and `strength: "low"`. 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

@@ -4,9 +4,9 @@ Model routes and agent types are dynamic references. Their shape and owner are d
 
 ## Model routes
 
-pi-subagents owns the agent-tier catalogue; a workflow names a key from it and nothing else. Available tier names depend on active configuration and are intentionally absent from static skill files — read them from the destination context.
+pi-subagents owns the agent-tier catalogue. A workflow never names a key from it: a script names a *strength* (`low`/`medium`/`high`), and the user's `strengths` table is the only thing that binds one to a tier. Tier names depend on active configuration and are intentionally absent from static skill files; you do not need them, because you never write one.
 
-A name a script writes is not a claim that the name exists. Scripts that ship with this package name `low`/`medium`/`high` — the profiles a fresh install receives — and a host that does not define one of those drops it in favour of that host's default, with a log line. A script you write is held to the stricter rule: an undefined tier is a typo in a catalogue you own, so it is rejected before dispatch rather than rerouted. Write the tier you mean for the host you are targeting; do not copy `low`/`medium`/`high` in on the assumption that every machine has them.
+A strength is a statement about the work, not a claim about the host. Every script — shipped or yours — names the same three, and there is no shipped/user distinction, because a strength can never reach the catalogue by itself: the binding is always an entry in a `strengths` table. A host that configured none uses the shipped default table, which is identity wherever the host defines a tier of the same name, so a stock machine honours your `low`/`medium` distinctions without configuration and a host with differently-named tiers leaves every strength unmapped. A user table replaces that default outright, and a strength it omits is unmapped even where a same-named tier exists — which is what lets workflow work be re-priced without touching the tier every ordinary spawn also names.
 
 ## Agent types
 
@@ -14,6 +14,6 @@ The agent registry owns agent-type names and their bound instructions, tools, Ag
 
 ## Priority
 
-A call's `tier` takes precedence over an agent type's own tier default, which takes precedence over `agentTiers.defaultTier`. `resolveAgentTier()` in pi-subagents then resolves model, thinking, clamping, availability, and the immutable snapshot as one decision. Neither a call, nor workflow meta, nor a phase may carry model or thinking fields.
+A call's strength resolves through the user's `strengths` table into at most one tier key. That key, when there is one, takes precedence over an agent type's own tier default, which takes precedence over `agentTiers.defaultTier`. A call that names no strength, or one whose strength the table does not define, sends no key and leaves that precedence to the host — which is why there is no default strength: one would overrule every agent type's own tier on calls the script never meant to route. `resolveAgentTier()` in pi-subagents then resolves model, thinking, clamping, availability, and the immutable snapshot as one decision. Neither a call, nor workflow meta, nor a phase may carry model, thinking, or tier fields.
 
-Unavailability is fail-closed: pi-subagents names the tier and does not silently run a different model. A managed call with no tier and no applicable default is rejected rather than inheriting the parent session.
+Unavailability is fail-closed: pi-subagents names the tier and does not silently run a different model. A managed call with no tier and no applicable default is rejected rather than inheriting the parent session — which an unmapped strength can reach on a host whose default has been cleared.