leopold-driver 0.1.1 → 0.1.2

package/assets/scripts/test-guard.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# Red-team suite for the Leopold PreToolUse guard (hooks/guard-irreversible.sh).
+# Every bypass attempt is a test: feed a crafted tool call, assert deny / allow.
+# Run: make test-guard   (or: bash scripts/test-guard.sh)
+set -u
+
+GUARD="$(cd "$(dirname "$0")/.." && pwd)/hooks/guard-irreversible.sh"
+command -v jq >/dev/null 2>&1 || { echo "jq required"; exit 1; }
+
+TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
+mkdir -p "$TMP/.leopold" "$TMP/src"
+active() { echo "$1" > "$TMP/.leopold/state.json"; }
+active '{"active":true,"iteration":1}'
+
+pass=0; fail=0
+run_bash() { jq -cn --arg c "$1" --arg cwd "$TMP" '{tool_name:"Bash",cwd:$cwd,tool_input:{command:$c}}' | bash "$GUARD" 2>/dev/null; }
+run_edit() { jq -cn --arg p "$1" --arg cwd "$TMP" '{tool_name:"Edit",cwd:$cwd,tool_input:{file_path:$p}}' | bash "$GUARD" 2>/dev/null; }
+is_deny()  { printf '%s' "$1" | grep -q '"permissionDecision":"deny"'; }
+
+ck_deny()  { if is_deny "$2"; then pass=$((pass+1)); else fail=$((fail+1)); printf '  \033[31mFAIL\033[0m want DENY : %s\n' "$1"; fi; }
+ck_allow() { if [ -z "$2" ]; then pass=$((pass+1)); else fail=$((fail+1)); printf '  \033[31mFAIL\033[0m want ALLOW: %s\n' "$1"; fi; }
+
+echo "== must DENY (destructive / locked / bypass attempts) =="
+DENY=(
+  'rm -rf /x' 'rm -fr /x' 'rm -Rf /x' 'rm --recursive --force /x' 'rm -r -f /x'
+  '/bin/rm -rf /x' 'cd /tmp && rm -rf x'
+  'find . -delete' 'find . -type f -delete' 'find . -exec rm {} +'
+  'git commit -m x' 'git -c user.name=foo commit -m x' 'git -C /r commit -m x'
+  'git --git-dir=/x commit' 'git -c a=b -c c=d commit'
+  '/usr/bin/git commit -m x' 'env git commit -m x' 'git  -c  x=y   commit'
+  'git push' 'git push origin main' 'git push --force' 'git push -f origin main' 'git -c x=y push'
+  'git reset --hard' 'git -c x=y reset --hard HEAD~1' 'git clean -fd' 'git branch -D feat'
+  'gh pr create' 'gh pr merge 3' 'gh release create v1' 'npm publish' 'pnpm publish' 'cargo publish'
+)
+for c in "${DENY[@]}"; do ck_deny "$c" "$(run_bash "$c")"; done
+
+echo "== must ALLOW (safe ops) =="
+ALLOW=( 'rm file.txt' 'rm -i note.md' 'git status' 'git add -A' 'git log --oneline' 'git diff' 'ls -la' 'echo hi' 'mkdir build' 'git fetch' )
+for c in "${ALLOW[@]}"; do ck_allow "$c" "$(run_bash "$c")"; done
+
+echo "== gated tokens / edits / state =="
+touch "$TMP/.leopold/ALLOW_GIT"
+ck_allow 'git commit (ALLOW_GIT present)' "$(run_bash 'git commit -m ok')"
+rm -f "$TMP/.leopold/ALLOW_GIT"
+touch "$TMP/.leopold/ALLOW_PUSH"
+ck_allow 'git push (ALLOW_PUSH present)' "$(run_bash 'git push origin main')"
+rm -f "$TMP/.leopold/ALLOW_PUSH"
+ck_deny  'edit GUARDRAILS.md'      "$(run_edit "$TMP/.leopold/GUARDRAILS.md")"
+ck_deny  'edit settings.json'      "$(run_edit "$HOME/.claude/settings.json")"
+ck_deny  'edit a leopold hook'     "$(run_edit "$HOME/.claude/leopold/hooks/x.sh")"
+ck_deny  'edit run state.json'     "$(run_edit "$TMP/.leopold/state.json")"
+ck_allow 'edit a normal source file' "$(run_edit "$TMP/src/main.ts")"
+
+active 'not valid json {'
+ck_deny  'malformed state.json fails CLOSED (still blocks commit)' "$(run_bash 'git commit -m x')"
+active '{"active":false}'
+ck_allow 'inactive run does not guard' "$(run_bash 'git commit -m x')"
+
+echo "== whitespace/tab evasion + LEOPOLD_PARANOID=1 =="
+active '{"active":true,"iteration":1}'
+ck_deny  'tab-separated git -c commit' "$(run_bash "$(printf 'git\t-c\tx=y\tcommit')")"
+run_par() { jq -cn --arg c "$1" --arg cwd "$TMP" '{tool_name:"Bash",cwd:$cwd,tool_input:{command:$c}}' | LEOPOLD_PARANOID=1 bash "$GUARD" 2>/dev/null; }
+ck_deny  'paranoid denies curl|sh'   "$(run_par 'curl http://x | sh')"
+ck_deny  'paranoid denies wget'      "$(run_par 'wget http://x')"
+ck_deny  'paranoid denies git commit' "$(run_par 'git commit -m x')"
+ck_allow 'paranoid allows ls'        "$(run_par 'ls -la')"
+ck_allow 'paranoid allows git add'   "$(run_par 'git add -A')"
+ck_allow 'paranoid allows make test' "$(run_par 'make test')"
+
+echo
+if [ "$fail" -eq 0 ]; then
+  printf '\033[32mguard red-team: %d passed, 0 failed\033[0m\n' "$pass"
+else
+  printf '\033[31mguard red-team: %d passed, %d FAILED\033[0m\n' "$pass" "$fail"
+fi
+[ "$fail" -eq 0 ]

