luciazero 1.5.0 → 2.0.0

package/CHANGELOG.md

@@ -7,18 +7,165 @@ Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
-## [1.5.0] - 2026-08-10
+## [2.0.0] - 2026-08-13
 
 ### Changed
 
-- **Project renamed to Luciazero** (from "lucidone", hours after 1.4.1, before
-  any adoption) — the mascot's name belongs in the project's name, and
-  Lucia + exit 0 says what the doctrine means by done. Every identifier moved:
-  files, `LUCIAZERO_*` env vars, hooks, markers, sidecars, npm/plugin names.
-  Versions 1.4.0–1.4.1 shipped to npm as `lucidone` and were unpublished
-  within npm's 72-hour window; GitHub tags v1.4.0/v1.4.1 keep the old-name
-  trees for the record. Earlier CHANGELOG entries read with the new name
-  applied retroactively.
+- The canonical Sonnet result is explicitly preliminary (`+31pp`, n=4–5).
+  The historical `+37pp` statement is retired because its eight replacement
+  raw rows could not be recovered.
+- `eval/report.sh` rejects mixed campaigns/commits/seeds, changed fixture
+  hashes, duplicate invocation IDs, and inconsistent pair order. Published
+  evidence also enforces registered task/arm/row/invalid/model expectations,
+  and discloses Haiku's incomplete per-row model provenance.
+- Eval tasks may provide deterministic offline setup before either arm. Provider
+  transcripts now live outside worked trees so they cannot alter Git status,
+  repository fingerprints, or final-tree grading.
+- Relay fingerprints encode untracked special files without opening them, so a
+  FIFO, socket, or device cannot block inspection or trigger device I/O.
+- GitHub workflows use the Node 24-based `actions/checkout@v5` and
+  `actions/setup-node@v5` runtimes.
+- **Breaking: `/handoff` is now `/lucia-relay`.** The branded name avoids
+  collisions with generic handoff skills. Installs remove an untouched v1.5
+  copy but preserve and warn about customized copies. Relay state is now a
+  validated `LUCIA_RELAY.json` manifest plus a generated human view, with a
+  repository fingerprint, verification evidence, negative knowledge,
+  cross-session/cross-agent routing, drift inspection, and explicit consume.
+- **Risk-routed review.** The single portable reviewer now accepts `general`,
+  `security`, and `contract` focus modes, reads callers/consumers, and uses one
+  blocker/major/minor policy. `/done` requests separate focused passes when a
+  diff crosses both security and contract boundaries.
+- **Smart verification is repo-owned.** Monorepos create `verify-changed` from
+  their native task graph and keep `verify-full` for closeout. The global hook
+  never guesses dependency impact from path prefixes.
+- **Classic and Codex installs track component ownership.** Exact hidden
+  snapshots distinguish Luciazero-managed skills/agents from same-name user or
+  third-party components. Updates back up collisions/customizations, and
+  uninstall removes only an unchanged managed copy.
+
+### Added
+
+- Auditable benchmark evidence: canonical Claude raw JSONL, a SHA-256 campaign
+  registry, generated README/benchmark tables, and a CI drift check.
+- Result schema 2 records campaign, pair, invocation, repository, fixture,
+  prompt, platform, and arm-order metadata. Seeded arm randomization reduces
+  fixed-order bias without making campaigns irreproducible.
+- Strict shared result validation rejects unsupported schemas and mistyped
+  booleans, criteria, metrics, timestamps, platform, and campaign metadata.
+  Output-aware `--resume` fills interrupted pairs without rerunning completed
+  invocation IDs; `--run-offset` extends completed batches.
+- Three zero-quota candidate eval tasks cover archive extraction security,
+  lossless atomic schema migration, and multi-page cursor integration. Each
+  grader proves reference/project/anti-gamed behavior offline.
+- **`relay-transfer` protocol eval** grades portable state, an exact next edit,
+  verification evidence, negative knowledge, scope preservation, and a current
+  repository fingerprint. CI proves its 6/6 reference and rejects generic
+  prose plus a content-complete stale relay without spending model quota.
+- **Lucia Relay demo** drives the shipped producer/receiver implementation in
+  a temporary Git repository: render, validate, detect drift, re-run evidence,
+  and explicitly consume. The checked-in GIF is generated from the same script
+  exercised by CI.
+- **Central component catalogs** drive classic/Codex install, status,
+  uninstall, and inventory tests, so a new skill or agent cannot silently ship
+  through only one channel.
+- **`/plan`** defines falsifiable acceptance signals and reversible steps,
+  while pausing for approval only on ambiguity, high stakes, destructive work,
+  public-contract choices, or scope changes.
+- **`/bisect` + `safe-bisect.sh`** locate the first bad commit in a detached
+  temporary worktree, repeat endpoints to catch flakes, preserve exit 125
+  skips, distinguish missing commands, and clean every exit path.
+- **`npx luciazero discipline` + `/discipline-report`** analyze schema-v2
+  local JSONL outcomes with day/project filters and JSON output. The hook logs
+  a privacy-preserving project hash and verify mode; legacy records remain
+  readable and recommendations distinguish observations from likely causes.
+- **`/lucia-relay` carries memory pointers** — the `Read first`
+  section quotes the `docs/lessons.md` entries relevant to the unfinished
+  work (a selection, never a copy — the ledger travels with the repo) and
+  copies applicable machine-local `luciazero-heuristics.md` entries
+  verbatim, since the relay is the only way those cross machines. The
+  consume protocol tells the reader to follow the pointers before touching
+  code and to adopt carried heuristics that earn their keep.
+
+- **`eval/run.sh --use-login`** — run the real eval on an existing Claude
+  subscription (Pro/Max) instead of API dollars: seeds each per-run sandbox
+  config dir with this machine's login state — `~/.claude.json`, plus
+  OAuth tokens from `.credentials.json` (Linux) or a Keychain export
+  (macOS). The copy lives only inside the mktemp sandbox and is deleted
+  with it. Fail-soft by
+  design: if the seed does not authenticate, `check-result.sh` marks the
+  arm INVALID and nothing is spent. Plumbing (seed per arm, warn on missing
+  login state) is proven offline in `test.sh`.
+
+- **`eval/check-result.sh`** — a zero exit code no longer proves the agent
+  ran: the CLI has wrapped a `Not logged in` error in subtype `"success"`
+  (observed 2026-08-11, caught free by a 1-run smoke). The guard inspects
+  the result payload (`is_error`, `terminal_reason: api_error`, login
+  errors) and `run.sh` books a refuted arm as INVALID with the reason
+  quoted; every accept/reject path is fixture-proven in `test.sh`.
+- **`eval/run.sh --offline`** — synthetic smoke mode: no `claude` CLI, no
+  API key, zero cost. Doctrine-style arms get the task's `reference/` tree,
+  bare keeps the planted bug, and the whole copy → grade → JSONL → report
+  loop runs in seconds. Rows are branded `"offline": true` and `report.sh`
+  prints a SYNTHETIC banner so the numbers can never pass as behavioral
+  results; end-to-end proven in `test.sh` plus a frozen fixture pair.
+- **README narrative reorder** (EN + TH): the demo GIF and the
+  "What it prevents" table now sit directly under the intro, before
+  Install — a newcomer sees what the pack does in 30 seconds before being
+  asked to install anything.
+
+- **README demo GIF** — 15 seconds of the enforcement pack's real behavior:
+  edit → `✎ unverified`, stop attempt → the rule-1 nudge, red verify →
+  `❌ verify RED`, fix → `✅ verify`. Recorded from the checked-in
+  `docs/assets/statusline-demo.sh`, which drives the shipped hooks in a
+  sandbox (so the GIF cannot drift from what the scripts actually print),
+  via the checked-in `docs/assets/demo.tape` (`vhs`). The driver script is
+  under `test.sh`'s shellcheck net.
+
+- **`false-green` eval task** (sixth): the false-done trap — the shipped
+  suite is green from the start while the CSV escaping bug lives outside
+  its coverage. The untouched tree *passes its own tests* and still fails
+  the grader (symptom probed on unseen data; bug-restored suite must go
+  red), which is doctrine rule 1 stated as a fixture. `gamed/` (comma-only
+  half fix) and `gamed-notest/` (correct fix, no test added) are rejected.
+- **`--with-lessons` eval arm** — `eval/run.sh --with-lessons` runs a third
+  arm for tasks that ship a `lessons.md` (currently `pipeline` and
+  `false-green`): doctrine install plus the task's ledger pre-seeded as
+  `docs/lessons.md`, the A/B/C comparison that measures whether the
+  learning layer pays. `report.sh` discovers arm columns from the data and
+  renders per-arm deltas; frozen three-arm fixture added to `test.sh`.
+- **Per-run resource accounting** — `run.sh --out` now records duration,
+  token usage, and cost per run (parsed fail-open from the CLI's
+  `--output-format json` result), and `report.sh` appends per-arm resource
+  means whenever the data is present — a pass-rate delta is only a win if
+  the cost next to it says so.
+- **Community eval issue templates** — `Evaluation result` (report.sh
+  output required, null results explicitly welcome) and `New eval task`
+  (asks for the doctrine rule probed and the gamed tree that would cheat
+  the grader).
+
+- **`merge-conflict` eval task** (fifth): an unresolved merge where main's
+  bulk discount and the branch's member discount must both survive. The
+  grader probes each feature on data the shipped tests never mention, and
+  swaps in one-sided feature mutants to prove the worked tests actually
+  cover both sides — `gamed/` (HEAD-only resolution, suite green) and
+  `gamed-notests/` (correct merge, no tests added) are both rejected.
+- **Machine-readable closeout evidence** — `/done` step 6 now mirrors the
+  report as a JSON block (status, verify command + exit code + decisive
+  line, not-covered, left-out) when the result feeds CI, a PR comment, or a
+  dashboard.
+- **README "What it prevents" section** (EN + TH): failure modes mapped to
+  the shipped mechanism that catches each — no promise without a mechanism.
+- **SECURITY.md** — private reporting channel plus the enforced design
+  guarantees (no network, no npm lifecycle scripts, fail-open hooks,
+  config-dir-only writes) and the documented strict-mode env sharp edge.
+- **GitHub issue templates** — bug report (channel + decisive-output
+  evidence required), feature request (doctrine-fit question), security
+  contact link.
+
+## [1.5.0] - 2026-08-10
+
+First version published to npm (`luciazero`); 1.4.x and below were
+development versions.
 
 ### Added
 

