flow-workflows 0.67.0 → 0.68.0

package/adapters/codex/CORE.md

@@ -17,7 +17,7 @@ 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.67.0`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.68.0`.** 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
@@ -65,6 +65,15 @@ a command relies on is simply absent in that session, and nothing else will repo
   base branch — and goes out in no MR/PR at all. So a phase writing a tracked file writes it
   **here**, in the directory it is running in, and `$flow-feat-ship §5.5` is what catches the
   tools that could not be told.
+- **A fenced block in a FLOW file is an example, and an example is not configuration.** These
+  files are prose with keys in them, and the rule that decides what a key *is* — a `- key:` line
+  under a `## section` — knows nothing about triple backticks. So a block written to be pasted
+  ("add this to try it once") was read as the configuration it illustrates, for as long as it sat
+  there. It happened in a real repo: `agents.exec_cmd` came from the fenced example of a file whose
+  prose argued at length that it was deliberately unset, and every review round took the one-shot
+  path that prose warned against — with nothing anywhere to say so, because the file and the
+  configuration disagreed while both looked right. **Skip fenced regions when you read a FLOW
+  file**; `flow-workflows` does the same, so the two of you resolve the same config.
 - Merge by section and key. A key present in the active overlay replaces the base value; a key
   absent there inherits the base. **A present-but-empty overlay key masks the base** and resolves
   to the normal empty-key fallback — this is how Codex can inherit its session model while a legacy

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

@@ -129,6 +129,10 @@ Whether the world they describe exists —
 CLIs installed *and authenticated*, agents discoverable, hooks executable, the MCP reachable, the
 base branch resolvable — is §2 below; flag the key here, check the world there, never both.
 
+- **Keys inside a fenced block**: report them, one line, naming the file and the keys — they are
+  an example and resolve to nothing (flow-core §0), which is exactly what a reader who pasted a
+  block to enable it cannot tell from a key that works. Say what to do about it: move the line out
+  of the fence to make it real, leave it there to keep it an illustration.
 - **Fan-out and cost ceilings**: `agents.fanout_max` must be a positive integer; else flag and note
   the default `4` applies. `agents.budget_max` must be a non-negative integer (`0` = no ceiling);
   else flag and note the default `12`. **Both absent → say so as a finding, not a pass**: the review

package/adapters/gemini/CORE.md

@@ -16,7 +16,7 @@ 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.67.0`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.68.0`.** 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
@@ -64,6 +64,15 @@ a command relies on is simply absent in that session, and nothing else will repo
   base branch — and goes out in no MR/PR at all. So a phase writing a tracked file writes it
   **here**, in the directory it is running in, and `/flow:feat:ship §5.5` is what catches the
   tools that could not be told.
+- **A fenced block in a FLOW file is an example, and an example is not configuration.** These
+  files are prose with keys in them, and the rule that decides what a key *is* — a `- key:` line
+  under a `## section` — knows nothing about triple backticks. So a block written to be pasted
+  ("add this to try it once") was read as the configuration it illustrates, for as long as it sat
+  there. It happened in a real repo: `agents.exec_cmd` came from the fenced example of a file whose
+  prose argued at length that it was deliberately unset, and every review round took the one-shot
+  path that prose warned against — with nothing anywhere to say so, because the file and the
+  configuration disagreed while both looked right. **Skip fenced regions when you read a FLOW
+  file**; `flow-workflows` does the same, so the two of you resolve the same config.
 - Merge by section and key. A key present in the active overlay replaces the base value; a key
   absent there inherits the base. **A present-but-empty overlay key masks the base** and resolves
   to the normal empty-key fallback — this is how Codex can inherit its session model while a legacy

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

@@ -125,6 +125,10 @@ Whether the world they describe exists —
 CLIs installed *and authenticated*, agents discoverable, hooks executable, the MCP reachable, the
 base branch resolvable — is §2 below; flag the key here, check the world there, never both.
 
+- **Keys inside a fenced block**: report them, one line, naming the file and the keys — they are
+  an example and resolve to nothing (flow-core §0), which is exactly what a reader who pasted a
+  block to enable it cannot tell from a key that works. Say what to do about it: move the line out
+  of the fence to make it real, leave it there to keep it an illustration.
 - **Fan-out and cost ceilings**: `agents.fanout_max` must be a positive integer; else flag and note
   the default `4` applies. `agents.budget_max` must be a non-negative integer (`0` = no ceiling);
   else flag and note the default `12`. **Both absent → say so as a finding, not a pass**: the review

package/adapters/hermes/CORE.md

@@ -17,7 +17,7 @@ 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.67.0`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.68.0`.** 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
@@ -65,6 +65,15 @@ a command relies on is simply absent in that session, and nothing else will repo
   base branch — and goes out in no MR/PR at all. So a phase writing a tracked file writes it
   **here**, in the directory it is running in, and `/flow-feat-ship §5.5` is what catches the
   tools that could not be told.
