flow-workflows 0.65.0-rc.1 → 0.65.0-rc.3

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.3`.** 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
@@ -26,6 +34,17 @@ carries what is specific to its phase. Read this once per session; a command tha
   valid without a base file; unknown `FLOW.*.md` names are ignored. Throughout every command,
   **"FLOW.md" means this effective merged configuration** unless the command explicitly names a
   file it will edit.
+- **"The repo root" is the main checkout's, not the worktree's.** With `git.worktree` set, every
+  phase after `start` runs inside a linked worktree — and a `FLOW.md` the repo git-ignores (the
+  normal case for a personal config, and always the case for a harness overlay) exists **only in
+  the main checkout**. Looking for it where the phase happens finds nothing, and a configuration
+  that resolves to every fallback looks exactly like a repo that never had one: the models, the
+  ceilings and the sensitive paths are silently the defaults, and the phase reports nothing
+  because from where it stands there is nothing to report. So: prefer a `FLOW.md` in the directory
+  you are in — a repo that commits its config has one in every worktree, and it may legitimately
+  differ — and otherwise read both files from the main checkout, which
+  `git rev-parse --path-format=absolute --git-common-dir` locates from anywhere (its parent
+  directory). Name the file you actually read when a stop reports configuration.
 - 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-bug-review/SKILL.md

@@ -28,8 +28,8 @@ 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 bundle --checks` prints
-  one context pack for this branch — worklist, the diff (minus `git.diff_exclude`), the changed files
+- **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
@@ -39,8 +39,15 @@ Read `~/.claude/flow/CORE.codex.md` first (shared rules: `FLOW.md` step 0, model
   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 review`, which spawns that command once per role over the pack above — **one
+  `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

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

@@ -33,6 +33,9 @@ changing machines, after `$flow-init`, or when a command failed the way an envir
   `FLOW.md`, then its `FLOW.<harness>.md` overlay. Never read another harness's overlay. Both absent
   is **not** an error: say so in one line, check what needs no config (git, hooks, harness, base
   branch, plugin files), and note that `$flow-init` would let this command check the rest.
+  **Say which checkout the configuration came from** whenever it is not the directory you are in
+  (flow-core §0: a worktree does not carry a git-ignored `FLOW.md`). A diagnosis run from a
+  worktree that quietly read nothing is the one that certifies a repo as unconfigured.
 - Parse both files by section: `tracker`, `git`, `autonomy`, `quality`, `agents`, `models`, `data`,
   `conventions`, `notes`, `knowledge`, `observability`; merge keys and empty masks per flow-core §0.
   Keep the source of every effective value. Both absent → §1.5 runs with **every** key empty (all
@@ -226,12 +229,22 @@ refuse) · **degraded** (it runs, quietly worse than the config promises), plus
   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` answers, and the number matches this 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. A version *behind* the plugin's is the one that misleads, because the commands then
-  describe flags the installed CLI does not have: report both numbers and let the reader decide.
-  This is the only check here about something no install step of ours puts on the machine.
+  `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,8 +28,8 @@ 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 bundle --checks` prints
-  one context pack for this branch — worklist, the diff (minus `git.diff_exclude`), the changed files
+- **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
@@ -39,8 +39,15 @@ Mandatory review phase. **`$flow-feat-ship` cannot run without passing through h
   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 review`, which spawns that command once per role over the pack above — **one
+  `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

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.3`.** 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
@@ -25,6 +33,17 @@ carries what is specific to its phase. Read this once per session; a command tha
   valid without a base file; unknown `FLOW.*.md` names are ignored. Throughout every command,
   **"FLOW.md" means this effective merged configuration** unless the command explicitly names a
   file it will edit.
+- **"The repo root" is the main checkout's, not the worktree's.** With `git.worktree` set, every
+  phase after `start` runs inside a linked worktree — and a `FLOW.md` the repo git-ignores (the
+  normal case for a personal config, and always the case for a harness overlay) exists **only in
+  the main checkout**. Looking for it where the phase happens finds nothing, and a configuration
+  that resolves to every fallback looks exactly like a repo that never had one: the models, the
+  ceilings and the sensitive paths are silently the defaults, and the phase reports nothing
+  because from where it stands there is nothing to report. So: prefer a `FLOW.md` in the directory
+  you are in — a repo that commits its config has one in every worktree, and it may legitimately
+  differ — and otherwise read both files from the main checkout, which
+  `git rev-parse --path-format=absolute --git-common-dir` locates from anywhere (its parent
+  directory). Name the file you actually read when a stop reports configuration.
 - 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/bug/review.toml

@@ -24,8 +24,8 @@ 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 bundle --checks` prints
-  one context pack for this branch — worklist, the diff (minus `git.diff_exclude`), the changed files
+- **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
@@ -35,8 +35,15 @@ Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, mode
   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 review`, which spawns that command once per role over the pack above — **one
+  `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

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

@@ -29,6 +29,9 @@ changing machines, after `/flow:init`, or when a command failed the way an envir
   `FLOW.md`, then its `FLOW.<harness>.md` overlay. Never read another harness's overlay. Both absent
   is **not** an error: say so in one line, check what needs no config (git, hooks, harness, base
   branch, plugin files), and note that `/flow:init` would let this command check the rest.
+  **Say which checkout the configuration came from** whenever it is not the directory you are in
+  (flow-core §0: a worktree does not carry a git-ignored `FLOW.md`). A diagnosis run from a
+  worktree that quietly read nothing is the one that certifies a repo as unconfigured.
 - Parse both files by section: `tracker`, `git`, `autonomy`, `quality`, `agents`, `models`, `data`,
   `conventions`, `notes`, `knowledge`, `observability`; merge keys and empty masks per flow-core §0.
   Keep the source of every effective value. Both absent → §1.5 runs with **every** key empty (all
@@ -222,12 +225,22 @@ refuse) · **degraded** (it runs, quietly worse than the config promises), plus
   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` answers, and the number matches this 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. A version *behind* the plugin's is the one that misleads, because the commands then
-  describe flags the installed CLI does not have: report both numbers and let the reader decide.
-  This is the only check here about something no install step of ours puts on the machine.
+  `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,8 +24,8 @@ 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 bundle --checks` prints
-  one context pack for this branch — worklist, the diff (minus `git.diff_exclude`), the changed files
+- **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
@@ -35,8 +35,15 @@ Mandatory review phase. **`/flow:feat:ship` cannot run without passing through h
   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 review`, which spawns that command once per role over the pack above — **one
+  `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

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.3`.** 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
@@ -26,6 +34,17 @@ carries what is specific to its phase. Read this once per session; a command tha
   valid without a base file; unknown `FLOW.*.md` names are ignored. Throughout every command,
   **"FLOW.md" means this effective merged configuration** unless the command explicitly names a
   file it will edit.
+- **"The repo root" is the main checkout's, not the worktree's.** With `git.worktree` set, every
+  phase after `start` runs inside a linked worktree — and a `FLOW.md` the repo git-ignores (the
+  normal case for a personal config, and always the case for a harness overlay) exists **only in
+  the main checkout**. Looking for it where the phase happens finds nothing, and a configuration
+  that resolves to every fallback looks exactly like a repo that never had one: the models, the
+  ceilings and the sensitive paths are silently the defaults, and the phase reports nothing
+  because from where it stands there is nothing to report. So: prefer a `FLOW.md` in the directory
+  you are in — a repo that commits its config has one in every worktree, and it may legitimately
+  differ — and otherwise read both files from the main checkout, which
+  `git rev-parse --path-format=absolute --git-common-dir` locates from anywhere (its parent
+  directory). Name the file you actually read when a stop reports configuration.
 - 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-bug-review/SKILL.md

@@ -28,8 +28,8 @@ 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 bundle --checks` prints
-  one context pack for this branch — worklist, the diff (minus `git.diff_exclude`), the changed files
+- **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
@@ -39,8 +39,15 @@ Read `~/.claude/flow/CORE.hermes.md` first (shared rules: `FLOW.md` step 0, mode
   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 review`, which spawns that command once per role over the pack above — **one
+  `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

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

@@ -33,6 +33,9 @@ changing machines, after `/flow-init`, or when a command failed the way an envir
   `FLOW.md`, then its `FLOW.<harness>.md` overlay. Never read another harness's overlay. Both absent
   is **not** an error: say so in one line, check what needs no config (git, hooks, harness, base
   branch, plugin files), and note that `/flow-init` would let this command check the rest.
+  **Say which checkout the configuration came from** whenever it is not the directory you are in
+  (flow-core §0: a worktree does not carry a git-ignored `FLOW.md`). A diagnosis run from a
+  worktree that quietly read nothing is the one that certifies a repo as unconfigured.
 - Parse both files by section: `tracker`, `git`, `autonomy`, `quality`, `agents`, `models`, `data`,
   `conventions`, `notes`, `knowledge`, `observability`; merge keys and empty masks per flow-core §0.
   Keep the source of every effective value. Both absent → §1.5 runs with **every** key empty (all
@@ -226,12 +229,22 @@ refuse) · **degraded** (it runs, quietly worse than the config promises), plus
   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` answers, and the number matches this 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. A version *behind* the plugin's is the one that misleads, because the commands then
-  describe flags the installed CLI does not have: report both numbers and let the reader decide.
-  This is the only check here about something no install step of ours puts on the machine.
+  `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.hermes.md`.
   Missing → every phase command runs without its shared rules; fix: reinstall or update the plugin.
 

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

@@ -28,8 +28,8 @@ 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 bundle --checks` prints
-  one context pack for this branch — worklist, the diff (minus `git.diff_exclude`), the changed files
+- **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
@@ -39,8 +39,15 @@ Mandatory review phase. **`/flow-feat-ship` cannot run without passing through h
   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 review`, which spawns that command once per role over the pack above — **one
+  `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

package/adapters/opencode/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.3`.** 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
@@ -25,6 +33,17 @@ carries what is specific to its phase. Read this once per session; a command tha
   valid without a base file; unknown `FLOW.*.md` names are ignored. Throughout every command,
   **"FLOW.md" means this effective merged configuration** unless the command explicitly names a
   file it will edit.
+- **"The repo root" is the main checkout's, not the worktree's.** With `git.worktree` set, every
+  phase after `start` runs inside a linked worktree — and a `FLOW.md` the repo git-ignores (the
+  normal case for a personal config, and always the case for a harness overlay) exists **only in
+  the main checkout**. Looking for it where the phase happens finds nothing, and a configuration
+  that resolves to every fallback looks exactly like a repo that never had one: the models, the
+  ceilings and the sensitive paths are silently the defaults, and the phase reports nothing
+  because from where it stands there is nothing to report. So: prefer a `FLOW.md` in the directory
+  you are in — a repo that commits its config has one in every worktree, and it may legitimately
+  differ — and otherwise read both files from the main checkout, which
+  `git rev-parse --path-format=absolute --git-common-dir` locates from anywhere (its parent
+  directory). Name the file you actually read when a stop reports configuration.
 - 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-bug-review.md

@@ -26,8 +26,8 @@ Read `~/.claude/flow/CORE.opencode.md` first (shared rules: `FLOW.md` step 0, mo
 - **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 bundle --checks` prints
-  one context pack for this branch — worklist, the diff (minus `git.diff_exclude`), the changed files
+- **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
@@ -37,8 +37,15 @@ Read `~/.claude/flow/CORE.opencode.md` first (shared rules: `FLOW.md` step 0, mo
   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 review`, which spawns that command once per role over the pack above — **one
+  `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

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

@@ -31,6 +31,9 @@ changing machines, after `/flow-init`, or when a command failed the way an envir
   `FLOW.md`, then its `FLOW.<harness>.md` overlay. Never read another harness's overlay. Both absent
   is **not** an error: say so in one line, check what needs no config (git, hooks, harness, base
   branch, plugin files), and note that `/flow-init` would let this command check the rest.
+  **Say which checkout the configuration came from** whenever it is not the directory you are in
+  (flow-core §0: a worktree does not carry a git-ignored `FLOW.md`). A diagnosis run from a
+  worktree that quietly read nothing is the one that certifies a repo as unconfigured.
 - Parse both files by section: `tracker`, `git`, `autonomy`, `quality`, `agents`, `models`, `data`,
   `conventions`, `notes`, `knowledge`, `observability`; merge keys and empty masks per flow-core §0.
   Keep the source of every effective value. Both absent → §1.5 runs with **every** key empty (all
@@ -224,12 +227,22 @@ refuse) · **degraded** (it runs, quietly worse than the config promises), plus
   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` answers, and the number matches this 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. A version *behind* the plugin's is the one that misleads, because the commands then
-  describe flags the installed CLI does not have: report both numbers and let the reader decide.
-  This is the only check here about something no install step of ours puts on the machine.
+  `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.opencode.md`.
   Missing → every phase command runs without its shared rules; fix: reinstall or update the plugin.
 

package/adapters/opencode/commands/flow-feat-review.md

@@ -26,8 +26,8 @@ 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 bundle --checks` prints
-  one context pack for this branch — worklist, the diff (minus `git.diff_exclude`), the changed files
+- **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
@@ -37,8 +37,15 @@ Mandatory review phase. **`/flow-feat-ship` cannot run without passing through h
   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 review`, which spawns that command once per role over the pack above — **one
+  `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

package/bin/cli.mjs

@@ -201,6 +201,7 @@ function check() {
 
 const MAX_FILE_BYTES = 64 * 1024
 const MAX_TOTAL_BYTES = 512 * 1024
+const MAX_DIFF_LINES = 2000
 
 function git(args, cwd = process.cwd()) {
   try {
@@ -215,6 +216,15 @@ function git(args, cwd = process.cwd()) {
 // `FLOW.md` is `## section` then `- key: value`, with an indented `- item` list where a key
 // has no inline value. `conventions` carries bare prose lines and is skipped by the same
 // rule that skips anything else without a `key:`.
+// A value wrapped in matching quotes means what is inside them. The template writes globs
+// that way (`- '*.lock'`), and keeping the quotes turned every one of them into a pathspec
+// that matches a filename with quotes in it — so the key silently excluded nothing. Only a
+// whole-value wrap is stripped: a command that quotes one of its own arguments is untouched.
+function unquote(v) {
+  const m = /^(['"])([\s\S]*)\1$/.exec(v)
+  return m ? m[2] : v
+}
+
 function parseFlow(text) {
   const out = {}
   let section = null
@@ -230,13 +240,13 @@ function parseFlow(text) {
     if (!section) continue
     const item = /^\s+-\s+(.*)$/.exec(line)
     if (item && listKey) {
-      out[section][listKey].push(item[1].trim())
+      out[section][listKey].push(unquote(item[1].trim()))
       continue
     }
     const kv = /^-\s+`?([a-z_]+)`?:\s*(.*)$/.exec(line)
     if (!kv) { listKey = null; continue }
     const [, key, value] = kv
-    if (value.trim()) { out[section][key] = value.trim(); listKey = null }
+    if (value.trim()) { out[section][key] = unquote(value.trim()); listKey = null }
     else { out[section][key] = []; listKey = key }
   }
   // A key with no inline value opens a list. One that never got an item is simply unset —
@@ -248,11 +258,25 @@ function parseFlow(text) {
   return out
 }
 
+// Where the FLOW files actually are. A phase run inside a linked worktree has its own root,
+// and a `FLOW.md` the repo git-ignores exists only in the main checkout — so a worktree would
+// resolve every key to its fallback and say nothing. Prefer the root we are in (a repo that
+// commits its config gets it in every worktree, and a worktree may legitimately differ), and
+// fall back to the main checkout, which `--git-common-dir` points into from anywhere.
+function configRoot(repo) {
+  if (existsSync(join(repo, 'FLOW.md'))) return repo
+  const common = git(['rev-parse', '--path-format=absolute', '--git-common-dir'], repo).trim()
+  if (!common) return repo
+  const main = dirname(common)
+  return main !== repo && existsSync(join(main, 'FLOW.md')) ? main : repo
+}
+
 // Base file plus the overlay of the harness running this, exactly as flow-core §0 resolves
 // it: a key present in the overlay replaces the base value.
 function flowConfig(repo, harness) {
+  const root = configRoot(repo)
   const read = (name) => {
-    const p = join(repo, name)
+    const p = join(root, name)
     return existsSync(p) ? parseFlow(readFileSync(p, 'utf8')) : {}
   }
   const base = read('FLOW.md')
@@ -298,6 +322,7 @@ function buildBundle(argv) {
   const cfg = flowConfig(repo, flag('--harness'))
   const branch = git(['rev-parse', '--abbrev-ref', 'HEAD'], repo).trim()
   const maxFile = Number(flag('--max-file-bytes', MAX_FILE_BYTES)) || MAX_FILE_BYTES
+  const maxDiffLines = Number(flag('--max-diff-lines', MAX_DIFF_LINES)) || MAX_DIFF_LINES
 
   const resolves = (ref) => Boolean(git(['rev-parse', '--verify', '--quiet', ref], repo).trim())
   let base = flag('--base') || cfg.git?.default_base || ''
@@ -324,15 +349,39 @@ function buildBundle(argv) {
   const excluded = (list) => ['--', '.', ...list.map((p) => `:(exclude)${p}`)]
   const paths = exclude.length ? excluded(exclude) : []
 
-  // One size rule for the whole pack. Applying it only to the file contents would let a
-  // generated file of any size through in the diff instead — which is the same cost, one
-  // section lower down, and exactly what a reviewer does not need to read.
+  // Two limits, because how big a file is and how big its change is are different questions,
+  // and one rule for both answers neither. A 1 MB source file with a 40-line edit belongs in
+  // the diff and not in the contents — measuring it by its size drops the change this pack
+  // exists to carry, and says so in a section nobody reads before the diff they were handed.
+  // A file whose *diff* is enormous is the one a reviewer cannot use, and a generated file
+  // nobody reviews at all belongs in `git.diff_exclude`, which is the key for exactly that.
   const changed = git(['diff', '--name-only', from, ...paths], repo).split('\n').filter(Boolean)
+
+  // `--numstat -z`: `<add>\t<del>\t<path>\0`, and for a rename an empty path field followed by
+  // the old and new paths as their own records. A path we fail to match simply keeps its diff,
+  // which is the safe direction for a rule whose failure mode was dropping too much.
+  const churn = new Map()
+  const fields = git(['diff', '--numstat', '-z', from, ...paths], repo).split('\0')
+  for (let i = 0; i < fields.length; i += 1) {
+    const m = /^(\d+|-)\t(\d+|-)\t(.*)$/.exec(fields[i])
+    if (!m) continue
+    let rel = m[3]
+    if (!rel) { rel = fields[i + 2] ?? ''; i += 2 }       // rename: old, new
+    if (!rel) continue
+    churn.set(rel, m[1] === '-' || m[2] === '-' ? null : Number(m[1]) + Number(m[2]))
+  }
+  const unreadableDiff = changed.filter((rel) => {
+    const n = churn.get(rel)
+    return n === null || (n !== undefined && n > maxDiffLines)
+  })
+  const diffPaths = excluded([...exclude, ...unreadableDiff])
+
+  // The contents section keeps the file-size rule: it is the one place a file's own size is
+  // what it costs.
   const oversize = changed.filter((rel) => {
     const abs = join(repo, rel)
     return existsSync(abs) && statSync(abs).size > maxFile
   })
-  const diffPaths = excluded([...exclude, ...oversize])
 
   const out = []
   out.push(`# flow bundle — ${branch}`)
@@ -343,13 +392,24 @@ function buildBundle(argv) {
 
   out.push('## Worklist')
   out.push('')
-  const stat = git(['diff', '--stat', from, ...diffPaths], repo).trim()
+  // The whole change, not the part that survived the limits below: a worklist that agrees
+  // with a reduced diff is how a reviewer reads half a change and never finds out.
+  const stat = git(['diff', '--stat', from, ...paths], repo).trim()
   out.push(stat ? fence(stat) : '_no changes against the base_')
   out.push('')
   if (exclude.length) {
     out.push(`Left out by \`git.diff_exclude\`: ${exclude.map((p) => `\`${p}\``).join(' · ')}`)
     out.push('')
   }
+  if (unreadableDiff.length) {
+    out.push('**Not in the diff below**, over `--max-diff-lines` (' + maxDiffLines + ') or binary — read these from git before reviewing them:')
+    out.push('')
+    out.push(unreadableDiff.map((rel) => {
+      const n = churn.get(rel)
+      return `- \`${rel}\` — ${n === null ? 'binary' : `${n} changed lines`}`
+    }).join('\n'))
+    out.push('')
+  }
   const untracked = git(['ls-files', '--others', '--exclude-standard'], repo).trim()
   if (untracked) {
     out.push('Untracked, so absent from the diff below:')
@@ -368,7 +428,7 @@ function buildBundle(argv) {
   out.push('')
   const skipped = oversize.map((rel) => {
     const size = statSync(join(repo, rel)).size
-    return `${rel} — ${size} bytes, over --max-file-bytes (${maxFile}); left out of the diff too`
+    return `${rel} — ${size} bytes, over --max-file-bytes (${maxFile}); its diff is above`
   })
   let spent = 0
   for (const rel of changed) {
@@ -712,7 +772,8 @@ function usage() {
 
   npx flow-workflows install <harness> [project]
   npx flow-workflows check
-  npx flow-workflows bundle [--base <ref>] [--checks] [--harness <name>] [--max-file-bytes N]
+  npx flow-workflows bundle [--base <ref>] [--checks] [--harness <name>]
+                            [--max-file-bytes N] [--max-diff-lines N]
   npx flow-workflows review [--out <file>] [--record] [same options as bundle]
   npx flow-workflows cost
 
@@ -726,6 +787,11 @@ Claude Code and Codex CLI have their own marketplaces:
   files in full, and the work's handoff — so a phase reads it in one call instead of
   rediscovering it in ten. --checks also runs quality.static_analysis and copies its
   output out verbatim. Paths in git.diff_exclude are left out of the diff.
+  Two limits, two questions: --max-file-bytes decides what is too big to print in full,
+  --max-diff-lines what is too big to read as a diff. A large file with a small change
+  keeps its diff; the worklist always shows the whole change, and anything held back is
+  named there rather than at the end. FLOW.md is read from the main checkout when this
+  runs inside a worktree that does not carry one.
 
 "review" runs one reviewer per role through agents.exec_cmd — any non-interactive
   harness invocation — over that same pack, one turn each instead of an agentic loop

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flow-workflows",
-  "version": "0.65.0-rc.1",
+  "version": "0.65.0-rc.3",
   "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.65.0-rc.1",
+  "version": "0.65.0-rc.3",
   "author": {
     "name": "Alberto Vioque",
     "email": "mashware@gmail.com"

package/plugins/flow/CHANGELOG.md

@@ -8,10 +8,10 @@ The canonical, richest notes live in the [GitHub Releases](https://github.com/ma
 ## 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.
+- **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. Two limits govern it, because how big a file is and how big its change is are different questions: a large file with a small edit keeps its diff.
 - **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.** Release candidates publish under the `next` channel, so `latest` never moves for a candidate, and four ways to run a branch on a real repo are written down.
+- **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
@@ -56,6 +56,43 @@ at all under `bin/`. And a change to the flow can now be installed before it is
 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.
+
+The second candidate ran the whole flow again and the CLI worked, which is how the next three were
+found — all of them in `bundle`, and all of them the kind that exit 0. **One size rule governed both
+the contents and the diff**, so a 1 MB source file with a 40-line edit lost its diff entirely: the
+pack carried 458 of 974 changed lines and its worklist, counted after the rule, agreed. There are
+two limits now — `--max-file-bytes` decides what is too big to print in full, `--max-diff-lines`
+what is too big to read as a diff — the worklist always counts the whole change, and anything held
+back is named there rather than at the end, before the diff it is missing from. **`FLOW.md` was read
+from wherever the command ran**, and with `git.worktree` set that is a worktree, where a git-ignored
+config does not exist: every key resolved to its fallback and nothing said so, which is
+indistinguishable from a repo that has no configuration. Both the CLI and flow-core §0 now fall back
+to the main checkout, which `--git-common-dir` locates from anywhere. And **a quoted value kept its
+quotes**, so the `- '*.lock'` the template itself documents became a pathspec matching a filename
+with quotes in it — `git.diff_exclude` excluded nothing for anyone who copied the example.
+
+None of the three could be seen from the repo, and none of them failed. That is the argument for
+driving a candidate through a real work rather than reading it: the run that found them is also the
+one whose review then read the diff from git and caught five blocking defects anyway, because the
+fallback is a real path and not an apology.
+
 ## v0.64.0 — Announcing the next step was how the run ended  ·  2026-09-16
 
 **In short**