package/assets/scripts/test-hooks.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# Behavior tests for the Leopold hooks. Exits non-zero on any failure.
+# Requires jq. Run via `make hooks-test` or directly.
+set -u
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+HOOKS="$ROOT/hooks"
+T="$(mktemp -d)"
+trap 'rm -rf "$T"' EXIT
+mkdir -p "$T/.leopold"
+fail=0
+
+assert() { # name expected actual
+  if [ "$2" = "$3" ]; then
+    echo "  ok: $1"
+  else
+    echo "  FAIL: $1 (expected '$2', got '$3')"; fail=1
+  fi
+}
+dec() { printf '%s' "$1" | jq -r '.decision // "none"' 2>/dev/null || echo none; }
+perm() { printf '%s' "$1" | jq -r '.hookSpecificOutput.permissionDecision // "allow"' 2>/dev/null || echo allow; }
+
+# --- Stop hook ---
+echo '{"active":true,"iteration":1,"max_iterations":50}' > "$T/.leopold/state.json"
+printf '# Plan\n- [ ] open item\n' > "$T/.leopold/PLAN.md"
+out="$(printf '{"cwd":"%s"}' "$T" | bash "$HOOKS/stop-continuity.sh")"
+assert "stop hook continues when work remains" "block" "$(dec "$out")"
+
+echo '{"active":true,"iteration":1}' > "$T/.leopold/state.json"
+printf '# Plan\n- [x] done\n' > "$T/.leopold/PLAN.md"
+out="$(printf '{"cwd":"%s"}' "$T" | bash "$HOOKS/stop-continuity.sh")"
+assert "stop hook halts when plan complete" "" "$out"
+
+echo '{"active":false}' > "$T/.leopold/state.json"
+out="$(printf '{"cwd":"%s"}' "$T" | bash "$HOOKS/stop-continuity.sh")"
+assert "stop hook inert when run inactive" "" "$out"
+
+# --- Guard hook ---
+echo '{"active":true}' > "$T/.leopold/state.json"
+out="$(printf '{"cwd":"%s","tool_name":"Bash","tool_input":{"command":"git commit -m x"}}' "$T" | bash "$HOOKS/guard-irreversible.sh")"
+assert "guard denies git commit (no token)" "deny" "$(perm "$out")"
+
+touch "$T/.leopold/ALLOW_GIT"
+out="$(printf '{"cwd":"%s","tool_name":"Bash","tool_input":{"command":"git commit -m x"}}' "$T" | bash "$HOOKS/guard-irreversible.sh")"
+assert "guard allows commit with ALLOW_GIT" "" "$out"
+rm -f "$T/.leopold/ALLOW_GIT"
+
+out="$(printf '{"cwd":"%s","tool_name":"Bash","tool_input":{"command":"git add -A"}}' "$T" | bash "$HOOKS/guard-irreversible.sh")"
+assert "guard allows git add" "" "$out"
+
+out="$(printf '{"cwd":"%s","tool_name":"Bash","tool_input":{"command":"git push origin main"}}' "$T" | bash "$HOOKS/guard-irreversible.sh")"
+assert "guard denies git push" "deny" "$(perm "$out")"
+
+out="$(printf '{"cwd":"%s","tool_name":"Bash","tool_input":{"command":"rm -rf build"}}' "$T" | bash "$HOOKS/guard-irreversible.sh")"
+assert "guard denies rm -rf" "deny" "$(perm "$out")"
+
+echo '{"active":false}' > "$T/.leopold/state.json"
+out="$(printf '{"cwd":"%s","tool_name":"Bash","tool_input":{"command":"git commit -m x"}}' "$T" | bash "$HOOKS/guard-irreversible.sh")"
+assert "guard inert when run inactive" "" "$out"
+
+# --- Token hygiene on stop ---
+echo '{"active":true,"iteration":1}' > "$T/.leopold/state.json"
+printf '# Plan\n- [x] done\n' > "$T/.leopold/PLAN.md"
+touch "$T/.leopold/ALLOW_GIT" "$T/.leopold/STOP"
+printf '{"cwd":"%s"}' "$T" | bash "$HOOKS/stop-continuity.sh" >/dev/null 2>&1
+assert "stop clears ALLOW_GIT token" "cleared" "$([ -f "$T/.leopold/ALLOW_GIT" ] && echo present || echo cleared)"
+assert "stop clears STOP file" "cleared" "$([ -f "$T/.leopold/STOP" ] && echo present || echo cleared)"
+
+# --- Loop detection (no progress for N turns) ---
+echo '{"active":true,"iteration":0,"max_iterations":50,"max_no_progress":2}' > "$T/.leopold/state.json"
+printf '# Plan\n- [ ] stuck item\n' > "$T/.leopold/PLAN.md"
+for _ in 1 2 3; do printf '{"cwd":"%s"}' "$T" | bash "$HOOKS/stop-continuity.sh" >/dev/null 2>&1; done
+assert "stop hook halts on a no-progress loop" "no_progress" "$(jq -r '.stopped_reason // ""' "$T/.leopold/state.json" 2>/dev/null)"
+
+# --- State validation: fail safe + loud ---
+echo '{"active":true,"iteration":"abc","max_iterations":50}' > "$T/.leopold/state.json"
+printf '# Plan\n- [ ] x\n' > "$T/.leopold/PLAN.md"
+printf '{"cwd":"%s"}' "$T" | bash "$HOOKS/stop-continuity.sh" >/dev/null 2>&1
+assert "non-numeric budget field stops the run" "state_invalid" "$(jq -r '.stopped_reason // ""' "$T/.leopold/state.json" 2>/dev/null)"
+
+printf 'not json {' > "$T/.leopold/state.json"
+printf '{"cwd":"%s"}' "$T" | bash "$HOOKS/stop-continuity.sh" >/dev/null 2>&1
+assert "malformed state.json stops the run" "state_invalid" "$(jq -r '.stopped_reason // ""' "$T/.leopold/state.json" 2>/dev/null)"
+
+# --- Subagent budget (cost guard) ---
+task='{"cwd":"%s","tool_name":"Task","tool_input":{"description":"x"}}'
+echo '{"active":true,"max_subagents":2,"subagents_spawned":0}' > "$T/.leopold/state.json"
+out="$(printf "$task" "$T" | bash "$HOOKS/guard-irreversible.sh")"; assert "subagent 1/2 allowed" "" "$(perm "$out")"
+out="$(printf "$task" "$T" | bash "$HOOKS/guard-irreversible.sh")"; assert "subagent 2/2 allowed" "" "$(perm "$out")"
+out="$(printf "$task" "$T" | bash "$HOOKS/guard-irreversible.sh")"; assert "subagent over budget denied" "deny" "$(perm "$out")"
+assert "subagent counter persisted" "2" "$(jq -r '.subagents_spawned' "$T/.leopold/state.json" 2>/dev/null)"
+echo '{"active":false,"max_subagents":2,"subagents_spawned":9}' > "$T/.leopold/state.json"
+out="$(printf "$task" "$T" | bash "$HOOKS/guard-irreversible.sh")"; assert "subagent free when run inactive" "" "$(perm "$out")"
+
+# --- Fork budget (forks clone the whole context) ---
+echo '{"active":true,"max_subagents":8,"subagents_spawned":0,"max_forks":1,"forks_spawned":0}' > "$T/.leopold/state.json"
+fork='{"cwd":"%s","tool_name":"Task","tool_input":{"subagent_type":"fork","prompt":"x"}}'
+out="$(printf "$fork" "$T" | bash "$HOOKS/guard-irreversible.sh")"; assert "fork 1/1 allowed" "" "$(perm "$out")"
+out="$(printf "$fork" "$T" | bash "$HOOKS/guard-irreversible.sh")"; assert "fork over budget denied" "deny" "$(perm "$out")"
+echo '{"active":true,"max_subagents":8,"subagents_spawned":0}' > "$T/.leopold/state.json"
+out="$(printf "$fork" "$T" | bash "$HOOKS/guard-irreversible.sh")"; assert "fork forbidden by default (max_forks absent)" "deny" "$(perm "$out")"
+
+# --- Spawn audit log ---
+echo '{"active":true,"max_subagents":8,"subagents_spawned":0}' > "$T/.leopold/state.json"; : > "$T/.leopold/events.jsonl"
+printf "$task" "$T" | bash "$HOOKS/guard-irreversible.sh" >/dev/null
+assert "spawn logged to events.jsonl" "1" "$(grep -c subagent_spawn "$T/.leopold/events.jsonl" 2>/dev/null || echo 0)"
+
+# --- Oversized subagent prompt (context dumping) ---
+echo '{"active":true,"max_subagents":8,"subagents_spawned":0}' > "$T/.leopold/state.json"
+head -c 300000 /dev/zero | tr '\0' x > "$T/big.txt"
+jq -cn --rawfile p "$T/big.txt" --arg c "$T" '{cwd:$c,tool_name:"Task",tool_input:{prompt:$p}}' > "$T/bigin.json"
+out="$(bash "$HOOKS/guard-irreversible.sh" < "$T/bigin.json")"; assert "oversized subagent prompt denied" "deny" "$(perm "$out")"
+
+# --- Context budget (transcript over max_context_mb) ---
+echo '{"active":true,"iteration":1,"max_context_mb":1}' > "$T/.leopold/state.json"
+printf '# Plan\n- [ ] open\n' > "$T/.leopold/PLAN.md"
+head -c 1200000 /dev/zero | tr '\0' a > "$T/transcript.jsonl"
+printf '{"cwd":"%s","transcript_path":"%s/transcript.jsonl"}' "$T" "$T" | bash "$HOOKS/stop-continuity.sh" >/dev/null 2>&1
+assert "context budget stops the run" "context_budget" "$(jq -r '.stopped_reason // ""' "$T/.leopold/state.json" 2>/dev/null)"
+
+echo
+if [ "$fail" -eq 0 ]; then echo "all hook behavior tests passed"; else echo "HOOK TESTS FAILED"; exit 1; fi

