bullswarm 0.13.2 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # bullswarm changelog
 
+## 0.14.0 — structured worker output, compact planner contract
+
+- A verify whose reply cannot be parsed as the verdict JSON gets ONE bounded
+  re-ask (event `verify.verdict_retry`) before its failure can reach a planner
+  boundary — observed on run `ejk9w2`: one unparseable verdict cost a full
+  planner turn plus ~8 minutes of re-proving a passing state.
+- Planner contract amendments from the same run's observations: a verify is
+  scoped to what can be true at its point in the graph (later-scheduled work is
+  not a defect; cosmetic mismatches are concerns, never ok:false); when the
+  goal's acceptance checks pass the planner returns complete instead of adding
+  polish actions; restored the shared-working-tree, redundant-verification,
+  and operatorSteering guidance dropped by the contract merge.
+- "Full" planner-context excerpts (scout, new-since-last-decision, failing
+  verifies) obey the per-excerpt and total budgets again; the compaction must
+  never rebuild the 163 k-char contexts it replaced.
+- Planner context and contract compacted: complete emitted planner task text up to the durable-context marker, worktree-isolation suffix included **OBSERVED** `16,316 -> 5,208` characters, and a sample turn-2 durable context **COMPUTED** `163,000 -> 23,547` characters by replacing full attempt records with compact ledger rows and retaining full output excerpts only for new/scout or `ok:false` verify actions.
+- Planner `run` actions and fan-out `stepTemplate`s may declare an optional
+  `outputSchema`, an object-typed JSON-Schema subset. The runtime tells the
+  worker to end its output with one matching JSON object, parses and validates
+  it, and persists a `run` result as `outputs.<id>.data` with `schemaOk: true`;
+  fan-out results store those fields inside each `outputs.<fanoutId>.items[]`
+  entry. Successful validation emits `action.output_validated`.
+- Schema failures emit `action.output_schema_retry` and receive exactly one
+  bounded retry with the validation errors and the previous output tail. If
+  that retry also fails, the action remains `ok:false`, records
+  `schemaOk:false` and `schemaErrors`, and keeps the output text with the
+  reason `output did not match outputSchema: <errors>`. Resumed runs do not
+  re-dispatch actions already marked `schemaOk:true`.
+- Dependent prompts can render `{{outputs.<id>.data.<field>}}`, and
+  `fanout.itemsFrom` accepts `outputs.<id>.data.items` without an extraction
+  agent when the array is already present. Planner decision validation rejects
+  `outputSchema` on a proposed `verify` because verify has a fixed verdict
+  shape.
+
 ## 0.13.2 — user text is never a template
 
 - `workflow goal` failed before anything ran when the goal text quoted

package/docs/claude-dynamic-workflow-mechanics.md

@@ -234,7 +234,7 @@ from `docs/experiments/2026-08-29-ultracode-vs-bullswarm.md`, never projected.
 | Phases | Labels for grouping; never synchronise | Forward-only kebab-case names per action; also just labels | None |
 | Parallelism | `pipeline` default, `parallel` barrier; cap min(16, CPUs−2) | `executeActions` ran dependency-ready siblings **serially** (`runner.js:558`); only `fanout` items ran concurrently; goal default concurrency 3 | **Fixed in 0.11.0** — ready-set scheduler + default 8 |
 | Planner bias | Script author is told to fan out and default to pipeline | Goal prompt said "return needs_more_work with the **smallest useful set** of bounded … actions" (`goal.js:18`) and planner prompt said "keep actions cohesive" | **Fixed in 0.11.0** — "propose the COMPLETE dependency graph", per-item fix→verify chains, file ownership, self-contained prompts |
-| Per-agent prompt | Self-contained, plus JSON schema enforced at tool layer | Planner-authored prompt; free-text answer, content-verified by heuristics; `verify` returns JSON verdict | Partial. Schema-enforced worker output is a candidate, not adopted yet |
+| Per-agent prompt | Self-contained, plus JSON schema enforced at tool layer | Planner-authored prompt; `outputSchema` validates structured worker data, while `verify` retains its fixed JSON verdict | Adopted for declared schemas; tool-layer enforcement remains a difference |
 | Failure handling | Loops in code; `null` on agent death | Planner replans (costly); 0.10.9 added corrective turns for invalid decisions and 0.11.0 recovers mis-shaped `verify.review` before dispatch | Improved; retry-in-code per action still absent |
 | Determinism / resume | Journal of return values; prefix cache | Durable `state.json` + `events.jsonl` + action ledger; resume skips durable outputs | Equivalent |
 | Data-driven fan-out | `pipeline(discovered.items, …)` — count unknown when the script is written | Decision schema forced inline `items`; the planner spent a turn waiting for discovery | **Fixed in 0.12.0** — `itemsFrom` on proposed fan-outs + one bounded extraction retry |
@@ -288,8 +288,7 @@ author and the `Workflow` runtime.
    if the output still has no array the runtime runs ONE bounded, read-only
    extraction action over it (never re-running the producer, which may have
    mutated files). That is the "schema retry" of Claude's `StructuredOutput`,
-   done as a second cheap agent instead of a tool-layer retry. A general
-   `outputSchema` on run actions is still open (§5).
+   done as a second cheap agent instead of a tool-layer retry.
 3. **Pre-authored repair** — shipped. `repair: { prompt, maxRounds }` on a
    verify: verify-fail → `<verifyId>-repair-<n>` (concerns verbatim) →
    re-verify, inside the executor. Claude's fix-loop as code.
@@ -350,6 +349,21 @@ author and the `Workflow` runtime.
    exist — the script's `while (!ok)` loop *is* the evidence — which is the
    general lesson: every piece of control flow bullswarm moves from planner
    into runtime needs its evidence rule moved with it.
+11. **[SPEC] Schema-enforced worker output** — a planner `run` action or fan-out
+    `stepTemplate` may declare an object-typed `outputSchema` subset. The
+    runtime appends instructions for one trailing matching JSON object, with no
+    prose or markdown fences after it, then parses and validates the object.
+    A successful `run` persists `outputs.<id>.data` and `schemaOk: true`; a
+    fan-out stores those schema results inside each
+    `outputs.<fanoutId>.items[]` entry. Both emit `action.output_validated`. A mismatch emits
+    `action.output_schema_retry` and gets exactly one bounded retry carrying
+    the validation errors and the previous output tail; a second mismatch
+    fails the action while retaining its output text and recording
+    `schemaOk:false` and `schemaErrors`. Dependent prompts can render data
+    fields, and `fanout.itemsFrom` can consume `outputs.<id>.data.items` without
+    extraction when it is already an array. Planner decision validation rejects
+    `outputSchema` on a proposed `verify` because verify has a fixed verdict
+    shape.
 
 **Honest limitation.** `itemsFrom` removes the planner *turn*, not the stage
 *barrier*: a verify depending on a data-driven fan-out waits for all items,
@@ -361,10 +375,6 @@ them.
 
 ## 5. Not adopted (yet), and why
 
-- **Schema-enforced worker output.** bullswarm's content verification and the
-  JSON `verify` verdict cover the failure mode today; adding per-action
-  `outputSchema` is the next step if planners keep re-asking workers for
-  structure.
 - **Per-action worktree isolation.** File ownership declared by the planner is
   cheaper and matches Claude's own guidance ("EXPENSIVE … use ONLY when agents
   mutate files in parallel and would otherwise conflict").

package/docs/planner-prompt-audit-2026-08-29.md

