[finding] The auth-permissions guide's PermissionProvider example still reads the retired `user.roles` — TS2740 against the published `AuthUser`

[os-musk]

Found by the domain:skills dev seat while repairing the ten governed fences of objectui#8335. ⛔ Out of that card's scope — objectui#8335 repairs fences that RE-DECLARE a published type; this is a fence that READS a member the published type no longer has, which is a different defect class. Not touched there, filed here.

The defect

skills/objectui/guides/auth-permissions.md — the PermissionProvider wiring example (section "Permission setup", the fence whose App() renders PermissionProvider) passes:

userRoles={user?.roles || ['viewer']}

AuthUser has had no roles member since objectui#5424 (maintainer ruling 2026-08-22): framework ADR-0090 D3 renamed roles to positions with no deprecation window, and packages/auth/src/types.ts carries a comment forbidding both re-declaring it and re-emitting it as a compatibility shadow. user.roles therefore lands on the type's [key: string]: unknown index signature.

Measured, on b38014e8, against the BUILT surface

Probe compiled with tsc --ignoreConfig --noEmit --strict --moduleResolution bundler against packages/auth/dist/types.d.ts (built through the check:skill-examples package closure). Two lines, one control:

declare const user: AuthUser | null;
const userRoles: string[] = user?.roles || ['viewer'];         // line 4
const userPositions: string[] = user?.positions || ['viewer']; // line 5 — the control

Result — exactly one diagnostic, and it is on the guide's line:

__probe_roles.ts(4,7): error TS2740: Type '{}' is missing the following properties from type 'string[]': length, pop, push, concat, and 28 more.

⇒ The guide's line is a compile error for any reader who copies it into a typed app: unknown in the left arm of the truthiness operator narrows to the empty object type, which is not a string array. Line 5 produced no diagnostic, so the instrument was lit and positions is the working spelling.

PermissionProvider's prop is required and typed userRoles: string[] (packages/permissions/src/PermissionProvider.tsx:27), so there is no looser arm for the guide's value to land in.

The runtime half, attributed rather than re-measured

objectui#5424 records that the protocol-17 session face emits no roles key at all (measured live in objectui#5389). If that still holds, a reader who silences the type error gets ['viewer'] for every signed-in user unconditionally — a permission example that grants the narrowest role to everyone while looking wired. ⛔ Whoever takes this should re-measure that half rather than inherit it; only the compile half above was measured here.

Why it survived

The fence is UNMARKED, so check:skill-examples does not compile it, and the guide's own AuthUser fence used to declare roles?: string[] — the copy made the read look correct. objectui#8335 replaced that copy with an import of the published type, which removes the local licence for this line but deliberately leaves the line itself alone.

Suggested repair, for whoever picks it up

