feat(state-line-guard): deny status=done while commits are unpushed

ORDRE 42 (operator, 2026-08-16). Two sessions had their push refused by the
UFW rate limit on port 22, reported that honestly in the coord inbox, and
wrote status=done anyway: board line green, one commit unpushed, published
surface 404. `done` meant "the session finished" where every reader takes it
to mean "the work landed" -- and since `done` drops a repo from the board
plan, `morning --say <repo>` could not reach either of them.

The deny sits on the WRITE, not on session end. Measured against the official
hooks docs rather than assumed: Stop fires "once per turn" with no signal
marking the last one, and its exit 2 "prevents Claude from stopping", so a
repo that genuinely cannot push would get a session that will not end;
SessionEnd is the once-per-session event and cannot block at all.

Fails open on every git uncertainty (no upstream, detached HEAD, missing
remote-tracking ref, not a repo) -- 8 of 44 repos on the real tree have no
upstream, one already status=done. Compares against the branch's own
upstream, never a hardcoded origin/main (three repos sit on master). Selects
the board line with board.sh's own anchor, so prose saying status=done never
triggers it. status=blocked and status=in-progress stay writable in the same
single edit, so the deny can never wedge a session.

state-line-guard-selftest.sh section 10, 17 checks (23 -> 40), including the
mandatory known-positive: status=done with everything pushed still allows.
Both outcomes also verified against real repos -- app-creator (1 unpushed)
denied, repo-mailbox (clean) allowed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01P4LMWBQGmufmBU6UdvJZ2E

hooks/scripts/pre-state-line-guard.mjs

@@ -52,9 +52,65 @@
 //     being created oversized.
 //   - Block: stderr + exit 2
 //   - Allow: exit 0, no output
+//
+// SECOND INVARIANT (ORDRE 42, operator decision 2026-08-16): the same projected
+// content must not claim `status=done` in its board line while the repo holds
+// commits that are not on the branch's upstream. Measured that day: two
+// sessions had their push refused by the UFW rate limit on port 22, said so
+// honestly in the coord inbox, and wrote status=done anyway - board line green,
+// one commit unpushed, published surface 404. `done` meant "the session
+// finished" where every reader takes it to mean "the work landed", and because
+// `done` removes a repo from the board plan, `morning --say <repo>` could not
+// reach either of them: one defect hid the other.
+//
+// WHY THE WRITE PATH AND NOT SESSION END. The order offered three directions
+// and named session-end (B) as the recommendation. B does not exist in the form
+// it assumes, measured against the official hooks docs 2026-08-16:
+//   - Stop fires "once per turn", not once when the session ends, and there is
+//     no signal telling a Stop hook that this turn is the last. Its premise
+//     ("by then commit and push are done") holds only for the final turn; on
+//     every earlier turn it would block live work, and exit 2 there
+//     "prevents Claude from stopping, continues the conversation" - so a repo
+//     that genuinely cannot push (the rate limit that caused the incident)
+//     gets a session that will not end.
+//   - SessionEnd is the once-per-session event, and it cannot block at all:
+//     "Can block? No", exit 2 "shows stderr to user only". It can nag after the
+//     fact, which is what the order explicitly did not want.
+// C (warn on write, deny at session end) inherits B's half without gaining
+// anything a single deny does not already give. So: the write path, which is
+// where the false claim is actually made.
+//
+// The false-positive trap the order warned about is real but bounded. STATE.md
+// is written BEFORE the session's final commit, so a session that batches its
+// pushes has unpushed commits at exactly this moment. Two things keep that from
+// biting: the global git rule already requires a push immediately after every
+// commit (so a compliant session sits at zero unpushed here - measured on the
+// real tree 2026-08-16, 43 of 44 repos carrying a STATE.md had nothing
+// unpushed, the one exception being status=blocked and honest), and the deny is
+// escapable by telling the truth rather than only by pushing: status=blocked
+// and status=in-progress are always writable, in the same single edit.
+//
+// NO RATCHET HERE, deliberately, and the difference from the line-count rule
+// above is the reason. A file already over the line limit needs many writes to
+// come back under it, so denying every intermediate step would make trimming
+// impossible; a false `done` is corrected by changing one token in the write
+// that is already being made. A "only deny the transition into done" rule was
+// considered and rejected outright: the common shape is a repo that ended
+// `done` last session and rewrites `done` this session, which such a rule would
+// wave through - precisely the case the order exists to stop.
+//
+// FAILS OPEN on every git uncertainty (no upstream, detached HEAD, missing
+// remote-tracking ref, not a repo, git absent or slow). A confident denial
+// built on a measurement that did not happen is the worse error, and 8 of the
+// 44 STATE.md repos on the real tree have no upstream at all - one of them
+// already status=done. The hole this leaves is named in the selftest (10.6).
+//
+// The file keeps its name: both invariants are properties of a line in
+// STATE.md, and one hook process per Write/Edit stays cheaper than two.
 
 import { readFileSync } from 'node:fs';
