@codyswann/lisa 4.54.13 → 4.55.0

package/plugins/src/base/hooks/worktree-binding-guard.mjs

@@ -402,6 +402,11 @@ function applyCd(current, target) {
  * disagreeing. The scripted form is the one neither covers, and it is the only
  * cell this arm fills.
  *
+ * That reason is a dependency on a runtime Lisa does not ship, and it can
+ * expire without anything here failing. It is pinned at
+ * {@link VERIFIED_RUNTIME_VERSION} and reported when the runtime moves off it
+ * — read that constant before widening this arm.
+ *
  * ## A relative script path is resolved against the cwd the command will have
  *
  * A leading `cd` establishes the directory this guard resolves relative tokens
@@ -511,11 +516,28 @@ function readState(sessionId) {
   }
 }
 
+/**
+ * Write the session's binding state, MERGING over whatever is already there.
+ *
+ * Every caller below hands in all three lifecycle fields explicitly, so the
+ * merge changes nothing for them — `claimedRoot: null` still clears a claim.
+ * What it buys is that a field one writer owns is not silently dropped by
+ * another writer that had no opinion about it: `runtimeNoticed` is written by
+ * {@link noticeRuntimeDrift} and read by nobody else, and a clobbering write
+ * would turn its "reported once" into "reported again after the next
+ * acknowledgement", which is the noise the notice is designed not to be.
+ * @param sessionId - The session whose state file this is
+ * @param state - Fields to write over the recorded state
+ * @returns Whether the write succeeded
+ */
 function writeState(sessionId, state) {
   const file = stateFile(sessionId);
   try {
     mkdirSync(dirname(file), { recursive: true });
-    writeFileSync(file, `${JSON.stringify(state, null, 2)}\n`);
+    writeFileSync(
+      file,
+      `${JSON.stringify({ ...readState(sessionId), ...state }, null, 2)}\n`
+    );
     return true;
   } catch (error) {
     say(`could not record the binding (${error.message}); NOT enforcing`);
@@ -695,6 +717,162 @@ function displaced(bound, observed) {
   ]);
 }
 
