flow-workflows 0.65.0 → 0.67.0

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

@@ -27,10 +27,10 @@ Read `~/.claude/flow/CORE.opencode.md` first (shared rules: `FLOW.md` step 0, mo
 
 - Read `meta.json` and `00-summary.md`; open in full only `04-fix.md` (the Brief), `06-review.md` (the verdict), `05-validation.md`, the §"Root cause identified" of `03-investigation.md`, and `99-postmortem.md` if it exists. (flow-core §5)
 - Require `review` in `phases_done`; also `validate` if `size` ≥ S, and `postmortem` if `size` is M or L (the same sizes `/flow-bug-review §8` routes to postmortem — one rule). Missing → refuse and redirect to the missing step.
-- **The review has to be about the tree you are about to push.** Compare `meta.json.reviewed_sha` and `validated_sha` against `git rev-parse HEAD`:
-  - **Equal** → continue.
+- **The review has to be about the tree you are about to push — `/flow-feat-ship` §1, in full and unchanged**, including its four newer cases: `reviewed_sha` is the revision the reviewers *read* (`/flow-bug-review` §1.5 froze it), so `fixed_sha` set alongside an equal sha is a mismatch and not a match; a dirty tree at this end is named and asked about rather than passed over; and a `reviewed_sha` that no longer resolves is reported, then treated as absent. Compare `meta.json.reviewed_sha` and `validated_sha` against `git rev-parse HEAD`:
+  - **Equal** (and no `fixed_sha`, over a clean tree) → continue.
   - **Absent** (a work from before the shas were recorded) → say so in one line, 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**. Only test files (`tests/`, `test/`, `spec/`, `__tests__/`, `*_test.*`, `*Test.*`, `*.test.*`, `*.spec.*`) or this work's folder under `.claude/work/` → append both shas and the file list to `06-review.md`, continue without asking. **Anything else** → stop and ask in **every** `autonomy.mode`, no exceptions (`AskUserQuestion`): *re-review the delta* (`/flow-bug-review` over `<sha>..HEAD`, the recommended default) · *ship as it stands*, recording in `06-review.md` the two shas and that the user accepted them unreviewed.
+  - **Different** → read the delta (`git log --oneline <sha>..HEAD`, `git diff --stat <sha>..HEAD`) and judge it by **what it touches**. Only test files (`tests/`, `test/`, `spec/`, `__tests__/`, `*_test.*`, `*Test.*`, `*.test.*`, `*.spec.*`) or this work's folder under `.claude/work/` → append both shas and the file list to `06-review.md`, continue without asking. **Anything else** → stop and ask in **every** `autonomy.mode`, no exceptions (`AskUserQuestion`): *re-review the delta* (`/flow-bug-review`, the recommended default — its §1.5 takes `reviewed_sha` as the base, so the delta is both what it reads and what sets its tier) · *ship as it stands*, recording in `06-review.md` the two shas and that the user accepted them unreviewed.
 
 ## 1. Draft title and description (without sending anything yet)
 
@@ -171,6 +171,7 @@ nothing was measured. A slowness bug is the case where this comment *is* the pro
 
 ## 4. Close
 
+- **A worktree does not own the tree its tools wrote into — `/flow-feat-ship` §5.5, in full and unchanged.** First, before anything below: `meta.json.worktree` not null → read the main checkout's `git status --porcelain`, name any paths it holds in one line as what they are (in the main checkout, not in the branch just pushed, and not necessarily put there by this run), and offer once to carry them over. A fix consolidates its knowledge one phase earlier, in `/flow-bug-postmortem` §4, so by the time this runs those writes have already happened and the branch has already been pushed — which is exactly the window this check exists to close.
 - Update `meta.json`: add `ship` to `phases_done`, update `updated_at`. **`phase` becomes `done` only once the MR/PR is confirmed merged** — creating it is not finishing it. Right after §3.1 it is open, so ask once with `AskUserQuestion` whether it has already been merged: **no** (the normal answer) → leave `phase = "ship"`; **yes** → `phase = "done"`. `/flow-work-green` and `/flow-work-respond` work on the open MR/PR; `/flow-work-clean` only sweeps what merged.
 - Refresh `panel.json`: while the MR/PR is open its line is `wait` with the `link`; once merged it is `done`, and only then say there is nothing left here (`mark: "info"`, `style: "ok"`). Drop the `Decision` line either way.
 - Overwrite `00-summary.md` whole (≤15 lines, flow-core §5).
@@ -181,5 +182,6 @@ nothing was measured. A slowness bug is the case where this comment *is* the pro
 - **Follow-up triage — `/flow-feat-ship` §6.4, in full and unchanged.** Read `meta.json.followups[]`; nothing `proposed` → skip silently. Otherwise §6.4 step 0 first — **3 or more candidates go to a skeptic** whose job is to refute that each deserves a ticket, and only the strongest `tracker.followup_ask_max` (empty → **2**) reach the user (flow-core §7) — then one batched `AskUserQuestion` (**Do it** / **Not worth it** / **Later**; `decision` entries asked as their question, `tooling` and everything `log`ged never asked), the accepted ones get their tracker issue created (outward-facing → **asks in every mode**), the logged ones nothing but `status: "logged"` in `meta.json`, then one offer to start the first. A bug flow is where the gate earns its keep: the prevention actions `/flow-bug-postmortem` wrote, the neighbouring bugs `/flow-bug-validate` found and the similar-risk patterns `/flow-bug-fix` flagged all land here — half a dozen of them, from one fix, and «similar risk elsewhere» that no skeptic ever read is exactly the entry that turns a closed bug into six open questions. Repeat for anything still `proposed` on the re-run that confirms the merge.
 - **Conventions learned — `/flow-feat-ship` §6.4bis, in full and unchanged.** Read `meta.json.conventions_candidates[]` (flow-core §8); nothing pending → skip silently. Otherwise: drop what `FLOW.md` already says, then one batched `AskUserQuestion` (**Add to FLOW.md** / **Not a rule** / **Later**, or **Replace** when it contradicts a line that is there). Asked in every mode — it edits a file in the tree. A fix is where the corrections land hardest: *«never mock the repository in that layer»*, *«the regression test goes next to the unit test, not in the functional suite»* — said once inside `bug:fix`, and proposed again in the next incident unless they reach the file.
 - **Close the follow-up that started this work.** `meta.json.origin` set and this ship moved `phase` to `done` → open the originating work's `meta.json` (live folder or `_archive/`) and set that `followups[]` entry to `status: "done"`. Best-effort: the originating folder is gone or unreadable → warn in one line and continue, never block. Without this the entry stays `in_progress` forever and `status`/`daily` keep reporting work that is finished.
+- **Only once `phase` is `done`**: delete the candidate anchor `/flow-bug-review §1.5` left behind — `git update-ref -d refs/flow/candidate/<TICKET>`. No question: local, never pushed, and the gate that needed it has run.
 - Ask whether to archive `.claude/work/<TICKET>/` to `.claude/work/_archive/`.
 - If `meta.json.worktree` is not null, offer `git worktree remove <worktree>` once the MR/PR is merged (`--force` only if the user confirms discarding remaining changes). Not before merge, not without confirmation.

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

@@ -178,6 +178,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`).
@@ -221,13 +232,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)**.
 
@@ -259,6 +270,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/opencode/commands/flow-feat-review.md

@@ -29,6 +29,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 opencode`
   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
@@ -60,60 +63,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 opencode --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 opencode --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
@@ -146,7 +140,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.
 
@@ -154,8 +148,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.
@@ -184,7 +182,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:
 
@@ -311,8 +309,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>
@@ -356,10 +355,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: ✅ / ❌
@@ -375,7 +374,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/opencode/commands/flow-feat-ship.md

@@ -25,12 +25,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)
@@ -226,6 +228,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
@@ -405,6 +423,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/opencode/commands/flow-feat-validate.md

@@ -28,10 +28,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/opencode/commands/flow-init.md

@@ -18,9 +18,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/opencode/commands/flow-work-README.md

@@ -23,7 +23,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
@@ -85,9 +85,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,
@@ -95,7 +98,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,
@@ -136,7 +141,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/opencode/commands/flow-work-respond.md

@@ -136,7 +136,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.