plans: the changelog has three "Unreleased" sections and nothing that reads it #1980

Merged
jaylouisw merged 2 commits from plan/1118-1210 into main 2026-11-20 04:51:10 +00:00
Owner

Plan only - no code, no engine/test/workflow edits in this PR.

docs/plans/changelog-discipline.md, measured on b89ab7d6:

  • CHANGELOG.md is 551 lines / 6,397 words and carries three headings claiming to be unreleased (:1, :315, :418); its own # Changelog title and Keep-a-Changelog preamble sit at :308-314, under a server-CORS entry. git blame dates the entries below the title to 2026-11-08 - the same day as the entries above it, so the split is an artefact, not history.
  • Nothing requires an entry: 1,465 commits since 2026-11-07, 274 touching engine/, 36 touching CHANGELOG.md - and none at all between 11-09 and 11-15. No workflow, no CONTRIBUTING line, not in docs/wiki/.
  • git ls-remote --tags returns 0 tags while package.json:3 says 0.1.0, and the footer links point at github.com (deliberately exempted at scripts/canonical.js:33).
  • The only test that reads the file is test/canonical-urls.test.js:135-143, and it asserts the exemption - delete every entry and it still passes.
  • 18 category headings for 6 categories, two invented (Devices, Known defects (filed, not fixed)); six recent entries run 211-311 words against a 64-word median.

Six ordered steps, each one PR and one worker: collapse the document moving lines only, then a shape guard, category repair, traceability backfill, shrinking the six long entries, and finally (needs Jay) a tag, a footer fix and a gated entry requirement scoped to engine/, server/, web/.

Closes no open issue - the queue is #130 and #803, both device requests. Steps 6 needs Jay's approval before anyone acts on it.

Plan only - no code, no engine/test/workflow edits in this PR. `docs/plans/changelog-discipline.md`, measured on `b89ab7d6`: - `CHANGELOG.md` is 551 lines / 6,397 words and carries **three** headings claiming to be unreleased (`:1`, `:315`, `:418`); its own `# Changelog` title and Keep-a-Changelog preamble sit at `:308-314`, under a server-CORS entry. git blame dates the entries below the title to 2026-11-08 - the same day as the entries above it, so the split is an artefact, not history. - Nothing requires an entry: 1,465 commits since 2026-11-07, 274 touching `engine/`, 36 touching `CHANGELOG.md` - and none at all between 11-09 and 11-15. No workflow, no CONTRIBUTING line, not in `docs/wiki/`. - `git ls-remote --tags` returns 0 tags while `package.json:3` says 0.1.0, and the footer links point at github.com (deliberately exempted at `scripts/canonical.js:33`). - The only test that reads the file is `test/canonical-urls.test.js:135-143`, and it asserts the *exemption* - delete every entry and it still passes. - 18 category headings for 6 categories, two invented (`Devices`, `Known defects (filed, not fixed)`); six recent entries run 211-311 words against a 64-word median. Six ordered steps, each one PR and one worker: collapse the document moving lines only, then a shape guard, category repair, traceability backfill, shrinking the six long entries, and finally (needs Jay) a tag, a footer fix and a gated entry requirement scoped to `engine/`, `server/`, `web/`. Closes no open issue - the queue is #130 and #803, both device requests. Steps 6 needs Jay's approval before anyone acts on it.
plans: the changelog has three Unreleased sections and nothing that reads it
Some checks failed
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 4s
CI / Classify the change (pull_request) Successful in 7s
CI / Test (Node 20) (pull_request) Failing after 5s
CI / Test (Node 18) (pull_request) Failing after 9s
CI / Server smoke test (pull_request) Successful in 6s
CI / Test (Node 22) (pull_request) Failing after 11s
CI / Docker build (pull_request) Successful in 18s
CI / Arm auto-merge (pull_request) Successful in 2s
1c85a41b30
Author
Owner

CI is red for one reason, and it is not the suite: scripts/check-canonical-urls.js exits 1 on this PR.

Verified locally on the merge of 1c85a41b into origin/main (a5551421, clean merge, no add/add):

$ node scripts/check-canonical-urls.js ; echo rc=$?
Canonical URL drift (1):
  docs/plans/changelog-discipline.md:36  E_STALE_REPO_URL
    points at the old GitHub repository; the canonical home is https://git.jayw.uk/jaylouisw/packetforge
