skillscript-runtime 0.14.1 → 0.15.0

package/examples/README.md

@@ -6,7 +6,9 @@ For full language semantics, see [`../docs/language-reference.md`](../docs/langu
 
 | Example | Patterns demonstrated |
 |---|---|
-| [`hello.skill.md`](./skillscripts/hello.skill.md) | Three-command first run; `! emit`; default target; `# Vars:` declared inputs |
+| [`hello-world.skill.md`](./skillscripts/hello-world.skill.md) | Phase 1 cold-adopter probe — no substrate; `# Vars:` + `--input` override; baseline runtime check |
+| [`skill-store-roundtrip.skill.md`](./skillscripts/skill-store-roundtrip.skill.md) | Phase 1 cold-adopter probe — Lisp-shape `$ skill_write` + `$ skill_read`; child lands as Draft per v0.15.0 bridge boundary |
+| [`data-store-roundtrip.skill.md`](./skillscripts/data-store-roundtrip.skill.md) | Phase 1 cold-adopter probe — `$ data_write` + `$ data_read` FTS round-trip |
 | [`morning-brief.skill.md`](./skillscripts/morning-brief.skill.md) | Multi-target with `needs:`; cron-fired with `EVENT.fired_at_*`; `# OnError:` fallback; dual `# Output:` (slack + prompt-context); `# Requires:` user-var cascade with fallback; LocalModel + retrieval composition |
 | [`doc-qa-with-citations.skill.md`](./skillscripts/doc-qa-with-citations.skill.md) | Single-target retrieval; `(fallback: [])` op-level fallback; LLM-with-citation pattern; pipe filter `\|json` for prompt embedding |
 | [`classify-support-ticket.skill.md`](./skillscripts/classify-support-ticket.skill.md) | `if`/`elif`/`else` multi-branch routing; classifier-cascade pattern; DataStore `$` writes with structured `domain_tags`; `$set` literal binding |
@@ -18,7 +20,7 @@ For full language semantics, see [`../docs/language-reference.md`](../docs/langu
 
 Most examples assume the bundled-default connectors:
 
-- `hello.skill.md` — zero deps (runs cold)
+- `hello-world.skill.md` — zero deps (runs cold)
 - `doc-qa-with-citations.skill.md` — Ollama (LocalModel) + DataStore for the retrieval cache
 - `morning-brief.skill.md`, `feedback-sentiment-scan.skill.md` — Ollama + DataStore + a calendar MCP connector (the `$ calendar.list_events` op)
 - `classify-support-ticket.skill.md` — Ollama + DataStore
@@ -31,13 +33,13 @@ Skills that talk to MCP tools (like `calendar.list_events`) need that tool wired
 
 ```sh
 # Cold install — no Ollama, no MCP, no external state
-skillfile run examples/skillscripts/hello.skill.md
+skillfile run examples/skillscripts/hello-world.skill.md
 
 # With overrides
-skillfile run examples/skillscripts/hello.skill.md --input WHO=Scott
+skillfile run examples/skillscripts/hello-world.skill.md --input WHO=Scott
 
 # Preview the compiled artifact without execution
-skillfile compile examples/skillscripts/hello.skill.md
+skillfile compile examples/skillscripts/hello-world.skill.md
 
 # Mechanical preview — $/~/> ops short-circuit (useful for examining flow
 # without firing real LLM calls)

package/examples/connectors/McpConnectorTemplate/McpConnectorTemplate.ts

@@ -18,6 +18,13 @@
  *   - `DataStoreMcpConnector` — bridges a registered DataStore as
  *     `$ data_read mode=...` MCP dispatch. Auto-wired when DataStore substrate
  *     is configured.
+ *   - `SkillStoreMcpConnector` (v0.15.0) — bridges a registered SkillStore as
+ *     `$ skill_write` / `$ skill_read` MCP dispatch. Makes the Lisp-shape
+ *     primitive (skills program skills) work from inside an executing skill.
+ *     Auto-wired against `substrate.skill_store`. In-skill writes are forced
+ *     to `# Status: Draft` at the bridge per the v0.15.0 trust boundary —
+ *     see `src/connectors/skill-store-mcp.ts` header for the threat-model
+ *     rationale.
  *
  * Fork from this template when none of those fit — e.g.:
  *   - Direct HTTP MCP (JSON-RPC over HTTP, no child process)

package/examples/connectors/McpConnectorTemplate/README.md

@@ -9,7 +9,8 @@ A skeleton `McpConnector` implementation for adopters writing their own. Not run
 | `RemoteMcpConnector` | Stdio bridging to remote MCP servers (`npx mcp-remote ...`). YouTrack, GitHub, Linear, most adopter MCP wiring goes through this. JSON-configurable via `connectors.json`. |
 | `CallbackMcpConnector` | Wraps a JS function. Test rigs + embedder-wired transports where the dispatch is local code. |
 | `LocalModelMcpConnector` | Bridges a registered `LocalModel` as `$ llm prompt=...`. Auto-wired when `substrate.local_model` is set. |
-| `DataStoreMcpConnector` | Bridges a registered `DataStore` as `$ data_read mode=...`. Auto-wired when `substrate.data_store` is set. |
+| `DataStoreMcpConnector` | Bridges a registered `DataStore` as `$ data_read mode=...` + `$ data_write content=...`. Auto-wired when `substrate.data_store` is set. |
+| `SkillStoreMcpConnector` (v0.15.0) | Bridges a registered `SkillStore` as in-skill `$ skill_write` + `$ skill_read` dispatch (Lisp-shape: skills program skills). Auto-wired against `substrate.skill_store`. In-skill writes are forced to `# Status: Draft` at the bridge per the v0.15.0 trust boundary. |
 
 **Fork this template only when none of those fit** — e.g.:
 
@@ -139,7 +140,7 @@ The declarative path is the canonical adopter pattern for stdio-bridged remote M
 | Cardinality | Many instances per deployment | One singleton per slot |
 | Substrate config | Per-instance via top-level keys | `substrate` section short/object/custom |
 | Class extensibility | `registerConnectorClass()` for adopter-custom classes | Programmatic bootstrap (or `substrate.skill_store: {type: "custom", ...}` once async-bootstrap lands) |
-| Auto-wired bridges | `llm` + `data_read` + `data_write` (LocalModel + DataStore exposed via bridge connectors) | n/a (these ARE the substrates being bridged) |
+| Auto-wired bridges | `llm` + `data_read` + `data_write` + `skill_read` + `skill_write` (v0.15.0 — LocalModel + DataStore + SkillStore exposed via bridge connectors) | n/a (these ARE the substrates being bridged) |
 
 McpConnector is fundamentally the "dispatch to external tools" surface — narrowest contract, broadest range of impls.
 

package/examples/connectors/README.md

@@ -9,7 +9,7 @@ Worked examples + fork-me templates for adopter-written connectors. The bundled
 | `SkillStore` | `FilesystemSkillStore`, `SqliteSkillStore` (in `src/connectors/`) | — | **[SkillStoreTemplate/](./SkillStoreTemplate/)** |
 | `DataStore` | `SqliteDataStore` (in `src/connectors/`) | — | **[DataStoreTemplate/](./DataStoreTemplate/)** |
 | `LocalModel` | `OllamaLocalModel` (in `src/connectors/`; opt-in via substrate config) | — | **[LocalModelTemplate/](./LocalModelTemplate/)** |
-| `McpConnector` | `RemoteMcpConnector`, `CallbackMcpConnector`, `LocalModelMcpConnector`, `DataStoreMcpConnector` (in `src/connectors/`) | — | **[McpConnectorTemplate/](./McpConnectorTemplate/)** |
+| `McpConnector` | `RemoteMcpConnector`, `CallbackMcpConnector`, `LocalModelMcpConnector`, `DataStoreMcpConnector`, `SkillStoreMcpConnector` (in `src/connectors/`) | — | **[McpConnectorTemplate/](./McpConnectorTemplate/)** |
 | `AgentConnector` | `NoOpAgentConnector` (in `src/connectors/`) | **[HttpWebhookAgentConnector/](./HttpWebhookAgentConnector/)** | — |
 
 **Bundled defaults** are runnable out of the box — wired through `connectors.json` substrate config or programmatic bootstrap.

package/examples/connectors/SkillStoreTemplate/SkillStoreTemplate.ts

@@ -26,6 +26,32 @@
  * you register via the registry, so once your fork passes the conformance
  * suite the entire skillscript surface (skill_write / skill_list /
  * execute_skill / etc.) reads + writes against your substrate.
+ *
+ * **v0.15.0 — `SkillStoreMcpConnector` bridge auto-wires against your impl.**
+ * The runtime's `defaultRegistry` wraps your registered SkillStore in a
+ * `SkillStoreMcpConnector` instance and registers it under the connector
+ * names `skill_read` + `skill_write`, so `$ skill_read` / `$ skill_write` from
+ * inside an executing skill dispatches through your `load()` / `store()`
+ * methods. This is the Lisp-shape primitive — skills can program skills —
+ * and works against any `SkillStore` impl that passes the conformance suite.
+ *
+ * Your impl doesn't need to do anything special to participate. Two things
+ * worth knowing:
+ *   - **In-skill writes arrive Draft-stamped.** The bridge layer applies a
+ *     `# Status: Draft` override to the body before calling your `store()`.
+ *     This is the v0.15.0 trust boundary — autonomously-generated skill
+ *     bodies (e.g., `~ qwen prompt="generate a skill"` → `$ skill_write`)
+ *     shouldn't bypass human review by landing Approved + immediately
+ *     executable. See `src/connectors/skill-store-mcp.ts` header for the
+ *     threat-model rationale. Outside-MCP `skill_write` (cold-author agents
+ *     authoring directly via the wire surface) keeps the existing "body
+ *     declares status, you auto-stamp via store()" path — that's the path
+ *     your `store()` honor-the-body-Status logic addresses.
+ *   - **Substrate-level lint runs at `store()` entry.** If you mirror
+ *     `FilesystemSkillStore` / `SqliteSkillStore`, you'll run tier-1 lint
+ *     on the body before persisting + throw `LintFailureError` on rejection.
+ *     The bridge propagates that error through `$ skill_write` so authors
+ *     see lint-rejection-on-write, not silent persistence of malformed bodies.
  */
 
 import type {

package/examples/custom-bootstrap.example.ts

@@ -89,11 +89,12 @@ registry.registerSkillStore("primary", skillStore);
 //   registry.registerDataStore("primary", new MyDataStoreAdapter(...));
 //   registry.registerAgentConnector("primary", new MyAgentHarnessAdapter(...));
 
-// Then wire bridges if you want the canonical `$ llm` / `$ data_read` /
-// `$ data_write` surfaces. The DataStore bridge handles BOTH read and
-// write via toolName discrimination; register the same instance under both
-// connector names so bare-form name-match resolution picks the right route.
-//   import { LocalModelMcpConnector, DataStoreMcpConnector } from "skillscript-runtime";
+// Then wire bridges if you want the canonical in-skill `$ llm` /
+// `$ data_read` / `$ data_write` / `$ skill_read` / `$ skill_write`
+// surfaces. Each bridge handles its multi-verb tool surface via toolName
+// discrimination; register the same instance under each connector name so
+// bare-form name-match resolution picks the right route.
+//   import { LocalModelMcpConnector, DataStoreMcpConnector, SkillStoreMcpConnector } from "skillscript-runtime";
 //   registry.registerMcpConnector("llm", new LocalModelMcpConnector(registry.getLocalModel("default")));
 //   const ms = registry.listDataStores().find((e) => e.name === "primary");
 //   if (ms !== undefined) {
@@ -101,6 +102,16 @@ registry.registerSkillStore("primary", skillStore);
 //     registry.registerMcpConnector("data_read", dataBridge);
 //     registry.registerMcpConnector("data_write", dataBridge);
 //   }
+//   // v0.15.0 — SkillStore-as-bridge. Makes `$ skill_write` / `$ skill_read`
+//   // dispatchable from inside an executing skill (Lisp-shape: skills program
+//   // skills). In-skill writes are Draft-forced at the bridge layer; outside-MCP
+//   // skill_write keeps the existing "body declares status" behavior.
+//   const ss = registry.listSkillStores().find((e) => e.name === "primary");
+//   if (ss !== undefined) {
+//     const skillBridge = new SkillStoreMcpConnector(ss.instance);
+//     registry.registerMcpConnector("skill_read", skillBridge);
+//     registry.registerMcpConnector("skill_write", skillBridge);
+//   }
 
 // Wire any connectors.json instances.
 for (const c of connectors) {

package/examples/onboarding-scaffold/bootstrap.ts

@@ -20,12 +20,13 @@ import {
 import { Scheduler } from "skillscript-runtime/scheduler";
 import { FilesystemTraceStore } from "skillscript-runtime/trace";
 import { McpServer } from "skillscript-runtime/mcp-server";
-// Note: LocalModelMcpConnector + DataStoreMcpConnector are bridge classes
-// already exported from skillscript-runtime/connectors. They wrap any
-// typed-contract impl as an MCP-dispatchable connector.
+// Note: LocalModelMcpConnector + DataStoreMcpConnector + SkillStoreMcpConnector
+// are bridge classes already exported from skillscript-runtime/connectors.
+// They wrap any typed-contract impl as an MCP-dispatchable connector.
 import {
   LocalModelMcpConnector,
   DataStoreMcpConnector,
+  SkillStoreMcpConnector,
 } from "skillscript-runtime/connectors";
 
 import { FileDataStore } from "./file-data-store.js";
@@ -63,15 +64,25 @@ const agentConnector = new TmuxShellAgentConnector({
 });
 registry.registerAgentConnector("primary", agentConnector);
 
-// Step 3: wire bridges so `$ llm` / `$ data_read` / `$ data_write` dispatch
-// through the adopter substrates above (case 1 typed-contract wiring —
-// portable). The DataStore bridge handles BOTH read and write via toolName
-// discrimination; register the same instance under both connector names so
-// bare-form name-match resolution picks the right route.
+// Step 3: wire bridges so canonical in-skill `$ llm` / `$ data_read` /
+// `$ data_write` / `$ skill_read` / `$ skill_write` dispatch through the
+// adopter substrates above (case 1 typed-contract wiring — portable). Each
+// bridge handles its multi-verb surface via toolName discrimination;
+// register the same instance under each connector name so bare-form
+// name-match resolution picks the right route.
 registry.registerMcpConnector("llm", new LocalModelMcpConnector(openai));
 const dataBridge = new DataStoreMcpConnector(dataStore);
 registry.registerMcpConnector("data_read", dataBridge);
 registry.registerMcpConnector("data_write", dataBridge);
+// v0.15.0 — SkillStore-as-bridge. Makes `$ skill_write` / `$ skill_read`
+// dispatchable from inside an executing skill (Lisp-shape: skills program
+// skills). In-skill writes are forced to `# Status: Draft` at the bridge
+// layer per the v0.15.0 trust boundary — see `src/connectors/skill-store-mcp.ts`
+// header for the threat-model rationale. Outside-MCP `skill_write` (via the
+// wire surface) keeps its existing "body declares status" behavior.
+const skillBridge = new SkillStoreMcpConnector(skillStore);
+registry.registerMcpConnector("skill_read", skillBridge);
+registry.registerMcpConnector("skill_write", skillBridge);
 
 // Step 4: wire connectors.json instances (adopter-defined MCP servers).
 for (const c of connectors) {

package/examples/skillscripts/data-store-roundtrip.skill.md

@@ -0,0 +1,11 @@
+# Skill: data-store-roundtrip
+# Status: Approved v1:83897803
+# Autonomous: true
+# Description: Round-trips the DataStore — writes a record, reads it back via full-text search. If this skill executes and emits a successful round-trip, your DataStore substrate is wired correctly.
+
+run:
+    $ data_write content="adopter dogfood probe record" tags=["phase1","probe"] -> W
+    $ data_read mode="fts" query="adopter dogfood probe" limit=5 -> R
+    emit(text="wrote record '${W.id}'; read back ${R.items|length} items")
+
+default: run

package/examples/skillscripts/doc-qa-with-citations.skill.md

@@ -1,5 +1,5 @@
 # Skill: doc-qa-with-citations
-# Status: Approved v1:2187bf35
+# Status: Approved v1:6e5dc167
 # Description: When the user asks a question that requires retrieval over the doc set, answer with inline citations to record IDs
 # Vars: QUESTION, K=6
 # Output: text

package/examples/skillscripts/hello-world.skill.md

@@ -0,0 +1,10 @@
+# Skill: hello-world
+# Status: Approved v1:5ce6d5bf
+# Description: The canonical first-run example. No substrate dependencies — pure emit. If this fails to execute, your install or runtime is broken; investigate before troubleshooting deeper layers. Demonstrates `# Vars:` declared inputs with `--input` override.
+# Vars: WHO=world
+
+greet:
+    emit(text="Hello, ${WHO}!")
+    emit(text="Your install is healthy. Try skill-store-roundtrip + data-store-roundtrip next to verify substrate wiring.")
+
+default: greet

package/examples/skillscripts/{hello.skill.provenance.json → hello-world.skill.provenance.json}

@@ -2,9 +2,9 @@
   "provenance_version": "1.0",
   "language_version": "1.0",
   "compiler_version": "0.1.0-dev",
-  "compiled_at": "2026-05-31T19:21:57.734Z",
+  "compiled_at": "2026-06-01T14:54:14.858Z",
   "source_skill": {
-    "name": "hello"
+    "name": "hello-world"
   },
   "data_skills_inlined": []
 }

package/examples/skillscripts/morning-brief.skill.md

@@ -1,5 +1,5 @@
 # Skill: morning-brief
-# Status: Approved v1:037c18af
+# Status: Approved v1:091ae2ae
 # Description: Compose a daily morning brief from calendar, mailbox, and overnight data writes when the cron trigger fires at 7am. Delivers via the agent: lifecycle hook to the receiving agent, who decides whether to surface to Slack / Discord / etc.
 # Vars: AGENT, BRIEF_HORIZON_HOURS=24
 # Triggers: cron: 0 7 * * *

package/examples/skillscripts/skill-store-roundtrip.skill.md

@@ -0,0 +1,11 @@
+# Skill: skill-store-roundtrip
+# Status: Approved v1:a3d46cf0
+# Autonomous: true
+# Description: Round-trips the SkillStore — writes a child skill, reads it back. Demonstrates the Lisp-shape primitive (skills can write skills). NOTE: under v0.15.0, in-skill `$ skill_write` lands the child as `# Status: Draft` regardless of what the body declares — to run the generated child, an authorized agent (human via dashboard, or MCP-direct) reviews + promotes via the outside-MCP `skill_status` tool. The Draft-default gate keeps autonomously-written skills out of the immediate execution loop.
+
+run:
+    $ skill_write name="hello-child" source="# Skill: hello-child\n# Status: Approved\nrun:\n    emit(text=\"hello from a programmatically-authored skill\")\ndefault: run\n" -> W
+    $ skill_read name="hello-child" -> R
+    emit(text="wrote skill '${W.name}' as Status: ${W.status}; read back ${R.source|length} bytes")
+
+default: run

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillscript-runtime",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Runtime, compiler, lint, CLI, and dashboard for Skillscript — a small declarative language for authoring agent workflows.",
   "license": "MIT",
   "author": "Scott Shwarts <scotts@pobox.com>",

package/scaffold/examples/hello-world.skill.md

@@ -0,0 +1,10 @@
+# Skill: hello-world
+# Status: Approved v1:5ce6d5bf
+# Description: The canonical first-run example. No substrate dependencies — pure emit. If this fails to execute, your install or runtime is broken; investigate before troubleshooting deeper layers. Demonstrates `# Vars:` declared inputs with `--input` override.
+# Vars: WHO=world
+
+greet:
+    emit(text="Hello, ${WHO}!")
+    emit(text="Your install is healthy. Try skill-store-roundtrip + data-store-roundtrip next to verify substrate wiring.")
+
+default: greet

package/examples/skillscripts/hello.skill.md

@@ -1,9 +0,0 @@
-# Skill: hello
-# Description: The canonical first-run example — runs without Ollama, MCP, or external state.
-# Vars: WHO=world
-
-greet:
-    emit(text="Hello, ${WHO}!")
-    emit(text="Welcome to Skillscript. You ran a skill end-to-end with three commands.")
-
-default: greet

package/scaffold/examples/hello.skill.md

@@ -1,10 +0,0 @@
-# Skill: hello
-# Status: Approved v1:03cf40ab
-# Description: The canonical first-run example — runs without Ollama, MCP, or external state.
-# Vars: WHO=world
-
-greet:
-    emit(text="Hello, ${WHO}!")
-    emit(text="Welcome to Skillscript. You ran a skill end-to-end with three commands.")
-
-default: greet