luciazero 1.5.0

package/claude/hooks/luciazero-statusline.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# Enforcement-pack statusline (Claude Code only; installed by `install.sh
+# --with-hooks`). Shows: model | git branch | verify status from the state
+# that luciazero-verify.sh maintains — so the doctrine's ground truth is visible
+# at a glance instead of remembered.
+#
+#   ✅ verify 3m     last verify-ish command succeeded, 3 minutes ago
+#   ❌ verify RED    last verify-ish command failed
+#   ✳ verify ran     a verify ran but its result was unreadable
+#   ✎ unverified     edits happened after the last verify run
+#   — no verify yet  nothing tracked this session
+#
+# Requires python3. Fails open to a minimal line.
+set -u
+
+IN="$(cat 2>/dev/null || true)"
+
+LINE="$(printf '%s' "${IN}" | python3 -c '
+import json, os, sys, time, hashlib
+
+try:
+    d = json.load(sys.stdin)
+except Exception:
+    d = {}
+
+model = ((d.get("model") or {}).get("display_name")) or "claude"
+cwd = ((d.get("workspace") or {}).get("current_dir")) or d.get("cwd") or os.getcwd()
+
+key = hashlib.md5(cwd.encode()).hexdigest()[:12]
+state = os.path.join(os.environ.get("TMPDIR", "/tmp"), "luciazero-verify-state", key)
+
+def mtime(name):
+    try:
+        return os.path.getmtime(os.path.join(state, name))
+    except OSError:
+        return None
+
+def age(ts):
+    s = int(time.time() - ts)
+    if s < 60:
+        return f"{s}s"
+    if s < 3600:
+        return f"{s // 60}m"
+    return f"{s // 3600}h"
+
+ve, ed = mtime("last_verify"), mtime("last_edit")
+if ve is None and ed is None:
+    verify = "— no verify yet"
+elif ve is None or (ed is not None and ed > ve):
+    verify = "✎ unverified"
+else:
+    try:
+        status = open(os.path.join(state, "last_verify")).read().strip()
+    except OSError:
+        status = "ran"
+    if status == "ok":
+        verify = f"✅ verify {age(ve)}"
+    elif status == "fail":
+        verify = f"❌ verify RED {age(ve)}"
+    else:
+        verify = f"✳ verify ran {age(ve)}"
+
+print(model + "\t" + cwd + "\t" + verify)' 2>/dev/null)" || LINE=""
+
+if [ -z "${LINE}" ]; then
+  echo "claude"
+  exit 0
+fi
+
+MODEL="${LINE%%$'\t'*}"
+REST="${LINE#*$'\t'}"
+DIR="${REST%%$'\t'*}"
+VERIFY="${REST#*$'\t'}"
+
+BRANCH="$(git -C "${DIR}" branch --show-current 2>/dev/null || true)"
+if [ -n "${BRANCH}" ]; then
+  printf '%s | %s | %s\n' "${MODEL}" "${BRANCH}" "${VERIFY}"
+else
+  printf '%s | %s\n' "${MODEL}" "${VERIFY}"
+fi
+exit 0

package/claude/hooks/luciazero-verify.sh

