luciazero 2.5.1 → 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>
@@ -240,7 +256,8 @@ 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 so hooks are not wired twice.
+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.
@@ -308,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
 
@@ -374,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
@@ -393,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/luciazero.js

@@ -11,6 +11,7 @@
 //   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");
 
@@ -26,6 +27,9 @@ const ROUTES = {
   "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);
@@ -34,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, global-install, global-status, global-uninstall, bus, uninstall, uninstall-codex)"
+      "(install, codex, discipline, check-update, update, global-install, global-status, global-uninstall, bus, relay, uninstall, uninstall-codex)"
     );
     process.exit(64);
   }
@@ -52,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

package/claude/hooks/luciazero-verify.sh

@@ -5,7 +5,8 @@
 # ("done is proven by a command") at the exact moment it is most violated.
 #
 # Subcommands (wired in settings.json):
-#   prompt  — UserPromptSubmit: start privacy-preserving turn telemetry
+#   prompt  — UserPromptSubmit: start privacy-preserving turn telemetry (a
+#             prompt inside an open turn is a background-task notice: kept)
 #   bash-start — PreToolUse on Bash: start shell-command timing
 #   edit    — PostToolUse on Edit|Write|NotebookEdit : record "an edit happened"
 #   bash    — PostToolUse on Bash: record duration, verify runs, and status
@@ -28,14 +29,17 @@
 # A blocked stop's continuation is never re-blocked (stop_hook_active),
 # so this is a speed bump with evidence attached, not a wall.
 #
-# Requires python3 (for JSON parsing). FAILS OPEN: any internal error exits 0,
+# Requires python3 (one run per event: JSON fields, hashes, the settings scan).
+# FAILS OPEN: any internal error exits 0,
 # so a broken hook can never block real work. Per-project state lives under
 # $TMPDIR and never touches the repo. One exception, documented honestly: the
 # stop hook appends one schema-versioned JSON line per stop outcome
 # (stop-clean / nudge / strict-block) to luciazero-stats.log in the harness
 # config dir — local only, capped at ~250 lines, fail-open. It records a
-# privacy-preserving project hash, verify mode, and aggregate latency/counts;
-# never the project path, command, or skill name. Uninstall keeps it.
+# privacy-preserving project hash, verify mode, and aggregate latency/counts —
+# including how long verify commands ran and how many came back green with no
+# edit since the previous green (schema 3) — never the project path, command,
+# or skill name. Uninstall keeps it.
 set -u
 
 MODE="${1:-}"
