luciazero 2.2.0 → 2.4.1

package/claude/hooks/luciazero-verify.sh

@@ -53,17 +53,11 @@ if [ "${MODE}" = "doctrine" ]; then
   exit 0
 fi
 
-# Plugin-channel dedupe (the plugin's hooks.json invokes every mode with
-# LUCIAZERO_CHANNEL=plugin): when `install.sh --with-hooks` wiring is ALSO
-# present, the classic copy wins and the plugin copy stands down — otherwise
-# the stop nudge double-fires and a strict verify runs twice concurrently.
-if [ "${LUCIAZERO_CHANNEL:-}" = "plugin" ]; then
-  CFG="${CLAUDE_CONFIG_DIR:-${HOME:-}/.claude}"
-  if [ -x "${CFG}/hooks/luciazero-verify.sh" ] \
-     && grep -qF "${CFG}/hooks/luciazero-verify.sh" "${CFG}/settings.json" 2>/dev/null; then
-    exit 0
-  fi
-fi
+hook_path() { # canonical path of $1; empty when its directory does not exist
+  HP_DIR="$(cd "$(dirname "$1")" 2>/dev/null && pwd -P)" || return 0
+  [ -n "${HP_DIR}" ] || return 0
+  printf '%s/%s' "${HP_DIR}" "$(basename "$1")"
+}
 
 # Hook stdin is always a pipe; when run by hand from a terminal for debugging,
 # do not hang waiting for EOF that never comes.
@@ -82,25 +76,156 @@ except Exception:
 
 CWD="$(pyfield "d.get('cwd')")"
 [ -n "${CWD}" ] || CWD="${PWD}"
