Skip to content

fork seam check: #506 lens follow-ups (exact pending ceiling, summary, tests) - #535

Merged
scuttletoby merged 6 commits into
mainfrom
fix/510-seam-lens-followups
Nov 19, 2026
Merged

scuttletoby merged 6 commits into
mainfrom
fix/510-seam-lens-followups

Conversation

@scuttletoby

Copy link
Copy Markdown
Owner

Fixes #510. Refs #311.

The six follow-ups from the two lenses on #506.

  1. Exact pending ceiling on a pull request (fork-seam-check.cjs, findUnlistedChanges). A pull request that removes more lines than it adds from a pending file must now set its own ceiling to exactly main's ceiling less that many lines. If none are left it must drop the entry, or it may move the file to files, where the run from upstream judges it. Before, only a ceiling left too high was refused. A ceiling set too low, or an entry dropped while lines remained, passed, and then the next fork-follow run refused main. The own list is still read only to refuse, so it can never widen the gate. The message says what the list has now ("its list has 1" / "its list drops it").
  2. Summary wording (fork-follow.sh). "Seam list lowered" goes into the run summary only after the plan has finished (after the re-check, the outside-workflow check and the outputs). It now says "Committed on top of the rebased series (the candidate)". A run that stops after the lowering pushes nothing and now claims nothing either. The "still lowers again" refusal now quotes what was lowered and says the lowering commit was only in the run's checkout.
  3. Pending file with no fork line left that lost still names (lowerList). It is now moved to files with "added": [] and a fixed why. That is stricter: no fork line may come back, and a pull request may lose none of its lines. Before, it kept its old ceiling and blocked the next same-base run until a pull request moved it by hand. The re-check passes, and the next run passes (end-to-end test). If a file is named __proto__, it stays an own key.
  4. "Update the branch from its base" hint (findSeamBreaches). It is shown only when the base branch's newer copies alone made the line too many. If the branch would be refused from its merge-base too (for example, 2 copies against an allowance of 1), the hint is left out.
  5. Docs (docs/fork/updates.md). Neither seam check runs on merge_group. The ruleset's "up to date before merging" rule (Owner: require PR branches to be up to date before merging into main? (recommend yes) #444, now on) is what makes the later of two changes be judged together with the other one. This replaces "the ruleset does not require…". The pending-ceiling and lowering paragraphs now match 1 to 3.
  6. End-to-end tests (fork-follow.test.sh):
    • a re-run of a rebase that lowered the list advances to the earlier release;
    • the "still lowers again" refusal (a seam check in the series that always lowers), and the summary claims nothing;
    • one count lowered and another raised in one run is refused, and nothing is lowered or committed;
    • a lost count lowered through fork-follow (2/2 → 1/1) together with item 3, and the next run passes.

Tests

  • node --test .github/scripts/fork-seam-check.test.cjs: 74 pass. bash .github/scripts/fork-follow.test.sh: all passed.
  • Fail before: I ran the new tests against the old scripts. These fail: the exact-ceiling, hint and lowerList unit tests, the "still lowers again" e2e and its summary check, and the lost/move e2e plus its next run. The re-run/advance and lowered-plus-raised e2e tests pass on the old code too. They are the coverage the lenses asked for, not bug reproductions.
  • oxfmt --check is clean on the changed JS and Markdown files.

State question (runs again, stops half-way, old or empty state)

  • Runs again: the lowering is deterministic, and the moved entry gets a fixed why. A re-run rebuilds the same tree and advances to the earlier release (tested).
  • Stops half-way: the summary is written only at the end of the plan. The lowering commit exists only in the plan's checkout, and every later failure pushes nothing (tested for the re-check failure and for a rise).
  • Old or empty state:
    • A list with no pending/lost key is unchanged.
    • An existing list with a zero-line pending file that lost names is now moved, not left as a note.
    • A PR whose own list does not parse keeps the old behaviour: the rule is skipped, and listProblem refuses the PR when it edits the list.
    • A PR that does not touch a pending file is not affected. Raising a ceiling with a list-only PR (the owner's step after a rebase rise) is still allowed, because the rule applies only when a file shrinks.

#311 seam-check items

Done before this PR, with tests on main. I checked each one:

  • 1: moved/deleted lines, through the lost counts.
  • 2: indentation is kept.
  • 3: the tip copy is spent, and the strict up-to-date rule applies.
  • 4: tests for:
    • the removed-workflows list read from main;
    • only fork-* workflows may be deleted;
    • the ceiling boundary;
    • a fork-named upstream file.
  • 5: an upstream rename is a note.
  • 6: --from-upstream.
  • The follow-up comment: a shrink must lower its own ceiling. Refs #311, Fixes #325, Fixes #416: seam check follow-ups #506 did that, and item 1 above makes it exact.

Remaining: items 7 and 8. Moving the 29 generic seam lines (}, };, ) {, /**, */) out of apps/server/src/serverSettings.ts into fork files is a refactor of server code in other files, not small, so it is not in this PR. #311 stays open for it.

