Skip to content

Commit 633b107

Browse files
donjor-agent[bot]donjor
authored andcommitted
refactor(fork): sync adaptations land as owner fixups, not Fork-Repair (#1645)
## Problem A sync that needed adaptations landed one omnibus `Fork-Repair` commit, then needed a manual `/fork-fold` repair split. That split cost owner-selection friction and swallowed the retirement explanations. ## Change ### Sync adaptations | Adaptation | Lands as | | --- | --- | | One owner | `fixup! <owner subject>`, owner's trailers | | No single owner | standalone `upstream-fixes` commit | | Retirement | its own commit | The next sync's autosquash absorbs tip fixups; `fork:ci`'s `fork-fixup-fold` proves each one folds. ### Removed | Area | Removed | | --- | --- | | Trailer | `Fork-Repair`, its parsing and inventory skip | | Fold | repair split, `--old`, `citeOld`, forced fallback | | Skill | post-sync `/fork-fold` step | ### Smaller fixes | Area | Fix | | --- | --- | | Fold | plain `fixup!` renders as a member | | Battery | red `fork:ci` skips later rows (⏭️) | | Push refusal | worktree kept, `decision.tip` set | | Hook guard | remedy names the tip-fixup route | | Skill | name a tag only when the user does | ## Scope and approval Agreed with the maintainer in-session: accept tip fixups, no separate adaptation record. Closes #1633 - [x] Message: a replay refusal names the tip-repair route - [x] Test: fork-hook-guard.test.ts asserts it | Refs | Why open | | --- | --- | | #1632 | live condition needs the next retiring sync | | #1635 | documented reset stays; no driver move | ## Verification | Command | Result | | --- | --- | | `vp test run` on 6 touched script test files | exit 0, 169 tests | | `vp test run scripts/lib/fork-hook-guard.test.ts` | exit 0, 11 tests | | `vp exec tsc --noEmit` in `scripts` | exit 0 | | `vp run fork:ci` | exit 0 | <details> <summary>New regression tests</summary> | Test | Proves | | --- | --- | | Tip fixup stack | each folds at its owner, every member proven | | Mixed fixups | plain and landed under one owner | | Refused push | tip kept; a rerun publishes it | | Red battery | only `fork:ci` runs, rest skipped | </details> Claude Opus 5.5, Claude Code in T3 Code. ## Fork trailers Squashes: - 5216fdf refactor(fork): sync adaptations land as owner fixups, not Fork-Repair (#1645) (#1645) - ee7866f fixup! refactor(fork): sync adaptations land as owner fixups, not Fork-Repair (#1645) (#1645) Fork-Domain: fork-meta Fork-Tier: qol Co-authored-by: donjor <[email protected]>
1 parent 71e0148 commit 633b107

16 files changed

Lines changed: 330 additions & 642 deletions

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

Lines changed: 20 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,10 @@ The agent picks the folds; `scripts/fork-fold.ts` only lists, applies, and publi
1010

1111
## Scope
1212

13-
| Noise | Owner |
14-
| ---------------------------- | -------------------------------------- |
15-
| A `fixup! <subject>` landing | `fork:sync`, folded at the next rebase |
16-
| Ordinary commits, now landed | This skill |
13+
| Noise | Owner |
14+
| ---------------------------------------- | -------------------------------------- |
15+
| A `fixup! <subject>` landing or sync tip | `fork:sync`, folded at the next rebase |
16+
| Ordinary commits, now landed | This skill |
1717

1818
## Run
1919

@@ -62,7 +62,6 @@ Backfill a link an earlier fold lost this way.
6262
## Fold rule
6363

6464
One PR-sized intent per output commit: a feature absorbs its fixes and resolutions.
65-
A `Fork-Repair` commit never survives the fold: [split it first](#repair-split).
6665

6766
Fold when both hold:
6867

@@ -71,30 +70,27 @@ Fold when both hold:
7170

7271
The plan refuses a mixed-domain line: across domains the ledger would lose one.
7372

74-
## Repair split
73+
## Prove
7574

76-
A `Fork-Repair` commit dissolves before the run, so no repair lands in the fold.
77-
Split each one on a detached copy of the head (`git worktree add --detach <dir> <head>`):
75+
`prove` and `publish` take the published tip as `<old>`; a tree-equal fold needs no retest.
76+
`prove` also refuses:
7877

79-
1. `git rebase -i <first repair>^` and mark every `Fork-Repair` commit `edit`. Commits before the first repair keep their shas — the rebase never replays them — and owners always precede the repairs they absorb, so `Squashes:` keeps resolving against the old tip.
80-
2. At each stop: `git reset HEAD^`; stage each owner's hunks and commit them as `fixup! <owner subject>` with the owner's trailers and the repair's line under `Squashes:` — `list` prints that line under every repair.
81-
3. One inseparable remainder: a single `upstream-fixes` commit naming the upstream change it adapts to, without `Fork-Repair`.
82-
4. `git rebase --continue`. The split head is tree-equal to the old tip.
83-
84-
Run the fold with `--head <split head> --old <old>`: 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.
85-
A replayed member cites its `<old>` counterpart by subject, since its split sha sits on no trunk.
86-
`prove` and `publish` take the pre-split tip as `<old>`; a tree-equal fold needs no retest.
87-
`prove` also refuses a dropped PR link, a `Squashes:` sha `<old>` never names, 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 by several, unless it carries `Fork-Repair` or every owner cites it under `Squashes:`.
78+
| Commit | Refused when |
79+
| ------ | ----------------------------------------- |
80+
| Any | it drops a PR link |
81+
| New | it cites a sha `<old>` never names |
82+
| New | it names no `<old>` member |
83+
| New | it touches a path no member touched |
84+
| Old | no new commit owns it |
85+
| Old | it splits and some owner does not cite it |
8886

8987
## Stops
9088

91-
| Output | Move |
92-
| ---------------------------------------- | ---------------------------------------- |
93-
| `does not apply at its plan position` | Reorder or split that line |
94-
| `plan does not cover the stack` | Fix the listed shas |
95-
| `a fixup! member carries no repair line` | Copy `list`'s fixup line into that piece |
96-
| `--head is a split head` | Pass the pre-split tip as `--old` |
97-
| `publish` refuses | Read the reason; nothing pushed |
89+
| Output | Move |
90+
| ------------------------------------- | ------------------------------- |
91+
| `does not apply at its plan position` | Reorder or split that line |
92+
| `plan does not cover the stack` | Fix the listed shas |
93+
| `publish` refuses | Read the reason; nothing pushed |
9894

9995
## Cadence
10096

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

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ vp run fork:sync <tag> --dry-run
1919

2020
`--dry-run` rebases and checks, then stops: no push, no issue, no publication.
2121
Any other flag is a defect.
22+
Name a tag only when the user names one; otherwise run with no tag.
2223

2324
A green dry run keeps its tip in the sync worktree for the real run:
2425

@@ -47,10 +48,6 @@ Post-push recovery reads this file, never a comment.
4748

4849
Never edit a report; a rerun supersedes it.
4950

50-
## After
51-
52-
A repairing sync — the rebased trunk carries `Fork-Repair` commits — ends with [`/fork-fold`](../fork-fold/SKILL.md) once trunk is green: its [repair split](../fork-fold/SKILL.md#repair-split) dissolves each repair into its owners. A sync with no repairs needs no fold.
53-
5451
## Stops
5552

5653
| Report | Stop |
@@ -76,11 +73,12 @@ Resolve each seam by verdict, then follow Unblock.
7673
| ------- | ----------------------------------------------------------- |
7774
| Keep | Only upstream moved; upstream stands, hook returns verbatim |
7875
| Reshape | Fork side moved too; resolve minimally, adapt at the tip |
79-
| Retire | Upstream owns it now; traced verdict, drop at rebase |
76+
| Retire | Upstream owns it now; its own commit, never inside a fixup |
8077

8178
### Check battery
8279

8380
The battery is red; the worktree keeps the rebased tip.
81+
A red `fork:ci` skips every later row.
8482

8583
- **Red job**: `checks[].job` names it
8684
- **Trunk-green fix**: by pull request
@@ -90,8 +88,11 @@ The battery is red; the worktree keeps the rebased tip.
9088
### Lease refusal
9189

9290
The expected-old lease lost; someone landed first.
91+
The worktree keeps the green tip; `decision.tip` names it.
9392

9493
- **Inspect**: the trunk
94+
- **Carry**: tip fixups from `decision.tip`
95+
- **Moved lease**: the rerun rebases again
9596
- **Rerun**: never `--force`
9697

9798
## Unblock
@@ -103,13 +104,21 @@ In the rebase, resolve minimally: upstream's text stands, and a marked fork hook
103104
Upstream deleted and the fork edit is net-zero: the deletion stands.
104105
A [regenerable file](../../../docs/fork/operations/fork-sync.md#regenerable-files) regenerates; when one is pending, skip `git rebase --continue` and rerun.
105106
Never adapt inside a replayed commit: the hook guard refuses it.
106-
Adaptation lands once, in one `Fork-Repair` commit at the tip; [`/fork-fold`](../fork-fold/SKILL.md) dissolves it afterward.
107+
Adaptation lands at the tip, one commit per owner:
108+
109+
| Change | Commit |
110+
| ---------------- | ------------------------------------------------------ |
111+
| Owner adaptation | `fixup! <owner subject>` with the owner's trailers |
112+
| No single owner | one `upstream-fixes` commit naming the upstream change |
113+
| Retirement | its own commit; a fixup body is discarded at the fold |
114+
115+
The next sync folds each fixup into its owner; no `/fork-fold` follows a sync.
107116

108117
1. Read `decision`: worktree, paths, resume commands.
109118
2. Open that worktree.
110119
3. Resolve each path by the rule above.
111120
4. `git add` them; `git rebase --continue`.
112-
5. Commit any adaptation there as one `Fork-Repair` commit at the tip.
121+
5. Commit any adaptation at the tip, per the table.
113122
6. Rerun `vp run fork:sync <tag>`.
114123

115124
The worktree ran the `t3.json` setup step, so it builds and tests.

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

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -57,15 +57,13 @@ A retirement is recorded by the retire commit itself, not a ledger.
5757

5858
## Trailers
5959

60-
| Trailer | Values | Required on |
61-
| ------------------- | ----------------------------- | ---------------------- |
62-
| `Fork-Domain` | A domain from the index below | Every fork commit |
63-
| `Fork-Tier` | `core`, `qol`, `bugfix` | Every fork commit |
64-
| `Fork-Upstreamable` | `yes`, `no` | Every `bugfix` |
65-
| `Fork-Repair` | The upstream tag of the walk | Every sync walk repair |
60+
| Trailer | Values | Required on |
61+
| ------------------- | ----------------------------- | ----------------- |
62+
| `Fork-Domain` | A domain from the index below | Every fork commit |
63+
| `Fork-Tier` | `core`, `qol`, `bugfix` | Every fork commit |
64+
| `Fork-Upstreamable` | `yes`, `no` | Every `bugfix` |
6665

6766
`Fork-Upstreamable: yes` is a tracking tag, never authorization to post upstream; `AGENTS.md` owns that rule.
68-
`Fork-Repair` marks a repair the next fold absorbs.
6967
`vp run fork:delta --check` enforces the table on every push, and a rebase preserves trailers.
7068

7169
**Squash-body mode.** The advisory `hyprws Body` workflow runs `--check --squash-body <file>`; it is not a required check.

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

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@ A sync pushes the trunk directly, so no pull request runs `hyprws CI` before the
4141
| Test jobs | every `test*` job in `hyprws-ci.yml`, one row per matrix cell |
4242
| Derived | read from the replayed workflow; an unreadable step stops the run |
4343
| No skip | no flag drops a row |
44+
| Fail fast | a red `fork:ci` marks every later row `skipped` |
4445
| Push | only when every row is green; a red row leaves `hyprws` unmoved |
4546
| Report | each row names its CI job; the run's error lists every red one |
4647
| Env | umask `022`; no `T3_*` or `T3CODE_*` variable reaches a check |
@@ -125,12 +126,20 @@ Rerere replays content resolutions but records nothing for a delete/modify: the
125126

126127
**Reshape.** Resolve minimally in the rebase: upstream's text plus marked hooks verbatim.
127128
Adaptation never lands inside a replayed commit; the hook guard (`scripts/lib/fork-hook-guard.ts`, run by `fork:ci`) refuses it.
128-
Commit it once, as one `Fork-Repair` commit at the tip of the kept sync worktree; a rerun on the same tag and lease adopts it.
129-
After the sync, the [`fork-fold`](../../../.agents/skills/fork-fold/SKILL.md) repair split dissolves it into its owners.
129+
Commit it at the tip of the kept sync worktree; a rerun on the same tag and lease adopts it.
130+
131+
| Change | Commit |
132+
| ---------------- | -------------------------------------------------------- |
133+
| Owner adaptation | `fixup! <owner subject>` with the owner's trailers |
134+
| No single owner | one standalone `upstream-fixes` commit naming the change |
135+
| Retirement | its own commit, never inside a fixup body |
136+
137+
The next sync's rebase folds each fixup into its owner, and `fork:ci` proves it folds there.
138+
Autosquash discards a fixup's body, so a reason worth keeping goes in its own commit.
130139

131140
**Kept sync worktree.** Created through the `t3.json` setup step, so a stop has dependencies installed.
132141
It carries every stop's rows between runs, so the report keeps them.
133-
A green dry run keeps it, so its tip and repairs reach the real run.
142+
A green dry run or a refused push keeps it, so its tip and tip fixups reach the next run.
134143
Rerun after each stop: the report records only the stops a run saw.
135144

136145
## Failure lifecycle
@@ -241,7 +250,7 @@ T3 Connect stays dark unless all four repository variables exist:
241250
| Failure | Response |
242251
| --------------------------- | ---------------------------------------------------------------- |
243252
| **Mirror fails** | Recreate the token. Someone wrote `main`; never force |
244-
| **Trunk lease rejected** | Inspect and rerun; never swap in `--force` |
253+
| **Trunk lease rejected** | `decision.tip` keeps the tip; inspect, rerun; never `--force` |
245254
| **A blocked issue remains** | Unblock by hand. Retirement needs a traced decision |
246255
| **A failure issue remains** | Inspect the report, fix, and rerun; the next clean run closes it |
247256
| **Check battery red** | Fix by pull request; never weaken a check |

‎scripts/fork-delta.test.ts‎

Lines changed: 0 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -557,49 +557,3 @@ it("prints the inventory object with --json and refuses the ledger-only --base",
557557
NodeFS.rmSync(root, { recursive: true, force: true });
558558
}
559559
});
560-
561-
it("excludes walk repair commits from the inventory sums", () => {
562-
const { root, base, upstream } = createStackFixture();
563-
try {
564-
NodeFS.writeFileSync(NodePath.join(root, "repair.ts"), "repair line one\nrepair line two\n");
565-
const withRepair = commitAll(
566-
root,
567-
"fix: repair the walk after a conflicted replay",
568-
"Fork-Domain: fork-meta\nFork-Tier: qol\nFork-Repair: v0.0.39-fix\n",
569-
);
570-
const result = runForkDelta(root, checkArgs(base, withRepair, upstream));
571-
assert.strictEqual(result.status, 0, result.stderr);
572-
assert.include(result.stdout, "ok: 3 fork commits tagged");
573-
574-
const json = runForkDelta(root, [
575-
"--inventory",
576-
"--json",
577-
"--head",
578-
withRepair,
579-
"--upstream",
580-
upstream,
581-
]);
582-
assert.strictEqual(json.status, 0, json.stderr);
583-
const inventory = JSON.parse(json.stdout) as {
584-
domains: ReadonlyArray<{
585-
domain: string;
586-
commits: number;
587-
added: number;
588-
deleted: number;
589-
files: number;
590-
overlaps: number;
591-
}>;
592-
commits: ReadonlyArray<{ short: string }>;
593-
distinctFiles: number;
594-
};
595-
// The repair commit's lines stay out of the sums and the distinct count
596-
// while its per-commit row remains visible.
597-
assert.deepStrictEqual(inventory.domains, [
598-
{ domain: "fork-meta", commits: 2, added: 3, deleted: 0, files: 3, overlaps: 1 },
599-
]);
600-
assert.strictEqual(inventory.commits.length, 3);
601-
assert.strictEqual(inventory.distinctFiles, 3);
602-
} finally {
603-
NodeFS.rmSync(root, { recursive: true, force: true });
604-
}
605-
});

‎scripts/fork-delta.ts‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,6 @@ export const ForkCommit = Schema.Struct({
9292
domain: OptionalTrailer,
9393
tier: OptionalTrailer,
9494
upstreamable: OptionalTrailer,
95-
repair: OptionalTrailer,
9695
});
9796
export type ForkCommit = typeof ForkCommit.Type;
9897

@@ -338,10 +337,6 @@ export const buildInventory = (input: {
338337
files: stats.files.length,
339338
overlaps: overlapPaths(stats.files, input.forkChanged, input.upstreamChanged).length,
340339
});
341-
// A walk repair commit is the walk's own bookkeeping, not a domain's change:
342-
// it stays visible in the per-commit table but its lines never count toward
343-
// the domain sums.
344-
if (commit.repair !== undefined) continue;
345340
for (const path of stats.files) distinctFiles.add(path);
346341
if (commit.domain === undefined) continue;
347342
const bucket = buckets.get(commit.domain) ?? {

0 commit comments

Comments
 (0)