rc=1
  • scripts/audit-port-types.js rc=0, scripts/check-control-bytes.js rc=0, scripts/check-node-surface.js rc=0, scripts/check-ci-disk-hygiene.js rc=0.
  • The failing line is the sentence quoting the CHANGELOG footer: defines `[Unreleased]` and `[0.1.0]` as `github.com/Jaylouisw/packetforge` links. That literal matches canonical.FORBIDDEN (scripts/canonical.js:35). The checker is line-based and does not skip fenced blocks or backticks, so quoting it in prose or in code both fail.
  • This explains the shape of the red: all three Test (Node *) legs died in 5 s / 9 s / 11 s, i.e. at the third static check, before run-tests.js starts (a green leg on this repo takes 48–64 s). Node 18/20/22 all fail identically, which is the signature of a shared pre-suite step, not of the diff.

Not mine to fix (docs/ and scripts/ content belong to the owning stream), so two mechanical options, both verified against the tests:

  1. Reword :36 so the literal does not appear — e.g. "GitHub links under the old owner/repo name". canonical.FORBIDDEN only matches github.com/Jaylouisw/packetforge; the bare word GitHub is not a violation. Smallest change, no code touched.
  2. Add to canonical.ALLOW in scripts/canonical.js: 'docs/plans/changelog-discipline.md': 'is the plan that documents the CHANGELOG URL exemption, so it has to quote the string under discussion'. test/canonical-urls.test.js validates that every ALLOW reason is a string >20 chars and does not count the keys, so no test edit is needed — I checked.

Take (1) unless you want the permanent exception. The plan content itself is fine and the PR merges cleanly; it is blocked on this one line.

**CI is red for one reason, and it is not the suite: `scripts/check-canonical-urls.js` exits 1 on this PR.** Verified locally on the merge of `1c85a41b` into `origin/main` (`a5551421`, clean merge, no add/add): ``` $ node scripts/check-canonical-urls.js ; echo rc=$? Canonical URL drift (1): docs/plans/changelog-discipline.md:36 E_STALE_REPO_URL points at the old GitHub repository; the canonical home is https://git.jayw.uk/jaylouisw/packetforge rc=1 ``` - `scripts/audit-port-types.js` rc=0, `scripts/check-control-bytes.js` rc=0, `scripts/check-node-surface.js` rc=0, `scripts/check-ci-disk-hygiene.js` rc=0. - The failing line is the sentence quoting the CHANGELOG footer: `` defines `[Unreleased]` and `[0.1.0]` as `github.com/Jaylouisw/packetforge` links ``. That literal matches `canonical.FORBIDDEN` (`scripts/canonical.js:35`). The checker is line-based and does **not** skip fenced blocks or backticks, so quoting it in prose or in code both fail. - This explains the shape of the red: all three `Test (Node *)` legs died in 5 s / 9 s / 11 s, i.e. at the third static check, before `run-tests.js` starts (a green leg on this repo takes 48–64 s). Node 18/20/22 all fail identically, which is the signature of a shared pre-suite step, not of the diff. **Not mine to fix** (docs/ and scripts/ content belong to the owning stream), so two mechanical options, both verified against the tests: 1. Reword `:36` so the literal does not appear — e.g. "GitHub links under the old owner/repo name". `canonical.FORBIDDEN` only matches `github.com/Jaylouisw/packetforge`; the bare word `GitHub` is not a violation. Smallest change, no code touched. 2. Add to `canonical.ALLOW` in `scripts/canonical.js`: `'docs/plans/changelog-discipline.md': 'is the plan that documents the CHANGELOG URL exemption, so it has to quote the string under discussion'`. `test/canonical-urls.test.js` validates that every ALLOW reason is a string >20 chars and does not count the keys, so no test edit is needed — I checked. Take (1) unless you want the permanent exception. The plan content itself is fine and the PR merges cleanly; it is blocked on this one line.
Author
Owner

Remedy verified - one token, not a rewrite. Line 36 quotes the CHANGELOG's own wording, so the guard fires on a mention rather than a wrong link. I did not edit the file (docs content is not mine to write); I tested the change in a throwaway worktree at 1c85a41b and threw it away.

Change on docs/plans/changelog-discipline.md:36:

- defines `[Unreleased]` and `[0.1.0]` as `github.com/Jaylouisw/packetforge` links, and `scripts/canonical.js:33`
+ defines `[Unreleased]` and `[0.1.0]` as `github.com/<owner>/packetforge` links, and `scripts/canonical.js:33`

Result with that single edit, run in the PR worktree:

$ node scripts/check-canonical-urls.js ; echo rc=$?
OK - 3138 files, every project URL points at https://git.jayw.uk/jaylouisw/packetforge
rc=0
$ node --test test/canonical-urls.test.js
# fail 0

scripts/canonical.js FORBIDDEN matches github\.com\/(Jaylouisw|jaylouisw)\/packetforge, so <owner> in place of the name satisfies it and the sentence still says what it meant (the footer names the old GitHub owner/name pair).

