bullswarm 0.23.2 → 0.25.0

package/AGENTS.md

@@ -29,10 +29,12 @@ content. Published as `bullswarm` on npm.
    stored under `~/.bullswarm/drafts/<name>/` and are runnable by name
    without an upfront JSON. JSON is still the durable artifact — drafts
    are JSON documents, just built one mutation at a time.
-8. Goal-driven execution is zero-graph by default: `bullswarm workflow goal`
-   internalizes the planner contract, chooses the orchestrator and workers,
-   persists the generated workflow, and can detach so observation never
-   depends on the initiating agent or CLI process.
+8. 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, and the graph finishes without automatic gap rounds. `verified`
+   separately records requirement evidence. `--isolation` opts into strict
+   per-worker worktrees. Saved V2 runs preserve their original semantics.
 
 ## Development
 

package/CHANGELOG.md

@@ -1,5 +1,159 @@
 # bullswarm changelog
 
+## 0.25.0 — shared programs that finish with the graph
+
+- New goal workflows share the target worktree by default. File territories
+  guide scheduling; newly created files and edits survive worker failure or
+  cancellation. Use `--isolation` for strict per-worker worktrees and exact-file
+  ownership. Saved older runs keep their original execution policy.
+- Independent actions run concurrently, and dependents start as soon as their
+  own inputs finish. An unrestricted integrator (`build`, empty `ownedFiles`)
+  runs alone after its writers and can reconcile shared files.
+- Programs finish when their graph finishes, without automatic gap-planning
+  rounds. `completed` describes execution; `verified` separately records
+  passing requirement evidence. Negative evidence stays visible, and further
+  repairs use explicitly authored programs.
+- Unexpected worker errors become action failures; independent branches keep
+  running. Quiet workers retain a kernel heartbeat, dead kernels are identified
+  in the TUI, and resume preserves durable successes and published results.
+- Cancellation intent survives concurrent kernel writes. Resume uses a kernel
+  lease and tracks delegate process groups; SIGTERM/SIGINT produce a resumable
+  interruption, and surviving delegates are drained before replacement work.
+  Durable completion receipts recover both successful worker output and partial
+  isolated integration without replaying the worker.
+- Failed/interrupted isolated workspaces are retained, conflicting user edits
+  block integration, and submodule file trees no longer break manifest capture.
+- Program dashboards show dependency levels instead of keyword-inferred phases,
+  including for saved runs. Independent levels can overlap as actions become ready.
+- Plain dependencies no longer need artificial artifact declarations. Evidence
+  prompts can inspect product JSON/output formats without being mistaken for
+  instructions to replace the kernel's verdict format.
+- The agent skill now presents one short choose → plan → launch → inspect flow,
+  with advanced operations in a separate reference. It distinguishes a planning
+  contract from a launch and passing evidence from guaranteed correctness.
+- Isolated ownership checks exclude dependency trees at every depth and handle
+  literal filenames containing glob metacharacters.
+
+## 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,35 +228,56 @@ 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
 target was reached. `--concurrency` still bounds simultaneous dispatches so
 the scheduler can batch a wider useful program safely.
 
-Bullswarm first runs optional read-only reconnaissance, then invokes one
-logical, resumable Workflow Planner conversation. The planner proposes a
-complete bounded program of generic actions. Work actions produce artifacts;
-evidence actions independently judge named requirements. The kernel rejects
-malformed, cyclic, overlapping, or needlessly serialized proposals before
-dispatch, runs dependency-ready file-disjoint actions concurrently, and
-updates the requirement ledger from schema-valid evidence. Only real
-consolidated gaps re-enter the planner. There are no formal reviewer or repair
-roles and no automatic semantic repair/reverify loop.
+The caller authors a complete program, or explicitly asks for a dispatched
+planner. The kernel validates the graph, executes it, and returns every action
+result. Independent agents share the target worktree. `ownedFiles` describes
+intended territory and lets the scheduler serialize overlapping writers; it
+does not reject or discard edits. A dependent starts as soon as its own inputs
+finish, without waiting for unrelated siblings. A failed action skips its
+dependents while other branches continue.
+
+After a parallel implementation wave, plan one integrator depending on all its
+writers. Give it `lane: "build"` and `ownedFiles: []` to run alone with permission
+to fix any file. Its prompt should read worker outputs, apply cross-territory
+requests, reconcile shared files, and run the repository acceptance commands.
+Analyze actions remain read-only. Evidence actions are optional and report
+independent judgments; negative evidence does not open another planner round.
+The graph ends with `completed` when all actions succeeded, or `partial` when
+some failed or were blocked. `verified` separately records whether all mandatory
+requirements have fresh passing evidence. Read that qualification and the
+actual outputs before claiming acceptance. Further repairs use a new program.
 
 Lane and effort are separate decisions for every proposed action. `analyze` is
 read-only investigation, judgment, or evidence; `build` is contextual product,
