Skip to content

Commit d3e402c

Browse files
fix(fork-sync): a sync session folds the stack before its hand-off, so the driver stays the only trunk writer (#1902)
## Problem `fork:fold publish` force-pushed `hyprws` through the ruleset's admin bypass. That made it a second trunk writer beside the land run, against #1886. The automated sync path never ran a fold, so fix-of-fix noise piled up on the trunk. ## Change - **Deleted:** `fork:fold publish` and its tests - **Fold:** a fork-sync step after a green run - **Where:** the kept worktree, `--base <tag>` - **Landing:** the next rerun's marker - **Gate:** candidate CI and the lease, unchanged - **Job budget:** fold only before 20 minutes gone - **Job disk:** allows `apply`'s rebase worktree The driver needs no change: an adopted, finished worktree lands any `HEAD` that contains the tag. A fold is tree-equal, so `lostHooks` and the link guard read it like the unfolded tip. ## Scope and approval The human asked for the fold to be part of the automated sync process. rsi-pr-agent needs no change: the job reads the fork-sync skill. ## Verification - fork-fold and fork-sync tests → 112/112 - `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 355f8d2 commit d3e402c

6 files changed

Lines changed: 48 additions & 242 deletions

File tree

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

Lines changed: 31 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
11
---
22
name: fork-fold
3-
description: Fold the RSI-Software/t3code-hyprws ahead commits to one PR-sized intent each: list the stack, write a plan, replay it, prove it, publish with the lease. Use on demand after a sync or landing leaves fix-of-fix noise on hyprws.
3+
description: Fold the RSI-Software/t3code-hyprws ahead commits to one PR-sized intent each: list the stack, write a plan, replay it, prove it, hand it off through the fork-sync marker. Use inside a fork-sync session after a green run, or when fork-sync points here.
44
---
55

66
# Fork fold
77

88
Keep each ahead commit one PR-sized intent, so a seam conflicts once per replay, not once per commit.
9-
The agent picks the folds; `scripts/fork-fold.ts` only lists, applies, and publishes.
9+
The agent picks the folds; `scripts/fork-fold.ts` only lists, applies, and proves.
10+
It never writes `hyprws`: the fold lands through the [fork-sync](../fork-sync/SKILL.md) marker, so the land run stays the only trunk writer.
1011

1112
## Scope
1213

@@ -17,18 +18,29 @@ The agent picks the folds; `scripts/fork-fold.ts` only lists, applies, and publi
1718

1819
## Run
1920

20-
From a checkout with `origin/hyprws` and `upstream/main` fetched:
21+
In the fork-sync kept worktree, after a green `vp run fork:sync <tag>`:
2122

2223
```bash
23-
vp run fork:fold list --head origin/hyprws
24-
vp run fork:fold apply plan.tsv --head origin/hyprws
25-
vp run fork:fold publish origin/hyprws <tip>
24+
vp run fork:fold list --base <tag> --head HEAD
25+
vp run fork:fold apply ../fold.tsv --base <tag> --head HEAD
26+
vp run fork:fold prove --base <tag> HEAD <tip>
27+
git checkout --detach <tip>
2628
```
2729

2830
1. **List:** domains, files, stack positions
29-
2. **Plan:** per the [fold rule](#fold-rule)
30-
3. **Apply:** prints `<tip>`; moves no ref. The fast path replays with merge-tree; from the first refused block the remaining plan finishes as one autosquashed rebase in a worktree under the git common dir, kept until the fold finishes; at each stop the agent resolves and reruns the same apply command
31-
4. **Publish:** refuses unless local hyprws sits at `<old>` and the worktree where hyprws is checked out is clean; proves, then pushes with the [expected-old lease][lease] and moves the [local trunks][trunk]; a failed proof pushes nothing
31+
2. **Plan:** `../fold.tsv`; [fold rule](#fold-rule)
32+
3. **Apply:** prints `<tip>`; moves no ref
33+
4. **Prove:** `<old>` is the unfolded `HEAD`
34+
5. **Move:** detach the kept worktree at `<tip>`
35+
6. **Rerun** the sync, then [hand off][handoff]
36+
37+
[handoff]: ../fork-sync/SKILL.md#hand-off
38+
39+
`apply` replays with merge-tree; from the first refused block the rest of the plan finishes as one autosquashed rebase in a worktree under the git common dir.
40+
At each stop, resolve there and rerun the same apply command.
41+
The fold is tree-equal, so the move changes nothing on disk.
42+
The land run gates the folded tip like any sync tip: candidate CI, then the [expected-old lease][lease].
43+
An apply stop or failed proof moves nothing: hand off the unfolded marker.
3244

3345
A conflict on a path the stack base lacks is fork-owned: `apply` resolves it to the old head, or drops it when the head lacks it.
3446
Only upstream-owned conflicts stop, since only they recur on a rebase.
@@ -37,7 +49,6 @@ A middle commit may then hold a fork-owned file's final form early; only the tip
3749
A fold is tree-equal but rewrites commit boundaries: the release delta revision changes, and a nightly may republish the same tree.
3850

3951
[lease]: ../../../docs/fork/operations/fork-sync.md#model
40-
[trunk]: ../../../docs/fork/operations/fork-sync.md#local-trunk
4152

4253
For JSON, run `node scripts/fork-fold.ts list --json`; `vp run` prints a banner first.
4354

@@ -54,7 +65,8 @@ One line per output commit: member shas, tab-separated, in stack order.
5465
- **Coverage:** every ahead commit, exactly once
5566
- **Order:** line order is the new stack order
5667
- **One member:** message kept verbatim
57-
- **Fold:** lead prose, `Squashes:` with each member's PR references, merged trailers
68+
- **Fold:** lead prose, merged trailers
69+
- **`Squashes:`** each member's PR references
5870

5971
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.
6072
Backfill a link an earlier fold lost this way.
@@ -68,7 +80,7 @@ The plan refuses a mixed-domain line: across domains the ledger would lose one.
6880

6981
## Prove
7082

71-
`prove` and `publish` take the published tip as `<old>`; a tree-equal fold needs no retest.
83+
A tree-equal fold needs no retest.
7284
`prove` also refuses:
7385

7486
| Commit | Refused when |
@@ -82,12 +94,13 @@ The plan refuses a mixed-domain line: across domains the ledger would lose one.
8294

8395
## Stops
8496

85-
| Output | Move |
86-
| ------------------------------------- | ------------------------------- |
87-
| `does not apply at its plan position` | Reorder or split that line |
88-
| `plan does not cover the stack` | Fix the listed shas |
89-
| `publish` refuses | Read the reason; nothing pushed |
97+
| Output | Move |
98+
| ------------------------------------- | ---------------------------------- |
99+
| `does not apply at its plan position` | Reorder or split that line |
100+
| `plan does not cover the stack` | Fix the listed shas |
101+
| `prove` fails | Fix the plan, or hand off unfolded |
90102

91103
## Cadence
92104

93-
On demand, after a sync or landing leaves fix-of-fix noise.
105+
Every sync session with budget left after a green run.
106+
A partial plan is fine: single-member lines keep their commits, so each sync tightens the stack further.

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

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,8 @@ Never edit a report; a rerun supersedes it.
6060
1. Run `vp run fork:sync [<tag>]`
6161
2. Stopped: [resolve](#resolve), then rerun
6262
3. `rebased`: commit [tip work](#tip-work), rerun
63-
4. [Hand off](#hand-off) the marker
63+
4. Green, with budget left: [fold](#fold), rerun
64+
5. [Hand off](#hand-off) the marker
6465

6566
Never `git rebase --continue`, `git cherry-pick --continue`, or script a resolver.
6667
The rerun continues with every automatic resolver, and the report keeps only stops a run saw.
@@ -101,7 +102,7 @@ A carried trunk commit conflicts like a seam: resolve, `git add`, rerun.
101102

102103
[hook]: ../../../docs/fork/internals/fork-delta.md#marking-a-hook
103104

104-
To fold it sooner, run [fork-fold](../fork-fold/SKILL.md) now.
105+
To fold it sooner, [fold](#fold) this session.
105106

106107
## Tip work
107108

@@ -130,6 +131,12 @@ Rerun once after tip work so the marker covers it.
130131

131132
[reshape]: ../../../docs/fork/operations/fork-sync.md#reshape
132133

134+
## Fold
135+
136+
After a green run, fold the stack in the kept worktree per [fork-fold](../fork-fold/SKILL.md).
137+
The fold is tree-equal, so the rerun that follows adopts it, and the marker hands it to the land run.
138+
Skip it when the budget is short; the next sync folds further.
139+
133140
## Hand off
134141

135142
Every rerun writes `refs/fork-sync/resolution`: finished once the rebase ends, partial at every block.
@@ -190,10 +197,12 @@ The summary ends with `Verify:` and those items: behaviour to exercise once the
190197

191198
**Disk.** The job's disk holds one install, about 8 GiB.
192199
The driver's kept worktree is the only other checkout; never clone, copy, add another, or run a second install.
200+
The one exception: `fork:fold apply`'s own rebase worktree, which holds no install.
193201

194202
**Budget.** The job has 45 minutes, and a killed job saves nothing.
195203

196204
- **Clock:** `date -u` at start and at every stop
205+
- **Fold:** start one only before 20 minutes gone
197206
- **30 minutes gone:** rerun, hand off the marker
198207
- **No progress:** same marker, so no new job
199208

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -164,7 +164,7 @@ Fork-only paths need no granularity curation.
164164
### Fold to stay tight
165165

166166
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.
167-
The [`fork-fold`](../../../.agents/skills/fork-fold/SKILL.md) skill runs it.
167+
The [`fork-fold`](../../../.agents/skills/fork-fold/SKILL.md) skill runs it inside a sync session, so the fold lands through the sync marker.
168168
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`.
169169
Fold commits that share one owning intent or cancel each other's upstream hunks, never only because they share a domain.
170170
A cancelling pair across domains cannot share a plan line: drop both hunks by hand at the fold, and `prove` checks the tree.

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ The land run pushes the trunk directly, so no pull request runs `hyprws CI` befo
5757

5858
A candidate replays every fork commit, so stale-delete has nothing new to judge.
5959

60-
`fork-fold` publishes only a tree-equal fold, so it inherits the same guarantee.
60+
A `fork-fold` fold lands through the same marker and gate, so the land run stays the only trunk writer.
6161

6262
## Local trunk
6363

‎scripts/fork-fold.test.ts‎

Lines changed: 0 additions & 136 deletions
Original file line numberDiff line numberDiff line change
@@ -1027,139 +1027,3 @@ it("proves tree equality, the delta check, and the replay scan, failing on any",
10271027
assert.strictEqual(run(["prove", head, parent, "--base", base], root, step), 1);
10281028
assert.strictEqual(run(["prove", head], root, step), 2);
10291029
}));
1030-
1031-
// Publish tests use a local bare origin, so they never push to a real remote.
1032-
1033-
const remoteHyprws = (root: string): string =>
1034-
git(root, ["rev-parse", "refs/remotes/origin/hyprws"]);
1035-
1036-
/** The stack fixture plus local `hyprws` at the tip, checked out in root, published to a bare origin. */
1037-
const createTrunk = () => {
1038-
const stack = createStack();
1039-
const origin = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "fork-fold-origin-"));
1040-
git(origin, ["init", "--bare", "-q"]);
1041-
git(stack.root, ["remote", "add", "origin", origin]);
1042-
git(stack.root, ["branch", "hyprws", stack.head]);
1043-
git(stack.root, ["checkout", "-q", "hyprws"]);
1044-
git(stack.root, ["push", "-q", "origin", "hyprws"]);
1045-
return { ...stack, origin };
1046-
};
1047-
1048-
const withTrunk = (body: (trunk: ReturnType<typeof createTrunk>) => void) => {
1049-
const trunk = createTrunk();
1050-
try {
1051-
body(trunk);
1052-
} finally {
1053-
NodeFS.rmSync(trunk.root, { recursive: true, force: true });
1054-
NodeFS.rmSync(trunk.origin, { recursive: true, force: true });
1055-
}
1056-
};
1057-
1058-
/** Applies the two per-domain folds; the plan file must not dirty the tree. */
1059-
const foldTo = (root: string, base: string, members: [string, string, string, string]): string => {
1060-
NodeFS.writeFileSync(
1061-
NodePath.join(root, "fold.tsv"),
1062-
`${members[0]}\t${members[1]}\n${members[2]}\t${members[3]}\n`,
1063-
);
1064-
const applied = cli(root, ["apply", "fold.tsv", "--base", base]);
1065-
NodeFS.unlinkSync(NodePath.join(root, "fold.tsv"));
1066-
assert.strictEqual(applied.status, 0, applied.stderr);
1067-
return applied.stdout.trim();
1068-
};
1069-
1070-
/** Real git against the fixture, stubbed green vp checks; every call recorded. */
1071-
const publishStep = (root: string) => {
1072-
const calls: Array<string> = [];
1073-
const step: ProveStep = (command, args) => {
1074-
calls.push([command, ...args].join(" "));
1075-
return command === "git"
1076-
? runCommand(command, args, { cwd: root })
1077-
: { status: 0, stdout: "", stderr: "" };
1078-
};
1079-
return { calls, step };
1080-
};
1081-
1082-
it("publish proves, pushes the expected-old lease, and moves the local trunk", () =>
1083-
withTrunk(({ root, base, metaOne, metaTwo, zmux, zmuxEdit, head }) => {
1084-
const next = foldTo(root, base, [metaOne, metaTwo, zmux, zmuxEdit]);
1085-
const target = git(root, ["merge-base", base, next]);
1086-
const { calls, step } = publishStep(root);
1087-
assert.strictEqual(run(["publish", head, next, "--base", base], root, step), 0);
1088-
assert.strictEqual(remoteHyprws(root), next);
1089-
assert.strictEqual(git(root, ["rev-parse", "refs/heads/hyprws"]), next);
1090-
// The lease is the <old> resolved at the start; no fetch re-resolves it.
1091-
assert.deepStrictEqual(calls, [
1092-
`git diff --quiet ${head} ${next}`,
1093-
`vp run fork:delta --check --base ${base} --head ${next}`,
1094-
`vp run fork:scan --head ${next} --target ${target} --since ${target} --replay-of ${head} --no-typecheck`,
1095-
`git push origin ${next}:hyprws --force-with-lease=hyprws:${head}`,
1096-
]);
1097-
}));
1098-
1099-
it("a failed proof pushes nothing", () =>
1100-
withTrunk(({ root, base, head }) => {
1101-
const parent = git(root, ["rev-parse", `${head}^`]);
1102-
const { calls, step } = publishStep(root);
1103-
assert.strictEqual(run(["publish", head, parent, "--base", base], root, step), 1);
1104-
assert.strictEqual(remoteHyprws(root), head);
1105-
assert.strictEqual(git(root, ["rev-parse", "refs/heads/hyprws"]), head);
1106-
assert.ok(calls.every((call) => !call.startsWith("git push")));
1107-
}));
1108-
1109-
it("a moved remote refuses the lease and keeps the local trunk", () =>
1110-
withTrunk(({ root, base, metaOne, metaTwo, zmux, zmuxEdit, head }) => {
1111-
const next = foldTo(root, base, [metaOne, metaTwo, zmux, zmuxEdit]);
1112-
git(root, ["push", "-q", "origin", "--force", `${base}:hyprws`]);
1113-
const { calls, step } = publishStep(root);
1114-
assert.strictEqual(run(["publish", head, next, "--base", base], root, step), 1);
1115-
assert.strictEqual(remoteHyprws(root), base);
1116-
assert.strictEqual(git(root, ["rev-parse", "refs/heads/hyprws"]), head);
1117-
assert.ok(calls.some((call) => call.startsWith("git push")));
1118-
}));
1119-
1120-
it("checks the hyprws worktree, not the invoking checkout, and skips when checked out nowhere", () =>
1121-
withTrunk(({ root, base, metaOne, metaTwo, zmux, zmuxEdit, head }) => {
1122-
const next = foldTo(root, base, [metaOne, metaTwo, zmux, zmuxEdit]);
1123-
git(root, ["checkout", "-q", "fixture"]); // publish runs from another checkout
1124-
const trunk = NodePath.join(
1125-
NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "fork-fold-trunk-")),
1126-
"wt",
1127-
);
1128-
git(root, ["worktree", "add", "-q", trunk, "hyprws"]);
1129-
try {
1130-
// A dirty trunk worktree refuses even though the invoking checkout is clean.
1131-
const dirtyTrunk = publishStep(root);
1132-
write(trunk, "dirty.txt", "uncommitted\n");
1133-
assert.strictEqual(run(["publish", head, next, "--base", base], root, dirtyTrunk.step), 1);
1134-
assert.deepStrictEqual(dirtyTrunk.calls, []);
1135-
assert.strictEqual(remoteHyprws(root), head);
1136-
NodeFS.unlinkSync(NodePath.join(trunk, "dirty.txt"));
1137-
git(root, ["worktree", "remove", trunk]);
1138-
1139-
// Checked out nowhere: no worktree tree to check, so a dirty invoking
1140-
// checkout does not refuse.
1141-
const nowhere = publishStep(root);
1142-
write(root, "dirty.txt", "uncommitted\n");
1143-
assert.strictEqual(run(["publish", head, next, "--base", base], root, nowhere.step), 0);
1144-
assert.strictEqual(remoteHyprws(root), next);
1145-
assert.strictEqual(git(root, ["rev-parse", "refs/heads/hyprws"]), next);
1146-
} finally {
1147-
NodeFS.rmSync(NodePath.dirname(trunk), { recursive: true, force: true });
1148-
}
1149-
}));
1150-
1151-
it("a dirty or moved local refuses before prove and push", () =>
1152-
withTrunk(({ root, base, head }) => {
1153-
const dirty = publishStep(root);
1154-
write(root, "dirty.txt", "uncommitted\n");
1155-
assert.strictEqual(run(["publish", head, head, "--base", base], root, dirty.step), 1);
1156-
assert.deepStrictEqual(dirty.calls, []);
1157-
assert.strictEqual(remoteHyprws(root), head);
1158-
NodeFS.unlinkSync(NodePath.join(root, "dirty.txt"));
1159-
1160-
const moved = publishStep(root);
1161-
git(root, ["update-ref", "refs/heads/hyprws", base]);
1162-
assert.strictEqual(run(["publish", head, head, "--base", base], root, moved.step), 1);
1163-
assert.deepStrictEqual(moved.calls, []);
1164-
assert.strictEqual(git(root, ["rev-parse", "refs/heads/hyprws"]), base);
1165-
}));

0 commit comments

Comments
 (0)