[scuttletoby]

What it adds

One more step in the existing No database schema changes job of fork-checks.yml (no new workflow, job name unchanged because rulesets require it):

• .github/scripts/fork-upstream-files-check.cjs refuses a pull request that changes a listed upstream file in any way (edit, delete, rename away, file mode).
• The list is one config line in the workflow: UPSTREAM_FILES: apps/server/src/orchestration-v2/Orchestrator.ts apps/server/src/provider/agentContextBudget.json. To guard another file, add its path there.
• It reads the PR the same way the schema check does: the diff from the merge-base of the PR's base and head, read as git tree entries (nothing from the PR is checked out or run; pull_request_target, default-branch copy).
• Upstream's own changes to these files reach main through fork-follow's nightly rebase, never through a PR, so they are never in a PR's diff. fork-follow is unchanged.
• The step runs even when the schema step refused (!cancelled()), so a PR sees both reasons.
• The new script and its test are added to the schema check's guarded files, so a PR cannot weaken them. This PR therefore goes red on the schema check by design (it changes fork-checks.yml and the schema check): the owner merges past it.

State question

• Runs again: the result depends only on the base and head SHAs; a rerun gives the same output (tested).
• A PR whose base moved: main rebased onto a newer upstream that changed both files: an old PR branch is not blamed for upstream's changes; a branch that took upstream's change another way (cherry-pick, older merge-base) passes because it carries main's copy; a real edit is still refused against the moved base. A branch behind a main that moved forward normally is judged only on its own edits (all tested).
• Empty state: an empty diff (head = base) passes; an empty list exits 2 (usage error, red), so the guard is never silently off.
• Old/broken state: a listed file that main no longer has (upstream moved or removed it) fails every PR with a message naming the list to update. This fails closed: a guard that guards nothing is worse than a red check the owner fixes once.
• Renamed / deleted file: diff runs with --no-renames, so a rename shows as a delete of the listed path and is refused; mode-only changes are refused too.
• The brief's "old settings files / corrupt store file" items do not apply: this check stores nothing.

Tests

