Skip to content

Commit 2299d18

Browse files
donjor-agent[bot]donjor
authored andcommitted
chore(fork): fork tooling sheds its dead flags, outputs, and stale docs (#1504)
## Problem The fork tooling carried flags, workflow outputs, header comments, and docs that nothing reads or that no longer match the scripts. `fork-delta.md` also named guards that do not exist: `fork-hook-seam`, `ADOPTED_AUTHORING_GUARDS`, `unexplainedRemoval`. ## Change Deletions and simplifications only; no new behavior. | Surface | Change | | --- | --- | | Script headers | Gate and job-step comments gone, with their two pinning tests | | `fork:delta` | `--squash-body` needs no refs; unused `warnings` gone; table separator fixed | | `fork:release-gate` | `--github-output` gone | | `fork-ci-flags` | Emits only `since`, the one output CI reads | | `fork:sync` | Battery drops its duplicate `fork:delta --check`; `publishedVia` drops `ghb` | | `fork:scan` | Help and comments lose step numbering | | `package.json` | `fork:release-version` and `fork:release-delta-rev` aliases gone | | `hyprws-body.yml` | No full fetch, no ref env | | `hyprws-release.yml` | Unread `gate_reason` output and preflight Electron install gone | | `hyprws-upstream-sync.yml` | Unread `exit` output gone | | `fork-delta.md` | Nonexistent guards and dead subsections gone; scan targets and roles match | | `fork-sync.md` | Battery and required contexts match the ruleset | | `fork-development.md` | Body workflow marked advisory | | PR template | Points to `FORK_DOMAINS` instead of copying it | | Kept | Why | | --- | --- | | `fork:regenerate-route-tree` | Still used by the sync | | "Marking a hook" | Only doc of the live `fork-hook:` marker | | Release "Fork ledger" step | No release job repeats it | ## Scope and approval Closes #1410 - [ ] **Docs:** every row above matches the scripts - [ ] **Code:** every row above deleted or simplified - [ ] **Checks:** `vp run fork:ci` passes ## Verification | Command | Exit | | --- | --- | | `vp run fork:ci` | 0 | | `vp run fork:delta --check` | 0 | | `vp run knip:check` | 0 | | `vp run --filter @t3tools/scripts typecheck` | 0 | | `vp test run` on the six touched fork test files (110 tests) | 0 | Claude Opus 5.5 in Claude Code, hosted by T3 Code. ## Fork trailers Squashes: - fbd91f5 chore(fork): fork tooling sheds its dead flags, outputs, and stale docs (#1504) (#1504) - ade60af fixup! chore(fork): fork tooling sheds its dead flags, outputs, and stale docs (#1504) (#1504) Fork-Domain: fork-meta Fork-Tier: qol Co-authored-by: donjor <[email protected]>
1 parent 9fa7d12 commit 2299d18

39 files changed

Lines changed: 99 additions & 500 deletions

‎.github/pull_request_template.md‎

Lines changed: 10 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -42,43 +42,26 @@ the change. Upload evidence to GitHub and embed or link it here. Never commit PR
4242

4343
<!-- RSI-Software/t3code-hyprws only. Delete this section on an upstream PR.
4444
45-
This body becomes the squash commit's message, so hyprws CI fails a pull
46-
request whose body does not END with the trailer block. Keep it last:
47-
git only reads trailers from the final paragraph.
48-
49-
Valid Fork-Domain values (copy one exactly; never invent a value):
50-
backend-attach
51-
browser-bookmarks
52-
custom-agents
53-
device-auth
54-
distribution
55-
fork-meta
56-
github-issues
57-
markdown-editing
58-
multi-window
59-
thread-ordering
60-
thread-fork
61-
upstream-fixes
62-
workspace-files
63-
workspaces
64-
worktrunk-hooks
65-
zmux-estate
66-
67-
This list copies FORK_DOMAINS in scripts/lib/fork-trailers.ts. It cannot tell a wrong domain
68-
from a right one, only a known value from an unknown one, so a plausible
69-
wrong pick quietly mis-attributes the change to a domain nobody touched.
45+
This body becomes the squash commit's message, so it must END with the
46+
trailer block; git only reads trailers from the final paragraph. The
47+
advisory hyprws Body workflow reports a body that does not.
48+
49+
Fork-Domain takes one value from FORK_DOMAINS in
50+
scripts/lib/fork-trailers.ts; copy it exactly and never invent one. The
51+
check only rejects an unknown value, so a plausible wrong pick quietly
52+
mis-attributes the change to a domain nobody touched.
7053
7154
Valid Fork-Tier values: core, qol, bugfix.
7255
Fork-Upstreamable values: yes, no. Required when Fork-Tier is bugfix.
7356
7457
Write a fork issue in full: `Closes RSI-Software/t3code-hyprws#N`.
75-
A bare `#N` counts as a live upstream reference and fails the Body job;
58+
A bare `#N` counts as a live upstream reference and fails hyprws Body;
7659
`vp run fork:upstream-refs <file>` runs the same check on a draft body.
7760
7861
Do not copy Base branch or Head branch prompt context into the PR body.
7962
Do not add prose, metadata, mentions, or headings after the trailers.
8063
81-
Replace the placeholders below. CI rejects them unedited. -->
64+
Replace the placeholders below; hyprws Body rejects them unedited. -->
8265

8366
Fork-Domain: DOMAIN
8467
Fork-Tier: TIER

‎.github/workflows/hyprws-body.yml‎

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,6 @@ jobs:
2929
- name: Checkout
3030
uses: actions/checkout@v6
3131
with:
32-
fetch-depth: 0
3332
sparse-checkout: |
3433
/*
3534
!/.repos/
@@ -73,9 +72,5 @@ jobs:
7372
github.event_name == 'pull_request' &&
7473
github.event.pull_request.base.ref == 'hyprws' &&
7574
github.event.pull_request.draft == false
76-
env:
77-
# The checkout refreshes this live base; the scanner compares its merge base with HEAD_SHA.
78-
BASE_REF: origin/hyprws
79-
HEAD_SHA: ${{ github.event.pull_request.head.sha }}
8075
run: |
81-
vp run fork:delta --check --base "$BASE_REF" --head "$HEAD_SHA" --squash-body "$RUNNER_TEMP/pull-request-body.md"
76+
vp run fork:delta --check --squash-body "$RUNNER_TEMP/pull-request-body.md"

‎.github/workflows/hyprws-release.yml‎

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,6 @@ jobs:
113113
upstream_base: ${{ steps.upstream_base.outputs.tag }}
114114
delta_revision: ${{ steps.delta_revision.outputs.delta_revision }}
115115
gate_proceed: ${{ steps.release_gate.outputs.gate_proceed }}
116-
gate_reason: ${{ steps.release_gate.outputs.gate_reason }}
117116
ref: ${{ steps.release_ref.outputs.sha }}
118117
steps:
119118
- id: release_channel
@@ -197,7 +196,6 @@ jobs:
197196
// A fetch failure closes the gate with a reason, never a throw.
198197
const close = async (reason) => {
199198
core.setOutput('gate_proceed', 'false');
200-
core.setOutput('gate_reason', reason);
201199
await core.summary.addHeading('Release gate: closed').addRaw(reason).write();
202200
core.setFailed(reason);
203201
};
@@ -207,7 +205,6 @@ jobs:
207205
// so this branch skips without failing the step.
208206
const skip = async (reason) => {
209207
core.setOutput('gate_proceed', 'false');
210-
core.setOutput('gate_reason', reason);
211208
await core.summary.addHeading('Release gate: skipped').addRaw(reason).write();
212209
core.info(reason);
213210
};
@@ -251,7 +248,6 @@ jobs:
251248
const proceed = first.startsWith('proceed');
252249
const reason = first.replace(/^(proceed|skip):\s*/, '');
253250
core.setOutput('gate_proceed', proceed ? 'true' : 'false');
254-
core.setOutput('gate_reason', reason);
255251
if (!proceed) {
256252
await close(reason);
257253
return;
@@ -265,9 +261,6 @@ jobs:
265261
cache: true
266262
run-install: true
267263

268-
- name: Ensure Electron runtime is installed
269-
run: vp run --filter @t3tools/desktop ensure:electron
270-
271264
- id: release_meta
272265
name: Resolve release version
273266
shell: bash

‎.github/workflows/hyprws-upstream-sync.yml‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -139,10 +139,9 @@ jobs:
139139
140140
# The driver pushes the trunk with the mirror
141141
# PAT, built here so the token never lands in .git/config or a workflow
142-
# env block the check battery inherits. Its issue writes go through ghb
142+
# env block the check battery inherits. Its issue writes go through gh
143143
# with the job's own token (issues: write).
144144
- name: Run the sync driver
145-
id: sync
146145
env:
147146
GH_TOKEN: ${{ github.token }}
148147
GH_REPO: ${{ github.repository }}
@@ -156,7 +155,6 @@ jobs:
156155
vp run fork:sync 2>&1 | tee "$RUNNER_TEMP/fork-sync.log"
157156
code=${PIPESTATUS[0]}
158157
set -e
159-
echo "exit=$code" >> "$GITHUB_OUTPUT"
160158
exit "$code"
161159
162160
- name: Summarize the run

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

Lines changed: 9 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -27,13 +27,10 @@ vp run fork:scan --target vX.Y.Z # the same walk pinned to a tag
2727
`fork:scan` fails when a domain's own commits change a file its table omits and upstream also changed.
2828
Every code span in a Path cell is one pattern: `*` stays inside a segment, `**` spans them.
2929

30-
| Where | Mode | Against |
31-
| --------------------------------------------------------- | -------------------- | -------------------- |
32-
| Fork CI | Blocking, every push | live `upstream/main` |
33-
| The sync driver's check step (`hyprws-upstream-sync.yml`) | Blocking | the rebased tip |
34-
35-
**Stale fork mocks.** On every rebase, diff each `*.fork.test.*` mock key set against the sibling `*.test.*` mock of the same service.
36-
A key present upstream and absent in the fork sibling is stale even when both suites pass.
30+
| Where | Mode | Against |
31+
| --------------------------------------------------------- | -------------------- | ----------------------- |
32+
| Fork CI | Blocking, every push | its upstream merge base |
33+
| The sync driver's check step (`hyprws-upstream-sync.yml`) | Blocking | the target tag |
3734

3835
## Why the fork exists
3936

@@ -71,14 +68,13 @@ A retirement is recorded by the retire commit itself, not a ledger.
7168
`Fork-Repair` marks a repair the next fold absorbs.
7269
`vp run fork:delta --check` enforces the table on every push, and a rebase preserves trailers.
7370

74-
**Squash-body mode.** Fork CI also runs it with `--base origin/hyprws --head <sha> --squash-body <file>`, both refs explicit.
71+
**Squash-body mode.** The advisory `hyprws Body` workflow runs `--check --squash-body <file>`; it is not a required check.
7572
It validates the body's final trailer paragraph, which becomes the squash trailers.
7673
A trailer carried only by a branch commit cannot satisfy it.
7774

7875
## Carry cost
7976

8077
Decided per commit by the levers retire, reshape, automate, or accept; no gate carries a numeric cap.
81-
8278
**Accept is never "as-is".** A kept commit needs a mechanical seam: fork code in fork-only files, and upstream files carrying only marked hook lines the walk re-applies.
8379

8480
### Marking a hook
@@ -87,7 +83,6 @@ Decided per commit by the levers retire, reshape, automate, or accept; no gate c
8783
| -------------- | ------------------------------------------------------------------------- |
8884
| Statement | trailing `// fork-hook: <domain>/<name>` or `/* fork-hook: … */` |
8985
| Multi-line JSX | the pair `{/* fork-hook: <domain>/<name> */}` and `{/* fork-hook-end */}` |
90-
| Charging | `scripts/lib/fork-hooks.ts` is fork-owned, so its edit is never charged |
9186

9287
**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.
9388
**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.
@@ -130,60 +125,6 @@ const trackInstaller = (install: (session: Session) => void) =>
130125
); // fork-hook: multi-window/download-track
131126
```
132127

133-
### The removal rule
134-
135-
`unexplainedRemoval` aligns base against fork over significant lines, accepting a removed base line only when its position falls inside a marked span.
136-
137-
| Case | Result |
138-
| -------------------------------------------- | ------------------------------------------------ |
139-
| A marked hook elsewhere in the file | absorbs nothing |
140-
| A removal outside every marked span | refused by the walk, charged by `fork-hook-seam` |
141-
| A needed deletion with no marked replacement | reshape debt with a named reason |
142-
143-
At a replay stop the walk re-inserts a marked hook by its manifest anchor when that anchor resolves to exactly one site.
144-
Zero sites, several, or an unplaceable end marker leaves an ordinary `conflict` stop naming the hook.
145-
146-
### The `fork-hook-seam` guard
147-
148-
It refuses an addition outside a marked hook, a deletion outside the removal rule, or an unknown marker, and lives in `ADOPTED_AUTHORING_GUARDS`.
149-
150-
| Aspect | Rule |
151-
| ----------------- | -------------------------------------------------------------------------------------------------- |
152-
| Fork side | rebuilt from the upstream blob and the diff's positions |
153-
| Unreconstructable | charged, never exempted |
154-
| Removal gap | every addition in it must be a line-kind marked hook |
155-
| Formatter reflow | same tokens either side: no `fork-hook-seam` addition charge; the hook guard has no such exemption |
156-
| Outside the rule | upstreamable `bugfix` commits, and generated paths |
157-
| Generated files | never reshape debt; a sync restores HEAD and regenerates |
158-
| Historical range | advisory, so the woven trunk is unaffected |
159-
160-
It charges some seams the walk accepts, never the reverse.
161-
A scar rule directs the author to a fork-owned file, and the narrow call left behind still needs its own marker.
162-
163-
### Declaration and placement
164-
165-
**Declaration comes from the fork tip, placement from the replayed blob, and the tip wins**, because a seam whose owning commit predates its marker carries no marker in that blob.
166-
167-
| Case | Resolution |
168-
| ------------------------- | --------------------------------------------- |
169-
| The blob carries a marker | the in-file marker wins |
170-
| Otherwise | locate the tip's marked span in the fork side |
171-
| Absent or ambiguous | refuse, reporting the key and replay position |
172-
| Replay position | threaded in, never inferred from rebase state |
173-
174-
### Measurement
175-
176-
**Measurement informs, it never enforces.** `vp run fork:delta --inventory` measures commits, lines, and shared files per domain.
177-
178-
| Subject | Rule |
179-
| ------------------------------- | ------------------------------------------------------- |
180-
| `Fork-Repair` commits | visible per commit, excluded from domain sums |
181-
| `vp run fork:delta --inventory` | measures the checkout; the sync report measures nothing |
182-
183-
**A `.fork.` in a filename is a reader signal only.**
184-
No guard decides on it, and its one placement rule is [Fork tests live in fork-owned files](./fork-development.md#fork-tests-live-in-fork-owned-files).
185-
A per-file diff says nothing about seam growth until `git cat-file -e origin/main:<path>` proves the path exists upstream.
186-
187128
## Domain index
188129

189130
| Domain | Status | Tiers present | Retires when |
@@ -445,10 +386,10 @@ Upstream ships rich Markdown editing with safe frontmatter and MDX boundaries, o
445386
| ------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
446387
| `README.md`, `AGENTS.md`, `docs/README.md` | The fork sections |
447388
| This document, [Fork development](./fork-development.md), [Fork sync](../operations/fork-sync.md) | Fork documentation |
448-
| `scripts/fork-*.ts` and their `fork:*` aliases | The fork gates; `package.json` names them |
389+
| `scripts/fork-*.ts` and their `fork:*` aliases | The fork tooling; hand-run ones get an alias |
449390
| [`fork-sync`](../../../.agents/skills/fork-sync/SKILL.md) skill | The sync driver's run and unblock procedure |
450391
| `.github/workflows/hyprws-upstream-sync.yml` | The sync workflow and its fork-local issue upserts |
451-
| `.github/pull_request_template.md` trailer block | Domain list copied from `FORK_DOMAINS` |
392+
| `.github/pull_request_template.md` trailer block | Points to `FORK_DOMAINS` for the domain list |
452393

453394
Every fork workflow checkout that runs rebased code scrubs its persisted credential first; `hyprws-upstream-sync.yml`'s scrub step is the pattern.
454395

@@ -521,7 +462,8 @@ A tagged upstream release ships owner-approved native client authorization.
521462

522463
| Item | Role |
523464
| ------------------------------------------------- | ---------------------------------------------------------------- |
524-
| `.github/workflows/hyprws-ci.yml` | Checks, tests, trailer check, citation guard, desktop build |
465+
| `.github/workflows/hyprws-ci.yml` | Checks, tests, trailer check, desktop build |
466+
| `.github/workflows/hyprws-body.yml` | Advisory body checks: citations, squash trailers |
525467
| `.github/workflows/hyprws-release.yml` | Human-cut stable releases plus a prerelease per `hyprws` landing |
526468
| `scripts/fork-release-version.ts` | Resolves channel metadata and the previous tag in that channel |
527469
| `scripts/build-desktop-artifact.ts` | Derives the update feed from `GITHUB_REPOSITORY` |

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -130,7 +130,7 @@ Land onto `hyprws` by squash; a merge commit breaks the stack.
130130
- **Never raw `git merge`:** bypasses both
131131

132132
`ghb pr merge` squashes with the PR title and body, so end it with trailers.
133-
`.github/workflows/hyprws-ci.yml` is the required check.
133+
`.github/workflows/hyprws-ci.yml` is the required check; `hyprws-body.yml` checks the body's trailers and citations, advisory only.
134134
Non-linear movement onto `hyprws` voids a sync run's lease; the next run rebases over a merge commit the same way over any other base, which is exactly what the fork stack forbids.
135135

136136
## Upstream citations
@@ -215,7 +215,7 @@ forkSupersedes({
215215
The import is a typed no-op: `fork:scan` reads the declaration from the sibling's text and never runs it.
216216
Never `it.skip`, a comment-out, or an in-place edit: a bare skip loses an assertion unnoticed.
217217

218-
| `fork:scan` step 4 reads | Result |
218+
| `fork:scan` reads | Result |
219219
| ------------------------------------------------ | ---------------- |
220220
| A call missing `upstream`, `reason`, or `commit` | fails the scan |
221221
| A named file or test the target lacks | fails the scan |

0 commit comments

Comments
 (0)