bullswarm 0.23.2 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,125 @@
 # bullswarm changelog
 
+## 0.24.0 — the calling agent is the Workflow Planner
+
+**BREAKING.** `bullswarm workflow goal` now needs a program. Add
+`--orchestrator auto` to any existing invocation to keep the previous
+behaviour, or pass the program you authored with `--program <file.json>`.
+
+- **Caller-first by default.** `workflow goal "<goal>"` with no
+  `--program`, `--scout`, or `--orchestrator` exits 2, launches nothing, and
+  prints the commands that come next (`{"error": "program-required", "next":
+  {contract, validate, launch, scout, orchestrator}}` under `--json`). The
+  kernel never plans on the caller's behalf unless the caller asks for it by
+  name. Exit codes are a contract: 0 done or paused durably for the caller
+  (nothing running), 1 the run ended without completing, 2 usage or validation
+  error with nothing launched.
+
+- `bullswarm workflow goal --program <file.json>` makes the invoking agent the
+  Workflow Planner. The kernel validates the caller-authored V2 program against
+  the exact requirement ledger before anything launches, executes it with zero
+  planner and (by default) zero scout dispatches, and keeps every kernel-owned
+  guarantee: quota routing, isolated worktrees and changed-path ownership,
+  independent evidence, the requirement ledger, completion, and the stable
+  result envelope. This is Bullswarm's equivalent of Claude Code's `Workflow`
+  tool: the frontier model writes the program once and is consulted again only
+  at a real planning boundary. `--scout` alone has the kernel survey the
+  repository first and pause at the initial boundary for the caller's program.
+
+- **Flag surface.** `--planner dispatched|caller` is removed; the presence of
+  `--orchestrator auto|<pool>` is the switch. `--strict-orchestrator <pool>`
+  becomes `--orchestrator <pool> --orchestrator-strict` and remains as a
+  deprecated alias for one release. `--suggested-plan`, `--no-scout`,
+  `--orchestrator-model`, and `--orchestrator-strict` are rejected without
+  `--orchestrator`: when the caller is the planner, the plan is the program.
+
+- **New commands.** `workflow plan validate "<goal>" --program <file>` dry-runs
+  a program against the contract (same validator, same preview state, no run
+  created) and exits 0 with the accepted actions or 2 with the issues.
+  `workflow cancel <runId>` is a first-class verb that finalizes a run paused
+  for its caller planner inline, and `workflow resume <runId>` is the verb form
+  of `goal --resume`; `goal --resume` and `tui --cancel` remain as aliases.
+
+- **`delegate`.** For workflow-shaped work it now returns the planning contract
+  (`action: "plan-required"`) plus the exact launch line, instead of launching
+  an orchestrated run on the caller's behalf. `--orchestrator auto|<pool>`
+  passes through for callers that do not want to plan.
+
+- **Requirement granularity is surfaced, never forced.** When a goal collapses
+  to a single requirement, `plan contract` adds an `advice.requirements` line
+  and `delegate` adds the same text to its `handoff` (printed as
+  `Requirements ·`): one requirement means one pass/fail verdict for the whole
+  goal, and any gap reopens all of it, so numbering distinct deliverables
+  (`1. ... 2. ...`) buys a tracked requirement, a separate verdict, and gap
+  rounds scoped to the part that failed. A goal that already splits into
+  several requirements never carries the advice, and the text says explicitly
+  not to invent clauses to split a genuinely holistic outcome.
+
+- New `bullswarm workflow plan` surface: `plan contract "<goal>"` prints the
+  requirement IDs the kernel will derive, the planning rules, the generic action
+  fields, the validation it enforces, and a worked example; `plan show <run>`
+  prints the durable planner request a paused run left behind (boundary,
+  context, consolidated gaps, known actions); `plan submit <run> --program
+  <file>` (or `--exhausted --reason <text>`) validates the response against the
+  exact durable state, records it as the next program revision with the same
+  counters a dispatched planner turn would produce (planner turn, expansion
+  round, program revision) plus a `planner.finished` event tagged
+  `source: "caller"` (no `planner.started` and no planner attempt is recorded,
+  because nothing was dispatched), and relaunches the kernel.
+
+- Caller-planner pauses are authoritative and lossless. A resume without a
+  submission re-pauses on the same boundary and turn, even when steering was
+  queued meanwhile: the request is refreshed to list the pending steering
+  (`pendingSteering`), `plan show` does the same refresh, and a submission
+  marks exactly the listed steering delivered; steering queued after that stays
+  pending and opens a steering boundary after the resume. A cancellation
+  requested while paused refuses every submission and `plan show`, `watch`, and
+  the TUI point at the one `workflow goal --resume` that finalizes the
+  cancelled result; finalizing always clears the pause record, and the state
+  validator rejects a terminal run that still claims to be waiting. A caller
+  program supplied at launch is kept in the run directory until applied, so an
+  interruption during an opt-in scout does not lose it. Bare value flags
+  (`--program` with no file) are usage errors instead of a silent
+  dispatched-mode launch, and `plan submit` checks the goal directory before
+  touching state.
+
+- Caller-planner runs pause durably instead of dispatching: at a planning
+  boundary the kernel writes `planner-request-turn-N.json`, records
+  `planner.awaiting` in state, emits `planner.awaiting_caller`, sets the run to
+  `waiting`, and exits. `workflow watch` ends at that pause (exit 0) and prints
+  the `plan show` command; `runs result` and the TUI Next line explain the
+  pause; resuming without a submission re-pauses on the same request. An
+  invalid initial program supplied through `--program` at launch is rejected
+  synchronously; one that fails only against live state pauses with a
+  correction request instead of dispatching anything.
+
+- The dispatched planner prompt and the caller-facing contract now render from
+  one shared rulebook (`v2PlannerContractRules`), so the two planning modes
+  cannot drift. A durable `exhausted` planner decision now survives resume: the
+  kernel finalizes the partial result instead of reopening the boundary.
+
+- `workflow capabilities` reports `plannerModes` and the `callerPlanner`
+  feature; the `bullswarm` skill and operations reference document the
+  caller-planner loop for frontier agents.
+
+- Fixed (ledger): evidence records now carry the ledger-wide `workspaceRevision`
+  they inspected, and semantic evidence recorded on a newer workspace
+  supersedes older evidence for the same requirement (`stale: true`,
+  `staleReason: "workspace-superseded"`). Before, a cross-cutting requirement
+  such as "the full suite passes 19/19" kept its first failed verdict alive
+  forever, because no work action listed it in `affects`; a later passing
+  verdict then conflicted with it and the requirement stayed `blocked` on every
+  gap round. Same-workspace disagreement between two verifiers still blocks,
+  and a mechanical (pending) record never supersedes a judgment. Found live
+  while driving a caller-planner run.
+
+- Fixed: a one-line goal with inline numbered clauses (`"1. Fix the parser.
+  2. Update the docs."`) produced a single requirement; only the
+  newline-separated form split. Both forms now yield one requirement per
+  clause, so `plan contract` advertises the IDs the run will enforce. Inline
+  markers are honored only when the list starts at 1, so prose such as
+  "version 2. Then" is not split.
+
 ## 0.22.1 — unified workflow dashboard navigation
 
 - The workflow dashboard now keeps V2 runs in the unified list and timeline