package/README.md

@@ -7,208 +7,202 @@
 [![license](https://img.shields.io/github/license/ohm41321/luciazero)](LICENSE)
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/ohm41321/luciazero/main/docs/assets/lucia.png" width="300" alt="Lucia — Luciazero's mascot — hugging her cat plushie">
+  <img src="https://raw.githubusercontent.com/ohm41321/luciazero/main/docs/assets/lucia.png" width="280" alt="Lucia — Luciazero's mascot">
 </p>
 
-Luciazero makes a coding agent run its own `plan → change → verify → fix` loop instead of handing back unverified work. Its first rule is not about prompting:
+Luciazero makes coding agents run a `plan → change → verify → fix` loop instead
+of handing back work they merely believe is finished.
 
-> Done is proven by a command, not by my judgment. If no verification command exists, that is the first bug.
+> Done is proven by a command, not by my judgment. If no verification command
+> exists, that is the first bug.
 
-Everything in this repo — a 9-rule doctrine, six skills, an adversarial reviewer agent, enforcement hooks, an eval harness — exists to make that rule hold without a human in the loop.
+It ships a compact [9-rule doctrine](claude/luciazero.md), 9 on-demand skills,
+verification hooks, a risk-routed reviewer, and an eval harness. It is a
+discipline layer, not an agent runtime or overnight orchestrator.
 
-## Install
-
-**Claude Code — plugin (recommended).** One install carries the six skills, the `reviewer` agent, the verify-tracking hooks, and the doctrine:
-
-```
-/plugin marketplace add ohm41321/luciazero
-/plugin install luciazero@luciazero
-```
-
-Then run `/luciazero:luciazero-bootstrap` in any repository (plugin skills are namespaced: `/luciazero:done`, `/luciazero:debug`, …). Honest print: installing the plugin is what enables its hooks — that install step *is* the opt-in; the doctrine loads via a `SessionStart` hook because plugins cannot add a `CLAUDE.md` import line (same word-ceiling-capped text, and it stays silent when a classic install exists, so it never loads twice); and there is no statusline, because Claude Code does not let plugins set `statusLine`.
+## See it in 15 seconds
 
-**Any agent — skills only.** Via [vercel-labs/skills](https://github.com/vercel-labs/skills), into Claude Code, Codex, Cursor, and 70+ others. No doctrine, no reviewer agent, no hooks:
+This GIF is driven by the shipped hooks, not a mockup:
 
-```
-npx skills add ohm41321/luciazero
-```
-
-**Classic install.** The reference channel — the only one with the statusline, the `CLAUDE.md` import, a `--status` health check, and the Codex CLI installer. Details in the next sections:
+<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">
+</p>
 
-```bash
-npx luciazero               # Claude Code   (--with-hooks for the enforcement pack, --status)
-npx luciazero codex         # Codex CLI     (npx luciazero uninstall to remove)
+```text
+✎ unverified   → edits happened after the last check
+❌ verify RED  → the latest check failed
+✅ verify 3m   → the latest check passed three minutes ago
 ```
 
-`npx luciazero` is a thin wrapper with zero lifecycle scripts — nothing runs at npm install time (`test.sh` enforces that); it just launches the same audited bash installers you would get from `git clone https://github.com/ohm41321/luciazero.git && ./install.sh`. Pick **one** channel — plugin or classic — so the hooks are never wired twice. Want proof before installing anything? `./demo.sh` scaffolds a planted-bug repo you fix in your own session and score with an offline grader.
-
-## After installing: which skill when
+## What it prevents
 
-Nothing to memorize — the doctrine and the hooks work by themselves. Skills are for specific moments, and the first move in any repository is `/luciazero-bootstrap`, once, so a verify command exists for everything else to lean on. (Plugin installs prefix the names: `/luciazero:done`, `/luciazero:debug`, …)
-
-| Moment | Skill | What it does |
-|---|---|---|
-| First time in a repository | `/luciazero-bootstrap` | Detects or creates the verify command, adds 3–6 smoke tests and a project notes file, proves the verify can actually go red |
-| A bug survives the first look | `/debug` | Deterministic reproduction, hypothesis ledger seeded from past lessons (`docs/lessons.md` + cross-repo heuristics), closes with a red-before-fix regression test |
-| About to say "done" | `/done` | Full-tier verify with the decisive line quoted, skeptic pass over the diff, `revert-probe.sh` test-honesty check, fixed report format |
-| Stopping while work is unfinished | `/handoff` | Writes the `HANDOFF.md` capsule: goal, verified state, the one literal next command |
-| "Make it faster" requests | `/experiment` | Metric and win threshold before any edit, baseline with repetitions, one variable per run, losers reverted |
-| After a hard task or a long debug | `/retro` | Routes lessons into the project's notes, the `docs/lessons.md` ledger, and cross-repo heuristics; reads the discipline stats log |
-
-The `reviewer` agent is never invoked by name — `/done` spawns it when a diff is risky enough, or ask for "an adversarial review" at any point.
-
-## What you get
-
-No dependencies, no runtime (python3 only for the opt-in enforcement pack):
+| Failure mode | Mechanism |
+|---|---|
+| “Done” without running a check | Stop-hook nudge; optional strict gate blocks a red stop |
+| `cat test.sh` counted as testing | Exact `LUCIAZERO_VERIFY_CMD` matching |
+| Tests weakened to reach green | Doctrine rule 3 + check-suppression guard |
+| New tests that pass without the fix | `revert-probe.sh` runs them against the old code |
+| Scope silently dropped | `/done` requires every item delivered or named as left out |
+| The same dead end repeated later | `/retro` records it; `/debug` reads it first |
+| Context lost between agents | `/lucia-relay` transfers evidence, next action, and negative knowledge |
 
-| Piece | Scope | Loaded |
-|---|---|---|
-| `claude/luciazero.md` | Doctrine — 9 rules | Always, every project, every session |
-| `skills/luciazero-bootstrap/` | Procedure — make a repo agent-ready (ships `scripts/detect.sh`) | On demand |
-| `skills/debug/` | Procedure — hypothesis-driven debugging | On demand |
-| `skills/done/` | Procedure — closeout ritual (ships `scripts/revert-probe.sh`) | On demand |
-| `skills/handoff/` | Procedure — state capsule for the next session/agent | On demand |
-| `skills/experiment/` | Procedure — measured-change protocol for perf work | On demand |
-| `skills/retro/` | Procedure — harvest lessons into project notes | On demand |
-| `claude/agents/reviewer.md` | Adversarial reviewer subagent | On demand (before "done") |
-| `claude/hooks/` | Enforcement pack — verify-nudge hooks, opt-in strict gate, statusline | Opt-in |
-| `eval/` | A/B harness — 4 planted-bug tasks, self-proving graders | Manual (costs API money) |
-| `demo.sh` | Two-minute demo — planted bug, your session, objective grader | Manual |
+Mechanical guarantees run in `test.sh`; behavioral claims are measured by the
+[eval harness](eval/README.md).
 
-How it stacks up against superpowers, SuperClaude, proof-loop, and the harness built-ins — including what they do better: [docs/comparison.md](docs/comparison.md).
+## Carry unfinished work across agents
 
-## What it looks like
+`/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.
 
-Actual output of the shipped scripts, not mockups. The statusline keeps the verify state on screen:
+<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">
+</p>
 
-```
-Opus | ✎ unverified          # edits made, no verify run since
-Opus | ✅ verify 3m           # last verify green, 3 minutes ago
-Opus | ❌ verify RED 40s      # last verify failed — the loop is not done
-```
+The GIF runs the [shipped implementation](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).
 
-Ending a session with unverified edits triggers the one-shot nudge:
+## Install
 
-```
-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.)
-```
+### Claude Code plugin — recommended
 
-And in opt-in strict mode, a red verify actually blocks the stop, evidence attached:
+Carries the doctrine, all skills, reviewer, and verify-tracking hooks:
 
+```text
+/plugin marketplace add ohm41321/luciazero
+/plugin install luciazero@luciazero
 ```
-Strict verify gate: './test.sh' is RED. Fix it before finishing — or say
-plainly that you are handing back a red state. Failing output:
-
-test_totals ... FAIL: expected 14, got 8
-```
-
-## Classic install & enforcement pack
 
-`./install.sh` does four things: copies `claude/luciazero.md` → `~/.claude/luciazero.md`, the six skills → `~/.claude/skills/`, the reviewer agent → `~/.claude/agents/reviewer.md` (backing up a customized copy first), and appends `@luciazero.md` to `~/.claude/CLAUDE.md`. It backs up `CLAUDE.md` before touching it, is idempotent, and never writes outside `~/.claude/`. Those four steps are also the whole manual install.
+Start a repository with `/luciazero:luciazero-bootstrap`. Plugin skills use the
+`/luciazero:` prefix. The plugin has no statusline because Claude Code plugins
+cannot set one.
 
-### Enforcement pack (opt-in)
+### Skills only — any compatible agent
 
 ```bash
-./install.sh --with-hooks    # requires python3
+npx skills add ohm41321/luciazero
 ```
 
-Wires two scripts into `~/.claude/settings.json` (backed up; merge is additive and idempotent): a **verify-nudge Stop hook** — if edits were made but no verify-ish command ran since the last edit, ending the session triggers the one-shot nudge above; fires once, never loops, fails open — and the **statusline** (left untouched if you have a custom one). The stop hook also appends one line per stop outcome (`stop-clean` / `nudge` / `strict-block`) to `luciazero-stats.log` in the config dir — local only, capped at ~250 lines, fail-open — which `/retro` reads to turn recurring discipline gaps into recorded lessons.
-
-What counts as a verify run is a broad regex (test.sh, pytest, `npm test`, `cargo test`, …) — override with `LUCIAZERO_VERIFY_REGEX`, or better, set the repo's exact command with `LUCIAZERO_VERIFY_CMD` (e.g. in the repo's `.claude/settings.local.json` `env` block): in exact mode only commands that *are* or *start with* it count, so `cat test.sh` cannot flip the state green. Documentation writes (`*.md` and friends — `LUCIAZERO_DOC_REGEX`) do not re-arm the nudge, because the closeout skills all write notes *after* the final green verify. A `SessionStart` hook prints a one-line pointer when the project has a `HANDOFF.md` capsule (staleness warning past `LUCIAZERO_HANDOFF_STALE_DAYS`, default 7) — the pointer only, never the contents.
-
-**Strict mode (opt-in on top of opt-in).** Set `LUCIAZERO_STRICT_VERIFY_CMD` to your repo's *fast* verify command — in your **personal** settings, never in anything committed. Honest limitation: the hook reads an environment variable and cannot tell which settings scope set it — a repo's committed `.claude/settings.json` `env` block would reach it too — so treat a repository that ships this variable as hostile and remove it before working there. At session stop the hook actually runs the command (unless the tracked state is already green after the last edit) and **blocks the stop** on red, quoting the failing output. Hard timeout via `LUCIAZERO_STRICT_TIMEOUT` (default 120s); every internal error — timeout, missing command, broken JSON — degrades to the ordinary nudge, never a block. A blocked stop's continuation is never re-blocked (`stop_hook_active`): a speed bump with evidence attached, not a wall.
-
-### Verify, update, uninstall
-
-`./install.sh --status` is a read-only health check: doctrine, skills, agent, import line, version, and — with the enforcement pack — that hook files are executable *and actually wired* (hooks fail open, so a broken install is otherwise silent). Non-zero exit if a core piece is missing. Update with `git pull && ./install.sh` (idempotent; a version sidecar lets `--status` flag an install older than the checkout). `./uninstall.sh` removes the scripts and cleans exactly our settings entries, matched by full path — run it from a checkout at least as new as the one you installed from.
-
-### Codex CLI
-
-`./install-codex.sh` (remove with `./uninstall-codex.sh`) — same content, single source of truth, converted at install time:
-
-| Piece | Lands in Codex as |
-|---|---|
-| Doctrine | Marker-delimited block in `~/.codex/AGENTS.md` (replaced in place on reinstall) |
-| All six skills | `~/.codex/skills/` — same `SKILL.md` format, copied as-is |
-| `reviewer` agent | `~/.codex/skills/reviewer/` — Codex has no subagents, so it ships as a skill |
-| Enforcement pack | Not installed — Codex has no hooks or statusline |
-
-Honors `CODEX_HOME`, backs up `AGENTS.md`, idempotent, writes nothing outside the Codex dir. The doctrine and skills are written platform-neutrally, so the same text works in both CLIs without translation.
-
-## What the doctrine says
+This installs the 9 skills only: no doctrine, reviewer, or hooks.
 
-Nine rules in four groups. Full text in `claude/luciazero.md`.
+### Classic Claude Code and Codex
 
-**Ground truth** — done is proven by an exit code, and a run that did not happen is reported as exactly that; a missing verify command is the first bug; never weaken a check to reach green.
-
-**Loop** — debugging starts with a hypothesis and the command that would refute it, not an edit, and the reproduction becomes a regression test; orient in an unfamiliar repo before editing — CI is the honest source of truth; smallest reversible step; review the final diff as a skeptic — risky diffs get an independent adversarial review.
-
-**Memory** — never re-derive a dead end twice: write down what the code cannot say (null results, footguns) and read the project's notes before working in an area they cover.
+```bash
+npx luciazero                 # Claude Code
+npx luciazero --with-hooks    # Claude Code + hooks/statusline; needs Python 3
+npx luciazero codex           # Codex CLI
 
-**Autonomy** — stop and ask a clear, decidable question before high-stakes or irreversible moves (delete data, deploy, production, public contracts, money, scope changes); everything else proceeds, with unknowns batched into one sharp question; finish the whole scope, naming anything left out.
+npx luciazero uninstall
+npx luciazero uninstall-codex
+```
 
-It is deliberately short, and `test.sh` enforces a word-count ceiling on it, because every line costs context on every turn of every session. Rules that merely restated what 2026 harnesses already enforce by default were removed; the CHANGELOG records each removal and the default it relies on.
+Pick either plugin or classic for Claude Code so hooks are not wired twice.
+Classic installs support `--status`; Codex receives the doctrine and skills but
+not Claude-only hooks/statusline. Installers back up name collisions and remove
+only exact Luciazero-managed copies on uninstall.
 
-## What the skills do
+## The 9 skills
 
-`/luciazero-bootstrap` walks a repository through six phases: **detect** (run the bundled `scripts/detect.sh` evidence scan, then read the CI config — CI is the source of truth; the script surfaces candidates, the agent decides), **establish the verify command** (use the existing one or create the smallest real one: non-zero on failure, unattended, offline, *timed once* — the measurement decides one tier or two; monorepos scope the fast tier), **smoke tests** (3–6 that catch catastrophic breakage — not coverage, and it says so), **guardrails** (only hooks that pay for themselves; on Codex, encoded as `AGENTS.md` instructions), **project notes** (only what reading the code cannot tell you), and **prove it** (run the fast tier twice — a green that does not repeat is a flake; break a covered line, confirm red, restore). Language-agnostic throughout: it detects, it does not assume.
+Run `/luciazero-bootstrap` first; the rest activate when their moment arrives.
 
-`/debug` expands the hypothesis rule for bugs that resist the first look: reproduce deterministically, minimize, keep a visible hypothesis ledger (each entry names the command that would refute it), one variable per iteration, revert failed fixes, close with a regression test that is red before the fix and green after. The ledger seeds itself from recorded experience first — the repo's `docs/lessons.md` and the cross-repo `luciazero-heuristics.md` are grepped for the symptom before new hypotheses are invented; a match starts as H1, still verified.
+| Moment | Skill | Result |
+|---|---|---|
+| Entering a repository | `/luciazero-bootstrap` | Finds or creates a verify command and proves it can fail |
+| Before risky or multi-step work | `/plan` | Fixes scope and observable acceptance evidence |
+| A bug survives the first look | `/debug` | Reproduction, hypothesis ledger, regression test |
+| Good and bad revisions are known | `/bisect` | Finds the first bad commit in a temporary worktree |
+| Before claiming completion | `/done` | Full verify, skeptic review, scope report |
+| Work must move elsewhere | `/lucia-relay` | Portable JSON + Markdown state with drift inspection |
+| Optimizing performance | `/experiment` | Baseline, threshold, controlled measurement |
+| Reviewing local verify habits | `/discipline-report` | Time/project-filtered local outcome report |
+| After difficult work | `/retro` | Stores reusable lessons and disproved approaches |
 
-`/done` is the closeout ritual: full-tier verify with the decisive line quoted, a skeptic pass over the final diff, an independent adversarial review when the diff earns it, an explicit scope check naming anything left out, and a fixed report format. The test-honesty question — *would the new tests fail if the change were reverted?* — has a mechanical form: the bundled `scripts/revert-probe.sh` checks the old code into a throwaway git worktree, overlays only the changed test files, runs your verify command there, and inverts the result (exit 0/1/2 = bites/vacuous/unassessable).
+Risky diffs also pass through one read-only `reviewer` with `security`,
+`contract`, or `general` focus. Security and contract risk together receive two
+separate passes.
 
-`/handoff` writes a state capsule (`HANDOFF.md`) when a session ends mid-task: goal, verified state, the one literal next command, open and refuted hypotheses, landmines. The next session — or the other harness — reads it, re-verifies against the tree, and deletes it.
+## Evidence
 
-`/experiment` is the measured-change protocol for "make it faster" work: metric and win threshold defined before touching code, baseline with repetitions, one variable per experiment, verdict recorded to `docs/experiments.md` — where a null result is worth as much as a win, and losers are reverted immediately.
+<!-- BEGIN GENERATED: benchmark-evidence -->
 
-`/retro` closes the loop on *never re-derive a dead end twice*: after a hard task it filters the session for what **reading the code cannot tell a future agent** (null results, footguns, environment quirks), routes repo-true lessons into the project's notes and machine-local facts into the harness's memory (never committed), updates instead of duplicating, and deletes notes the session disproved. Three learning stores make this compound over time: debugged failures land in the repo's `docs/lessons.md` in a fixed greppable shape (symptom → cause → proven-by → fix) that `/debug` reads next time; lessons true in every repository go to `luciazero-heuristics.md` in the config dir (one line each, hard 100-line cap — an unbounded heuristics file would become the context tax this pack exists to prevent); and the enforcement pack's stats log turns recurring nudges into recorded behavioral lessons. Uninstall keeps all three — they are learned data. An empty retro is a valid retro — and knowledge stops evaporating when the session ends.
+### Claude results
 
-## The adversarial check: `reviewer` agent
+Snapshot: 2026-08-11. All-criteria pass rate generated from checked-in raw rows:
 
-An exit code cannot catch *passes-the-tests-but-wrong*. For risky diffs the doctrine wants an independent adversarial review: on Claude Code the built-in `/code-review` is the stronger tool when available; the shipped `reviewer` agent is the portable fallback and the only reviewer on Codex. Read-only, instructed to **refute** the change, runs on the same model as the main thread (`model: inherit`), and reports `No findings.` rather than inventing some.
+| Claude model | Luciazero | Bare | Difference |
+|---|---:|---:|---:|
+| Haiku†, 10 valid/task | 36/60 (60%) | 27/60 (45%) | +15pp |
+| Sonnet, 4–5 valid/task* | 25/27 (93%) | 16/26 (62%) | +31pp |
 
-## Design notes
+The `Luciazero` arm installs the classic pack without hooks; it is not a clean
+doctrine-only ablation. *Sonnet is preliminary because eight invalid rows leave
+several arms at four valid runs. The previously stated `+37pp` top-up is retired
+because its replacement raw rows could not be recovered.
 
-**Why a file, not a hook.** Hooks enforce mechanical, deterministic things; doctrine is judgment, and judgment belongs in context. Claude Code already re-injects `CLAUDE.md` after compaction — the real anti-drift lever is keeping the doctrine small, which `test.sh` enforces.
+†Model provenance is incomplete for Haiku: only 70/140 rows encode model
+identity. The other 70 are attributed at campaign-file/report level and
+cannot be independently verified per row.
 
-**Why the doctrine and the skills are separate.** The doctrine must be cheap enough to carry on every turn; the procedures are long and moment-specific, so they load on demand. Merging them would make you pay for the procedures constantly.
+### GPT/Codex pilot — exploratory
 
-**How the plugin squares with this.** Plugins have no way to import a file into `CLAUDE.md`, so the plugin channel delivers the doctrine as `SessionStart` context — acceptable only because the text is word-ceiling-capped, and guarded so it stays silent when a classic install already imports it. The classic installer remains the reference channel; the plugin trades the statusline and `--status` for one-command install and marketplace updates.
+Snapshot: 2026-08-12.
 
-**Project settings stay in the project.** `examples/project-settings.example.json` shows the per-repo shape — a permission allowlist so the verify loop is not interrupted, and an inert check-suppression guard that mechanizes "never weaken a check to reach green". Copy into a repo's `.claude/settings.json`; do not put project commands in global settings.
+| Model | Valid invocations | Paired tasks | Luciazero | Bare | Observed difference |
+|---|---:|---:|---:|---:|---:|
+| GPT-5.6 Terra, medium | 11/12* | 5 | 5/5 runs, 28/28 criteria | 5/5 runs, 28/28 criteria | +0pp† |
 
-**Agentic CI stays a diagnosis loop.** `examples/luciazero-ci.example.yml` (inert, REPLACE-ME-gated) posts an agent's root-cause diagnosis on a PR when CI fails. It cannot push or edit code (`contents: read`, no Bash in the allowlist, no credentials); its one write scope posts the size-capped diagnosis comment. It never auto-fixes: an agent patching CI blind ships plausible-but-wrong fixes.
+*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).
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/ohm41321/luciazero/main/docs/assets/lucia-laptop.png" width="240" alt="Lucia grinding through the eval harness on her laptop">
-</p>
+<!-- END GENERATED: benchmark-evidence -->
 
