Skip to content

fork seams: after a rebase, exclude an upstream file named like a fork file (#432) - #567

Merged
scuttletoby merged 4 commits into
mainfrom
fix/432-fork-seam-followups
Nov 20, 2026
Merged

scuttletoby merged 4 commits into
mainfrom
fix/432-fork-seam-followups

Conversation

@scuttletoby

Copy link
Copy Markdown
Owner

Fixes #432

Where each point of #432 stands

# Point State
1 Upstream file taken for a fork file by name The single file was excluded in #436. This PR adds the general rule (below).
2 files/pending keys must be repository paths Done in #436 (isRepoPath, a test row per bad shape).
3 lost counts cannot tell lines apart Done in #436: the docs claim was corrected ("A count is not a set of lines…"). Content tracking was not built: keep each count small.
4 Ruleset does not require up-to-date branches Done in the ruleset, not in code. main: CI before merge has had strict_required_status_checks_policy: true since 2026-11-18 (ruleset history version 58460387), so a list-editing PR has to be green on top of main's current list before it merges. That makes a list-hash check unnecessary. #398 and #412 merged before that change; main's list as it is now parses, and with this branch's script all three modes (below) exit 0.
5 Operator message when a count rises after a rebase Done in #436 (AFTER_REBASE_RISE).
6 Duplicate keys, forged annotation line, "The series was left as it is", mutants killed only by a load failure Done in #436 and #446: findDuplicateKey, printable (control, bidi and invisible characters), the fork-follow message, and named tests.
7 announced must be a known key Done in #436.

What this PR changes (point 1, the general rule)

Before: from upstream, findHiddenUpstreamFiles refuses any upstream file that a pull request's run would take for a fork file, because of its name (fork-*, forkName*, …) or a forkFiles pattern. Upstream has its own thread-"fork" feature and names files after it, so each new file like that stopped fork-follow after the rebase until someone added a ! entry with a pull request. That is what happened with scripts/scenarios/fork-title-regenerates-from-inherited-history.e2e.ts.

Now: right after a rebase that writes a lowered list (--after-rebase --lowered-list, which is how fork-follow always calls it), each such file goes into lowered.hidden. lowerList takes it out of the fork's files, in the lowering commit fork-follow already makes:

  • if forkFiles names exactly that path, the entry is removed;
  • if a name or another pattern still takes it, !path is added (it replaces the exact entry when the name alone would still take it).

The lowered list is parsed again, and fork-follow checks it once more before going on, as it already does for counts.

Why this is safe, and why #436's reason for not doing it does not apply here: #436 turned down the rule "a file upstream has is never a fork file" because a pull request's run has no upstream commit, so it cannot apply that rule. This PR does not change the pull request's run. It changes the list that run reads, and only ever makes it stricter: an excluded file is judged as upstream's. The run from upstream already judges every file as upstream's (findUnlistedChanges ignores isForkFile there), so a fork change in such a file is still refused and nothing is written. Before a rebase, or after one without a list to write, the file is still refused, because nothing would commit the exclusion and main's pull request runs would keep the gap.

Small extras: a comment in fork-follow.sh, one sentence of the run summary ("…and each excluded file is upstream's"), and the docs in docs/fork/updates.md. The commit subject fork-follow writes stays "fork seams: lower counts after the rebase onto …"; the body lists each change.

Proof

  • Tests fail on the old code (I ran the new tests against origin/main's fork-seam-check.cjs):
    • node --test .github/scripts/fork-seam-check.test.cjs: both new tests fail (the CLI one is refused with "Fork changes to upstream files must stay within the seam lines"; the lowerList one throws because nothing is lowered). With the change: 87/87 pass.
    • bash .github/scripts/fork-follow.test.sh: the two new plan checks fail on the old code ("2 failed"). With the change: all pass.
  • The #426 follow-ups: upstream e2e file taken for a fork file, list path validation, operator messages #432 case on the real tree: with main's !scripts/scenarios/fork-title-…e2e.ts entry taken out (scratch commit, since reset), from v0.1.11-nightly.20261119.4954:
  • The real list on this branch: --from-upstream, --from-upstream --after-rebase --lowered-list (writes nothing) and the PR shape --config-ref origin/main origin/main HEAD all exit 0.

State question

  • Runs again: with the lowered list committed, the next --after-rebase --lowered-list, --after-rebase and plain run all exit 0, lower nothing and write no file (tested). fork-follow's plan test also runs the next plan from the new base and shows it releases with no new lowering.
  • Stopped half-way: the exclusion goes only into the lowered list that fork-follow commits on top of the rebased series. A run refused for any other reason writes nothing (tested: a fork line in the same file is refused, and no file is written). A plan stopped after the lowering pushes nothing, as for counts.
  • Old, empty or missing state:
    • a list with no forkFiles key gets ["!path"] (tested);
    • a list whose own entry names the upstream file loses that entry (tested);
    • a fork-named path that is also listed gets its entry replaced by !path (tested);
    • the fork's own files under the same patterns stay the fork's (tested);
    • callers that pass no hidden set to lowerList (the older {pending, lost} shape) work as before (existing tests).
  • Before the rebase / no list to write: still refused (tested for both).

General vs project

  • General: when a gate cannot tell two classes apart in the cheap run (here a pull request's run, with no upstream commit), the run that can tell them apart should write the distinction down for it, but only in the direction that makes the gate stricter, and in the same reviewed commit as its other automatic tightenings. Raising a limit stays the owner's job.
  • Project: the fork-name patterns, forkFiles, .github/fork-seams.json and fork-follow's lowering commit are this fork's. The script reads them from the list, not from code.

🤖 Generated with Claude Code

…k file (#432)

From upstream, a file upstream has that a pull request's run takes for the
fork's own (its name or a "forkFiles" pattern) was refused, so every such
upstream file stopped fork-follow after the rebase until a pull request added
a `!` entry by hand. Right after a rebase that writes a lowered list, the
check now puts each one in that list instead: its own "forkFiles" entry goes,
and a `!path` excludes it where a name or another pattern still takes it.
That only narrows what a pull request's run takes for the fork's own (the run
from upstream already judges the file as upstream's, so a fork change in it is
still refused). Before a rebase, or with no list to write, it is still refused.

Fixes #432

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@scuttletoby

Copy link
Copy Markdown
Owner Author

Review (lens B: main-move path, state): SAFE — but Lint is red, so not mergeable yet

The logic is safe. The new exclusion only ever makes a pull request's run stricter, and it only goes into a list that fork-follow commits after a good rebase. One blocking item before merge: CI Lint fails on lines this PR adds (main's Fork tests are green, so this PR caused it).

Blocking

Major

None.

Minor

  • fork-seam-check.cjs:939-943: !${file} is compiled as a pattern, not as a literal path. An upstream path that contains * would exclude every file that pattern matches. This fails closed: those fork files become upstream's in a PR run, so PRs that edit them are refused, and nothing is hidden. Even so, a path containing * could keep the old refusal, or the * could be escaped.
  • fork-seam-check.cjs:945-949: if the exact entry appears twice, both copies are removed and the message says "!…" added instead of "replaced". Wording only.
  • Automatic ! entries are never removed if upstream later deletes the file, so they pile up. This also fails closed (the path stays upstream's). It is the same for the hand-added ones today.

What I checked

  • Can it hide a real fork change? No. isForkFile matters in only two places: the PR run's skip (fork-seam-check.cjs:304) and the from-upstream hidden check. From upstream, findUnlistedChanges judges every changed file against upstream's copy (!upstream && …), so a fork line in an excluded file is still refused, and nothing is written (refused must be empty before lowerList runs, :1155). Removing an exact entry or adding a ! only moves files from "fork's own" to "upstream's" in the PR run. Workflow files named fork-*.yml are still refused earlier by refuse_upstream_fork_named (fork-follow.sh, before the --after-rebase seam check), so the sweep cannot keep an upstream workflow enabled.
  • Can an upstream file be taken for a fork file? Only before the rebase, which is the same as on main today. After the move, main's list already carries the exclusion, because the lowering commit is part of the candidate (also on the advance path, where the trees are equal and the output is deterministic: Set order = ls-tree order).
  • Is the list written only after a good rebase? Yes. --lowered-list needs --after-rebase (parseArgs), and fork-follow passes it only at the post-rebase seam_check. The check before the rebase and a run with no list still refuse (tested).
  • Items 2-7 on main: true. isRepoPath (fork-seam-check.cjs:694), AFTER_REBASE_RISE, findDuplicateKey, printable (bidi/invisible ranges), "The series was left as it is." on the seam refusal (fork-follow.sh:245-246), and announced in SEAM_KEYS. The docs say "A count is not a set of lines". Item 4: ruleset main: CI before merge, history 57701556 strict=false → 58460387 (2026-11-18) strict=true.
  • Tests fail on the old code: with main's fork-seam-check.cjs and fork-follow.sh, the 2 new node tests fail (85/87) and the 2 new plan checks fail ("2 failed"). With the PR: 87/87 pass and fork-follow.test.sh passes in full.
  • The #426 follow-ups: upstream e2e file taken for a fork file, list path validation, operator messages #432 case on the real tree (main's !scripts/scenarios/fork-title-… entry removed, from v0.1.11-nightly.20261119.4954): the plain --from-upstream run refuses and names the file. --after-rebase --lowered-list passes and writes a forkFiles identical to main's hand-made one.

State question

  • Runs again: the committed list lowers nothing more (fork-follow's re-check, plus tests in both files). On the advance path the released tree equals the candidate tree.
  • Stops half-way (rebase done, list not committed): the lowering commit lives only in the run's checkout. Any later stop (the second seam run, refuse_outside_workflows, release) pushes nothing. The next run rebases main again and makes the same exclusion. A crash of the second seam run gives exit ≠ 0 → fail, and nothing is pushed.
  • Old, empty or missing forkFiles: no key → ["!path"]; an exact entry → removed; a fork-named exact entry → replaced by !path; patterns are kept and the fork's own files under them stay its own; the lowered text goes through parseConfig again before it is written. Older callers without hidden are unchanged (?? []).

CI: everything else is green; Lint fails, so fork-ci-result is red.

@scuttletoby

Copy link
Copy Markdown
Owner Author

Lens A (trust + state, main-move path): SAFE in logic. Not mergeable until Lint is green

Reviewed head 0f33575b21 (base c09ed55b9f, which is main's tip). I read #432, the diff, fork-seam-check.cjs (forkFileTest, findUnlistedChanges, findHiddenUpstreamFiles, lowerList, parseArgs, main) and fork-follow.sh (seam_run / seam_check, and the call order around the after-rebase check, lines 598-604).

The exclusion only makes the gate stricter. isForkFile is read in two places only: the PR run's skip (fork-seam-check.cjs:304, !upstream && isForkFile(file)) and findHiddenUpstreamFiles. lowerList only ever removes an include entry that equals the path exactly, or adds a !path. Neither can make a new file count as the fork's own. An excluded file is then judged line by line on PRs. From upstream it was already judged that way, so a real fork change in that file is still refused (the CLI test checks this, and checks that nothing gets written). refuse_upstream_fork_named still runs before the after-rebase seam check (fork-follow.sh:601), so an upstream fork-*.yml is still refused and does not get excluded away.

The list is written only after a good rebase. --lowered-list is accepted only together with --from-upstream --after-rebase (parseArgs). The list is written only when nothing at all is refused. fork-follow.sh:602 is the only after-rebase call, and it runs after the rebase has succeeded and after the schema check.

Tests fail on the old code. I checked this: with main's fork-seam-check.cjs and fork-follow.sh, both new node tests fail (85/87) and both new plan checks fail ("2 failed"). With the PR, node gives 87/87 and fork-follow.test.sh prints "all passed".

Items 2-7 of #432, checked on main: isRepoPath is used for files/pending keys. The docs say "A count is not a set of lines" (docs/fork/updates.md:93). AFTER_REBASE_RISE exists. findDuplicateKey and printable exist. The seam refusal message says "The series was left as it is". announced is in SEAM_KEYS. Ruleset main: CI before merge has strict_required_status_checks_policy: true. All of these claims are true.

State:

  • Runs again: covered by the tests, at both the CLI and the plan level.
  • Stopped half-way (rebase done, list not committed): the lowering commit exists only in the run's checkout, and nothing is pushed. The next run rebases the unchanged series again and writes the same exclusion.
  • Rebased and pushed by hand without the lowering commit: the next plain run refuses, as it did before. The docs now say to add !path with a PR.
  • No forkFiles key, an exact entry, or a fork-named path plus an exact entry: each case is tested. With a missing list, readConfigAt still throws (exit 3), so fork-follow stops on a crash. No change there.

Blocking

  1. CI is red: Lint (vp check) finds 3 t3code(no-low-value-comments) errors, all in lines this PR adds. The fork-ci-result check is red too. Main at the same base is green.
    • .github/scripts/fork-seam-check.cjs:557: the findHiddenUpstreamFiles JSDoc is 6 lines, and the rule allows at most 4.
    • .github/scripts/fork-seam-check.cjs:886: the lowerList JSDoc grew to 6 lines, so it is now over the limit.
    • .github/scripts/fork-seam-check.test.cjs:916: the comment starts with #432:. The rule says to drop the issue number.

Major

None.

Minor

  1. The re-check of the lowered list fails open if lowerList stops excluding (fork-seam-check.cjs:567-570, :1155-1162). Whenever --lowered-list is given, a hidden file is never refused. It only goes into lowered.hidden. Suppose a later change makes lowerList return no change for it, or write an exclusion that does not match. Then both the first run and fork-follow's re-check (fork-follow.sh:225) exit 0 with no list written. A series whose list still has the gap reaches main, and PR runs then treat that upstream file as fork-owned. Today's code is correct, and the new tests would catch that regression. Still, one cheap guard would make this path fail closed. In main, after lowerList, refuse if any file in lowered.hidden is still a fork file under the list it just wrote (or under the head's list when nothing was written). On the re-check that guard means "a hidden file is still taken for the fork's own" turns into a refusal instead of a silent pass.

Nits

  • lowerList builds !${file} from the path. In a forkFiles pattern, * is a glob. So an upstream path that contains * would exclude more files than itself. That is stricter, not looser: matching fork files would then be refused on PRs. A path that is only * or ** fails parseConfig, which crashes with exit 3. That is fail-closed, but the message is unclear.
  • The change label is wrong when the exact entry is listed twice. kept.length === patterns.length then reports "!x" added when the entries were in fact replaced (fork-seam-check.cjs:945-950). This only affects the text.
  • !path entries stay after upstream deletes the file. Nothing reports them the way findListedGone reports stale files/pending entries. If the fork later owns that path, the PR hint "add it to forkFiles" (:328) will not help, because the ! entry wins. A Note for a ! entry whose file is gone from both base and head would make this visible.
  • If upstream adds a whole fork/ folder, the list gets one ! entry per file. That works, but it can make the list long.
  • Before, fork-follow stopped when upstream added a file under a path the fork treats as its own (for example apps/server/src/slots/). Now the only record is the lowering commit body and the run summary. That is fine for the gate, but an owner who wants to know when upstream starts working in a fork area should read the summary.

…t still takes a hidden file

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@scuttletoby

Copy link
Copy Markdown
Owner Author

Fix for both reviews (11f4515): the three comments are shortened for the comment rule, and the lowered-list run now fails closed. After lowerList, it refuses if any hidden upstream file is still a fork file under the list it would write, as lens A suggested. All 87 seam-check tests and the fork-follow checks pass. The nits (a * in a path, the label for a duplicate entry, stale ! entries) stay as notes: each one fails safe.

@scuttletoby
scuttletoby merged commit 1602bf6 into main Nov 20, 2026
37 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

#426 follow-ups: upstream e2e file taken for a fork file, list path validation, operator messages

1 participant