Skip to content

Published docs tell customers that admin-door edits of a packaged permission set are "no longer refused" — they 403; ADR-0094's 2026-07-14 direction was retired 2026-08-09 #8292

Description

@os-zhuang

Found while implementing #7351 (PRs #8290 / #8291), by re-running that card's own six-phrase sweep on a current ref. Outside #7351's three-file surface, so deliberately not fixed there. Filed unassigned, no domain:* label — routing and grading are the triage seat's call. content/docs/** is not the domain:cli lane, which is why this seat is filing rather than dispatching it.

The measurement

ADR-0094's 2026-07-14 direction — an env-scope overlay is the standard ADR-0005 customization of a packaged permission set, and deleting the overlay resets the row to the shipped declaration — was retired on 2026-08-09 by D5-R (#6858 / PR #6962), after #6483 / PR #6608 rolled permission back to allowOrgOverride: false. The admin-door edit now answers 403 not_overridable.

content/docs/permissions/authorization.mdx:231-234 still states the retired direction as current, in the present tense, to customers:

admin-door edits of a packaged set are no longer refused: the ADR-0094 write-through translates them into the standard ADR-0005 env-scope overlay — the record projects the effective body while the package keeps owning the row, and "delete" resets to the shipped declaration.

That is not merely stale — it is inverted. It tells a reader the edit succeeds; the platform refuses it.

Verified on origin/main at filing time, not taken from the finder's report:

$ git grep -n -A3 "no longer refused" origin/main -- content/docs/permissions/authorization.mdx
231:  admin-door **edits of a packaged set are no longer refused**: the ADR-0094
232-  write-through translates them into the standard ADR-0005 env-scope
233-  **overlay** — the record projects the effective body while the package keeps
...
$ git grep -c "RETIRED 2026-08-09" origin/main -- docs/adr/0094-sys-permission-set-pure-projection.md
1

The second command is the control: the direction really is retired, so the docs claim is genuinely wrong rather than a misreading of an unsettled question.

The finder also reports a looser sibling bullet in the same file (~:222), "Deleting an artifact-backed set through this door resets it to its declared body". ⚠️ I could not confirm that one with my own grep — my pattern did not match, and I am recording the gap rather than passing it on as verified. Whoever picks this up should re-locate it by text.

Second site, same defect class

docs/adr/0086-authz-metadata-config-boundary-and-cross-package-composition.md:400-403 carries a live-voiced, present-tense pointer at the retired D5:

ADR-0094 D5 (revised 2026-07-14) makes an environment overlay of a package-owned set a first-class ADR-0005 customization (overlay-wins … a data-door "delete" is an overlay reset to the shipped declaration)

Confirmed present on origin/main (git grep -n "revised 2026-07-14" -- docs/adr/0086-*). This is the same defect #7351 fixed inside ADR-0094's D2, one ADR over.

⚠️ That second site is under docs/adr/**, so fixing it is a maintainer-merged PR. If both sites are taken as one card, it must ship as two PRs — a mixed diff routes the whole thing to maintainer-only landing and would hold the customer-facing fix hostage to a human merge it does not need. #7351 has just been through exactly this split (#8290 normal path, #8291 maintainer-merged); reuse that shape.

Why this is graded higher than the card that found it

#7351's three sites were internal prose whose harm was bounded — two test headers contradicted by their own passing bodies, and an ADR parenthetical pointing at a section whose title already said RETIRED. This one is published, customer-facing, and inverted: a reader following it expects an edit to work and gets a 403, with the docs offering no hint that the supported channel is "edit the package and re-publish" (ADR-0086 two-doors). Severity is triage's to set, but the inputs differ in kind from #7351's, not just in degree.

Dedup

The finder searched open issues by keyword and by path; nothing covers authorization.mdx (#8165 is a different docs-currency card). Related and already handled, listed so the sweep is reproducible: PR #7346 swept packages/plugins/plugin-security; #7351 / PRs #8290, #8291 cover the two dogfood headers and ADR-0094 D2. Checked and clean: packages/spec/src/kernel/metadata-plugin.zod.ts:921 mentions the direction but is correctly retired-voiced; CHANGELOG hits are historical and correctly past-tense.

Note on provenance

This exists because a dispatch assumption was written down and then tested. The dispatch for #7351 asserted that no fourth site survived outside plugin-security and instructed the dev to re-run the sweep anyway and report rather than widen. The assumption was wrong; the instruction is what caught it. The dev correctly did not touch these files and reserved the widen-or-file decision — this card is that decision.

Refs: #7351 / PRs #8290, #8291 · #6858 / PR #6962 (D5-R) · #6483 / PR #6608 (the rollback) · #7082 / PR #7346 · ADR-0005, ADR-0086, ADR-0094

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions