@robmclarty/volley 0.5.3 → 0.5.4

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## v0.5.4 — 2026-09-25
+
+### Added
+- **A diagram of the loop, drawn from the code.** The README's new "The flow" section shows the real composition: the branch that skips verification once the builder alone crosses the cost cap, the critic's retry-then-tool-less fallback for local models, and the guard that stops the loop. fascicle's `describe.diagram` renders it from `src/flow.ts`, and `pnpm diagram` prints it from a checkout.
+
+### Changed
+- **The trajectory's flow structure includes the builder and the critic.** They now appear as children of `build` and `critique` in the tree a run records at its start, so the fascicle viewer draws both model calls, and the critic's retry and fallback, before the run reaches them. Live output, verdicts, and exit codes are unchanged.
+
+### Internal
+- Built on fascicle 0.12.13. A test holds the `src/flow.ts` header diagram and the README's copy to `describe.diagram`, so neither can drift from the code.
+
 ## v0.5.3 — 2026-09-24
 
 ### Fixed

package/README.md

@@ -88,6 +88,38 @@ workspace filesystem and the critic's feedback. Swap the critic to change what
 the loop optimizes for: `--critic reviewer` (default), `optimizer`,
 `researcher`, or a path to your own system prompt.
 
+### The flow
+
+Under the hood the loop is one [fascicle](https://www.npmjs.com/package/fascicle)
+composition in [`src/flow.ts`](./src/flow.ts), and fascicle's `describe.diagram`
+draws it straight from the code. It shows what the sketch above leaves out: the
+branch that skips verification once the builder alone crosses the cost cap, the
+critic's retry-then-tool-less fallback for local models whose streams die, and
+the guard that decides when the loop stops.
+
+<!-- flow diagram: pnpm diagram -->
+```text
+volley                                loop: one round per iteration, up to max_iterations
+├─ iteration                          sequence
+│  ├─ build                           open the iteration, run the builder, measure the change
+│  │  └─ builder                      model call: one agentic session in the build root
+│  ├─ verify                          branch: did the build alone cross the cost cap?
+│  │  ├─ then  skip_verify            record the check as skipped and call no critic
+│  │  └─ else  sequence
+│  │     ├─ check                     the deterministic gate: checkride, a command, or none
+│  │     └─ critique                  the read-only critic's verdict and feedback
+│  │        └─ critic                 fallback: judge without tools if a local critic's stream keeps dying
+│  │           ├─ retry               one more try after a stream death, local providers only
+│  │           │  └─ critic_tools     model call with read-only workspace tools
+│  │           └─ pipe                mark the verdict degraded
+│  │              └─ critic_toolless  model call judging from the check output and a file list
+│  └─ record                          archive the iteration and rewrite the run summary
+└─ guard  gate                        stop on approval over a green check, the cost cap, or a gate edit
+```
+
+`pnpm diagram` prints the same tree from a checkout. A test holds this copy and
+the one in the `src/flow.ts` header to what the code builds, so neither drifts.
+
 ## Install
 
 Requires Node ≥ 24, pnpm, and the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
@@ -290,7 +322,7 @@ Providers and their setup:
 Install the peer for your provider in the project running volley (e.g.
 `pnpm add ai-sdk-ollama@^4`); fascicle loads it lazily only when the local
 critic actually runs. The major matters: it must satisfy fascicle's declared
-peer range (`^4` for fascicle 0.12.10, which tracks the AI SDK v7 line; a bare
+peer range (`^4` for fascicle 0.12.13, which tracks the AI SDK v7 line; a bare
 `pnpm add ai-sdk-ollama` installs v4, which is exactly what this major wants).
 The Ollama base URL is the **server root** — `ai-sdk-ollama` adds the `/api`
 prefix itself (volley strips a trailing `/api` from `VOLLEY_OLLAMA_URL` for
@@ -485,6 +517,7 @@ pnpm test          # vitest
 pnpm typecheck     # tsc --noEmit
 pnpm check         # checkride — volley dogfoods its own definition of done
 pnpm build         # tsup → dist/
+pnpm diagram       # draw the flow from src/flow.ts with describe.diagram
 ```
 
 Live smoke tests against the real `claude` CLI and real checkride are opt-in:

package/dist/cli.js

@@ -1804,6 +1804,7 @@ function make_builder_step(deps) {
   return model_call({
     engine: deps.engine,
     id: "builder",
+    description: "model call: one agentic session in the build root",
     provider: config.builder_provider,
     model: config.builder_model,
     system: resolve_builder_system(config),
@@ -2045,11 +2046,16 @@ function make_critic_tools_step(deps) {
   return model_call2({
     ...critic_call_config(deps),
     id: "critic_tools",
+    description: "model call with read-only workspace tools",
     ...critic_tool_options(deps.config)
   });
 }
 function make_critic_toolless_step(deps) {
-  return model_call2({ ...critic_call_config(deps), id: "critic_toolless" });
+  return model_call2({
+    ...critic_call_config(deps),
+    id: "critic_toolless",
+    description: "model call judging from the check output and a file list"
+  });
 }
 function critic_retryable(config) {
   return (err) => is_retryable_critic_error(config, err);
@@ -2546,14 +2552,18 @@ function build_critic(deps) {
   const retryable = critic_retryable(deps.config);
   return fallback(
     retry(make_critic_tools_step(deps), {
+      description: "one more try after a stream death, local providers only",
       max_attempts: MAX_CRITIC_RETRIES + 1,
       backoff_ms: 0,
       when: retryable,
       project: with_retries
     }),
-    pipe(make_critic_toolless_step(deps), as_degraded),
+    pipe(make_critic_toolless_step(deps), as_degraded, {
+      description: "mark the verdict degraded"
+    }),
     {
       name: "critic",
+      description: "judge without tools if a local critic's stream keeps dying",
       when: retryable,
       handoff: (prompt) => toolless_critic_prompt(deps.config, prompt),
       project: with_fallback_cause
@@ -2569,13 +2579,27 @@ function build_flow(deps, resume_from) {
     bash_executor: deps.bash_executor
   });
   const critic = build_critic({ engine: deps.engine, config, on_chunk: renderer.critic_chunk });
-  const build = step("build", (s, ctx) => build_phase(deps, builder, s, ctx));
-  const skip_verify = step("skip_verify", (s) => skip_verify_phase(deps, s));
-  const check = step("check", (s, ctx) => check_phase(deps, s, ctx));
-  const critique = step("critique", (s, ctx) => critique_phase(deps, critic, s, ctx));
-  const record = step("record", (s) => record_phase(deps, s));
+  const build = step("build", (s, ctx) => build_phase(deps, builder, s, ctx), {
+    description: "open the iteration, run the builder, measure the change",
+    arm: builder
+  });
+  const skip_verify = step("skip_verify", (s) => skip_verify_phase(deps, s), {
+    description: "record the check as skipped and call no critic"
+  });
+  const check = step("check", (s, ctx) => check_phase(deps, s, ctx), {
+    description: "the deterministic gate: checkride, a command, or none"
+  });
+  const critique = step(
+    "critique",
+    (s, ctx) => critique_phase(deps, critic, s, ctx),
+    { description: "the read-only critic's verdict and feedback", arm: critic }
+  );
+  const record = step("record", (s) => record_phase(deps, s), {
+    description: "archive the iteration and rewrite the run summary"
+  });
   const verify = branch({
     name: "verify",
+    description: "did the build alone cross the cost cap?",
     when: (s) => cost_cap_hit(config, s),
     // fascicle names this arm `then`. It holds a Step object, never a function,
     // so nothing can mistake the config for a thenable.
@@ -2588,9 +2612,12 @@ function build_flow(deps, resume_from) {
   });
   return loop({
     name: "volley",
+    description: "one round per iteration, up to max_iterations",
     init: (input) => input.resume_from ?? initial_state(),
     body: iteration,
-    guard: step("gate", (s) => gate(config, s)),
+    guard: step("gate", (s) => gate(config, s), {
+      description: "stop on approval over a green check, the cost cap, or a gate edit"
+    }),
     finish: (s, { converged }) => ({ value: s, converged }),
     max_rounds: remaining_iterations(config, resume_from)
   });