bullswarm 0.36.0 → 0.37.0

package/AGENTS.md

@@ -30,6 +30,15 @@ step, the dispatched planner or the preflight scout alike; the
 needs-you block with `step rerun --avoid` and `step accept`; the per-step
 `route`; `verifyRounds` counts fixes (default 1); reviews are placed only by
 route. Runs started earlier keep their rules (`features.json`).
+0.37.0 (program v3, the generic model) has landed: a step is a run, and a
+workflow composes steps, phases, gates and loops. `bullswarm run` is a
+one-step workflow. New programs are `bullswarm.workflow.program.v3`: a step
+passes by facts (clean exit, deliverable produced, evidence passed, answer
+matching its schema), a gate waits for `workflow continue`, a loop reruns its
+steps until one condition holds (at most 5 rounds), and new work is added
+with `workflow add`, never by editing the run's steps. v3 reports facts per
+step and has no requirement IDs, `evidenceFor` or `verifyRounds`. v2 programs
+and saved runs keep running and replaying as before.
 
 ## Non-negotiable doctrine
 
@@ -82,12 +91,17 @@ route. Runs started earlier keep their rules (`features.json`).
 7. New goal workflows are caller-planned programs in a shared workspace.
    `bullswarm workflow goal --program` executes the graph; `--orchestrator`
    explicitly delegates planning. File territories are advisory scheduling
-   hints. A failed check gets one fix step and one re-review
-   (`defaults.verifyRounds`, default 1, 0-3), then the caller, who takes over
-   through the watcher's needs-you block: rerun elsewhere, change the step,
-   take over, or accept anyway. `verified` separately records requirement
-   evidence. `--isolation` opts into strict per-worker worktrees. Saved V2
-   runs preserve their original semantics (`features.json`).
+   hints. In a v3 program (the format for new work) a check is an ordinary
+   step, and fixing until it passes is a loop the caller declares (`loops`,
+   `until` one condition, `maxRounds` 1-5); a loop out of rounds or a gate
+   waits for the caller (`workflow continue`), and a failed step goes to the
+   caller through the watcher's needs-you block: rerun elsewhere, add steps
+   (`workflow add`), take over, or accept anyway. v3 validate refuses
+   `defaults.verifyRounds`. In a v2 program a failed check gets one fix step
+   and one re-review (`defaults.verifyRounds`, default 1, 0-3), then the
+   caller, and `verified` separately records requirement evidence.
+   `--isolation` opts into strict per-worker worktrees. Saved V2 runs
+   preserve their original semantics (`features.json`).
 8. Historical authored-graph runs remain visible as read-only `legacy` rows.
    Their executor was removed in 0.27.0; driving commands fail closed before
    dispatch and historical run directories remain untouched.

package/CHANGELOG.md

@@ -2,6 +2,240 @@
 
 ## Unreleased
 