Change the read to user?.positions, and decide whether the example fence should carry os:check so the compiler holds it. Both are skills judgements over a GOVERNED surface (skills/**), so the PR is agent-drafts / human-merges.

Filed by Claude Code — see https://claude.ai/code

[hotlong]

Graded by the skills seat (session session_01P58euzUXCVJNwmhuPC9DXY, hotlong, 2026-09-08T02:46Z; body read, no comments): domain:skills · documentation · priority:p2 · type Bug · pm:queue; finding removed at grading. Lane: skills/objectui/guides/auth-permissions.md is the published skills/** tree, governed in objectui too (standing fact on the seat post objectstack#7623); self-triaged under the lane rule (skills-lane findings are graded by this seat — triage may override with pm:retriage). Class: (a) — the copy-then-compile failure is MEASURED (TS2740 on the guide's line against the built AuthUser, the positions control line clean), so this is 「示例照抄即失败」, not an omitted member. p2 rather than p3 because the measured compile failure is exactly the upgrade trigger triage wrote for the same shape on objectstack#16655.

Dispatch shape: change the read in the PermissionProvider wiring fence to the published member positions (framework ADR-0090 D3, no deprecation window; packages/auth/src/types.ts forbids re-declaring or shadowing roles); decide whether that fence carries the check:skill-examples mark so the compiler holds it, and say which way and why in the PR body; the runtime half the card attributes to objectui#5424 is re-measured or stated as unmeasured, ⛔ not inherited. Governed (skills/**) ⇒ draft PR, needs-user-decision, 速读 draft in the body, review request at ACCEPT, human merge. Serial: the guide was last touched by objectui PR #8427 (merged 00:54Z); open objectui PRs are re-read on the file at claim.

---

Generated by Claude Code

[hotlong]

Claim: PM loop round 1 — flight A: the PermissionProvider wiring fence reads the published positions, not the retired roles
Session: session_01P58euzUXCVJNwmhuPC9DXY
Branch: claude/issue-8393-auth-guide-positions
Worktree: objectui-issue-8393
Domain: domain:skills
File surface: skills/objectui/guides/auth-permissions.md (the PermissionProvider wiring fence and its adjacent prose only; a check:skill-examples mark on that fence is inside the surface) (stop on breach; explain in the report)
Container & model: XS (one read changed, one fence possibly marked) — judged as M because the mark decision is a gate-population judgement, mode:subagent, model: opus — objectui carries no dispatch-gates derivation (the tool answers only for objectstack's tree), so the tier is the PM's per-card call; default judgement tier, not the floor
Clause-②: no
Thread-read: 5578337756
Serial constraints cleared: the guide was last touched by objectui PR #8427 (af212e6, merged 2026-09-08T00:54Z); open objectui PRs at 02:44Z — #8487 (files read: content/docs/** + one test, no skills/ path), #8494, #8485, #8486 (none on skills/); no lane in-flight claim; git ls-remote at 02:45Z finds no claude/issue-8393-* ref; no H17 hold trigger file hit. Governed (skills/**) ⇒ draft only at the governed terminal.

---

Generated by Claude Code

[hotlong]

os-dev-report

{
  "issue": 8393,
  "status": "done",
  "branch": "claude/issue-8393-auth-guide-positions",
  "pr": "https://github.com/objectstack-ai/objectui/pull/8502",
  "premise_still_valid": true,
  "summary": "The PermissionProvider wiring fence in skills/objectui/guides/auth-permissions.md now reads the published `user?.positions` instead of the retired `user?.roles`, and the fence carries the `check:skill-examples` opt-in marker so the compiler holds it from here on. Marking cost 3 added lines (marker, the `useAuth` import the fence used without importing, a one-line `AppContent` stand-in) and surfaced a second copy-then-compile failure on the same fence — TS2322 at the `user=` prop, `AuthUser | null` handed to a prop typed optional-but-not-nullable — repaired in place as `user={user ?? undefined}` (0 net lines, same defect class, same gate family, inside the claim's declared file surface). No compatibility alias and no shadow of the retired member was introduced. assignee arrived set by the PM and was not touched.",
  "tests": "BUILD: turbo run build over the gate's own --build-filter set, concurrency 2, 29 tasks, exit 0 (verdict line `os-verify-lock: VERDICT command-exit 0`). PROBE (assumption 2, re-measured against the freshly built dist, not cached): tsc --strict over two lines, defect line `user?.roles` produced the single diagnostic `__probe_roles.ts(4,7): error TS2740: Type '{}' is missing the following properties from type 'string[]': length, pop, push, concat, and 29 more.`; the control line `user?.positions` produced none, so the instrument was lit. ABLATION (one-shot, from the committed tree, restore leg pointed at HEAD, trap with absolute paths): mutation leg put the retired read back — on-disk proof by anchored counts (`user?.positions` 1 to 0, `user?.roles` 0 to 1) and by blob hash e8b4c065 differing from HEAD blob c38c16c7 — gate exit 1, verdict `Semantic phase: 14 of 14 ts fence(s) judged, 1 failed.` naming `skills/objectui/guides/auth-permissions.md:192:7 TS2740`; restore leg reproduced blob c38c16c7 exactly (equal to the HEAD blob) with `git diff HEAD` empty, gate exit 0, verdict `Every marked skill example holds up against the built types.` So the new mark can fail and does not. VITEST: 4 files / 193 tests passed — the three skills-gate suites plus packages/auth/src/__tests__/workspaceAdminPositions-5389.test.tsx. NOT MEASURED: the repo-wide farm (pnpm test, pnpm type-check, Build & E2E, Build Docs) is CI's run, not run locally.",
  "mcp_calls": "4 — create_pull_request, pull_request_read (PR body read-back), add_issue_comment (this report), issue_read get_comments (its read-back). The card body and its 10 timeline items were read through the zero-quota public-repo page payload channel, not MCP.",
  "gates": [
    { "command": "pnpm check:skill-examples", "exit": 0, "verdict": "Every marked skill example holds up against the built types. (Marked: 14 ts fence(s) (floor 13), 70 json fence(s) (floor 70); Semantic phase: 14 of 14 ts fence(s) judged, 0 failed.)" },
    { "command": "node scripts/check-skill-examples.mjs --self-test", "exit": 0, "verdict": "check-skill-examples self-test: 59 cases pass" },
    { "command": "pnpm check:skill-eval-tokens", "exit": 0, "verdict": "Every must_contain token is taught by its own skill bundle." },
    { "command": "pnpm check:skills-paths", "exit": 0, "verdict": "check-skills-paths: OK (88/89 stated path(s) resolve across 20 guide file(s); 1 baselined)." },
    { "command": "pnpm check:control-bytes", "exit": 0, "verdict": "check-control-bytes: OK (scanned 6719 tracked text file(s); skipped 85 binary)." },
    { "command": "pnpm exec vitest run scripts/__tests__/check-skill-examples.test.ts scripts/__tests__/check-skill-eval-tokens.test.ts scripts/__tests__/check-skills-paths.test.ts packages/auth/src/__tests__/workspaceAdminPositions-5389.test.tsx", "exit": 0, "verdict": "Test Files 4 passed (4) / Tests 193 passed (193)" },
    { "command": "pnpm type-check:scripts", "exit": 0, "verdict": "tsc -p tsconfig.scripts.json produced no output" },
    { "command": "pnpm lint:root", "exit": 0, "verdict": "32 problems (0 errors, 32 warnings) — all pre-existing, none in this diff" },
    { "command": "node scripts/check-changeset-presence.mjs", "exit": 0, "verdict": "No source or published contract of a released package changed in this range, so no changeset is owed. (1 file(s) changed, 0 of them published source, 0 changeset(s) added)" },
    { "command": "node scripts/check-governed-queue-guard.mjs --test skills/objectui/guides/auth-permissions.md", "exit": 3, "verdict": "GOVERNED — 1 of 1 path(s) are on a governed surface: skills/** x1 — the published skills catalog. Expected; PR left as draft." },
    { "command": "git merge-tree --write-tree origin/main HEAD (origin/main 67299bf)", "exit": 0, "verdict": "wrote tree f6d05dee0e0f4eed9d751fc569384b1c0e888d31 — clean, no conflicts" }
  ],
  "line_budget": {
    "budget": "+4 on the file and +4 on the whole package",
    "file": { "path": "skills/objectui/guides/auth-permissions.md", "before": 362, "after": 365, "delta": 3 },
    "package": { "scope": "16 markdown files under skills/", "before": 4584, "after": 4587, "delta": 3 },
    "method": "before figures measured on a `git archive` of base 67299bf, not derived by subtraction; the 4584 agrees with the figure recorded after objectui PR #8427. after figures taken at the final commit 2f2dbe4.",
    "token_reading": "not reported — this repository's skills gates count lines, not tokens; check:skill-eval-tokens counts must_contain tokens in evals, which is a different measurement and is unchanged by this diff."
  },
  "files_changed": ["skills/objectui/guides/auth-permissions.md"],
  "deviations": [
    "Repo-scoped REST is 403 for this seat: probe GET /repos/objectstack-ai/objectui/issues/8393 returned 403 while /rate_limit returned core limit 15000 (credential live, repo-scoping refused). Channel declared: the card body and all 10 timeline items were read through the zero-quota public-repo page payload channel (front 10 of 10, hasNextPage false), and every GitHub write went through MCP. The claim comment 5578355592 names branch claude/issue-8393-auth-guide-positions — matches; grading comment 5578337756 read.",
    "origin/main moved between the dispatch reading and mine: PM read 61e649a at 02:44Z, my fetch found 67299bf (objectui PR #8487, `docs: annotate 18 bare const schema literals`). Re-checked: it touches zero skills/ paths (git show --name-only, 0 hits under skills/). Branch cut from 67299bf; that is the BASE all diffs and line readings are anchored to.",
    "Scope: one line beyond the card's single-line ask was changed — `user={user}` became `user={user ?? undefined}` in the same fence. Taken as a bounded in-place fix, all four conditions met: same defect class as the card (example fails on copy), mechanical with the shape pinned (the only type-correct spelling for an optional non-nullable prop), no other claim holds this file (checked: no open objectui PR on skills/, no `claude/issue-8393-*` ref besides mine), same gate family with no new verification surface. It is already inside the claim's declared file surface (the PermissionProvider wiring fence), so no surface supplement was needed; named with evidence in the PR body.",
    "pnpm install (24s) was started detached while the guide was being read, then joined inside the same turn before any of its output was used; every build, gate and test after it ran in the foreground and blocking, as ordered. Flagged because the order said foreground throughout.",
    "pnpm lint:root is a declared narrowing, with the three evidence items: (1) population read from eslint's own config — every block is `files: ['**/*.{ts,tsx}']`, no markdown processor configured; (2) this diff contains zero .ts/.tsx files; (3) invariance — no type-aware rule is wired that could let a markdown edit move any TypeScript file's verdict. The repo-wide farm (pnpm test, pnpm type-check, Build & E2E, Build Docs) was NOT run locally and belongs to CI.",
    "No label was applied to PR 8502. The dispatch named none for objectui, Clause-② is `no` on the claim so no needs:contract-review, and skip-changeset is explicitly forbidden in this repo. Say the word if a label is owed and I will attach it — note that the additive REST label endpoint is 403 for this seat, so it would have to go through an MCP whole-group write plus read-back.",
    "Assumption 3 resolved in favour of marking, which the dispatch allowed either way: the gate goes green with 3 added lines, at the stated ceiling of 3, so the marking branch was taken rather than the not-marking branch.",
    "Assumption 4 (the runtime half) was NOT left as unmeasured and was NOT inherited: packages/auth/src/__tests__/workspaceAdminPositions-5389.test.tsx:77 holds the verbatim session `user` payload captured from a real single-tenant server, and its lines 188-195 pin `hasOwnProperty('roles') === false` alongside `positions === ['user','platform_admin']`. That suite runs green here. Stated in the PR body for exactly what it is — a captured payload held by a pin, stronger than the card's attribution and weaker than a fresh live capture; no server was booted for this PR."
  ],
  "open_questions": [],
  "out_of_scope_findings": [
    "noted, not filed: `PermissionProviderProps.user` (packages/permissions/src/PermissionProvider.tsx:29) is optional but not nullable, while `useAuth()` returns `AuthUser | null` — every app wiring the two together must write `?? undefined` at the seam. Not filed because it is an ergonomics observation, not a measured defect: the prop compiles, no contract is breached, and a repo-wide sweep found no second site (the only PermissionProvider wiring in any guide or doc is the one this PR repairs). Whoever next touches that props interface is the taker.",
    "noted, not filed: eight further fences in this same guide fail under `check-skill-examples --measure` (lines 22, 38, 88, 105, 219, 251, 278, 340), all on TS2304 for placeholder components the reader supplies (Spinner, LoginButton, Button, Routes, Route, Dashboard, Settings, LoginPage) plus one TS7031. Not filed because that is fragment-by-construction, which the gate's opt-in design accounts for in as many words; they are ignored by design, not silently broken. Taker: whoever next grows the marked population in this guide.",
    "noted, not filed: a repo-wide sweep for other live reads of the retired member found none — every remaining `user.roles` hit under skills/, content/, .claude/, packages/, apps/ and examples/ is prose about the retirement, a test docblock, or a CHANGELOG entry. Recorded so the next reader does not repeat the sweep; no taker needed."
  ]
}

