flow-workflows 0.65.0 → 0.67.0

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

@@ -180,6 +180,17 @@ The step's changes are **always reported before anything is recorded**. Who deci
    - **"Something needs to change"** → adjust; the step's commit stays pending until OK.
    - **"Continue without committing, we'll group later"** → next step without committing; changes accumulate in the working tree (fewer clean points if §2.3 cuts).
 
+4. **Write the step into the log, committed or not.** Append one line to a `## Steps` section of `05-implementation.md` (create it at the first step):
+
+   ```
+   - <short sha> · <step name> · <n files, +a −b>
+   - — · <step name> · <n files, +a −b>          ← not committed
+   ```
+
+   No question, in every autonomy mode — this is flow machinery on the never-ask list of flow-core §2. A step that was **not** committed gets its line too, with `—` where the sha would be: that is the case in `manual`, and the *"continue without committing, we'll group later"* branch above. The log then has no holes, and the absence of a commit is itself what the reader needs to see.
+
+   The step summary was already written for every step; the sha is the one identifier that makes the log line and the git history the same record. Without it `05-implementation.md` explains *why* each change was made and names not one commit that did it, so §2.3 reads the cut point off `git log --oneline` and matches it by the prose in `WIP <TICKET>: <step>`, and a delta-scoped review (`/flow-feat-review §1.5`) can say which lines are new but not which steps they came from.
+
 Rules when a commit does happen:
 - One commit per step. Do not batch steps unless the user explicitly requests it.
 - `--no-verify` **only for WIP commits** (slow hooks run in `/flow-feat-review` and in the final commit of `/flow-feat-ship`).
@@ -223,13 +234,13 @@ slip under a threshold buys itself the review a smaller change had earned.
 **Hot cut mechanics (option 1)**:
 
 0. **If there are uncommitted changes** in the working tree: warn the user and ask them to decide before cutting — commit what is done as a WIP for the corresponding step, or stash it (`git stash`) so it does not mix with the next MR/PR.
-1. Identify a cut point: the last WIP commit where the piece is coherent and mergeable (a closed sub-goal: "endpoint and DTO done", "migration applied", "flow X tests green"). Do not cut in the middle of a change.
+1. Identify a cut point from the `## Steps` lines of `05-implementation.md` (§2.2): the last committed step where the piece is coherent and mergeable (a closed sub-goal: "endpoint and DTO done", "migration applied", "flow X tests green"). Those lines pair each step with its sha, so the cut is chosen on what the step *was* rather than re-derived from `git log --oneline` and matched by the prose in a commit message. **Name the sha in the proposal** — the user confirms an identifier, not a description. A step with `—` instead of a sha is not a cut point; it never got one. Do not cut in the middle of a change.
 2. Edit `meta.json.mrs`:
    - The current MR/PR keeps `n`, `title`, `wave` and `depends_on`, adjusts `lines_est` and `files_est` to actuals, and stays `in_progress`.
    - Insert a new one with the next `n` (renumbering subsequent ones if any), `title` describing what remains, `status: "pending"`, `phases_done: []` (a fresh MR/PR earns its own review/validate), `depends_on: [n_current]`, `wave` = one after the current one, and new indicative `lines_est` and `files_est`. If you renumber subsequent entries, **update their `depends_on` references accordingly** so no `depends_on` points to a higher `n` than its own.
 3. Edit `04-mr-plan.md`: split the original entry in two, keeping the standalone-mergeable justification for both halves.
 4. Note in `05-implementation.md` under "Hot cut": date, reason, what stays and what moves to the next one.
-5. **Do not rewrite history with `git rebase`**: WIP commits belonging to the next MR/PR stay in the current branch. When building the next one, start from a new branch over the base and transfer them with `git cherry-pick` or equivalent — executed in `/flow-feat-ship` or when starting the next `/flow-feat-build`.
+5. **Do not rewrite history with `git rebase`**: WIP commits belonging to the next MR/PR stay in the current branch. When building the next one, start from a new branch over the base and transfer them with `git cherry-pick` or equivalent — executed in `/flow-feat-ship` or when starting the next `/flow-feat-build`. The shas to transfer are the `## Steps` lines below the cut point, which is what that section is for on this side of the cut too.
 
 **If there was already a cut and overrun happens again**: ask the user before cutting again — a second cut on the same MR/PR signals the plan is wrong. The right option is probably **3 (reopen plan)**.
 
