flow-workflows 0.65.0-rc.2 → 0.65.0-rc.4

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.65.0-rc.2`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.65.0-rc.4`.** 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
@@ -27,6 +27,16 @@ a command relies on is simply absent in that session, and nothing else will repo
 
 ## 0. Effective FLOW config — base plus harness overlay
 
+- **Look before you read.** The first thing a phase does about configuration is list what is there:
+  `ls <root>/FLOW*.md` (the root being the one the next bullet resolves). One call, and it is not
+  optional — **an overlay you did not list is an overlay you did not read**, and nothing downstream
+  will notice. This is not a hypothetical: every command below, and every artifact they write,
+  refers to the effective configuration as "`FLOW.md`", which is a file that exists, so reading it
+  and stopping feels finished. Two real sessions in a row read the base in full and never went
+  looking for the overlay sitting beside it — the models it set were silently the defaults, and
+  both runs reported the keys as unset with no way to tell that apart from a repo that never set
+  them. **Name the files this listing found the first time a phase reports any configured value**,
+  so a missed overlay is visible in the artifact rather than invisible everywhere.
 - Read `FLOW.md` at the repo root as the base, then the optional overlay for the harness running
   this command: `FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`, or
   `FLOW.hermes.md`. The
@@ -34,12 +44,24 @@ a command relies on is simply absent in that session, and nothing else will repo
   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
   `FLOW.md` still names a Claude model. A list-valued key is replaced as a whole, never appended.
   `conventions` is the one unkeyed section: its overlay lines are added after the base lines, so
-  both sets apply. Keep the source file of every effective value; `doctor` reports it and later
+  both sets apply. **Every value carries the file it came from**, and a phase that prints a value
+  prints that file with it — "`agents: opus` (`FLOW.claude.md`)", never the value alone. `doctor` reports it and later
   edits preserve it.
 - The sections in either file are tracker, git, autonomy, quality, agents, models, data,
   conventions, notes, knowledge, and observability. Both files missing, or an effective empty key

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

@@ -162,7 +162,7 @@ Cost line: count every subagent this command launched — reviewers = §2.1 buil
 - Measured cost: <what the harness reported for this round, when it reported anything — `flow review --record` writes it to `meta.json.cost[]` and `$flow-work-status` and `flow cost` read it back. A harness that reports no figure is recorded as "not reported": the subagent count above is a headcount, not a cost, and a guess is worse than a gap.>
 - Effective size: <diff size (N changed lines) vs `meta.json.size`, which the tier used, and — when the diff landed within 10% under a tier threshold — that fact (§2.0)>
 - Review path: <the two paths this round actually took: `flow bundle` or git for the material, `flow review` or the agentic panel for the reviewers — each with the reason when it was the fallback (no CLI, non-zero exit, `agents.exec_cmd` empty, every role empty). Without this line a round that skipped the CLI reads exactly like one that used it.>
-- Agent models: <the value of `models.workers`/`models.agents` when set; otherwise "inherited from this thread"; agents named in `agents.<role>` keep their own definition's model>
+- Agent models: <the value of `models.workers`/`models.agents` **with the file each came from** (flow-core §0) when set; otherwise "inherited from this thread", naming the config files you listed; agents named in `agents.<role>` keep their own definition's model>
 - Defaults used: <every empty `FLOW.md` key this round resolved with its default — one per line as `key → default` — or "none". In `guided`/`auto` each is also an entry in `meta.json.defaults_used[]` (flow-core §0); in `manual` the phase may offer one of them at its stop.>
 - Skipped for budget: <phases dropped by §2.0's give-up order, or "none">
 - Blockers: N

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

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

@@ -310,7 +310,7 @@ Write `.claude/work/<TICKET>/06-review.md`. The `Cost:` line of `## Summary` is
 - Review tier: <full | proportional | light — which reviewers ran, at what built-in effort (medium/high/xhigh/max), and why, per §2.0>
 - Effective size: <diff size (N changed lines) vs `meta.json.size`, which of the two the tier used, and — when the diff pointed higher — that the work may be misclassified. When the diff landed within 10% under a tier threshold, say so here (§2.0).>
 - Review path: <the two paths this round actually took: `flow bundle` or git for the material, `flow review` or the agentic panel for the reviewers — each with the reason when it was the fallback (no CLI, non-zero exit, `agents.exec_cmd` empty, every role empty). Without this line a round that skipped the CLI reads exactly like one that used it.>
