Skip to content

Commit 3c2bfa3

Browse files
donjor-agent[bot]donjor
authored andcommitted
fix(fork-sync): one standing blocked and failed issue, rewritten per run
## What Changed - `fork-sync.ts`: each sync issue kind (blocked, failed) keeps one standing open issue - A blocked or failed run rewrites that issue's title and body in place; it files only when none is open - Older open issues of the same kind close with `Superseded by #N.` - The body gains a short tail: open-since date, target count, last five runs - A rerun on the same target and detail writes nothing - Sync doc, glossary, and `fork-sync` skill updated; one new test ```md Open since 2026-09-27 across 4 targets; each failed run rewrites this issue and a clean run closes it. ## Recent runs - 2026-09-28 · `v0.0.43-nightly.20260928.2402` · check - 2026-09-28 · `v0.0.43-nightly.20260928.2375` · check ``` ## Why Failure issues were keyed by step and tag, and block issues by upstream sha. Every new nightly filed a fresh issue, so four `failed at check` issues sat open at once (#1332, #1354, #1366, #1384). ```text vp run fork:ci → exit 0 vp run fork:delta --check → exit 0 vp test run scripts/fork-sync.test.ts → 44 passed ``` ## Checklist - [x] This PR is small and focused - [x] I explained what changed and why ## Fork trailers Fork-Domain: fork-meta Fork-Tier: core Fork-Upstreamable: no Co-authored-by: donjor <[email protected]>
1 parent 687446c commit 3c2bfa3

5 files changed

Lines changed: 174 additions & 75 deletions

File tree

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

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -104,11 +104,9 @@ The rerun adopts the kept worktree and checks its HEAD.
104104
A resolved rebase still in progress continues; an unresolved one blocks again.
105105
A new tag or a moved lease recreates the worktree.
106106

107-
A blocked run files one block issue (label `ci`) keyed by the blocking upstream sha.
108-
A rerun on the same sha updates that issue; a clean run closes it.
109-
110-
A failed run files one failure issue the same way, keyed by the failing step and the target tag (the trunk sha before a tag resolves).
111-
A rerun with the same failure updates it; a clean run closes it.
107+
A blocked run rewrites the one open block issue (label `ci`), filing it only when none is open.
108+
A failed run does the same with the one open failure issue.
109+
Each body ends with its open-since date, target count, and last five runs; a clean run closes both.
112110

113111
### Finished tip from elsewhere
114112

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

Lines changed: 17 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ There is no state machine, no gates, no lanes, no modes: one run, one exit code,
1818
| rebase | detached worktree, `git rebase --rerere-autoupdate <tag>` | a conflict rerere and hook re-apply cannot resolve |
1919
| check | `fork:delta --check`, `fork:ci`, `vpr typecheck`, in the worktree | any red |
2020
| push | `--force-with-lease=hyprws:<fetched sha>` | lease refused |
21-
| blocked | one block issue per blocking sha, through `gh` | `gh` refuses the write |
21+
| blocked | one standing block issue, rewritten per run, through `gh` | `gh` refuses the write |
2222
| report | `.t3/fork-sync/<tag>.json`, typed, written before any post | |
2323

2424
A tag the fork already sits on reports `already applied` — after closing the block issues a previous run left open.
@@ -72,17 +72,16 @@ There is no "upstream superseded this" rule: retirement is a traced verdict writ
7272

7373
## Block lifecycle
7474

75-
A blocked run writes its report first, then files one issue per blocking upstream sha through plain `gh`.
76-
The title phrase and the sha key the issue; the body carries the conflict table (path, fork commit, upstream commit) and the resume commands.
75+
A blocked run writes its report first, then rewrites the one open block issue through plain `gh`, filing it only when none is open.
76+
The body carries the conflict table (path, fork commit, upstream commit), the resume commands, and a tail: open-since date, target count, last five runs.
7777

78-
| Rule | Detail |
79-
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
80-
| Identity | Title phrase `hyprws sync blocked`, label `ci`, and the exact `blocking-sha` body marker |
81-
| Filed once | Per blocking SHA, including after a manual close |
82-
| Rerun | Same sha updates the issue; a clean run closes it |
83-
| Close | A clean run (applied or already-applied) closes each open block issue with `gh issue close --reason completed --comment "Resolved by hyprws <sha>"`; a refusal lands in the report and fails the run |
84-
| Route | Plain `gh` only |
85-
| Refusal | A refusing `gh` prints the body; the run exits non-zero |
78+
| Rule | Detail |
79+
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
80+
| Identity | Title phrase `hyprws sync blocked` and label `ci`; the newest open issue is the standing one |
81+
| Standing | Each blocked run rewrites its title and body; older open block issues close as superseded |
82+
| Close | A clean run (applied or already-applied) closes each open block issue with `gh issue close --reason completed --comment "Resolved by hyprws <sha>"`; a refusal lands in the report and fails the run |
83+
| Route | Plain `gh` only |
84+
| Refusal | A refusing `gh` prints the body; the run exits non-zero |
8685

8786
Never post a block to `pingdotgg/t3code`.
8887

@@ -99,15 +98,13 @@ Rerere replays content resolutions but records nothing for a delete/modify: the
9998

10099
## Failure lifecycle
101100

102-
A run that fails on a non-blocked step — target, fetch, rebase, check, push, or a crash — files one issue the same way a block does, through the same `gh` route.
101+
A run that fails on a non-blocked step (target, fetch, rebase, check, push, or a crash) rewrites one standing failure issue the same way a block does, through the same `gh` route.
103102