-KEY="$(printf '%s' "${CWD}" | python3 -c 'import sys,hashlib;print(hashlib.md5(sys.stdin.buffer.read()).hexdigest()[:12])' 2>/dev/null)" || exit 0
+
+# A repository's COMMITTED .claude/settings.json can put anything in its `env`
+# block, and that env reaches this hook — so NO LUCIAZERO_* knob is accepted
+# from that scope. Each one is a way to disable enforcement while the
+# statusline stays green: a widened LUCIAZERO_VERIFY_REGEX (or a
+# LUCIAZERO_VERIFY_CMD pointing at `echo`) makes any command count as a verify
+# run, LUCIAZERO_DOC_REGEX='.*' makes every edit look like documentation so
+# nothing is ever unverified, and LUCIAZERO_STRICT_VERIFY_CMD is a command this
+# hook would RUN at stop. CLAUDE_CONFIG_DIR is refused from that scope too: it
+# moves the config directory the dedupe below trusts.
+#
+# PROJECT scope only. The walk covers the session directory and its ancestors —
+# Claude Code merges project settings from the repository root and a session's
+# cwd is often a subdirectory — but it stops at the repository root, at
+# CLAUDE_PROJECT_DIR, and at $HOME, and it never reads the user's own config
+# directory. Personal settings (global `~/.claude/settings.json`, gitignored
+# `.claude/settings.local.json`) are the user's scope and keep working.
+#
+# Refusal only ever falls back to this file's own defaults, never to a block,
+# and a parse error leaves the configured values untouched. Only the modes that
+# consume a knob pay for the lookup.
+# The scanner program lives in a variable, not a here-document inside
+# $( ): bash 3.2 (still the /bin/bash on macOS) cannot parse that
+# combination and fails the whole file at load time.
+REFUSED_SCAN_PY='import json, os, stat, sys
+LIMIT = 1000000    # a settings file is kilobytes; this runs on every tool call
+MAX_DEPTH = 40     # ancestor walk is bounded, never unbounded I/O
+
+def refused(key):
+    return isinstance(key, str) and (key.startswith("LUCIAZERO_")
+                                     or key == "CLAUDE_CONFIG_DIR")
+
+def keys_in(path):
+    try:
+        info = os.stat(path)
+    except OSError:
+        return ()
+    # never read a fifo or device planted here: that would hang the hook
+    # instead of failing open
+    if not stat.S_ISREG(info.st_mode):
+        return ()
+    if info.st_size > LIMIT:
+        # absurd for a settings file: refuse everything rather than parse it
+        return ("LUCIAZERO_*",)
+    try:
+        with open(path, encoding="utf-8") as handle:
+            env = json.loads(handle.read(LIMIT)).get("env")
+    except Exception:
+        return ()
+    if not isinstance(env, dict):
+        return ()
+    return tuple(k for k in env if refused(k))
+
+def real(path):
+    try:
+        return os.path.realpath(path)
+    except OSError:
+        return path
+
+home = real(os.path.expanduser("~"))
+# Only the DEFAULT config directory counts as user scope. CLAUDE_CONFIG_DIR is
+# attacker-reachable: pointed at the project itself, it would mark the
+# repository settings file as user scope and skip the very file that declares
+# it, and the dedupe below would then trust a classic install inside the repo.
+user_config = real(os.path.join(home, ".claude"))
+project_dir = os.environ.get("CLAUDE_PROJECT_DIR")
+project_dir = real(project_dir) if project_dir else None
+
+found, seen = [], set()
+directory = real(sys.argv[1] or ".")
+for _ in range(MAX_DEPTH):
+    claude_dir = os.path.join(directory, ".claude")
+    if directory != home and real(claude_dir) != user_config:
+        for key in keys_in(os.path.join(claude_dir, "settings.json")):
+            if key not in seen:
+                seen.add(key)
+                found.append(key)
+    if directory == home:
+        break
+    if os.path.exists(os.path.join(directory, ".git")):
+        break  # repository root: project scope ends here
+    if project_dir is not None and directory == project_dir:
+        break
+    parent = os.path.dirname(directory)
+    if parent == directory:
+        break
+    directory = parent
+print("\n".join(found))
+'
+REFUSED_ENV_KEYS=""
+case "${MODE}" in
+  edit|bash|bash-failure|stop|session)
+    REFUSED_ENV_KEYS="$(printf '%s' "${REFUSED_SCAN_PY}" \
+      | python3 - "${CWD}" 2>/dev/null || true)"
+    ;;
+esac
+if [ -n "${REFUSED_ENV_KEYS}" ]; then
+  # `LUCIAZERO_*` is the oversized-file marker: drop every knob this hook reads
+  case "${REFUSED_ENV_KEYS}" in
+    *'LUCIAZERO_*'*)
+      REFUSED_ENV_KEYS='LUCIAZERO_VERIFY_CMD
+LUCIAZERO_VERIFY_REGEX
+LUCIAZERO_DOC_REGEX
+LUCIAZERO_STRICT_VERIFY_CMD
+LUCIAZERO_STRICT_TIMEOUT
+LUCIAZERO_RELAY_STALE_DAYS
+LUCIAZERO_HANDOFF_STALE_DAYS
+CLAUDE_CONFIG_DIR' ;;
+  esac
+  while IFS= read -r RK; do
+    case "${RK}" in
+      LUCIAZERO_[A-Z_]*|CLAUDE_CONFIG_DIR) unset "${RK}" 2>/dev/null || true ;;
+    esac
+  done <<EOF
+${REFUSED_ENV_KEYS}
+EOF
+fi
+
+# Channel dedupe: when `install.sh --with-hooks` wiring is ALSO present, the
+# classic copy wins and every other copy (the plugin's) stands down — otherwise
+# the stop nudge double-fires and a strict verify runs twice concurrently.
+#
+# Decided from this script's own path, never from LUCIAZERO_CHANNEL: an
+# env-driven dedupe let a repository hand the CLASSIC hook a plugin label so it
+# stood itself down. It runs after the refusal above for the same reason — a
+# committed CLAUDE_CONFIG_DIR could otherwise point at a repository-controlled
+# directory holding a "wired classic install", and every copy would stand down.
+CFG="${CLAUDE_CONFIG_DIR:-${HOME:-}/.claude}"
+CLASSIC_HOOK="$(hook_path "${CFG}/hooks/luciazero-verify.sh")"
+SELF_HOOK="$(hook_path "$0")"
+if [ -n "${CLASSIC_HOOK}" ] && [ "${SELF_HOOK}" != "${CLASSIC_HOOK}" ] \
+   && [ -x "${CLASSIC_HOOK}" ] \
+   && grep -qF "${CFG}/hooks/luciazero-verify.sh" "${CFG}/settings.json" 2>/dev/null; then
+  exit 0
+fi
+
+# md5 here names a state directory; it is never a security decision. Saying so
+# explicitly keeps the hook alive on a FIPS-enforcing python3, where a bare
+# md5() call raises and the tracker would fail open (silently doing nothing).
+KEY="$(printf '%s' "${CWD}" | python3 -c 'import sys,hashlib;print(hashlib.md5(sys.stdin.buffer.read(), usedforsecurity=False).hexdigest()[:12])' 2>/dev/null)" || exit 0
 [ -n "${KEY}" ] || exit 0
 BASE="${TMPDIR:-/tmp}/luciazero-verify-state-$(id -u 2>/dev/null || echo unknown)"
 # The base name is predictable, so validate ownership/type before touching it.
 # A hostile pre-created symlink or directory makes the hook fail open.
