leopold-driver 0.1.1 → 0.1.3

package/assets/extensions/serena/manage.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# serena extension — LSP-backed code intelligence (MCP) for Claude Code.
+#
+# Serena gives the agent IDE-grade, symbol-level tools (find_symbol,
+# find_referencing_symbols, replace_symbol_body, ...) instead of grep + whole-file
+# reads. That means sharper edits AND far fewer tokens — which is exactly the lever
+# Leopold needs to keep an autonomous run's context lean. Mandatory for quality.
+#
+# Setup is the OFFICIAL path (uv tool + `claude mcp add`), NOT the MCP marketplace —
+# the marketplace ships outdated commands (per the Serena maintainers).
+set -euo pipefail
+
+CLAUDE="${CLAUDE_HOME:-$HOME/.claude}"
+SETTINGS="$CLAUDE/settings.json"
+BIN="$HOME/.local/bin"
+PKG="serena-agent"                                   # PyPI package -> `serena` + `serena-hooks`
+MCP_ARGS="start-mcp-server --context=claude-code --project-from-cwd"
+
+say()  { printf '\033[36m->\033[0m %s\n' "$*"; }
+ok()   { printf '   \033[32mok\033[0m   %s\n' "$*"; }
+warn() { printf '   \033[33mwarn\033[0m %s\n' "$*"; }
+have() { command -v "$1" >/dev/null 2>&1; }
+sver() { serena --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1; }
+mcp_present()  { have claude && claude mcp get serena >/dev/null 2>&1; }
+hooks_wired()  { [ -f "$SETTINGS" ] && grep -q 'serena-hooks ' "$SETTINGS" 2>/dev/null; }
+
+wire_hooks() {
+  have jq || { warn "jq missing; skipping Serena hook wiring (recommended for tool adherence)"; return 0; }
+  [ -f "$SETTINGS" ] || echo '{}' > "$SETTINGS"
+  cp "$SETTINGS" "$SETTINGS.serena.bak"
+  local rm="serena-hooks remind --client=claude-code" ap="serena-hooks auto-approve --client=claude-code"
+  local ac="serena-hooks activate --client=claude-code" cl="serena-hooks cleanup --client=claude-code"
+  local tmp; tmp="$(mktemp)"
+  jq --arg rm "$rm" --arg ap "$ap" --arg ac "$ac" --arg cl "$cl" '
+    .hooks //= {} | .hooks.PreToolUse //= [] | .hooks.SessionStart //= [] | .hooks.SessionEnd //= []
+    | (if any(.hooks.PreToolUse[]?.hooks[]?;   .command==$rm) then . else .hooks.PreToolUse  += [{matcher:"",hooks:[{type:"command",command:$rm}]}] end)
+    | (if any(.hooks.PreToolUse[]?.hooks[]?;   .command==$ap) then . else .hooks.PreToolUse  += [{matcher:"mcp__serena__*",hooks:[{type:"command",command:$ap}]}] end)
+    | (if any(.hooks.SessionStart[]?.hooks[]?; .command==$ac) then . else .hooks.SessionStart += [{hooks:[{type:"command",command:$ac}]}] end)
+    | (if any(.hooks.SessionEnd[]?.hooks[]?;   .command==$cl) then . else .hooks.SessionEnd   += [{hooks:[{type:"command",command:$cl}]}] end)
+  ' "$SETTINGS" > "$tmp" && mv "$tmp" "$SETTINGS"
+  ok "Serena hooks wired: remind + auto-approve + activate + cleanup (backup at $SETTINGS.serena.bak)"
+}
+
+do_install() {
+  if ! have uv; then
+    say "installing uv (Serena's only prerequisite)"
+    curl -LsSf https://astral.sh/uv/install.sh | sh || { warn "uv install failed"; return 1; }
+    export PATH="$BIN:$PATH"
+  fi
+  if have serena && [ "${1:-install}" != update ]; then
+    ok "serena already installed ($(sver))"
+  else
+    say "installing Serena (LSP code intelligence)"
+    have serena || printf '   \033[2m(downloading serena-agent + deps — up to a minute on first install)\033[0m\n'
+    uv tool install -p 3.13 "$PKG" || uv tool install "$PKG" \
+      || { warn "uv tool install $PKG failed"; return 1; }
+    export PATH="$BIN:$PATH"
+  fi
+  have serena || { warn "serena not on PATH after install (add $BIN to PATH)"; return 1; }
+  ok "serena $(sver) ready"
+
+  # Global config is created automatically on first run; only init if it is missing.
+  if [ ! -f "$HOME/.serena/serena_config.yml" ]; then
+    serena init </dev/null >/dev/null 2>&1 || warn "serena init skipped (the MCP server creates the global config on first start)"
+  fi
+
+  # Register the MCP server (user scope = all projects). claude mcp add is NOT idempotent,
+  # so only add when it is not already present.
+  if have claude; then
+    if mcp_present; then ok "Serena MCP already registered (user scope)"
+    else
+      say "registering Serena MCP for Claude Code (user scope, all projects)"
+      if claude mcp add --scope user serena -- serena $MCP_ARGS >/dev/null 2>&1; then ok "MCP registered"
+      else warn "couldn't auto-register; run: claude mcp add --scope user serena -- serena $MCP_ARGS"; fi
+    fi
+  else
+    warn "the 'claude' CLI is not on PATH — register manually once it is:"
+    warn "  claude mcp add --scope user serena -- serena $MCP_ARGS"
+  fi
+
+  # Recommended hooks (counter Claude Code's bias toward its built-in tools).
+  hooks_wired && ok "Serena hooks already wired" || wire_hooks
+  echo
+  ok "Serena ready. Reconnect with /mcp (or restart Claude Code) to load its tools."
+}
+
+case "${1:-}" in
+  detect) have serena ;;
+  status)
+    if have serena; then
+      printf 'serena %s' "$(sver)"
+      mcp_present && printf ' · MCP connected' || printf ' · MCP not registered'
+      hooks_wired && printf ' · hooks on'; echo
+    else echo "not installed"; fi
+    ;;
+  install) do_install install ;;
+  update)  do_install update ;;
+  remove)
+    if mcp_present; then claude mcp remove serena -s user >/dev/null 2>&1 && echo "unregistered Serena MCP"; fi
+    if [ -f "$SETTINGS" ] && have jq; then
+      cp "$SETTINGS" "$SETTINGS.serena.bak"
+      tmp="$(mktemp)"
+      jq 'if .hooks then .hooks |= ( to_entries
+            | map(.value |= ( map(.hooks |= map(select((.command // "") | test("serena-hooks ") | not)))
+                              | map(select((.hooks | length) > 0)) ))
+            | from_entries ) else . end' "$SETTINGS" > "$tmp" && mv "$tmp" "$SETTINGS"
+      echo "unwired Serena hooks (backup at $SETTINGS.serena.bak)"
+    fi
+    echo "left installed: the serena CLI. To remove it too: uv tool uninstall $PKG"
+    ;;
+  doctor)
+    echo "serena:   $(have serena && serena --version 2>/dev/null | head -1 || echo missing)"
+    echo "MCP:      $(mcp_present && echo "registered (user scope)" || echo "not registered")"
+    _hc="$(grep -c 'serena-hooks ' "$SETTINGS" 2>/dev/null || true)"; echo "hooks:    ${_hc:-0}/4 Serena hooks in settings.json"
+    echo "uv:       $(have uv && echo present || echo missing)"
+    have claude || echo "note:     'claude' CLI not found — MCP registration must be done manually"
+    ;;
+  *) echo "usage: manage.sh {detect|status|install|update|remove|doctor}" >&2; exit 2 ;;
+esac

package/assets/hooks/guard-irreversible.sh

@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+# Leopold PreToolUse guard: keeps irreversible / outbound actions locked while a
+# Leopold autonomous run is active. This is defense-in-depth on top of Claude
+# Code's own permission system. It never loosens anything; it only adds denials.
+#
+# Hook contract (Claude Code PreToolUse): read JSON on stdin. To block, print a
+# hookSpecificOutput object with permissionDecision "deny" and exit 0. To allow,
+# exit 0 with no output. Detection is intentionally over-broad: when in doubt it
+# blocks, because a blocked-but-safe op just means the human runs it.
+#
+# Each denial below has a matching case in scripts/test-guard.sh (red-team suite).
+
+input="$(cat 2>/dev/null || true)"
+command -v jq >/dev/null 2>&1 || exit 0   # cannot parse safely -> defer to CC perms
+
+cwd="$(printf '%s' "$input" | jq -r '.cwd // empty' 2>/dev/null || true)"
+[ -z "${cwd:-}" ] && cwd="$PWD"
+LEO="$cwd/.leopold"
+STATE="$LEO/state.json"
+
+# Only guard during an active autonomous run.
+[ -f "$STATE" ] || exit 0
+# Fail CLOSED on a malformed state.json: if the file exists but does not parse,
+# we cannot prove the run is inactive, so we keep guarding (and say so).
+if ! jq -e . "$STATE" >/dev/null 2>&1; then
+  active="true"
+else
+  active="$(jq -r '.active // false' "$STATE" 2>/dev/null || echo true)"
+fi
+[ "$active" = "true" ] || exit 0
+
+tool="$(printf '%s' "$input" | jq -r '.tool_name // empty' 2>/dev/null || true)"
+
+deny() {
+  local r="$1" ts
+  jq -cn --arg r "$r" '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:$r}}'
+  ts="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo '')"
+  printf '{"ts":"%s","event":"guard_block","tool":"%s"}\n' "$ts" "$tool" >> "$LEO/events.jsonl" 2>/dev/null || true
+  exit 0
+}
+
+has_token() { [ -f "$LEO/$1" ]; }
+matches()   { printf '%s' "$1" | grep -qiE -- "$2"; }   # $1 text, $2 ERE (case-insensitive)
+
+# Resolve the git subcommand, skipping leading global options AND their values
+# (-c k=v, -C path, --git-dir, --work-tree, --namespace, --exec-path, --config-env).
+# This is what closes the `git -c user.name=x commit` / `git -C /r commit` bypass.
+git_subcmd() {  # $1 = normalized command -> echoes the subcommand (or empty)
+  local toks=() i n t want=0
+  read -ra toks <<< "$1"
+  n=${#toks[@]}; i=0
+  # match 'git', '/usr/bin/git', './git', 'env git' ... by basename
+  while [ "$i" -lt "$n" ] && [ "${toks[$i]##*/}" != "git" ]; do i=$((i+1)); done
+  i=$((i+1))
+  while [ "$i" -lt "$n" ]; do
+    t="${toks[$i]}"
+    if [ "$want" -eq 1 ]; then want=0; i=$((i+1)); continue; fi
+    case "$t" in
+      -c|-C|--git-dir|--work-tree|--namespace|--exec-path|--config-env) want=1 ;;
+      --*=*|-*) : ;;          # self-contained option, skip
+      *) printf '%s' "$t"; return ;;
+    esac
+    i=$((i+1))
+  done
+}
+
+case "$tool" in
+  Task|Agent)
+    # Subagent fan-out is the #1 autonomous-run cost blowup, on TWO axes — how MANY are
+    # spawned, and how much CONTEXT each one carries. Guard both.
+    stype="$(printf '%s' "$input" | jq -r '.tool_input.subagent_type // empty' 2>/dev/null || true)"
+
+    # (a) Context per subagent: an oversized prompt means context is being dumped into the
+    # subagent (each is billed in full). A normal scoped prompt is a few KB; deny the absurd.
+    plen="$(printf '%s' "$input" | jq -r '.tool_input.prompt // .tool_input.description // empty' 2>/dev/null | wc -c | tr -d ' ')"
+    if [ "${plen:-0}" -gt 262144 ] 2>/dev/null; then
+      deny "Leopold guard: this subagent prompt is ~$(( ${plen:-0} / 1024 ))KB — you're handing the subagent a huge context (each spawn is billed in full). Pass a minimal, scoped prompt: point it at files to read, don't paste them in."
+    fi
+
+    # (b) Forks clone the ENTIRE parent session (multi-MB) — they ARE the per-subagent
+    # context leak. Forbidden by default (max_forks 0); a fresh scoped subagent does the
+    # same work with a clean slate. Raise max_forks in GUARDRAILS.md only for a sub-task
+    # that genuinely needs the full conversation.
+    if [ "$stype" = "fork" ]; then
+      max_fk="$(jq -r '.max_forks // 0' "$STATE" 2>/dev/null || echo 0)"; case "$max_fk" in (*[!0-9]*|"") max_fk=0 ;; esac
+      forked="$(jq -r '.forks_spawned // 0' "$STATE" 2>/dev/null || echo 0)"; case "$forked" in (*[!0-9]*|"") forked=0 ;; esac
+      if [ "$forked" -ge "$max_fk" ] 2>/dev/null; then
+        deny "Leopold guard: forks are forbidden in autonomous mode ($forked/$max_fk). A fork clones the WHOLE session context (multi-MB) into the spawn — this is the leak that runs up the bill. Use a regular subagent with a minimal prompt instead (it starts clean). To allow a fork, raise max_forks in GUARDRAILS.md."
+      fi
+      gtmp="$(mktemp 2>/dev/null || echo "$STATE.gtmp")"
+      jq --argjson f "$((forked+1))" '.forks_spawned=$f' "$STATE" > "$gtmp" 2>/dev/null && mv "$gtmp" "$STATE" || rm -f "$gtmp" 2>/dev/null
+    fi
+
+    # (c) Total subagent budget (forks count here too). Past it, deny so the run continues
+    # serially instead of exploding. Counters live in state.json (best-effort).
+    max_sub="$(jq -r '.max_subagents // 8' "$STATE" 2>/dev/null || echo 8)"; case "$max_sub" in (*[!0-9]*|"") max_sub=8 ;; esac
+    spawned="$(jq -r '.subagents_spawned // 0' "$STATE" 2>/dev/null || echo 0)"; case "$spawned" in (*[!0-9]*|"") spawned=0 ;; esac
+    if [ "$spawned" -ge "$max_sub" ] 2>/dev/null; then
+      deny "Leopold guard: subagent budget exhausted ($spawned/$max_sub this run). Spawning many subagents multiplies cost — each re-loads context. Do this task yourself in-turn (work serially). Raise max_subagents in GUARDRAILS.md and restart if you truly must."
+    fi
+    gtmp="$(mktemp 2>/dev/null || echo "$STATE.gtmp")"
+    jq --argjson s "$((spawned+1))" '.subagents_spawned=$s' "$STATE" > "$gtmp" 2>/dev/null && mv "$gtmp" "$STATE" || rm -f "$gtmp" 2>/dev/null
+    # Audit trail: one line per spawn (size + fork flag) so a run's cost is inspectable.
+    sts="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo '')"
+    printf '{"ts":"%s","event":"subagent_spawn","fork":%s,"prompt_kb":%s,"total":%s}\n' \
+      "$sts" "$([ "$stype" = fork ] && echo true || echo false)" "$(( ${plen:-0} / 1024 ))" "$((spawned+1))" \
+      >> "$LEO/events.jsonl" 2>/dev/null || true
+    ;;
+
+  Bash)
+    cmd="$(printf '%s' "$input" | jq -r '.tool_input.command // empty' 2>/dev/null || true)"
+    # normalize: newlines/tabs -> space, collapse runs (defeats whitespace/tab evasion).
+    norm="$(printf '%s' "$cmd" | tr '\n\t' '  ' | tr -s ' ')"
+
+    # Opt-in deny-by-default (LEOPOLD_PARANOID=1): only a small allowlist of
+    # read/build/test/lint commands passes; everything else is denied. Best-effort
+    # (it keys off the first command word), kept off by default in favor of the
+    # hardened denylist below. Documented in docs/guardrails.md.
+    if [ "${LEOPOLD_PARANOID:-0}" = "1" ]; then
+      first="$(printf '%s' "$norm" | awk '{print $1}')"; base="${first##*/}"; ok=0
+      case "$base" in
+        ls|cat|head|tail|wc|grep|rg|awk|sed|find|file|stat|tree|pwd|cd|echo|printf|true|jq|make|node|npx|tsc|mkdir|cp|touch|test|diff|cmp) ok=1 ;;
+        git) case "$(git_subcmd "$norm")" in add|status|diff|log|show|rev-parse|branch|fetch|remote|config) ok=1 ;; esac ;;
+        npm|pnpm|yarn) matches "$norm" '[[:space:]](run|test|ci|pack|install|build|typecheck|lint)([[:space:]]|$)' && ok=1 ;;
+      esac
+      [ "$ok" = 1 ] || deny "Leopold PARANOID: '$base' is not on the allowlist (read/build/test/lint/git add). Unset LEOPOLD_PARANOID to use the default denylist."
+    fi
+
+    # --- destructive deletes (rm recursive+force, in any spelling) ----------
+    if matches "$norm" '(^|[^[:alnum:]_-])rm([[:space:]]|$)'; then
+      rec=0; force=0
+      matches "$norm" '(--recursive|(^|[[:space:]])-[a-z]*r)' && rec=1
+      matches "$norm" '(--force|(^|[[:space:]])-[a-z]*f)'     && force=1
+      [ "$rec" = 1 ] && [ "$force" = 1 ] && \
+        deny "Leopold guard: recursive+forced rm is forbidden in autonomous mode (any spelling). Stop and let the human run it."
+    fi
+    # find-based deletion
+    if matches "$norm" '(^|[^[:alnum:]_-])find([[:space:]]|$)'; then
+      matches "$norm" '[[:space:]]-delete([[:space:]]|$)' && \
+        deny "Leopold guard: 'find ... -delete' is forbidden in autonomous mode."
+      matches "$norm" '-exec[[:space:]]+rm([[:space:]]|$)' && \
+        deny "Leopold guard: 'find ... -exec rm' is forbidden in autonomous mode."
+    fi
+
+    # --- git, by resolved subcommand (bypass-resistant) ---------------------
+    gsub="$(git_subcmd "$norm")"
+    case "$gsub" in
+      reset)  matches "$norm" '(^|[[:space:]])--hard([[:space:]]|$)' && \
+                deny "Leopold guard: 'git reset --hard' is forbidden in autonomous mode." ;;
+      clean)  matches "$norm" '(--force|(^|[[:space:]])-[a-z]*f)' && \
+                deny "Leopold guard: 'git clean -f' is forbidden in autonomous mode." ;;
+      branch) matches "$norm" '(^|[[:space:]])-D([[:space:]]|$)' && \
+                deny "Leopold guard: 'git branch -D' is forbidden in autonomous mode." ;;
+      push)
+        matches "$norm" '(--force|--force-with-lease|(^|[[:space:]])-f([[:space:]]|$))' && \
+          deny "Leopold guard: force-push is forbidden in autonomous mode."
+        has_token ALLOW_PUSH || \
+          deny "Leopold guard: git push is locked. Pushing is the user's call; report readiness instead." ;;
+      commit)
+        has_token ALLOW_GIT || \
+          deny "Leopold guard: git commit is locked. Stage the work (git add) and report instead. To allow this session: touch .leopold/ALLOW_GIT" ;;
+    esac
+
+    # --- outbound: PRs / releases / publishing ------------------------------
+    if matches "$norm" '(^|[^[:alnum:]_-])gh([[:space:]].*)?(pr[[:space:]]+(create|merge)|release[[:space:]]+create)'; then
+      has_token ALLOW_PUSH || \
+        deny "Leopold guard: opening/merging PRs and creating releases is locked. Report readiness instead."
+    fi
+    if matches "$norm" '(npm|pnpm|yarn)[[:space:]]+publish|cargo[[:space:]]+publish|twine[[:space:]]+upload|pip[[:space:]].*upload'; then
+      has_token ALLOW_PUBLISH || \
+        deny "Leopold guard: publishing packages is locked in autonomous mode."
+    fi
+    ;;
+
+  Edit|Write|MultiEdit|NotebookEdit)
+    path="$(printf '%s' "$input" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null || true)"
+    case "$path" in
+      */GUARDRAILS.md)             deny "Leopold guard: GUARDRAILS.md is immutable during an autonomous run." ;;
+      */settings.json|*/settings.local.json) deny "Leopold guard: editing Claude Code settings is forbidden in autonomous mode." ;;
+      */leopold/hooks/*|*/.leopold/state.json) deny "Leopold guard: the guardrail hooks and run state are immutable during an autonomous run." ;;
+    esac
+    ;;
+esac
+
+exit 0