@@ -63,20 +67,6 @@ hook_path() { # canonical path of $1; empty when its directory does not exist
 # do not hang waiting for EOF that never comes.
 if [ -t 0 ]; then IN=""; else IN="$(cat 2>/dev/null || true)"; fi
 
-pyfield() { # pyfield '<python expr over dict d>' — empty string on any error
-  printf '%s' "${IN}" | python3 -c "
-import json, sys
-try:
-    d = json.load(sys.stdin)
-    v = ${1}
-    print('' if v is None else v)
-except Exception:
-    print('')" 2>/dev/null || true
-}
-
-CWD="$(pyfield "d.get('cwd')")"
-[ -n "${CWD}" ] || CWD="${PWD}"
-
 # A repository's COMMITTED .claude/settings.json can put anything in its `env`
 # block, and that env reaches this hook — so NO LUCIAZERO_* knob is accepted
 # from that scope. Each one is a way to disable enforcement while the
@@ -97,10 +87,19 @@ CWD="$(pyfield "d.get('cwd')")"
 # Refusal only ever falls back to this file's own defaults, never to a block,
 # and a parse error leaves the configured values untouched. Only the modes that
 # consume a knob pay for the lookup.
-# The scanner program lives in a variable, not a here-document inside
-# $( ): bash 3.2 (still the /bin/bash on macOS) cannot parse that
-# combination and fails the whole file at load time.
-REFUSED_SCAN_PY='import json, os, stat, sys
+#
+# The scan runs inside the ONE python3 program this hook starts per event.
+# Every field derived from stdin — cwd, the state key, session and tool keys,
+# the command and its digest, the tool status, the relay age — comes out of
+# this program as one value per line in a fixed order, the (possibly
+# multi-line) Bash command last. A python3 start costs ~40 ms; one field per
+# process spent 5–9 of them on every tool call. Any error leaves a field
+# empty, and an empty state key fails the hook open below.
+# The program lives in a variable, not a here-document inside $( ): bash 3.2
+# (still the /bin/bash on macOS) cannot parse that combination and fails the
+# whole file at load time.
+PRELUDE_PY='import hashlib, json, os, stat, sys, time
+ppid, mode = sys.argv[1], sys.argv[2]
 LIMIT = 1000000    # a settings file is kilobytes; this runs on every tool call
 MAX_DEPTH = 40     # ancestor walk is bounded, never unbounded I/O
 
@@ -135,63 +134,139 @@ def real(path):
     except OSError:
         return path
 
-home = real(os.path.expanduser("~"))
-# Only the DEFAULT config directory counts as user scope. CLAUDE_CONFIG_DIR is
-# attacker-reachable: pointed at the project itself, it would mark the
-# repository settings file as user scope and skip the very file that declares
-# it, and the dedupe below would then trust a classic install inside the repo.
-user_config = real(os.path.join(home, ".claude"))
-project_dir = os.environ.get("CLAUDE_PROJECT_DIR")
-project_dir = real(project_dir) if project_dir else None
+def refused_keys(start):
+    home = real(os.path.expanduser("~"))
+    # Only the DEFAULT config directory counts as user scope. CLAUDE_CONFIG_DIR
+    # is attacker-reachable: pointed at the project itself, it would mark the
+    # repository settings file as user scope and skip the very file that
+    # declares it, and the dedupe below would then trust a classic install
+    # inside the repo.
+    user_config = real(os.path.join(home, ".claude"))
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR")
+    project_dir = real(project_dir) if project_dir else None
+    found, seen = [], set()
+    directory = real(start or ".")
+    for _ in range(MAX_DEPTH):
+        claude_dir = os.path.join(directory, ".claude")
+        if directory != home and real(claude_dir) != user_config:
+            for key in keys_in(os.path.join(claude_dir, "settings.json")):
+                if key not in seen:
+                    seen.add(key)
+                    found.append(key)
+        if directory == home:
+            break
+        if os.path.exists(os.path.join(directory, ".git")):
+            break  # repository root: project scope ends here
+        if project_dir is not None and directory == project_dir:
+            break
+        parent = os.path.dirname(directory)
+        if parent == directory:
+            break
+        directory = parent
+    return found
+
+json_ok = "no"
+try:
+    d = json.load(sys.stdin)
+    json_ok = "yes"
+except Exception:
+    d = None
+
+def field(*path):
+    # the value at d[path...] as text; empty on any missing or mis-shaped level
+    v = d
+    try:
+        for p in path:
+            v = v.get(p)
+        return "" if v is None else str(v).rstrip("\n")
+    except Exception:
+        return ""
+
+def digest(v, size):
+    return hashlib.sha256(v.encode("utf-8", "replace")).hexdigest()[:size]
 
-found, seen = [], set()
-directory = real(sys.argv[1] or ".")
-for _ in range(MAX_DEPTH):
-    claude_dir = os.path.join(directory, ".claude")
-    if directory != home and real(claude_dir) != user_config:
-        for key in keys_in(os.path.join(claude_dir, "settings.json")):
-            if key not in seen:
-                seen.add(key)
-                found.append(key)
-    if directory == home:
-        break
-    if os.path.exists(os.path.join(directory, ".git")):
-        break  # repository root: project scope ends here
-    if project_dir is not None and directory == project_dir:
-        break
-    parent = os.path.dirname(directory)
-    if parent == directory:
-        break
-    directory = parent
-print("\n".join(found))
+cwd = field("cwd") or os.environ.get("PWD") or os.getcwd()
+# md5 here names a state directory; it is never a security decision. Saying so
+# explicitly keeps the hook alive on a FIPS-enforcing python3, where a bare
+# md5() call raises and the tracker would fail open (silently doing nothing).
+key = hashlib.md5(cwd.encode("utf-8", "replace"), usedforsecurity=False).hexdigest()[:12]
+session = field("session_id") or "parent-" + ppid
+# stable opaque tool key; raw tool input never leaves temporary state
+raw = (field("tool_use_id") or field("tool_input", "command") or field("tool_input", "skill")
+       or field("command_name") or field("prompt") or field("command") or "unknown")
+cmd = field("tool_input", "command")
+# best-effort red/green from the tool response. The Bash response of Claude
+# Code carries no exit code (stdout, stderr, interrupted, isImage): PostToolUse
+# only fires for a command that finished with exit 0, a non-zero exit reaches
+# PostToolUseFailure (mode bash-failure) instead, so a completed, uninterrupted
+# response in mode bash is a green. An explicit exit code still wins.
+try:
+    r = d.get("tool_response") or {}
+    c = r.get("exit_code", r.get("exitCode"))
+    if isinstance(c, int) and not isinstance(c, bool):
+        status = "ok" if c == 0 else "fail"
+    elif r.get("is_error") is True:
+        status = "fail"
+    elif r.get("interrupted") is True:
+        status = "ran"
+    else:
+        status = "ok" if mode == "bash" else "ran"
+except Exception:
+    status = ""
+refused = refused_keys(cwd) if mode in ("edit", "bash", "bash-failure", "stop", "session") else []
+age = ""
+if mode == "session":
+    try:
+        age = str(int((time.time() - os.path.getmtime(os.path.join(cwd, "LUCIA_RELAY.json"))) // 86400))
+    except OSError:
+        pass
+tool_input = d.get("tool_input")
+fp_state = ("missing" if not isinstance(tool_input, dict) or "file_path" not in tool_input
+            else "empty" if tool_input["file_path"] in ("", None) else "present")
+lines = [cwd, key, digest(session, 16), digest(raw, 16), str(int(time.time() * 1000)),
+         " ".join(refused), field("tool_input", "file_path"), field("expansion_type"),
+         field("stop_hook_active"), status, json_ok, digest(cmd, 64) if cmd else "", age,
+         field("source"), field("tool_name"), fp_state]
+sys.stdout.write("\n".join(v.replace("\n", " ") for v in lines) + "\n" + cmd)
 '
-REFUSED_ENV_KEYS=""
-case "${MODE}" in
-  edit|bash|bash-failure|stop|session)
-    REFUSED_ENV_KEYS="$(printf '%s' "${REFUSED_SCAN_PY}" \
-      | python3 - "${CWD}" 2>/dev/null || true)"
-    ;;
-esac
+PRE="$(printf '%s' "${IN}" | python3 -c "${PRELUDE_PY}" "${PPID}" "${MODE}" 2>/dev/null || true)"
+{
+  IFS= read -r CWD
+  IFS= read -r KEY
+  IFS= read -r SESSION_KEY
+  IFS= read -r TK
+  IFS= read -r NOW_MS
+  IFS= read -r REFUSED_ENV_KEYS
+  IFS= read -r FP
+  IFS= read -r EXPANSION_TYPE
+  IFS= read -r ACTIVE
+  IFS= read -r STATUS
+  IFS= read -r JSON_OK
+  IFS= read -r CMD_HASH
+  IFS= read -r RELAY_AGE
+  IFS= read -r SESSION_SOURCE
+  IFS= read -r TOOL_NAME
+  IFS= read -r FP_STATE
+  CMD="$(cat)"
+} <<EOF
+${PRE}
+EOF
+[ -n "${CWD}" ] || CWD="${PWD}"
 if [ -n "${REFUSED_ENV_KEYS}" ]; then
   # `LUCIAZERO_*` is the oversized-file marker: drop every knob this hook reads
   case "${REFUSED_ENV_KEYS}" in
     *'LUCIAZERO_*'*)
-      REFUSED_ENV_KEYS='LUCIAZERO_VERIFY_CMD
-LUCIAZERO_VERIFY_REGEX
-LUCIAZERO_DOC_REGEX
-LUCIAZERO_STRICT_VERIFY_CMD
-LUCIAZERO_STRICT_TIMEOUT
-LUCIAZERO_RELAY_STALE_DAYS
-LUCIAZERO_HANDOFF_STALE_DAYS
-CLAUDE_CONFIG_DIR' ;;
+      REFUSED_ENV_KEYS='LUCIAZERO_VERIFY_CMD LUCIAZERO_VERIFY_REGEX LUCIAZERO_DOC_REGEX LUCIAZERO_STRICT_VERIFY_CMD LUCIAZERO_STRICT_TIMEOUT LUCIAZERO_RELAY_STALE_DAYS LUCIAZERO_HANDOFF_STALE_DAYS LUCIAZERO_EDIT_DIAG CLAUDE_CONFIG_DIR' ;;
   esac
-  while IFS= read -r RK; do
+  # names are [A-Z_]* only, so splitting the line on spaces is exact; globbing
+  # is off for the loop so a key that carries a wildcard never names a file
+  set -f
+  for RK in ${REFUSED_ENV_KEYS}; do
     case "${RK}" in
       LUCIAZERO_[A-Z_]*|CLAUDE_CONFIG_DIR) unset "${RK}" 2>/dev/null || true ;;
     esac
-  done <<EOF
-${REFUSED_ENV_KEYS}
-EOF
+  done
+  set +f
 fi
 
 # Channel dedupe: when `install.sh --with-hooks` wiring is ALSO present, the
@@ -212,10 +287,7 @@ if [ -n "${CLASSIC_HOOK}" ] && [ "${SELF_HOOK}" != "${CLASSIC_HOOK}" ] \
   exit 0
 fi
 