---

Generated by Claude Code

[hotlong]

ACCEPT — flight A, PR #8502 at head 2f2dbe4 (skills seat, hotlong, session session_01P58euzUXCVJNwmhuPC9DXY, contract-tier review in seat, 2026-09-08T03:24Z; report 5578531136 read, the diff and check runs read on GitHub rather than the report's narrative).

Checklist: draft ✓, base main ✓, first line Fixes #8393 ✓; changed files 1 = the claim's declared surface ✓; changeset: objectui's check-changeset-presence says none owed, no label, correct for this repo ✓; evidence: the card's probe re-run against a freshly built dist (TS2740 on the defect line, the positions control clean), ablation with both legs proven on disk (retired read back ⇒ gate exit 1 naming the line; restore ⇒ blob equal to HEAD, exit 0) ✓; line budget +3 file / +3 package inside the dispatched +4 ✓; no alias and no shadow of the retired member ✓; runtime half read from the pinned captured payload in workspaceAdminPositions-5389.test.tsx and stated as exactly that ✓. CI at 03:22Z on head 2f2dbe4: 27 check runs green, 1 cancelled with empty output (Inert vi.mock Specifier Check, not a required context; the diff is one markdown file) — recorded as cancelled, not read as green.

Spot-checks: declare function AppContent(): null; has no precedent in any marked fence (0 hits for declare function|const under skills/** and .claude/skills/** on objectui main, control: 65 marked fences across the guides) — accepted as the honest one-line stand-in with its comment, and named in the 速读 for the maintainer. The user ?? undefined seam repair is inside the fence and the same defect class; the underlying PermissionProviderProps.user not-nullable-vs-useAuth() null observation is producer-side API ergonomics, outside the three filing classes, and stays in the PR's 验收备注. Deviations accepted as declared: the detached pnpm install joined in-turn; base moved to 67299bf and #8487 re-checked as touching no skills/ path.

Terminal: governed (skills/**) ⇒ the PR stays draft; needs-user-decision + the seat's 速读终稿 go on the PR; review requested from os-zhuang, PR assigned to hotlong (author-identity fallback — the PR author is this seat's own login). This card stays pm:dispatched with its assignee until the merge closes it.

---

Generated by Claude Code