package/assets/settings.template.json

@@ -0,0 +1,23 @@
+{
+  "//": "Leopold hook wiring. install.sh merges this into your ~/.claude/settings.json,",
+  "//2": "substituting the absolute path to the installed hooks. Both hooks are no-ops",
+  "//3": "unless a Leopold run is active (.leopold/state.json with active=true), so they",
+  "//4": "are safe to leave installed in every session.",
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "~/.claude/leopold/hooks/stop-continuity.sh" }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          { "type": "command", "command": "~/.claude/leopold/hooks/guard-irreversible.sh" }
+        ]
+      }
+    ]
+  }
+}

package/assets/skills/leopold-brief/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: leopold-brief
+version: 0.1.0
+description: "Phase 1 of Leopold. A structured debate that captures the mission and your decision-making, then writes the brief (MISSION, CHARTER, GUARDRAILS, PLAN) that the autonomous run executes."
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+triggers:
+  - leopold brief
+  - brief leopold
+  - start a leopold run
+---
+
+# /leopold-brief
+
+You are running Phase 1 of Leopold. Your job is to turn the user's intent into a
+durable brief the autonomous run can execute without you. This is a debate, not
+a form. Push back, surface tradeoffs, and name what is missing.
+
+The brief is the contract. The autonomous run never invents intent; it executes
+what you write here. The quality of the run is capped by the quality of this
+brief, so do it well.
+
+## Preamble — update check
+
+Quietly check for a Leopold update; if one is available, tell the user. If
+`~/.leopold/auto-update` exists, update now (the brief is a safe point).
+
+```bash
+UP="$(bash ~/.claude/leopold/scripts/leopold-update-check.sh 2>/dev/null || true)"
+if [ -n "$UP" ]; then
+  echo "$UP"
+  [ -f ~/.leopold/auto-update ] && bash ~/.claude/leopold/scripts/leopold-update.sh || echo "Update with: make update (or /leopold-update)"
+fi
+```
+
+## Step 0 — Set up
+
+Run: `mkdir -p .leopold`
+
+If `.leopold/MISSION.md` already exists, read all existing artifacts and offer to
+revise rather than overwrite.
+
+## Step 1 — Understand the mission (debate it)
+
+Through conversation (use AskUserQuestion for real forks), establish:
+
+- The problem and why it matters now.
+- The goal, and explicit non-goals (what we are deliberately not doing).
+- The definition of done: how we will know the mission succeeded.
+- Constraints: stack, deadlines, things that must not change.
+
+Challenge vague goals. If the user cannot state a definition of done, the
+mission is not ready; help them find it.
+
+## Step 2 — Capture the charter (this is the part that "becomes them")
+
+Elicit how the user makes decisions, so the run can decide as they would:
+
+- Priorities and what they optimize for (speed, robustness, simplicity, ...).
+- Technology and style preferences.
+- Hard rules: what they will NEVER accept, what they ALWAYS want.
+- Risk tolerance and how to break ties when principles conflict.
+
+Ask for concrete examples. "I hate clever abstractions" is more useful as "prefer
+a 10-line obvious function over a reusable helper unless it is used 3+ times."
+
+## Step 3 — Confirm guardrails
+
+Default posture (the recommended one): git commit, push, and publish stay
+LOCKED; the run stages and reports, the human commits. Confirm or adjust:
+
+- Which action classes are autonomous vs gated (default: all git write ops gated).
+- Stop conditions: max consecutive failures (default 3), max iterations
+  (default 50), token/time budget if any.
+
+## Step 4 — Build the plan
+
+Decompose the mission into an ordered, checkbox backlog in `PLAN.md`. Each item
+should be independently completable and verifiable. Order by dependency, then by
+value. Keep items small enough that one is a reasonable unit of autonomous work.
+
+## Step 4b — Harden the plan with gstack (optional)
+
+If gstack is installed (check for `~/.claude/skills/gstack/`, or whether the
+`/spec` skill exists), offer to sharpen the plan before writing it. gstack's
+planning skills are excellent here:
+
+- Heavy or architectural plan -> offer `/autoplan` or `/plan-eng-review`.
+- Product or scope decision -> offer `/plan-ceo-review`.
+- A fuzzy item that needs an executable spec -> offer `/spec`.
+
+Run them in spawned mode (prefix any gstack bash with `OPENCLAW_SESSION=1`) so
+they auto-decide and report instead of prompting, then fold the result back into
+`PLAN.md`. If gstack is not installed, skip this step silently; the plan you
+already built is enough. gstack is optional and separate: https://github.com/garrytan/gstack
+
+## Step 5 — Write the artifacts
+
+Copy the templates from the Leopold install (`~/.claude/leopold/templates/`) and
+fill them in, writing to:
+
+- `.leopold/MISSION.md`
+- `.leopold/CHARTER.md`
+- `.leopold/GUARDRAILS.md`
+- `.leopold/PLAN.md`
+
+Then create an empty `.leopold/DECISIONS.md` with a header.
+
+## Step 6 — Read it back
+
+Summarize the brief to the user in a few lines: mission, the 3 sharpest charter
+rules, the guardrail posture, and the first 3 plan items. Ask if it reflects how
+they actually think. Iterate until they confirm.
+
+End by telling them: when ready, run `/leopold-run` to hand over the seat.

