luciazero 1.5.0

package/install.sh

@@ -0,0 +1,249 @@
+#!/usr/bin/env bash
+# Install the Luciazero doctrine + skills into ~/.claude/
+# Idempotent. Backs up CLAUDE.md (and settings.json when --with-hooks)
+# before editing. Writes nothing outside ~/.claude/.
+#
+#   ./install.sh               doctrine + skills + reviewer agent
+#   ./install.sh --with-hooks  also wire the enforcement pack: verify-tracking
+#                              hooks + statusline into ~/.claude/settings.json
+#                              (Claude Code only; requires python3)
+#   ./install.sh --status      read-only health check of an existing install;
+#                              exits non-zero if a core piece is missing
+set -euo pipefail
+
+WITH_HOOKS=0
+STATUS_ONLY=0
+for ARG in "$@"; do
+  case "${ARG}" in
+    --with-hooks) WITH_HOOKS=1 ;;
+    --status) STATUS_ONLY=1 ;;
+    *) echo "unknown option: ${ARG} (supported: --with-hooks, --status)" >&2; exit 1 ;;
+  esac
+done
+
+SRC="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLAUDE_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
+DOCTRINE="luciazero.md"
+IMPORT_LINE="@${DOCTRINE}"
+
+# newest released version in this checkout's CHANGELOG (informational)
+version_of() {
+  grep -m1 -oE '^## \[[0-9]+\.[0-9]+\.[0-9]+\]' "${SRC}/CHANGELOG.md" 2>/dev/null | tr -d '#[] ' || true
+}
+
+if [ "${STATUS_ONLY}" = 1 ]; then
+  echo "Status of ${CLAUDE_DIR} (read-only)"
+  STATUS_RC=0
+  check() { # check <file-test-flag: -f|-x> <path> <label...>
+    T="$1"; P="$2"; shift 2
+    OK=0
+    case "${T}" in
+      -x) if [ -x "${P}" ]; then OK=1; fi ;;
+      *)  if [ -f "${P}" ]; then OK=1; fi ;;
+    esac
+    if [ "${OK}" = 1 ]; then echo "  ok    $*"; else echo "  MISS  $*"; STATUS_RC=1; fi
+  }
+  check -f "${CLAUDE_DIR}/${DOCTRINE}" "doctrine ${DOCTRINE}"
+  for SKILL in luciazero-bootstrap retro debug 'done' handoff experiment; do
+    check -f "${CLAUDE_DIR}/skills/${SKILL}/SKILL.md" "skill ${SKILL}"
+  done
+  check -x "${CLAUDE_DIR}/skills/luciazero-bootstrap/scripts/detect.sh" "detect.sh executable"
+  check -x "${CLAUDE_DIR}/skills/done/scripts/revert-probe.sh" "revert-probe.sh executable"
+  check -f "${CLAUDE_DIR}/agents/reviewer.md" "reviewer agent"
+  GLOBAL_MD="${CLAUDE_DIR}/CLAUDE.md"
+  N="$(grep -cxF "${IMPORT_LINE}" "${GLOBAL_MD}" 2>/dev/null || true)"
+  if [ "${N:-0}" = 1 ]; then
+    echo "  ok    CLAUDE.md imports the doctrine"
+  else
+    echo "  MISS  CLAUDE.md import line (${IMPORT_LINE} exactly once; found ${N:-0})"; STATUS_RC=1
+  fi
+  V_SRC="$(version_of)"
+  V_INST="$(cat "${CLAUDE_DIR}/.luciazero-version" 2>/dev/null || true)"
+  if [ -z "${V_INST}" ]; then
+    echo "  --    installed version unknown (no sidecar — installed by an older version)"
+  elif [ "${V_INST}" = "${V_SRC}" ]; then
+    echo "  ok    version ${V_INST} (matches this checkout)"
+  else
+    echo "  !!    installed ${V_INST}, checkout ${V_SRC:-?} — re-run ./install.sh to update"
+  fi
+  if [ -f "${CLAUDE_DIR}/hooks/luciazero-verify.sh" ]; then
+    check -x "${CLAUDE_DIR}/hooks/luciazero-verify.sh" "hook luciazero-verify.sh executable"
+    check -x "${CLAUDE_DIR}/hooks/luciazero-statusline.sh" "hook luciazero-statusline.sh executable"
+    # stale hooks are the silent failure mode of `git pull && ./install.sh`
+    # without --with-hooks: sidecar updates, hook files do not
+    for HFILE in luciazero-verify.sh luciazero-statusline.sh; do
+      if cmp -s "${CLAUDE_DIR}/hooks/${HFILE}" "${SRC}/claude/hooks/${HFILE}"; then
+        echo "  ok    hooks/${HFILE} matches this checkout"
+      else
+        echo "  MISS  hooks/${HFILE} differs from this checkout (stale or customized) — re-run ./install.sh --with-hooks"; STATUS_RC=1
+      fi
+    done
+    WIRE_MISS=""
+    for SUB in edit bash stop session; do
+      grep -qF "${CLAUDE_DIR}/hooks/luciazero-verify.sh ${SUB}" "${CLAUDE_DIR}/settings.json" 2>/dev/null \
+        || WIRE_MISS="${WIRE_MISS} ${SUB}"
+    done
+    if [ -z "${WIRE_MISS}" ]; then
+      echo "  ok    hooks wired in settings.json (edit/bash/stop/session)"
+    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)"
+    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
+    fi
+  elif [ -f "${CLAUDE_DIR}/settings.json" ] \
+    && grep -qF "${CLAUDE_DIR}/hooks/luciazero-" "${CLAUDE_DIR}/settings.json"; then
+    # worse than not installed: Claude Code keeps executing references to
+    # files that are gone — exactly what uninstall.sh works to prevent
+    echo "  MISS  settings.json references hook files that do not exist (dangling — re-run ./install.sh --with-hooks or ./uninstall.sh)"; STATUS_RC=1
+  else
+    echo "  --    enforcement pack not installed (optional: ./install.sh --with-hooks)"
+  fi
+  exit "${STATUS_RC}"
+fi
+
+# 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 ${CLAUDE_DIR}"
+mkdir -p "${CLAUDE_DIR}/skills"
+
+# 1. doctrine
+cp "${SRC}/claude/${DOCTRINE}" "${CLAUDE_DIR}/${DOCTRINE}"
+echo "  ok  ${DOCTRINE}"
+
+# 2. skills
+for SKILL in luciazero-bootstrap retro debug 'done' handoff experiment; do
+  rm -rf "${CLAUDE_DIR}/skills/${SKILL}"
+  cp -r "${SRC}/skills/${SKILL}" "${CLAUDE_DIR}/skills/${SKILL}"
+  echo "  ok  skills/${SKILL}"
+done
+
+# 3. reviewer agent (back up a pre-existing customized copy before overwriting)
+mkdir -p "${CLAUDE_DIR}/agents"
+AGENT="${CLAUDE_DIR}/agents/reviewer.md"
+if [ -f "${AGENT}" ] && ! cmp -s "${SRC}/claude/agents/reviewer.md" "${AGENT}"; then
+  cp "${AGENT}" "$(bakpath "${AGENT}")"
+  echo "  ok  backed up existing agents/reviewer.md"
+fi
+cp "${SRC}/claude/agents/reviewer.md" "${AGENT}"
+echo "  ok  agents/reviewer.md"
+
+# 4. version sidecar — lets --status and future installs tell what is installed
+V_NEW="$(version_of)"
+V_OLD="$(cat "${CLAUDE_DIR}/.luciazero-version" 2>/dev/null || true)"
+if [ -n "${V_NEW}" ]; then
+  if [ -n "${V_OLD}" ] && [ "${V_OLD}" != "${V_NEW}" ]; then
+    echo "  ok  updating ${V_OLD} -> ${V_NEW}"
+  fi
+  printf '%s\n' "${V_NEW}" > "${CLAUDE_DIR}/.luciazero-version"
+fi
+
+# 5. import line in global CLAUDE.md
+GLOBAL_MD="${CLAUDE_DIR}/CLAUDE.md"
+if [ -f "${GLOBAL_MD}" ] && grep -qF "${IMPORT_LINE}" "${GLOBAL_MD}"; then
+  echo "  ok  CLAUDE.md already imports ${DOCTRINE}"
+else
+  if [ -f "${GLOBAL_MD}" ]; then
+    BACKUP="$(bakpath "${GLOBAL_MD}")"
+    cp "${GLOBAL_MD}" "${BACKUP}"
+    echo "  ok  backed up CLAUDE.md -> $(basename "${BACKUP}")"
+    printf '\n%s\n' "${IMPORT_LINE}" >> "${GLOBAL_MD}"
+  else
+    printf '%s\n' "${IMPORT_LINE}" > "${GLOBAL_MD}"
+  fi
+  echo "  ok  CLAUDE.md imports ${DOCTRINE}"
+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; }
+  mkdir -p "${CLAUDE_DIR}/hooks"
+  for H in luciazero-verify.sh luciazero-statusline.sh; do
+    DST="${CLAUDE_DIR}/hooks/${H}"
+    if [ -f "${DST}" ] && ! cmp -s "${SRC}/claude/hooks/${H}" "${DST}"; then
+      cp "${DST}" "$(bakpath "${DST}")"
+      echo "  ok  backed up existing hooks/${H}"
+    fi
+    cp "${SRC}/claude/hooks/${H}" "${DST}"
+    chmod +x "${DST}"
+  done
+  SETTINGS="${CLAUDE_DIR}/settings.json"
+  if [ -f "${SETTINGS}" ]; then
+    cp "${SETTINGS}" "$(bakpath "${SETTINGS}")"
+  fi
+  python3 - "${SETTINGS}" "${CLAUDE_DIR}/hooks" <<'PY' || { echo "FAIL: could not update settings.json (invalid JSON?) — hook files copied but not wired" >&2; exit 1; }
+import json, os, sys
+
+path, hooks_dir = sys.argv[1], sys.argv[2]
+verify_cmd = os.path.join(hooks_dir, "luciazero-verify.sh")
+status_cmd = os.path.join(hooks_dir, "luciazero-statusline.sh")
+
+settings = {}
+if os.path.exists(path):
+    with open(path) as f:
+        settings = json.load(f)
+
+changed = False
+hooks = settings.setdefault("hooks", {})
+
+def ensure(event, matcher, command):
+    global changed
+    entries = hooks.setdefault(event, [])
+    for e in entries:
+        for h in e.get("hooks", []):
+            if h.get("command") == command:
+                return
+    entry = {"hooks": [{"type": "command", "command": command}]}
+    if matcher is not None:
+        entry["matcher"] = matcher
+    entries.append(entry)
+    changed = True
+
+ensure("PostToolUse", "Edit|Write|NotebookEdit", verify_cmd + " edit")
+ensure("PostToolUse", "Bash", verify_cmd + " bash")
+ensure("Stop", None, verify_cmd + " stop")
+ensure("SessionStart", None, verify_cmd + " session")
+
+sl = settings.get("statusLine")
+if sl is None:
+    settings["statusLine"] = {"type": "command", "command": status_cmd}
+    changed = True
+    print("  ok  statusline wired")
+elif sl.get("command") == status_cmd:
+    print("  ok  statusline already wired")
+else:
+    print("  !!  statusline SKIPPED — a custom statusLine exists; to use ours, set")
+    print("      settings.json statusLine.command to: " + status_cmd)
+
+if changed:
+    with open(path, "w") as f:
+        # ensure_ascii=False: an escaped non-ASCII config path (é) would
+        # never match --status's byte-level greps for the hook commands
+        json.dump(settings, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+    print("  ok  hooks wired into settings.json")
+else:
+    print("  ok  hooks already wired")
+PY
+fi
+
+echo
+echo "Done. Verify:"
+echo "  ./install.sh --status"
+echo
+echo "Skills: /luciazero-bootstrap, /debug, /done, /handoff, /experiment, /retro. Reviewer agent: 'reviewer'."
+if [ "${WITH_HOOKS}" = 1 ]; then
+  echo "Enforcement pack installed: verify-tracking hooks + statusline (see settings.json)."
+else
+  echo "Optional: ./install.sh --with-hooks adds the verify-nudge hooks + statusline."
+fi
+echo "The doctrine applies from the next Claude Code session."

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "luciazero",
+  "version": "1.5.0",
+  "description": "Verification-first discipline for coding agents (Claude Code + Codex CLI): 9-rule doctrine, six skills, reviewer agent, 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" },
+  "bin": {
+    "luciazero": "bin/luciazero.js"
+  },
+  "files": [
+    "bin",
+    "claude",
+    "skills",
+    "install.sh",
+    "uninstall.sh",
+    "install-codex.sh",
+    "uninstall-codex.sh",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "codex",
+    "agent-skills",
+    "verification",
+    "doctrine",
+    "hooks",
+    "agentic-engineering"
+  ]
+}

