rules: stop hand-typing how long ze-verify takes

Four sites told an agent to run make ze-verify with a 240s timeout,
while other paragraphs of the same rule said 25 to 30 minutes and half
an hour, ai/rules/testing.md said 4-10 minutes, and
scripts/dev/verify-lock.sh said ~2 min with MAX_LOCK_AGE 1800s. 240s was
the only one written as a directive and the one no producer supports. An
agent that obeyed it killed a healthy run and read the result as a red
tree.

The rule now names no timeout. It says run it in the foreground, wait,
never poll, do not kill it for being slow, give the call the largest
timeout your harness allows, and take the duration from
tmp/.ze-verify-duration.txt, which _record_duration in verify-lock.sh
actually writes. It quotes the corpus's two competing figures rather
than pretending they are absent.

Each directive is one physical line. condense_body in
scripts/dev/rules_condensed.py appends the bold-led LINE raw, so a
directive that wraps reaches ai/rules/CORE.md cut mid-clause. The
always-on digest now carries all four whole.

The migration is completed rather than half-landed:
ai/skills/ze-verify.md was the operative instruction at the point of use
and still banned run_in_background while citing a rule section that does
not exist, and still told agents to abandon the pass at 240s.
ai/skills/ze-check.md, ai/rationale/git-safety.md and a hook comment
carried the same number. ai/rationale/git-safety.md also carved out a
backgrounding exception that contradicted the rule it exists to explain.
A stale 22-stage count in a commands point file is fixed the same way,
by naming no count.

Five independent reviewers over three rounds found ten defects in the
first two drafts of this change, including that the fix had introduced
600s with no producer and cited MAX_LOCK_AGE from the opposite premise.
Round 3 closed at 0 blocker, 0 issue. plan/learned/1359 records that,
because the failure it documents caught the person writing the rule
against it, three times.

Author: thomas-mangin

.claude/hooks/pretool-bash.py

@@ -183,10 +183,12 @@ def check_root_build(cmd, _ctx):
 # Options that take a SEPARATE argument (`timeout -k 5 30 make ...`,
 # `nice -n 5 make ...`): the flag and its value both sit in front.
 LAUNCHER_OPT_WITH_ARG = {"-k", "--kill-after", "-s", "--signal", "-n", "--adjustment"}
-# The duration/niceness operand itself. `timeout` accepts a unit suffix, and
-# ai/rules/git-safety.md tells every session to write exactly that (`timeout 240s
-# make ze-verify`) -- the old bare-`isdigit()` test did not match it, so the
-# repo's own documented invocation slipped straight past this gate. A bare
+# The duration/niceness operand itself. `timeout` accepts a unit suffix and
+# sessions write one (`timeout <n>s make ze-verify`) -- the old bare-`isdigit()`
+# test did not match it, so that invocation slipped straight past this gate.
+# No duration is named here on purpose: ai/rules/git-safety.md ("Running
+# ze-verify") sets the policy, and a number copied into a comment is the drift
+# this repo keeps paying for (plan/learned/1359). A bare
 # negative niceness (`nice -5 make ...`) is a flag and the operand at once, hence
 # the optional leading `-`.
 LAUNCHER_OPERAND = re.compile(r"^-?\d+(?:\.\d+)?[smhd]?$")

ai/LEARNED-FULL-INDEX.md

@@ -8,7 +8,7 @@ reading: `ai/LEARNED-INDEX.md`. Meta-summaries: `DESIGN-HISTORY.md`
 (why the code is as it is), `RECURRING-PATTERNS.md` (known traps),
 `HOOK-FRICTION.md` (hook false positives).
 
-Total: 933 summaries
+Total: 934 summaries
 
 ## 400-499
 
@@ -992,3 +992,4 @@ Total: 933 summaries
 | 1356 | Learned Corpus: Drain the Ceiling, Do Not Delete the Gate | `plan/learned/1356-learned-corpus-drain-over-archive.md` |
 | 1357 | `flock(1)` on a macOS dev machine is not util-linux | `plan/learned/1357-flock-macos-is-not-util-linux.md` |
 | 1358 | dev-setup-cross-platform | `plan/learned/1358-dev-setup-cross-platform.md` |
