skillscript-runtime 0.20.2 → 0.21.1

package/dist/dashboard/spa/app.js

@@ -76,7 +76,10 @@ async function refresh() {
     state.blockedShellAttempts = blocked;
     state.lastUpdate = ts;
     renderSecuredBanner();
-    document.getElementById("poll-status").textContent = `last updated ${ts.toLocaleTimeString()}`;
+    // v0.21.0 — surface the running runtime version next to the poll timestamp.
+    const ver = state.capabilities?.runtimeVersion;
+    document.getElementById("poll-status").textContent =
+      `last updated ${ts.toLocaleTimeString()}${ver ? ` · skillscript v${ver}` : ""}`;
     renderCurrentView();
   } catch (err) {
     document.getElementById("poll-status").textContent = `poll failed: ${err.message}`;
@@ -350,7 +353,7 @@ function renderSkills() {
           ${state.skills.map((s) => `
             <tr onclick="window.location.hash='#skill/${encodeURIComponent(s.name)}'">
               <td><strong>${esc(s.name)}</strong></td>
-              <td><span class="badge ${esc(s.status)}">${esc(s.status)}</span></td>
+              <td>${skillStatusBadge(s)}</td>
               <td>${esc(s.description ?? "—")}</td>
               <td><code>${esc(s.version?.slice(0, 8) ?? "—")}</code></td>
             </tr>
@@ -361,16 +364,28 @@ function renderSkills() {
   `;
 }
 
+// v0.21.0 — gate-aware status badge (adopter finding 576632ca). A legacy skill
+// stored `Approved` but failing the secured gate (e.g. a v1 stamp) WON'T run —
+// badging it a plain green "Approved" while the Approvals tab lists it as
+// "needs approval" reads as a contradiction. Show "re-approval needed" here too
+// so both views agree on the truth (what the gate will actually do).
+function skillStatusBadge(s) {
+  if (s.status === "Approved" && s.gate_ok === false) {
+    return `<span class="badge error" title="Approved status, but the body lacks a valid signature — won't run until re-approved">re-approval needed</span>`;
+  }
+  return `<span class="badge ${esc(s.status)}">${esc(s.status)}</span>`;
+}
+
 async function renderSkillDetail(name) {
   try {
-    // v0.13.3 — source moved out of skill_metadata into dedicated skill_read.
+    // v0.13.3 — source moved out of skill_preflight into dedicated skill_read.
     // Call both in parallel; skill_read may fail if the skill name doesn't
     // resolve (load() throws), so guard it to keep the detail view rendering.
     const [meta, readResult] = await Promise.all([
-      callTool("skill_metadata", { name }),
+      callTool("skill_preflight", { name }),
       callTool("skill_read", { name }).catch(() => null),
     ]);
-    const { metadata, versions, recent_fires, approval } = meta;
+    const { metadata, versions, recent_fires, approval, contract } = meta;
     const source = readResult?.source ?? null;
     const metrics = state.metrics?.perSkill?.[name];
     const triggersForSkill = state.triggers.filter((t) => t.skillName === name);
@@ -397,6 +412,8 @@ async function renderSkillDetail(name) {
         ${renderStatusActions(name, metadata, approval)}
       </section>
 
+      ${renderEffectfulFootprintPanel(contract?.effectful_footprint)}
+
       ${source ? renderSecuritySignalsPanel(source) : ""}
 
       <section>
@@ -626,6 +643,49 @@ function renderHighlightedSkillBody(source) {
 // showing aggregated counts so a reviewer knows WHAT to look for before
 // scanning the body. Pairs with renderHighlightedSkillBody() (the
 // WHERE).
+// v0.21.0 — the authoritative "what does it touch" least-privilege checklist
+// for the human approver. Unlike renderSecuritySignalsPanel (regex over the
+// source), this is the AST-derived effectful_footprint from skill_preflight —
+// the SAME op enumeration the capability gate authorizes — so it's the truth of
+// what the skill can do when signed, not a textual approximation. Surfaced right
+// at the approve action so the operator sees the surface they're signing off.
+function renderEffectfulFootprintPanel(fp) {
+  if (!fp) return ""; // source not loadable / parse failed → no contract to show
+  const items = [];
+  if (fp.connectors.length > 0) {
+    items.push(`<li class="sig-medium-text">Dispatches to ${fp.connectors.length} MCP connector${fp.connectors.length === 1 ? "" : "s"}: ${fp.connectors.map((c) => `<code>${esc(c)}</code>`).join(", ")}</li>`);
+  }
+  if (fp.builtins.length > 0) {
+    items.push(`<li class="sig-info-text">Uses ${fp.builtins.length} built-in op${fp.builtins.length === 1 ? "" : "s"}: ${fp.builtins.map((b) => `<code>${esc(b)}</code>`).join(", ")}</li>`);
+  }
+  if (fp.file_writes > 0) {
+    items.push(`<li class="sig-high-text">${fp.file_writes} <code>file_write</code> op${fp.file_writes === 1 ? "" : "s"} <small>(writes to the filesystem allowlist)</small></li>`);
+  }
+  if (fp.file_reads > 0) {
+    items.push(`<li class="sig-medium-text">${fp.file_reads} <code>file_read</code> op${fp.file_reads === 1 ? "" : "s"}</li>`);
+  }
+  if (fp.unsafe_shell > 0) {
+    items.push(`<li class="sig-high-text">${fp.unsafe_shell} unsafe (full-bash) shell op${fp.unsafe_shell === 1 ? "" : "s"}</li>`);
+  }
+  const safeShellBins = fp.shell_binaries.filter((b) => b !== "bash" || fp.unsafe_shell === 0);
+  if (safeShellBins.length > 0) {
+    items.push(`<li class="sig-medium-text">Runs shell ${safeShellBins.length === 1 ? "binary" : "binaries"}: ${safeShellBins.map((b) => `<code>${esc(b)}</code>`).join(", ")} <small>(allowlist-gated)</small></li>`);
+  }
+  if (fp.notifies > 0) {
+    items.push(`<li class="sig-medium-text">${fp.notifies} <code>notify</code> agent-wake op${fp.notifies === 1 ? "" : "s"}</li>`);
+  }
+  const body = items.length === 0
+    ? `<p class="empty">Pure — no connector, shell, file, or notify ops. Nothing effectful to authorize.</p>`
+    : `<ul class="security-signals">${items.join("")}</ul>
+       <p><small>This is the AST-derived footprint the capability gate authorizes — the surface this skill can touch once approved. Confirm every line is least-privilege before signing.</small></p>`;
+  return `
+    <section>
+      <h2>What this skill touches</h2>
+      ${body}
+    </section>
+  `;
+}
+
 function renderSecuritySignalsPanel(source) {
   const sig = collectSecuritySignals(source);
   const items = [];
@@ -957,7 +1017,7 @@ async function loadComposeContract(detailsEl) {
   panel.dataset.loaded = "true";
   const [kind, name] = detailsEl.dataset.composeRef.split(":");
   try {
-    const meta = await callTool("skill_metadata", { name });
+    const meta = await callTool("skill_preflight", { name });
     const m = meta.metadata;
     // For inline (data-only), also fetch the body since it bakes at
     // compile time — reviewer sees what literally lands in the

package/dist/help-content.d.ts

@@ -1,3 +1,12 @@
 import type { Registry } from "./connectors/registry.js";
+/**
+ * The canonical agent-usage block, delivered as the MCP server's `instructions`
+ * field at `initialize` so every connecting agent learns the workflow with no
+ * CLAUDE.md copy-paste. This static string is the shipped source of truth —
+ * backend-agnostic (no AMP / substrate references) so it serves dogfood +
+ * external adopters from one place. Keep the dev-agent CLAUDE.md and
+ * docs/adopter-agent-guide.md REFERENCING this, not forking divergent copies.
+ */
+export declare const SKILLSCRIPT_USAGE_INSTRUCTIONS = "A Skillscript runtime is wired over MCP. Skills are compiled, approved, reusable procedures \u2014 run them, don't re-derive.\n\n**Session start:** `skill_list()` \u2192 your skills, grouped: `skills` (invoke directly) \u00B7 `receives` (push context to you) \u00B7 `headless` (cron/event-fired; maintain, don't invoke). Know them before routine work.\n\n**Routine task \u2014 if a skill fits, use it, don't re-reason:**\n- `skill_preflight({name})` \u2192 vars, returns, requires, effectful footprint, cleared-to-run. (skill_list entries already carry this contract.)\n- `execute_skill({name})` \u2192 run end-to-end.\n- `compile_skill({name})` \u2192 preview the plan, no side effects.\n\n**Repeating a routine? Capture it as a skill.** What you can script = the wired connectors, models, and allowed shell binaries from `runtime_capabilities()` \u2014 that list is your menu. When you catch yourself re-running work over any of them, author it. If something you'd need isn't wired yet, ask the operator to add it, then capture it.\n- `help({topic})` \u2192 the language (ops, frontmatter, connectors, lint-codes).\n- Draft \u2192 `lint_skill({source})` \u2192 `compile_skill({source})` \u2192 `skill_write({name, source})`.\n- It lands **Draft** \u2014 you can't self-approve; a human does. Treat anything you authored as not-yet-runnable until approved.";
 export declare function helpResponse(topic: string | null, runtimeVersion: string, registry?: Registry): Record<string, unknown>;
 //# sourceMappingURL=help-content.d.ts.map

package/dist/help-content.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help-content.d.ts","sourceRoot":"","sources":["../src/help-content.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AA24BzD,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,cAAc,EAAE,MAAM,EACtB,QAAQ,CAAC,EAAE,QAAQ,GAClB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqBzB"}
+{"version":3,"file":"help-content.d.ts","sourceRoot":"","sources":["../src/help-content.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEzD;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B,k1CAYkF,CAAC;AA24B9H,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,cAAc,EAAE,MAAM,EACtB,QAAQ,CAAC,EAAE,QAAQ,GAClB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqBzB"}

package/dist/help-content.js

@@ -13,6 +13,27 @@
 //
 // Token estimates per topic are approximate; help() output is intended
 // for an agent's working context, not for human reading.
+/**
+ * The canonical agent-usage block, delivered as the MCP server's `instructions`
+ * field at `initialize` so every connecting agent learns the workflow with no
+ * CLAUDE.md copy-paste. This static string is the shipped source of truth —
+ * backend-agnostic (no AMP / substrate references) so it serves dogfood +
+ * external adopters from one place. Keep the dev-agent CLAUDE.md and
+ * docs/adopter-agent-guide.md REFERENCING this, not forking divergent copies.
+ */
+export const SKILLSCRIPT_USAGE_INSTRUCTIONS = `A Skillscript runtime is wired over MCP. Skills are compiled, approved, reusable procedures — run them, don't re-derive.
+
+**Session start:** \`skill_list()\` → your skills, grouped: \`skills\` (invoke directly) · \`receives\` (push context to you) · \`headless\` (cron/event-fired; maintain, don't invoke). Know them before routine work.
+
+**Routine task — if a skill fits, use it, don't re-reason:**
+- \`skill_preflight({name})\` → vars, returns, requires, effectful footprint, cleared-to-run. (skill_list entries already carry this contract.)
+- \`execute_skill({name})\` → run end-to-end.
+- \`compile_skill({name})\` → preview the plan, no side effects.
+
+**Repeating a routine? Capture it as a skill.** What you can script = the wired connectors, models, and allowed shell binaries from \`runtime_capabilities()\` — that list is your menu. When you catch yourself re-running work over any of them, author it. If something you'd need isn't wired yet, ask the operator to add it, then capture it.
+- \`help({topic})\` → the language (ops, frontmatter, connectors, lint-codes).
+- Draft → \`lint_skill({source})\` → \`compile_skill({source})\` → \`skill_write({name, source})\`.
+- It lands **Draft** — you can't self-approve; a human does. Treat anything you authored as not-yet-runnable until approved.`;
 const QUICKSTART = `# Skillscript — quickstart
 
 Skillscript is a declarative language for authoring agent workflows. A

package/dist/help-content.js.map

@@ -1 +1 @@
-{"version":3,"file":"help-content.js","sourceRoot":"","sources":["../src/help-content.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"help-content.js","sourceRoot":"","sources":["../src/help-content.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server.d.ts

@@ -14,23 +14,24 @@ import type { Registry } from "./connectors/registry.js";
  * protocol conforms to MCP — real MCP clients (Claude Desktop, Cursor,
  * future tools) can consume the server unchanged.
  *
- * Surface: tools wrapping existing T6 primitives.
+ * Surface: tools wrapping existing T6 primitives, ordered by the cold-author
+ * workflow loop the descriptions teach (learn → discover → draft → commit →
+ * approve → run → automate → observe).
  *
- *   skill_list({filter?})          → SkillCatalog (v0.9.8 — pre-grouped by audience)
- *   skill_metadata({name})         → metadata + version history + recent_fires + approval (no source — see skill_read)
- *   skill_read({name, version?})   → {name, version, status, source} (v0.13.3 — symmetric peer to skill_write)
- *   data_read({id, store?})      → PortableData | null (v0.13.8 — direct lookup; no data_write MCP by design)
- *   skill_status({name, new_state})→ SkillStatus update (write)
- *   list_triggers({filter?})       → TriggerRegistration[]
- *   register_trigger({...})        → TriggerRegistration (write)
- *   unregister_trigger({trigger_id})→ boolean (write)
- *   health_metrics({filter?})      → HealthMetrics
- *   runtime_capabilities({include?})→ wired connectors + shell-exec mode (v0.2.1)
- *   lint_skill({source?|name})     → diagnostics across tiers (v0.2.3)
- *   compile_skill({source?|name, inputs?})→ rendered artifact + errors (v0.2.3)
- *   skill_write({name, source, overwrite?})→ commit to SkillStore (write, v0.2.3)
- *   execute_skill({skill_name, inputs?, mechanical?})→ run + return result (write, v0.2.8)
- *   help({topic?})                 → cold-agent language discovery (read, v0.2.8)
+ *   LEARN     help({topic?})                  → language quickstart + deep topics
+ *             runtime_capabilities({include?})→ wired connectors + shell-exec mode
+ *   DISCOVER  skill_list({filter?})           → SkillCatalog (grouped by audience; entries carry the full contract)
+ *             skill_preflight({name})         → one skill's contract: takes/returns/requires/touches + approval + lifecycle
+ *             skill_read({name, version?})    → {name, version, status, source} (the body itself)
+ *             data_read({id, store?})         → PortableData | null (direct lookup; no data_write MCP by design)
+ *   DRAFT     lint_skill({source?|name})      → tiered diagnostics (inner loop)
+ *             compile_skill({source?|name, inputs?})→ rendered artifact + errors + exec order (pre-commit)
+ *   COMMIT    skill_write({name, source, overwrite?})→ store the body (write; secured mode forces unsigned→Draft)
+ *   APPROVE   skill_status({name, new_state}) → Draft/Approved/Disabled (write; secured promote needs a signature)
+ *   RUN       execute_skill({name|source, inputs?, mechanical?})→ run + return result (write)
+ *   AUTOMATE  register_trigger / list_triggers / set_trigger_enabled / unregister_trigger → autonomous dispatch
+ *   OBSERVE   health_metrics({filter?})       → per-skill/connector aggregates
+ *             blocked_shell_attempts()        → allowlist-refused shell ops (observe→promote loop)
  */
 export interface JsonRpcRequest {
     jsonrpc: "2.0";

package/dist/mcp-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server.js

@@ -4,10 +4,11 @@ import { healthMetrics } from "./metrics.js";
 import { lint } from "./lint.js";
 import { compile } from "./compile.js";
 import { parse as parseSkill } from "./parser.js";
+import { extractEffectfulFootprint } from "./skill-surface.js";
 import { listKnownConnectorClasses } from "./connectors/config.js";
 import { LintFailureError, MissingSkillReferenceError, OpError } from "./errors.js";
 import { executeSkillByName, executeSkillFromSource, RecursionDepthExceededError, SkillNotFoundForCompositionError, } from "./composition.js";
-import { helpResponse } from "./help-content.js";
+import { helpResponse, SKILLSCRIPT_USAGE_INSTRUCTIONS } from "./help-content.js";
 import { RUNTIME_VERSION } from "./version.js";
 import { evaluateApprovalGate, isSecuredMode, hasApprovalPublicKey } from "./approval.js";
 import { forceDraftStatus } from "./connectors/skill-store-mcp.js";
@@ -44,6 +45,9 @@ export class McpServer {
                             protocolVersion: MCP_PROTOCOL_VERSION,
                             capabilities: { tools: {} },
                             serverInfo: { name: SERVER_NAME, version: this.version },
+                            // Canonical agent-usage block — every connecting agent learns the
+                            // workflow at session start, no CLAUDE.md copy-paste required.
+                            instructions: SKILLSCRIPT_USAGE_INSTRUCTIONS,
                         },
                     };
                 case "tools/list":
@@ -118,7 +122,7 @@ export class McpServer {
     registerBuiltinTools() {
         this.registerTool({
             name: "skill_list",
-            description: "Discover skills in the configured SkillStore (v0.9.8). Returns a `SkillCatalog` pre-grouped by audience-derived category: `receives` (skills that push to the calling agent via `# Output: agent:`), `skills` (skills the agent can invoke), `headless` (admin-view only). Category derived from each skill's `# Output:` declarations. Filter by audience / status / trigger_kind / domain_tags / name_prefix / author (AND-composed). Default: audience=\"agent\", status=\"Approved\". v0.18.6 — `author` filter narrows to skills authored by a specific identity; entries carry `author` for substrates that track it (null when not).",
+            description: "Discover skills in the configured SkillStore. Returns a `SkillCatalog` pre-grouped by audience-derived category: `receives` (skills that push to the calling agent via `# Output: agent:`), `skills` (skills the agent can invoke), `headless` (admin-view only). Category derived from each skill's `# Output:` declarations. Filter by audience / status / trigger_kind / domain_tags / name_prefix / author (AND-composed). Default: audience=\"agent\", status=\"Approved\". Every entry carries the full preflight contract — `vars` (inputs), `returns` (exported vars), `requires` (capability needs), `effectful_footprint` (which connectors / shell binaries / file + notify ops it touches), plus `gate_ok` (cleared-to-run under the current mode) and `author` (when the substrate tracks it). So you can read a skill's whole I/O + effect contract here without a per-skill `skill_preflight` call; reach for `skill_preflight` when you want one skill's contract + version/lifecycle detail, or `skill_read` for the body.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -143,7 +147,7 @@ export class McpServer {
         });
         this.registerTool({
             name: "blocked_shell_attempts",
-            description: "v0.18.9 — list shell op dispatches refused by the binary allowlist gate. Queries the trace store cross-skill, filters to op records carrying `blocked_reason: \"binary-not-allowed\"`. Returns flat list ready for the dashboard's observe→promote loop (operator sees what binaries skills tried to invoke; decides whether to add any to `SKILLSCRIPT_SHELL_ALLOWLIST`).",
+            description: "List shell op dispatches refused by the binary allowlist gate. Queries the trace store cross-skill, filtering to op records carrying `blocked_reason: \"binary-not-allowed\"`. Returns a flat list for the dashboard's observe→promote loop: the operator sees what binaries skills tried to invoke, then decides whether to add any to `SKILLSCRIPT_SHELL_ALLOWLIST`. Read-only.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -196,8 +200,8 @@ export class McpServer {
             },
         });
         this.registerTool({
-            name: "skill_metadata",
-            description: "Get metadata + version history + recent fires + approval-gate state for a specific skill by name. For the source body itself, call skill_read.",
+            name: "skill_preflight",
+            description: "PRE-EXECUTION CONTRACT CHECK — call this BEFORE executing or composing a skill to see what it takes, returns, requires, and touches: its inputs (vars), exported variables (returns), capability requirements, and effectful footprint (which connectors / shell binaries / write + notify ops it dispatches). Also reports whether it's cleared to run (approval-gate state) + version/lifecycle. The least-privilege checklist for a human approver, and the contract surface for a cold author composing against it. Discover skills with skill_list (its entries already carry this same contract); call skill_preflight for one skill's contract plus version/lifecycle detail, or skill_read for the source body.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -219,15 +223,28 @@ export class McpServer {
                 // stale-Approved skills (body edited since approval, token no
                 // longer verifies). `null` when the source isn't loadable.
                 let approval = null;
+                // v0.21.0 — the contract surface: what the skill TAKES (vars, via the
+                // parser's frontmatter), RETURNS (exported vars), REQUIRES (capability
+                // clauses), and TOUCHES (effectful footprint). Derived statically from
+                // the body. Null when the source isn't loadable.
+                let contract = null;
                 if (loaded?.source !== undefined) {
                     const g = evaluateApprovalGate(loaded.source);
                     approval = g.ok ? { gate_ok: true } : { gate_ok: false, reason: g.reason };
+                    const parsed = parseSkill(loaded.source);
+                    contract = {
+                        vars: parsed.vars.map((v) => v.name),
+                        returns: parsed.returns,
+                        requires: parsed.requires,
+                        effectful_footprint: extractEffectfulFootprint(parsed),
+                    };
                 }
                 return {
                     metadata,
+                    contract,
+                    approval,
                     versions,
                     recent_fires,
-                    approval,
                 };
             },
         });
@@ -277,7 +294,7 @@ export class McpServer {
         });
         this.registerTool({
             name: "skill_status",
-            description: "Transition a skill's status. Valid states: Draft, Approved, Disabled. Write operation.",
+            description: "Transition a skill's lifecycle status: Draft, Approved, Disabled. Approved is the only status that executes and lets triggers fire; Draft is the editing state; Disabled retires a skill without deleting it (re-enable by transitioning back to Approved/Draft). In secured mode you CANNOT promote to Approved here without a valid signature — approve via the dashboard or `skillfile approve` (which signs the body); a bare status flip can't grant approval. Write operation.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -296,6 +313,19 @@ export class McpServer {
                 if (!isSkillStatus(newState)) {
                     throw new OpError(`\`skill_status\` requires \`new_state\` to be one of ${VALID_SKILL_STATUSES.map((s) => `"${s}"`).join(", ")}; got ${JSON.stringify(newState)}.`, "skill_status", `Pass \`new_state\` as one of: ${VALID_SKILL_STATUSES.join(" | ")}.`, name);
                 }
+                // v0.21.0 — store-agnostic secured-mode closure (red-team 33bf53d3).
+                // skill_status cannot GRANT approval in secured mode: promotion to
+                // Approved is refused unless the stored body already carries a valid v3
+                // signature. The per-store guard (FilesystemSkillStore/SqliteSkillStore)
+                // didn't cover custom adopter stores (e.g. AMP-backed), so an agent could
+                // flip Draft→Approved with no signature — a forgeable trust-state lie.
+                // Enforce HERE, at the ingress, regardless of substrate.
+                if (newState === "Approved" && isSecuredMode()) {
+                    const loaded = await this.deps.skillStore.load(name).catch(() => null);
+                    if (loaded === null || !evaluateApprovalGate(loaded.source).ok) {
+                        throw new OpError(`cannot promote '${name}' to Approved in secured mode — the skill carries no valid signature. Approve it via the dashboard or \`skillfile approve\` (which signs the body); a status change alone cannot grant approval.`, "skill_status", `Sign the skill with the operator's key, then it can be Approved.`, name);
+                    }
+                }
                 const result = await this.deps.skillStore.update_status(name, newState);
                 // v0.19.1 — sync declarative triggers on status transition.
                 // Approved → register the skill's declared triggers; Draft or
@@ -307,7 +337,7 @@ export class McpServer {
         });
         this.registerTool({
             name: "list_triggers",
-            description: "List registered triggers. Optionally filter by skill name or trigger source.",
+            description: "List registered triggers — the autonomous-dispatch registry. Optionally filter by skill name or trigger source (cron / event). Read-only. Pairs with register_trigger / set_trigger_enabled / unregister_trigger to manage how Approved skills fire on their own.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -326,7 +356,7 @@ export class McpServer {
         });
         this.registerTool({
             name: "register_trigger",
-            description: "Register a new trigger for a skill. Returns the registration. Write operation.",
+            description: "Register an autonomous-dispatch trigger for a skill — cron (time-based) or event (HTTP POST /event ingress, named). Only Approved skills fire; the scheduler re-verifies the approval gate at fire time, so registering a trigger never bypasses approval. Skills can also declare triggers inline via `# Triggers:` frontmatter (synced automatically on approval) — use this tool for imperative / dynamic registration. Returns the registration. Write operation.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -374,7 +404,7 @@ export class McpServer {
         });
         this.registerTool({
             name: "unregister_trigger",
-            description: "Unregister a trigger by id. Returns boolean (true if removed, false if id not found). Write operation.",
+            description: "Remove a registered trigger by id (see list_triggers for ids). Returns true if removed, false if the id wasn't found. Write operation.",
             inputSchema: {
                 type: "object",
                 properties: { trigger_id: { type: "string" } },
@@ -387,7 +417,7 @@ export class McpServer {
         });
         this.registerTool({
             name: "set_trigger_enabled",
-            description: "v0.9.0 — toggle a trigger's enabled state. Disabled triggers stay registered but the scheduler skips firing them (vacation / maintenance windows). State persists via the onTriggersChanged hook for imperative triggers. Returns the updated registration, or null if no trigger has that id. Write operation.",
+            description: "Toggle a trigger's enabled state without unregistering it — disabled triggers stay in the registry but the scheduler skips firing them (vacation / maintenance windows). State persists via the onTriggersChanged hook for imperative triggers. Returns the updated registration, or null if no trigger has that id. Write operation.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -449,7 +479,7 @@ export class McpServer {
         // ─── v0.2.3 — over-the-wire authoring lifecycle ────────────────────────
         this.registerTool({
             name: "lint_skill",
-            description: "Run static lint against a skill source body or stored skill name. Returns diagnostics across tier-1 (errors that block compile), tier-2 (warnings), tier-3 (advisories). Read-only. Inner-loop affordance for cold authors iterating on a draft.",
+            description: "Run static lint against a skill source body or stored skill name. Returns diagnostics across tier-1 (errors that block compile), tier-2 (warnings), tier-3 (advisories). Read-only. The inner-loop affordance while drafting — lint as you iterate, then compile_skill for the full pre-commit check before skill_write.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -461,7 +491,7 @@ export class McpServer {
         });
         this.registerTool({
             name: "compile_skill",
-            description: "Compile a skill source body or stored skill name. Returns the rendered artifact + parse/compile errors + resolved variables + topological execution order. Read-only. Pre-commit validation affordance.",
+            description: "Compile a skill source body or stored skill name. Returns the rendered artifact + parse/compile errors + resolved variables + topological execution order. Read-only. The pre-commit check after lint_skill passes and before skill_write — confirms the body compiles and shows the execution order without running effects (use execute_skill `mechanical: true` for a no-fire dispatch preview).",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -478,7 +508,7 @@ export class McpServer {
         });
         this.registerTool({
             name: "skill_write",
-            description: "Write a skill body into the configured SkillStore. Tier-1 lint runs at write time (SkillStore contract); throws on rejection. Returns version + content_hash. The `# Status:` header in the source body is honored — write with `# Status: Approved` and the skill lands Approved (otherwise defaults to Draft). Promote/demote later via skill_status. Write operation.",
+            description: "Write a skill body into the configured SkillStore. Tier-1 lint runs at write time (SkillStore contract) and throws on rejection — run lint_skill / compile_skill first to iterate cleanly. The `# Status:` header is honored: `# Status: Approved` lands Approved in unsecured mode, but in secured mode an unsigned body is forced to Draft (a write can't grant approval). Promote later via skill_status, or the dashboard / `skillfile approve` in secured mode. Returns version + content_hash. Write operation.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -533,7 +563,7 @@ export class McpServer {
     async executeSkill(args, callerCtx = {}) {
         // v0.15.2 — `name` is the canonical kwarg; `skill_name` is a silent
         // back-compat alias. Aligns the surface with the other skill_* tools
-        // (skill_read / skill_metadata / skill_status / skill_write all take
+        // (skill_read / skill_preflight / skill_status / skill_write all take
         // `name`). Per Perry signoff (thread 75abc8c0): silent alias — no
         // tier-3 advisory, no deprecation warn. If both are supplied with
         // different values, that's ambiguous; reject so the caller picks one.
@@ -817,7 +847,21 @@ export class McpServer {
         // posture (every write requires explicit human promotion regardless
         // of body claim) opt in via the flag at runtime startup. Per Perry's
         // `787b6b95` Option A.
-        const bodyToStore = this.deps.forceAlwaysDraft === true ? forceDraftStatus(source) : source;
+        // v0.21.0 — store-agnostic secured-mode closure (red-team 33bf53d3).
+        // skill_write cannot GRANT approval: if the body claims Approved without a
+        // valid v3 signature, force Draft — regardless of the SkillStore impl. The
+        // per-store guard didn't cover custom adopter stores (AMP-backed), letting an
+        // agent write status=Approved with no signature (a forgeable trust-state lie
+        // that misleads skill_list / skill_preflight / the dashboard). evaluateApproval
+        // -Gate is not-ok for any Draft OR unsigned-Approved body, so a genuine
+        // approve-flow write (signed body) is honored; everything else lands Draft.
+        let bodyToStore = source;
+        if (this.deps.forceAlwaysDraft === true) {
+            bodyToStore = forceDraftStatus(source);
+        }
+        else if (isSecuredMode() && !evaluateApprovalGate(source).ok) {
+            bodyToStore = forceDraftStatus(source);
+        }
         // v0.17.0 — thread host-attested caller identity into `store({author})`
         // so MCP-authored skills stamp `SkillMeta.author = <calling agent>`,
         // not the runtime's wiring identity. When ctx.callerIdentity is