@@ -0,0 +1,157 @@
+# Planner prompt and context audit — 2026-08-29
+
+Question from the user: after the 0.11 → 0.14 iterations, does the instruction
+set given to the orchestrator/planner still make sense, or should it be
+simplified or refactored?
+
+Method: measure what the planner actually receives, not what the source files
+look like. The two planner task files of dogfood run `wf-mtdq1l9v-ed22fe`
+(`75t4n2`, bullswarm building `outputSchema` in its own repo, runtime 0.13.2)
+are the specimens; sizes are characters of the task text
+(`task-orchestrator-*.md`), tokens ≈ chars / 4.
+
+## 1. What one planner turn receives
+
+| section | source | turn 1 | turn 2 |
+| --- | --- | ---: | ---: |
+| orchestrator prompt + worktree line | `goal.js` `AUTONOMOUS_ORCHESTRATOR_PROMPT` | 5 000 | 5 000 |
+| PLANNING DOCTRINE (11 bullets) | `runtime.js` runDecision | 3 605 | 3 605 |
+| Action skeletons (6 shapes + verify semantics) | `runtime.js` | 1 342 | 1 342 |
+| Program skeleton (discovery → fan-out → verify → suite) | `runtime.js` | 1 217 | 1 217 |
+| Graph skeleton (two chains + suite) + fanout paragraph + runtime-owned line | `runtime.js` | 4 054 | 4 054 |
+| durable context (JSON) | `runtime.js` plannerContext | 17 474 | 162 946 |
+| **total** | | **32 730** (~8 k tokens) | **178 452** (~45 k tokens) |
+
+The fixed prefix is 15.2 k chars on every turn. The durable context grew
+**9×** between turn 1 and turn 2 of the same run.
+
+### Where the 163 k of turn 2 went
+
+| key | chars | what it is |
+| --- | ---: | --- |
+| `completedActions` (19 entries) | 66 700 | every finished action **with its full attempt records**: routing candidates and pace numbers, usage, pricing table, child pid, timings — ~3.5 k per action |
+| `outputs` (19 entries) | 41 560 | `outputExcerpt` of ~3 k chars for *every* finished action, including ones that finished ok and were already verified in the previous program |
+| `intent` | 6 657 | the goal text (6.5 k) + cwd + policy — needed, once |
+| `failures` | 1 073 | the two blocked actions — duplicates of `completedActions` entries |
+| `availablePools`, `budget`, `executionConstraints`, `closedPhases`, … | ~1 800 | fine |
+
+## 2. What is said more than once
+
+Reading the prefix as the planner does, the same rules appear two or three
+times in different words:
+
+| rule | orchestrator prompt | doctrine | skeletons |
+| --- | --- | --- | --- |
+| propose the whole program, one round trip costs minutes | item 2 | bullets 1, 2 | "all in ONE decision" ×2 |
+| N items → N run + N verify + one suite verify | item 5 | "Per-item chains" | Graph skeleton |
+| unknown items → discovery + `itemsFrom` fan-out | item 5 | "Unknown item count" | Program skeleton + fanout paragraph |
+| every verify gets a `repair` policy | item 5 | "Verification failures" | verify skeleton |
+| `completion: all-actions-ok` on a clean program | item 5 | "Self-completing programs" | — |
+| self-contained worker prompts, file ownership | item 3 | "File ownership", "Self-contained prompts" | — |
+| don't propose pool/addDir/taskFile | closing line | — | final line |
+
+Item 5 of the orchestrator prompt alone is 1 050 chars and restates four
+doctrine bullets. The two program skeletons both end in the same
+`verify-items → verify-suite` tail.
+
+## 3. Does it matter? Measured
+
+- Turn 1 (32.7 k chars) took **637 s**; turn 2 (178 k chars) took **390 s**.
+  Latency is therefore dominated by the model's reasoning on the goal, not by
+  context size — the 6.5 k-char goal and a 12-action program cost more thinking
+  than reading 45 k tokens. Trimming context is a **cost** and **attention**
+  lever, not primarily a latency lever.
+- Cost: turn 2 read ~45 k tokens to emit a ~1 k-token decision. At Opus
+  prices that is ~$0.25 per boundary; a run with four boundaries (goal 2 on
+  0.12.1) spends more on re-reading attempt metadata than on the decisions.
+- Attention: the planner's turn-2 reason correctly diagnosed the blocked
+  graph, so quality did not visibly suffer here — but 64 k chars of pricing
+  tables and routing candidates are noise it must skip to find the two
+  `ok:false` concerns that matter.
+- Behaviour observed in three runs (goal 2, goal 3, dogfood): every rule the
+  prefix repeats was followed on the first turn (whole program, per-item
+  chains, repair policies, `completion`). No observed decision needed a rule
+  to be stated twice.
+
+## 4. Recommendation
+
+Yes — refactor, in two independent pieces, both measurable:
+
+**A. Compact the durable context (the 9× growth).** Planner-facing ledger rows
+instead of raw ledger entries: `{ id, type, phase, status, pool, durationSec,
+attempts, why }` (~150 chars; 19 actions → ~3 k instead of 66.7 k). Keep a
+full `outputExcerpt` only for actions finished **since the last decision** and
+for every `ok:false` verify; older ok actions get a one-line summary (id, ok,
+first 200 chars). Replace `failures` with the ids of failing actions (their
+full entry already sits in the ledger). Expected turn-2 context: ~25 k chars
+instead of 163 k. Pure runtime change; no planner behaviour change intended.
+
+**B. One contract instead of three overlapping texts.** Merge
+`AUTONOMOUS_ORCHESTRATOR_PROMPT` and the doctrine bullets into a single ordered
+list of ~10 rules (target ≤ 4 k chars, from 8.1 k), each stated once with its
+reason; keep exactly two JSON examples — the action shapes list and one
+complete program (discovery → data-driven fan-out → per-item verify with
+repair → suite verify, with `completion`) — and delete the second program
+skeleton (target ≤ 3 k, from 6.6 k). Total prefix ≤ 7 k chars, from 15.2 k.
+
+Acceptance for both: unit tests on the context builder (row shape, excerpt
+policy by decision sequence) and on the prompt (each rule appears once; the
+skeleton assertions in `tests/workflow-adaptive.test.js` updated); then one
+re-run of goal 3 on the same fixture (baseline 0.13.1: 28 min 42 s, 1 planner
+turn, 294 s) to confirm the decision shape is unchanged and record the new
+per-turn size.
+
+Not recommended: cutting the goal text or the scout excerpt from the context —
+both were used verbatim by every first-turn program observed.
+
+## 5. Outcome
+
+Measurements below were taken after the refactor from the current source and
+from the committed source saved into `/tmp/goal-before.mjs` and
+`/tmp/runtime-before.js`, using the same temporary measurement script. The
+canonical prefix is the complete emitted planner task text counted from its
+first character up to (not including) the durable-context marker, with the
+worktree-isolation suffix included. The committed baseline predates the named
+section exports, so its emitted prefix was reconstructed from the committed
+`runtime.js` task-text assembly and the committed `AUTONOMOUS_ORCHESTRATOR_PROMPT`.
+
+- Complete emitted planner task text up to the durable-context marker,
+  worktree-isolation suffix included: **OBSERVED**, `16,316` characters before
+  and `5,208` characters after. Command: `node /tmp/measure-planner.mjs`.
+- Static planner task-prefix array through the durable-context boundary:
+  **OBSERVED**, `16,209` characters before and `5,101` characters after. The
+  after value is 107 characters shorter because it excludes the unchanged
+  worktree-isolation suffix; this is a secondary source-level measurement, not
+  the canonical emitted-prefix headline. Command: `node /tmp/measure-planner.mjs`.
+- `PLANNER_RULES_SECTION`: **OBSERVED**, `2,202` characters after. Command:
+  `node /tmp/measure-planner.mjs`.
+- `PLANNER_EXAMPLES_SECTION`: **OBSERVED**, `1,867` characters after. Command:
+  `node /tmp/measure-planner.mjs`.
+- `AUTONOMOUS_ORCHESTRATOR_PROMPT`: **OBSERVED**, `4,670` characters after;
+  the committed before source had no separately exported rules or examples
+  sections, so separate before-section sizes are **NOT AVAILABLE**, not
+  inferred. Command: `node /tmp/measure-planner.mjs`.
+- Sample durable context: **OBSERVED** baseline `163,000` characters in the
+  audit's rounded turn-2 durable-context total (the detailed table records
+  `162,946`; the full turn-2 task was `178,452`), and **COMPUTED** `23,547`
+  characters after. The computed sample applies 19
+  compact ledger rows at 150 characters each, keeps a 3,000-character scout
+  excerpt and two 3,000-character failing-verify excerpts, truncates the
+  other 16 action excerpts to 200 characters, represents two failures as
+  20-character IDs, and retains the audit's 6,657-character intent and
+  1,800-character other-context components. Command: `node /tmp/compute-context.mjs`.
+
+Deliverables:
+
+- Durable planner context shrank because completed actions are compact ledger
+  rows, failures are IDs, and stale successful output is truncated.
+- Planner contract shrank because overlapping prompt/doctrine/skeleton text is
+  now one ordered rules section plus exactly two JSON examples, single-sourced
+  in `src/workflow/goal.js`.
+- Runtime prompt construction shrank because `src/workflow/runtime.js` imports
+  the shared contract instead of carrying a duplicate doctrine and graph
+  skeleton.
+- `skill/SKILL.md` was left unchanged: it documents the general durable
+  context and the separate run-state/TUI attempt view, but does not document a
+  renamed/dropped planner-context field shape such as the old attempt records
+  or an old `failures` representation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bullswarm",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "description": "Route work across coding-agent CLI subscriptions — paced by live quota meters, verified by content, never trusting exit codes.",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -361,6 +361,11 @@ that expressible without extra turns:
   (`source: "program-completion"`, event `decision.auto_completed`) and the run
   ends without another planner turn; a failing action emits
   `decision.completion_predicate_unmet` and the boundary returns to the planner.
+- `outputSchema` on a `run` or fan-out `stepTemplate` — declare it when a
+  downstream action needs reliable structured data, such as an object to render
+  into a dependent prompt or an `items` array for `fanout.itemsFrom`; leave it
+  off for ordinary prose; planner proposals must not put it on `verify`, whose
+  verdict shape is fixed.
 
 Every fan-out records a summary artifact as `outputs.<id>.outFile` and a
 boolean `ok` (item count in `succeeded`), so a verify may depend on a fan-out

package/src/workflow/decision.js

@@ -3,6 +3,7 @@
 // or dispatch any new action.
 
 export const DECISION_SCHEMA_VERSION = 'bullswarm.workflow.decision.v1';
