bullswarm 0.29.1 → 0.32.0

package/AGENTS.md

@@ -16,7 +16,7 @@ content. Published as `bullswarm` on npm.
    `src/meters/framework.js`).
 3. Provider quirks live in the provider's directory (`src/providers/<name>/`,
    `providers/contrib/<name>/`, or `~/.bullswarm/providers/<name>/`), never in
-   core logic (see `docs/guide/providers.md`).
+   core logic (see `docs/reference/providers.md`).
 4. Quarantine always auto-releases; recursion depth is core-owned via env
    (`BULLSWARM_DEPTH`).
 5. Workflow dispatches must honor the same guarantees as single runs:
@@ -84,7 +84,7 @@ providers live in `src/providers/<name>/`, contrib providers in
 `bullswarm provider scaffold <name> [--from <template>]`, then
 `bullswarm provider validate` and `bullswarm provider probe <pool>`. Write a
 `readUsage` export only if the vendor exposes a usage API — declared meters
-are the fallback, never the goal. The contract is `docs/guide/providers.md`;
+are the fallback, never the goal. The contract is `docs/reference/providers.md`;
 the authoring method is `skill/references/providers.md`.
 
 ## Releasing

package/CHANGELOG.md

@@ -1,5 +1,136 @@
 # bullswarm changelog
 
