@signalridge/pi-workflows 1.5.0 → 1.6.0

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

@@ -22,9 +22,10 @@ Review author-visible behavior, not formatting preferences. When behavior depend
 
 - Does JavaScript consume structured fields only after a small plain JSON Schema guarantees them?
 - Does synthesis receive complete coverage and failure ledgers?
-- Does every `tier` name a key the destination host actually defines, rather than a guessed one?
-- Is the tier the only model/thinking policy source, via pi-subagents' `resolveAgentTier()`?
-- Did every tier or agent-type name come from context with a name and purpose?
+- Does every call name a `strength` from `low`/`medium`/`high`, chosen for the effort the step deserves rather than copied from a tier name?
+- Does every helper that dispatches for you (`verify`, `judgePanel`, `completenessCheck`) either take its documented default deliberately or pass an explicit `strength`?
+- Is the strength the only model/thinking policy source, resolved through the active `strengths` table and then pi-subagents' `resolveAgentTier()`?
+- Did every agent-type name come from context with a name and purpose?
 
 ## Lifecycle
 

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

@@ -17,7 +17,7 @@ The runtime supplies `agent`, `parallel`, `pipeline`, `orchestrate`, `workflow`,
 
 ## Data and failure
 
-Call `agent(prompt, { label, schema?, tier? })`; it returns text, a schema-validated value, or recoverable `null`. `tier` names a key in the host's agent-tier catalogue. Nonrecoverable limit, validation, budget, unknown-tier, and unavailable-tier failures throw. Record each intended work ID before filtering. A `null` means missing coverage, never a negative finding.
+Call `agent(prompt, { label, schema?, strength? })`; it returns text, a schema-validated value, or recoverable `null`. `strength` is `low`/`medium`/`high` and has no default — omitting it sends no tier. Nonrecoverable limit, validation, budget, unknown-strength, and unavailable-tier 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.
 
@@ -25,6 +25,6 @@ When JavaScript reads fields, pass a small plain JSON Schema. Schema noncomplian
 
 ## Routing and support
 
-`tier` is a key in the host's agent-tier catalogue, not a model ID. The catalogue and its names belong to the user running the workflow; read the available keys from the destination context rather than assuming any particular name exists. A tier this host does not define is rejected before dispatch — only the scripts shipped with this package reroute to the host default instead, because they cannot know the catalogue they will land in. pi-subagents' `resolveAgentTier()` alone resolves the final model, thinking, clamping, availability, and snapshot. A tier the host does not define is rejected before dispatch. Omitting `tier` uses the agent's own tier, then `agentTiers.defaultTier`; a host whose default has been cleared rejects the call instead of inheriting the parent model. There is no per-call model or thinking, and workflow meta and phases may not carry them either. Worktree isolation remains owned by pi-subagents. See [registry ownership](registry-ownership.md).
+`strength` is this package's own vocabulary — `low`, `medium`, `high` — not a model ID and not an agent-tier key. A `strengths` table is the only thing that binds a strength to a tier: the user's, or a shipped default (identity, wherever the host defines a tier of the same name) on a host that configured none. A strength no table defines dispatches with no tier and takes the agent's own default, then `agentTiers.defaultTier`; a call that names no strength takes that same untiered path, because a default strength would have outranked the agent type's own tier on every unlabelled call. A word outside the three is rejected before dispatch, and so is any option name `agent()` does not read — `tier`, `model`, and `thinking` answer by naming their replacement, anything else lists the legal keys. `checkpoint()` gates its own options the same way. pi-subagents' `resolveAgentTier()` alone resolves the final model, thinking, clamping, availability, and snapshot. A host whose default has been cleared rejects an untiered call instead of inheriting the parent model. There is no per-call model, thinking, or tier, and workflow meta and phases may not carry them either. Worktree isolation 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

@@ -6,7 +6,7 @@ Preserve candidate or work identity outside helper results that may omit failed
 
 | 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. |
+| `completenessCheck(args, results, { strength })` | Returns `{ complete, missing? }` or recoverable `null`. Defaults to `strength: "medium"`, not `low` like the other gates: one call, no vote to average over, and an open-ended read of the whole task. 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

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

