bullswarm 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # bullswarm changelog
 
+## 0.12.0 — one decision is a whole program
+
+Completes the convergence on Claude Code's dynamic-workflow mechanics
+(`docs/claude-dynamic-workflow-mechanics.md` §1.11 and §4.2): the orchestrator
+is positioned as the compiler of the goal into a program the runtime runs to
+the end, and it is consulted again only at the program boundary (every action
+finished, or the graph blocked).
+
+- Data-driven fan-out in proposals: a planner `fanout` may carry
+  `itemsFrom: "outputs.<actionId>.outFile"` instead of inline `items`. The
+  producer becomes an implicit `dependsOn` and the runtime resolves the item
+  list when the producer finishes, so the planner no longer spends a round trip
+  waiting to see how many items discovery found. If the producer's output has
+  no parseable JSON array, the runtime runs ONE bounded, read-only extraction
+  action (`<fanoutId>-items`, `source: "runtime-extraction"`) over that output
+  before failing the fan-out truthfully. Resolved lists above
+  `maxItemsPerExpansion` fail the fan-out with the count. Events:
+  `action.items_resolved`, `action.items_extraction_requested`,
+  `action.items_extracted`.
+- Repair policy on verify: `repair: { prompt, maxRounds (1–3), effort? }` on a
+  planner `verify`. When the verifier returns `ok:false`, the executor runs a
+  fix action (`<verifyId>-repair-<n>`, `source: "repair-policy"`) carrying the
+  verifier's concerns verbatim and re-runs the same verify, without a planner
+  turn. Dispatch or JSON-parse failures are not repaired. Events:
+  `action.repair_started`, `action.reverify_started`, `action.repaired`,
+  `action.reverify_rejected`, `action.repair_failed`.
+- Fan-out artifact: a fan-out now writes `out-<id>-summary-*.md` (every item's
+  verdict plus an output excerpt) and records it as `outputs.<id>.outFile`, so a
+  verify can depend on a fan-out directly and `review` is inferred as usual.
+- Fix: fan-out outputs stored the success COUNT in `ok`, so a dynamic action
+  depending on a fan-out could never become ready ("blocked by failed or
+  unresolved dependencies") and a fan-out never counted as a successful worker
+  for completion evidence. `ok` is now a boolean and the count moved to
+  `succeeded`; `fanoutSucceededCount()` reads pre-0.12 state files.
+- Fix: the content gate rejected a worker whose whole answer is a JSON array
+  or object as an "announcement without substance", which is exactly what a
+  discovery step is told to return. Structured answers now pass
+  (`hasStructuredAnswer`).
+- `parseJsonArray` prefers the trailing array, so prose containing brackets
+  before the list no longer poisons `itemsFrom`.
+- Planner prompt: PLANNING DOCTRINE rewritten around "you are compiling the
+  goal into a program"; new data-driven fanout and repair skeletons; a
+  four-action program skeleton (discover → fanout(itemsFrom) → verify(repair)
+  → verify-suite); `executionConstraints.programFeatures` and
+  `plannerConsultedOnlyAtProgramBoundary`. The goal orchestrator prompt is
+  reframed the same way.
+- Literal double braces in prompts no longer kill actions. Only a known root
+  followed by dotted identifiers (`{{item}}`, `{{outputs.<id>.outFile}}`,
+  `{{inputs.x}}`, `{{runId}}`, `{{wfDir}}`) is a template ref; any other
+  `{{…}}` text (a JSDoc type such as `{{maxLength?: number}}`, Mustache, a JS
+  object in a template literal) is left exactly as written by the renderer
+  and ignored by the validator. Observed in the 0.11.1 comparison run: a
+  planner-authored verify prompt containing `{{maxLength?: number}}` failed
+  at render time with zero attempts. Relatedly, `verify` no longer
+  template-renders the artifact it reviews: only the reviewer instructions
+  are a template; the worker's report is appended verbatim.
+- Doctrine: an `ok:true` verify is accepted; its concerns are informational.
+  The 0.11.1 comparison run spent a whole extra program round (7 actions,
+  ~10 min) polishing "non-blocking" nits reported by verifiers that had
+  passed, which Claude's fix stage never does.
+- Scout before compiling: `workflow goal` now starts with a read-only `scout`
+  run action (tree, manifest, test status, units of work with the files each
+  owns, shared files, risks; ends with a JSON array of unit names) so the
+  orchestrator's first program names real files and commands — the counterpart
+  of the inline scouting a Claude Code session does before authoring a
+  Workflow script. `--no-scout` skips it. A failed scout is non-fatal: the
+  planner still runs and sees `outputs.scout.ok=false` with the reason, and
+  the scout never counts as a delivery worker.
+- The planner finally sees what workers said: every `outputs.<id>` in the
+  durable planner context carries `outputExcerpt` (up to 3 000 chars each,
+  36 000 total, newest first) instead of only `ok`/`why`/`outFile`.
+- `workflow goal` default `maxItemsPerExpansion` raised 8 → 24 so a
+  data-driven fan-out over a medium repository does not fail on the bound.
+- Known limitation: `itemsFrom` removes the planner turn, not the stage
+  barrier. A verify that depends on a data-driven fan-out waits for all items;
+  per-item verify overlap on discovered items would need chained
+  `stepTemplate`s (not in this release). For known items keep proposing N fix
+  + N verify chains inline, which already overlap under the ready-set
+  scheduler.
+
 ## 0.11.1 — reliable `--watch` handoff
 
 - `workflow goal --watch` no longer races the detached child: the watcher now

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

@@ -149,6 +149,53 @@ multi-phase work (understand → design → implement → review), that often me
 several workflows in sequence — one per phase — so you stay in the loop between
 them."
 
+## 1.11 Upfront plan or mid-flight steering? — the answer
+
+The question that decides how bullswarm should converge: does Claude prepare
+all phases and parallelism **before** the workflow starts, or does it keep
+planning **during** execution?
+
+**Before. Entirely.** The orchestrator model writes one complete program, the
+harness validates it, and then executes it without consulting the model again.
+Evidence:
+
+- **[SPEC]** the script is passed whole and parsed before any agent runs;
+  "Use this tool for multi-step orchestration where control flow should be
+  deterministic (loops, conditionals, fan-out) rather than model-driven";
+  "Workflows run in the background — this tool returns immediately … a
+  task-notification arrives when the workflow completes."
+- **[OBSERVED, goal 2]** ~4 minutes of inline scouting and advisor review →
+  one 23 k-character script (probe → author → adversarial verify → fix-loop,
+  per module) → rejected on a parse error before any agent spawned → corrected
+  in 80 s → ~20 minutes of execution with six agents concurrent and **zero
+  orchestrator decisions**. The session's own words: "the harness will
+  re-invoke me when it completes, so polling would just burn tokens. Waiting."
+
+What *looks* like mid-flight steering is pre-authored into the program:
+
+1. **Data-driven shape.** A stage's structured result (`schema`) becomes the
+   next stage's items: `pipeline(discovery.failures, fix, verify)`,
+   loop-until-dry. The author fixes the *policy*; the runtime fixes the *size*.
+2. **Repair as code.** `if (!verify.ok) { fix; verify }` bounded by a counter.
+   Every fix → re-verify handoff observed in the goal-2 journal was this `if`.
+3. **Budget as data.** `budget.remaining()` scales loops; the ceiling is hard.
+
+Model-level re-planning exists only **at workflow boundaries**: "run several
+in sequence — read each result before deciding the next phase"; the hybrid
+"scout inline first … then call Workflow"; and edit-and-resume ("the longest
+unchanged prefix of agent() calls returns cached results instantly; the first
+edited/new call and everything after it runs live"). Steering means stop, edit
+the program, resume — never a per-step decision.
+
+**Consequence for bullswarm.** Converge on *Direction A — a program, not a
+step list*: one planning turn produces the complete graph **plus** the
+adaptation policy, the runtime executes it to completion, and the planner is
+consulted again only at the boundary (complete, or next program). Do not build
+a continuous mid-flight steering loop (Direction B); Claude has none inside a
+workflow, and bullswarm already has `steer`, cancel and resume for the
+boundary-level levers. What the runtime still lacks to express a program is
+listed in §4.2 (0.12.0 scope).
+
 ## 2. What that looks like from the outside **[OBSERVED]**
 
 Filled from the experiment report as runs complete. Numbers here are copied
@@ -182,6 +229,8 @@ from `docs/experiments/2026-08-29-ultracode-vs-bullswarm.md`, never projected.
 | 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 |
 | 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 |
+| Repair loops | `while`/retry in code | Planner replanned after every failed verify | **Fixed in 0.12.0** — `verify.repair` policy runs fix → re-verify inside the executor |
 | Budget | Hard ceiling | Advisory targets (user decision) | Intentional difference |
 | Observability | Progress tree, narrator, `/workflows` | `watch` heartbeat (semantic quiet + agent-output quiet since 0.10.9), `tui`, events | Comparable |
 | Isolation | `isolation: 'worktree'` per agent | Shared `addDir`; planner-declared file ownership | Candidate |
@@ -212,6 +261,69 @@ from `docs/experiments/2026-08-29-ultracode-vs-bullswarm.md`, never projected.
    validation (so the 0.10.9 corrective turn fixes it) instead of failing a
    dispatch after a planning round trip.
 
+### 4.2 Adopted in 0.12.0 — a *program* expressible in one decision
+
+The user's framing for this release: position the orchestrator as the
+**compiler** of the goal into a workflow program; the program drives every
+phase and turn; the model is consulted again only at a boundary that needs
+judgement — the same division of labour Claude Code uses between the script
+author and the `Workflow` runtime.
+
+1. **Data-driven fan-out in proposals** — shipped. A proposed `fanout` takes
+   `itemsFrom: "outputs.<actionId>.outFile"` (producer may be co-proposed; it
+   becomes an implicit `dependsOn`). The runtime resolves the list when the
+   producer finishes. This is Claude's `pipeline(discovery.failures, …)`: the
+   planner no longer spends a turn waiting to see how many items there are.
+2. **Structured worker output** — shipped in its cheap form. Discovery workers
+   are told to end with a JSON array; `parseJsonArray` prefers the trailing
+   array; the content gate accepts a bare JSON array/object as substance; and
+   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).
+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.
+4. **Boundary-only consultation** — the loop is now: decision 1 = the program;
+   the ready-set executor runs it to completion (fan-outs resolve, repairs run);
+   decision 2 = `complete` or the next program. The planner prompt says so
+   explicitly (`plannerConsultedOnlyAtProgramBoundary`), and the goal
+   orchestrator prompt is reframed as "compile the goal into a complete
+   workflow program".
+5. **Scout, then compile** — shipped. Claude's author reads the repo inline
+   for ~4 min before writing the script; bullswarm's orchestrator was compiling
+   blind (goal text + cwd, forbidden to run commands, and the planner context
+   exposed no worker output text at all — only `ok`/`why`/`outFile`). `workflow
+   goal` now runs a read-only `scout` action first, and every output in the
+   planner context carries an `outputExcerpt`, so the first program is written
+   against a real survey and boundary decisions read what workers reported.
+6. Two bugs found on the way that had silently blocked this shape in ≤ 0.11.1:
+   fan-out outputs recorded the success *count* in `ok`, so nothing could ever
+   depend on a fan-out (the ready-set test is `ok === true`); and the content
+   gate rejected a worker whose whole answer was a JSON array as an
+   "announcement without substance".
+
+7. Two robustness gaps the 0.11.1 comparison run itself exposed, fixed
+   before 0.12.0 shipped: (a) a planner-authored verify prompt that quoted a
+   JSDoc type literally — `{{maxLength?: number}}` — was parsed as a template
+   ref and killed the action at render time with zero attempts, forcing an
+   extra planner turn to re-issue it. Only a known root plus dotted
+   identifiers is a ref now; other double-brace text is prompt content.
+   (Claude never has this class of bug: prompts are JS strings, the runtime
+   does no substitution.) (b) The new scout is a failable step ahead of the
+   planner; it is non-fatal by construction (`onError: continue`), the planner
+   sees `outputs.scout.ok=false` with the reason, and a run where only the
+   scout succeeded is `blocked`, never "delivered".
+
+**Honest limitation.** `itemsFrom` removes the planner *turn*, not the stage
+*barrier*: a verify depending on a data-driven fan-out waits for all items,
+whereas Claude's `pipeline()` overlaps verify-B with fix-C for discovered items
+too. Per-item overlap on unknown items would need a fan-out whose
+`stepTemplate` is itself a chain — not in 0.12.0. For known items the planner
+proposes N fix + N verify inline and the ready-set scheduler already overlaps
+them.
+
 ## 5. Not adopted (yet), and why
 
 - **Schema-enforced worker output.** bullswarm's content verification and the

package/docs/experiments/2026-08-29-ultracode-vs-bullswarm.md

@@ -221,15 +221,116 @@ session #1; goal submitted 17:24:4x Z. Observed driving sequence:
   bullswarm 0.10.9 now has for planner decisions, except here the correction is
   an inline retry inside one turn rather than a fresh planning process.
 
-(execution numbers pending)
+Execution numbers (from the workflow journal `wf_b235c760…/journal.jsonl` and
+the session transcript; read-only, no interference):
 
-### bullswarm 0.11.0 code (`node bin/bullswarm.js` from the repo checkout)
+| Measure | Value |
+| --- | --- |
+| Goal submitted → session idle | 17:24:46 → 18:22:45 Z = **58 min 0 s** |
+| Inline scouting + advisor before the Workflow call | 4 min (17:24:46 → 17:28:42) |
+| Workflow call rejected (parse error) → corrected resend | 94 s (17:28:42 → 17:30:16) |
+| Workflow execution | 17:30:16 → 18:19:07 = **48 min 51 s**, 24 agents, 0 errors |
+| Agents by stage | 6 probe, 6 author, 9 adversarial verify, 3 fix (slugify ×2, intervals ×1) |
+| Max concurrent agents / mean parallelism | **6** (= the six items; cap was 8) / 3.1 |
+| Orchestrator (session) model turns during execution | **0** — the session sat in "Waiting for 1 dynamic workflow to finish" |
+| Session tool calls overall | 16 Bash, 2 Workflow, 1 ToolSearch, 0 Agent |
+| Post-workflow inline verification | 18:19:15 → 18:22:44 (3.5 min): own `npm test`, comment-stripped code identity diff, executing every `@example`, link check, advisor |
+| Session output tokens (orchestrator only) | 91 k; workers 534 k output, 52.9 M cache-read |
+
+How the program actually ran (agent start → end):
 
-(pending)
+```text
+probe     ×6  17:30:16 → 17:34:36 … 17:36:53   all six in flight at once
+author    ×6  17:34:36 → 17:41:20 … 17:46:59   each starts the second ITS probe ends (pipeline, no barrier)
+verify    ×6  17:41:20 → 17:45:48 … 17:52:08   each starts the second ITS author ends
+fix       slugify 17:46:45→17:55:10 · intervals 17:48:41→17:53:06 · slugify 18:01:34→18:11:52
+re-verify intervals 17:53:07→17:58:36 · slugify 17:55:10→18:01:34 · slugify 18:11:52→18:19:07
+```
 
-### bullswarm 0.10.9 (installed binary), if time allows
+Four of the six modules were completely done by 17:49; the remaining 30 min of
+wall time was one module's (slugify) two-round fix loop, pre-authored in the
+script as `while (!verdict.ok && rounds < N)`. No planner turn was spent on
+"how many items", "did the verify pass", or "repair or not" — all three were
+data-driven inside the program. This is the concrete shape 0.12.0 reproduces
+(`itemsFrom`, `repair`).
 
-(pending)
+Correctness audit of `g2-claude` (mine, read-only): `npm test` 168/168 (52 → 116
+new); every existing `tests/<module>.test.js` SHA unchanged; every `src/*.js`
+byte-identical to the base after stripping comment/blank lines (JSDoc only);
+6 edge test files (16–24 tests each), 6 docs pages + `docs/README.md` index,
+`@example` on every export. No deliverable missing.
+
+### bullswarm 0.11.1 (installed binary) — same goal, `g2-bs-v2`
+
+Launched 18:23:39 Z via `run-bs-g2-v2.sh` (`--concurrency 8 --max-agents 40
+--max-expansion-rounds 8`, orchestrator `claude-code`, single pool, Fable
+excluded). Started only after the Claude session went idle so the two never
+competed for the machine.
+
+Run `wf-mtda5qq5-c6166f`, isolated `BULLSWARM_HOME`, single pool
+`claude-code` / `claude-opus-5`, `--concurrency 8 --max-agents 40
+--max-expansion-rounds 8 --foreground`, launched 18:23:42 Z on a pristine copy
+of the fixture. Observed read-only from `state.json` / `events.jsonl`.
+
+**Timeline**
+
+| When (Z) | What happened |
+| --- | --- |
+| 18:23:42 → 18:27:55 | Planner turn 1 (253 s). ONE decision carrying the whole graph: **14 actions** — `module-{csv,duration,intervals,lru,semver,slugify}` (run, no deps), `verify-<module>` ×6 (each depending only on its own module), `docs-index` (depends on all six modules), `verify-suite` (depends on `docs-index` + all six verifies, `review: outputs.docs-index.outFile`). |
+| 18:27:55 | All six module writers start together — **6 concurrent workers** (cap 8, six items). |
+| 18:33:17 → 18:36:39 | Writers finish one by one; each `verify-<module>` starts the moment its own writer finishes (ready-set scheduler); `docs-index` starts at 18:36:40 when the last writer lands. |
+| 18:35:26 | **`verify-slugify` dies with zero attempts**: `template ref "{{maxLength?: number}}" unresolved at render time`. The planner had quoted a JSDoc record type literally in the prompt; the renderer treated the double braces as a template ref. `verify-suite` is then blocked by a failed dependency. |
+| 18:41 → 18:46:01 | Planner turn 2 (~5 min). It diagnosed the render-time death correctly ("two consecutive opening curly braces … treated as an unresolved reference") and proposed **7 actions**: `slugify-recheck` + `verify-slugify-2`, `polish-semver` + `verify-semver-2`, `polish-lru` + `verify-lru-2`, `final-suite`. The two `polish-*` actions react to *non-blocking* nits reported by verifiers that had **passed** (`verify-semver` and `verify-lru` were `ok:true`). |
+| 18:46:01 → 19:03:06 | Remediation round runs (3 fixes → 3 re-verifies → `final-suite`), max 3 concurrent. |
+| 19:03:06 → 19:04:56 | Planner turn 3 (110 s): `complete`, verified, no concerns. |
+
+What this run settles, before the numbers: 0.11.x's planning doctrine already
+produces the Claude shape — one decision = the whole graph, six writers in
+parallel, per-item verify overlapping other items' writes, a final
+whole-suite verify at the end. The remaining differences are (a) a runtime
+robustness bug (literal braces), (b) repair happening as a *planner turn*
+rather than inside the program, (c) the planner treating informational
+concerns as work, and (d) no scout before the first program (the planner
+compiled from the goal text alone — correctly here, because the goal names the
+six modules).
+
+**Numbers** (from `state.json`/`events.jsonl` via `metrics-bullswarm.mjs`; audit
+via `audit-fixture.sh`, read-only, after the run ended)
+
+| Measure | bullswarm 0.11.1 | Claude Code #2 (for reference) |
+| --- | --- | --- |
+| Goal submitted → terminal | 18:23:42 → 19:04:56 Z = **41 min 14 s** (2 474 s) | 58 min 0 s (48 min 51 s of it inside `Workflow`) |
+| Planner / orchestrator time | **667 s = 27 % of wall**, 3 turns (253 s, 304 s, 110 s) | 4 min scouting + 94 s script fix before execution; **0 turns during** the 48 min 51 s execution |
+| Agents dispatched | **22** (19 workers + 3 planner) | 24 workers (6 probe, 6 author, 9 verify, 3 fix) |
+| Max concurrent / mean parallelism | **6** / 2.74 | 6 / 3.1 |
+| Actions per decision | 14, 7, 0 | one script (24 agents) |
+| Actions that died without running | 2 (`verify-slugify` render-time template ref; `verify-suite` blocked by it) | 0 |
+| Remediation rounds | 1 (as a planner turn) | fix loops inside the script (3 fix agents) |
+| Outcome | `completed`, verified, no concerns | done, self-verified inline |
+| Tests after | **130/130** (52 existing + 78 new: 15/14/12/11/13/13 per module) | 168/168 (52 + 116 new: 24/18/19/21/… per module) |
+| Existing `tests/*.test.js` | byte-identical to base (all 7) | byte-identical (all 7) |
+| `src/` changes | comment-only in all 6 modules (0 non-comment line diffs) | comment-only in all 7 files |
+| Deliverables | 6 edge suites, 6 docs pages, `docs/README.md` index (6 links) — all present | same set, all present |
+| Tokens | 148 k *estimated* (utf8 bytes/4 — provider gave no usage; not comparable) | orchestrator 91 k output; workers 534 k output, 52.9 M cache-read (real usage) |
+
+Two things worth noting beyond the table. (1) The run *modified the fixture
+to route around the tool's bug*: the planner's remediation rewrote
+`src/slugify.js`'s JSDoc from `@param {{maxLength?: number}} [options]` to the
+dotted `@param {number} [options.maxLength=0]` form so that no later verify
+would trip on the double braces. Comment-only, goal-compliant, but a
+runtime defect leaked into the deliverable. Root cause is two-fold and both
+are fixed in 0.12.0: the renderer treated any `{{…}}` as a ref, and `verify`
+template-rendered the *review artifact* (a worker's report, arbitrary text)
+together with its instructions. (2) The remediation round spent two of its
+three fixes on "non-blocking" nits from verifiers that had returned
+`ok:true`; 0.12.0's doctrine tells the planner those are informational.
+
+### bullswarm 0.12.0 (installed binary) — same goal, fresh copy `g2-bs-v3`
+
+(pending — after the 0.12.0 release)
+
+The originally planned 0.10.9 goal-2 run was dropped at the user's request
+(2026-08-29): the installed latest is the only baseline that matters.
 
 ## Behaviour differences observed
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bullswarm",
-  "version": "0.11.1",
+  "version": "0.12.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

@@ -340,6 +340,29 @@ per-item fix→verify chains plus one whole-system verify — because each plann
 turn is a full orchestrator round trip. See
 `docs/claude-dynamic-workflow-mechanics.md` for the model this follows.
 
+Since 0.12.0 a decision is meant to be a whole *program*: the runtime executes
+it to the end and consults the planner again only at the program boundary
+(every action finished, or the graph blocked). Two planner-level features make
+that expressible without extra turns:
+
+- `fanout.itemsFrom: "outputs.<actionId>.outFile"` — fan out over the JSON
+  array an earlier (or co-proposed) action ends its output with. The producer
+  becomes an implicit dependency and the list is resolved at execution time. A
+  producer that answered in prose gets one bounded read-only extraction action
+  (`<fanoutId>-items`, `source: "runtime-extraction"`) before the fan-out fails
+  truthfully.
+- `verify.repair: { prompt, maxRounds }` — when the verifier returns
+  `ok:false`, the executor runs `<verifyId>-repair-<n>` (`source:
+  "repair-policy"`) with the verifier's concerns verbatim and re-runs the same
+  verify, up to `maxRounds` (1–3), without a planner turn.
+
+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
+directly. The planner context carries `outputs.<id>.outputExcerpt` (what each
+finished action reported), and `workflow goal` runs a read-only `scout` action
+first (`--no-scout` to skip) so the first program is compiled from a real
+survey of the repository rather than from the goal text alone.
+
 Allowed planner decisions are `proceed`, `complete`, `needs_more_work`,
 `retry`, `escalate`, `wait_for_approval`, and `stop`. Expansion decisions must
 contain bounded actions; malformed or over-budget output executes nothing.

package/src/help.js

@@ -585,7 +585,8 @@ const workflowGoalText = rich({
     { flag: '--max-agents <n>', desc: 'planning target for total dispatched agents (soft, not a hard stop)', default: '30 (max 500)' },
     { flag: '--max-expansion-rounds <n>', desc: 'planning target for planner replanning rounds', default: '8 (max 50)' },
     { flag: '--max-actions <n>', desc: 'planning target for total dispatched actions', default: '40 (max 1000)' },
-    { flag: '--max-items-per-expansion <n>', desc: 'cap on fanout items added per planner round', default: '8 (max 100)' },
+    { flag: '--max-items-per-expansion <n>', desc: 'cap on fanout items per planner round, inline or resolved from itemsFrom at execution time', default: '24 (max 100)' },
+    { flag: '--no-scout', desc: 'skip the read-only scout action that surveys the repository (tree, manifest, test status, units of work) before the orchestrator compiles its first program', default: 'scout runs first' },
     { flag: '--max-workflow-seconds <n>', desc: 'planning target for total wall-clock seconds', default: '3600 (max 86400)' },
     { flag: '--concurrency <n>', desc: 'max parallel dispatches; dependency-ready actions from one decision run concurrently up to this cap', default: '8 (max 16)' },
     { flag: '--retry-attempts <0..3>', desc: 'same-pool retries per failed action', default: '1' },

package/src/lib/verify.js

@@ -120,6 +120,28 @@ function hasVerifyJson(text) {
   }
 }
 
+/**
+ * A structured answer: the output is, or ends with, a JSON array (a discovery
+ * step's item list, possibly empty) or is a single JSON object. Such output is
+ * substance by construction; the prose heuristics must not reject it as an
+ * announcement.
+ */
+export function hasStructuredAnswer(text) {
+  const trimmed = text.trim();
+  if (trimmed.startsWith('{') && trimmed.endsWith('}')) {
+    try { return typeof JSON.parse(trimmed) === 'object'; } catch { /* not a single object */ }
+  }
+  const end = trimmed.lastIndexOf(']');
+  if (end === -1 || trimmed.slice(end + 1).trim().length > 0) return false;
+  for (let start = trimmed.lastIndexOf('[', end); start !== -1; start = trimmed.lastIndexOf('[', start - 1)) {
+    try {
+      if (Array.isArray(JSON.parse(trimmed.slice(start, end + 1)))) return true;
+    } catch { /* keep widening */ }
+    if (start === 0) break;
+  }
+  return false;
+}
+
 /**
  * Judge delegate output content.
  * @param {string} text   full delegate output
@@ -134,7 +156,7 @@ export function judgeContent(text, { exitCode, expectWork = true, acceptVerifyJs
   if (scanForFailure(text)) {
     return { verdict: 'fail', why: 'failure pattern at output head' };
   }
-  if (expectWork && !looksLikeWork(text) && !(acceptVerifyJson && hasVerifyJson(text))) {
+  if (expectWork && !looksLikeWork(text) && !(acceptVerifyJson && hasVerifyJson(text)) && !hasStructuredAnswer(text)) {
     return { verdict: 'intent_only', why: 'announcement without substance' };
   }
   return { verdict: 'pass', why: 'content passed all gates' };

package/src/workflow/cli.js

@@ -372,6 +372,7 @@ async function wfGoal(opts) {
         cwd: opts.cwd ?? process.cwd(),
         orchestrator,
         settings: goalSettings(opts),
+        scout: !opts.noScout,
         worktreeIsolation: loadState(BULLSWARM_DIR()).config?.worktreeIsolation ?? 'agent-decides',
       });
     } catch (err) {
@@ -622,6 +623,7 @@ function parseFlags(argv) {
     const a = argv[i];
     if (a === '--json') out.json = true;
     else if (a === '--quiet') out.quiet = true;
+    else if (a === '--no-scout') out.noScout = true;
     else if (a === '--resume') out.resume = argv[++i];
     else if (a === '--after') out.after = argv[++i];
     else if (a === '--input') {

package/src/workflow/dashboard.js

@@ -2,6 +2,7 @@
 // It deliberately uses only ANSI sequences and Node's standard streams.
 
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { fanoutSucceededCount } from './runner.js';
 import { join } from 'node:path';
 import { listRuns, resolveRunId } from './short-id.js';
 import { appendEvent, readEvents } from './events.js';
@@ -64,7 +65,7 @@ export function dashboardRows(bullswarmDir) {
       const state = r.state ?? {};
       const steps = state.steps ?? [];
       const fanout = Object.values(state.outputs ?? {}).filter((v) => v?.items).reduce((acc, v) => ({
-        total: acc.total + (v.total ?? 0), ok: acc.ok + (v.ok ?? 0), failed: acc.failed + (v.failed ?? 0),
+        total: acc.total + (v.total ?? 0), ok: acc.ok + fanoutSucceededCount(v), failed: acc.failed + (v.failed ?? 0),
       }), { total: 0, ok: 0, failed: 0 });
       return {
         ...r,

package/src/workflow/decision.js

@@ -38,6 +38,14 @@ export function parseDecisionText(text) {
 // dispatch: instructions move to prompt, and a single-dependency verify reviews
 // its dependency's artifact.
 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 REPAIR_MAX_ROUNDS = 3;
+
+export function looksLikeItemsFromPath(value) {
+  return typeof value === 'string' && ITEMS_FROM_RE.test(value.trim());
+}
 
 export function looksLikeReviewPath(value) {
   return typeof value === 'string' && REVIEW_PATH_RE.test(value.trim());
@@ -48,6 +56,17 @@ export function normalizeDecisionProposal(proposal) {
   return {
     ...proposal,
     actions: proposal.actions.map((action) => {
+      if (action?.type === 'fanout' && !Array.isArray(action.items) && looksLikeItemsFromPath(action.itemsFrom)) {
+        // A fanout fed by an artifact implicitly depends on the producer.
+        const itemsFrom = action.itemsFrom.trim();
+        const producer = ITEMS_FROM_RE.exec(itemsFrom)[1];
+        const dependsOn = Array.isArray(action.dependsOn) ? action.dependsOn : [];
+        return {
+          ...action,
+          itemsFrom,
+          ...(dependsOn.includes(producer) || producer === action.id ? {} : { dependsOn: [...dependsOn, producer] }),
+        };
+      }
       if (action?.type !== 'verify') return action;
       const singleDependency = Array.isArray(action.dependsOn) && action.dependsOn.length === 1
         ? action.dependsOn[0] : null;
@@ -137,8 +156,23 @@ export function validateDecisionProposal(proposal, {
       issues.push(`${at} needs a prompt`);
     }
     if (action.type === 'fanout') {
-      if (!Array.isArray(action.items)) issues.push(`${at}.items must be an inline array`);
-      else proposedItems += action.items.length;
+      const hasItems = Array.isArray(action.items);
+      const hasItemsFrom = action.itemsFrom != null;
+      if (!hasItems && !hasItemsFrom) {
+        issues.push(`${at}.items must be an inline array, or ${at}.itemsFrom must be "outputs.<actionId>.outFile" naming the action whose output ends with the JSON array of items`);
+      } else if (hasItems) {
+        proposedItems += action.items.length;
+        if (hasItemsFrom) issues.push(`${at} must use either items or itemsFrom, not both`);
+      }
+      if (hasItemsFrom && !hasItems) {
+        if (!looksLikeItemsFromPath(action.itemsFrom)) {
+          issues.push(`${at}.itemsFrom must be a dotted artifact path like "outputs.<actionId>.outFile" (the action whose output ends with a JSON array), not inline items, instructions, or a filesystem path`);
+        } else {
+          const producer = ITEMS_FROM_RE.exec(action.itemsFrom.trim())[1];
+          if (producer === action.id) issues.push(`${at}.itemsFrom cannot reference the fanout itself`);
+          else if (!known.has(producer) && !proposedIds.has(producer)) issues.push(`${at}.itemsFrom references unknown action "${producer}"`);
+        }
+      }
       if (!action.stepTemplate || typeof action.stepTemplate !== 'object') issues.push(`${at}.stepTemplate is required`);
       for (const runtimeOwned of ['pool', 'addDir', 'taskFile']) {
         if (action.stepTemplate?.[runtimeOwned] != null) {
@@ -146,6 +180,28 @@ export function validateDecisionProposal(proposal, {
         }
       }
     }
+    if (action.repair != null && action.type !== 'verify') {
+      issues.push(`${at}.repair is only valid on verify actions`);
+    }
+    if (action.type === 'verify' && action.repair != null) {
+      const repair = action.repair;
+      if (!repair || typeof repair !== 'object' || Array.isArray(repair)) {
+        issues.push(`${at}.repair must be an object like {"prompt":"<how to fix what the verifier rejects>","maxRounds":1}`);
+      } else {
+        if (typeof repair.prompt !== 'string' || !repair.prompt.trim()) {
+          issues.push(`${at}.repair.prompt must be a non-empty string telling a worker how to fix what the verifier rejected`);
+        }
+        if (repair.maxRounds != null && !(Number.isInteger(repair.maxRounds) && repair.maxRounds >= 1 && repair.maxRounds <= REPAIR_MAX_ROUNDS)) {
+          issues.push(`${at}.repair.maxRounds must be an integer from 1 to ${REPAIR_MAX_ROUNDS}`);
+        }
+        if (repair.effort != null && !['high', 'medium', 'low'].includes(repair.effort)) {
+          issues.push(`${at}.repair.effort must be high|medium|low`);
+        }
+        for (const runtimeOwned of ['pool', 'addDir', 'taskFile']) {
+          if (repair[runtimeOwned] != null) issues.push(`${at}.repair.${runtimeOwned} is runtime-owned and cannot be proposed by a planner`);
+        }
+      }
+    }
     if (action.type === 'verify') {
       if (typeof action.review !== 'string') {
         issues.push(`${at}.review is required: a verify with one dependsOn reviews that artifact automatically; with several, set review to "outputs.<actionId>.outFile" and put reviewer instructions in prompt`);

package/src/workflow/goal.js

@@ -9,17 +9,18 @@ const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
 
 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.',
   '',
   '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 dependency graph of bounded run, fanout, and verify actions 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.',
+  '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 independent 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 when every item needs the identical prompt.',
-  '   A verify action with exactly one dependency automatically reviews that dependency artifact; you do not need to supply a review path.',
+  '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.',
   '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.',
@@ -33,6 +34,28 @@ export const AUTONOMOUS_ORCHESTRATOR_PROMPT = [
   '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.',
 ].join('\n');
 
+// Read-only survey that runs before the orchestrator's first decision, so the
+// program it compiles names real files, modules, and commands instead of
+// guessing — the equivalent of the inline scouting a Claude Code session does
+// before authoring a Workflow script.
+export function scoutPrompt(goal, cwd) {
+  return [
+    'You are the read-only SCOUT for an autonomous workflow. Another agent will turn the goal below into a program of parallel worker actions using ONLY your report, so be concrete and complete.',
+    `Working directory (absolute): ${cwd}`,
+    `Goal: ${goal}`,
+    '',
+    'Survey what the goal touches. Do NOT modify, create, or delete any file; do not install dependencies; do not commit.',
+    'Report under exactly these headings, at most ~80 lines total:',
+    'TREE: the directory tree to depth 3 (skip node_modules, .git, build output), one entry per line.',
+    'MANIFEST: package/build manifest facts that matter (name, language/runtime, test command, lint/format command, module system).',
+    'TEST STATUS: run the test command once and report the exact pass/fail counts and any failing test names.',
+    'UNITS OF WORK: one bullet per independent item the goal implies (module, file, finding, page). For each: the exact files it owns, the exact focused command that proves it is done, and anything already present.',
+    'SHARED FILES: files that more than one unit would touch (indexes, barrels, README tables, config) and therefore must be edited by one action after the others.',
+    'RISKS: anything that constrains the plan (files that must not change, flaky tests, missing tools, ambiguous requirements).',
+    'Finally, END your output with a JSON array of the unit-of-work names in UNITS OF WORK, e.g. ["csv","duration"]. Nothing after the array.',
+  ].join('\n');
+}
+
 function positiveInt(value, fallback, { min = 1, max = Number.MAX_SAFE_INTEGER } = {}) {
   if (value == null) return fallback;
   const parsed = Number(value);
@@ -48,6 +71,7 @@ export function buildGoalWorkflow({
   orchestrator = null,
   name = null,
   settings = {},
+  scout = true,
   worktreeIsolation = 'agent-decides',
 } = {}) {
   if (typeof goal !== 'string' || !goal.trim()) {
@@ -64,7 +88,7 @@ export function buildGoalWorkflow({
   const maxAgents = positiveInt(settings.maxAgents, 30, { max: 500 });
   const maxExpansionRounds = positiveInt(settings.maxExpansionRounds, 8, { max: 50 });
   const maxActions = positiveInt(settings.maxActions, 40, { max: 1000 });
-  const maxItemsPerExpansion = positiveInt(settings.maxItemsPerExpansion, 8, { max: 100 });
+  const maxItemsPerExpansion = positiveInt(settings.maxItemsPerExpansion, 24, { max: 100 });
   const maxWorkflowSeconds = positiveInt(settings.maxWorkflowSeconds, 3600, { max: 86_400 });
   const concurrency = positiveInt(settings.concurrency, 8, { max: 16 });
   const retryAttempts = positiveInt(settings.retryAttempts, 1, { min: 0, max: 3 });
@@ -112,7 +136,13 @@ export function buildGoalWorkflow({
     },
     phases: [{
       name: 'autonomous-delivery',
-      steps: [{
+      steps: [...(scout === true ? [{
+        id: 'scout',
+        type: 'run',
+        lane: 'analyze',
+        addDir: targetDir,
+        prompt: scoutPrompt(goal.trim(), targetDir),
+      }] : []), {
         id: 'orchestrator',
         type: 'decide',
         ...(orchestrator ? { pool: orchestrator } : {}),

package/src/workflow/runner.js

@@ -11,8 +11,10 @@ import { randomBytes } from 'node:crypto';
 import { validateWorkflow } from './validate.js';
 import { WorkflowRuntime } from './runtime.js';
 import { generateShortId, listRuns } from './short-id.js';
+import { extractItems } from './template.js';
 import {
   validateDecisionProposal, normalizeDecisionProposal, DecisionValidationError,
+  ITEMS_FROM_RE,
 } from './decision.js';
 
 export function loadWorkflow(pathOrName, searchDirs) {
@@ -459,6 +461,10 @@ export async function runWorkflow(opts) {
   }
 }
 
+function isScoutAction(action) {
+  return action?.id === 'scout' && action?.parentId == null && action?.kind === 'run';
+}
+
 function actionOutputOk(action, outputs) {
   return Object.hasOwn(outputs ?? {}, action.id)
     ? outputs[action.id]?.ok === true
@@ -503,8 +509,11 @@ function responseExcerpt(text, limit = 1200) {
 function terminalPlannerOutcome(state, gate, reason) {
   const dynamicActions = (state.actionLedger ?? []).filter((action) => action.parentId === gate.id);
   const observedActions = (state.actionLedger ?? []).filter((action) => action.kind !== 'decide');
+  // A read-only scout (goal survey) is evidence for the planner, never a
+  // delivery: a run where only the scout succeeded is blocked, not delivered.
   const usefulWorkers = observedActions.filter((action) =>
-    action.kind !== 'verify' && action.status === 'succeeded' && actionOutputOk(action, state.outputs));
+    action.kind !== 'verify' && !isScoutAction(action)
+    && action.status === 'succeeded' && actionOutputOk(action, state.outputs));
   const latestWorker = usefulWorkers.at(-1) ?? null;
   const concerns = completionEvidenceGaps(
     dynamicActions,
@@ -551,6 +560,163 @@ async function runDecisionLoop({ runtime, gate, phase, state, retryAttempts }) {
   // dependencies finish, not when the whole wave finishes. Real concurrency is
   // capped by the runtime's global dispatch limiter (settings.concurrency), so
   // this mirrors a pipeline: item B's verify overlaps item C's fix.
+  const latestDecisionSequence = () => state.decisions?.at?.(-1)?.sequence ?? null;
+  const runProgramAction = async (definition, source) => {
+    state.plan.actions.push({
+      id: definition.id,
+      kind: definition.type,
+      phase: executionPhase(definition),
+      dependsOn: definition.dependsOn ?? [],
+      source,
+      decisionSequence: latestDecisionSequence(),
+      definition,
+    });
+    state.currentStep = { id: definition.id, type: definition.type, phase: executionPhase(definition) };
+    runtime.persist();
+    let result;
+    try {
+      result = await runtime.runStep(
+        { ...definition, parentId: gate.id, _dynamic: true },
+        { phase: executionPhase(definition), retryAttempts },
+      );
+    } catch (err) {
+      result = { ok: false, why: err.message };
+      state.outputs[definition.id] = result;
+      runtime.setActionStatus(definition, { phase: executionPhase(definition) }, 'failed_terminal', {
+        finishedAt: new Date().toISOString(), why: err.message,
+      });
+      runtime.emit('action.failed', { actionId: definition.id, status: 'failed_terminal', why: err.message });
+    }
+    state.steps.push({
+      phase: executionPhase(definition), stepId: definition.id, type: definition.type,
+      ok: result.ok, why: result.why ?? null, dynamic: true, source,
+    });
+    runtime.persist();
+    return result;
+  };
+
+  // Resolve a proposed fanout's items from the producer artifact named by
+  // itemsFrom. If the producer did not end with a parseable JSON array, run
+  // ONE bounded, read-only extraction action over its output before giving up;
+  // never re-run the producer (it may have mutated files).
+  const resolveProposedItems = async (action) => {
+    const itemsFrom = action.itemsFrom.trim();
+    const producerId = ITEMS_FROM_RE.exec(itemsFrom)?.[1] ?? null;
+    const limit = Number(settings.maxItemsPerExpansion ?? 50) || 50;
+    const attempt = (path) => {
+      try { return { ok: true, items: extractItems(state, path) }; } catch (err) { return { ok: false, why: err.message }; }
+    };
+    const finish = (outcome) => {
+      if (outcome.items.length > limit) {
+        return { ok: false, why: `fanout "${action.id}" resolved ${outcome.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: outcome.items.length });
+      return outcome;
+    };
+    let resolved = attempt(itemsFrom);
+    if (!resolved.ok) {
+      const producer = producerId ? state.outputs[producerId] : null;
+      let sourceText = typeof producer?.outputText === 'string' ? producer.outputText : '';
+      try {
+        if (producer?.outFile && existsSync(producer.outFile)) sourceText = readFileSync(producer.outFile, 'utf8');
+      } catch { /* fall back to the recorded excerpt */ }
+      const excerpt = sourceText.length > 20_000 ? `${sourceText.slice(0, 20_000)}\n[truncated]` : sourceText;
+      const extractionId = `${action.id}-items`;
+      if (state.outputs[extractionId]?.ok === true) {
+        // Resume: the extraction already ran durably; reuse its artifact.
+        resolved = attempt(`outputs.${extractionId}.outFile`);
+        if (resolved.ok) return finish(resolved);
+      }
+      runtime.emit('action.items_extraction_requested', {
+        actionId: action.id, producerId, extractionActionId: extractionId, why: resolved.why,
+      });
+      const extraction = {
+        id: extractionId,
+        type: 'run',
+        phase: action.phase,
+        ...(action.lane != null ? { lane: action.lane } : {}),
+        ...(action.addDir != null ? { addDir: action.addDir } : {}),
+        ...(action.timeoutSec != null ? { timeoutSec: action.timeoutSec } : {}),
+        dependsOn: producerId ? [producerId] : [],
+        prompt: [
+          `A previous step ("${producerId ?? itemsFrom}") was supposed to end its output with a JSON array of items, but no JSON array could be parsed (${resolved.why}).`,
+          'Below is that step\'s complete output. Extract the list of items it describes and RETURN ONLY a JSON array: no prose, no markdown fences, nothing before "[" or after "]".',
+          'Each element must be a short string or a small flat object, exactly as the text describes it. If the text describes no list at all, return [].',
+          'Do not run commands and do not modify any file; this is a read-only extraction.',
+          '',
+          '---- BEGIN STEP OUTPUT ----',
+          excerpt,
+          '---- END STEP OUTPUT ----',
+        ].join('\n'),
+      };
+      const extracted = await runProgramAction(extraction, 'runtime-extraction');
+      if (!extracted.ok) {
+        return { ok: false, why: `fanout "${action.id}" items could not be resolved from ${itemsFrom} (${resolved.why}); extraction action "${extractionId}" failed: ${extracted.why}` };
+      }
+      resolved = attempt(`outputs.${extractionId}.outFile`);
+      if (!resolved.ok) {
+        return { ok: false, why: `fanout "${action.id}" items could not be resolved from ${itemsFrom}; extraction action "${extractionId}" returned no JSON array either (${resolved.why})` };
+      }
+      runtime.emit('action.items_extracted', { actionId: action.id, extractionActionId: extractionId, count: resolved.items.length });
+    }
+    return finish(resolved);
+  };
+
+  // Bounded repair loop for a verify that returned a real ok:false verdict:
+  // run a fix action carrying the verifier's concerns verbatim, then re-run the
+  // same verify. Dispatch or parse failures are not repairable and return as-is.
+  const repairAndReverify = async (action, firstResult) => {
+    const maxRounds = Math.min(3, Math.max(1, Number(action.repair.maxRounds) || 1));
+    // Rounds already spent (a resumed run re-verifies first) count against the bound.
+    const priorRounds = (state.plan?.actions ?? [])
+      .filter((entry) => entry.source === 'repair-policy' && entry.dependsOn?.[0] === action.id).length;
+    let result = firstResult;
+    for (let round = priorRounds + 1; round <= maxRounds && result.ok === false; round++) {
+      const verdict = state.outputs[action.id]?.verify;
+      if (!verdict || typeof verdict !== 'object') break;
+      const concerns = Array.isArray(verdict.concerns)
+        ? verdict.concerns.filter((entry) => typeof entry === 'string' && entry.trim()) : [];
+      const repairId = `${action.id}-repair-${round}`;
+      const repair = {
+        id: repairId,
+        type: 'run',
+        phase: action.phase,
+        ...(action.lane != null ? { lane: action.lane } : {}),
+        ...(action.addDir != null ? { addDir: action.addDir } : {}),
+        ...(action.timeoutSec != null ? { timeoutSec: action.timeoutSec } : {}),
+        ...(action.repair.effort != null ? { effort: action.repair.effort } : {}),
+        ...(action.requiresCapabilities != null ? { requiresCapabilities: action.requiresCapabilities } : {}),
+        dependsOn: [action.id],
+        prompt: [
+          action.repair.prompt.trim(),
+          '',
+          `An independent verifier ("${action.id}") rejected the previous result${
+            typeof verdict.summary === 'string' && verdict.summary.trim() ? `: ${verdict.summary.trim()}` : '.'}`,
+          ...(concerns.length ? ['Concerns to resolve (verbatim from the verifier):', ...concerns.map((entry) => `- ${entry}`)] : []),
+          '',
+          `Repair round ${round} of ${maxRounds}. Resolve every concern above, re-run the acceptance command yourself, and report exactly what changed with evidence.`,
+        ].join('\n'),
+      };
+      runtime.emit('action.repair_started', { verifyId: action.id, repairId, round, maxRounds, concerns });
+      const repaired = await runProgramAction(repair, 'repair-policy');
+      if (!repaired.ok) {
+        runtime.emit('action.repair_failed', { verifyId: action.id, repairId, round, why: repaired.why });
+        break;
+      }
+      runtime.emit('action.reverify_started', { verifyId: action.id, repairId, round });
+      state.currentStep = { id: action.id, type: action.type, phase: executionPhase(action) };
+      runtime.persist();
+      result = await runtime.runStep(
+        { ...action, parentId: gate.id, _dynamic: true },
+        { phase: executionPhase(action), retryAttempts },
+      );
+      runtime.emit(result.ok ? 'action.repaired' : 'action.reverify_rejected', {
+        verifyId: action.id, repairId, round, ok: result.ok, why: result.why ?? null,
+      });
+    }
+    return result;
+  };
+
   const executeActions = async (actions) => {
     const pending = new Map(actions.map((action) => [action.id, action]));
     const running = new Map();
@@ -561,16 +727,40 @@ async function runDecisionLoop({ runtime, gate, phase, state, retryAttempts }) {
       }
       let result;
       try {
-        state.currentStep = {
-          id: action.id,
-          type: action.type,
-          phase: executionPhase(action),
-        };
-        runtime.persist();
-        result = await runtime.runStep(
-          { ...action, parentId: gate.id, _dynamic: true },
-          { phase: executionPhase(action), retryAttempts },
-        );
+        let executable = action;
+        // Data-driven fan-out: the item list comes from an earlier action's
+        // artifact, resolved now that the producer has finished. No planner
+        // turn is needed to turn "discovered N things" into N workers.
+        if (action.type === 'fanout' && !Array.isArray(action.items) && typeof action.itemsFrom === 'string') {
+          const resolved = await resolveProposedItems(action);
+          if (!resolved.ok) {
+            result = { ok: false, why: resolved.why, itemsUnresolved: true };
+            state.outputs[action.id] = result;
+            runtime.setActionStatus(action, { phase: executionPhase(action) }, 'failed_terminal', {
+              finishedAt: new Date().toISOString(), why: resolved.why,
+            });
+            runtime.emit('action.failed', { actionId: action.id, status: 'failed_terminal', why: resolved.why });
+          } else {
+            executable = { ...action, items: resolved.items, itemsResolvedFrom: action.itemsFrom.trim() };
+          }
+        }
+        if (!result) {
+          state.currentStep = {
+            id: action.id,
+            type: action.type,
+            phase: executionPhase(action),
+          };
+          runtime.persist();
+          result = await runtime.runStep(
+            { ...executable, parentId: gate.id, _dynamic: true },
+            { phase: executionPhase(action), retryAttempts },
+          );
+          // Repair policy: a verify that carries `repair` fixes and re-checks
+          // inside the executor instead of returning to the planner.
+          if (action.type === 'verify' && result.ok === false && action.repair && typeof action.repair === 'object') {
+            result = await repairAndReverify(action, result);
+          }
+        }
       } catch (err) {
         // A post-artifact observer failure must not rewrite a durably
         // successful action as failed. Propagate it to the gate boundary;
@@ -852,6 +1042,13 @@ async function runDecisionLoop({ runtime, gate, phase, state, retryAttempts }) {
   }
 }
 
+/** Item success count of a fan-out output; tolerates pre-0.12 state where `ok` held the count. */
+export function fanoutSucceededCount(output) {
+  if (typeof output?.succeeded === 'number') return output.succeeded;
+  if (typeof output?.ok === 'number') return output.ok;
+  return output?.ok === true ? (output.total ?? 0) : 0;
+}
+
 export function buildReport(state, doc, runDir) {
   const stepResults = state.steps ?? [];
   const fanoutSteps = Object.entries(state.outputs ?? {}).filter(
@@ -860,7 +1057,7 @@ export function buildReport(state, doc, runDir) {
   let fanoutOk = 0;
   let fanoutFailed = 0;
   for (const [, v] of fanoutSteps) {
-    fanoutOk += v.ok ?? 0;
+    fanoutOk += fanoutSucceededCount(v);
     fanoutFailed += v.failed ?? 0;
   }
   const simpleOk = stepResults.filter((s) => s.ok).length;

package/src/workflow/runtime.js

@@ -40,6 +40,11 @@ import { resolveDispatchModel } from '../lib/strategy.js';
 // Persisting full transcripts bloat state.json on long workflows. The
 // full text is always on disk in the per-step outFile.
 export const OUTPUT_TEXT_CAP_BYTES = 64 * 1024;
+// Per-item excerpt kept in a fan-out's durable summary artifact.
+const FANOUT_ITEM_EXCERPT_BYTES = 6_000;
+// What the planner sees of each action's output (per output / all outputs).
+const PLANNER_EXCERPT_CHARS = 3_000;
+const PLANNER_EXCERPT_TOTAL_CHARS = 36_000;
 
 export function plannerBudgetContext(budget = {}) {
   const dispatchesUsedBeforePlanner = Number(budget.dispatchesUsed ?? 0);
@@ -846,22 +851,26 @@ export class WorkflowRuntime {
       '{"ok": <true|false>, "concerns": [<string>...], "summary": <string>}.',
       'No prose and no markdown fences. Set ok:true only when the requested checks actually pass.',
     ].join('\n');
-    const stepTemplate = {
+    // Only the reviewer INSTRUCTIONS are a template. The review target is a
+    // worker's artifact — arbitrary text that routinely contains code, JSDoc
+    // types and other double-brace sequences — and is appended verbatim,
+    // never rendered. (Observed 2026-08-28: a worker report quoting
+    // `{{maxLength?: number}}` killed its verify at render time.)
+    const rendered = renderDeep({
       lane: step.lane ?? 'analyze',
       addDir: step.addDir,
-      // A custom prompt changes the review instructions, never the review
-      // input. Always append the resolved artifact so the skeptic receives
-      // the thing it is meant to judge.
-      prompt: [
-        reviewInstructions,
-        '',
-        '---- BEGIN REVIEW TARGET ----',
-        reviewedText,
-        '---- END REVIEW TARGET ----',
-      ].join('\n'),
-    };
-    const rendered = renderDeep(stepTemplate, scope);
-    const taskText = rendered.prompt;
+      prompt: reviewInstructions,
+    }, scope);
+    // A custom prompt changes the review instructions, never the review
+    // input. Always append the resolved artifact so the skeptic receives
+    // the thing it is meant to judge.
+    const taskText = [
+      rendered.prompt,
+      '',
+      '---- BEGIN REVIEW TARGET ----',
+      reviewedText,
+      '---- END REVIEW TARGET ----',
+    ].join('\n');
     const targetDir = rendered.addDir ? String(rendered.addDir).replace(/^~/, process.env.HOME ?? '') : process.cwd();
 
     const stamp = `${step.id}-${Date.now().toString(36)}`;
@@ -933,14 +942,32 @@ export class WorkflowRuntime {
         decisionSequence: steering.decisionSequence,
       });
     }
-    const outputs = Object.fromEntries(Object.entries(this.state.outputs ?? {}).map(([id, output]) => [id, {
+    // 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.
+    let excerptBudget = PLANNER_EXCERPT_TOTAL_CHARS;
+    const excerptFor = (output) => {
+      const text = typeof output?.outputText === 'string' ? output.outputText.trim() : '';
+      if (!text) return { outputExcerpt: null };
+      if (excerptBudget <= 0) return { outputExcerpt: null, outputExcerptOmitted: true, outputChars: text.length };
+      const limit = Math.min(PLANNER_EXCERPT_CHARS, excerptBudget);
+      const excerpt = text.length > limit ? `${text.slice(0, limit)}\n…[${text.length - limit} more chars in outFile]` : text;
+      excerptBudget -= excerpt.length;
+      return { outputExcerpt: excerpt, outputChars: text.length };
+    };
+    const outputEntries = Object.entries(this.state.outputs ?? {});
+    const excerpts = new Map(outputEntries.slice().reverse().map(([id, output]) => [id, excerptFor(output)]));
+    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,
       total: output?.total,
+      succeeded: output?.succeeded,
       failed: output?.failed,
+      itemsFrom: output?.itemsFrom,
+      ...excerpts.get(id),
     }]));
     const actionForPlanner = (action) => ({
       id: action.id,
@@ -989,6 +1016,8 @@ export class WorkflowRuntime {
       executionConstraints: {
         concurrency: Number(this.state.settings?.concurrency ?? 1) || 1,
         readySiblingsRunConcurrently: true,
+        programFeatures: ['itemsFrom', 'repair'],
+        plannerConsultedOnlyAtProgramBoundary: true,
         actionTimeoutSec: Number(step.actionDefaults?.timeoutSec ?? step.timeoutSec) || null,
         actionTimeoutIsExplicitOptIn: step.actionDefaults?.timeoutSec != null || step.timeoutSec != null,
         retryAttempts: Number(this.state.settings?.retryAttempts ?? 0),
@@ -1038,27 +1067,37 @@ 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 — propose the whole graph, not one step:',
-      '- Each planning turn is a full round trip through a separate process (typically 1-2 minutes). Propose the COMPLETE dependency graph you can see now as one decision. A decision carrying a single action when several independent actions are already obvious wastes a round trip.',
-      '- Execution is a ready-set scheduler: every action whose dependsOn have all succeeded starts immediately and concurrently, up to executionConstraints.concurrency at once; a dependent action starts the moment its own dependencies finish, not when the whole round finishes. Independent actions therefore run in parallel automatically. Only add dependsOn where a real data or file-ordering dependency exists.',
-      '- Per-item chains: for N independent items (modules, files, findings), 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 the whole-system check.',
+      '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.',
+      '- 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"]}',
-      '  verify: {"id":"independent-check","type":"verify","phase":"verify","prompt":"Independently re-run the tests and report pass/fail with evidence.","dependsOn":["bounded-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.items MUST be an inline array and fanout.stepTemplate MUST be an object whose prompt uses {{item}}. verify.review MUST be a string. dependsOn is optional and may only name existing or newly proposed action IDs.',
+      '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 with inline items, or verify. The runtime validates every proposal and returns rejected proposals to you with the exact issues for a bounded correction turn.',
+      '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.',
@@ -1239,11 +1278,23 @@ export class WorkflowRuntime {
 
     const oks = results.filter((r) => r?.verdict?.ok === true).length;
     if (this.state.cancelRequested) failures += items.length - results.filter(Boolean).length;
+    // A fan-out is itself an artifact: write a durable summary of every item
+    // result so a verify (or a later fan-out) can depend on the fan-out
+    // directly via outputs.<fanoutId>.outFile, the same way it depends on a run.
+    const summary = this.writeFanoutSummary(step, items, results, oks);
+    // `ok` is a boolean like every other output (so dependents and the
+    // ready-set scheduler can test outputs.<id>.ok === true); the item count
+    // lives in `succeeded`.
     this.state.outputs[step.id] = {
       total: items.length,
-      ok: oks,
+      ok: failures === 0,
+      succeeded: oks,
       failed: items.length - oks,
       items: results,
+      ...(step.itemsResolvedFrom ? { itemsFrom: step.itemsResolvedFrom } : {}),
+      outFile: summary.outFile,
+      outputText: summary.outputText,
+      outputTruncated: summary.truncated || undefined,
     };
     parentAction.status = failures === 0 ? 'succeeded' : 'failed_terminal';
     parentAction.itemsCompleted = oks;
@@ -1256,6 +1307,31 @@ export class WorkflowRuntime {
     return { ok: failures === 0, results };
   }
 
+  writeFanoutSummary(step, items, results, oks) {
+    const lines = [`# fanout ${step.id}: ${oks}/${items.length} items ok`, ''];
+    for (const [index, entry] of results.entries()) {
+      const item = entry?.item ?? items[index];
+      const label = typeof item === 'string' ? item : JSON.stringify(item);
+      const verdict = entry?.verdict;
+      lines.push(`## [${index}] ${label} — ${verdict?.ok === true ? 'ok' : `failed: ${verdict?.why ?? 'no result'}`}`);
+      if (entry?.outFile) lines.push(`artifact: ${entry.outFile}`);
+      let text = '';
+      try {
+        if (entry?.outFile && existsSync(entry.outFile)) text = readFileSync(entry.outFile, 'utf8');
+      } catch { /* the per-item artifact is optional in the summary */ }
+      if (text.trim()) {
+        lines.push('', text.length > FANOUT_ITEM_EXCERPT_BYTES
+          ? `${text.slice(0, FANOUT_ITEM_EXCERPT_BYTES)}\n[truncated]` : text.trimEnd());
+      }
+      lines.push('');
+    }
+    const outFile = join(this.runDir, `out-${step.id}-summary-${Date.now().toString(36)}.md`);
+    const full = lines.join('\n');
+    try { writeFileSync(outFile, full); } catch { /* summary is best-effort; items remain in state */ }
+    const truncated = full.length > OUTPUT_TEXT_CAP_BYTES;
+    return { outFile, outputText: truncated ? full.slice(0, OUTPUT_TEXT_CAP_BYTES) : full, truncated };
+  }
+
   recordOutput(stepId, verdict, paths) {
     let outputText = null;
     let truncated = false;
@@ -1282,11 +1358,3 @@ export class WorkflowRuntime {
     this.persist();
   }
 }
-
-function renderTemplate0(str, scope) {
-  return str.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_, ref) => {
-    const v = ref.trim().split('.').reduce((acc, k) => (acc == null ? undefined : acc[k]), scope);
-    if (v === undefined) throw new Error(`unresolved ref {{${ref.trim()}}}`);
-    return typeof v === 'string' ? v : JSON.stringify(v);
-  });
-}

package/src/workflow/template.js

@@ -10,14 +10,32 @@ export function getPath(obj, path) {
   return path.split('.').reduce((acc, key) => (acc == null ? undefined : acc[key]), obj);
 }
 
+/**
+ * The only things bullswarm treats as template refs: a known root followed by
+ * dotted identifier segments. Anything else between double braces — a JSDoc
+ * type like `{{maxLength?: number}}`, a Mustache/Jinja snippet, a JS object in
+ * a template literal — is ordinary prompt text and is left exactly as written.
+ * (Observed 2026-08-28: a planner-authored verify prompt containing the literal
+ * `{{maxLength?: number}}` killed the action at render time with zero attempts.)
+ */
+export const TEMPLATE_REF_ROOTS = ['item', 'inputs', 'outputs', 'runId', 'wfDir', 'steps'];
+const TEMPLATE_REF_GRAMMAR = new RegExp(`^(?:${TEMPLATE_REF_ROOTS.join('|')})(?:\\.[A-Za-z0-9_-]+)*$`);
+export const TEMPLATE_TOKEN_RE = /\{\{\s*([^}]+?)\s*\}\}/g;
+
+export function isTemplateRef(ref) {
+  return typeof ref === 'string' && TEMPLATE_REF_GRAMMAR.test(ref.trim());
+}
+
 /**
  * Expand {{ref}} tokens in a string against a scope object.
  * Supports {{item}}, {{item.path.to.field}}, {{inputs.x}}, {{outputs.stepId}},
- * {{runId}}, {{wfDir}}. Non-string values are JSON-stringified.
+ * {{runId}}, {{wfDir}}. Non-string values are JSON-stringified. Double-brace
+ * text that is not a ref (see isTemplateRef) is returned untouched.
  */
 export function renderTemplate(str, scope) {
   if (typeof str !== 'string') return str;
-  return str.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_, ref) => {
+  return str.replace(TEMPLATE_TOKEN_RE, (match, ref) => {
+    if (!isTemplateRef(ref)) return match;
     const v = getPath(scope, ref.trim());
     if (v === undefined) {
       throw new Error(`template ref "{{${ref.trim()}}}" unresolved at render time`);
@@ -89,13 +107,27 @@ export function extractItems(state, itemsFrom) {
 
 /** Parse the first JSON array found in a text blob, tolerating prose around it. */
 export function parseJsonArray(text) {
-  const start = text.indexOf('[');
+  if (typeof text !== 'string') return null;
+  const tryParse = (slice) => {
+    try {
+      const arr = JSON.parse(slice);
+      return Array.isArray(arr) ? arr : null;
+    } catch {
+      return null;
+    }
+  };
+  // Workers are told to END their output with the array, so prefer the
+  // trailing array: from the last "]" walk "[" candidates right-to-left until
+  // one parses. Prose that itself contains brackets ("[see below]") then no
+  // longer poisons the parse.
   const end = text.lastIndexOf(']');
-  if (start === -1 || end <= start) return null;
-  try {
-    const arr = JSON.parse(text.slice(start, end + 1));
-    return Array.isArray(arr) ? arr : null;
-  } catch {
-    return null;
+  if (end === -1) return null;
+  for (let start = text.lastIndexOf('[', end); start !== -1; start = text.lastIndexOf('[', start - 1)) {
+    const parsed = tryParse(text.slice(start, end + 1));
+    if (parsed) return parsed;
+    if (start === 0) break;
   }
+  // Fallback: the widest span (first "[" to last "]").
+  const first = text.indexOf('[');
+  return first !== -1 && first < end ? tryParse(text.slice(first, end + 1)) : null;
 }

package/src/workflow/validate.js

@@ -7,6 +7,8 @@
 //   W3. Lanes and pinned pools are checked against the live registry so a
 //       typo never burns quota discovering itself mid-run.
 
+import { TEMPLATE_TOKEN_RE, isTemplateRef } from './template.js';
+
 const LANES = ['analyze', 'build', 'chore'];
 const ON_ERROR = ['continue', 'fail', 'skip-phase'];
 const STEP_TYPES = ['run', 'fanout', 'verify', 'decide'];
@@ -24,12 +26,17 @@ function collect(issues, ok, msg) {
   return ok;
 }
 
-/** Extract {{ref}} tokens from a string. */
+/**
+ * Extract {{ref}} tokens from a string. Only grammar-conforming refs count
+ * (known root + dotted identifiers); other double-brace text is prompt content.
+ */
 export function templateRefs(str) {
   const out = [];
-  const re = /\{\{\s*([^}]+?)\s*\}\}/g;
+  const re = new RegExp(TEMPLATE_TOKEN_RE.source, 'g');
   let m;
-  while ((m = re.exec(str)) !== null) out.push(m[1].trim());
+  while ((m = re.exec(str)) !== null) {
+    if (isTemplateRef(m[1])) out.push(m[1].trim());
+  }
   return out;
 }