104-
| Rule | Detail |
105-
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
106-
| Identity | Title phrase `hyprws sync failed`, label `ci`, and the `sync-failure:<step>:<key>` body marker |
107-
| Key | The failing step plus the target tag, or the trunk sha before a tag resolved |
108-
| Filed once | Per key, including after a manual close |
109-
| Rerun | The same failure updates the issue; a dry run reports and never files |
110-
| Close | A clean run (applied or already-applied) closes it in the same `gh issue close --comment` pass that closes block issues; a refusal lands in the report and fails the run |
103+
| Rule | Detail |
104+
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
105+
| Identity | Title phrase `hyprws sync failed` and label `ci`; the newest open issue is the standing one |
106+
| Standing | Each failed run rewrites its title and body; a dry run reports and never files |
107+
| Close | A clean run (applied or already-applied) closes it in the same `gh issue close --comment` pass that closes block issues; a refusal lands in the report and fails the run |
111108

112109
## Regenerable files
113110

@@ -140,7 +137,7 @@ The workflow uses its own `GITHUB_TOKEN` with `issues: write`; never widen the t
140137
### Labels
141138

142139
Block issues carry the governed `ci` label; nothing creates a sync-specific label.
143-
They are found by the title phrase `hyprws sync blocked` and the `blocking-sha` body marker.
140+
They are found by the title phrase `hyprws sync blocked`.
144141

145142
### Which events run the fork matrix
146143

‎docs/internals/glossary.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -20,11 +20,11 @@ Terms whose meaning matters across T3 Code. Architecture and lifecycle constrain
2020

2121
Fork-only terms. The [fork sync runbook](../fork/operations/fork-sync.md) owns the procedure behind them.
2222

23-
| Term | Meaning |
24-
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
25-
| `release/vX.Y.Z-hyprws` | A create-only branch snapshotting the fork stack rebased onto stable upstream `vX.Y.Z`. Stable `vX.Y.Z-hyprws.<n>` tags are cut from it, and later trunk work never moves it. |
26-
| `hyprws sync blocked` | The fork's block issue: one per blocking upstream sha, labelled `ci` and found by its title phrase and `blocking-sha` body marker. A maintainer resolves it through the `fork-sync` skill. |
27-
| Nightly channel | The prerelease update channel for `vX.Y.Z-hyprws-nightly.YYYYMMDD.<run>` tags, kept separate from stable fork releases in the desktop updater. |
23+
| Term | Meaning |
24+
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
25+
| `release/vX.Y.Z-hyprws` | A create-only branch snapshotting the fork stack rebased onto stable upstream `vX.Y.Z`. Stable `vX.Y.Z-hyprws.<n>` tags are cut from it, and later trunk work never moves it. |
26+
| `hyprws sync blocked` | The fork's standing block issue: one open at a time, labelled `ci`, found by its title phrase, and rewritten by each blocked run. A maintainer resolves it through the `fork-sync` skill. |
27+
| Nightly channel | The prerelease update channel for `vX.Y.Z-hyprws-nightly.YYYYMMDD.<run>` tags, kept separate from stable fork releases in the desktop updater. |
2828

2929
## Orchestration
3030

‎scripts/fork-sync.test.ts‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -830,6 +830,48 @@ it("edits the open issue in place when the rendered body drifts, never comments"
830830
);
831831
});
832832

833+
it("rewrites the one standing issue for a new target and supersedes older open ones", () => {
834+
const first = failedReport("check", "v1.0.0");
835+
const next = { ...failedReport("check", "v1.1.0"), startedAt: "2026-09-22T10:00:00.000Z" };
836+
const edits: Array<{ readonly args: ReadonlyArray<string>; readonly body: string }> = [];
837+
const recording = exec({
838+
gh: (args) => {
839+
if (args[0] === "issue" && args[1] === "edit") {
840+
edits.push({
841+
args,
842+
body: NodeFS.readFileSync(args[args.indexOf("--body-file") + 1] ?? "", "utf8"),
843+
});
844+
return ok();
845+
}
846+
if (args[0] === "issue" && args[1] === "list")
847+
return ok(
848+
JSON.stringify([
849+
{ number: 7, title: "legacy", body: "older failure" },
850+
{ number: 12, title: first.failure!.title, body: failureIssueBody(first) },
851+
]),
852+
);
853+
return ok();
854+
},
855+
});
856+
const published = publishFailure(recording.runner, "/tmp", next);
857+
assert.strictEqual(published.failure?.issue, 12);
858+
assert.strictEqual(edits.length, 1);
859+
const args = edits[0]!.args;
860+
assert.strictEqual(args[2], "12");
861+
assert.strictEqual(args[args.indexOf("--title") + 1], "hyprws sync failed at check (v1.1.0)");
862+
const body = edits[0]!.body;
863+
assert.include(body, "Open since 2026-09-21 across 2 targets;");
864+
assert.include(body, "- 2026-09-22 · `v1.1.0` · check\n- 2026-09-21 · `v1.0.0` · check");
865+
// the older open issue of the same kind closes as superseded; nothing new files
866+
const close = recording.calls.find(({ args }) => args[0] === "issue" && args[1] === "close");
867+
assert.strictEqual(close?.args[2], "7");
868+
assert.include(close?.args ?? [], "Superseded by #12.");
869+
assert.strictEqual(
870+
recording.calls.some(({ args }) => args[0] === "issue" && args[1] === "create"),
871+
false,
872+
);
873+
});
874+
833875
it("makes no write when the live title and body already match the render", () => {
834876
const report = blockedReport("5".repeat(40));
835877
const recording = exec({

0 commit comments

Comments
 (0)