@@ -9,5 +9,5 @@ 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 tier keys and agent types from destination context; both come from the destination host's configuration, and static docs intentionally contain no live catalogue entries.
+4. Re-resolve agent types from destination context; they come from the destination host's configuration, and static docs intentionally contain no live registry entries. Strengths need no re-resolution — the vocabulary is fixed and the mapping belongs to the destination, whether that is the user's table or the shipped default.
 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

@@ -2,7 +2,7 @@
 name: workflow-patterns
 description: Choose and run one of Pi's built-in multi-agent workflows for research, adversarial review, code review, multi-perspective analysis, or codebase auditing. Use when the request matches a named pattern; use workflow-authoring instead for a new script or custom topology.
 metadata:
-  version: "1.5.0"
+  version: "1.6.0"
 ---
 
 # Built-in workflow patterns

package/skills/workflow-review/SKILL.md

@@ -2,7 +2,7 @@
 name: workflow-review
 description: Audit an existing Pi JavaScript workflow for topology, prompt/data flow, limits, failure handling, cancellation, resume safety, and publication compatibility. Use when reviewing or debugging a workflow script or saved run; do not use to run a standard named workflow.
 metadata:
-  version: "1.5.0"
+  version: "1.6.0"
 ---
 
 # Workflow review

package/src/builtins.ts

@@ -55,7 +55,7 @@ const plan = await agent(
   'You are planning web research for this question:\\n' + question +
   '\\n\\nProduce ' + angles + ' diverse, specific search queries that together cover the question from different angles. ' +
   'Use your web search tools when helpful to refine them.',
-  { label: 'plan queries', tier: 'medium', schema: { type: 'object', properties: { queries: { type: 'array', items: { type: 'string' } } }, required: ['queries'] } }
+  { label: 'plan queries', strength: 'medium', schema: { type: 'object', properties: { queries: { type: 'array', items: { type: 'string' } } }, required: ['queries'] } }
 )
 const planned = plan && Array.isArray(plan.queries) ? plan.queries.filter((q) => typeof q === 'string' && q.trim().length > 0) : []
 const queries = (planned.length > 0 ? planned : [question]).slice(0, angles)
@@ -67,7 +67,7 @@ const gathered = await parallel(queries.map((q, i) => () =>
     '\\n\\nSteps: (1) run a web search for the query; (2) fetch the most relevant result URLs; ' +
     '(3) extract concrete, verifiable factual claims, each tagged with the exact source URL it came from. ' +
     'Do NOT invent sources or claims — report only what the fetched pages actually say.',
-    { label: 'research ' + (i + 1), tier: 'low', schema: { type: 'object', properties: { sources: { type: 'array', items: { type: 'object', properties: { url: { type: 'string' }, claims: { type: 'array', items: { type: 'string' } } }, required: ['url', 'claims'] } } }, required: ['sources'] } }
+    { label: 'research ' + (i + 1), strength: 'low', schema: { type: 'object', properties: { sources: { type: 'array', items: { type: 'object', properties: { url: { type: 'string' }, claims: { type: 'array', items: { type: 'string' } } }, required: ['url', 'claims'] } } }, required: ['sources'] } }
   )
 ))
 const allSources = gathered.filter(Boolean).flatMap((g) => (g && g.sources) || [])
@@ -77,7 +77,7 @@ const verdict = await agent(
   'Cross-check these research sources. Group claims that assert the same fact across different source URLs. ' +
   'Keep a claim only if it is supported by at least ' + minSupport + ' distinct source URLs OR by one clearly authoritative source. ' +
   'Discard claims found in a single weak source or that conflict with others.\\n\\nSOURCES JSON:\\n' + JSON.stringify(allSources),
-  { label: 'cross-check', tier: 'medium', schema: { type: 'object', properties: { supported: { type: 'array', items: { type: 'object', properties: { claim: { type: 'string' }, sources: { type: 'array', items: { type: 'string' } } }, required: ['claim', 'sources'] } }, discarded: { type: 'array', items: { type: 'string' } } }, required: ['supported'] } }
+  { label: 'cross-check', strength: 'medium', schema: { type: 'object', properties: { supported: { type: 'array', items: { type: 'object', properties: { claim: { type: 'string' }, sources: { type: 'array', items: { type: 'string' } } }, required: ['claim', 'sources'] } }, discarded: { type: 'array', items: { type: 'string' } } }, required: ['supported'] } }
 )
 
 phase('Report')
