Skip to content
This repository was archived by the owner on Nov 4, 2026. It is now read-only.

Commit 3d72fb6

Browse files
os-teslaclaude
andauthored
docs(skills): gate the usePermissions example on can(), a boolean, and mark its fence (objectui#9671) (#9994)
Fixes #9671 Clause-②: yes Draft against `main`. `skills/**` is a governed surface (Tier H): this PR stays draft until an authorized approval, and the seat lands it. Dev run under the `domain:skills` seat (objectstack#7623), session `https://claude.ai/code/session_01W5y9kRg1YtYaMQYExVLRc2`. ## What changed One file: `skills/objectui/guides/auth-permissions.md`, the `usePermissions` hook example under the heading "usePermissions hook". - The two button gates rest on `can('contacts', 'update')` / `can('contacts', 'delete')` — a **boolean**, and the one spelling the guide's neighbouring paragraph ("Publish `can(...)`") already publishes. `check(...)` is gone from the example: it answers a `PermissionCheckResult` object, an object is truthy, and so gated on it both buttons rendered for a denied user. - Each gate is annotated `: boolean`. That annotation is the tripwire: a `check(...)` put back in that position no longer compiles (TS2322), so the next instance of this defect class goes red in the gate instead of shipping (ablation leg A below). - The fence carries the `os:check` HTML-comment marker on the line directly above it and is tagged `tsx`, so `scripts/check-skill-examples.mjs` compiles it against the built dist from now on. To compile it: `Button` is imported from `@object-ui/components`, and `contact` is typed inline as an object with an optional numeric `salary`. `checkField(...)` is untouched (it already answers a boolean). - The `contact` argument is dropped from the gates — see the API-shape decision. ## API-shape decision: `can(object, action)`, record dropped `can` takes no record; the old example passed `contact` to `check`. Measured against the BUILT `packages/permissions/dist/index.js`, with a throwing Proxy handed in as `record` (any `get` / `has` / `ownKeys` / descriptor read on it throws and is counted), over the guide's own `PermissionProvider` config: | role | action | `can()` (no record) | `check(..., record).allowed` | agree | |---|---|---|---|---| | admin | update | true | true | yes | | admin | delete | true | true | yes | | viewer | update | false | false | yes | | viewer | delete | false | false | yes | | owner | update | true | true | yes | | owner | delete | true | true | yes | - `record property accesses observed: 0` — `evaluatePermission` (`packages/permissions/src/evaluator.ts`) never reads a field of the record. Its only use of `record` is presence: when a record is passed AND the role carries `rowPermissions`, the role's grant additionally requires some row rule's `actions` to list the action. `evaluateCondition` in the same file has no caller on the `check` path (its callers are tests and other packages' own evaluators). - On the guide's own config the two spellings agree on every (role, action) above, so dropping the argument changes no verdict the example demonstrates. - Boundary, stated so the parameter is not read as inert: a role that grants `delete` whose row rules list only `read` answers `true` without a record and `false` with one — still with zero reads of the record. That is a per-role static toggle, not record-level gating; the guide's own section "Row filters are returned verbatim — nothing interpolates them" already says the package evaluates no row filter client-side. An example passing `contact` therefore taught record-level gating the package does not perform; the boolean spelling that keeps the example true is `can(...)` with no record. - Ruled out: `check(...).allowed` (a second spelling for the same question — the drift the card names), and any new helper or package API change (the repair is in the guide). ## Line readings (the two the skills rule requires) | reading | before (`c255b38`, unchanged at `edbcf1e`) | after (`48d3d2b`) | delta | |---|---|---|---| | `skills/objectui/guides/auth-permissions.md` | 403 | 409 | +6 (budget: net ≤ +6) | | whole package, every `skills/objectui/**/*.md` summed | 4,640 | 4,646 | +6 | (`wc -l`; `origin/main` moved from `c255b38` to `edbcf1e` between dispatch and branch-out with both readings unchanged.) ## Marked population At `48d3d2b` the gate prints `Marked: 16 ts fence(s) (floor 13), 70 json fence(s) (floor 70)`; `--list` shows the new row `skills/objectui/guides/auth-permissions.md:225 [tsx] marked pass`. Before: the BASE tree carries 85 `os:check` markers under `skills/` plus `.claude/skills/` and this branch 86 (`git grep -c` on the BASE ref vs the worktree — the unbuilt BASE tree cannot print the gate's own line), so ts 15 → 16, json 70 → 70. `MARKED_FLOOR` in `scripts/check-skill-examples.mjs` is left at `ts: 13`. Its header invites raising it in the PR that adds a marker; that file is outside this card's claimed file surface (the guide, and the eval JSON only if a gate demanded it), so it is not touched here — see Acceptance notes. ## Gates (exit captured before any pipe; verdict lines quoted) Closure build first, under objectstack's verification lock: `pnpm exec turbo run build $(node scripts/check-skill-examples.mjs --build-filter) --concurrency=2` → `Tasks: 29 successful, 29 total` · lock `VERDICT command-exit 0 · held the lock 217s`. | command | exit | verdict line | |---|---|---| | `pnpm check:skill-examples` | 0 | `Semantic phase: 16 of 16 ts fence(s) judged, 0 failed.` · `Every marked skill example holds up against the built types.` | | `pnpm check:skill-eval-tokens` | 0 | `Every must_contain token is taught by its own skill bundle.` (eval JSON untouched) | | `pnpm check:skills-paths` | 0 | `check-skills-paths: OK (88/89 stated path(s) resolve across 20 guide file(s); 1 baselined).` | | `pnpm check:new-line-citations` | 0 | `VERDICT new-cross-file-line-citations: 0 new citation(s), enforcement report-only → exit 0` | | `pnpm check:control-bytes` | 0 | `check-control-bytes: OK (scanned 8061 tracked text file(s); skipped 85 binary).` | | `node scripts/check-governed-queue-guard.mjs --test skills/objectui/guides/auth-permissions.md` | 3 | `GOVERNED — 1 of 1 path(s) are on a governed surface: skills/** x1` (informational; the expected reading) | | `node scripts/check-changeset-presence.mjs` | 0 | `No source or published contract of a released package changed in this range, so no changeset is owed.` — no changeset added | | `pnpm exec vitest run packages/permissions/src/__tests__/skill-guide-permission-config.test.tsx` (the test `markdown-test-inputs.mjs --changed` names for this guide) | 0 | `Test Files 1 passed (1)` · `Tests 8 passed (8)` | | `pnpm exec vitest run scripts/__tests__/check-skill-examples.test.ts` | 0 | `Test Files 1 passed (1)` · `Tests 113 passed (113)` | NOT MEASURED locally: `pnpm lint` (repo-level `turbo run lint`, CI's run). Reason it was not run, not a measurement: the diff is one `.md` file and `eslint.config.js` configures no markdown processor. ## Ablation From the committed state `48d3d2b`, each leg through objectstack's `scripts/ablation-replace.mjs`: mutation proven by anchor counts and blob hash, restore proven by blob == HEAD blob (`b9f4672`) and an empty `git diff HEAD`, tree clean after each leg. - **Leg A — defect back, marker kept**: `check` re-added to the destructure and `canEdit: boolean = check('contacts', 'update', contact)`. Gate exit **1**: `[semantic] skills/objectui/guides/auth-permissions.md:236:9 TS2322: Type 'PermissionCheckResult' is not assignable to type 'boolean'.` · `Semantic phase: 16 of 16 ts fence(s) judged, 1 failed.` Direction: red, as predicted. - **Leg B — same defect, marker removed**: gate exit **0**, `Marked: 15 ts fence(s) (floor 13)`, `Semantic phase: 15 of 15 ts fence(s) judged, 0 failed`, `Every marked skill example holds up`. That is the blind spot the card names, reproduced: unmarked, the defect is invisible to the only instrument that can see it. It also shows the floor at 13 does not red on this fence being unmarked (16 → 15), which is why the floor note above exists. - A first attempt at leg B did not run: the tool refused a marker removal whose replacement text was a substring of its anchor (`x1 → x1`), restored, and exited 1 before the gate; the leg was re-run with a distinct replacement. Recorded so the count of runs is honest. ## Acceptance notes - noted, not filed: `MARKED_FLOOR` `ts` stays 13 with 16 marked; the gate header's invited raise is outside this card's file surface. 承接者: the landing seat (a one-line follow-up in `scripts/check-skill-examples.mjs`), or none if the seat prefers the floor to move only with a census. - noted, not filed: the guide's "Permission evaluation pipeline" step 4 reads "If record provided + row permissions exist: evaluate row-level filter"; the evaluator consults the row rules' `actions` list and never the filter or the record (measured above). Different paragraph, outside this card's section; prose precision, not a copied-code defect. 承接者: none identified. - Board: 0 of 12 open PRs touched this guide at dispatch; PR #9378 (objectui#9370) holds three other guides of the package and is not touched. - No label writes from this run; `needs:contract-review` is the seat's to hang on this PR. ## 维护者速读(草稿) **改了什么** — `skills/objectui/guides/auth-permissions.md` 里 `usePermissions` 那段示例:两个按钮的显隐改为看 `can('contacts', 'update')` / `can('contacts', 'delete')`(布尔值),不再看 `check(...)`(一个对象,恒为真);示例围栏加了 `os:check` 标记并改为 `tsx`,补上编译所需的 `Button` 导入与 `contact` 类型;去掉了传给 `check` 的 `contact` 参数。 **为什么改** — 这段代码会被客户项目照抄。原写法下被拒绝的用户也能看到「编辑」「删除」按钮,权限门形同虚设;而该围栏此前未被任何门禁编译,所以没人发现。实测(对着已构建的 `@object-ui/permissions`)`check` 从不读取记录的任何字段,`can` 在指南自己的配置上与 `check(..., record).allowed` 逐项一致,所以去掉记录参数不改变示例演示的任何结论。 **风险与代价(含回滚)** — 只改一个已发布技能文件(净 +6 行,在 PM 预算内),不动任何包源码、不动 API,不需要 changeset。回滚 = revert 这一个 commit。留下的一处:门禁的 `MARKED_FLOOR` 仍是 13(现有 16 个标记围栏),要不要同步抬到 16 交席位决定。 **席位意见** — **你要做的** — 受管面 PR,需要一条获授权账号的 APPROVED review;批准后由席位入队落地。无需其他动作。 --- _Generated by [Claude Code](https://claude.ai/code/session_01W5y9kRg1YtYaMQYExVLRc2)_ Co-authored-by: Claude <noreply@anthropic.com>
1 parent c2f0f48 commit 3d72fb6

1 file changed

Lines changed: 11 additions & 5 deletions

File tree

‎skills/objectui/guides/auth-permissions.md‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -221,14 +221,20 @@ guide does not govern it; the two look alike and are unrelated.
221221

222222
### usePermissions hook
223223

224-
```typescript
224+
<!-- os:check -->
225+
```tsx
225226
import { usePermissions } from '@object-ui/permissions';
227+
import { Button } from '@object-ui/components';
226228
227-
function ContactActions({ contact }) {
228-
const { check, checkField, getFieldPermissions, getRowFilter } = usePermissions();
229+
function ContactActions({ contact }: { contact: { salary?: number } }) {
230+
const { can, checkField, getFieldPermissions, getRowFilter } = usePermissions();
229231
230-
const canEdit = check('contacts', 'update', contact);
231-
const canDelete = check('contacts', 'delete', contact);
232+
// Gate on `can`, which answers a boolean. `check` answers `{ allowed, … }`, and
233+
// an object is truthy, so gated on it both buttons render for a denied user
234+
// too; its `record` argument reads no field of the record, so none is passed.
235+
// `: boolean` is what makes a `check(...)` here fail to compile.
236+
const canEdit: boolean = can('contacts', 'update');
237+
const canDelete: boolean = can('contacts', 'delete');
232238
const canSeeSalary = checkField('contacts', 'salary', 'read');
233239
234240
return (

0 commit comments

Comments
 (0)