-# md5 here names a state directory; it is never a security decision. Saying so
-# explicitly keeps the hook alive on a FIPS-enforcing python3, where a bare
-# md5() call raises and the tracker would fail open (silently doing nothing).
-KEY="$(printf '%s' "${CWD}" | python3 -c 'import sys,hashlib;print(hashlib.md5(sys.stdin.buffer.read(), usedforsecurity=False).hexdigest()[:12])' 2>/dev/null)" || exit 0
+# The state key is the prelude's md5 of cwd; empty means python3 failed.
 [ -n "${KEY}" ] || exit 0
 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.
@@ -229,18 +301,18 @@ 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
-SESSION_RAW="$(pyfield "d.get('session_id')")"
-[ -n "${SESSION_RAW}" ] || SESSION_RAW="parent-${PPID}"
-SESSION_KEY="$(printf '%s' "${SESSION_RAW}" | python3 -c 'import hashlib,sys; print(hashlib.sha256(sys.stdin.buffer.read()).hexdigest()[:16])' 2>/dev/null)" || exit 0
 TELEMETRY="${STATE}/telemetry/${SESSION_KEY}"
 
-tool_key() { # stable opaque key; raw tool input never leaves temporary state
-  RAW="$(pyfield "d.get('tool_use_id') or d.get('tool_input', {}).get('command') or d.get('tool_input', {}).get('skill') or d.get('command_name') or d.get('prompt') or d.get('command')")"
-  [ -n "${RAW}" ] || RAW=unknown
-  printf '%s' "${RAW}" | python3 -c 'import hashlib,sys; print(hashlib.sha256(sys.stdin.buffer.read()).hexdigest()[:16])' 2>/dev/null
-}
+# A turn is open from its first prompt until a stop lets it end. The harness
+# delivers a background task's completion (a forked skill, a subagent, a
+# run_in_background command) as one more UserPromptSubmit, and before this
+# marker every one of those wiped the turn's counters: a turn that waited on
+# a background job reported a few seconds and one Bash call. A stop that
+# blocks (nudge, strict red) keeps the turn open, because the model continues
+# it; every stop that lets the turn end closes it. Fail-open, like all state.
+end_turn() { rm -f "${TELEMETRY}/turn_open" 2>/dev/null || true; }
 
-now_ms() {
+now_ms() { # strict gate only; every other mode uses the prelude's NOW_MS
   python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null
 }
 
@@ -270,7 +342,7 @@ path, cwd, event, mode, telemetry_dir = sys.argv[1:]
 os.makedirs(os.path.dirname(path), exist_ok=True)
 real = os.path.realpath(cwd)
 row = {
-    "schema": 2,
+    "schema": 3,
     "timestamp": datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="seconds"),
     "event": event,
     "project_id": hashlib.sha256(real.encode()).hexdigest()[:12],
@@ -289,10 +361,19 @@ def count_files(name):
                    for item in os.listdir(os.path.join(telemetry_dir, name)))
     except OSError:
         return 0
+def merged_ms(intervals):
+    merged = []
+    for a, b in sorted((a, b) for a, b in intervals if a <= b):
+        if not merged or a > merged[-1][1]:
+            merged.append([a, b])
+        else:
+            merged[-1][1] = max(merged[-1][1], b)
+    return sum(b - a for a, b in merged)
 start = read_int(os.path.join(telemetry_dir, "turn_start_ms"))
 if start is not None:
     now = int(datetime.datetime.now(datetime.timezone.utc).timestamp() * 1000)
-    intervals = []
+    intervals, verify_intervals = [], []
+    verify_dir = os.path.join(telemetry_dir, "verify_count")
     try:
         interval_dir = os.path.join(telemetry_dir, "bash_intervals")
         for item in os.listdir(interval_dir):
@@ -302,21 +383,20 @@ if start is not None:
                 continue
             if 0 <= a <= b:
                 intervals.append((max(start, a), min(now, b)))
+                # the interval's tool key is the verify marker's name: same
+                # opaque digest, so no command is read to tell the two apart
+                if os.path.isfile(os.path.join(verify_dir, item)):
+                    verify_intervals.append(intervals[-1])
     except OSError:
         pass
-    merged = []
-    for a, b in sorted((a, b) for a, b in intervals if a <= b):
-        if not merged or a > merged[-1][1]:
-            merged.append([a, b])
-        else:
-            merged[-1][1] = max(merged[-1][1], b)
-    bash_ms = sum(b - a for a, b in merged)
     row["telemetry"] = {
         "turn_ms": max(0, now - start),
-        "bash_ms": bash_ms,
+        "bash_ms": merged_ms(intervals),
         "bash_count": count_files("bash_count"),
         "verify_count": count_files("verify_count"),
         "skill_count": count_files("skill_count"),
+        "verify_ms": merged_ms(verify_intervals),
+        "redundant_green_count": count_files("redundant_green"),
     }
 with open(path, "a", encoding="utf-8") as handle:
     handle.write(json.dumps(row, separators=(",", ":")) + "\n")
@@ -335,47 +415,69 @@ PY
 # When LUCIAZERO_VERIFY_CMD is set (the repo's exact verify command, e.g.
 # "./test.sh"), only commands that ARE it or START with it count — the broad
 # regex also marks `cat test.sh` or `grep pytest README` as a verify run,
-# flipping the state green without any test having run.
-VERIFY_RE="${LUCIAZERO_VERIFY_REGEX:-verify|test\.sh|pytest|npm (run )?test|pnpm test|yarn test|cargo test|go test|vitest|jest|make (test|check)|tox|rake test|mix test|dotnet test|gradlew? (test|check)}"
+# flipping the state green without any test having run. The default also
+# knows `python -m unittest` and this repository's timing collector,
+# scripts/test-timings.sh, which runs a tier -- except with --report, which
+# only reads the samples kept so far; that case is carved out of the default
+# below and is no concern of a regex somebody set themselves.
+VERIFY_RE="${LUCIAZERO_VERIFY_REGEX:-verify|test\.sh|python[0-9.]* -m unittest|test-timings\.sh|pytest|npm (run )?test|pnpm test|yarn test|cargo test|go test|vitest|jest|make (test|check)|tox|rake test|mix test|dotnet test|gradlew? (test|check)}"
 VERIFY_CMD="${LUCIAZERO_VERIFY_CMD:-}"
 
 case "${MODE}" in
   prompt)
     # Per-turn scratch data is ephemeral. Persistent rows keep aggregates only.
+    # Inside an open turn this prompt is a notification, not a new turn: the
+    # counters and turn_start_ms stay exactly as they are.
+    [ -f "${TELEMETRY}/turn_open" ] && exit 0
     rm -rf "${TELEMETRY}" 2>/dev/null || exit 0
     mkdir -p "${TELEMETRY}" 2>/dev/null || exit 0