package/skills/debug/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: debug
+description: Hypothesis-driven debugging procedure. Use when a bug is not yet reliably reproduced, when a fix attempt just failed, when debugging has gone two or more iterations without progress, or when the user asks "why is this failing", "debug this properly", "ไล่บั๊ก". Not for trivial errors whose cause is already visible in the message.
+---
+
+# Debug — hypothesis before edit
+
+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.
+
+## 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.
+
+- 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".
+
+## 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.
+
+## 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:
+
+- 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.
+
+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:
+
+```
+H<N>: <suspected cause> — refutable by: <command / observation> → <result: 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.
+
+## 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.
+
+## 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.

package/skills/done/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: done
+description: Closeout ritual before declaring any non-trivial task complete. Use when about to say "done", "finished", "it works now", before opening a PR, when the user asks "is it done?", "wrap it up", "ปิดงาน" — or whenever a change is about to be handed back as complete. Not for trivial single-line answers with no code change.
+---
+
+# Done — prove it before you say it
+
+The doctrine says: *done is proven by a command, not by my judgment.* This is the ritual that turns that rule into a checklist. Run every step; skipping one is how "done" ships broken.
+
+## 1. Full verify
+
+Run the **full** tier (`verify-full` if the repo has two tiers, else the verify command). Quote the shortest decisive line of real output.
+
+- Red → you are not here yet. Go back to the loop; do not continue this ritual.
+- No verify command exists → that is the first bug (`/luciazero-bootstrap`). Say so instead of declaring done.
+- The command must actually have run **now**, in this session — a green from an hour ago proves the past, not the present.
+
+## 2. Skeptic diff pass
+
+Re-read the final diff as a hostile reviewer. Tests prove what they cover; hunt what they do not:
+
+- **Edge cases** — empty, zero, negative, unicode, first/last, concurrent
+- **Error paths** — the call fails, the file is missing, the network drops; are errors swallowed?
+- **Changed contracts** — public API shape, serialized formats, schema, config keys: who consumes the old shape?
+- **Accidental content** — files touched by mistake, debug prints, commented-out code, leftover instrumentation, loosened dependency pins, secrets
+- **Test honesty** — would the new/changed tests fail if the change were reverted? The mechanical form: `scripts/revert-probe.sh "<verify-cmd>"` answers it in one command. Weakened or deleted checks are findings, not cleanup.
+
+Fix what you find, re-run step 1, then continue.
+
+## 3. Independent review, if the diff earns it
+
+Get an adversarial second opinion — the harness's built-in review command (Claude Code: `/code-review`) or the `reviewer` agent — when **any** of these hold:
+
+- Touches a public API, data migration, auth, money, or concurrency
+- Wide diff (many files, or a subsystem you did not previously know)
+- You cannot explain in one sentence why each hunk is safe
+
+Findings go back through step 1. For small well-understood diffs, step 2 suffices — do not add ceremony the diff does not need.
+
+## 4. Scope check
+
+Re-read the original request. For each part: delivered, or named as left out with the reason. Silently dropped scope is the failure mode this step exists to catch. Anything left out gets said **plainly** in the report, not buried.
+
+## 5. Lessons
+
+If the session hit a dead end, a footgun, or disproved a tempting approach — run `/retro` now, while the evidence is fresh. If unfinished work remains for a future session, `/handoff` instead.
+
+## 6. Report
+
+```
+Done: <what changed, one line>
+Proof: <verify command> → <decisive output line>
+Not covered: <what verify does not prove>
+Left out: <scope not delivered + why, or "nothing">
+```
+
+No hedging in the report: if all steps passed, state it plainly; if one did not, the task is not done and the report says what remains instead.

package/skills/done/scripts/revert-probe.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# revert-probe.sh — the mechanical form of the done-skill question "would the
+# new tests fail if the change were reverted?" (doctrine: red before green).
+# Checks <base-ref> out into a throwaway worktree, copies ONLY the test files
+# changed since <base-ref> from the working tree on top of it, and runs the
+# verify command there. The result is INVERTED: old code failing the new
+# tests is the PASS.
+#
+# Usage: revert-probe.sh "<verify-cmd>" [base-ref]    (base-ref default: HEAD)
+# Run it BEFORE committing — the fix and its new tests sit in the working
+# tree while HEAD is still the old code. For an already-committed fix, pass
+# the pre-fix ref (e.g. HEAD~1) as base-ref.
+#
+# Exit: 0 tests bite · 1 tests stay green on old code, or no changed test
+# files · 2 UNASSESSABLE (not a git repo, no commits, invalid base).
+# Pure bash + git; never touches the caller's working tree.
+set -euo pipefail
+
+VERIFY="${1:?usage: revert-probe.sh \"<verify-cmd>\" [base-ref]}"
+BASE="${2:-HEAD}"
+
+unassessable() { echo "UNASSESSABLE: $*"; exit 2; }
+
+git rev-parse --git-dir >/dev/null 2>&1 || unassessable "not a git repo"
+git rev-parse --verify HEAD >/dev/null 2>&1 || unassessable "no commits yet"
+git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null 2>&1 \
+  || unassessable "invalid base ref: ${BASE}"
+TOP="$(git rev-parse --show-toplevel 2>/dev/null)" || unassessable "no working tree (bare repo?)"
+cd "${TOP}"
+
+# test-file patterns mirror luciazero-bootstrap's detect.sh: tests-style dirs
+# plus test_*.*, *_test.*, *.test.*, *.spec.* file names
+is_test_file() {
+  case "/$1" in
+    */tests/*|*/test/*|*/spec/*|*/__tests__/*) return 0 ;;
+  esac
+  case "${1##*/}" in
+    test_*.*|*_test.*|*.test.*|*.spec.*) return 0 ;;
+  esac
+  return 1
+}
+
+# scratch space first — the changed-file list is stored NUL-delimited in a
+# file, because git C-quotes non-ASCII/backslash names in its plain output
+# (-z emits them raw) and bash variables cannot hold NUL bytes
+TMP="$(mktemp -d)"
+WT="${TMP}/worktree"
+trap 'git worktree remove --force "${WT}" >/dev/null 2>&1 || true
+      rm -rf "${TMP}"
+      git worktree prune >/dev/null 2>&1 || true' EXIT
+
+# changed vs base (tracked) plus untracked — the two sets are disjoint —
+# filtered to test files that still exist (a deleted test cannot bite)
+TEST_LIST="${TMP}/tests"
+: > "${TEST_LIST}"
+COUNT=0
+while IFS= read -r -d '' F; do
+  [ -f "${F}" ] || continue
+  if is_test_file "${F}"; then
+    printf '%s\0' "${F}" >> "${TEST_LIST}"
+    COUNT=$((COUNT + 1))
+  fi
+done < <({ git diff --name-only -z "${BASE}" --; git ls-files --others --exclude-standard -z; } 2>/dev/null)
+
+if [ "${COUNT}" -eq 0 ]; then
+  echo "FAIL: no test files changed since ${BASE} — the change ships without a test that bites"
+  exit 1
+fi
+
+# old code in a throwaway worktree; cleanup runs on every exit path
+git worktree add --detach "${WT}" "${BASE}" >/dev/null 2>&1 \
+  || unassessable "git worktree add failed for ${BASE}"
+
+# overlay ONLY the changed test files from the working tree
+while IFS= read -r -d '' F; do
+  mkdir -p "${WT}/$(dirname "${F}")"
+  cp "${F}" "${WT}/${F}"
+done < "${TEST_LIST}"
+
+RC=0
+OUT="$(cd "${WT}" && sh -c "${VERIFY}" 2>&1)" || RC=$?
+
+if [ "${RC}" -ne 0 ]; then
+  LAST=""
+  while IFS= read -r LINE; do
+    case "${LINE}" in *[![:space:]]*) LAST="${LINE}" ;; esac
+  done <<EOF
+${OUT}
+EOF
+  echo "PASS: regression tests bite — old code fails the new tests"
+  echo "  evidence (exit ${RC}): ${LAST:-<no output>}"
+  exit 0
+fi
+echo "FAIL: the changed tests stay green against the old code — they do not cover the change"
+exit 1

package/skills/experiment/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: experiment
+description: Measured-change protocol for performance and tuning work. Use when the task is "make it faster", "optimize", "reduce memory", "ทดลอง", when comparing two approaches, or whenever a claim like "this should be faster" is about to be made without a number. Not for correctness bugs — that is /debug.
+---
+
+# Experiment — no claim without a measurement
+
+An optimization without a baseline is a guess with confidence. The protocol is the same loop as always — but *verify* here means **measure**, and the doctrine's "never re-derive a dead end twice" means null results get recorded with the same weight as wins.
+
+## 1. Define the metric before touching code
+
+- One command that prints the number: runtime, RSS, p95 latency, binary size, query count. If no such command exists, building it is step zero (the measurement twin of "no verify command is the first bug").
+- Decide **now** what improvement would count — "worth it if ≥10% faster" — so the verdict is not negotiated after the numbers exist.
+
+## 2. Baseline
+
+- Run the measurement **at least 3 times**; record all values, not just the mean — the spread is what separates signal from noise.
+- Pin what you can: fixed seed, same input data, warm/cold state chosen deliberately, machine as quiet as you can get it. Note what you could not pin.
+- Correctness verify must be green before and after — a fast wrong answer is not an optimization.
+
+## 3. One variable per experiment
+
+Change one thing. Two changes in one measurement produce a number that explains neither. (Same discipline as `/debug`; same reason.)
+
+## 4. Measure again
+
+- Same command, same repetitions, same conditions.
+- The difference counts only if it clearly beats the baseline spread. Inside the noise = **null result**, not "slightly faster".
+
+## 5. Verdict and record
+
+Append to `docs/experiments.md` (create it if absent; follow the repo's existing log if one exists):
+
+```
+## <date> — <hypothesis, one line>
+change: <what was changed, file/approach>
+baseline: <values> | result: <values>
+verdict: WIN <n%> | NULL (inside noise) | LOSS
+decision: <kept / reverted> — <one-line reason>
+```
+
+- **Losers and nulls are reverted immediately** — the log keeps the knowledge, the tree keeps only wins.
+- A null result is a finding: "tried X, no measurable gain — do not retry without new evidence" saves the next session the same hour. If it is load-bearing, surface it via `/retro` into the project notes too.
+- Never delete a previous entry; if a new experiment overturns an old one, add the new entry and cross-reference.

package/skills/handoff/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: handoff
+description: Write a state capsule so the next session — or a different agent/harness — can resume unfinished work without re-deriving context. Use when a session is ending with work incomplete, when the user says "handoff", "pack up", "ส่งต่อ", "continue tomorrow", when switching between Claude Code and Codex mid-task, or when context is about to be compacted away on a long task.
+---
+
+# Handoff — state that survives the session
+
+`/retro` records **permanent lessons**; this records **transient state**. A good capsule lets a stranger (including future-you with zero context) type one command and be productive in two minutes. A stale capsule is worse than none — so capsules are consumed and deleted, never accumulated.
+
+## 1. Write the capsule
+
+Create `HANDOFF.md` at the repo root:
+
+```markdown
+# Handoff — <date>
+
+## Goal
+<the original request, one paragraph, verbatim enough to re-anchor>
+
+## State
+- Done: <what is finished, and the verify evidence: command → decisive line>
+- In progress: <the exact piece mid-flight, and which files hold it>
+- Verify: <the command(s) to run, fast and full tier>
+
+## Next step
+<ONE literal command or edit to do first — not a theme, an action>
+
+## Open hypotheses
+- H1: <suspected cause / approach> — status: <untested | supported by X | refuted by Y>
+
+## Landmines
+- <thing that looks safe but is not, discovered this session>
+```
+
+Rules:
+
+- **The next step is literal.** "Continue the refactor" is not a next step; "run `pytest tests/test_auth.py -k refresh` — it is the failing one" is.
+- **State only what this session knows.** No aspirations, no backlog — that belongs in the issue tracker.
+- **Refuted hypotheses stay in the capsule** — they are exactly what the next session would otherwise waste an hour re-deriving. If a lesson is permanent (true beyond this task), it also goes through `/retro`.
+- Uncommitted changes: say so explicitly, and name the files. The capsule must not imply a clean tree that is not clean.
+
+## 2. Route it
+
+- **Same machine, next session** — `HANDOFF.md` in the repo root is enough. Do not commit it.
+- **Cross-machine or another person/agent** — commit it on the working branch (it travels with the code), and say in the final message that it exists.
+- The project's notes file does **not** get the capsule — notes are permanent, capsules are transient. A one-line pointer is fine if the repo's convention wants one.
+
+## 3. Consume protocol (for the reader)
+
+A session that finds `HANDOFF.md`:
+
+1. Read it **before** touching the code.
+2. Run the Verify command(s) to confirm the described state is still true — the capsule describes the past; the tree is the truth.
+3. **Delete the capsule** (or `git rm` on the branch) once absorbed. Never leave a consumed capsule to go stale; never update one incrementally across many sessions — write a fresh one at each handoff.
+
+If the capsule and the tree disagree, trust the tree and say so.