flow-workflows 0.89.0 → 0.90.0

package/adapters/codex/CORE.md

@@ -17,7 +17,7 @@ Every `$flow-*` command assumes these rules. They are stated once, here, so a co
 carries what is specific to its phase. Read this once per session; a command that says "load
 `flow-core`" means this file.
 
-**This file belongs to flow `0.89.0`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.90.0`.** Compare it once, at the start of the session, against
 `version` in `~/.claude/flow/.claude-plugin/plugin.json`. The two differing means the session
 is running a **mixture** — the commands from one copy of the plugin, these shared rules from another
 — which is exactly what happens when a branch or a release candidate is loaded over an installed

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

@@ -185,9 +185,9 @@ With an "all threads resolved before merge" policy, the MR/PR cannot be merged o
 
 ### 3.3 Performance comment
 
-`$flow-feat-ship` §4.3, unchanged: query rows from `06-review.md` and benchmark rows from
-`05-validation.md`, posted as a comment on the MR/PR, confirmed in every mode, nothing posted when
-nothing was measured. A slowness bug is the case where this comment *is* the proof the fix worked.
+`$flow-feat-ship` §4.3, unchanged: query rows from `06-review.md` — a modified query that was not
+measured included, as `not measured (<reason>)` — and benchmark rows from `05-validation.md`,
+posted as comments anchored on the changed lines of the MR/PR, confirmed in every mode. A slowness bug is the case where this comment *is* the proof the fix worked.
 
 ## 4. Close
 

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

@@ -212,6 +212,8 @@ Judging rules: **no number, no win** (unresolved is recorded unresolved, never s
 
 **A modified query is judged against its own past, not only against its rivals.** For every query the diff *changes* (as opposed to adds), the duel carries the **base row** — the same query on `git merge-base HEAD <git.default_base>`, measured in the same sandbox with the same seed (`$flow-work-query` §4). Without it the table cannot say whether this diff made things better or worse, which is the one thing a reviewer wants from it.
 
+**A modified query with no plan behind its verdict is recorded `ok (plan not measured)` — and says what would measure it (`data.explain_cmd`, a data set) — never a bare `ok`.** Ship publishes that row on the MR/PR (`$flow-feat-ship` §4.3); a reviewer who finds a plain "ok" and no number has no way to know nobody looked.
+
 Verdicts as findings: **change** = blocker, through §6; **regressed** = blocker unless `03-design.md` justifies the trade, in which case it is stated and published; **schema / follow-up** → proposed ticket in the output **and a `followups[]` entry** (flow-core §7); **unresolved** → recorded literally with the open question (as §3.5). A `change` verdict resting on a measured plan is already confirmed — no §6 skeptic.
 
 ## 4. Over-engineering audit (fit + YAGNI)

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

@@ -240,22 +240,40 @@ Thread body: the SQL block under "Pre-deploy: run this SQL on the server BEFORE
 
 With the repo policy "all threads resolved before merge", the MR/PR cannot merge until the SQL is executed and the thread **resolved**. **One single thread even with multiple statements.** Tell the user it is left open on purpose.
 
-### 4.3 Performance comment (only when there are numbers)
-
-`06-review.md` §"Data-access duel" has rows for modified queries, or `07-validation.md` §3.7 has
-benchmark rows → post them as a **comment** on the MR/PR just created (`gh pr comment` /
-`glab mr note`). Nothing measured → post nothing; an empty performance comment is noise.
-
-A comment, not a description section, because it is **re-posted on every push that changes a
-measured path** (`$flow-work-green`, `$flow-work-respond`), and a description rewritten each round
+### 4.3 Performance comment (every modified query, measured or not)
+
+Post one when `06-review.md` §"Data-access duel" has a row for a **modified** query — **whatever its
+verdict, measured or not** — or `07-validation.md` §3.7 has benchmark rows. New queries only, or
+renames and reformats only, and nothing benchmarked → post nothing.
+
+**A modified query that was never measured is the case this comment exists for.** Silence reads as
+"nothing to see"; a reviewer cannot tell a query that was measured and is fine from one that nobody
+looked at. The row says `not measured (<reason>)` and what would settle it (`data.explain_cmd`, a
+data set, the entry point to run), so the reviewer knows what was *not* checked.
+
+**Where it goes: on the query, not under the title.** One **inline thread anchored to the changed
+lines of that query in the MR/PR diff** (a resolvable GitLab discussion with a `position`; a GitHub
+review comment on `path` + `line`), one per modified query. The entry-point rows anchor to the entry
+point's changed line the same way. Anchoring fails (the line is not in the diff, the forge refuses
+the position) → a general MR/PR comment that names the file and line, and say so. A general comment
+is the fallback, never the default: a number a reviewer meets on the line they are reading is read;
+one at the bottom of the page is not.
+
+Still a comment and not a description section, because it is **re-posted on every push that changes
+a measured path** (`$flow-work-green`, `$flow-work-respond`), and a description rewritten each round
 loses what the numbers were two rounds ago. The history is the point.
 
+For each modified query the comment carries the **plan before and after** — the `data.explain_cmd`
+output on the merge base and on the branch, same data, trimmed to access type, index, rows read — next
+to the numbers:
+
 ```markdown
-## Performance — base `<sha>` → `<sha>`
+## Performance — `FooRepository::findBar()`, base `<sha>` → `<sha>`
 
-| Query | Rows read | Time (min–max, 3 runs) | Verdict |
-|---|---|---|---|
-| `FooRepository::findBar()` | 41k → 750 | 120–131 ms → 8–9 ms | improved |
+| | Plan (access · index · rows read) | Rows returned | Time (min–max, 3 runs) | Verdict |
+|---|---|---|---|---|
+| base | `ref` · `idx_a` · 41k | 15 | 120–131 ms | |
+| now | `range` · `idx_b` · 750 | 15 | 8–9 ms | improved |
 
 | Entry point | Time | Peak memory | Verdict |
 |---|---|---|---|
