Skip to content

Commit aafd1e1

Browse files
donjor-agent[bot]donjor
authored andcommitted
fix(fork): folds never drop a PR link, and a plan line can attach one (#1498)
## Problem A refold drops PR links an older fold wrote as a bare `(#N)` on its member lines: `forkPullRequests` harvests only full `RSI-Software/t3code-hyprws#N` refs there. The 2026-10-02 sync refold lost `#395` this way; `#29` and `#177` went earlier. ## Change - **Harvest:** `forkPullRequests` also reads a bare `(#N)` on `Squashes:` member lines - **Guard:** `prove` runs a link guard; it refuses a fold that drops any link an old commit cites - **Backfill:** a plan field `RSI-Software/t3code-hyprws#N` attaches that link to the line's lead member line; a lone member then renders as a fold - **Docs:** fork guide and `fork-fold` skill state the rule and the plan field On today's trunk the bare harvest already rescues 7 links that the next refold would have dropped (`#118`, `#142`, `#174`, `#178`, `#183`, `#671`, `#753`). ## Scope and approval Refs #1491 Implements its decision rows: harvest, guard, backfill on the next fold, no pin tags or extra refs. No trunk history is rewritten here, so the backfill conditions stay open until the next fold publishes with these plan lines: ```text be0d8ab #395 c12585f #177 2613b16 #29 ``` The other eight links still need an attach-or-retire call at that fold. ## Verification ```text vp test run scripts/fork-fold.test.ts → exit 0 (32 passed) vp run typecheck (scripts) → exit 0 vp run fork:ci → exit 0 ``` <details> <summary>Dry-run backfill on origin/hyprws b4b09b8 (no ref moved)</summary> An identity plan of all 139 ahead commits plus the three link fields above: ```text fork:fold apply → 139 commits → 139 on 9f65218585 - be0d8ab feat(desktop): launch Electron … (#224) (#224) (#395) - c12585f feat(agents): select custom main-thread agents (#31) (#31) (#177) - 2613b16 refactor(web): centralize thread route navigation (#1480) (#29) fork:fold prove origin/hyprws 9f65218585 member guard → 0 finding(s) link guard → 0 finding(s) git diff --quiet → exit 0 fork:delta --check → exit 0 fork:scan --replay-of b4b09b8 → exit 0 ``` </details> Claude Opus 5.5, Claude Code. ## Fork trailers Squashes: - be0770d fix(fork): folds never drop a PR link, and a plan line can attach one (#1498) (#1498) - 6d6fe23 fixup! fix(fork): folds never drop a PR link, and a plan line can attach one (#1498) (#1498) Fork-Domain: fork-meta Fork-Tier: core Co-authored-by: donjor <[email protected]>
1 parent b452743 commit aafd1e1

5 files changed

Lines changed: 194 additions & 24 deletions

File tree

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

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,14 +48,17 @@ One line per output commit: member shas, tab-separated, in stack order.
4848
```text
4949
# a comment
5050
9e2656daeb 4f7a0802b5 fix(fork): optional subject override
51-
25bf181b2a
51+
25bf181b2a RSI-Software/t3code-hyprws#395
5252
```
5353

5454
- **Coverage:** every ahead commit, exactly once
5555
- **Order:** line order is the new stack order
5656
- **One member:** message kept verbatim
5757
- **Fold:** lead prose, `Squashes:` with each member's PR references, merged trailers
5858

59+
A `RSI-Software/t3code-hyprws#N` field attaches that PR link to the lead's `Squashes:` line; a lone member then renders as a fold.
60+
Backfill a link an earlier fold lost this way.
61+
5962
## Fold rule
6063

6164
One PR-sized intent per output commit: a feature absorbs its fixes and resolutions.
@@ -80,7 +83,7 @@ Split each one on a detached copy of the head (`git worktree add --detach <dir>
8083

8184
Run the fold with `--head <split head>`: each fixup joins its owner's plan line and squashes there, so the owner's `Squashes:` lists its own old sha, the repair sha, and the repair's references.
8285
`prove` and `publish` take the pre-split tip as `<old>`; a tree-equal fold needs no retest.
83-
`prove` also refuses a commit naming no `<old>` member or touching a path none of its members touched, and an old commit owned by no new commit or, unless it carries `Fork-Repair`, by several.
86+
`prove` also refuses a dropped PR link, a commit naming no `<old>` member or touching a path none of its members touched, and an old commit owned by no new commit or, unless it carries `Fork-Repair`, by several.
8487

8588
## Stops
8689

‎docs/fork/internals/fork-development.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,8 @@ Superseded-upstream first, fork-specific last:
104104
A generic fix in no product domain is `upstream-fixes`.
105105
New commits land on top and move down at the next rebase.
106106
Reorder only on a clean stack; publish with a lease.
107-
A squash lists its members under `Squashes:`, one `- <sha> <subject>` line each plus every PR reference the member carried, so the rebase scan reads every member as a replay counterpart; a refold keeps the links an earlier fold gathered.
107+
A squash lists its members under `Squashes:`, one `- <sha> <subject>` line each plus every PR reference the member carried, so the rebase scan reads every member as a replay counterpart.
108+
A refold keeps every link an earlier fold gathered, bare `(#N)` markers included, and `prove` refuses a fold that drops one.
108109

109110
### Branch bases
110111

‎scripts/fork-fold.test.ts‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ import {
1414
forkPullRequests,
1515
memberFindings,
1616
foldTrailers,
17+
linkFindings,
1718
parsePlan,
1819
type ProveStep,
1920
resolvePlan,
@@ -52,6 +53,16 @@ it("parses members, a subject override, and skips blank and comment lines", () =
5253
assert.throws(() => parsePlan("aaaa1111\tHEAD~1\tsubject\n"), /plan line 1/);
5354
});
5455

56+
it("parses fork PR link fields on a plan line beside its members and subject", () => {
57+
const link = "RSI-Software/t3code-hyprws#395";
58+
assert.deepStrictEqual(parsePlan(`aaaa1111\t${link}\tbbbb2222\t${link}\tfix: reworded\n`), [
59+
{ line: 1, members: ["aaaa1111", "bbbb2222"], links: [link], subject: "fix: reworded" },
60+
]);
61+
const stack = stackOf(commit("aaaa1111"));
62+
assert.deepStrictEqual(resolvePlan(parsePlan(`aaaa1111\t${link}\n`), stack)[0]?.links, [link]);
63+
assert.throws(() => parsePlan("aaaa1111\t#395\tsubject\n"), /plan line 1/);
64+
});
65+
5566
it("refuses a plan that drops, repeats, or invents a commit", () => {
5667
const stack = stackOf(commit("aaaa1111"), commit("bbbb2222"), commit("cccc3333"));
5768
assert.throws(
@@ -230,6 +241,105 @@ it("carries an earlier fold's links into the next fold", () => {
230241
assert.deepStrictEqual(squashedMembers(folded), ["cccc3333", "dddd4444"]);
231242
});
232243

244+
it("keeps the bare (#N) links an older fold's member lines carry", () => {
245+
// The shape folds wrote before full refs: a member line ending in a bare squash marker.
246+
const older = commit("cccc3333", {
247+
subject: "feat(desktop): launch Electron into Hyprland workspaces (#224)",
248+
message: [
249+
"feat(desktop): launch Electron into Hyprland workspaces (#224)",
250+
"",
251+
"Squashes:",
252+
"",
253+
"- 6dd0b2fd97 feat(desktop): launch Electron into Hyprland workspaces (#224)",
254+
"- d0aef4f9c7 fix(web): keep the sidebar brand inside a project window (#395)",
255+
"",
256+
"Fork-Domain: multi-window",
257+
"Fork-Tier: core",
258+
].join("\n"),
259+
});
260+
const folded = foldMessage({ members: [older, commit("dddd4444")] });
261+
assert.include(
262+
folded,
263+
"- cccc3333 feat(desktop): launch Electron into Hyprland workspaces (#224) (RSI-Software/t3code-hyprws#224) (RSI-Software/t3code-hyprws#395)",
264+
);
265+
assert.notInclude(folded, "d0aef4f9c7");
266+
});
267+
268+
it("attaches plan links to the lead line, re-rendering a single member as a fold", () => {
269+
const lead = commit("aaaa1111", {
270+
subject: "refactor(web): centralize thread route navigation",
271+
message:
272+
"refactor(web): centralize thread route navigation\n\nWhy.\n\nFork-Domain: fork-meta\nFork-Tier: qol\n",
273+
});
274+
const linked = foldMessage({
275+
members: [lead],
276+
links: ["RSI-Software/t3code-hyprws#29", "RSI-Software/t3code-hyprws#2"],
277+
});
278+
assert.strictEqual(
279+
linked,
280+
[
281+
"refactor(web): centralize thread route navigation",
282+
"",
283+
"Why.",
284+
"",
285+
"Squashes:",
286+
"",
287+
"- aaaa1111 refactor(web): centralize thread route navigation (RSI-Software/t3code-hyprws#29) (RSI-Software/t3code-hyprws#2)",
288+
"",
289+
"Fork-Domain: fork-meta",
290+
"Fork-Tier: qol",
291+
].join("\n"),
292+
);
293+
assert.deepStrictEqual(squashedMembers(linked), ["aaaa1111"]);
294+
// A link a member line already names is not repeated.
295+
const tail = commit("bbbb2222", { subject: "fix: b (#29)", message: "fix: b (#29)\n" });
296+
const folded = foldMessage({ members: [lead, tail], links: ["RSI-Software/t3code-hyprws#29"] });
297+
assert.strictEqual(folded.split("RSI-Software/t3code-hyprws#29").length - 1, 1);
298+
assert.include(folded, "- bbbb2222 fix: b (#29) (RSI-Software/t3code-hyprws#29)");
299+
});
300+
301+
it("no fold drops a link any member cites, and the link guard finds one that does", () => {
302+
const members = [
303+
commit("aaaa1111", { subject: "feat: a (#10)", message: "feat: a (#10)\n" }),
304+
commit("bbbb2222", {
305+
subject: "fix: b",
306+
message: "fix: b\n\nhttps://github.com/RSI-Software/t3code-hyprws/pull/11\n",
307+
}),
308+
commit("cccc3333", {
309+
subject: "feat: c",
310+
message:
311+
"feat: c\n\nSquashes:\n\n- 0123456 feat: old (#12)\n- 1234567 fix: old (RSI-Software/t3code-hyprws#13)\n",
312+
}),
313+
commit("dddd4444", {
314+
subject: "fixup! feat: a (#10)",
315+
message: "fixup! feat: a (#10)\n\nSquashes:\n\n- 2345678 fix: repair (#14)\n",
316+
}),
317+
];
318+
const cited = members.flatMap((member) => forkPullRequests(member.message));
319+
assert.strictEqual(new Set(cited).size, 5);
320+
const [a, b, c, fixup] = members as [FoldCommit, FoldCommit, FoldCommit, FoldCommit];
321+
// A fixup piece always folds with its owner.
322+
for (const block of [
323+
{ members },
324+
{ members: [a, fixup] },
325+
{ members: [b, c] },
326+
{ members: [c] },
327+
]) {
328+
const kept = forkPullRequests(foldMessage(block));
329+
const dropped = block.members
330+
.flatMap((member) => forkPullRequests(member.message))
331+
.filter((ref) => !kept.includes(ref));
332+
assert.deepStrictEqual(dropped, []);
333+
}
334+
335+
const folded = commit("ffff0001", { message: foldMessage({ members }) });
336+
assert.deepStrictEqual(linkFindings(stackOf(...members), stackOf(folded)), []);
337+
const bare = commit("ffff0002", { message: "feat: a\n\nSquashes:\n\n- aaaa1111 feat: a\n" });
338+
assert.deepStrictEqual(linkFindings(stackOf(a), stackOf(bare)), [
339+
"RSI-Software/t3code-hyprws#10: cited by aaaa1111 feat: a (#10), by no new commit",
340+
]);
341+
});
342+
233343
it("carries only fork PR links: no upstream ref, no bare body #N", () => {
234344
const message = [
235345
"feat(web): port of pingdotgg/t3code#6452 (#1355)",
@@ -311,13 +421,15 @@ it("reads fork PR refs from a subject marker, a fork pull URL, and earlier Squas
311421
"Squashes:",
312422
"",
313423
"- aaaa1111 feat: older (RSI-Software/t3code-hyprws#1370)",
424+
"- bbbb2222 fix: older still (#395)",
314425
"",
315426
"Fork-Domain: fork-meta",
316427
].join("\n");
317428
assert.deepStrictEqual(forkPullRequests(message), [
318429
"RSI-Software/t3code-hyprws#1355",
319430
"RSI-Software/t3code-hyprws#1361",
320431
"RSI-Software/t3code-hyprws#1370",
432+
"RSI-Software/t3code-hyprws#395",
321433
]);
322434
});
323435

‎scripts/fork-fold.ts‎

Lines changed: 72 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ const HELP = `Usage: vp run fork:fold <command> [options]
4040
Commands:
4141
list [--json] Ahead commits grouped by Fork-Domain, with files
4242
apply <plan.tsv> Replay the plan onto a detached tip; prints the tip sha
43-
prove <old> <new> Member guard, tree-equal, fork:delta --check, fork:scan on <new>
43+
prove <old> <new> Member and link guards, tree-equal, fork:delta --check, fork:scan on <new>
4444
publish <old> <new> Prove, push the expected-old lease, move local hyprws
4545
4646
Options:
@@ -51,6 +51,8 @@ Options:
5151
5252
Plan: one line per output commit, tab-separated member shas in stack order.
5353
A last field that is not a sha overrides the first member's subject.
54+
A RSI-Software/t3code-hyprws#N field attaches that PR link to the line's
55+
commit, even a single member, which then renders as a fold.
5456
Blank lines and # lines are ignored. Every ahead commit appears exactly once,
5557
and a line's members never mix Fork-Domain values.
5658
@@ -175,10 +177,12 @@ export const parsePlan = (text: string): ReadonlyArray<PlanLine> =>
175177
text.split("\n").flatMap((raw, index) => {
176178
const trimmed = raw.trim();
177179
if (trimmed.length === 0 || trimmed.startsWith("#")) return [];
178-
const fields = raw
180+
const all = raw
179181
.split("\t")
180182
.map((field) => field.trim())
181183
.filter((field) => field.length > 0);
184+
const links = [...new Set(all.filter((field) => PLAN_LINK.test(field)))];
185+
const fields = all.filter((field) => !PLAN_LINK.test(field));
182186
const last = fields.at(-1) ?? "";
183187
const subject = SHA.test(last) ? undefined : last;
184188
const members = subject === undefined ? fields : fields.slice(0, -1);
@@ -188,7 +192,14 @@ export const parsePlan = (text: string): ReadonlyArray<PlanLine> =>
188192
`plan line ${index + 1}: expected tab-separated shas, got "${bad ?? raw}"`,
189193
);
190194
}
191-
return [{ line: index + 1, members, ...(subject === undefined ? {} : { subject }) }];
195+
return [
196+
{
197+
line: index + 1,
198+
members,
199+
...(links.length === 0 ? {} : { links }),
200+
...(subject === undefined ? {} : { subject }),
201+
},
202+
];
192203
});
193204

194205
/** Maps each plan member onto the stack; every ahead commit must appear exactly once. */
@@ -215,7 +226,11 @@ export const resolvePlan = (
215226
const domains = [...new Set(members.map((member) => member.domain ?? ""))];
216227
if (domains.length > 1)
217228
problems.push(`line ${line.line}: fold mixes Fork-Domain: ${domains.toSorted().join(", ")}`);
218-
return { members, ...(line.subject === undefined ? {} : { subject: line.subject }) };
229+
return {
230+
members,
231+
...(line.links === undefined ? {} : { links: line.links }),
232+
...(line.subject === undefined ? {} : { subject: line.subject }),
233+
};
219234
});
220235
for (const commit of stack.commits) {
221236
if (!used.has(commit.sha)) problems.push(`${commit.short} ${commit.subject}: missing`);
@@ -256,18 +271,23 @@ const withoutSquashes = (prose: string): string =>
256271

257272
const FORK_REPO = "RSI-Software/t3code-hyprws";
258273
const FORK_PULL_URL = new RegExp(`https://github\\.com/${FORK_REPO}/pull/(\\d+)`, "g");
259-
const FORK_ITEM_REF = new RegExp(`${FORK_REPO}#(\\d+)`, "g");
274+
/** A plan field naming a fork pull request to attach to the line's commit. */
275+
const PLAN_LINK = new RegExp(`^${FORK_REPO}#\\d+$`);
276+
/**
277+
* A PR ref on a `Squashes:` member line: the full fork ref, or the bare `(#N)`
278+
* squash marker a member subject carries — the only form folds before
279+
* RSI-Software/t3code-hyprws#1404 wrote.
280+
*/
281+
const MEMBER_LINE_REF = new RegExp(`${FORK_REPO}#(\\d+)|\\(#(\\d+)\\)`, "g");
260282
/** GitHub squash-merge appends ` (#N)` to a landed pull request's subject. */
261283
const SQUASH_MARKER = /\(#(\d+)\)\s*$/;
262284
/** A `Squashes:` member line; fork-scan's squashedMembers reads the same shape. */
263285
const SQUASH_MEMBER_LINE = /^- [0-9a-f]{7,40}\b/;
264286

265287
/**
266-
* The fork pull requests a commit cites, as full `RSI-Software/t3code-hyprws#N`
267-
* refs in first-seen order: its subject's squash marker, a fork pull URL in its
268-
* message, and refs already listed on an earlier fold's `Squashes:` lines. A
269-
* bare `#N` in a body is usually an issue (`Closes #N`), and any other repo's
270-
* ref posts backlinks upstream, so neither is carried.
288+
* The fork pull requests a commit cites, as full `RSI-Software/t3code-hyprws#N` refs in first-seen
289+
* order: its subject's squash marker, fork pull URLs, and earlier `Squashes:` refs, full or bare
290+
* `(#N)`. A bare `#N` in a body is usually an issue, and another repo's ref backlinks upstream.
271291
*/
272292
export const forkPullRequests = (message: string): ReadonlyArray<string> => {
273293
const normalized = message.replace(/\r\n/g, "\n");
@@ -279,11 +299,15 @@ export const forkPullRequests = (message: string): ReadonlyArray<string> => {
279299
add(SQUASH_MARKER.exec(subject.trim())?.[1]);
280300
for (const match of normalized.matchAll(FORK_PULL_URL)) add(match[1]);
281301
for (const line of squashesLines(bodyLines.join("\n"))) {
282-
for (const match of line.matchAll(FORK_ITEM_REF)) add(match[1]);
302+
for (const ref of memberLineRefs(line)) refs.set(ref, ref);
283303
}
284304
return [...refs.keys()];
285305
};
286306

307+
/** The fork pull requests one `Squashes:` member line names, as full refs. */
308+
const memberLineRefs = (line: string): ReadonlyArray<string> =>
309+
[...line.matchAll(MEMBER_LINE_REF)].map((match) => `${FORK_REPO}#${match[1] ?? match[2]}`);
310+
287311
/** The trimmed `- <sha> …` member lines under a message's first `Squashes:` heading. */
288312
const squashesLines = (message: string): ReadonlyArray<string> => {
289313
const lines = message.replace(/\r\n/g, "\n").split("\n");
@@ -333,25 +357,33 @@ const memberLine = (member: FoldCommit): string => {
333357
};
334358

335359
/**
336-
* One member keeps its message verbatim. A fold keeps the first member's prose,
337-
* lists every member under `Squashes:` (fork-scan's squashedMembers reads it)
338-
* with its fork pull request links, and ends with the merged trailers.
360+
* One member without plan links keeps its message verbatim. A fold keeps the
361+
* first member's prose, lists every member under `Squashes:` (fork-scan's
362+
* squashedMembers reads it) with its fork pull request links, appends the
363+
* plan's links to the lead line, and ends with the merged trailers.
339364
*/
340365
export const foldMessage = (block: FoldBlock): string => {
341366
const [first] = block.members;
342367
if (first === undefined) throw new FoldError("empty plan line");
343368
const [subjectLine = "", ...rest] = first.message.replace(/\r\n/g, "\n").split("\n");
344369
const subject = block.subject ?? subjectLine;
345-
if (block.members.length === 1) return [subject, ...rest].join("\n").trimEnd();
370+
const attached = block.links ?? [];
371+
if (block.members.length === 1 && attached.length === 0) {
372+
return [subject, ...rest].join("\n").trimEnd();
373+
}
346374
const prose = withoutSquashes(bodyProse(rest.join("\n")));
375+
// Two pieces of one repair render the same line; a repair is listed once.
376+
const [lead = "", ...others] = new Set(block.members.map(memberLine));
377+
const listed = new Set([lead, ...others].flatMap(memberLineRefs));
378+
const added = attached.filter((ref) => !listed.has(ref)).map((ref) => ` (${ref})`);
347379
return [
348380
subject,
349381
...(prose.length === 0 ? [] : ["", prose]),
350382
"",
351383
"Squashes:",
352384
"",
353-
// Two pieces of one repair render the same line; a repair is listed once.
354-
...new Set(block.members.map(memberLine)),
385+
`${lead}${added.join("")}`,
386+
...others,
355387
"",
356388
foldTrailers(block.members),
357389
].join("\n");
@@ -534,6 +566,19 @@ export const memberFindings = (old: FoldStack, next: FoldStack): ReadonlyArray<s
534566
return findings;
535567
};
536568

569+
/**
570+
* Link guard: every fork pull request an old commit cites must still be cited
571+
* by some new commit, so no fold ever drops a link.
572+
*/
573+
export const linkFindings = (old: FoldStack, next: FoldStack): ReadonlyArray<string> => {
574+
const kept = new Set(next.commits.flatMap((commit) => forkPullRequests(commit.message)));
575+
return old.commits.flatMap((commit) =>
576+
forkPullRequests(commit.message)
577+
.filter((ref) => !kept.has(ref))
578+
.map((ref) => `${ref}: cited by ${commit.short} ${commit.subject}, by no new commit`),
579+
);
580+
};
581+
537582
export type ProveStep = (command: string, args: ReadonlyArray<string>) => CommandResult;
538583

539584
export const proveChecks = (
@@ -567,10 +612,16 @@ const prove = (git: FoldGit, step: ProveStep, base: string, oldRef: string, newR
567612
const next = git.text(["rev-parse", "--verify", `${newRef}^{commit}`]);
568613
const target = git.text(["merge-base", base, next]);
569614
let failed = 0;
570-
const findings = memberFindings(readStack(git, base, old), readStack(git, base, next));
571-
for (const finding of findings) process.stderr.write(`member: ${finding}\n`);
572-
if (findings.length > 0) failed += 1;
573-
process.stdout.write(`member guard → ${findings.length} finding(s)\n`);
615+
const oldStack = readStack(git, base, old);
616+
const nextStack = readStack(git, base, next);
617+
for (const [guard, findings] of [
618+
["member", memberFindings(oldStack, nextStack)],
619+
["link", linkFindings(oldStack, nextStack)],
620+
] as const) {
621+
for (const finding of findings) process.stderr.write(`${guard}: ${finding}\n`);
622+
if (findings.length > 0) failed += 1;
623+
process.stdout.write(`${guard} guard → ${findings.length} finding(s)\n`);
624+
}
574625
for (const [command, args] of proveChecks(base, old, next, target)) {
575626
const result = step(command, args);
576627
if (result.status !== 0) {

‎scripts/lib/fork-fold-rebase.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,11 +34,14 @@ export interface FoldStack {
3434
export interface PlanLine {
3535
readonly line: number;
3636
readonly members: ReadonlyArray<string>;
37+
/** Fork PR refs the plan attaches to this commit, as `RSI-Software/t3code-hyprws#N`. */
38+
readonly links?: ReadonlyArray<string>;
3739
readonly subject?: string;
3840
}
3941

4042
export interface FoldBlock {
4143
readonly members: ReadonlyArray<FoldCommit>;
44+
readonly links?: ReadonlyArray<string>;
4245
readonly subject?: string;
4346
}
4447

0 commit comments

Comments
 (0)