bullswarm 0.11.1 → 0.12.1

package/CHANGELOG.md

@@ -1,5 +1,102 @@
 # bullswarm changelog
 
+## 0.12.1 — a burst-gated provider is waited for, never failed on the spot
+
+- `workflow` runs no longer die with `no eligible pool` when every candidate
+  pool is burst-gated (provider 5-hour window ≥ 90 % used). The runtime parks
+  the dispatch in a new `waiting_for_quota` stage (`state.quotaWait` names the
+  pool, its 5h usage and reset time; events `dispatch.waiting_for_quota`,
+  `dispatch.quota_available`, `dispatch.quota_wait_expired`), re-reads the
+  provider meter every 60 s, and continues the moment the gate lifts. It gives
+  up — with the pool, usage and reset time in the failure reason — only after
+  the known reset time plus 10 min of grace (5 h when no reset time is known).
+  The planner's context is composed after the wait, so it never sees an empty
+  pool list. Observed 2026-08-28 19:09 Z: the first 0.12.0 comparison run
+  failed in 4 s because the account's Claude 5h window read 91 % (reset
+  22:30 Z); Claude Code in the same situation waits on the rate limit.
+  Options for embedding callers/tests: `quotaPollMs`, `quotaWaitGraceMs`,
+  `quotaWaitUnknownResetMs` on `runWorkflow`; `readMeter` injection.
+
+## 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.1",
   "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,35 @@ 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.
+
+A burst-gated provider (5-hour window ≥ 90 % used) is a *wait*, not a
+failure: the run parks in stage `waiting_for_quota` (`state.quotaWait` shows
+the pool, usage and reset time), re-reads the meter every 60 s, and continues
+when the window resets. Only after the reset time plus 10 min of grace does the
+action fail, with the gate named in `why`.
+
 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`);