-import { basename } from 'node:path';
+import { basename, dirname } from 'node:path';
+import { execFileSync } from 'node:child_process';
 
 const MAX_LINES = 120;
 
@@ -121,6 +177,52 @@ if (toolName === 'Write') {
   currentLines = countLines(current);
 }
 
+// The board line is selected with board.sh's own anchor (grep -m1 '^<!-- board:'),
+// so the guard judges the exact line the board renders - or neither of them
+// finds one. Prose is therefore never a trigger, which matters because a
+// STATE.md documenting this very guard writes the literal string status=done.
+function boardLineOf(text) {
+  const m = text.match(/^<!-- board:[^\n]*/m);
+  return m ? m[0] : null;
+}
+
+// board.sh's `sed -n 's/.*status=\([a-z-]*\).*/\1/p'` is greedy, so it reads the
+// LAST status= on the line; mirror that rather than the first. The value is
+// then compared to the exact vocabulary token: board.sh's prefix defect (F3+F4,
+// queued separately) reads done2 as done, and copying that here would pin the
+// defect instead of the vocabulary.
+function boardStatusOf(line) {
+  const all = line.match(/status=[^;>\s]*/g);
+  return all ? all[all.length - 1].slice('status='.length) : null;
+}
+
+function git(dir, args) {
+  return execFileSync('git', ['-C', dir, ...args], {
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: 5000,
+  }).trim();
+}
+
+// Returns { branch, upstream, count, subjects } when the repo demonstrably has
+// commits the upstream does not, or null in every other case INCLUDING every
+// case it could not measure.
+function unpushedOf(dir) {
+  try {
+    const upstream = git(dir, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}']);
+    const count = parseInt(git(dir, ['rev-list', '--count', '@{u}..HEAD']), 10);
+    if (!Number.isFinite(count) || count < 1) return null;
+    return {
+      branch: git(dir, ['rev-parse', '--abbrev-ref', 'HEAD']),
+      upstream,
+      count,
+      subjects: git(dir, ['log', '--format=%h %s', '-n', '5', '@{u}..HEAD']),
+    };
+  } catch {
+    return null;
+  }
+}
+
 const lines = countLines(projected);
 if (lines > MAX_LINES && lines > currentLines) {
   process.stderr.write(
@@ -133,4 +235,38 @@ if (lines > MAX_LINES && lines > currentLines) {
   process.exit(2);
 }
 
+const boardLine = boardLineOf(projected);
+if (boardLine && boardStatusOf(boardLine) === 'done') {
+  const unpushed = unpushedOf(dirname(filePath));
+  if (unpushed) {
+    const one = unpushed.count === 1;
+    const noun = one ? 'commit' : 'commits';
+    const verb = one ? 'is' : 'are';
+    const indented = unpushed.subjects.split('\n').map((l) => `    ${l}`).join('\n');
+    const more = unpushed.count > 5 ? `    ... and ${unpushed.count - 5} more\n` : '';
+    process.stderr.write(
+      `\n[repo-mailbox] STATE DONE GUARD: ${toolName} blocked\n` +
+      `  File: ${filePath}\n` +
+      `  Board line: ${boardLine}\n` +
+      `  Branch: ${unpushed.branch} -> ${unpushed.upstream}\n` +
+      `  Unpushed: ${unpushed.count} ${noun}, present only in this checkout\n` +
+      `${indented}\n${more}\n` +
+      `status=done claims the WORK LANDED, not that the session finished. It has\n` +
+      `not landed: the ${noun} above ${verb} not on ${unpushed.upstream}, so anything\n` +
+      `reading the board -- or the published remote -- sees green over nothing.\n\n` +
+      `Do one of these, then write STATE.md again:\n` +
+      `  git push origin ${unpushed.branch}\n` +
+      `      -- if it goes through, status=done is true\n` +
+      `  status=blocked\n` +
+      `      -- if the push is refused (SSH rate limit: UFW allows 6 connections\n` +
+      `         per 30s on port 22, and the chain ends in REJECT)\n` +
+      `  status=in-progress\n` +
+      `      -- if the work simply is not finished\n\n` +
+      `Only the board line's status token is judged here; nothing else in this\n` +
+      `write is being questioned.\n`
+    );
+    process.exit(2);
+  }
+}
+
 process.exit(0);