+- **A fenced block in a FLOW file is an example, and an example is not configuration.** These
+  files are prose with keys in them, and the rule that decides what a key *is* — a `- key:` line
+  under a `## section` — knows nothing about triple backticks. So a block written to be pasted
+  ("add this to try it once") was read as the configuration it illustrates, for as long as it sat
+  there. It happened in a real repo: `agents.exec_cmd` came from the fenced example of a file whose
+  prose argued at length that it was deliberately unset, and every review round took the one-shot
+  path that prose warned against — with nothing anywhere to say so, because the file and the
+  configuration disagreed while both looked right. **Skip fenced regions when you read a FLOW
+  file**; `flow-workflows` does the same, so the two of you resolve the same config.
 - Merge by section and key. A key present in the active overlay replaces the base value; a key
   absent there inherits the base. **A present-but-empty overlay key masks the base** and resolves
   to the normal empty-key fallback — this is how Codex can inherit its session model while a legacy

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

@@ -129,6 +129,10 @@ Whether the world they describe exists —
 CLIs installed *and authenticated*, agents discoverable, hooks executable, the MCP reachable, the
 base branch resolvable — is §2 below; flag the key here, check the world there, never both.
 
+- **Keys inside a fenced block**: report them, one line, naming the file and the keys — they are
+  an example and resolve to nothing (flow-core §0), which is exactly what a reader who pasted a
+  block to enable it cannot tell from a key that works. Say what to do about it: move the line out
+  of the fence to make it real, leave it there to keep it an illustration.
 - **Fan-out and cost ceilings**: `agents.fanout_max` must be a positive integer; else flag and note
   the default `4` applies. `agents.budget_max` must be a non-negative integer (`0` = no ceiling);
   else flag and note the default `12`. **Both absent → say so as a finding, not a pass**: the review

package/adapters/opencode/CORE.md

@@ -16,7 +16,7 @@ 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.67.0`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.68.0`.** 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
@@ -64,6 +64,15 @@ a command relies on is simply absent in that session, and nothing else will repo
   base branch — and goes out in no MR/PR at all. So a phase writing a tracked file writes it
   **here**, in the directory it is running in, and `/flow-feat-ship §5.5` is what catches the
   tools that could not be told.
+- **A fenced block in a FLOW file is an example, and an example is not configuration.** These
+  files are prose with keys in them, and the rule that decides what a key *is* — a `- key:` line
+  under a `## section` — knows nothing about triple backticks. So a block written to be pasted
+  ("add this to try it once") was read as the configuration it illustrates, for as long as it sat
+  there. It happened in a real repo: `agents.exec_cmd` came from the fenced example of a file whose
+  prose argued at length that it was deliberately unset, and every review round took the one-shot
+  path that prose warned against — with nothing anywhere to say so, because the file and the
+  configuration disagreed while both looked right. **Skip fenced regions when you read a FLOW
+  file**; `flow-workflows` does the same, so the two of you resolve the same config.
 - Merge by section and key. A key present in the active overlay replaces the base value; a key
   absent there inherits the base. **A present-but-empty overlay key masks the base** and resolves
   to the normal empty-key fallback — this is how Codex can inherit its session model while a legacy

package/adapters/opencode/commands/flow-doctor.md

@@ -127,6 +127,10 @@ Whether the world they describe exists —
 CLIs installed *and authenticated*, agents discoverable, hooks executable, the MCP reachable, the
 base branch resolvable — is §2 below; flag the key here, check the world there, never both.
 
+- **Keys inside a fenced block**: report them, one line, naming the file and the keys — they are
+  an example and resolve to nothing (flow-core §0), which is exactly what a reader who pasted a
+  block to enable it cannot tell from a key that works. Say what to do about it: move the line out
+  of the fence to make it real, leave it there to keep it an illustration.
 - **Fan-out and cost ceilings**: `agents.fanout_max` must be a positive integer; else flag and note
   the default `4` applies. `agents.budget_max` must be a non-negative integer (`0` = no ceiling);
   else flag and note the default `12`. **Both absent → say so as a finding, not a pass**: the review

package/bin/cli.mjs

@@ -240,7 +240,22 @@ function parseFlow(text) {
   const out = {}
   let section = null
   let listKey = null
+  let fence = null
   for (const line of text.split('\n')) {
+    // A fenced block is an illustration, not configuration. This reader knows headings and
+    // `- key:` lines and nothing else, so an example written the way `docs/CONFIGURATION.md`
+    // and every FLOW.md in the wild write one — keys inside triple backticks, under a sentence
+    // saying "paste this to try it" — was live config the whole time. A real repo had
+    // `agents.exec_cmd` set from the block of a file whose prose argued, at length, that it was
+    // deliberately unset, and every review round took the one-shot path it warned against.
+    // Closing fence: same character, at least as long as the opening one (CommonMark).
+    const f = /^\s{0,3}(`{3,}|~{3,})/.exec(line)
+    if (f) {
+      if (!fence) fence = f[1]
+      else if (f[1][0] === fence[0] && f[1].length >= fence.length) fence = null
+      continue
+    }
+    if (fence) continue
     const heading = /^##\s+(\S+)/.exec(line)
     if (heading) {
       section = heading[1]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flow-workflows",
-  "version": "0.67.0",
+  "version": "0.68.0",
   "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.",
   "type": "module",
   "bin": {

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.68.0",
   "author": {
     "name": "Alberto Vioque",
     "email": "mashware@gmail.com"

package/plugins/flow/CHANGELOG.md

@@ -5,6 +5,33 @@ 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.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**