docs(spec): state that skill.permissions is REJECTED, not silently stripped (#7567) - #7610
Merged
Merged
Conversation
…ripped (#7567) `SkillSchema`'s docblock NOTE paragraph said an authored `permissions` key "is unknown to this schema and silently stripped at parse time." The behaviour changed since that was written: the key is now REFUSED outright by `guidance.permissions`, with a located message telling the author to gate at the agent level instead. Rewrite the NOTE paragraph to state the current truth and point at the refusal message below it in the same file. The refusal message itself is untouched — its own "stripped in silence" phrase narrates history, not current behaviour, and is correct as written. Every input parses byte-identically before and after (git diff touches only comment lines). Claude-Session: https://claude.ai/code/session_016R9de1FqP7NvwKvqXi92Gh
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 106 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
⛔ 7 release-owned page(s) also reference the affected code. These are read-only:
|
github-actions
Bot
added
documentation
os-help
marked this pull request as ready for review
August 11, 2026 08:34
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #7567
What was wrong
packages/spec/src/ai/skill.zod.ts'sSkillSchemadocblock carried aNOTEparagraph saying an authoredpermissionskey "is unknown to this schema and silently stripped at parse time." That was true once, but the behaviour changed:SkillSchemais astrictObjectwhoseguidance.permissionsentry now REFUSES an authoredpermissionskey outright, with a located message telling the author to gate at the agent level instead (agent.access/agent.permissions, enforced since #1884). The docblock's stale present tense was the only thing still saying "stripped" — a reader could conclude the authoring surface was still lax exactly where it is now strict.What changed
Only the
NOTEparagraph's wording. It now says the key is REJECTED outright at parse time and points at the located refusal message (guidance.permissions, ~line 284) below it in the same file. Still-true content is kept: no per-skillpermissionsfield by design, agent-level gating viaagent.access/agent.permissions, ADR-0049 rationale.⛔ The refusal message itself (
guidance.permissions, ~line 284) is untouched — its own "this was stripped in silence" phrase narrates the historical reason for the refusal, not current behaviour, and is correct as written per the card.git diffconfirms only comment lines changed:Every input parses byte-identically before and after this change.
Verification
pnpm --filter @objectstack/spec typecheck— green (tsc, check:scripts-typecheck, check:test-typecheck all pass).pnpm --filter @objectstack/spec test— full suite green: 375 test files / 9840 tests passed, 0 failed.skill.permissions— none found.packages/spec/src/ai/skill.test.ts's existing test (REJECTS a \permissions` key and points at the agent-level gate`) already asserts current (rejection) behaviour and needed no change.pnpm --filter @objectstack/spec gen:schemathencheck:docs— 231 generated files in sync, zero diff. TheNOTEparagraph is an inner/property-level TSDoc comment aboveSkillSchema, not the module-level first docblockbuild-docs.tsrenders as the page blurb (that'sSkillTriggerConditionSchema's docblock) — confirmed by greppingcontent/docs/references/ai/skill.mdxfor the NOTE text/silently stripped: no match, before or after.node scripts/check-nul-bytes.mjs— OK, no raw control bytes.Changeset
Added a patch changeset for
@objectstack/spec, following the #7444 / #7473 / #7565 precedent for describe/TSDoc-only spec docs fixes.Generated by Claude Code