@@ -0,0 +1,252 @@
+#!/usr/bin/env bash
+# Enforcement-pack hook (Claude Code only; installed by `install.sh --with-hooks`).
+# Tracks per-project whether edits have been followed by a verify run, and
+# nudges ONCE at session stop when they have not — mechanizing doctrine rule 1
+# ("done is proven by a command") at the exact moment it is most violated.
+#
+# Subcommands (wired in settings.json):
+#   edit    — PostToolUse on Edit|Write|NotebookEdit : record "an edit happened"
+#   bash    — PostToolUse on Bash                    : record verify runs + status
+#   stop    — Stop                                   : warn once if edits are unverified
+#   session — SessionStart                           : point at an existing HANDOFF.md
+#   doctrine— SessionStart (plugin installs only)    : emit the doctrine as context
+#             (plugins cannot add a CLAUDE.md import line; this is the same
+#             word-ceiling-capped text the classic install imports. Silent when
+#             a classic install exists, so the doctrine never loads twice.)
+#
+# Optional strict gate: when LUCIAZERO_STRICT_VERIFY_CMD is set, `stop`
+# actually RUNS that command and refuses the stop (exit 2) while it is red.
+# Set it in your PERSONAL settings (settings.local.json env block, or your
+# shell). LIMITATION: this hook cannot tell which settings scope set the
+# variable — a committed .claude/settings.json env block reaches it too — so
+# never commit it, and treat a repo that ships this variable as hostile.
+# A blocked stop's continuation is never re-blocked (stop_hook_active),
+# so this is a speed bump with evidence attached, not a wall.
+#
+# Requires python3 (for JSON parsing). FAILS OPEN: any internal error exits 0,
+# so a broken hook can never block real work. Per-project state lives under
+# $TMPDIR and never touches the repo. One exception, documented honestly: the
+# stop hook appends one line per stop outcome (stop-clean / nudge /
+# strict-block) to luciazero-stats.log in the harness config dir — local only,
+# capped at ~250 lines, fail-open — so /retro can turn recurring discipline
+# gaps into recorded lessons. Uninstall keeps it (it is learned data).
+set -u
+
+MODE="${1:-}"
+
+# doctrine mode needs no python3, no state, and no stdin — handled before the
+# shared setup so a machine without python3 still gets the doctrine (everything
+# below fails open to doing nothing there). ${HOME:-} keeps set -u fail-open
+# on hosts with no HOME at all.
+if [ "${MODE}" = "doctrine" ]; then
+  # a classic install's CLAUDE.md import already loads this text — never twice
+  [ -f "${CLAUDE_CONFIG_DIR:-${HOME:-}/.claude}/luciazero.md" ] && exit 0
+  DOCTRINE="$(cd "$(dirname "$0")" 2>/dev/null && cd .. && pwd)/luciazero.md"
+  [ -f "${DOCTRINE}" ] || exit 0
+  cat "${DOCTRINE}" 2>/dev/null || true
+  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 stdin is always a pipe; when run by hand from a terminal for debugging,
+# do not hang waiting for EOF that never comes.
+if [ -t 0 ]; then IN=""; else IN="$(cat 2>/dev/null || true)"; fi
+
+pyfield() { # pyfield '<python expr over dict d>' — empty string on any error
+  printf '%s' "${IN}" | python3 -c "
+import json, sys
+try:
+    d = json.load(sys.stdin)
+    v = ${1}
+    print('' if v is None else v)
+except Exception:
+    print('')" 2>/dev/null || true
+}
+
+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
+[ -n "${KEY}" ] || exit 0
+STATE="${TMPDIR:-/tmp}/luciazero-verify-state/${KEY}"
+mkdir -p "${STATE}" 2>/dev/null || exit 0
+
+stat_log() { # stat_log <event> — discipline stats for /retro; fail-open, capped
+  SDIR="${CLAUDE_CONFIG_DIR:-${HOME:-}/.claude}"
+  SFILE="${SDIR}/luciazero-stats.log"
+  {
+    mkdir -p "${SDIR}" \
+      && printf '%s %s %s\n' "$(date +%Y-%m-%dT%H:%M)" "$1" "$(basename "${CWD}")" >> "${SFILE}"
+    if [ "$(wc -l < "${SFILE}")" -gt 500 ]; then
+      tail -n 250 "${SFILE}" > "${SFILE}.tmp" && mv "${SFILE}.tmp" "${SFILE}"
+    fi
+  } 2>/dev/null || true
+}
+
+# What counts as a verify run. Deliberately broad; override per-shell with
+# LUCIAZERO_VERIFY_REGEX (extended regex, matched against the Bash tool command).
+# When LUCIAZERO_VERIFY_CMD is set (the repo's exact verify command, e.g.
+# "./test.sh"), only commands that ARE it or START with it count — the broad
+# regex also marks `cat test.sh` or `grep pytest README` as a verify run,
+# flipping the state green without any test having run.
+VERIFY_RE="${LUCIAZERO_VERIFY_REGEX:-verify|test\.sh|pytest|npm (run )?test|pnpm test|yarn test|cargo test|go test|vitest|jest|make (test|check)|tox|rake test|mix test|dotnet test|gradlew? (test|check)}"
+VERIFY_CMD="${LUCIAZERO_VERIFY_CMD:-}"
+
+case "${MODE}" in
+  edit)
+    # Documentation writes do not re-arm the nudge: the closeout skills
+    # (/done, /retro, /handoff, /experiment) all write markdown AFTER the
+    # final green verify — nudging on those would punish the prescribed flow.
+    FP="$(pyfield "d.get('tool_input', {}).get('file_path')")"
+    DOC_RE="${LUCIAZERO_DOC_REGEX:-\.(md|markdown|rst|txt)\$}"
+    if [ -n "${FP}" ] && printf '%s' "${FP}" | grep -qE "${DOC_RE}"; then
+      :  # doc-only write; verify state unchanged
+    else
+      touch "${STATE}/last_edit"
+      rm -f "${STATE}/nudged"        # new code edits re-arm the one-shot nudge
+    fi
+    ;;
+  bash)
+    CMD="$(pyfield "d.get('tool_input', {}).get('command')")"
+    IS_VERIFY=no
+    if [ -n "${CMD}" ]; then
+      if [ -n "${VERIFY_CMD}" ]; then
+        # exact mode: the command must BE or START WITH the configured command
+        case "${CMD}" in
+          "${VERIFY_CMD}"|"${VERIFY_CMD} "*) IS_VERIFY=yes ;;
+        esac
+      elif printf '%s' "${CMD}" | grep -qE "${VERIFY_RE}"; then
+        IS_VERIFY=yes
+      fi
+    fi
+    if [ "${IS_VERIFY}" = yes ]; then
+      # Best-effort red/green from the tool response; unknown shape -> "ran"
+      STATUS="$(pyfield "(lambda r, c=None: (lambda c: 'ok' if c == 0 else ('fail' if isinstance(c, int) else ('fail' if r.get('is_error') is True else 'ran')))(r.get('exit_code', r.get('exitCode'))))(d.get('tool_response') or {})")"
+      printf '%s\n' "${STATUS:-ran}" > "${STATE}/last_verify"
+      # remember WHICH command produced the state — the strict gate's fast
+      # path trusts a green only when this matches its own command
+      printf '%s\n' "${CMD}" > "${STATE}/last_verify_cmd" 2>/dev/null || true
+      rm -f "${STATE}/nudged"
+    fi
+    ;;
+  stop)
+    # Never re-block a continuation that a stop hook itself caused
+    ACTIVE="$(pyfield "d.get('stop_hook_active')")"
+    if [ "${ACTIVE}" = "True" ] || [ "${ACTIVE}" = "true" ]; then exit 0; fi
+    # Strict gate (opt-in, see header): actually run the user's verify command
+    # unless the tracked state is already green-after-last-edit. Any internal
+    # error — timeout, missing command, unparseable state — degrades to the
+    # ordinary fail-open nudge below, never to a block.
+    STRICT_CMD="${LUCIAZERO_STRICT_VERIFY_CMD:-}"
+    # Strict gate only on well-formed input: unparseable stdin means we know
+    # neither cwd nor stop_hook_active — running a command on guesses would
+    # break both the fail-open and the never-re-block guarantees.
+    JSON_OK="$(printf '%s' "${IN}" | python3 -c 'import json,sys; json.load(sys.stdin); print("yes")' 2>/dev/null || echo no)"
+    if [ -n "${STRICT_CMD}" ] && [ "${JSON_OK}" = yes ]; then
+      OUT="$(python3 -c '
+import os, subprocess, sys
+state, cwd, cmd, timeout = sys.argv[1:5]
+def m(name):
+    try:
+        return os.path.getmtime(os.path.join(state, name))
+    except OSError:
+        return None
+def read(name):
+    try:
+        return open(os.path.join(state, name)).read().strip()
+    except OSError:
+        return ""
+e, v = m("last_edit"), m("last_verify")
+# Fast path only for a green that THIS command (or a longer invocation of
+# it) produced — a broad-regex green from a mere read of the test file must
+# not disarm a gate whose promise is "actually runs the command".
+vcmd = read("last_verify_cmd")
+if (v is not None and read("last_verify") == "ok"
+        and (e is None or e <= v)
+        and (vcmd == cmd or vcmd.startswith(cmd + " "))):
+    print("green"); sys.exit(0)
+try:
+    r = subprocess.run(cmd, shell=True, cwd=cwd or None, timeout=float(timeout),
+                       capture_output=True, text=True)
+except Exception:
+    print("error"); sys.exit(0)
+if r.returncode in (126, 127):
+    # command not found / not executable: an internal error, not a red verify
+    print("error"); sys.exit(0)
+if r.returncode == 0:
+    print("ok")
+else:
+    tail = ((r.stdout or "") + "\n" + (r.stderr or "")).strip().splitlines()[-8:]
+    print("red")
+    print("\n".join(tail))
+' "${STATE}" "${CWD}" "${STRICT_CMD}" "${LUCIAZERO_STRICT_TIMEOUT:-120}" 2>/dev/null || echo error)"
+      case "${OUT%%$'\n'*}" in
+        green) stat_log stop-clean; exit 0 ;;
+        ok)
+          printf 'ok\n' > "${STATE}/last_verify" 2>/dev/null || true
+          printf '%s\n' "${STRICT_CMD}" > "${STATE}/last_verify_cmd" 2>/dev/null || true
+          rm -f "${STATE}/nudged"
+          stat_log stop-clean
+          exit 0 ;;
+        red)
+          printf 'fail\n' > "${STATE}/last_verify" 2>/dev/null || true
+          printf '%s\n' "${STRICT_CMD}" > "${STATE}/last_verify_cmd" 2>/dev/null || true
+          stat_log strict-block
+          echo "Strict verify gate: '${STRICT_CMD}' is RED. Fix it before finishing — or say plainly that you are handing back a red state. Failing output:" >&2
+          echo "${OUT#red}" >&2
+          exit 2 ;;
+        *) : ;;  # error — fall through to the ordinary fail-open nudge
+      esac
+    fi
+    # Sub-second mtime comparison via python: bash 3.2's [ -nt ] compares
+    # whole seconds only, silently missing an edit made in the same second
+    # as the last verify (the statusline already compares float mtimes).
+    NUDGE="$(python3 -c '
+import os, sys
+state = sys.argv[1]
+def m(name):
+    try:
+        return os.path.getmtime(os.path.join(state, name))
+    except OSError:
+        return None
+e, v = m("last_edit"), m("last_verify")
+print("yes" if e is not None and (v is None or e > v) else "no")' "${STATE}" 2>/dev/null || echo no)"
+    if [ "${NUDGE}" = yes ] && [ ! -f "${STATE}/nudged" ]; then
+      touch "${STATE}/nudged"
+      stat_log nudge
+      echo "Doctrine rule 1: edits were made but no verify command has run since the last edit. Run the repo's verify command and quote its decisive line — or finish anyway and say plainly that the change is unverified. (This nudge fires once.)" >&2
+      exit 2
+    fi
+    # NUDGE=no -> genuinely clean stop; yes-but-already-nudged logs nothing
+    # (that nudge was counted when it fired)
+    [ "${NUDGE}" = no ] && stat_log stop-clean
+    ;;
+  session)
+    # SessionStart: if a handoff capsule exists, emit ONE pointer line as
+    # context (stdout) — never the capsule's contents, which must be read and
+    # re-verified, not trusted. Silent (zero context cost) when none exists.
+    CAP="${CWD}/HANDOFF.md"
+    [ -f "${CAP}" ] || exit 0
+    AGE="$(python3 -c 'import os,sys,time;print(int((time.time()-os.path.getmtime(sys.argv[1]))//86400))' "${CAP}" 2>/dev/null || echo '')"
+    STALE="${LUCIAZERO_HANDOFF_STALE_DAYS:-7}"
+    if [ -n "${AGE}" ] && [ "${AGE}" -ge "${STALE}" ] 2>/dev/null; then
+      echo "HANDOFF.md exists but is ${AGE} days old — likely stale; a stale capsule is worse than none. Verify its claims with extra suspicion or delete it."
+    else
+      echo "HANDOFF.md exists (age: ${AGE:-?}d) — read it before touching code, re-verify its claims against the tree, then delete it (/handoff consume protocol)."
+    fi
+    ;;
+  *)
+    ;;
+esac
+
+exit 0