-- Agent models: <the value of `models.workers`/`models.agents` when set; otherwise "inherited from this thread" — plus, when the panel ran, that agents named in `agents.<role>` kept the model their own definition sets. The values as they are, no judgement on them>
+- Agent models: <the value of `models.workers`/`models.agents` **with the file each came from** (flow-core §0) when set; otherwise "inherited from this thread", naming the config files you listed — "unset" without them reads the same whether the overlay was empty or never opened — plus, when the panel ran, that agents named in `agents.<role>` kept the model their own definition sets. The values as they are, no judgement on them>
 - Cost: <n>/<budget_max> subagents launched (<k> reviewers · <m> reinforcements · <s> skeptics), tier <light|proportional|full>, effort <medium|high|xhigh|max>
 - Measured cost: <what the harness reported for this round, when it reported anything — `flow review --record` writes it to `meta.json.cost[]` and `$flow-work-status` and `flow cost` read it back. A harness that reports no figure is recorded as "not reported": the subagent count above is a headcount, not a cost, and a guess is worse than a gap.>
 - Agents launched: <ran vs defined — `N/M` of the `review_skill`/`reviewers` roster, naming any that did not run (with the reason) and any substitution; "built-in only" if §2.0 selected no panel>

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.65.0-rc.2`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.65.0-rc.4`.** 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
@@ -26,6 +26,16 @@ a command relies on is simply absent in that session, and nothing else will repo
 
 ## 0. Effective FLOW config — base plus harness overlay
 
+- **Look before you read.** The first thing a phase does about configuration is list what is there:
+  `ls <root>/FLOW*.md` (the root being the one the next bullet resolves). One call, and it is not
+  optional — **an overlay you did not list is an overlay you did not read**, and nothing downstream
+  will notice. This is not a hypothetical: every command below, and every artifact they write,
+  refers to the effective configuration as "`FLOW.md`", which is a file that exists, so reading it
+  and stopping feels finished. Two real sessions in a row read the base in full and never went
+  looking for the overlay sitting beside it — the models it set were silently the defaults, and
+  both runs reported the keys as unset with no way to tell that apart from a repo that never set
+  them. **Name the files this listing found the first time a phase reports any configured value**,
+  so a missed overlay is visible in the artifact rather than invisible everywhere.
 - Read `FLOW.md` at the repo root as the base, then the optional overlay for the harness running
   this command: `FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`, or
   `FLOW.hermes.md`. The
@@ -33,12 +43,24 @@ a command relies on is simply absent in that session, and nothing else will repo
   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
   `FLOW.md` still names a Claude model. A list-valued key is replaced as a whole, never appended.
   `conventions` is the one unkeyed section: its overlay lines are added after the base lines, so
-  both sets apply. Keep the source file of every effective value; `doctor` reports it and later
+  both sets apply. **Every value carries the file it came from**, and a phase that prints a value
+  prints that file with it — "`agents: opus` (`FLOW.claude.md`)", never the value alone. `doctor` reports it and later
   edits preserve it.
 - The sections in either file are tracker, git, autonomy, quality, agents, models, data,
   conventions, notes, knowledge, and observability. Both files missing, or an effective empty key

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

@@ -158,7 +158,7 @@ Cost line: count every subagent this command launched — reviewers = §2.1 buil
 - Measured cost: <what the harness reported for this round, when it reported anything — `flow review --record` writes it to `meta.json.cost[]` and `/flow:work:status` and `flow cost` read it back. A harness that reports no figure is recorded as "not reported": the subagent count above is a headcount, not a cost, and a guess is worse than a gap.>
 - Effective size: <diff size (N changed lines) vs `meta.json.size`, which the tier used, and — when the diff landed within 10% under a tier threshold — that fact (§2.0)>
 - Review path: <the two paths this round actually took: `flow bundle` or git for the material, `flow review` or the agentic panel for the reviewers — each with the reason when it was the fallback (no CLI, non-zero exit, `agents.exec_cmd` empty, every role empty). Without this line a round that skipped the CLI reads exactly like one that used it.>
