@oneie/claude 0.2.1 → 0.3.1

package/commands/do.md

@@ -122,7 +122,7 @@ For each **enabled** stop (per the pruned spine), in order: check if its artifac
 | ↳ *ANALYZE* | — | `do-analyze.sh plans/<slug>-todo.md` — CRITICAL exit 1 blocks BUILD | bash · none |
 | **code** | survey verdict = `build` (≥70% match → `expose`/`extend` instead) | the BUILD engine (Step 3) | sonnet · low–medium |
 | **tests** | test file in the repo folder | test-first, one assertion per deliverable | sonnet · low |
-| **proof** | proof artifact captured | `do-prove.sh` (browser / curl / contract / sync) + `accessibility`; **promise-check** the shipped thing against `text/<slug>.md`; FEATURE/SCHEMA built in a worktree → **merge to trunk only on PROVE pass**, abandon on fail | sonnet · low |
+| **proof** | proof artifact captured | `do-prove.sh` (browser / curl / contract / sync) + `accessibility`; **promise-check** the shipped thing against `text/<slug>.md`. A multi-cycle plan already built on its own `do/<slug>` branch (worktree isolation — see Step 2); PROVE is the gate that branch must clear before a human merges it to trunk | sonnet · low |
 | **docs** | feature doc + runbook exist | `tutorial` + `writer` — written against the *proven* behavior | sonnet · medium |
 | **release** | changelog / README row | `/release` + adoption signal | sonnet · low |
 
@@ -163,6 +163,8 @@ bun .claude/scripts/do-auto.sh <slug>
 
 `do-auto.sh` loops: each iteration spawns a clean `/do <slug> --next-cycle` that runs exactly one batch (W1→W4), ticks its boxes, writes state, and exits. Because each cycle starts from near-zero context, prior-cycle recon/edit/verify chatter never accumulates. The main session just kicks off the loop and reports the close.
 
+**Worktree isolation comes free with the loop.** The loop's existence *is* the trigger — `do-auto.sh` only runs for multi-cycle plans, which is exactly the FEATURE/SCHEMA work that must not land half-built on trunk. So before the first cycle it cuts a worktree `.do-worktrees/<slug>` on branch `do/<slug>` (reusing it on resume), syncs the plan's spine artifacts into it, and runs **every cycle inside it** — each cycle's edits and box-ticks commit to that branch. Trunk never moves while the loop runs; a halt (trust `cautious` / stall / max-cycles) leaves a clean, inspectable WIP branch, and re-running `/do <slug>` resumes in the same worktree. On plan-complete the loop **reports** the merge (`git merge --no-ff do/<slug>`) rather than running it — landing to trunk is a human decision (commit only when asked), and PROVE is the gate that branch cleared to earn the merge. PATCH/FIX never reach the loop, so they run inline with no worktree.
+
 A **single** incomplete cycle (or a PATCH/FIX) runs inline — there's nothing to isolate from, and spawning a subprocess would cost more than it saves.
 
 **`--next-cycle` is internal.** It means "run one batch, tick boxes, exit — do **not** loop." Only `do-auto.sh` passes it; it is the recursion guard that keeps a fresh `/do` from re-entering the loop. A human never types it.
@@ -266,7 +268,7 @@ PATCH clears {1,2,3,8}. FEATURE clears all eight.
 
 ## Available to /do — the toolbox
 
