[P2] AI scope keys declared but unenforced: skill.permissions + agent.knowledge (enforce-or-prune)

[os-zhuang]

Split out of the #1878 §3 naming-drift recheck (#3677). The ledger has been made honest about these (#3685 marks both dead + authorWarn); this issue tracks the actual enforce-or-prune decision, which needs a product call and a cloud-side change.

Common shape

Both are declarative scope keys in the AI domain whose declaration face is in the open spec while their enforcement face would live in the closed cloud runtime — and the wire between them was never connected.

1. skill.permissions — no gate

• Spec: packages/spec/src/ai/skill.zod.ts:121
• Consumers: skill.form.ts (authoring input) + objectui SkillPreview.tsx:48 (echo). No gate. The cloud SkillRegistry reads active, triggerConditions, tools, labels/instructions/triggerPhrases — never permissions.
• The Studio form labels the section "Access / Required permissions to use this skill" — a security-shaped promise with nothing behind it.
• Cloud documents the intent without implementing it — packages/service-ai-studio/src/skills/metadata-authoring-skill.ts:15:

  - Layer permissions via Skill.permissions independent of the agent's permissions.

• Note the live sibling: agent-level access/permissions are enforced (evaluateAgentAccess → 403, [P0][security] Agent access control is a no-op (permissions/visibility/access) #1884). So the mechanism exists; skill-level was simply never wired.

Decision needed: is skill-level gating a real requirement (the argued case: one agent serving different users should expose different skills — e.g. a refund skill only to managers), or is agent-level gating sufficient?

• Yes → wire it in cloud (registry filters the skill set by the caller's permissions), then flip the ledger back to live with a real proof.
• No → prune permissions from SkillSchema (breaking, minor per launch-window policy) and drop the misleading form section. Precedent: agent visibility was pruned for exactly this "security-shaped field that lies" reason ([P2][security] Enforce agent visibility (organization/private) — context now has tenant (ADR-0095); needs owner/org anchor on the agent #1901).

2. agent.knowledge — declares a scope the runtime ignores

• Spec: packages/spec/src/ai/agent.zod.ts:35-48 (the topics→sources naming drift itself is fixed, [P2] Naming drift → silent no-ops (spec key ≠ consumed key) #1891).
• The retrieval path takes sourceIds from the LLM's tool-call arguments (cloud service-ai/src/tools/knowledge-tools.ts:96), never from the agent record. So an agent declared with knowledge: { sources: ['public_faq'] } can still search any other source the service exposes.
• This is arguably not just inert config but a scope gap: the author declared a boundary and the model can step outside it.

Decision needed: wire agent.knowledge.sources as the default/ceiling for sourceIds (small change at the tool seam — but it is a behaviour change: today the LLM chooses freely), or mark it experimental and rely on knowledge-source-level access control.

Also worth scheduling: verify the other ten preview-only live claims

The same 2026-06 sweep marked 13 properties live citing only a preview renderer. Three were re-verified and all three were wrong or misleading (see #3685). The remaining ten are unverified:

action.execute / action.shortcut / action.bulkEnabled, flow.status / flow.active, skill.triggerPhrases, tool.category / tool.requiresConfirmation / tool.active / tool.builtIn

Each needs the same treatment: find a real runtime reader or downgrade to dead + authorWarn.

Refs #1878, #3677, #3685, #1884, #1891.

[os-zhuang]

Owner decisions

1. skill.permissions → PRUNE. Shipping in #3704 (framework) + objectstack-ai/objectui#2874 (preview panel). Skill-level gating was a documented intent, never an implementation; a security-shaped field that enforces nothing is worse than none. Access stays gated where it is real: agent-level access/permissions (403 at the chat route, #1884) or the underlying actions the skill's tools call (permission sets, ADR-0066). If skill-level gating is wanted later it returns as a designed, enforced feature — the schema shape is trivial to re-add.

2. agent.knowledge → PAUSED. Not a priority this phase. It keeps the honest state set in #3685 — dead + authorWarn with a hint explaining that search_knowledge takes sourceIds from the LLM's tool-call arguments, so a declared knowledge.sources does not scope retrieval. Authors get a warning instead of a false promise. Re-open the wiring question when knowledge/RAG becomes an active workstream; the scope-gap framing (an agent can search sources it was never scoped to) is the reason to do it then.

What stays open on this issue

Only the third item: verify the ten remaining preview-only live claims — action.execute / action.shortcut / action.bulkEnabled, flow.status / flow.active, skill.triggerPhrases, tool.category / tool.requiresConfirmation / tool.active / tool.builtIn. Each needs a real runtime reader cited, or a downgrade to dead + authorWarn.

Worth noting for whoever picks that up: of the three preview-only claims verified so far, all three were wrong or misleading, and the cheapest sound method turned out to be author the key and watch the running app, not grep for readers (see the methodology note in docs/audits/2026-07-naming-drift-recheck.md).

[os-zhuang]

Sweep complete — all 13 preview-only claims re-verified

Final tally: 3 stand as live, 10 were wrong (77% error rate for the preview-renderer standard). Corrections shipped in #3685 (first three) and #3711 (the last ten).

Verdict	Properties
live, evidence corrected to the real reader	action.execute, action.disabled, flow.status
corrected → dead + authorWarn	action.shortcut, action.bulkEnabled, flow.active, skill.triggerPhrases, tool.category, tool.requiresConfirmation, tool.active, tool.builtIn, agent.knowledge
pruned outright	skill.permissions (#3704 — owner decision)

flow.json's file-level note ("status/active gate nothing") was also rewritten: true when written, falsified a month later by 497bda853.

Spun out into their own issues

• [P2] action execute vs target: spec and objectui resolve the precedence in OPPOSITE directions #3713 — action.execute vs target: spec keeps target, objectui ActionRunner keeps execute. An action declaring both runs different code on the two sides. Behavioural bug, not a ledger problem.
• [P3] liveness: action.undoable is marked experimental but has two real runtime readers #3714 — action.undoable is marked experimental but has two real runtime readers (useConsoleActionRuntime.tsx:409, RecordDetailView.tsx:545). Errs in the understating direction.
• [P2] Execute ADR-0033's deletion of the unenforced tool.requiresConfirmation (safety-shaped, gated by nothing) #3715 — execute ADR-0033's already-recorded decision to delete tool.requiresConfirmation, or wire it. Safety-shaped, gated by nothing, and the authoring surface teaches reliance on it.

The durable lesson (recorded in packages/spec/liveness/README.md)

Two failure directions, not one: entries overstate liveness (a preview panel counted as a consumer) and understate it (flow.status, action.undoable — code moved under a correct-at-the-time note). A ledger entry is a claim with a timestamp.

And three concrete search traps produced false negatives during this work, each of which reached a published document before being caught:

1. … | head -3 truncated away the real hit;
2. a pathspec glob packages/*/src never matched nested paths;
3. macOS git grep -E silently ignores \b — git grep -cE "\.active\b" returns nothing on a file with three .active occurrences.

A grep proves presence only. To prove absence: close the call graph by hand, or author the property and watch the running app.

Closing — the remaining work lives in #3713 / #3714 / #3715.