package/claude/luciazero.md

@@ -0,0 +1,24 @@
+# Luciazero — default operating mode
+
+Applies to every repo, every session. The loop is plan → change → verify → fix, repeated until verify passes or the blocker is real.
+
+## Ground truth
+
+1. **Done is proven by a command, not by my judgment.** Before saying a change works, run something that returns an exit code — test, lint, type-check, build, or a real invocation — and quote the shortest decisive line of its output. A run that did not happen is reported as exactly that. (closeout procedure: `/done`)
+2. **If no verification command exists, that is the first bug.** Say so and offer to create the smallest one that covers the change (procedure: `/luciazero-bootstrap`). Do not silently proceed on vibes.
+3. **Failing test/lint means not done.** Fix the cause. Never delete, skip, weaken, or suppress a check to reach green — if a check is genuinely wrong, say why and ask.
+
+## Loop
+
+4. **Debugging starts with a hypothesis, not an edit.** State the suspected cause and the command whose output would confirm or refute it — run that command before touching code (procedure: `/debug`). Keep the reproduction as a regression test: red before the fix, green after.
+5. **Orient before editing an unfamiliar repo:** find how to run, test, and lint it — CI is the most honest source of truth.
+6. **Smallest reversible step.** Targeted diff over rewrite; extend an existing helper instead of adding a parallel one.
+7. **Review the diff as a skeptic before saying done.** Tests prove what they cover; the last pass hunts what they do not — edge cases, error paths, changed contracts, files touched by accident. For risky or wide diffs, get an independent adversarial review — the harness's built-in review command when one exists, otherwise the `reviewer` agent — instructed to refute, not approve.
+
+## Memory
+
+8. **Never re-derive a dead end twice.** Non-obvious findings — null results, footguns, "tried X, failed because Y" — go into the project's notes file (`CLAUDE.md` / `AGENTS.md`, extend the one the repo uses), and those notes get read before working in an area they cover (procedure: `/retro`).
+
+## Autonomy
+
+9. **Stop and ask before:** deleting data, deploying or touching production, force-pushing, changing a public API or contract, spending real money, or leaving the agreed scope — make the question decidable in one reply: what, why, options, recommendation. Everything else: proceed, batching unknowns into one sharp question at the right time. Finish the whole scope; name anything left out.