-**The setup measures itself.** `eval/` is a small A/B harness: the same planted-bug tasks run with and without the doctrine installed, graded offline by behavioral criteria. Four tasks, each probing a different rule — slugify (regression-test discipline), red-suite (bending tests toward a bug), flaky-report (making an intermittent failure deterministic), pipeline (root-cause vs symptom patch, graded by diff locality). CI proves every grader three ways on every push: `reference/` passes, unfixed `project/` fails, and the checked-in `gamed/` cheat trees are rejected. `eval/run.sh --runs N` + `eval/report.sh` produce per-criterion pass-rate tables; see `eval/README.md`, including its honesty box about small n.
+## Requirements and safety
 
-## Safety
+- Node.js 18+ for the CLI and discipline report.
+- Bash for classic installers; Python 3 for hooks and Lucia Relay.
+- Core installers, hooks, helpers, and graders are offline. Real behavioral
+  evals invoke a model CLI and consume API credit or subscription quota.
+- Hooks run commands on your machine. Read them before enabling them.
+- Set `LUCIAZERO_VERIFY_CMD` to the repo's exact fast verify command.
+- Put `LUCIAZERO_STRICT_VERIFY_CMD` only in personal settings, never in a
+  committed repository config. Strict mode fails open on internal errors.
 
-Hooks execute commands on your machine automatically. The example settings file is inert by design — every hook in it is commented out and must be edited before it does anything. Read any hook before enabling it, and do not enable one that pushes, deploys, deletes, or writes outside the repository.
+See [SECURITY.md](SECURITY.md) for the complete trust boundary.
 
 ## Development
 
