luciazero 1.5.0

package/skills/luciazero-bootstrap/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: luciazero-bootstrap
+description: Make a repository agentic-ready so an agent can run its own plan→change→verify→fix loop without a human checking each step. Use when entering an unfamiliar repo, when the user asks to "set up agentic engineering", "make this repo agent-friendly", "add a verify command", "add smoke tests so you can check your own work", "set up hooks/CLAUDE.md/allowlist" — or when a change was requested but no automated way exists to prove it works.
+---
+
+# Luciazero Bootstrap
+
+Goal: leave the repo with **one command that returns an exit code** and enough guardrails that future agent work self-verifies. Nothing here is language-specific — detect, don't assume.
+
+Bootstrapping is itself work: verify each artifact you add actually runs before reporting it.
+
+## Phase 1 — Detect (never assume)
+
+Run the bundled evidence scan first — it replaces a dozen manual reads with one call:
+
+```
+<this-skill-dir>/scripts/detect.sh <repo-root>
+```
+
+(The skill directory is wherever this SKILL.md lives, e.g. `~/.claude/skills/luciazero-bootstrap/` or `~/.codex/skills/luciazero-bootstrap/`.) The script surfaces candidates — **you still decide**. It cannot parse CI matrices or exotic build systems; open anything it flags and read the CI config yourself.
+
+Sources, in order of trust:
+
+1. CI config — the most honest source of truth: `.github/workflows/*`, `.gitlab-ci.yml`, `.circleci/`. **Whatever CI runs is the verify command.**
+2. Manifests: `package.json` scripts, `pyproject.toml` / `tox.ini` / `noxfile.py`, `Makefile`, `justfile`, `Cargo.toml`, `go.mod`, `build.gradle`, `composer.json`
+3. Repo docs: `README*`, `CONTRIBUTING*`, `AGENTS.md`, `CLAUDE.md`, `docs/` — docs go stale; cross-check any doc-claimed command against CI when CI exists. A docs/CI mismatch is itself a finding to record in Phase 5.
+4. Existing test dirs: `tests/`, `test/`, `spec/`, `__tests__/`, `*_test.*`, `test_*.*`
+
+Report what was found as a short table: run / test / lint / typecheck / build / git repo — command or `MISSING`.
+
+**If the directory is not under version control**, propose `git init` early (ask first — some dirs are deliberately not repos): without git there is no smallest reversible step, no safe break-and-restore in Phase 6, and no bisect.
+
+## Phase 2 — Establish the verify command
+
+If a verify path exists, **use it** — do not invent a parallel one.
+
+If none exists, create the smallest real one. Order of preference:
+
+1. The project's native runner, already installed (`pytest`, `vitest`, `go test`, `cargo test`, `dotnet test`)
+2. A single entrypoint that chains them, matching the repo's existing convention (`Makefile` target, `package.json` script, `justfile` recipe) — e.g. `make verify` running lint then tests
+
+Rules:
+- Must exit non-zero on failure. A script that always exits 0 is worse than nothing.
+- Must run to completion unattended: disable watch/interactive modes (e.g. `CI=1`, `--run`, `--watch=false`) — a command that waits for input or watches files hangs the loop.
+- Must run offline, with no credentials. Anything needing GPU/network/secrets belongs in a separate slow target.
+- Time the suite once (`time <cmd>`); the measurement, not a guess, decides one tier or two.
+- On success, output should be near-silent — prefer quiet flags in the fast tier so failures, not progress spam, fill the context.
+- Add it to the repo's own docs so humans find it too.
+
+**Two tiers when the repo has slow checks.** One `verify` command forces a bad trade: either the loop crawls or coverage gets cut. Split it:
+
+- `verify` — fast (<~60s), offline: lint, typecheck, unit/smoke tests. Run on **every** loop iteration.
+- `verify-full` — everything else: full suite, integration, build, slow checks. Run **before declaring done** and before a PR — "done" means `verify-full` green, not just `verify`.
+
+Name them by the repo's convention (`make verify` / `make verify-full`, npm scripts, just recipes). A small repo whose whole suite runs in seconds needs only the single tier — do not add ceremony it does not need.
+
+**Monorepos:** detect the workspace layout (`package.json` `workspaces`, `pnpm-workspace.yaml`, turbo/nx config, `go.work`, Cargo `[workspace]`). The fast tier must be scoped to the package being changed (e.g. `pnpm --filter <pkg> test`, `go test ./changed/pkg/...`, `cargo test -p <crate>`); `verify-full` is the root suite. Record in the Phase 5 notes how to derive the scoped command from a file path.
+
+**Enforcement pack users (Claude Code, ask first):** if the verify-tracking hooks are active — classic install: `~/.claude/hooks/luciazero-verify.sh` exists; plugin install: the `luciazero` plugin is enabled — offer to record the established command in the repo's *personal* settings so the tracker matches it exactly instead of by broad regex — `.claude/settings.local.json` (gitignored, never committed): `{"env": {"LUCIAZERO_VERIFY_CMD": "<the fast-tier command>"}}`. Derive it from CI (the honest source); it is a cache of that truth, so note it must be updated if CI changes. Show the exact JSON before writing anything.
+
+## Phase 3 — Smoke tests, if there are none
+
+Do **not** attempt coverage. Write 3–6 tests that would catch a catastrophic break. Pick by this heuristic:
+
+- **Contract shape** — the core data structure in/out: dimensions, keys, types, no NaN/null where impossible
+- **Round trip** — serialize→deserialize, encode→decode, save→load returns equal
+- **Import/boot** — every package imports, the app answers one request, the CLI runs `--help`. Prefer the framework's test client over binding a real port; any test that starts a process needs a hard timeout and must kill what it started.
+- **Artifact loads** — trained model / migration / config parses and does one forward pass or one query
+- **The bug you were sent to fix** — a regression test reproducing it, written *before* the fix
+
+Use fixtures small enough to commit. Never depend on the user's real data paths.
+
+State plainly that these are smoke tests, not a suite.
+
+## Phase 4 — Guardrails (only ones that pay for themselves)
+
+Hooks, `.claude/settings.json`, and `/fewer-permission-prompts` are **Claude Code mechanisms**. On a harness without them (Codex CLI), skip the hook items and encode the same guardrails as instructions in the project's `AGENTS.md` instead: which files are untouchable, which derived file must be regenerated after editing which source.
+
+Prefer few and deterministic. Candidates, in value order:
+
+- **Auto-format/lint on write** — `PostToolUse` hook matching `Edit|Write`, running the repo's own formatter. Only if the repo already has one configured.
+- **Regenerate derived files** — if editing source X requires regenerating Y (protobuf, OpenAPI clients, migrations, lockfiles), hook it, scoped inside the command to the relevant paths. This is the highest-value hook in most repos because humans forget it.
+- **Protect the untouchables** — `PreToolUse` deny on production config, secrets, live model/deploy pointers.
+- **Permission allowlist** — put the repo's read-only and verify commands into `.claude/settings.json` so the loop is not interrupted. `/fewer-permission-prompts` derives this from real transcripts.
+
+Put project-scoped settings in the repo's `.claude/settings.json` (shared) or `.claude/settings.local.json` (personal, gitignored) — **not** in global settings.
+
+Hooks execute automatically on the user's machine. Show the exact command before installing it, and never install one that pushes, deploys, deletes, or writes outside the repo.
+
+## Phase 5 — Project notes file (`CLAUDE.md` / `AGENTS.md`)
+
+Extend the notes file the repo already uses; if neither exists, create the one matching the current harness and add a one-line pointer from the other name so both find it. Write only what reading the code cannot tell you:
+
+- How to run / test / verify — the commands from Phase 2
+- Architecture facts that are load-bearing and non-obvious (what serves what, which file is source of truth)
+- **Footguns and null results**: "X looks right but breaks Y", "tried A, measured no gain, do not retry", "always rebuild Z after W"
+- Where the real docs live
+
+Do not restate the directory tree, git history, or anything a `grep` answers. Keep it dense; every line costs context on every future session.
+
+## Phase 6 — Prove it and report
+
+1. **Flake check** — run the fast verify tier twice. A green that does not repeat is a flake, and a flaky verify makes every future red ambiguous; fixing or quarantining the flake comes before relying on the loop. (Skip the double run only when the repo has a single slow tier — say so.)
+2. **Red check** — break a line a smoke test actually covers (flip an expected value or a return), confirm verify goes red, then restore. The break is one deliberate edit: **record file, line, and original text before making it, and restore by reverting exactly that edit.** Only use `git checkout -- <file>` if the file was committed before the break — on a file carrying uncommitted work it silently discards that work too, and it cannot restore the untracked test files this skill just wrote. Never use bare `git stash` here (it sweeps the whole tree and skips untracked files). Breaking an uncovered line and staying green proves nothing. A verify command that cannot fail is not a verify command.
+
+Report:
+- The one command to run (both tiers if split)
+- What it does and does not cover
+- What was added, and what was deliberately left out