+| 1359 | A number typed into a rule file is an unverified claim | `plan/learned/1359-rules-corpus-paraphrase-drift.md` |

ai/rationale/git-safety.md

@@ -26,10 +26,14 @@ tea issue create --title "..."
 
 ## Why `ze-verify` Runs Foreground
 
-`ze-verify` finishes well under the 240s Bash timeout in normal cases
-(two-pass strategy: cached full pass + `-race` only on changed groups).
 Running foreground means the tool result IS the completion signal -- no
-polling, no missed notifications, log is ready to read on return.
+polling, no missed notifications, log is ready to read on return. The
+two-pass strategy (cached full pass + `-race` only on changed groups) is
+what keeps the common case short enough for that to be practical. How
+short is not stated here: `_record_duration` (`scripts/dev/verify-lock.sh`)
+appends the real elapsed seconds to `tmp/.ze-verify-duration.txt`, and a
+duration typed into a document is a claim
+(`plan/learned/1359-rules-corpus-paraphrase-drift.md`).
 
 If a previous run is still going, `verify-lock.sh` blocks the second
 invocation inside the same foreground Bash call until the lock releases.
@@ -42,8 +46,11 @@ Anti-patterns that look like "smart" backgrounding but break:
 | `run_in_background: true` + `stat -c %Y` mtime check on `tmp/ze-verify.log` | Log is written continuously during the run; mtime never "settles" reliably |
 | `run_in_background: true` then assume you'll be notified | You will be, but a concurrent polling/sleep loop in Bash can swallow the notification |
 
-Legitimate reasons to background `ze-verify`:
-- Genuinely independent work to do for >60s while it runs (rare).
-
-In both cases: launch with `run_in_background: true` and **stop**. No
-polling loop. Ever.
+There is no legitimate reason to background it. `ai/rules/git-safety.md`
+("Running ze-verify") says foreground, wait, never poll, and `ai/skills/ze-verify.md`
+step 2 says the same. This paragraph used to carve out an exception for
+"genuinely independent work to do for >60s while it runs", contradicting the
+rule it exists to explain, and enumerating "both cases" under a single bullet.
+Editing the tree during a run is what makes that exception unsafe: the gate
+reads the working tree, so independent work invalidates the run it is waiting
+for.

ai/rules/CORE.md

@@ -70,7 +70,7 @@ BLOCKING only when the commit could plausibly affect build, tests, or generated
 | Anything that runs at build time or affects a binary | YES |
 | `ai/**/*.md`, `.claude/**/*.md`, `plan/**/*.md`, `docs/**/*.md`, `README.md` | NO |
 ### Step 1: If `ze-verify` applies (BLOCKING)
