skillscript-runtime 0.8.0 → 0.9.6

package/dist/lint.js

@@ -5,6 +5,7 @@ export async function lint(source, options) {
     const parsed = parse(source);
     const ctx = {
         parsed,
+        source,
         capabilityClasses: options?.classes ?? collectClassesFromRegistry(options?.registry),
         skillStore: options?.skillStore,
         hasSkillStore: options?.skillStore !== undefined,
@@ -14,6 +15,7 @@ export async function lint(source, options) {
         connectorConfigErrors: options?.connectorConfigErrors ?? [],
         mcpConnectorAllowedTools: options?.mcpConnectorAllowedTools ?? collectMcpConnectorAllowedToolsFromRegistry(options?.registry),
         agentConnectorNames: options?.agentConnectorNames ?? collectAgentConnectorNamesFromRegistry(options?.registry),
+        mcpConnectorStaticTools: collectMcpConnectorStaticToolsFromRegistry(options?.registry),
     };
     const findings = [];
     for (const rule of RULES) {
@@ -42,6 +44,7 @@ export function lintSync(source, options) {
     const parsed = parse(source);
     const ctx = {
         parsed,
+        source,
         capabilityClasses: options?.classes ?? collectClassesFromRegistry(options?.registry),
         skillStore: options?.skillStore,
         hasSkillStore: options?.skillStore !== undefined,
@@ -51,6 +54,7 @@ export function lintSync(source, options) {
         connectorConfigErrors: options?.connectorConfigErrors ?? [],
         mcpConnectorAllowedTools: options?.mcpConnectorAllowedTools ?? collectMcpConnectorAllowedToolsFromRegistry(options?.registry),
         agentConnectorNames: options?.agentConnectorNames ?? collectAgentConnectorNamesFromRegistry(options?.registry),
+        mcpConnectorStaticTools: collectMcpConnectorStaticToolsFromRegistry(options?.registry),
     };
     const findings = [];
     for (const rule of RULES) {
@@ -379,36 +383,47 @@ const INDENTATION = {
 };
 // v0.3.1: demoted tier-1 → tier-2. Forward-references are allowed; the
 // runtime throws `SkillNotFoundError` if the ref still can't resolve at
-// execute time. The tier-3 `deferred-skill-reference` advisory below
-// confirms the deferred-resolution path is engaged.
+// execute time. v0.9.4.1: paired `deferred-skill-reference` advisory
+// removed — the warning's remediation already explains the forward-ref
+// path; the second finding was just noise (per Perry's `77ed6c65`
+// "4 diagnostics for 2 missing skills" cold-author finding).
 const UNKNOWN_SKILL_REFERENCE = {
     id: "unknown-skill-reference",
     severity: "warning",
-    description: "An `&` or `$ execute_skill` op references a skill that's not present in the configured SkillStore. Lint warning (not error) since v0.3.1 — runtime throws `SkillNotFoundError` if still missing at execute time.",
+    description: "An `&` or `$ execute_skill` op references a skill that's not present in the configured SkillStore. Lint warning (not error) since v0.3.1 — runtime throws `SkillNotFoundError` if still missing at execute time. Dedup is per-missing-skill, not per-call-site (v0.9.4.1).",
     remediation: "If this is a typo, fix the spelling against your declarations. If it's a forward reference to a skill you'll author next, this warning clears once the skill is stored. The runtime will throw `SkillNotFoundError` at execute time if the skill is still missing.",
     check: async (ctx) => {
         if (ctx.skillStore === undefined)
             return [];
         const findings = [];
-        const seen = new Set();
+        // v0.9.4.1 — dedup by skill name (not via:name) so one missing skill
+        // referenced via both `&` and `$ execute_skill` (or from multiple
+        // targets) produces one diagnostic, not N. Per Perry's `77ed6c65`
+        // next-ring finding: "4 diagnostics for 2 missing skills" — the via
+        // and target list now folds into a single message.
+        const byName = new Map();
         for (const [targetName, target] of ctx.parsed.targets) {
             for (const ref of collectAmpRefsFromOps(target.ops)) {
-                const key = `${ref.via}:${ref.name}`;
-                if (seen.has(key))
-                    continue;
-                seen.add(key);
-                try {
-                    await ctx.skillStore.metadata(ref.name);
-                }
-                catch {
-                    findings.push({
-                        rule: "unknown-skill-reference",
-                        severity: "warning",
-                        message: `Skill '${targetName}' references skill '${ref.name}' via \`${ref.via}\`, but the SkillStore has no skill by that name.`,
-                        block: targetName,
-                        extras: { referenced_skill: ref.name, via: ref.via },
-                    });
-                }
+                const entry = byName.get(ref.name);
+                if (entry === undefined)
+                    byName.set(ref.name, { vias: new Set([ref.via]), firstTarget: targetName });
+                else
+                    entry.vias.add(ref.via);
+            }
+        }
+        for (const [name, { vias, firstTarget }] of byName) {
+            try {
+                await ctx.skillStore.metadata(name);
+            }
+            catch {
+                const viaList = Array.from(vias).map((v) => `\`${v}\``).join(" / ");
+                findings.push({
+                    rule: "unknown-skill-reference",
+                    severity: "warning",
+                    message: `Skill '${name}' is referenced via ${viaList} (first seen in target '${firstTarget}'), but the SkillStore has no skill by that name.`,
+                    block: firstTarget,
+                    extras: { referenced_skill: name, vias: Array.from(vias) },
+                });
             }
         }
         return findings;
@@ -531,6 +546,117 @@ const DISALLOWED_TOOL = {
         return findings;
     },
 };
+// v0.9.1 — `$ ref.tool` where `ref` is wired AND `allowed_tools` doesn't
+// exclude `tool` AND the connector class declares its static tool surface
+// AND `tool` is NOT in that declared surface. Tier-1 error.
+//
+// Closes the v0.9.0 multi-layer-promise recurrence (third in the
+// v0.7.2→v0.7.3→v0.9.0 series). Before v0.9.1, `disallowed-tool` only
+// fired when an explicit allow-list was configured; connectors with
+// `allowed_tools: undefined` (allow-all) green-lit any qualified tool
+// name. Runtime then failed downstream with misleading kwarg errors.
+//
+// The fix: connectors that ship with a closed static tool surface
+// (LocalModelMcpConnector → ["prompt"], MemoryStoreMcpConnector →
+// ["query", "memory_write"]) declare it via `staticTools()`; lint
+// validates qualified dispatches against that surface.
+//
+// Connectors WITHOUT a declared static surface (RemoteMcpConnector,
+// adopter classes) emit the tier-3 `unverified-qualified-tool`
+// advisory instead — see UNVERIFIED_QUALIFIED_TOOL below.
+const UNKNOWN_TOOL_ON_CONNECTOR = {
+    id: "unknown-tool-on-connector",
+    severity: "error",
+    description: "A qualified `$ ref.tool` op references a tool not declared on the connector class's static surface.",
+    remediation: "Use a tool from the connector's declared list (see `runtime_capabilities()` for the wired connector and its class). If the tool genuinely exists on the connector but isn't in the static list, that's a connector-class bug — file as such; for now use bare-form `$ tool ...` if the name-match dispatch reaches the right connector.",
+    check: (ctx) => {
+        if (ctx.mcpConnectorStaticTools.size === 0)
+            return [];
+        const findings = [];
+        const reported = new Set();
+        for (const [targetName, target] of ctx.parsed.targets) {
+            walkOps(target.ops, (op) => {
+                if (op.kind !== "$" || op.mcpConnector === undefined)
+                    return;
+                const ref = op.mcpConnector;
+                const declared = ctx.mcpConnectorStaticTools.get(ref);
+                if (declared === undefined || declared === null)
+                    return; // no info; UNVERIFIED rule handles
+                const m = /^([A-Za-z_][\w:-]*)/.exec(op.body);
+                if (m === null)
+                    return;
+                const toolName = m[1];
+                if (declared.includes(toolName))
+                    return;
+                // If an `allowed_tools` allowlist excludes the tool, `disallowed-tool`
+                // already fires — avoid double-reporting.
+                const allowed = ctx.mcpConnectorAllowedTools.get(ref);
+                if (allowed !== undefined && !allowed.includes(toolName))
+                    return;
+                const key = `${targetName}:${ref}:${toolName}`;
+                if (reported.has(key))
+                    return;
+                reported.add(key);
+                findings.push({
+                    rule: "unknown-tool-on-connector",
+                    severity: "error",
+                    message: `\`$ ${ref}.${toolName}\` in target '${targetName}' — tool '${toolName}' is not declared on connector '${ref}'. Declared tools: ${declared.length === 0 ? "(none)" : declared.join(", ")}. Use a declared tool, or wire a different connector that supports '${toolName}'.`,
+                    block: targetName,
+                    extras: { connector: ref, tool: toolName, declared_tools: declared },
+                });
+            });
+        }
+        return findings;
+    },
+};
+// v0.9.1 — tier-3 advisory for qualified dispatches against connectors
+// whose class doesn't declare a static tool surface. RemoteMcpConnector
+// is the canonical case: it wraps an arbitrary upstream MCP server, so
+// the tool list is only knowable at runtime via `tools/list`. Adopter
+// classes that don't implement `staticTools()` land here too.
+//
+// Surfaces as `info` (advisory) — author sees the hint, can proceed if
+// they know the tool exists. Pairs with the structural validateDispatch
+// extraction; the runtime still dispatches, and if the tool is missing
+// the connector-specific error surfaces at execute time.
+const UNVERIFIED_QUALIFIED_TOOL = {
+    id: "unverified-qualified-tool",
+    severity: "info",
+    description: "A qualified `$ ref.tool` op against a connector class without a static tool surface — can't validate at compile time.",
+    remediation: "Verify the tool exists on the connector before relying on this. RemoteMcpConnector adopters can use `runtime_capabilities()` to inspect the upstream `tools/list`; class authors can implement `staticTools()` to lift this validation into lint.",
+    check: (ctx) => {
+        if (ctx.mcpConnectorStaticTools.size === 0)
+            return [];
+        const findings = [];
+        const reported = new Set();
+        for (const [targetName, target] of ctx.parsed.targets) {
+            walkOps(target.ops, (op) => {
+                if (op.kind !== "$" || op.mcpConnector === undefined)
+                    return;
+                const ref = op.mcpConnector;
+                // null = wired but class doesn't expose; undefined = not wired (different rule)
+                if (ctx.mcpConnectorStaticTools.get(ref) !== null)
+                    return;
+                const m = /^([A-Za-z_][\w:-]*)/.exec(op.body);
+                if (m === null)
+                    return;
+                const toolName = m[1];
+                const key = `${targetName}:${ref}:${toolName}`;
+                if (reported.has(key))
+                    return;
+                reported.add(key);
+                findings.push({
+                    rule: "unverified-qualified-tool",
+                    severity: "info",
+                    message: `\`$ ${ref}.${toolName}\` in target '${targetName}' — connector '${ref}' doesn't declare its tool surface statically; can't validate at compile time. Verify the tool exists on the connector; runtime will fail with a connector-specific error if it doesn't.`,
+                    block: targetName,
+                    extras: { connector: ref, tool: toolName },
+                });
+            });
+        }
+        return findings;
+    },
+};
 // v0.5.0 item 5 — bare `$ TOOL` op (no connector prefix) when no
 // `primary` connector is wired. Runtime now throws ConnectorNotFoundError
 // instead of silent-stub (was: emitted "Would call tool X" + bound null,
@@ -549,16 +675,26 @@ const DISALLOWED_TOOL = {
 // (lint context has real registry info) — embedder contexts that don't
 // expose the registry stay silent rather than risk noise on legitimate
 // toolDispatch-only setups.
+// v0.9.4.1 — fallback-aware demotion. When every call site for a (target, tool)
+// pair carries an op-level `(fallback: ...)` trailer, demote the tier-1 error
+// to advisory (info). Lint runs at authoring-time; `(fallback:)` is honored at
+// dispatch-time, so the runtime is guarded even though the connector isn't
+// wired here. Per Perry's `77ed6c65` next-ring finding: cold authors expect
+// `(fallback:)` to suppress the tier-1 error (it didn't pre-v0.9.4.1), and
+// the lint message didn't explain the layering. Now: if all sites have
+// fallback → info with layering explanation; if any site lacks it → error
+// (unchanged).
 const UNWIRED_PRIMARY_CONNECTOR = {
     id: "unwired-primary-connector",
     severity: "error",
-    description: "A bare `$ TOOL` op (no connector prefix) routes to either (a) a wired connector matching the op name, or (b) the `primary` connector's tool dispatch. Neither resolves.",
-    remediation: "Either wire a connector whose name matches the bare op (the v0.7.2 canonical pattern — e.g., `llm` / `memory` auto-wire by default), add a `primary` entry to connectors.json that handles the tool, or qualify the op as `$ named_connector.TOOL` against a wired connector.",
+    description: "A bare `$ TOOL` op (no connector prefix) routes to either (a) a wired connector matching the op name, or (b) the `primary` connector's tool dispatch. Neither resolves. Demoted to advisory when every call site declares `(fallback: ...)` (v0.9.4.1).",
+    remediation: "For skill authors (in-skill fix): qualify the op as `$ <connector>.<tool>` against a wired connector, OR pick a `tool` name that matches a wired connector name (e.g., `$ llm prompt=...` if `llm` is wired), OR add `(fallback: \"...\")` to every call site to acknowledge dispatch-time guarding. For runtime operators (config fix): wire a connector whose name matches the bare op (the v0.7.2 canonical pattern — e.g., `llm` / `memory` auto-wire by default in bundled deployments), or add a `primary` entry to connectors.json that handles the tool.",
     check: (ctx) => {
         if (ctx.mcpConnectorNames === undefined)
             return [];
         const findings = [];
-        const reported = new Set();
+        // Collect per (target, tool); track whether ALL call sites carry an op-level fallback.
+        const groups = new Map();
         for (const [targetName, target] of ctx.parsed.targets) {
             walkOps(target.ops, (op) => {
                 if (op.kind !== "$" || op.mcpConnector !== undefined)
@@ -580,17 +716,36 @@ const UNWIRED_PRIMARY_CONNECTOR = {
                 if (ctx.mcpConnectorNames.includes("primary"))
                     return;
                 const key = `${targetName}:${toolName}`;
-                if (reported.has(key))
-                    return;
-                reported.add(key);
+                const hasFallback = op.fallback !== undefined;
+                const existing = groups.get(key);
+                if (existing === undefined) {
+                    groups.set(key, { targetName, toolName, allFallback: hasFallback });
+                }
+                else if (!hasFallback) {
+                    existing.allFallback = false;
+                }
+            });
+        }
+        for (const { targetName, toolName, allFallback } of groups.values()) {
+            const wired = ctx.mcpConnectorNames.length === 0 ? "(none)" : ctx.mcpConnectorNames.join(", ");
+            if (allFallback) {
+                findings.push({
+                    rule: "unwired-primary-connector",
+                    severity: "info",
+                    message: `\`$ ${toolName}\` in target '${targetName}': connector isn't wired (wired: ${wired}), but every call site declares \`(fallback: ...)\`. Tier-1 lint demoted — at runtime, the fallback value binds when the dispatch errors, so the skill keeps working without the real connector.`,
+                    block: targetName,
+                    extras: { tool: toolName, hasFallback: true },
+                });
+            }
+            else {
                 findings.push({
                     rule: "unwired-primary-connector",
                     severity: "error",
-                    message: `\`$ ${toolName}\` in target '${targetName}' is a bare tool op — no connector named '${toolName}' wired and no \`primary\` fallback. Wired connectors: ${ctx.mcpConnectorNames.length === 0 ? "(none)" : ctx.mcpConnectorNames.join(", ")}.`,
+                    message: `\`$ ${toolName}\` in target '${targetName}' is a bare tool op — no connector named '${toolName}' wired and no \`primary\` fallback. Wired connectors: ${wired}.`,
                     block: targetName,
                     extras: { tool: toolName },
                 });
-            });
+            }
         }
         return findings;
     },
@@ -613,56 +768,12 @@ const UNKNOWN_CONNECTOR_CLASS = {
         message: msg,
     })),
 };
-// v0.3.1: tier-3 advisory that fires alongside the demoted tier-2
-// unknown-skill-reference / unknown-template-reference. Confirms the
-// deferred-resolution path is engaged so cold authors can distinguish
-// "intentional forward-ref" from "typo I should fix now."
-const DEFERRED_SKILL_REFERENCE = {
-    id: "deferred-skill-reference",
-    severity: "info",
-    description: "An `&` / `$ execute_skill` / `# Templates:` reference targets a skill not currently in the SkillStore; resolution is deferred to execute time (v0.3.1+).",
-    remediation: "If this is a forward reference, this advisory will clear once the referenced skill is stored. If it's a typo, fix the spelling — the runtime will throw `SkillNotFoundError` at execute time if still missing.",
-    check: async (ctx) => {
-        if (ctx.skillStore === undefined)
-            return [];
-        const findings = [];
-        const seenComposition = new Set();
-        for (const [targetName, target] of ctx.parsed.targets) {
-            for (const ref of collectAmpRefsFromOps(target.ops)) {
-                const key = `${ref.via}:${ref.name}`;
-                if (seenComposition.has(key))
-                    continue;
-                seenComposition.add(key);
-                try {
-                    await ctx.skillStore.metadata(ref.name);
-                }
-                catch {
-                    findings.push({
-                        rule: "deferred-skill-reference",
-                        severity: "info",
-                        message: `Skill '${ref.name}' referenced via \`${ref.via}\` is not currently in the SkillStore. Lint demoted in v0.3.1 — will resolve at execute time if the skill exists by then, or throw SkillNotFoundError if not. If this is a typo, fix it now; if it's a forward reference, this advisory will clear once you store '${ref.name}'.`,
-                        block: targetName,
-                        extras: { referenced_skill: ref.name, via: ref.via },
-                    });
-                }
-            }
-        }
-        for (const name of ctx.parsed.templates) {
-            try {
-                await ctx.skillStore.metadata(name);
-            }
-            catch {
-                findings.push({
-                    rule: "deferred-skill-reference",
-                    severity: "info",
-                    message: `Skill '${name}' referenced via \`# Templates:\` is not currently in the SkillStore. Lint demoted in v0.3.1 — will resolve at execute time if the skill exists by then, or throw SkillNotFoundError if not. If this is a typo, fix it now; if it's a forward reference, this advisory will clear once you store '${name}'.`,
-                    extras: { referenced_skill: name, via: "# Templates" },
-                });
-            }
-        }
-        return findings;
-    },
-};
+// v0.3.1 → v0.9.4.1: `deferred-skill-reference` advisory removed. The
+// paired unknown-skill-reference warning's remediation already covers the
+// "this advisory clears once you store the skill" guidance; the second
+// finding was just noise (Perry's `77ed6c65` — "4 diagnostics for 2
+// missing skills"). Cold authors now see one warning per missing skill,
+// not two.
 // v0.3.3 — `|json_parse` filter removed; the shape `$(VAR|json_parse).field`
 // is statically detectable. Fire a tier-3 advisory pointing at the new
 // `$ json_parse $(VAR) -> P` op so authors who carried the v0.3.2 pattern
@@ -1232,21 +1343,83 @@ const REFERENCE_TO_DISABLED_SKILL = {
 };
 // ─── Tier-3 rules (info) ────────────────────────────────────────────────────
 const NO_DEFAULT_TARGET = {
-    id: "no-default-target",
-    severity: "info",
-    description: "Multi-target skill resolves entry via fallback (last target) instead of an explicit `default:` declaration. Authors lose intent visibility.",
-    remediation: "Add `default: <target-name>` to make the entry point explicit.",
+    id: "missing-default-target",
+    severity: "error",
+    description: "Skill has no explicit `default:` declaration. The parser falls back to the last declared target as the entry point, but the implicit shape is a footgun — the entry point is invisible without reading the bottom of the source.",
+    remediation: "Add `default: <target-name>` at the bottom of the skill to make the entry point explicit. The fallback is preserved for back-compat but the implicit form is no longer supported.",
     check: (ctx) => {
-        if (ctx.parsed.targets.size <= 1)
+        // v0.9.2 — P0.9 lift to tier-1. Per qwen single-shot Test A: missing
+        // `default:` silently accepts; runtime picks the last target. Cold
+        // authors lose intent visibility. The parser's `entryTargetExplicit`
+        // field distinguishes explicit-vs-implicit.
+        if (ctx.parsed.targets.size === 0)
+            return []; // no targets → nothing to enter
+        if (ctx.parsed.entryTargetExplicit)
             return [];
-        // The parser sets entryTarget to the last declared target when no `default:`
-        // line was present. Re-derive that condition from the source.
-        // Simpler: ParsedSkill doesn't distinguish explicit vs fallback. The
-        // parser's behavior is `entryTarget === null` only when no targets at
-        // all; with targets it picks the last. So we can't distinguish at
-        // this layer without a parser change. For v1.0-dev, skip the check
-        // (parser change deferred to v1.x).
-        return [];
+        return [{
+                rule: "missing-default-target",
+                severity: "error",
+                message: "Skill has no explicit `default:` declaration. Entry point resolves via fallback (last declared target). Add `default: <target-name>` to make the entry point explicit.",
+            }];
+    },
+};
+// v0.9.2 — P0.6 colon-style kwarg syntax (`limit:20`) silently parses as
+// part of an adjacent token, then either gets dropped or passed as a
+// malformed kwarg the connector won't understand. Per qwen Test A
+// finding (a3a20593). Canonical kwarg form is `key=value` (equals sign).
+//
+// Detect: pattern `\w+:\w+` (or `\w+:"..."` or `\w+:[...]`) appearing in
+// op-body kwarg position. Exclude legitimate uses: quoted strings, the
+// `(fallback:...)` clause, ratio/time expressions inside string values.
+const COLON_KWARG_SYNTAX = {
+    id: "colon-kwarg-syntax",
+    severity: "error",
+    description: "Op body uses `key:value` colon syntax for a kwarg. The canonical kwarg form is `key=value`.",
+    remediation: "Rewrite as `key=value` (equals sign). Colon-style is reserved for `(fallback: ...)` trailers and frontmatter keys; it's not valid in kwarg position.",
+    check: (ctx) => {
+        const findings = [];
+        const reported = new Set();
+        for (const [targetName, target] of ctx.parsed.targets) {
+            walkOps(target.ops, (op) => {
+                // Only check `$` ops — function-call ops are tokenized by the parser
+                // already, so colon-style would either fail tokenization or be silently
+                // absorbed.
+                if (op.kind !== "$")
+                    return;
+                // Strip quoted strings + bracket/brace literals before scanning so
+                // quotation contents (`"3:30 PM"`), array literals
+                // (`[a, foo:bar, b]`), and JSON object values don't trip the rule.
+                // The lint is targeting colon-in-kwarg-position only.
+                const stripped = op.body
+                    .replace(/"[^"]*"/g, '""')
+                    .replace(/'[^']*'/g, "''")
+                    .replace(/\[[^\]]*\]/g, "[]")
+                    .replace(/\{[^}]*\}/g, "{}");
+                // Pattern: identifier followed by `:` followed by a non-space non-colon
+                // char — that's kwarg-position colon. Skip `(fallback: ...)` which
+                // already gets parsed out of the body by the time we see it, but
+                // belt-and-suspenders skip explicit `fallback:` matches too.
+                const re = /(?:^|\s)([A-Za-z_]\w*)\s*:\s*[^\s:][^\s]*/g;
+                let m;
+                while ((m = re.exec(stripped)) !== null) {
+                    const key = m[1];
+                    if (key === "fallback")
+                        continue;
+                    const findingKey = `${targetName}:${op.body}:${key}`;
+                    if (reported.has(findingKey))
+                        continue;
+                    reported.add(findingKey);
+                    findings.push({
+                        rule: "colon-kwarg-syntax",
+                        severity: "error",
+                        message: `\`${op.body.slice(0, 40)}${op.body.length > 40 ? "..." : ""}\` in target '${targetName}' — kwarg \`${key}:\` uses colon syntax. Rewrite as \`${key}=...\` (the canonical kwarg form is \`key=value\`).`,
+                        block: targetName,
+                        extras: { kwarg: key },
+                    });
+                }
+            });
+        }
+        return findings;
     },
 };
 const DUPLICATE_SKILL_NAME = {
@@ -1283,27 +1456,23 @@ const PLUGIN_COLLISION = {
 const UNUSED_AUGMENTING_HEADER = {
     id: "unused-augmenting-header",
     severity: "warning",
-    description: "`# Delivery-context:` or `# Templates:` set on a skill that has no `agent:` or `template:` output declaration. The fields route through `DeliveryPayload`; without an agent-bound output they don't reach a substrate.",
-    remediation: "Either add an agent-bound output (`# Output: agent: <name>` or `# Output: template: <name>`) so the augmenting fields fire, or remove `# Delivery-context:` / `# Templates:` from the frontmatter if the skill is genuinely Headless.",
+    description: "`# Event-type:` set on a skill that has no `agent:` or `template:` output declaration. The field flows to `DeliveryMeta.event_type`; without an agent-bound output it doesn't reach a substrate.",
+    remediation: "Either add an agent-bound output (`# Output: agent: <name>` or `# Output: template: <name>`) so the event_type fires, or remove `# Event-type:` from the frontmatter if the skill is genuinely Headless.",
     check: (ctx) => {
         const hasAgentBoundOutput = ctx.parsed.outputs.some((o) => o.kind === "agent" || o.kind === "template");
         if (hasAgentBoundOutput)
             return [];
         const findings = [];
-        if (ctx.parsed.deliveryContext !== null) {
+        if (ctx.parsed.eventType !== null) {
             findings.push({
                 rule: "unused-augmenting-header",
                 severity: "warning",
-                message: "`# Delivery-context:` is set but this skill has no `agent:` or `template:` output — the value won't reach any agent.",
-            });
-        }
-        if (ctx.parsed.templates.length > 0) {
-            findings.push({
-                rule: "unused-augmenting-header",
-                severity: "warning",
-                message: `\`# Templates:\` lists ${ctx.parsed.templates.length} skill(s) but this skill has no \`agent:\` or \`template:\` output — the field won't reach any agent.`,
+                message: "`# Event-type:` is set but this skill has no `agent:` or `template:` output — the value won't reach any agent.",
             });
         }
+        // v0.9.6 — `# Templates:` no longer flows through DeliveryPayload (Q10);
+        // the list is consulted by `unknown-template-reference` lint for skill-
+        // existence validation, but it's not delivery-bound metadata anymore.
         return findings;
     },
 };
@@ -1337,6 +1506,269 @@ const OUTPUT_AGENT_TARGET_NO_EMIT = {
         return findings;
     },
 };
+// v0.9.3 — P1.2 numeric-subscript dotted-ref like `${ARRAY.0}` or
+// `${LATEST.items.0}`. The substitution machinery's resolveRef does
+// string-keyed property access; arrays handle string keys ("0" coerces
+// to index 0) at runtime, so single-step `${ARR.0}` may resolve when
+// `ARR` is bound to an array — but multi-step `${LATEST.items.0.field}`
+// or chained subscripts are fragile and surface as silent failures.
+// Per R8 minion #5: cold author wrote `${LATEST.items.0}` against a
+// query result; got UnresolvedVariableError. Foreach iteration is the
+// canonical pattern for indexed access.
+//
+// Tier-2 warning: cold authors get a clear nudge toward `foreach`
+// instead of guessing at numeric subscripts.
+// v0.9.4 — N8 tier-3 advisory: skill with this name already exists in
+// the SkillStore. `skill_write` will reject with "already exists. Pass
+// overwrite=true to replace." Cold authors iterating on a new skill
+// otherwise discover the collision only at write time — round-trip cost
+// per R8 minion #6 finding. The lint surfaces it earlier so authors
+// can either rename or pass overwrite=true intentionally.
+const SKILL_NAME_COLLISION = {
+    id: "skill-name-collision",
+    severity: "info",
+    description: "A skill with this name already exists in the SkillStore. `skill_write` will reject unless `overwrite=true` is passed.",
+    remediation: "If you intended to replace the existing skill, pass `overwrite=true` to `skill_write`. If not, rename the skill (change the `# Skill:` header value).",
+    check: async (ctx) => {
+        if (ctx.skillStore === undefined)
+            return [];
+        if (ctx.parsed.name === null)
+            return [];
+        // CLI lint is the "I'm just checking a file" surface; it shouldn't
+        // surface write-preflight warnings. Cold-author write-preflight goes
+        // through MCP lint_skill (callSite "api") or compile-preflight.
+        if (ctx.callSite === "cli")
+            return [];
+        try {
+            // Compare the stored body to the source being linted. If identical,
+            // the user is re-linting their already-stored skill — no collision
+            // worth surfacing. Only fire when the stored body materially differs.
+            const stored = await ctx.skillStore.load(ctx.parsed.name);
+            if (stored.source === ctx.source)
+                return [];
+            return [{
+                    rule: "skill-name-collision",
+                    severity: "info",
+                    message: `Skill '${ctx.parsed.name}' already exists in the SkillStore with a different body. \`skill_write\` will reject without \`overwrite=true\`. Rename, or pass \`overwrite=true\` intentionally.`,
+                }];
+        }
+        catch {
+            // Not found → no collision
+            return [];
+        }
+    },
+};
+// v0.9.4 — N5 tier-3 advisory on `$set VAR = [{...}]` JSON-object-array
+// literals. The parser's processSetValue doesn't JSON-parse the value —
+// it strips outer quotes and otherwise treats it as a literal. So
+// `$set ISSUES = [{"id":"X","status":"open"}]` binds the STRING
+// `[{"id":"X","status":"open"}]` rather than a structured array.
+// Cold authors expect JS-class literal parsing; the gap is silent.
+// Per haiku/qwen finding N5 in 9086b3f8.
+const SET_JSON_LITERAL_ADVISORY = {
+    id: "set-json-literal-advisory",
+    severity: "info",
+    description: "`$set VAR = [{...}]` binds the literal string form, not a parsed JSON structure. Skillscript's `$set` is literal-only — JS-class object/array literals don't auto-parse.",
+    remediation: "If you need a parsed structure, use `$ json_parse '[{...}]' -> VAR` (parses the JSON and binds the structured value). If literal string accumulation is the intent, the current `$set` behavior is fine — this advisory just clarifies the semantic.",
+    check: (ctx) => {
+        const findings = [];
+        const reported = new Set();
+        for (const [targetName, target] of ctx.parsed.targets) {
+            walkOps(target.ops, (op) => {
+                if (op.kind !== "$set")
+                    return;
+                const value = op.setValue ?? "";
+                // Match the START of the value being an array-of-objects literal.
+                if (!/^\s*\[\s*\{/.test(value))
+                    return;
+                const key = `${targetName}:${op.setName}`;
+                if (reported.has(key))
+                    return;
+                reported.add(key);
+                findings.push({
+                    rule: "set-json-literal-advisory",
+                    severity: "info",
+                    message: `\`$set ${op.setName} = [{...}]\` in target '${targetName}' binds the literal string form, not parsed JSON. If you need a structured array of objects, use \`$ json_parse '[{...}]' -> ${op.setName}\` instead.`,
+                    block: targetName,
+                });
+            });
+        }
+        return findings;
+    },
+};
+// v0.9.4 — N3 tier-2 advisory on `${R.transcript}` in composition. The
+// composition result shape exposes `transcript` as the emissions array
+// (per docs); cold authors interpolate it as "the human-readable text"
+// and get JSON-ish array stringification. The semantic mismatch is
+// silent — lint and runtime accept the ref, but the rendered output is
+// wrong-shape. Per R8 minion #6 finding in 9086b3f8.
+//
+// Detect: `${VAR.transcript}` references where VAR was bound by a
+// `$ execute_skill ... -> VAR` op (i.e., the child-skill result envelope).
+// The conservative-but-actionable form: match any `${VAR.transcript}`
+// substitution and advise. False positives possible (if a user binds a
+// non-composition var named with `.transcript`), but the suggestion
+// reads as a helpful nudge either way.
+const TRANSCRIPT_FOOTGUN = {
+    id: "transcript-footgun",
+    severity: "warning",
+    description: "Substitution ref `${VAR.transcript}` against a composition-result var renders as a JSON-ish array string, not the human-readable text the field name suggests. The child skill's emissions are an array.",
+    remediation: "Bind the value you need explicitly in the child skill (e.g., `$set RESULT_TEXT = ...` followed by access via `${R.final_vars.RESULT_TEXT}`). For joined text, use `${R.outputs.text}` (single-string output) or iterate `foreach LINE in ${R.transcript}:` to consume per-line.",
+    check: (ctx) => {
+        const findings = [];
+        const reported = new Set();
+        // Pattern: ${ANY.transcript} or $(ANY.transcript) — both legacy and canonical
+        const re = /\$[({][A-Za-z_]\w*\.transcript[)}]/g;
+        const scanString = (s, targetName) => {
+            let m;
+            while ((m = re.exec(s)) !== null) {
+                const key = `${targetName}:${m[0]}`;
+                if (reported.has(key))
+                    continue;
+                reported.add(key);
+                findings.push({
+                    rule: "transcript-footgun",
+                    severity: "warning",
+                    message: `Substitution ref \`${m[0]}\` in target '${targetName}' renders as a JSON-ish array, not human-readable text. \`transcript\` is the child skill's emissions array. Use \`final_vars.NAMED_VAR\` (bind explicitly in child), \`outputs.text\` (joined string), or iterate via \`foreach\`.`,
+                    block: targetName,
+                });
+            }
+        };
+        for (const [targetName, target] of ctx.parsed.targets) {
+            walkOps(target.ops, (op) => {
+                if (op.body !== undefined)
+                    scanString(op.body, targetName);
+                if (op.setValue !== undefined)
+                    scanString(op.setValue, targetName);
+            });
+        }
+        return findings;
+    },
+};
+const NUMERIC_SUBSCRIPT = {
+    id: "numeric-subscript",
+    severity: "warning",
+    description: "A `${VAR.N}` substitution ref uses a numeric segment (e.g. `${ARR.0}` or `${LATEST.items.0}`). Numeric subscripts are not a first-class language feature — `foreach IT in ${VAR}` is the canonical iteration pattern.",
+    remediation: "Replace with `foreach IT in ${VAR}:` to iterate, or with `$set FIRST = ${VAR|first}` (when first-only is the intent). If a specific JSON-array element is unavoidable, bind it via an intermediary `$ json_parse` op + dotted descent against the parsed structure.",
+    check: (ctx) => {
+        const findings = [];
+        const reported = new Set();
+        // Pattern: `${X.0...}` or `${X.items.5}` etc — any segment that's
+        // all-digits inside a brace-form substitution. Skip $(...) legacy
+        // form since it's already tier-2 deprecated.
+        const re = /\$\{([A-Za-z_]\w*(?:\.\w+)+)/g;
+        const scanString = (s, targetName) => {
+            let m;
+            while ((m = re.exec(s)) !== null) {
+                const ref = m[1];
+                const segments = ref.split(".");
+                // First segment is var name (can't be numeric); look at the rest
+                const hasNumeric = segments.slice(1).some((seg) => /^\d+$/.test(seg));
+                if (!hasNumeric)
+                    continue;
+                const key = `${targetName}:${ref}`;
+                if (reported.has(key))
+                    continue;
+                reported.add(key);
+                findings.push({
+                    rule: "numeric-subscript",
+                    severity: "warning",
+                    message: `Substitution ref \`\${${ref}}\` in target '${targetName}' uses a numeric segment. Numeric subscripts aren't first-class; use \`foreach\` iteration or bind via \`$ json_parse\` for indexed access against parsed JSON.`,
+                    block: targetName,
+                    extras: { ref },
+                });
+            }
+        };
+        for (const [targetName, target] of ctx.parsed.targets) {
+            walkOps(target.ops, (op) => {
+                // Scan body + kwargs (which live in body for $ ops; in setValue for $set/$append)
+                if (op.body !== undefined)
+                    scanString(op.body, targetName);
+                if (op.setValue !== undefined)
+                    scanString(op.setValue, targetName);
+            });
+        }
+        return findings;
+    },
+};
+// v0.9.3 — P1.3 canonicalize `recipients=[...]` over `addressed_to="..."`
+// for `$ memory_write` dispatch. The bundled MemoryStoreMcpConnector only
+// reads `args["recipients"]` (line 132 of memory-store-mcp.ts), so
+// `addressed_to=...` was always a doc-bug: it parsed but silently
+// dropped. Help docs had it pre-v0.9.3 (`help({topic:"connectors"})`
+// line 318) — fixed in this same ship. Lint catches any cold author
+// who picked the wrong shape from older docs / muscle memory.
+//
+// Tier-2 warning, not tier-1 — adopter substrates may genuinely accept
+// `addressed_to` if they wire a custom MemoryStoreMcpConnector. The
+// lint nudges toward the bundled-canonical shape without breaking
+// adopter freedom.
+const DEPRECATED_ADDRESSED_TO = {
+    id: "deprecated-addressed-to",
+    severity: "warning",
+    description: "`$ memory_write addressed_to=...` is not the canonical kwarg for the bundled MemoryStoreMcpConnector. The bundled bridge reads `recipients=[...]` (array). `addressed_to` may parse but silently drops in default deployments.",
+    remediation: "Rewrite as `$ memory_write content=\"...\" recipients=[<agent_id>, ...] -> R`. The bracket-array form is the canonical shape that the bundled `MemoryStoreMcpConnector` reads. Adopters with a custom memory bridge that genuinely accepts `addressed_to` can wire it; this lint is a nudge toward the default contract.",
+    check: (ctx) => {
+        const findings = [];
+        const reported = new Set();
+        for (const [targetName, target] of ctx.parsed.targets) {
+            walkOps(target.ops, (op) => {
+                if (op.kind !== "$")
+                    return;
+                const m = /^([A-Za-z_][\w:-]*)/.exec(op.body);
+                if (m === null)
+                    return;
+                const toolName = m[1];
+                // Only fire on memory_write — adopters may have other tools that
+                // legitimately accept addressed_to.
+                if (toolName !== "memory_write")
+                    return;
+                if (!/\baddressed_to\s*=/.test(op.body))
+                    return;
+                const key = `${targetName}:${op.body}`;
+                if (reported.has(key))
+                    return;
+                reported.add(key);
+                findings.push({
+                    rule: "deprecated-addressed-to",
+                    severity: "warning",
+                    message: `\`$ memory_write ... addressed_to=...\` in target '${targetName}' — the bundled MemoryStoreMcpConnector reads \`recipients=[...]\`, not \`addressed_to=\`. Use \`recipients=[<agent_id>, ...]\` (bracket-array form).`,
+                    block: targetName,
+                });
+            });
+        }
+        return findings;
+    },
+};
+// v0.9.6 — legacy frontmatter header advisory per Perry's `ce41bd4d` signoff
+// probe #4. `# Delivery-context:` was renamed to `# Event-type:` in v0.9.6
+// (audit Q9). The parser silently ignores unknown headers; without this lint
+// cold authors migrating from stale docs hit silent semantic drift — write
+// `# Delivery-context:`, runtime drops it, then debug-loop on why
+// `meta.event_type` is empty. Same silent-permissiveness anti-pattern that
+// v0.9.5's fallback-demotion advisory landed against.
+const LEGACY_FRONTMATTER_HEADER = {
+    id: "legacy-frontmatter-header",
+    severity: "warning",
+    description: "A frontmatter header was renamed in a previous version; the legacy name is silently ignored at runtime. Migrate to the current name.",
+    remediation: "Rename the header per the message. The parser silently drops unknown headers, so this advisory is the only signal that the field isn't reaching its destination.",
+    check: (ctx) => {
+        const findings = [];
+        const lines = ctx.source.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (/^#\s*Delivery-context:/i.test(line)) {
+                findings.push({
+                    rule: "legacy-frontmatter-header",
+                    severity: "warning",
+                    message: "Header `# Delivery-context:` was renamed to `# Event-type:` in v0.9.6. The legacy header is silently ignored at runtime — migrate to `# Event-type:` so the value flows to `meta.event_type` on delivery.",
+                    extras: { legacy_header: "# Delivery-context:", new_header: "# Event-type:", line: i + 1 },
+                });
+            }
+        }
+        return findings;
+    },
+};
 const OUTPUT_AGENT_TARGET_NO_CONNECTOR = {
     id: "output-agent-target-no-connector",
     severity: "warning",
@@ -1915,12 +2347,13 @@ const RULES = [
     RESERVED_KEYWORD,
     UNKNOWN_SKILL_REFERENCE,
     UNKNOWN_TEMPLATE_REFERENCE,
-    DEFERRED_SKILL_REFERENCE,
     UNKNOWN_RETRIEVAL_ARG,
     UNKNOWN_CONNECTOR,
     UNKNOWN_CONNECTOR_CLASS,
     UNWIRED_PRIMARY_CONNECTOR,
     DISALLOWED_TOOL,
+    UNKNOWN_TOOL_ON_CONNECTOR,
+    UNVERIFIED_QUALIFIED_TOOL,
     UNINITIALIZED_APPEND,
     FOREACH_LOCAL_ACCUMULATOR_TARGET,
     APPEND_TO_NON_LIST,
@@ -1945,8 +2378,16 @@ const RULES = [
     UNUSED_AUGMENTING_HEADER,
     OUTPUT_AGENT_TARGET_NO_EMIT,
     OUTPUT_AGENT_TARGET_NO_CONNECTOR,
-    // Tier-3 (info)
+    NUMERIC_SUBSCRIPT,
+    DEPRECATED_ADDRESSED_TO,
+    LEGACY_FRONTMATTER_HEADER,
+    TRANSCRIPT_FOOTGUN,
+    SET_JSON_LITERAL_ADVISORY,
+    SKILL_NAME_COLLISION,
+    // v0.9.2 — promoted from tier-3 info to tier-1 error (P0.9 in c9c667d2)
     NO_DEFAULT_TARGET,
+    COLON_KWARG_SYNTAX,
+    // Tier-3 (info)
     DUPLICATE_SKILL_NAME,
     PLUGIN_COLLISION,
     UNPARSED_JSON_FIELD_ACCESS,
@@ -2127,6 +2568,21 @@ function collectMcpConnectorAllowedToolsFromRegistry(registry) {
     }
     return out;
 }
+function collectMcpConnectorStaticToolsFromRegistry(registry) {
+    const out = new Map();
+    if (registry === undefined)
+        return out;
+    for (const e of registry.listMcpConnectors()) {
+        const ctor = e.ctor;
+        if (ctor.staticTools !== undefined) {
+            out.set(e.name, ctor.staticTools());
+        }
+        else {
+            out.set(e.name, null);
+        }
+    }
+    return out;
+}
 function buildFeatureSet(classes) {
     const provided = new Set();
     for (const Ctor of classes) {