package/assets/hooks/hooks.json

@@ -0,0 +1,20 @@
+{
+  "description": "Leopold hooks: Stop-hook continuity and the PreToolUse git-lock guard. Both are no-ops unless a Leopold run is active in the project.",
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/stop-continuity.sh\"" }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/guard-irreversible.sh\"" }
+        ]
+      }
+    ]
+  }
+}

package/assets/hooks/stop-continuity.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Leopold Stop hook: state-coupled autonomous continuity.
+#
+# When the main agent finishes a turn, this hook reads .leopold/state.json and
+# PLAN.md in the project. If a Leopold run is active and work remains with no
+# stop condition met, it blocks the stop and re-injects a compact "continue"
+# instruction. Otherwise it allows the session to halt.
+#
+# Hook contract (Claude Code Stop): read JSON on stdin. To keep going, print
+# {"decision":"block","reason":"..."} and exit 0. To allow stopping, exit 0 with
+# no output. Failure mode is intentionally fail-open (allow stop): a broken hook
+# must never trap a session in a loop.
+
+input="$(cat 2>/dev/null || true)"
+
+# jq is required to parse state safely; without it, allow the stop.
+command -v jq >/dev/null 2>&1 || exit 0
+
+cwd="$(printf '%s' "$input" | jq -r '.cwd // empty' 2>/dev/null || true)"
+[ -z "${cwd:-}" ] && cwd="$PWD"
+LEO="$cwd/.leopold"
+STATE="$LEO/state.json"
+
+# Not a Leopold run -> normal stop.
+[ -f "$STATE" ] || exit 0
+
+now="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo '')"
+
+# Fail SAFE and LOUD on a broken state file. Malformed JSON, or a missing/non-numeric
+# budget field, means the iteration budget cannot be trusted -- the run could loop
+# forever on a silently-skipped budget. Stop the run and say why, rather than continue
+# blindly or die in silence.
+state_invalid() {
+  printf '{"ts":"%s","event":"state_invalid","reason":"%s"}\n' "$now" "$1" >> "$LEO/events.jsonl" 2>/dev/null || true
+  echo "Leopold: .leopold/state.json is invalid ($1) -- stopping the run (fail-safe). Fix the file or re-run /leopold-brief." >&2
+  printf '{"active":false,"stopped_reason":"state_invalid"}\n' > "$STATE" 2>/dev/null || true
+  exit 0
+}
+jq -e . "$STATE" >/dev/null 2>&1 || state_invalid "malformed JSON"
+
+active="$(jq -r '.active // false' "$STATE" 2>/dev/null || echo false)"
+[ "$active" = "true" ] || exit 0
+
+# A present-but-non-numeric budget field is the real hole: it would make the
+# `iter >= max` test below error out (and get swallowed), silently skipping the
+# budget -> unbounded loop. So any present budget field must be an integer. Missing
+# fields fall back to the safe defaults below (50 / 0 / 3), so the budget still holds.
+for f in iteration max_iterations consecutive_failures max_failures; do
+  v="$(jq -r --arg k "$f" '.[$k] // empty' "$STATE" 2>/dev/null)"
+  if [ -n "$v" ] && ! printf '%s' "$v" | grep -qE '^[0-9]+$'; then
+    state_invalid "non-numeric $f ($v)"
+  fi
+done
+
+log_event() { printf '%s\n' "$1" >> "$LEO/events.jsonl" 2>/dev/null || true; }
+
+allow_stop() {
+  local r="$1" tmp
+  tmp="$(mktemp 2>/dev/null || echo "$STATE.tmp")"
+  jq --arg r "$r" '.active=false | .stopped_reason=$r' "$STATE" > "$tmp" 2>/dev/null && mv "$tmp" "$STATE" || true
+  log_event "{\"ts\":\"$now\",\"event\":\"stop\",\"reason\":\"$r\"}"
+  # Safety hygiene: always clear the kill switch and per-session git opt-in tokens
+  # so the next run re-locks git and does not halt immediately on a stale STOP.
+  rm -f "$LEO/STOP" "$LEO/ALLOW_GIT" "$LEO/ALLOW_PUSH" "$LEO/ALLOW_PUBLISH" 2>/dev/null || true
+  # on_finish policy (GUARDRAILS.md): archive the run logs on a clean finish.
+  if [ "$r" = "plan_complete" ] && grep -qiE '^[[:space:]]*-?[[:space:]]*on_finish:[[:space:]]*archive' "$LEO/GUARDRAILS.md" 2>/dev/null; then
+    arch="$LEO/runs/$(date -u +%Y%m%dT%H%M%SZ)"
+    mkdir -p "$arch" 2>/dev/null || true
+    [ -f "$LEO/DECISIONS.md" ] && mv "$LEO/DECISIONS.md" "$arch/" 2>/dev/null || true
+    [ -f "$LEO/events.jsonl" ] && mv "$LEO/events.jsonl" "$arch/" 2>/dev/null || true
+    cp "$LEO/PLAN.md" "$arch/" 2>/dev/null || true
+  fi
+  exit 0
+}
+
+# Kill switch.
+if [ -f "$LEO/STOP" ]; then allow_stop "kill_switch"; fi
+
+iter="$(jq -r '.iteration // 0' "$STATE" 2>/dev/null || echo 0)"
+max_iter="$(jq -r '.max_iterations // 50' "$STATE" 2>/dev/null || echo 50)"
+fails="$(jq -r '.consecutive_failures // 0' "$STATE" 2>/dev/null || echo 0)"
+max_fails="$(jq -r '.max_failures // 3' "$STATE" 2>/dev/null || echo 3)"
+
+# Budgets and repeated failure.
+if [ "$iter" -ge "$max_iter" ] 2>/dev/null; then allow_stop "iteration_budget"; fi
+if [ "$fails" -ge "$max_fails" ] 2>/dev/null; then allow_stop "repeated_failure"; fi
+
+# Context budget — the real money pit. A long run accumulates context every turn; on a
+# big-context model it never auto-compacts, so each turn re-bills the whole (growing)
+# transcript and any fork clones it (one report: a session ballooned to ~6MB over 681
+# turns). Stop when the transcript passes max_context_mb (default 5) so it cannot silently
+# balloon. The brief persists -> a fresh /leopold-run resumes from PLAN.md with clean context.
+max_ctx_mb="$(jq -r '.max_context_mb // 5' "$STATE" 2>/dev/null || echo 5)"
+case "$max_ctx_mb" in (*[!0-9]*|"") max_ctx_mb=5 ;; esac
+ctx_mb=0
+tpath="$(printf '%s' "$input" | jq -r '.transcript_path // empty' 2>/dev/null || true)"
+if [ -n "$tpath" ] && [ -f "$tpath" ]; then
+  ctx_bytes="$(wc -c < "$tpath" 2>/dev/null || echo 0)"
+  ctx_mb="$(awk "BEGIN{printf \"%.1f\", ${ctx_bytes:-0}/1048576}" 2>/dev/null || echo 0)"
+  [ "$(( ${ctx_bytes:-0} / 1048576 ))" -ge "$max_ctx_mb" ] 2>/dev/null && allow_stop "context_budget"
+fi
+
+# Plan complete? (no unchecked checkboxes remain)
+PLAN="$LEO/PLAN.md"
+open_items="$(grep -cE '^[[:space:]]*- \[ \]' "$PLAN" 2>/dev/null || true)"
+open_items="${open_items:-0}"
+if [ "$open_items" -eq 0 ] 2>/dev/null; then allow_stop "plan_complete"; fi
+
+# Loop detection: if the SET of open plan items is byte-identical for N consecutive
+# turns, the run is thrashing without progress (no item checked off, no item added) ->
+# stop and report rather than burn the whole iteration budget hammering one spot.
+max_np="$(jq -r '.max_no_progress // 6' "$STATE" 2>/dev/null || echo 6)"
+case "$max_np" in (*[!0-9]*|"") max_np=6 ;; esac
+sig="$(grep -E '^[[:space:]]*- \[ \]' "$PLAN" 2>/dev/null | cksum | awk '{print $1}')"
+last_sig="$(jq -r '.progress_sig // empty' "$STATE" 2>/dev/null || true)"
+np="$(jq -r '.no_progress // 0' "$STATE" 2>/dev/null || echo 0)"
+case "$np" in (*[!0-9]*|"") np=0 ;; esac
+if [ "$sig" = "$last_sig" ] && [ -n "$last_sig" ]; then np=$((np + 1)); else np=0; fi
+if [ "$np" -ge "$max_np" ] 2>/dev/null; then allow_stop "no_progress"; fi
+
+# Otherwise: continue. Increment the iteration counter; persist the progress signature.
+next=$((iter + 1))
+tmp="$(mktemp 2>/dev/null || echo "$STATE.tmp")"
+jq --argjson n "$next" --arg t "$now" --argjson np "$np" --arg sig "$sig" --argjson cm "${ctx_mb:-0}" --arg tp "${tpath:-}" \
+   '.iteration=$n | .last_turn=$t | .no_progress=$np | .progress_sig=$sig | .context_mb=$cm
+    | (if $tp != "" then .transcript_path=$tp else . end)' "$STATE" > "$tmp" 2>/dev/null && mv "$tmp" "$STATE" || true
+log_event "{\"ts\":\"$now\",\"event\":\"turn_start\",\"iteration\":$next,\"open_items\":$open_items,\"no_progress\":$np}"
+
+reason="Leopold autonomous mode is ACTIVE (turn $next/$max_iter, $open_items open plan items). Do not stop. Steps: (1) Read .leopold/PLAN.md and pick the next unchecked item. (2) Complete it; reach for the gstack playbook skill that fits the situation. (3) On any fork, apply .leopold/CHARTER.md and the decision protocol: if the call is reversible OR the charter is clear, decide it yourself, append the decision to .leopold/DECISIONS.md, and keep going; stop only for an irreversible AND ambiguous fork, a charter contradiction, or a mission-premise change. (4) Mark the finished item as done ([x]) in PLAN.md. Hard rules: git commit/push/publish stay locked; never edit files outside this project; never touch .leopold/GUARDRAILS.md or the hooks. When the plan is complete or a stop condition is met, write a short final summary and then stop."
+
+jq -cn --arg r "$reason" '{decision:"block", reason:$r}'
+exit 0

