From 049b5574aaa9bfc55c95948d9c0feafcd3db4a35 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 11 Aug 2026 07:55:10 +0000 Subject: [PATCH] docs(spec): state that skill.permissions is REJECTED, not silently stripped (#7567) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `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 --- .../skill-permissions-docblock-truth.md | 30 +++++++++++++++++++ packages/spec/src/ai/skill.zod.ts | 6 ++-- 2 files changed, 34 insertions(+), 2 deletions(-) create mode 100644 .changeset/skill-permissions-docblock-truth.md diff --git a/.changeset/skill-permissions-docblock-truth.md b/.changeset/skill-permissions-docblock-truth.md new file mode 100644 index 0000000000..1367d18f46 --- /dev/null +++ b/.changeset/skill-permissions-docblock-truth.md @@ -0,0 +1,30 @@ +--- +"@objectstack/spec": patch +--- + +docs(spec): state that a `permissions` key on a skill is REJECTED, not stripped (#7567) + +`SkillSchema`'s docblock carried a `NOTE` paragraph saying an authored +`permissions` key "is unknown to this schema and silently stripped at parse +time." That was true once, but the behaviour changed: `SkillSchema` is a +`strictObject` whose `guidance.permissions` entry now REFUSES an authored +`permissions` key 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. + +Only the `NOTE` paragraph's wording changes: it now says the key is rejected +at parse time and points at the located refusal message +(`guidance.permissions`) below it in the same file. The refusal message +itself is untouched — its own "this was stripped in silence" phrase narrates +the historical reason for the refusal, not current behaviour, and stays +correct as written. Every input parses byte-identically before and after this +change (`git diff` touches only comment lines); `pnpm --filter @objectstack/spec +typecheck` and the full spec test suite (9840 tests) are green, and +`check:docs` reports all 231 generated files still in sync — this paragraph +is an inner/property-level TSDoc comment, not the module-level blurb +`build-docs.ts` renders, so no generated doc changes. + +Adds a patch changeset for `@objectstack/spec`, following the #7444 / #7473 / +#7565 precedent for describe/TSDoc-only spec docs fixes. diff --git a/packages/spec/src/ai/skill.zod.ts b/packages/spec/src/ai/skill.zod.ts index ef9a53ab7e..c9f5c0988e 100644 --- a/packages/spec/src/ai/skill.zod.ts +++ b/packages/spec/src/ai/skill.zod.ts @@ -240,8 +240,10 @@ export type SkillTriggerCondition = z.input; * capability is gated at the AGENT level (`agent.access` / `agent.permissions`, * both enforced at the chat route), and each tool enforces its own authz when * invoked. A `permissions` key authored on a skill is unknown to this schema - * and silently stripped at parse time — it grants and restricts nothing - * (ADR-0049: no unenforced security-shaped fields). Do not author one. + * and is REJECTED outright at parse time, with a located message keyed on + * `permissions` (see `guidance.permissions` below) pointing the author at the + * agent-level gate instead (ADR-0049: no unenforced security-shaped fields). + * Do not author one. * * @example * ```ts