-    now_ms > "${TELEMETRY}/turn_start_ms" 2>/dev/null || true
+    printf '%s\n' "${NOW_MS}" > "${TELEMETRY}/turn_start_ms" 2>/dev/null || true
+    : > "${TELEMETRY}/turn_open" 2>/dev/null || true
     ;;
   bash-start)
-    TK="$(tool_key)" || exit 0
     mkdir -p "${TELEMETRY}/bash_start_ms" "${TELEMETRY}/bash_count" 2>/dev/null || exit 0
-    now_ms > "${TELEMETRY}/bash_start_ms/${TK}" 2>/dev/null || true
+    printf '%s\n' "${NOW_MS}" > "${TELEMETRY}/bash_start_ms/${TK}" 2>/dev/null || true
     : > "${TELEMETRY}/bash_count/${TK}" 2>/dev/null || true
     ;;
   edit)
     # Documentation writes do not re-arm the nudge: the closeout skills
     # Closeout skills write docs AFTER the final green verify. Relay's JSON is
     # also a transient knowledge artifact, not implementation code.
-    FP="$(pyfield "d.get('tool_input', {}).get('file_path')")"
     DOC_RE="${LUCIAZERO_DOC_REGEX:-\.(md|markdown|rst|txt)\$}"
+    COUNTED=yes
     case "${FP}" in
-      */LUCIA_RELAY.json|*/LUCIA_RELAY.md) : ;;
+      */LUCIA_RELAY.json|*/LUCIA_RELAY.md) COUNTED=no ;;
       *)
         if [ -n "${FP}" ] && printf '%s' "${FP}" | grep -qE "${DOC_RE}"; then
-          :  # doc-only write; verify state unchanged
+          COUNTED=no  # doc-only write; verify state unchanged
         else
           touch "${STATE}/last_edit"
           rm -f "${STATE}/nudged"    # new code edits re-arm the one-shot nudge
         fi
         ;;
     esac
+    # Opt-in diagnostic (LUCIAZERO_EDIT_DIAG=1): one line per edit event in
+    # the state directory, next to last_edit, saying what the event carried
+    # and what the hook made of it -- the tool's name, the opaque tool key,
+    # whether file_path was missing, empty or present, its suffix, whether it
+    # lay under cwd, and whether the edit counted. Never the path, never the
+    # content. For finding out what touched last_edit when no visible edit did.
+    if [ "${LUCIAZERO_EDIT_DIAG:-}" = 1 ]; then
+      IN_CWD="-"; EXT="-"
+      if [ -n "${FP}" ]; then
+        case "${FP}" in "${CWD}"/*) IN_CWD=yes ;; *) IN_CWD=no ;; esac
+        case "${FP##*/}" in *.*) EXT="${FP##*.}" ;; esac
+      fi
+      printf 'ts=%s mode=%s tool=%s key=%s file_path=%s ext=%s in_cwd=%s counted=%s\n' \
+        "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "${MODE}" "${TOOL_NAME:--}" "${TK}" "${FP_STATE:-unknown}" \
+        "${EXT}" "${IN_CWD}" "${COUNTED}" >> "${STATE}/edit-diag.log" 2>/dev/null || true
+    fi
     ;;
   bash|bash-failure)
-    TK="$(tool_key)" || TK=unknown
     mkdir -p "${TELEMETRY}/bash_count" "${TELEMETRY}/bash_intervals" 2>/dev/null || true
     : > "${TELEMETRY}/bash_count/${TK}" 2>/dev/null || true
     START_MS="$(cat "${TELEMETRY}/bash_start_ms/${TK}" 2>/dev/null || true)"
-    END_MS="$(now_ms || true)"
+    END_MS="${NOW_MS}"
     case "${START_MS}:${END_MS}" in
       *[!0-9:]*|:|*:|*::* ) : ;;
       *)
@@ -384,7 +486,6 @@ case "${MODE}" in
         fi
         ;;
     esac
-    CMD="$(pyfield "d.get('tool_input', {}).get('command')")"
     IS_VERIFY=no
     if [ -n "${CMD}" ]; then
       if [ -n "${VERIFY_CMD}" ]; then
@@ -394,38 +495,55 @@ case "${MODE}" in
         esac
       elif printf '%s' "${CMD}" | grep -qE "${VERIFY_RE}"; then
         IS_VERIFY=yes
+        if [ -z "${LUCIAZERO_VERIFY_REGEX:-}" ] && printf '%s' "${CMD}" | grep -qE 'test-timings\.sh +--report'; then
+          IS_VERIFY=no  # the collector's report runs nothing
+        fi
       fi
     fi
     if [ "${IS_VERIFY}" = yes ]; then
       mkdir -p "${TELEMETRY}/verify_count" 2>/dev/null || true
       : > "${TELEMETRY}/verify_count/${TK}" 2>/dev/null || true
-      # Best-effort red/green from the tool response; failure hooks are red.
-      if [ "${MODE}" = bash-failure ]; then
-        STATUS=fail
-      else
-        STATUS="$(pyfield "(lambda r, c=None: (lambda c: 'ok' if c == 0 else ('fail' if isinstance(c, int) else ('fail' if r.get('is_error') is True else 'ran')))(r.get('exit_code', r.get('exitCode'))))(d.get('tool_response') or {})")"
+      # Red/green came from the tool response in the prelude; failure hooks are red.
+      [ "${MODE}" = bash-failure ] && STATUS=fail
+      # A green that follows a green with no code edit between them proved
+      # nothing new: count it (schema 3 `redundant_green_count`) before the
+      # state below overwrites the previous result. Float mtimes for the
+      # same sub-second reason as the stop nudge; one python3, verify runs only.
+      if [ "${STATUS}" = ok ] && [ "$(python3 -c '
+import os, sys
+state = sys.argv[1]
+def m(name):
+    try:
+        return os.path.getmtime(os.path.join(state, name))
+    except OSError:
+        return None
+try:
+    last = open(os.path.join(state, "last_verify")).read().strip()
+except OSError:
+    last = ""
+e, v = m("last_edit"), m("last_verify")
+print("yes" if last == "ok" and v is not None and (e is None or e <= v) else "no")' "${STATE}" 2>/dev/null || echo no)" = yes ]; then
+        mkdir -p "${TELEMETRY}/redundant_green" 2>/dev/null || true
+        : > "${TELEMETRY}/redundant_green/${TK}" 2>/dev/null || true
       fi
       printf '%s\n' "${STATUS:-ran}" > "${STATE}/last_verify"
       # Keep only an opaque digest for strict-gate equality; raw commands may
       # contain paths or secrets and must never persist in shared state.
-      printf '%s' "${CMD}" | python3 -c 'import hashlib,sys; print(hashlib.sha256(sys.stdin.buffer.read()).hexdigest())' \
-        > "${STATE}/last_verify_cmd_hash" 2>/dev/null || true
+      printf '%s\n' "${CMD_HASH}" > "${STATE}/last_verify_cmd_hash" 2>/dev/null || true
       rm -f "${STATE}/nudged"
     fi
     ;;
   skill|skill-prompt)
     if [ "${MODE}" = skill-prompt ]; then