@@ -261,6 +272,9 @@ Keep `.claude/work/<TICKET>/05-implementation.md` updated as you work (not at th
 ## Changes per file
 - <file> — what changed and why (1 line each)
 
+## Steps
+<one line per step of §2.2, in order: `- <short sha> · <step name> · <n files, +a −b>`, and `—` in place of the sha where the step was not committed. Written as each step closes, in every autonomy mode. This is what joins the log to the git history: §2.3 reads its cut point here, the transfer after a cut picks its shas here, and a delta-scoped review can say which steps a range came from. A section with no holes is the point — an uncommitted step still gets its line.>
+
 ## Decisions made during implementation
 - Decision: …
   - Why: …

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

@@ -31,6 +31,9 @@ Mandatory review phase. **`/flow-feat-ship` cannot run without passing through h
 - **Gather the material once, not once per reviewer.** `npx flow-workflows@<version> bundle --checks --harness hermes`
   prints one context pack for this branch — worklist, the diff (minus `git.diff_exclude`), the changed files
   in full, the raw output of `quality.static_analysis`, and the work's handoff — in a single call.
+  **§1.5 runs first and adds `--rev` and `--base` to that call**: the pack is then one frozen
+  revision against one resolved base, which is what makes it the same material for every reader
+  rather than the same *call* made at different moments.
   Read that instead of rediscovering it, and **pass it to the briefs of §2-§6**: a panel where every
   member runs its own `git diff` and opens the same files pays for that material once per agent, and
   a reviewer that spends its turns exploring has fewer left to review. **Any non-zero exit is a
@@ -62,60 +65,51 @@ Mandatory review phase. **`/flow-feat-ship` cannot run without passing through h
   picks the model, so `models.agents`/`models.workers` do not reach those reviewers. A one-shot sweep
   cannot pull a thread, so an ambiguous finding still goes to a real agent with tools, as below.
 
-## 2. Invoke the code reviews
+### 1.5 Freeze what you are about to read, and resolve what to compare it against
 
-Scope for every reviewer: the full feature work against the base branch (committed + working tree — commits are opt-in).
+Two questions, answered here and nowhere later: **which tree** this round reads, and **against which base**. Both used to be answered implicitly — by the checkout as it happened to stand at each moment, and by `git.default_base` always — and both answers were wrong in a way no artifact could show.
 
-### 2.0 Resolve review depth (scale to *this diff* and the risk)
-Read `quality.review_depth` from `FLOW.md` (`proportional` | `full` | `light`; empty → `proportional`) and `meta.json.size`. This decides **what §2.1 launches and at which effort**. Built-in `code-review` effort ladder: **low < medium < high < xhigh < max** (lower = fewer, higher-confidence findings; higher = broader coverage, may surface uncertain ones).
+**The candidate.** A round applies its own fixes; the README's own first-minute example is *"3 reviewers, one finding — fixed"*. So "the working tree" is a different tree for the reviewer that read it first, for the skeptic that read it last, and for the `git rev-parse HEAD` taken at §9 — which by construction contains code no reviewer ever saw, and which `/flow-feat-ship §1` then compares against `HEAD` and finds equal. Resolve one revision before §2 launches anything:
 
-**The tier is resolved against the diff in front of you, not against the size of the feature.**
-`meta.json.size` describes the whole work; in a multi-MR/PR train every MR/PR inherits it, so a
-41-line third MR/PR gets reviewed as the L its feature is — the single largest source of wasted
-review in this plugin. Measure the real diff (`git diff --shortstat <git.default_base>...HEAD`, plus
-the working tree) and derive its own size:
+- Tree clean → `git rev-parse HEAD`.
+- Tree dirty → `git stash create`. It writes a real, addressable commit object holding the index and the tracked working tree; it does **not** touch the checkout and there is nothing to pop. Empty output (nothing to stash after all) → `git rev-parse HEAD`.
+- **Untracked files are in no revision**, so they are outside the candidate. `git status --porcelain` lists them; name them in `06-review.md` in one line and read them from disk. A new file nobody mentions is the review's blind spot, not a technicality.
+- Anchor it so it cannot be collected: `git update-ref refs/flow/candidate/<TICKET> <sha>`. A `stash create` object is unreferenced, and a candidate the `ship` gate cannot resolve is a gate that reports nothing. The ref is local, never pushed, and `/flow-feat-ship §6.5` deletes it.
+- Write `candidate_sha` to `meta.json` — work-level and in the current `mrs[]` entry — **in this pre-flight**. A candidate recorded after the reading is not a freeze.
 
-| Changed lines in this diff | Diff size |
-|---|---|
-| ≤ 150 | XS |
-| 151-600 | S |
-| 601-1500 | M |
-| > 1500 | L |
+**The review base.** `reviewed_sha` already records the tree the last passing review read, and `ship` trusts it enough to stop a push — yet the review itself never read it, so a second review re-reads every line the first one cleared, and §2.0 resolves the tier on the accumulated total: a 30-line delta on a 900-line branch reviewed as the 900. Resolve:
 
-**Effective size = the lower of `meta.json.size` and the diff size**, and every size-gated step in
-this command (§3.5, §5.5, §6) reads the effective size, not the recorded one. The diff pointing
-*higher* than the recorded size is worth one line in `06-review.md` (the work may be misclassified),
-not a heavier review. The **sensitive-surface bump below applies on top of the effective size and is
-never scaled away** — a 12-line change to an authorization check still gets the panel.
+- The current MR/PR's `reviewed_sha` (work-level when there is no train) when it is **non-empty** and **an ancestor of the candidate** (`git merge-base --is-ancestor <sha> <candidate>`) → that is the base.
+- Otherwise `git.default_base`. A `reviewed_sha` that is not an ancestor means history was rewritten or the branch recut; say so in one line rather than producing a nonsensical delta.
+- **A first review has no `reviewed_sha` and reads the whole branch**, exactly as before. The delta path only exists after a review that passed.
+- `/flow-feat-review --full` ignores `reviewed_sha` and reads the branch on demand.
+- **Fall back to `git.default_base` and say why** when either holds, because a delta cannot see how it interacts with what was cleared before: the delta touches a file the previous review left a finding on, or it changes an external contract copied under `/flow-feat-build §2.0bis`.
 
-**The threshold is visible in the artifact, because it is the one number with an incentive on it.**
-A diff of 148 lines is reviewed at `medium` with no panel and closes §6's gate; one of 160 gets the
-panel. When the measured diff lands **within 10% under** a threshold that changed the tier (135-150,
-541-600, 1351-1500), say so in one line of `06-review.md`, beside the effective size. It is not an
-accusation and it changes no tier — it is the only place a reader can see that the review they are
-holding was selected by a number, and it is what makes flow-core §9 (the diff reports the change; the
-change is never shaped to fit the number) checkable after the fact rather than merely stated.
+**Then everything reads those two.** `npx flow-workflows@<version> bundle --checks --harness hermes --rev <candidate_sha> --base <review base>` — the pack is that one revision for every reader, and its header says so. The briefs of §2–§6 name the candidate, and the agent that pulls a thread on an ambiguous finding is told to read `git diff <review base>...<candidate_sha>`, never the live tree. `quality.static_analysis` still runs against the checkout, which the pack states: a linter reads the working tree and freezing does not change that.
 
-- **`full`** (any size): built-in `code-review` at **xhigh** + the project panel. Skip the tiering below.
-- **`light`** (any size): built-in `code-review` (or `quality.review_skill`) **only**, at **medium** effort. No project panel, no §3 reinforcements, no §6 skeptic fan-out. The sensitive-surface bump still applies: a sensitive surface upgrades `light` to the `proportional` tier for that work.
-- **`proportional`** (default), base effort by size:
+## 2. Invoke the code reviews
+
+Scope for every reviewer: **the candidate revision of §1.5, against the review base of §1.5** — which is the whole feature work against `git.default_base` on a first review, and the delta since the last passing one otherwise. Committed and uncommitted work travel together inside the candidate; untracked files do not, and §1.5 named them.
 
-| Size | Built-in `code-review` | Project panel (`review_skill`/`reviewers`) |
-|---|---|---|
-| XS | **medium** | do **not** launch |
-| S | **high** | only if the diff touches a sensitive surface; otherwise the built-in alone is the review |
-| M | **high** | full panel |
-| L | **xhigh** | full panel |
+### 2.0 Resolve review depth (scale to *this diff* and the risk)
 
-- **Sensitive-surface bump** (proportional, any size): the diff touches a sensitive surface → **raise the built-in effort one tier** (medium→high→xhigh→**max**) and always run the panel. S/M on a sensitive surface → **xhigh**; **L on a sensitive surface → `max`**.
+**The CLI resolves it; you obey the output and record any deviation.** `npx flow-workflows@<version> tier --harness hermes --rev <candidate_sha> --base <review base>` prints, from the config it already parses: changed lines over the §1.5 range, diff size, `meta.json.size`, **effective size** (the lower of the two), the built-in `code-review` effort with and without the sensitive-surface bump, whether the panel runs, the resolved `agents.budget_max`/`fanout_max`, whether the measurement landed **within 10% under** a threshold that changed the tier, and which `quality.sensitive_paths` globs the diff matched, with the path that matched each.
 
-**Sensitive surface** = the generic categories — authentication/authorization, secrets/credentials, payments/billing, personal or otherwise sensitive data, a public API/contract shape, or a DB migration/schema change — **plus** every glob in `quality.sensitive_paths` from `FLOW.md`. The key is **additive**: it names what is sensitive in *this* repo and nowhere in that list (an internal event or message contract consumers depend on, a pricing or entitlement table, a consent flow, a feature-flag resolver), and a repo that declares its own surfaces never loses the ones it never thought about.
+Every step of that is arithmetic, and the cost of leaving it here was never mainly the tokens: `06-review.md` recorded the tier *this agent said it derived*, so a round that eyeballed the diff and a round that measured it wrote a byte-identical artifact — on the one number in this command that carries an incentive on it. Same treatment `Review path` and `Cost:` already got, for the same reason.
 
-**A sensitive path is not yet a sensitive diff, and this is where the precision comes from** — not from a shorter list. The bump asks what the change *does* there, not where it lives. It applies when the diff touches **control flow, or the data that reaches a person, a charge or a stored record** — a new guard, a new `catch`, a changed condition, a changed value, a changed contract. It does **not** apply when the diff moves **observability alone**: a log level, a log channel, the text of a message, a metric, a comment. That diff gets the review its size already earned. Mixed diff → not observability-only, so it bumps. Say which of the two it was in one line; a diff demoted here is the one place a missed defect is expensive, so the line is not optional.
+**Copy the output verbatim** into the `Review tier` and `Effective size` lines of §8, the way `bundle --checks` copies static analysis out. A computed line, not a narrated one.
 
-**Query changes do not belong here.** §3.6 already duels every query the diff adds or modifies, at every size, whatever this section resolved — routing them through the bump would buy a second opinion on prose where §3.6 buys a plan.
+**What the CLI deliberately does not decide, because a command cannot see it:**
 
-Record in `06-review.md` which tier and effort ran and why (e.g. "L + DB migration → built-in at `max` + panel"; "S, `src/**/Payment/**` but log level only → no bump, built-in at `high`").
+- **Whether a generic category applies.** The sensitive surface is the generic list — authentication/authorization, secrets/credentials, payments/billing, personal or otherwise sensitive data, a public API/contract shape, a DB migration/schema change — **plus** every glob in `quality.sensitive_paths`. The CLI reads the key; it carries no idea of its own about what is sensitive (that list is the repo's). You judge the categories against the diff.
+- **Whether a matched path is a sensitive *diff*.** The bump asks what the change *does* there, not where it lives: it applies to **control flow, or the data that reaches a person, a charge or a stored record** — a new guard, a new `catch`, a changed condition, a changed value, a changed contract. It does **not** apply when the diff moves **observability alone**: a log level, a channel, a message's text, a metric, a comment. Mixed diff → not observability-only, so it bumps. **Say which of the two it was in one line**; a diff demoted here is the one place a missed defect is expensive.
+- **Query changes.** §3.6 duels every query the diff adds or modifies, at every size, whatever this section resolved — routing them through the bump buys a second opinion on prose where §3.6 buys a plan.
+
+**No CLI, or a non-zero exit → the prose fallback**, and `Review path` names it with the reason (the same contract the panel follows). Measure `git diff --shortstat <review base>...<candidate_sha>`; **≤150 → XS · 151-600 → S · 601-1500 → M · >1500 → L**; effective size = the lower of that and `meta.json.size`; `proportional` runs the built-in at **medium/high/high/xhigh** by size and the panel at M and above (at S only on a sensitive surface); the bump raises the effort one tier (medium→high→xhigh→**max**) and always runs the panel; `full` is **xhigh** plus the panel at any size, `light` is the built-in alone at **medium** with no panel, no §3 and no §6 — and a sensitive surface lifts `light` to the proportional tier for that work. The thresholds and the ladder are documented in `docs/CONFIGURATION.md`, where they can be read without being re-taught to a model on every invocation.
+
+**The diff pointing *higher* than `meta.json.size`** is worth one line in `06-review.md` (the work may be misclassified), never a heavier review. **The sensitive-surface bump is never scaled away** — a 12-line change to an authorization check still gets the panel, on a delta exactly as on a first review.
+
+Record in `06-review.md` which tier and effort ran and why (e.g. "L + DB migration → built-in at `max` + panel"; "S, `src/**/Payment/**` but log level only → no bump, built-in at `high`"), and **any deviation from what the CLI resolved, with its reason**.
 
 ### 2.0b Resolve the agent budget (the ceiling is the command's, not the round's)
 This command is the widest fan-out in the plugin: a panel, area reinforcements, a coverage sweep that
@@ -148,7 +142,7 @@ Launch the reviewers selected in §2.0 and **consolidate their findings into a s
 
 1. **Built-in `code-review`** (the Claude Code one, no prefix), at the §2.0 effort. Single pass over the local diff: correctness failures + reuse/simplification/efficiency.
 2. **Project panel** (only when §2.0 selected it): read `quality.review_skill` from `FLOW.md`.
-   - `review_skill` set → invoke that skill with `03-design.md` as additional context. Scope: `git diff <git.default_base>...HEAD`, plus uncommitted working-tree changes.
+   - `review_skill` set → invoke that skill with `03-design.md` as additional context. Scope: `git diff <review base>...<candidate_sha>` (§1.5) — the candidate carries the uncommitted work, so there is no second, later reading to take.
    - `review_skill` empty, `quality.reviewers` has entries → launch each agent in parallel as a panel, same context and scope.
    - Both empty → step 1 already covers this pass; launch nothing more.
 
@@ -156,8 +150,12 @@ Launch the reviewers selected in §2.0 and **consolidate their findings into a s
 
    **Every brief you write here ends with the report contract of flow-core §6** — `agents.report_max_words` (empty → 250), findings only, one line each as `file:line` + what is wrong + the fix. This file's own prompts (§3.5, §4, §5.5) already carry theirs; the panel briefs are yours to write, and an uncapped one is truncated in transit and reaches you looking exactly like a reviewer that found nothing. The built-in `code-review` takes no brief — bound it with the §2.0 effort tier and hold it to the same fan-out deadline (flow-core §6): over a large diff it is the likeliest member of this round to stall before its first sentence.
 
+**Nothing edits the tree while a round is in flight** (flow-core §6). The candidate of §1.5 means every reviewer is handed the same bytes however long it takes to get to them; it does not mean the checkout underneath can be edited freely, because an agent with tools reads that one. The fixes this phase applies are the parent's own edits — applied mid-round they land underneath agents still reading, and a reviewer that reports a line which has moved, or runs `git status` around its own reading to work out what it touched, is the reading this phase exists to trust. Findings are fixed **after** the round is consolidated. The fixes are then a delta the candidate does not contain, which is exactly what §9's `fixed_sha` records and `ship` asks about.
+
 When both run, deduplicate overlapping correctness/simplification findings (count each once). The `review_skill` specialists (offensive/defensive security, silent failures, architecture) are not repeated in later phases.
 
+**Dedup keeps every source, not the first one.** A finding carries its **origin** from here to §8 — `built-in`, a panel role, or the pass that raised it (`§3.5`, `§3.6`, `§5`, `§5.5`) — and a finding more than one source raised lists all of them. Counted once, credited to each. Beyond the built-in and the panel this command runs four specialised passes, roughly 1 800 of its words, every one added after a real defect got through and not one able to show it still earns that cost: a finding only the idiom audit saw and a finding three sources raised say opposite things about that pass, and until now both were written identically. The `Cost:` line stopped being a headcount when `meta.json.cost[]` arrived; this is the same move for the thing those costs are spent on.
+
 ### 2.2 Design truth vs design rationale (do not inherit rationalizations)
 `03-design.md` goes to reviewers as context, with unequal authority:
 - **Contracts and acceptance criteria are truth** — verify the code meets them.
@@ -186,7 +184,7 @@ wall-clock, that is the tell: wait.
 
 Loop, maximum **2 rounds**:
 
-1. **Worklist**: `git diff --stat <git.default_base>...HEAD` → list of changed files/areas.
+1. **Worklist**: `git diff --stat <review base>...<candidate_sha>` (§1.5) → list of changed files/areas.
 2. **Coverage map**: from the consolidated §2-§3 findings, mark which files/areas received at least one finding or were explicitly examined.
 3. **Completeness critic (1 agent, blinded and text-only)**: `Agent general-purpose` (takes `models.agents` like every other subagent here), passing **only** the full diff file list (step 1) and, per §2-§3 reviewer, one line on what it covered. **Do not** pass the detailed findings, the design, or the diff. This agent compares two lists and answers in three sentences; it opens no file, runs no `git diff`, reads no code. An agent here that is still working after a few minutes is not being thorough — it was handed the wrong job, and the fix is to kill it and re-launch with the two lists alone. Prompt:
 
@@ -313,8 +311,9 @@ Write `.claude/work/<TICKET>/06-review.md`. The `Cost:` line of `## Summary` is
 # Code review <TICKET>
 
 ## Summary
+- Reviewed: <`<review base>...<candidate_sha>` (§1.5), each as a short sha, plus which base was chosen and why — the previous `reviewed_sha`, or `git.default_base` because this is a first review / the sha was not an ancestor / a fallback rule fired / `--full` was asked for. Any untracked file the candidate could not hold is named here. Without this line a round that read a delta and a round that read the branch are indistinguishable, and so are a frozen round and one that read a moving tree.>
 - 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).>
+- Effective size: <diff size (N changed lines, measured over the §1.5 range — the branch on a first review, the delta afterwards) 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. When the pack ran, quote its `Config read:` line verbatim: it is the only place that says whether the overlay reached the material, and “no `--harness` was given” there means every key set only in the overlay was missing from this round.>
 - 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>
@@ -358,10 +357,10 @@ Write `.claude/work/<TICKET>/06-review.md`. The `Cost:` line of `## Summary` is
 <if §6 did not run, one line saying which condition did not hold — size, diff size, or count>
 
 ## Blockers (must-fix)
-1. [file:line] description + concrete proposal
+1. [file:line] · <origin> · description + concrete proposal
 
 ## Suggestions (nice-to-have)
-1. [file:line] description
+1. [file:line] · <origin> · description
 
 ## Quality gates
 - style_fix: ✅ / ❌
@@ -377,7 +376,12 @@ Write `.claude/work/<TICKET>/06-review.md`. The `Cost:` line of `## Summary` is
 
 - Blockers → **do not advance `phase`**. Leave `phase = "build"`; the user resolves them.
 - No blockers → `phase = "review"`, add to `phases_done`. **In a multi-MR/PR work**, also add `review` to the current `in_progress` MR/PR's own `phases_done` (its `mrs[]` entry) — `/flow-feat-ship §1` gates on it per MR/PR.
-- **Record *what* you reviewed**, in the same write: `reviewed_sha` = `git rev-parse HEAD`, work-level and — in a multi-MR/PR work — in this MR/PR's `mrs[]` entry too. `phases_done` says a review *happened*; the sha says which tree, and `/flow-feat-ship §1` compares it before pushing. Write it whenever the phase advances, never when it does not: a review that ended in blockers reviewed nothing that stands.
+- **Record *what* you reviewed, and separately what you changed after reading it**, in the same write, work-level and — in a multi-MR/PR work — in this MR/PR's `mrs[]` entry too:
+  - `reviewed_sha` = **the candidate of §1.5**, the revision the reviewers actually read. Not `git rev-parse HEAD`, which is what it used to be and which by then holds this round's own fixes — code no reviewer saw, recorded as reviewed, and `ship` finding it equal to `HEAD` every time.
+  - `fixed_sha` = `git rev-parse HEAD` after this round's fixes, or **empty** when the round applied none. Two fields because they are two facts, and collapsing them is what hid the delta.
+  - `phases_done` says a review *happened*; these say which tree, and `/flow-feat-ship §1` reads both before pushing. Written whenever the phase advances, never when it does not: a review that ended in blockers reviewed nothing that stands.
+- **Record which pass found what**, in the same write: `meta.json.review_findings[]`, one entry per finding **per source** — `{ round, origin, severity, file, discarded_by_skeptic }`, and no finding text, which stays in the artifact. `flow review --record` writes these itself when the CLI ran the panel; when the agentic panel ran, write them here from the origins §2.1 carried. `flow cost` reads them back per origin: how many findings each pass contributed, how many only it raised, and how many of those survived §6. That last number is the only evidence a pass is still earning its words.
+  **The retirement rule, written down before the data arrives** so it cannot be argued backwards later: a pass that contributes **no exclusive surviving finding across twenty reviews** is removed from this command. Zero is zero, and the decision is made against the number rather than against whoever is most attached to the pass.
 - **Stage what the review taught** (`knowledge.stage` set; silence by default). Review is where a project teaches the most and, until now, the one phase that never staged — a work with three review rounds and seventeen blockers produced zero knowledge cards because nothing asked for them while they were in context. Candidates are findings about the **domain or the codebase's real behaviour**, not about this diff: a library that does other than its name says, a test disguise that kept the suite green over a live defect, a module rule the reviewers had to cite from its own prose, a measurement. A blocker fixed here is not knowledge; *why it was written wrong* may be. Same evidence rule as `/flow-feat-design` §8 — one line of evidence per finding or it is not staged. One call per finding, one line to the user («Staged N finding(s) for `ship`»). Never `knowledge.save` here.
 - Overwrite `00-summary.md` whole (≤15 lines, flow-core §5).
 - **Configuration this phase earned the right to ask about** (flow-core §0, `manual` only, at most one key per work, as an extra option on this same stop — never a question of its own): a role the panel had to improvise on an M/L or sensitive diff → `agents.<role>`; a `Cost:` line that went over `agents.budget_max` → `quality.review_depth`. In `guided`/`auto` neither is asked: the default is taken and recorded in `meta.json.defaults_used[]`.

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

@@ -27,12 +27,14 @@ Closes the feature: commit, push, MR/PR (assigned per `git.assignee`, squash per
 - Read `meta.json` and `00-summary.md`; open in full only the `Brief MR/PR #N` of `05-implementation.md`, the `## Summary`/blockers of `06-review.md` and `07-validation.md`. (flow-core §5)
 - Require `review` in `phases_done`; for `size` other than `XS`, also require `validate`. **In a multi-MR/PR work** (`meta.json.mrs` has >1 entry) check the **current `in_progress` MR/PR's** own `phases_done` (its `mrs[]` entry), NOT the work-level list — a previous MR/PR's `review`/`validate` does **not** satisfy this gate.
 - Not met → refuse and send the user to the missing step (multi-MR/PR: `/flow-feat-review` or `/flow-feat-validate` **for this MR/PR**).
-- **The review has to be about the tree you are about to push.** Compare `meta.json.reviewed_sha` and `validated_sha` (this MR/PR's `mrs[]` entry in a multi-MR/PR work) against `git rev-parse HEAD`:
-  - **Equal** → continue, nothing to report.
+- **The review has to be about the tree you are about to push.** `reviewed_sha` is the revision the reviewers **read** (`/flow-feat-review §1.5` froze it), not the one that phase ended on, so the round's own fixes are a real delta here rather than a match. Compare `meta.json.reviewed_sha` and `validated_sha` (this MR/PR's `mrs[]` entry in a multi-MR/PR work) against `git rev-parse HEAD`:
+  - **Equal** → continue, nothing to report — **unless `fixed_sha` is set**, which says the review changed the tree after reading it and cannot then be equal to `HEAD`. That combination is a mismatch, not a match: the shas were recorded by two different mechanisms and one of them is wrong. Say so and treat it as Different below.
+  - **The tree is dirty at this end** (`git status --porcelain` non-empty, ignoring untracked) → both shas describe committed history and the bytes about to be pushed are not in either. Name the paths and ask, exactly as Different does; a comparison of two identical shas over two different trees is the case the old gate passed over in silence.
+  - **`reviewed_sha` does not resolve** (`git cat-file -e <sha>^{commit}`) — a candidate from a dirty tree whose anchor ref was deleted, or history rewritten since — → say so in one line and treat it as Absent. A gate that cannot read its own input must not report nothing wrong here.
   - **Absent** (work started before the shas were recorded) → say so in one line and continue. Absence is not a mismatch.
-  - **Different** → read the delta (`git log --oneline <sha>..HEAD`, `git diff --stat <sha>..HEAD`) and judge it by **what it touches**, never by size.
+  - **Different** → read the delta (`git log --oneline <sha>..HEAD`, `git diff --stat <sha>..HEAD`) and judge it by **what it touches**, never by size. When `fixed_sha` is set, say in the same line that part of this delta is the review's own fixes: the user is judging what the reviewers never read, and where it came from is the first thing they need.
     - Only test files (`tests/`, `test/`, `spec/`, `__tests__/`, `*_test.*`, `*Test.*`, `*.test.*`, `*.spec.*`) and this work's own folder under `.claude/work/` → append both shas and the file list to `06-review.md`, continue **without asking** (a test written by `validate` after the review is the normal order).
-    - **Anything else** → stop and ask, in **every** `autonomy.mode`, with a single `AskUserQuestion`: *re-review the delta* (`/flow-feat-review`, recommended default — it reads `<sha>..HEAD`, not the whole branch) · *ship it as it stands*, which first appends to `06-review.md` the two shas, the files, and that the user accepted them unreviewed. Never resolve this one silently.
+    - **Anything else** → stop and ask, in **every** `autonomy.mode`, with a single `AskUserQuestion`: *re-review the delta* (`/flow-feat-review`, recommended default — §1.5 resolves `reviewed_sha` as its base, so it reads the delta and nothing else, and resolves the tier on the delta too) · *ship it as it stands*, which first appends to `06-review.md` the two shas, the files, and that the user accepted them unreviewed. Never resolve this one silently.
 - Check for blocking TODO/FIXME added on this branch (`git diff --unified=0 <git.default_base>...HEAD | grep -E '^\+.*(TODO|FIXME)'`). If any, list them and ask whether to continue.
 
 ## 2. Draft title and description (without sending anything yet)
@@ -228,6 +230,22 @@ Only if `knowledge.read_staging` or `knowledge.save` is set; neither → skip wi
 3. **Combine staging + new findings** into a short list. Empty or only code-derivable → do not insist.
 4. 1+ relevant findings → ask the user whether to consolidate. Yes → run the consolidation of flow-core §0 (`read_staging`, then one decision and one `knowledge.save` per finding). No → do not insist.
 
+## 5.5 A worktree does not own the tree its tools wrote into
+
+`meta.json.worktree` null → skip silently; there is nothing here that can go wrong.
+
+Everything above this line ran in a worktree, and several of the tools it called had no way of knowing that. A configured tool — `knowledge.save` is the first one this caught, and no key is special — is started once per session, resolves the repo from the directory it was started in, and takes no root in its call. A worktree is the same repo with another tree, so its output can land in the **main checkout**, which is standing on another branch, while the branch §4 just pushed goes out without it. Nothing in the invocation could have corrected that: flow is the only party that knows `meta.json.worktree` is set, and this is the only place that knows the push already happened.
+
+So, before the Close:
+
+```
+git -C "$(git rev-parse --path-format=absolute --git-common-dir)/.." status --porcelain
+```
+
+Empty → say nothing at all. Non-empty → **one line naming the paths**, and what it means in plain words: they are sitting in the main checkout, not in the branch that was pushed. Say it as a reading, never as an accusation — that checkout may have been dirty before this work started, and only the user can tell their own leftovers from what this run put there.
+
+Then offer once, with `AskUserQuestion` **in every autonomy mode** (it edits two trees): **carry them over** — copy the paths the user confirms into this worktree, commit onto the branch, push, and the MR/PR from §4 updates itself — or **leave them**, which is the right answer whenever what is sitting there belongs to the other branch. Either way the Close reports what was decided: a `ship` that quietly repaired two checkouts is worse than one that named the problem and left it standing.
+
 ## 6. Close
 
 ### 6.1 Update `meta.json` per scenario
@@ -407,6 +425,7 @@ paste. Never a list here, and never a question: in `guided`/`auto` not asking is
 ### 6.5 Archive and cleanup
 
 Only if `phase = "done"`:
+- Delete the candidate anchor `/flow-feat-review §1.5` left behind: `git update-ref -d refs/flow/candidate/<TICKET>`. It existed to stop the object being collected while the gate still needed it; the gate has run. No question — it is local, it was never pushed, and nothing reads it after this. Absent already → nothing to do.
 - Ask whether to keep `.claude/work/<TICKET>/` or archive it (move to `.claude/work/_archive/`).
 - If `meta.json.worktree` is not null, offer to remove the worktree (from the main checkout) with `git worktree remove <worktree>` (`--force` only if it still has changes the user confirms discarding). Never without confirmation, never if the MR/PR is not yet merged.
 

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

@@ -30,10 +30,14 @@ Verify the feature is complete: test coverage, edge cases, performance, regressi
 
 ## 2. Work
 
-Launch **in parallel** — both briefs end with the report contract of flow-core §6 (`agents.report_max_words`, empty → 250; findings only, one line each), and the testing agent is told the **test files are the deliverable**, saved as each one is finished, not at the end:
+One of the three below writes and two of them read, so they do not all go at once (flow-core §6, one writer of the working tree at a time). The testing agent's deliverable is **files on disk**; the performance agent and the suite both read the tree it is writing into. Run beside it, the suite reports on a tree that no longer exists by the time you read the result — and a red raised by a half-written test file is a red nobody can act on. Both briefs end with the report contract of flow-core §6 (`agents.report_max_words`, empty → 250; findings only, one line each).
+
+**First, alone — the writer.** It is told the **test files are the deliverable**, saved as each one is finished, not at the end:
 
 1. **Testing agent**: the `agents.testing` agent from the effective FLOW config; if empty, `Agent general-purpose` with this role. Brief: "Review the branch changes and complete the test suite where coverage is missing. Focus: the acceptance criteria in `03-design.md` marked `test` that no current test demonstrably asserts (see the §3 mapping), plus edge cases from `03-design.md`, error paths, input validations, emitted domain events. Do not rewrite tests that already pass. Read `.claude/work/<TICKET>/03-design.md` and `05-implementation.md`. Follow the project's effective test conventions from `FLOW.md` plus the active harness overlay."
 
+**Then, in parallel — the readers**, once the testing agent has reported and its files are on disk. The suite runs here and not earlier for a second reason beyond the collision: run after the writer, it is the first thing that has ever executed the tests this phase just added.
+
 2. **Performance agent** if the feature touches persistence, repositories, templates on hot paths, controllers with real traffic, or calls anything outside the process inside a loop: the `agents.performance` agent from `FLOW.md`; if empty, `Agent general-purpose` with this role. Brief: "Detect N+1, missing indexes, unbounded queries, flush in a loop, per-iteration calls that leave the process (external API, HTTP, cache, filesystem), and heavy synchronous work that should go to a queue. For any call inside a loop that can fail, follow what **each failed iteration** sets off downstream — what it publishes, enqueues, disables or logs — and whether N failures multiply it. Report only actionable findings."
 
    **A green suite is not a performance result** — a tiny fixture database proves a query's **rows**, never its **plan**. If `/flow-feat-review §3.6` left any query verdict `unresolved`, or an acceptance criterion concerns speed or volume: run the measurement of **`/flow-work-query §4`** with the volumes in `data.volumes` (or a data set shaped like them — the distribution matters more than the total), record plan and timings, and gate on the result. No `data.*` configuration and the criterion cannot be measured → it is `unproven` with the reason, never silently `proven`.

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

@@ -20,9 +20,10 @@ description: "Assistant that generates FLOW.md and its optional harness overlay
 
 Creates or updates the effective FLOW configuration at the repo root: shared values in `FLOW.md`
 and optional harness-owned values in the active `FLOW.<harness>.md`. The active filename is
-`FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`, or `FLOW.hermes.md`;
-identify it from the
-product executing this command, never from the selected model. Every other `/flow-*` command reads
+`FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`, `FLOW.hermes.md`, or
+`FLOW.zcode.md`; identify it from the
+product executing this command, never from the selected model (zcode runs the Claude pages too, so
+the page you are reading does not name the harness). Every other `/flow-*` command reads
 the base and then that overlay. The user answers the **minimum**: what the repo can tell is
 auto-detected and only confirmed.
 

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

@@ -25,7 +25,7 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
 - `FLOW.md` at the repo root is the shared base: tracker, branch and MR/PR conventions, quality
   commands, code conventions, and observability profile.
 - The active `FLOW.<harness>.md` is an optional sparse overlay (`claude`, `codex`, `opencode`,
-  `gemini`, or `hermes`) for model names, agents, skills, orchestration, knowledge tools, or any other value that
+  `gemini`, `hermes`, or `zcode`) for model names, agents, skills, orchestration, knowledge tools, or any other value that
   differs on that harness. Every command reads the base and then the active overlay in step 0;
   existing repos with only `FLOW.md` behave exactly as before.
 - An overlay key replaces the base even when explicitly empty; an absent key inherits it. Lists
@@ -87,9 +87,12 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
   "phase": "context" | "design" | "plan" | "build" | "review" | "validate" | "ship" | "investigate" | "fix" | "postmortem" | "done" | "abandoned",
   // retired in v0.53.0 and still read from older works: "brainstorm" → treat as "context", "diagnose" → as "investigate"
   "phases_done": ["context", ...],
+  "candidate_sha": "40-char sha the current review froze before reading, or ''",
   "reviewed_sha": "40-char sha the last passing review read, or ''",
+  "fixed_sha": "40-char sha after that review's own fixes, or '' when it applied none",
   "validated_sha": "40-char sha the suite last went green on, or ''",
   "respond_rounds": 0,
+  "review_findings": [{"round": 1, "origin": "security", "severity": "blocker", "file": "src/X.php", "discarded_by_skeptic": false}],
   "mrs": [
     {
       "n": 1,
@@ -97,7 +100,9 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
       "size": "S",
       "status": "pending" | "in_progress" | "merged" | "closed" | "superseded",
       "phases_done": ["build", "review", "validate"],
+      "candidate_sha": "",
       "reviewed_sha": "",
+      "fixed_sha": "",
       "validated_sha": "",
       "respond_rounds": 0,
       "wave": 1,
@@ -138,7 +143,9 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
 }
 ```
 
-- **`reviewed_sha` / `validated_sha`**: which code the review / green run happened to. Written by `review` and `validate` at `## Close`, **only when the phase actually advances**, work-level and in the current `mrs[]` entry. Read by `ship` at pre-flight against `HEAD`: a delta of test files and this work's own folder passes with a note in `06-review.md`; anything else stops and asks in every autonomy mode. Empty is not a mismatch.
+- **`candidate_sha` / `reviewed_sha` / `fixed_sha` / `validated_sha`**: which code each verdict is about. `candidate_sha` is written by `review` in its **pre-flight** (§1.5) — the revision it froze before reading anything, `git rev-parse HEAD` over a clean tree and `git stash create` over a dirty one, anchored at `refs/flow/candidate/<TICKET>` so nothing collects it. The other three are written at `## Close`, **only when the phase actually advances**, work-level and in the current `mrs[]` entry: `reviewed_sha` is the candidate that was actually read, `fixed_sha` is `HEAD` after that round's own fixes (empty when it applied none), `validated_sha` is where the suite went green.
+- **`review_findings[]`**: one entry per finding **per source** — `{ round, origin, severity, file, discarded_by_skeptic }`, no finding text (that stays in `06-review.md`). Written at `review`'s Close, and by `flow review --record` when the CLI ran the panel. `origin` is `built-in`, a panel role, or the pass that raised it. It exists so a pass can be retired on evidence: `flow cost` reports per origin how many findings each contributed, how many **only** it raised, and how many of those survived §6 — and a finding three sources raised says nothing about any of them, which is why dedup keeps every source rather than the first. The rule was written down before the data arrived: no exclusive surviving finding across twenty reviews and the pass comes out of the command.
+  Two fields for the review because they are two facts. `reviewed_sha` used to be `git rev-parse HEAD` at the end of the phase, which by then held the round's own fixes — so `ship` compared a sha against itself and reported a match over code no reviewer had read. Read by `ship` at pre-flight against `HEAD`: a delta of test files and this work's own folder passes with a note in `06-review.md`; anything else stops and asks in every autonomy mode. Empty is not a mismatch; `fixed_sha` set with `reviewed_sha == HEAD` is one. `review` also reads `reviewed_sha` back as **its own base** on a re-review, so the second round reads the delta instead of the whole branch.
 - **`respond_rounds`**: rounds of `/flow-work-respond` on an MR/PR. `/flow-work-respond §1` reads it against `quality.respond_max_rounds` (empty = 3) and refuses the round that would exceed it, handing the open threads back to the user.
 - **`related_repos`**: the **other repos a task touches**. Captured at `/flow-feat-start` / `/flow-bug-start` §cross-repo, refined at `design`/`plan`, reminded at `ship`, shown by `daily`/`resume`/`status`. flow only notes and reminds — never touches the other repo. `[]` for single-repo.
 - **`contract_handoff`**: whether the sibling knows **what shape to build against** (`scope` is prose; distinct from `status`). `none` — consumes no contract declared here. `pending` — consumes one, not handed over yet. `published → <location>` — published where that side reads it (normally the tracker ticket; `/flow-feat-ship` §6.3), picked up by the sibling's `/flow-feat-start` §3.6.

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

@@ -138,7 +138,7 @@ Only the **code-change** bucket, with the flow's building mechanics and conventi
 In-review edits are **not** exempt because they are "small": they are where a wrong primitive or over-engineered mechanism slips in, straight into an MR/PR already under human eyes. The round's diff passes the **same gate as `/flow-feat-review`**, scaled to the round:
 
 - **Trivial rounds** — only nitpick/style edits, no new classes or wiring → a single built-in `code-review` pass over the round's diff; skip the rest of this subsection.
-- **Non-trivial rounds** — anything beyond nitpicks, or new architectural pieces → run the review machinery of `/flow-feat-review`, **scoped to this round's diff** (not the whole feature), applying:
+- **Non-trivial rounds** — anything beyond nitpicks, or new architectural pieces → run the review machinery of `/flow-feat-review`, **scoped to this round's diff** (not the whole feature). Its **§1.5** is what now delivers that scope rather than leaving it a promise: the previous `reviewed_sha` is the base when it is an ancestor of the candidate, so the round's own diff is both what is read and what sets the tier. Then apply:
   - Its **§2.0 depth ladder** — pick the built-in `code-review` effort from the round's diff size (proxying `meta.json.size` when the round is small) plus the **sensitive-surface bump**; launch the project panel (`quality.review_skill` / `quality.reviewers`) when the ladder selects it, **as defined**. Per its **§2.2**: the stance agreed in §4 goes to the reviewer as context, never as a scope exclusion in the prompt.
   - Its **§4 over-engineering / YAGNI audit** and **§5.5 idiom / primitive audit (blind to the design's rationale)** — they catch extracting a class/interface/mechanism to "answer a comment". **§5.5's trigger — "introduces new architectural pieces" — always runs when that is true, regardless of round size.**
   - Its **§3.6 data-access duel** whenever the round **added or changed a query** — including a one-line change to an order, a bound or a join, and a change made to satisfy a reviewer's comment. If §4.G already measured it this round, reuse that table.

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`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.67.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
@@ -37,10 +37,14 @@ a command relies on is simply absent in that session, and nothing else will repo
   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
+  this command: `FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`,
+  `FLOW.hermes.md`, or `FLOW.zcode.md`. The
   harness is the product executing the command, never guessed from a model name. An overlay is
-  valid without a base file; unknown `FLOW.*.md` names are ignored. Throughout every command,
+  valid without a base file; unknown `FLOW.*.md` names are ignored. **A page can outlive the product it
+  was written for**: zcode reads the plugin's Claude pages as well as its own `/flow:`-prefixed
+  mirror of them, so a `claude` in a path or in a `--harness` flag records where the page was
+  written, never who is running it. On zcode the overlay is `FLOW.zcode.md` and the flag is
+  `--harness zcode`, whichever of the two pages you were handed. 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
@@ -54,6 +58,12 @@ a command relies on is simply absent in that session, and nothing else will repo
   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.
+  **This is a rule about reading a git-ignored config, and it inverts for anything a phase
+  writes into the repo.** A tracked file belongs to the branch, and the branch is the worktree:
+  written to the main checkout it lands on whatever that checkout is standing on — usually the
+  base branch — and goes out in no MR/PR at all. So a phase writing a tracked file writes it
+  **here**, in the directory it is running in, and `/flow-feat-ship §5.5` is what catches the
+  tools that could not be told.
 - 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
@@ -114,7 +124,8 @@ worth a command of its own, which is why there is no longer one:
 3. **Per finding**: `knowledge.search` set → query it with the topic and the finding's paths, then
    decide *create* · *update* · *enrich with a new angle* · *conflict*. A conflict is asked
    immediately (`AskUserQuestion`) and nothing is saved until it is resolved. Then `knowledge.save`,
-   one call per finding; the role empty → append to **`KNOWLEDGE.md` at the repo root** under a
+   one call per finding; the role empty → append to **`KNOWLEDGE.md` at the root of the checkout
+   you are in** (a tracked file belongs to the branch — the inversion above) under a
    `## <topic>` heading — the finding, its evidence line, the date and the branch. Creating that file
    the first time edits the tree, so it is asked once, in every mode; appending to an existing one is
    recorded, not asked.
@@ -314,6 +325,21 @@ test suite, a migration, a batch of edits — name the **path it writes** and re
 after each finished piece, not at the end**. Then verify the artifact instead of believing the
 report: half a chunk on disk is recoverable, what lives only in the agent's context is not.
 
+**One writer of the working tree at a time.** An agent whose deliverable is files on disk is not
+another reader with a longer report: it is break, run, restore, and it composes with nothing else
+looking at the same tree. Two of them at once — or one of them beside a reader — and every reading
+taken in that window is of a tree somebody else was halfway through changing. That is how a suite
+comes back red for an edit belonging to another agent, how a reviewer ends up running `git status`
+around each of its own findings to work out which changes are its doing, and how a commit that
+looks clean is clean by luck. **The parent thread is a writer too**: applying a round's fixes while
+its agents are still reading is the same collision, from the side nobody counts.
+
+So a round that contains a writer is not one round. Readers fan out freely, as they always did;
+writers go one at a time, each either alone or in a worktree of its own, and the readers sit
+entirely before them or entirely after them. The parent's own edits wait until the round is
+consolidated. Ordering costs wall clock and the phase says so in one line — a reading nobody can
+trust costs the phase twice, which is the trade this rule is making.
+
 **A parallel round names a path too, however short the answer.** Not for volume — for arrival. A
 round of four is four chances for a result to reach you as nothing: truncated in transit, delivered
 as a notification while you were mid-turn, or an agent that went idle without replying at all. From

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

@@ -72,6 +72,8 @@ Save the brief at the top of `04-fix.md`. Any "also fix X while we're at it" dur
 - **`guided`** — ask **once**, at the first step; apply that answer for the rest of the fix; record it in `04-fix.md`.
 - **`auto`** — commit the WIP yourself (`git add <files> && git commit -m "WIP <TICKET>: <step>" --no-verify`) without asking. Invoking the command in `auto` is the authorization, and it covers **only** WIP commits on the work branch — push and MR/PR creation stay hard gates in every mode.
 
+**Then write the step into the log, committed or not** — `/flow-feat-build §2.2`, unchanged, into a `## Steps` section of `04-fix.md`: `- <short sha> · <step name> · <n files, +a −b>`, with `—` in place of the sha for a step that was not committed. No question, in every mode. A fix is usually one step and one commit, which is exactly when the missing line costs least to add and the `06-review.md` delta is most likely to be that one sha.
+
 ## 2.2 The premise this fix rests on (any size)
 
 Same instrument as `/flow-feat-build §2.1bis`: the four conditions, one round per fix, the same
@@ -120,6 +122,9 @@ A **product decision** the fix turns out to need is neither of these — not sco
 ## Changes by file
 - <file> — what changed and why (1 line)
 
+## Steps
+<one line per step of §2.1, in order: `- <short sha> · <step name> · <n files, +a −b>`, and `—` in place of the sha where the step was not committed. This is what joins the log to the git history; a section with no holes is the point, so an uncommitted step still gets its line.>
+
 ## Premises the fix depends on
 <one row per premise put through §2.2, plus any belief recorded as an assumption without a round: premise · what it rests on · verdict (holds / refuted / unsettled) · the evidence, or what would settle it. Omit the section when the fix depends on nothing outside its own diff.>
 

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

@@ -60,14 +60,24 @@ Read `~/.claude/flow/CORE.opencode.md` first (shared rules: `FLOW.md` step 0, mo
   picks the model, so `models.agents`/`models.workers` do not reach those reviewers. A one-shot sweep
   cannot pull a thread, so an ambiguous finding still goes to a real agent with tools, as below.
 
+### 1.5 Freeze what you are about to read, and resolve what to compare it against
+
+**`/flow-feat-review` §1.5, in full and unchanged.** In short, before §2 launches anything:
+
+- **Candidate**: `git rev-parse HEAD` over a clean tree, `git stash create` over a dirty one (a real commit object, the checkout untouched, nothing to pop), anchored with `git update-ref refs/flow/candidate/<TICKET> <sha>` so nothing collects it and `/flow-bug-ship §0` can still resolve it. Untracked files are in no revision — name them and read them from disk. Written to `meta.json.candidate_sha` here, not later: a candidate recorded after the reading is not a freeze.
+- **Review base**: the previous `reviewed_sha` when it is non-empty and an ancestor of the candidate, otherwise `git.default_base`, with the reason in one line. `--full` forces the whole branch.
+- **Then**: `bundle --rev <candidate_sha> --base <review base>`, and every brief names that range rather than the live tree.
+
+A fix is usually small enough that the delta and the branch are the same thing — which is exactly why the freeze matters more here than the scoping: a one-file fix whose round applies its own correction is the case where `reviewed_sha` used to equal `HEAD` while describing a tree nobody read.
+
 ## 2. Run the code reviews
 
-Scope for every reviewer: the fix against the base (committed + uncommitted working tree).
+Scope for every reviewer: **the candidate revision of §1.5, against the review base of §1.5** — the fix against `git.default_base` on a first review, the delta since the last passing one afterwards. The candidate carries the uncommitted work; untracked files stay outside it and §1.5 named them.
 
 ### 2.0 Resolve review depth (scale to *this diff* and the risk)
 Read `quality.review_depth` from `FLOW.md` (`light` | `proportional` | `full`; empty → `proportional`) and `meta.json.size`. Built-in `code-review` effort ladder: **low < medium < high < xhigh < max** (lower = fewer, higher-confidence findings; higher = broader coverage).
 
-**The tier is resolved against the diff in front of you**, per `/flow-feat-review §2.0`: measure the real diff (`git diff --shortstat <git.default_base>...HEAD` plus the working tree), derive its size (≤150 lines → XS · 151-600 → S · 601-1500 → M · >1500 → L), and run on the **lower** of that and `meta.json.size` — a one-file fix inside a bug classified M is an XS review. Every size-gated step here (§4.5, §5) reads that effective size. The sensitive-surface bump applies on top and is never scaled away. **When the measured diff lands within 10% under a threshold that changed the tier** (135-150, 541-600, 1351-1500), say so in one line beside the effective size in §7 — the tier does not change, and it is what makes flow-core §9 checkable after the fact.
+**The tier is resolved by the CLI, against the diff in front of you** — `/flow-feat-review §2.0`, in full and unchanged: `npx flow-workflows@<version> tier --harness opencode --rev <candidate_sha> --base <review base>` prints changed lines, diff size, `meta.json.size`, effective size (the lower of the two — a one-file fix inside a bug classified M is an XS review), the effort with and without the bump, the resolved ceilings, the within-10% flag and which `quality.sensitive_paths` globs matched. **Copy it verbatim** into §7 and record any deviation with its reason; no CLI or a non-zero exit falls back to the prose there (≤150 → XS · 151-600 → S · 601-1500 → M · >1500 → L) and `Review path` names the fallback. What stays yours is what a command cannot see: whether a generic category applies, and whether a matched path is a control-flow change or observability only. Every size-gated step here (§4.5, §5) reads the effective size; the bump is never scaled away.
 
 **Say what the round will run on** (flow-core §1): the skeptics and the completeness check have no agent of their own, so with the fan-out key empty they inherit this thread's model — one line before the first round of 4 or more naming the count and the inheritance, and the same fact on the artifact's `Agent models` line. Name the key (`models.workers`, then `models.agents`), never a model.
 
@@ -95,6 +105,8 @@ Launch the reviewers selected in §2.0 and **consolidate their findings into a s
 1. **Built-in `code-review`** (the Claude Code one, no prefix), at the effort of §2.0. Single pass over the local diff: correctness + simplification/efficiency.
 2. **Project panel** (only when §2.0 selected it): skill `quality.review_skill` from FLOW.md, invoked as `<review_skill> branch`. `review_skill` empty and `quality.reviewers` set → launch those agents in parallel as a panel. Both empty → the built-in `code-review` is the whole review. Launch the panel **as defined** — whole roster, no subset, no substitutions; an agent that cannot run goes to §7 `Agents launched` with the reason. **Every brief you write for it — and for the §3 reinforcements — ends with the report contract of flow-core §6** (`agents.report_max_words`, empty → 250; findings only, one line each): an uncapped report is truncated in transit and reads exactly like a reviewer with nothing to say. The built-in `code-review` takes no brief; bound it with the §2.0 tier and hold it to the same fan-out deadline.
 
+**Nothing edits the tree while a round is in flight** — `/flow-feat-review` §2.1, unchanged: the reviewers all read the same working tree, and this phase's own fixes wait until the round is consolidated, so §3 onward read a tree that stopped moving (flow-core §6).
+
 Deduplicate overlaps (count once). Fix-specific focus beyond generic analysis:
 - The change genuinely resolves the problem from `03-investigation.md`.
 - No expanded scope (hidden refactor) — list any.
@@ -134,7 +146,7 @@ Review the diff for new defensive mechanisms smuggled in "just in case" (validat
 
 ## 4.5. Completeness check (M/L, no loop)
 
-**M/L by effective size (§2.0) only**, **one** check, no loop, and only while the budget covers it: after consolidating §2-§3 — never in parallel with them, since the check's input is what they covered — contrast `git diff --stat <git.default_base>...HEAD` against what was reviewed. Any changed file no reviewer looked at → targeted pass with the applicable reviewer, merge. A small diff (normal for a fix) resolves this in seconds or makes it not apply.
+**M/L by effective size (§2.0) only**, **one** check, no loop, and only while the budget covers it: after consolidating §2-§3 — never in parallel with them, since the check's input is what they covered — contrast `git diff --stat <review base>...<candidate_sha>` (§1.5) against what was reviewed. Any changed file no reviewer looked at → targeted pass with the applicable reviewer, merge. A small diff (normal for a fix) resolves this in seconds or makes it not apply.
 
 ## 5. Adversarial finding verification (parallel fan-out, optional)
 
@@ -206,17 +218,18 @@ Cost line: count every subagent this command launched — reviewers = §2.1 buil
 <only if §5 was run; refuted findings with their reason, or "not applicable">
 
 ## Blockers
-1. [file:line] …
+1. [file:line] · <origin> · …
 
 ## Suggestions
-1. …
+1. [file:line] · <origin> · …
 ```
 
 ## 8. Close
 
 - With blockers: `phase` stays where it was (`validate` for size ≥ S, `fix` on XS, where validate never ran). Iterate.
 - Without blockers: `phase = "review"`, add to `phases_done`. Suggest `/flow-bug-postmortem` (M/L) or `/flow-bug-ship` (XS/S).
-- **Record *what* you reviewed**, in the same write: `reviewed_sha` = `git rev-parse HEAD` — `phases_done` says a review happened, the sha says on which tree, and `/flow-bug-ship §0` compares it against what is being pushed. Only when the phase advances: a review that ended in blockers reviewed nothing that stands.
+- **Record *what* you reviewed, and separately what you changed after reading it** — `/flow-feat-review` §9, unchanged: `reviewed_sha` = the **candidate** of §1.5 (the revision the reviewers read, never `git rev-parse HEAD`, which by now holds this round's own fixes), and `fixed_sha` = `git rev-parse HEAD` after those fixes, empty when the round applied none. `phases_done` says a review happened; these two say on which tree and what moved afterwards, and `/flow-bug-ship §0` reads both against what is being pushed. Only when the phase advances: a review that ended in blockers reviewed nothing that stands.
+- **Record which pass found what** — `/flow-feat-review §9`, unchanged: one `meta.json.review_findings[]` entry per finding **per source** (`{ round, origin, severity, file, discarded_by_skeptic }`, no finding text), written by `flow review --record` when the CLI ran the panel and by this Close when the agentic panel did. `flow cost` reads them back per origin, and the retirement rule is the same: a pass with no exclusive surviving finding across twenty reviews comes out of the command.
 - **Stage what the review taught** (`knowledge.stage` set; silence by default). Review is where a project teaches the most and, until now, the one phase that never staged — a work with three review rounds and seventeen blockers produced zero knowledge cards because nothing asked for them while they were in context. Candidates are findings about the **domain or the codebase's real behaviour**, not about this diff: a library that does other than its name says, a test disguise that kept the suite green over a live defect, a module rule the reviewers had to cite from its own prose, a measurement. A blocker fixed here is not knowledge; *why it was written wrong* may be. Same evidence rule as `/flow-feat-design` §8 — one line of evidence per finding or it is not staged. One call per finding, one line to the user («Staged N finding(s) for `postmortem`/`ship`»). Never `knowledge.save` here.
 - Overwrite `00-summary.md` whole (≤15 lines, flow-core §5).
 - Stop body (after the flow-core §3 header): the findings that survived and what you did with each, plus the same Cost line as the Summary: "- Cost: <n>/<budget_max> subagents launched (<k> reviewers · <m> reinforcements · <s> skeptics), tier <light|proportional|full>".