package/README.md

@@ -79,7 +79,9 @@ bullswarm delegate --cwd ~/some-repo --prompt "Audit all commands, fix help, and
 bullswarm delegate --dry-run --json --cwd ~/some-repo --prompt "Your task"     # bounded classification + decision/plan; no work dispatch
 bullswarm run --lane analyze --add-dir ~/some-repo --task-file /tmp/t.md --json
 bullswarm run --lane analyze --add-dir ~/some-repo --prompt "Inspect the parser" --json
-bullswarm workflow goal "Fix the failing tests and verify the change" --cwd ~/some-repo
+bullswarm workflow plan contract "Fix the failing tests and verify the change" --cwd ~/some-repo --json  # you are the planner
+bullswarm workflow goal "Fix the failing tests and verify the change" --cwd ~/some-repo --program plan.json
+bullswarm workflow goal "Fix the failing tests and verify the change" --cwd ~/some-repo --orchestrator auto  # dispatch a planner agent
 bullswarm health   # re-judge saved outputs; catch gate failures
 ```
 
@@ -89,7 +91,7 @@ bullswarm health   # re-judge saved outputs; catch gate failures
 |---|---|
 | `setup` | Discover installed agent CLIs, show quota state, toggle pools, suggest a routing table, write config. Approval-gated, idempotent. |
 | `integrate` | Register or remove the canonical Bullswarm skill and global awareness rules for Codex, Claude, and Grok. |
-| `delegate` | Explain and execute the smallest reliable shape: one content-verified agent or an autonomous verified workflow. |
+| `delegate` | Explain and execute the smallest reliable shape: one content-verified agent, or the planning contract for an autonomous workflow you author (`--orchestrator` dispatches a planner agent instead). |
 | `run` | route → dispatch → watch → verify → one JSON verdict |
 | `health` | Re-judge saved outputs against their verdicts; surface verify-gate failures and quarantine clusters |
 | `pools` | Show each pool's meter state, pace position, quarantine status |
@@ -226,20 +228,32 @@ phase/step/attempt tree.
 
 ## One-command autonomous goals
 
-For normal multi-step work, give Bullswarm the goal—not a JSON graph:
+For normal multi-step work, give Bullswarm the goal and the program you authored
+for it—not a JSON graph of phases:
 
 ```bash
