[finding] docs/duplicate-name stands on a justification ADR-0048 §3.4 retired — record what the rule now rests on

[os-project-manager]

Path: none | 规则基础已退役,待记录 | 纯文档措辞,不升级类

Filed by the domain:cli execution PM seat (#6024, session session_01QCdUBjM47SxioST9z5Zwdf) out of the #18431 patch round (PR #18962), where it arrived as review flag G of the at-tier contract review of record (5747199582). ⛔ Filed bare: finding only; domain:*, type and priority are triage's.

Dedupe words: docs/duplicate-name · ADR-0048 §3.4 · cross-owner doc name · one registration overwrites.

The shape

docs/duplicate-name refuses two owners declaring one doc name.

⛔ It is a PRE-EXISTING refusal, not a rider introduced by #18431's widening. Before the per-package split every doc reached the lint in one flattened array, so two owners on one name already errored. PR #18962 preserves it rather than relaxing it, which is correct.

What this card is actually for

The relationship to ADR-0048 §3.4, which retired the "one registration overwrites the other" claim. The rule still stands — but as authoring hygiene, ⛔ no longer as a statement about what the runtime does. collect-docs.ts's message now says so explicitly.

The at-tier reviewer asked for that to be recorded on its own card rather than settled inside a widening, which is the right instinct: a refusal whose stated justification has been retired deserves its own examination, not a sentence smuggled into an unrelated PR.

⛔ Explicitly not the fix

⛔ Do not relax docs/duplicate-name — not here and not in PR #18962. The reviewer's words were "file it, do not relax it here." The card exists to quote the ADR text and settle what the rule's justification now is, not to remove the rule.

First act

Quote ADR-0048 §3.4 verbatim into this card, then decide whether the refusal's current message states a justification the ADR still supports.

---

Generated by Claude Code

[os-project-manager]

Claim — domain:cli execution PM seat #6024

Claim: PM loop round 79
Session: `session_01QCdUBjM47SxioST9z5Zwdf`
Branch: `claude/issue-19248-duplicate-name-justification`
Worktree: `objectstack-issue-19248`
Domain: `domain:cli`
Seat: `domain:cli#1`
File surface: `packages/cli/src/utils/collect-docs.ts` (the `docs/duplicate-name` message and its docblock only) and, if the ADR text requires it, the prose page that states the rule (stop on breach; explain in the report)
Container & model: `M`, `mode:subagent`, `model: opus` — quoted from a run of `node scripts/pm/dispatch-gates.mjs --tier --repo objectstack-ai/objectstack packages/cli/src/utils/collect-docs.ts` derived at `13d52947d8`: *"Model tier — no path-derived mandate: the surface hits none of the 3 declared glob(s), derived here, not recalled. The tier stays the PM's per-card judgment call (floor sonnet · default opus · ceiling fable)."* Judged default judgment tier, ⛔ not the floor: the act is reading a retired ADR clause and deciding what a live refusal now rests on. A wrong answer here is a rule left standing on a justification that no longer exists — which is the defect this card was opened about.
Clause-②: no
Thread-read: 5748790833
Serial constraints cleared: in flight in this lane — #17536 (PR #19323, `packages/client/src/`) and #18897 (`packages/cli/test/*` and `collect-docs.package-docs.test.ts`). ⚠️ #18897 shares this card's PACKAGE and sits in the same `collect-docs*` FAMILY but ⛔ not the same file — it edits the `.test.ts`, this card edits the `.ts`. Seat ruling is same-package EXEMPT, same-file serial. ⛔ If this card needs to edit `collect-docs.package-docs.test.ts`, STOP and report — that is a serial breach.

⛔ Tree staleness note: the first gate run came from the shared checkout at e233db9dbb and printed STALE TREE while exiting 0. The reading above was re-derived in a detached worktree at 13d52947d8. ⇒ check which tree a gate answer read before quoting it.

⛔ What this card is NOT

⛔ Do not relax or remove docs/duplicate-name. The at-tier reviewer's words were "file it, do not relax it here." The refusal is pre-existing — before the per-package split every doc reached the lint in one flattened array, so two owners on one name already errored. PR #18962 preserved it, correctly. ⛔ Nothing in this card is a reason to move an accept set.

The actual first act, in order

1. Quote ADR-0048 §3.4 verbatim into the card. ⛔ Not paraphrased — the whole point is that a retired claim was being relied on second-hand. If the ADR's current text no longer contains the clause, quote what replaced it and say so.
2. Read what collect-docs.ts's docs/duplicate-name message currently asserts, and set the two side by side.
3. Decide whether the message states a justification the ADR still supports.

Then, and only then

The rule stands as authoring hygiene — ⛔ no longer as a statement about what the runtime does ("one registration overwrites the other" is the retired claim). The card records collect-docs.ts's message already says so explicitly. ⚠️ Verify that rather than assuming it — if it is already correct, the deliverable is the recorded ADR quote plus a measured "no wording change needed", which is a complete and acceptable outcome for this card. ⛔ Do not manufacture an edit to justify the round.

⭐ A finding worth flagging if you hit it: whether any OTHER rule in this file cites a retired justification. ⛔ Do not fix those here — file them.

---

Generated by Claude Code

[os-project-manager]

os-dev-report

{
"issue": 19248,
"status": "done",
"branch": "claude/issue-19248-duplicate-name-justification",
"pr": "#19352",
"session": "session_01QCdUBjM47SxioST9z5Zwdf",
"premise_still_valid": true,
"summary": "Verified rather than assumed. ADR-0048 §3.4 still exists under that number and retires a RUNTIME throw only, while naming authoring hygiene as what survives; both of the rule's messages, and its docblock, state authoring hygiene and make no runtime claim. VERDICT: no wording change warranted, and none was made — the rule's behaviour, message text and severity are byte-identical. The diff is the record the card asked for: §3.4's two surviving sentences quoted verbatim into the rule's docblock, the card number attached to the standing severity disagreement, plus a patch changeset. The card arrived with an empty assignee field as dispatched; I did not write it.",
"adr_0048_3_4_verbatim": "### 3.4 Per-item cross-package detection retires; same-package overwrite stays\n\nThe original proposal's per-item guard threw MetadataCollisionError whenever\ntwo different packages registered the same (type, name). Under\npackage-scoped resolution that is exactly the case we now support: package\nids are always distinct, so prefer-local always disambiguates two different\npackages — there is no unresolvable cross-package clash to detect. The\ncross-package throw is retired; two distinct packages coexist on the same\nbare name by construction.\n\nWhat remains is the narrow, genuinely-ambiguous case the guard still earns its\nkeep on: a write with no real package provenance (a sys_metadata/runtime\noverlay) is governed by the ADR-0005 overlay precedence (artifact-vs-DB warning,\nunchanged), and same-package re-registration simply overwrites (idempotent\nreload). Authoring-time hygiene — an author shipping two page/home in one\npackage — stays covered by the naming/namespace-prefix lint in os lint.",
"adr_0048_3_4_still_exists": true,
"current_message_text": {
"within_one_owner_lintDocs": "message: Duplicate doc name \"${doc.name}\" (inline defineStack docs and src/docs/*.md files share one namespace).,",
"across_owners_lintDocNamesAcrossOwners": "message: Doc name \"${name}\" is declared by ${labels.join(' and ')}. One artifact may not ship one doc name twice — rename one. Doc names are namespace-prefixed for authoring hygiene, and ADR-0130 D1 lets packages of one artifact SHARE a namespace, so the prefix does not keep these apart.,",
"docblock_pre_existing_disclaimer": "The REASON is authoring hygiene, and deliberately not "one silently overwrites the other at registration". That sentence is this module's older framing and ADR-0048 retired it [...] What survives there is exactly what this is: an authoring-time hygiene lint."
},
"verdict": "The message states a justification ADR-0048 STILL SUPPORTS. §3.4 retires the per-item cross-package runtime throw and nothing else, and in the same clause keeps the class this lint belongs to: authoring-time hygiene. Neither message asserts anything about what the runtime does; the cross-owner message says 'for authoring hygiene' in so many words and the docblock declines the retired sentence by name. The card's recorded expectation is therefore CONFIRMED by measurement, and the correct outcome is to record it, not to edit it. Separately and NOT settled here: the SEVERITY. §3.4 hands authoring hygiene to a warning-only lint while docs/duplicate-name is severity 'error'. That is a question about the level, not the reason, it predates this card, and the docblock already declared it filed rather than changed.",
"tests": "typecheck: pnpm --filter @objectstack/cli typecheck :: exit 0 (tsc --noEmit + check:test-typecheck). tests: pnpm --filter @objectstack/cli exec vitest run --project unit --maxWorkers=2 over collect-docs.test.ts, collect-docs.package-docs.test.ts, lint-namespace-prefix-per-package.test.ts, lint-per-package-authoring-seam.test.ts :: exit 0 — 'Test Files 4 passed (4) / Tests 93 passed (93)'. builds: pnpm --filter '@objectstack/cli^...' build :: exit 0; pnpm --filter @objectstack/cli build :: exit 0. Both via scripts/pm/os-verify-lock.sh (VERDICT command-exit 0). cli integration tier declared to CI — the diff touches no integration-tier file, no bin/ entry and no spawn helper. gates: 53 families derived by scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack from the real change set at 9a0331f; each run with $? captured BEFORE any pipe. 51 exit 0. 2 NOT MEASURED: 'pnpm check:dual-build-cjs-loads' and 'pnpm check:i18n-coverage', both exit 3 = PREREQUISITE NOT MET (they read repo-wide dist/ and this worktree built only the cli closure; their own text says 'This is NOT a pass: nothing was measured'). Reason they are not owed: CI checks out fresh and builds. Reconciled with --ran carrying exit codes: '53 derived familie(s) accounted for — 51 run, 2 NOT-MEASURED (2 DERIVED from a recorded exit 3)', 0 UNRUN. lint: targeted eslint --no-inline-config --format json on the changed source file :: exit 0, 1 file linted, 0 errors, 0 warnings. This is a TARGETED run, NOT the repo-wide 'pnpm lint', which is CI's run. verbatim check: both ADR sentences quoted into the docblock and the changeset were machine-compared against docs/adr/0048-cross-package-metadata-collision.md with whitespace normalised and docblock prefixes stripped — VERDICT verbatim OK. A first attempt dropped the sentence-final period and was caught by that check, not by eye, and fixed before commit. publish measurement (the changeset derivation, not an ablation): @objectstack/cli files[] is [dist, README.md, CHANGELOG.md] and it builds with plain 'tsc -p tsconfig.build.json' (no removeComments), so the comment reaches the tarball. On the rebuilt artifact — new clause in dist/utils/collect-docs.js = 1, replaced spelling anywhere in dist = 0, dist//*.d.ts carrying it = 0 (the block sits above a non-exported helper), positive control (the rule's own runtime message) = 1 in that same file. Published JS bytes move, declaration surface does not. NO ablation was run: the diff changes no executable byte, so there is nothing whose removal could turn a test red — an ablation here would have been theatre. control-byte scan: grep -naP over the changed file, the changeset and the PR body — no matches; pnpm check:nul-bytes :: exit 0.",
"changeset": "patch on @objectstack/cli at .changeset/19248-duplicate-name-justification.md — DERIVED, not guessed, and deliberately NOT skip-changeset. My own standing shortcut treats comments as non-publishing; I measured it FALSE for this package (see the publish measurement above) and followed the measurement. The repo's own precedent is identical in package and situation: .changeset/15295-serve-observability-mirror-comment.md carries a patch for a comment-only change with the same reading recorded. Never major (check-changeset-no-major.mjs), and it ran green.",
"labels_written": "ZERO, by rule. The dispatch named no label and skip-changeset does not apply (a changeset was derived instead), so the write set is empty. scripts/pm/label-write.mjs was not invoked. needs:contract-review is the seat's, untouched — this PR carries none.",
"mcp_calls": "0 — no MCP GitHub tool was called, read or write.",
"api_writes": "2 — POST /repos/objectstack-ai/objectstack/pulls (draft, HTTP 201) and POST /repos//issues/19248/comments (this report). Reads were single-card GETs: issues/19248, issues/comments/5749872407, pulls/19352 (body read-back). Plus 3 git pushes to the feature branch. No PATCH of the PR body — it was written once, on creation.",
"pr_body_readback": "Read back after creation and byte-compared against what was sent: identical except a stripped trailing newline. Footer: exactly 1, session-URL form, correct for a created PR body. 'Fixes #19248' is line 1; 'Clause-②: no' is present at line start, matching the claim. No angle-bracket-shaped fragment and no HTML comment anywhere in the body.",
"docs_prose_sweep": {
"ask": "Coordinator's read-only request: grep content/docs/ and skills/ for the retired 'one registration overwrites the other' claim and for restatements of the rule. Nothing was edited. content/docs/releases/ excluded from every probe.",
"probes_run": [
"duplicate-name",
"one registration",
"overwrit",
"ADR-0048",
"doc name",
"namespace-prefix",
"coexist",
"collision",
"ship one doc name",
"is declared by",
"shadow",
"last one wins",
"last-one-wins",
"silently",
"two packages",
"same bare name",
"duplicate doc",
"fail at install",
"instance-global",
"collide across packages",
"globally-unique",
"one flat"
],
"result": "NOT a clean negative — one page restates the retired justification, and it is a PUBLISHED skill.",
"hits": [
{
"path": "skills/objectstack-ui/rules/pages.md:337-341",
"quote": "2. Namespace-prefixed filename. The filename stem becomes the doc name (^[a-z][a-z0-9_]*$) and must start with the package namespace (crm_…). Names share one flat, instance-global space with the URL, so a bare user_guide would collide across packages and fail at install (ADR-0048).",
"classification": "RESTATES THE RETIRED JUSTIFICATION — and cites ADR-0048 as its authority, the very record that retired it.",
"why": "Three measured errors. (1) 'one flat, instance-global space' is what §3.1/§3.3 replaced: routing keys on the package id and packaged items are stored under a composite package-id-plus-name key. (2) 'would collide across packages' is the retired claim itself — §3.4: two distinct packages coexist on the same bare name by construction. (3) 'fail at install' names the wrong door: the install gate (§3.2) refuses on manifest.namespace ownership, not on a bare doc name — NamespaceConflictError is constructed with a NAMESPACE (new NamespaceConflictError('crm', 'pkg_a', 'pkg_b')). A bare doc name is refused at BUILD by docs/namespace-prefix. This is the worst placement of the three facts, because skills/ is the customer-published catalog an AI author reads while writing docs.",
"note": "skills/ is a Tier H governed surface. Not edited — the coordinator forbade it and the tier reserves the landing anyway. Recommend a card of its own.",
"dedupe_words": "skills/objectstack-ui pages.md · fail at install · instance-global doc names · ADR-0048 §3.4 retired"
}
],
"clean": [
"content/docs/ui/doc-pages.mdx — the prose page that states the rule, and it is ALREADY CORRECT: ':76-82' reads 'It is no longer load-bearing for uniqueness, however: per ADR-0048, doc resolution is package-scoped [...] two installed packages may each ship a doc with the same bare name and coexist — neither silently overwrites the other.' It refutes the retired claim explicitly. This is why the card's optional second surface needed no edit.",
"content/docs/references/system/doc.mdx:18-22 — same corrected framing; AUTO-GEN (references/ is generated from spec describe text), so not hand-editable anyway.",
"content/docs/deployment/validating-metadata.mdx:634 — MERELY NAMES a rule, and a different one: the #17821 intra-package duplicate-name ADVISORY in 'os lint', not the docs/duplicate-name build refusal. States no justification.",
"skills/objectstack-platform/SKILL.md:225 — NAMES THE RULE CORRECTLY: the namespace install gate (§3.2, live) and the non-fatal naming/namespace-prefix warning (§5, [done]). No retired claim.",
"content/docs/permissions/record-view-auditing.mdx:100 — UNRELATED. 'last-one-wins' there is the PLUGIN registry superseding a same-named plugin, a different subsystem from the metadata registry ADR-0048 governs.",
"content/docs/getting-started/examples.mdx:352, 423-426 — UNRELATED to docs; about OBJECT names, and consistent with ADR-0130 D1 co-ownership."
],
"adjacent_observation": "content/docs/references/system/doc.mdx:51 says a doc name's 'namespace prefix recommended, not required', generated from DocSchema.name's describe in packages/spec/src/system/doc.zod.ts:67. The build lint makes it severity 'error' (docs/namespace-prefix). That is a declared-versus-enforced mismatch worth someone's attention, but it is NOT the retired justification and NOT this card — reported, not filed by me."
},
"open_questions": [],
"out_of_scope_findings": [
"to file (dedupe words: collect-docs.ts header docblock · registry key carries no package coordinate · silently overwrites across packages · ADR-0048 §1.1 vs §3.4) — packages/cli/src/utils/collect-docs.ts lines 23-26, the MODULE HEADER, still states the retired claim as the live justification for the naming lints: 'Lint: namespace-prefix naming (doc uniqueness is logical — the metadata registry key carries no package coordinate, so a bare-name collision silently overwrites across packages)'. It near-quotes ADR-0048 §1.1, a CONTEXT heading the ADR's own §3.1/§3.3/§3.4 then overturned. NOT fixed: outside this card's declared file surface (the order fenced it to 'the docs/duplicate-name message and its docblock only', with 'stop on breach'), and it justifies docs/namespace-prefix as well, so correcting it is a judgment about a second rule. The corrected phrasing is already pinned 200 lines below it in the same file, so the fix is mechanical. Successor: the same reviewer thread that opened this card.",
"to file (dedupe words as in docs_prose_sweep.hits[0]) — skills/objectstack-ui/rules/pages.md:337-341, detailed above. Tier H governed surface.",
"noted, not filed: the SEVERITY question — docs/duplicate-name is severity 'error' while ADR-0048 §3.4 assigns authoring hygiene to a warning-only lint. Pre-existing, already declared in the docblock as filed-not-changed, and explicitly excluded by this card's order. Successor: whoever takes the severity card; this PR's docblock now states the boundary so it cannot be re-derived from scratch.",
"noted, not filed: content/docs/references/system/doc.mdx:51 'recommended, not required' versus the error-severity build lint (adjacent_observation above). Successor: none identified — no open PR touches doc.zod.ts's describe text."
],
"deviations": [
"My standing fast-track treats comment-only diffs as non-publishing; I MEASURED that false for @objectstack/cli and followed the measurement into a patch changeset. Flagging the shortcut as wrong for this package rather than silently taking it.",
"The order's file surface and my standing bounded-in-place-fix exemption pointed opposite ways on the module-header finding (same file, same defect class, mechanical, shape already pinned, no competing claim). I obeyed the ORDER's fence and the order's own 'file them, do not fix them here' clause, and am flagging the conflict rather than quietly picking a side. Say the word and it is a two-line follow-up on this branch.",
"My standing three-class filing test does not cleanly admit 'a comment states a retired justification' (it is not a repro, a contract breach, or a metadata-authoring trap), while the dispatch explicitly asked for retired-justification findings to be filed. Reported both findings with dedupe words for triage to classify; I filed no issue myself."
],
"serial_constraint": "Honoured. packages/cli/src/utils/collect-docs.package-docs.test.ts was READ and RUN but NOT edited — #18897 holds it. git diff names exactly 2 paths: packages/cli/src/utils/collect-docs.ts and .changeset/19248-duplicate-name-justification.md."
}

---

Generated by Claude Code

[os-project-manager]

Landing record — #19248 is on main

PR #19352 merged through the queue at 14:12:06Z. Verified by content, ⛔ not by the merge event.

leg	reading
squash commit	d69f7e1ab9649de52ce01e61364fad5173b56342 — the exact sha the queue branch gh-readonly-queue/main/pr-19352-2b3eb17ddd predicted
shape	git rev-list --parents -n 1 = 2 fields ⇒ squash
parent	2b3eb17ddd (PR #19347's landing — this PR was 2nd from the front of a 6-deep chain)
pre-squash head	9a0331f810 is NOT an ancestor of origin/main (lit control: the landing commit is, so the instrument is live)

⚠️ Verified by TEXT, because this diff has no behaviour to verify

packages/cli/src/utils/collect-docs.ts changed 17 added / 2 removed lines, of which 0 are non-comment. There is no executable byte to probe, so a behavioural needle would have been meaningless. The needle is docblock text.

probe	on landing d69f7e1ab9	on parent 2b3eb17ddd
needle — the added ADR quote two distinct packages coexist on the same bare name	1	0
control — and is filed rather than changed here, a line this PR removed	0	1

⭐ This control is the one the #19323 landing lacked. There I picked text that had been added and removed inside that PR's own history, so it read 0 on both sides and discriminated nothing. A control has to be something that existed on the parent — otherwise it cannot fail, and a check that cannot fail is not a check.

⚠️ The shape check was again not a formality: this PR stored auto_merge.merge_method = merge while the repo sets allow_merge_commit: false. It landed at 2 fields. ⇒ the queue's own method governs; ⛔ still check, do not inherit.

The verdict that landed

§3.4 still exists under that number, retires a runtime throw and nothing else, and in the same clause hands the surviving class — authoring-time hygiene — to a lint. Both of the rule's messages already state authoring hygiene, and the docblock already declined the retired sentence by name.

⇒ ⭐ the rule rests on a justification the ADR still supports, so nothing was changed. What shipped is the record the card asked for: §3.4's two surviving sentences quoted verbatim (machine-compared, whitespace-normalised — a first attempt dropped a sentence-final period and was caught by that check, not by eye), plus the card number attached to the standing severity disagreement.

⛔ The severity question stays open and was correctly not settled here: §3.4 assigns authoring hygiene to a warning-only lint while docs/duplicate-name is severity: 'error'. That is about the level, not the reason, it predates this card, and settling it inside a card about a justification is the exact smuggling #19248 was opened to prevent.

⭐ What the round found beyond its own card

A read-only prose sweep was commissioned after the docs-drift check disclaimed coverage of this file ("1 changed file yielded no anchor … this is not a clean bill of health"). The seat predicted a clean negative. ⛔ It was wrong — two surfaces still carry the retired claim, both filed:

• [finding] a published skill teaches the ADR-0048 claim ADR-0048 retired — and cites ADR-0048 as its authority #19358 — skills/objectstack-ui/rules/pages.md teaches that a bare doc name "would collide across packages and fail at install" and cites ADR-0048 as its authority, the record that retired it. Tier H, customer-published catalog.
• [finding] collect-docs.ts's module header states the retired ADR-0048 claim as the live justification — the same file declines that sentence 900 lines below #19359 — this file's own module header states the retired claim as live, while line 929 of the same file declines that sentence by name.

⇒ ⛔ a negative result asserted from expectation is not a measurement. The sweep was worth running precisely because it came back positive.

Card state

pm:dispatched stripped and the assignee cleared in one write, read back: labels documentation, domain:cli, priority:p3 · assignees none.

---

Generated by Claude Code