The alternative - an entry in canonical.ALLOW - would weaken a guard whose stated rule is "nothing may present GitHub as the place to clone from", for a document that is only describing the CHANGELOG. The reword is the smaller claim; ALLOW should stay for files that must name the old location.

Four of the legs are already green (Classify, Server smoke, Docker build, both arming jobs); only Test Node 18/20/22 fail, and they fail on this same checker line, so one edit turns the whole run green. No rebase needed - the PR is 1 ahead / 8 behind but the failing line is its own new file, so a rebase changes nothing.

Whoever holds this branch: apply the line above and push and it merges under Jay's standing green-PR rule. If Jay would rather the doc quote the URL verbatim, that needs the ALLOW entry instead - his call, not mine.

**Remedy verified - one token, not a rewrite.** Line 36 quotes the CHANGELOG's own wording, so the guard fires on a *mention* rather than a wrong link. I did not edit the file (docs content is not mine to write); I tested the change in a throwaway worktree at `1c85a41b` and threw it away. Change on `docs/plans/changelog-discipline.md:36`: ```diff - defines `[Unreleased]` and `[0.1.0]` as `github.com/Jaylouisw/packetforge` links, and `scripts/canonical.js:33` + defines `[Unreleased]` and `[0.1.0]` as `github.com/<owner>/packetforge` links, and `scripts/canonical.js:33` ``` Result with that single edit, run in the PR worktree: ``` $ node scripts/check-canonical-urls.js ; echo rc=$? OK - 3138 files, every project URL points at https://git.jayw.uk/jaylouisw/packetforge rc=0 $ node --test test/canonical-urls.test.js # fail 0 ``` `scripts/canonical.js` FORBIDDEN matches `github\.com\/(Jaylouisw|jaylouisw)\/packetforge`, so `<owner>` in place of the name satisfies it and the sentence still says what it meant (the footer names the old GitHub owner/name pair). The alternative - an entry in `canonical.ALLOW` - would weaken a guard whose stated rule is "nothing may present GitHub as the place to clone from", for a document that is only describing the CHANGELOG. The reword is the smaller claim; ALLOW should stay for files that must name the old location. Four of the legs are already green (Classify, Server smoke, Docker build, both arming jobs); only Test Node 18/20/22 fail, and they fail on this same checker line, so one edit turns the whole run green. **No rebase needed** - the PR is 1 ahead / 8 behind but the failing line is its own new file, so a rebase changes nothing. Whoever holds this branch: apply the line above and push and it merges under Jay's standing green-PR rule. If Jay would rather the doc quote the URL verbatim, that needs the ALLOW entry instead - his call, not mine.
Author
Owner

Re-verified against 40670d22, and one refinement on the two remedies.

Merged 1c85a41b into current origin/main locally: clean, no add/add. The guard failure set is unchanged — exactly one finding:

docs/plans/changelog-discipline.md:36  E_STALE_REPO_URL

check-control-bytes.js rc=0 on the same merge.

The refinement: canonical.ALLOW (scripts/canonical.js:43) is keyed by whole file, not by line. An entry for docs/plans/changelog-discipline.md would exempt that entire plan document from URL checking forever, not just the quoted CHANGELOG line — that is wider than the problem.

So the two options are not equivalent:

  1. Reword :36 to github.com/<owner>/packetforge — one token, guard stays full-strength. My recommendation.
  2. ALLOW entry — only worth it if the plan must keep quoting the literal old URL, and it silently blinds the guard for the rest of the file.

Still needs Jay's decision; I am not editing docs/ content as my own contribution.

**Re-verified against `40670d22`, and one refinement on the two remedies.** Merged `1c85a41b` into current `origin/main` locally: clean, no add/add. The guard failure set is unchanged — exactly one finding: ``` docs/plans/changelog-discipline.md:36 E_STALE_REPO_URL ``` `check-control-bytes.js` rc=0 on the same merge. The refinement: `canonical.ALLOW` (`scripts/canonical.js:43`) is keyed by **whole file**, not by line. An entry for `docs/plans/changelog-discipline.md` would exempt that entire plan document from URL checking forever, not just the quoted CHANGELOG line — that is wider than the problem. So the two options are not equivalent: 1. **Reword `:36`** to `github.com/<owner>/packetforge` — one token, guard stays full-strength. My recommendation. 2. **ALLOW entry** — only worth it if the plan must keep quoting the literal old URL, and it silently blinds the guard for the rest of the file. Still needs Jay's decision; I am not editing `docs/` content as my own contribution.
Author
Owner

Still red, and now I can name the exact cause — it is one line, and it is docs wording I do not write.

Measured locally on 1c85a41b merged with today's main (0df1bef6): clean merge, no add/add, then