-python3 - "${BASE}" <<'PY' 2>/dev/null || exit 0
-import os, stat, sys
-path = sys.argv[1]
-try:
-    info = os.lstat(path)
-except FileNotFoundError:
-    os.mkdir(path, 0o700)
-    info = os.lstat(path)
-if not stat.S_ISDIR(info.st_mode) or stat.S_ISLNK(info.st_mode):
-    raise SystemExit(1)
-if hasattr(os, "getuid") and info.st_uid != os.getuid():
-    raise SystemExit(1)
-os.chmod(path, 0o700)
-PY
+if [ -e "${BASE}" ] || [ -L "${BASE}" ]; then
+  [ -d "${BASE}" ] && [ ! -L "${BASE}" ] && [ -O "${BASE}" ] || exit 0
+else
+  (umask 077 && mkdir "${BASE}") 2>/dev/null || exit 0
+fi
+chmod 700 "${BASE}" 2>/dev/null || exit 0
 STATE="${BASE}/${KEY}"
 mkdir -p "${STATE}" 2>/dev/null || exit 0
 chmod 700 "${STATE}" 2>/dev/null || exit 0
@@ -396,6 +521,12 @@ print("yes" if e is not None and (v is None or e > v) else "no")' "${STATE}" 2>/
     [ "${NUDGE}" = no ] && stat_log stop-clean
     ;;
   session)
+    # A committed settings env block that reconfigures this hook is worth one
+    # loud line: the refusal above is silent, and a repository that ships these
+    # keys is either mistaken or hostile. Names the keys, never their values.
+    if [ -n "${REFUSED_ENV_KEYS}" ]; then
+      echo "This repository's committed .claude/settings.json sets $(printf '%s' "${REFUSED_ENV_KEYS}" | tr '\n' ' ')— Luciazero refuses those keys from project scope (they can disable verify tracking or run a command at every stop). Review that env block before trusting this repo."
+    fi
     # SessionStart emits ONE pointer, never the relay contents. A legacy
     # HANDOFF.md gets a migration warning but is not silently rewritten.
     CAP="${CWD}/LUCIA_RELAY.json"

package/install-codex.sh

@@ -27,6 +27,10 @@ skill_inventory() {
   catalog "${SRC}/skills/catalog.txt"
   catalog "${SRC}/skills/aliases.txt"
 }