@@ -265,6 +283,14 @@ Measured on <data set>, <n> runs each. A difference inside the run-to-run spread
 no measurable change, not a percentage.
 ```
 
+- **The query, ready to run where the data is real.** Every performance comment ends with the exact
+  query (as the engine receives it, parameters filled with representative values) and the read-only
+  plan command for it — `EXPLAIN`, never `EXPLAIN ANALYZE` on a write — in a code block, so the
+  author can run it on production or a replica and answer in the thread. This is a complement to the
+  sandbox measurement, never a substitute: the flow does not touch production.
+- **Memory is the entry point's, not the query's.** A modified query also gets the entry-point row
+  that exercises it, through `quality.bench_cmd` on both sides (`$flow-*-validate` §3.7). No
+  `bench_cmd` → the entry-point row says `not measured (no quality.bench_cmd)`; never an estimate.
 - **Verdicts**: `improved` · `no measurable change` · `regressed` · `not measured (<reason>)`.
 - **A `regressed` row is a review blocker** unless `03-design.md` justifies the trade — in which
   case the justification goes in the comment, in one line, next to the row.

package/adapters/codex/skills/flow-work-README/SKILL.md

@@ -50,7 +50,7 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
 - **Understand before starting**: design-affecting doubts left after ticket + knowledge search + code → one `AskUserQuestion` with all of them before closing `$flow-feat-start` or `$flow-feat-design` §1.5.
 - **Reuse before creating**: in `$flow-feat-design`, check the affected and neighbouring modules before any new entity, column, repository, service or event; justify intentional duplication in `03-design.md`; never force a poor fit.
 - **Solve the real project problem, not the generic one (fit + YAGNI)**: before any defensive mechanism, **two questions with evidence** — **(a) Does it fit? Can this scenario actually happen given how this project works?** (knowledge search + code, **not** textbook patterns; already prevented → **unnecessary**); **(b) Do we need it now, for what the ticket asks?** (hypothetical → **don't add it**, "idea for a separate ticket"). Bias **remove, not add** — `$flow-feat-design` challenger ("Fit and need") and the defensive mechanisms table of `03-design.md`.
-- **A change is measured against what it replaces, not only against its rivals**: a **modified** query carries the **base row** — the same query on `git merge-base HEAD <git.default_base>`, same sandbox, same seed, same three runs (`$flow-work-query` §4) — and `quality.bench_cmd` benchmarks a touched route, command, consumer or job on both sides (`$flow-*-validate` §3.7). Times are reported `min–max`, and **a difference inside the spread is "no measurable change", never a percentage**. `regressed` blocks like `change` unless the design justifies the trade. The numbers are posted as an MR/PR **comment** (`ship` §4.3), re-posted whenever a later push changes a measured path.
+- **A change is measured against what it replaces, not only against its rivals**: a **modified** query carries the **base row** — the same query on `git merge-base HEAD <git.default_base>`, same sandbox, same seed, same three runs (`$flow-work-query` §4) — and `quality.bench_cmd` benchmarks a touched route, command, consumer or job on both sides (`$flow-*-validate` §3.7). Times are reported `min–max`, and **a difference inside the spread is "no measurable change", never a percentage**. `regressed` blocks like `change` unless the design justifies the trade. The numbers — or, for a modified query nobody could measure, `not measured` and why — are posted as **inline comments on the changed query** (`ship` §4.3), re-posted whenever a later push changes a measured path.
 - **A query is judged on its plan, not on its prose**: cost lives in the **execution plan**, not the diff. `$flow-work-query`: facts, a challenger blinded to the design's rationale, the main agent judges — **no number, no win**, **no dogma in either direction**, **the objector's variant measured next to yours**. **Any size, XS included.** A performance objection is answered with a plan; an unmeasured plan is never reported as measured ("schema only" / "not measured" are legitimate verdicts; a fixture-sized test database is not evidence).
 - **Size is revisable**: a later phase (`design`, `plan`, `investigate`) seeing a clear mismatch **proposes reclassifying to the user** and updates `meta.json.size`.
 - **If the implementation invalidates the design, return to design**: in `$flow-feat-build`, 2+ significant deviations in `05-implementation.md`, or one changing an ADR-light decision → **pause and return to `$flow-feat-design`** (what `$flow-feat-review` and `$flow-feat-validate` read). Same for `$flow-bug-fix` vs `$flow-bug-investigate`.

package/adapters/codex/skills/flow-work-query/SKILL.md

@@ -149,6 +149,9 @@ Per query, exactly one of:
 
 - **ok** — access supported and bounded; state the index used and rows read. For a modified query,
   say how it compares to the base row: *improved*, *no measurable change*, or *regressed*.
+  **No plan was read → it is `ok (plan not measured)`**, with the reason, never a bare `ok`: a
+  modified query reaches the MR/PR through `$flow-feat-ship` §4.3 and the reviewer must be able to
+  tell it was never measured.
 - **regressed** — measurably worse than the base version, and the design does not justify it. A
   blocker, the same as `change`. Justified in `03-design.md` (a correctness fix that costs time, a
   deliberate trade) → not a blocker, but it is stated in the verdict and it reaches the MR/PR.

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.89.0`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.90.0`.** Compare it once, at the start of the session, against
 `version` in `~/.claude/flow/.claude-plugin/plugin.json`. The two differing means the session
 is running a **mixture** — the commands from one copy of the plugin, these shared rules from another
 — which is exactly what happens when a branch or a release candidate is loaded over an installed

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

@@ -181,9 +181,9 @@ With an "all threads resolved before merge" policy, the MR/PR cannot be merged o
 
 ### 3.3 Performance comment
 
-`/flow:feat:ship` §4.3, unchanged: query rows from `06-review.md` and benchmark rows from
-`05-validation.md`, posted as a comment on the MR/PR, confirmed in every mode, nothing posted when
-nothing was measured. A slowness bug is the case where this comment *is* the proof the fix worked.
+`/flow:feat:ship` §4.3, unchanged: query rows from `06-review.md` — a modified query that was not
+measured included, as `not measured (<reason>)` — and benchmark rows from `05-validation.md`,
+posted as comments anchored on the changed lines of the MR/PR, confirmed in every mode. A slowness bug is the case where this comment *is* the proof the fix worked.
 
 ## 4. Close
 

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

@@ -208,6 +208,8 @@ Judging rules: **no number, no win** (unresolved is recorded unresolved, never s
 
 **A modified query is judged against its own past, not only against its rivals.** For every query the diff *changes* (as opposed to adds), the duel carries the **base row** — the same query on `git merge-base HEAD <git.default_base>`, measured in the same sandbox with the same seed (`/flow:work:query` §4). Without it the table cannot say whether this diff made things better or worse, which is the one thing a reviewer wants from it.
 
+**A modified query with no plan behind its verdict is recorded `ok (plan not measured)` — and says what would measure it (`data.explain_cmd`, a data set) — never a bare `ok`.** Ship publishes that row on the MR/PR (`/flow:feat:ship` §4.3); a reviewer who finds a plain "ok" and no number has no way to know nobody looked.
+
 Verdicts as findings: **change** = blocker, through §6; **regressed** = blocker unless `03-design.md` justifies the trade, in which case it is stated and published; **schema / follow-up** → proposed ticket in the output **and a `followups[]` entry** (flow-core §7); **unresolved** → recorded literally with the open question (as §3.5). A `change` verdict resting on a measured plan is already confirmed — no §6 skeptic.
 
 ## 4. Over-engineering audit (fit + YAGNI)

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

@@ -236,22 +236,40 @@ Thread body: the SQL block under "Pre-deploy: run this SQL on the server BEFORE
 
 With the repo policy "all threads resolved before merge", the MR/PR cannot merge until the SQL is executed and the thread **resolved**. **One single thread even with multiple statements.** Tell the user it is left open on purpose.
 
-### 4.3 Performance comment (only when there are numbers)
-
-`06-review.md` §"Data-access duel" has rows for modified queries, or `07-validation.md` §3.7 has
-benchmark rows → post them as a **comment** on the MR/PR just created (`gh pr comment` /
-`glab mr note`). Nothing measured → post nothing; an empty performance comment is noise.
-
-A comment, not a description section, because it is **re-posted on every push that changes a
-measured path** (`/flow:work:green`, `/flow:work:respond`), and a description rewritten each round
+### 4.3 Performance comment (every modified query, measured or not)
+
+Post one when `06-review.md` §"Data-access duel" has a row for a **modified** query — **whatever its
+verdict, measured or not** — or `07-validation.md` §3.7 has benchmark rows. New queries only, or
+renames and reformats only, and nothing benchmarked → post nothing.
+
+**A modified query that was never measured is the case this comment exists for.** Silence reads as
+"nothing to see"; a reviewer cannot tell a query that was measured and is fine from one that nobody
+looked at. The row says `not measured (<reason>)` and what would settle it (`data.explain_cmd`, a
+data set, the entry point to run), so the reviewer knows what was *not* checked.
+
+**Where it goes: on the query, not under the title.** One **inline thread anchored to the changed
+lines of that query in the MR/PR diff** (a resolvable GitLab discussion with a `position`; a GitHub
+review comment on `path` + `line`), one per modified query. The entry-point rows anchor to the entry
+point's changed line the same way. Anchoring fails (the line is not in the diff, the forge refuses
+the position) → a general MR/PR comment that names the file and line, and say so. A general comment
+is the fallback, never the default: a number a reviewer meets on the line they are reading is read;
+one at the bottom of the page is not.
+
+Still a comment and not a description section, because it is **re-posted on every push that changes
+a measured path** (`/flow:work:green`, `/flow:work:respond`), and a description rewritten each round
 loses what the numbers were two rounds ago. The history is the point.
 
+For each modified query the comment carries the **plan before and after** — the `data.explain_cmd`
+output on the merge base and on the branch, same data, trimmed to access type, index, rows read — next
+to the numbers:
+
 ```markdown