-- Agent models: <the value of `models.workers`/`models.agents` when set; otherwise "inherited from this thread"; agents named in `agents.<role>` keep their own definition's model>
+- Agent models: <the value of `models.workers`/`models.agents` **with the file each came from** (flow-core §0) when set; otherwise "inherited from this thread", naming the config files you listed; agents named in `agents.<role>` keep their own definition's model>
 - Defaults used: <every empty `FLOW.md` key this round resolved with its default — one per line as `key → default` — or "none". In `guided`/`auto` each is also an entry in `meta.json.defaults_used[]` (flow-core §0); in `manual` the phase may offer one of them at its stop.>
 - Skipped for budget: <phases dropped by §2.0's give-up order, or "none">
 - Blockers: N

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

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

@@ -306,7 +306,7 @@ Write `.claude/work/<TICKET>/06-review.md`. The `Cost:` line of `## Summary` is
 - Review tier: <full | proportional | light — which reviewers ran, at what built-in effort (medium/high/xhigh/max), and why, per §2.0>
 - Effective size: <diff size (N changed lines) vs `meta.json.size`, which of the two the tier used, and — when the diff pointed higher — that the work may be misclassified. When the diff landed within 10% under a tier threshold, say so here (§2.0).>
 - Review path: <the two paths this round actually took: `flow bundle` or git for the material, `flow review` or the agentic panel for the reviewers — each with the reason when it was the fallback (no CLI, non-zero exit, `agents.exec_cmd` empty, every role empty). Without this line a round that skipped the CLI reads exactly like one that used it.>
-- Agent models: <the value of `models.workers`/`models.agents` when set; otherwise "inherited from this thread" — plus, when the panel ran, that agents named in `agents.<role>` kept the model their own definition sets. The values as they are, no judgement on them>
+- Agent models: <the value of `models.workers`/`models.agents` **with the file each came from** (flow-core §0) when set; otherwise "inherited from this thread", naming the config files you listed — "unset" without them reads the same whether the overlay was empty or never opened — plus, when the panel ran, that agents named in `agents.<role>` kept the model their own definition sets. The values as they are, no judgement on them>
 - Cost: <n>/<budget_max> subagents launched (<k> reviewers · <m> reinforcements · <s> skeptics), tier <light|proportional|full>, effort <medium|high|xhigh|max>
 - Measured cost: <what the harness reported for this round, when it reported anything — `flow review --record` writes it to `meta.json.cost[]` and `/flow:work:status` and `flow cost` read it back. A harness that reports no figure is recorded as "not reported": the subagent count above is a headcount, not a cost, and a guess is worse than a gap.>
 - Agents launched: <ran vs defined — `N/M` of the `review_skill`/`reviewers` roster, naming any that did not run (with the reason) and any substitution; "built-in only" if §2.0 selected no panel>

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.65.0-rc.2`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.65.0-rc.4`.** 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
@@ -27,6 +27,16 @@ a command relies on is simply absent in that session, and nothing else will repo
 
 ## 0. Effective FLOW config — base plus harness overlay
 
+- **Look before you read.** The first thing a phase does about configuration is list what is there:
+  `ls <root>/FLOW*.md` (the root being the one the next bullet resolves). One call, and it is not
+  optional — **an overlay you did not list is an overlay you did not read**, and nothing downstream
+  will notice. This is not a hypothetical: every command below, and every artifact they write,
+  refers to the effective configuration as "`FLOW.md`", which is a file that exists, so reading it
+  and stopping feels finished. Two real sessions in a row read the base in full and never went
+  looking for the overlay sitting beside it — the models it set were silently the defaults, and
+  both runs reported the keys as unset with no way to tell that apart from a repo that never set
+  them. **Name the files this listing found the first time a phase reports any configured value**,
+  so a missed overlay is visible in the artifact rather than invisible everywhere.
 - Read `FLOW.md` at the repo root as the base, then the optional overlay for the harness running
   this command: `FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`, or
   `FLOW.hermes.md`. The