+version_of() {
+  awk -F '"' '/^[[:space:]]*"version"[[:space:]]*:/ { print $4; exit }' \
+    "${SRC}/package.json" 2>/dev/null || true
+}
 
 # collision-proof backup path for $1 (two runs in the same second must not overwrite)
 bakpath() {
@@ -64,6 +68,28 @@ install_tree() {
   cp -R "${IT_SRC}" "${IT_SNAPSHOT}"
 }
 
+# Remove a retired Luciazero skill only when its managed snapshot proves
+# ownership. A customized or colliding directory is user data and must survive
+# the migration with an explicit warning. Symlinked skill parents are refused
+# so the deletion cannot escape the configured directory.
+remove_legacy_tree() {
+  LT_DST="$1"; LT_SNAPSHOT="$2"; LT_LABEL="$3"
+  if [ ! -e "${LT_DST}" ] && [ ! -L "${LT_DST}" ]; then
+    if [ ! -L "$(dirname "${LT_SNAPSHOT}")" ]; then
+      rm -rf "${LT_SNAPSHOT}"
+    fi
+    return
+  fi
+  if [ -L "$(dirname "${LT_DST}")" ] || [ -L "$(dirname "${LT_SNAPSHOT}")" ]; then
+    echo "  !!  ${LT_LABEL} has a symlinked parent; left untouched" >&2
+  elif same_tree "${LT_DST}" "${LT_SNAPSHOT}"; then
+    rm -rf "${LT_DST}" "${LT_SNAPSHOT}"
+    echo "  ok  migrated ${LT_LABEL}"
+  else
+    echo "  !!  ${LT_LABEL} is customized or not Luciazero-owned; left untouched" >&2
+  fi
+}
+
 echo "Installing into ${CODEX_DIR}"
 mkdir -p "${CODEX_DIR}/skills"
 
@@ -99,6 +125,12 @@ while IFS= read -r SKILL; do
   echo "  ok  skills/${SKILL}"
 done < <(skill_inventory)
 
+# v2.3 migration: remove only the untouched /luciazero-bootstrap compatibility
+# alias from older installs. Customized copies remain user data.
+remove_legacy_tree "${CODEX_DIR}/skills/luciazero-bootstrap" \
+  "${MANAGED_DIR}/skills/luciazero-bootstrap" \
+  "skills/luciazero-bootstrap"
+
 LEGACY_HANDOFF="${CODEX_DIR}/skills/handoff"
 if [ -f "${LEGACY_HANDOFF}/SKILL.md" ]; then
   if cmp -s "${SRC}/migrations/handoff-v1.5.0.SKILL.md" "${LEGACY_HANDOFF}/SKILL.md"; then
@@ -123,7 +155,7 @@ while IFS= read -r AGENT_NAME; do
 done < <(catalog "${SRC}/claude/agents/catalog.txt")
 
 # 4. version sidecar (informational; removed by uninstall-codex.sh)
-V_NEW="$(grep -m1 -oE '^## \[[0-9]+\.[0-9]+\.[0-9]+\]' "${SRC}/CHANGELOG.md" 2>/dev/null | tr -d '#[] ' || true)"
+V_NEW="$(version_of)"
 if [ -n "${V_NEW}" ]; then
   printf '%s\n' "${V_NEW}" > "${CODEX_DIR}/.luciazero-version"
 fi

package/install.sh

@@ -34,9 +34,10 @@ skill_inventory() {
   catalog "${SRC}/skills/aliases.txt"
 }
 
-# newest released version in this checkout's CHANGELOG (informational)
+# Package metadata is present in git checkouts and npm payloads alike.
 version_of() {
-  grep -m1 -oE '^## \[[0-9]+\.[0-9]+\.[0-9]+\]' "${SRC}/CHANGELOG.md" 2>/dev/null | tr -d '#[] ' || true
+  awk -F '"' '/^[[:space:]]*"version"[[:space:]]*:/ { print $4; exit }' \
+    "${SRC}/package.json" 2>/dev/null || true
 }
 
 if [ "${STATUS_ONLY}" = 1 ]; then
@@ -100,8 +101,11 @@ if [ "${STATUS_ONLY}" = 1 ]; then
     else
       echo "  MISS  settings.json missing hook entries:${WIRE_MISS} (re-run ./install.sh --with-hooks)"; STATUS_RC=1
     fi
-    if command -v python3 >/dev/null 2>&1; then
-      echo "  ok    python3 available (the hooks need it)"
+    if command -v python3 >/dev/null 2>&1 \
+      && python3 -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 9) else 1)' 2>/dev/null; then
+      echo "  ok    python3 >= 3.9 available (the hooks need it)"
+    elif command -v python3 >/dev/null 2>&1; then
+      echo "  MISS  python3 is older than 3.9 — the hooks fail open (doing nothing)"; STATUS_RC=1
     else
       # fail-open means a missing python3 breaks the hooks SILENTLY — surface it here
       echo "  MISS  python3 not found — the installed hooks are failing open (doing nothing)"; STATUS_RC=1
@@ -158,6 +162,28 @@ install_tree() {
   cp -R "${IT_SRC}" "${IT_SNAPSHOT}"
 }
 
