From 2fa78a78579c441ffd94a04cb8dcf09875a17736 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 20 Sep 2026 12:50:33 +0000 Subject: [PATCH 1/2] =?UTF-8?q?docs(cli):=20record=20what=20docs/duplicate?= =?UTF-8?q?-name=20rests=20on=20after=20ADR-0048=20=C2=A73.4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Quote §3.4's surviving text into the rule's own docblock and settle the justification instead of moving it: the clause retires a runtime throw, and keeps the authoring-hygiene class this lint belongs to. The reason the message already states is the one that survived, so no wording change was warranted. Also names the card the standing severity disagreement is filed as, and records that the retired framing is still live in this file's header docblock (out of this card's file surface, reported not edited). Claude-Session: https://claude.ai/code/session_01QCdUBjM47SxioST9z5Zwdf Co-authored-by: Claude --- packages/cli/src/utils/collect-docs.ts | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/packages/cli/src/utils/collect-docs.ts b/packages/cli/src/utils/collect-docs.ts index 5b44d5b6c2..05630c9764 100644 --- a/packages/cli/src/utils/collect-docs.ts +++ b/packages/cli/src/utils/collect-docs.ts @@ -934,8 +934,23 @@ function bodyDocsOf(packages: unknown, index: number): DocItem[] { * cross-package throw is retired"). What survives there is exactly what this * is: an authoring-time hygiene lint. ⚠️ That `os build` refuses the shape at * all is a standing disagreement with ADR-0048 §3.4 which PREDATES this card - * and is filed rather than changed here — ⛔ relaxing a refusal that shipped is - * not a rider on a widening. + * and is filed as #19248 rather than changed here — ⛔ relaxing a refusal that + * shipped is not a rider on a widening. + * + * #19248 read §3.4 back and settled the justification rather than moving it. + * The clause retires a RUNTIME throw and nothing else — *"The cross-package + * **throw is retired**; two distinct packages coexist on the same bare name by + * construction."* — while keeping the class this lint belongs to: *"Authoring-time + * hygiene — an author shipping two `page/home` in one package — stays covered by + * the `naming/namespace-prefix` lint in `os lint`."* So the reason stated above is + * the one that survived §3.4, and ⛔ no wording change was warranted. What #19248 + * left open is the SEVERITY, not the reason: §3.4 hands authoring hygiene to a + * warning-only lint while this one is `severity: 'error'`. + * + * ⚠️ "this module's older framing" above is not gone — it is still live in this + * file's HEADER docblock, which states the retired claim as the current reason for + * the naming lints. Out of #19248's file surface (it also justifies + * `docs/namespace-prefix`), so it is reported, not edited here. */ function lintDocNamesAcrossOwners( sets: ReadonlyArray<{ label: string; docs: readonly DocItem[] }>, From 9a0331f8101fe1094410482fe63b2b98c213e2d5 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 20 Sep 2026 13:03:38 +0000 Subject: [PATCH 2/2] chore(changeset): patch @objectstack/cli for the docs/duplicate-name record The comment is emitted into the published tarball (files[] ships dist/, tsc without removeComments), so the diff publishes bytes and takes a changeset rather than skip-changeset. Measurement recorded in the body. Claude-Session: https://claude.ai/code/session_01QCdUBjM47SxioST9z5Zwdf Co-authored-by: Claude --- .../19248-duplicate-name-justification.md | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 .changeset/19248-duplicate-name-justification.md diff --git a/.changeset/19248-duplicate-name-justification.md b/.changeset/19248-duplicate-name-justification.md new file mode 100644 index 0000000000..edb5ccbf50 --- /dev/null +++ b/.changeset/19248-duplicate-name-justification.md @@ -0,0 +1,43 @@ +--- +'@objectstack/cli': patch +--- + +`collect-docs.ts` records what the `docs/duplicate-name` refusal rests on now that ADR-0048 §3.4 retired its older justification (#19248) + +`docs/duplicate-name` refuses two owners declaring one doc name. The claim it +was once explained by — *"one registration overwrites the other"* — was retired +by ADR-0048, and a refusal whose stated justification no longer exists is worth +examining rather than inheriting second-hand. #19248 examined it. + +**The verdict is that no wording change was warranted**, and the ADR text is +quoted into the rule's own docblock so the next reader does not have to +re-derive it. §3.4 retires a RUNTIME throw and nothing else — *"The +cross-package **throw is retired**; two distinct packages coexist on the same +bare name by construction."* — while keeping, in the same clause, the class +this lint belongs to: *"Authoring-time hygiene — an author shipping two +`page/home` in one package — stays covered by the `naming/namespace-prefix` +lint in `os lint`."* Both sentences are quoted verbatim, checked against +`docs/adr/0048-cross-package-metadata-collision.md` on this branch's base +(`13d52947d8`) rather than recalled. + +The message already said `for authoring hygiene` and already declined the +retired claim by name, so what shipped was correct and stays byte-identical. +What the docblock gains is the ADR's own words, the card number the standing +**severity** disagreement is filed under, and the boundary between the two +questions: §3.4 hands authoring hygiene to a warning-only lint while this one +is `severity: 'error'`, which is a live question about the level and not about +the reason. + +⛔ No behaviour changes. No rule, message, severity or accept set moves; the +only edited bytes are inside one docblock comment. + +**This ships, which is why it carries a changeset rather than +`skip-changeset`.** `@objectstack/cli`'s published `files[]` is +`["dist","README.md","CHANGELOG.md"]` and the package builds with plain `tsc` +(`tsc -p tsconfig.build.json`, no `removeComments`), so the comment is emitted +into the tarball — measured on the rebuilt artifact: the new clause is present +in `dist/utils/collect-docs.js` (1 occurrence), the replaced spelling is absent +from all of `dist` (0), and `dist/**/*.d.ts` carries 0 of it because the block +sits above a non-exported helper. The rule's own runtime message resolves to +that same file as the positive control. So the published JS bytes move while +the declaration surface does not.