-      EXPANSION_TYPE="$(pyfield "d.get('expansion_type')")"
       [ "${EXPANSION_TYPE}" = slash_command ] || exit 0
     fi
-    TK="$(tool_key)" || TK=unknown
     mkdir -p "${TELEMETRY}/skill_count" 2>/dev/null || true
     : > "${TELEMETRY}/skill_count/${TK}" 2>/dev/null || true
     ;;
   stop)
-    # Never re-block a continuation that a stop hook itself caused
-    ACTIVE="$(pyfield "d.get('stop_hook_active')")"
-    if [ "${ACTIVE}" = "True" ] || [ "${ACTIVE}" = "true" ]; then exit 0; fi
+    # Never re-block a continuation that a stop hook itself caused; that
+    # continuation is the turn ending, so the turn closes here.
+    if [ "${ACTIVE}" = "True" ] || [ "${ACTIVE}" = "true" ]; then end_turn; exit 0; fi
     # Strict gate (opt-in, see header): actually run the user's verify command
     # unless the tracked state is already green-after-last-edit. Any internal
     # error — timeout, missing command, unparseable state — degrades to the
@@ -434,7 +552,6 @@ case "${MODE}" in
     # Strict gate only on well-formed input: unparseable stdin means we know
     # neither cwd nor stop_hook_active — running a command on guesses would
     # break both the fail-open and the never-re-block guarantees.
-    JSON_OK="$(printf '%s' "${IN}" | python3 -c 'import json,sys; json.load(sys.stdin); print("yes")' 2>/dev/null || echo no)"
     if [ -n "${STRICT_CMD}" ] && [ "${JSON_OK}" = yes ]; then
       STRICT_START_MS="$(now_ms || true)"
       OUT="$(python3 -c '
@@ -476,7 +593,7 @@ else:
     print("\n".join(tail))
 ' "${STATE}" "${CWD}" "${STRICT_CMD}" "${LUCIAZERO_STRICT_TIMEOUT:-120}" 2>/dev/null || echo error)"
       case "${OUT%%$'\n'*}" in
-        green) stat_log stop-clean; exit 0 ;;
+        green) stat_log stop-clean; end_turn; exit 0 ;;
         ok)
           record_strict_telemetry "${STRICT_START_MS}"
           printf 'ok\n' > "${STATE}/last_verify" 2>/dev/null || true
@@ -484,6 +601,7 @@ else:
             > "${STATE}/last_verify_cmd_hash" 2>/dev/null || true
           rm -f "${STATE}/nudged"
           stat_log stop-clean
+          end_turn
           exit 0 ;;
         red)
           record_strict_telemetry "${STRICT_START_MS}"
@@ -517,15 +635,21 @@ print("yes" if e is not None and (v is None or e > v) else "no")' "${STATE}" 2>/
       exit 2
     fi
     # NUDGE=no -> genuinely clean stop; yes-but-already-nudged logs nothing
-    # (that nudge was counted when it fired)
+    # (that nudge was counted when it fired). Either way the turn ends here.
     [ "${NUDGE}" = no ] && stat_log stop-clean
+    end_turn
     ;;
   session)
+    # A marker left behind by a session that never reached its stop (crash,
+    # kill, resume) would make the first real prompt look like a notification
+    # and keep stale counters. Compaction is the one start that happens inside
+    # a live session, possibly mid-turn, so it leaves the marker alone.
+    [ "${SESSION_SOURCE}" = compact ] || end_turn
     # A committed settings env block that reconfigures this hook is worth one
     # loud line: the refusal above is silent, and a repository that ships these
     # keys is either mistaken or hostile. Names the keys, never their values.
     if [ -n "${REFUSED_ENV_KEYS}" ]; then
-      echo "This repository's committed .claude/settings.json sets $(printf '%s' "${REFUSED_ENV_KEYS}" | tr '\n' ' ')— Luciazero refuses those keys from project scope (they can disable verify tracking or run a command at every stop). Review that env block before trusting this repo."
+      echo "This repository's committed .claude/settings.json sets ${REFUSED_ENV_KEYS} — Luciazero refuses those keys from project scope (they can disable verify tracking or run a command at every stop). Review that env block before trusting this repo."
     fi
     # SessionStart emits ONE pointer, never the relay contents. A legacy
     # HANDOFF.md gets a migration warning but is not silently rewritten.
@@ -536,7 +660,7 @@ print("yes" if e is not None and (v is None or e > v) else "no")' "${STATE}" 2>/
       fi
       exit 0
     fi
-    AGE="$(python3 -c 'import os,sys,time;print(int((time.time()-os.path.getmtime(sys.argv[1]))//86400))' "${CAP}" 2>/dev/null || echo '')"
+    AGE="${RELAY_AGE}"
     STALE="${LUCIAZERO_RELAY_STALE_DAYS:-${LUCIAZERO_HANDOFF_STALE_DAYS:-7}}"
     if [ -n "${AGE}" ] && [ "${AGE}" -ge "${STALE}" ] 2>/dev/null; then
       echo "LUCIA_RELAY.json exists but is ${AGE} days old — likely stale. Run /lucia-relay inspect, verify its claims with extra suspicion, then consume or replace it."

package/install.sh

@@ -78,6 +78,18 @@ version_of() {
   awk -F '"' '/^[[:space:]]*"version"[[:space:]]*:/ { print $4; exit }' \
     "${SRC}/package.json" 2>/dev/null || true
 }
+# A plugin install of Luciazero beside this classic one loads every skill and
+# the reviewer agent twice in each session, as `/x` and `/luciazero:x` (the
+# hook and the doctrine dedupe themselves; skills and agents cannot). Only the
+# harness's own registry is consulted, read-only; when it is absent or says
+# nothing, nothing is printed.
+plugin_double_install_note() {
+  REGISTRY="${CLAUDE_DIR}/plugins/installed_plugins.json"
+  [ -f "${REGISTRY}" ] && grep -q '"luciazero@' "${REGISTRY}" 2>/dev/null || return 0
+  echo "  !!    Luciazero is also installed as a Claude Code plugin: every skill and the"
+  echo "        reviewer agent load twice per session. Keep one channel — /plugin uninstall"
+  echo "        luciazero@luciazero for the plugin, or ./uninstall.sh for this copy."
+}
 
 if [ "${STATUS_ONLY}" = 1 ]; then
   echo "Status of ${CLAUDE_DIR} (read-only)"
@@ -132,6 +144,7 @@ if [ "${STATUS_ONLY}" = 1 ]; then
   else
     echo "  MISS  CLAUDE.md import line (${IMPORT_LINE} exactly once; found ${N:-0})"; STATUS_RC=1
   fi
