Skip to content

Commit 74f1379

Browse files
donjor-agent[bot]donjor
authored andcommitted
fix(fork-sync): a file's second hooked commit re-applies; hooks must stay pure insertions (#1780)
## Problem Fork sync stops by hand on almost every seam. Across 10 recent sync reports, 450 conflict rows were manual and 11 were hook re-applies. - **263 rows:** not a marked insertion - **154 of those:** earlier hooks in the base - **Bug:** base hooks were never stripped - **So:** a second hooked commit always refused - **Docs:** allowed substitutions re-apply refuses ## Change - **Driver:** strip earlier hooks left unchanged - **Safety:** an edited earlier hook still refuses - **Hook rule:** no removed or modified line - **Fold rule:** owning intent or cancellation - **Second block:** reshape owner in a `fixup!` - **Runbook:** `-preview.` tags skipped on purpose - **Skill:** links tables, stops copying them Replaying the 263 refused rows through the new check: 20 pass. Most of the rest delete unmarked lines; the new hook rule stops new ones. ## Scope and approval Maintainer-requested follow-up to a fork-sync audit. ## Verification - `fork-sync.test.ts -t hook` → 5 passed - New second-hook test fails without the fix - Edited-hook test fails with an unconditional strip - `vp run fork:ci` → exit 0 Claude Opus 5.5 in Claude Code, with GPT Sol and Claude Opus peer thinkers. ## Fork trailers Fork-Domain: fork-meta Fork-Tier: bugfix Fork-Upstreamable: no Co-authored-by: donjor <[email protected]>
1 parent eeef974 commit 74f1379

7 files changed

Lines changed: 103 additions & 32 deletions

File tree

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

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: Fold the RSI-Software/t3code-hyprws ahead commits to one PR-sized i
55

66
# Fork fold
77

8-
Keep each ahead commit one PR-sized intent, so a rebase conflict is solved once.
8+
Keep each ahead commit one PR-sized intent, so a seam conflicts once per replay, not once per commit.
99
The agent picks the folds; `scripts/fork-fold.ts` only lists, applies, and publishes.
1010

1111
## Scope
@@ -63,11 +63,7 @@ Backfill a link an earlier fold lost this way.
6363

6464
One PR-sized intent per output commit: a feature absorbs its fixes and resolutions.
6565