-`make ze-verify` (timeout 240s).
+`make ze-verify`, in the foreground ("Running ze-verify" below).
 ### Structural Gates Are Never Known-Red (BLOCKING)
 The item-2 "log to `plan/known-failures/`" path is for **non-deterministic** failures only -- flaky or environmental TEST reds (load-sensitive races, GC-pressure pool flakes, host-specific listener probes).
 **The general escape is owner-only: `--structural-red-ok "<reason>"`** (the
@@ -110,7 +110,11 @@ One `make ze-verify*` (or `ze-chaos-verify`) at a time repo-wide -- parallel run
 | If the run is yours (same tree), read `tmp/ze-verify.log` instead of re-running | Delete the lockfile |
 | If "waiting for lock" appears, do other work | Start `go test` / `golangci-lint` / `bin/ze-test` in parallel (bypasses lock) |
 ### Running ze-verify
-Foreground with 240s timeout.
+Each directive below is one physical line on purpose.
+**Run `make ze-verify` in the foreground, wait for it, and never poll: the foreground return IS the completion signal.**
+**Do not kill it for being slow. Give the call the largest timeout your harness allows.**
+**Never take a timeout from a duration written in a rule. The one measurement is `tmp/.ze-verify-duration.txt`.**
+**Never edit the tree while a verify runs, yours or anybody's: it reads the working tree.**
 ### A SHARED CHECKOUT NEVER GIVES A CLEAN `ze-verify` (BLOCKING)
 **Several agents work this checkout at once. `make ze-verify` reads the WORKING
 TREE, so it reads their half-finished edits too, and a fully green run is unreachable by construction.

ai/rules/commands.md

@@ -261,7 +261,7 @@ loops make it quadratic.
 ### Poll cost
 
 On 2026-08-02 a session left four `until ! pgrep ...; do sleep 5; done` loops
-running on a machine that was also running QEMU, Docker and a 22-stage
+running on a machine that was also running QEMU, Docker and a full
 `ze-verify`. The loops were started because a foreground `sleep` is refused, and
 they were never stopped when the thing they watched changed. The wake-ups were
 the contention that made the functional suites flaky for the rest of that

ai/rules/git-safety.md

@@ -249,7 +249,8 @@ No = skip and note in commit summary. Unsure = run.
 
 ### Step 1: If `ze-verify` applies (BLOCKING)
 
-`make ze-verify` (timeout 240s). Not `go test`, not any subset.
+`make ze-verify`, in the foreground ("Running ze-verify" below). Not `go test`,
+not any subset.
 Before any verify target, check freshness. A FRESH status covers the
 byte-identical tree and forbids rerunning `make ze-verify` or
 `make ze-verify-changed`. The check output is qualified by mode:
@@ -271,7 +272,7 @@ under `tmp/verify/`, `tmp/ze-verify-failures.log`,
 
 ```
 [ ] 0. `scripts/dev/verify-status.sh check`. FRESH -> MUST NOT run `make ze-verify` or `make ze-verify-changed` again; note timestamp. STALE -> continue only if the table above says verification applies.
-[ ] 1. `make ze-verify` (240s) only when status is STALE and the table above says YES. On failure read `tmp/ze-verify-failures.log` FIRST, choose a stage-local group, then open that group's `tmp/verify/<nn>-<stage>.log`.
+[ ] 1. `make ze-verify` (foreground, largest timeout your harness allows, never killed early) only when status is STALE and the table above says YES. On failure read `tmp/ze-verify-failures.log` FIRST, choose a stage-local group, then open that group's `tmp/verify/<nn>-<stage>.log`.
 [ ] 2. Failure from current work: fix + re-run. Pre-existing: fix after primary task in separate commit; if >10 min, log to `plan/known-failures/` (one `<make-target>-<test-name>.md` shard per failure).
 ```
 
@@ -479,8 +480,27 @@ PID-backed -- no cleanup after a crash.
 
 ### Running ze-verify
 
-Foreground with 240s timeout. No background execution, no polling
-loops. Wait for completion.
+Each directive below is one physical line on purpose. `condense_body`
+(`scripts/dev/rules_condensed.py`) emits a bold-led LINE raw into
+`ai/rules/CORE.md`, so an instruction that wraps arrives there cut in half.
+
+**Run `make ze-verify` in the foreground, wait for it, and never poll: the foreground return IS the completion signal.**
+No background run, no sleep-and-check loop, no `tail` on a log that is still
+growing.
+
+**Do not kill it for being slow. Give the call the largest timeout your harness allows.**
+A verify that is still running is not a verify that is hung, and killing one
+costs the whole pass rather than the seconds it saves.
+
+**Never take a timeout from a duration written in a rule. The one measurement is `tmp/.ze-verify-duration.txt`.**
+This corpus disagrees with itself about how long a full pass takes: "25 to 30
+minutes" below, "4-10 minutes" in `ai/rules/testing.md`. Both were typed by
+hand. `_record_duration` (`scripts/dev/verify-lock.sh`) appends the real elapsed
+seconds to that file, and when it is absent nothing here has measured it
+(`plan/learned/1359-rules-corpus-paraphrase-drift.md`).
+
+**Never edit the tree while a verify runs, yours or anybody's: it reads the working tree.**
+An edit mid-run invalidates the run you are waiting for.
 
 ### A SHARED CHECKOUT NEVER GIVES A CLEAN `ze-verify` (BLOCKING)
 

ai/rules/points/commands/rationale/abandoned-poll-loops-made-the-suites-flaky.md

@@ -4,7 +4,7 @@ level:
 stage:
 ---
 On 2026-08-02 a session left four `until ! pgrep ...; do sleep 5; done` loops
-running on a machine that was also running QEMU, Docker and a 22-stage
+running on a machine that was also running QEMU, Docker and a full
 `ze-verify`. The loops were started because a foreground `sleep` is refused, and
 they were never stopped when the thing they watched changed. The wake-ups were
 the contention that made the functional suites flaky for the rest of that

ai/rules/points/git-safety/before-any-commit/run-make-ze-verify-and-check-freshness-first.md

@@ -3,7 +3,8 @@ kind: note
 level:
 stage:
 ---
-`make ze-verify` (timeout 240s). Not `go test`, not any subset.
+`make ze-verify`, in the foreground ("Running ze-verify" below). Not `go test`,
+not any subset.
 Before any verify target, check freshness. A FRESH status covers the
 byte-identical tree and forbids rerunning `make ze-verify` or
 `make ze-verify-changed`. The check output is qualified by mode:

ai/rules/points/git-safety/before-any-commit/run-verify-in-the-foreground-and-wait.md

@@ -3,5 +3,24 @@ kind: note
 level:
 stage:
 ---
-Foreground with 240s timeout. No background execution, no polling
-loops. Wait for completion.
+Each directive below is one physical line on purpose. `condense_body`
+(`scripts/dev/rules_condensed.py`) emits a bold-led LINE raw into
+`ai/rules/CORE.md`, so an instruction that wraps arrives there cut in half.
+
+**Run `make ze-verify` in the foreground, wait for it, and never poll: the foreground return IS the completion signal.**
+No background run, no sleep-and-check loop, no `tail` on a log that is still
+growing.
+
+**Do not kill it for being slow. Give the call the largest timeout your harness allows.**
+A verify that is still running is not a verify that is hung, and killing one
+costs the whole pass rather than the seconds it saves.
+
+**Never take a timeout from a duration written in a rule. The one measurement is `tmp/.ze-verify-duration.txt`.**
+This corpus disagrees with itself about how long a full pass takes: "25 to 30
+minutes" below, "4-10 minutes" in `ai/rules/testing.md`. Both were typed by
+hand. `_record_duration` (`scripts/dev/verify-lock.sh`) appends the real elapsed
+seconds to that file, and when it is absent nothing here has measured it
+(`plan/learned/1359-rules-corpus-paraphrase-drift.md`).
+
+**Never edit the tree while a verify runs, yours or anybody's: it reads the working tree.**
+An edit mid-run invalidates the run you are waiting for.

ai/rules/points/git-safety/before-any-commit/the-pre-commit-verify-checklist.md

@@ -5,6 +5,6 @@ stage:
 ---
 ```
 [ ] 0. `scripts/dev/verify-status.sh check`. FRESH -> MUST NOT run `make ze-verify` or `make ze-verify-changed` again; note timestamp. STALE -> continue only if the table above says verification applies.
-[ ] 1. `make ze-verify` (240s) only when status is STALE and the table above says YES. On failure read `tmp/ze-verify-failures.log` FIRST, choose a stage-local group, then open that group's `tmp/verify/<nn>-<stage>.log`.
+[ ] 1. `make ze-verify` (foreground, largest timeout your harness allows, never killed early) only when status is STALE and the table above says YES. On failure read `tmp/ze-verify-failures.log` FIRST, choose a stage-local group, then open that group's `tmp/verify/<nn>-<stage>.log`.
 [ ] 2. Failure from current work: fix + re-run. Pre-existing: fix after primary task in separate commit; if >10 min, log to `plan/known-failures/` (one `<make-target>-<test-name>.md` shard per failure).
 ```