@@ -34,12 +44,24 @@ a command relies on is simply absent in that session, and nothing else will repo
   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
   `FLOW.md` still names a Claude model. A list-valued key is replaced as a whole, never appended.
   `conventions` is the one unkeyed section: its overlay lines are added after the base lines, so
-  both sets apply. Keep the source file of every effective value; `doctor` reports it and later
+  both sets apply. **Every value carries the file it came from**, and a phase that prints a value
+  prints that file with it — "`agents: opus` (`FLOW.claude.md`)", never the value alone. `doctor` reports it and later
   edits preserve it.
 - The sections in either file are tracker, git, autonomy, quality, agents, models, data,
   conventions, notes, knowledge, and observability. Both files missing, or an effective empty key

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

@@ -162,7 +162,7 @@ Cost line: count every subagent this command launched — reviewers = §2.1 buil
 - Measured cost: <what the harness reported for this round, when it reported anything — `flow review --record` writes it to `meta.json.cost[]` and `/flow-work-status` and `flow cost` read it back. A harness that reports no figure is recorded as "not reported": the subagent count above is a headcount, not a cost, and a guess is worse than a gap.>
 - Effective size: <diff size (N changed lines) vs `meta.json.size`, which the tier used, and — when the diff landed within 10% under a tier threshold — that fact (§2.0)>
 - Review path: <the two paths this round actually took: `flow bundle` or git for the material, `flow review` or the agentic panel for the reviewers — each with the reason when it was the fallback (no CLI, non-zero exit, `agents.exec_cmd` empty, every role empty). Without this line a round that skipped the CLI reads exactly like one that used it.>
-- Agent models: <the value of `models.workers`/`models.agents` when set; otherwise "inherited from this thread"; agents named in `agents.<role>` keep their own definition's model>
+- Agent models: <the value of `models.workers`/`models.agents` **with the file each came from** (flow-core §0) when set; otherwise "inherited from this thread", naming the config files you listed; agents named in `agents.<role>` keep their own definition's model>
 - Defaults used: <every empty `FLOW.md` key this round resolved with its default — one per line as `key → default` — or "none". In `guided`/`auto` each is also an entry in `meta.json.defaults_used[]` (flow-core §0); in `manual` the phase may offer one of them at its stop.>
 - Skipped for budget: <phases dropped by §2.0's give-up order, or "none">
 - Blockers: N

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

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

@@ -310,7 +310,7 @@ Write `.claude/work/<TICKET>/06-review.md`. The `Cost:` line of `## Summary` is
 - Review tier: <full | proportional | light — which reviewers ran, at what built-in effort (medium/high/xhigh/max), and why, per §2.0>
 - Effective size: <diff size (N changed lines) vs `meta.json.size`, which of the two the tier used, and — when the diff pointed higher — that the work may be misclassified. When the diff landed within 10% under a tier threshold, say so here (§2.0).>
 - Review path: <the two paths this round actually took: `flow bundle` or git for the material, `flow review` or the agentic panel for the reviewers — each with the reason when it was the fallback (no CLI, non-zero exit, `agents.exec_cmd` empty, every role empty). Without this line a round that skipped the CLI reads exactly like one that used it.>
-- Agent models: <the value of `models.workers`/`models.agents` when set; otherwise "inherited from this thread" — plus, when the panel ran, that agents named in `agents.<role>` kept the model their own definition sets. The values as they are, no judgement on them>
+- Agent models: <the value of `models.workers`/`models.agents` **with the file each came from** (flow-core §0) when set; otherwise "inherited from this thread", naming the config files you listed — "unset" without them reads the same whether the overlay was empty or never opened — plus, when the panel ran, that agents named in `agents.<role>` kept the model their own definition sets. The values as they are, no judgement on them>
 - Cost: <n>/<budget_max> subagents launched (<k> reviewers · <m> reinforcements · <s> skeptics), tier <light|proportional|full>, effort <medium|high|xhigh|max>
 - Measured cost: <what the harness reported for this round, when it reported anything — `flow review --record` writes it to `meta.json.cost[]` and `/flow-work-status` and `flow cost` read it back. A harness that reports no figure is recorded as "not reported": the subagent count above is a headcount, not a cost, and a guess is worse than a gap.>
 - Agents launched: <ran vs defined — `N/M` of the `review_skill`/`reviewers` roster, naming any that did not run (with the reason) and any substitution; "built-in only" if §2.0 selected no panel>

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.65.0-rc.2`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.65.0-rc.4`.** 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
@@ -26,6 +26,16 @@ a command relies on is simply absent in that session, and nothing else will repo
 
 ## 0. Effective FLOW config — base plus harness overlay
 