-## Performance — base `<sha>` → `<sha>`
+## Performance — `FooRepository::findBar()`, base `<sha>` → `<sha>`
 
-| Query | Rows read | Time (min–max, 3 runs) | Verdict |
-|---|---|---|---|
-| `FooRepository::findBar()` | 41k → 750 | 120–131 ms → 8–9 ms | improved |
+| | Plan (access · index · rows read) | Rows returned | Time (min–max, 3 runs) | Verdict |
+|---|---|---|---|---|
+| base | `ref` · `idx_a` · 41k | 15 | 120–131 ms | |
+| now | `range` · `idx_b` · 750 | 15 | 8–9 ms | improved |
 
 | Entry point | Time | Peak memory | Verdict |
 |---|---|---|---|
@@ -261,6 +279,14 @@ Measured on <data set>, <n> runs each. A difference inside the run-to-run spread
 no measurable change, not a percentage.
 ```
 
+- **The query, ready to run where the data is real.** Every performance comment ends with the exact
+  query (as the engine receives it, parameters filled with representative values) and the read-only
+  plan command for it — `EXPLAIN`, never `EXPLAIN ANALYZE` on a write — in a code block, so the
+  author can run it on production or a replica and answer in the thread. This is a complement to the
+  sandbox measurement, never a substitute: the flow does not touch production.
+- **Memory is the entry point's, not the query's.** A modified query also gets the entry-point row
+  that exercises it, through `quality.bench_cmd` on both sides (`/flow:*:validate` §3.7). No
+  `bench_cmd` → the entry-point row says `not measured (no quality.bench_cmd)`; never an estimate.
 - **Verdicts**: `improved` · `no measurable change` · `regressed` · `not measured (<reason>)`.
 - **A `regressed` row is a review blocker** unless `03-design.md` justifies the trade — in which
   case the justification goes in the comment, in one line, next to the row.

package/adapters/gemini/commands/flow/work/README.toml

@@ -46,7 +46,7 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
 - **Understand before starting**: design-affecting doubts left after ticket + knowledge search + code → one `AskUserQuestion` with all of them before closing `/flow:feat:start` or `/flow:feat:design` §1.5.
 - **Reuse before creating**: in `/flow:feat:design`, check the affected and neighbouring modules before any new entity, column, repository, service or event; justify intentional duplication in `03-design.md`; never force a poor fit.
 - **Solve the real project problem, not the generic one (fit + YAGNI)**: before any defensive mechanism, **two questions with evidence** — **(a) Does it fit? Can this scenario actually happen given how this project works?** (knowledge search + code, **not** textbook patterns; already prevented → **unnecessary**); **(b) Do we need it now, for what the ticket asks?** (hypothetical → **don't add it**, "idea for a separate ticket"). Bias **remove, not add** — `/flow:feat:design` challenger ("Fit and need") and the defensive mechanisms table of `03-design.md`.
-- **A change is measured against what it replaces, not only against its rivals**: a **modified** query carries the **base row** — the same query on `git merge-base HEAD <git.default_base>`, same sandbox, same seed, same three runs (`/flow:work:query` §4) — and `quality.bench_cmd` benchmarks a touched route, command, consumer or job on both sides (`/flow:*:validate` §3.7). Times are reported `min–max`, and **a difference inside the spread is "no measurable change", never a percentage**. `regressed` blocks like `change` unless the design justifies the trade. The numbers are posted as an MR/PR **comment** (`ship` §4.3), re-posted whenever a later push changes a measured path.
+- **A change is measured against what it replaces, not only against its rivals**: a **modified** query carries the **base row** — the same query on `git merge-base HEAD <git.default_base>`, same sandbox, same seed, same three runs (`/flow:work:query` §4) — and `quality.bench_cmd` benchmarks a touched route, command, consumer or job on both sides (`/flow:*:validate` §3.7). Times are reported `min–max`, and **a difference inside the spread is "no measurable change", never a percentage**. `regressed` blocks like `change` unless the design justifies the trade. The numbers — or, for a modified query nobody could measure, `not measured` and why — are posted as **inline comments on the changed query** (`ship` §4.3), re-posted whenever a later push changes a measured path.
 - **A query is judged on its plan, not on its prose**: cost lives in the **execution plan**, not the diff. `/flow:work:query`: facts, a challenger blinded to the design's rationale, the main agent judges — **no number, no win**, **no dogma in either direction**, **the objector's variant measured next to yours**. **Any size, XS included.** A performance objection is answered with a plan; an unmeasured plan is never reported as measured ("schema only" / "not measured" are legitimate verdicts; a fixture-sized test database is not evidence).
 - **Size is revisable**: a later phase (`design`, `plan`, `investigate`) seeing a clear mismatch **proposes reclassifying to the user** and updates `meta.json.size`.
 - **If the implementation invalidates the design, return to design**: in `/flow:feat:build`, 2+ significant deviations in `05-implementation.md`, or one changing an ADR-light decision → **pause and return to `/flow:feat:design`** (what `/flow:feat:review` and `/flow:feat:validate` read). Same for `/flow:bug:fix` vs `/flow:bug:investigate`.

package/adapters/gemini/commands/flow/work/query.toml

@@ -145,6 +145,9 @@ Per query, exactly one of:
 
 - **ok** — access supported and bounded; state the index used and rows read. For a modified query,
   say how it compares to the base row: *improved*, *no measurable change*, or *regressed*.
+  **No plan was read → it is `ok (plan not measured)`**, with the reason, never a bare `ok`: a
+  modified query reaches the MR/PR through `/flow:feat:ship` §4.3 and the reviewer must be able to
+  tell it was never measured.
 - **regressed** — measurably worse than the base version, and the design does not justify it. A
   blocker, the same as `change`. Justified in `03-design.md` (a correctness fix that costs time, a
   deliberate trade) → not a blocker, but it is stated in the verdict and it reaches the MR/PR.

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.89.0`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.90.0`.** Compare it once, at the start of the session, against
 `version` in `~/.claude/flow/.claude-plugin/plugin.json`. The two differing means the session
 is running a **mixture** — the commands from one copy of the plugin, these shared rules from another
 — which is exactly what happens when a branch or a release candidate is loaded over an installed

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

@@ -185,9 +185,9 @@ With an "all threads resolved before merge" policy, the MR/PR cannot be merged o
 
 ### 3.3 Performance comment
 
-`/flow-feat-ship` §4.3, unchanged: query rows from `06-review.md` and benchmark rows from
-`05-validation.md`, posted as a comment on the MR/PR, confirmed in every mode, nothing posted when
-nothing was measured. A slowness bug is the case where this comment *is* the proof the fix worked.
+`/flow-feat-ship` §4.3, unchanged: query rows from `06-review.md` — a modified query that was not
+measured included, as `not measured (<reason>)` — and benchmark rows from `05-validation.md`,
+posted as comments anchored on the changed lines of the MR/PR, confirmed in every mode. A slowness bug is the case where this comment *is* the proof the fix worked.
 
 ## 4. Close
 

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

@@ -212,6 +212,8 @@ Judging rules: **no number, no win** (unresolved is recorded unresolved, never s
 
 **A modified query is judged against its own past, not only against its rivals.** For every query the diff *changes* (as opposed to adds), the duel carries the **base row** — the same query on `git merge-base HEAD <git.default_base>`, measured in the same sandbox with the same seed (`/flow-work-query` §4). Without it the table cannot say whether this diff made things better or worse, which is the one thing a reviewer wants from it.
 
+**A modified query with no plan behind its verdict is recorded `ok (plan not measured)` — and says what would measure it (`data.explain_cmd`, a data set) — never a bare `ok`.** Ship publishes that row on the MR/PR (`/flow-feat-ship` §4.3); a reviewer who finds a plain "ok" and no number has no way to know nobody looked.
+
 Verdicts as findings: **change** = blocker, through §6; **regressed** = blocker unless `03-design.md` justifies the trade, in which case it is stated and published; **schema / follow-up** → proposed ticket in the output **and a `followups[]` entry** (flow-core §7); **unresolved** → recorded literally with the open question (as §3.5). A `change` verdict resting on a measured plan is already confirmed — no §6 skeptic.
 
 ## 4. Over-engineering audit (fit + YAGNI)

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

@@ -240,22 +240,40 @@ Thread body: the SQL block under "Pre-deploy: run this SQL on the server BEFORE
 
 With the repo policy "all threads resolved before merge", the MR/PR cannot merge until the SQL is executed and the thread **resolved**. **One single thread even with multiple statements.** Tell the user it is left open on purpose.
 
-### 4.3 Performance comment (only when there are numbers)
-
-`06-review.md` §"Data-access duel" has rows for modified queries, or `07-validation.md` §3.7 has
-benchmark rows → post them as a **comment** on the MR/PR just created (`gh pr comment` /
-`glab mr note`). Nothing measured → post nothing; an empty performance comment is noise.
-
-A comment, not a description section, because it is **re-posted on every push that changes a
-measured path** (`/flow-work-green`, `/flow-work-respond`), and a description rewritten each round
+### 4.3 Performance comment (every modified query, measured or not)
+
+Post one when `06-review.md` §"Data-access duel" has a row for a **modified** query — **whatever its
+verdict, measured or not** — or `07-validation.md` §3.7 has benchmark rows. New queries only, or
+renames and reformats only, and nothing benchmarked → post nothing.
+
+**A modified query that was never measured is the case this comment exists for.** Silence reads as
+"nothing to see"; a reviewer cannot tell a query that was measured and is fine from one that nobody
+looked at. The row says `not measured (<reason>)` and what would settle it (`data.explain_cmd`, a
+data set, the entry point to run), so the reviewer knows what was *not* checked.
+
+**Where it goes: on the query, not under the title.** One **inline thread anchored to the changed
+lines of that query in the MR/PR diff** (a resolvable GitLab discussion with a `position`; a GitHub
+review comment on `path` + `line`), one per modified query. The entry-point rows anchor to the entry
+point's changed line the same way. Anchoring fails (the line is not in the diff, the forge refuses
+the position) → a general MR/PR comment that names the file and line, and say so. A general comment
+is the fallback, never the default: a number a reviewer meets on the line they are reading is read;
+one at the bottom of the page is not.
+
+Still a comment and not a description section, because it is **re-posted on every push that changes
+a measured path** (`/flow-work-green`, `/flow-work-respond`), and a description rewritten each round
 loses what the numbers were two rounds ago. The history is the point.
 
+For each modified query the comment carries the **plan before and after** — the `data.explain_cmd`
+output on the merge base and on the branch, same data, trimmed to access type, index, rows read — next
+to the numbers:
+
 ```markdown