@@ -85,7 +85,7 @@ const report = await agent(
   'Write a concise, well-structured research report that answers the question using ONLY the supported claims below. ' +
   'Cite source URLs inline next to each claim. If the evidence is thin, say so explicitly.\\n\\n' +
   'QUESTION: ' + question + '\\n\\nSUPPORTED CLAIMS JSON:\\n' + JSON.stringify((verdict && verdict.supported) || []),
-  { label: 'write report', tier: 'medium' }
+  { label: 'write report', strength: 'medium' }
 )
 
 return { question, queries, supported: (verdict && verdict.supported) || [], report }`;
@@ -107,7 +107,7 @@ const threshold = (args && args.threshold) || 0.5
 phase('Investigate')
 const investigation = await agent(
   'Investigate the following and list concrete, individually-checkable findings:\\n' + task,
-  { label: 'investigate', tier: 'medium', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }
+  { label: 'investigate', strength: 'medium', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }
 )
 const findings = (investigation && Array.isArray(investigation.findings) ? investigation.findings : [])
 
@@ -118,7 +118,7 @@ const judged = await parallel(findings.map((f, i) => () =>
       'You are a skeptical reviewer. Try to REFUTE this finding for the task below. ' +
       'Default to real=false when uncertain. Investigate with the available tools if needed.\\n\\n' +
       'TASK: ' + task + '\\nFINDING: ' + f,
-      { label: 'refute ' + (i + 1) + '.' + (r + 1), tier: 'low', schema: { type: 'object', properties: { real: { type: 'boolean' }, reason: { type: 'string' } }, required: ['real'] } }
+      { label: 'refute ' + (i + 1) + '.' + (r + 1), strength: 'low', schema: { type: 'object', properties: { real: { type: 'boolean' }, reason: { type: 'string' } }, required: ['real'] } }
     )
   )).then((votes) => {
     const valid = votes.filter(Boolean)
@@ -134,7 +134,7 @@ const report = await agent(
   'Synthesize the surviving findings into a concise review. For each finding, note the skeptic agreement ' +
   '(realVotes/totalVotes). Do not include findings that failed the refutation pass.\\n\\n' +
   'TASK: ' + task + '\\n\\nSURVIVING FINDINGS JSON:\\n' + JSON.stringify(survivors),
-  { label: 'consensus report', tier: 'medium' }
+  { label: 'consensus report', strength: 'medium' }
 )
 
 return { findings, judged: judged.filter(Boolean), survivors, report }`;