+# Remove a retired Luciazero skill only when its managed snapshot proves
+# ownership. A customized or colliding directory is user data and must survive
+# the migration with an explicit warning. Symlinked skill parents are refused
+# so the deletion cannot escape the configured directory.
+remove_legacy_tree() {
+  LT_DST="$1"; LT_SNAPSHOT="$2"; LT_LABEL="$3"
+  if [ ! -e "${LT_DST}" ] && [ ! -L "${LT_DST}" ]; then
+    if [ ! -L "$(dirname "${LT_SNAPSHOT}")" ]; then
+      rm -rf "${LT_SNAPSHOT}"
+    fi
+    return
+  fi
+  if [ -L "$(dirname "${LT_DST}")" ] || [ -L "$(dirname "${LT_SNAPSHOT}")" ]; then
+    echo "  !!  ${LT_LABEL} has a symlinked parent; left untouched" >&2
+  elif same_tree "${LT_DST}" "${LT_SNAPSHOT}"; then
+    rm -rf "${LT_DST}" "${LT_SNAPSHOT}"
+    echo "  ok  migrated ${LT_LABEL}"
+  else
+    echo "  !!  ${LT_LABEL} is customized or not Luciazero-owned; left untouched" >&2
+  fi
+}
+
 install_file() {
   IF_SRC="$1"; IF_DST="$2"; IF_SNAPSHOT="$3"; IF_LABEL="$4"
   if [ -e "${IF_DST}" ] || [ -L "${IF_DST}" ]; then
@@ -191,7 +217,7 @@ install_file "${SRC}/claude/${DOCTRINE}" "${CLAUDE_DIR}/${DOCTRINE}" \
   "${MANAGED_DIR}/${DOCTRINE}" "${DOCTRINE}"
 echo "  ok  ${DOCTRINE}"
 
-# 2. canonical skills plus temporary compatibility aliases
+# 2. canonical skills
 while IFS= read -r SKILL; do
   install_tree "${SRC}/skills/${SKILL}" \
     "${CLAUDE_DIR}/skills/${SKILL}" \
@@ -200,6 +226,12 @@ while IFS= read -r SKILL; do
   echo "  ok  skills/${SKILL}"
 done < <(skill_inventory)
 
+# v2.3 migration: remove only the untouched /luciazero-bootstrap compatibility
+# alias from older installs. Customized copies remain user data.
+remove_legacy_tree "${CLAUDE_DIR}/skills/luciazero-bootstrap" \
+  "${MANAGED_DIR}/skills/luciazero-bootstrap" \
+  "skills/luciazero-bootstrap"
+
 # v1.5 migration: remove only an untouched Luciazero /handoff. A customized
 # skill is user data and stays in place with an explicit warning.
 LEGACY_HANDOFF="${CLAUDE_DIR}/skills/handoff"
@@ -250,6 +282,10 @@ fi
 # 6. enforcement pack (opt-in): hooks + statusline wired into settings.json
 if [ "${WITH_HOOKS}" = 1 ]; then
   command -v python3 >/dev/null 2>&1 || { echo "FAIL: --with-hooks requires python3" >&2; exit 1; }
+  # 3.9 is where hashlib gained usedforsecurity=, which the hooks pass so their
+  # md5 state key does not raise under FIPS and silently disable tracking
+  python3 -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 9) else 1)' 2>/dev/null \
+    || { echo "FAIL: --with-hooks requires a working python3 >= 3.9" >&2; exit 1; }
   mkdir -p "${CLAUDE_DIR}/hooks"
   for H in luciazero-verify.sh luciazero-statusline.sh; do
     DST="${CLAUDE_DIR}/hooks/${H}"
@@ -332,7 +368,6 @@ echo
 SKILL_SUMMARY="$(catalog "${SRC}/skills/catalog.txt" | awk 'BEGIN{s=""} {s=s (s ? ", " : "") "/" $0} END{print s}')"
 AGENT_SUMMARY="$(catalog "${SRC}/claude/agents/catalog.txt" | awk 'BEGIN{s=""} {s=s (s ? ", " : "") $0} END{print s}')"
 echo "Skills: ${SKILL_SUMMARY}. Agents: ${AGENT_SUMMARY}."