-# Default: starts independently, prints observation/result commands, and returns.
+# 1. What the kernel will enforce: requirement IDs, rules, action schema, example.
+bullswarm workflow plan contract \
+  "1. Fix the failing tests with the smallest correct change. 2. Verify them." \
+  --cwd ~/some-repo --json
+
+# 2. Launch with your program. Starts independently, prints observation
+#    commands, and returns. Add --watch to follow low-noise progress.
 bullswarm workflow goal \
-  "Fix the failing tests with the smallest correct change and verify them" \
-  --cwd ~/some-repo
+  "1. Fix the failing tests with the smallest correct change. 2. Verify them." \
+  --cwd ~/some-repo --program plan.json --watch
 
-# Follow low-noise semantic progress immediately after launch.
+# Don't want to plan? Ask for a Workflow Planner agent explicitly.
 bullswarm workflow goal \
   "Audit and repair the parser, then run its acceptance tests" \
-  --cwd ~/some-repo --watch
+  --cwd ~/some-repo --orchestrator auto --watch
 ```
 
+`workflow goal` needs a program: with neither `--program`, `--scout`, nor
+`--orchestrator` it exits 2, launches nothing, and prints the commands above.
+That is deliberate — the kernel never plans on the caller's behalf unless the
+caller asks for it by name.
+
 `--max-agents`, `--max-actions`, and `--max-expansion-rounds` are soft V2
 planning targets. They encourage the Workflow Planner to consolidate optional
 work, but the kernel never stops or rejects essential work merely because a
@@ -286,25 +300,30 @@ bullswarm workflow events --json <shortId> --after 0
 bullswarm workflow action show --json <shortId> <actionId>
 ```
 
-Resume a process-interrupted autonomous run from its persisted workflow:
+Manage a run with first-class verbs:
 
 ```bash
-bullswarm workflow goal --resume <shortId> --json
+bullswarm workflow steer  <shortId> --message "<guidance>"   # next planning boundary
+bullswarm workflow cancel <shortId> --json                   # a paused run is finalized here
+bullswarm workflow resume <shortId> --watch                  # verb form of goal --resume
 ```
 
 `--orchestrator <pool>` expresses a preference and immediately falls back to