.github/scripts/fork-upstream-files-check.test.cjs (node --test, same style as fork-schema-check.test.cjs: real git in a scratch repository): 21 tests. A PR touching each listed file goes red (edit, delete, rename), an unrelated PR stays green, an upstream sync stays green (fork-follow's series check and a PR on the new main), base-moved cases, empty diff, mode change, the list read from the workflow line, the fail-closed missing file, and a workflow contract with mutants (dropped step, no list, no if, base/head swapped, tests not run).

Red-checks: on the code without the change every test fails; broken variants of the script (always pass, diff from the base instead of the merge-base, no "main's copy" rule, no fail-closed, any-commit-ever, no mode check) are each caught by at least one test.

Also run: fork-schema-check.test.cjs (61, one count made relative to the guarded list), fork-ci-tests.test.cjs, fork-contracts.test.py (all passed), fork-follow.test.sh (all passed). actionlint was not run locally (needs a download); CI's workflows job runs it. No TypeScript package touched, so no typecheck.

General vs project

General: the script takes any list of paths and works for any fork that must leave some upstream files alone. Fork-specific: only the one UPSTREAM_FILES line in this fork's fork-checks.yml. Nothing names a project, machine or account.

References

Spec: F3 waitfor.md, test T21 / rule R21 (fork add-ons in their own layers, upstream's Orchestrator.ts and agentContextBudget.json untouched). Check note: waitfor-check-2026-11-14.md, sections 3.4 and 6 (row T21: extend fork-checks.yml, no new workflow).

🤖 Generated with Claude Code

[scuttletoby]

lens: correctness · reviewer: opus high (t3lens97) · read at: ca2c14f

covered: git diff origin/main...HEAD (6 files), the new script and test in full, fork-schema-check.cjs (CHECK_FILES, findSchemaChanges, main), fork-checks.yml, fork-follow's rebase model (series rebased onto upstream tags, upstream SHAs kept), fork-tests.yml (workflows job, fork_ci_result), main's effective rules, this PR's CI run, and how #3/#8/#12 (earlier changes to the schema check's own files) merged.

checks:

• State question: "What happens when this runs again, stops half-way, or meets existing/old/empty state (rerun, half-applied, legacy data, empty history)?" Rerun: same payload (base, head, default SHA), same answer; it stores nothing, so nothing is half-applied. Empty diff passes; an empty list exits 2. Old state: main today has both files exactly as upstream has them (no diff from the merge-base with upstream), so turning the guard on blames no existing branch. A listed file missing on main fails every PR (see finding 6).
• node --test of both test files on the head, with no token: 72/72 pass on a full checkout.
• (1) Upstream sync never blames a PR. I ran 12 scenarios of my own on real git: an old PR against a main rebased onto an upstream that changed the file passes; a PR that merged the new main passes, and still passes after main is rebased again onto a newer upstream that changes the file once more; a criss-cross merge of old main passes. A real change is always refused: edit, delete, rename, file to symlink, an edit kept through a merge from main, and a delete followed by re-adding different content. Deleting and re-adding the same content passes, which is correct because nothing changed. A branch that cherry-picked upstream's older copy while main moved past it is refused with "rebase onto main", which is correct.
• (2) Merge base after a force-rebase: git merge-base falls back to the shared upstream commit, and the listed files are not in that diff, so the PR passes. One case goes red: a stale base.sha (the pre-rebase main) together with a branch that already merged the new main. It reads as "changes it". This is inherited from the schema check, and a rerun does not refresh the payload; only a push does. Not counted as a finding, because GitHub normally refreshes base.sha on synchronize.
• (3) A missing file fails closed, and its message names the list in fork-checks.yml. See finding 6 for what that message leaves out.
• (4) Merge path, in plain terms: main's only required check is fork-ci-result, from fork-tests.yml (ruleset "main: CI before merge", read-only GET /rules/branches/main). "No database schema changes" is not required. fork: green main again (schema-check comments, checkout without submodule cleanup) #8 and fork: outside PRs run nothing, one checkout without actions/checkout, contract tests #12 merged with it red, before the ruleset existed. So today, a PR that is red only on this job can be merged by anyone with write access, with or without the admin bypass. Dropping the bypass (Owner question: remove the admin bypass on fork main? #80) changes nothing for this job. What it does block is this PR as it stands, because fork-ci-result is red (findings 1 and 2). If the owner later makes this job required (needed for T21 to be a real gate, see finding 3) and drops the bypass, then a PR like this one, which changes the check's own files, can only merge by editing the ruleset for the merge.
• (5) Without the script, the new tests fail. The schema test now counts CHECK_FILES.length + 2, which is sound: inclusion is pinned separately by "the check's own files are guarded by the schema check", and both test files are guarded themselves.

finding 1 (high, blocks merge): .github/scripts/fork-upstream-files-check.test.cjs:64. The test file is listed in .github/fork-ci-tests.txt, so fork-tests.yml runs it in the "Workflow lint and upstream drift" job. That job uses a sparse checkout (/.github/ /docs/fork/ /fork-ci/ /fork-kit/ /scripts/, no apps/), so fs.existsSync(apps/...) is false and test 5 fails. This PR's run already shows not ok 5 - the config line lists the upstream files, and each one exists in this repository → fork-ci-result red. After merge, the same job runs on every PR, on every push to main and in release runs (no change gate), so every PR and fork-follow's nightly release would go red. Reproduced with only .github/ on disk: 20 pass, 1 fail. Fix: check existence with git (git cat-file -e HEAD:<path>), add the two paths to the sparse checkout, or drop the existence assert (the script's fail-closed path already covers it).

finding 2 (high, blocks merge): Lint is red on this PR (fork-ci-result needs it), with 4 t3code(no-low-value-comments) errors, all in the new files: section dividers at fork-upstream-files-check.test.cjs:20, :57 and :134, and the header at fork-upstream-files-check.cjs:1, which is over the 4-line limit.

finding 3 (medium, gate not enforced): .github/workflows/fork-checks.yml:26-27 and the PR body say "rulesets require the check by this name". No ruleset requires it (see (4)), so T21, like the schema check, is advisory, and "only the owner may change these files" is not enforced. The owner has to decide this: add "No database schema changes" and "Outside pull request" (Fork checks) to the ruleset's required checks, and settle the merge path for changes to the check itself (keep a bypass, or edit the ruleset for those merges). Until then, the comment should not claim the check is required.

finding 4: none (the stale base.sha case is in checks (2), not counted).

finding 5 (low): fork-upstream-files-check.cjs:24/:41. If a listed path is a directory, ls-tree returns a tree entry, so the path never shows up as "touched" and edits inside it pass silently. The same happens if upstream ever turns a listed file into a directory. Fix: refuse any listed entry whose type is not blob.

finding 6 (low): when upstream removes or moves a listed file, the refusal names only fork-checks.yml. But test 5 also hard-codes the list and checks existence, so "Test the check" fails as well. Because the next step has no if, "Refuse schema and migration changes" is then skipped on every PR until the owner edits both the workflow line and the test. The message should say so, or the test should read the list from the workflow line only.

verdict: NOT SAFE (2 high findings that block merge: this PR's own fork-ci-result is red, and after merge every fork-tests run would be; plus 1 medium (the guard is advisory, owner decision) and 2 low). The guard's logic itself is correct in every upstream-sync and base-moved case I tried.

[scuttletoby]

fix round 1 · fixer: orchestrator (opus high) · head: d7604a9

• finding 1 (high): the test now reads each listed path from git (git ls-tree HEAD), not from the disk. Checked in a checkout with only /.github/: 22/22 pass.
• finding 2 (high): removed the 3 divider comments and cut the script header to 4 lines. CI lint will confirm.
• finding 3 (medium): the comment no longer says a ruleset requires the check. Whether to make it required is owner question Owner question: make the fork's schema / upstream-files check required on main? #98.
• finding 5 (low): a listed path that is not a file on main (a folder or submodule) now fails closed with its own message. The new test fails on the old code: the folder is never a single changed path, so nothing was refused.
• finding 6 (low): the test no longer hard-codes the list. It reads only the workflow line, so fixing that line alone is enough.
• Full checkout: 73/73 pass (both test files).

🤖 Generated with Claude Code