node test/canonical-urls.test.js  ->  48 passed, 4 failed
  x no file points at the old repository (1 problems)
    docs/plans/changelog-discipline.md:36  E_STALE_REPO_URL
       points at the old GitHub repository; the canonical home is https://git.jayw.uk/jaylouisw/packetforge
       > defines `[Unreleased]` and `[0.1.0]` as `github.com/Jaylouisw/packetforge` links, and `scripts/canonical.js:33`
    x and the tree is clean again once the probe is removed
    x and the README is restored
    x and the tree is clean again once the probe is removed

All three red legs (Node 18/20/22) come from this one finding: the canonical-URL checker scans the literal text, and line 36 quotes the old GitHub URL while discussing the changelog's exemption. The other 48 assertions in the file pass. The 19 unrelated server-* suites that failed in my full local run pass in isolation (23/23 for server-cors, 41/41 for sfp28-legacy) — that was port/TIME_WAIT contention on my host from running 345 suites serially, not this PR.

Consequence: this PR cannot go green while line 36 holds the bare URL. A rebase cannot fix it — it is the file's own content.

Needs Jay's decision (third ask):

  1. Reword line 36 so the URL is not a literal (e.g. name the host and path rather than emitting a clickable/literal github.com/...), or
  2. grant a whole-file exemption in canonical.ALLOW — note ALLOW is file-granular, so that exempts all 102 lines, not just the quotation.

I am not editing docs content or scripts/canonical.js myself (standing rule). The rest of the plan reads correctly and merges cleanly, so nothing else needs to change.

**Still red, and now I can name the exact cause — it is one line, and it is docs wording I do not write.** Measured locally on `1c85a41b` merged with today's `main` (`0df1bef6`): clean merge, no add/add, then ``` node test/canonical-urls.test.js -> 48 passed, 4 failed x no file points at the old repository (1 problems) docs/plans/changelog-discipline.md:36 E_STALE_REPO_URL points at the old GitHub repository; the canonical home is https://git.jayw.uk/jaylouisw/packetforge > defines `[Unreleased]` and `[0.1.0]` as `github.com/Jaylouisw/packetforge` links, and `scripts/canonical.js:33` x and the tree is clean again once the probe is removed x and the README is restored x and the tree is clean again once the probe is removed ``` All three red legs (Node 18/20/22) come from this one finding: the canonical-URL checker scans the literal text, and line 36 *quotes* the old GitHub URL while discussing the changelog's exemption. The other 48 assertions in the file pass. The 19 unrelated `server-*` suites that failed in my full local run pass in isolation (23/23 for `server-cors`, 41/41 for `sfp28-legacy`) — that was port/TIME_WAIT contention on my host from running 345 suites serially, not this PR. **Consequence: this PR cannot go green while line 36 holds the bare URL.** A rebase cannot fix it — it is the file's own content. **Needs Jay's decision (third ask):** 1. Reword line 36 so the URL is not a literal (e.g. name the host and path rather than emitting a clickable/literal `github.com/...`), or 2. grant a whole-file exemption in `canonical.ALLOW` — note ALLOW is file-granular, so that exempts all 102 lines, not just the quotation. I am not editing docs content or `scripts/canonical.js` myself (standing rule). The rest of the plan reads correctly and merges cleanly, so nothing else needs to change.
Author
Owner

Status check: this is now the only open PR in the repo.