package/assets/install.sh

@@ -0,0 +1,184 @@
+#!/usr/bin/env bash
+# Leopold installer.
+# Copies the skills into ~/.claude/skills/, the hooks/templates/docs into
+# ~/.claude/leopold/, and wires the Stop + PreToolUse hooks into
+# ~/.claude/settings.json (idempotent, with a backup). The hooks are no-ops
+# unless a Leopold run is active, so they are safe to leave installed.
+set -euo pipefail
+
+# Resolve the source tree. When run from a clone, that is the script's dir.
+# When piped (curl ... | bash), there is no local tree, so we fetch one first.
+_self="${BASH_SOURCE[0]:-}"
+if [ -n "$_self" ] && [ -d "$(dirname "$_self")/skills" ]; then
+  SRC="$(cd "$(dirname "$_self")" && pwd)"
+else
+  SRC="${LEOPOLD_SRC:-$HOME/.local/share/leopold}"
+  echo "-> fetching Leopold into $SRC"
+  if [ -d "$SRC/.git" ]; then
+    ( cd "$SRC" && git pull --ff-only -q ) || true
+  else
+    mkdir -p "$(dirname "$SRC")"
+    git clone --progress --depth 1 https://github.com/Jonhvmp/leopold.git "$SRC"
+  fi
+fi
+CLAUDE="${CLAUDE_HOME:-$HOME/.claude}"
+SKILLS="$CLAUDE/skills"
+LEO_HOME="$CLAUDE/leopold"
+SETTINGS="$CLAUDE/settings.json"
+
+# Optional gstack integration: pass --with-gstack to install it non-interactively.
+WITH_GSTACK=0
+for _a in "$@"; do [ "$_a" = "--with-gstack" ] && WITH_GSTACK=1; done
+
+echo "Leopold installer"
+echo "  source:   $SRC"
+echo "  target:   $CLAUDE"
+echo
+
+mkdir -p "$SKILLS" "$LEO_HOME"
+
+echo "-> installing skills"
+for d in "$SRC"/skills/*/; do
+  name="$(basename "$d")"
+  rm -rf "${SKILLS:?}/$name"
+  cp -R "$d" "$SKILLS/$name"
+  echo "   $name"
+done
+
+echo "-> installing hooks, templates, docs, extensions"
+cp -R "$SRC/hooks"      "$LEO_HOME/"
+cp -R "$SRC/templates"  "$LEO_HOME/"
+cp -R "$SRC/docs"       "$LEO_HOME/" 2>/dev/null || true
+cp -R "$SRC/scripts"    "$LEO_HOME/" 2>/dev/null || true
+cp -R "$SRC/extensions" "$LEO_HOME/" 2>/dev/null || true
+cp    "$SRC/VERSION"    "$LEO_HOME/" 2>/dev/null || true
+chmod +x "$LEO_HOME"/hooks/*.sh
+chmod +x "$LEO_HOME"/scripts/*.sh 2>/dev/null || true
+chmod +x "$LEO_HOME"/extensions/*/manage.sh 2>/dev/null || true
+
+STOP_HOOK="$LEO_HOME/hooks/stop-continuity.sh"
+GUARD_HOOK="$LEO_HOME/hooks/guard-irreversible.sh"
+
+echo "-> wiring hooks into $SETTINGS"
+if ! command -v jq >/dev/null 2>&1; then
+  echo
+  echo "   jq not found. Add this to $SETTINGS manually:"
+  sed "s#~/.claude/leopold#$LEO_HOME#g" "$SRC/settings.template.json"
+  echo
+else
+  [ -f "$SETTINGS" ] || echo '{}' > "$SETTINGS"
+  cp "$SETTINGS" "$SETTINGS.leopold.bak"
+  tmp="$(mktemp)"
+  jq --arg stop "$STOP_HOOK" --arg guard "$GUARD_HOOK" '
+    .hooks //= {}
+    | .hooks.Stop //= []
+    | .hooks.PreToolUse //= []
+    | (if any(.hooks.Stop[]?.hooks[]?; .command == $stop)
+        then . else .hooks.Stop += [{hooks:[{type:"command",command:$stop}]}] end)
+    | (if any(.hooks.PreToolUse[]?.hooks[]?; .command == $guard)
+        then . else .hooks.PreToolUse += [{matcher:"Bash|Edit|Write|MultiEdit|NotebookEdit",hooks:[{type:"command",command:$guard}]}] end)
+  ' "$SETTINGS" > "$tmp" && mv "$tmp" "$SETTINGS"
+  echo "   merged (backup at $SETTINGS.leopold.bak)"
+fi
+
+# Serena — MANDATORY. LSP-backed code intelligence (MCP): symbol-level retrieval/editing
+# instead of grep + whole-file reads. It is the biggest lever for code quality AND for
+# keeping context lean (fewer tokens per operation), so Leopold sets it up for everyone.
+echo
+echo "-> setting up Serena (LSP code intelligence — mandatory for quality + lean context)"
+SERENA_MGR="$LEO_HOME/extensions/serena/manage.sh"
+if [ -f "$SERENA_MGR" ]; then
+  bash "$SERENA_MGR" install || echo "   Serena setup did not finish; complete it with: make serena-install  (or: make menu)"
+else
+  echo "   (serena extension missing from this build; skipping)"
+fi
+
+# The `leopold` CLI — so `leopold menu / watch / doctor / serena` work from anywhere,
+# no repo and no `make`. Skip if it's already here (e.g. you ran `leopold install`).
+echo
+if command -v leopold >/dev/null 2>&1; then
+  echo "-> leopold CLI already installed"
+elif command -v npm >/dev/null 2>&1; then
+  echo "-> installing the leopold CLI (npm i -g leopold-driver)"
+  if npm i -g leopold-driver >/dev/null 2>&1; then
+    if command -v leopold >/dev/null 2>&1; then
+      echo "   ok   'leopold' command ready (leopold menu · watch · doctor)"
+    else
+      echo "   installed, but 'leopold' isn't on PATH yet — open a new shell (or: hash -r)"
+    fi
+  else
+    echo "   warn: 'npm i -g leopold-driver' failed (permissions?) — run it yourself, maybe with sudo"
+  fi
+else
+  echo "-> npm not found — the 'leopold' CLI needs Node/npm. Then: npm i -g leopold-driver"
+fi
+
+echo
+GSTACK_DIR="$SKILLS/gstack"
+gstack_present() { [ -d "$GSTACK_DIR" ] || ls "$SKILLS" 2>/dev/null | grep -q '^spec$'; }
+install_gstack() {
+  echo "-> installing gstack (MIT, by Garry Tan: https://github.com/garrytan/gstack)"
+  command -v bun >/dev/null 2>&1 || echo "   note: gstack needs Bun v1.0+ (https://bun.sh); its setup will guide you."
+  echo "   cloning gstack (shows progress) + running its setup…"
+  if git clone --progress --single-branch --depth 1 https://github.com/garrytan/gstack.git "$GSTACK_DIR" && ( cd "$GSTACK_DIR" && ./setup ); then
+    echo "   gstack installed."
+  else
+    echo "   gstack install did not finish; retry with: make gstack-install"
+  fi
+}
+
+if gstack_present; then
+  echo "gstack detected: Leopold will conduct its planning toolchain (/spec, /autoplan, /plan-*-review, ...)."
+elif [ "$WITH_GSTACK" = "1" ]; then
+  install_gstack
+else
+  echo "gstack not detected. Leopold works on plain Claude Code, but it shines when it can conduct"
+  echo "gstack's planning toolchain (/autoplan, /plan-eng-review, /spec). gstack is a separate MIT"
+  echo "project by Garry Tan: https://github.com/garrytan/gstack"
+  if [ -t 0 ]; then
+    printf "Install gstack now? (clones to %s, runs its setup, needs Bun) [y/N] " "$GSTACK_DIR"
+    read -r _ans || _ans=""
+    case "$_ans" in [yY]*) install_gstack ;; *) echo "Skipped. Install later: make gstack-install" ;; esac
+  else
+    echo "Enable it later with: make gstack-install   (or re-run ./install.sh --with-gstack)"
+  fi
+fi
+
+# Verify the install: skills, hooks, and the leopold CLI should all be in place.
+echo
+echo "-> verifying"
+v_warn=0
+sc="$(ls "$SKILLS" 2>/dev/null | grep -c '^leopold-' || true)"
+[ "${sc:-0}" -ge 4 ] 2>/dev/null && echo "   ok   $sc leopold skills installed" || { echo "   warn: leopold skills not found in $SKILLS"; v_warn=$((v_warn+1)); }
+if command -v jq >/dev/null 2>&1 && [ -f "$SETTINGS" ] && jq -e '(.hooks.Stop|length>0) and (.hooks.PreToolUse|length>0)' "$SETTINGS" >/dev/null 2>&1; then
+  echo "   ok   Stop + PreToolUse hooks wired in settings.json"
+else echo "   warn: hooks not detected in settings.json"; v_warn=$((v_warn+1)); fi
+command -v leopold  >/dev/null 2>&1 && echo "   ok   leopold CLI on PATH" || { echo "   warn: 'leopold' not on PATH yet (open a new shell, or: npm i -g leopold-driver)"; v_warn=$((v_warn+1)); }
+command -v serena   >/dev/null 2>&1 && echo "   ok   serena (LSP) present" || echo "   note: serena not on PATH — run: leopold serena install"
+[ "$v_warn" -eq 0 ] && echo "   all good." || echo "   $v_warn warning(s) above — see the hints."
+
+echo
+echo "Done. In any project:"
+echo "  /leopold-brief    debate the mission, write the brief"
+echo "  /leopold-run      hand over the seat"
+echo "  /leopold-status   see where it is"
+echo "  /leopold-stop     take the seat back"
+echo "  (or from a shell: leopold menu · leopold watch · leopold doctor)"
+echo
+# Offer the toolchain manager. We read from /dev/tty (the controlling terminal),
+# not stdin, so this works even when the installer is piped: `curl ... | bash`
+# leaves stdin as the script, but the terminal is still reachable via /dev/tty.
+MENU="$LEO_HOME/scripts/leopold-menu.sh"
+if exec 3<>/dev/tty 2>/dev/null; then
+  printf "Open the toolchain manager (install/manage gstack, ovmem, ...)? [Y/n] " >&3
+  read -r _ans <&3 || _ans="y"
+  case "$_ans" in
+    [nN]*) echo "Skipped. Open it anytime:  bash $MENU   (or: make menu)" ;;
+    *)     bash "$MENU" <&3 || true ;;
+  esac
+  exec 3>&-
+else
+  # no terminal (headless / CI): just point at it
+  echo "Manage the toolchain (gstack, ovmem, ...):"
+  echo "  bash $MENU    (or: make menu)"
+fi