skill-authoring §6: name the deployment runtime before the review concludes

skills/skill-authoring/SKILL.md

@@ -229,6 +229,65 @@ The sharpest usability probe is behavioral: give a fresh weaker-tier
 behavior down first, then patch the gaps the probe surfaces — not the ones
 you imagine.
 
+**A skill — or a plugin's instruction files — is under this section's
+review: verify the deployment runtime before the review concludes**
+(`unprobed` — private incident as shape; see Provenance). A skill
+verified only on the author's machine can pass every lens above and
+still be wrong where it will actually run: one reviewed-and-finalized
+skill was reworked wholesale when its real target — a sandboxed Linux
+VM, not the author's macOS — surfaced only after sign-off. §1's gate
+placement applies at authoring start: the target answer (or a recorded
+`user-must-provide`) is required before the first artifact-producing
+step; this review is the enforcement backstop, and it blocks adoption
+when the answer is missing. Confirm the review record — the same
+artifact as §7's change record, verbatim: "the PR description or commit
+message when one is being created, otherwise the completion report" —
+names the target runtime(s): the execution environment (OS, container,
+sandbox) and any governing connector or tool instance. Not named →
+read the repo's own deployment manifests and docs first, then obtain
+what they cannot tell you from the requester; no answer → write
+`user-must-provide` in the record; adoption then proceeds ONLY under a
+recorded risk acceptance by whoever owns the deployment — that
+acceptance is an alternate Done which still requires the sweep below
+and every in-file label; without it the artifact stays blocked.
+Named or not, always run the sweep for assumptions that silently bind
+the file to the author's machine — this list is a floor, not the
+ceiling: an accidentally machine-local repository path gets §2's
+remedy, verbatim ("Anchor to the VCS root (`git rev-parse
+--show-toplevel`) and verify the path prefix before reading"), while
+an absolute path the target itself defines (a socket, device, mount)
+is a machine-bound assumption like the rest; OS-specific launchers and
+helpers (URL-scheme opens, clipboard or notification tools), host
+identity (a literal hostname or username), wall-clock or timezone
+assumptions (a hard-coded TZ, a locale), instance-specific tool
+identifiers (a connector's tool prefix can be unique to the author's
+instance), and — for anything that executes programs — architecture,
+interpreter and dependency availability, runtime versions, filesystem
+semantics, permissions, and network reach. `runtime-agnostic` may be
+recorded only for pure instruction text with no executable dependency;
+anything that runs programs names its dimensions instead. Each
+machine-bound assumption keeps a verified portable form, or stays
+behind a verified target-scoped dispatch — which satisfies a named
+target only when that target ALSO keeps a working path for every
+capability the file claims (a foreign-OS-only branch is not
+compatibility) — or carries a label naming the exact runtime or
+instance required, written IN the skill file beside the dependency
+(§2's embed-the-knowledge; the review record points to it), verified
+against that instance where reachable and marked `unverified` (§2)
+where not: a label records a limitation, never proves compatibility.
+Done when every target runtime named in the record is compatible with
+every assumption reachable on it — a labeled incompatibility with a
+named target blocks completion, and shrinking the supported scope can
+only exclude an optional target with the requester's explicit say — or
+when the recorded risk acceptance above stands in; and everything
+machine-bound carries its named label in the file.
+✅ "target: sandboxed Linux VM plus the team's shared connector
+instance; the macOS-only notify helper replaced with the project's CLI
+logger; the connector prefix labeled in-file 'requires the shared
+instance' and resolved against it."
+❌ "labeled the launcher 'requires macOS' and concluded — while the
+named target is a Linux VM."
+
 Fix what blocks, then read back the final files to confirm they landed
 complete. When mining sessions or external material into skills, strip
 names/slogans first and keep a procedure only if it still has an apply-when,
@@ -397,4 +456,14 @@ marker per the README covenant: the external measurement is of one
 skill's one gate, and whether placement generalizes across gate types is
 exactly what an in-house probe would test — that probe has not been run;
 the marker records the debt.
+The §6 deployment-runtime rule (2026-07-21) comes from a private incident:
+a skill was authored, reviewed through the lenses above, and finalized for
+the author's local macOS environment, then rebuilt wholesale the same week
+when the user mentioned it would run inside a sandboxed Linux VM — host
+identity, launcher mechanism, and machine-local MCP tool-name assumptions
+all failed on the real target (contributor-reported; the private repo is
+verifiable by the contributor, not linkable here). Ships `unprobed` per the
+README covenant's second branch: no in-repo probe has run; the probe shape
+(give a weak-tier reviewer a machine-bound skill plus a named foreign
+runtime, observe whether the sweep fires) is recorded as debt.
 Stable method; no environment facts to re-verify.