plans: the changelog has three "Unreleased" sections and nothing that reads it #1980
No reviewers
Labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
jaylouisw/packetforge!1980
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "plan/1118-1210"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Plan only - no code, no engine/test/workflow edits in this PR.
docs/plans/changelog-discipline.md, measured onb89ab7d6:CHANGELOG.mdis 551 lines / 6,397 words and carries three headings claiming to be unreleased (:1,:315,:418); its own# Changelogtitle 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.engine/, 36 touchingCHANGELOG.md- and none at all between 11-09 and 11-15. No workflow, no CONTRIBUTING line, not indocs/wiki/.git ls-remote --tagsreturns 0 tags whilepackage.json:3says 0.1.0, and the footer links point at github.com (deliberately exempted atscripts/canonical.js:33).test/canonical-urls.test.js:135-143, and it asserts the exemption - delete every entry and it still passes.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.
CI is red for one reason, and it is not the suite:
scripts/check-canonical-urls.jsexits 1 on this PR.Verified locally on the merge of
1c85a41bintoorigin/main(a5551421, clean merge, no add/add):scripts/audit-port-types.jsrc=0,scripts/check-control-bytes.jsrc=0,scripts/check-node-surface.jsrc=0,scripts/check-ci-disk-hygiene.jsrc=0.defines `[Unreleased]` and `[0.1.0]` as `github.com/Jaylouisw/packetforge` links. That literal matchescanonical.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.Test (Node *)legs died in 5 s / 9 s / 11 s, i.e. at the third static check, beforerun-tests.jsstarts (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:
:36so the literal does not appear — e.g. "GitHub links under the old owner/repo name".canonical.FORBIDDENonly matchesgithub.com/Jaylouisw/packetforge; the bare wordGitHubis not a violation. Smallest change, no code touched.canonical.ALLOWinscripts/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.jsvalidates 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.
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
1c85a41band threw it away.Change on
docs/plans/changelog-discipline.md:36:Result with that single edit, run in the PR worktree:
scripts/canonical.jsFORBIDDEN matchesgithub\.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.
Re-verified against
40670d22, and one refinement on the two remedies.Merged
1c85a41binto currentorigin/mainlocally: clean, no add/add. The guard failure set is unchanged — exactly one finding:check-control-bytes.jsrc=0 on the same merge.The refinement:
canonical.ALLOW(scripts/canonical.js:43) is keyed by whole file, not by line. An entry fordocs/plans/changelog-discipline.mdwould 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:
:36togithub.com/<owner>/packetforge— one token, guard stays full-strength. My recommendation.Still needs Jay's decision; I am not editing
docs/content as my own contribution.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
1c85a41bmerged with today'smain(0df1bef6): clean merge, no add/add, thenAll 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 forserver-cors, 41/41 forsfp28-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):
github.com/...), orcanonical.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.jsmyself (standing rule). The rest of the plan reads correctly and merges cleanly, so nothing else needs to change.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:36quotes the old GitHub URL verbatim, which tripsE_STALE_REPO_URLand drags 4 assertions down on all three Node legs; every other check on1c85a41bis green.needs Jay's decision, one of:
canonical.ALLOWif 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.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/mainintoplan/1118-1210merges cleanly (noCONFLICT (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/packetforgeThe offending text is
docs/plans/changelog-discipline.md:36, which quotes the stale URL verbatim while explaining the CHANGELOG footer: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:
github.com/Jaylouisw/packetforge), ortest/canonical-urls.test.jswith a documented exemption for this plan doc — but that weakens the gate, so it needs Jay's sign-off, orscripts/canonical.js:33alone 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.1c85a41b30d0579f8c9aRed PR classified: real failing suite, not staleness — and it is this PR's own file.
Rebased onto main
68857a05(clean, no conflicts) and pushed asd0579f8c; the fresh run is red on all three Node legs, andnpm testlocally reproduces it: 353/354 suites green, 12,233 assertions pass, 1 fails —test/canonical-urls.test.js.origin/mainalone passes that suite 58/58, so the regression is the added doc, line 36:The literal old URL in prose trips the scanner;
EXEMPT_FILESonly coversCHANGELOG.md, notdocs/plans/. Fix is one line of wording (name the host without spelling the full path, e.g. "the oldgithub.comrepository"), not a test change — anddocs/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.
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 ontest/canonical-urls.test.js:docs/plans/changelog-discipline.md:36(and:41) quotegithub.com/Jaylouisw/packetforgewhile describing the CHANGELOG link form.scripts/canonical.js:33exempts onlyCHANGELOG.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.d0579f8c9ac5469b7714Rebased onto main (
8349c59d) — clean, no conflicts; branch is nowc5469b77. The red-all-legs run is a real failure, and it is one assertion:It is line 36, in the description of the CHANGELOG's link definitions:
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-citationsand 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.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:
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 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:The single failure is
E_STALE_REPO_URLondocs/plans/changelog-discipline.md, and only on the two lines where the doc quotes the old URL inside backticks as prose:github.com/Jaylouisw/packetforgeEXEMPT_FILES.has('CHANGELOG.md')and that the text still containsgithub.comscripts/canonical.jsscans 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:
github.comhost" in prose instead of the literal URL.docs/plans/changelog-discipline.mdto the scanner's exception list with a reason (the test already asserts "every exception says why").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.