-## Performance — base `<sha>` → `<sha>`
+## Performance — `FooRepository::findBar()`, base `<sha>` → `<sha>`
 
-| Query | Rows read | Time (min–max, 3 runs) | Verdict |
-|---|---|---|---|
-| `FooRepository::findBar()` | 41k → 750 | 120–131 ms → 8–9 ms | improved |
+| | Plan (access · index · rows read) | Rows returned | Time (min–max, 3 runs) | Verdict |
+|---|---|---|---|---|
+| base | `ref` · `idx_a` · 41k | 15 | 120–131 ms | |
+| now | `range` · `idx_b` · 750 | 15 | 8–9 ms | improved |
 
 | Entry point | Time | Peak memory | Verdict |
 |---|---|---|---|
@@ -265,6 +283,14 @@ Measured on <data set>, <n> runs each. A difference inside the run-to-run spread
 no measurable change, not a percentage.
 ```
 
+- **The query, ready to run where the data is real.** Every performance comment ends with the exact
+  query (as the engine receives it, parameters filled with representative values) and the read-only
+  plan command for it — `EXPLAIN`, never `EXPLAIN ANALYZE` on a write — in a code block, so the
+  author can run it on production or a replica and answer in the thread. This is a complement to the
+  sandbox measurement, never a substitute: the flow does not touch production.
+- **Memory is the entry point's, not the query's.** A modified query also gets the entry-point row
+  that exercises it, through `quality.bench_cmd` on both sides (`/flow-*-validate` §3.7). No
+  `bench_cmd` → the entry-point row says `not measured (no quality.bench_cmd)`; never an estimate.
 - **Verdicts**: `improved` · `no measurable change` · `regressed` · `not measured (<reason>)`.
 - **A `regressed` row is a review blocker** unless `03-design.md` justifies the trade — in which
   case the justification goes in the comment, in one line, next to the row.

package/adapters/hermes/skills/flow-work-README/SKILL.md

@@ -50,7 +50,7 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
 - **Understand before starting**: design-affecting doubts left after ticket + knowledge search + code → one `AskUserQuestion` with all of them before closing `/flow-feat-start` or `/flow-feat-design` §1.5.
 - **Reuse before creating**: in `/flow-feat-design`, check the affected and neighbouring modules before any new entity, column, repository, service or event; justify intentional duplication in `03-design.md`; never force a poor fit.
 - **Solve the real project problem, not the generic one (fit + YAGNI)**: before any defensive mechanism, **two questions with evidence** — **(a) Does it fit? Can this scenario actually happen given how this project works?** (knowledge search + code, **not** textbook patterns; already prevented → **unnecessary**); **(b) Do we need it now, for what the ticket asks?** (hypothetical → **don't add it**, "idea for a separate ticket"). Bias **remove, not add** — `/flow-feat-design` challenger ("Fit and need") and the defensive mechanisms table of `03-design.md`.
-- **A change is measured against what it replaces, not only against its rivals**: a **modified** query carries the **base row** — the same query on `git merge-base HEAD <git.default_base>`, same sandbox, same seed, same three runs (`/flow-work-query` §4) — and `quality.bench_cmd` benchmarks a touched route, command, consumer or job on both sides (`/flow-*-validate` §3.7). Times are reported `min–max`, and **a difference inside the spread is "no measurable change", never a percentage**. `regressed` blocks like `change` unless the design justifies the trade. The numbers are posted as an MR/PR **comment** (`ship` §4.3), re-posted whenever a later push changes a measured path.
+- **A change is measured against what it replaces, not only against its rivals**: a **modified** query carries the **base row** — the same query on `git merge-base HEAD <git.default_base>`, same sandbox, same seed, same three runs (`/flow-work-query` §4) — and `quality.bench_cmd` benchmarks a touched route, command, consumer or job on both sides (`/flow-*-validate` §3.7). Times are reported `min–max`, and **a difference inside the spread is "no measurable change", never a percentage**. `regressed` blocks like `change` unless the design justifies the trade. The numbers — or, for a modified query nobody could measure, `not measured` and why — are posted as **inline comments on the changed query** (`ship` §4.3), re-posted whenever a later push changes a measured path.
 - **A query is judged on its plan, not on its prose**: cost lives in the **execution plan**, not the diff. `/flow-work-query`: facts, a challenger blinded to the design's rationale, the main agent judges — **no number, no win**, **no dogma in either direction**, **the objector's variant measured next to yours**. **Any size, XS included.** A performance objection is answered with a plan; an unmeasured plan is never reported as measured ("schema only" / "not measured" are legitimate verdicts; a fixture-sized test database is not evidence).
 - **Size is revisable**: a later phase (`design`, `plan`, `investigate`) seeing a clear mismatch **proposes reclassifying to the user** and updates `meta.json.size`.
 - **If the implementation invalidates the design, return to design**: in `/flow-feat-build`, 2+ significant deviations in `05-implementation.md`, or one changing an ADR-light decision → **pause and return to `/flow-feat-design`** (what `/flow-feat-review` and `/flow-feat-validate` read). Same for `/flow-bug-fix` vs `/flow-bug-investigate`.

package/adapters/hermes/skills/flow-work-query/SKILL.md

@@ -149,6 +149,9 @@ Per query, exactly one of:
 
 - **ok** — access supported and bounded; state the index used and rows read. For a modified query,
   say how it compares to the base row: *improved*, *no measurable change*, or *regressed*.
+  **No plan was read → it is `ok (plan not measured)`**, with the reason, never a bare `ok`: a
+  modified query reaches the MR/PR through `/flow-feat-ship` §4.3 and the reviewer must be able to
+  tell it was never measured.
 - **regressed** — measurably worse than the base version, and the design does not justify it. A
   blocker, the same as `change`. Justified in `03-design.md` (a correctness fix that costs time, a
   deliberate trade) → not a blocker, but it is stated in the verdict and it reaches the MR/PR.

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.89.0`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.90.0`.** Compare it once, at the start of the session, against
 `version` in `~/.claude/flow/.claude-plugin/plugin.json`. The two differing means the session
 is running a **mixture** — the commands from one copy of the plugin, these shared rules from another
 — which is exactly what happens when a branch or a release candidate is loaded over an installed

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

@@ -183,9 +183,9 @@ With an "all threads resolved before merge" policy, the MR/PR cannot be merged o
 
 ### 3.3 Performance comment
 
-`/flow-feat-ship` §4.3, unchanged: query rows from `06-review.md` and benchmark rows from
-`05-validation.md`, posted as a comment on the MR/PR, confirmed in every mode, nothing posted when
-nothing was measured. A slowness bug is the case where this comment *is* the proof the fix worked.
+`/flow-feat-ship` §4.3, unchanged: query rows from `06-review.md` — a modified query that was not
+measured included, as `not measured (<reason>)` — and benchmark rows from `05-validation.md`,
+posted as comments anchored on the changed lines of the MR/PR, confirmed in every mode. A slowness bug is the case where this comment *is* the proof the fix worked.
 
 ## 4. Close
 

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

@@ -210,6 +210,8 @@ Judging rules: **no number, no win** (unresolved is recorded unresolved, never s
 
 **A modified query is judged against its own past, not only against its rivals.** For every query the diff *changes* (as opposed to adds), the duel carries the **base row** — the same query on `git merge-base HEAD <git.default_base>`, measured in the same sandbox with the same seed (`/flow-work-query` §4). Without it the table cannot say whether this diff made things better or worse, which is the one thing a reviewer wants from it.
 
+**A modified query with no plan behind its verdict is recorded `ok (plan not measured)` — and says what would measure it (`data.explain_cmd`, a data set) — never a bare `ok`.** Ship publishes that row on the MR/PR (`/flow-feat-ship` §4.3); a reviewer who finds a plain "ok" and no number has no way to know nobody looked.
+
 Verdicts as findings: **change** = blocker, through §6; **regressed** = blocker unless `03-design.md` justifies the trade, in which case it is stated and published; **schema / follow-up** → proposed ticket in the output **and a `followups[]` entry** (flow-core §7); **unresolved** → recorded literally with the open question (as §3.5). A `change` verdict resting on a measured plan is already confirmed — no §6 skeptic.
 
 ## 4. Over-engineering audit (fit + YAGNI)

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

@@ -238,22 +238,40 @@ Thread body: the SQL block under "Pre-deploy: run this SQL on the server BEFORE
 
 With the repo policy "all threads resolved before merge", the MR/PR cannot merge until the SQL is executed and the thread **resolved**. **One single thread even with multiple statements.** Tell the user it is left open on purpose.
 
-### 4.3 Performance comment (only when there are numbers)
-
-`06-review.md` §"Data-access duel" has rows for modified queries, or `07-validation.md` §3.7 has
-benchmark rows → post them as a **comment** on the MR/PR just created (`gh pr comment` /
-`glab mr note`). Nothing measured → post nothing; an empty performance comment is noise.
-
-A comment, not a description section, because it is **re-posted on every push that changes a
-measured path** (`/flow-work-green`, `/flow-work-respond`), and a description rewritten each round
+### 4.3 Performance comment (every modified query, measured or not)
+
+Post one when `06-review.md` §"Data-access duel" has a row for a **modified** query — **whatever its
+verdict, measured or not** — or `07-validation.md` §3.7 has benchmark rows. New queries only, or
+renames and reformats only, and nothing benchmarked → post nothing.
+
+**A modified query that was never measured is the case this comment exists for.** Silence reads as
+"nothing to see"; a reviewer cannot tell a query that was measured and is fine from one that nobody
+looked at. The row says `not measured (<reason>)` and what would settle it (`data.explain_cmd`, a
+data set, the entry point to run), so the reviewer knows what was *not* checked.
+
+**Where it goes: on the query, not under the title.** One **inline thread anchored to the changed
+lines of that query in the MR/PR diff** (a resolvable GitLab discussion with a `position`; a GitHub
+review comment on `path` + `line`), one per modified query. The entry-point rows anchor to the entry
+point's changed line the same way. Anchoring fails (the line is not in the diff, the forge refuses
+the position) → a general MR/PR comment that names the file and line, and say so. A general comment
+is the fallback, never the default: a number a reviewer meets on the line they are reading is read;
+one at the bottom of the page is not.
+
+Still a comment and not a description section, because it is **re-posted on every push that changes
+a measured path** (`/flow-work-green`, `/flow-work-respond`), and a description rewritten each round
 loses what the numbers were two rounds ago. The history is the point.
 
+For each modified query the comment carries the **plan before and after** — the `data.explain_cmd`
+output on the merge base and on the branch, same data, trimmed to access type, index, rows read — next
+to the numbers:
+
 ```markdown