+- **Look before you read.** The first thing a phase does about configuration is list what is there:
+  `ls <root>/FLOW*.md` (the root being the one the next bullet resolves). One call, and it is not
+  optional — **an overlay you did not list is an overlay you did not read**, and nothing downstream
+  will notice. This is not a hypothetical: every command below, and every artifact they write,
+  refers to the effective configuration as "`FLOW.md`", which is a file that exists, so reading it
+  and stopping feels finished. Two real sessions in a row read the base in full and never went
+  looking for the overlay sitting beside it — the models it set were silently the defaults, and
+  both runs reported the keys as unset with no way to tell that apart from a repo that never set
+  them. **Name the files this listing found the first time a phase reports any configured value**,
+  so a missed overlay is visible in the artifact rather than invisible everywhere.
 - Read `FLOW.md` at the repo root as the base, then the optional overlay for the harness running
   this command: `FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`, or
   `FLOW.hermes.md`. The
@@ -33,12 +43,24 @@ a command relies on is simply absent in that session, and nothing else will repo
   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
   `FLOW.md` still names a Claude model. A list-valued key is replaced as a whole, never appended.
   `conventions` is the one unkeyed section: its overlay lines are added after the base lines, so
-  both sets apply. Keep the source file of every effective value; `doctor` reports it and later
+  both sets apply. **Every value carries the file it came from**, and a phase that prints a value
+  prints that file with it — "`agents: opus` (`FLOW.claude.md`)", never the value alone. `doctor` reports it and later
   edits preserve it.
 - The sections in either file are tracker, git, autonomy, quality, agents, models, data,
   conventions, notes, knowledge, and observability. Both files missing, or an effective empty key

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

@@ -160,7 +160,7 @@ Cost line: count every subagent this command launched — reviewers = §2.1 buil
 - Measured cost: <what the harness reported for this round, when it reported anything — `flow review --record` writes it to `meta.json.cost[]` and `/flow-work-status` and `flow cost` read it back. A harness that reports no figure is recorded as "not reported": the subagent count above is a headcount, not a cost, and a guess is worse than a gap.>
 - Effective size: <diff size (N changed lines) vs `meta.json.size`, which the tier used, and — when the diff landed within 10% under a tier threshold — that fact (§2.0)>
 - Review path: <the two paths this round actually took: `flow bundle` or git for the material, `flow review` or the agentic panel for the reviewers — each with the reason when it was the fallback (no CLI, non-zero exit, `agents.exec_cmd` empty, every role empty). Without this line a round that skipped the CLI reads exactly like one that used it.>
-- Agent models: <the value of `models.workers`/`models.agents` when set; otherwise "inherited from this thread"; agents named in `agents.<role>` keep their own definition's model>
+- Agent models: <the value of `models.workers`/`models.agents` **with the file each came from** (flow-core §0) when set; otherwise "inherited from this thread", naming the config files you listed; agents named in `agents.<role>` keep their own definition's model>
 - Defaults used: <every empty `FLOW.md` key this round resolved with its default — one per line as `key → default` — or "none". In `guided`/`auto` each is also an entry in `meta.json.defaults_used[]` (flow-core §0); in `manual` the phase may offer one of them at its stop.>
 - Skipped for budget: <phases dropped by §2.0's give-up order, or "none">
 - Blockers: N

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

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

