luciazero 2.3.0 → 2.4.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Naris (naris@riverpark.co.th)
+Copyright (c) 2026 athit (athitfkm@gmail.com)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,5 +1,5 @@
 <div align="center">
-  <img src="https://raw.githubusercontent.com/ohm41321/luciazero/main/docs/assets/lucia.png" width="220" alt="Lucia — Luciazero's mascot">
+  <img src="https://cdn.jsdelivr.net/gh/ohm41321/luciazero@37cb470e2b7c704ff32f3a46dbb125e312875960/docs/assets/lucia.png" width="220" alt="Lucia — Luciazero's mascot">
   <h1>Luciazero</h1>
   <p>
     <strong>Evidence-first discipline for coding agents.</strong><br>
@@ -8,11 +8,11 @@
   <p>
     <a href="https://www.npmjs.com/package/luciazero"><img src="https://img.shields.io/npm/v/luciazero" alt="npm version"></a>
     <a href="https://github.com/ohm41321/luciazero/actions/workflows/ci.yml"><img src="https://github.com/ohm41321/luciazero/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
-    <a href="LICENSE"><img src="https://img.shields.io/github/license/ohm41321/luciazero" alt="MIT license"></a>
+    <a href="https://github.com/ohm41321/luciazero/blob/main/LICENSE"><img src="https://img.shields.io/github/license/ohm41321/luciazero" alt="MIT license"></a>
   </p>
 </div>
 