-## Performance — base `<sha>` → `<sha>`
+## Performance — `FooRepository::findBar()`, base `<sha>` → `<sha>`
 
-| Query | Rows read | Time (min–max, 3 runs) | Verdict |
-|---|---|---|---|
-| `FooRepository::findBar()` | 41k → 750 | 120–131 ms → 8–9 ms | improved |
+| | Plan (access · index · rows read) | Rows returned | Time (min–max, 3 runs) | Verdict |
+|---|---|---|---|---|
+| base | `ref` · `idx_a` · 41k | 15 | 120–131 ms | |
+| now | `range` · `idx_b` · 750 | 15 | 8–9 ms | improved |
 
 | Entry point | Time | Peak memory | Verdict |
 |---|---|---|---|
@@ -263,6 +281,14 @@ Measured on <data set>, <n> runs each. A difference inside the run-to-run spread
 no measurable change, not a percentage.
 ```
 
+- **The query, ready to run where the data is real.** Every performance comment ends with the exact
+  query (as the engine receives it, parameters filled with representative values) and the read-only
+  plan command for it — `EXPLAIN`, never `EXPLAIN ANALYZE` on a write — in a code block, so the
+  author can run it on production or a replica and answer in the thread. This is a complement to the
+  sandbox measurement, never a substitute: the flow does not touch production.
+- **Memory is the entry point's, not the query's.** A modified query also gets the entry-point row
+  that exercises it, through `quality.bench_cmd` on both sides (`/flow-*-validate` §3.7). No
+  `bench_cmd` → the entry-point row says `not measured (no quality.bench_cmd)`; never an estimate.
 - **Verdicts**: `improved` · `no measurable change` · `regressed` · `not measured (<reason>)`.
 - **A `regressed` row is a review blocker** unless `03-design.md` justifies the trade — in which
   case the justification goes in the comment, in one line, next to the row.

package/adapters/opencode/commands/flow-work-README.md

@@ -48,7 +48,7 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
 - **Understand before starting**: design-affecting doubts left after ticket + knowledge search + code → one `AskUserQuestion` with all of them before closing `/flow-feat-start` or `/flow-feat-design` §1.5.
 - **Reuse before creating**: in `/flow-feat-design`, check the affected and neighbouring modules before any new entity, column, repository, service or event; justify intentional duplication in `03-design.md`; never force a poor fit.
 - **Solve the real project problem, not the generic one (fit + YAGNI)**: before any defensive mechanism, **two questions with evidence** — **(a) Does it fit? Can this scenario actually happen given how this project works?** (knowledge search + code, **not** textbook patterns; already prevented → **unnecessary**); **(b) Do we need it now, for what the ticket asks?** (hypothetical → **don't add it**, "idea for a separate ticket"). Bias **remove, not add** — `/flow-feat-design` challenger ("Fit and need") and the defensive mechanisms table of `03-design.md`.
-- **A change is measured against what it replaces, not only against its rivals**: a **modified** query carries the **base row** — the same query on `git merge-base HEAD <git.default_base>`, same sandbox, same seed, same three runs (`/flow-work-query` §4) — and `quality.bench_cmd` benchmarks a touched route, command, consumer or job on both sides (`/flow-*-validate` §3.7). Times are reported `min–max`, and **a difference inside the spread is "no measurable change", never a percentage**. `regressed` blocks like `change` unless the design justifies the trade. The numbers are posted as an MR/PR **comment** (`ship` §4.3), re-posted whenever a later push changes a measured path.
+- **A change is measured against what it replaces, not only against its rivals**: a **modified** query carries the **base row** — the same query on `git merge-base HEAD <git.default_base>`, same sandbox, same seed, same three runs (`/flow-work-query` §4) — and `quality.bench_cmd` benchmarks a touched route, command, consumer or job on both sides (`/flow-*-validate` §3.7). Times are reported `min–max`, and **a difference inside the spread is "no measurable change", never a percentage**. `regressed` blocks like `change` unless the design justifies the trade. The numbers — or, for a modified query nobody could measure, `not measured` and why — are posted as **inline comments on the changed query** (`ship` §4.3), re-posted whenever a later push changes a measured path.
 - **A query is judged on its plan, not on its prose**: cost lives in the **execution plan**, not the diff. `/flow-work-query`: facts, a challenger blinded to the design's rationale, the main agent judges — **no number, no win**, **no dogma in either direction**, **the objector's variant measured next to yours**. **Any size, XS included.** A performance objection is answered with a plan; an unmeasured plan is never reported as measured ("schema only" / "not measured" are legitimate verdicts; a fixture-sized test database is not evidence).
 - **Size is revisable**: a later phase (`design`, `plan`, `investigate`) seeing a clear mismatch **proposes reclassifying to the user** and updates `meta.json.size`.
 - **If the implementation invalidates the design, return to design**: in `/flow-feat-build`, 2+ significant deviations in `05-implementation.md`, or one changing an ADR-light decision → **pause and return to `/flow-feat-design`** (what `/flow-feat-review` and `/flow-feat-validate` read). Same for `/flow-bug-fix` vs `/flow-bug-investigate`.

package/adapters/opencode/commands/flow-work-query.md

@@ -147,6 +147,9 @@ Per query, exactly one of:
 
 - **ok** — access supported and bounded; state the index used and rows read. For a modified query,
   say how it compares to the base row: *improved*, *no measurable change*, or *regressed*.
+  **No plan was read → it is `ok (plan not measured)`**, with the reason, never a bare `ok`: a
+  modified query reaches the MR/PR through `/flow-feat-ship` §4.3 and the reviewer must be able to
+  tell it was never measured.
 - **regressed** — measurably worse than the base version, and the design does not justify it. A
   blocker, the same as `change`. Justified in `03-design.md` (a correctness fix that costs time, a
   deliberate trade) → not a blocker, but it is stated in the verdict and it reaches the MR/PR.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flow-workflows",
-  "version": "0.89.0",
+  "version": "0.90.0",
   "description": "Guided feat/bug workflows (start→ship), post-deploy monitoring and multi-agent code review, stack-agnostic. Each repo uses a shared FLOW.md plus optional harness overlay.",
   "type": "module",
   "bin": {

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

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

package/plugins/flow/CHANGELOG.md

@@ -5,6 +5,27 @@ plugin and is what `/flow:news` reads to show you what changed since your previo
 
 The canonical, richest notes live in the [GitHub Releases](https://github.com/mashware/flow-workflows/releases).
 
+## v0.90.0 — A query that changed reaches the MR with its plan, or with the admission that nobody measured it  ·  2026-10-07
+
+**In short**
+- **A modified query always leaves a performance comment**, measured or not. Before, a repo without
+  `data.explain_cmd` closed the review with the query marked `ok` on the schema alone, the ship step
+  saw "nothing measured" and posted nothing — so the reviewer could not tell a query that had been
+  checked from one nobody looked at.
+- **The comment sits on the query**: an inline thread on the changed lines of the diff, one per
+  modified query, instead of a general note under the title. A general comment is only the fallback
+  when the forge refuses the anchor.
+- **Before and after, side by side**: plan (access, index, rows read), rows returned and time
+  `min–max` on the merge base and on the branch; peak memory comes from the entry point that runs the
+  query, through `quality.bench_cmd`. Missing pieces say `not measured (<reason>)` and which key
+  would measure them.
+- **The comment ends with the query and its read-only plan command**, ready to run on production or a
+  replica; the answer goes in the thread.
+- **A bare `ok` is gone for a modified query with no plan**: the review writes
+  `ok (plan not measured)`.
+- `docs/CONFIGURATION.md` now lists what the comment can say for each combination of `data.*` and
+  `quality.bench_cmd`.
+
 ## v0.89.0 — An unattended run can stop at the end of the study, for a person to approve it  ·  2026-10-02
 
 **In short**