package/skills/luciazero-bootstrap/scripts/detect.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# Read-only evidence scan for luciazero-bootstrap Phase 1.
+# Prints what exists in a repo — docs, manifests, script/target names, CI run
+# lines, test dirs, workspace markers. It surfaces candidates only; it never
+# picks the verify command. Judgment stays with the agent.
+#
+# Usage: detect.sh [repo-root]   (default: current directory)
+# Exits 0 unless the target directory does not exist; absence of a section
+# means nothing was found.
+set -euo pipefail
+
+cd "${1:-.}" 2>/dev/null || { printf 'detect.sh: no such directory: %s\n' "${1:-.}" >&2; exit 1; }
+
+say() { printf '%s\n' "$*"; }
+hr()  { printf '\n== %s ==\n' "$*"; }
+
+hr "repo: $(pwd)"
+if git rev-parse --git-dir >/dev/null 2>&1; then
+  say "git repo: yes (toplevel: $(git rev-parse --show-toplevel))"
+  if [ -z "$(git ls-files . | head -1)" ]; then
+    say "  WARNING: no tracked files under this dir — it may just sit inside an unrelated repo; revert/stash will not protect it"
+  fi
+else
+  say "git repo: NO — no safe revert, stash, or bisect until 'git init' (ask first)"
+fi
+
+hr "docs"
+for F in README README.md README.rst CONTRIBUTING.md AGENTS.md CLAUDE.md docs; do
+  if [ -e "$F" ]; then say "exists: $F"; fi
+done
+
+hr "manifests"
+for F in package.json pyproject.toml setup.py tox.ini noxfile.py Makefile \
+         justfile Justfile Cargo.toml go.mod build.gradle build.gradle.kts \
+         pom.xml composer.json Gemfile mix.exs CMakeLists.txt Package.swift; do
+  if [ -f "$F" ]; then say "exists: $F"; fi
+done
+
+if [ -f package.json ]; then
+  hr "package.json scripts"
+  if command -v python3 >/dev/null 2>&1; then
+    python3 -c 'import json,sys
+d = json.load(open("package.json"))
+for k, v in d.get("scripts", {}).items():
+    print(f"  {k}: {v}")' 2>/dev/null || say "  (unparseable package.json)"
+  else
+    sed -n '/"scripts"[[:space:]]*:/,/}/p' package.json
+  fi
+fi
+
+if [ -f Makefile ]; then
+  hr "Makefile targets"
+  grep -E '^[A-Za-z0-9_.-]+:' Makefile | cut -d: -f1 | sed 's/^/  /' | head -30 || true
+fi
+
+for J in justfile Justfile; do
+  if [ -f "$J" ]; then
+    hr "$J recipes"
+    grep -E '^[A-Za-z0-9_-]+.*:' "$J" | sed 's/^/  /' | head -30 || true
+  fi
+done
+
+hr "ci — whatever CI runs is the honest verify command; read these files yourself"
+for C in .github/workflows/*.yml .github/workflows/*.yaml .gitlab-ci.yml .circleci/config.yml; do
+  if [ -f "$C" ]; then
+    say "file: $C"
+    grep -nE '^[[:space:]]*(-[[:space:]]+)?(run|script)[[:space:]]*:' "$C" | sed 's/^/  /' | head -30 || true
+  fi
+done
+
+hr "test dirs / files (top two levels)"
+find . -maxdepth 2 \( -name .git -o -name node_modules -o -name .venv -o -name vendor \) -prune -o \
+  \( -type d \( -name tests -o -name test -o -name spec -o -name __tests__ \) -print \) 2>/dev/null | sed 's/^/  /' | head -10 || true
+find . -maxdepth 2 \( -name .git -o -name node_modules -o -name .venv -o -name vendor \) -prune -o \
+  \( -type f \( -name '*_test.*' -o -name 'test_*.*' -o -name '*.test.*' -o -name '*.spec.*' \) -print \) 2>/dev/null | sed 's/^/  /' | head -10 || true
+
+hr "workspace / monorepo markers"
+for F in pnpm-workspace.yaml turbo.json nx.json lerna.json go.work; do
+  if [ -f "$F" ]; then say "exists: $F"; fi
+done
+if [ -f package.json ] && grep -q '"workspaces"' package.json; then say "package.json declares workspaces"; fi
+if [ -f Cargo.toml ] && grep -q '^\[workspace\]' Cargo.toml; then say "Cargo.toml declares [workspace]"; fi
+
+exit 0

package/skills/retro/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: retro
+description: Harvest lessons from the session into the project's permanent notes. Use after finishing a hard task, a long debugging session, or any work that hit dead ends — when the user says "run a retro", "record what we learned", "จดบทเรียน", or when a task ends having disproven an approach that looked right.
+---
+
+# Retro — turn experience into recorded knowledge
+
+The doctrine says: *never re-derive a dead end twice.* This skill is the procedure that makes it actually happen. A team that logs its null results stops paying for the same experiment twice — that is the cheapest intelligence upgrade available.
+
+## 1. Scan the session
+
+Walk back through the work just finished and list candidates:
+
+- What took the longest, and was the time spent where you first expected?
+- Which attempts **failed**, and what was the real cause once found?
+- What looked like the right approach but was wrong — and why exactly?
+- What surprised you: environment quirks, undocumented behavior, a flag or version that mattered?
+- What did you have to re-discover that should already have been written down?
+
+**Also read the discipline stats**, if the enforcement pack is installed: `luciazero-stats.log` in the harness config dir (`~/.claude`), one line per stop outcome. Recurring `nudge` or `strict-block` lines for this project are behavioral lessons — e.g. repeated nudges usually mean the repo has no `LUCIAZERO_VERIFY_CMD` set or the fast verify tier is too slow to run habitually. Treat those patterns as candidates like any other.
+
+## 2. Filter hard
+
+Record only what **reading the code cannot tell a future agent**:
+
+- ✅ Null results: "tried X, measured no gain / broke Y — do not retry without new evidence"
+- ✅ Footguns: "A looks correct but silently breaks B"
+- ✅ Environment facts: version pins, platform quirks, commands that must follow other commands
+- ✅ Why a tempting approach is wrong (with the one-line evidence)
+- ❌ What the diff/git history already says
+- ❌ Anything a `grep` or `--help` answers
+- ❌ Session-only details (temp paths, one-off values)
+
+A null result is worth exactly as much as a success. If the session proved nothing new, say so and stop — an empty retro is a valid result; padding it with restated code facts makes every future session pay for noise.
+
+## 3. Route it, then write it
+
+**First decide who the lesson is true for:**
+
+- **Anyone who clones the repo** — code behavior, build quirks, disproven approaches → the committed notes below. A **debugged failure** specifically goes to the repo's lesson ledger `docs/lessons.md` in this fixed shape, so `/debug` can seed its hypothesis ledger from it next time:
+
+  ```
+  ## <one-line symptom, greppable — include the error string>
+  cause: <root cause> | proven-by: `<command>` | fix: <what fixed it> | date: YYYY-MM-DD
+  ```
+
+- **True in every repository** — engineering lessons not tied to this codebase ("intermittent async test: check timezone pinning before touching the test") → append one line to `luciazero-heuristics.md` in the harness config dir (`~/.claude` / `~/.codex`). Hard rules: one line per lesson, same update-in-place/dedup discipline, **cap the file at 100 lines** — when full, drop the weakest entry rather than growing (an unbounded heuristics file becomes context tax, the exact failure this pack exists to prevent). Never personal paths or secrets, even here.
+- **Only this machine or this user** — local paths, installed tool versions, personal preferences, credential locations → must **never** be committed. If the harness provides a persistent memory directory (Claude Code announces its per-project `memory/` dir and `MEMORY.md` index in context when enabled), write it there and update the index, applying the same format, dedup, and prune rules. If no memory system exists (Codex CLI, or memory disabled), keep only the generalization that is true for anyone who clones the repo — never personal preferences or credential locations, even generalized; if nothing repo-true remains, state the lesson in the retro report instead of writing it anywhere — an honest gap beats a note no harness will ever load.
+
+Format, one entry per lesson:
+
+```
+- **<topic>** — tried <X>; failed because <Y>; do <Z> instead. (evidence: <shortest decisive line>, <date>)
+```
+
+Committed destinations:
+
+- **Project notes file** (`CLAUDE.md` / `AGENTS.md` — extend the one the repo uses) — if the lesson is load-bearing for most future sessions and fits in 1–2 lines.
+- **`docs/<topic>.md`** — if it needs detail (measurements, alternatives tried, tables); then put a one-line pointer in the notes file.
+- Follow the project's existing convention if it already has an experiments log or notes dir — extend it, do not invent a parallel one.
+
+## 4. Dedup and prune
+
+Before writing, read the existing notes (and `MEMORY.md` when routing to harness memory):
+
+- If a note on the topic exists, **update it in place** — do not append a duplicate.
+- If the session **disproved** an existing note, correct or delete it and say so in the report.
+- The same two rules govern `docs/lessons.md` and `luciazero-heuristics.md`: a ledger entry whose cause this session disproved gets corrected or deleted — a stale lesson mis-seeds every future `/debug`.
+
+## 5. Verify as a future reader
+
+Re-read each entry pretending it is six months later and context is gone. Would you know what to do differently? If an entry needs this session's context to make sense, rewrite it with the missing facts inline.
+
+Report what was recorded, where, and what was deliberately not recorded (and why).

package/uninstall-codex.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Remove the Luciazero doctrine + skills from OpenAI Codex CLI (~/.codex).
+set -euo pipefail
+
+for ARG in "$@"; do
+  echo "unknown option: ${ARG} (uninstall-codex.sh takes no options)" >&2; exit 1
+done
+
+CODEX_DIR="${CODEX_HOME:-$HOME/.codex}"
+AGENTS_MD="${CODEX_DIR}/AGENTS.md"
+START='<!-- luciazero:start -->'
+END='<!-- luciazero:end -->'
+
+# collision-proof backup path for $1 (two runs in the same second must not overwrite)
+bakpath() {
+  B="$1.bak.$(date +%Y%m%d%H%M%S)"
+  N=1
+  while [ -e "${B}" ]; do B="$1.bak.$(date +%Y%m%d%H%M%S).${N}"; N=$((N+1)); done
+  printf '%s' "${B}"
+}
+
+echo "Removing from ${CODEX_DIR}"
+
+rm -f "${CODEX_DIR}/.luciazero-version"
+for SKILL in luciazero-bootstrap retro debug 'done' handoff experiment reviewer; do
+  rm -rf "${CODEX_DIR}/skills/${SKILL}"
+  echo "  ok  skills/${SKILL}"
+done
+
+if [ -f "${AGENTS_MD}" ] && grep -qF "${START}" "${AGENTS_MD}"; then
+  BACKUP="$(bakpath "${AGENTS_MD}")"
+  cp "${AGENTS_MD}" "${BACKUP}"
+  awk -v s="${START}" -v e="${END}" '
+    $0==s {inblock=1; next}
+    $0==e {inblock=0; next}
+    !inblock {print}
+  ' "${AGENTS_MD}" > "${AGENTS_MD}.tmp"
+  mv "${AGENTS_MD}.tmp" "${AGENTS_MD}"
+  [ -s "${AGENTS_MD}" ] || rm -f "${AGENTS_MD}"
+  echo "  ok  removed doctrine block (backup: $(basename "${BACKUP}"))"
+else
+  echo "  ok  no doctrine block in AGENTS.md"
+fi
+
+if [ -f "${CODEX_DIR}/luciazero-heuristics.md" ]; then
+  echo "  kept luciazero-heuristics.md (learned data) — delete manually if unwanted"
+fi
+
+echo
+echo "Done. Other AGENTS.md content was left untouched."

package/uninstall.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# Remove the Luciazero doctrine + bootstrap skill from ~/.claude/
+set -euo pipefail
+
+for ARG in "$@"; do
+  echo "unknown option: ${ARG} (uninstall.sh takes no options)" >&2; exit 1
+done
+
+CLAUDE_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
+DOCTRINE="luciazero.md"
+IMPORT_LINE="@${DOCTRINE}"
+GLOBAL_MD="${CLAUDE_DIR}/CLAUDE.md"
+
+# collision-proof backup path for $1 (two runs in the same second must not overwrite)
+bakpath() {
+  B="$1.bak.$(date +%Y%m%d%H%M%S)"
+  N=1
+  while [ -e "${B}" ]; do B="$1.bak.$(date +%Y%m%d%H%M%S).${N}"; N=$((N+1)); done
+  printf '%s' "${B}"
+}
+
+echo "Removing from ${CLAUDE_DIR}"
+
+rm -f "${CLAUDE_DIR}/${DOCTRINE}"
+rm -f "${CLAUDE_DIR}/.luciazero-version"
+echo "  ok  ${DOCTRINE}"
+
+for SKILL in luciazero-bootstrap retro debug 'done' handoff experiment; do
+  rm -rf "${CLAUDE_DIR}/skills/${SKILL}"
+  echo "  ok  skills/${SKILL}"
+done
+
+rm -f "${CLAUDE_DIR}/agents/reviewer.md"
+echo "  ok  agents/reviewer.md"
+
+# enforcement pack, if it was installed with --with-hooks.
+# Order matters: clean settings.json FIRST and delete the hook files only if
+# that succeeded — otherwise Claude Code would keep executing references to
+# files we just deleted.
+SRC="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SETTINGS="${CLAUDE_DIR}/settings.json"
+HOOKS_CLEAN=1
+if [ -f "${SETTINGS}" ] && grep -qF "${CLAUDE_DIR}/hooks/luciazero-" "${SETTINGS}"; then
+  if command -v python3 >/dev/null 2>&1; then
+    cp "${SETTINGS}" "$(bakpath "${SETTINGS}")"
+    # exact-path matching only: never touch a user's own hook that merely
+    # shares a basename with ours
+    if python3 - "${SETTINGS}" "${CLAUDE_DIR}" 2>/dev/null <<'PY'
+import json, os, sys
+
+path, claude_dir = sys.argv[1], sys.argv[2]
+with open(path) as f:
+    settings = json.load(f)
+
+MARKERS = (
+    os.path.join(claude_dir, "hooks", "luciazero-verify.sh"),
+    os.path.join(claude_dir, "hooks", "luciazero-statusline.sh"),
+)
+def ours(cmd):
+    return any(cmd == m or cmd.startswith(m + " ") for m in MARKERS)
+
+changed = False
+hooks = settings.get("hooks") or {}
+for event in list(hooks):
+    kept = []
+    for entry in hooks[event]:
+        inner = [h for h in entry.get("hooks", []) if not ours(h.get("command", ""))]
+        if inner != entry.get("hooks", []):
+            changed = True
+            if inner:
+                entry = dict(entry)
+                entry["hooks"] = inner
+                kept.append(entry)
+            # entry emptied by removal -> dropped
+        else:
+            kept.append(entry)
+    if kept:
+        hooks[event] = kept
+    elif hooks[event] != kept:
+        del hooks[event]
+        changed = True
+
+sl = settings.get("statusLine") or {}
+if isinstance(sl, dict) and ours(sl.get("command", "")):
+    del settings["statusLine"]
+    changed = True
+
+if changed:
+    with open(path, "w") as f:
+        json.dump(settings, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+PY
+    then
+      echo "  ok  removed hook entries from settings.json"
+    else
+      HOOKS_CLEAN=0
+      echo "  !!  could not clean settings.json (invalid JSON?) — hook files kept so nothing dangles; remove the luciazero-* entries manually, then delete ${CLAUDE_DIR}/hooks/luciazero-*.sh" >&2
+    fi
+  else
+    HOOKS_CLEAN=0
+    echo "  !!  python3 not found — settings.json untouched; hook files kept so nothing dangles" >&2
+  fi
+else
+  echo "  ok  no enforcement-pack entries in settings.json"
+fi
+if [ "${HOOKS_CLEAN}" = 1 ]; then
+  for H in luciazero-verify.sh luciazero-statusline.sh; do
+    F="${CLAUDE_DIR}/hooks/${H}"
+    if [ -f "${F}" ]; then
+      if cmp -s "${F}" "${SRC}/claude/hooks/${H}" 2>/dev/null; then
+        rm -f "${F}"
+        echo "  ok  hooks/${H}"
+      else
+        echo "  !!  hooks/${H} differs from the shipped version (customized or newer?) — left in place" >&2
+      fi
+    fi
+  done
+fi
+
+if [ -f "${GLOBAL_MD}" ] && grep -qF "${IMPORT_LINE}" "${GLOBAL_MD}"; then
+  BACKUP="$(bakpath "${GLOBAL_MD}")"
+  cp "${GLOBAL_MD}" "${BACKUP}"
+  # grep exits 1 when the import line was the only content — that is fine
+  grep -vxF "${IMPORT_LINE}" "${GLOBAL_MD}" > "${GLOBAL_MD}.tmp" || [ $? -eq 1 ]
+  mv "${GLOBAL_MD}.tmp" "${GLOBAL_MD}"
+  [ -s "${GLOBAL_MD}" ] || rm -f "${GLOBAL_MD}"
+  echo "  ok  removed import line (backup: $(basename "${BACKUP}"))"
+else
+  echo "  ok  no import line in CLAUDE.md"
+fi
+
+for KEEP in luciazero-stats.log luciazero-heuristics.md; do
+  if [ -f "${CLAUDE_DIR}/${KEEP}" ]; then
+    echo "  kept ${KEEP} (learned data) — delete manually if unwanted"
+  fi
+done
+
+echo
+echo "Done. Other CLAUDE.md content was left untouched."