@@ -154,13 +154,13 @@ const diffSource = (args && args.diffSource) || 'provided diff'
 
 phase('Scan')
 const finders = await parallel([
-  () => agent('You are a correctness reviewer. Find bugs, race conditions, error-handling gaps, and edge-case failures in this diff.\\n\\n' + diff, { label: 'correctness', tier: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
-  () => agent('You are a reuse reviewer. Find duplicated logic, reinvented wheels, and missed opportunities to reuse existing code or libraries.\\n\\n' + diff, { label: 'reuse', tier: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
-  () => agent('You are a simplification reviewer. Find over-engineering, unnecessary complexity, and simpler alternatives.\\n\\n' + diff, { label: 'simplification', tier: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
-  () => agent('You are an efficiency reviewer. Find performance problems, avoidable allocations, and scaling risks.\\n\\n' + diff, { label: 'efficiency', tier: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
-  () => agent('You are an architecture reviewer. Assess the change at the right altitude: design fit, layering, boundaries, and future maintenance.\\n\\n' + diff, { label: 'altitude', tier: 'medium', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
-  () => agent('You are a security reviewer. Find trust-boundary, injection, secret-leak, permission, and unsafe-input risks in this diff.\\n\\n' + diff, { label: 'security', tier: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
-  () => agent('You are a testability reviewer. Find missing regression tests, observability gaps, and rollout/recovery risks in this diff.\\n\\n' + diff, { label: 'testability', tier: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
+  () => agent('You are a correctness reviewer. Find bugs, race conditions, error-handling gaps, and edge-case failures in this diff.\\n\\n' + diff, { label: 'correctness', strength: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
+  () => agent('You are a reuse reviewer. Find duplicated logic, reinvented wheels, and missed opportunities to reuse existing code or libraries.\\n\\n' + diff, { label: 'reuse', strength: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
+  () => agent('You are a simplification reviewer. Find over-engineering, unnecessary complexity, and simpler alternatives.\\n\\n' + diff, { label: 'simplification', strength: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
+  () => agent('You are an efficiency reviewer. Find performance problems, avoidable allocations, and scaling risks.\\n\\n' + diff, { label: 'efficiency', strength: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
+  () => agent('You are an architecture reviewer. Assess the change at the right altitude: design fit, layering, boundaries, and future maintenance.\\n\\n' + diff, { label: 'altitude', strength: 'medium', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
+  () => agent('You are a security reviewer. Find trust-boundary, injection, secret-leak, permission, and unsafe-input risks in this diff.\\n\\n' + diff, { label: 'security', strength: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
+  () => agent('You are a testability reviewer. Find missing regression tests, observability gaps, and rollout/recovery risks in this diff.\\n\\n' + diff, { label: 'testability', strength: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
 ])
 const candidates = finders.filter(Boolean).flatMap((f) => (f && f.findings) || [])
 
@@ -168,7 +168,7 @@ phase('Verify')
 const verified = await parallel(candidates.map((finding, i) => () =>
   agent('You are a skeptical verifier. For this candidate finding, check whether it is a REAL issue in the diff. ' +
     'Default to real=false when uncertain.\\n\\nCANDIDATE: ' + finding + '\\n\\nDIFF:\\n' + diff,
-    { label: 'verify ' + (i + 1), tier: 'low', schema: { type: 'object', properties: { real: { type: 'boolean' }, reason: { type: 'string' } }, required: ['real'] } })
+    { label: 'verify ' + (i + 1), strength: 'low', schema: { type: 'object', properties: { real: { type: 'boolean' }, reason: { type: 'string' } }, required: ['real'] } })
 ))
 
 phase('Report')
@@ -179,7 +179,7 @@ const report = await agent(
   'Write a ranked code review report for this diff (' + diffSource + '). ' +
   'Include only verified findings, ordered by severity, each with a concrete location and fix suggestion.\\n\\n' +
   'VERIFIED FINDINGS JSON:\\n' + JSON.stringify(ranked),
-  { label: 'final report', tier: 'medium' }
+  { label: 'final report', strength: 'medium' }
 )
 
 return { candidates, ranked, report }`;
@@ -199,13 +199,13 @@ const perspectives = (args && Array.isArray(args.perspectives) && args.perspecti
 phase('Perspectives')
 const views = await parallel(perspectives.map((p, i) => () =>
   agent('Evaluate this topic from the perspective of: ' + p + '. Be concrete and specific; note risks, trade-offs, and what matters most from this angle.\\n\\nTOPIC: ' + topic,
-    { label: 'perspective ' + (i + 1), tier: 'low', schema: { type: 'object', properties: { angle: { type: 'string' }, points: { type: 'array', items: { type: 'string' } }, risks: { type: 'array', items: { type: 'string' } } }, required: ['angle', 'points', 'risks'] } })
+    { label: 'perspective ' + (i + 1), strength: 'low', schema: { type: 'object', properties: { angle: { type: 'string' }, points: { type: 'array', items: { type: 'string' } }, risks: { type: 'array', items: { type: 'string' } } }, required: ['angle', 'points', 'risks'] } })
 ))
 
 phase('Synthesis')
 const synthesis = await agent(
   'Synthesize these perspectives into a balanced assessment. Identify where perspectives agree, where they conflict, and give a bottom-line recommendation with the key trade-offs.\\n\\nTOPIC: ' + topic + '\\n\\nPERSPECTIVES JSON:\\n' + JSON.stringify(views.filter(Boolean)),
-  { label: 'synthesis', tier: 'medium' }
+  { label: 'synthesis', strength: 'medium' }
 )
 
 return { views: views.filter(Boolean), synthesis }`;
@@ -229,21 +229,21 @@ const map = await agent(
   'Explore the codebase at ' + root + ' and produce a structural map: top-level modules, entry points, ' +
   'data flow, and where complexity concentrates. Use the available file tools.\\n' +
   (focus ? 'Focus/checks requested: ' + focus + '\\n' : ''),
-  { label: 'map', tier: 'medium', schema: { type: 'object', properties: { modules: { type: 'array', items: { type: 'object', properties: { name: { type: 'string' }, purpose: { type: 'string' }, risk: { type: 'string' } }, required: ['name', 'purpose'] } }, entryPoints: { type: 'array', items: { type: 'string' } }, complexityHotspots: { type: 'array', items: { type: 'string' } } }, required: ['modules'] } }
+  { label: 'map', strength: 'medium', schema: { type: 'object', properties: { modules: { type: 'array', items: { type: 'object', properties: { name: { type: 'string' }, purpose: { type: 'string' }, risk: { type: 'string' } }, required: ['name', 'purpose'] } }, entryPoints: { type: 'array', items: { type: 'string' } }, complexityHotspots: { type: 'array', items: { type: 'string' } } }, required: ['modules'] } }
 )
 
 phase('Audit')
 const audits = await parallel([
-  () => agent('Audit this codebase for correctness risks: error handling, boundary conditions, concurrency, security. Use file tools.\\n\\nSTRUCTURE:\\n' + JSON.stringify(map), { label: 'correctness', tier: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } }, severity: { type: 'string' } }, required: ['findings'] } }),
-  () => agent('Audit this codebase for maintainability: coupling, duplication, naming, test coverage, documentation. Use file tools.\\n\\nSTRUCTURE:\\n' + JSON.stringify(map), { label: 'maintainability', tier: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } }, severity: { type: 'string' } }, required: ['findings'] } }),
-  () => agent('Audit this codebase for operational health: dependencies, build, deployment, observability, secrets handling. Use file tools.\\n\\nSTRUCTURE:\\n' + JSON.stringify(map), { label: 'operations', tier: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } }, severity: { type: 'string' } }, required: ['findings'] } }),
+  () => agent('Audit this codebase for correctness risks: error handling, boundary conditions, concurrency, security. Use file tools.\\n\\nSTRUCTURE:\\n' + JSON.stringify(map), { label: 'correctness', strength: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } }, severity: { type: 'string' } }, required: ['findings'] } }),
+  () => agent('Audit this codebase for maintainability: coupling, duplication, naming, test coverage, documentation. Use file tools.\\n\\nSTRUCTURE:\\n' + JSON.stringify(map), { label: 'maintainability', strength: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } }, severity: { type: 'string' } }, required: ['findings'] } }),
+  () => agent('Audit this codebase for operational health: dependencies, build, deployment, observability, secrets handling. Use file tools.\\n\\nSTRUCTURE:\\n' + JSON.stringify(map), { label: 'operations', strength: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } }, severity: { type: 'string' } }, required: ['findings'] } }),
 ])
 
 phase('Report')
 const report = await agent(
   'Write a codebase health audit report: overall health score, ranked findings across dimensions with concrete locations, ' +
   'and a prioritized remediation roadmap.\\n\\nSTRUCTURE:\\n' + JSON.stringify(map) + '\\n\\nAUDITS JSON:\\n' + JSON.stringify(audits.filter(Boolean)),
-  { label: 'audit report', tier: 'medium' }
+  { label: 'audit report', strength: 'medium' }
 )
 
 return { map, audits: audits.filter(Boolean), report }`;

package/src/capabilities.ts

@@ -34,6 +34,14 @@ export const WORKFLOW_CAPABILITY_CONTRACT_VERSION = "2.0.0";
 /**
  * The runtime globals a script can rely on. `options` documents each helper's
  * accepted inputs with defaults; `constraints` states the behavioral contract.
+ *
+ * The strength option's type is spelled out on each of the four helpers that
+ * take it, rather than derived from `WORKFLOW_STRENGTHS`, because this array
+ * must stay literal-only: `check:capabilities` evaluates it in an empty VM
+ * realm so the published contract can be read without executing this package.
+ * `strengths.test.ts` pins the four copies against the vocabulary the runtime
+ * enforces, which is the drift protection a shared constant would otherwise
+ * have provided.
  */
 export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
   {
@@ -45,10 +53,10 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
       { name: "phase", kind: "string", optional: true, default: "current phase" },
       { name: "schema", kind: "plain JSON Schema", optional: true, default: "none" },
       {
-        name: "tier",
-        kind: "agent tier key",
+        name: "strength",
+        kind: '"low" | "medium" | "high"',
         optional: true,
-        default: "the agent's own tier, else agentTiers.defaultTier",
+        default: "no tier is sent; the agent's own tier, else agentTiers.defaultTier",
       },
       { name: "isolation", kind: '"worktree"', optional: true, default: "pi-subagents worktree policy" },
       { name: "thread", kind: "string", optional: true, default: "fresh session per call" },
@@ -64,11 +72,15 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
       "resume replays only the longest unchanged prefix; the first miss and every later call execute live",
       "replayed calls do not consume the real-dispatch maxAgents or token/phase budgets",
       "spawnKeys rotate by generation on resume so pi-subagents never raises a fingerprint conflict",
-      "tier names a key in the host's agentTiers catalogue; a key it does not define is rejected before dispatch",
+      "strength is this package's own vocabulary, not an agentTiers key; a word outside low/medium/high is rejected before dispatch",
+      "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",
+      "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",
+      "an unconfigured host uses a shipped default table: each strength on the catalogue tier of the same name, where the host defines one",
       "resolveAgentTier in pi-subagents owns model, thinking, clamping, availability, and the resolution snapshot",
-      "there is no per-call model or thinking: a tier is the only model policy a workflow can express",
+      "there is no per-call model, thinking, or tier: a strength is the only model policy a workflow can express",
       "same-thread calls must be sequential and preserve a stable workflow thread name",
       "threads cannot be combined with worktree isolation",
+      "an option name outside this list is rejected before dispatch, not ignored; tier, model, and thinking name their replacement",
     ],
   },
   {
@@ -136,6 +148,7 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
       { name: "reviewers", kind: "number", optional: true, default: "2" },
       { name: "threshold", kind: "number", optional: true, default: "0.5" },
       { name: "lens", kind: "string | string[]", optional: true, default: "none" },
+      { name: "strength", kind: '"low" | "medium" | "high"', optional: true, default: '"low"' },
     ],
     constraints: ["threshold comparison is inclusive; real is false when no reviewer succeeds"],
   },
@@ -146,6 +159,7 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
     options: [
       { name: "judges", kind: "number", optional: true, default: "3" },
       { name: "rubric", kind: "string", optional: true, default: "overall quality and correctness" },
+      { name: "strength", kind: '"low" | "medium" | "high"', optional: true, default: '"low"' },
     ],
     constraints: ["highest mean score wins with stable input index as the tie-break; empty input returns undefined"],
   },
@@ -164,8 +178,8 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
   {
     name: "completenessCheck",
     classification: "runtime-global",
-    signature: "completenessCheck(taskArgs, results) => Promise<{ complete, missing? } | null>",
-    options: [],
+    signature: "completenessCheck(taskArgs, results, options?) => Promise<{ complete, missing? } | null>",
+    options: [{ name: "strength", kind: '"low" | "medium" | "high"', optional: true, default: '"medium"' }],
     constraints: ["only the first 4,000 characters of serialized result evidence are sent to the critic"],
   },
   {
@@ -199,6 +213,7 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
     constraints: [
       "consumes one agent slot and no tokens",
       "journaled answers replay only within an unchanged resume prefix",
+      "an option name outside this list is rejected rather than ignored, since a dropped headless silently auto-approves",
     ],
   },
   { name: "log", classification: "runtime-global", signature: "log(message) => void", options: [], constraints: [] },

package/src/engine.ts

@@ -61,6 +61,7 @@ import {
   type WorkflowRunResult,
   type WorkflowRuntimeEvent,
 } from "./runtime.js";
+import type { WorkflowStrengthTable } from "./strengths.js";
 
 export const MAX_ATTEMPTS_PER_NODE = 3;
 
@@ -88,8 +89,19 @@ export interface ScriptStartOptions {
   concurrency?: number;
   agentRetries?: number;
   tokenBudget?: number | null;
-  /** True for a script this package ships; see WorkflowRunOptions.shippedScript. */
-  shippedScript?: boolean;
+  /**
+   * The user's strength → Agent tier table; see WorkflowRunOptions.strengths.
+   *
+   * Deliberately absent from `frozenOptions`. The frozen set is the run's
+   * inputs — budget, scale, toolset — which a resume must not silently
+   * renegotiate. Routing is not an input: a resume already re-reads the host's
+   * tier catalogue, and a table frozen against a catalogue that has since moved
+   * would be the one thing in the run still pointing at the old world.
+   *
+   * Being unfrozen makes supplying it every resume's job, including the resumes
+   * the engine starts itself — see {@link WorkflowEngine.strengths}.
+   */
+  strengths?: WorkflowStrengthTable;
   agentTimeoutMs?: number | null;
   toolset?: string;
   excludeTools?: string[];
@@ -105,13 +117,8 @@ export interface ScriptStartOptions {
       timeoutMs?: number;
     },
   ) => Promise<unknown>;
-  /**
-   * Resolve a nested `workflow(name)` reference. The result reports whether the
-   * script it returned ships with this package, because that decides how the
-   * child frame treats a tier name the host does not define — see
-   * `WorkflowRunOptions.shippedScript`.
-   */
-  loadSavedWorkflow?: (name: string) => { script: string; shippedScript?: boolean } | undefined;
+  /** Resolve a nested `workflow(name)` reference to the script it names. */
+  loadSavedWorkflow?: (name: string) => string | undefined;
   mainModel?: string;
 }
 
@@ -151,14 +158,7 @@ export interface ScriptRunState {
   /** Frozen run parameters — resume reuses the original values, ignoring new budget/toolset overrides. */
   frozenOptions: Pick<
     ScriptStartOptions,
-    | "tokenBudget"
-    | "maxAgents"
-    | "concurrency"
-    | "agentRetries"
-    | "agentTimeoutMs"
-    | "toolset"
-    | "shippedScript"
-    | "excludeTools"
+    "tokenBudget" | "maxAgents" | "concurrency" | "agentRetries" | "agentTimeoutMs" | "toolset" | "excludeTools"
   >;
   /** Abort controller for this run's script execution. */
   controller: AbortController;
@@ -289,6 +289,18 @@ export class WorkflowEngine {
   onRunSettled: (() => void) | undefined;
   /** Optional in-process observer for phase/task/quality runtime events. */
   onRuntimeEvent: ((runId: string, event: WorkflowRuntimeEvent) => void) | undefined;
+  /**
+   * The user's current strength → Agent tier table, read fresh per execution.
+   *
+   * A callback rather than a value because the table is deliberately unfrozen:
+   * "read fresh at each start and resume" has to hold for the resumes the
+   * engine starts on its own — `control("resume")` and the provider-limit
+   * retry — which have no caller to pass options for them. Without it those
+   * resume with no table at all, and since a call's identity keys on the tier
+   * it requested, every already-finished call would miss its journal entry and
+   * re-run untabled: the exact re-spend this table exists to prevent.
+   */
+  strengths: (() => WorkflowStrengthTable | undefined) | undefined;
   private readonly waiters = new Map<
     string,
     Set<{ resolve: (run: ScriptRun) => void; reject: (e: unknown) => void; settled: boolean; cleanup: () => void }>
@@ -628,7 +640,6 @@ export class WorkflowEngine {
     const runId = randomUUID();
     const scriptHash = hashScript(script);
     const toolset = options.toolset;
-    const shippedScript = options.shippedScript === true ? true : undefined;
     const durableArgs = cloneWorkflowArgs(options.args);
     const runtimeArgs = cloneWorkflowArgs(durableArgs);
     const journalArgs = cloneWorkflowArgs(durableArgs);
@@ -657,7 +668,6 @@ export class WorkflowEngine {
       meta,
       ...(durableArgs === undefined ? {} : { args: durableArgs }),
       frozenArgsPresent,
-      ...(shippedScript === undefined ? {} : { shippedScript }),
       ...(toolset ? { toolset } : {}),
       ...(frozenMaxAgents !== undefined ? { frozenMaxAgents } : {}),
       ...(frozenConcurrency !== undefined ? { frozenConcurrency } : {}),
@@ -686,7 +696,6 @@ export class WorkflowEngine {
       meta,
       ...(journalArgs === undefined ? {} : { args: journalArgs }),
       frozenArgsPresent,
-      ...(shippedScript === undefined ? {} : { shippedScript }),
       ...(toolset ? { toolset } : {}),
       ...(frozenMaxAgents !== undefined ? { frozenMaxAgents } : {}),
       ...(frozenConcurrency !== undefined ? { frozenConcurrency } : {}),
@@ -705,7 +714,6 @@ export class WorkflowEngine {
         ...(frozenAgentRetries !== undefined ? { agentRetries: frozenAgentRetries } : {}),
         ...(frozenAgentTimeoutMs !== undefined ? { agentTimeoutMs: frozenAgentTimeoutMs } : {}),
         ...(options.toolset ? { toolset: options.toolset } : {}),
-        ...(shippedScript === undefined ? {} : { shippedScript }),
         ...(options.excludeTools ? { excludeTools: [...options.excludeTools] } : {}),
       },
       controller: new AbortController(),
@@ -802,11 +810,15 @@ export class WorkflowEngine {
     this.setWorkflowStatus(run, "running");
     state.controller = new AbortController();
     // Freeze semantics: original run parameters and args win over new options.
-    // Only signal/confirm/background/loadSavedWorkflow/mainModel are per-resume context;
-    // input/budget/scale/toolset are frozen from the original start.
+    // Only signal/confirm/background/loadSavedWorkflow/mainModel/strengths are
+    // per-resume context; input/budget/scale/toolset are frozen from the
+    // original start.
     const frozen = state.frozenOptions;
     const resumeOptions: ScriptStartOptions = {
       ...options,
+      // `??`, not an overwrite: a caller that passed a table meant it, and only
+      // a caller that passed none is asking the engine to read the current one.
+      strengths: options.strengths ?? this.strengths?.(),
       args: resumeArgs,
       tokenBudget: frozen.tokenBudget,
       maxAgents: frozen.maxAgents,
@@ -814,7 +826,6 @@ export class WorkflowEngine {
       agentRetries: frozen.agentRetries,
       agentTimeoutMs: frozen.agentTimeoutMs,
       toolset: frozen.toolset,
-      shippedScript: frozen.shippedScript,
       excludeTools: frozen.excludeTools ? [...frozen.excludeTools] : undefined,
     };
     state.bufferedTerminals.clear();
@@ -1010,7 +1021,7 @@ export class WorkflowEngine {
         executionNonce: `${generation}-${randomUUID()}`,
         resumeJournal,
         toolset: options.toolset,
-        shippedScript: options.shippedScript,
+        strengths: options.strengths,
         excludeTools: options.excludeTools,
         confirm: options.confirm,
         loadSavedWorkflow: options.loadSavedWorkflow,
@@ -1750,7 +1761,6 @@ export class WorkflowEngine {
           ...(run.frozenAgentRetries !== undefined ? { agentRetries: run.frozenAgentRetries } : {}),
           ...(run.frozenAgentTimeoutMs !== undefined ? { agentTimeoutMs: run.frozenAgentTimeoutMs } : {}),
           ...(run.toolset ? { toolset: run.toolset } : {}),
-          ...(run.shippedScript === undefined ? {} : { shippedScript: run.shippedScript }),
           ...(run.frozenExcludeTools ? { excludeTools: [...run.frozenExcludeTools] } : {}),
         },
         controller: new AbortController(),