package/install-codex.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# Install the Luciazero doctrine + skills into OpenAI Codex CLI (~/.codex).
+# Idempotent. Backs up AGENTS.md before editing. Writes nothing outside CODEX_HOME.
+#
+# Mapping (single source of truth stays in claude/):
+#   claude/luciazero.md        -> marker block in ~/.codex/AGENTS.md
+#   skills/<each>/                -> ~/.codex/skills/<each>/
+#     (luciazero-bootstrap, retro, debug, done, handoff, experiment)
+#   claude/agents/reviewer.md            -> ~/.codex/skills/reviewer/SKILL.md
+#                                           (Codex has no subagents; ships as a skill,
+#                                            Claude-only `tools:`/`model:` lines dropped)
+#   claude/hooks/ (enforcement pack)     -> NOT installed: Codex has no hooks/statusline
+set -euo pipefail
+
+for ARG in "$@"; do
+  echo "unknown option: ${ARG} (install-codex.sh takes no options)" >&2; exit 1
+done
+
+SRC="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+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 "Installing into ${CODEX_DIR}"
+mkdir -p "${CODEX_DIR}/skills"
+
+# 1. doctrine as a marker block in global AGENTS.md (replaced in place on reinstall)
+TMP="$(mktemp)"
+if [ -f "${AGENTS_MD}" ]; then
+  cp "${AGENTS_MD}" "$(bakpath "${AGENTS_MD}")"
+  # strip the old block AND trailing blank lines, so reinstalls do not
+  # accumulate one separator blank line per run
+  awk -v s="${START}" -v e="${END}" '
+    $0==s {inblock=1; next}
+    $0==e {inblock=0; next}
+    inblock {next}
+    NF {for (i=0; i<blank; i++) print ""; blank=0; print; next}
+    {blank++}
+  ' "${AGENTS_MD}" > "${TMP}"
+fi
+{
+  if [ -s "${TMP}" ]; then cat "${TMP}"; echo; fi
+  echo "${START}"
+  cat "${SRC}/claude/luciazero.md"
+  echo "${END}"
+} > "${AGENTS_MD}"
+rm -f "${TMP}"
+echo "  ok  AGENTS.md doctrine block"
+
+# 2. skills — same SKILL.md format as Claude Code, copied as-is
+for SKILL in luciazero-bootstrap retro debug 'done' handoff experiment; do
+  rm -rf "${CODEX_DIR}/skills/${SKILL}"
+  cp -r "${SRC}/skills/${SKILL}" "${CODEX_DIR}/skills/${SKILL}"
+  echo "  ok  skills/${SKILL}"
+done
+
+# 3. reviewer agent as a Codex skill, minus the Claude-only tools:/model: lines
+rm -rf "${CODEX_DIR}/skills/reviewer"
+mkdir -p "${CODEX_DIR}/skills/reviewer"
+awk 'NR==1 {front=($0=="---")} front && /^(tools|model): / {next} {print} front && NR>1 && $0=="---" {front=0}' \
+  "${SRC}/claude/agents/reviewer.md" > "${CODEX_DIR}/skills/reviewer/SKILL.md"
+echo "  ok  skills/reviewer"
+
+# 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)"
+if [ -n "${V_NEW}" ]; then
+  printf '%s\n' "${V_NEW}" > "${CODEX_DIR}/.luciazero-version"
+fi
+
+echo
+echo "Done. Verify:"
+echo "  grep -c 'luciazero:start' ${AGENTS_MD}   # expect 1"
+echo "  ls ${CODEX_DIR}/skills/"
+echo
+echo "The doctrine applies from the next Codex session."