Skip to content

Commit abe51a1

Browse files
Fork Merge Botclaude
authored andcommitted
fork: make the merge checks executable, and the inventory data
The 2026-08-08 upstream merge took 89 minutes. Most of that was not conflict resolution; it was performing checks that existed only as prose in docs/fork/upstream-merge-inventory.md, one at a time, and rediscovering two things the doc could have told me before I started. Five changes, in the order they pay off. **The inventory is data now.** docs/fork/inventory.json holds the fork-owned concerns, path policy, fork inventory, tripwires, deliberately deleted upstream paths, off-repository state and convergence entries. The markdown keeps only what a check cannot hold — the four re-application deltas, where the unsupported-method set comes from, and the reasoning behind the path policy rule — and drops from 784 lines to 243. **The checks run.** Five dependency-free scripts under the skill: - `preflight.mjs` — the range, stale entries, the owned-concern sweep, and the conflict forecast: every file both sides touched, grouped by the verdict that resolves it, before the merge starts. - `inventory-check.mjs` — every inventory path read back out of upstream/main. This is the one that matters: last merge, upstream moved SidebarV2's content into Sidebar.tsx and Sidebar.tsx's into LegacySidebar.tsx. Git cannot see a content swap as a rename — it is a delete paired with a modify, which no -M threshold detects — so it surfaced as a modify/delete conflict mid-merge. Run against the pre-merge tree, this check names it in about a second. - `tripwires.mjs`, `unsupported-methods.mjs`, `verify.mjs`. Running inventory-check against the current tree immediately found three dead path-policy entries that had been faithfully transcribed forward through several merges, for directories deleted in pingdotgg#13 and pingdotgg#26. **Verification is one command, earlier.** `verify.mjs` runs tripwires, the unsupported-method derivation, format, lint, types and tests — and does not stop at the first failure, so a formatting nit no longer hides the type errors behind it. It raises the heap the web suite needs, whose failure mode is otherwise an exit 137 that reads like a real test failure. The skill now runs it *before* the documentation steps, because its output is their input. **Counts come out of prose.** Both snapshots the last merge relied on were stale. "38 of 87 methods" and "Clerk 4 / pairing 73 / session bootstrap 9" are replaced by the command that derives them. **The fork test no longer hard-codes upstream paths.** features.test.ts read `../components/Sidebar.tsx?raw`; when upstream renamed that file the whole suite failed to build, at a module path, saying nothing about the gate. It now reads the guarded files out of inventory.json and reaches them through import.meta.glob, so a rename fails as a named assertion that says which entry to re-point — and the test and the merge scripts read the same guards, so they cannot drift apart. Verified: fmt, lint, typecheck and 1908 tests pass. `tripwires.mjs` reports one finding, which is genuine and already tracked — thread-transfer-report.yml went active on GitHub when the merge branch was pushed and still needs disabling. Co-Authored-By: Claude Opus 5 <[email protected]>
1 parent 426b4b7 commit abe51a1

13 files changed

Lines changed: 2095 additions & 771 deletions

File tree

‎.agents/skills/fork-upstream-merge/SKILL.md‎

Lines changed: 139 additions & 83 deletions
Large diffs are not rendered by default.
Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
#!/usr/bin/env node
2+
/**
3+
* Checks every path in docs/fork/inventory.json against upstream/main and the
4+
* working tree, and reports the entries that have gone stale.
5+
*
6+
* This is the check that catches the expensive kind of merge surprise: a fork
7+
* delta whose anchor upstream has renamed, deleted, or started shipping itself.
8+
* The 2026-08-08 merge found `SidebarV2.tsx` deleted upstream only by hitting a
9+
* modify/delete conflict mid-merge, because git cannot see that swap as a
10+
* rename (upstream moved SidebarV2's content into Sidebar.tsx and Sidebar.tsx's
11+
* into LegacySidebar.tsx — a delete paired with a modify, which no `-M`
12+
* threshold detects). Reading the inventory's own paths back out of upstream
13+
* finds it in a second, before the merge starts.
14+
*
15+
* It also enforces the rule the path policy states in prose: an entry may be
16+
* `ours` only if the path does not exist in upstream/main.
17+
*
18+
* node .agents/skills/fork-upstream-merge/scripts/inventory-check.mjs
19+
*/
20+
import * as NodeFS from "node:fs";
21+
import * as NodePath from "node:path";
22+
import * as NodeURL from "node:url";
23+
24+
import {
25+
REPO_ROOT,
26+
Report,
27+
filesInRef,
28+
filesInWorkingTree,
29+
loadInventory,
30+
refExists,
31+
runMain,
32+
} from "./lib.mjs";
33+
34+
/** Verdicts whose paths upstream is expected to own. */
35+
const UPSTREAM_OWNED = new Set(["decide", "converged", "theirs", "theirs-verbatim"]);
36+
37+
function checkPathPolicy(inventory, report, ref) {
38+
const section = report.section("Path policy vs upstream");
39+
for (const entry of inventory.pathPolicy) {
40+
for (const path of entry.paths) {
41+
const upstreamHits = filesInRef(ref, [path]).length;
42+
const localHits = filesInWorkingTree([path]).length;
43+
44+
if (entry.verdict === "ours" && upstreamHits > 0) {
45+
section.fail(`${entry.id}: \`ours\` path is now shipped by upstream — ${path}`, [
46+
`upstream/main has ${upstreamHits} file(s) here; \`ours\` would discard them.`,
47+
"Split the entry, or change the verdict to decide/converged.",
48+
]);
49+
continue;
50+
}
51+
if (UPSTREAM_OWNED.has(entry.verdict) && upstreamHits === 0) {
52+
section.fail(`${entry.id}: upstream no longer has ${path} (${entry.verdict})`, [
53+
localHits > 0
54+
? "The fork still has it, so upstream renamed or deleted it out from under the delta."
55+
: "Gone from both sides — the entry is dead and should be removed.",
56+
"Find where upstream moved the behavior and re-home the delta before merging.",
57+
]);
58+
continue;
59+
}
60+
if (localHits === 0 && upstreamHits === 0) {
61+
section.fail(`${entry.id}: ${path} exists on neither side`, ["Stale entry — remove it."]);
62+
continue;
63+
}
64+
if (localHits === 0) {
65+
section.warn(`${entry.id}: ${path} is absent from the fork's tree`, [
66+
"Expected when the fork deliberately deletes an upstream path; otherwise stale.",
67+
]);
68+
continue;
69+
}
70+
section.ok(`${entry.id}: ${path} (${entry.verdict})`);
71+
}
72+
}
73+
}
74+
75+
function checkInventoryPaths(inventory, report) {
76+
const section = report.section("Fork inventory vs working tree");
77+
for (const entry of inventory.inventory) {
78+
const dead = entry.paths.filter((path) => filesInWorkingTree([path]).length === 0);
79+
if (dead.length === 0) {
80+
section.ok(`${entry.id}: ${entry.paths.length} path(s) live`);
81+
continue;
82+
}
83+
section.fail(`${entry.id}: ${dead.length} path(s) no longer exist`, [
84+
...dead,
85+
"The behavior this entry protects has moved. Re-point the entry in the same merge.",
86+
]);
87+
}
88+
}
89+
90+
/**
91+
* A gate that a merge can silently drop is worth naming a file and a symbol for.
92+
* Grepping for it here fails the check the moment an upstream rewrite takes the
93+
* gate with it, rather than at review time.
94+
*/
95+
function checkGuards(inventory, report) {
96+
const section = report.section("Delta guards");
97+
const guarded = inventory.inventory.filter((entry) => entry.guard);
98+
if (guarded.length === 0) return section.info("no guards declared");
99+
for (const entry of guarded) {
100+
const { symbol, files } = entry.guard;
101+
for (const file of files) {
102+
if (filesInWorkingTree([file]).length === 0) {
103+
section.fail(`${entry.id}: guarded file is gone — ${file}`, [
104+
"Upstream renamed or deleted it; the gate needs a new home.",
105+
]);
106+
continue;
107+
}
108+
const source = NodeFS.readFileSync(NodePath.resolve(REPO_ROOT, file), "utf8");
109+
if (source.includes(symbol)) section.ok(`${entry.id}: ${symbol} present in ${file}`);
110+
else section.fail(`${entry.id}: ${symbol} MISSING from ${file}`, [entry.mustSurvive]);
111+
}
112+
}
113+
}
114+
115+
function checkDeletedPaths(inventory, report, ref) {
116+
const section = report.section("Upstream paths the fork deletes");
117+
for (const path of inventory.deletedUpstreamPaths.paths) {
118+
const upstreamHas = filesInRef(ref, [path]).length > 0;
119+
const localHas = filesInWorkingTree([path]).length > 0;
120+
if (!upstreamHas) {
121+
section.warn(`${path}: upstream dropped it too`, [
122+
"Nothing left to re-delete; remove it from deletedUpstreamPaths.",
123+
]);
124+
} else if (localHas) {
125+
section.fail(`${path}: restored in the fork`, [
126+
"Taking upstream on a delete/modify conflict silently brings these back.",
127+
]);
128+
} else {
129+
section.ok(`${path}: still deleted`);
130+
}
131+
}
132+
}
133+
134+
/** Exported so `preflight.mjs` runs the same checks inside its own report. */
135+
export function runInventoryChecks(inventory, report, ref) {
136+
checkPathPolicy(inventory, report, ref);
137+
checkInventoryPaths(inventory, report);
138+
checkGuards(inventory, report);
139+
checkDeletedPaths(inventory, report, ref);
140+
}
141+
142+
export function requireUpstream(inventory) {
143+
const ref = inventory.upstream.ref;
144+
if (!refExists(ref)) {
145+
throw new Error(
146+
`${ref} is not available. Run:\n` +
147+
` git remote add upstream ${inventory.upstream.url}\n` +
148+
` git fetch upstream`,
149+
);
150+
}
151+
return ref;
152+
}
153+
154+
// Only run the report when invoked directly, not when preflight imports it.
155+
if (NodePath.resolve(process.argv[1] ?? "") === NodeURL.fileURLToPath(import.meta.url)) {
156+
runMain(async () => {
157+
const inventory = loadInventory();
158+
const report = new Report();
159+
runInventoryChecks(inventory, report, requireUpstream(inventory));
160+
report.print();
161+
162+
if (report.failed) {
163+
process.stdout.write(
164+
"Inventory is stale. Fix the entries above (in docs/fork/inventory.json) before merging.\n\n",
165+
);
166+
return 1;
167+
}
168+
process.stdout.write("Inventory matches upstream and the working tree.\n\n");
169+
return 0;
170+
});
171+
}

0 commit comments

Comments
 (0)