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

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](./0048-cross-package-metadata-collision.md) 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`
(#19359) as repaired and `skills/objectstack-ui/rules/pages.md` (#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](https://claude.ai/code/session_01Wnstp2kTth7sGXfr8fXypc)_

---
_Generated by [Claude Code](https://claude.ai/code)_

Co-authored-by: Claude <noreply@anthropic.com>

Author: huangyiirene

docs/adr/0046-package-docs-as-metadata.md

@@ -1,6 +1,7 @@
 # ADR-0046: Package documentation as metadata — flat `src/docs/*.md` compiled into the manifest
 
 **Status**: Proposed (2026-06-12, revised — simplified from the original directory/docSet design)
+· **Superseded in part (2026-06-13, ADR-0048)** — the bare-name overwrite premise; note at §3.2.
 **Deciders**: ObjectStack Protocol Architects
 **Builds on**: [ADR-0003](./0003-package-as-first-class-citizen.md) (package + versioned releases), [ADR-0016](./0016-studio-package-authoring-and-publish.md) (publish pipeline, `manifest_json` snapshot), [ADR-0025](./0025-plugin-package-distribution.md) (artifact distribution, trust boundary), [ADR-0033](./0033-ai-assisted-metadata-authoring.md) (AI as primary author)
 **Consumers**: `@objectstack/spec` (`DocSchema`, stack `docs` element), `@objectstack/cli` (collection, publish lint), `@objectstack/console` (doc rendering route), cloud control plane (registry rendering, grants), `@objectstack/core` (kernel registers `doc` as inert metadata)
@@ -155,6 +156,13 @@ unbounded, and manifest-size pressure lands here first.
 TS-first stacks may also pass `docs: [...]` inline in `defineStack()`;
 the md-file convention is sugar over the same array.
 
+> **Superseded in part (2026-06-13) — the bare-name overwrite premise above.**
+> [ADR-0048](./0048-cross-package-metadata-collision.md) 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.3 Cross-references
 
 Docs link to each other with plain relative Markdown links: