flow-workflows 0.67.0 → 0.69.0

package/plugins/flow/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "flow",
   "displayName": "Flow — guided dev workflows",
   "description": "Guided feat/bug workflows (start→ship), post-deploy monitoring and multi-agent code review, stack-agnostic. Each repo uses a shared FLOW.md plus optional harness overlay.",
-  "version": "0.67.0",
+  "version": "0.69.0",
   "author": {
     "name": "Alberto Vioque",
     "email": "mashware@gmail.com"

package/plugins/flow/CHANGELOG.md

@@ -5,6 +5,64 @@ 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.69.0 — Waiting on the pipeline was paid for at the main thread's price  ·  2026-09-21
+
+**In short**
+- **A wait is delegated now, not sat through.** A running pipeline, a deploy that has not landed and a suite measured in tens of minutes go to one supervisor subagent with an interval, a deadline and every terminal state; this thread ends its turn instead of polling.
+- **What comes back is evidence, never a verdict** — failing job names, exit codes, the log tail, the run URL, the SHA it watched. Whether a red job is flaky, whether a threshold is close enough, whether the branch can merge is still decided on the main thread.
+- **`models.supervisors`** names the model for it, falling back to `models.agents` and then to inheritance. An empty section behaves exactly as before, and the dispatch says in one line that the wait inherits this thread's model — an unattended wait is where an unpriced default runs longest.
+- **Applied where the flow actually waits**: `/flow:work:green` §2.3 and its re-trigger, `/flow:work:watch` §1, both `validate` commands for a long suite, and both `ship` commands for the pipeline the push starts.
+- **Delegating a wait is mechanics**, so it is on the never-ask list: `manual` still asks whatever the evidence turns out to call for, once it is back.
+
+Every command that waited, waited on the thread holding the whole conversation. `green` offered to
+poll a running pipeline every two or three minutes; `watch` polled for a deploy that had not landed
+yet; `validate` ran the full suite in the background and stayed with it. None of that reads a diff
+or weighs a finding — it reads `pending` — and each cycle resends the entire context to do it. A
+forty-minute pipeline could cost more to watch than the diff cost to write, and the cost was
+invisible because waiting looks like nothing happening.
+
+The delegation is bounded on purpose. The brief names the exact run rather than "the CI", every
+terminal state rather than the first red job, and a deadline after which the supervisor returns what
+it has instead of waiting forever. It writes its evidence to a path before it replies, like every
+other brief, so a report lost in transit is recoverable for the cost of one `ls`. And it counts
+against `agents.budget_max` like any other subagent, relaunches included.
+
+What it must never do is rule. Handing the judgement to whoever is cheapest to ask is how a pipeline
+ends up declared green by a model that was hired to watch a clock — the machine version of the
+green-washing `/flow:work:green` refuses in every autonomy mode. The supervisor reports; the triage,
+the merge verdict and the decision to push stay exactly where they were.
+
+Not every wait is worth a brief either: a suite that finishes in ninety seconds costs more to
+delegate than to run, and anything the phase must react to mid-wait was never a wait — it is the
+work.
+
+## v0.68.0 — The block written to be pasted was the configuration  ·  2026-09-21
+
+**In short**
+- **A fenced block in a FLOW file is an example again.** `- key:` lines inside triple backticks (or tildes) are skipped by `bin/cli.mjs` and by flow-core §0, so the two resolve the same configuration. Until now they were read as the config they illustrate.
+- **This was found in a live repo, not imagined.** `agents.exec_cmd` was set from the fenced example of a file whose prose argued, at length, that it was deliberately unset — so every review round took the one-shot path that prose warned against, and nothing anywhere said so.
+- **`/flow:doctor` reports keys found inside a fence**, names the file and says what to do: move the line out to make it real, leave it to keep it an illustration.
+- **`script/tests/flow-config.sh`** pins it — fenced values never leak, `~~~` and four-backtick blocks are fences, a closed fence does not swallow the keys after it. Every case fails against the old reader.
+- **Two tests now actually run in CI**: the new one and `tier.sh`, which existed and was wired into nothing.
+
+A `FLOW.md` is prose with keys in it, and that is the point of it: the keys are the contract, the
+prose is why the value is what it is. What decides which is which is shape alone — a `- key:` line
+under a `## section` — and shape is exactly what a documented example shares with the thing it
+documents. `docs/CONFIGURATION.md` teaches keys in fenced blocks. The template's own comments do.
+So does every real `FLOW.md` that explains an option before enabling it.
+
+The repo where this surfaced had a Claude overlay with three paragraphs on why `agents.exec_cmd`
+stays unset — cost against the panel that had been finding the defects — followed by a block
+introduced with *"to try it once, add both blocks below and take them out again afterwards"*. The
+block was live from the moment it was written: `exec_cmd` set, `quality.reviewers` masked with four
+role descriptions instead of the four agents the base names. The file and its configuration said
+opposite things, and both looked right.
+
+Nothing warns about that class of mistake, because the file is valid and the round it produces is
+green. So the reader changes: fenced regions are skipped, by the CLI and by the command pages that
+read the file themselves, and `doctor` reports what it found in one — a reader who pasted a block
+to enable it needs to be told why it does nothing, which is the mirror of the same problem.
+
 ## v0.67.0 — Every layer of the review was argued from judgement, and none was ever checked  ·  2026-09-21
 
 **In short**

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

@@ -239,11 +239,19 @@ subagent ignores the value and the step says so once, in one line.
 - `workers:`  # the parallel fan-out rounds ONLY: approach panel (design §1.5.3), hypothesis sweep
               #   (investigate §3.A), finding skeptics (review §6 / §5), the deferred-work skeptic
               #   (ship). Empty = falls back to `agents`, then to what the command runs on.
-
-**Two keys, not one per kind of step.** There used to be five — `study`, `code`, `test`, `review` —
-named after phases. They promised a granularity no harness delivers: the main agent cannot switch
-its own model, so the phases those keys named ran on whatever you launched, and the value only ever
-reached the subagents. These two name what can actually be set.
+- `supervisors:` # the ONE subagent a command hands a long wait to instead of polling it from the main thread
+              #   (flow-core §6.5): a running pipeline (green §2.3, §6), a deploy that has not landed yet
+              #   (watch §1), a suite measured in tens of minutes (validate §2). It watches, times out and
+              #   brings back status plus evidence — job names, exit codes, log tail, run URL — and never
+              #   rules on it: triage and the merge verdict stay on the main thread whatever this says.
+              #   Empty = falls back to `agents`, then to what the command runs on, and the dispatch says so
+              #   in one line — an unattended wait is the one place an unpriced default runs longest.
+
+**Three keys, one per kind of subagent — not one per kind of step.** There used to be five —
+`study`, `code`, `test`, `review` — named after phases. They promised a granularity no harness
+delivers: the main agent cannot switch its own model, so the phases those keys named ran on whatever
+you launched, and the value only ever reached the subagents. These three name what can actually be
+set: the improvised agent, the fan-out round, and the wait.
 
 Two limits, stated here because they bound what these keys can promise:
 
@@ -255,7 +263,7 @@ question in `guided`/`auto` and never a gate.
 
 **A named agent keeps its own model.** If `agents.<role>` names a real agent, that agent's own
 definition wins — you configured it, and it is not overridden from two places. `/flow:doctor` prints
-both keys resolved, with who decided each.
+the three keys resolved, with who decided each.
 
 ## data
 How this repo lets you look at a query's **plan** instead of arguing about it. Read by