flow-workflows 0.64.0 → 0.65.0-rc.2

package/plugins/flow/CHANGELOG.md

@@ -5,6 +5,75 @@ plugin and is what `/flow:news` reads to show you what changed since your previo
 
 The canonical, richest notes live in the [GitHub Releases](https://github.com/mashware/flow-workflows/releases).
 
+## v0.65.0 — Every phase rediscovered the same context, and nobody knew what it cost  ·  2026-09-17
+
+**In short**
+- **A round gathers its material once.** `npx flow-workflows bundle` prints one context pack — worklist, diff, changed files, the repo's own analysis output, the work's handoff — instead of every reviewer paying to rediscover it.
+- **The panel can run outside the agentic loop.** With `agents.exec_cmd` set, `npx flow-workflows review` runs one reviewer per role in **one turn each**, deduplicated — and that is what runs when the key is there, not one option among two.
+- **What a phase spent is written down.** `meta.json.cost[]` records the figure the harness reported, `"not reported"` when it reported none and never an estimate; `flow cost`, `/flow:work:status` and the review artifact read it back.
+- **A change can be run before it is tagged — and the candidate's own code is what runs.** Candidates publish under the `next` channel so `latest` never moves; the commands pin the CLI to the plugin's own version, so a candidate's commands can never be served by the previous release's CLI; and a session that has ended up with two copies of the plugin says so instead of running a mixture.
+- **Two claims stopped being promises.** The preflight now refuses a line that *depends* on one ecosystem, and a test pins the four answer shapes the review CLI has to unwrap.
+
+A phase costs turns times context. The API keeps no state, so ten calls spent finding out what
+changed cost ten times the context they find — and `review` made that worse by construction: every
+member of a panel ran its own `git diff`, opened the same files, and read the same code, paying for
+that material once per agent. `bundle` gathers it for the whole round in a single call, and
+`quality.static_analysis` — a key that until now only ran at the end — is copied into the pack
+verbatim, so a reviewer no longer spends its turns hunting for what a linter already knew.
+
+It knows nothing about any ecosystem, which is the constraint that decided its shape. Which paths to
+leave out of the diff comes from the new `git.diff_exclude`; which command reports problems comes
+from the existing `quality.static_analysis`; that command's output is copied out rather than parsed,
+because parsing it is exactly what would tie the plugin to one toolchain. One size rule governs the
+whole pack: a file over the limit is out of both the contents and the diff, and is named with its
+size.
+
+`agents.exec_cmd` is the other half. A reviewer that only has to read a pack and answer does not
+need an agentic loop, and where the key is set the round now runs one non-interactive invocation per
+role — any harness, any vendor, a script of your own — with the findings deduplicated in code rather
+than by a model reading eight reports. It arrived as an alternative the panel *could* take, and a
+real run showed what that costs: the familiar path wins every time, in silence. So it is the path
+when the key is set, with three named ways back to the agentic panel, and the review artifact now
+records which one ran — a round that skipped the CLI and one that used it read the same otherwise.
+
+Cost stopped being a design argument and became a number. Every phase that can measure what it spent
+appends one entry to `meta.json.cost[]`, and the two rules are what make the block worth having: a
+harness that reports nothing is recorded as `"not reported"` rather than estimated, and a phase with
+no entry measured nothing — absence is not zero. The `Cost:` line of a review, meanwhile, stopped
+counting subagents: a headcount is not a bill, and saying so was cheaper than pretending otherwise.
+
+None of this requires anything of an existing repo. An empty `agents.exec_cmd` is the default and
+the agentic panel runs exactly as before; a `FLOW.md` written before any of these keys existed still
+produces a pack; a work with no cost block simply has none. What a machine without node loses is the
+saving, not the review — the CLI failing for any reason is a documented fallback to reading the diff
+from git, and `/flow:doctor` now checks for that CLI so it is a line in a diagnosis rather than a
+surprise mid-phase.
+
+Finally, two things this repo asserted about itself and never checked. `check_no_stack_leak` reads
+every line of the plugin and fails the ones that *depend* on a single ecosystem — naming several is
+a detection table and passes, naming one is a leak — with three narrow exemptions and no exemption
+at all under `bin/`. And a change to the flow can now be installed before it is tagged: an rc
+publishes under `next`, `claude --plugin-dir` loads a branch over the release you use daily, and npm
+serves a branch straight from git for the other harnesses.
+
+The first candidate then proved that last sentence half-true, in the only way that counts — a real
+work, driven end to end, on a real repo. Two things a page of prose could not have found. The
+commands call the CLI unpinned, so an unpinned fetch resolves the channel a candidate deliberately
+does not move: the candidate's own commands were served the **previous** release's CLI, `bundle` came
+back *"Unknown command"*, and the round took the documented fallback — correctly, silently, for a
+reason that had nothing to do with the machine. Every `flow-workflows` call now carries the plugin's
+own version, and the preflight refuses a tree where the manifest, the npm package and `flow-core`
+do not state the same number, because a pin is only worth having if the number it asks for was
+published. And loading a branch over an installed copy leaves **two** plugins of the same name: the
+session took its commands from the branch and its shared rules from the release, ran perfectly, and
+recorded the wrong thing. `flow-core` now states which version it belongs to, so any session can
+compare it against the plugin it is running and name both numbers at its first stop; `/flow:doctor`
+checks it outright, and `RELEASING.md` says to disable the installed copy rather than rely on either.
+
+What made all of this visible was the `Review path` line added above — a round that fell back and a
+round that did not are one line apart in the artifact, and without that line this release would have
+shipped believing its own notes.
+
 ## v0.64.0 — Announcing the next step was how the run ended  ·  2026-09-16
 
 **In short**

package/plugins/flow/examples/FLOW.template.md

@@ -69,6 +69,12 @@ Branch and Pull/Merge Request conventions.
 - `cli:`              # Empty = the default for `host` in the table above. Set it for a self-hosted forge, a wrapper, or
                       #   a host with no CLI of its own (`bitbucket`), where the commands degrade to plain git and say so.
 - `default_base:`     # base for new branches, e.g. `origin/master` or `origin/main`.
+- `diff_exclude:`     # paths kept out of the diff a phase reads, one per line with `- `. Generated files nobody reviews —
+                      #   dependency locks, generated migrations, compiled assets, recorded fixtures — cost context in every
+                      #   phase that opens the diff and in every reviewer launched over it. Empty = exclude nothing.
+                      #   `/flow:init` proposes what it finds. Git pathspec syntax, so a glob works. e.g.:
+                      #   - '*.lock'
+                      #   - 'assets/build/**'
 - `branch_pattern:`   # e.g. `{PREFIX}{TICKET}-{slug}`. `{slug}` in English, kebab-case. Empty = `{PREFIX}{TICKET}-{slug}`.
 - `assignee:`         # user to assign the MR/PR to. Empty = do not assign.
 - `squash:`           # `true` | `false` (squash-before-merge).
@@ -180,6 +186,18 @@ Two keys below configure the **parallel fan-out** (approach panel in `design` §
 sweep in `investigate` §3.A, finding verification in `review`) instead of naming an agent. The
 fan-out runs as plain parallel subagents — the primitive every harness has.
 
+- `exec_cmd:`         # how to invoke a harness NON-interactively, so `flow review` can run one reviewer per role in one
+                      #   turn each instead of an agentic loop each. `{ROLE}` and `{SCHEMA}` are substituted; the diff and
+                      #   the brief arrive on stdin. **Empty = the agentic panel inside `/flow:*:review` reviews, exactly
+                      #   as before** — this key is the opt-in, nothing changes without it. It takes any command: a
+                      #   subscription login, an API key, another vendor's CLI, or a script of your own. When it is set,
+                      #   that command picks the model and `models.agents`/`models.workers` no longer apply to review.
+                      #   Quote `{SCHEMA}` with DOUBLE quotes: the substitution escapes for that context and single
+                      #   quotes would hand the command invalid JSON. A harness that answers in an envelope of its own
+                      #   is unwrapped here — no `jq` needed. Measured: one reviewer over a small diff ≈ $0.17, so a
+                      #   four-role round ≈ $0.70, which is what `budget_max` below is bounding. e.g.:
+                      #   - claude -p --model sonnet --output-format json --json-schema "{SCHEMA}"
+                      #   - codex exec --model <m>
 - `fanout_max:`     # max subagents per parallel round. Empty = 4. Lower it to keep the flow cheap; what a cap drops is always reported
 - `budget_max:`     # max subagents ONE command run may launch in total, summed over every round (flow-core §6). Empty = 12. `0` = no ceiling
                     #   (not recommended). `fanout_max` bounds a round; this bounds the command — `/flow:*:review` composes a panel, area
@@ -195,6 +213,8 @@ command composes itself — the panel in `review`, the delegated pieces in `buil
 `validate` — not to the prompts this plugin already writes out with their own cap.
 
 - `report_max_words:`      # word cap every brief you write for a subagent carries. Empty = 250. Not a style rule: a report too long for the harness to carry is truncated in transit and reaches you as silence
+                           #   Output tokens are the most expensive kind and are never served from cache,
+                           #   so this is a cost ceiling as much as a format rule
 - `stall_after_minutes:`   # a fan-out agent past this with nothing written to its named path is stopped, its brief split in two, and relaunched. Empty = 25 —
                            #   a guess from one session, not a measurement. Lower it if your rounds are short and you would rather relaunch early; raise it
                            #   for agents that legitimately read for half an hour before writing