Upstream fit

Only fork files change: .github/scripts/fork-*, docs/fork/. No upstream file gains a line, so no seam announcement is needed.

General vs project

General: the seam check and fork-follow are fork tooling that any fork of T3 Code following upstream would use. No project facts are added.

🤖 Generated with Claude Code

…, tests)

- A pull request that shrinks a "pending" file must set its own ceiling to
  exactly main's less the lines it removes (or drop the entry when none are
  left, or move the file to "files"). A ceiling set too low, or an entry
  dropped while lines remain, used to pass and stop the next nightly.
- fork-follow writes "Seam list lowered" to the run summary only once the
  plan has finished; a run stopped after the lowering claimed a commit it
  never pushed. The "still lowers again" refusal now names what was lowered.
- After a rebase, a pending file with no fork line left that "lost" still
  names moves to "files" with no seam line (tighter), instead of keeping its
  old ceiling and blocking the next same-base run.
- The "update the branch from its base" hint shows only when the base
  branch's newer copies alone made the line too many.
- Docs: neither seam check runs on merge_group; the strict up-to-date rule
  (#444) is what judges two such changes together.
- End-to-end fork-follow tests: a re-run of a lowering rebase advances to the
  earlier release; the "still lowers again" refusal; a lowered and a raised
  count in one run commit nothing; a "lost" count lowered through fork-follow.

Fixes #510

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

Copy link
Copy Markdown
Owner Author

Review (independent, Opus)

Head reviewed: a17aa26. Verdict: 1 BLOCKING, 1 SHOULD-FIX, 1 NIT.

Tests. On the PR head, node --test .github/scripts/fork-seam-check.test.cjs and bash .github/scripts/fork-follow.test.sh both pass. I copied the new test files onto main's scripts. 4 unit tests fail there: the exact ceiling, the CLI refusal wording, the hint and lowerList. 4 end-to-end checks fail too: the "still lowers again" refusal, the summary that claims nothing, the lost/move lowering, and the next run after the move. The re-run/advance and lowered-plus-raised end-to-end tests pass on main too, as the PR body says. Items 2 to 6 look right to me. I checked the merge_group docs claim against the workflows and the ruleset: the seam check runs only on pull_request_target/pull_request/push, and the required checks use the strict policy.

1. BLOCKING: the exact ceiling refuses a correct PR that restores an upstream line, and asks for a ceiling the nightly refuses

.github/scripts/fork-seam-check.cjs:359 (want = ceiling + grows), and the same rule in docs/fork/updates.md:64.

grows is the change in the file's total line count. The fork-line count from upstream changes by a different amount when the PR also restores upstream text the fork had changed. For each line text, with u/h = copies in upstream/head: fork lines = max(0, h-u) and gone = max(0, u-h). So Δfork = Δtotal + Δgone, and Δgone is negative when an upstream line comes back. The PR-mode rule ignores Δgone. 27 of the 66 pending files have a lost entry with gone ≥ 1: the fork changed an upstream line there. So "move the fork change out, put upstream's line back" is the normal way these files shrink.

Scenario (run through findUnlistedChanges on this head and on main):

  • upstream p.ts = a(); b(x); c();
  • main = a(); b(x, fork); forkG(); forkH(); c();: pending 3, lost {lines:1, gone:1}.
  • The PR reverts b(x, fork) to b(x) and moves forkG() out. Head = a(); b(x); forkH(); c();. The correct list is pending 1, with the lost entry removed.
  • This PR: refused, with "set it to 2 … (its list has 1; main holds its ceiling exactly)". main: passes.
  • If the author does what the message says (pending 2), the nightly's pre-rebase check (fork-follow.sh:269, not after a rebase, so ceilings refuse) fails with "pending" with 1 fork lines, fewer than its ceiling of 2. Every fork-follow run stays stopped until another PR lowers it.
  • The only way through is to split the work into a removal PR and a separate revert PR (grows 0, not checked). The message does not say that.

So this rule refuses a correct PR, and the value its message names is the wrong ceiling the nightly then refuses. Before this PR the rule was "at most", which let the correct value through.

Suggested fix: count the own list's gone change too. Use want = max(0, ceiling + grows + (ownGone - mainGone)), where ownGone/mainGone are lost[file].gone in the PR's list and in main's list (0 when the file has no entry). The nightly holds gone exact, so an own list with the right gone gets the exact pending value, and a wrong gone is refused by the nightly anyway. That needs ownLost read beside ownPending/ownFiles. Add a unit test for the scenario above. Or go back to own <= want for files whose main list has a lost entry. If you go further, the identity also lets grows == 0 with Δgone ≠ 0 (a pure revert) be held exact.

2. SHOULD-FIX: moving a pending file to files skips the check even while fork lines are left

.github/scripts/fork-seam-check.cjs:351 (!Object.hasOwn(ownFiles, file)), and the test at .github/scripts/fork-seam-check.test.cjs:2063 asserts this behaviour.

Scenario: pending p.ts 3. The PR removes one fork line, so 2 are left, and its own list moves p.ts to files with "added": []. This PR's run passes. main passes too, so this is not new. The nightly then refuses main: p.ts: adds \f1();`, p.ts: adds `f2();`. The PR body says #510 item 1 now refuses "an entry dropped while lines remained", but a move to fileswith lines remaining is that same drop. Exempt the move only whenwant === 0. If the move ever needs to keep lines, require each remaining line to be in that file's added. That is a seam addition for the owner to review, and the same want` caveat from finding 1 applies.

3. NIT: the "update the branch" hint still shows when the announcement has expired

.github/scripts/fork-seam-check.cjs:196 uses inDate for both pushes, but the reason pushed at :215 (not late) is judged against allowed. Scenario: the announcement of fork(); is expired, added is empty, the base tip already has one fork(); (the merge-base has none), and the branch adds one. The refusal says "update the branch from its base", but the branch would also be refused from its merge-base (the expired announcement allows 0), and updating does not help. main prints the same, so this is not new. Pass the allowance map that applies (allowed for the reasons push, inDate for the late push) into adds.

State question

  • Re-run on the same base: the lowering and MOVED_WHY are deterministic, and the tree matches, so the run advances to the earlier release (tested).
  • Stops half-way, after lowering and before push: lowered_summary is printed only after the outputs block (fork-follow.sh:622). Every fail before it exits with nothing pushed and nothing claimed (tested). The existing "Seam check notes" summary is still written right away. That is fine, because notes describe the run, not a push.
  • Old seams list: a zero-line pending file that lost names is moved, the re-check passes, and the next run passes (tested). __proto__ stays an own key. parseConfig runs on the result, so a malformed move cannot be committed.
  • Empty pending or lost, or the key missing: lowerList and findUnlistedChanges handle undefined/{}. A PR whose own list does not parse skips the rule, and listProblem refuses it.
  • A file with zero lines left: want clamps to 0 and the entry must go, or move to files (see finding 2 for the lines-left case).
  • Can a change stop the nightly on a correct PR, or let a wrong ceiling through? Yes, through finding 1: a correct PR is refused, and the check names a ceiling that stops the nightly. Finding 2 lets a wrong list through, but main already did that. I found nothing else.

…nly when empty, hint)

- The exact pending ceiling on a pull request counts the upstream lines the change puts back:
  main's ceiling + lines gained - (main's "lost" gone - the change's own), so a correct ceiling
  is accepted and the one the message names is what the run from upstream holds. Every edited
  pending file is held, not only one that shrinks; a list-only change is not.
- A pending file may move to "files" in the change's own list only when no fork line is left.
- The "update the branch from its base" hint is judged by the allowance that applies, so an
  expired announcement does not get it.

Tests: the revert-plus-move case, the move refusal, the expired hint, and a property check that
every list the pull request's run accepts passes the run from upstream.

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

Copy link
Copy Markdown
Owner Author

Review fixes (head ea80357)

  1. BLOCKING, fixed. The exact ceiling now counts upstream lines the change puts back. It uses want = main's ceiling + lines gained - (main's lost.gone - the PR's own lost.gone), at .github/scripts/fork-seam-check.cjs:374 (ownLost is read beside ownPending/ownFiles, :367). Per line text, fork lines minus gone lines equals head copies minus upstream copies, so this is exact. Every edited pending file is held now, not only one that shrinks: a pure revert (grows == 0, gone changes) is held too. A list-only change (file text unchanged) is still not held, so a list-only PR can still correct main's list. Docs: docs/fork/updates.md:62. Tests:
    • fork-seam-check.test.cjs:2135: the review's case (revert b(x, fork), move forkG() out). 1 passes on both runs, 2 is refused with "set it to 1", and the run from upstream refuses 2. The pure revert is covered too.
    • :2158, property check: 3000 seeded random upstream/main/head triples. Every own list the PR run accepts (dropped, moved, or ceiling 1…main+3, with the lost entry the run from upstream holds) passes the run from upstream (findSeamBreaches, findUnlistedChanges, findLostLines, as fork-follow's pre-rebase check calls them). The right list always passes the PR run unless the file grows. On the old script it fails.
  2. SHOULD-FIX, fixed. A move from pending to files is refused while fork lines are left, including a list-only move: fork-seam-check.cjs:387. It names the ceiling to keep. The move is allowed when none are left. Test: fork-seam-check.test.cjs:2079. The old assertion that allowed the move is replaced.
  3. NIT, fixed. adds() now takes the allowance that applies: inDate for late, allowed for reasons (fork-seam-check.cjs:198, :214, :217). An expired announcement gets no "update the branch" hint. An in-date one keeps it. Test: fork-seam-check.test.cjs:2303.

Tests. node --test .github/scripts/fork-seam-check.test.cjs: 77 pass. bash .github/scripts/fork-follow.test.sh: all passed. oxfmt --check is clean on the 3 files. On the previous script, the 5 new or changed seam tests fail: the exact ceiling, the put-back case, the move, the property check and the hint.

State question.

  • Re-run on the same base: this is a pure check with no writes, and it gives the same result.
  • Stopped half-way: nothing in PR mode writes anything.
  • Old list (no lost key): gone counts as 0, so the result is as before.
  • Own list with no lost entry: its gone is 0. If main's gone is 1 or more, that counts as putting lines back, which is the review's case.
  • Empty pending or lost: handled (?? {}, Object.hasOwn).
  • A branch behind main's lost: it can be told a different value. Updating from the base fixes that, as the up-to-date rule already requires.
  • A wrong own gone: the run from upstream still refuses it, as the review noted. This run cannot see upstream, so the property check holds lost to the right value.

@scuttletoby
scuttletoby merged commit 1e5b69d into main Nov 19, 2026
37 checks passed
scuttletoby added a commit that referenced this pull request Nov 21, 2026
…, tests) (#535)

* fork seam check: #506 lens follow-ups (exact pending ceiling, summary, tests)

- A pull request that shrinks a "pending" file must set its own ceiling to
  exactly main's less the lines it removes (or drop the entry when none are
  left, or move the file to "files"). A ceiling set too low, or an entry
  dropped while lines remain, used to pass and stop the next nightly.
- fork-follow writes "Seam list lowered" to the run summary only once the
  plan has finished; a run stopped after the lowering claimed a commit it
  never pushed. The "still lowers again" refusal now names what was lowered.
- After a rebase, a pending file with no fork line left that "lost" still
  names moves to "files" with no seam line (tighter), instead of keeping its
  old ceiling and blocking the next same-base run.
- The "update the branch from its base" hint shows only when the base
  branch's newer copies alone made the line too many.
- Docs: neither seam check runs on merge_group; the strict up-to-date rule
  (#444) is what judges two such changes together.
- End-to-end fork-follow tests: a re-run of a lowering rebase advances to the
  earlier release; the "still lowers again" refusal; a lowered and a raised
  count in one run commit nothing; a "lost" count lowered through fork-follow.

Fixes #510

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

* fork seam check: #535 review fixes (gone in the exact ceiling, move only when empty, hint)

- The exact pending ceiling on a pull request counts the upstream lines the change puts back:
  main's ceiling + lines gained - (main's "lost" gone - the change's own), so a correct ceiling
  is accepted and the one the message names is what the run from upstream holds. Every edited
  pending file is held, not only one that shrinks; a list-only change is not.
- A pending file may move to "files" in the change's own list only when no fork line is left.
- The "update the branch from its base" hint is judged by the allowance that applies, so an
  expired announcement does not get it.

Tests: the revert-plus-move case, the move refusal, the expired hint, and a property check that
every list the pull request's run accepts passes the run from upstream.

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

* fork seam check: comments within the lint rules (no issue numbers, 4 lines at most)

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
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.

Seam check: #506 lens follow-ups (exact pending ceiling, summary wording, tests)

1 participant