+/**
+ * The runtime version the inline-redirect gap was last verified at.
+ *
+ * ## What this constant is a pin ON
+ *
+ * This guard deliberately does NOT refuse an INLINE redirect into another
+ * worktree — `cd <other> && git …`, `git -C <other> …`. The reason is good and
+ * is written out at {@link scriptReachingForeignTree}: the runtime's own
+ * worktree isolation already refuses them, and duplicating a control is how two
+ * controls drift into disagreeing about the same command.
+ *
+ * That reason is a DEPENDENCY on behaviour Lisa does not ship. It was verified
+ * refusing at this version, with the refusal wording "this command names git in
+ * a form too complex to verify that it stays inside the worktree" and
+ * "redirects git to the shared checkout via -C".
+ *
+ * ## Why a pin rather than a test
+ *
+ * The runtime's isolation is not reachable from a unit test: it adjudicates
+ * inside a live worktree-isolated session, and there is no entry point that
+ * takes one hook envelope and returns a verdict the way this guard does. So the
+ * dependency cannot be turned red by writing a test, and a claim that cannot go
+ * red goes stale silently instead (CodySwannGT/lisa#3944).
+ *
+ * What CAN be measured is whether the runtime is still the one the claim was
+ * checked against. That does not prove the behaviour changed — only that nobody
+ * has checked since, which is the honest thing to report and the whole of what
+ * this pin does.
+ *
+ * ## Moving it
+ *
+ * Re-run both inline forms in a worktree-isolated session. Still refused: move
+ * this pin, and say where. Permitted: those two cells are UNCOVERED, and #3944
+ * owns the decision about which of them Lisa takes on.
+ */
+const VERIFIED_RUNTIME_VERSION = "2.1.261";
+
+/** The ticket that owns the inline-redirect dependency and its expiry. */
+const RUNTIME_ASSUMPTION_TICKET = "CodySwannGT/lisa#3944";
+
+/**
+ * This session's runtime version, or null when this is not that runtime.
+ *
+ * Three answers, and the difference between the last two is the point:
+ * - `null` — not Claude Code. Codex, Cursor and Copilot ship this guard too,
+ *   and the assumption above is about a control none of them has. A notice that
+ *   fires on every session of every harness is noise, and noise gets switched
+ *   off.
+ * - `""` — Claude Code, which will not say which version. Read as a DIVERGENCE
+ *   rather than as a match: the assumption is unconfirmed either way, and
+ *   treating an unreadable version as "still 2.1.261" is exactly the silent
+ *   expiry #3944 was filed about.
+ * - a version — take it at its word.
+ *
+ * Both env vars are read because either can be the one a future release keeps.
+ * `AI_AGENT` carries `claude-code_2-1-261_agent`; `CLAUDE_CODE_EXECPATH` ends
+ * in the version directory the running build was launched from.
+ * @param env - Environment to read
+ * @returns The version, `""` when unreadable, or null for another runtime
+ */
+const isDigit = ch => ch >= "0" && ch <= "9";
+
+/** @param value - Segment to test @returns Whether it is all digits */
+const allDigits = value => value.length > 0 && [...value].every(isDigit);
+
+/** @param value - Segment to read @returns Its trailing digit run, else `""` */
+const trailingDigits = value => {
+  let start = value.length;
+  while (start > 0 && isDigit(value[start - 1])) start -= 1;
+  return value.slice(start);
+};
+
+function runtimeVersion(env) {
+  if (!env.CLAUDECODE) return null;
+  const tagged = /claude-code[_-](\d+)[-.](\d+)[-.](\d+)/u.exec(
+    env.AI_AGENT ?? ""
+  );
+  if (tagged) return `${tagged[1]}.${tagged[2]}.${tagged[3]}`;
+  // Read the version off the final path segment by scanning characters rather
+  // than by regex: an unanchored `\d+\.\d+\.\d+` before `$` backtracks
+  // super-linearly on a long execpath, and the version Claude Code launches
+  // from is always the trailing directory name.
+  const segments = (env.CLAUDE_CODE_EXECPATH ?? "").split("/").filter(Boolean);
+  const trailing = segments.length ? segments[segments.length - 1] : "";
+  const parts = trailing.split(".");
+  if (parts.length < 3) return "";
+  const [major, minor, patch] = parts.slice(-3);
+  const majorDigits = trailingDigits(major);
+  if (!majorDigits || !allDigits(minor) || !allDigits(patch)) return "";
+  return `${majorDigits}.${minor}.${patch}`;
+}
+
+/**
+ * The notice text for a runtime the inline-redirect claim was not checked at.
+ * @param version - The observed runtime version, `""` when unreadable
+ * @returns The lines to report
+ */
+function driftNotice(version) {
+  return [
+    "worktree-binding-guard: the inline-redirect gap is UNVERIFIED here.",
+    "",
+    "This guard does not refuse `cd <other-worktree> && git …` or",
+    "`git -C <other-worktree> …`. Those two cells are covered by the runtime's",
+    `own worktree isolation, verified refusing at Claude Code ${VERIFIED_RUNTIME_VERSION}.`,
+    version
+      ? `This session is running ${version}, so that check does not cover it.`
+      : "This session's runtime version could not be read, so nothing covers it.",
+    "",
+    "This does NOT say the runtime stopped refusing them — only that nobody has",
+    "checked since. Run both forms in a worktree-isolated session: still",
+    "refused, move VERIFIED_RUNTIME_VERSION in worktree-binding-guard.mjs;",
+    `permitted, the two cells are uncovered and ${RUNTIME_ASSUMPTION_TICKET}`,
+    "owns what Lisa does about it.",
+  ];
+}
+
+/**
+ * Report, once per session, that the runtime moved off the verified version.
+ *
+ * ## Why SessionStart and not the guarded call
+ *
+ * SessionStart is the guard's first evaluation of a session, it fires exactly
+ * once per start, and its `additionalContext` is the one channel here that the
+ * agent actually reads — the `say()` lines elsewhere in this file are for a
+ * human reading a transcript. A notice attached to a guarded tool call would
+ * either repeat on every Bash command or need a suppression rule of its own.
+ *
+ * ## Why it is recorded rather than counted
+ *
+ * A resume fires SessionStart again for the same session id. The recorded
+ * version is what makes the second one silent, and recording the VERSION rather
+ * than a flag means a runtime that moves twice inside one resumed session is
+ * still reported the second time.
+ *
+ * Never refuses. The dependency is a reporting gap, not a live displacement,
+ * and blocking a session over a version number would be a wall where an
+ * observation belongs.
+ * @param sessionId - The session being started
+ * @param env - Environment to read the runtime version from
+ * @returns Nothing; every path through this allows
+ */
+function noticeRuntimeDrift(sessionId, env) {
+  const version = runtimeVersion(env);
+  if (version === null || version === VERIFIED_RUNTIME_VERSION) return;
+  if (readState(sessionId)?.runtimeNoticed === version) return;
+  writeState(sessionId, { runtimeNoticed: version });
+  process.stdout.write(
+    `${JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: driftNotice(version).join("\n"),
+      },
+    })}\n`
+  );
+}
+
 function evaluate(payload) {
   const sessionId = payload.session_id;
   const cwd = payload.cwd;
@@ -707,6 +885,10 @@ function evaluate(payload) {
 
   if (payload.hook_event_name === "SessionStart") {
     recordBaseline(sessionId, observed);
+    // After the baseline, never before: `recordBaseline` writes a fresh state
+    // for a session it has not seen, and the notice's record has to go on top
+    // of that write rather than under it.
+    noticeRuntimeDrift(sessionId, process.env);
     return 0;
   }
   if (payload.tool_name === "EnterWorktree") {

package/plugins/src/base/hooks/worktree-binding-guard.sh

@@ -36,6 +36,27 @@ set -uo pipefail
 
 input="$(cat)"
 
+# Evaluate once per tool call when this guard is registered on both channels.
+#
+# Lisa reaches an agent through the repository dispatcher AND the plugin
+# manifest, and where both are live the harness runs this guard twice for one
+# tool call. `guard-dedupe.bash` short-circuits the second run ONLY when a
+# byte-identical copy already ALLOWED this exact payload on this exact tool
+# call; a differing vintage, a refusal, and a host with one channel all
+# evaluate exactly as before. Nothing is de-registered by it
+# (CodySwannGT/lisa#3814).
+#
+# Absent library means no dedupe, which is the pre-existing behaviour, so an
+# older channel copy that predates it is unaffected.
+lisa_guard_hook_dir="${BASH_SOURCE[0]%/*}"
+lisa_guard_dedupe_lib="$lisa_guard_hook_dir/guard-dedupe.bash"
+if [ -r "$lisa_guard_dedupe_lib" ]; then
+  # shellcheck source=guard-dedupe.bash
+  . "$lisa_guard_dedupe_lib"
+  trap 'lisa_guard_dedupe_record $?' EXIT
+  lisa_guard_dedupe worktree-binding-guard "$input"
+fi
+
 if ! command -v node >/dev/null 2>&1; then
   printf 'worktree-binding-guard: node not found; worktree-binding enforcement is NOT active\n' >&2
   exit 0

package/plugins/src/base/rules/eager/00-rule-index.md

@@ -29,6 +29,7 @@ Paths are relative to this file.
 | `prd-definition-of-ready` | authoring or validating a PRD's requirement atoms | [../reference/prd-definition-of-ready.md](../reference/prd-definition-of-ready.md) |
 | `prd-lifecycle-rollup` | rolling a PRD up from its generated top-level work | [../reference/prd-lifecycle-rollup.md](../reference/prd-lifecycle-rollup.md) |
 | `usage-accounting` | writing the managed `## Lisa Usage` section on an artifact | [../reference/usage-accounting.md](../reference/usage-accounting.md) |
+| `work-item-trailer-definition` | reading, counting, or auditing a `Work-Item:` trailer — BEFORE reaching for `%(trailers)` | [../reference/work-item-trailer-definition.md](../reference/work-item-trailer-definition.md) |
 
 ## Build-intake claim time
 

package/plugins/src/base/rules/eager/operational-hazards.md

@@ -0,0 +1,50 @@
+# Operational Hazards — Short-Lived, Expiring, and Read by Sessions That Do Not Exist Yet
+
+**A broadcast cannot reach a session that starts after it, and the sessions that missed it never
+knew there was something to miss.** The lanes most likely to collide on a port, saturate the
+workers, or re-hit a defect somebody diagnosed an hour ago are precisely the ones that just
+started — so the population a fan-out structurally cannot reach is the population most exposed.
+
+Enumerating peers does not fix it: two sessions listing peers at the same moment returned different
+rosters, so "I told everyone" carries an unknown hole.
+
+## Mandatory
+
+- **Declare a transient hazard instead of announcing it.** A condition another session will hit —
+  a port another lane holds, a saturated resource, a command that dumps credentials, a gate that is
+  red for an environmental reason — is not communicated until this has run:
+
+  ```
+  node "$CLAUDE_PLUGIN_ROOT/hooks/operational-hazards.mjs" --declare <id> \
+    --hazard "<what will go wrong>" \
+    --avoid "<what to do instead>" \
+    --until <YYYY-MM-DD>
+  ```
+
+  `--until` is required and has no default. **An entry that never expires is doctrine, and doctrine
+  belongs in a rule** — a hazard surface without an expiry becomes permanent scripture, which is
+  the failure this exists against. Past its `until`, an entry stops being shown with nobody
+  remembering to remove it.
+
+- **Lift it when it ends.** A declaration nothing can void is the defect the QA-failure signal and
+  the human gate each closed:
+
+  ```
+  node "$CLAUDE_PLUGIN_ROOT/hooks/operational-hazards.mjs" --lift <id> --because "<what resolved it>"
+  ```
+
+- **Read it where no hook runs:** `node "$CLAUDE_PLUGIN_ROOT/hooks/operational-hazards.mjs" --list`.
+
+## What arrives on its own
+
+On Claude Code the ledger is read for you at SessionStart **and SubagentStart** — a subagent
+spawned an hour from now reads it, which no fan-out reaches at all — and re-checked after every
+tool call, so a hazard declared or lifted **while you are running** arrives on your next tool
+result. Two `stat` calls when nothing changed.
+
+An entry naming no evaluable expiry still applies and is reported as `unchecked`, loudly. An expiry
+that lapsed into "no longer shown" would restore permanent scripture while every signal read
+healthy.
+
+Both ledger tiers, what belongs here versus in a rule, and the surfaces with no hook runtime:
+[reference/operational-hazards.md](../reference/operational-hazards.md).

package/plugins/src/base/rules/eager/tracked-work.md

@@ -4,4 +4,4 @@ Before the first durable project mutation (code, tests, config, docs, committed
 
 The mandatory order is: live-validate an explicit ref, or conservatively search and create exactly one valid leaf through `lisa-tracker-write` when no unique match exists; idempotently claim it through `lisa-tracker-claim`; then persist and verify the worktree-local binding with `node scripts/lisa-work-item.mjs link <ref>`. A tracker that answers no, and any claim or binding failure, blocks durable work; a tracker that cannot be reached does not block a commit — the offline checks still run, the skip is loud on stderr, and the required `Work-Item Traceability` check re-runs the live checks with credentials before anything merges.
 
-Carry that canonical ref through the branch, every ordinary commit's `Work-Item:` trailer, the PR, usage/evidence, and `lisa-tracker-sync`. Hooks and CI never create tickets. Keep the binding through interruptions or blocked outcomes; run `node scripts/lisa-work-item.mjs clear` only after merge/deploy/verification, two-way linkage/evidence, and the tracker item have all reached true terminal completion.
+Carry that canonical ref through the branch, every ordinary commit's `Work-Item:` trailer, the PR, usage/evidence, and `lisa-tracker-sync`. Hooks and CI never create tickets. Anything that READS a `Work-Item:` trailer — a gate, an audit, a count, a report — must import `workItemLines` from the shipped `scripts/lisa-work-item.mjs` rather than reach for `git interpret-trailers` or `%(trailers)`, which see only a message's final block and miss 92% of this fleet's trailers; read the `work-item-trailer-definition` rule before writing such a reader. Keep the binding through interruptions or blocked outcomes; run `node scripts/lisa-work-item.mjs clear` only after merge/deploy/verification, two-way linkage/evidence, and the tracker item have all reached true terminal completion.

package/plugins/src/base/rules/reference/config-resolution.md

@@ -1028,7 +1028,7 @@ When `github-to-tracker` is invoked AND `tracker = "github"`, both reads and wri
 
 Never overload one label across both lifecycles.
 
-The same separation applies for Linear self-host (`source = "linear"` AND `tracker = "linear"`), with one asymmetry: project-level **labels** (`prd-*`) drive the PRD lifecycle, because a PRD is a Linear Project and Projects carry their own status object rather than Issue workflow states; issue-level **workflow states** (`linear.workflow`) drive the build lifecycle; the sentinel feedback issue carries the issue-level `prd-intake-feedback` label. So on Linear the two lanes are not merely different vocabularies, they are different *mechanisms* — never move a PRD by state or an Issue by `status:*` label.
+The same separation applies for Linear self-host (`source = "linear"` AND `tracker = "linear"`), with one asymmetry: project-level **labels** (`prd-*`) drive the PRD lifecycle, because a PRD is a Linear Project and Projects carry their own status object rather than Issue workflow states; issue-level **workflow states** (`linear.workflow`) drive the build lifecycle; clarifying-question comments go on the Project itself via `commentCreate(input: { projectId, body })`, so the PRD lane needs no issue label of its own (`prd-intake-feedback` survives only to recognise the fabricated feedback issues earlier versions created). So on Linear the two lanes are not merely different vocabularies, they are different *mechanisms* — never move a PRD by state or an Issue by `status:*` label.
 
 ## Notion access (substrate ladder)
 

package/plugins/src/base/rules/reference/leaf-only-lifecycle.md

@@ -182,7 +182,7 @@ The env rungs are whatever the project configures for `done` — which is **env-
 
 Intermediate-env rollup and terminal native closure are distinct: a parent **rolls up to** an intermediate env (`On Dev`/`On Stg`) as its required leaves reach it, but native closure (next section) fires **only** at the production/terminal `done` value. A parent sitting at `On Stg` is correctly rolled up *and* still open.
 
-**Single-environment collapse (this repo).** Lisa's own deploy has only `main`/`production` (no dev/staging), so `done` is a single value, not a map. For GitHub, the build lifecycle collapses to one chain: `ready → claimed (in-progress) → done`. The rollup terminal state is simply `done`. This is the *collapsed* case of the generic rule, not a different rule — projects with more environments keep the env-keyed map.
+**Single-environment collapse (this repo).** The collapse is a property of the **resolution**, not of the declaration. `.lisa.config.json` declares `github.labels.build.done` as the generic **env-keyed map** — `dev: status:on-dev`, `staging: status:on-stg`, `production: status:done` — which is exactly the shape `lisa-setup-github` creates by default. What this repo lacks is deploy *branches*: `deploy.branches` maps only `production → main`, so `production` is the sole reachable rung and every merge this repo can make resolves to `status:done`. For GitHub the build lifecycle therefore runs one chain in practice: `ready → claimed (in-progress) → done`, and the rollup terminal state is `status:done`. Do not read the collapse as an absent map: code that reads the `done` role must still resolve the merged PR's base branch through `deploy.branches` and take that env's rung, in this repo as in any other — assuming a scalar here would read the wrong rung the moment a deploy branch is added. Projects with more deploy branches differ only in how many rungs are reachable, not in the declared shape.
 
 ## Terminal native closure
 

package/plugins/src/base/rules/reference/operational-hazards.md

@@ -0,0 +1,115 @@
+# Operational Hazards — reference
+
+Full contract behind the `operational-hazards` slug (CodySwannGT/lisa#3681). The eager rule carries
+the two commands; this is the reasoning, the tiers, and the boundary against doctrine.
+
+## The general property
+
+**A detector whose only failure mode is staying quiet cannot be audited.** A fan-out reaches the
+sessions alive at one instant. The sessions that were not alive receive nothing and are told
+nothing, so nobody — the sender included — can name who was missed.
+
+Measured on one machine in one hour: one session started 18 minutes after a warning it needed;
+another started 8 minutes after a different one; four more appeared and vanished entirely inside
+the hour. And the lanes most likely to collide are the ones that just started and are standing up
+fresh environments — so the warning that would have prevented the collision cannot reach the
+session that causes it, because that session does not exist yet.
+
+**The hole is unmeasurable, not merely growing.** Two sessions on the same machine, enumerating
+peers at the same moment, returned different rosters: one session appeared in one listing and had
+never appeared in four consecutive reads by the other. So "I enumerated the roster and checked the
+list" carries an unknown hole, and a fan-out audited against one session's view cannot be audited
+at all.
+
+## What the existing rule injector cannot do
+
+`inject-rules.sh` reads `CLAUDE_PLUGIN_ROOT/rules/eager` — the plugin root, not the project. A
+project cannot register anything there without editing an installed plugin, which the next apply
+overwrites. And it concatenates every `.md` unconditionally: no front matter, no date, no filter.
+Anything written there is injected on every start, permanently, until a human deletes the file.
+
+So the injector is the right *reach* and the wrong *store*. This ledger reuses the reach — the same
+two start events, plus the tool-result event — and supplies a project-owned store whose entries
+carry a condition something evaluates.
+
+## Why the expiry is the mechanism, not a convenience
+
+**The expiry is what separates a transient hazard from doctrine**, and it is the only reason the
+surface can be trusted with transient content: nobody has to remember to remove anything. A hazard
+surface without an expiry becomes the permanent-scripture problem, and a project that has watched
+that happen once will correctly refuse to use the surface again.
+
+The shape is deliberately the threshold-ratchet exemption's (CodySwannGT/lisa#3856) rather than a
+third scheme:
+
+- record the condition in a form something can evaluate — `until`, a `YYYY-MM-DD` day or an
+  ISO-8601 timestamp, live *through* the day named;
+- never let an unevaluable condition lapse into the permissive answer. An entry naming no evaluable
+  expiry — hand-written, or written before `until` existed — **still applies**, and is reported as
+  `unchecked` every time it is read.
+
+An expiry that lapses into "no longer shown" is worse than no expiry: it restores permanent
+scripture in reverse — the hazard vanishes — while every signal still reads healthy. That is why
+the writer refuses `--declare` without `--until`, and refuses an `until` it cannot parse, while the
+reader tolerates one and says so.
+
+## The inverse
+
+A hazard also ends before its expiry. A declaration nothing can void is the defect closed twice
+already — the QA-failure signal (CodySwannGT/lisa#3855) and the human gate (CodySwannGT/lisa#3852)
+— so `--lift` appends a void record naming what resolved it.
+
+Matching is **time-ordered**: a lift voids only a declaration that pre-dates it. A hazard
+re-declared after an earlier lift is therefore not born discharged, which is the unsafe direction
+#3852 records as the one this must not introduce. For the same reason the ledger union keeps the
+**newest** declaration for an id, not the first one read.
+
+## The ledger's two tiers
+
+- **`.lisa/HAZARDS.jsonl`**, committed — reaches every future reader of this project and merges by
+  git's built-in union driver. This is also the tier that answers "does `lisa apply` preserve it":
+  it is host-authored content under `.lisa/`, like the withdrawal tombstones beside it, and no
+  managed-file reconciliation writes it.
+- **`${LISA_STATE_HOME:-~/.lisa}/operational-hazards.jsonl`** — reaches sibling sessions in OTHER
+  worktrees on this machine *now*, which a committed file cannot do until it is merged and pulled.
+  For the fleet case above, this is the tier that matters.
+
+`--declare` and `--lift` write both. Reads are the union. Both files are append-only JSONL, so
+concurrent writers on their own branches reconstruct exactly under `merge=union`.
+
+## How a running session is reached
+
+`--session-start` delivers everything applying and stamps what the session was born knowing.
+`--hook` runs as a PostToolUse hook and announces only what changed since that stamp: a hazard
+declared while this session runs, and a **lift** of a hazard this session was told about. Both
+directions were measured — the provenance of #3681 is a session that was sent a lift for a hold it
+had never received.
+
+A missing stamp is deliberately silent. A session whose starting knowledge is unknown would
+otherwise be told every historical hazard, which degrades the mechanism into distrusting
+everything.
+
+The common path is cheap: when neither tier's `size:mtime` has moved, `--hook` exits after two
+`stat` calls without parsing anything. It fires on every tool call in every session, so anything
+expensive multiplies.
+
+## Surface parity
+
+The hook pair ships into every payload that carries the base hooks, and the injector fires on
+`SubagentStart` as well as `SessionStart` — which makes this better than a broadcast rather than
+merely equivalent, since a fan-out never reaches a subagent at all.
+
+Surfaces with no PostToolUse runtime get the start-event half and `--list`. That is the honest
+split: **the durable half — reaching every session that starts later — is closed everywhere the
+hook installs. The already-running half depends on a tool-result event, so where there is none, a
+running session is reached only when it runs `--list`.**
+
+## What deliberately does not belong here
+
+Anything that should still be true next month. A hazard is a condition of *this machine, this
+branch, this hour*: a port another lane holds, a resource one run has saturated, a command that
+dumps more than you asked for, a gate red for an environmental reason. If the entry would want
+renewing when it expires, it was never a hazard — promote it through the learnings ladder to a rule
+or an executable control, and let the entry lapse.
+
+Not a severity taxonomy, not a notification system, and not a change to how eager rules work.

package/plugins/src/base/rules/reference/work-item-trailer-definition.md

@@ -0,0 +1,129 @@
+# Work-Item Trailer Definition — What Counts As One, And Which Reader Is Authoritative
+
+Read this **before** writing anything that reads, counts, audits, or verifies a
+`Work-Item:` reference in a commit message or a pull-request body. There are two
+plausible definitions of "a `Work-Item:` trailer", they disagree about real
+commits in this fleet, and the obvious tool — git's own trailer parser — is the
+wrong one.
+
+## The two definitions
+
+**Definition A — git's.** `git log --format='%(trailers:key=Work-Item)'` and
+`git interpret-trailers --parse` read only the **final contiguous block** of
+`Key: value` lines. Any non-trailer line after a trailer ends that block, and
+everything above it becomes invisible to the parser.
+
+**Definition B — Lisa's.** A `Work-Item:` line is any line of the **whole
+message** whose first character begins the ASCII-case-insensitive prefix
+`Work-Item:` at **column zero**, with a non-empty value after it. Position in
+the message carries no information. Repeats of the same reference are accepted.
+
+## Definition B is authoritative. This is settled, not open.
+
+Definition A was tried and abandoned in CodySwannGT/lisa#2672: it reported
+`found 0` about messages that plainly contained a trailer, because a blank line
+before the `Co-Authored-By:` attribution block — or a bot appending release
+notes below it — was enough to end the block. Making Definition A work would
+require that nothing ever append to a commit message, which is precisely the
+assumption #2672 recorded as false.
+
+The `🤖 Generated with Claude Code` convention puts boilerplate **after** the
+trailer by default, so under Definition A a large share of this repository's own
+commits read as untrailered. **The failure is the common case, not the edge
+case.**
+
+### Measured, not asserted
+
+Both definitions run over real history, non-merge commits, counting only commits
+where at least one definition finds a reference:
+
+| Range | Commits naming an item | Agree | A finds none, B finds one | Other disagreement |
+|---|---|---|---|---|
+| A single multi-agent branch | 51 | 4 | **47 (92%)** | 0 |
+| Full default-branch history | 1,730 | 1,248 | **477 (27.6%)** | 5 |
+
+The five "other" disagreements are commits carrying a bare `Work-Item: #1234`
+above the block as well as the canonical reference inside it; B sees both, A
+sees only the one in the final block.
+
+**The undercount is clean, plausible and well-formed**, which is why it survives
+review. `%(trailers)` printing nothing is genuinely convincing evidence until
+you know this rule exists — which is why at least three separate audits have
+shipped confident, specific, wrong findings from it, including an instruction to
+amend a commit whose trailer was fine.
+
+## Do not reimplement it. Import it.
+
+`workItemLines(message)` and `soleWorkItem(text, contract, subject)` are
+exported from the shipped `scripts/lisa-work-item.mjs`. They are the definition.
+A second parser is a second answer to "which item is this?", and two answers is
+the state this rule exists to end.
+
+```js
+import { workItemLines } from "./lisa-work-item.mjs";
+```
+
+`workItemLines` returns every value found, in order of appearance, untouched
+beyond trimming. `soleWorkItem` canonicalizes them against the tracker contract
+and refuses a text naming two **different** items.
+
+## What each layer owns, and why the shape filter stays at the call site
+
+`workItemLines` deliberately does **not** validate the shape of a value. It
+answers "what does this text say?" — nothing more. Canonicalization,
+repository-membership, and the refusal of the full issue-URL form all live in
+`canonicalizeRef`, above it.
+
+That split is load-bearing and must not be converged away. A reader that
+filtered malformed values out during the scan would make a bad value
+**invisible** rather than **refused**: `Work-Item: https://github.com/o/r/issues/7`
+would read as no trailer at all, and the gate would report "no Work-Item trailer
+anywhere in the commit message" about a message containing exactly one, which is
+the #2672 failure re-created one layer down. The reader sees everything; the
+layer above decides what is acceptable.
+
+The consequence a caller must respect: **a filter you apply to `workItemLines`'
+output is your filter, not the definition.** State what it drops.
+
+## Column zero is part of the definition
+
+The prefix is anchored at column zero, so `# Work-Item: …` in a comment never
+matches, and neither does a unified-diff line — every one of those carries a
+space, `+` or `-` in that column. A reader that tolerates leading whitespace
+matches the **context line of a verbose commit's own diff**. Measured over full
+default-branch history: 2,059 `Work-Item:` lines at column zero, **zero**
+indented ones. There is no real input that needs the looser form and one class
+of false positive that needs the anchor.
+
+The prefix is matched with a non-Unicode `/i` regex rather than
+`toLowerCase().startsWith(…)` on purpose: `toLowerCase()` applies full Unicode
+case mapping, so U+212A KELVIN SIGN would fold to `k` and `WorK-Item:` written
+with it would be accepted — a form this has never accepted.
+
+## Testing a trailer reader
+
+**A checker exercised only against well-formed messages passes under either
+definition.** That is why three audits shipped with the bug undetected. The only
+input that distinguishes them is a `Work-Item:` line sitting **above** a
+non-trailer line, and any test of a trailer reader must pin one:
+
+```
+feat: something
+
+Work-Item: owner/repo#123
+
+🤖 Generated with Claude Code
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+Under Definition A this message has no work item. Under Definition B — the
+authoritative one — it names exactly one. Assert **present**.
+
+## Related
+
+- `tracked-work` (eager) — the obligation to carry the ref on every commit
+- `settled-decisions` — why this is recorded as closed rather than re-litigated
+- CodySwannGT/lisa#2672 — where Definition A was tried and abandoned
+- CodySwannGT/lisa#3747 — where the decision was made discoverable
+- CodySwannGT/lisa#3859 — the same undercount measured on the audit side