-echo "Compatibility alias for one release: /luciazero-bootstrap -> /ready."
 if [ "${WITH_HOOKS}" = 1 ]; then
   echo "Enforcement pack installed: verify-tracking hooks + statusline (see settings.json)."
 else

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "luciazero",
-  "version": "2.2.0",
-  "description": "Verification-first discipline for coding agents (Claude Code + Codex CLI): 9-rule doctrine, 11 skills plus a temporary command alias, risk-routed reviewer, fail-open enforcement hooks. npx luciazero installs it.",
-  "repository": { "type": "git", "url": "git+https://github.com/ohm41321/luciazero.git" },
+  "version": "2.4.1",
+  "description": "Verification-first discipline for coding agents (Claude Code + Codex CLI): 9-rule doctrine, 11 skills, risk-routed reviewer, fail-open enforcement hooks. npx luciazero installs it.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ohm41321/luciazero.git"
+  },
   "homepage": "https://github.com/ohm41321/luciazero#readme",
-  "bugs": { "url": "https://github.com/ohm41321/luciazero/issues" },
+  "bugs": {
+    "url": "https://github.com/ohm41321/luciazero/issues"
+  },
   "bin": {
     "luciazero": "bin/luciazero.js"
   },
@@ -17,8 +22,7 @@
     "install.sh",
     "uninstall.sh",
     "install-codex.sh",