+## 0.32.0 — the dashboard is the main screen
+
+- wording: a program run's dependency levels are called phases everywhere the
+  product prints them (`Phase 2 · integrate`), matching what the planner's runs
+  already say; the ids in the events are unchanged.
+- dashboard: the full-screen Home, Run, Step, Usage, and Help pages now share
+  a sticky header and bottom nav, keyboard shortcuts, mouse clicks, and wheel
+  scrolling, so a live workflow can be understood in one place.
+- usage and edit: Usage renders every meter window, elapsed mark, reset, pace,
+  credit meter, and rung record with the same coloured cells as the status
+  view; its read-only note hands `[edit]` to setup and returns with fresh data.
+- install: Home's `[install]` action runs the same integration install as
+  `bullswarm integrate install --yes`, then shows each agent's skill,
+  awareness, and Claude Mod status.
+- bare command: after setup, bare `bullswarm` opens the dashboard; the first
+  run and `bullswarm --setup` or `bullswarm setup` open setup, while
+  `bullswarm workflow tui` remains the explicit dashboard form.
+- docs: the README, guides, CLI reference, and Claude Code pages now make the
+  dashboard the main screen and describe the Claude Mod as its read-only
+  counterpart — the same Run, Step, and Usage pages in the same colours, with
+  no edit or install action.
+
+## 0.31.0 — the Claude Mod, and a documentation site
+
+- mod: `mods/bullswarm` puts Bullswarm inside Claude Code's own interface as a
+  Claude Mod (function hooks, early access behind
+  `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1`). Claude's general-purpose subagents
+  are routed to the pool with spare quota through `bullswarm run --no-caller`
+  and answered with the verified output; the verdict of every `bullswarm run`
+  and `workflow goal` the model runs is appended to its Bash result; the pool
+  meters are named in the model's context; a strip above the prompt lists
+  the ongoing workflow runs; and a docked pane shows one run as
+  `bullswarm workflow tui` draws it, every step a button that opens the
+  step laid out as the TUI's agent panel. `/bullswarm pools|status|on|off|
+  refresh|runs|pane|open <step> [run]|routed` answer from the mod; anything
+  else still reaches the packaged skill. The pool rows draw a white mark
+  where the window's elapsed time falls, and `usage` in the pane's bottom
+  nav opens a page with every meter window of every pool, its reset time
+  and pace, the credit meter where there is one, and every pool × tier rung
+  with its model, reasoning and record, grouped by lane or by provider. A
+  `route` tool lets the model switch routing when the person asks. Pool
+  display names come from the
+  `poolAliases` option; `strip` picks `runs`, `full` or `off`.
+- integrate: `bullswarm integrate install --agents claude --yes` also links
+  the mod under `~/.claude/skills/bullswarm-mod` and sets
+  `env.CLAUDE_CODE_ENABLE_FUNCTION_HOOKS` to `"1"` in `~/.claude/settings.json`;
+  `status` reports both and `remove` undoes both. A `settings.json` that is
+  not a JSON object is left alone and reported. `.claude-plugin/marketplace.json`
+  at the repository root makes `claude plugin marketplace add Bulls-Work/bullswarm`
+  and `claude plugin install bullswarm@bullswarm` work too.
+- workflow tui: the Preflight milestone now states the accepted goal (wrapped)
+  with the paths of `goal.json` and `initial-planner-response.json`, and the
+  planner milestone says how many actions in how many dependency levels the
+  plan has. The Live section lists the planner only while it is planning;
+  the "waiting for N workers" planner row and the "· N waiting" count are
+  gone, since Next already says that. The first plan's own milestone is gone
+  too: the levels that follow it say what it planned; plan revisions and
+  rejected planning attempts still appear. A goal with several lines wraps
+  line by line instead of carrying a line break inside one row. `workflow tui <run> --overview
+  [--width <cols>] [--height <rows>]` prints one overview frame (or `--json`)
+  for a caller that draws its own.
+- docs: the documentation site is now a VitePress site under `docs-site/`,
+  built from `docs/` and deployed to GitHub Pages by
+  `.github/workflows/docs.yml` at https://bulls-work.github.io/bullswarm/.
+  Guide (introduction, getting started, concepts, run, workflows, observing,
+  routing), Reference (CLI, workflow program, configuration, providers,
+  result envelope) and Integrations (Claude Code, Codex and Grok, issue
+  watcher) replace the Jekyll pages; the historical notes are indexed under
+  `/notes/`. `tests/unknown-flags.test.js` now checks every command form on
+  the new pages against the CLI.
+
+## 0.30.0 — a run never waits: it finishes and hands back what is left
+
+- workflow: a run no longer waits for anyone. Every point where a
+  caller-planned run used to hold now finishes it and hands the decision
+  back: a `--scout` run with no program, a launch program the kernel could not
+  accept, requirements still open with nothing left to run, and steering still
+  unread when the last step ended. In a study of 41 caller runs on a real
+  project (2026-09-14), one run sat 197 minutes waiting for a caller that had
+  moved on.
+- result: a new optional `handback` field lists every unfinished step with its
+  failure kind, its reason, whether a plain resume runs it again, and
+  `retryAfter` when every pool that could run it was paused; every open
+  requirement with its latest reason; and steering nobody acted on.
+  `runs result --summary` adds `handback.options`, one command each to
+  continue (plan revise), retry (resume), take over, or restart. Results
+  written before 0.30.0 still validate, and their summaries derive the same
+  view.
+- result: the reason line says what happened. "all program actions finished
+  successfully; consult evidence for verification" read as success on runs
+  whose check had failed the work. It now reads, for example, "all 4 steps
+  succeeded, but not verified: requirement-2 failed — requirement-2: …" or "2
+  of 5 steps did not succeed: build-api failed (stalled), …". A long finding
+  quoted there is cut between words and ends in `…`; the full text is in the
+  requirement's `why`.
+- summary: an open requirement's `why` is no longer blanked to fit the 4 KB
+  budget. Concerns, per-step detail and output names shrink first, and a
+  passed requirement carries no `why`. The same study found `why` blank in 6
+  of 10 unverified runs.
+- watch: a finished run prints `outcome: <status> · verified|not verified`,
+  `reason:`, one line per unfinished step and open requirement, unread
+  steering, and `your call:` with the command for each option. A `--jsonl`
+  `finished` object carries `verified`, `reason` and `handback`.
+- resume: `workflow resume` on a finished run is a retry. It reopens the run
+  for pending and cancelled steps, failed steps whose kind a retry fixes
+  (`provider`, `quota`, `auth`, `process`, `unavailable`, `interrupted`,
+  `runtime`, `schema`, `stalled`) and the steps blocked behind them, moves the
+  result to `result-before-resume-<n>.json`, and relaunches. With nothing
+  retryable it prints `nothing to retry`, starts nothing, and exits 1.
+- dispatch: with no pool able to run a step, the step fails at once and says
+  which case it is: every capable pool is paused until a time (recorded as
+  `retryAfter`), the pinned pool cannot run that lane and effort, or no enabled
+  pool has a model on that tier.
+- workers: a worker that writes nothing for 60 minutes is stopped and fails as
+  `stalled`, a mechanical failure retried once. The clock restarts on every
+  byte, so a long step that keeps working is never cut off.
+  `BULLSWARM_WORKER_SILENCE_SEC` sets the limit.
+- kernel: a kernel that throws marks its run `interrupted` with `kernel
+  stopped on an error: <message>` instead of leaving it claiming to run, and
+  `runs show` reports a run whose kernel died as `interrupted`, with the
+  reason and the resume command.
+- validate: an `ownedFiles` entry naming a directory (`src/`, or an existing
+  `src`) or a glob is refused by `plan validate`, `workflow goal` and
+  `plan revise`; it used to pass and then stop the kernel right after launch.
+  A pinned worker pool that cannot run a step's lane and effort is refused
+  before launch. A new advisory, `requirement-unchecked`, names requirements
+  no step checks.
+- legacy: runs an older version left waiting still accept `plan show` and
+  `plan submit`; `workflow resume` now finishes them with a handback instead
+  of pausing again.
+
 ## 0.29.1 — a revised cancelled run runs its cancelled steps again
 
 - workflow: revising a cancelled run reopened it but left every step the

package/README.md

@@ -43,12 +43,53 @@ version in place (`bullswarm update --check` only reports). Requires Node.js
 22.12 or later. `bullswarm setup` walks through detecting your
 installed agent CLIs, showing their quota state, and writing a routing
 configuration. See
-[Getting started](https://cowcow02.github.io/bullswarm/guide/getting-started/)
+[Getting started](https://bulls-work.github.io/bullswarm/guide/getting-started)
 for integrating Bullswarm's skill into Codex, Claude, and Grok, and for the
 full quick-start command list.
 
+## Claude Mod (early access)
+
+`mods/bullswarm` is the same routing injected into Claude Code's own engine
+as a Claude Mod (a plugin of TypeScript function hooks, behind
+`CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1`): the pool meters drawn above the
+prompt, the pools named in the model's context, Claude's general-purpose
+subagents routed to whichever pool has surplus and answered with the
+verified output, and the verdict appended to every `bullswarm run` the model
+runs. The Mod is the dashboard's read-only counterpart: the same Run, Step and
+Usage pages in the same meter colours, with no edit or install action. See
+[mods/bullswarm/README.md](mods/bullswarm/README.md).
+
+Three ways to load it:
+
+```bash
+# with the CLI: links the mod under ~/.claude/skills and sets the flag in ~/.claude/settings.json
+bullswarm integrate install --agents claude --yes
+
+# from Claude Code's plugin marketplace (a copy that `claude plugin update` refreshes)
+claude plugin marketplace add Bulls-Work/bullswarm
+claude plugin install bullswarm@bullswarm
+
+# one session only, from the installed package
+CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude --plugin-dir "$(npm root -g)/bullswarm/mods/bullswarm"
+```
+
+The marketplace route still needs `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1`, in
+the shell or under `env` in `~/.claude/settings.json`, and the `bullswarm`
+CLI on `PATH`. Pick one route: an installed marketplace copy takes precedence
+over the skills-dir link, and Claude says so at startup.
+
 ## Quick start
 
+Once setup is complete, bare `bullswarm` opens the dashboard on its Home page.
+Use `bullswarm --setup` or `bullswarm setup` to open setup again, and use
+`bullswarm workflow tui` when you want the explicit dashboard command. The
+pages are Home, Run, Step, Usage, and Help. A sticky header and bottom nav
+(`[ 1.<run> ] … [ usage ] [ help ] [ quit ]`, each button's key
+underlined inside its label) carry `q` (quit),
+`h` or `?` (help), `u` (usage), `e` (edit), `i` (install), `l`/`p` (Usage tabs), arrows or
+PgUp/PgDn (scroll), and Enter; click any button, tab, run or step, or use the
+wheel to scroll.
+
 One bounded outcome — a task with a clear finish line:
 
 ```bash
