flow-workflows 0.64.0 → 0.65.0-rc.2

package/README.md

@@ -229,13 +229,47 @@ usable on real work.
 
 ## Token budget
 
-- The shared rules live in the `flow-core` skill, loaded once per session; a command file carries only its phase.
-- Every phase reads `meta.json` and `00-summary.md` first and opens a full artifact only on demand.
-- `quality.review_depth: light` runs only the base code-review — no panel, reinforcements or skeptics.
-- The review tier scales to the **diff under review**, not the size of the feature: a 40-line MR/PR in an L-sized work is reviewed as the 40 lines it is.
-- Two ceilings, both counting agents rather than findings: `agents.fanout_max` per parallel round (default 4) and `agents.budget_max` for everything one command run launches (default 12). Each command declares which phase it gives up first, and what a ceiling drops is reported.
-- The review output prints its cost as `spent/budget`: subagents launched, tier, effort, and every phase the ceiling skipped.
-- Which is why nothing here ever asks you to `/compact`: the phase boundary already is the compaction point, and it is selective, on disk and reversible. → [PHILOSOPHY](docs/PHILOSOPHY.md#nothing-here-asks-you-to-compact)
+**A phase costs `turns × context`, plus what it writes.** The API keeps no state, so every tool call
+resends the whole conversation: a 40-turn `build` carrying 70k of context pays for those 70k forty
+times, even though the window never grows past 70k. Prompt caching makes the resent part roughly ten
+times cheaper, which is why the number that matters is *turns*, not the size of a command file. Every
+design decision below follows from that one line.
+
+- **Fewer turns per phase.** The shared rules live in the `flow-core` skill, loaded once per session;
+  a command file carries only its phase. Every phase reads `meta.json` and `00-summary.md` first and
+  opens a full artifact only on demand — a handoff read in one turn instead of rediscovered in ten.
+- **Fewer agents, declared in advance.** Two ceilings, both counting agents rather than findings:
+  `agents.fanout_max` per parallel round (default 4) and `agents.budget_max` for everything one
+  command run launches (default 12). Each command declares which phase it gives up first, and what a
+  ceiling drops is reported.
+- **A tier that matches the diff, not the ticket.** The review scales to the **diff under review**: a
+  40-line MR/PR inside an L-sized work is reviewed as the 40 lines it is.
+- **Bounded output.** Output tokens are the most expensive kind and are never cached.
+  `agents.report_max_words` (default 250) is a cost ceiling as much as a format rule.
+- **The cost is printed.** `review` reports `spent/budget` — subagents launched, tier, effort, and
+  every phase the ceiling skipped.
+
+### When it costs too much
+
+Ordered by effect. Each is one line in `FLOW.md`:
+
+| Change | What it drops | What you lose |
+|---|---|---|
+| `models.agents` / `models.workers` to a cheaper tier | Subagents stop running on the thread's model | Little: a subagent reads a diff and reports ≤250 words |
+| `quality.review_depth: light` | The panel, the reinforcements, the skeptic fan-out | Depth on everything but the built-in reviewer; a sensitive surface still bumps back up |
+| `agents.budget_max`, `agents.fanout_max` | Rounds past the ceiling, in the order each command declares | Coverage — but named coverage: what a ceiling skipped is reported, never silently dropped |
+| `agents.report_max_words` | Output length per subagent | Detail in reports, not findings |
+
+**Two things that cost real money and look free.** The first: a cache entry expires, so a phase run
+in one sitting is cheaper than the same phase spread across an afternoon — coming back after a long
+pause, the next turn repays the whole prefix at write price. The second: `/compact` is not a saving.
+It rewrites the history the provider has already priced and stored, so the turn after it pays for
+everything again. Nothing here ever asks you to compact, because the phase boundary already is the
+compaction point — selective, on disk and reversible.
+→ [PHILOSOPHY](docs/PHILOSOPHY.md#nothing-here-asks-you-to-compact)
+
+Cost figures in these docs are estimates, not measurements: the flow reports how many agents a
+command launched, not how many tokens they spent.
 
 ## Other harnesses
 
@@ -300,9 +334,10 @@ python3 script/adapter-smoke.py      # also runs install.sh against a throwaway
 bash script/tests/push-guard.sh      # the push guard's cases
 bash script/tests/notify-update.sh   # the update-notice hook's cases
 bash script/tests/session-start.sh   # the where-you-left-off hook's cases
+bash script/tests/review-unwrap.sh   # the answer shapes `flow review` has to unwrap
 ```
 
-CI runs the same five on every PR. The preflight refuses what has shipped broken before: an empty tracked file, unparsable JSON or TOML, a manifest version out of step with `CHANGELOG.md`, a hook without its executable bit, a stale or unusable mirror. → [RELEASING](RELEASING.md)
+CI runs the same six on every PR. The preflight refuses what has shipped broken before: an empty tracked file, unparsable JSON or TOML, a manifest version out of step with `CHANGELOG.md`, a hook without its executable bit, a stale or unusable mirror. → [RELEASING](RELEASING.md)
 
 ## What it does not ship (on purpose)
 

package/adapters/codex/CORE.md

@@ -17,6 +17,14 @@ Every `$flow-*` command assumes these rules. They are stated once, here, so a co
 carries what is specific to its phase. Read this once per session; a command that says "load
 `flow-core`" means this file.
 
+**This file belongs to flow `0.65.0-rc.2`.** Compare it once, at the start of the session, against
+`version` in `~/.claude/flow/.claude-plugin/plugin.json`. The two differing means the session
+is running a **mixture** — the commands from one copy of the plugin, these shared rules from another
+— which is exactly what happens when a branch or a release candidate is loaded over an installed
+copy that stays enabled: the harness resolves a command from the one and a skill from the other,
+silently. Name both numbers at the first stop and say which half is which; a rule this file adds and
+a command relies on is simply absent in that session, and nothing else will report it.
+
 ## 0. Effective FLOW config — base plus harness overlay
 
 - Read `FLOW.md` at the repo root as the base, then the optional overlay for the harness running
@@ -235,6 +243,15 @@ about to type into the chat is a panel write instead** (§3):
 - **When:** (a) in pre-flight, as soon as `meta.json` is loaded; (b) immediately **before** every stop header; (c) **before** any long stretch (fan-out, full suite, CI poll) — never after, so a step that dies halfway is not shown as finished. When the stretch will outlast the ~30 min staleness warning, set `stale_after_minutes` to what it will really take; (d) wherever `## Close` updates `meta.json`.
 - **Rules:** `phase` is the phase you are **running now** (not `meta.json.phase`, which advances only at Close). `header: true` means ticket, type, phase and age are drawn by the reader — do not repeat them in `lines`. Keep it under ~14 lines. Every fact from `meta.json` and the artifacts — an invented MR/PR state is worse than a blank panel. `updated_at` from the real clock (`date -Iseconds`), never carried over. Write in the language of the work's artifacts. No work folder (lightweight `respond`/`green`) → nothing to write.
 
+### `meta.json.cost[]` — what a phase measured, when it could
+
+A phase that can measure what it spent appends one entry: `{ "phase": "review", "at": "<ISO>",
+"reviewers": 8, "usd": 0.0124, "source": "harness" }`. `flow review --record` writes it; `flow cost`
+reads it back per phase. Two rules, and they are the reason the block is worth having: a harness
+that reports no figure is recorded with `"source": "not reported"` rather than estimated, and a
+phase with no entry measured nothing — **absence is not zero**. Every figure is the harness's own
+client-side estimate and can differ from a bill.
+
 ## 5. Work summary — `00-summary.md`
 
 Each phase reads what the previous ones wrote. Reading every artifact whole on every phase is the
@@ -466,7 +483,7 @@ not `declined`/`logged`/`done`: a work being finished is precisely when its defe
 
 Mid-phase, the user corrects you. *«We don't put that in a listener here, use a message handler.»*
 *«Never mock the repository in that layer.»* *«The test command is `make test-unit`, not
-`bin/phpunit`.»* *«Stop proposing a DTO for that, we pass the entity.»* You comply, the phase closes,
+`bin/test`.»* *«Stop proposing a DTO for that, we pass the entity.»* You comply, the phase closes,
 and the next work on the same repo proposes the same thing again. The place for these exists —
 `FLOW.md`'s `conventions` and `quality` — and nothing on the path from the correction to that file is
 automatic: the user has to notice they have said it three times and go and edit it.

package/adapters/codex/skills/flow-bug-review/SKILL.md

@@ -28,6 +28,33 @@ Read `~/.claude/flow/CORE.codex.md` first (shared rules: `FLOW.md` step 0, model
 - **A premise left open by `fix` §2.2 is an input to this review, not a note.** Every row of "Premises the fix depends on" whose verdict is `unsettled` enters §5 as an **ambiguous finding** and is named in §7 whether or not that gate opened — in a bug it is usually the claim that the root cause was the whole cause, which is exactly what the regression test cannot prove.
 - Require `fix` in `phases_done`; for `size` ≥ S also require `validate`.
 - `git diff` shows no changes → warn and stop.
+- **Gather the material once, not once per reviewer.** `npx flow-workflows@<version> bundle --checks`
+  prints one context pack for this branch — worklist, the diff (minus `git.diff_exclude`), the changed files
+  in full, the raw output of `quality.static_analysis`, and the work's handoff — in a single call.
+  Read that instead of rediscovering it, and **pass it to the briefs of §2-§5**: a panel where every
+  member runs its own `git diff` and opens the same files pays for that material once per agent, and
+  a reviewer that spends its turns exploring has fewer left to review. **Any non-zero exit is a
+  fallback, not a failure** — no CLI on the machine, a base that does not resolve, a network that
+  cannot reach it: read the diff from git as before and carry on, once, without retrying variants.
+  What is not optional is the `Review path` line of §7: a round that skipped the pack and one that
+  used it are indistinguishable from the artifact otherwise, which is how a phase quietly stops
+  paying for itself.
+- **`<version>` is this plugin's own, in every `flow-workflows` call on this page.** Read it once
+  from `version` in `~/.claude/flow/.claude-plugin/plugin.json` and substitute it. Left
+  unpinned, the fetcher resolves whatever the registry calls newest, which while a release candidate
+  is under test is the **previous** release: the page then describes subcommands and flags the CLI
+  that actually runs does not carry, every call exits non-zero, and the round takes the documented
+  fallback for a reason nobody can see. The version the plugin asks for and the version that answers
+  are the same number by construction, or the `Review path` line of §8 says which one failed.
+- **`agents.exec_cmd` set → the panel runs from the CLI.** Not a choice to weigh: run
+  `npx flow-workflows@<version> review`, which spawns that command once per role over the pack above — **one
+  turn each instead of an agentic loop each** — and returns the findings already deduplicated, with
+  the reviewers it dropped for `agents.budget_max` named. Exactly three things send the round to the
+  agentic panel below: the key is empty (the default — nothing changes without it), the CLI is
+  unavailable by the rule above, or **every** role came back empty, which is a broken `exec_cmd` and
+  not a clean diff. Whichever happened is named in §7. When the CLI runs the panel, that command
+  picks the model, so `models.agents`/`models.workers` do not reach those reviewers. A one-shot sweep
+  cannot pull a thread, so an ambiguous finding still goes to a real agent with tools, as below.
 
 ## 2. Run the code reviews
 
@@ -132,7 +159,9 @@ Cost line: count every subagent this command launched — reviewers = §2.1 buil
 - Review tier: <light | full | proportional — which reviewers ran, at what built-in effort (medium/high/xhigh/max), and why, per §2.0>
 - Agents launched: <ran vs defined — `N/M` of the `review_skill`/`reviewers` roster, naming any that did not run (with the reason) and any substitution; "built-in only" if §2.0 selected no panel>
 - Cost: <n>/<budget_max> subagents launched (<k> reviewers · <m> reinforcements · <s> skeptics), tier <light|proportional|full>
+- Measured cost: <what the harness reported for this round, when it reported anything — `flow review --record` writes it to `meta.json.cost[]` and `$flow-work-status` and `flow cost` read it back. A harness that reports no figure is recorded as "not reported": the subagent count above is a headcount, not a cost, and a guess is worse than a gap.>
 - Effective size: <diff size (N changed lines) vs `meta.json.size`, which the tier used, and — when the diff landed within 10% under a tier threshold — that fact (§2.0)>
+- Review path: <the two paths this round actually took: `flow bundle` or git for the material, `flow review` or the agentic panel for the reviewers — each with the reason when it was the fallback (no CLI, non-zero exit, `agents.exec_cmd` empty, every role empty). Without this line a round that skipped the CLI reads exactly like one that used it.>
 - Agent models: <the value of `models.workers`/`models.agents` when set; otherwise "inherited from this thread"; agents named in `agents.<role>` keep their own definition's model>
 - Defaults used: <every empty `FLOW.md` key this round resolved with its default — one per line as `key → default` — or "none". In `guided`/`auto` each is also an entry in `meta.json.defaults_used[]` (flow-core §0); in `manual` the phase may offer one of them at its stop.>
 - Skipped for budget: <phases dropped by §2.0's give-up order, or "none">

package/adapters/codex/skills/flow-doctor/SKILL.md

@@ -89,6 +89,10 @@ workers  (empty)  →  fan-out rounds — falls back to `agents`
   handoff; nothing enforces it.
 - One line: a role set in `agents.*` keeps its own agent definition's model, so a round can mix
   configured and self-declared models.
+- **`agents.exec_cmd` set → say so here, next to the models it makes inert.** That command picks the
+  model for the review round it runs, so neither key reaches those reviewers while every other phase
+  still resolves them normally. A key that silently does nothing is worse than one that is absent,
+  and this is the only place a reader finds out.
 
 #### 1.5.3 Defaults that keep being used
 
@@ -221,6 +225,23 @@ refuse) · **degraded** (it runs, quietly worse than the config promises), plus
   a non-negative integer (`0` = no ceiling; else the default `12` applies). Report both effective
   numbers with the count of panel members `quality.review_skill`/`quality.reviewers` defines, so
   the widest command's cost is visible before it is paid, not after.
+- **The `flow-workflows` CLI, which `review` reaches for before it composes a panel**:
+  `npx flow-workflows@<version> --version` answers, with `<version>` read from `version` in
+  `~/.claude/flow/.claude-plugin/plugin.json` — the same pin `review` uses, so the number that
+  answers cannot be behind the plugin's. Unreachable — no node, no network, a machine that installs
+  nothing — is **not** a failure: say so in one line, and that the review falls back to reading the
+  diff from git, paying for that material once per reviewer. What this check catches is a pin that
+  **cannot be fetched at all**: a candidate withdrawn from the registry, or a plugin loaded from a
+  branch whose version was never published, where every `flow-workflows` call will fail for the whole
+  session. Report the version asked for and what came back. This is the only check here about
+  something no install step of ours puts on the machine.
+- **The plugin is one copy, not two.** The version in `~/.claude/flow/.claude-plugin/plugin.json`
+  and the one the loaded `flow-core` states (its opening lines) are the same number. They differ →
+  this session resolves its commands from one copy of the plugin and its shared rules from another,
+  which is what loading a branch or a candidate over an installed copy does when the installed one is
+  left enabled. Name both numbers and the fix: disable the installed plugin for the session, or stop
+  loading the second copy. A mixture is worth a `warn` rather than a `fail` — everything still runs,
+  which is precisely why it goes unnoticed.
 - The `flow-core` skill file exists under the plugin root: `~/.claude/flow/CORE.codex.md`.
   Missing → every phase command runs without its shared rules; fix: reinstall or update the plugin.
 

package/adapters/codex/skills/flow-feat-review/SKILL.md

@@ -28,6 +28,33 @@ Mandatory review phase. **`$flow-feat-ship` cannot run without passing through h
 - **A premise left open by `build` §2.1bis is an input to this review, not a note.** Every row of "Premises the change depends on" whose verdict is `unsettled` enters §6 as an **ambiguous finding** (it rests, by construction, on code outside the diff) and is named in §7 whether or not the gate opened. A premise the build could not settle and the review does not mention is one the MR/PR ships as a fact.
 - Require `build` in `phases_done`. **In a multi-MR/PR work** (`meta.json.mrs` has >1 entry) require `build` in the **current `in_progress` MR/PR's** own `phases_done` (its `mrs[]` entry) — a previous MR/PR's `build` does not count. If missing, send the user to `$flow-feat-build` and stop.
 - Check that `git diff` has real changes. None → warn and stop.
+- **Gather the material once, not once per reviewer.** `npx flow-workflows@<version> bundle --checks`
+  prints one context pack for this branch — worklist, the diff (minus `git.diff_exclude`), the changed files
+  in full, the raw output of `quality.static_analysis`, and the work's handoff — in a single call.
+  Read that instead of rediscovering it, and **pass it to the briefs of §2-§6**: a panel where every
+  member runs its own `git diff` and opens the same files pays for that material once per agent, and
+  a reviewer that spends its turns exploring has fewer left to review. **Any non-zero exit is a
+  fallback, not a failure** — no CLI on the machine, a base that does not resolve, a network that
+  cannot reach it: read the diff from git as before and carry on, once, without retrying variants.
+  What is not optional is the `Review path` line of §8: a round that skipped the pack and one that
+  used it are indistinguishable from the artifact otherwise, which is how a phase quietly stops
+  paying for itself.
+- **`<version>` is this plugin's own, in every `flow-workflows` call on this page.** Read it once
+  from `version` in `~/.claude/flow/.claude-plugin/plugin.json` and substitute it. Left
+  unpinned, the fetcher resolves whatever the registry calls newest, which while a release candidate
+  is under test is the **previous** release: the page then describes subcommands and flags the CLI
+  that actually runs does not carry, every call exits non-zero, and the round takes the documented
+  fallback for a reason nobody can see. The version the plugin asks for and the version that answers
+  are the same number by construction, or the `Review path` line of §8 says which one failed.
+- **`agents.exec_cmd` set → the panel runs from the CLI.** Not a choice to weigh: run
+  `npx flow-workflows@<version> review`, which spawns that command once per role over the pack above — **one
+  turn each instead of an agentic loop each** — and returns the findings already deduplicated, with
+  the reviewers it dropped for `agents.budget_max` named. Exactly three things send the round to the
+  agentic panel below: the key is empty (the default — nothing changes without it), the CLI is
+  unavailable by the rule above, or **every** role came back empty, which is a broken `exec_cmd` and
+  not a clean diff. Whichever happened is named in §8. When the CLI runs the panel, that command
+  picks the model, so `models.agents`/`models.workers` do not reach those reviewers. A one-shot sweep
+  cannot pull a thread, so an ambiguous finding still goes to a real agent with tools, as below.
 
 ## 2. Invoke the code reviews
 
@@ -282,8 +309,10 @@ Write `.claude/work/<TICKET>/06-review.md`. The `Cost:` line of `## Summary` is
 ## Summary
 - Review tier: <full | proportional | light — which reviewers ran, at what built-in effort (medium/high/xhigh/max), and why, per §2.0>
 - Effective size: <diff size (N changed lines) vs `meta.json.size`, which of the two the tier used, and — when the diff pointed higher — that the work may be misclassified. When the diff landed within 10% under a tier threshold, say so here (§2.0).>
+- Review path: <the two paths this round actually took: `flow bundle` or git for the material, `flow review` or the agentic panel for the reviewers — each with the reason when it was the fallback (no CLI, non-zero exit, `agents.exec_cmd` empty, every role empty). Without this line a round that skipped the CLI reads exactly like one that used it.>
 - Agent models: <the value of `models.workers`/`models.agents` when set; otherwise "inherited from this thread" — plus, when the panel ran, that agents named in `agents.<role>` kept the model their own definition sets. The values as they are, no judgement on them>
 - Cost: <n>/<budget_max> subagents launched (<k> reviewers · <m> reinforcements · <s> skeptics), tier <light|proportional|full>, effort <medium|high|xhigh|max>
+- Measured cost: <what the harness reported for this round, when it reported anything — `flow review --record` writes it to `meta.json.cost[]` and `$flow-work-status` and `flow cost` read it back. A harness that reports no figure is recorded as "not reported": the subagent count above is a headcount, not a cost, and a guess is worse than a gap.>
 - Agents launched: <ran vs defined — `N/M` of the `review_skill`/`reviewers` roster, naming any that did not run (with the reason) and any substitution; "built-in only" if §2.0 selected no panel>
 - Completeness rounds (M/L): N
 - Critical findings (block ship): N

package/adapters/codex/skills/flow-init/SKILL.md

@@ -44,6 +44,10 @@ editing. This is an optional migration, not part of a normal update.
 
 ## 2. Auto-detection (do NOT ask about what you can infer)
 
+<!-- stack-detection:start — the one place in this plugin that may name an
+     ecosystem's tools. Recognising eleven stacks is not depending on one;
+     outside these markers a tool name belongs in a FLOW.md key. -->
+
 Run, deduce, show what was found for confirmation or correction:
 
 - **Git host and CLI** — from `git remote -v`:
@@ -53,6 +57,10 @@ Run, deduce, show what was found for confirmation or correction:
   - Unknown domain (self-hosted) → ask which host (GitLab/Gitea/other) and which CLI.
   - Installed CLIs: `command -v gh glab tea az`.
 - **Base branch** — `git symbolic-ref refs/remotes/origin/HEAD` (or `git remote show origin`): `origin/main` or `origin/master` → `git.default_base`.
+- **Generated files** — the lock, build and generated-migration paths this repo tracks, from what the
+  ecosystem markers above imply plus what `git ls-files` shows at the root → propose `git.diff_exclude`.
+  These cost context in every phase that opens the diff and buy nothing: nobody reviews a lockfile.
+  Nothing tracked that matches → leave the key out.
 - **Quality commands** — propose what the repo has (empty if nothing found):
   - `Makefile` → targets `test`, `lint`, `phpstan`/`stan`, `cs-fixer`/`fmt`, `database`/`migrate`.
   - `package.json` → `scripts` (test, lint, build, typecheck).
@@ -67,6 +75,8 @@ Run, deduce, show what was found for confirmation or correction:
 - **Data access** (`data.*`, all optional) — only if the repo talks to a database. Find the client and the local stack (a `docker-compose.yml` service, a `DATABASE_URL`/`DB_*` env var, a `Makefile` target that opens a shell). Propose `data.explain_cmd` and `data.schema_cmd` in the engine's dialect against the **development** database — MySQL over Docker Compose: `docker compose exec -T <db-service> mysql <db> -e "EXPLAIN {QUERY}"` and `… -e "SHOW CREATE TABLE {TABLE}"`; PostgreSQL: `psql -c "EXPLAIN (ANALYZE, BUFFERS) {QUERY}"` / `\d+ {TABLE}`. Leave `sandbox_cmd`/`seed_cmd`/`volumes` empty unless the user has something ready. Nothing detected → leave the section out (the query duel degrades to schema-only and says so).
 - **Knowledge sources** (`knowledge.*`) — look at the MCP tools exposed in this session: `mcp__domain-memory__*` → propose `search: mcp__domain-memory__search_knowledge`, `stage: mcp__domain-memory__stage_finding`, `read_staging: mcp__domain-memory__read_staging`, `save: mcp__domain-memory__save_knowledge`; any other tool whose name says search / query / knowledge / memory / graph (e.g. `mcp__codegraph__*`) → propose it as an additional `search` entry, roles it cannot fill left empty. A `docs/adr` or similar folder with no MCP → propose `search: rg -n -i "{QUERY}" docs/adr`. Nothing found → leave the section out. MCP and harness tool names detected in this session belong in the active overlay; a plain repo command such as the `rg` example belongs in `FLOW.md`.
 
+<!-- stack-detection:end -->
+
 ## 3. Ask five things
 
 Everything §2 detected is shown **in one screen** for confirmation or correction — host, base

package/adapters/codex/skills/flow-work-status/SKILL.md

@@ -40,12 +40,14 @@ Overview of works in progress; detects divergences between artifacts and actual
   MR/PRs:      2/4 merged · MR/PR #3 in_progress · MR/PR #4 pending
   Cross-repo:  <meta.related_repos entries not "done", as "repo: scope">   (line only if any)
   Follow-ups:  2 awaiting a decision · 1 accepted, not started            (line only if any)
+  Cost:        $0.71 measured over 2 phases · 1 phase not reported        (line only if any)
   Next:        <suggested next command>
 ```
 
 - "MR"/"PR" from `git.host` (`gitlab` → MR, every other host → PR); no host → "MR/PR".
 - `Cross-repo:` only when `meta.json.related_repos` has entries not `done`: each as `<repo>: <scope>`, appending ` — contract not handed over` when that entry's `contract_handoff` is `pending`. It flags that a **sibling repo still has a pending part**; flow never scans or touches the other repo.
 - `Follow-ups:` only when `meta.json.followups[]` has entries not `declined`/`logged`/`done` (flow-core §7): count the `proposed` ones as *awaiting a decision* and the `accepted` ones without a `work` as *accepted, not started*, naming the ticket id when there is one. `in_progress` entries are already visible as their own work — do not double-count them.
+- `Cost:` only when `meta.json.cost[]` has entries (flow-core §4): sum the `usd` figures that are there, count the phases behind them, and count separately the entries whose `source` is `not reported`. A work with no entries shows **no line at all** — absence is not zero, and a `$0.00` under a work nobody measured is the one output that would make the block worth ignoring. The figures are the harness's own client-side estimates, not a bill; `flow cost` prints the same data phase by phase.
 - `MR/PRs:` only when `meta.json.mrs` exists with >0 entries:
   - Summary: `<merged>/<total> merged`.
   - `closed` or `superseded` MR/PRs present → add to the count: `2/4 merged · 1 closed · 1 pending`.

package/adapters/gemini/CORE.md

@@ -16,6 +16,14 @@ Every `/flow:*` command assumes these rules. They are stated once, here, so a co
 carries what is specific to its phase. Read this once per session; a command that says "load
 `flow-core`" means this file.
 
+**This file belongs to flow `0.65.0-rc.2`.** Compare it once, at the start of the session, against
+`version` in `~/.claude/flow/.claude-plugin/plugin.json`. The two differing means the session
+is running a **mixture** — the commands from one copy of the plugin, these shared rules from another
+— which is exactly what happens when a branch or a release candidate is loaded over an installed
+copy that stays enabled: the harness resolves a command from the one and a skill from the other,
+silently. Name both numbers at the first stop and say which half is which; a rule this file adds and
+a command relies on is simply absent in that session, and nothing else will report it.
+
 ## 0. Effective FLOW config — base plus harness overlay
 
 - Read `FLOW.md` at the repo root as the base, then the optional overlay for the harness running
@@ -234,6 +242,15 @@ about to type into the chat is a panel write instead** (§3):
 - **When:** (a) in pre-flight, as soon as `meta.json` is loaded; (b) immediately **before** every stop header; (c) **before** any long stretch (fan-out, full suite, CI poll) — never after, so a step that dies halfway is not shown as finished. When the stretch will outlast the ~30 min staleness warning, set `stale_after_minutes` to what it will really take; (d) wherever `## Close` updates `meta.json`.
 - **Rules:** `phase` is the phase you are **running now** (not `meta.json.phase`, which advances only at Close). `header: true` means ticket, type, phase and age are drawn by the reader — do not repeat them in `lines`. Keep it under ~14 lines. Every fact from `meta.json` and the artifacts — an invented MR/PR state is worse than a blank panel. `updated_at` from the real clock (`date -Iseconds`), never carried over. Write in the language of the work's artifacts. No work folder (lightweight `respond`/`green`) → nothing to write.
 
+### `meta.json.cost[]` — what a phase measured, when it could
+
+A phase that can measure what it spent appends one entry: `{ "phase": "review", "at": "<ISO>",
+"reviewers": 8, "usd": 0.0124, "source": "harness" }`. `flow review --record` writes it; `flow cost`
+reads it back per phase. Two rules, and they are the reason the block is worth having: a harness
+that reports no figure is recorded with `"source": "not reported"` rather than estimated, and a
+phase with no entry measured nothing — **absence is not zero**. Every figure is the harness's own
+client-side estimate and can differ from a bill.
+
 ## 5. Work summary — `00-summary.md`
 
 Each phase reads what the previous ones wrote. Reading every artifact whole on every phase is the
@@ -465,7 +482,7 @@ not `declined`/`logged`/`done`: a work being finished is precisely when its defe
 
 Mid-phase, the user corrects you. *«We don't put that in a listener here, use a message handler.»*
 *«Never mock the repository in that layer.»* *«The test command is `make test-unit`, not
-`bin/phpunit`.»* *«Stop proposing a DTO for that, we pass the entity.»* You comply, the phase closes,
+`bin/test`.»* *«Stop proposing a DTO for that, we pass the entity.»* You comply, the phase closes,
 and the next work on the same repo proposes the same thing again. The place for these exists —
 `FLOW.md`'s `conventions` and `quality` — and nothing on the path from the correction to that file is
 automatic: the user has to notice they have said it three times and go and edit it.

package/adapters/gemini/commands/flow/bug/review.toml

@@ -24,6 +24,33 @@ Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, mode
 - **A premise left open by `fix` §2.2 is an input to this review, not a note.** Every row of "Premises the fix depends on" whose verdict is `unsettled` enters §5 as an **ambiguous finding** and is named in §7 whether or not that gate opened — in a bug it is usually the claim that the root cause was the whole cause, which is exactly what the regression test cannot prove.
 - Require `fix` in `phases_done`; for `size` ≥ S also require `validate`.
 - `git diff` shows no changes → warn and stop.
+- **Gather the material once, not once per reviewer.** `npx flow-workflows@<version> bundle --checks`
+  prints one context pack for this branch — worklist, the diff (minus `git.diff_exclude`), the changed files
+  in full, the raw output of `quality.static_analysis`, and the work's handoff — in a single call.
+  Read that instead of rediscovering it, and **pass it to the briefs of §2-§5**: a panel where every
+  member runs its own `git diff` and opens the same files pays for that material once per agent, and
+  a reviewer that spends its turns exploring has fewer left to review. **Any non-zero exit is a
+  fallback, not a failure** — no CLI on the machine, a base that does not resolve, a network that
+  cannot reach it: read the diff from git as before and carry on, once, without retrying variants.
+  What is not optional is the `Review path` line of §7: a round that skipped the pack and one that
+  used it are indistinguishable from the artifact otherwise, which is how a phase quietly stops
+  paying for itself.
+- **`<version>` is this plugin's own, in every `flow-workflows` call on this page.** Read it once
+  from `version` in `~/.claude/flow/.claude-plugin/plugin.json` and substitute it. Left
+  unpinned, the fetcher resolves whatever the registry calls newest, which while a release candidate
+  is under test is the **previous** release: the page then describes subcommands and flags the CLI
+  that actually runs does not carry, every call exits non-zero, and the round takes the documented
+  fallback for a reason nobody can see. The version the plugin asks for and the version that answers
+  are the same number by construction, or the `Review path` line of §8 says which one failed.
+- **`agents.exec_cmd` set → the panel runs from the CLI.** Not a choice to weigh: run
+  `npx flow-workflows@<version> review`, which spawns that command once per role over the pack above — **one
+  turn each instead of an agentic loop each** — and returns the findings already deduplicated, with
+  the reviewers it dropped for `agents.budget_max` named. Exactly three things send the round to the
+  agentic panel below: the key is empty (the default — nothing changes without it), the CLI is
+  unavailable by the rule above, or **every** role came back empty, which is a broken `exec_cmd` and
+  not a clean diff. Whichever happened is named in §7. When the CLI runs the panel, that command
+  picks the model, so `models.agents`/`models.workers` do not reach those reviewers. A one-shot sweep
+  cannot pull a thread, so an ambiguous finding still goes to a real agent with tools, as below.
 
 ## 2. Run the code reviews
 
@@ -128,7 +155,9 @@ Cost line: count every subagent this command launched — reviewers = §2.1 buil
 - Review tier: <light | full | proportional — which reviewers ran, at what built-in effort (medium/high/xhigh/max), and why, per §2.0>
 - Agents launched: <ran vs defined — `N/M` of the `review_skill`/`reviewers` roster, naming any that did not run (with the reason) and any substitution; "built-in only" if §2.0 selected no panel>
 - Cost: <n>/<budget_max> subagents launched (<k> reviewers · <m> reinforcements · <s> skeptics), tier <light|proportional|full>
+- Measured cost: <what the harness reported for this round, when it reported anything — `flow review --record` writes it to `meta.json.cost[]` and `/flow:work:status` and `flow cost` read it back. A harness that reports no figure is recorded as "not reported": the subagent count above is a headcount, not a cost, and a guess is worse than a gap.>
 - Effective size: <diff size (N changed lines) vs `meta.json.size`, which the tier used, and — when the diff landed within 10% under a tier threshold — that fact (§2.0)>
+- Review path: <the two paths this round actually took: `flow bundle` or git for the material, `flow review` or the agentic panel for the reviewers — each with the reason when it was the fallback (no CLI, non-zero exit, `agents.exec_cmd` empty, every role empty). Without this line a round that skipped the CLI reads exactly like one that used it.>
 - Agent models: <the value of `models.workers`/`models.agents` when set; otherwise "inherited from this thread"; agents named in `agents.<role>` keep their own definition's model>
 - Defaults used: <every empty `FLOW.md` key this round resolved with its default — one per line as `key → default` — or "none". In `guided`/`auto` each is also an entry in `meta.json.defaults_used[]` (flow-core §0); in `manual` the phase may offer one of them at its stop.>
 - Skipped for budget: <phases dropped by §2.0's give-up order, or "none">

package/adapters/gemini/commands/flow/doctor.toml

@@ -85,6 +85,10 @@ workers  (empty)  →  fan-out rounds — falls back to `agents`
   handoff; nothing enforces it.
 - One line: a role set in `agents.*` keeps its own agent definition's model, so a round can mix
   configured and self-declared models.
+- **`agents.exec_cmd` set → say so here, next to the models it makes inert.** That command picks the
+  model for the review round it runs, so neither key reaches those reviewers while every other phase
+  still resolves them normally. A key that silently does nothing is worse than one that is absent,
+  and this is the only place a reader finds out.
 
 #### 1.5.3 Defaults that keep being used
 
@@ -217,6 +221,23 @@ refuse) · **degraded** (it runs, quietly worse than the config promises), plus
   a non-negative integer (`0` = no ceiling; else the default `12` applies). Report both effective
   numbers with the count of panel members `quality.review_skill`/`quality.reviewers` defines, so
   the widest command's cost is visible before it is paid, not after.
+- **The `flow-workflows` CLI, which `review` reaches for before it composes a panel**:
+  `npx flow-workflows@<version> --version` answers, with `<version>` read from `version` in
+  `~/.claude/flow/.claude-plugin/plugin.json` — the same pin `review` uses, so the number that
+  answers cannot be behind the plugin's. Unreachable — no node, no network, a machine that installs
+  nothing — is **not** a failure: say so in one line, and that the review falls back to reading the
+  diff from git, paying for that material once per reviewer. What this check catches is a pin that
+  **cannot be fetched at all**: a candidate withdrawn from the registry, or a plugin loaded from a
+  branch whose version was never published, where every `flow-workflows` call will fail for the whole
+  session. Report the version asked for and what came back. This is the only check here about
+  something no install step of ours puts on the machine.
+- **The plugin is one copy, not two.** The version in `~/.claude/flow/.claude-plugin/plugin.json`
+  and the one the loaded `flow-core` states (its opening lines) are the same number. They differ →
+  this session resolves its commands from one copy of the plugin and its shared rules from another,
+  which is what loading a branch or a candidate over an installed copy does when the installed one is
+  left enabled. Name both numbers and the fix: disable the installed plugin for the session, or stop
+  loading the second copy. A mixture is worth a `warn` rather than a `fail` — everything still runs,
+  which is precisely why it goes unnoticed.
 - The `flow-core` skill file exists under the plugin root: `~/.claude/flow/CORE.gemini.md`.
   Missing → every phase command runs without its shared rules; fix: reinstall or update the plugin.
 

package/adapters/gemini/commands/flow/feat/review.toml

@@ -24,6 +24,33 @@ Mandatory review phase. **`/flow:feat:ship` cannot run without passing through h
 - **A premise left open by `build` §2.1bis is an input to this review, not a note.** Every row of "Premises the change depends on" whose verdict is `unsettled` enters §6 as an **ambiguous finding** (it rests, by construction, on code outside the diff) and is named in §7 whether or not the gate opened. A premise the build could not settle and the review does not mention is one the MR/PR ships as a fact.
 - Require `build` in `phases_done`. **In a multi-MR/PR work** (`meta.json.mrs` has >1 entry) require `build` in the **current `in_progress` MR/PR's** own `phases_done` (its `mrs[]` entry) — a previous MR/PR's `build` does not count. If missing, send the user to `/flow:feat:build` and stop.
 - Check that `git diff` has real changes. None → warn and stop.
+- **Gather the material once, not once per reviewer.** `npx flow-workflows@<version> bundle --checks`
+  prints one context pack for this branch — worklist, the diff (minus `git.diff_exclude`), the changed files
+  in full, the raw output of `quality.static_analysis`, and the work's handoff — in a single call.
+  Read that instead of rediscovering it, and **pass it to the briefs of §2-§6**: a panel where every
+  member runs its own `git diff` and opens the same files pays for that material once per agent, and
+  a reviewer that spends its turns exploring has fewer left to review. **Any non-zero exit is a
+  fallback, not a failure** — no CLI on the machine, a base that does not resolve, a network that
+  cannot reach it: read the diff from git as before and carry on, once, without retrying variants.
+  What is not optional is the `Review path` line of §8: a round that skipped the pack and one that
+  used it are indistinguishable from the artifact otherwise, which is how a phase quietly stops
+  paying for itself.
+- **`<version>` is this plugin's own, in every `flow-workflows` call on this page.** Read it once
+  from `version` in `~/.claude/flow/.claude-plugin/plugin.json` and substitute it. Left
+  unpinned, the fetcher resolves whatever the registry calls newest, which while a release candidate
+  is under test is the **previous** release: the page then describes subcommands and flags the CLI
+  that actually runs does not carry, every call exits non-zero, and the round takes the documented
+  fallback for a reason nobody can see. The version the plugin asks for and the version that answers
+  are the same number by construction, or the `Review path` line of §8 says which one failed.
+- **`agents.exec_cmd` set → the panel runs from the CLI.** Not a choice to weigh: run
+  `npx flow-workflows@<version> review`, which spawns that command once per role over the pack above — **one
+  turn each instead of an agentic loop each** — and returns the findings already deduplicated, with
+  the reviewers it dropped for `agents.budget_max` named. Exactly three things send the round to the
+  agentic panel below: the key is empty (the default — nothing changes without it), the CLI is
+  unavailable by the rule above, or **every** role came back empty, which is a broken `exec_cmd` and
+  not a clean diff. Whichever happened is named in §8. When the CLI runs the panel, that command
+  picks the model, so `models.agents`/`models.workers` do not reach those reviewers. A one-shot sweep
+  cannot pull a thread, so an ambiguous finding still goes to a real agent with tools, as below.
 
 ## 2. Invoke the code reviews
 
@@ -278,8 +305,10 @@ Write `.claude/work/<TICKET>/06-review.md`. The `Cost:` line of `## Summary` is
 ## Summary
 - Review tier: <full | proportional | light — which reviewers ran, at what built-in effort (medium/high/xhigh/max), and why, per §2.0>
 - Effective size: <diff size (N changed lines) vs `meta.json.size`, which of the two the tier used, and — when the diff pointed higher — that the work may be misclassified. When the diff landed within 10% under a tier threshold, say so here (§2.0).>
+- Review path: <the two paths this round actually took: `flow bundle` or git for the material, `flow review` or the agentic panel for the reviewers — each with the reason when it was the fallback (no CLI, non-zero exit, `agents.exec_cmd` empty, every role empty). Without this line a round that skipped the CLI reads exactly like one that used it.>
 - Agent models: <the value of `models.workers`/`models.agents` when set; otherwise "inherited from this thread" — plus, when the panel ran, that agents named in `agents.<role>` kept the model their own definition sets. The values as they are, no judgement on them>
 - Cost: <n>/<budget_max> subagents launched (<k> reviewers · <m> reinforcements · <s> skeptics), tier <light|proportional|full>, effort <medium|high|xhigh|max>
+- Measured cost: <what the harness reported for this round, when it reported anything — `flow review --record` writes it to `meta.json.cost[]` and `/flow:work:status` and `flow cost` read it back. A harness that reports no figure is recorded as "not reported": the subagent count above is a headcount, not a cost, and a guess is worse than a gap.>
 - Agents launched: <ran vs defined — `N/M` of the `review_skill`/`reviewers` roster, naming any that did not run (with the reason) and any substitution; "built-in only" if §2.0 selected no panel>
 - Completeness rounds (M/L): N
 - Critical findings (block ship): N

package/adapters/gemini/commands/flow/init.toml

@@ -40,6 +40,10 @@ editing. This is an optional migration, not part of a normal update.
 
 ## 2. Auto-detection (do NOT ask about what you can infer)
 
+<!-- stack-detection:start — the one place in this plugin that may name an
+     ecosystem's tools. Recognising eleven stacks is not depending on one;
+     outside these markers a tool name belongs in a FLOW.md key. -->
+
 Run, deduce, show what was found for confirmation or correction:
 
 - **Git host and CLI** — from `git remote -v`:
@@ -49,6 +53,10 @@ Run, deduce, show what was found for confirmation or correction:
   - Unknown domain (self-hosted) → ask which host (GitLab/Gitea/other) and which CLI.
   - Installed CLIs: `command -v gh glab tea az`.
 - **Base branch** — `git symbolic-ref refs/remotes/origin/HEAD` (or `git remote show origin`): `origin/main` or `origin/master` → `git.default_base`.
+- **Generated files** — the lock, build and generated-migration paths this repo tracks, from what the
+  ecosystem markers above imply plus what `git ls-files` shows at the root → propose `git.diff_exclude`.
+  These cost context in every phase that opens the diff and buy nothing: nobody reviews a lockfile.
+  Nothing tracked that matches → leave the key out.
 - **Quality commands** — propose what the repo has (empty if nothing found):
   - `Makefile` → targets `test`, `lint`, `phpstan`/`stan`, `cs-fixer`/`fmt`, `database`/`migrate`.
   - `package.json` → `scripts` (test, lint, build, typecheck).
@@ -63,6 +71,8 @@ Run, deduce, show what was found for confirmation or correction:
 - **Data access** (`data.*`, all optional) — only if the repo talks to a database. Find the client and the local stack (a `docker-compose.yml` service, a `DATABASE_URL`/`DB_*` env var, a `Makefile` target that opens a shell). Propose `data.explain_cmd` and `data.schema_cmd` in the engine's dialect against the **development** database — MySQL over Docker Compose: `docker compose exec -T <db-service> mysql <db> -e "EXPLAIN {QUERY}"` and `… -e "SHOW CREATE TABLE {TABLE}"`; PostgreSQL: `psql -c "EXPLAIN (ANALYZE, BUFFERS) {QUERY}"` / `\\d+ {TABLE}`. Leave `sandbox_cmd`/`seed_cmd`/`volumes` empty unless the user has something ready. Nothing detected → leave the section out (the query duel degrades to schema-only and says so).
 - **Knowledge sources** (`knowledge.*`) — look at the MCP tools exposed in this session: `mcp__domain-memory__*` → propose `search: mcp__domain-memory__search_knowledge`, `stage: mcp__domain-memory__stage_finding`, `read_staging: mcp__domain-memory__read_staging`, `save: mcp__domain-memory__save_knowledge`; any other tool whose name says search / query / knowledge / memory / graph (e.g. `mcp__codegraph__*`) → propose it as an additional `search` entry, roles it cannot fill left empty. A `docs/adr` or similar folder with no MCP → propose `search: rg -n -i "{QUERY}" docs/adr`. Nothing found → leave the section out. MCP and harness tool names detected in this session belong in the active overlay; a plain repo command such as the `rg` example belongs in `FLOW.md`.
 
+<!-- stack-detection:end -->
+
 ## 3. Ask five things
 
 Everything §2 detected is shown **in one screen** for confirmation or correction — host, base

package/adapters/gemini/commands/flow/work/status.toml

@@ -36,12 +36,14 @@ Overview of works in progress; detects divergences between artifacts and actual
   MR/PRs:      2/4 merged · MR/PR #3 in_progress · MR/PR #4 pending
   Cross-repo:  <meta.related_repos entries not "done", as "repo: scope">   (line only if any)
   Follow-ups:  2 awaiting a decision · 1 accepted, not started            (line only if any)
+  Cost:        $0.71 measured over 2 phases · 1 phase not reported        (line only if any)
   Next:        <suggested next command>
 ```
 
 - "MR"/"PR" from `git.host` (`gitlab` → MR, every other host → PR); no host → "MR/PR".
 - `Cross-repo:` only when `meta.json.related_repos` has entries not `done`: each as `<repo>: <scope>`, appending ` — contract not handed over` when that entry's `contract_handoff` is `pending`. It flags that a **sibling repo still has a pending part**; flow never scans or touches the other repo.
 - `Follow-ups:` only when `meta.json.followups[]` has entries not `declined`/`logged`/`done` (flow-core §7): count the `proposed` ones as *awaiting a decision* and the `accepted` ones without a `work` as *accepted, not started*, naming the ticket id when there is one. `in_progress` entries are already visible as their own work — do not double-count them.
+- `Cost:` only when `meta.json.cost[]` has entries (flow-core §4): sum the `usd` figures that are there, count the phases behind them, and count separately the entries whose `source` is `not reported`. A work with no entries shows **no line at all** — absence is not zero, and a `$0.00` under a work nobody measured is the one output that would make the block worth ignoring. The figures are the harness's own client-side estimates, not a bill; `flow cost` prints the same data phase by phase.
 - `MR/PRs:` only when `meta.json.mrs` exists with >0 entries:
   - Summary: `<merged>/<total> merged`.
   - `closed` or `superseded` MR/PRs present → add to the count: `2/4 merged · 1 closed · 1 pending`.

package/adapters/hermes/CORE.md

@@ -17,6 +17,14 @@ Every `/flow-*` command assumes these rules. They are stated once, here, so a co
 carries what is specific to its phase. Read this once per session; a command that says "load
 `flow-core`" means this file.
 
+**This file belongs to flow `0.65.0-rc.2`.** Compare it once, at the start of the session, against
+`version` in `~/.claude/flow/.claude-plugin/plugin.json`. The two differing means the session
+is running a **mixture** — the commands from one copy of the plugin, these shared rules from another
+— which is exactly what happens when a branch or a release candidate is loaded over an installed
+copy that stays enabled: the harness resolves a command from the one and a skill from the other,
+silently. Name both numbers at the first stop and say which half is which; a rule this file adds and
+a command relies on is simply absent in that session, and nothing else will report it.
+
 ## 0. Effective FLOW config — base plus harness overlay
 
 - Read `FLOW.md` at the repo root as the base, then the optional overlay for the harness running
@@ -235,6 +243,15 @@ about to type into the chat is a panel write instead** (§3):
 - **When:** (a) in pre-flight, as soon as `meta.json` is loaded; (b) immediately **before** every stop header; (c) **before** any long stretch (fan-out, full suite, CI poll) — never after, so a step that dies halfway is not shown as finished. When the stretch will outlast the ~30 min staleness warning, set `stale_after_minutes` to what it will really take; (d) wherever `## Close` updates `meta.json`.
 - **Rules:** `phase` is the phase you are **running now** (not `meta.json.phase`, which advances only at Close). `header: true` means ticket, type, phase and age are drawn by the reader — do not repeat them in `lines`. Keep it under ~14 lines. Every fact from `meta.json` and the artifacts — an invented MR/PR state is worse than a blank panel. `updated_at` from the real clock (`date -Iseconds`), never carried over. Write in the language of the work's artifacts. No work folder (lightweight `respond`/`green`) → nothing to write.
 
+### `meta.json.cost[]` — what a phase measured, when it could
+
+A phase that can measure what it spent appends one entry: `{ "phase": "review", "at": "<ISO>",
+"reviewers": 8, "usd": 0.0124, "source": "harness" }`. `flow review --record` writes it; `flow cost`
+reads it back per phase. Two rules, and they are the reason the block is worth having: a harness
+that reports no figure is recorded with `"source": "not reported"` rather than estimated, and a
+phase with no entry measured nothing — **absence is not zero**. Every figure is the harness's own
+client-side estimate and can differ from a bill.
+
 ## 5. Work summary — `00-summary.md`
 
 Each phase reads what the previous ones wrote. Reading every artifact whole on every phase is the
@@ -466,7 +483,7 @@ not `declined`/`logged`/`done`: a work being finished is precisely when its defe
 
 Mid-phase, the user corrects you. *«We don't put that in a listener here, use a message handler.»*
 *«Never mock the repository in that layer.»* *«The test command is `make test-unit`, not
-`bin/phpunit`.»* *«Stop proposing a DTO for that, we pass the entity.»* You comply, the phase closes,
+`bin/test`.»* *«Stop proposing a DTO for that, we pass the entity.»* You comply, the phase closes,
 and the next work on the same repo proposes the same thing again. The place for these exists —
 `FLOW.md`'s `conventions` and `quality` — and nothing on the path from the correction to that file is
 automatic: the user has to notice they have said it three times and go and edit it.

package/adapters/hermes/skills/flow-bug-review/SKILL.md

@@ -28,6 +28,33 @@ Read `~/.claude/flow/CORE.hermes.md` first (shared rules: `FLOW.md` step 0, mode
 - **A premise left open by `fix` §2.2 is an input to this review, not a note.** Every row of "Premises the fix depends on" whose verdict is `unsettled` enters §5 as an **ambiguous finding** and is named in §7 whether or not that gate opened — in a bug it is usually the claim that the root cause was the whole cause, which is exactly what the regression test cannot prove.
 - Require `fix` in `phases_done`; for `size` ≥ S also require `validate`.
 - `git diff` shows no changes → warn and stop.
+- **Gather the material once, not once per reviewer.** `npx flow-workflows@<version> bundle --checks`
+  prints one context pack for this branch — worklist, the diff (minus `git.diff_exclude`), the changed files
+  in full, the raw output of `quality.static_analysis`, and the work's handoff — in a single call.
+  Read that instead of rediscovering it, and **pass it to the briefs of §2-§5**: a panel where every
+  member runs its own `git diff` and opens the same files pays for that material once per agent, and
+  a reviewer that spends its turns exploring has fewer left to review. **Any non-zero exit is a
+  fallback, not a failure** — no CLI on the machine, a base that does not resolve, a network that
+  cannot reach it: read the diff from git as before and carry on, once, without retrying variants.
+  What is not optional is the `Review path` line of §7: a round that skipped the pack and one that
+  used it are indistinguishable from the artifact otherwise, which is how a phase quietly stops
+  paying for itself.
+- **`<version>` is this plugin's own, in every `flow-workflows` call on this page.** Read it once
+  from `version` in `~/.claude/flow/.claude-plugin/plugin.json` and substitute it. Left
+  unpinned, the fetcher resolves whatever the registry calls newest, which while a release candidate
+  is under test is the **previous** release: the page then describes subcommands and flags the CLI
+  that actually runs does not carry, every call exits non-zero, and the round takes the documented
+  fallback for a reason nobody can see. The version the plugin asks for and the version that answers
+  are the same number by construction, or the `Review path` line of §8 says which one failed.
+- **`agents.exec_cmd` set → the panel runs from the CLI.** Not a choice to weigh: run
+  `npx flow-workflows@<version> review`, which spawns that command once per role over the pack above — **one
+  turn each instead of an agentic loop each** — and returns the findings already deduplicated, with
+  the reviewers it dropped for `agents.budget_max` named. Exactly three things send the round to the
+  agentic panel below: the key is empty (the default — nothing changes without it), the CLI is
+  unavailable by the rule above, or **every** role came back empty, which is a broken `exec_cmd` and
+  not a clean diff. Whichever happened is named in §7. When the CLI runs the panel, that command
+  picks the model, so `models.agents`/`models.workers` do not reach those reviewers. A one-shot sweep
+  cannot pull a thread, so an ambiguous finding still goes to a real agent with tools, as below.
 
 ## 2. Run the code reviews
 
@@ -132,7 +159,9 @@ Cost line: count every subagent this command launched — reviewers = §2.1 buil
 - Review tier: <light | full | proportional — which reviewers ran, at what built-in effort (medium/high/xhigh/max), and why, per §2.0>
 - Agents launched: <ran vs defined — `N/M` of the `review_skill`/`reviewers` roster, naming any that did not run (with the reason) and any substitution; "built-in only" if §2.0 selected no panel>
 - Cost: <n>/<budget_max> subagents launched (<k> reviewers · <m> reinforcements · <s> skeptics), tier <light|proportional|full>
+- Measured cost: <what the harness reported for this round, when it reported anything — `flow review --record` writes it to `meta.json.cost[]` and `/flow-work-status` and `flow cost` read it back. A harness that reports no figure is recorded as "not reported": the subagent count above is a headcount, not a cost, and a guess is worse than a gap.>
 - Effective size: <diff size (N changed lines) vs `meta.json.size`, which the tier used, and — when the diff landed within 10% under a tier threshold — that fact (§2.0)>
+- Review path: <the two paths this round actually took: `flow bundle` or git for the material, `flow review` or the agentic panel for the reviewers — each with the reason when it was the fallback (no CLI, non-zero exit, `agents.exec_cmd` empty, every role empty). Without this line a round that skipped the CLI reads exactly like one that used it.>
 - Agent models: <the value of `models.workers`/`models.agents` when set; otherwise "inherited from this thread"; agents named in `agents.<role>` keep their own definition's model>
 - Defaults used: <every empty `FLOW.md` key this round resolved with its default — one per line as `key → default` — or "none". In `guided`/`auto` each is also an entry in `meta.json.defaults_used[]` (flow-core §0); in `manual` the phase may offer one of them at its stop.>
 - Skipped for budget: <phases dropped by §2.0's give-up order, or "none">