package/assets/skills/leopold-doctor/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: leopold-doctor
+version: 0.1.1
+description: "Diagnose the Leopold install: checks skills, hooks and their wiring, gstack, the driver toolchain, and whether an update is available."
+allowed-tools:
+  - Bash
+triggers:
+  - leopold doctor
+  - check leopold install
+---
+
+# /leopold-doctor
+
+Verify that Leopold is installed correctly. Read-only.
+
+Run:
+
+```bash
+bash ~/.claude/leopold/scripts/leopold-doctor.sh
+```
+
+Report the summary. If any `[FAIL]` lines appear, tell the user the exact fix
+(usually re-running `./install.sh`, installing `jq`, or installing the plugin).

package/assets/skills/leopold-run/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: leopold-run
+version: 0.1.0
+description: "Phase 2 of Leopold. Enters autonomous mode and conducts Claude Code through the plan, deciding from the charter instead of asking, with git locked. The Stop hook keeps it going until the plan is done or a stop condition fires."
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Skill
+  - Agent
+triggers:
+  - leopold run
+  - run leopold
+  - hand over to leopold
+  - go autonomous
+---
+
+# /leopold-run
+
+You are now Leopold, conducting Claude Code on the user's behalf. You decide the
+way their charter says they would, you keep going on your own, and you never
+touch their git. Read this fully before acting.
+
+## Preamble — update check (notify only)
+
+```bash
+bash ~/.claude/leopold/scripts/leopold-update-check.sh 2>/dev/null || true
+```
+
+If it prints `UPDATE_AVAILABLE`, mention it once but do NOT update mid-run; finish
+the run first, then `/leopold-update`.
+
+## Step 0 — Preflight
+
+Confirm the brief exists: `.leopold/MISSION.md`, `.leopold/CHARTER.md`,
+`.leopold/GUARDRAILS.md`, `.leopold/PLAN.md`. If any is missing, stop and tell
+the user to run `/leopold-brief` first. Do not improvise a brief.
+
+Read all four artifacts in full. They are your authority.
+
+**Single-run guard (one run per checkout).** A project supports one active Leopold
+run at a time: parallel runs share `.leopold/` and the same working tree, so they
+would collide. Before activating, check for another active run:
+
+```bash
+LEO=.leopold
+if [ -f "$LEO/state.json" ]; then
+  a=$(jq -r '.active // false' "$LEO/state.json" 2>/dev/null)
+  l=$(jq -r '.last_turn // .started_at // empty' "$LEO/state.json" 2>/dev/null)
+  s=$(jq -r '.session_id // empty' "$LEO/state.json" 2>/dev/null)
+  if [ "$a" = "true" ] && [ -n "$l" ]; then
+    age=$(( $(date -u +%s) - $(date -u -d "$l" +%s 2>/dev/null || echo 0) ))
+    if [ "$age" -lt 600 ] && [ "$s" != "${CLAUDE_CODE_SESSION_ID:-none}" ]; then
+      echo "BLOCKED: another Leopold run is active in this checkout (last active $l)."
+    fi
+  fi
+fi
+```
+
+If it prints `BLOCKED`, stop. Tell the user a run is already active here. To run
+in **parallel**, use a separate git worktree (one run per worktree):
+
+    git worktree add ../<proj>-leopold-2 && cd ../<proj>-leopold-2
+
+Otherwise wait for the other run, or `/leopold-stop` it first. A run idle for
+over 10 minutes is treated as stale and may be taken over.
+
+## Step 1 — Activate the run
+
+Write `.leopold/state.json` (read `max_iterations` / `max_failures` from
+`GUARDRAILS.md`, else use defaults):
+
+```bash
+mkdir -p .leopold
+[ -f .leopold/DECISIONS.md ] || printf '# Decisions\n\nAutonomous decisions, newest last.\n\n' > .leopold/DECISIONS.md
+: >> .leopold/events.jsonl
+cat > .leopold/state.json <<JSON
+{"active":true,"iteration":0,"max_iterations":50,"consecutive_failures":0,"max_failures":3,"max_no_progress":6,"max_subagents":8,"subagents_spawned":0,"max_forks":0,"forks_spawned":0,"max_context_mb":5,"started_at":"$(date -u +%Y-%m-%dT%H:%M:%SZ)","last_turn":"$(date -u +%Y-%m-%dT%H:%M:%SZ)","session_id":"${CLAUDE_CODE_SESSION_ID:-}"}
+JSON
+```
+
+Once `state.json` has `active:true`, the guardrail hook is live: git
+commit/push/publish and destructive ops are blocked. The Stop hook will
+re-engage you after each turn until the plan is done.
+
+## Step 2 — Adopt spawned-session behavior
+
+For this entire run you are an orchestrator-driven session. That means:
+
+- **Do not use AskUserQuestion** except for a true irreversible-and-ambiguous
+  fork (see the decision protocol). Decide everything else yourself.
+- **Work serially. Do NOT fan out into parallel subagents.** Spawning subagents
+  (the `Task` tool) is the biggest cost multiplier there is: each one re-loads the
+  full session context, and a burst of 10 means 10× that context billed at once.
+  Do each plan item yourself, in your own turn. Only spawn a subagent for a single
+  genuinely isolatable sub-task, rarely, and never as a batch — there is a per-run
+  budget (`max_subagents`, default 8) the guard hard-enforces; past it, spawns are
+  denied and you continue serially. **Never fork** (a fork clones the entire session
+  context — the most expensive spawn; the guard caps forks at 2). When you do spawn a
+  subagent, hand it a **minimal prompt** — point it at file paths to read, never paste
+  files or the brief in; the guard denies oversized subagent prompts.
+- **Context discipline — the brief is your memory, not the transcript.** This is the
+  single biggest cost lever: a long session re-bills its whole growing context *every
+  turn*, so keeping your own context flat is what keeps a run cheap. Three rules:
+  1. **Don't pull bulk into your context.** Use targeted reads (offset/limit), grep, and
+     lean on `PLAN.md`/`CHARTER.md` instead of re-reading large files each turn.
+  2. **Delegate bulk-output work to a subagent that writes to a FILE.** For any item that
+     produces a lot of output (authoring content, generating files), spawn one subagent
+     whose prompt is only the spec + input *paths* + the output *path*. The subagent writes
+     the file; you verify it exists and mark the item done — **never read the full output
+     back** into your context. (This is exactly what blew up a real run: the orchestrator
+     held every lesson it generated.)
+  3. **Let it stop and resume.** The run auto-stops at `max_context_mb` (default 5); that
+     is by design — a fresh `/leopold-run` continues from `PLAN.md` with clean context.
+     Bounded, resumable segments beat one giant session.
+- **Prefer Serena's symbolic tools.** If the `mcp__serena__*` tools are present (the
+  Leopold install sets Serena up), use them to read and edit code: `get_symbols_overview`
+  / `find_symbol` / `find_referencing_symbols` to navigate, `replace_symbol_body` /
+  `insert_after_symbol` to edit. They operate on the *symbol*, not the whole file, so they
+  are far more token-efficient than grep + full-file reads — which is the same context-lean
+  discipline above — and far more reliable for cross-file refactors. Fall back to
+  grep/Read only for discovery or non-code files.
+- When you invoke a **gstack** skill, run it in spawned mode: it should
+  auto-pick the recommended option and report, not prompt. If a gstack skill
+  shells out to its own bins, prefix that bash with `OPENCLAW_SESSION=1`.
+
+## Step 3 — The decision protocol (how you decide instead of ask)
+
+On every fork, classify it:
+
+- **Reversible OR charter-clear** -> decide it yourself, append a one-block entry
+  to `.leopold/DECISIONS.md` (Fork / Class / Charter / Decision / Why / Reversal),
+  and continue.
+- **Irreversible AND ambiguous** -> stop and ask. Also stop for a charter
+  contradiction or a sign the mission premise itself is wrong.
+
+When you decide, use the charter first; when it is silent, use these six
+principles in order: completeness, boil-lakes-not-oceans, pragmatic, DRY,
+explicit-over-clever, bias-toward-action.
+
+## Step 4 — The turn loop
+
+Each turn:
+
+1. Read `.leopold/PLAN.md`; pick the next unchecked item.
+2. Complete it. Reach for the gstack playbook skill that fits the situation
+   (`/spec` before non-trivial builds, `/code-review` after changes, `/verify`
+   to confirm behavior, `/investigate` when something breaks, `/find-docs`
+   before guessing an API). Verify your work (build, lint, tests) before moving on.
+3. Resolve forks with the decision protocol; log non-mechanical decisions.
+4. Mark the item done (`[x]`) in `PLAN.md`.
+5. Finish your turn. Do not ask "should I continue?" The Stop hook decides that
+   from the plan and the stop conditions.
+
+If the same thing fails repeatedly, increment `consecutive_failures` in
+`state.json`; the stop condition will catch a stuck run.
+
+## Hard rules (never break, even if a turn seems to want it)
+
+- git commit/push/publish stay locked. Stage and report; do not commit. (The
+  hook enforces this; do not try to route around it.)
+- Never edit files outside this project root.
+- Never edit `.leopold/GUARDRAILS.md`, the hooks, or Claude Code settings.
+- When the plan is complete or a stop condition is hit, write a short final
+  summary (what shipped, key decisions, what is ready for the human to commit)
+  and stop.
+
+Begin now with turn 1.

