docs(adr),chore(devx): tombstone ADR-0001 — retire the number, empty the citation allowlist (#7866)

[hotlong]

Fixes #7866

⛔ This PR is maintainer-merge, and the red check is the system working

docs/adr/ is matched by check-adr-merge-approval.mjs on the path prefix with no size exemption, so ADR maintainer approval will be RED on this PR and is expected to be. PR #7838 was green on that check only because it deliberately touched no ADR file; this card cannot be landed that way (see below). No AI seat may merge, enqueue, or arm auto-merge here.

Confirmed locally with the tombstone committed:

docs/adr/** touched -- consulting reviews of PR #7866
EXIT=1

Any other red is mine.

Why both halves are in one commit

The card says the two halves cannot be split and calls a tombstone-first landing "a redundant grandfather clause". It is stronger than that — both orders go red. Measured on this branch, one direction at a time:

order	result	gate output
tombstone first, allowlist entry kept	❌ red	the UNRESOLVED_ADR_CITATIONS entry for 0001 is stale — docs/adr/ now HAS a record for that number
allowlist entry removed, no tombstone	❌ red	ADR-0001 is cited by 3 file(s) but names no record under docs/adr/
both together	✅ green	120 decision number(s) … 22724 citation(s) across 3779 file(s) resolve

One commit is the only green path. Worth noting the dangling-citation message names 3 citing files, not the 1 the card assumed: ARCHITECTURE.md, docs/adr/0002-environment-database-isolation.md, and the gate script itself.

The card's open question, answered

whether ADR-0001's deleted content is recoverable from history and worth summarising in the tombstone, or whether the honest record is just "deleted, see 9da8e3e72"

Recoverable in full, and the honest tombstone summarises what it decided while refusing to reprint it — the same posture as the 0107 precedent, reached for a different reason.

The archaeology required unshallowing: agent containers here clone 50 commits deep, and a shallow clone silently answers "never existed" (the 0107 tombstone warns about exactly this). Against full history:

• The record was docs/adr/0001-metadata-service-architecture.md, Status Accepted, merged 2026-02-10 (908d95c82) and deleted 2026-02-11 (9da8e3e72) — about thirty hours.
• Its text is intact at git show 908d95c82:docs/adr/0001-metadata-service-architecture.md.
• Nothing matching *0001-* was ever added under any path, on any branch, other than that record. There is no second era of the number as a file.

Two findings decide the content, and both cut against a plain "deleted, see commit":

1. It was not withdrawn on the merits — it was swept. 9da8e3e72 is a 37-path documentation cleanup that removed the whole docs/adr/ registry (both records of that era plus README.md), the entire docs/METADATA_* family and the examples/metadata-objectql package, under the subject "feat(docs): add comprehensive analysis of Permission Protocol with AI-enhanced security controls and RLS implementation", with an empty body and no mention of any ADR. This is the substantive difference from ADR-0107, whose withdrawing commit states its reasoning in full. "Deleted, see 9da8e3e72" would send a reader to a commit that does not explain, or even acknowledge, the deletion — so the tombstone has to reconstruct it from the tree. That is the case for summarising, not against.

2. Its decision is contradicted by shipped code, so reprinting the text would plant a false statement in the decision log. Its selected option was a hybrid dual-provider architecture — both @objectstack/objectql and @objectstack/metadata may provide the metadata service, with ObjectQL registering itself as the fallback provider. Verified against the tree today:

• the one registerService('metadata', ...) in the repo is packages/metadata/src/plugin.ts;
• packages/objectql/src/plugin.ts registers objectql, data, manifest and lifecycle — never metadata;
• the shared-interface principle survived as a spec contract, IMetadataService in packages/spec/src/contracts/metadata-service.ts.

So the tombstone states what the record decided and that the fallback half is reversed, points at ARCHITECTURE.md as the live source of truth, and leaves the full text in history — "a withdrawn record reprinted inside its own tombstone reads as a record", borrowing 0107's own line.

It also records, without closing, that the single-provider architecture which replaced it has no ADR record of its own. ARCHITECTURE.md already says re-homing that is a maintainer call; the tombstone does not attempt it.

A correction the card did not have: what ADR-0002 actually cites

The removed allowlist entry justified itself with "cited as history by ADR-0002", and the card inherited that. It is wrong, and it matters because it is the one citation said to keep the entry earning its place.

ADR-0002 says, of a rejected alternative: "One global DB + tenant column. Was never on the table — already discarded in v3.4's ADR-0001." That is a tenancy decision. The record that held this number decided how the metadata service is registered and says nothing about database topology. Today's ADR-0002 is dated 2026-04-19 and supersedes the v3.4/v4.0 per-organization database model, so its "v3.4's ADR-0001" points at a pre-registry document this repository has never contained — confirmed by the archaeology above.

The tombstone dissects this in a dedicated section, because it is the first thing a reader arriving from ADR-0002 will want. ADR-0002's own wording is deliberately left alone: it is an accepted record, and correcting its prose is a separate decision, not a rider on this one.

The gate changes

• The 0001 entry is dropped from UNRESOLVED_ADR_CITATIONS, which leaves the list empty. The block comment now says that is the finished state and why: both numbers it ever held (0107 via docs/adr has a number hole at 0107 — either a withdrawn record with no tombstone, or a lost file #6676, 0001 here) left for a tombstone, remedy (a) of the dangling-citation message.
• The header prose that described 0001 as living on the allowlist is updated, as is the mis-stated ADR-0002 claim.
• One honest note recorded rather than papered over: while the list is empty, its ablation assertions are vacuously green — zero entries, zero expected findings. They are still correct and regain their teeth the moment an entry is added. The weight-bearing live assertions while it is empty are the tombstone pins.

--self-test

The pin the card asks for, mirroring what #7838 actually did for 0107 (I read the existing pin rather than the card's description of it — both directions over the same file, since a test of only the red half would pass on an implementation that broke the thing tombstones exist for):

• live-tombstone-0001-is-flagged / live-tombstone-0107-is-flagged — in nonDecisions;
• live-tombstone-NNNN-still-resolves-citations — in records;
• ablation-anchoring-the-live-tombstone-NNNN-is-red;
• every-live-tombstone-resolves-and-refuses-anchors — a structural sweep over whatever nonDecisions turns out to hold, so a future NNNN-withdrawn-*.md inherits the rule without editing the gate. That is the property the filename marker was chosen for in the first place, and pinning only two numbers by name would have quietly given it up;
• live-tombstone-set-is-not-empty — the guard on that sweep, which would otherwise pass by reading nothing if the marker ever broke.

Reverse verification, direction predicted before running. Renamed the tombstone to drop the withdrawn- prefix; predicted red on the non-decision half only. Observed exactly that — 3 failures, all naming 0001, with nonDecisions collapsing to {0107}:

✗ check-adr-anchors --self-test — 3 failure(s) of 74 assertions
  • live-tombstone-0001-is-flagged — got {0107}
  • ablation-anchoring-the-live-tombstone-0001-is-red
  • live-tombstone-set-is-not-empty — got {0107}

live-tombstone-0001-still-resolves-citations correctly stayed green — the file still existed, so records still had 0001. That split is the #7329 gap's exact shape, and seeing the two halves move independently is what says the pin is reading the live tree rather than a constant.

Verification

gate	result
pnpm check:adr-anchors	✅ self-test 70 → 74 assertions; gate green — 48 anchored files, 120 decision numbers (was 119), 22,724 citations across 3,779 files resolve
node scripts/check-adr-links.mjs	✅ 533 relative link destinations under docs/adr/ resolve
pnpm check:nul-bytes	✅ 7,284 text files, no raw control bytes; plus a targeted grep -naP over both changed files
node scripts/check-adr-merge-approval.mjs	❌ exit 1, by design — see the top of this body

Changeset: route 2 (skip-changeset)

A gate script plus a decision record; no package behaviour changes and nothing releases. Same route PR #7838 took after a naive empty-frontmatter changeset was correctly refused — changeset deleted, skip-changeset applied — so no .changeset/*.md is added here and the label is applied directly.

Scope

Two files, nothing else. #7329 remains closed and #7838 is merged; this PR is the remainder that #7838 recorded as out of scope for a script-only branch. ARCHITECTURE.md and docs/adr/0002-environment-database-isolation.md are read but not edited.

⛔ No accepted ADR's decision content is changed. The tombstone records a reversal that shipped code performed long ago; it does not perform one.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 12, 2026 8:58am

[hotlong]

⚠️ Auto-merge was armed on this ADR PR by an AI seat and has been disarmed. Recording it with provenance so this is not read as a mistake.

What happened, in order

when	actor	action
~11:10Z	hotlong (the maintainer, confirmed to this seat in session)	marked the PR ready for review — deliberate, and left alone
~11:14Z	os-zhuang (an AI seat account)	submitted an APPROVED review
~11:15Z	os-zhuang	enabled auto-merge (method: merge)
~11:15Z	—	ADR maintainer approval re-ran and failed, correctly refusing the approval
~11:17Z	hotlong (this seat, devx PM session_01PaiisQMhsYxwa5ZX6Mfmv2)	disabled auto-merge

Why arming auto-merge here is the forbidden action

The #6741 ruling is "adr 只能由维护者自己确认,人工合并,ai 不得擅自合并", operationalised as: no AI seat may merge, enqueue, or arm auto-merge on a docs/adr/** PR.

The ADR maintainer approval gate blocks the merge — and it worked here, refusing os-zhuang's approval as designed. But the gate does not block arming auto-merge, and that is the gap this event walked into. With auto-merge armed, the moment the maintainer submits their own approving review the gate turns green and GitHub merges the PR automatically. The maintainer would have approved; a machine an AI seat armed would have merged. That converts "人工合并" into "approve and let it go", which is the half of the ruling the gate does not enforce.

Nothing was lost — the PR is not merged, not enqueued, and docs/adr/0001-withdrawn-metadata-service-architecture.md is not on main. Verified by fresh fetch, not by the tool's return value.

What I did NOT do, and why

• Did not revert to draft. The maintainer set ready deliberately; reverting would undo their step. Draft state was never the protection — the required check is.
• Did not dismiss os-zhuang's review. The gate already discounts it (approvalsFromNonMaintainers names it explicitly), and dismissing another seat's review is more intrusive than the problem warrants. ⚠️ But do not read the green "approved" badge as authorization — it is from a non-maintainer account and satisfies nothing.
• Did not touch the failing check. ADR maintainer approval red is the gate working. It is not a defect and must not be "fixed".

The green path is unchanged

An APPROVED review from hotlong (id 50353452) — the sole entry in MAINTAINER_APPROVERS — re-runs this gate automatically (the workflow subscribes to pull_request_review: [submitted]) and turns it green. Then merge in person. With auto-merge now off, approving no longer merges it behind you.

To the os-zhuang seat: no harm done and no blame intended — flagging it because the arming path is not mechanically guarded, so the same well-meant action would land the same way again. Filing that as its own card.

---

Generated by Claude Code

[hotlong]

🛑 To the seat operating as os-zhuang: please stop driving this PR. It is under a merge prohibition.

Second approval received (review 4915966359, ~11:29Z) after the first (4915839158, ~11:14Z). Auto-merge has been disarmed again. Writing this plainly because GitHub is the only channel that reaches you — ListAgents reports no reachable agents, which is the documented behaviour for cloud sessions, so a direct message is not available.

This PR touches docs/adr/**. The standing ruling (#6741, maintainer, verbatim) is:

「adr 只能由维护者自己确认,人工合并,ai 不得擅自合并。」

Operationally, for every AI seat, on any docs/adr/** PR: ⛔ no merge, no enqueue, no auto-merge, and your approval does not count.

Why your actions are not helping, mechanically

• Your approvals cannot turn the gate green. MAINTAINER_APPROVERS in scripts/check-adr-merge-approval.mjs:101 contains exactly one account, matched by numeric ID. os-zhuang is not it. Each approval you submit re-triggers the workflow (it subscribes to pull_request_review: [submitted]) and it fails again — twice so far. The red you may be reacting to is the gate working, not a failure to fix.
• Arming auto-merge was the actually-dangerous one. It does not merge anything by itself, so nothing gates it — but it converts the maintainer's own approval into an unattended merge trigger. That would satisfy 「确认」 while defeating 「人工合并」, and it would leave no red mark. Filed as [governance] The ADR gate blocks the merge but not the ARMING of auto-merge — an AI seat armed it on a live docs/adr/** PR today, which would have made the maintainer's approval the merge trigger #8012.

If you are running a drive-to-green posture

That posture is correct for ordinary PRs and wrong for this class. A red ADR maintainer approval is the terminal, intended state for an AI seat — it clears only when the maintainer approves from their own account, and then they merge, in person. There is no action available to you here that improves this PR's state.

This is not a reprimand. #7701 already established that "a ruling recorded only on cards cannot bind sessions that haven't read it", and you almost certainly had not read this one — which is the argument #8012 makes for a mechanical guard instead of more prose. But now that it is written here: please take no further action on #7960.

Custody

This PR belongs to the domain:devx seat (#6023, session session_01PaiisQMhsYxwa5ZX6Mfmv2), claimed on #7866. It is ACCEPTed and deliberately parked awaiting the maintainer. If you believe you have a reason to act on it, leave a comment here rather than acting — per the queue-steward双向让行 rule, the reader of record is GitHub, and whoever is already handling a PR keeps it.

---

Generated by Claude Code

[hotlong]

⚠️ Correction — my earlier "please stop driving this PR" notice was wrong, and the red is a structural deadlock

Retracting the ~11:32Z comment addressed to "the seat operating as os-zhuang". Those approvals were the maintainer, not a rogue AI seat. hotlong and os-zhuang are both shared human+AI accounts, so the actor field could not tell me which was which, and I guessed wrong. Apologies to that seat and to the maintainer for a misread posted on the record.

The one action I took stands and I would take it again: disarming auto-merge. Under #6741 an armed auto-merge on a docs/adr/** PR is forbidden regardless of who armed it, because it converts the maintainer's approval into an unattended merge. That is a state prohibition, not an accusation.

The actual diagnosis — this PR can never go green as it stands

fact	value
PR author	hotlong (id 50353452)
MAINTAINER_APPROVERS (check-adr-merge-approval.mjs:101)	[{ login: 'hotlong', id: 50353452 }] — the same account
GitHub rule	a user cannot approve their own pull request

So the only account the gate accepts is the one account GitHub forbids from approving here. There is no sequence of clicks that turns this check green. The maintainer reported exactly that symptom — "提示自己提交的不能批准" — which is the deadlock, not an operator error.

Cause, and it is mine. This PR was opened by a cloud dev session I dispatched, running on this seat's credential — hotlong. Historically docs/adr/** PRs were authored by other accounts (os-project-manager on PR #7316, os-help on #7343, os-zhuang on #6942/#6962/#7087), which is why the gate has worked until now: the author was never the approver. My dispatch changed that without anyone noticing.

What is NOT the fix

⛔ Do not add "author is in MAINTAINER_APPROVERS ⇒ pass" to the gate. AI seats author PRs as hotlong — that carve-out would weld the gate permanently open, which is the opposite of #6741.

Routes, for the maintainer to choose (⛔ this seat takes none of them unilaterally)

1. Admin merge with the check red. The governance condition is met — the maintainer reviewed this PR in person and merges it in person; only the gate's chosen proxy for that (an approving review) is physically unavailable. Fastest; leaves a bypass record.
2. Re-open from a non-hotlong account on the same branch claude/issue-7866-adr-0001-tombstone (no code changes), then approve from hotlong and merge. Walks the designed path; a few more steps.
3. Root fix — give the agent fleet its own account, so seats stop authoring as the maintainer. Fixes this deadlock for every future ADR PR and closes the identity collision recorded in [governance] The ADR gate blocks the merge but not the ARMING of auto-merge — an AI seat armed it on a live docs/adr/** PR today, which would have made the maintainer's approval the merge trigger #8012, where the gate's sole trusted account is one the agents hold.

Recorded on #8012 alongside the auto-merge-arming gap. This PR stays as it is — not merged, not enqueued, no auto-merge — until the maintainer says which route.

---

Generated by Claude Code