Skip to content

Commit 7f8dad0

Browse files
donjor-agent[bot]donjor
authored andcommitted
fix(fork-sync): a sync refuses a tip that lost fork hook lines (#1891)
## Problem A rebase can drop a fork hook's marked lines while typecheck and tests stay green. The 3748 proof tip lost lines in 36 hook keys; 25 vanished entirely. Nothing in `fork:sync` or `fork:ci` noticed. ## Change - **New `hooks` step:** after carry, before check or CI - **Count:** `fork-hook:` marker lines per key in `apps` and `packages` - **Refuses:** any key with fewer lines on the tip than the trunk - **Retire:** `Fork-Hook-Retired: domain/name` trailer on a tip commit - **Both paths:** session and land run refuse alike - **Skill and docs:** new row, tip-work rule, step table ## Scope and approval Found by the fork-sync proof run for #1886. The human chose a hard gate on lost hooks. It lives in `fork:sync`, not `fork:ci`: only a sync has a trunk to compare against. Refs #1886 ## Verification - `fork-sync.test.ts`: names a hook with fewer lines; a retirement trailer clears it (80/80) - `vp run fork:ci` → exit 0 Claude Opus 5.5 via Claude Code. ## Fork trailers Fork-Domain: fork-meta Fork-Tier: bugfix Fork-Upstreamable: no Co-authored-by: donjor <[email protected]>
1 parent 998088f commit 7f8dad0

4 files changed

Lines changed: 106 additions & 0 deletions

File tree

‎.agents/skills/fork-sync/SKILL.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ Never edit a report; a rerun supersedes it.
5151
| `rebased` | 0 | [tip work](#tip-work), then [hand off](#hand-off) |
5252
| `blocked` | 1 | [resolve](#resolve) the seams |
5353
| `failed` `carry` | 1 | [resolve](#resolve) the pick |
54+
| `failed` `hooks` | 1 | restore or retire each; rerun |
5455
| `failed` `check` | 1 | fix it as [tip work](#tip-work), rerun |
5556
| `failed` other | 1 | fix the remote, tag, or `error`; rerun |
5657

@@ -115,6 +116,9 @@ Adaptation the candidate needs (build or test fixes, ports) commits at the tip o
115116
- **Owner:** newest fork commit on those lines
116117
- **Find it:** `vp run fork:fixup-fold`
117118
- **Unmarked fork line:** the fixup marks it
119+
- **Lost hook:** restore it at the tip
120+
- Target carries it: drop its leftovers
121+
- Trailer: `Fork-Hook-Retired: domain/name`
118122
- **Local checks:** each rerun runs `fork:ci`
119123
- Focused tests: `vp test run`
120124
- **Gate:** candidate CI in the land run

‎docs/fork/operations/fork-sync.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,16 @@ Without a named tag it targets a valid [marker](#resolution-marker)'s tag the tr
2121
It folds each `fixup! <subject>` landing into the one fork commit it names, a squash landing's trailing ` (#N)` included, and refuses a fixup naming none or several.
2222
It rewords only an owner that absorbs a squash-landed fixup: the fixup's PR link joins its `Squashes:` list, rendered the way fork:fold renders one.
2323
The rebase refuses a rebased tip that dropped any PR link, except from a commit the target carries: patch-for-patch, or superseded with every path it touched identical to the target.
24+
Typecheck and tests miss a dropped hook, so the `hooks` step counts marked lines per key; a tip commit's `Fork-Hook-Retired: domain/name` trailer retires a hook the target made obsolete.
2425

2526
| Step | Does | Fails when |
2627
| ------- | ---------------------------------------------- | ------------------------ |
2728
| fetch | `upstream` tags, `origin/hyprws`, the marker | fetch error |
2829
| target | named, kept, marker's, or newest tag | not a release tag |
2930
| rebase | `git rebase -i --autosquash <tag>` | a seam no resolver fixes |
3031
| carry | cherry-picks trunk commits since the lease | a pick conflicts |
32+
| hooks | each trunk hook keeps its marked lines | a hook lost lines |
33+
| check | session: `vp run fork:ci` on the tip | the battery is red |
3134
| ci | land: [candidate CI](#candidate-ci) on the tip | the run is not green |
3235
| push | land: `--force-with-lease=hyprws:<lease>` | lease refused |
3336
| blocked | land: one attention issue per red run | `gh` refuses the write |

‎scripts/fork-sync.test.ts‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ import {
1414
closeBlocks,
1515
failureMarker,
1616
foldSyncMessages,
17+
lostHooks,
1718
refuseDroppedLinks,
1819
resolveFixups,
1920
publishAttention,
@@ -631,6 +632,23 @@ it("refuses a session's hand-off while the local fork:ci battery is red on its t
631632
});
632633
});
633634

635+
it("names a hook the tip carries fewer marked lines of, unless a tip commit retires it", () => {
636+
withFixture(CLEAN, (f) => {
637+
const write = (lines: ReadonlyArray<string>, message: string): string => {
638+
NodeFS.mkdirSync(NodePath.join(f.root, "apps"), { recursive: true });
639+
NodeFS.writeFileSync(NodePath.join(f.root, "apps", "a.ts"), lines.join("\n"));
640+
f.git(["add", "apps"], f.root);
641+
f.git(["commit", "--quiet", "-m", message], f.root);
642+
return f.git(["rev-parse", "HEAD"], f.root);
643+
};
644+
const trunk = write(["a(); // fork-hook: d/call", "b(); // fork-hook: d/call"], "hook");
645+
const tip = write(["a(); // fork-hook: d/call"], "drop one");
646+
assert.deepStrictEqual(lostHooks(realRunner, f.root, trunk, tip), ["d/call (2→1)"]);
647+
const retired = write(["a();"], "retire\n\nFork-Hook-Retired: d/call");
648+
assert.deepStrictEqual(lostHooks(realRunner, f.root, trunk, retired), []);
649+
});
650+
});
651+
634652
const redThenGreen = (): { readonly red: Recording; readonly green: Recording } => ({
635653
red: exec({ ci: { conclusion: "failure" } }),
636654
green: exec(),

‎scripts/fork-sync.ts‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1123,6 +1123,67 @@ export const finishRebase = (
11231123
return writeMarker(runner, root, { tip, tag: target.tag, lease, todo: null });
11241124
};
11251125

1126+
/** The trailer a tip commit carries to retire a hook the target made obsolete. */
1127+
export const HOOK_RETIRED_TRAILER = "Fork-Hook-Retired";
1128+
1129+
/** Marked lines per hook key in `ref`'s tree. */
1130+
const hookLineCounts = (
1131+
runner: CommandRunner,
1132+
root: string,
1133+
ref: string,
1134+
): ReadonlyMap<string, number> => {
1135+
// Exit 1 is no match; anything else is a read failure.
1136+
const result = gitResult(runner, root, [
1137+
"grep",
1138+
"-h",
1139+
"-o",
1140+
"-E",
1141+
"fork-hook:[[:space:]]*[A-Za-z0-9_-]+/[A-Za-z0-9_-]+",
1142+
ref,
1143+
"--",
1144+
"apps",
1145+
"packages",
1146+
]);
1147+
if (result.status !== 0 && result.status !== 1)
1148+
throw new Error(`git grep for fork hooks failed on ${ref}: ${result.stderr.trim()}`);
1149+
const counts = new Map<string, number>();
1150+
for (const marker of lines(result.stdout)) {
1151+
const key = marker.replace(/^fork-hook:\s*/, "");
1152+
counts.set(key, (counts.get(key) ?? 0) + 1);
1153+
}
1154+
return counts;
1155+
};
1156+
1157+
/**
1158+
* The hook keys whose marked lines the tip carries fewer of than the trunk:
1159+
* a resolution that silently dropped fork behaviour, which typecheck and tests
1160+
* miss. A key a commit above the merge base retires with a
1161+
* `Fork-Hook-Retired: domain/name` trailer is exempt.
1162+
*/
1163+
export const lostHooks = (
1164+
runner: CommandRunner,
1165+
root: string,
1166+
trunk: string,
1167+
tip: string,
1168+
): ReadonlyArray<string> => {
1169+
const before = hookLineCounts(runner, root, trunk);
1170+
const after = hookLineCounts(runner, root, tip);
1171+
const since = git(runner, root, ["merge-base", trunk, tip]);
1172+
const retired = new Set(
1173+
lines(
1174+
git(runner, root, [
1175+
"log",
1176+
`--format=%(trailers:key=${HOOK_RETIRED_TRAILER},valueonly)`,
1177+
`${since}..${tip}`,
1178+
]),
1179+
),
1180+
);
1181+
return [...before]
1182+
.filter(([key, count]) => (after.get(key) ?? 0) < count && !retired.has(key))
1183+
.map(([key, count]) => `${key} (${count}→${after.get(key) ?? 0})`)
1184+
.toSorted();
1185+
};
1186+
11261187
const VERIFICATION_ENV_KEYS = new Set([
11271188
// Vite+'s `node_modules/.bin/vp` shim exports an absolute NODE_PATH into the
11281189
// store of the checkout it belongs to; inherited, it pins module resolution
@@ -2094,6 +2155,26 @@ export const run = (argv: ReadonlyArray<string>, options: RunOptions = {}): numb
20942155
}
20952156
const newSha = finished.tip;
20962157

2158+
// hooks — every fork hook the trunk marks survives on the tip, or a tip commit retires it
2159+
step = "hooks";
2160+
const lost = lostHooks(runner, root, expectedOld, newSha);
2161+
if (lost.length > 0)
2162+
return fail({
2163+
conflicts: [...rebase.recorded],
2164+
marker: markerReport(finished),
2165+
decision: {
2166+
worktree: land ? "" : worktree,
2167+
tip: newSha,
2168+
paths: [],
2169+
resume: [
2170+
`# restore each hook as tip work, or retire one the target made obsolete with a`,
2171+
`# '${HOOK_RETIRED_TRAILER}: <domain/name>' trailer on a tip commit; then rerun:`,
2172+
`vp run fork:sync ${target.tag}`,
2173+
].join("\n"),
2174+
},
2175+
error: `${lost.length} fork hook(s) lost marked lines against ${expectedOld.slice(0, 7)}: ${lost.join(", ")}`,
2176+
});
2177+
20972178
if (!land) {
20982179
// check — the land run's local battery, so a handed-off tip is one it accepts
20992180
step = "check";

0 commit comments

Comments
 (0)