docs(adr): annotate ADR-0046 §3.2's retired overwrite premise

[huangyiirene]

Fixes #19408

维护者速读(草稿)

改了什么 — 给 ADR-0046 加了一条超越注记,没有改写它的正文。状态行后面多一行:说明 §3.2 的「同名文档互相覆盖」前提已被 ADR-0048 取代;§3.2 末尾多一段引用块(本文件自己的 amendment 体例),指向 ADR-0048 的 §1.2 / §3.4 / §3.3。共 +8 行,只动这一个文件,§3.2 原文一字未动。

为什么改 — §3.2 那句「注册表键是 org/type/name,没有包坐标,所以两个包发同名文档会静默互相覆盖(last-write-wins)」是前提加结论的一整条推理,ADR-0048 已把它推翻:写入侧本来就是复合键(§1.2),§3.4 退役了跨包抛错,真正的残留是读侧的无上下文首个匹配,由 §3.3 的包内优先解析修掉。这段话已经繁殖出两处下游文案(#19359 的 collect-docs.ts 头注释、#19358 的 skills/objectstack-ui/rules/pages.md),两处都已在 main 上改正、卡也已关闭;源头不注记,它还能长出第三处。

风险与代价(含回滚) — 纯文档改动:不发布任何包(70 个带 files[] 的 package.json 里零条目涉及 docs/adr,docs/adr 也不在任何包根之内),不改行为,不改门禁,19 个派生门禁族全绿。唯一的判断风险在措辞:注记声称「§3.2 规定的 build/publish lint 仍然成立,只是它依据的理由换了 —— 靠的是作者侧卫生和扁平链接命名空间,不是覆盖」,这与已落地的 collect-docs.ts 更正读法一致。回滚 = revert 本 PR 的单个 commit,ADR 回到未注记状态,无其它后果。

席位意见 —— 技能席 1(session_01Wnstp2kTth7sGXfr8fXypc)已按 GitHub 与拉取的 head 0cba6186d 复核:一个文件 +8/−0;第 3 行(带日期的状态行)逐字节未动,第 4 行追加的 superseded 子句 96 字符,§3.2 末尾六行引用块每行 78–87 字符;注记对 ADR-0048 §1.2 / §3.4 / §3.3 的四处引用本席逐一在 ADR-0048 原文核对无误,末句与 origin/main 上 collect-docs.ts(#19359)已落地的读法一致;被退役的原句仍在文件中出现恰好一次——是注记,不是改写,正是卡上 Path: 行与车道评级 5752868774 认可的形式。体例在树内有先例(ADR-0012 状态行的内联 · **Superseded by …**、ADR-0053 的「Partly superseded」、本文件 §6.7 自己的 amendment 引用块)。本席在独立 worktree 复跑 ADR 链接 / 锚点 / doc-authoring / nul-bytes 等七个门禁均 exit 0;check-governed-merges --pr 19702 读 GOVERNED、Tier H(docs/adr/**);CI 31 项全绿。复核记录 PASS 5774341677(席内 fable),ACCEPT 5774422000 在卡上。建议合并。卡上那张下游表已过时但方向对本卡有利:两处下游副本都已在 main 修正并关卡,本 ADR 是该退役论断的最后一个载体。

你要做的 — 先判断卡片 First act 的那个治理问题:一段已被取代的文字,该不该在既有的日期记录里加注记。认可就合并(docs/adr/** 是 Tier H,由你的手落地);若你认为 ADR 是不可改写的日期记录、ADR-0048 存在本身已经够了,那就关掉这个 PR 并把该裁决记在卡上 —— 按卡片自己的说法,那同样是一个完整结果,不是失败。

---

What changed

Two additions to docs/adr/0046-package-docs-as-metadata.md, +8 physical lines, nothing removed:

1. Status line (line 4) — one appended clause. The dated line 3 is byte-identical to what it was; the clause continues the same header paragraph, the way ADR-0048's own status line wraps across three physical lines:

   · **Superseded in part (2026-06-13, ADR-0048)** — the bare-name overwrite premise; note at §3.2.

2. A note closing §3.2 (lines 159-164) — a blockquote in the file's own amendment style, naming what §3.2 claimed, what retired it, and where the current truth lives:

   Superseded in part (2026-06-13) — the bare-name overwrite premise above.
   ADR-0048 measured the write as already
   composite-keyed (packageId:name) in its §1.2, so two packages on one bare name do
   not overwrite each other, and its §3.4 retires the cross-package throw. The residual
   is a context-free read, repaired by its §3.3 (package-scoped, prefer-local); the
   lint above stands on authoring hygiene and the flat link namespace, not on overwrite.

§3.2's own text — the claim, the lint it prescribes, the bullet list — is untouched. This is the form Prime Directive #13 names ("a new ADR, or an amended status line on the old one") and the form the lane's grading named: an amended status line plus a one-line pointer at §3.2, ⛔ not a rewrite of a dated record.

The form, measured rather than assumed

• Note style — ADR-0046 already carries its own amendment: a blockquote with a bold lead-in at §6.7 (> **Amendment (…)**.), plus a second blockquote emphasis block in §4. The note here is that shape. It is not ADR-0090's [ruled] form, because this file has its own.
• Placement — that existing amendment sits inside its section, immediately after the prose it amends, with more prose following. The §3.2 claim lives in the first bullet of a six-bullet list, so a block between bullets would split the list; the note therefore closes §3.2, after the "TS-first stacks" sentence and before ### 3.3. Every section reference inside it is spelled "its §N" so it reads against ADR-0048, never against ADR-0046's own §3.3 that follows two lines later.
• Wrap — the added blockquote lines measure 78-87 columns, against the 77-85 of the file's existing amendment block; the status-line clause is 96. All are under the 100-column budget this card was dispatched with.
• Budget — git diff --stat: 1 file changed, 8 insertions(+), against a ceiling of +8.

Gates

Derived, not recalled: node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands (no paths) at 0cba6186d — 19 families, all run, exit captured before any pipe.

family	exit	verdict line
node scripts/check-adr-links.mjs (+ --self-test)	0	check-adr-links: 690 relative link destination(s) under docs/adr/ resolve
node scripts/check-adr-symbol-anchors.mjs (+ --self-test)	0	2121 anchors across 140 records resolve
pnpm check:adr-anchors	0	106 assertions over the real auditAdrDirectory() / auditCitedNumbers() / assembleAnchors() paths
pnpm check:doc-authoring	0	44 published skill files clean; 16120 customer-facing string(s) across 1031 spec sources clean
pnpm check:nul-bytes	0	OK (scanned 9205 text file(s) … no raw ASCII control bytes)
pnpm check:pm-governed-merges	0	self-test 441 assertions; live: generator declared 9 output(s) and certified this tree
pnpm check:pm-prior-rulings	0	155 cases pass
pnpm --filter @objectstack/lint run check:doc-formula-expressions	0	first run exited 3 — PREREQUISITE NOT MET (unbuilt @objectstack/formula / @objectstack/lint), i.e. NOT MEASURED, not a finding; re-run 0 after turbo run build --filter=@objectstack/formula --filter=@objectstack/lint
the other 8 (check-ci-filter-parity, check-closing-keyword-parity ×2, check-comment-mask-corpus, check:cross-package-test-inputs, check:driver-memory-census, check:gitlink-declared, check:refd-timer-probe, check:watch-hint-literal)	0	—

Reconciled: dispatch-gates --ran → 19 derived famil(ies) accounted for — 19 run, 0 NOT-MEASURED (a DERIVED zero — all 19 recorded an exit code and none of them is 3).

Also swept by hand, outside the gate: grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]' over the edited file — no match.

skip-changeset: measured, not assumed. 70 package.json files declare files[]; 0 entries name docs/adr or escape their package root, and 0 package roots contain docs/adr. The diff ships in no tarball.

Governed-merge reading on this PR is reported in the card's os-dev-report comment (check-governed-merges.mjs --pr): Tier H, the maintainer's merge. The PR stays draft.

Acceptance notes

• The card's downstream table is stale, in the direction that strengthens it. It lists packages/cli/src/utils/collect-docs.ts ([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) as repaired and skills/objectstack-ui/rules/pages.md ([finding] a published skill teaches the ADR-0048 claim ADR-0048 retired — and cites ADR-0048 as its authority #19358) as open. On 7e1b048a1d both are repaired and both cards are closed as completed: collect-docs.ts:38-44 now declines the sentence by name, and pages.md:340-341 reads "hygiene, not uniqueness: two packages coexist on one bare name (ADR-0048 §3.4)". So this ADR is the last carrier of the retired claim in the tree, not one of three. Observation only — no card.
• ADR-0046's status stays Proposed. Whether that line should also move is a separate governance question this PR deliberately does not answer.

---

Generated by Claude Code

---

Generated by Claude Code

[huangyiirene]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 0cba6186d7dd67acca0b5695b728bf3291e34fc6

① Derived judgments

Rendered in-seat by the skills seat 1 session at the served tier the maintainer named on this date (the fable tier word at get_session → external_metadata.last_served_model; ruling record 5771798588; the constant on origin/main names it since PR #19684). The contract is the card's Path: line and the lane's grading 5752868774: the sanctioned form is an amended status line / supersession note on ADR-0046 §3.2, ⛔ not a rewrite of a dated record; Tier H on the register.

• (a) The diff is an annotation, not a rewrite — right, measured. git diff origin/main...0cba6186d is docs/adr/0046-package-docs-as-metadata.md +8 / −0, one commit on the branch, merge base 7e1b048a1 = origin/main at the seat's fetch. Line 3 (the dated **Status** line) is byte-identical; line 4 appends one clause 「· Superseded in part (2026-06-13, ADR-0048) — the bare-name overwrite premise; note at §3.2.」 (96 characters); §3.2 closes with a six-line blockquote (78–87 characters per line) after the 「TS-first stacks …」 sentence and before ### 3.3. The retired sentence itself (「silently overwrite each other」) is still in the file exactly once — the record is annotated, its text untouched.
• (b) Every claim the note makes is in ADR-0048 where the note says — read by this seat, not the report. §1.2 (「The silence is in the read, not the write」) shows storageKey = packageId ? \${packageId}:${baseName}` : baseNameand says two packages 「do **not** overwrite one map entry」; its root-cause line is 「context-free resolution + a missing package coordinate in the address — not a write conflict」. §3.3 is headed 「Resolution is package-scoped (prefer-local, qualify-to-cross)」. §3.4 reads 「The cross-package **throw is retired**」. The note's last clause — the lint stands on authoring hygiene and the flat link namespace — is the reading already landed onorigin/maininpackages/cli/src/utils/collect-docs.ts(#19359):docs/duplicate-namerests on authoring hygiene (the class ADR-0048 §3.4 keeps),docs/namespace-prefix/docs/namespace-requiredrest on the flat link namespace. The date 2026-06-13 is ADR-0048's ownStatus: Revised (2026-06-13)`.
• (c) House form — right, with precedent in the tree. An inline supersession clause on a status line: ADR-0012 :3 「… · Superseded by ADR-0030 (2026-06-01) — …」; the 「in part」 wording: ADR-0053 :3 「Partly superseded (2026-07-29, …):」. A blockquote amendment inside the section it amends: ADR-0046's own §6.7 (> **Amendment (framework#3963).**). The clause opens with ·, the separator ADR-0012 uses, so it reads the same whether the renderer keeps the soft break or folds it.
• (d) Placement — argued and right. The claim sits in bullet 1 of a six-bullet list; a block between bullets would split the list, so the note closes the section. Every section reference in the note is spelled 「its §N」, so nothing reads against ADR-0046's own ### 3.3 two lines below.
• (e) The dispatch's constraints — met. Net +8 against a ceiling of +8; every added line ≤ 100 characters; ⛔ nothing outside this one file; H1 evidence given (the claim verbatim at :139–:144 on the base, ADR-0048 named only at :335 / :525, no supersession note); 19 gate families derived at this head, all run, --ran reconciled 0 NOT-MEASURED. Re-run by this seat on a clean worktree at 0cba6186d after pnpm install --frozen-lockfile --offline: check-adr-links, check-adr-symbol-anchors, check:adr-anchors, check:doc-authoring, check:nul-bytes, check:pm-prior-rulings, check-closing-keyword-parity — all exit 0; a raw-control-byte sweep of the edited file finds none; check-governed-merges.mjs --pr 19702 exit 3 — GOVERNED, Tier H, docs/adr/** ×1, 8 lines. check:doc-formula-expressions exit 0 is the dev's reading after its prerequisite build (⛔ not re-measured by the seat).
• (f) No index to update. docs/adr/PRIORITIZATION.md names 0046 nowhere; the link and anchor gates above cover the new relative link.
• (g) Out of scope, recorded, not filed. The card's downstream table is stale in the direction that strengthens the card: both copies it names are repaired on origin/main ([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 in collect-docs.ts; [finding] a published skill teaches the ADR-0048 claim ADR-0048 retired — and cites ADR-0048 as its authority #19358 in skills/objectstack-ui/rules/pages.md :340–:341 「hygiene, not uniqueness: two packages coexist on one bare name (ADR-0048 §3.4)」), so this ADR was the last carrier of the retired claim. Neither file is touched here.

② Semver level

None — no release. docs/adr/** is in no package's files[] (the dev measured 70 declaring packages, 0 entries; this seat's check-governed-merges reads the same register). skip-changeset is the correct carrier, written through label-write.mjs with read-back; documentation and size/xs are the labelers'.

③ Boundary flags

• Tier H — the PR stays draft for the maintainer's hand (landing-operations.md :28); ⛔ no ready, no queue, no auto-merge by the seat.
• CI at this head was in progress at the seat's read (Lint & Repo Gates, Test Core (1/6), two type-check lanes); the ACCEPT follows only on all green.
• A build ran for a docs-only diff (@objectstack/formula + @objectstack/lint, through the shared verify lock) solely to clear check:doc-formula-expressions' declared prerequisite — declared, harmless.
• Body-byte mutation on the POST /pulls: GitHub dropped the blank line before the footer and the trailing newline; read-back otherwise identical, reported. The dev made ⛔ no PATCH of the PR body; the seat will make one — filling the body's empty 「席位意见」 section — announced here.
• Report 5774268707 on the card parses; mcp_calls 0; three REST writes plus two pushes, as budgeted.

Implemented-by: claude/issue-19408-adr-0046-3-2-supersession-note
Reviewed-by: session_01Wnstp2kTth7sGXfr8fXypc

VERDICT: PASS

---

Generated by Claude Code