@@ -0,0 +1,39 @@
+---
+'@objectstack/lint': patch
+---
+
+`ai-skill-tool-unresolved` is a whole-stack verdict by design: `os validate` / `os lint` / `os build` report it, and the runtime publish gate never does (#19527)
+
+A skill's `tools[]` entries resolve against three sources: `stack.tools`, the
+platform tool registry, and the `action_<name>` tools materialised from
+AI-exposed actions. The runtime publish gate judges one written item against a
+per-write snapshot that carries neither `stack.tools` nor `stack.actions`, and
+no snapshot can carry a tool that a runtime plugin registers outside the
+registry. At that door the rule could only ever produce a false
+`ai-skill-tool-unresolved`: a skill naming a real stack-level action would be
+told the tool does not exist. The ruling on #19527 (letter B) places this
+check at the whole-stack rule, following ADR-0109 Decision §3, and keeps the
+per-write snapshot as it is.
+
+`skill` was already outside the runtime gate. The earlier comments called that
+a temporary hold-out, pending a wider snapshot. They now describe it as the
+design, so no later change should add `actions` / `tools` to the snapshot in
+order to move this check onto the door. New tests pin both halves:
+
+- a `skill` write through the runtime gate gets no tool-reference finding. This
+  holds for a stack-level action tool, a plugin-registered tool, and a tool
+  that exists nowhere. No other write type can put a skill into a door
+  snapshot;
+- `validate`, `build` and `lint` still report a tool that exists nowhere, at
+  warning severity, and do not report the stack-level action that resolves.
+
+⛔ No behaviour changes. Before and after this change, the runtime gate runs no
+rule for a `skill` write, and the whole-stack commands report the same
+findings. No authorable key, accept set or export changes.
+
+**This ships, so it carries a changeset rather than `skip-changeset`.**
+`@objectstack/lint` publishes `dist`, and its build keeps source comments. A
+rebuilt artifact shows the reworded block in `dist/index.js`,
+`dist/index.cjs`, `dist/runtime.js` and `dist/runtime.cjs`, and the old
+wording (「held out on a measurement」) in none of them. So the published JS
+bytes change, but behaviour and the declaration surface do not.
@@ -907,14 +907,24 @@ export const AUTHORING_RULES: readonly AuthoringRule[] = [
     // MEMBERS judge that snapshot. A `report` write reaches exactly
     // `validateChartBindings`. Every other member keeps its declaration.
     //
-    // ⛔ `skill` is NOT here. It was crossed in an earlier revision of this
-    // card and is held out on a measurement: `validateAiToolReferences`
-    // resolves into `stack.tools` and `stack.actions`, neither of which the
-    // per-write snapshot carries, so the shipped corpus's own AI-exposed
-    // stack-level action reads as unresolved at the door and the rule ships a
-    // false advisory into Studio. The member carries the measurement; the type
-    // takes the ruling's group B treatment of `tool`, the same universe
-    // obstacle read from the other side.
+    // ⛔ `skill` is NOT here, BY DESIGN: cross-item reference resolution
+    // belongs to the whole-stack rule (ruling `5791822697` on #19527, letter
+    // B; ADR-0109 Decision §3). `ai-skill-tool-unresolved` is a verdict of
+    // `os validate` / `os lint` / `os build`, and this door NEVER emits it.
+    // `validateAiToolReferences` resolves a skill's tools against a universe of
+    // three limbs — `stack.tools`, the platform registry and the materialised
+    // `action_<name>` family — and a per-write snapshot carries neither
+    // `stack.tools` nor `stack.actions`, while a tool a runtime plugin
+    // registers outside the registry is invisible to every static universe.
+    // So at this door the member has no truthful `unresolved` verdict to give:
+    // the shipped corpus's own AI-exposed stack-level action reads as
+    // unresolved here and resolves over the whole stack (the reason pin is the
+    // LIT case in `runtime-gate.inert-type-writes.test.ts`). ⛔ Not a hold-out
+    // awaiting a wider snapshot: the ruling rejected carrying `actions` /
+    // `tools` in `RuntimeStackContext` (a read on every gated write that still
+    // leaves the plugin limb false). The member keeps the frozen `flow` default
+    // and `skill` has no `TYPE_TO_STACK_KEY` row: with no rule to run it is not
+    // a runtime-gated type, so the wiring guard's invariant asks no row of it.
     //
     // ⛔ `action` and `hook` are deliberately NOT here, although this card
     // crosses both types on `validateStackExpressions` above. The suite carries
 
@@ -460,45 +460,50 @@ export const REFERENCE_INTEGRITY_RULES: readonly ReferenceIntegrityRule[] = [
   { name: 'validateTranslatableSections', run: validateTranslatableSections },
   { name: 'validateFlowTemplatePaths', run: validateFlowTemplatePaths },
   { name: 'validateAiSurfaceAffinity', run: validateAiSurfaceAffinity },
-  // [#19542] NO `runtimeTypes`, i.e. the frozen `flow` default — and `skill` is
-  // HELD OUT of the ADR-0049 wiring deliberately, on a measurement, not
-  // forgotten. This member is the measurement's named bridge for the type and
-  // it does read the written skill as its subject (`recordsOf(stack.skills)`,
-  // findings pathed `skills[si].tools[ti]`), so on paper it crosses. What
-  // stops it is the UNIVERSE it resolves into.
+  // [#19542, #19527] NO `runtimeTypes`, i.e. the frozen `flow` default — and
+  // `skill` stays outside the runtime publish door BY DESIGN: cross-item
+  // reference resolution belongs to the whole-stack rule (ruling `5791822697`
+  // on #19527, letter B). `ai-skill-tool-unresolved` is a verdict of
+  // `os validate` / `os lint` / `os build` and the door NEVER emits it. The
+  // governing text is ADR-0109 Decision §3: `skill.tools[]` reference
+  // integrity is decided by THIS member over the WHOLE stack, at warning
+  // severity, because a runtime plugin outside the registry stays statically
+  // invisible and the runtime deliberately tolerates unresolved names.
   //
+  // This member does read the written skill as its subject
+  // (`recordsOf(stack.skills)`, findings pathed `skills[si].tools[ti]`), so on
+  // paper it could cross. What rules it out is the UNIVERSE it resolves into.
   // `collectToolUniverse` unions `PLATFORM_PROVIDED_TOOL_NAMES` ∪
   // `stack.tools` ∪ the materialised action family from `stack.actions` and
   // every object's `actions`. A per-write snapshot carries `objects` — so an
-  // object-level `action_<name>` resolves — but NEITHER `tools` NOR `actions`.
-  // Two of the three limbs are missing, so at this door the rule has no
-  // truthful `unresolved` verdict at all: only its CLEAN answers are reliable.
+  // object-level `action_<name>` resolves — but NEITHER `tools` NOR `actions`,
+  // and no snapshot can carry a tool a runtime plugin registers. So at this
+  // door the member has no truthful `unresolved` verdict at all: only its
+  // CLEAN answers are reliable.
   //
-  // ⚠️ Measured on the SHIPPED corpus, not synthetically. `app-showcase`
-  // declares exactly one AI-exposed action, `showcase_portfolio_snapshot`, and
-  // it exists at stack level only (todo's six are mirrored under
-  // `objects[].actions`, so those resolve; crm has none). A skill naming
-  // `action_showcase_portfolio_snapshot` is advised `ai-skill-tool-unresolved`
-  // at the door while the same member over the whole showcase stack answers
-  // `[]`. The advisory's own hint tells the author to declare the action and
-  // opt it in with `ai.exposed: true` — which is exactly what the author did —
-  // and it reaches `SaveMetaItemResponseSchema.advisories`, which Studio
-  // renders. A user would see a warning that is not true.
+  // ⚠️ The reading, measured on the SHIPPED corpus rather than synthetically:
+  // `app-showcase` declares exactly one AI-exposed action,
+  // `showcase_portfolio_snapshot`, and it exists at stack level only (todo's
+  // six are mirrored under `objects[].actions`, so those resolve; crm has
+  // none). A skill naming `action_showcase_portfolio_snapshot` would be
+  // advised `ai-skill-tool-unresolved` on the door's snapshot while the same
+  // member over the whole showcase stack answers `[]`, and the advisory would
+  // reach `SaveMetaItemResponseSchema.advisories`, which Studio renders. That
+  // is the reason pin — the LIT case in
+  // `runtime-gate.inert-type-writes.test.ts` — not a wait state.
   //
-  // ⛔ ADR-0109 does NOT bound this. Its 「the default path declares no tool
-  // records」 covers tool RECORDS; the `action_<name>` family IS that default
-  // path, so the bound argues the opposite way.
-  //
-  // So the type takes the ruling's OWN group B treatment of `tool` — 「the
-  // `tools` universe rule … can only remove findings ⇒ a reading, not a
-  // ruling」 — which is this same rule read from the other side. Crossing it
-  // needs `actions` / `tools` carried in `RuntimeStackContext` +
-  // `CONTEXT_STACK_KEYS`, a `CLOSURE_CONTEXT_KEY_BY_TYPE` row and two more
-  // door gathers in `@objectstack/metadata-protocol` — a second package, a
-  // snapshot widening on EVERY gated write, and its own card. `skill` has no
-  // `TYPE_TO_STACK_KEY` row either, so the two absences are CONSISTENT and the
-  // gate dispatches nothing for it; `runtime-gate.inert-type-writes.test.ts`
-  // holds both absent and records the measurement that put them there.
+  // ⛔ Not a hold-out awaiting a wider snapshot. The ruling rejected carrying
+  // `actions` / `tools` in `RuntimeStackContext` + `CONTEXT_STACK_KEYS`: that
+  // costs an indexed read on EVERY gated write, the hot `object` / `flow`
+  // doors included, and still leaves the plugin limb false — a narrower false
+  // advisory, not a true one. `skill` has no `TYPE_TO_STACK_KEY` row either,
+  // so the two absences are CONSISTENT and the gate dispatches nothing for it.
+  // With no rule to run, `skill` is not a runtime-gated type under the wiring
+  // guard's invariant (「every runtime-gated metadata type maps to a stack
+  // key」), so that invariant asks no row of it; a row with no declaring rule
+  // is the inert mapping-ahead-of-its-rules shape `runtime-gate.ts` refuses,
+  // and inventing a rule to give the door something to run is refused by the
+  // same ruling. `runtime-gate.inert-type-writes.test.ts` holds both absent.
   { name: 'validateAiToolReferences', run: validateAiToolReferences },
   { name: 'validateAiAgentAuthoring', run: validateAiAgentAuthoring },
   // Field names WRITTEN by an L2 hook body (`ctx.input.x = …`,
 
@@ -257,7 +257,9 @@ describe('#19568 — the hold-out test: what the door sees is what the whole sta
     // The `skill` measurement (#19527), asked of this type. There, the door's
     // snapshot lacked `stack.tools` / `stack.actions`, so one rule produced
     // `ai-skill-tool-unresolved` at the door and `[]` over the whole stack —
-    // a falsehood rendered in Studio, and the reason that type is held out.
+    // a falsehood rendered in Studio, and the reason that type stays outside
+    // the door by design (ruling `5791822697`: cross-item reference resolution
+    // belongs to the whole-stack rule).
     //
     // Here the two runs are the same rule over the same written item, once in
     // the shape a per-write snapshot has (objects + the written collection),
@@ -356,8 +358,9 @@ describe('#19568 — DARK: what this crossing did NOT widen', () => {
 
   it('the types still awaiting their own readings are untouched', () => {
     // The standing ungated controls: group B reads `translation` / `tool`
-    // first, group D retires `doc` / `external_catalog`, and `skill` is held
-    // out on the measurement this file tested itself against.
+    // first, group D retires `doc` / `external_catalog`, and `skill` stays
+    // outside the door by design (ruling `5791822697` on #19527), for the
+    // reason this file tested itself against.
     expect(runtimeAuthoringRulesFor('translation')).toEqual([]);
     expect(runtimeAuthoringRulesFor('tool')).toEqual([]);
     expect(runtimeAuthoringRulesFor('doc')).toEqual([]);