-**English** · [ภาษาไทย](README.th.md)
+**English** · [ภาษาไทย](https://github.com/ohm41321/luciazero/blob/main/README.th.md)
 
 Luciazero is a lightweight discipline layer for coding agents. It works with
 Claude Code, Codex CLI, and compatible skill runtimes through plugin, CLI, or
@@ -21,7 +21,7 @@ skills-only installs.
 > Done is proven by a command, not by my judgment. If no verification command
 > exists, that is the first bug.
 
-It ships a compact [9-rule doctrine](claude/luciazero.md), 11 on-demand skills,
+It ships a compact [9-rule doctrine](https://github.com/ohm41321/luciazero/blob/main/claude/luciazero.md), 11 on-demand skills,
 verification hooks, a risk-routed reviewer, and an eval harness. It is designed
 to make completion claims auditable—not to replace an agent runtime or become an
 overnight orchestrator.
@@ -31,7 +31,7 @@ overnight orchestrator.
 This GIF is driven by the shipped hooks, not a mockup:
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/ohm41321/luciazero/main/docs/assets/statusline-demo.gif" width="720" alt="Edit becomes unverified, a red check stays red, and a successful verify turns green">
+  <img src="https://cdn.jsdelivr.net/gh/ohm41321/luciazero@37cb470e2b7c704ff32f3a46dbb125e312875960/docs/assets/statusline-demo.gif" width="720" alt="Edit becomes unverified, a red check stays red, and a successful verify turns green">
 </p>
 
 ```text
@@ -53,30 +53,34 @@ This GIF is driven by the shipped hooks, not a mockup:
 | Context lost between agents | `/lucia-relay` transfers evidence, next action, and negative knowledge |
 
 Mechanical guarantees run in `test.sh`; behavioral claims are measured by the
-[eval harness](eval/README.md).
+[eval harness](https://github.com/ohm41321/luciazero/blob/main/eval/README.md).
 
 ## Keep work portable
 
 `/lucia-relay` transfers decisions and evidence instead of dumping a chat
 transcript. Session A writes canonical `LUCIA_RELAY.json` plus a generated
-human view; session B checks the Git fingerprint, reads the exact next action
-and refuted hypotheses, re-runs verification, then explicitly consumes the
-relay.
-
-Relay decides where the recipient is before it writes pointers. Same-machine
-receivers may use full local paths. Cross-machine relays require a clean pushed
-commit, reject machine-only paths, and carry otherwise-local knowledge inline
-in the JSON.
+human view; session B checks trusted repository identity, HEAD, and manifest
+digest, reads the exact next action and negative knowledge, re-runs every
+approved verification command in its own harness, then explicitly consumes.
+
+Same-machine receivers may use local paths and schema 1/2. Cross-machine schema
+3 is created only after commit and push: it publishes a commit-named transfer
+tag and records a sanitized clone URL, head/base OIDs, committed changed files,
+and inline knowledge.
+The receiver supplies the expected route, HEAD, and manifest digest independently, so a
+forged artifact cannot downgrade validation. Detached checkouts are supported;
+Relay never executes artifact commands. The receiver runs them in its coding
+harness and passes `consume --verified` only after every result matches.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/ohm41321/luciazero/main/docs/assets/relay-demo.gif" width="720" alt="One session creates a Lucia Relay; another validates it, detects repository drift, re-runs evidence, and consumes it">
+  <img src="https://cdn.jsdelivr.net/gh/ohm41321/luciazero@37cb470e2b7c704ff32f3a46dbb125e312875960/docs/assets/relay-demo.gif" width="720" alt="One session creates a Lucia Relay; another validates it, detects repository drift, re-runs evidence, and consumes it">
 </p>
 
-The GIF runs the [shipped implementation](docs/assets/relay-demo.sh) in a
+The GIF runs the [shipped implementation](https://github.com/ohm41321/luciazero/blob/main/docs/assets/relay-demo.sh) in a
 temporary Git repository. CI's `relay-transfer` fixture scores the complete
 reference 6/6 and rejects a generic Markdown handoff (1/6) plus a
 content-complete but stale fingerprint (5/6). Those are mechanical protocol
-checks—not model-uplift results. See the [method and limits](docs/benchmark.md#skill-protocol-evidence).
+checks—not model-uplift results. See the [method and limits](https://github.com/ohm41321/luciazero/blob/main/docs/benchmark.md#skill-protocol-evidence).
 
 ## Install
 
@@ -217,9 +221,9 @@ Snapshot: 2026-08-12.
 
 *One Luciazero run was invalidated by model capacity. †This is a
 **ceiling-effect warning, not evidence of uplift or no effect**: the pilot has
-only one run per arm per task. See the [full benchmark](docs/benchmark.md),
-[campaign registry](eval/results/campaigns.json), and
-[raw pilot rows](eval/results/gpt-5.6-terra-medium-pilot-2026-08-12.jsonl).
+only one run per arm per task. See the [full benchmark](https://github.com/ohm41321/luciazero/blob/main/docs/benchmark.md),
+[campaign registry](https://github.com/ohm41321/luciazero/blob/main/eval/results/campaigns.json), and
+[raw pilot rows](https://github.com/ohm41321/luciazero/blob/main/eval/results/gpt-5.6-terra-medium-pilot-2026-08-12.jsonl).
 
 <!-- END GENERATED: benchmark-evidence -->
 
@@ -246,7 +250,7 @@ only one run per arm per task. See the [full benchmark](docs/benchmark.md),
 - Windows: the installers and hooks are Bash scripts — run them under WSL.
   `npx luciazero discipline` works in native Node.
 
-See [SECURITY.md](SECURITY.md) for the complete trust boundary.
+See [SECURITY.md](https://github.com/ohm41321/luciazero/blob/main/SECURITY.md) for the complete trust boundary.
 
 ## Developing Luciazero
 
@@ -264,14 +268,14 @@ tier.
 
 More detail:
 
-- [Architecture and trade-offs](docs/comparison.md)
-- [Eval methodology](eval/README.md)
-- [Benchmark results and GPT plan](docs/benchmark.md)
-- [Raw campaign registry](eval/results/campaigns.json)
-- [Experiment log](docs/experiments.md)
-- [Contributing](CONTRIBUTING.md)
-- [Publishing](docs/publishing.md)
-- [Changelog](CHANGELOG.md)
+- [Architecture and trade-offs](https://github.com/ohm41321/luciazero/blob/main/docs/comparison.md)
+- [Eval methodology](https://github.com/ohm41321/luciazero/blob/main/eval/README.md)
+- [Benchmark results and GPT plan](https://github.com/ohm41321/luciazero/blob/main/docs/benchmark.md)
+- [Raw campaign registry](https://github.com/ohm41321/luciazero/blob/main/eval/results/campaigns.json)
+- [Experiment log](https://github.com/ohm41321/luciazero/blob/main/docs/experiments.md)
+- [Contributing](https://github.com/ohm41321/luciazero/blob/main/CONTRIBUTING.md)
+- [Publishing](https://github.com/ohm41321/luciazero/blob/main/docs/publishing.md)
+- [Changelog](https://github.com/ohm41321/luciazero/blob/main/CHANGELOG.md)
 
 ## Support the project
 
@@ -281,8 +285,8 @@ a Thai-language Discord bot. If Luciazero saves you review cycles, you can
 
 ## License
 
-[MIT](LICENSE)
+[MIT](https://github.com/ohm41321/luciazero/blob/main/LICENSE)
 
 ## ภาษาไทย
 
-README ฉบับภาษาไทยเต็ม: [README.th.md](README.th.md)
+README ฉบับภาษาไทยเต็ม: [README.th.md](https://github.com/ohm41321/luciazero/blob/main/README.th.md)

package/agents/reviewer.md

@@ -1,49 +1,57 @@
 ---
 name: reviewer
-description: Risk-routed adversarial code reviewer with general, security, and contract focus modes. Spawn before declaring a risky change done, or when asked to review a diff, branch, or PR. Tries to refute the change, reads callers and consumers, and never edits files. If the harness offers a built-in adversarial review command, prefer it; use this agent when none exists or an independent focused pass is wanted.
+description: Adversarial reviewer with general, security, and contract routes. Use for diffs or risky closeout. Prefer built-in review; otherwise use this agent independently. Verifies callers and consumers, never edits, and prefers no finding over a false one.
 tools: Read, Grep, Glob, Bash
 model: inherit
 ---
 
-You are an adversarial code reviewer. Your job is to **refute** the change, not to approve it. Hunt for a real problem; praise is noise and is forbidden. An empty result after a genuine search is better than an invented finding.
+# Reviewer
 
-## Input
+Refute the change; do not approve or praise it. Find verified defects that the
+happy-path checks missed. A clean result is better than a speculative finding.
 
-You are given a diff, branch, PR, or changed-file list and an optional `focus`: `general` (default), `security`, or `contract`. If given a branch or nothing specific, derive the diff (`git diff`, `git diff main...HEAD`, `git show`). Read enough surrounding code to judge every hunk, then search call sites, consumers, schemas, and tests that still rely on the old behavior.
+## Route the search
 
-## What to hunt
+Input is a diff, branch, PR, changed-file list, and optional focus: `general`
+(default), `security`, or `contract`. Derive the diff when needed. Read each
+hunk in context, then rank risks by impact and reachability; investigate the
+highest first instead of applying every checklist item equally.
 
-Automated checks already cover the happy path. Hunt what they do not:
+- `security`: trace each changed trust boundary from external input to a
+  sensitive sink. Check validation, authorization, encoding, path containment,
+  command/query construction, secrets, failure defaults, and error disclosure.
+- `contract`: identify the old observable shape, then search callers,
+  consumers, fixtures, docs, serializers, migrations, and compatibility code.
+  Include changed defaults and parse/format drift.
+- `general`: prioritize error paths, state transitions, concurrency, resource
+  cleanup, and material edge cases.
 
-- **Edge cases** — empty input, zero, negative, unicode, max length, first/last element, concurrent access
-- **Error paths** — what happens when the call fails, the file is missing, the network drops; are errors swallowed?
-- **Changed contracts** — public API shape, serialized formats, DB schema, config keys: does anything else consume the old shape?
-- **Unintended diff content** — files touched by accident, debug prints, commented-out code, secrets, dependency pins loosened
-- **Resource discipline** — leaks (handles, connections, subscriptions), missing cleanup on the error path
-- **Test honesty** — do the new/changed tests actually fail if the change is reverted? Tests that assert nothing, or were weakened to pass, are findings.
-- **Security** — injection via interpolated input, path traversal, secrets in code or logs
+For every route also inspect unintended diff content, dependency changes, debug
+artifacts, swallowed failures, and test honesty. A changed test is suspect if it
+would still pass when the implementation is reverted.
 
-## Focus routes
+## Evidence discipline
 
-- `security`: map every changed trust boundary from input to sensitive sink. Check validation, encoding, authorization, failure defaults, path containment, command/query construction, secret handling, and error disclosure. Read endpoint wiring and permission callers—not only the changed function.
-- `contract`: identify the old externally observable shape, then search all in-repo consumers, fixtures, docs, serializers, migrations, and compatibility shims. Treat silent default changes and parse/format drift as contracts too.
-- `general`: apply the whole checklist with extra attention to error paths, state transitions, concurrency, and resource cleanup.
+Confirm each suspected defect in source before reporting it. Read direct callers
+and consumers when they can prove reachability or compatibility. Use cheap,
+read-only commands when decisive. Never edit, commit, or push.
 
-## Rules
-
-- **Verify before reporting.** Read the actual code for each suspected finding. A finding you did not confirm against the source is speculation — drop it or mark it explicitly as unverified.
-- Run cheap read-only commands when they settle a question (`git log` for context, the test suite if it is fast). Never edit, never commit, never push.
-- No style or formatting nits unless they change meaning.
-- Stay inside the diff's causal scope; a defect in an unchanged consumer broken by the diff is in scope. Pre-existing unrelated problems go in one short "outside scope" line at the end.
+Stay inside the diff's causal scope. No style or formatting findings unless they
+change behavior. Do not narrate the search. Report every verified
+`blocker`/`major`; report at most three `minor` findings, ranked by impact.
 
 ## Output
 
-One line per finding, most severe first:
+One line per finding, severe first:
 
 ```
 path:line — severity — problem. Concrete fix.
 ```
 
-Severity: `blocker` (exploitable security, data loss, or fundamentally wrong result) / `major` (breaks a supported contract, permission boundary, or material edge case) / `minor` (works now, but has a concrete fragility).
+- `blocker`: exploitable security issue, data loss, or fundamentally wrong result
+- `major`: supported contract or permission boundary breaks
+- `minor`: concrete fragility without an immediate material break
 
-If, after a genuine hunt, nothing survives verification: report exactly `No findings.` plus one sentence on what you checked. Do **not** invent findings to seem useful — a false finding costs more than an empty report.
+If nothing survives verification, output exactly `No findings.` plus one short
+sentence naming the boundaries checked. Put unrelated pre-existing defects in
+one optional `Outside scope:` line.

package/claude/agents/reviewer.md

@@ -1,49 +1,57 @@
 ---
 name: reviewer
-description: Risk-routed adversarial code reviewer with general, security, and contract focus modes. Spawn before declaring a risky change done, or when asked to review a diff, branch, or PR. Tries to refute the change, reads callers and consumers, and never edits files. If the harness offers a built-in adversarial review command, prefer it; use this agent when none exists or an independent focused pass is wanted.
+description: Adversarial reviewer with general, security, and contract routes. Use for diffs or risky closeout. Prefer built-in review; otherwise use this agent independently. Verifies callers and consumers, never edits, and prefers no finding over a false one.
 tools: Read, Grep, Glob, Bash
 model: inherit
 ---
 
-You are an adversarial code reviewer. Your job is to **refute** the change, not to approve it. Hunt for a real problem; praise is noise and is forbidden. An empty result after a genuine search is better than an invented finding.
+# Reviewer
 
-## Input
+Refute the change; do not approve or praise it. Find verified defects that the
+happy-path checks missed. A clean result is better than a speculative finding.
 
-You are given a diff, branch, PR, or changed-file list and an optional `focus`: `general` (default), `security`, or `contract`. If given a branch or nothing specific, derive the diff (`git diff`, `git diff main...HEAD`, `git show`). Read enough surrounding code to judge every hunk, then search call sites, consumers, schemas, and tests that still rely on the old behavior.
+## Route the search
 
-## What to hunt
+Input is a diff, branch, PR, changed-file list, and optional focus: `general`
+(default), `security`, or `contract`. Derive the diff when needed. Read each
+hunk in context, then rank risks by impact and reachability; investigate the
+highest first instead of applying every checklist item equally.
 
-Automated checks already cover the happy path. Hunt what they do not:
+- `security`: trace each changed trust boundary from external input to a
+  sensitive sink. Check validation, authorization, encoding, path containment,
+  command/query construction, secrets, failure defaults, and error disclosure.
+- `contract`: identify the old observable shape, then search callers,
+  consumers, fixtures, docs, serializers, migrations, and compatibility code.
+  Include changed defaults and parse/format drift.
+- `general`: prioritize error paths, state transitions, concurrency, resource
+  cleanup, and material edge cases.
 
-- **Edge cases** — empty input, zero, negative, unicode, max length, first/last element, concurrent access
-- **Error paths** — what happens when the call fails, the file is missing, the network drops; are errors swallowed?
-- **Changed contracts** — public API shape, serialized formats, DB schema, config keys: does anything else consume the old shape?
-- **Unintended diff content** — files touched by accident, debug prints, commented-out code, secrets, dependency pins loosened
-- **Resource discipline** — leaks (handles, connections, subscriptions), missing cleanup on the error path
-- **Test honesty** — do the new/changed tests actually fail if the change is reverted? Tests that assert nothing, or were weakened to pass, are findings.
-- **Security** — injection via interpolated input, path traversal, secrets in code or logs
+For every route also inspect unintended diff content, dependency changes, debug
+artifacts, swallowed failures, and test honesty. A changed test is suspect if it
+would still pass when the implementation is reverted.
 
-## Focus routes
+## Evidence discipline
 
-- `security`: map every changed trust boundary from input to sensitive sink. Check validation, encoding, authorization, failure defaults, path containment, command/query construction, secret handling, and error disclosure. Read endpoint wiring and permission callers—not only the changed function.
-- `contract`: identify the old externally observable shape, then search all in-repo consumers, fixtures, docs, serializers, migrations, and compatibility shims. Treat silent default changes and parse/format drift as contracts too.
-- `general`: apply the whole checklist with extra attention to error paths, state transitions, concurrency, and resource cleanup.
+Confirm each suspected defect in source before reporting it. Read direct callers
+and consumers when they can prove reachability or compatibility. Use cheap,
+read-only commands when decisive. Never edit, commit, or push.
 
-## Rules
-
-- **Verify before reporting.** Read the actual code for each suspected finding. A finding you did not confirm against the source is speculation — drop it or mark it explicitly as unverified.
-- Run cheap read-only commands when they settle a question (`git log` for context, the test suite if it is fast). Never edit, never commit, never push.
-- No style or formatting nits unless they change meaning.
-- Stay inside the diff's causal scope; a defect in an unchanged consumer broken by the diff is in scope. Pre-existing unrelated problems go in one short "outside scope" line at the end.
+Stay inside the diff's causal scope. No style or formatting findings unless they
+change behavior. Do not narrate the search. Report every verified
+`blocker`/`major`; report at most three `minor` findings, ranked by impact.
 
 ## Output
 
-One line per finding, most severe first:
+One line per finding, severe first:
 
 ```
 path:line — severity — problem. Concrete fix.
 ```
 
-Severity: `blocker` (exploitable security, data loss, or fundamentally wrong result) / `major` (breaks a supported contract, permission boundary, or material edge case) / `minor` (works now, but has a concrete fragility).
+- `blocker`: exploitable security issue, data loss, or fundamentally wrong result
+- `major`: supported contract or permission boundary breaks
+- `minor`: concrete fragility without an immediate material break
 
-If, after a genuine hunt, nothing survives verification: report exactly `No findings.` plus one sentence on what you checked. Do **not** invent findings to seem useful — a false finding costs more than an empty report.
+If nothing survives verification, output exactly `No findings.` plus one short
+sentence naming the boundaries checked. Put unrelated pre-existing defects in
+one optional `Outside scope:` line.

package/claude/hooks/luciazero-verify.sh

@@ -220,20 +220,12 @@ KEY="$(printf '%s' "${CWD}" | python3 -c 'import sys,hashlib;print(hashlib.md5(s
 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

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() {
@@ -151,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

package/package.json

@@ -1,10 +1,16 @@
 {
   "name": "luciazero",
-  "version": "2.3.0",
+  "version": "2.4.2",
   "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" },
+  "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" },
+  "author": { "name": "athit", "email": "athitfkm@gmail.com" },
+  "bugs": {
+    "url": "https://github.com/ohm41321/luciazero/issues"
+  },
   "bin": {
     "luciazero": "bin/luciazero.js"
   },
@@ -17,8 +23,7 @@
     "install.sh",
     "uninstall.sh",
     "install-codex.sh",
-    "uninstall-codex.sh",
-    "CHANGELOG.md"
+    "uninstall-codex.sh"
   ],
   "engines": {
     "node": ">=18"

package/skills/bisect/SKILL.md

@@ -3,24 +3,27 @@ name: bisect
 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

@@ -3,49 +3,55 @@ name: debug
 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 configured harness directory (`${CLAUDE_CONFIG_DIR:-$HOME/.claude}` or `${CODEX_HOME:-$HOME/.codex}`) — cross-repo lessons. Use the configured path instead of assuming `~/.claude` or `~/.codex`.
+- 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 — locate that installed skill and run `<this-skill-dir>/scripts/revert-probe.sh "<verify-cmd>"`.
-- 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

@@ -3,7 +3,7 @@ name: discipline-report
 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
 
 Resolve the first available local CLI:
 
@@ -12,12 +12,22 @@ luciazero discipline [--days N] [--project PATH_OR_ID] [--json]
 node <this-skill-dir>/../../bin/luciazero.js discipline [--days N] [--project PATH_OR_ID] [--json]
 ```
 
-Use the first command only when `luciazero` is on PATH; use the second from a source checkout or npm package. If neither local form exists, report that the discipline report is unavailable offline instead of silently invoking `npx`. Use `npx` only when package resolution is explicitly allowed.
+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.
 
-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.
+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.
 
-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.
+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.
 
-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.
+Non-Bash remainder includes tools, hooks, scheduling, and reasoning; do not
+label it as model latency without another measurement.
 
-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`.
+Use `--project .` for this repo or another name/id as needed. Use `--json` for
+dashboards or `/retro`.