-another eligible pool if that provider is quota-gated or unavailable. Ordinary
-use can leave selection on `auto`. For controlled provider QA only,
-`--strict-orchestrator <pool>` requires that exact pool and fails if it is not
-available. Controlled comparisons can additionally pin the exact planner
+another eligible pool if that provider is quota-gated or unavailable; plain
+`--orchestrator auto` leaves selection to the kernel. For controlled provider
+QA only, add `--orchestrator-strict` to require that exact pool and fail if it
+is not available. Controlled comparisons can additionally pin the exact planner
 and worker routes without changing global strategy:
 
 ```bash
 bullswarm workflow goal "Implement and verify the change" --cwd . \
-  --strict-orchestrator codex --orchestrator-model gpt-5.6-sol \
+  --orchestrator codex --orchestrator-strict --orchestrator-model gpt-5.6-sol \
   --worker-pool opencode2 --worker-model kaihk/gpt-5.6-luna
 ```
 
+These pins, plus `--suggested-plan` and `--no-scout`, apply only with
+`--orchestrator`. When you are the planner, the plan is the program.
+
 The worker lock covers scout, work actions, and evidence actions. A pool that cannot guarantee
 the requested model is ineligible rather than silently substituting another
 model.
@@ -333,6 +352,46 @@ writers and still enforces the changed-path boundary.
 
 ## Building a workflow from the shell
 
+### You are the planner: `--program` and `workflow plan`
+
+This is the default. The calling agent (Claude Code, Codex, or any frontier
+model with the repository in context) is the Workflow Planner, instead of the
+kernel paying for a dispatched scout and planner that cannot see the
+conversation. The kernel keeps everything it owns — proposal validation, quota
+routing, isolated worktrees and changed-path ownership, independent evidence,
+the requirement ledger, completion, and the stable result envelope — while the
+caller supplies the program, exactly the division of labour Claude Code's
+`Workflow` tool uses between the authoring model and its harness.
+
+```bash
+bullswarm workflow plan contract "1. Fix the parser. 2. Update the docs." --cwd . --json
+#   → requirement IDs (requirement-1..n), rules, action fields, validation, example
+bullswarm workflow plan validate "1. Fix the parser. 2. Update the docs." --cwd . --program plan.json --json
+#   → dry run against that contract; exit 0 valid, exit 2 with the issues; nothing launches
+bullswarm workflow goal "1. Fix the parser. 2. Update the docs." --cwd . --program plan.json --watch
+#   → validated before launch; executes with zero planner/scout dispatches
+bullswarm workflow plan show <shortId> --json      # when the run pauses at a gap boundary
+bullswarm workflow plan submit <shortId> --program plan-2.json --watch
+bullswarm workflow plan submit <shortId> --exhausted --reason "<why no bounded action remains>"
+```
+
+Exit codes are a contract: **0** done or paused durably for you (nothing is
+running), **1** the run ended without completing, **2** usage or validation
+error with nothing launched. Every refusal names the commands that come next.
+
+`--program` accepts the planner response envelope or a bare
+`bullswarm.workflow.program.v2` document. An invalid program exits 2 with the
+validator's issues and nothing is launched. When the kernel reaches a planning
+boundary it does not guess: it writes `planner-request-turn-N.json` (the same
+context a dispatched planner would receive, plus the consolidated gaps and any
+queued steering), sets the run to `waiting`, exits, and `watch` prints the
+`plan show` command. A submitted program contains only new actions and is
+validated against the exact durable state at that boundary; `--exhausted`
+finalizes a partial result with its gaps disclosed. `--scout` without
+`--program` runs the kernel scout first and pauses at the initial boundary so
+the caller plans against a real survey; scout units are advisory for a caller
+planner.
+
 Use an explicit draft when the graph itself is a durable contract and should
 not be planner-defined. `bullswarm workflow draft ...` lets you assemble it one
 mutation at a time. No upfront JSON required. Drafts persist under