-`./test.sh` is this repo's own verify command — the doctrine says a missing verify command is the first bug, so the repo passes its own rule. It covers shell syntax + shellcheck, the hook state machine (strict gate included), plugin + npm manifests, every eval grader proven red *and* green *and* anti-cheat, `revert-probe.sh` in throwaway git fixtures, `demo.sh`, and full install → reinstall → uninstall cycles for both harnesses in sandbox config dirs — never your real `~/.claude/` or `~/.codex/`. CI runs it on every push; tagging `vX.Y.Z` publishes a GitHub Release. See `CONTRIBUTING.md` and [docs/publishing.md](docs/publishing.md).
-
-```
-$ ./test.sh
-PASS  all checks green
+```bash
+./test.sh
 ```
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/ohm41321/luciazero/main/docs/assets/lucia-cheer.png" width="240" alt="Lucia celebrating — all checks green">
-</p>
+The suite covers scripts, hook state, Relay, bisect, plugin/npm manifests,
+self-proving eval graders, and sandboxed install → reinstall → uninstall for
+Claude Code and Codex.
 
-## Lucia family & support
+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)
 
-Luciazero shares its mascot with [Lucia](https://lucia-discord-bot.vercel.app) — a Thai-language Discord bot with AI chat, music playback, mini-games, and a gacha card collection.
+## Lucia family & support
 
-If Luciazero saves you review cycles, you can [support the project here](https://easydonate.app/itsathitz) 💚
+Luciazero shares its mascot with [Lucia](https://lucia-discord-bot.vercel.app),
+a Thai-language Discord bot. If Luciazero saves you review cycles, you can
+[support the project here](https://easydonate.app/itsathitz) 💚
 
 ## License