+## 0.37.0 — One model: steps, phases, gates and loops
+
+- 0.37.0 in one line: a step is a run, and a workflow composes steps, phases,
+  gates and loops. `bullswarm run` is a one-step workflow; `bullswarm workflow
+  goal --program` runs a program you write. New programs are
+  `bullswarm.workflow.program.v3`; v2 programs and saved runs still run and
+  replay as before.
+- workflow: program v3 has four blocks. `steps` (the work: `id`, `prompt`,
+  `dependsOn`, and optional `phase`, `label`, `lane`, `effort`, `reasoning`,
+  `route`, `answer`, `evidence`, `deliverable`, `files`, `retry` 0 or 1,
+  `timeBox`), `phase` (a label that groups steps and changes nothing else),
+  `gates` (`{id, dependsOn, when?, note?}`: the steps behind it wait for
+  `bullswarm workflow continue <run> <gate>`, or only when its condition
+  holds) and `loops` (`{id, steps, until, maxRounds}` 1-5: the steps run again
+  until the condition holds). There is one condition form:
+  `{step, field, equals?}` on a required boolean of the step's answer, or
+  `{step, evidence: "passed"}`. A check is an ordinary step with an `answer`
+  schema and/or `evidence`; roles, kinds, requirement IDs, `evidenceFor` and
+  `verifyRounds` belong to v2 programs and are refused in v3.
+- workflow: `answer` asks a step to write JSON to a file Bullswarm names; the
+  file (at most 256 KiB), not the reply, is checked against the schema (a
+  mismatch is failure kind `schema`), handed to the steps that depend on it,
+  read by conditions and printed by `watch`, `wait` and `runs result`. The
+  text of `runs result` on a v3 run prints `# answer  <step>  <json>` for each
+  step that declares one (and no `# gaps` line), and `runs result --json
+  --summary` carries it as the step's `answer` (`answerBytes` in its place when
+  the answer's JSON is over 1 KiB; the full result holds it). A finished step
+  whose answer passed its schema reads `answer checked`, not proven: a
+  well-formed answer is the worker's claim, and only a command or schema check
+  Bullswarm runs itself proves a step (the proof line counts such steps apart,
+  `N answer checked: <steps>`).
+- workflow: new verbs for v3 runs. `bullswarm workflow add <run> --steps
+  part.json` (or `--from-answer <step>`) appends steps, gates and loops without
+  changing anything the run has, and reopens a finished run. `bullswarm
+  workflow wait <run> <id...>` reads until the named steps, gates or loops
+  settle and prints their facts and answers (exit 0, 1 when one failed or the
+  run stopped short, 2 on a timeout or unknown id). `bullswarm workflow
+  continue <run> <gate|loop> [--rounds <1-5>]` passes a waiting gate or gives
+  a loop more rounds. A run with only waiting gates or loops left is parked
+  with status `waiting`; `watch --until trouble` wakes on it and prints the
+  `continue` command.
+- workflow: a v3 run's steps are never edited. `plan revise` on a v3 run
+  accepts only reruns and otherwise refuses with "a v3 run's steps cannot be
+  added, changed or removed with plan revise in this build; add steps, gates
+  or loops with `bullswarm workflow add` …". The needs-you block and the
+  refusals on a v3 run offer `add steps` / `then wait` (`bullswarm workflow add
+  <run> --steps part.json`, then `bullswarm workflow wait <run> <added ids>`)
+  where a v2 run offers `change the step`.
+- workflow: a completed v3 run hands nothing back and prints no `your call:`
+  (a v3 run is never "verified": every step succeeding is what it reports, and
+  its `runs result --json --summary` carries no `verified` field). A
+  partial v3 run's `restart` line names the run's folder: `start a new run:
+  bullswarm workflow goal "<goal>" --cwd <run folder> --program <file.json>`.
+- workflow: `bullswarm workflow plan contract` prints the v3 contract
+  (`bullswarm.workflow.contract.v3`: fields, rules and an example that
+  validates); `--v2` prints the contract of old programs. `plan validate`'s
+  launch line names the absolute path of the program file you gave it.
+- workflow: a v3 build or chore step in a folder that is not a git repository
+  is now checked for a change: Bullswarm lists the folder before and after the
+  worker (up to 5,000 files and 64 MiB, `.git` and `node_modules` skipped), and
+  a step that changed nothing fails `not-produced`. In a larger folder the
+  change stays unchecked, as before; name the step's `files` there.
+- workflow: `bullswarm workflow goal --program` launches print `watch
+  --until trouble` for a v3 run, since a gate or loop can stop it for you.
+- run: `bullswarm run` is a one-step workflow. Its flags become a one-step
+  program that the workflow kernel runs in the foreground, with no scout and no
+  planner, and the run is recorded under `workflows/<id>/` with its rollup, so
+  `bullswarm workflow runs --all` and `workflow runs show <shortId>` list it
+  with the other runs. It no longer writes a separate task entry to the
+  decision log: the step's attempt writes the one entry, as every workflow
+  step does. The verdict keeps `ok`, `why`, `failureKind`, `retryAfter`,
+  `pick` and `outFile`, and adds `runId`, `shortId`, `answer`, `answerCheck`
+  and `attempts`; `why` is the run's own fact line (`all 1 step succeeded`, or
+  the step's failure). The `--json` verdict is compact (about 50 lines): the
+  last attempt's full usage (`meta.usage`, often 200 lines of cost detail) is
+  replaced by `usage`, a short summary of the whole run (attempts, minutes,
+  tokens, money with its basis), and the last field, `details`, names
+  `bullswarm workflow runs result <shortId> --json`, where per-attempt cost
+  lives. A caller that reads only the tail still finds its run. The text
+  verdict ends with `run: <shortId> · details: bullswarm workflow runs result
+  <shortId>`.
+- run: a run gets the step's one automatic retry (a crash on another pool
+  that can run it, a failed answer check on the same pool with the errors
+  attached). `--no-retry` gives one attempt, as before. A usage limit is
+  still never retried.
+- run: a run passes by facts, as every workflow step does: the exit, its
+  deliverable and, with the new `--answer-schema <file>`, a JSON answer the
+  worker writes to a file Bullswarm names and Bullswarm checks against the
+  schema (a mismatch is failure kind `schema`). A `build` or `chore` run must
+  change a file, else it fails `not-produced`; ask a question on
+  `--lane analyze`. A file git ignores counts when its bytes change (a
+  deliverable in an `out/` that `.gitignore` lists), except tool caches and
+  build output (`dist`, `build`, `coverage`, `target`, `*.log`,
+  `*.tsbuildinfo`), and no worker prompt names a commit as a way to produce,
+  so a retry is never steered into committing.
+- workflow: `workflow runs` lists a goal that starts with a folder ("Work in
+  /path/proj. Read every ticket…") by the words after the folder, or by the
+  next line when the folder is alone on its line, so runs with the same
+  lead-in can be told apart. A bare leading file path stays, shown by its
+  name ("parser.js: fix …").
+- workflow: a `## Not done` line that says `none`, `nothing` or `n/a` and
+  then gives a reason or a scope (`- none for this build step. The review
+  rounds belong to other actions…`, `- None — all done.`, `- nothing left`)
+  is not an unfinished item, so the step no longer reads `returned early · 1
+  not done`. A line that goes on to name work (`- none of the tests pass`,
+  `- None, except the README update.`) still counts.
+- run: new routing flags `--avoid-pool`, `--use-provider` and
+  `--avoid-provider` (comma-separated), the same filters a workflow step's
+  `route` takes. `--dry-run` prints the kernel's own first pick for the step.
+- run: keep-on-caller and incumbency are gone. The calling agent is never a
+  pool of its own run, so `keepOnClaude` is no longer in the verdict;
+  `--no-caller` is accepted with a one-line notice for this release and
+  will be removed. A run at
+  the recursion depth limit is a plain refusal: `ok: false`, failure kind
+  `depth`. Every step is routed by one rule, so nothing reads or writes
+  `incumbents` in `state.json` or `config.callerName` (a new home no longer
+  writes it), and the fleet view and the Claude Code mod no longer show
+  "incumbent for".
+- run: `--timeout <seconds>` kills the worker as before and the verdict reads
+  `timeout after <N>s` with failure kind `interrupted` (a process failure), so
+  it gets the one automatic retry on another pool; `--no-retry` gives one
+  attempt. A new failure kind was not added: `interrupted` already has the
+  right retry, and one more kind would change every failure table for one flag.
+- mod: routed Claude Code subagents run on lane `analyze` with one attempt: a
+  build run must change a file, so a subagent that only answers would fail
+  `not-produced`.
+- dashboard: a v3 run reads by its blocks. The Run page groups its steps by
+  their `phase` (plan boxes and timeline rules carry the phase name), draws each
+  gate and loop as a row of its own (`loop polish · passed in round 2 of 3 ·
+  check's evidence passed`, `gate approve · waiting for you · <note>` with its
+  `continue` command), tags each loop step's attempt with its round, and prints
+  each attempt's checked answer under it. A run parked at a gate or loop reads
+  `waiting at gate approve` with `next: bullswarm workflow continue <run>
+  <gate>` on Run, Runs and Home. A one-step run shows no plan boxes and no
+  phase frame. A v3 run or step never reads `verified` or `not verified`; the
+  Step page leads its result with the answer. `bullswarm workflow runs --json`
+  lists a parked run's `waitingFor`.
+- run: the verdict carries `notDone`, `{count, items}` (the first five
+  items, each at most 160 characters), when the worker's report listed
+  unfinished items under `## Not done`, and `null` otherwise; the text verdict
+  prints `worker left 2 items not done: <item>; <item>`. `ok` and `why` are
+  unchanged: a step that returned early still succeeded by its facts, and the
+  caller now sees what it left. The mod's verdict note and routed-subagent
+  notice say the same.
+- mod: the verdict note of `bullswarm run --answer-schema` carries the checked
+  answer (or the failed check); a launched workflow is pointed at `workflow
+  watch <run> --until trouble` instead of `--next`; the strip and prompt
+  context list a parked run as `waiting at gate <id>` with its continue
+  command; a `workflow watch` or `workflow wait` result gets a note naming a
+  waiting gate or loop, the loop's round and the checked answers.
+- stats: the totals line and Home's figures name single runs apart from
+  workflows (the totals line reads `3 runs · 5 workflows`, Home reads
+  `Runs: 3 · workflows 5 · verified 2 (40%)`). Home's verified count and share
+  are of the v2 workflows alone, and Home leaves them out when the period has
+  no v2 workflow (`Runs: 3 · workflows 2`). The overview carries `oneStepRuns`,
+  `verifiableRuns` and `verifiedRuns`, and a v3 rollup carries
+  `programFormat: 3` and, for a one-step run, `oneStep: true`.
+- stats: single runs count. Stats, Budget and History read the single runs the
+  decision log still holds (older ones) and the one-step workflows new runs
+  record, so totals from this version on include `bullswarm run` work that
+  earlier versions left out.
+- stats: one definition of each number on every page. A run belongs to the
+  day it finished (History counted it on its start day). A money total exists
+  only when every attempt in the scope was priced, and the priced subtotal
+  always travels beside it; Budget's `apiEquivalentUsd` is the pool's whole
+  amount for the period instead of a sum of per-pool amounts, and History's
+  day spend is the priced subtotal, equal to the Stats trend for that day.
+  Worker minutes and usage come from one per-attempt record, so Stats numbers
+  move only by rounding (up to 0.01 worker-minutes).
+- fixed (candidate QA): `workflow add` with a step whose `phase` names a
+  phase the run already has failed `presentation is missing program action
+  <step>`; the step now joins that phase.
+- fixed (candidate QA): a step whose route left no pool said `every pool that
+  could run it shares a provider` when a pool of another provider could run
+  it one tier up. The reason now names the step's lane and tier and each other
+  provider's pool with what ruled it out (`claude-code (claude-code): no model
+  on the low tier for analyze work (has high)`), and the step records
+  `routeWhy` and `routeCandidates` (`{pool, provider, excluded}`) in its
+  failure and in `result.json`, which were null before.
+- fixed (candidate QA): the result summary named at most four steps in
+  `answerCheckedSteps` beside a larger `answerChecked` count; it now names
+  every one (and every `acceptedSteps` entry). A v3 step whose route left no
+  pool reads `retryable: false` with `noPool: true` in `handback.unfinished`,
+  since resume fails it the same way until a pool passes its route at its
+  tier.
+- fixed (candidate QA): `bullswarm workflow plan contract` with no goal
+  printed a usage error; the v3 contract now prints with `goal: null` and
+  `'<goal>'` in its commands. `--v2` still needs the goal.
+- fixed (candidate QA): a loop you continued after it ran out of rounds read
+  as passed (`✓ loop polish passed`). It now reads `→ loop polish continued by
+  the caller after 3 of 3 rounds (condition not met)` in `workflow continue`,
+  watch, wait and the Run page; `result.json` records `loops: [{id, outcome,
+  rounds, maxRounds}]` (`outcome` is `passed`, `continued-unmet`,
+  `out-of-rounds`, `blocked` or `pending`), names a continued loop at the end
+  of `reason`, and the summary and proof line carry it.
+- fixed (candidate QA): `watch --until trouble|outcome` printed nothing until
+  a wake; it now prints one start line, `watching <run> until trouble · <n>
+  steps`.
+- fixed (candidate QA): in a run under the failure rule, an attempt that
+  failed and was retried is recorded as `failed` (its `attempt.finished`
+  event says `willRetry: true`), not `interrupted`. Earlier runs keep their
+  label.
+- fixed (candidate QA): a loop writer that changed no file in round 2 or later
+  passed, carrying round 1's work; a loop round is new work now, so it fails
+  `not-produced` like round 1. `workflow wait` said `deliverable files
+  produced` for a step whose attempt changed nothing and carried earlier work;
+  `wait` and `watch` now say `carried from an earlier attempt`.
+- workflow: `watch --timeout <seconds>` exits 0 after that long with no wake,
+  printing `⧖ watch timed out after <s>s · the run is still <status>` and a
+  `next:` line with `--after`, `--since` and `--timeout`, so a foreground watch
+  ends before the caller's tool call is killed and loses no wake.
+- skill: the run-or-workflow choice comes first. One worker that can hold the
+  whole input and make one deliverable (a 40-ticket triage, a research brief,
+  one feature) is one `bullswarm run`, with `--answer-schema` for a checkable
+  answer; do not split an input into chunks unless one worker cannot hold it.
+  A loop's critique asks only for what the sources can show, rounds are capped
+  at 2 unless a round is cheap, and a watch runs in the foreground when the
+  caller's harness cannot wake it when a background process ends. Pattern 5
+  (triage) is one run, or one classify step with a gate for uncertain
+  tickets.
+- removed: keep-on-caller (`keepOnClaude` in the verdict), incumbency (the
+  `incumbents` state and the "incumbent for" lines), and the rule that a run
+  never waits for its caller: a v3 run waits at the gates and loops you
+  declare, and nowhere else.
+- upgrade: nothing to migrate. v2 programs (`bullswarm.workflow.program.v2`)
+  still validate and run, `plan contract --v2` prints their contract, and runs
+  saved by earlier versions keep their rules when resumed or viewed. Write new
+  programs as v3 (`skill/references/patterns.md` has five that validate as
+  printed). Scripts that parsed `keepOnClaude` from a `run` verdict, or passed
+  `--no-caller`, should drop them; scripts that read a `run` verdict gain
+  `runId`, `shortId`, `answer`, `answerCheck` and `attempts`. A `build` or
+  `chore` run that changes nothing now fails `not-produced`, in or outside a
+  git repository: ask questions on `--lane analyze`.
+
 ## 0.36.0 — Usage limits go back to the caller; each account bills itself
 
 - known issues in this release: a limit marker whose reset was guessed still

package/README.md

@@ -36,11 +36,11 @@ flowchart LR
 
 - **Spends quota by pace.** Each task goes to the plan with the most spare quota for how far its window has run, so a plan that is behind, or about to reset with quota left, gets used first.
 - **Picks models for you.** Tasks come in three lanes (`analyze`, `build`, `chore`). Setup asks each CLI which models it offers and suggests the newest one for each effort level, so you don't have to update settings every time a vendor ships a model.
-- **Runs one task or a whole workflow.** `bullswarm run` sends one task to one agent and returns a verdict. For bigger goals your main agent writes a plan; Bullswarm runs the independent steps in parallel across agents, then integration, and a review by a different agent when the plan asks for one.
-- **Checks the work, not the exit code.** A delegate saying "done" isn't enough. Bullswarm reads what it actually produced, and a workflow finishing is kept separate from its requirements being verified.
+- **Runs one task or a whole workflow.** `bullswarm run` is a one-step workflow: one task to one agent, one automatic retry, and an optional answer checked against a JSON schema. For bigger goals your main agent writes a program from four blocks: steps (each with an optional checked answer), phases that group them, gates where the run waits for you, and loops that repeat steps until a condition holds, such as "until the tests pass". Independent steps run in parallel across agents, and a step can be routed away from the agents that did the work it checks.
+- **Checks the work, not the exit code.** A delegate saying "done" isn't enough. Bullswarm reads what it actually produced, runs the checks a step declares (a command, a schema), checks each answer itself, and labels every finished step by what backs it: `proven by command` (a check Bullswarm ran passed), `answer checked` (the answer is well formed, which is a claim, not proof), or `unproven`. A run reports these facts, not a verdict; `verified` requirements belong to old v2 programs only.
 - **Shows everything live.** A terminal dashboard covers quota, history, running workflows and each agent's individual turns.
 - **Works with the agent you already use.** The `/bullswarm` skill teaches Claude Code, Codex and Grok when to delegate. There's also an early-access Claude Code Mod that shows runs and usage inside Claude Code.
-- **Lets you steer mid-run.** Add, change, remove or rerun steps while a workflow is running, or pause and resume it.
+- **Lets you steer mid-run.** Add steps, gates or loops while a workflow runs (`workflow add`, also straight from a step's answer), continue a waiting gate or give a loop more rounds, rerun a step, or pause and resume it.
 - **Extends with providers.** Claude Code, Codex and Grok are built in. Other CLIs can be added as providers without touching the core.
 
 ## See it