From 345beb091dc461fa4f30d959b1011297787e525a Mon Sep 17 00:00:00 2001
From: garrytan <garrytan@gmail.com>
Date: Mon, 2 Nov 2026 15:08:35 +0000
Subject: [PATCH] docs: GST-985 changelog fragment and troubleshooting note

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
---
 changelog.d/gst-985-review-bind-scratch.md | 3 +++
 docs/troubleshooting.md                    | 3 +++
 2 files changed, 6 insertions(+)
 create mode 100644 changelog.d/gst-985-review-bind-scratch.md

diff --git a/changelog.d/gst-985-review-bind-scratch.md b/changelog.d/gst-985-review-bind-scratch.md
new file mode 100644
index 000000000..696ed8de3
--- /dev/null
+++ b/changelog.d/gst-985-review-bind-scratch.md
@@ -0,0 +1,3 @@
+### Fixed
+
+- **A test lane's scratch folder no longer breaks the /ship review bind.** When an untracked `.review-units-test-*/` folder appeared or vanished while reviewers ran, Step 11.5 saw a different tree and the only repair was rerunning Steps 9 to 11.5 (about 20M tokens). Review records now fingerprint with `gstack-wtree --review`, which leaves out root dot-folders that hold no tracked file. `.github/` and `.gstack/` always count, and any change to a tracked file still breaks the bind. The pregate, test evidence and every other caller keep the whole tree. (GST-985)
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 6634be10f..9f306b85b 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -570,6 +570,9 @@ the base has moved.
 **Meaning.** The working tree changed between the pass's `gstack-review-log --start` and
 its logged row: an edit, commit or merge landed while reviewers were still reading. The
 reviewers may not have seen that change, so the row's `review_binding.state` is `changed`.
+Review records fingerprint with `gstack-wtree --review`, which skips untracked root dot-folders
+that hold no tracked file (never `.github/` or `.gstack/`), so a test lane's scratch folder alone
+does not move the tree.
 Step 11.5 cannot bind it and inserts `9 → 10 → 11 → 11.5`. Logging the same results again
 cannot repair it.