@@ -308,7 +308,7 @@ Write `.claude/work/<TICKET>/06-review.md`. The `Cost:` line of `## Summary` is
 - Review tier: <full | proportional | light — which reviewers ran, at what built-in effort (medium/high/xhigh/max), and why, per §2.0>
 - Effective size: <diff size (N changed lines) vs `meta.json.size`, which of the two the tier used, and — when the diff pointed higher — that the work may be misclassified. When the diff landed within 10% under a tier threshold, say so here (§2.0).>
 - Review path: <the two paths this round actually took: `flow bundle` or git for the material, `flow review` or the agentic panel for the reviewers — each with the reason when it was the fallback (no CLI, non-zero exit, `agents.exec_cmd` empty, every role empty). Without this line a round that skipped the CLI reads exactly like one that used it.>
-- Agent models: <the value of `models.workers`/`models.agents` when set; otherwise "inherited from this thread" — plus, when the panel ran, that agents named in `agents.<role>` kept the model their own definition sets. The values as they are, no judgement on them>
+- Agent models: <the value of `models.workers`/`models.agents` **with the file each came from** (flow-core §0) when set; otherwise "inherited from this thread", naming the config files you listed — "unset" without them reads the same whether the overlay was empty or never opened — plus, when the panel ran, that agents named in `agents.<role>` kept the model their own definition sets. The values as they are, no judgement on them>
 - Cost: <n>/<budget_max> subagents launched (<k> reviewers · <m> reinforcements · <s> skeptics), tier <light|proportional|full>, effort <medium|high|xhigh|max>
 - Measured cost: <what the harness reported for this round, when it reported anything — `flow review --record` writes it to `meta.json.cost[]` and `/flow-work-status` and `flow cost` read it back. A harness that reports no figure is recorded as "not reported": the subagent count above is a headcount, not a cost, and a guess is worse than a gap.>
 - Agents launched: <ran vs defined — `N/M` of the `review_skill`/`reviewers` roster, naming any that did not run (with the reason) and any substitution; "built-in only" if §2.0 selected no panel>

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,36 @@ 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
+}
+
+// Which config files a run actually read. The pack says so out loud because the failure it
+// makes visible is silent by nature: a phase that read the base and never looked for the
+// overlay reports every key it set as unset, which is what a repo with no overlay reports too.
+function configFiles(repo, harness) {
+  const root = configRoot(repo)
+  const names = ['FLOW.md', harness && `FLOW.${harness}.md`].filter(Boolean)
+  const found = names.filter((n) => existsSync(join(root, n)))
+  const where = root === repo ? '' : ` (from ${root})`
+  return found.length ? found.join(' + ') + where : `none found${where || ` in ${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 +333,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,32 +360,68 @@ 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}`)
   out.push('')
   out.push(`Base \`${base}\` · merge base \`${from.slice(0, 12)}\` · generated by \`flow bundle\`.`)
+  out.push(`Config read: ${configFiles(repo, flag('--harness'))}.`)
   out.push('Committed and uncommitted changes together. Nothing here is parsed or summarised.')
   out.push('')
 
   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 +440,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 +784,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 +799,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.2",
+  "version": "0.65.0-rc.4",
   "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.2",
+  "version": "0.65.0-rc.4",
   "author": {
     "name": "Alberto Vioque",
     "email": "mashware@gmail.com"

package/plugins/flow/CHANGELOG.md

@@ -8,7 +8,7 @@ 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 — 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.
@@ -74,6 +74,37 @@ What made all of this visible was the `Review path` line added above — a round
 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.
+
+The third candidate then found the one that had been hiding behind them. A harness overlay —
+`FLOW.claude.md` and its siblings, where a model id belongs so it never reaches another harness —
+**was never read**. Not once, in two full runs, on two different models: both read the base file in
+full and neither went looking for the overlay beside it, so the models it set were silently the
+defaults and both artifacts reported the keys as *unset* — which is exactly what a repo that never
+set them reports. The instruction to merge an overlay has always been there; what was missing was
+anything that made a phase **look**. Every command, and every artifact they write, calls the
+effective configuration "`FLOW.md`", and that is a real file, so reading it and stopping feels
+finished. Step 0 now begins by listing `FLOW*.md` — one call, not optional — every printed value
+carries the file it came from, and `bundle` states in its header which files the run read, so an
+overlay that was never opened is a line in the pack instead of nothing at all.
+
+None of the four 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**