66-
Fold when both hold:
67-
68-
- **Intent:** one
69-
- **Domain:** the same `Fork-Domain`
70-
66+
Fold by [owning intent or cancellation](../../../docs/fork/internals/fork-development.md#fold-to-stay-tight), never by domain alone.
7167
The plan refuses a mixed-domain line: across domains the ledger would lose one.
7268

7369
## Prove

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

Lines changed: 13 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -36,16 +36,8 @@ A moved lease or a new tag rebases again instead.
3636
`.t3/fork-sync/<tag>.json` is the only run authority; the printed Markdown is output.
3737
Post-push recovery reads this file, never a comment.
3838

39-
| Field | Meaning |
40-
| -------------- | ---------------------------------------------------------- |
41-
| `outcome` | `applied`, `already-applied`, `blocked`, or `failed` |
42-
| `target` | The tag and its sha |
43-
| `lease` | The `origin/hyprws` sha the push is leased against |
44-
| `trunk` | Trunk before and after the run |
45-
| `conflicts[]` | Every stop's path, fork and upstream commit, route |
46-
| `ci` | The candidate's `hyprws CI` run, conclusion, and jobs |
47-
| `decision` | A stopped run's worktree, paths, and exact resume commands |
48-
| `decision.tip` | A red candidate's or green dry run's tip, in the worktree |
39+
Fields: [the report](../../../docs/fork/operations/fork-sync.md#the-report).
40+
`decision.tip` names a kept tip: a red candidate or a green dry run.
4941

5042
Never edit a report; a rerun supersedes it.
5143

@@ -106,21 +98,24 @@ In the rebase, resolve minimally: upstream's text stands, and a marked fork hook
10698
Upstream deleted and the fork edit is net-zero: the deletion stands.
10799
A [regenerable file](../../../docs/fork/operations/fork-sync.md#regenerable-files) regenerates; when one is pending, skip `git rebase --continue` and rerun.
108100
Never adapt inside a replayed commit: the hook guard refuses it.
109-
Adaptation lands at the tip, one commit per owner:
101+
Adaptation lands at the tip, one commit per owner, per [Reshape](../../../docs/fork/operations/fork-sync.md#unblocking-by-hand).
110102

111-
| Change | Commit |
112-
| ---------------- | ------------------------------------------------------ |
113-
| Owner adaptation | `fixup! <owner subject>` with the owner's trailers |
114-
| No single owner | one `upstream-fixes` commit naming the upstream change |
115-
| Retirement | its own commit; a fixup body is discarded at the fold |
103+
**Second block:** the same seam stops a second sync.
116104

117-
The next sync folds each fixup into its owner; no `/fork-fold` follows a sync.
105+
- **Cause:** the owner is not a pure insertion
106+
- **Fix:** reshape it in a tip `fixup!`
107+
- **Shape:** [marked insertions only][hook]
108+
- **Next sync:** may stop once more, then folds it
109+
- **Sooner:** fold it now with [fork-fold][fold]
110+
111+
[hook]: ../../../docs/fork/internals/fork-delta.md#marking-a-hook
112+
[fold]: ../fork-fold/SKILL.md
118113

119114
1. Read `decision`: worktree, paths, resume commands.
120115
2. Open that worktree.
121116
3. Resolve each path by the rule above.
122117
4. `git add` them; `git rebase --continue`.
123-
5. Commit any adaptation at the tip, per the table.
118+
5. Commit any adaptation at the tip.
124119
6. Rerun `vp run fork:sync <tag>`.
125120

126121
The worktree ran the `t3.json` setup step, so it builds and tests.
@@ -135,8 +130,6 @@ Each body ends with its open-since date, target count, and last five runs; a cle
135130

136131
### Finished tip from elsewhere
137132

138-
A green dry run's tip needs none of this: the real run adopts it.
139-
140133
1. Open the kept worktree.
141134
2. `git rebase --abort` if one is in progress.
142135
3. `git reset --hard <sha>`.

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

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,10 @@ Decided per commit by the levers retire, reshape, automate, or accept; no gate c
8383
| Multi-line JSX | the pair `{/* fork-hook: <domain>/<name> */}` and `{/* fork-hook-end */}` |
8484

8585
**A hook is exactly one construct:** one import, one call, one `const` from a single fork call, one JSX element, one fork-named property or spread, or one re-export.
86-
**A hook never removes or modifies an upstream line**, except that a marked JSX region may re-indent what it wraps, and an in-place substitution removes the line its marked replacement supplies.
86+
**A hook never removes or modifies an upstream line**, not even to re-indent or substitute one.
87+
Hook re-apply (`reapplyHooks` in `scripts/fork-sync.ts`) accepts only a pure insertion: the fork side minus its marked spans equals the base minus the earlier hooks this commit leaves unchanged.
88+
Any other shape stops every sync that touches the file, and the hook guard misses it because it checks only added lines.
89+
Move the logic into a `*.fork.ts` sibling and leave one marked call; precedent `222ac20a66` for `DesktopClerk.ts`.
8790

8891
**A trailing marker covers the whole statement it closes.** `statementStartLine` in `scripts/lib/fork-hooks.ts` walks back from the marker line.
8992

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ Superseded-upstream first, fork-specific last:
102102
3. Product domains, commits contiguous
103103

104104
A generic fix in no product domain is `upstream-fixes`.
105-
New commits land on top and move down at the next rebase.
105+
New commits land on top and stay there; sync moves only a `fixup!`, beneath its owner.
106106
Reorder only on a clean stack; publish with a lease.
107107
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.
108108
A refold keeps every link an earlier fold gathered, bare `(#N)` markers included, and `prove` refuses a fold that drops one.
@@ -164,9 +164,11 @@ Fork-only paths need no granularity curation.
164164

165165
### Fold to stay tight
166166

167-
Fold the ahead commits to one PR-sized intent each: a feature absorbs its fixes and resolutions, so a rebase conflict is solved once.
167+
Fold the ahead commits to one PR-sized intent each: a feature absorbs its fixes and resolutions, so a seam conflicts once per replay, not once per commit.
168168
The [`fork-fold`](../../../.agents/skills/fork-fold/SKILL.md) skill runs it.
169169
Replay sees each commit, not the net, so an upstream line one commit deletes and a later one restores conflicts on every rebase; [`fork:stale-delete`](../../../scripts/lib/fork-stale-delete.ts) refuses that pair in `fork:ci`.
170+
Fold commits that share one owning intent or cancel each other's upstream hunks, never only because they share a domain.
171+
A cancelling pair across domains cannot share a plan line: drop both hunks by hand at the fold, and `prove` checks the tree.
170172
A `fixup!` that only applies at the branch tip lands green and blocks the next sync; [`fork:fixup-fold`](../../../scripts/fork-fixup-fold.ts) proves each fixup folds at its owner in `fork:ci`.
171173
A fold is tree-equal but rewrites commit boundaries: the release delta revision changes, and a nightly may republish the same tree.
172174

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,8 @@ Discipline lives in [Fork development](../internals/fork-development.md); the pr
99

1010
`hyprws` is the single fork trunk.
1111
The sync driver runs one upstream release tag end to end: one run, one exit code, one report.
12-
It never merges upstream in, nor drops or reorders a commit.
12+
It never merges upstream in, nor drops a commit; only a `fixup!` moves, beneath its owner.
13+
Without a named tag it targets the newest stable or nightly tag; `-preview.` tags are skipped on purpose.
1314
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.
1415
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.
1516
The rebase refuses a rebased tip that dropped any PR link.

‎scripts/fork-sync.test.ts‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -711,6 +711,66 @@ it("resolves a marked hook seam by re-applying the hook", () => {
711711
);
712712
});
713713

714+
it("re-applies a second commit's hook when the first commit's hook is already in the base", () => {
715+
const lines = ["const l1 = 1;", "const l2 = 2;", "const l3 = 3;", "const l4 = 4;"];
716+
withFixture(
717+
{
718+
baseContent: `${lines.join("\n")}\nconst l5 = 5;\n`,
719+
forkContent: `${lines[0]}\nconst one = 1; // fork-hook: fork-meta/one\n${lines.slice(1).join("\n")}\nconst l5 = 5;\n`,
720+
upstreamContent: `${lines.join("\n")}\nconst up = 0;\nconst l5 = 5;\n`,
721+
},
722+
(f) => {
723+
const file = NodePath.join(f.root, "shared.txt");
724+
const content = NodeFS.readFileSync(file, "utf8");
725+
NodeFS.writeFileSync(
726+
file,
727+
content.replace(
728+
"const l5 = 5;",
729+
"const two = 2; // fork-hook: fork-meta/two\nconst l5 = 5;",
730+
),
731+
);
732+
f.git(["commit", "--quiet", "-am", "fork adds a second hook"], f.root);
733+
f.git(["push", "--quiet", "origin", "hyprws"], f.root);
734+
const { runner } = exec();
735+
const code = capture(() => run(["v1.0.0", "--dry-run"], { runner, root: f.root })).value;
736+
assert.strictEqual(code, 0);
737+
const report = readReport(f.root, "v1.0.0");
738+
assert.strictEqual(report.outcome, "applied");
739+
assert.deepEqual(
740+
report.conflicts.map((row) => [row.via, row.hooksReapplied]),
741+
[["hook", ["fork-meta/two"]]],
742+
);
743+
},
744+
);
745+
});
746+
747+
it("refuses a commit that edits an earlier hook, even beside a new one", () => {
748+
withFixture(
749+
{
750+
baseContent: 'import { a } from "a";\n',
751+
forkContent:
752+
'import { a } from "a";\nimport { forkOne } from "fork"; // fork-hook: fork-meta/one\n',
753+
upstreamContent: 'import { a } from "a";\nimport { b } from "b";\n',
754+
},
755+
(f) => {
756+
NodeFS.writeFileSync(
757+
NodePath.join(f.root, "shared.txt"),
758+
'import { a } from "a";\nimport { forkOne, more } from "fork"; // fork-hook: fork-meta/one\nimport { forkTwo } from "fork"; // fork-hook: fork-meta/two\n',
759+
);
760+
f.git(["commit", "--quiet", "-am", "fork edits the hook"], f.root);
761+
f.git(["push", "--quiet", "origin", "hyprws"], f.root);
762+
const { runner } = exec();
763+
assert.strictEqual(capture(() => run(["v1.0.0"], { runner, root: f.root })).value, 1);
764+
const report = readReport(f.root, "v1.0.0");
765+
assert.strictEqual(report.outcome, "blocked");
766+
assert.deepEqual(
767+
report.conflicts.map((row) => row.via),
768+
["hook", "manual"],
769+
);
770+
},
771+
);
772+
});
773+
714774
it("refuses a marked hook beside an unmarked edit and files one keyed block", () => {
715775
withFixture(
716776
{

‎scripts/fork-sync.ts‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -490,15 +490,31 @@ const reapplyHooks = (
490490
return null;
491491
}
492492
if (entries.length === 0) return null;
493+
const theirsLines = theirs.split("\n");
494+
const baseSplit = base.split("\n");
495+
const spanText = (lines: ReadonlyArray<string>, span: { startLine: number; endLine: number }) =>
496+
lines.slice(span.startLine - 1, span.endLine).join("\n");
493497
const marked = new Set<number>();
494498
for (const entry of entries)
495499
for (let line = entry.span.startLine; line <= entry.span.endLine; line += 1) marked.add(line);
500+
// An earlier commit's hook sits in the base too; strip it only when this
501+
// commit leaves it byte-identical, so an edited hook still refuses instead
502+
// of re-applying as `intact` with its old text.
503+
const theirsHooks = new Map(entries.map(({ key, span }) => [key, spanText(theirsLines, span)]));
504+
let baseEntries: ReturnType<typeof deriveForkHooksIn> = [];
505+
try {
506+
baseEntries = deriveForkHooksIn(path, base);
507+
} catch {}
508+
const baseMarked = new Set<number>();
509+
for (const { key, span } of baseEntries)
510+
if (theirsHooks.get(key) === spanText(baseSplit, span))
511+
for (let line = span.startLine; line <= span.endLine; line += 1) baseMarked.add(line);
496512
// Line arrays, not raw text: the fork blob and the base blob may differ in a
497513
// trailing newline while carrying the same lines.
498514
const shape = (lines: ReadonlyArray<string>): ReadonlyArray<string> =>
499515
lines.length > 0 && lines[lines.length - 1] === "" ? lines.slice(0, -1) : lines;
500-
const baseLines = shape(base.split("\n"));
501-
const forkLines = shape(theirs.split("\n").filter((_, index) => !marked.has(index + 1)));
516+
const baseLines = shape(baseSplit.filter((_, index) => !baseMarked.has(index + 1)));
517+
const forkLines = shape(theirsLines.filter((_, index) => !marked.has(index + 1)));
502518
const pureInsertion =
503519
baseLines.length === forkLines.length &&
504520
baseLines.every((line, index) => line === forkLines[index]);

0 commit comments

Comments
 (0)