luciazero 2.5.0 → 2.6.0

package/README.md

@@ -26,6 +26,11 @@ Luciazero is the verification and handoff layer for Claude Code, Codex CLI, and
 compatible skill runtimes. It helps agents prove tests, preserve scope, and
 move unfinished work with evidence.
 
+This checkout is the **2.6.0** tree: the manifests and the top
+[changelog](CHANGELOG.md) entry agree, and this document describes that
+source. Its twelve eval fixtures pass offline under `./test.sh`; no real-model
+skills-ablation pilot has run yet.
+
 > Done is proven by a command, not by my judgment. If no verification command
 > exists, that is the first bug.
 
@@ -170,6 +175,17 @@ 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.
 
+The whole exchange is two commands per side. The producer runs
+`luciazero relay draft --write` (add `--recipient cross-machine --base <base>`
+to publish the transfer tag), fills the JSON, then `luciazero relay finalize`,
+which validates, renders the human view, and for cross-machine prints the
+trusted envelope (`--envelope-out <file>` saves it). The receiver runs
+`luciazero relay inspect --trusted-envelope <file>` and, after re-running the
+evidence, `luciazero relay consume --verified --trusted-envelope <file>`. The
+envelope is only trusted when it arrived through an authenticated channel and
+is named explicitly from outside the clone; one shipped beside the artifact is
+refused.
+
 <p align="center">
   <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>
@@ -215,16 +231,33 @@ This installs the 13 skills: no doctrine, reviewer, or hooks.
 <details>
 <summary><strong>Classic install · Claude Code or Codex CLI</strong></summary>
 
+Install the command globally once, without `sudo`:
+
 ```bash
-npx luciazero                 # Claude Code
-npx luciazero --with-hooks    # Claude Code + hooks/statusline; needs Python 3.9+
-npx luciazero codex           # Codex CLI
+npx luciazero@latest global-install
+```
 
-npx luciazero uninstall
-npx luciazero uninstall-codex
+This installs the CLI under `~/.local/npm` and, after confirmation, adds its
+bin directory to your zsh or bash PATH. Start a new shell, then use the global
+command from any directory:
+
+```bash
+luciazero                 # Claude Code
+luciazero --with-hooks    # Claude Code + hooks/statusline; needs Python 3.9+
+luciazero codex           # Codex CLI
+
+luciazero uninstall             # remove the Claude classic files
+luciazero uninstall-codex       # remove the Codex classic files
+luciazero global-status         # check the global command and PATH
+luciazero global-uninstall      # remove the command and its exact PATH block
 ```
 
-Pick either plugin or classic for Claude Code so hooks are not wired twice.
+For a one-off install without keeping the command, `npx luciazero@latest`
+continues to work. Automation may pass `global-install --yes`; interactive use
+asks before installing the package and changing a shell startup file.
+
+Pick either plugin or classic for Claude Code: installing both loads every
+skill and the reviewer twice, even though hooks and doctrine deduplicate.
 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.
@@ -236,10 +269,13 @@ only exact Luciazero-managed copies on uninstall.
 Luciazero never changes classic or Codex files in the background.
 
 ```bash
-npx luciazero@latest check-update   # read-only; contacts npm only now
-npx luciazero@latest update         # updates every detected classic/Codex install
+luciazero check-update   # read-only; contacts npm only now
+luciazero update         # updates every detected classic/Codex install
 ```
 
+If you chose the one-off path, use the same commands through
+`npx luciazero@latest` instead.
+
 `update` preserves whether the Claude classic install uses hooks, repairs stale
 managed files, starts no fresh install when it cannot find one, and stops on a
 known newer version or malformed version metadata. Start a new agent session
@@ -289,8 +325,9 @@ technical evidence plain. Plugin users invoke `/luciazero:imouto-mode focus`;
 Codex users invoke `$imouto-mode focus`.
 
 Risky diffs also pass through one read-only `reviewer` with `security`,
-`contract`, or `general` focus. Security and contract risk together receive two
-separate passes.
+`contract`, or `general` focus. Security and contract risk together get one
+pass that names both focuses, never two. A small diff with no routed risk gets
+no review.
 
 ## Evidence & limitations
 