930050b0 -> f9b18c28 (#2008) -> c142e739 (#2005) both merged; the queue behind you is empty, so this one failing suite is the only thing blocking a clean queue.

Unchanged diagnosis: docs/plans/changelog-discipline.md:36 quotes the old GitHub URL verbatim, which trips E_STALE_REPO_URL and drags 4 assertions down on all three Node legs; every other check on 1c85a41b is green.

needs Jay's decision, one of:

  1. reword line 36 so the quotation is not a live-looking URL (mark it as historical, e.g. wrap in an explicit "was:" or code-escape the host), or
  2. grant the whole-file canonical.ALLOW if a plan document is allowed to carry a dead URL.

I cannot make that call: docs/ content is out of bounds for me, and either option is an editorial decision about whether a plan may quote a retired URL.

**Status check: this is now the only open PR in the repo.** `930050b0` -> `f9b18c28` (#2008) -> `c142e739` (#2005) both merged; the queue behind you is empty, so this one failing suite is the only thing blocking a clean queue. Unchanged diagnosis: `docs/plans/changelog-discipline.md:36` quotes the old GitHub URL verbatim, which trips `E_STALE_REPO_URL` and drags 4 assertions down on all three Node legs; every other check on `1c85a41b` is green. **needs Jay's decision**, one of: 1. reword line 36 so the quotation is not a live-looking URL (mark it as historical, e.g. wrap in an explicit "was:" or code-escape the host), or 2. grant the whole-file `canonical.ALLOW` if a plan document is allowed to carry a dead URL. I cannot make that call: `docs/` content is out of bounds for me, and either option is an editorial decision about whether a plan may quote a retired URL.
Author
Owner

Escalation — needs Jay's decision (surgery watchdog, 2026-11-18 19:37Z)

Classified as real failing suite, not superseded and not a stale-branch red:

  • git merge origin/main into plan/1118-1210 merges cleanly (no CONFLICT (add/add), no other conflict), so the branch is not reintroducing files main already carries.

  • Full suite locally on the merged tree: 347 suite(s) in 192.1s — 12031 assertions passed, 4 failed, one failing suite:
    test/canonical-urls.test.js -> ✗ no file points at the old repository (1 problems)
    docs/plans/changelog-discipline.md E_STALE_REPO_URL — points at the old GitHub repository; the canonical home is https://git.jayw.uk/jaylouisw/packetforge

  • The offending text is docs/plans/changelog-discipline.md:36, which quotes the stale URL verbatim while explaining the CHANGELOG footer:

    defines [Unreleased] and [0.1.0] as github.com/Jaylouisw/packetforge links, and scripts/canonical.js:33

So the doc trips the same rule it is documenting. That is a wording-vs-test question, not a mechanical fix, so I have not touched it (docs/ content is not mine to edit).

Options, all one-liners for whoever owns the PR:

  1. Reword the quote so it does not spell out the host+repo (e.g. "the old GitHub repository" + a code-span split like github.com/ Jaylouisw/packetforge), or
  2. Extend test/canonical-urls.test.js with a documented exemption for this plan doc — but that weakens the gate, so it needs Jay's sign-off, or
  3. Point the sentence at scripts/canonical.js:33 alone and drop the literal URL.

Also note: the branch is 37 commits behind main (base e16e36cd), so once the content is fixed it still needs a rebase before it can go green. Ping me and I will rebase + re-run.

**Escalation — needs Jay's decision (surgery watchdog, 2026-11-18 19:37Z)** Classified as **real failing suite**, not superseded and not a stale-branch red: - `git merge origin/main` into `plan/1118-1210` merges **cleanly** (no `CONFLICT (add/add)`, no other conflict), so the branch is not reintroducing files main already carries. - Full suite locally on the merged tree: `347 suite(s) in 192.1s — 12031 assertions passed, 4 failed`, one failing suite: `test/canonical-urls.test.js` -> `✗ no file points at the old repository (1 problems)` `docs/plans/changelog-discipline.md E_STALE_REPO_URL — points at the old GitHub repository; the canonical home is https://git.jayw.uk/jaylouisw/packetforge` - The offending text is `docs/plans/changelog-discipline.md:36`, which *quotes* the stale URL verbatim while explaining the CHANGELOG footer: > defines `[Unreleased]` and `[0.1.0]` as `github.com/Jaylouisw/packetforge` links, and `scripts/canonical.js:33` So the doc trips the same rule it is documenting. That is a wording-vs-test question, not a mechanical fix, so I have not touched it (`docs/` content is not mine to edit). Options, all one-liners for whoever owns the PR: 1. Reword the quote so it does not spell out the host+repo (e.g. "the old GitHub repository" + a code-span split like `github.com/` `Jaylouisw/packetforge`), or 2. Extend `test/canonical-urls.test.js` with a documented exemption for this plan doc — but that weakens the gate, so it needs Jay's sign-off, or 3. Point the sentence at `scripts/canonical.js:33` alone and drop the literal URL. Also note: the branch is **37 commits behind** main (base `e16e36cd`), so once the content is fixed it still needs a rebase before it can go green. Ping me and I will rebase + re-run.
jaylouisw force-pushed plan/1118-1210 from 1c85a41b30
Some checks failed
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 4s
CI / Classify the change (pull_request) Successful in 7s
CI / Test (Node 20) (pull_request) Failing after 5s
CI / Test (Node 18) (pull_request) Failing after 9s
CI / Server smoke test (pull_request) Successful in 6s
CI / Test (Node 22) (pull_request) Failing after 11s
CI / Docker build (pull_request) Successful in 18s
CI / Arm auto-merge (pull_request) Successful in 2s
to d0579f8c9a
Some checks failed
CI / Classify the change (pull_request) Successful in 8s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 4s
CI / Server smoke test (pull_request) Successful in 9s
CI / Docker build (pull_request) Successful in 22s
CI / Test (Node 20) (pull_request) Failing after 52s
CI / Test (Node 22) (pull_request) Failing after 54s
CI / Test (Node 18) (pull_request) Failing after 57s
CI / Arm auto-merge (pull_request) Successful in 2s
2026-11-18 23:42:46 +00:00
Compare
Author
Owner

Red PR classified: real failing suite, not staleness — and it is this PR's own file.

Rebased onto main 68857a05 (clean, no conflicts) and pushed as d0579f8c; the fresh run is red on all three Node legs, and npm test locally reproduces it: 353/354 suites green, 12,233 assertions pass, 1 fails — test/canonical-urls.test.js.

✗ The repository is clean right now
    ✗ no file points at the old repository (1 problems)
        docs/plans/changelog-discipline.md E_STALE_REPO_URL — points at the old
        GitHub repository; the canonical home is https://git.jayw.uk/jaylouisw/packetforge

origin/main alone passes that suite 58/58, so the regression is the added doc, line 36:

defines `[Unreleased]` and `[0.1.0]` as `github.com/Jaylouisw/packetforge` links, and `scripts/canonical.js:33`

The literal old URL in prose trips the scanner; EXEMPT_FILES only covers CHANGELOG.md, not docs/plans/. Fix is one line of wording (name the host without spelling the full path, e.g. "the old github.com repository"), not a test change — and docs/ content is not mine to edit, so needs Jay's decision (or the plans stream) to land it.

Everything else in the rebase is clean and would merge as-is once that line is reworded.

Red PR classified: **real failing suite**, not staleness — and it is this PR's own file. Rebased onto main `68857a05` (clean, no conflicts) and pushed as `d0579f8c`; the fresh run is red on all three Node legs, and `npm test` locally reproduces it: **353/354 suites green, 12,233 assertions pass, 1 fails — `test/canonical-urls.test.js`**. ``` ✗ The repository is clean right now ✗ no file points at the old repository (1 problems) docs/plans/changelog-discipline.md E_STALE_REPO_URL — points at the old GitHub repository; the canonical home is https://git.jayw.uk/jaylouisw/packetforge ``` `origin/main` alone passes that suite 58/58, so the regression is the added doc, line 36: ``` defines `[Unreleased]` and `[0.1.0]` as `github.com/Jaylouisw/packetforge` links, and `scripts/canonical.js:33` ``` The literal old URL in prose trips the scanner; `EXEMPT_FILES` only covers `CHANGELOG.md`, not `docs/plans/`. Fix is one line of wording (name the host without spelling the full path, e.g. "the old `github.com` repository"), not a test change — and `docs/` content is not mine to edit, so **needs Jay's decision** (or the plans stream) to land it. Everything else in the rebase is clean and would merge as-is once that line is reworded.
Author
Owner

Surgery check on this PR (2026-11-19 02:5xZ).

Rebase: clean onto main a9e74b2e — no conflicts, nothing to resolve.

The red is real, and it is this PR's own doc. All three Test (Node N) legs fail on test/canonical-urls.test.js:

✗ no file points at the old repository (1 problems)
    docs/plans/changelog-discipline.md E_STALE_REPO_URL
    — points at the old GitHub repository; the canonical home is https://git.jayw.uk/jaylouisw/packetforge

docs/plans/changelog-discipline.md:36 (and :41) quote github.com/Jaylouisw/packetforge while describing the CHANGELOG link form. scripts/canonical.js:33 exempts only CHANGELOG.md (EXEMPT_FILES), so a plan doc that names the host is a hit.

Verified: main alone passes that suite (58 passed, 0 failed), so this is not a stale-main breakage — it is the new file.

Fix (author's, not surgery's — it is doc content): write the canonical URL https://git.jayw.uk/jaylouisw/packetforge, or refer to "the old GitHub repository" without spelling the host. Push and it will go green; the branch is otherwise ready. Needs the author's edit — I cannot amend docs content.

Surgery check on this PR (2026-11-19 02:5xZ). **Rebase:** clean onto main `a9e74b2e` — no conflicts, nothing to resolve. **The red is real, and it is this PR's own doc.** All three `Test (Node N)` legs fail on `test/canonical-urls.test.js`: ``` ✗ no file points at the old repository (1 problems) docs/plans/changelog-discipline.md E_STALE_REPO_URL — points at the old GitHub repository; the canonical home is https://git.jayw.uk/jaylouisw/packetforge ``` `docs/plans/changelog-discipline.md:36` (and `:41`) quote `github.com/Jaylouisw/packetforge` while describing the CHANGELOG link form. `scripts/canonical.js:33` exempts only `CHANGELOG.md` (`EXEMPT_FILES`), so a plan doc that names the host is a hit. **Verified:** main alone passes that suite (58 passed, 0 failed), so this is not a stale-main breakage — it is the new file. **Fix (author's, not surgery's — it is doc content):** write the canonical URL `https://git.jayw.uk/jaylouisw/packetforge`, or refer to "the old GitHub repository" without spelling the host. Push and it will go green; the branch is otherwise ready. **Needs the author's edit — I cannot amend docs content.**
jaylouisw force-pushed plan/1118-1210 from d0579f8c9a
Some checks failed
CI / Classify the change (pull_request) Successful in 8s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 4s
CI / Server smoke test (pull_request) Successful in 9s
CI / Docker build (pull_request) Successful in 22s
CI / Test (Node 20) (pull_request) Failing after 52s
CI / Test (Node 22) (pull_request) Failing after 54s
CI / Test (Node 18) (pull_request) Failing after 57s
CI / Arm auto-merge (pull_request) Successful in 2s
to c5469b7714
Some checks failed
CI / Classify the change (pull_request) Successful in 12s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 20s
CI / Test (Node 18) (pull_request) Failing after 59s
CI / Server smoke test (pull_request) Successful in 12s
CI / Test (Node 20) (pull_request) Failing after 56s
CI / Test (Node 22) (pull_request) Failing after 55s
CI / Docker build (pull_request) Successful in 22s
CI / Arm auto-merge (pull_request) Successful in 4s
2026-11-19 06:52:25 +00:00
Compare
Author
Owner

Rebased onto main (8349c59d) — clean, no conflicts; branch is now c5469b77. The red-all-legs run is a real failure, and it is one assertion:

✗ test/canonical-urls.test.js — the repository is clean right now
    docs/plans/changelog-discipline.md E_STALE_REPO_URL — points at the old GitHub repository;
    the canonical home is https://git.jayw.uk/jaylouisw/packetforge

It is line 36, in the description of the CHANGELOG's link definitions:

defines [Unreleased] and [0.1.0] as github.com/Jaylouisw/packetforge links

The scanner reads that as a stale repository URL. The rest of the suite (57 assertions) passes, as do syntax-check (443 files), check-control-bytes, check-doc-citations and the other 363 suites locally — 12,419 assertions, 1 failed, and that one is this line.

The fix is a wording change to the plan text, so it is the author's (or Jay's) to make, not a rebase resolution — e.g. say the links are GitHub-style compare links and name the file (CHANGELOG.md) instead of spelling the host. I have not touched the file. Once the URL is reworded, this PR is green and mergeable.

**Rebased onto main (`8349c59d`) — clean, no conflicts; branch is now `c5469b77`.** The red-all-legs run is a real failure, and it is one assertion: ``` ✗ test/canonical-urls.test.js — the repository is clean right now docs/plans/changelog-discipline.md E_STALE_REPO_URL — points at the old GitHub repository; the canonical home is https://git.jayw.uk/jaylouisw/packetforge ``` It is line 36, in the description of the CHANGELOG's link definitions: > defines `[Unreleased]` and `[0.1.0]` as `github.com/Jaylouisw/packetforge` links The scanner reads that as a stale repository URL. The rest of the suite (57 assertions) passes, as do `syntax-check` (443 files), `check-control-bytes`, `check-doc-citations` and the other 363 suites locally — 12,419 assertions, 1 failed, and that one is this line. The fix is a wording change to the plan text, so it is the author's (or Jay's) to make, not a rebase resolution — e.g. say the links are *GitHub-style compare links* and name the file (`CHANGELOG.md`) instead of spelling the host. I have not touched the file. Once the URL is reworded, this PR is green and mergeable.
Author
Owner

Surgery re-verification, 18:5xZ — main is now e0fa4221.

Rebased cleanly onto today's main in a scratch worktree (no conflicts), then ran the checker:

$ node test/canonical-urls.test.js
  ✗ no file points at the old repository (1 problems)
      docs/plans/changelog-discipline.md E_STALE_REPO_URL — points at the old GitHub repository;
      the canonical home is https://git.jayw.uk/jaylouisw/packetforge
57 passed, 1 failed

So the red is this PR's own new file tripping the canonical-URL rule — one line, the same one every previous check found. Not staleness, not a superseded merge: the branch is 83 commits behind but rebases clean, and the failure survives the rebase.

Needs Jay's decision, and it is a small one: either the doc should not quote the old GitHub URL at all (reword the example), or the checker needs a stated exception for a URL quoted as a historical example. I will not hand-edit docs/ content or weaken a rule on my own initiative.

**Surgery re-verification, 18:5xZ — main is now `e0fa4221`.** Rebased cleanly onto today's main in a scratch worktree (no conflicts), then ran the checker: ``` $ node test/canonical-urls.test.js ✗ no file points at the old repository (1 problems) docs/plans/changelog-discipline.md E_STALE_REPO_URL — points at the old GitHub repository; the canonical home is https://git.jayw.uk/jaylouisw/packetforge 57 passed, 1 failed ``` So the red is this PR's own new file tripping the canonical-URL rule — one line, the same one every previous check found. Not staleness, not a superseded merge: the branch is 83 commits behind but rebases clean, and the failure survives the rebase. **Needs Jay's decision**, and it is a small one: either the doc should not quote the old GitHub URL at all (reword the example), or the checker needs a stated exception for a URL quoted as a historical example. I will not hand-edit `docs/` content or weaken a rule on my own initiative.
Author
Owner

Surgery re-verification 2026-11-20 01:1xZ — the failure is now pinned to two lines, and it is the quoted-URL question, nothing else.

Merged today's origin/main (5ff2aba0) into the branch in a scratch worktree (clean, no conflicts) and ran the full suite:

394 suite(s) in 303.0 s — 13202 assertions passed, 1 failed
  ✗ test/canonical-urls.test.js

The single failure is E_STALE_REPO_URL on docs/plans/changelog-discipline.md, and only on the two lines where the doc quotes the old URL inside backticks as prose:

  • line 36: github.com/Jaylouisw/packetforge
  • line 41: EXEMPT_FILES.has('CHANGELOG.md') and that the text still contains github.com

scripts/canonical.js scans literally, so a quoted example reads as a real stale link. Everything else in the branch is green — this is not a code defect and not a rebase problem.

Three ways out, all one-liners, all needing your call because they touch authored docs or the scanner's policy:

  1. Reword the doc — say "the GitHub mirror" / "a github.com host" in prose instead of the literal URL.
  2. Exempt the file — add docs/plans/changelog-discipline.md to the scanner's exception list with a reason (the test already asserts "every exception says why").
  3. Loosen the scanner — ignore URLs inside backticks or blockquotes; bigger blast radius.

I have not touched either side: the doc is authored content and the allowlist is test/+scripts/ policy. Say which and it merges on the next run.

**Surgery re-verification 2026-11-20 01:1xZ — the failure is now pinned to two lines, and it is the quoted-URL question, nothing else.** Merged today's `origin/main` (`5ff2aba0`) into the branch in a scratch worktree (clean, no conflicts) and ran the full suite: ``` 394 suite(s) in 303.0 s — 13202 assertions passed, 1 failed ✗ test/canonical-urls.test.js ``` The single failure is `E_STALE_REPO_URL` on `docs/plans/changelog-discipline.md`, and only on the two lines where the doc *quotes* the old URL inside backticks as prose: - line 36: `github.com/Jaylouisw/packetforge` - line 41: `EXEMPT_FILES.has('CHANGELOG.md')` and that the text still contains `github.com` `scripts/canonical.js` scans literally, so a quoted example reads as a real stale link. Everything else in the branch is green — this is not a code defect and not a rebase problem. Three ways out, all one-liners, all needing your call because they touch authored docs or the scanner's policy: 1. **Reword the doc** — say "the GitHub mirror" / "a `github.com` host" in prose instead of the literal URL. 2. **Exempt the file** — add `docs/plans/changelog-discipline.md` to the scanner's exception list with a reason (the test already asserts "every exception says why"). 3. **Loosen the scanner** — ignore URLs inside backticks or blockquotes; bigger blast radius. I have not touched either side: the doc is authored content and the allowlist is `test/`+`scripts/` policy. Say which and it merges on the next run.
plans(changelog-discipline): stop the plan quoting the stale URL it is about
All checks were successful
CI / Classify the change (pull_request) Successful in 15s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 20s
CI / Test (Node 22) (pull_request) Successful in 1m7s
CI / Test (Node 20) (pull_request) Successful in 1m10s
CI / Server smoke test (pull_request) Successful in 10s
CI / Test (Node 18) (pull_request) Successful in 1m14s
CI / Docker build (pull_request) Successful in 21s
CI / Arm auto-merge (pull_request) Successful in 5s
79bb230393
This PR's own document reproduced `github.com/Jaylouisw/packetforge` verbatim
while describing the CHANGELOG footer links, so scripts/canonical.js reported
docs/plans/changelog-discipline.md E_STALE_REPO_URL and
test/canonical-urls.test.js failed on the branch head (57 passed, 1 failed) -
the only red suite in the tree, and the reason this plan could not merge.

Reworded the sentence to name the owner (`Jaylouisw`, capital included, which is
half the point) without reproducing the forbidden host/path, so the guard keeps
its meaning: CHANGELOG.md is the only file exempt, and nothing else may present
GitHub as the place to clone from. No change to the plan's substance.

node test/canonical-urls.test.js -> 58 passed, 0 failed
npm test -> 364 suites, 12420 assertions, 0 failed
forgejo-actions scheduled this pull request to auto merge when all checks succeed 2026-11-20 04:46:59 +00:00
jaylouisw deleted branch plan/1118-1210 2026-11-20 04:51:12 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jaylouisw/packetforge!1980
No description provided.