-**Scripts** (`.claude/scripts/`): `do-auto.sh` (*internal* — the context-isolated loop `/do` drives for multi-cycle plans) · `do-tier.sh` (tier + pruned spine + classifier + ceiling) · `do-folder.sh` (folder-aware verify/build) · `do-survey.sh` (reuse verdict) · `do-reconcile.sh` (substrate dim/verb/dead-name gate) · `do-analyze.sh` (deliverable↔cycle coverage gate) · `do-prove.sh` (surface-detect proof) · `do-smoke.sh` (deterministic outcome) · `w1-recon.ts` (prompt-cached recon) · `w4-rubric.ts` (cached parallel rubric).
+**Scripts** (`.claude/scripts/`): `do-auto.sh` (*internal* — the context-isolated, worktree-isolated loop `/do` drives for multi-cycle plans; builds on branch `do/<slug>`, merges to trunk only on a human's say-so) · `do-tier.sh` (tier + pruned spine + classifier + ceiling) · `do-folder.sh` (folder-aware verify/build) · `do-survey.sh` (reuse verdict) · `do-reconcile.sh` (substrate dim/verb/dead-name gate) · `do-analyze.sh` (deliverable↔cycle coverage gate) · `do-prove.sh` (surface-detect proof) · `do-smoke.sh` (deterministic outcome) · `w1-recon.ts` (prompt-cached recon) · `w4-rubric.ts` (cached parallel rubric).
 
 **Templates**: `text/template-frame.md` (promise) · `plans/template-spec.md` (design + pre-mortem + decisions) · `plans/template-todo.md` (plan + parallel budget + testing policy) · `plans/agent-template.md` (agent definition).
 

package/commands/skill-create.md

@@ -0,0 +1,100 @@
+# /skill-create — crystallise a cycle's learnings into a reusable skill
+
+Run after a `/do` cycle closes (or any meaningful session). Reads the recent git
+diff and the last `learnings.md` entry, then drafts a `SKILL.md` under
+`.claude/skills/<slug>/` — so the pattern compounds instead of evaporating.
+
+---
+
+## When to invoke
+
+- After `/do` closes a cycle and `learnings.md` has a new entry
+- When you notice a pattern being repeated across sessions
+- Explicitly: `/skill-create [slug]`
+
+If `[slug]` is omitted, derive it from the most recent `learnings.md` entry
+(the slug of the last `/do` cycle).
+
+---
+
+## What it does
+
+**Step 1 — Gather raw material (zero LLM)**
+
+```bash
+# Last learnings entry
+tail -5 plans/learnings.md
+
+# Recent cycle diff (what actually changed)
+git diff HEAD~1 HEAD --stat
+git diff HEAD~1 HEAD -- $(git diff HEAD~1 HEAD --name-only | grep -v 'plans/\|text/' | head -20)
+```
+
+**Step 2 — Extract the pattern (Haiku · low)**
+
+From the diff + learnings entry, identify:
+- What recurring problem this cycle solved
+- The specific shape of the solution (code pattern, file layout, command sequence)
+- When it applies (trigger condition)
+- When it doesn't (anti-patterns / exclusions)
+
+Ignore one-off specifics (feature names, slugs). Keep the reusable skeleton.
+
+**Step 3 — Write `.claude/skills/<slug>/SKILL.md`**
+
+Use this template:
+
+```markdown
+# <title> skill
+
+<one-sentence description — what this skill does for the model>
+
+## When to use
+<trigger phrase or condition that should invoke this skill>
+
+## Pattern
+<the reusable shape — code snippet, command, or process>
+
+## Don't
+- <anti-pattern 1>
+- <anti-pattern 2>
+
+## Example
+<minimal concrete example>
+```
+
+**Step 4 — Wire it (if applicable)**
+
+- If the skill has a natural trigger phrase, append a row to the skills table in
+  `.claude/CLAUDE.md` so it auto-loads.
+- If it extends an existing skill, note the relation.
+
+**Step 5 — Close**
+
+Emit `signal("learning:harden", 1, "skill=<slug>")` and append one line to
+`plans/learnings.md`:
+
+```
+- YYYY-MM-DD · skill:<slug> · crystallised from <source-slug> · source=skill-create
+```
+
+---
+
+## Rules
+
+- **Extract, don't invent.** The pattern must be in the diff or learnings entry — no
+  generalising beyond what the cycle actually did.
+- **One skill = one pattern.** If the cycle contains two independent patterns, create
+  two skills.
+- **Lean.** A skill that fits in 30 lines is more likely to be read than one that
+  doesn't. Cut examples to the minimum that makes the pattern clear.
+- **No cycle-specific names.** Slug and title describe the pattern, not the feature
+  that spawned it (`worktree-isolation`, not `do-auto-fix`).
+
+---
+
+## Close
+
+After writing the skill file: `[ ] skill-create:<slug> done` appended to
+`plans/learnings.md`, signal emitted, session stop-reflect will pick it up as
+a new primitive on the next session start.

package/hooks/hooks.json

@@ -1,9 +1,35 @@
 {
+  "PreToolUse": [
+    {
+      "matcher": "Edit|Write|MultiEdit",
+      "hooks": [
+        {
+          "id": "hook:gate-guard",
+          "type": "command",
+          "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/gate-guard.sh\"",
+          "timeout": 5000,
+          "blocking": true
+        }
+      ]
+    }
+  ],
   "PostToolUse": [
+    {
+      "matcher": "Read",
+      "hooks": [
+        {
+          "id": "hook:read-tracker",
+          "type": "command",
+          "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/read-tracker.sh\"",
+          "timeout": 3000
+        }
+      ]
+    },
     {
       "matcher": "Write|Edit",
       "hooks": [
         {
+          "id": "hook:post-edit",
           "type": "command",
           "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/post-edit-check.sh\"",
           "timeout": 15000
@@ -14,6 +40,7 @@
       "matcher": "Write|Edit|MultiEdit",
       "hooks": [
         {
+          "id": "hook:sync-todo-docs",
           "type": "command",
           "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/sync-todo-docs.sh\"",
           "timeout": 5000
@@ -24,6 +51,7 @@
       "matcher": "Write|Edit|MultiEdit",
       "hooks": [
         {
+          "id": "hook:design-check",
           "type": "command",
           "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/design-check.sh\"",
           "timeout": 5000,
@@ -35,6 +63,7 @@
       "matcher": "*",
       "hooks": [
         {
+          "id": "hook:tool-signal",
           "type": "command",
           "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/tool-signal.sh\"",
           "timeout": 3000
@@ -47,6 +76,7 @@
       "matcher": "*",
       "hooks": [
         {
+          "id": "hook:task-complete",
           "type": "command",
           "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/task-complete-verify.sh\"",
           "timeout": 120000,
@@ -60,12 +90,14 @@
       "matcher": "*",
       "hooks": [
         {
+          "id": "hook:session-end",
           "type": "command",
           "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/session-end-verify.sh\"",
           "timeout": 30000,
           "blocking": false
         },
         {
+          "id": "hook:stop-reflect",
           "type": "command",
           "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/stop-reflect.sh\"",
           "timeout": 10000,
@@ -79,6 +111,7 @@
       "matcher": "*",
       "hooks": [
         {
+          "id": "hook:session-start",
           "type": "command",
           "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/session-start.sh\"",
           "timeout": 5000,

package/hooks/lib/hook.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# Shared hook utilities. Source from any hook:
+#   source "$CLAUDE_PROJECT_DIR/.claude/hooks/lib/hook.sh"
+#
+# is_hook_disabled <id>  — returns 0 (skip) or 1 (run)
+# hook_session_key <json-arg>  — stable per-session key for temp files
+
+# ── Runtime toggles ──────────────────────────────────────────────────────────
+#
+# ECC_DISABLED_HOOKS=hook:gate-guard,hook:stop-reflect
+#   Comma-separated hook IDs to skip. Useful in CI or setup scripts.
+#
+# ECC_HOOK_PROFILE=minimal|standard (default: standard)
+#   minimal  — skips signal emissions, reflect, session-end, post-edit lint
+#   standard — all hooks active
+#
+# Per-hook disable: ECC_GATEGUARD=off  (alias for hook:gate-guard)
+
+is_hook_disabled() {
+  local id="$1"
+  local profile="${ECC_HOOK_PROFILE:-standard}"
+
+  # Explicit disable list (comma-separated)
+  if [[ -n "${ECC_DISABLED_HOOKS:-}" ]]; then
+    local IFS=','
+    for entry in $ECC_DISABLED_HOOKS; do
+      # trim whitespace
+      entry="${entry#"${entry%%[![:space:]]*}"}"
+      entry="${entry%"${entry##*[![:space:]]}"}"
+      [[ "$entry" == "$id" ]] && return 0
+    done
+  fi
+
+  # Profile-based skips
+  case "$profile" in
+    minimal)
+      case "$id" in
+        hook:tool-signal|hook:stop-reflect|hook:session-end|hook:post-edit) return 0 ;;
+      esac
+      ;;
+  esac
+
+  # Per-hook env aliases
+  case "$id" in
+    hook:gate-guard)
+      local v="${ECC_GATEGUARD:-}"
+      [[ "$v" =~ ^(0|off|false|disabled|disable)$ ]] && return 0
+      ;;
+  esac
+
+  return 1  # not disabled — run
+}
+
+# Derive a stable per-session key from the hook JSON payload ($1).
+# Uses session_id from JSON if present; falls back to a cksum of the
+# project dir so the key is consistent across hook invocations in one
+# session even when CLAUDE_SESSION_ID isn't set.
+hook_session_key() {
+  local payload="${1:-}"
+  local sid
+  sid=$(printf '%s' "$payload" | jq -r '.session_id // empty' 2>/dev/null)
+  if [[ -n "$sid" ]]; then
+    # Sanitise to filesystem-safe chars
+    printf '%s' "$sid" | tr -dc 'a-zA-Z0-9_-' | cut -c1-48
+    return
+  fi
+  # Fallback: hash of project dir
+  printf '%s' "${CLAUDE_PROJECT_DIR:-$(pwd)}" | cksum | awk '{print $1}'
+}

package/hooks/scripts/gate-guard.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# GATE-GUARD — PreToolUse(Edit|Write|MultiEdit): require Read before edit.
+#
+# Blocks the first attempt to Edit/Write an existing file that hasn't been
+# Read in this session. Forces "understand before you change."
+#
+# Rules:
+#   - New files (Write creating a file that doesn't exist yet) → always allowed
+#   - Settings files (.claude/settings*.json) → always allowed
+#   - Subagent calls → allowed (parent session's reads cover the session)
+#   - File already in this session's read registry → allowed
+#   - Existing file NOT yet read → BLOCK with instructions
+#
+# Disable for the session: ECC_GATEGUARD=off
+# Disable one-off:         ECC_DISABLED_HOOKS=hook:gate-guard
+# Skip globally in CI:     add hook:gate-guard to ECC_DISABLED_HOOKS in env
+
+# shellcheck source=lib/hook.sh
+_HOOK_LIB="${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/lib"
+source "$_HOOK_LIB/hook.sh"
+is_hook_disabled "hook:gate-guard" && exit 0
+
+PAYLOAD="${1:-}"
+[[ -z "$PAYLOAD" ]] && exit 0
+
+TOOL=$(printf '%s' "$PAYLOAD" | jq -r '.tool_name // empty' 2>/dev/null)
+case "$TOOL" in Edit|Write|MultiEdit) ;; *) exit 0 ;; esac
+
+# Subagents: parent session already passed the gate for these files
+SUBAGENT=$(printf '%s' "$PAYLOAD" | jq -r '.parent_tool_use_id // .parentToolUseId // empty' 2>/dev/null)
+[[ -n "$SUBAGENT" ]] && exit 0
+
+SESSION_KEY=$(hook_session_key "$PAYLOAD")
+READS_FILE="/tmp/oneie-gate-reads-${SESSION_KEY}"
+
+_deny() {
+  # Claude Code PreToolUse block format
+  printf '%s' "$(jq -nc --arg msg "$1" \
+    '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":$msg}}')"
+  exit 0
+}
+
+_is_settings() {
+  [[ "$1" =~ \.claude/settings[^/]*\.json$ ]]
+}
+
+_was_read() {
+  local fp="$1"
+  [[ -f "$READS_FILE" ]] && grep -qF "$fp" "$READS_FILE" 2>/dev/null
+}
+
+_block_msg() {
+  local fp="$1" verb="$2"
+  printf '[Gate-Guard] Read %s before you %s it.\n\nUse the Read tool on this file first to prove you understand it, then retry.\n\nTo disable for this session: set ECC_GATEGUARD=off\nTo disable permanently:   add hook:gate-guard to ECC_DISABLED_HOOKS in your environment.' \
+    "$fp" "$verb"
+}
+
+check() {
+  local fp="$1" tool="$2"
+  [[ -z "$fp" ]] && return 0
+  _is_settings "$fp" && return 0
+  # New file being created — no prior read needed
+  [[ "$tool" == "Write" && ! -f "$fp" ]] && return 0
+  # Previously read this session — allowed
+  _was_read "$fp" && return 0
+  # Existing file not read → block
+  [[ -f "$fp" ]] && { _deny "$(_block_msg "$fp" "$(printf '%s' "$tool" | tr '[:upper:]' '[:lower:]')")"; }
+  return 0
+}
+
+case "$TOOL" in
+  Edit|Write)
+    FILE=$(printf '%s' "$PAYLOAD" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+    check "$FILE" "$TOOL"
+    ;;
+  MultiEdit)
+    while IFS= read -r fp; do
+      [[ -z "$fp" ]] && continue
+      check "$fp" "Edit"
+    done < <(printf '%s' "$PAYLOAD" | jq -r '.tool_input.edits[].file_path // empty' 2>/dev/null)
+    ;;
+esac
+
+exit 0

package/hooks/scripts/read-tracker.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# READ-TRACKER — PostToolUse(Read): record file_path as read this session.
+#
+# Feeds gate-guard.sh: once a file appears in the reads registry,
+# Edit/Write on that file is allowed. Disable both with ECC_GATEGUARD=off
+# or ECC_DISABLED_HOOKS=hook:gate-guard.
+#
+# Non-blocking, always exits 0. Failure to write the registry is silent
+# (gate-guard falls back to allow on missing registry).
+
+# shellcheck source=lib/hook.sh
+_HOOK_LIB="${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/lib"
+source "$_HOOK_LIB/hook.sh"
+is_hook_disabled "hook:gate-guard" && exit 0
+
+PAYLOAD="${1:-}"
+[[ -z "$PAYLOAD" ]] && exit 0
+
+FILE=$(printf '%s' "$PAYLOAD" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+[[ -z "$FILE" ]] && exit 0
+
+SESSION_KEY=$(hook_session_key "$PAYLOAD")
+READS_FILE="/tmp/oneie-gate-reads-${SESSION_KEY}"
+
+# Append absolute path — idempotent (duplicates are fine, grep is fast)
+echo "$FILE" >> "$READS_FILE" 2>/dev/null || true
+exit 0

package/hooks/scripts/stop-reflect.sh

@@ -73,6 +73,18 @@ check_drift '^packages/sdk/src/'   'packages/sdk/CLAUDE.md'
 check_drift '^one\.ie/web/src/'    'one.ie/web/CLAUDE.md'
 check_drift '^api/src/'            'api/CLAUDE.md'
 
+# (4) Completed /do cycle → suggest /skill-create to crystallise the pattern.
+# Heuristic: learnings.md was touched AND W3 edited >=3 non-plan/non-text files.
+if echo "$CHANGED" | grep -qF 'plans/learnings.md'; then
+  CYCLE_FILES=$(echo "$CHANGED" | grep -vE '^plans/|^text/|^\.claude/' | wc -l | awk '{print $1}')
+  if [ "$CYCLE_FILES" -ge 3 ]; then
+    # Extract the cycle slug from the last learnings entry
+    CYCLE_SLUG=$(grep -oE 'cycle [0-9]+|· [a-z][a-z0-9-]+' plans/learnings.md 2>/dev/null | tail -1 | sed 's/^· //')
+    BUF+="- **skill-create** cycle closed with ${CYCLE_FILES} file(s) changed — run \`/skill-create ${CYCLE_SLUG}\` to crystallise the pattern as a reusable skill.\n"
+    PROPOSALS=$((PROPOSALS + 1))
+  fi
+fi
+
 # Only write the file if we found something worth reviewing
 if [ "$PROPOSALS" -gt 0 ]; then
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneie/claude",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "ONE Claude Code plugin — /do lifecycle, W1-W4 BUILD engine, ONE substrate via MCP, signals, and rules",
   "files": [
     ".claude-plugin",
@@ -19,11 +19,27 @@
     "@oneie/cli": ">=0.2.0"
   },
   "peerDependenciesMeta": {
-    "@oneie/sdk": { "optional": true },
-    "@oneie/mcp": { "optional": true },
-    "@oneie/cli": { "optional": true }
+    "@oneie/sdk": {
+      "optional": true
+    },
+    "@oneie/mcp": {
+      "optional": true
+    },
+    "@oneie/cli": {
+      "optional": true
+    }
   },
-  "keywords": ["claude-code", "plugin", "do", "lifecycle", "mcp", "signals", "typedb", "agents", "one"],
+  "keywords": [
+    "claude-code",
+    "plugin",
+    "do",
+    "lifecycle",
+    "mcp",
+    "signals",
+    "typedb",
+    "agents",
+    "one"
+  ],
   "license": "SEE LICENSE IN https://one.ie/free-license",
   "repository": {
     "type": "git",

package/scripts/do-auto.sh

@@ -40,15 +40,73 @@ fi
 # claude subprocess uses --dangerously-skip-permissions because it is non-interactive
 # — it cannot prompt the human for tool approvals. The workspace is the isolation
 # boundary. Do not expose this script to untrusted input or run it in shared environments.
-TODO="plans/${SLUG}-todo.md"
-TRUST=".do-trust.json"
+[ -f "plans/${SLUG}-todo.md" ] || { echo "[do-auto] plans/${SLUG}-todo.md not found — run /do $SLUG first" >&2; exit 1; }
 
-[ -f "$TODO" ] || { echo "[do-auto] $TODO not found — run /do $SLUG first" >&2; exit 1; }
+# ── Worktree isolation (one per plan) ────────────────────────────────────────
+# The loop's existence IS the trigger: do-auto only runs for multi-cycle plans
+# (>=2 incomplete cycles) = exactly the FEATURE/SCHEMA work that must not land
+# half-built on trunk. So every loop builds in its own worktree on branch
+# do/<slug>, leaving trunk green until a human merges. No tier plumbing, no flag.
+#
+# Why a worktree and not just a branch: the main session keeps observing trunk
+# while the loop's subprocesses build in a separate checkout — they never fight
+# over HEAD or the working tree. A halt leaves a clean, inspectable WIP branch.
+#
+#   trunk (BASE) ── never moves during the loop
+#        └─ do/<slug>  (worktree .do-worktrees/<slug>) ── every cycle commits here
+#   plan complete → report `git merge do/<slug>`  (human lands it — never auto)
+#   halt          → worktree persists → re-run /do <slug> resumes in place
+BASE="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo HEAD)"
+BR="do/${SLUG}"
+WT=".do-worktrees/${SLUG}"
+
+_setup_worktree() {
+  # Idempotent: reuse an existing worktree (resume), else attach one to an
+  # existing branch (prior halt), else create branch+worktree fresh from HEAD.
+  if git -C "$WT" rev-parse --git-dir >/dev/null 2>&1; then
+    echo "[do-auto] resuming worktree $WT on $BR"
+  elif git show-ref --verify --quiet "refs/heads/$BR"; then
+    echo "[do-auto] re-attaching worktree $WT to existing branch $BR"
+    git worktree add "$WT" "$BR" >/dev/null
+  else
+    echo "[do-auto] creating worktree $WT on new branch $BR (from $BASE)"
+    git worktree add -b "$BR" "$WT" HEAD >/dev/null
+  fi
+
+  # Carry the plan's own artifacts into the worktree. The spine walk may have
+  # just written promise/spec/todo uncommitted in the main tree; a worktree cut
+  # from HEAD wouldn't have them. Copy only this slug's files — never unrelated
+  # working-tree changes — then commit them as the branch baseline.
+  local f changed=0
+  for f in "plans/${SLUG}.md" "plans/${SLUG}-todo.md" "text/${SLUG}.md" ".w4-improvements.json"; do
+    if [ -f "$f" ]; then
+      mkdir -p "$WT/$(dirname "$f")"
+      if ! cmp -s "$f" "$WT/$f" 2>/dev/null; then cp "$f" "$WT/$f"; changed=1; fi
+    fi
+  done
+  if [ "$changed" -eq 1 ]; then
+    git -C "$WT" add -A
+    git -C "$WT" commit -q -m "do(${SLUG}): sync spine artifacts" 2>/dev/null || true
+  fi
+}
+
+if ! $DRY_RUN; then
+  _setup_worktree
+  # All loop state now lives in the worktree — read the boxes the subprocess ticks.
+  TODO="$WT/plans/${SLUG}-todo.md"
+  TRUST="$WT/.do-trust.json"
+else
+  TODO="plans/${SLUG}-todo.md"
+  TRUST=".do-trust.json"
+fi
 
 _remaining() {
   # Count cycles in the Status section that are open ([ ]) or in-flight ([~]) — i.e. not [x].
   # Pattern starts with '\[' (not '-') so grep never mistakes it for an option flag.
-  grep -cE '\[[ ~]\] C[0-9]+' "$TODO" 2>/dev/null || echo 0
+  # grep -c already prints a count (0 on no match) but exits 1 then — capture it so
+  # the `|| true` swallows the exit without appending a second "0" to the output.
+  local n; n=$(grep -cE '\[[ ~]\] C[0-9]+' "$TODO" 2>/dev/null) || true
+  echo "${n:-0}"
 }
 
 _trust() {
@@ -82,6 +140,7 @@ while [ "$i" -lt "$MAX_CYCLES" ]; do
     if [ "$stall" -ge 2 ]; then
       echo "[do-auto] no progress for 2 iterations (${remaining} cycle(s) stuck) — halting." >&2
       echo "[do-auto] The last cycle ticked no checkbox. Inspect $TODO, fix the blocker, then re-run /do $SLUG." >&2
+      echo "[do-auto] WIP preserved on branch $BR (worktree $WT)." >&2
       exit 1
     fi
   else
@@ -92,6 +151,7 @@ while [ "$i" -lt "$MAX_CYCLES" ]; do
   trust=$(_trust)
   if [ "$trust" = "cautious" ]; then
     echo "[do-auto] trust=cautious — halting. Fix the issue, then re-run /do $SLUG."
+    echo "[do-auto] WIP preserved on branch $BR (worktree $WT)."
     exit 1
   fi
 
@@ -107,11 +167,31 @@ while [ "$i" -lt "$MAX_CYCLES" ]; do
     break
   fi
 
-  # Fresh context: no --resume, no --continue. Each cycle is a clean slate.
-  claude --dangerously-skip-permissions -p "/do $SLUG --next-cycle"
+  # Fresh context, isolated tree: the subprocess runs INSIDE the worktree, so
+  # every edit/box-tick/state-write lands on branch $BR — trunk is never touched.
+  ( cd "$WT" && claude --dangerously-skip-permissions -p "/do $SLUG --next-cycle" )
+
+  # Commit the cycle on its branch. A cycle closes with a passing rubric, so it
+  # is the natural commit unit — and committed progress survives a later halt.
+  if [ -n "$(git -C "$WT" status --porcelain)" ]; then
+    git -C "$WT" add -A
+    git -C "$WT" commit -q -m "do(${SLUG}): cycle ${i}" || true
+  fi
 done
 
+if $DRY_RUN; then exit 0; fi
+
 if [ "$i" -ge "$MAX_CYCLES" ]; then
   echo "[do-auto] hit --max-cycles $MAX_CYCLES — halting"
+  echo "[do-auto] WIP preserved on branch $BR (worktree $WT)."
   exit 1
 fi
+
+# Plan complete. The branch holds every cycle, proven and committed; trunk is
+# untouched. Landing it is a human decision (commit/push only when asked), so we
+# report the merge instead of running it — the worktree stays for inspection.
+echo ""
+echo "[do-auto] ✓ plan complete on branch $BR — trunk ($BASE) untouched."
+echo "[do-auto]   land:    git merge --no-ff $BR        # from $BASE"
+echo "[do-auto]   inspect: git -C $WT log --oneline $BASE..$BR"
+echo "[do-auto]   discard: git worktree remove $WT && git branch -D $BR"