baro-ai 0.18.1 → 0.21.0

package/README.md

@@ -124,21 +124,98 @@ Options:
   --resume                     Resume from existing prd.json (also runs dry-run plans)
   --skip-context               Skip CLAUDE.md auto-generation
   --cwd <path>                 Working directory (default: current)
+  --no-critic                  Disable live Critic (default: on). The Critic
+                               reviews each agent turn against acceptance
+                               criteria via `claude --model haiku` and injects
+                               corrective feedback when the turn doesn't pass.
+  --critic-model <name>        Model for the Critic (default: haiku)
+  --no-librarian               Disable cross-agent runtime memory (default: on)
+  --no-sentry                  Disable file-touch conflict detector (default: on)
+  --no-surgeon                 Disable Surgeon (default: on). The Surgeon
+                               observes terminal story failures and proposes
+                               replans (split / prereq / rewire) so failed
+                               work gets done in a different shape rather
+                               than dropped.
+  --no-surgeon-llm             Use deterministic Surgeon (skip-only) instead
+                               of the LLM-driven replanner. The LLM Surgeon
+                               is on by default; it costs an Opus call per
+                               terminal failure but produces richer replans.
+  --surgeon-model <name>       Model for the Surgeon LLM (default: opus)
   -h, --help                   Print help
 ```
 
+### Phase 2/3/4 observers (Mozaik bus)
+
+baro 0.19+ runs every story through a TypeScript Mozaik orchestrator.
+Stories on the same DAG level run truly in parallel and observers can
+react to one another's bus events:
+
+- **Librarian** (default ON) — when one agent reads a file or runs grep,
+  later agents in the run see the digest in their prompt and skip the
+  redundant exploration. Measurable token savings on multi-story runs.
+- **Sentry** (default ON) — flags overlapping Edit/Write tool calls
+  across concurrent stories.
+- **Critic** (default ON) — Haiku evaluator reviews each agent turn
+  against acceptance criteria; on a fail verdict, an inline corrective
+  message lands as the agent's next turn so it self-corrects before
+  commit. Disable with `--no-critic`.
+- **Surgeon** (default ON, with LLM) — when a story fails its retry
+  budget, the Surgeon asks Opus for a richer replan and emits a
+  ReplanItem the Conductor applies at the next level boundary. The LLM
+  is biased toward keeping the work done — it prefers splitting a too-
+  large story into smaller pieces, inserting a prerequisite, or
+  rewiring dependencies, over dropping outright. A run is reported as
+  successful only when every original story passes; if the Surgeon
+  drops a story without replacement, the run terminates with a clear
+  "did not complete the goal" verdict instead of a green tick. Disable
+  the LLM with `--no-surgeon-llm` to fall back to deterministic
+  skip-only behavior, or `--no-surgeon` to remove adaptive replans
+  entirely.
+
 ## Requirements
 
 - [Claude CLI](https://docs.anthropic.com/en/docs/claude-cli) installed and authenticated
 - macOS (arm64/x64), Linux (x64/arm64), or Windows (x64)
-- Node.js 18+ (only if using `--planner openai`)
+- **Node.js 20+** (orchestrator runtime)
 - `gh` CLI (optional, for automatic PR creation)
 
 > **Windows note:** Windows 10+ is required. For best TUI experience, use [Windows Terminal](https://aka.ms/terminal) or another modern terminal emulator.
 
 ## Architecture
 
-Rust binary distributed via npm. TUI built with ratatui, async execution with tokio, one Claude CLI process per story.
+Rust binary distributed via npm. TUI built with ratatui, async execution
+with tokio. Each `baro` invocation spawns the bundled TypeScript
+[Mozaik](https://github.com/jigjoy-ai/mozaik) orchestrator as a
+subprocess; the orchestrator owns story execution and emits typed
+events into a shared `AgenticEnvironment` bus. Each story is one
+`claude` CLI subprocess (auth inherits from your Claude CLI session —
+no API key needed).
+
+The orchestrator is itself a Mozaik agentic environment: there is no
+imperative `run()` method, no top-level `Promise.all` loop. The
+**Conductor** is a state machine that reacts to typed bus events
+(`RunStartRequest` → `LevelComputeRequest` → `StorySpawnRequest` →
+`StoryResult` → `LevelCompleted` → …). Spawning a story, evaluating a
+turn, and replanning the DAG are all reactions, not steps in a loop.
+
+Ten participants share that bus:
+
+| Participant     | Role                                                              |
+| --------------- | ----------------------------------------------------------------- |
+| `Conductor`     | Orchestration state machine — drives the run by reacting          |
+| `StoryFactory`  | Spawns Story Agents on each `StorySpawnRequest`                   |
+| `StoryAgent`    | Runs one story via Claude CLI, with retries and timeout           |
+| `Librarian`     | Cross-agent memory — indexes outputs of exploration tools         |
+| `Sentry`        | Flags overlapping file writes across concurrent stories           |
+| `Critic`        | Per-turn acceptance-criteria evaluator (opt-in: `--with-critic`)  |
+| `Surgeon`       | Emits DAG replans when a story fails terminally (opt-in: `--with-surgeon`) |
+| `Operator`      | Bridges external user commands (TUI, web UI) into bus events      |
+| `Auditor`       | JSONL log of every event on the bus                               |
+| `Cartographer`  | Translates bus events into UI frames for the Rust TUI             |
+
+The bus is open. New participants — CI deployers, Slack notifiers,
+external ticket triggers — are subscribers and emitters with no changes
+to the orchestrator.
 
 ## License