@@ -107,7 +148,7 @@ instead.
   and never retried early.
 
 The full mechanics behind each of these are in
-[Routing](https://cowcow02.github.io/bullswarm/guide/routing/).
+[Routing](https://bulls-work.github.io/bullswarm/guide/routing).
 
 ## What you get back
 
@@ -121,7 +162,7 @@ The full mechanics behind each of these are in
   content still verified; read it before re-running
 
 A non-zero exit from the delegate is never treated as success on its own. See
-[Doctrine](https://cowcow02.github.io/bullswarm/guide/doctrine/) for the full
+[Result envelope](https://bulls-work.github.io/bullswarm/reference/result) for the full
 verdict shape.
 
 A workflow produces a durable, versioned result envelope — a JSON document
@@ -137,29 +178,37 @@ bullswarm workflow runs result <shortId> --json --summary  # compact status once
 the exact flags to keep polling; `runs result --summary` is what to read once
 a run finishes, and `runs result --json` (no `--summary`) gives the full
 envelope for a failed or partial run. See
-[Operations](https://cowcow02.github.io/bullswarm/guide/operations/) for the
+[Observing runs](https://bulls-work.github.io/bullswarm/guide/observing) for the
 full shape of both.
 
 ## Documentation
 
 The full documentation is published at
-[cowcow02.github.io/bullswarm](https://cowcow02.github.io/bullswarm/) once
-GitHub Pages is enabled for this repository (Settings → Pages → deploy from
-branch `main`, folder `/docs`). Until then, the same pages are readable
-directly under [`docs/guide/`](docs/guide/) in this repository.
+[bulls-work.github.io/bullswarm](https://bulls-work.github.io/bullswarm/).
+
+The dashboard is the main screen after setup: bare `bullswarm` opens Home,
+`bullswarm --setup` or `bullswarm setup` opens setup, and
+`bullswarm workflow tui` is the explicit form. The [Observing runs](https://bulls-work.github.io/bullswarm/guide/observing)
+page maps its pages, keys, and mouse controls.
 
 | Page | What it covers |
 |---|---|
-| [Entry points](https://cowcow02.github.io/bullswarm/guide/entry-points/) | `run` vs `workflow goal`, and every top-level verb |
-| [Doctrine](https://cowcow02.github.io/bullswarm/guide/doctrine/) | The non-negotiable rules, and the result verdict shape |
-| [Getting started](https://cowcow02.github.io/bullswarm/guide/getting-started/) | Install, agent integration, quick-start commands |
-| [Strategy](https://cowcow02.github.io/bullswarm/guide/strategy/) | Model/provider configuration, rungs (model plus reasoning level per effort tier), benchmark evidence |
-| [Workflows](https://cowcow02.github.io/bullswarm/guide/workflows/) | Authoring a program, kinds, advisories, plan contract/validate/goal |
-| [Operations](https://cowcow02.github.io/bullswarm/guide/operations/) | Listing/inspecting runs, the result envelope, context diet |
-| [Dashboard](https://cowcow02.github.io/bullswarm/guide/dashboard/) | `workflow watch`, the interactive TUI, terminal glyph fallback |
-| [Repository operations](https://cowcow02.github.io/bullswarm/guide/repository-operations/) | The issue-watcher launchd agent |
-| [Routing](https://cowcow02.github.io/bullswarm/guide/routing/) | How a pool is picked: pace, headroom, urgency, load, quarantine |
-| [Providers](https://cowcow02.github.io/bullswarm/guide/providers/) | Adding your own agent CLI or reseller account as a provider plugin |
+| [Introduction](https://bulls-work.github.io/bullswarm/guide/) | What Bullswarm is, the two entry points, and the four rules it never breaks |
+| [Getting started](https://bulls-work.github.io/bullswarm/guide/getting-started) | Install, `setup`, `doctor`, agent integration, and your first verified run |
+| [Concepts](https://bulls-work.github.io/bullswarm/guide/concepts) | Pools, lanes, surplus, the two windows, verdicts, quarantine, and the run directory |
+| [Run one task](https://bulls-work.github.io/bullswarm/guide/run) | Every `bullswarm run` option, and what each verdict asks you to do |
+| [Workflows](https://bulls-work.github.io/bullswarm/guide/workflows) | Authoring the program `workflow goal` executes: territories, dependencies, integration, acceptance |
+| [Observing runs](https://bulls-work.github.io/bullswarm/guide/observing) | `workflow watch`, the Home/Run/Step/Usage/Help dashboard pages, keys, mouse, and terminal glyphs |
+| [Routing](https://bulls-work.github.io/bullswarm/guide/routing) | How a pool is picked: pace, 5-hour headroom, urgency, load, quarantine |
+| [CLI reference](https://bulls-work.github.io/bullswarm/reference/cli) | Every verb and nested subcommand, with its flags and defaults |
+| [Workflow program](https://bulls-work.github.io/bullswarm/reference/program) | The `bullswarm.workflow.program.v2` document: action fields, kinds, validation rules |
+| [Configuration](https://bulls-work.github.io/bullswarm/reference/configuration) | The Bullswarm home, `state.json`, strategy models and rungs, environment variables |
+| [Providers](https://bulls-work.github.io/bullswarm/reference/providers) | Adding your own agent CLI or reseller account as a provider plugin |
+| [Result envelope](https://bulls-work.github.io/bullswarm/reference/result) | Every field of `run --json` and of the workflow result document |
+| [Claude Code](https://bulls-work.github.io/bullswarm/integrations/claude-code) | The packaged skill, the MCP server, and the read-only Claude Mod counterpart under `mods/bullswarm` |
+| [Codex and Grok](https://bulls-work.github.io/bullswarm/integrations/agent-clis) | What `bullswarm integrate` writes for each agent CLI, and how to check it |
+| [Issue watcher](https://bulls-work.github.io/bullswarm/integrations/issue-watcher) | The launchd agent that triages and fixes new GitHub issues |
+| [Historical notes](https://bulls-work.github.io/bullswarm/notes/) | Working notes, audits, and experiment writeups, kept as records |
 
 ## License