skills: evaluate whether the published security/platform guidance must teach the app-capability vs system-permission distinction and the `isDefault` → `everyone` binding rule (after #17189)

[os-litant]

Filed by the director seat (summon #21, session_01QVMnxyWBx8cAQMsV6akDV9) on the maintainer's instruction, verbatim and untranslated: 「17189 同意，但是同时评估是否需要改进skills」 (director chat, 2026-09-10T08:4xZ, replying to decision batch #110 item 1). Routed domain:skills under the maintainer direct-dispatch channel (the instruction names the work explicitly); pm:queue.

The question

After #17189 lands (ruling (i): an app-declared capability token is not a system permission for the everyone-anchor high-privilege check; ADR-0090 D5 amended), does any published skill under skills/** need to change so that an AI author writing a metadata app does not reproduce the shape hotclm hit?

Measured on origin/main 47863f4 (2026-09-10T08:3xZ)

git grep -n -iE 'isDefault|systemPermissions|capabilit|everyone|permission set' origin/main -- 'skills/**':

• skills/objectstack-data/rules/security.md teaches definePermissionSet, the permissions: stack key, requiredPermissions as an ADR-0066 D3 AND-gate, and the platform-exclusive capabilities (manage_metadata, manage_platform_settings, …).
• skills/objectstack-platform/SKILL.md teaches the capabilities stack key as a demand for a platform provider (the 28 PLATFORM_CAPABILITY_TOKENS) and requires:.
• Zero hits for: isDefault: true on a permission set (the ADR-0090 D5 everyone auto-binding), the high-privilege refusal and what trips it, an app-declared capability token (ADR-0066 D1, scope: 'org') as distinct from a platform token, or the pattern "one default set that every employee holds, carrying the app's own navigation tokens". The only isDefault in the corpus is a list-view example.

⇒ Today the published guidance can teach an author to declare app capabilities (D1) and to gate navigation on them, and separately to write permission sets, but it says nothing about the one combination that failed in the field: the default set that carries app tokens. Whether that is a gap worth text, and where it lands (security.md vs platform SKILL.md), is this card's assessment.

Deliverable

1. An assessment on this card: which skill file(s), which sentences, and whether a negative example (hotclm#11's shape: seven per-position bindings as a workaround) belongs in the text. If the answer is "no change needed", say why with the grep above as the control.
2. If text is needed: the change lands after An app-declared capability with scope: 'org' counts as a high-privilege bit, so a set carrying only app capability tokens cannot bind to the everyone anchor #17189's fix merges, so it teaches the post-fix semantics (until then this card's deliverable is the assessment only). skills/** is a governed surface: contract-review tier build (skills seat), draft PR, ## 维护者速读(草稿) in the body, human merge; the dispatch carries a net-line budget.

Dedup

Open domain:skills cards read by title on 2026-09-10T08:3xZ (17): none about capability tokens, the everyone anchor, or permission-set defaults. Refs: #17189 (the fix and its ruling), hotclm#11, ADR-0090 D5/D9, ADR-0066 D1.

---

Generated by Claude Code

[os-litant]

Claim: PM loop round 1
Session: session_01YKEjmbYNvYWJvWGSWx26zK (GitHub os-litant, skills seat), claimed at 2026-09-10T09:03Z
Branch: claude/issue-17359-skills-capability-guidance
Worktree: objectstack-issue-17359
Domain: domain:skills
File surface: skills/objectstack-data/rules/security.md, skills/objectstack-platform/SKILL.md — READ-ONLY in this dispatch: deliverable 1 (the assessment on this card); ⛔ no edit to skills/** until #17189's fix merges (the card's own condition) (stop on breach; explain in the report)
Container & model: M (a judgment card — the deliverable decides what a published skills/** surface will say; not mechanical), mode:subagent, model: claude-fable-5-1 — node scripts/pm/dispatch-gates.mjs --tier skills/objectstack-data/rules/security.md skills/objectstack-platform/SKILL.md at 706ad0f prints 「Model tier — MANDATORY: claude-fable-5-1 … 'skills/**' — clause ① (2026-09-10 ruling, verbatim 「必须 fable的还包括对外发布的skills」) … no one-line exemption applies under this root」; passed explicitly as the dispatch's model parameter.
Clause-②: no — an assessment; no accept set or public surface moves (any later text is guidance on an already-ruled contract, #17189 (i)).
Thread-read: none (0 comments on the card at claim time; body read in full; #17189's four comments incl. the ruling 5615806616 read).
Serial constraints cleared: no open PR touches the two files and no other claim on this lane names them (git ls-remote at claim: the lane's only branch was the merged #17302's, deleted); action face git log -8 origin/main -- <the two files> newest b110578 (same day — the dev works from current origin/main e669e5e); #17189 has no PR (closed_by_pull_requests 0; spec seat vacant) ⇒ the text half stays blocked on it; H17 hold index names neither file; verify-lock free (--status: lock is free, queue empty).

---

Generated by Claude Code

[os-litant]

Dispatched — R1, 2026-09-10T09:09Z, mode:subagent, build tier claude-fable-5-1 passed explicitly (clause ①: published skills/** is the surface under assessment). Claim 5616017852 is the dev's identity; branch claude/issue-17359-skills-capability-guidance. Scope of this dispatch = deliverable 1 only (the assessment comment; pr: null); ⛔ no edit to skills/** until #17189's fix merges. Disjoint from #17164 (objectos CLAUDE.md) and #17346 (check-clause2-carriers.mjs C4 + contract-review.md :35–:37). Patrol timer trig_012AMK9J7RnbBAeY1WNEtrLA fires 09:49Z.

---

Generated by Claude Code

[os-litant]

Assessment

CHANGE NEEDED

One 3-line construct in skills/objectstack-data/rules/security.md; skills/objectstack-platform/SKILL.md unchanged. The text lands only after #17189's fix merges, because it teaches ruling (i)'s semantics, not the pre-fix refusal.

Ruling assessed against (#17189 comment 5615806616, verbatim): 「describeHighPrivilegeBits 多收一个输入——本 stack 声明过的应用能力名单——名单内的名字不计为系统权限；启动侧拒绝与 lint 规则同笔跟随；ADR-0090 D5 的 offending 清单相应收窄为「平台系统权限；带 package provenance 的应用声明 capability 令牌不计」，ADR 修订走独立受管 PR」. Maintainer's instruction for this card, verbatim: 「17189 同意，但是同时评估是否需要改进skills」.

Control

Tip read: origin/main = e669e5e (e669e5eee296410731c8a00cba366369f005bc96), read 2026-09-10T09:1xZ. The two candidate files last moved at b110578 (same day); both read at tip, in full for security.md (210 lines) and by section for the platform file.

git grep -n -iE 'isDefault|systemPermissions|capabilit|everyone|permission set' origin/main -- 'skills/**' → 83 hits in 19 files: objectstack-data/references/data-hooks.md 23 · objectstack-platform/SKILL.md 14 · objectstack-data/SKILL.md 10 · objectstack-data/rules/security.md 9 · objectstack-ai/SKILL.md 4 · objectstack-upgrade/SKILL.md 3 · objectstack-ui/rules/pages.md 3 · objectstack-data/references/_index.md 3 · objectstack-ui/rules/navigation.md 2 · objectstack-platform/references/_index.md 2 · objectstack-automation/SKILL.md 2 · one each in objectstack-ui/rules/list-views.md, objectstack-ui/rules/actions.md, objectstack-ui/references/_index.md, objectstack-ui/SKILL.md, objectstack-formula/SKILL.md, objectstack-data/rules/indexing.md, objectstack-data/evals/README.md, skills/README.md.

• isDefault: exactly one hit, skills/objectstack-ui/rules/list-views.md:122 (a list-view example).
• everyone: skills/objectstack-data/SKILL.md:78-79 (sharing-model table) and skills/objectstack-formula/SKILL.md:409 only.
• systemPermissions / system_permissions: zero. defineCapability / scope: 'org': zero (second grep, exit 1).
• capabilities in skills/objectstack-platform/SKILL.md: the top-level key list at :76 (name only) and the requires: section :435-482, which teaches the 28 PLATFORM_CAPABILITY_TOKENS (kernel/platform-capabilities.ts) — a different registry from the capabilities: stack key (security/capabilities.ts, ADR-0066 D1).

Positive control git grep -c definePermissionSet origin/main -- 'skills/**' → skills/objectstack-api/SKILL.md:1, skills/objectstack-data/rules/security.md:4 — identical to the PM's reading at e669e5e.

Zone-2 assumptions: A holds (as above). B holds and is wider than the card's one combination: the published skills teach neither the DEFINE key (capabilities: / defineCapability) nor the GRANT key (systemPermissions); security.md:145's own requiredPermissions: ['view_pii'] names an app token that no skill shows declared or granted anywhere (view_pii is not among the 9 curated PLATFORM_CAPABILITIES). C is falsified in one half — see Reader.

Reader

The reader is an AI author writing a metadata app's permissions (and capabilities) into the post-(i) world. Under (i) a systemPermissions name is an app token only when it carries package provenance, i.e. when the stack declares it under capabilities: (boot side: the sys_capability row is managed_by:'package'; lint side: the stack's declaration list). The back-compat implicit derivation that ADR-0066 D1 keeps alive seeds an undeclared name as managed_by:'platform' with no package provenance (packages/plugins/plugin-security/src/bootstrap-declared-capabilities.ts :9-11, :230). So after the fix:

• a declared app token on the isDefault: true set binds to everyone with no warning — hotclm's intended shape works;
• an undeclared app token on that set still reads as 'system permissions': security-anchor-high-privilege (error) and the boot refusal are unchanged, and the lint's fix-it hint (packages/lint/src/validate-security-posture.ts :781-783, "Split the powerful bits into a separate set granted through ordinary positions") walks the author into exactly hotclm#11's seven-per-position workaround instead of the declaration;
• a platform capability (manage_users, setup.access, … — the 9 curated names) or VAMA / delete / transfer / export on that set is refused, loudly, with the bit named.

Value gate:

① Which decision the text changes: whether to declare the token under capabilities: before granting it via systemPermissions on the isDefault: true set. Shape produced today without the text: the skills name none of the three keys, so an author reaches systemPermissions from the schema alone (its .describe() is "System level capabilities") and writes the undeclared grant — the shape the skill's own view_pii example models. That shape still fails after the fix, and its diagnostic steers into the workaround. The plain "app tokens may ride on the default set" sentence (Zone 2 C) changes no decision post-fix — that shape simply works — so it is not what is written.

② Deletion or rewrite instead of addition: no. No existing sentence in either file names isDefault, systemPermissions or capabilities:, so there is nothing to rewrite; the only candidate neighbour (security.md:135-139, requiredPermissions, the REQUIRE side) is correct as written, and folding DEFINE/GRANT into it would be re-wrap paying for new content, which is not a currency.

③ Construct over prose: yes — one bullet in the permission-set key list naming the three keys, the anchor, and the two things refused there.

Real-usage reading (axis ①, measured at e669e5e): examples/app-showcase declares two capabilities (showcase.export_data, showcase.restricted_ops, src/security/capabilities.ts :52, :77) and grants one on OpsPermissionSet (permission-sets.ts :220); its isDefault set showcase_member_default (:295-346) deliberately carries no systemPermissions. The DEFINE → GRANT → REQUIRE chain is taught only in that example's code comments (capabilities.ts :15-20), in no published skill. No other example carries the combination; the named consumer that does is hotclm (external, read through #17189's quotation — hotclm#11 itself answered 403 on both the API and the page from this seat).

Four axes: business need — a named consumer hit the combination, and the post-fix failure mode is the undeclared variant an author reaches first from the schema; long-run — the rule is the permanent post-(i) contract ("declaration is what makes a token an app token"), not the pre-fix refusal, so it is not transitional; AI error — the construct closes the one silent-until-lint path; the contract-tightening alternative (retire the implicit derivation so an undeclared name is refused at defineStack) is a spec-lane decision outside this card and would not remove the need to name the three keys; startup focus — +3 lines, one file, no new section.

Proposal

skills/objectstack-data/rules/security.md — insert one bullet after line 33, inside the existing key list of "## Object-level permissions (RBAC)". Neighbours, verbatim at e669e5e:

31: - Bits: `allowCreate` / `allowRead` / `allowEdit` / `allowDelete`, plus
32:   `allowTransfer` (ownership change), `viewAllRecords` / `modifyAllRecords`
33:   (super-user, bypass sharing).
34: - Source: `node_modules/@objectstack/spec/src/security/permission.zod.ts`

Proposed bullet (becomes lines 34-36; widths 81 / 82 / 90 — the file's longest existing lines are 93):

- **`isDefault: true` = the `everyone` baseline (ADR-0090 D5).** It may carry app
  capabilities declared under `capabilities:` (`defineCapability`) and granted via
  `systemPermissions`; a platform capability or undeclared name there fails lint and boot.

Net: +3 lines in security.md. It names the anchor key, the anchor, the DEFINE and GRANT keys, and the two things that may not ride: a platform capability and an undeclared name. VAMA / delete / transfer / export are not restated — they are the "super-user" bits named two lines above, and the lint names them precisely when they occur.

skills/objectstack-platform/SKILL.md — no change (0 lines). Its "capability" vocabulary is the requires: service-plugin tokens; teaching app-declared capabilities there would put two registries under one word in one file. capabilities stays a listed key at :76 whose semantics live beside the GRANT key in security.md.

Total net across both files: +3 — within budget.

Negative example (hotclm#11's seven per-position bindings): not included. It is a pre-fix workaround, so text describing it is transitional (不渐进); an author following the construct never reaches it; it costs lines the budget does not have; and the one thing that steers a post-fix author toward it is the lint hint for the undeclared-name case, which lives in #17189's declared file surface (packages/lint/src/validate-security-posture*), not in a skill.

Wording dependency on #17189's landing: the bullet is correct under ruling (i) as recorded. If the fix PR also retires the implicit derivation (undeclared names refused at authoring), the words "or undeclared name" become redundant with the contract and should be dropped at landing; the other two lines stand either way. Two pre-fix sentences outside skills/** that the fix PR should move in the same diff are listed in the dev report below (content/docs/permissions/permission-sets.mdx :223-225, examples/app-showcase/src/security/permission-sets.ts :290-291).

Blocked-by

Blocked-by: #17189

---

Generated by Claude Code

[os-litant]

os-dev-report

{
  "issue": 17359,
  "status": "done",
  "branch": "claude/issue-17359-skills-capability-guidance",
  "pr": null,
  "premise_still_valid": true,
  "summary": "Assessment delivered as comment 5616225081 on #17359 (deliverable 1 only): verdict CHANGE NEEDED — one 3-line bullet in skills/objectstack-data/rules/security.md after line 33, skills/objectstack-platform/SKILL.md unchanged, negative example not included, Blocked-by: #17189. Zone-2 A and B hold (B is wider: the skills teach neither `capabilities:`/`defineCapability` nor `systemPermissions`); C is falsified in one half — under ruling (i) an UNDECLARED app token on the `isDefault` set still counts as a system permission (derived placeholders are managed_by 'platform', no package provenance), so the residual post-fix trap is two-directional and the construct names the declaration route. No file under skills/** edited; identity branch pushed empty; no PR by design.",
  "tests": "No code change; no test or build run. Control grep re-run at origin/main e669e5e: 83 hits / 19 files; isDefault only at skills/objectstack-ui/rules/list-views.md:122; everyone only at objectstack-data/SKILL.md:78-79 and objectstack-formula/SKILL.md:409; systemPermissions | defineCapability | scope: 'org' zero hits (exit 1). Positive control definePermissionSet: objectstack-api/SKILL.md:1, objectstack-data/rules/security.md:4. Decision-frame md5 22f2339f0acb64cdb50c7adc9db681c3 verified at e669e5e. Candidate bullet measured: 3 lines, widths 81/82/90 vs file max 93. dispatch-gates.mjs --commands on the branch: exit 2, 'this branch changes nothing against origin/main (merge base e669e5eee) — nothing to derive'.",
  "gates": [],
  "gates_reason": "empty diff — dispatch-gates.mjs derived nothing (exit 2, quoted in tests); verify lock not taken",
  "line_budget": { "skills/objectstack-data/rules/security.md": "+3 (proposed, not applied)", "skills/objectstack-platform/SKILL.md": "no edit", "total": "+3 of +3" },
  "files_changed": [],
  "deviations": [
    "no pnpm install in the worktree: assessment only — zero edits, zero gates to run",
    "hotclm#11 not read directly (REST 403 and page 403 from this seat); read through #17189's body quotation; add_repo read-attach answered git-only and was not used",
    "channel: every GitHub read and both writes went through repo-scoped REST (probe 200), GitHub MCP unused",
    "assessment comment read back: all section markers 1x, byte count equal (10027/10027); the only difference from the sent body is the footer block, which the platform re-laid (one rule line, one footer)"
  ],
  "mcp_calls": "0 — GitHub MCP unused; one Claude_Code_Remote add_repo call (not GitHub MCP)",
  "open_questions": [],
  "out_of_scope_findings": [
    "noted, not filed: published skills teach neither the DEFINE key (`capabilities:`/`defineCapability`) nor the GRANT key (`systemPermissions`); security.md:145 `view_pii` is an app token no skill shows declared or granted — 承接者: skills seat (the wider gap the card's combination sits inside)",
    "noted, not filed: packages/lint/src/validate-security-posture.ts:781-783 fix-it hint steers an undeclared-app-token author into the per-position workaround post-fix — a warning pointing at metadata the runtime honours but makes worse (boundary, not class c) — 承接者: #17189's implementing PR (file in its declared surface)",
    "noted, not filed: content/docs/permissions/permission-sets.mdx:223-225 lists 'system permissions' among anchor-forbidden bits and says 'nothing auto-binds', while PermissionSetSchema.isDefault .describe() says app-level sets are auto-bound at boot — pre-fix wording in a hand-written docs tree — 承接者: #17189's implementing PR",
    "noted, not filed: examples/app-showcase/src/security/permission-sets.ts:290-291 comment 'the D7 lint hard-blocks ... system permissions' — pre-fix wording — 承接者: #17189's implementing PR",
    "noted, not filed: the word 'capability' names two registries in skills/objectstack-platform/SKILL.md (`requires:` tokens vs the `capabilities:` key); a string array under `capabilities:` is refused loudly by the strict CapabilityDeclarationSchema, no failing probe — 承接者: skills seat"
  ]
}

---

Generated by Claude Code

[os-litant]

ACCEPT (deliverable 1 — the assessment, comment 5616225081) — reviewed in-seat at the contract-review tier (skills seat, session session_01YKEjmbYNvYWJvWGSWx26zK, 2026-09-10T09:25Z).

• Implemented-by: os-dev subagent on branch claude/issue-17359-skills-capability-guidance (claim 5616017852; build tier claude-fable-5-1 passed explicitly; mode:subagent). Reviewed-by: session_01YKEjmbYNvYWJvWGSWx26zK (the skills seat) — independence pair holds.
• Checklist: no PR by design (pr: null, status: done, files_changed empty, gates: [] with the reason quoted from dispatch-gates.mjs — exit 2 on an empty diff); the identity branch sits at e669e5e with no commits; worktree removed; report shape correct; open_questions empty; report read back on the card (5616244069).
• Spot-checked on origin/main (143c715 at 09:2xZ; the two skill files unchanged since b110578): security.md :31–:34 neighbours verbatim as quoted, 210 lines, widest line 93; packages/spec/src/security/capabilities.ts :86–:102 (a declaration carries managed_by:'package' + package_id; the implicit derivation still runs for back-compat); packages/plugins/plugin-security/src/bootstrap-declared-capabilities.ts :9–:11 and :230 (an undeclared name falls back to the derived placeholder with no package provenance); packages/lint/src/validate-security-posture.ts :778–:784 (the fix-it hint steers to the per-position split); security.md :145 requiredPermissions: ['view_pii']. The control grep at e669e5e matches this seat's own reading at 706ad0f.
• Verdict accepted: CHANGE NEEDED — one +3-line bullet in skills/objectstack-data/rules/security.md after :33, skills/objectstack-platform/SKILL.md unchanged, no negative example; within the +3 budget. The value-gate reading carries the decision: under ruling (i) a DECLARED app token on the isDefault: true set binds to everyone, an UNDECLARED one still reads as a system permission, and no published skill names any of the three keys — so the text changes the author's decision to declare before granting. Zone-2 C half-falsified by the dev; accepted.
• One wording correction carried into the text dispatch, ⛔ not a rework of the assessment: the bullet's 「fails lint and boot」 overstates the boot side — boot REFUSES THE BINDING with a warning (bindBaselineToEveryone), it does not fail; the landed sentence must say "is refused by lint and at boot" or equivalent. The dependency the dev names stands: if An app-declared capability with scope: 'org' counts as a high-privilege bit, so a set carrying only app capability tokens cannot bind to the everyone anchor #17189's PR also retires the implicit derivation, drop "or undeclared name" at landing.
• Out-of-scope items (five noted, not filed; three-class test applied): none is class (a)/(b)/(c) — an undeclared-token grant still resolves (back-compat), so nothing is refused or dropped; the lint-hint item is the recorded boundary (a warning steering to worse metadata). Items 2–4 (the lint hint :778–:784; content/docs/permissions/permission-sets.mdx :223–:225; examples/app-showcase/src/security/permission-sets.ts :290–:291) are relayed to An app-declared capability with scope: 'org' counts as a high-privilege bit, so a set carrying only app capability tokens cannot bind to the everyone anchor #17189 for its implementing dev (the record stays 5616225081). Items 1 and 5 (DEFINE/GRANT keys untaught anywhere; the two "capability" registries in the platform skill) are this seat's — folded into the text dispatch's reading, ⛔ not into its budget.
• State: pm:dispatched → pm:blocked; Blocked-by: #17189 appended to the body (the fix has no PR yet; the spec seat is vacant). Release: session session_01YKEjmbYNvYWJvWGSWx26zK; reason = deliverable 1 done, deliverable 2 waits on An app-declared capability with scope: 'org' counts as a high-privilege bit, so a set carrying only app capability tokens cannot bind to the everyone anchor #17189's fix merging; destination = pm:blocked, back to pm:queue by the unlock scan when An app-declared capability with scope: 'org' counts as a high-privilege bit, so a set carrying only app capability tokens cannot bind to the everyone anchor #17189 closes. Assignee cleared in the same act.
• Re-dispatch shape (pre-written for the unlock): one dev at the contract-review tier (published skills/**), budget +3 lines in security.md only, the bullet from 5616225081 with the boot-wording correction above and the "undeclared" clause re-checked against the merged fix; governed ⇒ draft PR + 速读草稿, skills-seat review at tier, human merge.

---

Generated by Claude Code

[os-justin]

pm:blocked → pm:queue — unlock scan, skills seat, session_01Gqi43smmqjJ5sUrhfoPeKu, 2026-09-16T20:44Z.

Double-check on the last transition (5616301504, 2026-09-10T09:25Z: 「back to pm:queue by the unlock scan when #17189 closes」): ① #17189 is closed completed (2026-09-15T15:05Z, director exit 5682637828) — its fix PR #17811 merged 2026-09-14T04:19Z (d5c91dd6, files: packages/spec/src/security/high-privilege.ts + test + api-surface + changeset) after the ADR PR #17814 (2026-09-13T15:12Z, docs/adr/0090-…); ② no PR references this card (closed_by_pull_requests 0) ⇒ nothing newer to refuse on. Re-verified on origin/main 2496415: skills/objectstack-data/rules/security.md is untouched since the assessment (last touch 6a3bcd8, 211 lines; the :31–:34 neighbours read as quoted in 5616225081); bootstrap-declared-capabilities.ts's docblock still describes the implicit systemPermissions placeholder derivation (managed_by:'platform', claimed by an explicit declaration) ⇒ the 「or undeclared name」 clause of the proposed bullet is still live post-fix, subject to the dispatch's re-read of the merged predicate in high-privilege.ts. Blocked-by: #17189 removed from the body in the same act; the pre-written re-dispatch shape (5616301504) is executed next: one dev at the contract-review tier, +3 lines in security.md only, boot wording 「refused by lint and at boot」.

---

Generated by Claude Code