-    "uninstall-codex.sh",
-    "CHANGELOG.md"
+    "uninstall-codex.sh"
   ],
   "engines": {
     "node": ">=18"

package/skills/aliases.txt

@@ -1,2 +1 @@
-# Temporary compatibility aliases. Remove luciazero-bootstrap after one release.
-luciazero-bootstrap
+# Compatibility aliases are retired. Keep this file as the empty alias catalog.

package/skills/bisect/SKILL.md

@@ -1,26 +1,29 @@
 ---
 name: bisect
-description: Pinpoint the first bad commit for a reproducible regression without disturbing the caller's working tree. Use when HEAD is bad, a known revision is good, and one unattended command distinguishes them; supports flaky-endpoint detection and git-bisect skip exit 125.
+description: Pinpoint the first bad commit for a reproducible regression in a safe temporary worktree. Use when HEAD is bad, a known revision is good, and one unattended command distinguishes them; handles flaky endpoints and git-bisect skip exit 125.
 ---
 
-# Bisect — isolate the first bad commit safely
+# Bisect
 
 ## 1. Freeze the criterion
 
-Confirm the bad endpoint fails and identify a good commit or tag. Use one unattended command whose exit `0` means good, `1–124` means bad, and `125` means the revision cannot be tested. A missing executable is an infrastructure error, not evidence that a revision is bad.
+Confirm the bad endpoint fails and name a good commit or tag. One unattended
+command decides: exit `0` means good, `1–124` means bad, and `125` means
+untestable. A missing executable is an infrastructure error.
 
 ## 2. Run in a throwaway worktree
 
-Locate this skill's installed directory, stay in the repository under investigation, and invoke the bundled script by its absolute path:
-
 ```bash
 <this-skill-dir>/scripts/safe-bisect.sh --good <good-rev> --bad <bad-rev> -- <verify-command> [args...]
 ```
 
-The script resolves both endpoints, repeats each endpoint twice to catch instability, creates a detached temporary worktree, cleans generated state between revisions, runs `git bisect`, resets it, and removes the worktree on every exit path. Use `--retries N` only when the reproduction needs more endpoint samples.
-
-Do not run it for a nondeterministic symptom. Make the reproduction deterministic first through `/debug`.
+The helper repeats each endpoint twice, uses a detached temporary worktree,
+cleans state, resets bisect, and removes the worktree on every exit path. Use
+`--retries N` only for endpoint samples. Make the reproduction deterministic
+first through `/debug`.
 
 ## 3. Interpret narrowly
 
-Report the result as the **first bad commit**, not automatically the root cause. Read its diff and relevant callers, then feed that evidence into `/debug` as a hypothesis. Keep the reproduction as a regression test and run the full verification tier after the fix.
+Report the first bad commit, not automatically the root cause. Read its diff and
+relevant callers; feed `/debug`, keep the regression test, and run the full
+verification tier after fixing.

package/skills/debug/SKILL.md

@@ -1,51 +1,57 @@
 ---
 name: debug
-description: Hypothesis-driven debugging procedure. Use when a bug is not yet reliably reproduced, a fix attempt failed, debugging has gone two or more iterations without progress, or the user asks "debug this properly" or "ไล่บั๊ก". Not for a first obvious failure whose cause is already visible; reproduce and fix it directly.
+description: Debug a stubborn bug with a deterministic reproduction, hypothesis ledger, one-variable fixes, and a regression test. Use after the first obvious look fails, reproduction is unclear, or a fix attempt failed. Not for routine obvious failures; use for "ไล่บั๊ก".
 ---
 
-# Debug — hypothesis before edit
+# Debug
 
-The doctrine says: *debugging starts with a hypothesis, not an edit.* Mutating code until the test goes green is not debugging — it is how plausible-but-wrong fixes ship. This is the procedure for bugs that resist the first obvious look.
+For bugs that resist the first obvious look: debugging starts with a hypothesis,
+not an edit. Reality, not a plausible patch, decides.
 
 ## 1. Reproduce first
 
-One command that shows the failure deterministically. This command is the ground truth for the whole session — every hypothesis is judged against it.
+Find one command that shows the failure deterministically. It is ground truth.
+Do not theorize about causes of a failure you cannot trigger.
 
-- If it cannot be reproduced yet, that is the entire current task. Do not theorize about causes of a failure you cannot trigger.
-- If it is intermittent, make it deterministic before proceeding: fix the seed, pin the time/timezone, run it in a loop (`for i in $(seq 20)`) until the trigger condition is understood. An intermittent repro means the hypothesis space still contains "timing/state you have not seen".
+For intermittent failures, fix the seed, pin the time/timezone, run it in a loop,
+and identify the trigger before proceeding.
 
 ## 2. Minimize
 
-Shrink the reproduction — smaller input, fewer flags, one test instead of the suite — until the failure is small enough to reason about. Every element removed eliminates a family of hypotheses for free. Stop minimizing when shrinking stops being cheap.
+Shrink to smaller input, fewer flags, one test instead of the suite. Stop when
+further reduction costs more than it clarifies.
 
 ## 3. Hypothesis ledger
 
-**Seed it from recorded experience first.** Before inventing hypotheses, grep the symptom's keywords (error strings, subsystem names) against two files, if they exist:
+Before inventing causes, search the symptom in:
 
-- the repo's lesson ledger `docs/lessons.md` — this project's previously debugged failures;
-- the global heuristics file `luciazero-heuristics.md` in the harness config dir (`~/.claude` / `~/.codex`) — cross-repo lessons.
+- repo ledger `docs/lessons.md`;
+- configured harness `luciazero-heuristics.md` under
+  `${CLAUDE_CONFIG_DIR:-$HOME/.claude}` or
+  `${CODEX_HOME:-$HOME/.codex}`.
 
-A match becomes **H1** — still verify it with its `proven-by` command; a ledger match is a hypothesis with a head start, not a conclusion. No match, or no files: proceed normally.
-
-Keep a visible ledger in the conversation. Each entry:
+A match becomes **H1**, but must pass its `proven-by` observation.
 
 ```
-H<N>: <suspected cause> — refutable by: <command / observation> → <result: refuted | confirmed | pending>
+H<N>: <suspected cause> — refutable by: <command / observation> → <refuted|confirmed|pending>
 ```
 
-- **Run the observation, not the edit.** Choose the cheapest command whose output discriminates between this hypothesis and the alternatives — a log line, a targeted print, a debugger break, one `grep`, `git bisect run <verify-cmd>` when a known-good commit exists.
-- Prefer reading real state over reasoning about imagined state. The bug exists precisely because the mental model and reality differ — trust output.
-- Dead hypotheses stay in the ledger marked refuted, so they are not silently retried an hour later.
+Run the observation, not the edit. Choose the cheapest discriminating log,
+query, debugger stop, grep, or bisect. Trust real state. Dead hypotheses stay in
+the ledger marked refuted. Keep the ledger visible in the conversation.
 
 ## 4. One variable per iteration
 
-- Change one thing, re-run the reproduction, record the result in the ledger.
-- A fix attempt that failed gets **reverted before the next attempt** — stacked failed fixes create a second bug on top of the first.
-- Two consecutive failed fixes on the same hypothesis means the hypothesis is dead, not unlucky. Widen the search: environment, dependency versions, input data, concurrency, or the test itself being wrong.
+Change one thing, re-run the reproduction, and record the result. A failed fix
+gets **reverted before the next attempt**. Two consecutive failed fixes on the
+same hypothesis means the hypothesis is dead; widen to environment, versions,
+input, concurrency, or a wrong test.
 
 ## 5. Close out
 
-- The reproduction becomes a committed regression test: **red before the fix, green after** — run it both ways and quote both results. This proves the fix touched the actual cause. The mechanical form lives in the done skill's `scripts/` dir — run its `scripts/revert-probe.sh "<verify-cmd>"` from wherever that skill is installed (classic: `~/.claude/skills/done/`; plugin and `npx skills` installs keep it next to the done SKILL.md).
-- Remove all instrumentation (prints, sleeps, debug flags) — check the diff for it explicitly.
-- Run the full verify tier, not just the one test.
-- If the session surfaced something reading the code cannot teach (a footgun, an environment quirk, a disproven approach), run `/retro` so the next session does not pay for this one's dead ends — for a debugged failure specifically, `/retro` records it in `docs/lessons.md` (symptom → cause → proven-by → fix), which is exactly what step 3 reads next time.
+- Commit a regression test. Run it both ways and quote both results: red before
+  the fix, green after. Use the done skill's `revert-probe.sh` when applicable.
+- Remove all instrumentation: prints, sleeps, debug flags.
+- Run the full verify tier.
+- If the cause, footgun, or null result is not obvious from code, run `/retro`;
+  debugged failures go to `docs/lessons.md` as symptom → cause → proof → fix.

package/skills/discipline-report/SKILL.md

@@ -1,20 +1,33 @@
 ---
 name: discipline-report
-description: Analyze Luciazero's local stop-outcome log for evidence-backed verification habits. Use when the user asks for discipline stats, recurring nudge or strict-block patterns, a local behavior report, or runs `npx luciazero discipline`; supports time/project filters and machine-readable JSON.
+description: Analyze Luciazero stop-outcome logs for evidence-backed verification habits. Use for discipline stats, recurring nudge or strict-block patterns, local behavior reports, or machine-readable JSON.
 ---
 
-# Discipline report — turn local outcomes into evidence
+# Discipline report
 
-Run:
+Resolve the first available local CLI:
 
 ```bash
-npx luciazero discipline [--days N] [--project PATH_OR_ID] [--json]
+luciazero discipline [--days N] [--project PATH_OR_ID] [--json]
+node <this-skill-dir>/../../bin/luciazero.js discipline [--days N] [--project PATH_OR_ID] [--json]
 ```
 
-The report reads `luciazero-stats.log` from the Claude config directory by default. It accepts current schema-versioned JSON lines and legacy space-delimited records, ignores malformed lines without failing, and never sends data over the network. New enforcement-pack installs also summarize measured turn/Bash wall-clock milliseconds and Bash, verify, and model/user skill invocation counts. Parallel Bash intervals are merged before subtraction. These are aggregates: raw commands and skill names are never persisted.
+Use the first only when on PATH; use the second from a checkout/package. If
+neither local form exists, report unavailable offline. Use `npx` only when
+package resolution is explicitly allowed.
 
-Treat recorded outcomes as observations, not causes. A `nudge` proves an edit lacked a recognized later verify run; it does not prove why. A `strict-block` proves the configured strict command was red. Recommendations derived from patterns must say `likely` unless the log directly records the cause.
+The command reads `luciazero-stats.log`, accepts current
+schema-versioned JSON lines and legacy space-delimited records, ignores malformed
+lines without failing, and never sends data over the network. Telemetry includes
+turn/Bash wall time plus Bash, verify, and skill counts; parallel Bash intervals
+are merged. Raw commands and skill names are never persisted.
 
-Latency telemetry separates observed Bash time from the rest of the measured turn. The non-Bash remainder can include model reasoning, non-Bash tools, hook overhead, and harness scheduling, so do not label it as model latency without another measurement.
+Treat recorded outcomes as observations, not causes. `nudge` means no recognized
+later verify; `strict-block` means its strict command was red. Explanations must
+say `likely` unless the log records the cause.
 
-Use `--project .` to filter by the current repository's privacy-preserving project hash, or `--project <display-name-or-id>` for another entry. Use `--json` when feeding a dashboard or `/retro`.
+Non-Bash remainder includes tools, hooks, scheduling, and reasoning; do not
+label it as model latency without another measurement.
+
+Use `--project .` for this repo or another name/id as needed. Use `--json` for
+dashboards or `/retro`.