From ba26aa065db83a154967e80db419a6d67451640f Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Wed, 9 Sep 2026 10:45:20 -0400 Subject: [PATCH] docs(#4467): document fallow's structural-pre-pass has no upper-bound scope (#4574) * docs(#4467): document fallow's structural-pre-pass has no upper-bound scope structural-pre-pass.md's FALLOW_SCOPE_ARGS=(--changed-since "$FALLOW_BASE") derives a correct, phase-anchored LOWER bound (lockstep with Tier 3's own scope step, #3995), but fallow's --changed-since is one-sided by design -- verified against fallow 2.70.0's own --help: the only other scoping flags are --changed-workspaces (workspace selection, not a file range) and --diff-file (its own help text scopes it to line-range refinement within the hot-path-touched verdict, not general file selection; gsd-core never uses it). Reviewing an earlier phase after a later one has landed pulls the later phase's files into the earlier phase's structural audit. Not fixable inside this file: fixing fallow itself is a third-party concern, and working around it (e.g. auditing from a temporary worktree checked out at the phase tip) is disproportionate machinery for what is supplementary structural-analysis context, not a blocking gate -- both routes the issue's own analysis already ruled out. Documented the asymmetry at the point the scope is derived instead, so a future reader does not assume this step's tip agrees with Tier 3's just because the base does. No regression test: documentation-only, no runtime behavior change. A prior revision of this commit carried an Emitted-Drift-Ack-Growth trailer for this growth -- gsd-test's own emitted-attribution check rejected it as stale ("written or reworded in THIS diff, but nothing here needed them"), meaning this file (nested under gsd-core/workflows/code-review/steps/, unlike a top-level gsd-core/workflows/*.md file) is not tracked by that specific growth conservation law. Removed the now-confirmed-unnecessary trailer rather than guess again -- the test's own verdict is authoritative here, not a re-derivation of its tracked-path rules. Co-Authored-By: Claude Sonnet 5 * docs(#4467): backfill changeset PR number Co-Authored-By: Claude Sonnet 5 --------- Co-authored-by: sim Co-authored-by: Claude Sonnet 5 --- .changeset/sharp-bears-roar.md | 5 +++++ .../workflows/code-review/steps/structural-pre-pass.md | 7 +++++++ 2 files changed, 12 insertions(+) create mode 100644 .changeset/sharp-bears-roar.md diff --git a/.changeset/sharp-bears-roar.md b/.changeset/sharp-bears-roar.md new file mode 100644 index 000000000..40679b871 --- /dev/null +++ b/.changeset/sharp-bears-roar.md @@ -0,0 +1,5 @@ +--- +type: Fixed +pr: 4574 +--- +**Structural pre-pass now documents that its fallow scope has no upper bound** — the phase-directory-anchored base is correct and lockstep with Tier 3's own scope step, but nothing bounds the tip, so reviewing an earlier phase after a later one has landed could silently pull the later phase's files into the audit. The limitation is now documented at the point the scope is derived. diff --git a/gsd-core/workflows/code-review/steps/structural-pre-pass.md b/gsd-core/workflows/code-review/steps/structural-pre-pass.md index f6621413b..41a97f6df 100644 --- a/gsd-core/workflows/code-review/steps/structural-pre-pass.md +++ b/gsd-core/workflows/code-review/steps/structural-pre-pass.md @@ -31,6 +31,13 @@ FALLOW_STDERR_TMP=$(mktemp) # scope step (#3191/#3995): base = the parent of the first commit that added # anything under the phase's own directory. Commit subjects carry no milestone # bound — a same-numbered phase in a previous milestone used to win the grep. +# #4467: the BASE half above is lockstep with Tier 3 (#3995); the TIP is not. +# fallow's own --changed-since is one-sided by design (no upper-bound flag +# exists in fallow 2.70.0 — --diff-file only scopes line ranges within the +# hot-path-touched verdict, it is not a general file-scoping control), so +# reviewing an earlier phase after a later one has landed pulls the later +# phase's files into this pass's audited set. Do not assume this step and +# Tier 3's scope step agree on the tip just because they agree on the base. FALLOW_SCOPE_ARGS=() if [ \"$FALLOW_SCOPE\" = \"phase\" ]; then # #3995: phase-directory anchor — same derivation as the Tier-3 scope step