@@ -269,7 +292,8 @@ then resolves through the High/Medium/Low routes configured by `bullswarm setup`
 
 The planner does not author phases or declare success/failure. The kernel
 derives stable presentation stages for the TUI and computes the final V2
-result. Old autonomous run directories are not migrated or resumed;
+result. Saved V2 runs retain their original execution and workspace policy on
+resume. V1 autonomous run directories are not migrated or resumed;
 explicitly naming one fails before any paid dispatch. Fixed JSON workflows and
 drafts remain a separate authored-graph feature with their existing step
 types.
@@ -286,25 +310,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.
@@ -324,15 +353,58 @@ hard-stop useful work. `--concurrency` is the actual bound on simultaneous
 dependency-ready dispatches. There is no default wall-clock timeout: fresh
 semantic/transport heartbeats allow a useful worker to continue, while silence
 is inspected rather than blindly killed.
-Interactive setup also records a worktree-isolation
-preference (`agent-decides`, `off`, or `required`); Bullswarm communicates that
-policy to the V2 kernel. Unless explicitly set to `off`, mutating autonomous
-actions use isolated worktrees; the kernel checks actual changed paths against
-declared ownership before integration. `off` serializes shared-workspace
-writers and still enforces the changed-path boundary.
+New goal runs use the shared workspace regardless of the older setup
+worktree-isolation preference. Add `--isolation` to `workflow goal` when you
+explicitly want per-worker worktrees and strict ownership before integration.
+Pass it to `workflow plan contract` and `workflow plan validate` as well so the
+contract describes that run. Shared execution does no manifest scan, copying,
+integration, or rollback. Its final Git inventory is advisory, includes
+pre-existing/concurrent changes, and never prevents completion if unavailable.
 
 ## 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 handles graph validation, quota routing, scheduling,
+mechanical retries, optional evidence, durable recovery, and the 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      # initial scout or explicit steering pause
+bullswarm workflow plan submit <shortId> --program plan-2.json --watch
+```
+
+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.
+
+For foreground execution, exit 0 means the graph ran successfully or paused
+durably; it does not imply independent verification. An independent launch
+also returns 0 before the workers finish. Consume its eventual result.
+
+`--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 for an initial plan or queued user steering, it writes
+`planner-request-turn-N.json`, 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. Older saved V2
+runs still support their original gap boundaries and `--exhausted` submissions.
+`--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
@@ -393,8 +465,12 @@ After a workflow reaches a terminal state, agents should consume
 `workflow runs result <id> --json` instead of probing `state.json`, task files,
 or provider-specific output. Autonomous V2 returns the versioned
 `bullswarm.workflow.result.v2` envelope with kernel-computed status, fresh
-requirement evidence, action/artifact records, explicit gaps, usage, and
-verification qualification. Fixed authored workflows retain their existing
+requirement evidence, per-action status/failure/output files, explicit gaps,
+usage, and verification qualification. New programs include `executionMode:
+"program"` and a `workspace` report with `changedFiles`, `baselineChangedFiles`,
+and warnings. This is a Git status inventory, not attribution to individual
+workers; files stay in the target directory. A completed program may be
+unverified and contain negative evidence. Fixed authored workflows retain their existing
 result envelope. `runs show` remains the low-level debugging surface.
 Goal launch output includes an `instructions` handoff with four named paths:
 `agentInspect` for a machine-readable snapshot, `watch` for low-noise progress,
@@ -465,12 +541,19 @@ bullswarm workflow action show --json <id> <actionId>
 bullswarm workflow approval approve --json <id>  # then resume the run
 ```
 
-Cancellation is persisted as `cancelling`, terminates an active child process,
-records its termination signal and latency evidence, then commits `cancelled`.
-`SIGTERM` and `SIGINT` use the same cooperative child termination path but
-commit a distinct resumable `interrupted` state. On every workflow command,
-active states with a dead/stale owner are automatically reconciled to
-`interrupted` instead of remaining falsely `running`.
+Cancellation stops active delegates and commits `cancelled`. V2 goal workflows
+keep the operator request in a separate durable file so kernel progress cannot
+overwrite it; authored V1 graphs additionally expose a `cancelling` state.
+`SIGTERM` and `SIGINT` stop delegate process groups and commit a resumable
+`interrupted` state. A V2 resume holds an exclusive kernel lease, stops recorded
+surviving delegates from the previous kernel, and finishes post-processing from
+durable successful-attempt receipts instead of dispatching that work again.
+
+Watchers identify dead kernels as interrupted; V2 state is reconciled on resume.
+Unfinished attempts may execute again, so external side effects still require
+idempotency. Shared edits are retained. Failed or interrupted isolated trees
+are preserved for inspection; result warnings identify any retained trees.
+Recovery refuses to overwrite conflicting user edits during integration.
 
 `workflow steer` is optional operator guidance, not hot-patching. It appends a
 durable instruction that is delivered only to the next not-yet-started