ADR-0066 credits ADR-0094 D5 with "retire implicit managed_by-guessing" — D5 never says that, and the cite now sends readers to a RETIRED section; authorization.mdx:190 inherited it

[qq9340100]

Found while implementing #8292 (PRs #8384 / #8385). Outside both of that card's declared file surfaces (content/docs/permissions/authorization.mdx and docs/adr/0086-*), and a different defect class from it, so deliberately not fixed there. Filed unassigned, no domain:* label — routing and grading are the triage seat's call.

The measurement

docs/adr/0066-unified-authorization-model.md:45 ends its "Landed (2026-07)" paragraph on capability declaration with:

> Aligns with ADR-0094 D5 (retire implicit managed_by-guessing).

ADR-0094 D5 is "Env-scope overlays of package-owned sets are FIRST-CLASS customizations". It is about permission-set overlays. It does not discuss capabilities, placeholder derivation, or back-doors at all:

$ grep -ni "capabilit" docs/adr/0094-sys-permission-set-pure-projection.md
    (no hit anywhere in D5's body, lines 197-236)
$ grep -ni "back-door|backdoor|guess" docs/adr/0094-sys-permission-set-pure-projection.md
    (no hits in the file)

The claim being attributed is real and correct — retiring the implicit back-door where a capability existed only as an untitled placeholder derived from a permission set's systemPermissions[], implemented in bootstrap-declared-capabilities.ts. It is ADR-0066 D1's own direction. Only the cross-reference is wrong.

Why it is worth fixing now rather than later

The cite has become actively misleading since 2026-08-09: ADR-0094 D5 is RETIRED (D5-R, #6858 / PR #6962). A reader following "Aligns with ADR-0094 D5" from a paragraph describing live, shipped behavior lands on a section whose heading says RETIRED 2026-08-09, and has no way to tell that the retirement does not touch the claim they came in for. That is the same reader-harm class as #8292, arriving by a different route.

Second site — it propagated

content/docs/permissions/authorization.mdx:190 (published, customer-facing) carries the inherited version:

> This is the ADR-0094 D5 direction: retire the implicit managed_by-guessing back-doors in favour of explicit, attributable declarations.

This is why the fix spans two files and did not fit inside #8292: #8292's PR 1 owns authorization.mdx but not 0066-*, and fixing only the docs copy would leave the ADR still asserting the wrong alignment for the next reader to re-propagate.

Suggested shape (triage's call)

Re-point both to ADR-0066 D1 — the decision that actually holds the DEFINE/GRANT/REQUIRE separation and the explicit-declaration direction. If some part of the alignment really was meant to reference ADR-0094, name the surviving decision (D1 — the metadata layer as the only authoritative store) rather than D5. Both sites are one sentence each. docs/adr/** is in the diff ⇒ maintainer-merged PR; if the docs half is wanted on the normal path it needs the #8290/#8291 two-PR split again.

Dedup

Searched open issues by keyword (ADR citation / cross-reference accuracy / retired section / defineCapability) and by path. Nothing covers this pair. Closest is #7963 (ADR-0002 citing an ADR-0001 that never existed) — same family of defect, different documents and different cause; not a duplicate. #8292 is the card this was found under and does not cover it.

Refs: #8292 / PRs #8384, #8385 · #6858 / PR #6962 (D5-R) · #7963 (related, not duplicate) · ADR-0066, ADR-0094

---

Generated by Claude Code

[hotlong]

Triage: lands in docs/adr/0066-unified-authorization-model.md + content/docs/permissions/authorization.mdx ⇒ domain:devx, pm:queue, type Bug (a factually wrong cross-reference, now actively misleading since ADR-0094 D5 is RETIRED; the grep evidence is in the card).

Constraints for the executing seat:

• ADR-class landing path: the diff touches docs/adr/**, so one path-hit ⇒ the full terminal three-piece at ACCEPT — review conclusion on this card, PR visibly parked for the maintainer (⛔ no merge / no enqueue / no auto-merge — note the gate now also hard-reds any armed auto-merge on ADR PRs), and a round-report "awaiting a human merge" line. If the docs half should land on the normal queue path, use the two-PR split the card itself names (docs(qa): correct two dogfood headers that still state ADR-0094's retired 2026-07-14 overlay direction #8290/docs(adr): mark ADR-0094 D2's env-overlay cross-reference as retired, pointing at D5-R #8291 precedent): ADR sentence in the maintainer PR, authorization.mdx sentence in a normal PR.
• Hard same-file serial: authorization.mdx has in-flight PRs docs(permissions): state the 403 not_overridable refusal for admin-door edits of packaged permission sets #8384/docs(adr): mark ADR-0086's three ADR-0094 D5 pointers as retired, pointing at D5-R #8385 (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). Claim after they land/clear; name them in the claim's serial line, and re-verify the line-190 anchor on the merged ref — 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's own edit may move or even absorb it.
• Fix direction per the card: re-point both sites to ADR-0066 D1 (one sentence each). ⛔ No other prose churn in the ADR.

Size/model suggestion: S (two one-sentence edits + anchors re-check), mode:subagent, sonnet/opus.

Triage seat Routine, scheduled fire 2026-08-13 ~11:11Z.

---

Generated by Claude Code

[qq9340100]

Claim: PM loop round 4 (accelerated batch per maintainer instruction)
Session: session_01Jqe56GnYFddggeAyfkZFVz
Branch: claude/issue-8386-authz-docs-d5-cite (docs PR) + claude/issue-8386-adr-0066-d5-cite (ADR PR, maintainer-merged)
Worktree: objectstack-issue-8386
Domain: domain:devx
File surface: content/docs/permissions/authorization.mdx (PR 1, normal path) + docs/adr/0066-unified-authorization-model.md (PR 2, ADR-class ⇒ maintainer-merged, no shared diff) (stop on breach; explain in the report)
Container & model: S, mode:subagent, model: sonnet
Serial constraints cleared: the triage-named hard serial is CLEARED — PRs #8384 and #8385 (#8292) both MERGED (11:13Z / 12:05Z). Both anchors re-verified on the merged ref at claim time: 0066-*.md:45 still ends "Aligns with ADR-0094 D5 (retire implicit managed_by-guessing)"; authorization.mdx:190-191 still carries the inherited "This is the ADR-0094 D5 direction: retire the implicit managed_by-guessing back-doors…" — #8292's edit did not move or absorb either. No other in-flight claim declares either file. ⚠️ Note: armed auto-merge on any docs/adr/** PR is now hard-red (PR #8302) — PR 2 stays draft, nothing armed.

---

Generated by Claude Code

[qq9340100]

<!-- os-dev-report -->

{
  "issue": 8386,
  "status": "done",
  "branch": "claude/issue-8386-authz-docs-d5-cite + claude/issue-8386-adr-0066-d5-cite",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/8437 (docs, normal path) + https://github.com/objectstack-ai/objectstack/pull/8440 (ADR, maintainer-merged)",
  "premise_still_valid": true,
  "summary": "Re-verified both anchors on origin/main at claim time: 0066-*.md:45 still ended 'Aligns with ADR-0094 D5 (retire implicit managed_by-guessing)', authorization.mdx:190-191 still carried the inherited copy. Confirmed ADR-0094 D5 (env-scope overlay first-class customization) has zero hits for capabilit/guess/back-door and is RETIRED; confirmed ADR-0066 D1's own paragraph already states the claim being attributed (capability back-door retirement, DEFINE/GRANT/REQUIRE decoupling) and checked the alternative candidate ADR-0094 D1 (metadata layer as authoritative store — about sys_permission_set projection, not capability retirement) does not fit as well. Re-pointed both one-sentence cites to ADR-0066 D1 per the ruling's default, no other prose changed in either file (git diff confirms 1 line each). PR 1 (authorization.mdx) is a normal-path draft PR; PR 2 (docs/adr/0066-*) is ADR-class per repo convention — draft, nothing armed, left for the maintainer.",
  "tests": "PR1 (content/docs/permissions/authorization.mdx): pnpm check:docs-audit-scope (pass), pnpm check:quick-reference-counts (pass), pnpm check:role-word (pass, 44 baselined files no new occurrences), pnpm --filter @objectstack/lint run check:doc-formula-expressions (pass, 24 self-test cases + 22 record-scoped + 9 spec-TSDoc examples judged clean — required building packages/spec + packages/formula deps first via pnpm --filter '@objectstack/lint^...' build), pnpm check:nul-bytes (pass, 7610 files scanned). Re-derived via node scripts/pm/dispatch-gates.mjs content/docs/permissions/authorization.mdx: surfaced exactly the 4 named families, no addition. || PR2 (docs/adr/0066-unified-authorization-model.md): pnpm check:docs-audit-scope (pass), pnpm check:adr-anchors (pass, 48 anchored files / 23547 citations resolve), node scripts/check-adr-links.mjs (pass, 533 relative links resolve), pnpm check:nul-bytes (pass, 7615 files). check-adr-merge-approval.mjs not run locally (401s without a token, per dispatch prompt — CI judges it). Re-derived via node scripts/pm/dispatch-gates.mjs docs/adr/0066-unified-authorization-model.md: surfaced check:adr-anchors, check-adr-links.mjs, check-adr-merge-approval.mjs — matches the named set exactly, no addition.",
  "open_questions": [],
  "out_of_scope_findings": []
}

---

Generated by Claude Code

[qq9340100]

os-dev-report

(correction: the previous comment's marker was sanitizer-eaten — it stored the HTML-escaped literal <!-- os-dev-report --> instead of the intended comment tag. This comment carries the same report with a plain-text marker per the fallback instruction.)

{
  "issue": 8386,
  "status": "done",
  "branch": "claude/issue-8386-authz-docs-d5-cite + claude/issue-8386-adr-0066-d5-cite",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/8437 (docs, normal path) + https://github.com/objectstack-ai/objectstack/pull/8440 (ADR, maintainer-merged)",
  "premise_still_valid": true,
  "summary": "Re-verified both anchors on origin/main at claim time: 0066-*.md:45 still ended 'Aligns with ADR-0094 D5 (retire implicit managed_by-guessing)', authorization.mdx:190-191 still carried the inherited copy. Confirmed ADR-0094 D5 (env-scope overlay first-class customization) has zero hits for capabilit/guess/back-door and is RETIRED; confirmed ADR-0066 D1's own paragraph already states the claim being attributed (capability back-door retirement, DEFINE/GRANT/REQUIRE decoupling) and checked the alternative candidate ADR-0094 D1 (metadata layer as authoritative store — about sys_permission_set projection, not capability retirement) does not fit as well. Re-pointed both one-sentence cites to ADR-0066 D1 per the ruling's default, no other prose changed in either file (git diff confirms 1 line each). PR 1 (authorization.mdx) is a normal-path draft PR; PR 2 (docs/adr/0066-*) is ADR-class per repo convention — draft, nothing armed, left for the maintainer.",
  "tests": "PR1 (content/docs/permissions/authorization.mdx): pnpm check:docs-audit-scope (pass), pnpm check:quick-reference-counts (pass), pnpm check:role-word (pass, 44 baselined files no new occurrences), pnpm --filter @objectstack/lint run check:doc-formula-expressions (pass, 24 self-test cases + 22 record-scoped + 9 spec-TSDoc examples judged clean -- required building packages/spec + packages/formula deps first via pnpm --filter '@objectstack/lint^...' build), pnpm check:nul-bytes (pass, 7610 files scanned). Re-derived via node scripts/pm/dispatch-gates.mjs content/docs/permissions/authorization.mdx: surfaced exactly the 4 named families, no addition. || PR2 (docs/adr/0066-unified-authorization-model.md): pnpm check:docs-audit-scope (pass), pnpm check:adr-anchors (pass, 48 anchored files / 23547 citations resolve), node scripts/check-adr-links.mjs (pass, 533 relative links resolve), pnpm check:nul-bytes (pass, 7615 files). check-adr-merge-approval.mjs not run locally (401s without a token, per dispatch prompt -- CI judges it). Re-derived via node scripts/pm/dispatch-gates.mjs docs/adr/0066-unified-authorization-model.md: surfaced check:adr-anchors, check-adr-links.mjs, check-adr-merge-approval.mjs -- matches the named set exactly, no addition.",
  "open_questions": [],
  "out_of_scope_findings": []
}

---

Generated by Claude Code