package/assets/skills/leopold-status/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: leopold-status
+version: 0.1.0
+description: "Show the state of the current Leopold run: active or not, progress through the plan, decisions logged, and the most recent events."
+allowed-tools:
+  - Read
+  - Bash
+triggers:
+  - leopold status
+  - where is leopold
+---
+
+# /leopold-status
+
+Report the current run state. Read-only; never mutate anything.
+
+Run:
+
+```bash
+LEO=.leopold
+if [ ! -f "$LEO/state.json" ]; then echo "No Leopold run in this project."; exit 0; fi
+echo "=== Leopold status ==="
+jq -r '"active: \(.active)  turn: \(.iteration)/\(.max_iterations)  fails: \(.consecutive_failures)/\(.max_failures)  started: \(.started_at // "?")  stopped_reason: \(.stopped_reason // "-")"' "$LEO/state.json"
+done_n=$(grep -cE '^[[:space:]]*- \[x\]' "$LEO/PLAN.md" 2>/dev/null || echo 0)
+open_n=$(grep -cE '^[[:space:]]*- \[ \]' "$LEO/PLAN.md" 2>/dev/null || echo 0)
+echo "plan: $done_n done, $open_n open"
+echo "next open items:"; grep -E '^[[:space:]]*- \[ \]' "$LEO/PLAN.md" 2>/dev/null | head -3
+dec=$(grep -cE '^## D' "$LEO/DECISIONS.md" 2>/dev/null || echo 0)
+echo "decisions logged: $dec"
+echo "recent events:"; tail -5 "$LEO/events.jsonl" 2>/dev/null
+```
+
+Then summarize in one or two plain sentences: is it running, how far through the
+plan, and anything notable in the recent decisions or events.