+import { isValidOutputSchema } from './schema.js';
 export const DECISIONS = new Set([
   'proceed', 'complete', 'needs_more_work', 'retry', 'escalate',
   'wait_for_approval', 'stop',
@@ -40,7 +41,7 @@ export function parseDecisionText(text) {
 export const REVIEW_PATH_RE = /^outputs\.([A-Za-z0-9_-]+(?:\[\d+\])?)\.outFile$/;
 // Data-driven fan-out source: the artifact of an earlier (or co-proposed)
 // action whose output ends with a JSON array of items.
-export const ITEMS_FROM_RE = /^outputs\.([A-Za-z0-9_-]+)(?:\.outFile)?$/;
+export const ITEMS_FROM_RE = /^outputs\.([A-Za-z0-9_-]+)(?:\.data\.([A-Za-z0-9_-]+)|\.outFile)?$/;
 export const REPAIR_MAX_ROUNDS = 3;
 // Program-level completion predicates a planner may attach to a program so the
 // runtime can record completion itself when every action finishes ok.
@@ -179,7 +180,15 @@ export function validateDecisionProposal(proposal, {
     if (action.type === 'run' && typeof action.prompt !== 'string') {
       issues.push(`${at} needs a prompt`);
     }
-    if (action.type === 'fanout') {
+       if (action.outputSchema !== undefined) {
+         if (action.type !== 'run') issues.push(`${at}.outputSchema is only allowed on run actions`);
+         else {
+           const schema = isValidOutputSchema(action.outputSchema);
+           if (!schema.ok) issues.push(...schema.issues.map((issue) => `${at}.outputSchema: ${issue}`));
+           else if (action.outputSchema.type !== 'object') issues.push(`${at}.outputSchema.type must be "object"`);
+         }
+       }
+       if (action.type === 'fanout') {
       const hasItems = Array.isArray(action.items);
       const hasItemsFrom = action.itemsFrom != null;
       if (!hasItems && !hasItemsFrom) {
@@ -198,10 +207,15 @@ export function validateDecisionProposal(proposal, {
         }
       }
       if (!action.stepTemplate || typeof action.stepTemplate !== 'object') issues.push(`${at}.stepTemplate is required`);
-      for (const runtimeOwned of ['pool', 'addDir', 'taskFile']) {
+       for (const runtimeOwned of ['pool', 'addDir', 'taskFile']) {
         if (action.stepTemplate?.[runtimeOwned] != null) {
           issues.push(`${at}.stepTemplate.${runtimeOwned} is runtime-owned and cannot be proposed by a planner`);
-        }
+       }
+       if (action.stepTemplate?.outputSchema !== undefined) {
+         const schema = isValidOutputSchema(action.stepTemplate.outputSchema);
+         if (!schema.ok) issues.push(...schema.issues.map((issue) => `${at}.stepTemplate.outputSchema: ${issue}`));
+         else if (action.stepTemplate.outputSchema.type !== 'object') issues.push(`${at}.stepTemplate.outputSchema.type must be "object"`);
+       }
       }
     }
     if (action.repair != null && action.type !== 'verify') {

package/src/workflow/goal.js

@@ -7,31 +7,40 @@ import { resolve } from 'node:path';
 
 const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
 
+export const PLANNER_RULES_SECTION = [
+  '1. Compile the whole program in one decision: the runtime executes all proposed actions and consults you only at a finished-or-blocked boundary, so deferring decidable work costs another round trip.',
+  '2. Make every worker prompt self-contained: include the exact goal, absolute cwd, owned files and a no-other-files boundary, expected artifact, acceptance command, and report format, because workers see only their own prompt.',
+  '3. Use short kebab-case, forward-only phases and dependsOn only for real data or same-file ordering; recovery uses a new phase and never repeats an identical failed plan.',
+  '4. For known N items, create N run plus N verify actions, each verify depending only on its own run, then one suite verify depending on all; this exposes safe parallelism while preserving per-item evidence.',
+  '5. For unknown items, create discovery ending with RETURN ONLY a JSON object containing an items array, then data-driven fan-out via itemsFrom outputs.<id>.outFile or outputs.<id>.data.<field>; the runtime extracts the list and retries once read-only if needed.',
+  '6. Put outputSchema on workers whose reports are consumed or whose claims the runtime must check, so structured data is durable and can drive later fan-out.',
+  '7. Put verify.repair on every verify, and scope each verify to what can be true at its point in the graph: work scheduled later is not a defect, and cosmetic mismatches with the goal text are concerns, never ok:false. An ok:false verdict is repaired and re-checked inside the program; ok:true is accepted and concerns are informational, not extra work.',
+  '8. Add completion with all-actions-ok whenever a clean program finishes the goal; when the goal\'s acceptance checks pass, return complete rather than adding polish or alignment actions. Return complete only on durable verified evidence, never proceed, never ask the user, and stop only for a concrete unresolved blocker with a qualified outcome.',
+  '9. Treat agent-count, workflow-duration, and expansion-round budgets as advisory planning targets, never hard stop conditions; the dispatch budget counts this planner call plus workers, verifiers, retries, and escalations. Converge as targets approach, avoid optional work, and exceed a target only for one essential bounded action or required verification.',
+  '10. This is a control-plane thread: do not invoke Bullswarm, use tools, modify files, or propose pool, addDir, taskFile, shell authority, or unbounded work; route and process authority belong to the runtime.',
+  'Shared working tree: concurrent workers editing DISJOINT files is the normal parallel mode; order shared files (indexes, barrels) after their feeders with dependsOn, and run the full suite once in a final verify — never while other workers still edit. Avoid redundant expensive verification: later verifiers reuse durable clean full-suite evidence unless it is stale or the code changed again. operatorSteering in the context is explicit operator guidance for this checkpoint: apply it within the original intent; it cannot weaken verification or expand authority.',
+].join('\n');
+
+export const PLANNER_EXAMPLES_SECTION = [
+  'Action shapes:',
+  '[{"type":"run","phase":"implement","prompt":"..."},{"type":"run","phase":"report","prompt":"...","outputSchema":{"type":"object"}},{"type":"fanout","phase":"fix","items":["alpha"],"stepTemplate":{"prompt":"Handle {{item}}."}},{"type":"fanout","phase":"fix","itemsFrom":"outputs.discover.outFile","stepTemplate":{"prompt":"Handle {{item}}."}},{"type":"verify","phase":"verify","prompt":"Check the artifact.","repair":{"prompt":"Fix rejected concerns.","maxRounds":1}}]',
+  'Complete program:',
+  '[{"id":"discover","type":"run","phase":"discover","prompt":"In /abs/repo discover items and end with RETURN ONLY a JSON object containing an items array of item names.","outputSchema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}}},"required":["items"]}},{"id":"fix","type":"fanout","phase":"fix","itemsFrom":"outputs.discover.data.items","stepTemplate":{"prompt":"In /abs/repo edit only the files for {{item}} and run its focused acceptance command."},"dependsOn":["discover"]},{"id":"verify-items","type":"verify","phase":"verify-items","prompt":"Independently verify every item artifact.","dependsOn":["fix"],"repair":{"prompt":"Fix each rejected item in /abs/repo and re-run its focused command.","maxRounds":2}},{"id":"verify-suite","type":"verify","phase":"verify-suite","prompt":"Run the full acceptance command in /abs/repo.","dependsOn":["verify-items"],"repair":{"prompt":"Fix the suite failure in /abs/repo and rerun the suite.","maxRounds":1}}],"completion":{"when":"all-actions-ok","reason":"The item checks and final suite verification prove the goal."}]',
+  'Rules the validator enforces: action type is run, fanout, or verify; fanout has stepTemplate and either items or itemsFrom; verify.review is a string when explicit review is needed; dependsOn names existing or proposed actions; runtime-owned fields are rejected.',
+].join('\n');
+
 export const AUTONOMOUS_ORCHESTRATOR_PROMPT = [
   'You are the autonomous orchestrator for the user goal in the durable workflow context.',
-  'Your job is to compile the goal into a complete workflow program. The runtime executes every action you propose, in dependency order and in parallel, without consulting you, and calls you again only at the program boundary: when every action has finished or the graph is blocked.',
-  'Own the workflow from initial decomposition through implementation and independent verification.',
-  'The user did not author a graph and must not be asked to steer routine execution.',
-  'This is a control-plane decision thread, not a worker assignment. Do not invoke Bullswarm, run shell commands, call tools, or modify repository files. Use only the durable context supplied below and return the requested decision JSON; delegate all inspection, implementation, and verification as bounded actions.',
+  'This is a control-plane decision thread. Compile the goal into a complete workflow program, own decomposition through independent verification, and use only the supplied context. Do not invoke Bullswarm, run shell commands, call tools, modify files, or ask the user to steer routine execution.',
+  '',
+  'Ordered planning contract:',
+  PLANNER_RULES_SECTION,
   '',
-  'At every checkpoint:',
-  '1. Observe the intent, completed actions, artifacts, failures, verification results, available capabilities, and remaining budget.',
-  '2. If evidence is insufficient, return needs_more_work with the COMPLETE program: every bounded run, fanout, and verify action you can see now, not the smallest step. Independent actions run concurrently; dependent actions start as soon as their dependencies succeed. One planning round trip costs minutes, so a decision with one action when several are obvious is the expensive choice, and anything decidable by data (how many items, whether a check passed, whether to repair once) belongs in the program, not in a later decision.',
-  '3. Give workers self-contained prompts with the exact goal, absolute working directory, the files they may edit (and that they must not touch others), the expected artifact, and the exact acceptance command. A worker sees only its own prompt.',
-  '4. Assign every action a short kebab-case phase name such as discover, fix, verify-items, or verify-suite. Phases are forward-only: never append new work to a phase that already finished.',
-  '5. Use dependsOn only for real data or same-file ordering dependencies. For N known items propose N fix actions and N verify actions (each verify depending only on its own fix) plus one final verify depending on all of them; use fanout with inline items when every item needs the identical prompt. When the item count is unknown, propose a discovery run whose prompt ends with "RETURN ONLY a JSON array of <items>" and a fanout with itemsFrom "outputs.<discovery-id>.outFile", so the runtime fans out the moment discovery finishes.',
-  '   A verify action with exactly one dependency automatically reviews that dependency artifact (a fan-out artifact summarises every item); you do not need to supply a review path. Give every verify a repair policy {"prompt": "<how to fix what the verifier rejects>", "maxRounds": 1-3} so a rejected verdict is fixed and re-checked inside the program instead of costing another checkpoint. When the program ends with verification that would satisfy the goal, add a top-level "completion": {"when": "all-actions-ok", "reason": "<what a clean run proves>"} so a clean run is recorded as complete without another checkpoint.',
-  '6. Recover from a failed action with a new bounded action in a new phase when useful; do not repeat an identical failed plan.',
-  '7. Require concrete verification of changed behavior. For code changes, obtain relevant test or inspection evidence before completion.',
-  '8. Return complete only when durable outputs prove the original goal and its acceptance checks are satisfied.',
+  // Keep the fanout token inert in the authored workflow prompt. The runtime
+  // restores it when constructing the planner task, after template validation.
+  PLANNER_EXAMPLES_SECTION.replaceAll('{{item}}', '__BULLSWARM_ITEM_TEMPLATE__'),
   '',
-  'Do not return proceed: this autonomous workflow has no hidden static work after this gate.',
-  'Do not ask the initiating user to construct JSON or choose agents.',
-  'Do not propose pool, addDir, taskFile, shell authority, or unbounded work; Bullswarm owns routing and process authority.',
-  'Treat maxAgents, maxWorkflowSeconds, and maxExpansionRounds as planning targets, not hard stop conditions.',
-  'As those targets approach, converge aggressively: consolidate existing artifacts, avoid optional investigation, and finish with the best useful outcome rather than spending on marginal refinements.',
-  'Exceed an advisory target only for a small essential action needed to avoid discarding otherwise-completable work or skipping required verification.',
-  'Return stop when unresolved concerns make verified completion disproportionate or when a concrete safety, authority, capability, dependency, or external blocker remains. Stop returns a qualified final outcome; it is not a blanket workflow failure when useful work exists.',
+  'Return only the requested decision JSON. Do not return proceed: this autonomous workflow has no hidden static work after this gate.',
 ].join('\n');
 
 // Read-only survey that runs before the orchestrator's first decision, so the

package/src/workflow/runner.js

@@ -343,8 +343,9 @@ export async function runWorkflow(opts) {
       runtime.persist();
       // R2: skip ok:true on resume for both `run` and `verify`. (Fanout
       // is resumed inside the runtime, per-item by fingerprint.)
-      if (resuming && state.outputs[step.id]?.ok === true
-          && (step.type === 'run' || step.type === 'verify')) {
+       if (resuming && state.outputs[step.id]?.ok === true
+           && (step.outputSchema === undefined || state.outputs[step.id]?.schemaOk === true)
+           && (step.type === 'run' || step.type === 'verify')) {
         runtime.emit('step.skipped', { stepId: step.id });
         continue;
       }
@@ -619,7 +620,15 @@ async function runDecisionLoop({ runtime, gate, phase, state, retryAttempts }) {
   const resolveProposedItems = async (action) => {
     const itemsFrom = action.itemsFrom.trim();
     const producerId = ITEMS_FROM_RE.exec(itemsFrom)?.[1] ?? null;
+    const dataField = ITEMS_FROM_RE.exec(itemsFrom)?.[2] ?? null;
     const limit = Number(settings.maxItemsPerExpansion ?? 50) || 50;
+    if (dataField) {
+      const items = state.outputs?.[producerId]?.data?.[dataField];
+      if (!Array.isArray(items)) return { ok: false, why: `fanout itemsFrom "${itemsFrom}" did not resolve to an array in producer data` };
+      if (items.length > limit) return { ok: false, why: `fanout "${action.id}" resolved ${items.length} items from ${itemsFrom}, exceeding maxItemsPerExpansion=${limit}; propose a narrower discovery or split the fan-out` };
+      runtime.emit('action.items_resolved', { actionId: action.id, itemsFrom, count: items.length });
+      return { ok: true, items };
+    }
     const attempt = (path) => {
       try { return { ok: true, items: extractItems(state, path) }; } catch (err) { return { ok: false, why: err.message }; }
     };
@@ -738,7 +747,8 @@ async function runDecisionLoop({ runtime, gate, phase, state, retryAttempts }) {
     const pending = new Map(actions.map((action) => [action.id, action]));
     const running = new Map();
     const runOne = async (action) => {
-      if (state.outputs[action.id]?.ok === true) {
+       if (state.outputs[action.id]?.ok === true
+           && (action.outputSchema === undefined || state.outputs[action.id]?.schemaOk === true)) {
         runtime.emit('action.resumed', { actionId: action.id, status: 'succeeded' });
         return;
       }

package/src/workflow/runtime.js

@@ -36,6 +36,8 @@ import { classifyAgentProgress, recordAgentAction } from '../lib/agent-events.js
 import { deliverSteering } from './steering.js';
 import { resolveDispatchModel } from '../lib/strategy.js';
 import { getMeterReading } from '../meters/registry.js';
+import { validateAgainstSchema } from './schema.js';
+import { AUTONOMOUS_ORCHESTRATOR_PROMPT } from './goal.js';
 
 // Cap how much of each step's output we keep inline in state.json.
 // Persisting full transcripts bloat state.json on long workflows. The
@@ -296,6 +298,7 @@ export class WorkflowRuntime {
             meta: { exitCode: null },
           };
           action.status = 'failed_terminal';
+          action.why = refused.why;
           action.finishedAt = new Date().toISOString();
           this.emit('action.failed', { actionId, status: action.status, why: refused.why });
           return refused;
@@ -469,6 +472,7 @@ export class WorkflowRuntime {
           attemptRecord.finishedAt = new Date().toISOString();
           attemptRecord.why = refused.why;
           action.status = 'failed_terminal';
+          action.why = refused.why;
           action.finishedAt = attemptRecord.finishedAt;
           this.state.activeAgents[activeKey].status = 'failed';
           this.state.activeAgents[activeKey].finishedAt = attemptRecord.finishedAt;
@@ -599,6 +603,7 @@ export class WorkflowRuntime {
           });
         }
         action.status = attemptRecord.status;
+        if (!verdict.ok) action.why = verdict.why ?? null;
         action.finishedAt = attemptRecord.finishedAt;
         this.emit('attempt.completed', {
           actionId, attemptNumber, status: attemptRecord.status, ok: verdict.ok, why: verdict.why ?? null,
@@ -885,6 +890,93 @@ export class WorkflowRuntime {
     };
   }
 
+  schemaTaskText(taskText, schema, retry = null) {
+    return [
+      taskText,
+      '',
+      retry
+        ? `Your previous answer did not match the required schema: ${retry.errors.join('; ')}. Previous output tail: ${retry.tail}. Return the full answer again and END with a JSON object that matches.`
+        : 'END YOUR OUTPUT with exactly one JSON object matching this schema. No prose or markdown fences may appear after it.',
+      JSON.stringify(schema),
+    ].join('\n');
+  }
+
+  /**
+   * The last JSON object in the output, validated against the schema. Found
+   * the way hasStructuredAnswer finds a trailing array: from the final "}"
+   * walk back over each "{" and try to parse — no hand-rolled brace/quote
+   * scanner (a reverse scan mis-handles \" inside strings and would waste
+   * the single schema retry on a valid answer).
+   */
+  readTrailingObject(path, schema) {
+    let text;
+    try { text = readFileSync(path, 'utf8'); } catch (err) { return { ok: false, errors: [`output file could not be read: ${err.message}`] }; }
+    const trimmed = text.trimEnd();
+    if (!trimmed.endsWith('}')) return { ok: false, errors: ['output did not end with a JSON object'] };
+    const close = trimmed.length - 1;
+    // Walk "{" positions from the right. Inner braces of the trailing object
+    // parse (as nested objects), then its own "{" parses (the widest), then
+    // every brace further left belongs to prose and fails. The trailing object
+    // is therefore the LAST successful parse before the first failure — never
+    // the first success, which would be its innermost nested object.
+    // (Adversarial review 2026-08-29 caught the first-success version
+    // recording {"ok":"inner"} out of {"wrapper":{"ok":"inner"}}.)
+    let best = null;
+    let parseError = null;
+    // lastIndexOf clamps a negative fromIndex to 0, so the walk must stop
+    // explicitly at position 0 or it spins forever on output that starts with "{".
+    for (let start = trimmed.lastIndexOf('{', close); start !== -1; start = start > 0 ? trimmed.lastIndexOf('{', start - 1) : -1) {
+      let value;
+      try { value = JSON.parse(trimmed.slice(start, close + 1)); } catch (err) {
+        if (best) break;
+        parseError = err.message;
+        continue;
+      }
+      if (value !== null && typeof value === 'object' && !Array.isArray(value)) best = value;
+      else if (best) break;
+    }
+    if (!best) return { ok: false, errors: [parseError ? `trailing JSON object could not be parsed: ${parseError}` : 'output did not contain a balanced trailing JSON object'] };
+    const checked = validateAgainstSchema(best, schema);
+    return checked.ok ? { ok: true, data: best } : checked;
+  }
+
+  async dispatchWithOutputSchema(step, taskText, targetDir, paths, opts = {}) {
+    const schema = step.outputSchema;
+    // Schema validation owns the retry: generic dispatch retries would make
+    // the promised single schema retry depend on workflow settings. Pool
+    // escalation is orthogonal — it only follows a dispatch that FAILED
+    // (exit/content gate); a schema-invalid answer is a successful dispatch,
+    // so the schema retry count stays exactly one.
+    const first = await this.dispatch(step, this.schemaTaskText(taskText, schema), targetDir, paths, {
+      ...opts,
+      retryAttempts: 0,
+    });
+    if (!first.ok) return { verdict: first, schema: null };
+    let checked = this.readTrailingObject(first.outFile ?? paths.outFile, schema);
+    if (checked.ok) {
+      this.emit('action.output_validated', { actionId: this.actionId(step, opts), keys: Object.keys(checked.data) });
+      return { verdict: first, schema: checked };
+    }
+    const firstSchemaErrors = checked.errors;
+    this.emit('action.output_schema_retry', { actionId: this.actionId(step, opts), errors: checked.errors });
+    const retry = await this.dispatch(step, this.schemaTaskText(taskText, schema, {
+      errors: checked.errors,
+      tail: (() => { try { return readFileSync(first.outFile ?? paths.outFile, 'utf8').slice(-2000); } catch { return ''; } })(),
+    }), targetDir, paths, { ...opts, retryAttempts: 0 });
+    if (retry.ok) checked = this.readTrailingObject(retry.outFile ?? paths.outFile, schema);
+    if (retry.ok && checked.ok) {
+      this.emit('action.output_validated', { actionId: this.actionId(step, opts), keys: Object.keys(checked.data) });
+      return { verdict: retry, schema: checked };
+    }
+    // Report the latest evidence: the retry's schema errors when it ran, the
+    // first attempt's when the retry dispatch itself failed.
+    const errors = retry.ok ? checked.errors : firstSchemaErrors;
+    return {
+      verdict: { ...retry, ok: false, why: `output did not match outputSchema: ${errors[0]}` },
+      schema: { ok: false, errors },
+    };
+  }
+
   async runSingle(step, scope, opts = {}) {
     this.enforceRequiredInputs(step.id);
     const rendered = renderDeep(
@@ -907,14 +999,25 @@ export class WorkflowRuntime {
       outFile: join(this.runDir, `out-${stamp}.md`),
     };
 
-    const verdict = await this.dispatch(step, taskText, targetDir, paths, {
+    const dispatched = step.outputSchema
+      ? await this.dispatchWithOutputSchema(step, taskText, targetDir, paths, {
+        escalate: this.state.settings.escalateOnFail !== false,
+        retryAttempts: opts.retryAttempts,
+        phase: opts.phase,
+      })
+      : { verdict: await this.dispatch(step, taskText, targetDir, paths, {
       escalate: this.state.settings.escalateOnFail !== false,
       retryAttempts: opts.retryAttempts,
       phase: opts.phase,
-    });
+      }) };
+    const verdict = dispatched.verdict;
     delete this.state.activeAgents?.[step.id];
     const finalPaths = { taskFile: verdict.taskFile ?? paths.taskFile, outFile: verdict.outFile ?? paths.outFile };
-    this.recordOutput(step.id, verdict, finalPaths);
+    this.recordOutput(step.id, verdict, finalPaths, step.outputSchema ? {
+      data: dispatched.schema?.data,
+      schemaOk: dispatched.schema?.ok === true,
+      ...(dispatched.schema?.ok === false ? { schemaErrors: dispatched.schema.errors } : {}),
+    } : {});
     if (verdict.ok) this.emit('artifact.published', { actionId: step.id, outFile: finalPaths.outFile });
     return verdict;
   }
@@ -992,7 +1095,7 @@ export class WorkflowRuntime {
       outFile: join(this.runDir, `out-${stamp}.md`),
     };
 
-    const verdict = await this.dispatch(step, taskText, targetDir, paths, {
+    let verdict = await this.dispatch(step, taskText, targetDir, paths, {
       escalate: this.state.settings.escalateOnFail !== false,
       retryAttempts: opts.retryAttempts,
       phase: opts.phase,
@@ -1001,18 +1104,45 @@ export class WorkflowRuntime {
 
     const finalPaths = { taskFile: verdict.taskFile ?? paths.taskFile, outFile: verdict.outFile ?? paths.outFile };
 
-    let parsed = null;
-    let parseError = null;
-    try {
-      const out = readFileSync(finalPaths.outFile, 'utf8');
-      const start = out.indexOf('{');
-      const end = out.lastIndexOf('}');
-      if (start >= 0 && end > start) {
-        const j = JSON.parse(out.slice(start, end + 1));
-        if (j && typeof j === 'object') parsed = j;
+    const parseVerdictFile = (path) => {
+      try {
+        const out = readFileSync(path, 'utf8');
+        const start = out.indexOf('{');
+        const end = out.lastIndexOf('}');
+        if (start >= 0 && end > start) {
+          const j = JSON.parse(out.slice(start, end + 1));
+          if (j && typeof j === 'object') return { parsed: j, parseError: null };
+        }
+        return { parsed: null, parseError: null };
+      } catch (err) {
+        return { parsed: null, parseError: err.message };
+      }
+    };
+    let { parsed, parseError } = parseVerdictFile(finalPaths.outFile);
+
+    // An unparseable verdict gets ONE bounded re-ask before it can cost a
+    // planner boundary. Observed 2026-08-29 (run ejk9w2): final-check returned
+    // an unparseable reply, the boundary consulted the planner, and the
+    // follow-up program spent ~8 minutes re-proving a passing state — the
+    // same economics that give outputSchema its single retry.
+    if (verdict.ok && !parsed) {
+      this.emit('verify.verdict_retry', { actionId: step.id, why: parseError ?? 'no JSON object in verdict' });
+      const retryVerdict = await this.dispatch(step, [
+        taskText,
+        '',
+        `Your previous reply could not be used: ${parseError ?? 'it did not contain a parseable JSON object'}.`,
+        'Do the review again if needed, then RETURN ONLY the single JSON object {"ok": <true|false>, "concerns": [...], "summary": "..."} — no prose, no markdown fences, nothing before "{" or after "}".',
+      ].join('\n'), targetDir, paths, {
+        escalate: this.state.settings.escalateOnFail !== false,
+        retryAttempts: 0,
+        phase: opts.phase,
+      });
+      if (retryVerdict.ok) {
+        verdict = retryVerdict;
+        finalPaths.taskFile = retryVerdict.taskFile ?? finalPaths.taskFile;
+        finalPaths.outFile = retryVerdict.outFile ?? finalPaths.outFile;
+        ({ parsed, parseError } = parseVerdictFile(finalPaths.outFile));
       }
-    } catch (err) {
-      parseError = err.message;
     }
 
     const ok = verdict.ok && !!parsed && parsed.ok === true;
@@ -1056,9 +1186,7 @@ export class WorkflowRuntime {
         decisionSequence: steering.decisionSequence,
       });
     }
-    // The planner sees what each action actually said, not just ok/why: an
-    // excerpt of every output, newest first, under a total character budget so
-    // long runs stay within the planner's context.
+    const previousDecisionAt = this.state.decisions?.at?.(-1)?.createdAt ?? null;
     let excerptBudget = PLANNER_EXCERPT_TOTAL_CHARS;
     const excerptFor = (output) => {
       const text = typeof output?.outputText === 'string' ? output.outputText.trim() : '';
@@ -1069,33 +1197,56 @@ export class WorkflowRuntime {
       excerptBudget -= excerpt.length;
       return { outputExcerpt: excerpt, outputChars: text.length };
     };
+    // "Full" excerpts still obey the per-excerpt/total budget: a turn with
+    // many fresh actions must not rebuild the 163 k contexts this replaced.
     const outputEntries = Object.entries(this.state.outputs ?? {});
-    const excerpts = new Map(outputEntries.slice().reverse().map(([id, output]) => [id, excerptFor(output)]));
+    const ledgerById = new Map((this.state.actionLedger ?? []).map((action) => [action.id, action]));
+    const isNewOutput = (id) => {
+      const finishedAt = ledgerById.get(id)?.finishedAt;
+      return Boolean(previousDecisionAt && finishedAt && Date.parse(finishedAt) > Date.parse(previousDecisionAt));
+    };
+    const excerpts = new Map(outputEntries.slice().reverse().map(([id, output]) => {
+      const full = id === 'scout' || isNewOutput(id) || output?.verify?.ok === false;
+      if (full) return [id, excerptFor(output)];
+      if (output?.ok !== true) return [id, excerptFor(output)];
+      const text = typeof output?.outputText === 'string' ? output.outputText.trim() : '';
+      return [id, { outputExcerpt: text ? text.slice(0, 200) : null, outputChars: text.length }];
+    }));
     const outputs = Object.fromEntries(outputEntries.map(([id, output]) => [id, {
       ok: output?.ok,
       why: output?.why ?? null,
       pool: output?.pool ?? null,
-      outFile: output?.outFile ?? null,
-      verify: output?.verify ?? null,
+       outFile: output?.outFile ?? null,
+       data: output?.data ?? null,
+       schemaOk: output?.schemaOk,
+       schemaErrors: output?.schemaErrors ?? null,
+       verify: output?.verify ?? null,
       total: output?.total,
       succeeded: output?.succeeded,
       failed: output?.failed,
       itemsFrom: output?.itemsFrom,
       ...excerpts.get(id),
     }]));
-    const actionForPlanner = (action) => ({
-      id: action.id,
-      parentId: action.parentId ?? null,
-      type: action.kind,
-      phase: action.phase ?? null,
-      status: action.status,
-      dependsOn: action.dependsOn ?? [],
-      item: action.item,
-      attempts: (action.attempts ?? []).map((index) => this.state.attempts?.[index]).filter(Boolean),
-      startedAt: action.startedAt ?? null,
-      finishedAt: action.finishedAt ?? null,
-      why: action.why ?? null,
-    });
+    const actionForPlanner = (action) => {
+      const attempts = (action.attempts ?? []).map((index) => this.state.attempts?.[index]).filter(Boolean);
+      const lastAttempt = attempts.at(-1);
+      const startedAt = Date.parse(action.startedAt ?? '');
+      const finishedAt = Date.parse(action.finishedAt ?? '');
+      const row = {
+        id: action.id,
+        type: action.kind,
+        phase: action.phase ?? null,
+        status: action.status,
+        pool: lastAttempt?.pool ?? null,
+        model: lastAttempt?.model ?? null,
+        durationSec: Number.isFinite(startedAt) && Number.isFinite(finishedAt)
+          ? Math.round((finishedAt - startedAt) / 100) / 10 : null,
+        attempts: attempts.length,
+        why: action.why ?? null,
+      };
+      if (action.item !== undefined) row.item = action.item;
+      return row;
+    };
     const workflowElapsedSec = Math.max(0,
       (Date.now() - Date.parse(this.state.startedAt)) / 1000);
     const workflowTargetSec = this.state.settings?.maxWorkflowSeconds == null
@@ -1121,7 +1272,7 @@ export class WorkflowRuntime {
         ['succeeded', 'failed_terminal', 'cancelled', 'abandoned'].includes(action.status)).map(actionForPlanner),
       outputs,
       failures: (this.state.actionLedger ?? []).filter((action) =>
-        ['failed_terminal', 'abandoned'].includes(action.status)).map(actionForPlanner),
+        ['failed_terminal', 'abandoned'].includes(action.status)).map((action) => action.id),
       closedPhases: [...new Set((this.state.plan?.actions ?? [])
         .filter((action) => action.source === 'planner')
         .map((action) => action.definition?.phase)
@@ -1130,7 +1281,6 @@ export class WorkflowRuntime {
       executionConstraints: {
         concurrency: Number(this.state.settings?.concurrency ?? 1) || 1,
         readySiblingsRunConcurrently: true,
-        programFeatures: ['itemsFrom', 'repair', 'completion'],
         plannerConsultedOnlyAtProgramBoundary: true,
         actionTimeoutSec: Number(step.actionDefaults?.timeoutSec ?? step.timeoutSec) || null,
         actionTimeoutIsExplicitOptIn: step.actionDefaults?.timeoutSec != null || step.timeoutSec != null,
@@ -1163,14 +1313,20 @@ export class WorkflowRuntime {
           lanes: pool.lanes ?? pool.connector?.lanes ?? [],
           capabilities: pool.capabilities ?? pool.connector?.capabilities ?? [],
           pace: pool.pace ?? null,
-        })),
-    };
+         })),
+     };
+    const contextJson = JSON.stringify(plannerContext);
+    this.emit('decision.context_built', {
+      sequence: (this.state.decisions?.length ?? 0) + 1,
+      chars: contextJson.length,
+      keys: Object.fromEntries(Object.entries(plannerContext).map(([key, value]) => [key, JSON.stringify(value).length])),
+    });
     const rendered = renderDeep({
       prompt: step.prompt ?? 'Judge whether the workflow has enough evidence to finish.',
       addDir: step.addDir,
     }, scope, this.renderOpts(step.id));
     const taskText = [
-      rendered.prompt,
+      rendered.prompt.replaceAll('__BULLSWARM_ITEM_TEMPLATE__', '{{item}}'),
       '',
       ...(opts.correction ? [
         `CORRECTION REQUIRED (attempt ${opts.correction.attempt} of ${opts.correction.maxAttempts}): the runtime rejected your previous decision. validationFeedback in the durable context lists the exact issues. Fix only those issues and return the corrected JSON decision. No prose, no markdown fences.`,
@@ -1181,44 +1337,7 @@ export class WorkflowRuntime {
       'Every proposed action MUST use the field "type" (never "kind").',
       'Every action MUST include a forward-only kebab-case "phase". Never reuse a name listed in closedPhases.',
       '',
-      'PLANNING DOCTRINE — you are compiling the goal into a PROGRAM, not choosing the next step:',
-      '- The runtime executes your whole decision to completion without consulting you: a ready-set scheduler starts every action whose dependsOn have all succeeded, concurrently up to executionConstraints.concurrency, and starts each dependent the moment its own dependencies finish. You are consulted again only at the program boundary, when every action has finished or the graph is blocked. Each consultation is a separate process round trip (typically 1-2 minutes), so anything decidable by data must be encoded in the program, never deferred to a later decision.',
-      '- Propose the COMPLETE dependency graph you can see now: discovery, per-item work, per-item verification, and the final whole-system verification, all in ONE decision. A decision carrying a single action when several are obvious wastes a round trip.',
-      '- Unknown item count: never spend a decision to learn how many items there are. Propose a discovery run action whose prompt ends with "RETURN ONLY a JSON array of <items>", plus a fanout with "itemsFrom":"outputs.<discovery-id>.outFile" whose stepTemplate.prompt uses {{item}}. The runtime resolves the list when discovery finishes (with one bounded read-only extraction retry if the output is not a clean array) and fans out immediately.',
-      '- Verification failures: give each verify a "repair" policy {"prompt":"<how to fix what the verifier rejects>","maxRounds":1-3}. When the verifier returns ok:false, the runtime runs a fix action carrying the verifier concerns verbatim and re-runs the same verify, inside the program. Only verifies still failing after their rounds come back to you.',
-      '- A verify that returned ok:true is accepted. Its concerns are informational (overlaps, wording nits, "non-blocking" notes): do not spend a program round polishing them unless the goal text itself demands it. Only ok:false verifies are work.',
-      '- Self-completing programs: when the program you propose ends with verification that would satisfy the goal, add a top-level "completion": {"when":"all-actions-ok","reason":"<what a clean run proves>"}. If every action of the program (repairs included) finishes ok and the completion policy is met, the runtime records the completion itself and does not consult you again; anything failing brings the boundary back to you. Use it on every program whose clean run would be the finished goal.',
-      '- Per-item chains: for N known items propose N focused run actions plus N verify actions, each verify depending only on its own run, so verifying one item overlaps with fixing another; add one final verify depending on all of them. For items discovered at run time use the discovery → fanout → verify shape above.',
-      '- File ownership: every action prompt must name exactly which files it may edit and state that it must not touch any other file. Two actions that must edit the same file MUST be ordered with dependsOn; never let concurrent actions write the same file.',
-      '- Self-contained prompts: a worker sees only its own prompt, never this context. Each prompt must state the absolute working directory, what to read, what to change, the exact command that proves success, and what to report back. Prefer many small parallel actions over one large serial one.',
-      '- Read before you compile: outputs.<id>.outputExcerpt is what each finished action actually reported (outputs.scout, when present, is a read-only survey of the repository: tree, manifest, test status, units of work, shared files, risks). Name real files, modules, and commands from it in your program instead of guessing.',
-      '',
-      'Action skeletons (copy the shape exactly; every field shown is required unless marked optional):',
-      '  run:    {"id":"bounded-action","type":"run","phase":"implement","prompt":"Do bounded work.","dependsOn":["prior-action"]}',
-      '  fanout: {"id":"per-item-check","type":"fanout","phase":"inspect","items":["alpha","beta"],"stepTemplate":{"prompt":"Inspect {{item}} and report concrete evidence."},"dependsOn":["prior-action"]}',
-      '  fanout (data-driven): {"id":"per-module-fix","type":"fanout","phase":"fix","itemsFrom":"outputs.discover-modules.outFile","stepTemplate":{"prompt":"In /abs/repo fix only the module {{item}}; run its focused test; report the diff summary."}}',
-      '  verify: {"id":"independent-check","type":"verify","phase":"verify","prompt":"Independently re-run the tests and report pass/fail with evidence.","dependsOn":["bounded-action"],"repair":{"prompt":"In /abs/repo fix the failing behaviour the verifier reports, editing only the files named in the concerns, then re-run the tests.","maxRounds":1}}',
-      'verify semantics: the reviewer receives the artifact of the action named in review, which the runtime infers as outputs.<the single dependsOn>.outFile; put the reviewer INSTRUCTIONS in prompt. A verify with several dependsOn must set review explicitly to "outputs.<actionId>.outFile". review is never instructions or a filesystem path.',
-      'Program skeleton (discovery → data-driven fan-out → verify with repair → final whole-suite check, all in ONE decision; the runtime runs it to the end without you):',
-      '  [{"id":"discover-modules","type":"run","phase":"discover","prompt":"In /abs/repo list every module under src/ whose test in tests/ fails. Do not edit anything. RETURN ONLY a JSON array of module names, e.g. [\\"alpha\\",\\"beta\\"]."},',
-      '   {"id":"fix-module","type":"fanout","phase":"fix","itemsFrom":"outputs.discover-modules.outFile","stepTemplate":{"prompt":"In /abs/repo edit only src/{{item}}.js so tests/{{item}}.test.js passes; run node --test tests/{{item}}.test.js; report the diff summary."}},',
-      '   {"id":"verify-modules","type":"verify","phase":"verify-items","prompt":"For every module in the reviewed fan-out summary re-run node --test tests/<module>.test.js in /abs/repo and confirm tests/ is unchanged.","dependsOn":["fix-module"],"repair":{"prompt":"In /abs/repo fix the modules the verifier lists, editing only their src files, and re-run their tests.","maxRounds":2}},',
-      '   {"id":"verify-suite","type":"verify","phase":"verify-suite","prompt":"Run the full npm test in /abs/repo and report pass/fail counts.","dependsOn":["verify-modules"]}]',
-      'Graph skeleton (two parallel fix→verify chains plus a final whole-suite check, all in ONE decision):',
-      '  [{"id":"fix-alpha","type":"run","phase":"fix","prompt":"In /abs/repo edit only src/alpha.js so tests/alpha.test.js passes; run node --test tests/alpha.test.js; report the diff summary."},',
-      '   {"id":"fix-beta","type":"run","phase":"fix","prompt":"In /abs/repo edit only src/beta.js so tests/beta.test.js passes; run node --test tests/beta.test.js; report the diff summary."},',
-      '   {"id":"verify-alpha","type":"verify","phase":"verify-items","prompt":"Re-run node --test tests/alpha.test.js in /abs/repo and confirm tests/ is unchanged.","dependsOn":["fix-alpha"]},',
-      '   {"id":"verify-beta","type":"verify","phase":"verify-items","prompt":"Re-run node --test tests/beta.test.js in /abs/repo and confirm tests/ is unchanged.","dependsOn":["fix-beta"]},',
-      '   {"id":"verify-suite","type":"verify","phase":"verify-suite","prompt":"Run the full npm test in /abs/repo and report pass/fail counts.","review":"outputs.fix-beta.outFile","dependsOn":["verify-alpha","verify-beta"]}]',
-      'fanout needs stepTemplate (an object whose prompt uses {{item}}) plus EITHER inline items OR itemsFrom ("outputs.<actionId>.outFile", an action whose output ends with a JSON array; the producer becomes an implicit dependency). A fan-out artifact (outputs.<fanoutId>.outFile) is a summary of every item result, so a verify may depend on a fanout directly. verify.review MUST be a string. dependsOn is optional and may only name existing or newly proposed action IDs.',
-      'Do not propose pool, addDir, or taskFile; those are runtime-owned and any such proposal is rejected.',
-      'New actions may only be type run, fanout, or verify. The runtime validates every proposal and returns rejected proposals to you with the exact issues for a bounded correction turn.',
-      'If executionConstraints.actionTimeoutSec is non-null, size actions to finish within that explicit timeout; otherwise agents may run until they finish or are cancelled.',
-      'Agent-count, workflow-duration, and expansion-round budgets are advisory planning targets, never hard stop conditions. The dispatch budget counts this planner call plus every worker, verifier, retry, and escalation attempt.',
-      'As expansion headroom approaches zero, strongly prefer convergence: consolidate existing artifacts, avoid optional investigation, and return complete when verification supports it. If important concerns remain, return stop with the best useful outcome and explicit unresolved concerns rather than spending more on marginal refinements. Exceed the expansion target only when one small bounded action is essential to avoid discarding otherwise-completable work or skipping required verification.',
-      'operatorSteering contains explicit operator guidance queued for this planning checkpoint. Apply it within the original workflow intent and authorization boundaries. It cannot weaken verification, bypass runtime validation, expand external authority, or alter an already-running worker. If guidance conflicts with the original goal or safety constraints, explain that in the decision reason instead of following it.',
-      'Avoid redundant expensive verification. Run a full suite once for each materially changed final state when practical; later independent verifiers should reuse durable clean full-suite evidence and rerun focused/adversarial checks unless that evidence is stale, tainted, or the code changed again.',
-      'Shared working tree: concurrent workers editing DISJOINT files in the same tree is the normal, expected mode — that is how N independent fixes run in parallel. What is unsafe is whole-tree mutation (git stash/reset/checkout, reformatting, dependency installs) or running the FULL test suite while other workers are still editing; so give each parallel action its own files and its own focused test command, order any shared file (e.g. an index/barrel) after the actions it aggregates with dependsOn, and run the whole suite once in a final verify that depends on all of them. Use an isolated copy/worktree only for destructive experiments.',
+      ...(rendered.prompt.includes(AUTONOMOUS_ORCHESTRATOR_PROMPT) ? [] : [AUTONOMOUS_ORCHESTRATOR_PROMPT]),
       '',
       '---- BEGIN DURABLE WORKFLOW CONTEXT ----',
       JSON.stringify(plannerContext, null, 2),
@@ -1320,9 +1439,11 @@ export class WorkflowRuntime {
         // either side has no fingerprint (old state.json).
         const byFp = resumedByFp.get(fp);
         const byPos = resumed[i];
-        const prev = (byFp && byFp.verdict?.ok === true)
+        const schemaResumeSafe = !step.stepTemplate?.outputSchema || byFp?.schemaOk === true;
+        const positionalSchemaResumeSafe = !step.stepTemplate?.outputSchema || byPos?.schemaOk === true;
+        const prev = (byFp && byFp.verdict?.ok === true && schemaResumeSafe)
           ? byFp
-          : ((!byFp && byPos?.verdict?.ok === true) ? byPos : null);
+          : ((!byFp && byPos?.verdict?.ok === true && positionalSchemaResumeSafe) ? byPos : null);
 
         if (prev) {
           results[i] = { ...prev, item, fingerprint: fp };
@@ -1362,12 +1483,15 @@ export class WorkflowRuntime {
           ?? readFileSync(String(template.taskFile), 'utf8');
 
         this.emit('item.started', { stepId: step.id, index: i, total: items.length, item });
-        const verdict = await this.dispatch(
-          { ...step, ...template, id: step.id },
-          taskText, targetDir, paths,
-          { item, itemIndex: i, phase: opts.phase, escalate: this.state.settings.escalateOnFail !== false, retryAttempts: opts.retryAttempts },
-        );
-        results[i] = { item, verdict, outFile: verdict.outFile ?? paths.outFile, fingerprint: fp };
+         const itemStep = { ...step, ...template, id: step.id, ...(template.outputSchema ? { outputSchema: template.outputSchema } : {}) };
+         const dispatched = itemStep.outputSchema
+           ? await this.dispatchWithOutputSchema(itemStep, taskText, targetDir, paths,
+             { item, itemIndex: i, phase: opts.phase, escalate: this.state.settings.escalateOnFail !== false, retryAttempts: opts.retryAttempts })
+           : { verdict: await this.dispatch(itemStep, taskText, targetDir, paths,
+             { item, itemIndex: i, phase: opts.phase, escalate: this.state.settings.escalateOnFail !== false, retryAttempts: opts.retryAttempts }) };
+         const verdict = dispatched.verdict;
+         results[i] = { item, verdict, outFile: verdict.outFile ?? paths.outFile, fingerprint: fp,
+           ...(itemStep.outputSchema ? { data: dispatched.schema?.data, schemaOk: dispatched.schema?.ok === true, ...(dispatched.schema?.ok === false ? { schemaErrors: dispatched.schema.errors } : {}) } : {}) };
         if (verdict.ok) {
           this.emit('item.completed', { stepId: step.id, index: i, pool: verdict.pick?.pool, wall: verdict.meta?.wallSec });
         } else {
@@ -1447,7 +1571,7 @@ export class WorkflowRuntime {
     return { outFile, outputText: truncated ? full.slice(0, OUTPUT_TEXT_CAP_BYTES) : full, truncated };
   }
 
-  recordOutput(stepId, verdict, paths) {
+  recordOutput(stepId, verdict, paths, extra = {}) {
     let outputText = null;
     let truncated = false;
     try {
@@ -1469,6 +1593,7 @@ export class WorkflowRuntime {
       wallSec: verdict.meta?.wallSec,
       outputText,
       outputTruncated: truncated || undefined,
+      ...extra,
     };
     this.persist();
   }

package/src/workflow/schema.js

@@ -0,0 +1,80 @@
+const TYPES = new Set(['object', 'array', 'string', 'number', 'integer', 'boolean', 'null']);
+const KEYWORDS = new Set(['type', 'properties', 'required', 'additionalProperties', 'items', 'minItems', 'maxItems', 'enum', 'minimum', 'maximum', 'minLength', 'pattern', 'description']);
+
+function matches(value, type) {
+  if (type === 'null') return value === null;
+  if (type === 'object') return value !== null && typeof value === 'object' && !Array.isArray(value);
+  if (type === 'array') return Array.isArray(value);
+  if (type === 'integer') return Number.isInteger(value);
+  if (type === 'number') return typeof value === 'number' && Number.isFinite(value);
+  return typeof value === type;
+}
+
+function validateNode(value, schema, path, errors) {
+  if (schema.type !== undefined) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!types.some((type) => matches(value, type))) {
+      errors.push(`${path || 'value'} must be ${types.join('|')}`);
+      return;
+    }
+  }
+  if (schema.enum !== undefined && !schema.enum.some((candidate) => Object.is(candidate, value))) errors.push(`${path || 'value'} must be one of ${JSON.stringify(schema.enum)}`);
+  if (typeof value === 'string') {
+    if (schema.minLength !== undefined && value.length < schema.minLength) errors.push(`${path || 'value'} must have at least ${schema.minLength} characters`);
+    if (schema.pattern !== undefined && !(new RegExp(schema.pattern)).test(value)) errors.push(`${path || 'value'} must match pattern ${JSON.stringify(schema.pattern)}`);
+  }
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    if (schema.minimum !== undefined && value < schema.minimum) errors.push(`${path || 'value'} must be at least ${schema.minimum}`);
+    if (schema.maximum !== undefined && value > schema.maximum) errors.push(`${path || 'value'} must be at most ${schema.maximum}`);
+  }
+  if (Array.isArray(value)) {
+    if (schema.minItems !== undefined && value.length < schema.minItems) errors.push(`${path || 'value'} must contain at least ${schema.minItems} items`);
+    if (schema.maxItems !== undefined && value.length > schema.maxItems) errors.push(`${path || 'value'} must contain at most ${schema.maxItems} items`);
+    if (schema.items) value.forEach((item, index) => validateNode(item, schema.items, `${path}[${index}]`, errors));
+  }
+  if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+    const properties = schema.properties ?? {};
+    // Own properties only: `in` would count inherited names (toString,
+    // constructor, __proto__) as present or as declared.
+    for (const key of schema.required ?? []) if (!Object.hasOwn(value, key)) errors.push(`${path ? `${path}.` : ''}${key} is required`);
+    for (const [key, child] of Object.entries(properties)) if (Object.hasOwn(value, key)) validateNode(value[key], child, `${path ? `${path}.` : ''}${key}`, errors);
+    if (schema.additionalProperties === false) for (const key of Object.keys(value)) if (!Object.hasOwn(properties, key)) errors.push(`${path ? `${path}.` : ''}${key} is not allowed`);
+  }
+}
+
+function schemaIssues(schema, path = 'schema') {
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) return [`${path} must be an object`];
+  const issues = [];
+  for (const key of Object.keys(schema)) if (!KEYWORDS.has(key)) issues.push(`${path}.${key} is an unknown keyword`);
+  if (schema.type !== undefined) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!types.length || types.some((type) => !TYPES.has(type))) issues.push(`${path}.type must be a supported type or array of supported types`);
+  }
+  if (schema.properties !== undefined && (!schema.properties || typeof schema.properties !== 'object' || Array.isArray(schema.properties))) issues.push(`${path}.properties must be an object`);
+  else for (const [key, child] of Object.entries(schema.properties ?? {})) issues.push(...schemaIssues(child, `${path}.properties.${key}`));
+  if (schema.required !== undefined && (!Array.isArray(schema.required) || schema.required.some((key) => typeof key !== 'string'))) issues.push(`${path}.required must be an array of strings`);
+  if (schema.additionalProperties !== undefined && typeof schema.additionalProperties !== 'boolean') issues.push(`${path}.additionalProperties must be a boolean`);
+  if (schema.items !== undefined) issues.push(...schemaIssues(schema.items, `${path}.items`));
+  if (schema.enum !== undefined && !Array.isArray(schema.enum)) issues.push(`${path}.enum must be an array`);
+  for (const key of ['minItems', 'maxItems', 'minLength']) if (schema[key] !== undefined && (!Number.isInteger(schema[key]) || schema[key] < 0)) issues.push(`${path}.${key} must be a non-negative integer`);
+  for (const key of ['minimum', 'maximum']) if (schema[key] !== undefined && (typeof schema[key] !== 'number' || !Number.isFinite(schema[key]))) issues.push(`${path}.${key} must be a finite number`);
+  if (schema.pattern !== undefined) {
+    if (typeof schema.pattern !== 'string') issues.push(`${path}.pattern must be a string`);
+    else try { new RegExp(schema.pattern); } catch (err) { issues.push(`${path}.pattern is not a valid regex: ${err.message}`); }
+  }
+  if (schema.description !== undefined && typeof schema.description !== 'string') issues.push(`${path}.description must be a string`);
+  return issues;
+}
+
+export function isValidOutputSchema(schema) {
+  const issues = schemaIssues(schema);
+  return { ok: issues.length === 0, issues };
+}
+
+export function validateAgainstSchema(value, schema) {
+  const validity = isValidOutputSchema(schema);
+  if (!validity.ok) return { ok: false, errors: validity.issues };
+  const errors = [];
+  validateNode(value, schema, '', errors);
+  return { ok: errors.length === 0, errors };
+}

package/src/workflow/template.js

@@ -50,7 +50,7 @@ export function renderTemplate(str, scope, opts = {}) {
       if (typeof opts.onUnresolved === 'function') opts.onUnresolved(ref.trim());
       return match;
     }
-    return typeof v === 'string' ? v : JSON.stringify(v);
+    return typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean' ? String(v) : JSON.stringify(v);
   });
 }
 
@@ -79,6 +79,9 @@ export function extractItems(state, itemsFrom) {
     throw new Error(`fanout itemsFrom "${itemsFrom}" not found in workflow state`);
   }
   if (Array.isArray(v)) return v;
+  if (/^outputs\.[A-Za-z0-9_-]+\.data\.[A-Za-z0-9_-]+$/.test(itemsFrom)) {
+    throw new Error(`fanout itemsFrom "${itemsFrom}" must resolve to an array (got ${typeof v})`);
+  }
 
   // outputs.<stepId> envelope (state.outputs.<id> is the full record
   // with ok/pool/outFile/outputText): use the recorded outputText,

package/src/workflow/validate.js

@@ -8,6 +8,7 @@
 //       typo never burns quota discovering itself mid-run.
 
 import { TEMPLATE_TOKEN_RE, isTemplateRef } from './template.js';
+import { isValidOutputSchema } from './schema.js';
 
 const LANES = ['analyze', 'build', 'chore'];
 const ON_ERROR = ['continue', 'fail', 'skip-phase'];
@@ -154,10 +155,10 @@ export function validateWorkflow(wf, { lanes = LANES, poolNames = [] } = {}) {
         if (typeof step.itemsFrom === 'string' && step.itemsFrom.includes('.')) {
           const [root, target] = step.itemsFrom.split('.');
           collect(issues, root === 'inputs' || (root === 'outputs' && outputs.has(target)),
-            `${sat}.itemsFrom "${step.itemsFrom}" cannot resolve (use inputs.<name> or outputs.<priorStepId>)`);
+            `${sat}.itemsFrom "${step.itemsFrom}" cannot resolve (use inputs.<name> or outputs.<priorStepId>[.data.<field>])`);
         } else if (typeof step.itemsFrom === 'string') {
           collect(issues, false,
-            `${sat}.itemsFrom "${step.itemsFrom}" must be a dotted path (inputs.<name> or outputs.<priorStepId>)`);
+            `${sat}.itemsFrom "${step.itemsFrom}" must be a dotted path (inputs.<name> or outputs.<priorStepId>[.data.<field>])`);
         }
         collect(issues, step.stepTemplate && typeof step.stepTemplate === 'object',
           `${sat}.stepTemplate is required for fanout steps`);
@@ -168,10 +169,20 @@ export function validateWorkflow(wf, { lanes = LANES, poolNames = [] } = {}) {
         if (step.items != null) {
           collect(issues, Array.isArray(step.items), `${sat}.items must be an array`);
         }
+        if (step.stepTemplate?.outputSchema !== undefined) {
+          const schema = isValidOutputSchema(step.stepTemplate.outputSchema);
+          collect(issues, schema.ok, `${sat}.stepTemplate.outputSchema is invalid: ${schema.issues.join('; ')}`);
+          if (schema.ok) collect(issues, step.stepTemplate.outputSchema.type === 'object', `${sat}.stepTemplate.outputSchema.type must be "object"`);
+        }
       } else if (step.type === 'run') {
         collect(issues,
           typeof step.taskFile === 'string' || typeof step.prompt === 'string',
           `${sat} needs taskFile or prompt`);
+        if (step.outputSchema !== undefined) {
+          const schema = isValidOutputSchema(step.outputSchema);
+          collect(issues, schema.ok, `${sat}.outputSchema is invalid: ${schema.issues.join('; ')}`);
+          if (schema.ok) collect(issues, step.outputSchema.type === 'object', `${sat}.outputSchema.type must be "object"`);
+        }
       } else if (step.type === 'verify') {
         collect(issues, typeof step.review === 'string' && step.review.length > 0,
           `${sat}.review is required for verify steps (path to a prior outFile, e.g. outputs.<prior>.outFile)`);