aw-spec-cli 0.1.5 → 0.1.7

package/assets/.aw-spec/interpreter/run-skill.py

@@ -1,1158 +0,0 @@
-#!/usr/bin/env python3
-"""
-run-skill.py — reference interpreter for aw-spec declarative skills
-(dialect: aw-spec.declarative/v1).
-
-╔══════════════════════════════════════════════════════════════════════════════╗
-║ RETIRED AS AN ENTRY POINT — BUT DO NOT DELETE THIS FILE.                      ║
-║                                                                              ║
-║ The declarative tier it drove (the `aw-spec-decl-*` skills across .claude/,   ║
-║ .agents/ and .kilocode/) was removed 2026-08-03; nothing launches this        ║
-║ interpreter any more. It survives for ONE reason:                            ║
-║                                                                              ║
-║   .aw-spec/orchestrator/orchestrator.py imports this module at load time      ║
-║   for its YAML-subset loader (`load_yaml`) — see orchestrator.py ~L112.       ║
-║                                                                              ║
-║ Deleting this file makes EVERY orchestrator workflow fail with               ║
-║ FileNotFoundError before a single step runs. Fold `load_yaml` into            ║
-║ orchestrator.py first if you want this gone.                                 ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-
-This was the "no-prompt" execution path: it PARSES a skill.yaml and EXECUTES the
-`workflow:` itself. The model is invoked in exactly one place — the `llm_generate`
-action — and only to author content. Everything else (loading context, verifying,
-running the shared scripts, dispatching hooks, interactive selection) is done here.
-
-Stdlib only — no PyYAML dependency. A compact YAML-subset loader (loader tuned to
-the dialect) is bundled below and validated against a full YAML parser in tests.
-
-Usage:
-  run-skill.py <skill.yaml> [--input "<user input>"] [--select name=value ...]
-               [--llm mock|command:<cmd>|agent] [--os posix|windows] [--dry-run] [--json]
-  run-skill.py <skill.yaml> --validate [--json]     # lint without executing
-
-LLM backends:
-  --llm mock              (default) writes a deterministic placeholder file; no model call.
-  --llm command:<cmd>     pipes the resolved prompt on stdin to <cmd>; stdout is the content.
-  --llm agent             defers each llm_generate to the CALLING agent (e.g. Claude):
-                          the interpreter records the request in `pending_generation`
-                          and continues; the agent authors the content afterward.
-"""
-import argparse
-import json
-import os
-import re
-import subprocess
-import sys
-
-# ─────────────────────────────────────────────────────────────────────────────
-# Minimal YAML-subset loader
-#
-# Supports the constructs the dialect uses: nested block mappings, block
-# sequences (items may sit at the parent key's indent), inline flow maps/lists,
-# literal block scalars ("|"), quoted/plain scalars, comments, bool/int/null.
-# Not a general YAML parser — intentionally small and predictable.
-# ─────────────────────────────────────────────────────────────────────────────
-class YamlError(Exception):
-    pass
-
-
-def _indent(line):
-    return len(line) - len(line.lstrip(" "))
-
-
-def _strip_comment(s):
-    """Strip a trailing ' #...' comment that is outside quotes/flow."""
-    out, i, depth = [], 0, 0
-    quote = None
-    while i < len(s):
-        c = s[i]
-        if quote:
-            out.append(c)
-            if c == quote:
-                quote = None
-        elif c in ("'", '"'):
-            quote = c
-            out.append(c)
-        elif c in "[{":
-            depth += 1
-            out.append(c)
-        elif c in "]}":
-            depth = max(0, depth - 1)
-            out.append(c)
-        elif c == "#" and depth == 0 and (i == 0 or s[i - 1] == " "):
-            break
-        else:
-            out.append(c)
-        i += 1
-    return "".join(out).rstrip()
-
-
-def _scalar(tok):
-    tok = tok.strip()
-    if tok == "" or tok == "~" or tok.lower() == "null":
-        return None
-    if len(tok) >= 2 and tok[0] == tok[-1] and tok[0] in "'\"":
-        return tok[1:-1]
-    low = tok.lower()
-    if low == "true":
-        return True
-    if low == "false":
-        return False
-    if re.fullmatch(r"-?\d+", tok):
-        return int(tok)
-    if re.fullmatch(r"-?\d+\.\d+", tok):
-        return float(tok)
-    return tok
-
-
-def _parse_flow(s):
-    """Parse a JSON-ish flow scalar: {a: b, c: [x, y]} / [a, b] / plain."""
-    s = s.strip()
-    pos = [0]
-
-    def skip_ws():
-        while pos[0] < len(s) and s[pos[0]] in " \t":
-            pos[0] += 1
-
-    def parse_value():
-        skip_ws()
-        if pos[0] >= len(s):
-            return None
-        c = s[pos[0]]
-        if c == "{":
-            return parse_map()
-        if c == "[":
-            return parse_list()
-        return _scalar(read_until(",]}"))
-
-    def read_until(stops):
-        start = pos[0]
-        quote = None
-        while pos[0] < len(s):
-            ch = s[pos[0]]
-            if quote:
-                if ch == quote:
-                    quote = None
-            elif ch in "'\"":
-                quote = ch
-            elif ch in stops:
-                break
-            pos[0] += 1
-        return s[start:pos[0]]
-
-    def parse_map():
-        obj = {}
-        pos[0] += 1  # {
-        skip_ws()
-        if pos[0] < len(s) and s[pos[0]] == "}":
-            pos[0] += 1
-            return obj
-        while True:
-            skip_ws()
-            key = read_until(":").strip()
-            if pos[0] < len(s) and s[pos[0]] == ":":
-                pos[0] += 1
-            val = parse_value()
-            obj[_scalar(key)] = val
-            skip_ws()
-            if pos[0] < len(s) and s[pos[0]] == ",":
-                pos[0] += 1
-                continue
-            if pos[0] < len(s) and s[pos[0]] == "}":
-                pos[0] += 1
-            break
-        return obj
-
-    def parse_list():
-        arr = []
-        pos[0] += 1  # [
-        skip_ws()
-        if pos[0] < len(s) and s[pos[0]] == "]":
-            pos[0] += 1
-            return arr
-        while True:
-            arr.append(parse_value())
-            skip_ws()
-            if pos[0] < len(s) and s[pos[0]] == ",":
-                pos[0] += 1
-                continue
-            if pos[0] < len(s) and s[pos[0]] == "]":
-                pos[0] += 1
-            break
-        return arr
-
-    if s and s[0] in "[{":
-        return parse_value()
-    return _scalar(s)
-
-
-class _Lines:
-    def __init__(self, text):
-        self.raw = text.splitlines()
-        self.i = 0
-
-    def peek(self):
-        while self.i < len(self.raw):
-            line = self.raw[self.i]
-            stripped = line.strip()
-            if stripped == "" or stripped.startswith("#"):
-                self.i += 1
-                continue
-            return line
-        return None
-
-    def next(self):
-        line = self.peek()
-        if line is not None:
-            self.i += 1
-        return line
-
-
-def _parse_block(lines, min_indent):
-    line = lines.peek()
-    if line is None or _indent(line) < min_indent:
-        return None
-    indent = _indent(line)
-    if line.strip().startswith("- "):
-        return _parse_seq(lines, indent)
-    return _parse_map(lines, indent)
-
-
-def _parse_map(lines, indent):
-    obj = {}
-    while True:
-        line = lines.peek()
-        if line is None or _indent(line) != indent or line.strip().startswith("- "):
-            break
-        content = _strip_comment(line.strip())
-        m = re.match(r"^(.*?):(?:\s+(.*))?$", content)
-        if not m:
-            raise YamlError(f"bad mapping line: {line!r}")
-        key = _scalar(m.group(1))
-        rest = m.group(2)
-        lines.next()
-        if rest is None or rest == "":
-            child = _parse_block(lines, indent + 1)
-            obj[key] = child
-        elif rest in ("|", "|-", "|+", ">", ">-", ">+"):
-            obj[key] = _parse_block_scalar(lines, indent, folded=rest[0] == ">",
-                                           chomp=(rest[1:] or ""))
-        elif rest[0] in "[{":
-            obj[key] = _parse_flow(rest)
-        else:
-            obj[key] = _scalar(rest)
-    return obj
-
-
-def _parse_seq(lines, indent):
-    arr = []
-    while True:
-        line = lines.peek()
-        if line is None or _indent(line) != indent or not line.strip().startswith("- "):
-            break
-        content = _strip_comment(line.strip()[2:])
-        lines.next()
-        if content == "":
-            arr.append(_parse_block(lines, indent + 1))
-        elif content[0] in "[{":
-            arr.append(_parse_flow(content))
-        elif re.match(r"^.*?:(?:\s+.*)?$", content) and ":" in content:
-            # inline map entry starting on the "- " line; parse it + following keys
-            m = re.match(r"^(.*?):(?:\s+(.*))?$", content)
-            item = {}
-            key = _scalar(m.group(1))
-            rest = m.group(2)
-            if rest is None or rest == "":
-                item[key] = _parse_block(lines, indent + 2)
-            elif rest[0] in "[{":
-                item[key] = _parse_flow(rest)
-            else:
-                item[key] = _scalar(rest)
-            # subsequent sibling keys at indent+2
-            sub = _parse_map(lines, indent + 2)
-            if sub:
-                item.update(sub)
-            arr.append(item)
-        else:
-            arr.append(_scalar(content))
-    return arr
-
-
-def load_yaml(text):
-    lines = _Lines(text)
-    result = _parse_block(lines, 0)
-    return result if result is not None else {}
-
-
-def _parse_block_scalar(lines, parent_indent, folded, chomp):
-    """Collect a block scalar ('|' literal or '>' folded) with chomping.
-
-    chomp: '' clip (single trailing \\n), '-' strip, '+' keep all trailing \\n.
-    """
-    block, block_indent = [], None
-    while lines.i < len(lines.raw):
-        raw = lines.raw[lines.i]
-        if raw.strip() == "":
-            block.append("")
-            lines.i += 1
-            continue
-        if _indent(raw) <= parent_indent:
-            break
-        if block_indent is None:
-            block_indent = _indent(raw)
-        block.append(raw[block_indent:])
-        lines.i += 1
-
-    trailing = 0
-    while block and block[-1] == "":
-        block.pop()
-        trailing += 1
-
-    if folded:
-        text = ""
-        for i, ln in enumerate(block):
-            if i == 0:
-                text = ln
-            else:
-                text += ("\n" if (block[i - 1] == "" or ln == "") else " ") + ln
-    else:
-        text = "\n".join(block)
-
-    if chomp == "-":
-        return text
-    if chomp == "+":
-        return text + "\n" * (trailing + 1 if block else trailing)
-    return text + "\n"  # clip
-
-
-# ─────────────────────────────────────────────────────────────────────────────
-# Interpreter
-# ─────────────────────────────────────────────────────────────────────────────
-class Stop(Exception):
-    pass
-
-
-class Suspend(Exception):
-    """Raised in checkpoint mode when the interpreter needs the agent (generate a
-    file / answer a query / ask a question). Carries the typed request."""
-    def __init__(self, request):
-        self.request = request
-
-
-class Interp:
-    def __init__(self, skill, opts):
-        self.skill = skill
-        self.opts = opts
-        self.vars = {}
-        self.context = []          # ordered list of loaded file paths
-        self.log = []
-        self.pending = []          # deferred llm_generate requests (--llm agent)
-        # checkpoint mode: replay + response cache keyed by invocation path
-        self.checkpoint = getattr(opts, "checkpoint", None)
-        self.cache = getattr(opts, "_cache", {}) or {}
-        self.key_stack = []        # loop-aware invocation-key prefix
-        # session context ledger: files loaded by earlier commands this session
-        self.session_loaded = set(getattr(opts, "_session_loaded", None) or set())
-        self.ledger_path = getattr(opts, "_ledger_path", None)
-        self.session_id = getattr(opts, "session", None)
-
-    # -- helpers --------------------------------------------------------------
-    def emit(self, msg):
-        self.log.append(msg)
-        if not self.opts.json:
-            print(msg)
-
-    def _lookup(self, key):
-        """Dotted lookup into vars: 'q.text', 'items.0'. Returns (found, value)."""
-        parts = key.split(".")
-        if parts[0] not in self.vars:
-            return (False, None)
-        cur = self.vars[parts[0]]
-        for pth in parts[1:]:
-            if isinstance(cur, dict) and pth in cur:
-                cur = cur[pth]
-            elif isinstance(cur, list) and pth.isdigit() and int(pth) < len(cur):
-                cur = cur[int(pth)]
-            else:
-                return (False, None)
-        return (True, cur)
-
-    def resolve(self, val):
-        """Recursively substitute {{name}} / {{a.b}} in strings using self.vars."""
-        if isinstance(val, str):
-            def sub(m):
-                found, v = self._lookup(m.group(1).strip())
-                if not found:
-                    return m.group(0)
-                return v if isinstance(v, str) else json.dumps(v)
-            return re.sub(r"\{\{\s*([^}]+?)\s*\}\}", sub, val)
-        if isinstance(val, list):
-            return [self.resolve(x) for x in val]
-        if isinstance(val, dict):
-            return {k: self.resolve(v) for k, v in val.items()}
-        return val
-
-    def resolve_value(self, x):
-        """Like resolve, but if x is exactly one {{ref}} return the raw object
-        (list/dict/bool), not a stringified form."""
-        if isinstance(x, str):
-            m = re.fullmatch(r"\{\{\s*([^}]+?)\s*\}\}", x.strip())
-            if m:
-                found, v = self._lookup(m.group(1).strip())
-                return v if found else x
-            return self.resolve(x)
-        return x
-
-    def truthy(self, v):
-        if isinstance(v, str):
-            return v.strip() not in ("", "false", "False", "None", "null", "[]")
-        return bool(v)
-
-    def eval_condition(self, expr):
-        expr = self.resolve(expr).strip()
-        for op in ("==", "!="):
-            if op in expr:
-                lhs, rhs = [s.strip().strip("'\"") for s in expr.split(op, 1)]
-                return (lhs == rhs) if op == "==" else (lhs != rhs)
-        return self.truthy(expr)
-
-    # -- checkpoint helpers ---------------------------------------------------
-    def _key(self, step):
-        """Stable, loop-aware invocation key for a step (for the replay cache)."""
-        return "/".join(self.key_stack + [step.get("id", "?")])
-
-    def _suspend(self, request):
-        """Persist a pending agent-request and raise Suspend."""
-        request["response_path"] = self.checkpoint + ".response"
-        raise Suspend(request)
-
-    def script_path(self, ref):
-        s = self.skill.get("scripts", {}).get(ref, {})
-        variant = "ps1" if self.opts.os == "windows" else "sh"
-        return s.get(variant)
-
-    def act_include(self, step):
-        """Run a reusable workflow module inline — shares vars, context, cache, and
-        the caller's `scripts:` map. `with:` seeds module inputs; the module's steps
-        are namespaced under the include id for stable checkpoint keys."""
-        module_path = self.resolve(step.get("module", ""))
-        for k, v in (step.get("with", {}) or {}).items():
-            self.vars[k] = self.resolve_value(v)
-        try:
-            with open(module_path, encoding="utf-8") as fh:
-                mod = load_yaml(fh.read())
-        except OSError as e:
-            raise YamlError(f"include: module not found: {module_path} ({e})")
-        self.emit(f"[include] {module_path}")
-        self.key_stack.append("inc:" + step.get("id", "include"))
-        try:
-            self._run_steps(mod.get("workflow", []) or [])
-        finally:
-            self.key_stack.pop()
-
-    def json_get(self, obj, path):
-        if not path.startswith("$."):
-            return obj.get(path) if isinstance(obj, dict) else None
-        cur = obj
-        for part in path[2:].split("."):
-            if isinstance(cur, dict):
-                cur = cur.get(part)
-            else:
-                return None
-        return cur
-
-    # -- actions --------------------------------------------------------------
-    def run(self):
-        self._run_steps(self.skill.get("workflow", []))
-        return 0
-
-    def _run_steps(self, steps):
-        """Run a list of steps. Returns 'break' if a break bubbled up, else None."""
-        for step in steps:
-            cond = step.get("condition")
-            if cond is not None and not self.eval_condition(cond):
-                self.emit(f"[skip] {step.get('id')} (condition false)")
-                continue
-            action = step.get("action")
-            if action == "break":
-                self.emit(f"[break] {step.get('id', '')}")
-                return "break"
-            if action == "loop":
-                self.act_loop(step)   # a break inside is consumed by the loop itself
-                continue
-            fn = getattr(self, f"act_{action}", None)
-            if fn is None:
-                raise YamlError(f"unknown action: {action}")
-            fn(step)
-        return None
-
-    def act_loop(self, step):
-        """foreach (`over:` a list var) or while (`while:` + `max_iterations`)."""
-        as_name = step.get("as", "item")
-        max_it = step.get("max_iterations")
-        substeps = step.get("steps", []) or []
-        if "over" in step:
-            items = self.resolve_value(step["over"]) or []
-            if not isinstance(items, list):
-                raise YamlError(f"loop 'over' is not a list: {step.get('over')}")
-            loop_id = step.get("id", "loop")
-            for idx, item in enumerate(items):
-                if max_it is not None and idx >= max_it:
-                    break
-                self.vars[as_name] = item
-                self.vars[as_name + "_index"] = idx
-                self.key_stack.append(f"{loop_id}#{idx}")
-                try:
-                    brk = self._run_steps(substeps)
-                finally:
-                    self.key_stack.pop()
-                if brk == "break":
-                    break        # break exits THIS loop (consumed here), not the caller
-            return None
-        # while variant
-        cond = step.get("while", "true")
-        loop_id = step.get("id", "loop")
-        i = 0
-        while self.eval_condition(cond):
-            if max_it is not None and i >= max_it:
-                break
-            self.vars[as_name + "_index"] = i
-            self.key_stack.append(f"{loop_id}#{i}")
-            try:
-                brk = self._run_steps(substeps)
-            finally:
-                self.key_stack.pop()
-            if brk == "break":
-                break        # break exits THIS while-loop (consumed here)
-            i += 1
-        return None
-
-    def _bind_outputs(self, step, data):
-        for out in step.get("outputs", []) or []:
-            self.vars[out["name"]] = self.json_get(data, out["from"])
-
-    def act_load_context(self, step):
-        p = step.get("parameters", {})
-        files = p.get("files") or []
-        if p.get("files_from_variable"):
-            var = self.vars.get(p["files_from_variable"]) or []
-            files = [{"path": x} for x in var]
-        step_optional = p.get("optional", False)
-        for f in files:
-            path = self.resolve(f["path"] if isinstance(f, dict) else f)
-            optional = f.get("optional", step_optional) if isinstance(f, dict) else step_optional
-            if p.get("deduplicate") and path in self.context:
-                self.emit(f"[load_context] dedup skip {path}")
-                continue
-            # session ledger: a file already loaded by an EARLIER command in this
-            # agent session is already in the model's context — don't reload/re-attach.
-            if path in self.session_loaded:
-                self.emit(f"[load_context] session-dedup skip {path} (loaded earlier this session)")
-                continue
-            if os.path.exists(path):
-                self.context.append(path)
-                self.emit(f"[load_context] loaded {path}")
-            elif optional:
-                self.emit(f"[load_context] optional missing, skip {path}")
-            else:
-                raise YamlError(f"required context file missing: {path}")
-
-    def act_verify_context(self, step):
-        p = step.get("parameters", {})
-        if p.get("require_non_empty"):
-            var = p["require_non_empty"]
-            val = self.vars.get(var)
-            if not val:
-                self.emit(f"[verify_context] {var} is empty: {p.get('on_empty_message','')}")
-                if p.get("on_empty") == "stop":
-                    raise Stop(p.get("on_empty_message", "stopped"))
-            else:
-                self.emit(f"[verify_context] {var} non-empty ({len(val)})")
-        if p.get("require_true"):
-            var = p["require_true"]
-            if not self.truthy(self.vars.get(var)):
-                msg = self.resolve(p.get("on_false_message", f"{var} is not satisfied"))
-                self.emit(f"[verify_context] gate failed ({var}): {msg}")
-                if p.get("on_false", "stop") == "stop":
-                    raise Stop(msg)
-            else:
-                self.emit(f"[verify_context] gate ok ({var})")
-        if p.get("require_value"):
-            var = p["require_value"]
-            actual = str(self.vars.get(var, ""))
-            expected = str(self.resolve(p.get("equals", "")))
-            if actual != expected:
-                msg = self.resolve(p.get("on_mismatch_message", f"{var} != {expected}"))
-                self.emit(f"[verify_context] value gate failed ({var}={actual!r}): {msg}")
-                if p.get("on_mismatch", "stop") == "stop":
-                    raise Stop(msg)
-            else:
-                self.emit(f"[verify_context] value gate ok ({var}=={expected})")
-        for rf in p.get("required_files", []) or []:
-            rf = self.resolve(rf)
-            present = rf in self.context or os.path.exists(rf)
-            if present:
-                self.emit(f"[verify_context] present {rf}")
-            elif p.get("allow_missing"):
-                self.emit(f"[verify_context] missing (allowed) {rf}")
-            else:
-                raise YamlError(f"required file not in context: {rf}")
-
-    def act_execute_script(self, step):
-        p = step.get("parameters", {})
-        ref = p["script"]["ref"]
-        script = self.script_path(ref)
-        if not script or not os.path.exists(script):
-            raise YamlError(f"script not found for ref '{ref}': {script}")
-        args = [self.resolve(a) for a in (p.get("args") or [])]
-        # checkpoint replay: reuse cached output, don't re-run the side effect
-        ck = self._key(step)
-        if self.checkpoint and ck in self.cache:
-            self._bind_outputs(step, self.cache[ck])
-            self.emit(f"[execute_script] {p['subcommand']} (cached)")
-            return
-        runner = ["pwsh", "-NoProfile", "-File", script] if self.opts.os == "windows" else ["bash", script]
-        cmd = runner + [p["subcommand"]] + args
-        self.emit(f"[execute_script] {p['subcommand']} {' '.join(args)}")
-        if self.opts.dry_run:
-            self._bind_outputs(step, {})
-            return
-        proc = subprocess.run(cmd, capture_output=True, text=True)
-        if proc.returncode != 0:
-            raise YamlError(f"script failed ({p['subcommand']}): {proc.stderr.strip()}")
-        try:
-            data = json.loads(proc.stdout.strip().splitlines()[-1])
-        except Exception as e:
-            raise YamlError(f"script did not return JSON ({p['subcommand']}): {proc.stdout!r} ({e})")
-        self._bind_outputs(step, data)
-        if self.checkpoint:
-            self.cache[ck] = data
-        self.emit(f"[execute_script] -> {json.dumps(data)}")
-
-    def act_dispatch_hooks(self, step):
-        p = step.get("parameters", {})
-        # checkpoint replay: don't re-dispatch hooks already handled
-        ck = self._key(step)
-        if self.checkpoint and ck in self.cache:
-            self.emit("[dispatch_hooks] (cached)")
-            return
-        hooks = self.vars.get(p.get("hooks_from_variable")) or []
-        if hooks:
-            for h in hooks:
-                kind = "mandatory" if not h.get("optional") else "optional"
-                self.emit(f"[dispatch_hooks] {kind}: {h.get('slash')} ({h.get('extension')})")
-                # An agent runs the slash command here; the interpreter records intent.
-        else:
-            self.emit("[dispatch_hooks] none")
-        if self.checkpoint:
-            self.cache[ck] = True
-
-    def act_user_select(self, step):
-        p = step.get("parameters", {})
-        options = self.vars.get(p.get("options_from_variable")) or []
-        # Direct-argument fast path
-        pre = p.get("preselect_from")
-        pre_val = self.vars.get(pre) if pre else None
-        chosen = None
-        if pre_val and pre_val in options:
-            chosen = pre_val
-        elif self.opts.selects.get(step.get("id")):
-            chosen = self.opts.selects[step["id"]]
-        elif len(options) == 1 and p.get("single_option_confirm"):
-            chosen = options[0]
-        elif self.opts.non_interactive:
-            chosen = options[0] if options else None
-        else:
-            chosen = self._prompt_choice(p.get("prompt", "Select:"), options)
-        if not chosen:
-            raise Stop("selection cancelled")
-        self.vars["selection"] = chosen
-        for out in step.get("outputs", []) or []:
-            src = out["from"]
-            self.vars[out["name"]] = chosen if src == "selection" else self.vars.get(src)
-        self.emit(f"[user_select] chosen: {chosen}")
-
-    def _prompt_choice(self, prompt, options):
-        print(prompt)
-        for i, o in enumerate(options, 1):
-            print(f"  {i}) {o}")
-        try:
-            raw = input("> ").strip()
-        except EOFError:
-            return None
-        if raw.isdigit() and 1 <= int(raw) <= len(options):
-            return options[int(raw) - 1]
-        return raw if raw in options else None
-
-    def act_ask(self, step):
-        """Single or multi-select question. Answer sources, in order:
-           --answer <key>=<value>  (key = resolved `answer_key`, else step id)
-           interactive stdin        (unless --non-interactive)
-        Binds the answer to `answer_var` (default 'answer')."""
-        p = step.get("parameters", {})
-        prompt = self.resolve(p.get("prompt", "?"))
-        options = []
-        if p.get("options_from"):
-            options = self.resolve_value(p["options_from"]) or []
-        elif p.get("options_from_variable"):
-            options = self.vars.get(p["options_from_variable"]) or []
-        elif p.get("options"):
-            options = [self.resolve(o) for o in p["options"]]
-        multi = bool(p.get("multi"))
-        key = self.resolve(p["answer_key"]) if p.get("answer_key") else step.get("id", "")
-        var = p.get("answer_var", "answer")
-
-        ck = self._key(step)
-        if self.checkpoint and ck in self.cache:
-            self.vars[var] = self.cache[ck]
-            self.emit(f"[ask] {key} -> {self.cache[ck]} (cached)")
-            return
-
-        raw = self.opts.answers.get(key)
-        if raw is None and self.checkpoint:
-            # need the agent/user — suspend with an ask request
-            self._suspend({"kind": "ask", "key": key, "step": ck,
-                           "prompt": prompt, "options": options, "multi": multi})
-        if raw is None and self.opts.non_interactive:
-            raw = ",".join(str(o) for o in options) if multi else (options[0] if options else "")
-        if raw is None:
-            raw = self._prompt_choice(prompt, options) if options else \
-                (input(prompt + " ").strip() if not self.opts.non_interactive else "")
-        if raw is None:
-            raise Stop("question cancelled")
-        # multi-select: split on commas and DROP empties, so "" => [] (empty selection)
-        answer = [s.strip() for s in str(raw).split(",") if s.strip()] if multi else raw
-        self.vars[var] = answer
-        if self.checkpoint:
-            self.cache[ck] = answer
-        self.emit(f"[ask] {key} -> {answer}")
-
-    def act_set(self, step):
-        """Set variables from literals/expressions (parameters: {name: value})."""
-        for k, v in (step.get("parameters", {}) or {}).items():
-            self.vars[k] = self.resolve_value(v)
-        self.emit(f"[set] {list((step.get('parameters') or {}).keys())}")
-
-    def act_llm_query(self, step):
-        """In-run LLM call that returns STRUCTURED JSON bound to vars via outputs[].
-        Requires a synchronous backend (mock/command); not available with --llm agent."""
-        p = step.get("parameters", {})
-        ck = self._key(step)
-        if self.checkpoint and ck in self.cache:
-            self._bind_outputs(step, self.cache[ck])
-            self.emit(f"[llm_query] (cached) -> {json.dumps(self.cache[ck])[:120]}")
-            return
-        prompt = self.resolve(p.get("prompt", ""))
-        ctx_files = [self.resolve_value(c) for c in (p.get("context") or [])]
-        ctx_files = [c for c in ctx_files if isinstance(c, str)]
-        if p.get("include_loaded_context", True):
-            for c in self.context:
-                if c not in ctx_files:
-                    ctx_files.append(c)
-        if self.checkpoint:
-            self._suspend({"kind": "llm_query", "step": ck,
-                           "prompt": prompt, "context": ctx_files})
-        if self.opts.llm == "agent":
-            raise YamlError("llm_query needs a synchronous --llm backend "
-                            "(mock/command:...) or --checkpoint, not --llm agent")
-        raw = self._invoke_llm(prompt, ctx_files, None)
-        try:
-            data = json.loads(raw.strip().splitlines()[-1] if raw.strip() else "{}")
-        except Exception as e:
-            raise YamlError(f"llm_query did not return JSON: {raw!r} ({e})")
-        self._bind_outputs(step, data)
-        self.emit(f"[llm_query] -> {json.dumps(data)[:200]}")
-
-    def act_llm_generate(self, step):
-        p = step.get("parameters", {})
-        prompt = self.resolve(p.get("prompt", ""))
-        ctx_files = [self.resolve(c) for c in (p.get("context") or [])]
-        # Fix #1: augment with everything pulled in by load_context so the standards
-        # and domain rules actually reach generation (dedup, order-preserving).
-        if p.get("include_loaded_context", True):
-            for c in self.context:
-                if c not in ctx_files:
-                    ctx_files.append(c)
-        target = self.resolve(p["output_target"]["path"])
-        ck = self._key(step)
-        # checkpoint replay: rewrite the target from cached content (idempotent)
-        if self.checkpoint and ck in self.cache:
-            os.makedirs(os.path.dirname(target) or ".", exist_ok=True)
-            with open(target, "w", encoding="utf-8") as fh:
-                fh.write(self.cache[ck])
-            self.emit(f"[llm_generate] (cached) rewrote {target}")
-            return
-        self.emit(f"[llm_generate] context={ctx_files} -> {target}")
-        if self.checkpoint:
-            self._suspend({"kind": "llm_generate", "step": ck, "target": target,
-                           "prompt": prompt, "context": ctx_files})
-        if self.opts.llm == "agent":
-            # Defer generation to the calling agent (e.g. Claude). The interpreter
-            # does NOT write the file; it records the request and continues the
-            # remaining deterministic steps. The agent fulfills these afterward.
-            self.pending.append({"target": target, "context": ctx_files, "prompt": prompt})
-            self.emit("[llm_generate] deferred to agent (see pending_generation)")
-            return
-        content = self._invoke_llm(prompt, ctx_files, target)
-        if self.opts.dry_run:
-            self.emit("[llm_generate] dry-run: not writing")
-            return
-        os.makedirs(os.path.dirname(target) or ".", exist_ok=True)
-        with open(target, "w", encoding="utf-8") as fh:
-            fh.write(content)
-        self.emit(f"[llm_generate] wrote {len(content)} chars")
-
-    def _invoke_llm(self, prompt, ctx_files, target):
-        backend = self.opts.llm
-        if backend.startswith("command:"):
-            cmd = backend[len("command:"):]
-            ctx_blob = ""
-            for c in ctx_files:
-                if os.path.exists(c):
-                    ctx_blob += f"\n\n===== CONTEXT: {c} =====\n" + open(c, encoding="utf-8").read()
-            proc = subprocess.run(cmd, shell=True, input=prompt + ctx_blob,
-                                  capture_output=True, text=True)
-            if proc.returncode != 0:
-                raise YamlError(f"llm command failed: {proc.stderr.strip()}")
-            return proc.stdout
-        # mock backend — deterministic, no model call
-        return (
-            "<!-- generated by run-skill.py mock LLM backend -->\n"
-            f"<!-- target: {target} -->\n"
-            f"<!-- context files: {', '.join(ctx_files)} -->\n"
-            f"<!-- prompt chars: {len(prompt)} -->\n\n"
-            "# (mock content)\n\nReplace --llm mock with a real backend to author this file.\n"
-        )
-
-
-# ─────────────────────────────────────────────────────────────────────────────
-# Static validator (--validate): lints a skill.yaml without executing it.
-# ─────────────────────────────────────────────────────────────────────────────
-KNOWN_ACTIONS = {
-    "load_context", "verify_context", "execute_script",
-    "dispatch_hooks", "user_select", "llm_generate",
-    "loop", "ask", "llm_query", "set", "break", "include",
-}
-_SPECIAL_VARS = {"selection", "answer"}
-
-
-def _refs_in(v):
-    found = set()
-    if isinstance(v, str):
-        for m in re.findall(r"\{\{\s*([^}]+?)\s*\}\}", v):
-            found.add(m.strip())
-    elif isinstance(v, list):
-        for x in v:
-            found |= _refs_in(x)
-    elif isinstance(v, dict):
-        for x in v.values():
-            found |= _refs_in(x)
-    return found
-
-
-def validate_skill(skill, base_dir):
-    errors, warnings = [], []
-    if not isinstance(skill, dict):
-        return (["top-level YAML is not a mapping"], [])
-
-    wf = skill.get("workflow")
-    if not isinstance(wf, list) or not wf:
-        errors.append("missing or empty 'workflow' list")
-        wf = wf if isinstance(wf, list) else []
-    scripts = skill.get("scripts", {}) or {}
-
-    def walk(steps):
-        for s in steps or []:
-            if isinstance(s, dict):
-                yield s
-                if s.get("action") == "loop":
-                    yield from walk(s.get("steps"))
-
-    produced = set(_SPECIAL_VARS)
-    for _, spec in (skill.get("inputs") or {}).items():
-        if isinstance(spec, dict) and spec.get("bind"):
-            produced.add(spec["bind"])
-    # pre-scan everything that produces variables (recursively) so ordering /
-    # forward references don't false-alarm
-    for step in walk(wf):
-        for o in step.get("outputs") or []:
-            if isinstance(o, dict) and o.get("name"):
-                produced.add(o["name"])
-        p = step.get("parameters", {}) or {}
-        act = step.get("action")
-        if act == "ask":
-            produced.add(p.get("answer_var", "answer"))
-        elif act == "set":
-            produced.update((step.get("parameters") or {}).keys())
-        elif act == "loop" and step.get("as"):
-            produced.add(step["as"])
-            produced.add(step["as"] + "_index")
-        elif act == "include":
-            # vars the module seeds + produces become available to the caller
-            produced.update((step.get("with") or {}).keys())
-            mpath = step.get("module", "")
-            for cand in (mpath, os.path.join(base_dir, mpath)):
-                if mpath and os.path.exists(cand):
-                    try:
-                        mwf = load_yaml(open(cand, encoding="utf-8").read()).get("workflow", [])
-                        for ms in walk(mwf):
-                            for o in ms.get("outputs") or []:
-                                if isinstance(o, dict) and o.get("name"):
-                                    produced.add(o["name"])
-                            mp = ms.get("parameters", {}) or {}
-                            if ms.get("action") == "ask":
-                                produced.add(mp.get("answer_var", "answer"))
-                            elif ms.get("action") == "set":
-                                produced.update((ms.get("parameters") or {}).keys())
-                    except Exception:
-                        pass
-                    break
-
-    seen_ids = set()
-    for step in walk(wf):
-        loc = step.get("id") or "step"
-        sid = step.get("id")
-        if not sid:
-            warnings.append(f"{loc}: missing id")
-        elif sid in seen_ids:
-            errors.append(f"duplicate step id: {sid}")
-        else:
-            seen_ids.add(sid)
-
-        action = step.get("action")
-        if action not in KNOWN_ACTIONS:
-            errors.append(f"{loc}: unknown action '{action}' (known: {', '.join(sorted(KNOWN_ACTIONS))})")
-        p = step.get("parameters", {}) or {}
-
-        if action == "loop" and "over" not in step and "while" not in step:
-            errors.append(f"{loc}: loop needs 'over:' or 'while:'")
-        if action == "ask" and not (p.get("options_from") or p.get("options_from_variable") or p.get("options")):
-            warnings.append(f"{loc}: ask has no options source (free-text input)")
-        if action == "include":
-            m = step.get("module")
-            if not m:
-                errors.append(f"{loc}: include needs 'module'")
-            elif not (os.path.exists(m) or os.path.exists(os.path.join(base_dir, m))):
-                warnings.append(f"{loc}: include module not found on disk: {m}")
-        if action == "llm_query" and not (step.get("outputs")):
-            warnings.append(f"{loc}: llm_query has no outputs[] to bind")
-
-        if action == "execute_script":
-            ref = (p.get("script") or {}).get("ref")
-            if not ref:
-                errors.append(f"{loc}: execute_script needs parameters.script.ref")
-            elif ref not in scripts:
-                errors.append(f"{loc}: script ref '{ref}' not declared in top-level scripts:")
-            else:
-                variants = scripts.get(ref) or {}
-                found = False
-                for v in ("sh", "ps1"):
-                    path = variants.get(v)
-                    if path and (os.path.exists(path) or os.path.exists(os.path.join(base_dir, path))):
-                        found = True
-                if not found:
-                    warnings.append(f"{loc}: no script variant file found on disk for ref '{ref}'")
-            if not p.get("subcommand"):
-                errors.append(f"{loc}: execute_script needs parameters.subcommand")
-
-        if action == "user_select":
-            if not p.get("options_from_variable"):
-                errors.append(f"{loc}: user_select needs parameters.options_from_variable")
-
-        if action == "llm_generate":
-            if not p.get("prompt"):
-                warnings.append(f"{loc}: llm_generate has an empty prompt")
-            if not (p.get("output_target") or {}).get("path"):
-                errors.append(f"{loc}: llm_generate needs parameters.output_target.path")
-
-    used = _refs_in(wf) | _refs_in(skill.get("outputs", {}))
-    for name in sorted(used):
-        root = name.split(".")[0]
-        if root not in produced:
-            warnings.append(f"variable {{{{{name}}}}} referenced but never produced")
-
-    return errors, warnings
-
-
-def main(argv=None):
-    ap = argparse.ArgumentParser(description="aw-spec declarative skill interpreter")
-    ap.add_argument("skill")
-    ap.add_argument("--input", default="")
-    ap.add_argument("--select", action="append", default=[], help="stepid=value")
-    ap.add_argument("--answer", action="append", default=[], help="key=value (for ask steps)")
-    ap.add_argument("--llm", default="mock")
-    ap.add_argument("--os", choices=["posix", "windows"],
-                    default="windows" if os.name == "nt" else "posix")
-    ap.add_argument("--dry-run", action="store_true")
-    ap.add_argument("--non-interactive", action="store_true")
-    ap.add_argument("--validate", action="store_true",
-                    help="lint the skill (parse + static checks) without executing")
-    ap.add_argument("--checkpoint", metavar="STATEFILE",
-                    help="suspend/resume mode: persist state to STATEFILE and "
-                         "suspend when the agent is needed (see docs)")
-    ap.add_argument("--session", default=os.environ.get("AW_SPEC_SESSION"),
-                    help="agent session id (or $AW_SPEC_SESSION); enables cross-command "
-                         "context dedup via .aw-spec/.context-ledger.json")
-    ap.add_argument("--session-reset", action="store_true",
-                    help="clear the session context ledger and exit")
-    ap.add_argument("--json", action="store_true")
-    opts = ap.parse_args(argv)
-    opts.selects = dict(s.split("=", 1) for s in opts.select if "=" in s)
-    opts.answers = dict(s.split("=", 1) for s in opts.answer if "=" in s)
-
-    # ---- session context ledger --------------------------------------------
-    # Files loaded to context by an earlier command in the SAME agent session are
-    # already in the model's window; later commands skip re-loading / re-attaching
-    # them. Opt-in via --session / $AW_SPEC_SESSION (safe no-op when unset — e.g.
-    # stateless headless runs where each model call has no memory).
-    LEDGER = ".aw-spec/.context-ledger.json"
-    if opts.session_reset:
-        try:
-            os.remove(LEDGER)
-            msg = "context ledger reset"
-        except FileNotFoundError:
-            msg = "no context ledger to reset"
-        print(json.dumps({"status": "ok", "message": msg}) if opts.json else msg)
-        return 0
-    opts._ledger_path = None
-    opts._session_loaded = set()
-    if opts.session:
-        opts._ledger_path = LEDGER
-        if os.path.exists(LEDGER):
-            try:
-                led = json.load(open(LEDGER, encoding="utf-8"))
-                # only reuse the ledger when it belongs to THIS session id
-                if led.get("session") == opts.session:
-                    opts._session_loaded = set(led.get("loaded", []))
-            except Exception:
-                pass
-
-    # --validate: parse + static checks only, never execute.
-    if opts.validate:
-        try:
-            with open(opts.skill, encoding="utf-8") as fh:
-                skill = load_yaml(fh.read())
-        except (OSError, YamlError) as e:
-            print(json.dumps({"status": "invalid", "errors": [f"parse: {e}"]})
-                  if opts.json else f"ERROR: parse: {e}")
-            return 1
-        errors, warnings = validate_skill(skill, os.path.dirname(os.path.abspath(opts.skill)))
-        if opts.json:
-            print(json.dumps({"status": "valid" if not errors else "invalid",
-                              "errors": errors, "warnings": warnings}, indent=2))
-        else:
-            for w in warnings:
-                print("WARN: ", w)
-            for e in errors:
-                print("ERROR:", e)
-            print(f"\n{opts.skill}: {len(errors)} error(s), {len(warnings)} warning(s)")
-        return 1 if errors else 0
-
-    with open(opts.skill, encoding="utf-8") as fh:
-        skill = load_yaml(fh.read())
-
-    # ---- checkpoint mode: load prior state + ingest the agent's response ------
-    opts._cache = {}
-    if opts.checkpoint and os.path.exists(opts.checkpoint):
-        with open(opts.checkpoint, encoding="utf-8") as fh:
-            state = json.load(fh)
-        opts._cache = state.get("cache", {})
-        # merge stored inputs; CLI-provided --answer/--input override/extend them
-        if not opts.input:
-            opts.input = state.get("input", "")
-        merged = dict(state.get("answers", {}))
-        merged.update(opts.answers)
-        opts.answers = merged
-        # ingest the response the agent wrote for the pending request
-        pending = state.get("pending")
-        if pending:
-            rp = pending.get("response_path")
-            if rp and os.path.exists(rp):
-                raw = open(rp, encoding="utf-8").read()
-                kind = pending["kind"]
-                if kind == "llm_query":
-                    opts._cache[pending["step"]] = json.loads(
-                        raw.strip().splitlines()[-1] if raw.strip() else "{}")
-                elif kind == "llm_generate":
-                    opts._cache[pending["step"]] = raw
-                elif kind == "ask":
-                    val = raw.strip()
-                    opts._cache[pending["step"]] = (
-                        [s.strip() for s in val.split(",") if s.strip()] if pending.get("multi") else val)
-                os.remove(rp)
-            else:
-                # no response yet — re-emit the same pending request
-                _print_result({"status": "suspended", "pending": pending}, opts)
-                return 2
-
-    interp = Interp(skill, opts)
-    # bind declared inputs
-    for _, spec in (skill.get("inputs") or {}).items():
-        if isinstance(spec, dict) and spec.get("bind"):
-            interp.vars[spec["bind"]] = opts.input
-
-    def _persist_ledger():
-        # Record this run's loaded files into the session ledger — ONLY at a terminal
-        # end (ok/stop), never on suspend (mid-run), so a checkpoint run's own resumes
-        # keep seeing the pre-run snapshot and reload their context consistently.
-        if not opts._ledger_path:
-            return
-        merged = sorted(set(opts._session_loaded) | set(interp.context))
-        try:
-            with open(opts._ledger_path, "w", encoding="utf-8") as fh:
-                json.dump({"session": opts.session, "loaded": merged,
-                           "updated_at": __import__("time").strftime("%Y-%m-%dT%H:%M:%S")}, fh)
-        except OSError:
-            pass
-
-    rc = 0
-    try:
-        interp.run()
-        result = {"status": "ok",
-                  "outputs": interp.resolve(skill.get("outputs", {})),
-                  "pending_generation": interp.pending,
-                  "vars": interp.vars}
-        if opts.checkpoint and os.path.exists(opts.checkpoint):
-            os.remove(opts.checkpoint)   # finished — clear state
-        _persist_ledger()
-    except Suspend as e:
-        # persist state and emit the request for the agent to fulfill (NOT the ledger)
-        with open(opts.checkpoint, "w", encoding="utf-8") as fh:
-            json.dump({"input": opts.input, "answers": opts.answers,
-                       "cache": interp.cache, "pending": e.request}, fh, indent=2)
-        _print_result({"status": "suspended", "pending": e.request}, opts)
-        return 2
-    except Stop as e:
-        result = {"status": "stopped", "reason": str(e), "vars": interp.vars}
-        if opts.checkpoint and os.path.exists(opts.checkpoint):
-            os.remove(opts.checkpoint)
-        _persist_ledger()
-    except YamlError as e:
-        result = {"status": "error", "error": str(e), "vars": interp.vars}
-        rc = 1
-
-    _print_result(result, opts)
-    return rc
-
-
-def _print_result(result, opts):
-    if opts.json:
-        print(json.dumps(result, indent=2))
-        return
-    print(f"\n=== {result['status'].upper()} ===")
-    if result.get("pending"):
-        print("PENDING (agent action needed):")
-        print(json.dumps(result["pending"], indent=2))
-    if result.get("outputs"):
-        print(json.dumps(result["outputs"], indent=2))
-    if result.get("pending_generation"):
-        print("PENDING_GENERATION:", json.dumps(result["pending_generation"], indent=2))
-    if result.get("reason"):
-        print(result["reason"])
-    if result.get("error"):
-        print("ERROR:", result["error"])
-
-
-if __name__ == "__main__":
-    sys.exit(main())