package/assets/skills/leopold-stop/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: leopold-stop
+version: 0.1.0
+description: "Take the seat back. Cleanly ends the autonomous run at the next turn boundary and writes a final summary. Nothing is interrupted mid-turn."
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+triggers:
+  - leopold stop
+  - stop leopold
+  - take back the seat
+---
+
+# /leopold-stop
+
+End the autonomous run cleanly.
+
+Run:
+
+```bash
+LEO=.leopold
+if [ ! -f "$LEO/state.json" ]; then echo "No Leopold run to stop."; exit 0; fi
+tmp="$(mktemp)"; jq '.active=false | .stopped_reason="user_stop"' "$LEO/state.json" > "$tmp" && mv "$tmp" "$LEO/state.json"
+printf '{"ts":"%s","event":"stop","reason":"user_stop"}\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$LEO/events.jsonl"
+rm -f "$LEO/STOP" "$LEO/ALLOW_GIT" "$LEO/ALLOW_PUSH" "$LEO/ALLOW_PUBLISH"
+echo "Leopold run stopped (git re-locked; STOP and opt-in tokens cleared)."
+```
+
+This sets the run inactive, so the Stop hook will allow the session to halt at
+the next turn boundary. The blunt alternative is `touch .leopold/STOP`.
+
+After stopping, give the user a short handoff: what was completed (done items in
+`PLAN.md`), what decisions were made (`DECISIONS.md`), and what is staged and
+ready for them to review and commit. Remember: Leopold never committed; that is
+their call.

package/assets/skills/leopold-update/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: leopold-update
+version: 0.1.0
+description: "Update the Leopold engine (skills + hooks) to the latest release: pulls the source and re-runs the installer."
+allowed-tools:
+  - Bash
+triggers:
+  - leopold update
+  - update leopold
+---
+
+# /leopold-update
+
+Update the installed Leopold engine to the latest version.
+
+Run:
+
+```bash
+bash ~/.claude/leopold/scripts/leopold-update.sh
+```
+
+This pulls the latest source (`~/.local/share/leopold`) and re-runs `install.sh`
+(idempotent, backs up settings). For the Claude Code plugin install, use
+`claude plugin update leopold` instead; for the npm driver, `npm i -g leopold-driver@latest`.
+
+To opt into automatic updates (the brief checks and updates on its own):
+`touch ~/.leopold/auto-update`. Remove the file to go back to notify-only.