@@ -355,9 +392,15 @@ only one run per arm per task. See the [full benchmark](https://github.com/ohm41
   evals invoke a model CLI and consume API credit or subscription quota.
 - Hooks run commands on your machine. Read them before enabling them.
 - Hook telemetry stays local in private per-session state and records aggregate
-  turn/Bash wall time plus Bash, verify, and model/user skill counts—never raw
-  commands, skill names, or paths.
+  turn/Bash/verify wall time, redundant-green counts, and Bash, verify, and
+  model/user skill counts—never raw commands, skill names, or paths. Older rows
+  without verify timing are reported as not measured, not zero.
 - Set `LUCIAZERO_VERIFY_CMD` to the repo's exact fast verify command.
+- `LUCIAZERO_EDIT_DIAG=1` in your own shell makes the hook keep one line per
+  edit event in its state directory (tool name, opaque key, whether
+  `file_path` was missing, empty or present, its suffix, under cwd or not,
+  counted or not — never the path or the content), for finding out what
+  re-armed the nudge when no visible edit did.
 - Put `LUCIAZERO_STRICT_VERIFY_CMD` only in personal settings, never in a
   committed repository config. Strict mode fails open on internal errors.
 - A repository's committed `.claude/settings.json` cannot configure Luciazero
@@ -374,16 +417,28 @@ See [SECURITY.md](https://github.com/ohm41321/luciazero/blob/main/SECURITY.md) f
 ## Developing Luciazero
 
 ```bash
-./test.sh --fast   # intermediate loop: core doctrine/hooks/report/Relay checks
-./test.sh          # closeout/CI: full eval, packaging, and install coverage
+./test.sh --discipline  # editing a hook, the report or a skill prompt: ~30 s
+./test.sh --fast        # intermediate loop: adds the agentd suite, Relay, bisect, evidence
+./test.sh               # closeout/CI: full eval, packaging, and install coverage
+LZ_TEST_TIMINGS=1 ./test.sh --fast   # plus one `TIMING gate=<name> seconds=<n>` per gate on stderr
+scripts/test-timings.sh --fast       # same run, and keeps stdout/stderr/meta under .test-timings/
+scripts/test-timings.sh --report     # median and p95 per gate over the green samples kept so far,
+                                     # and the commits they came from (a warning when they span more than one)
 ```
 
-The fast tier is the default intermediate check for this repository; use a
-more targeted command when changing a component it does not cover. The default
+The discipline tier is the loop command for the enforcement pack, the
+discipline report and the prompts: syntax, bash 3.2 and ShellCheck over every
+shipped script, the prompt and doctrine contracts, and the hook state machine,
+nothing else. The fast tier is the default intermediate check for everything
+else; use a more targeted command when changing a component it does not cover. The default
 full tier (also `./test.sh --full`) covers scripts, hook state, Relay, bisect,
 plugin/npm manifests, self-proving eval graders, and sandboxed install →
 reinstall → uninstall for Claude Code and Codex. CI and `/done` use the full
-tier.
+tier. `test.sh` is the dispatcher; the checks live in `tests/gates/*.sh`, one
+file per subsystem, sourced in order — read the gate a change touches. In the
+full tier the tiers, eval, packaging, install and codex-install gates run at
+once, each in its own subshell, with their output replayed in order so it
+reads as the serial run; `LZ_TEST_PARALLEL=0` runs them one at a time.
 
 More detail:
 

package/agents/reviewer.md

@@ -36,8 +36,10 @@ 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.
 
-Stay inside the diff's causal scope. No style or formatting findings unless they
-change behavior. Do not narrate the search. Report every verified
+Stay inside the diff's causal scope. Read the changed hunks and their direct
+callers and consumers, never a repository sweep or a module the diff does not
+reach, and stop once every routed risk is checked. 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

package/bin/discipline-report.js

@@ -49,7 +49,10 @@ function parseLine(line) {
   if (trimmed.startsWith("{")) {
     let row;
     try { row = JSON.parse(trimmed); } catch (_) { return { malformed: true }; }
-    if (row.schema !== 2 || !["stop-clean", "nudge", "strict-block"].includes(row.event)) {
+    // Schema 2 rows carry turn/Bash/skill aggregates; schema 3 adds how long
+    // verify commands ran and how many greens repeated a green with no edit
+    // between. Either is read; anything else is a row this reader cannot vouch for.
+    if (![2, 3].includes(row.schema) || !["stop-clean", "nudge", "strict-block"].includes(row.event)) {
       return { malformed: true };
     }
     const timestamp = new Date(row.timestamp);
@@ -58,9 +61,16 @@ function parseLine(line) {
     }
     let telemetry = null;
     if (row.telemetry && typeof row.telemetry === "object") {
+      const count = (key) => Number.isSafeInteger(row.telemetry[key]) && row.telemetry[key] >= 0;
       const keys = ["turn_ms", "bash_ms", "bash_count", "verify_count", "skill_count"];
-      if (keys.every((key) => Number.isSafeInteger(row.telemetry[key]) && row.telemetry[key] >= 0)) {
+      if (keys.every(count)) {
         telemetry = Object.fromEntries(keys.map((key) => [key, row.telemetry[key]]));
+        // The verify aggregates are optional on purpose: a schema-2 row never
+        // had them, and a schema-3 row missing or garbling them still counts
+        // for everything else. `null` means "not measured", never zero.
+        const verifyKeys = ["verify_ms", "redundant_green_count"];
+        const measured = verifyKeys.every(count);
+        for (const key of verifyKeys) telemetry[key] = measured ? row.telemetry[key] : null;
       }
     }
     return {
@@ -123,6 +133,7 @@ const modes = { regex: 0, exact: 0, strict: 0, unknown: 0 };
 const telemetry = {
   measured_turns: 0, turn_ms: 0, bash_ms: 0, non_bash_ms: 0,
   bash_count: 0, verify_count: 0, skill_count: 0,
+  verify_measured_turns: 0, verify_ms: 0, redundant_green_count: 0,
 };
 const projects = new Map();
 for (const row of rows) {
@@ -136,6 +147,11 @@ for (const row of rows) {
     telemetry.bash_count += row.telemetry.bash_count;
     telemetry.verify_count += row.telemetry.verify_count;
     telemetry.skill_count += row.telemetry.skill_count;
+    if (row.telemetry.verify_ms !== null) {
+      telemetry.verify_measured_turns += 1;
+      telemetry.verify_ms += row.telemetry.verify_ms;
+      telemetry.redundant_green_count += row.telemetry.redundant_green_count;
+    }
   }
   const current = projects.get(row.projectId) || {
     project: row.project,
@@ -167,6 +183,13 @@ if (counts.nudge > 0) {
 if (counts["strict-block"] > 0) {
   recommendations.push(`Investigate the configured strict command: it returned red at ${counts["strict-block"]} stop attempt(s).`);
 }
+if (telemetry.redundant_green_count > 0) {
+  recommendations.push(
+    `Likely: ${telemetry.redundant_green_count} verify run(s) came back green with no edit since the previous green` +
+    ` (${Math.round(telemetry.verify_ms / telemetry.verify_measured_turns)} ms of verify per measured turn);` +
+    " re-run the verify command after an edit, not to reconfirm a result nothing changed."
+  );
+}
 if (total > 0 && recommendations.length === 0) {
   recommendations.push("No recurring gap is supported by the selected records.");
 }
@@ -215,6 +238,12 @@ if (telemetry.measured_turns === 0) {
   console.log(`  Average Bash time: ${average(telemetry.bash_ms)} ms`);
   console.log(`  Average non-Bash:  ${average(telemetry.non_bash_ms)} ms`);
   console.log(`  Bash / verify / skill calls: ${telemetry.bash_count} / ${telemetry.verify_count} / ${telemetry.skill_count}`);
+  if (telemetry.verify_measured_turns > 0) {
+    const perTurn = Math.round(telemetry.verify_ms / telemetry.verify_measured_turns);
+    console.log(`  Verify time:       ${perTurn} ms per turn over ${telemetry.verify_measured_turns} turn(s), ${telemetry.redundant_green_count} redundant green(s)`);
+  } else {
+    console.log("  Verify time:       not measured yet (schema-3 hooks record it)");
+  }
 }
 console.log("");
 console.log("Top Nudged Repositories:");

package/bin/global.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const readline = require("node:readline");
+const { spawnSync } = require("node:child_process");
+
+const START = "# luciazero:start global-npm-path";
+const END = "# luciazero:end global-npm-path";
+const BODY = `${START}\nexport PATH="$HOME/.local/npm/bin:$PATH"\n${END}\n`;
+
+function locations(env = process.env) {
+  const home = env.HOME || os.homedir();
+  if (!path.isAbsolute(home)) throw new Error("HOME must be an absolute path");
+  const shell = path.basename(env.SHELL || "");
+  const rcName = shell === "zsh" ? ".zshrc" : shell === "bash" ? ".bashrc" : null;
+  if (!rcName) throw new Error("supported shells are zsh and bash; set SHELL to the shell whose PATH should be updated");
+  return { home, prefix: path.join(home, ".local", "npm"), rc: path.join(home, rcName) };
+}
+
+function readRc(file) {
+  try {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`${file} is not a regular file; left untouched`);
+    return { text: fs.readFileSync(file, "utf8"), mode: stat.mode & 0o777 };
+  } catch (error) {
+    if (error.code === "ENOENT") return { text: "", mode: 0o600 };
+    throw error;
+  }
+}
+
+function nextRc(current, remove = false) {
+  const starts = current.split(START).length - 1;
+  const ends = current.split(END).length - 1;
+  if (starts !== ends || starts > 1) throw new Error("shell config has malformed Luciazero PATH markers; left untouched");
+  if (starts === 1) {
+    const begin = current.indexOf(START);
+    const finish = current.indexOf("\n", current.indexOf(END, begin));
+    const owned = current.slice(begin, finish < 0 ? current.length : finish + 1);
+    if (owned !== BODY) throw new Error("shell config has a customized Luciazero PATH block; left untouched");
+    if (remove) return current.slice(0, begin) + current.slice(begin + owned.length);
+    return current;
+  }
+  if (remove) return current;
+  const separator = current.length && !current.endsWith("\n") ? "\n" : "";
+  return current + separator + BODY;
+}
+
+function writeRc(file, text, mode) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const tmp = path.join(path.dirname(file), `.${path.basename(file)}.luciazero-${process.pid}-${Date.now()}`);
+  const fd = fs.openSync(tmp, "wx", mode);
+  try {
+    // open(2)'s requested mode is filtered by umask.  This is a replacement
+    // for an existing user file, so restore its exact permission bits before
+    // publishing the temporary file with rename(2).
+    fs.fchmodSync(fd, mode);
+    fs.writeFileSync(fd, text, "utf8");
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fs.renameSync(tmp, file);
+  } catch (error) {
+    try { fs.closeSync(fd); } catch {}
+    try { fs.unlinkSync(tmp); } catch {}
+    throw error;
+  }
+}
+
+function npm(args, env = process.env) {
+  const result = spawnSync("npm", args, { stdio: "inherit", env });
+  if (result.error) throw new Error(`could not run npm: ${result.error.message}`);
+  if (result.status !== 0) throw new Error(`npm exited ${result.status === null ? "without a status" : result.status}`);
+}
+
+function confirm(question) {
+  if (!process.stdin.isTTY) return Promise.resolve(false);
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => rl.question(`${question} [y/N] `, (answer) => {
+    rl.close();
+    resolve(/^y(?:es)?$/i.test(answer.trim()));
+  }));
+}
+
+async function install(args) {
+  if (args.includes("--help")) {
+    console.log("Usage: luciazero global-install [--yes]\nInstalls luciazero@latest under ~/.local/npm and adds its bin to PATH.");
+    return 0;
+  }
+  const unknown = args.filter((arg) => arg !== "--yes");
+  if (unknown.length) throw new Error(`unknown option: ${unknown[0]}`);
+  const place = locations();
+  const before = readRc(place.rc);
+  const after = nextRc(before.text);
+  if (!args.includes("--yes") && !await confirm(`Install luciazero@latest globally in ${place.prefix}?`)) {
+    console.error("global install cancelled; nothing changed");
+    return 1;
+  }
+  npm(["install", "--global", "--prefix", place.prefix, "luciazero@latest"]);
+  if (after !== before.text) {
+    try {
+      writeRc(place.rc, after, before.mode);
+    } catch (error) {
+      throw new Error(
+        `the package was installed, but PATH was not changed: ${error.message}. ` +
+        `Run ${path.join(place.prefix, "bin", "luciazero")} directly or retry global-install`
+      );
+    }
+  }
+  console.log(`luciazero installed globally in ${place.prefix}`);
+  console.log(`PATH recorded in ${place.rc}; start a new shell or source that file`);
+  return 0;
+}
+
+function status(args) {
+  if (args.includes("--help")) {
+    console.log("Usage: luciazero global-status\nChecks the user-owned global command and its shell PATH block.");
+    return 0;
+  }
+  if (args.length) throw new Error(`unknown option: ${args[0]}`);
+  const place = locations();
+  const command = path.join(place.prefix, "bin", "luciazero");
+  let commandOk = false;
+  try {
+    const commandStat = fs.statSync(command);
+    commandOk = commandStat.isFile() && Boolean(commandStat.mode & 0o111);
+  } catch {}
+  let pathOk = false;
+  try {
+    const current = readRc(place.rc).text;
+    pathOk = nextRc(current) === current;
+  } catch (error) {
+    console.error(`luciazero: ${error.message}`);
+    return 1;
+  }
+  if (!commandOk || !pathOk) {
+    if (!commandOk) console.error(`MISS  ${command}`);
+    if (!pathOk) console.error(`MISS  Luciazero PATH block in ${place.rc}`);
+    return 1;
+  }
+  console.log(`luciazero is installed globally in ${place.prefix}`);
+  console.log(`PATH is recorded in ${place.rc}`);
+  return 0;
+}
+
+async function uninstall(args) {
+  if (args.includes("--help")) {
+    console.log("Usage: luciazero global-uninstall [--yes]\nRemoves the global npm package and only Luciazero's exact PATH block.");
+    return 0;
+  }
+  const unknown = args.filter((arg) => arg !== "--yes");
+  if (unknown.length) throw new Error(`unknown option: ${unknown[0]}`);
+  const place = locations();
+  const before = readRc(place.rc);
+  const after = nextRc(before.text, true);
+  if (!args.includes("--yes") && !await confirm(`Uninstall global luciazero from ${place.prefix}?`)) {
+    console.error("global uninstall cancelled; nothing changed");
+    return 1;
+  }
+  npm(["uninstall", "--global", "--prefix", place.prefix, "luciazero"]);
+  if (after !== before.text) {
+    try {
+      writeRc(place.rc, after, before.mode);
+    } catch (error) {
+      throw new Error(
+        `the package was removed, but its PATH block remains in ${place.rc}: ${error.message}. ` +
+        `Remove only the lines from '${START}' through '${END}'`
+      );
+    }
+  }
+  console.log(`global luciazero removed from ${place.prefix}`);
+  return 0;
+}
+
+async function main(argv) {
+  const [command, ...args] = argv;
+  if (command === "install") return install(args);
+  if (command === "status") return status(args);
+  if (command === "uninstall") return uninstall(args);
+  throw new Error(`${command || "command"} is not implemented`);
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2)).then((code) => { process.exitCode = code; }).catch((error) => {
+    console.error(`luciazero: ${error.message}`);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = { BODY, locations, nextRc, readRc, writeRc };

package/bin/luciazero.js

@@ -9,7 +9,9 @@
 //   npx luciazero discipline [options]       -> local stats report
 //   npx luciazero check-update [--json]       -> explicit npm version check
 //   npx luciazero update                      -> update detected classic installs
+//   npx luciazero global-install [--yes]       -> persistent user-owned CLI
 //   npx luciazero bus status [--json]         -> Agent Bus queue summary (beta)
+//   npx luciazero relay <subcommand> [...]    -> Lucia Relay (draft, finalize, inspect, consume, ...)
 const { spawnSync } = require("node:child_process");
 const path = require("node:path");
 
@@ -21,7 +23,13 @@ const ROUTES = {
   discipline: { runtime: process.execPath, script: "bin/discipline-report.js" },
   "check-update": { runtime: process.execPath, script: "bin/update.js", args: ["check"] },
   update: { runtime: process.execPath, script: "bin/update.js", args: ["update"] },
+  "global-install": { runtime: process.execPath, script: "bin/global.js", args: ["install"] },
+  "global-status": { runtime: process.execPath, script: "bin/global.js", args: ["status"] },
+  "global-uninstall": { runtime: process.execPath, script: "bin/global.js", args: ["uninstall"] },
   bus: { runtime: process.execPath, script: "bin/bus.js" },
+  // python.org installers on Windows ship python.exe, and python3 there is
+  // usually the Store alias, so the wrapper names the interpreter that exists.
+  relay: { runtime: process.platform === "win32" ? "python" : "python3", script: "skills/lucia-relay/scripts/relay.py" },
 };
 
 const args = process.argv.slice(2);
@@ -30,7 +38,7 @@ if (args[0] && !args[0].startsWith("-")) {
   if (!Object.prototype.hasOwnProperty.call(ROUTES, args[0])) {
     console.error(
       `luciazero: unknown command '${args[0]}' ` +
-      "(install, codex, discipline, check-update, update, bus, uninstall, uninstall-codex)"
+      "(install, codex, discipline, check-update, update, global-install, global-status, global-uninstall, bus, relay, uninstall, uninstall-codex)"
     );
     process.exit(64);
   }
@@ -48,7 +56,7 @@ if (process.platform === "win32" && selected.runtime === "bash") {
 
 const result = spawnSync(selected.runtime, [script, ...(selected.args || []), ...args], { stdio: "inherit" });
 if (result.error) {
-  console.error("luciazero: could not run bash: " + result.error.message);
+  console.error(`luciazero: could not run ${path.basename(selected.runtime)}: ${result.error.message}`);
   process.exit(1);
 }
 process.exit(result.status === null ? 1 : result.status);

package/claude/agents/reviewer.md

@@ -36,8 +36,10 @@ 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.
 
-Stay inside the diff's causal scope. No style or formatting findings unless they
-change behavior. Do not narrate the search. Report every verified
+Stay inside the diff's causal scope. Read the changed hunks and their direct
+callers and consumers, never a repository sweep or a module the diff does not
+reach, and stop once every routed risk is checked. 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