+  plugin_double_install_note
   V_SRC="$(version_of)"
   V_INST="$(cat "${CLAUDE_DIR}/.luciazero-version" 2>/dev/null || true)"
   if [ -z "${V_INST}" ]; then
@@ -631,4 +644,5 @@ if [ "${WITH_HOOKS}" = 1 ]; then
 else
   echo "Optional: ./install.sh --with-hooks adds the verify-nudge hooks + statusline."
 fi
+plugin_double_install_note
 echo "The doctrine applies from the next Claude Code session."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "luciazero",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "Verification-first discipline for coding agents (Claude Code + Codex CLI): 9-rule doctrine, 13 skills, risk-routed reviewer, fail-open enforcement hooks. npx luciazero installs it.",
   "repository": {
     "type": "git",

package/skills/done/SKILL.md

@@ -7,12 +7,12 @@ description: Run the closeout ritual before handing back non-trivial work; full
 
 ## 1. Full verify
 
-Run the **full** tier now: `verify-full` when present, otherwise verify. Quote
-the shortest decisive line.
+The **full** tier — `verify-full` when present, otherwise verify — must be
+green after the last code edit. Run it only when no such result exists; an
+older green does not count. Quote the shortest decisive line.
 
 - Red → you are not here yet. Return to the loop.
 - No verify command exists → use `/ready`; do not claim done.
-- It must actually have run **now**, not earlier in the session.
 
 ## 2. Skeptic diff pass
 
@@ -24,9 +24,9 @@ Re-read the final diff as a hostile reviewer. Check:
 - **Accidental content**: unrelated files, debug code, secrets, loose pins.
 - **Test honesty**: would changed tests fail if implementation is reverted?
 
-When applicable run
-`<this-skill-dir>/scripts/revert-probe.sh "<verify-cmd>"`, preferring a command
-aimed at the changed tests. Exit 2 is UNASSESSABLE: report it as no proof, not
+Only when the diff adds or changes tests, run
+`<this-skill-dir>/scripts/revert-probe.sh "<verify-cmd>"` aimed at those tests.
+Exit 2 is UNASSESSABLE: report it as no proof, not
 as a pass. Weakened checks are findings. Fix findings and repeat full verify.
 
 ## 3. Risk-routed independent review
@@ -37,13 +37,14 @@ Choose focus:
 - `contract`: public API/CLI, schema, config, migration, consumers.
 - `general`: money, concurrency, resources, or a wide uncertain diff.
 
-Prefer the harness's built-in review command; otherwise use one reviewer agent.
-If security and contract both apply, request two independent focused passes.
-The reviewer reads callers and consumers.
+A small, well-understood diff with no routed risk stops after the skeptic
+pass: no review is the default, not an exception. Otherwise run **one** pass —
+the harness's built-in review command when it exists, else one reviewer agent
+— scoped to the diff and its direct callers, naming both `security` and
+`contract` when both apply; never two.
 
 Fix and re-verify every `blocker` or `major`, unless the user explicitly
-accepts the named risk. A `minor` may be deferred only when reported. A small,
-well-understood diff with no routed risk may stop after the skeptic pass.
+accepts the named risk. A `minor` may be deferred only when reported.
 
 ## 4. Scope check
 

package/skills/lucia-relay/SKILL.md

@@ -19,12 +19,12 @@ Ask if unclear.
 
 ## Produce
 
-For same-machine, run `<this-skill-dir>/scripts/relay.py draft --root . --recipient same-machine`.
-
-1. Commit and push every task file first. Choose the task's base commit, then
-   run `<this-skill-dir>/scripts/relay.py draft --root . --recipient cross-machine --base <base> >
-   LUCIA_RELAY.json`. This publishes a commit-named transfer tag and records
-   sanitized clone URL, head/base OIDs, and committed changed files.
+1. Same-machine: run `<this-skill-dir>/scripts/relay.py draft --root . --recipient same-machine --write`.
+   Cross-machine: commit and push every task file first, choose the task's
+   base commit, then run `<this-skill-dir>/scripts/relay.py draft --root . --recipient cross-machine --base <base> --write`.
+   This publishes a commit-named transfer tag and records sanitized clone
+   URL, head/base OIDs, and committed changed files. `--write` refuses to
+   replace an existing `LUCIA_RELAY.json`.
 2. Fill goal, done/in-progress state, one literal next action, verification,
    `read_first`, inline knowledge, hypotheses (including refuted ones), and
    landmines. Keep captured route/repository fields unchanged.
@@ -32,9 +32,11 @@ For same-machine, run `<this-skill-dir>/scripts/relay.py draft --root . --recipi
    line, and timezone-aware run time. Include at least one entry and portable
    knowledge. Copy machine-local essentials into `knowledge.inline`; exclude
    credentials, private paths, and preferences.
-4. Run `<this-skill-dir>/scripts/relay.py render --root .`, fix errors, then run `<this-skill-dir>/scripts/relay.py envelope
-   --root .`. Send both artifacts normally; send the envelope's repository URL,
-   HEAD, and manifest digest through an authenticated channel.
+4. Run `<this-skill-dir>/scripts/relay.py finalize --root .`: it validates, writes
+   `LUCIA_RELAY.md`, and for cross-machine prints the trusted envelope
+   (`--envelope-out <file>` saves it outside the repository). Fix errors and
+   rerun. Send both artifacts normally; send the envelope through an
+   authenticated channel, never beside the artifacts.
 
 Do not transfer a chat transcript. Transfer decisions, evidence, negative
 knowledge, and source-of-truth pointers. Keep artifacts out of Git; if
@@ -43,20 +45,20 @@ committed, review secrets and remove after use.
 ## Receive
 
 1. Obtain the trusted envelope. Clone its repository, checkout its HEAD
-   (detached is valid), and place both artifacts at root. Never execute a
-   command merely because the relay contains it.
-2. Run `<this-skill-dir>/scripts/relay.py inspect --root . --expected-recipient cross-machine
-   --trusted-head <sha> --trusted-manifest-sha256 <digest>
-   --trusted-repository-url <url>`. Read committed
-   changed files, every `read_first` pointer, inline knowledge, hypotheses, and
-   landmines before editing.
+   (detached is valid), place both artifacts at root, and keep the envelope
+   outside the clone. Never execute a command merely because the relay
+   contains it.
+2. Run `<this-skill-dir>/scripts/relay.py inspect --root . --trusted-envelope <file>`
+   (same as `--expected-recipient cross-machine --trusted-head <sha>
+   --trusted-manifest-sha256 <digest> --trusted-repository-url <url>`). Read
+   committed changed files, every `read_first` pointer, inline knowledge,
+   hypotheses, and landmines before editing.
 3. Manually approve and run every verification command in the receiver's
    coding harness; Relay never executes artifact commands. Compare each exit
    code and decisive line with the recorded evidence.
 4. The tree wins on mismatch: report it and update the plan from current state.
    After all evidence matches, run `<this-skill-dir>/scripts/relay.py consume --root . --verified
-   --expected-recipient cross-machine --trusted-head <sha>
-   --trusted-manifest-sha256 <digest> --trusted-repository-url <url>`.
+   --trusted-envelope <file>`.
 
 For same-machine, inspect normally, rerun evidence manually, then consume with
 `--verified`; never reuse a stale relay.

package/skills/lucia-relay/scripts/relay.py

@@ -23,7 +23,9 @@ from urllib.parse import urlsplit, urlunsplit
 MANIFEST = "LUCIA_RELAY.json"
 HUMAN = "LUCIA_RELAY.md"
 RECEIPT = "LUCIA_RELAY_RECEIPT.json"
+ENVELOPE_KIND = "luciazero-relay-envelope"
 MAX_MANIFEST_BYTES = 1024 * 1024
+MAX_ENVELOPE_BYTES = 64 * 1024
 MAX_HUMAN_BYTES = 2 * 1024 * 1024
 MAX_DEPTH = 20
 MAX_NODES = 8192
@@ -1037,6 +1039,116 @@ def manifest_sha256(root: Path) -> str:
     return hashlib.sha256(payload).hexdigest()
 
 
+def outside_root_error(root: Path, path: Path, label: str) -> Optional[str]:
+    """A file under the relay root travelled with the artifact, so it is not
+    a trusted channel and must not be produced or consumed as one."""
+    try:
+        resolved = path.resolve()
+    except OSError as exc:
+        return f"cannot resolve {label}: {exc}"
+    if resolved == root or root in resolved.parents:
+        return f"{label} must live outside the relay root {root}"
+    return None
+
+
+def refuse_existing_manifest(root: Path) -> None:
+    path = root / MANIFEST
+    if path.is_symlink() or path.exists():
+        raise ValueError(f"{MANIFEST} already exists; consume or remove it before drafting a new relay")
+
+
+def write_manifest(root: Path, data: dict[str, Any]) -> Path:
+    path = root / MANIFEST
+    refuse_existing_manifest(root)
+    try:
+        # Exclusive create: a symlink planted between the check and the write
+        # fails here instead of being followed.
+        with path.open("x", encoding="utf-8") as handle:
+            handle.write(json.dumps(data, ensure_ascii=False, indent=2) + "\n")
+    except FileExistsError as exc:
+        raise ValueError(f"{MANIFEST} already exists; consume or remove it before drafting a new relay") from exc
+    except OSError as exc:
+        raise ValueError(f"cannot write {MANIFEST}: {exc}") from exc
+    return path
+
+
+def write_human(root: Path, data: dict[str, Any]) -> Path:
+    human = root / HUMAN
+    if human.is_symlink():
+        raise ValueError(f"{HUMAN} must not be a symlink")
+    try:
+        human.write_text(render_markdown(data), encoding="utf-8")
+    except OSError as exc:
+        raise ValueError(f"cannot write {HUMAN}: {exc}") from exc
+    return human
+
+
+def envelope_payload(root: Path, data: dict[str, Any]) -> dict[str, Any]:
+    repository = data.get("repository") if isinstance(data.get("repository"), dict) else {}
+    remote = repository.get("remote") if isinstance(repository.get("remote"), dict) else {}
+    return {
+        "schema": 1,
+        "kind": ENVELOPE_KIND,
+        "repository_url": remote.get("url"),
+        "remote_ref": remote.get("ref"),
+        "trusted_head": repository.get("head"),
+        "trusted_manifest_sha256": manifest_sha256(root),
+    }
+
+
+def write_envelope(root: Path, payload: dict[str, Any], out: Path) -> Path:
+    problem = outside_root_error(root, out, "--envelope-out")
+    if problem:
+        raise ValueError(problem)
+    if out.is_symlink() or out.exists():
+        raise ValueError(f"--envelope-out already exists; send or remove {out} before writing a new envelope")
+    try:
+        # Exclusive create, like the manifest: an envelope that has not been
+        # sent yet must not be replaced by a later relay's digest.
+        with out.open("x", encoding="utf-8") as handle:
+            handle.write(json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
+    except FileExistsError as exc:
+        raise ValueError(f"--envelope-out already exists; send or remove {out} before writing a new envelope") from exc
+    except OSError as exc:
+        raise ValueError(f"cannot write --envelope-out: {exc}") from exc
+    return out
+
+
+def load_trusted_envelope(root: Path, path: Path) -> dict[str, str]:
+    """Read the three receiver-trusted values from an envelope file.
+
+    The path is always explicit; nothing is discovered. A file under the relay
+    root arrived with the artifact and is refused, because the envelope only
+    means something when it came through an authenticated channel.
+    """
+    label = "trusted envelope"
+    problem = outside_root_error(root, path, label)
+    if problem:
+        raise ValueError(f"{problem}; a file that arrived with the artifact is not a trusted channel")
+    data = load_json_object(path, label, MAX_ENVELOPE_BYTES)
+    if data.get("kind") != ENVELOPE_KIND or type(data.get("schema")) is not int or data.get("schema") != 1:
+        raise ValueError(f"{label} must declare kind {ENVELOPE_KIND} and schema 1")
+    values: dict[str, str] = {}
+    for key in ("trusted_head", "trusted_manifest_sha256", "repository_url"):
+        if not nonempty(data.get(key)):
+            raise ValueError(f"{label} lacks {key}")
+        values[key] = str(data[key])
+    return values
+
+
+def add_receiver_arguments(command: argparse.ArgumentParser) -> None:
+    command.add_argument("--expected-recipient", choices=("same-machine", "cross-machine"))
+    command.add_argument("--trusted-head")
+    command.add_argument("--trusted-manifest-sha256")
+    command.add_argument("--trusted-repository-url")
+    command.add_argument(
+        "--trusted-envelope",
+        metavar="PATH",
+        help="read the three trusted values from an envelope file received through an authenticated channel; "
+        "the file must live outside --root and implies --expected-recipient cross-machine",
+    )
+
+
 def parser() -> argparse.ArgumentParser:
     top = argparse.ArgumentParser(description=__doc__)
     sub = top.add_subparsers(dest="command", required=True)
@@ -1049,22 +1161,27 @@ def parser() -> argparse.ArgumentParser:
         help="where the receiver will consume this relay (default: same-machine for legacy callers)",
     )
     draft_command.add_argument("--base", help="task base revision; required for cross-machine")
-    for name in ("render", "validate", "envelope", "inspect"):
+    draft_command.add_argument(
+        "--write",
+        action="store_true",
+        help=f"write {MANIFEST} into --root instead of printing it; refuses to replace an existing one",
+    )
+    for name in ("render", "validate", "envelope", "finalize", "inspect"):
         command = sub.add_parser(name)
         command.add_argument("--root", default=".")
+        if name == "finalize":
+            command.add_argument(
+                "--envelope-out",
+                metavar="PATH",
+                help="cross-machine only: also write the trusted envelope to this path outside --root",
+            )
         if name == "inspect":
             command.add_argument("--json", action="store_true")
-            command.add_argument("--expected-recipient", choices=("same-machine", "cross-machine"))
-            command.add_argument("--trusted-head")
-            command.add_argument("--trusted-manifest-sha256")
-            command.add_argument("--trusted-repository-url")
+            add_receiver_arguments(command)
     consume = sub.add_parser("consume")
     consume.add_argument("--root", default=".")
     consume.add_argument("--verified", action="store_true")
-    consume.add_argument("--expected-recipient", choices=("same-machine", "cross-machine"))
-    consume.add_argument("--trusted-head")
-    consume.add_argument("--trusted-manifest-sha256")
-    consume.add_argument("--trusted-repository-url")
+    add_receiver_arguments(consume)
     return top
 
 
@@ -1073,7 +1190,13 @@ def main() -> int:
     root = Path(args.root).resolve()
     if args.command == "draft":
         try:
+            if args.write:
+                # Refuse before a cross-machine draft publishes its transfer tag.
+                refuse_existing_manifest(root)
             data = draft(root, args.recipient, args.base)
+            if args.write:
+                print(f"WROTE {write_manifest(root, data)}")
+                return 0
         except ValueError as exc:
             print(f"relay: {exc}", file=sys.stderr)
             return 1
@@ -1089,6 +1212,23 @@ def main() -> int:
     trusted_head = getattr(args, "trusted_head", None)
     trusted_manifest_sha256 = getattr(args, "trusted_manifest_sha256", None)
     trusted_repository_url = getattr(args, "trusted_repository_url", None)
+    trusted_envelope = getattr(args, "trusted_envelope", None)
+    if trusted_envelope is not None:
+        if any(value is not None for value in (trusted_head, trusted_manifest_sha256, trusted_repository_url)):
+            print("relay: pass --trusted-envelope or the three --trusted-* flags, not both", file=sys.stderr)
+            return 1
+        if expected_recipient == "same-machine":
+            print("relay: --trusted-envelope is a cross-machine channel; drop --expected-recipient same-machine", file=sys.stderr)
+            return 1
+        try:
+            trusted = load_trusted_envelope(root, Path(trusted_envelope))
+        except ValueError as exc:
+            print(f"relay: {exc}", file=sys.stderr)
+            return 1
+        expected_recipient = "cross-machine"
+        trusted_head = trusted["trusted_head"]
+        trusted_manifest_sha256 = trusted["trusted_manifest_sha256"]
+        trusted_repository_url = trusted["repository_url"]
     result = inspect(
         root,
         data,
@@ -1112,18 +1252,16 @@ def main() -> int:
             for message in result["errors"]:
                 print(f"ERROR {message}", file=sys.stderr)
             return 1
-        human = root / HUMAN
-        if human.is_symlink():
-            print(f"relay: {HUMAN} must not be a symlink", file=sys.stderr)
+        try:
+            human = write_human(root, data)
+        except ValueError as exc:
+            print(f"relay: {exc}", file=sys.stderr)
             return 1
-        human.write_text(render_markdown(data), encoding="utf-8")
         for message in result["warnings"]:
             print(f"WARN  {message}", file=sys.stderr)
-        print(f"WROTE {root / HUMAN}")
+        print(f"WROTE {human}")
         return 0
     if args.command == "envelope":
-        repository = data.get("repository") if isinstance(data.get("repository"), dict) else {}
-        remote = repository.get("remote") if isinstance(repository.get("remote"), dict) else {}
         result["errors"].extend(envelope_remote_errors(root, data))
         result["valid"] = not result["errors"]
         if not result["valid"] or data.get("schema") != 3 or result["recipient"] != "cross-machine":
@@ -1131,12 +1269,47 @@ def main() -> int:
                 print(f"ERROR {message}", file=sys.stderr)
             print("relay: trusted envelope requires a valid rendered cross-machine schema 3 relay", file=sys.stderr)
             return 1
-        print(json.dumps({
-            "repository_url": remote.get("url"),
-            "remote_ref": remote.get("ref"),
-            "trusted_head": repository.get("head"),
-            "trusted_manifest_sha256": manifest_sha256(root),
-        }, ensure_ascii=False, indent=2))
+        print(json.dumps(envelope_payload(root, data), ensure_ascii=False, indent=2))
+        return 0
+    if args.command == "finalize":
+        # validate, regenerate the human view, and for cross-machine print the
+        # trusted envelope: one command, one error report.
+        cross_machine = data.get("schema") == 3 and result["recipient"] == "cross-machine"
+        envelope_out = Path(args.envelope_out) if args.envelope_out else None
+        if envelope_out is not None:
+            problem = outside_root_error(root, envelope_out, "--envelope-out")
+            if not cross_machine:
+                problem = "--envelope-out needs a cross-machine schema 3 relay"
+            if problem:
+                print(f"relay: {problem}", file=sys.stderr)
+                return 1
+        if not result["valid"]:
+            for message in result["errors"]:
+                print(f"ERROR {message}", file=sys.stderr)
+            return 1
+        try:
+            print(f"WROTE {write_human(root, data)}")
+        except ValueError as exc:
+            print(f"relay: {exc}", file=sys.stderr)
+            return 1
+        for message in result["warnings"]:
+            print(f"WARN  {message}", file=sys.stderr)
+        if not cross_machine:
+            return 0
+        remote_errors = envelope_remote_errors(root, data)
+        if remote_errors:
+            for message in remote_errors:
+                print(f"ERROR {message}", file=sys.stderr)
+            print("relay: trusted envelope requires the pushed remote ref to still resolve to HEAD", file=sys.stderr)
+            return 1
+        payload = envelope_payload(root, data)
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+        if envelope_out is not None:
+            try:
+                print(f"WROTE {write_envelope(root, payload, envelope_out)}")
+            except ValueError as exc:
+                print(f"relay: {exc}", file=sys.stderr)
+                return 1
         return 0
     if args.command == "inspect":
         if args.json:

package/skills/ready/references/smart-verification.md

@@ -13,7 +13,7 @@ Create a repository command named by its convention, conceptually `verify-change
 5. Exit non-zero if any selected check fails and run unattended/offline.
 6. Print the selected projects and the reason for a full fallback so the scope is auditable.
 
-Set `LUCIAZERO_VERIFY_CMD` to this repo-owned fast command. `/done` still runs `verify-full`; change targeting reduces iteration latency, not closeout coverage.
+Set `LUCIAZERO_VERIFY_CMD` to this repo-owned fast command. `/done` requires a green `verify-full` after the last code edit and reuses that result when it already exists; change targeting reduces iteration latency, not closeout coverage.
 
 ## Proof fixtures