skillscript-runtime 0.19.16 → 0.20.1

package/docs/language-reference.md

@@ -1,91 +1,14 @@
-# Skillscript Language Reference — syntax, ops, semantics
+---
+title: Language Reference
+description: "Canonical spec — syntax, ops, semantics. Frontmatter, ops, filters, conditionals, triggers, output kinds, composition, error handling."
+mode: wide
+---
 
 Canonical language reference for skillscript. Audience: skill authors (human + agent). Specifies what is valid syntax, what behavior to expect at compile + runtime, and what is currently pending implementation.
 
 Implementation state is cross-referenced to commit hashes; pending items mark v2/v3 work.
 
 
-## Not yet implemented, but planned
-
-These are features designed or anticipated but not yet implemented in the current build. Authors should not use these forms; they will not compile.
-
-## Control flow
-
-- **`while CONDITION:` loops** — today's iteration is `foreach IDENT in EXPR:` only. While loops are planned for ad-hoc orchestration patterns ("loop until response contains 'done'").
-- **Arithmetic in `$set`** — today accepts literals + `${VAR}` interpolation; no `+ - * /` operators. Planned alongside `while` for turn counters and orchestration bookkeeping.
-
-## Pipe filter extensions
-
-- **Array aggregation primitives** — `|max`, `|min`, `|sum`, `|reduce` over arrays. Today the language tops out at "shape one record" — aggregating across an array requires `foreach` accumulator ceremony. Planned as a design question: is `foreach` the deliberate ceiling for aggregation, or do we add primitives?
-
-## Triggers — note
-
-Trigger sources are `cron` + `event` only (see the Triggers section). There is no separate `agent-event:` / `file-watch:` / `sensor:` trigger source — anything that isn't time-based is an external adapter that POSTs to the `/event` ingress. So there's nothing pending here on the trigger axis; the entry remains only to point readers who expect those sources at the adapter-POST pattern.
-
-## Synchronous agent exchange
-
-- **`exchange()` runtime-intrinsic op** — synchronous send + wait pattern for multi-agent conferences. Awaits adopter-substrate queue impl + AgentConnector contract grow.
-
-## Tests
-
-- **`# Tests:` block** with `given:` / `expect:` assertions — author-authored test cases. Will land when adopter signal demands test infrastructure.
-
-## Output kinds
-
-- **`# Output: file: <path>`** — file-output routing parses but no router exists today.
-- **`# Output: card:`** — depends on a substrate-side card render surface; not implemented.
-
-## Persistent state with declared scope
-
-```
-$set NAME = value scope=skill-local
-$set NAME = value scope=agent-global
-$set NAME = value scope=session
-```
-
-Scopes: skill-local (persists across fires of this skill, not visible to other skills), agent-global (visible to all skills of the same agent), session (alive for the duration of the current session, cleared at session end). Backed by a configured data-records connector.
-
-## Sensors as a read-channel category
-
-> `sensor:` is not a trigger source — to fire a skill on a sensor signal, a sensor adapter POSTs to `/event` (see Triggers). The concept below is the separate *read-channel* idea — continuous values an agent reads, distinct from triggering — which remains a future possibility if demand surfaces.
-
-Distinct from triggers. Sensors are continuous channels the agent reads but doesn't emit on. Planned syntax:
-
-```
-# Sensors: presence, screen-state, voice-prosody
-```
-
-Ambient refs `$(SENSOR.presence)`, `$(SENSOR.voice-prosody.affect)` for read access. Privacy-gating discipline determines when a sensor is readable.
-
-## Time as first-class primitives
-
-Currently `$(NOW)` (wall-clock). Planned relative-time primitives:
-
-```
-$(SECONDS_SINCE_LAST_USER_MESSAGE)
-$(MINUTES_SINCE_SESSION_START)
-$(SECONDS_SINCE_LAST_FIRE_OF.<skill-name>)
-```
-
-Most "right time" reasoning is relative, not wall-clock.
-
-## Other planned
-
-- **Absence-as-trigger** — `# Triggers: idle: 5m` fire-on-quiet primitive (would be a new trigger source beyond `cron`|`event`, or an adapter that POSTs on a timer)
-- **Time-windowed aggregation** — filter-like primitives across firings (e.g., "user has shown frustration in 3 of 5 recent turns")
-- **Debounce / rate-limit / coalesce** — declarative queueing policy headers
-- **Suppression as valid output** — explicit "fire-and-suppress" (different from `# Output: none`)
-- **Cross-skill pub-sub** — `# Publishes: signal.X` / `# Subscribes: signal.Y` decoupling
-- **Confidence/threshold gating** — `# RequiresConfidence: classifier >= 0.8` / `# RequiresThreshold:`
-- **Invocation-control axis** — `# Invocable-By: user | agent | trigger` (sensitive ops shouldn't leak across invocation boundaries)
-- **Channel/locality awareness** — `$(CHANNEL_TYPE)`, `$(CHANNEL_PRIVACY)` ambient refs for routing decisions
-- **Introspection primitives** — `$(PROMPT_CONTEXT.size)`, `$(SKILLS_FIRED_RECENTLY.last-1h)`, `$(SELF.confidence-trend)`
-- **Capability declarations** — `# Requires-Capabilities: sensors=[mic, camera], tools=[...]` (audit surface for operators)
-
-## When the language extends, this section shrinks
-
-When any of these primitives ship, the relevant grammar moves into its canonical section (Ops reference, Variables, Triggers, etc.) and the entry here is removed. This section stays alive as a continuous staging area for the next horizon of unshipped work.
-
 ## Overview & language model
 
 Skillscript is a constrained domain-specific language for authoring agent workflows. A skillscript is a declarative recipe: a small program with a dependency DAG of named targets, each composed of typed operations. Skillscripts are written once and executed many times.
@@ -378,7 +301,7 @@ Closed list of language-intrinsic ops the runtime knows directly. Each is a func
 | `emit` | `emit(text="...")` | none | Append to the skill's emission stream; consumed by the configured `# Output:` delivery channel. |
 | `notify` | `notify(agent="...", message="...", [event_type=...], [correlation_id=...]) -> ACK` | optional | Mid-skill agent alert; synchronous send via configured AgentConnector. |
 | `inline` | `inline(skill="<data-skill-name>")` | none | Compile-time inline of an Approved `# Type: data` skill. Resolves at compile, records `content_hash` in provenance. |
-| `execute_skill` | `execute_skill(skill_name="...", inputs={...}) -> R` | optional | Composition primitive. Runtime-resolved. See Composition section. |
+| `execute_skill` | `execute_skill(skill_name="...", inputs=\{...}) -> R` | optional | Composition primitive. Runtime-resolved. See Composition section. |
 | `shell` | `shell(command="...") -> R` / `shell(argv=[...]) -> R` / `shell(command="...", unsafe=true) -> R` | optional | Structural spawn (default), explicit-argv spawn (`argv=[...]`, no tokenizer), or full-shell exec (`unsafe=true`, gated by `runtime.enable_unsafe_shell`). Binary gated by the operator allowlist (see below). stdout binds. |
 | `file_read` | `file_read(path="...") -> R` | required | Read a file at `path`; binds string contents. |
 | `file_write` | `file_write(path="...", content="...")` | none | Write `content` to `path`. `mkdir -p` semantics for parent directories. Mutation-classified. |
@@ -735,12 +658,12 @@ deliver:
 
 | Class | Op | Shape | Binding |
 |---|---|---|---|
-| Mutation | `$set` | `$set NAME = value` (with `${VAR}` interpolation at bind) | NAME (no arrow) |
+| Mutation | `$set` | `$set NAME = value` (with `$\{VAR}` interpolation at bind) | NAME (no arrow) |
 | Mutation | `$append` | `$append VAR <value>` (type-dispatched: list element / string concat) | VAR (no arrow) |
 | Runtime-intrinsic | `emit` | `emit(text="...")` or `emit(text="""...""")` for multi-line | none |
 | Runtime-intrinsic | `notify` | `notify(agent="...", [message=...], [event_type=...], [correlation_id=...]) -> ACK` | optional |
 | Runtime-intrinsic | `inline` | `inline(skill="<name>")` | none (compile-time) |
-| Runtime-intrinsic | `execute_skill` | `execute_skill(skill_name="...", inputs={...}) -> R` | optional |
+| Runtime-intrinsic | `execute_skill` | `execute_skill(skill_name="...", inputs=\{...}) -> R` | optional |
 | Runtime-intrinsic | `shell` | `shell(command="...", [unsafe=true], [approved="..."]) [-> R] [(fallback: "...")]` or `shell(argv=[...], [approved="..."]) [-> R] [(fallback: "...")]` (mutually exclusive forms; binary allowlist applies to both) | optional |
 | Runtime-intrinsic | `file_read` | `file_read(path="...") -> R` | required |
 | Runtime-intrinsic | `file_write` | `file_write(path="...", content="...", [approved="..."])` | none |
@@ -769,13 +692,13 @@ Injected automatically at runtime; never declared by the author.
 
 | Var | Value |
 |-----|-------|
-| `${NOW}` | ISO-8601 timestamp at op-dispatch time |
-| `${USER}` | The configured user identity |
-| `${SESSION_CONTEXT}` | Current session-scope context (project/entity/etc., substrate-defined) |
-| `${TRIGGER_TYPE}` | What event fired this skill |
-| `${TRIGGER_PAYLOAD}` | Event-specific data |
-| `${EVENT.*}` | Event-payload fields populated by the trigger source |
-| `${ERROR_CONTEXT}` | In `# OnError:` fallback skills: type + target where failure occurred |
+| `$\{NOW}` | ISO-8601 timestamp at op-dispatch time |
+| `$\{USER}` | The configured user identity |
+| `$\{SESSION_CONTEXT}` | Current session-scope context (project/entity/etc., substrate-defined) |
+| `$\{TRIGGER_TYPE}` | What event fired this skill |
+| `$\{TRIGGER_PAYLOAD}` | Event-specific data |
+| `$\{EVENT.*}` | Event-payload fields populated by the trigger source |
+| `$\{ERROR_CONTEXT}` | In `# OnError:` fallback skills: type + target where failure occurred |
 
 Iterator vars from `foreach` and output bindings from runtime-intrinsic / MCP-dispatch ops also pass through ambient at compile time; the runtime substitutes them per iteration / per op completion.
 
@@ -880,14 +803,14 @@ Pipe filters apply transforms to resolved variables before substitution. Syntax:
 
 | Filter | Effect | Example | Output |
 |--------|--------|---------|--------|
-| `url` | `encodeURIComponent(value)` | `${location|url}` for `"Asheville, NC"` | `Asheville%2C%20NC` |
-| `shell` | POSIX single-quote escape with outer quotes | `${arg|shell}` for `it's safe` | `'it'\''s safe'` |
-| `json` | `JSON.stringify(value)` | `${payload|json}` for `{k:"v"}` | `"{\"k\":\"v\"}"` |
-| `trim` | Whitespace trim | `${VERDICT|trim}` for `"urgent\n"` | `urgent` |
-| `length` | Count of items (array) or characters (string) | `${ITEMS|length}` for `["a","b","c"]` | `3` |
-| `contains:"X"` | Boolean: type-aware substring / element membership | `${MSG|contains:"urgent"}` for `"Yes, urgent"` | `true` |
-| `fallback:"X"` | Coalesce on missing/undefined/empty ref | `${VAR.missing|fallback:"-"}` | `-` |
-| `isodate` | Epoch seconds → ISO-8601 timestamp | `${EPOCH|isodate}` for `1779660000` | `2026-05-24T22:00:00.000Z` |
+| `url` | `encodeURIComponent(value)` | `$\{location|url}` for `"Asheville, NC"` | `Asheville%2C%20NC` |
+| `shell` | POSIX single-quote escape with outer quotes | `$\{arg|shell}` for `it's safe` | `'it'\''s safe'` |
+| `json` | `JSON.stringify(value)` | `$\{payload|json}` for `\{k:"v"}` | `"\{\"k\":\"v\"}"` |
+| `trim` | Whitespace trim | `$\{VERDICT|trim}` for `"urgent\n"` | `urgent` |
+| `length` | Count of items (array) or characters (string) | `$\{ITEMS|length}` for `["a","b","c"]` | `3` |
+| `contains:"X"` | Boolean: type-aware substring / element membership | `$\{MSG|contains:"urgent"}` for `"Yes, urgent"` | `true` |
+| `fallback:"X"` | Coalesce on missing/undefined/empty ref | `$\{VAR.missing|fallback:"-"}` | `-` |
+| `isodate` | Epoch seconds → ISO-8601 timestamp | `$\{EPOCH|isodate}` for `1779660000` | `2026-05-24T22:00:00.000Z` |
 
 ### `length` semantics
 
@@ -1501,11 +1424,11 @@ The substrate-routing ops (`$ connector.tool`, `$ data_read`, `$ llm`) and the a
 
 ## Five connector types
 
-### MemoryStore
+### DataStore
 
-Routes `$ data_read` retrieval ops. Interface: `MemoryStore.query(filters) → PortableMemory[]`.
+Routes `$ data_read` retrieval ops. Interface: `DataStore.query(filters) → PortableMemory[]`.
 
-Implementations vary by deployment — a knowledge-substrate-backed store, a SQLite-backed store, a vector-DB-backed store, an in-memory test store. All conform to the `MemoryStore.query` contract and return `PortableMemory[]`.
+Implementations vary by deployment — a knowledge-substrate-backed store, a SQLite-backed store, a vector-DB-backed store, an in-memory test store. All conform to the `DataStore.query` contract and return `PortableMemory[]`.
 
 ### LocalModel
 
@@ -1621,7 +1544,7 @@ Skill records are infrastructure, not knowledge atoms — adopter impls should t
 
 All connector types expose `capabilities()` for runtime discovery. Consumers:
 1. `# Requires:` matching against the registered set
-2. Dynamic queries via `listMemoryStores()` / `listLocalModels()` / `listMcpConnectors()` / `listAgentConnectors()` to pick a connector for the moment
+2. Dynamic queries via `listDataStores()` / `listLocalModels()` / `listMcpConnectors()` / `listAgentConnectors()` to pick a connector for the moment
 3. Authoring tools that surface the registered set
 
 ## Multi-instance by design
@@ -1630,7 +1553,7 @@ Multiple instances of the same connector type are the *normal case*, not the exc
 
 ```
 {
-  primary: MemoryStoreImplA,
+  primary: DataStoreImplA,
   project: SqliteProjectStore,
   scratch: InMemoryStore
 }
@@ -1779,7 +1702,7 @@ interface McpDispatchCtx {
 
 Hard-coupling skills to specific substrates would make information-flow decisions infrastructural rather than skill-authored, defeating the point of skills as the agent's programming language. The connector layer is what lets the same skill body run against substrate A today and run against substrate B tomorrow without rewriting.
 
-## Lifecycle and status — # Status: header, six canonical states, compile + runtime enforcement
+## Lifecycle and status — # Status: header, three canonical states (Draft / Approved / Disabled), compile + runtime enforcement
 
 Skillscripts carry an explicit lifecycle state via the `# Status:` header. The compiler and runtime enforce status — a Disabled skillscript cannot fire under any path, regardless of who invokes it.
 
@@ -2037,6 +1960,13 @@ default: fetch
 
 **Recursion guard.** The runtime enforces a configurable recursion-depth limit (default 10) to prevent infinite-loop composition. Exceeding the limit raises a clean structured error attributable to the offending dispatch site, not a stack overflow.
 
+## Error surfacing in composition
+
+Two non-obvious behaviors when reading a child's failures from the parent (both confirmed by the v1.0 runtime-semantics test battery):
+
+- **Nested errors do NOT surface at the top level.** When a child op fails — e.g. the recursion-depth guard fires — the structured error nests inside the child's `R.errors`, which nests inside *its* parent's `R.errors`, and so on up the chain. It does **not** bubble to the caller's top-level `result.errors`. So a top-level `errors: []` does **not** mean nothing failed downstream. To detect a child failure, inspect the bound `${R.errors}` (and deeper), or rely on `(fallback: ...)` / `# OnError:` — those fire on the structured error regardless of nesting depth.
+- **`# Returns: R` is load-bearing for observability.** If the parent binds a child via `-> R` but does not declare `# Returns: R`, the `# Returns:` filter strips `R` from the parent's `final_vars` — and any nested child errors disappear from the parent's MCP-wire response along with it. A composition skill that wants its child's failures observable from *its own* caller must declare the binding (`# Returns: R`) explicitly. Observability of child failure is opt-in, the same way value export is.
+
 ## Forward-reference resolution
 
 Skill references (`inline(skill=...)`, `execute_skill(skill_name=...)`) are validated at compile time but allow forward references with tier-2 advisories — making it possible to author sibling skills together (chicken-and-egg).
@@ -2152,6 +2082,7 @@ For *data skills* (skills marked `# Type: data`), the compile-time inline primit
 
 - Treat composition as a real cost. Each `execute_skill()` dispatch incurs the child's full execution time + side effects. Don't compose for trivial cases that could be inlined.
 - Declare `# Returns:` when a caller needs structured access to a child's variables. Leave it off for emit-only skills whose consumers read `.outputs.text` — the default-empty filter keeps scratch from propagating.
+- Want a child's failures visible to your caller? Declare the child binding in `# Returns:` — nested errors are filtered out with the binding otherwise (see Error surfacing in composition), and don't trust a top-level `errors: []`.
 - Pair composition with `(fallback: ...)` when the child skill might fail and the parent has a sensible degraded path.
 - Use mechanical mode to TestFlight any multi-skill chain before shipping it as a Headless skill on a cron trigger.
 - Forward references work — author sibling skills in any order, validate independently. The tier-2 warning surfaces the deferred-resolution path; runtime catches genuine misses.
@@ -2481,50 +2412,72 @@ Some features depend on others:
 
 The "Not yet implemented, but planned" section at top tracks the user-facing surface; this section preserves the design-order argument for when implementation work picks up.
 
-## Open spec questions — unresolved language design decisions
+## Not yet implemented, but planned
+
+These are features designed or anticipated but not yet implemented in the current build. Authors should not use these forms; they will not compile.
+
+## Control flow
 
-Questions surfaced during design that haven't been resolved. Each carries a current lean where applicable. Resolved items have moved to their canonical sections; this section tracks only what's still open.
+- **`while CONDITION:` loops** — today's iteration is `foreach IDENT in EXPR:` only. While loops are planned for ad-hoc orchestration patterns ("loop until response contains 'done'").
+- **Arithmetic in `$set`** — today accepts literals + `${VAR}` interpolation; no `+ - * /` operators. Planned alongside `while` for turn counters and orchestration bookkeeping.
 
-## 1. Block execution model — write down the rules
+## Pipe filter extensions
+
+- **Array aggregation primitives** — `|max`, `|min`, `|sum`, `|reduce` over arrays. Today the language tops out at "shape one record" — aggregating across an array requires `foreach` accumulator ceremony. Planned as a design question: is `foreach` the deliberate ceiling for aggregation, or do we add primitives?
+
+## Triggers — note
+
+Trigger sources are `cron` + `event` only (see the Triggers section). There is no separate `agent-event:` / `file-watch:` / `sensor:` trigger source — anything that isn't time-based is an external adapter that POSTs to the `/event` ingress. So there's nothing pending here on the trigger axis; the entry remains only to point readers who expect those sources at the adapter-POST pattern.
 
-Within a target body, op ordering and variable binding conventions aren't fully written down. Specific questions:
-- Can `emit()` calls precede `$` ops in the same target? (Yes; `emit()` has no dependency on subsequent ops.)
-- What's the default output binding when `-> NAME` is omitted? (`${target.output}` — same as bare `target` referenced from other blocks.)
-- How do cross-block references work syntactically? (`${other_target.output}` or `${VAR_BOUND_THERE}`.)
 
-**Write a "Block execution model" subsection** in the Overview or Ops reference section. No semantic change, just documentation gap.
+## Tests
 
-## 2. `else:` block visibility into the error
+- **`# Tests:` block** with `given:` / `expect:` assertions — author-authored test cases. Will land when adopter signal demands test infrastructure.
 
-Should `${ERROR}` be an ambient ref inside `else:` blocks, populated with the error type/message? Lean: yes, same shape as `${ERROR_CONTEXT}` in `# OnError:` fallback skills. Useful for logging/telemetry skills.
+## Output kinds
 
-## 3. Multiple triggers — concurrency
+- **`# Output: file: <path>`** — file-output routing parses but no router exists today.
+- **`# Output: card:`** — depends on a substrate-side card render surface; not implemented.
 
-If `cron: 0 8 * * *` and `event: user-present` both fire within seconds, does the skill run twice (independent) or get deduped? Lean: independent. Author dedups via state if needed. Affects dispatch layer.
+## Persistent state with declared scope
 
-## 4. `execute_skill()` invocation vs trigger firing
+```
+$set NAME = value scope=skill-local
+$set NAME = value scope=agent-global
+$set NAME = value scope=session
+```
 
-When skill A invokes skill B via `execute_skill()`, do skill B's `# Triggers:` fire? Almost certainly no — `execute_skill()` is direct invocation, distinct from the trigger event surface. Worth saying explicitly.
+Scopes: skill-local (persists across fires of this skill, not visible to other skills), agent-global (visible to all skills of the same agent), session (alive for the duration of the current session, cleared at session end). Backed by a configured data-records connector.
 
-## 5. Output target delivery failures
 
-If a delivery target is unreachable when the skill fires, what happens? Lean: delivery failure is its own retryable error; queue if possible, else error to caller. Worth a separate small spec section. Affects dispatch layer.
+## Time as first-class primitives
 
-## 6. Skill versioning rollback UX
+Currently `$(NOW)` (wall-clock). Planned relative-time primitives:
 
-Edits via upsert preserve history through substrate versioning (SqliteSkillStore's `skill_versions` table, FilesystemSkillStore's git history), but no first-class "rollback" affordance. Probably needs a `--version <N>` flag on the compile API or a sister tool.
+```
+$(SECONDS_SINCE_LAST_USER_MESSAGE)
+$(MINUTES_SINCE_SESSION_START)
+$(SECONDS_SINCE_LAST_FIRE_OF.<skill-name>)
+```
 
-## 7. Connector capability declarations
+Most "right time" reasoning is relative, not wall-clock.
 
-Skills can declare required connector capabilities via `# Requires:` for var resolution. Extending this to "needs semantic search" / "needs structured-extraction model with 32K context" capabilities would be useful for the substrate-portable story. Pending design.
+## Other planned
 
-## 8. Per-op timeouts
+- **Absence-as-trigger** — `# Triggers: idle: 5m` fire-on-quiet primitive (would be a new trigger source beyond `cron`|`event`, or an adapter that POSTs on a timer)
+- **Time-windowed aggregation** — filter-like primitives across firings (e.g., "user has shown frustration in 3 of 5 recent turns")
+- **Debounce / rate-limit / coalesce** — declarative queueing policy headers
+- **Suppression as valid output** — explicit "fire-and-suppress" (different from `# Output: none`)
+- **Cross-skill pub-sub** — `# Publishes: signal.X` / `# Subscribes: signal.Y` decoupling
+- **Confidence/threshold gating** — `# RequiresConfidence: classifier >= 0.8` / `# RequiresThreshold:`
+- **Invocation-control axis** — `# Invocable-By: user | agent | trigger` (sensitive ops shouldn't leak across invocation boundaries)
+- **Introspection primitives** — `$(PROMPT_CONTEXT.size)`, `$(SKILLS_FIRED_RECENTLY.last-1h)`, `$(SELF.confidence-trend)`
 
-Hung dispatches hang the skill without explicit timeout configuration. Lean: skill-level `# Timeout:` header + per-op `timeout=N` kwarg + runtime defaults. Pending implementation; see "Not yet implemented, but planned" at top.
+## When the language extends, this section shrinks
 
-*(The former "file-watch path semantics" question was removed — `file-watch` is no longer a trigger source; filesystem watching is now an external adapter that POSTs to the `/event` ingress, so there are no in-language file-watch path semantics to settle.)*
+When any of these primitives ship, the relevant grammar moves into its canonical section (Ops reference, Variables, Triggers, etc.) and the entry here is removed. This section stays alive as a continuous staging area for the next horizon of unshipped work.
 
 ---
 
-*Rendered from `skillscript/skillscript-language-reference` — 2026-06-15 18:44 EDT*  
+*Rendered from `skillscript/skillscript-language-reference` — 2026-06-16 15:46 EDT*  
 *Source of truth: AMP (`amp_render_document("skillscript/skillscript-language-reference")`)*

package/docs/sqlite-skill-store.md

@@ -1,4 +1,8 @@
-# SqliteSkillStore — example
+---
+title: SqliteSkillStore
+description: "Worked example of SkillStore against a SQLite database — schema, semantics, forking checklist."
+mode: wide
+---
 
 Worked example of `SkillStore` against a SQLite database. Copy this directory into your codebase, customize per your storage needs, register with skillscript-runtime's `Registry`. This README is written for the agent implementing your adopter's connector — including the human reviewing the PR.
 

package/examples/skillscripts/classify-support-ticket.skill.md

@@ -1,5 +1,5 @@
 # Skill: classify-support-ticket
-# Status: Approved v1:ae27d3f9
+# Status: Draft
 # Autonomous: true
 # Description: Read an incoming support ticket and route it: severity-1 tickets get paged to ops-channel, billing tickets get tagged for finance review, everything else gets a draft reply queued for human review
 # Vars: TICKET_TEXT, TICKET_ID

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

@@ -1,5 +1,5 @@
 # Skill: data-store-roundtrip
-# Status: Approved v1:b37bc111
+# Status: Draft
 # Autonomous: true
 # Description: Round-trips the DataStore — writes a record tagged with a per-run marker in the content, reads it back via FTS query against the same marker. The exact item count depends on substrate FTS matching strictness (strict FTS substrates return 1; substrates with looser token-match semantics may return prior runs' records that share token shapes). If this skill executes and the output line shows N ≥ 1 items returned, your DataStore substrate is wired correctly. For adopters needing deterministic counts (e.g. authoring round-trip tests), the `domain_tags` filter is the portable strict-match read path — see the adopter-playbook §"Notable things..." for the pattern.
 

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

@@ -1,5 +1,5 @@
 # Skill: doc-qa-with-citations
-# Status: Approved v1:dc6e903d
+# Status: Draft
 # 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/feedback-sentiment-scan.skill.md

@@ -1,5 +1,5 @@
 # Skill: feedback-sentiment-scan
-# Status: Approved v1:2b4868c1
+# Status: Draft
 # Description: Each night, scan the previous 24h of customer feedback records, classify sentiment via the local model, and surface entries that read 'frustrated' or 'blocking' so the team sees them at start-of-day.
 # Triggers: cron: 0 3 * * *
 # Vars: SCAN_LIMIT=50

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

@@ -1,5 +1,5 @@
 # Skill: hello-world
-# Status: Approved v1:b662ccd6
+# Status: Draft
 # Description: The canonical first-run example. No substrate dependencies, no compute block — pure declarative output. If this fails to execute, your install or runtime is broken; investigate before troubleshooting deeper layers. Demonstrates the template-only shape: body text IS the skill; `# Vars:` declared inputs feed the template with `--input` override.
 # Vars: WHO=world
 

package/examples/skillscripts/hello-world.skill.provenance.json

@@ -2,7 +2,7 @@
   "provenance_version": "1.0",
   "language_version": "1.0",
   "compiler_version": "0.1.0-dev",
-  "compiled_at": "2026-06-16T13:54:50.151Z",
+  "compiled_at": "2026-06-18T00:42:44.631Z",
   "source_skill": {
     "name": "hello-world"
   },

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

@@ -1,5 +1,5 @@
 # Skill: morning-brief
-# Status: Approved v1:1530981d
+# Status: Draft
 # Description: Compose a daily morning brief from calendar, mailbox, and overnight notes 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. Requires a `calendar` connector configured in connectors.json (the dotted `$ calendar.*` form). `model=qwen` is a representative LocalModel alias — adopters register one under whatever name fits (the bundled bootstrap registers `default`).
 # Vars: AGENT, BRIEF_HORIZON_HOURS=24
 # Triggers: cron: 0 7 * * *

package/examples/skillscripts/queue-length-monitor.skill.md

@@ -1,5 +1,5 @@
 # Skill: queue-length-monitor
-# Status: Approved v1:c6bc06df
+# Status: Draft
 # Description: Count pending items in a queue and alert when the count exceeds threshold. Requires `cat` on the operator's shell allowlist (default-deny: a non-allowlisted binary is refused).
 # Vars: QUEUE_PATH=/var/queue/pending.json, THRESHOLD=10
 # Triggers: cron: */5 * * * *

package/examples/skillscripts/service-health-watch.skill.md

@@ -1,5 +1,5 @@
 # Skill: service-health-watch
-# Status: Approved v1:5378fb77
+# Status: Draft
 # Autonomous: true
 # Description: Every 5 minutes check named service endpoints — if latency or status degrades, write a signal record and alert. Requires `curl` on the operator's shell allowlist (default-deny: a non-allowlisted binary is refused).
 # Vars: SERVICES=[auth-api, ledger-api, search-api], LATENCY_BUDGET_MS=400

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

@@ -1,5 +1,5 @@
 # Skill: skill-store-roundtrip
-# Status: Approved v1:55e43285
+# Status: Draft
 # Autonomous: true
 # Description: Round-trips the SkillStore — writes a child skill, reads it back. Demonstrates the Lisp-shape primitive (skills can write skills). NOTE: 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.
 

package/examples/skillscripts/youtrack-morning-sweep.skill.md

@@ -1,5 +1,5 @@
 # Skill: youtrack-morning-sweep
-# Status: Approved v1:d4c872d9
+# Status: Draft
 # Description: Pull recent YouTrack issues via a configured RemoteMcpConnector + dotted field access on parsed JSON + foreach over the issues array. Requires a `youtrack` connector configured in connectors.json (RemoteMcpConnector class, mcp-remote bridge, newline framing) with allowed_tools including search_issues + get_current_user.
 
 fetch_me:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillscript-runtime",
-  "version": "0.19.16",
+  "version": "0.20.1",
   "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/skills/data-store-roundtrip.skill.md

@@ -1,5 +1,5 @@
 # Skill: data-store-roundtrip
-# Status: Approved v1:b37bc111
+# Status: Draft
 # Autonomous: true
 # Description: Round-trips the DataStore — writes a record tagged with a per-run marker in the content, reads it back via FTS query against the same marker. The exact item count depends on substrate FTS matching strictness (strict FTS substrates return 1; substrates with looser token-match semantics may return prior runs' records that share token shapes). If this skill executes and the output line shows N ≥ 1 items returned, your DataStore substrate is wired correctly. For adopters needing deterministic counts (e.g. authoring round-trip tests), the `domain_tags` filter is the portable strict-match read path — see the adopter-playbook §"Notable things..." for the pattern.
 

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

@@ -1,5 +1,5 @@
 # Skill: hello-world
-# Status: Approved v1:b662ccd6
+# Status: Draft
 # Description: The canonical first-run example. No substrate dependencies, no compute block — pure declarative output. If this fails to execute, your install or runtime is broken; investigate before troubleshooting deeper layers. Demonstrates the template-only shape: body text IS the skill; `# Vars:` declared inputs feed the template with `--input` override.
 # Vars: WHO=world
 

package/scaffold/skills/skill-store-roundtrip.skill.md

@@ -1,5 +1,5 @@
 # Skill: skill-store-roundtrip
-# Status: Approved v1:55e43285
+# Status: Draft
 # Autonomous: true
 # Description: Round-trips the SkillStore — writes a child skill, reads it back. Demonstrates the Lisp-shape primitive (skills can write skills). NOTE: 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.