@oneie/claude 0.7.0 → 0.8.0

package/hooks/scripts/governor-escape.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# GOVERNOR-ESCAPE — PreToolUse(Bash): an executor cannot escape the governor.
+#
+# WHY (measured 2026-08-18): several sessions each ran the full verify on one
+# 10-core/24GB Mac. Six tsc and three vitest pools ran at once -> load 57, swap
+# 15.7/16 GB. Starved by paging, each gate took 18 MINUTES instead of ~2, so
+# sessions hit their Bash timeout and launched MORE. The box got slower the
+# harder it was pushed. gate-run.sh (slot + wall-bound + group-reap) is the fix.
+#
+# Four doors bypass all of it, and an agent taking one is invisible to every
+# arbiter in factory-do.md's § Concurrency:
+#   verify:raw · test:raw · a directly-typed vitest · GOVERN_DISABLE=1 / CI=1
+#
+# They exist for a HUMAN who means it. This hook is about an EXECUTOR reaching
+# for one. hook:load-guard already refuses an ungoverned heavy command -- but
+# only once load > 2x cores, free mem < 10%, or 3 gates are already burning.
+# That is a check that fires AFTER the damage. This one fires INSTEAD of it.
+#
+# WHY A HOOK AND NOT A POST-HOC CHECK: the Bash tool does not carry shell state
+# between calls, so an `export GOVERN_DISABLE=1` in one call is gone by the
+# next. An env bypass therefore has to appear INLINE in the command string --
+# which is precisely the surface a PreToolUse hook reads. For that class of
+# escape prevention is not merely stronger than detection, it is complete.
+# (Honest limit: this reads the command string, not an inherited environment.
+# A GOVERN_DISABLE exported into the whole session's env is out of its view.)
+#
+# What counts as an escape lives in ONE place, shared with the checker:
+#   .claude/hooks/lib/governor-escape-match.sh
+# Proof, both directions (it bites / it does not false-positive):
+#   bash .claude/scripts/governor-escape-check.sh
+#
+# Disable (the deliberate human override): ECC_DISABLED_HOOKS=hook:governor-escape
+
+# shellcheck source=lib/hook.sh
+source "$CLAUDE_PROJECT_DIR/.claude/hooks/lib/hook.sh"
+is_hook_disabled "hook:governor-escape" && exit 0
+# shellcheck source=lib/governor-escape-match.sh
+source "$CLAUDE_PROJECT_DIR/.claude/hooks/lib/governor-escape-match.sh"
+
+PAYLOAD="${1:-}"
+# Claude Code delivers the hook payload on STDIN; argv stays first so any
+# caller that passes it positionally still works. Bounded read: a bare $(cat)
+# would hang forever on a tty or an idle pipe, freezing every Bash call.
+if [[ -z "$PAYLOAD" && ! -t 0 ]]; then
+  IFS= read -r -d '' -t 2 PAYLOAD <&0 || true
+fi
+[[ -z "$PAYLOAD" ]] && exit 0
+
+TOOL=$(printf '%s' "$PAYLOAD" | jq -r '.tool_name // empty' 2>/dev/null)
+[[ "$TOOL" == "Bash" ]] || exit 0
+
+CMD=$(printf '%s' "$PAYLOAD" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[[ -z "$CMD" ]] && exit 0
+
+KIND=$(gov_escape_kind "$CMD") || exit 0
+
+case "$KIND" in
+  env)    WHAT="an inline GOVERN_DISABLE= / CI= in front of a gate. gate-run.sh:26
+execs straight through on either, so the slot, the wall-clock bound and the
+process-group reap are all skipped." ;;
+  raw)    WHAT="a \`:raw\` package script (verify:raw / test:raw). Those exist to
+bypass the cap -- that is their whole definition." ;;
+  vitest) WHAT="vitest invoked directly. It takes no slot, has no wall-clock
+bound, and its forks reparent to launchd if the session dies." ;;
+esac
+
+MSG="[governor-escape] That command bypasses the machine governor.
+
+Detected: $WHAT
+
+Measured 2026-08-18, before the governor existed: concurrent ungoverned gates
+took this box to load 57 and swap 15.7/16 GB, and each gate ran 18 minutes
+instead of ~2. The box gets SLOWER the harder it is pushed, so one agent's
+shortcut is every other agent's stall.
+
+Run the same thing governed -- it queues for a free slot instead of piling on:
+
+  bash .claude/scripts/gate-run.sh test -- bunx vitest run <path>
+  bash .claude/scripts/gate-run.sh verify -- bun run verify
+
+The cheap rungs of the gate ladder are still cheap: gate-run.sh is re-entrant
+and returns immediately when a slot is free, so a targeted 0.4s test stays a
+targeted 0.4s test.
+
+Or use the governed package scripts, which already do this:
+  bun run verify:fast     (the dev lane)
+  bun run verify          (the review gate)
+
+See what is holding the box:
+  bash .claude/scripts/machine-check.sh --watch
+
+Deliberate human override (session-level, on purpose, and visible):
+  ECC_DISABLED_HOOKS=hook:governor-escape"
+
+jq -nc --arg r "$MSG" '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":$r}}'
+exit 0

package/hooks/scripts/load-guard.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+# LOAD-GUARD — PreToolUse(Bash): refuse to pile a heavy gate onto a thrashing box.
+#
+# WHY (measured 2026-08-18): several sessions each ran `bun run verify`
+# (tsc --noEmit + vitest over 875 files) at the same time on a 10-core/24GB Mac.
+# Six tsc and three vitest pools ran concurrently -> load 57, swap 15.7/16 GB,
+# ~26 MB/s of swapins. Starved by paging, each gate took 18 min instead of ~2,
+# so sessions hit their Bash timeout and launched MORE. The box got slower the
+# harder it was pushed.
+#
+# package.json's verify/test/check now route through gate-run.sh, but a session
+# can still type `bunx tsc --noEmit` or `vitest run` straight into Bash and
+# bypass the governor entirely (observed: pid 88114). This hook is the backstop
+# for that path — it is the difference between a convention and a guarantee.
+#
+# Rule: a heavy, UNGOVERNED command is denied while the machine is already
+# saturated. It is never denied on a healthy box, and never for the governed
+# form (which queues by design rather than piling on).
+#
+# Disable: ECC_DISABLED_HOOKS=hook:load-guard
+
+source "$CLAUDE_PROJECT_DIR/.claude/hooks/lib/hook.sh"
+is_hook_disabled "hook:load-guard" && exit 0
+
+PAYLOAD="${1:-}"
+# Claude Code delivers the hook payload on STDIN; argv stays first so any
+# caller that passes it positionally still works. Bounded read: a bare $(cat)
+# would hang forever on a tty or an idle pipe, freezing every Bash call.
+if [[ -z "$PAYLOAD" && ! -t 0 ]]; then
+  IFS= read -r -d '' -t 2 PAYLOAD <&0 || true
+fi
+[[ -z "$PAYLOAD" ]] && exit 0
+TOOL=$(printf '%s' "$PAYLOAD" | jq -r '.tool_name // empty' 2>/dev/null)
+[[ "$TOOL" == "Bash" ]] || exit 0
+CMD=$(printf '%s' "$PAYLOAD" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[[ -z "$CMD" ]] && exit 0
+
+# Already governed (gate-run.sh queues rather than piling) — always allow.
+printf '%s' "$CMD" | grep -q 'gate-run\.sh' && exit 0
+# Explicit opt-out for a deliberate full-throughput run.
+[[ "${GOVERN_DISABLE:-0}" == "1" ]] && exit 0
+
+# Heavy = spawns a long multi-core, multi-hundred-MB job.
+# Heavy only when INVOKED, never when merely NAMED. The previous pattern
+# matched the bare word anywhere in the command string, so `sed -n 1,60p
+# vitest.config.ts` and a `git commit -m` whose message quoted `bun run
+# verify` were both refused as though they were gates. Reading a config is
+# not running a suite; both cost a retry through a temp file while fixing the
+# engine on 2026-08-31.
+#
+# Anchor to command POSITION: start of the command or just after a shell
+# operator, allowing leading env assignments and a bunx/npx/bun/npm runner.
+# This decides only WHETHER the command is a heavy gate -- it still falls
+# through to the saturation check below, which is what actually denies.
+HEAVY_POS='(^|[;&|(]|&&|\|\|)[[:space:]]*([A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*[[:space:]]+)*'
+_is_heavy=0
+printf '%s' "$CMD" | grep -qE "${HEAVY_POS}((bunx|npx|bun|npm)[[:space:]]+)?(tsc[[:space:]]+--noEmit|vitest([[:space:]]+run)?|astro[[:space:]]+check|playwright[[:space:]]+test)" && _is_heavy=1
+printf '%s' "$CMD" | grep -qE "${HEAVY_POS}(bun|npm)[[:space:]]+run[[:space:]]+(verify|test|typecheck|check)(:[a-z]+)?([[:space:]]|$)" && _is_heavy=1
+[ "$_is_heavy" = "1" ] || exit 0
+# `bun run test:raw` etc. are the deliberate escape hatches — still guarded, since
+# their whole point is bypassing the cap.
+
+CORES=$(sysctl -n hw.ncpu 2>/dev/null || echo 8)
+LOAD1=$(uptime | sed -E 's/.*load averages?: //' | awk '{print int($1)}')
+# FREE is the share of RAM genuinely available. It used to read memory_pressure's
+# "free percentage", which counts file cache, purgeable and already-compressed
+# pages as free: measured 2026-09-03, that said 74% while vm_stat said 1.3% and
+# 9.4 GB sat in swap — so this guard's MEMORY arm could not fire on a thrashing
+# box; only its load arm ever did. gate_mem_avail_mb is the honest quantity —
+# two vm_stat/sysctl reads, no ps, no sleep, nothing on stdin (see the bounded
+# -read scar above). Unreadable probe -> 100, i.e. this arm stays silent.
+#
+# The probe runs in a SUBSHELL with `set +eu`, and its failure is swallowed. A
+# PreToolUse hook that dies mid-stream emits no deny decision, so the heavy gate
+# proceeds — a guard that crashes fails OPEN. lib/hook.sh sets no -e/-u today,
+# but nothing stops it from doing so tomorrow, and this arm must not be the
+# reason a block silently stops happening. Anything other than a plain integer
+# leaves FREE at 100, i.e. this arm stays silent.
+FREE=100
+_gv_lib="$CLAUDE_PROJECT_DIR/.claude/scripts/lib/govern.sh"
+if [[ -r "$_gv_lib" ]]; then
+  _pct=$( set +eu
+          # shellcheck source=../scripts/lib/govern.sh
+          source "$_gv_lib" 2>/dev/null || exit 0
+          _a=$(gate_mem_avail_mb 2>/dev/null) || exit 0
+          _t=$(( $(sysctl -n hw.memsize 2>/dev/null || echo 0) / 1048576 ))
+          [ -n "$_a" ] && [ "$_t" -gt 0 ] && echo $(( _a * 100 / _t ))
+          exit 0 ) 2>/dev/null
+  [[ "$_pct" =~ ^[0-9]+$ ]] && FREE="$_pct"
+fi
+
+# How many heavy gates are already burning cores right now?
+RUNNING=$(ps -Ao command= 2>/dev/null | grep -cE '(\.bin/tsc --noEmit|\.bin/vitest run|astro check)' || echo 0)
+
+# Thresholds are env-tunable so they can be exercised in both directions —
+# a guard that has only ever been seen to fire is an unproven guard.
+LOAD_FACTOR="${GUARD_LOAD_FACTOR:-2}"
+MIN_FREE="${GUARD_MIN_FREE_PCT:-10}"
+MAX_RUNNING="${GUARD_MAX_RUNNING:-3}"
+
+SAT=""
+[[ "$LOAD1" -gt $(( CORES * LOAD_FACTOR )) ]] && SAT="load ${LOAD1} on ${CORES} cores"
+[[ "$FREE" -lt "$MIN_FREE" ]]                 && SAT="${SAT:+$SAT; }free memory ${FREE}%"
+[[ "$RUNNING" -ge "$MAX_RUNNING" ]]           && SAT="${SAT:+$SAT; }${RUNNING} heavy gates already running"
+[[ -z "$SAT" ]] && exit 0           # healthy box — proceed
+
+MSG="[load-guard] This machine is saturated ($SAT).
+
+Starting another ungoverned build gate makes it slower, not faster: the box is
+already paging, so every running gate takes ~10x longer and yours would too.
+
+Run it through the governor instead — it queues for a free slot rather than
+piling on, and kills its whole process group if it overruns:
+
+  bash .claude/scripts/gate-run.sh verify -- <your command>
+
+Or use the governed package script, which already does this:
+  bun run verify     (in one.ie/web)
+
+See what is holding the box:
+  bash .claude/scripts/machine-check.sh --watch
+
+Deliberate override:  GOVERN_DISABLE=1 <command>
+Disable this hook:    ECC_DISABLED_HOOKS=hook:load-guard"
+
+jq -nc --arg r "$MSG" '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":$r}}'
+exit 0

package/hooks/scripts/post-edit-check.sh

@@ -1,48 +1,55 @@
 #!/bin/bash
-# POST-EDIT CHECK — The deterministic sandwich around every file change
+# POST-EDIT-CHECK — PostToolUse(Write|Edit): two cheap reads, never a block.
 #
-# Runs after Write/Edit. Checks the touched file with biome.
-# Non-blocking (exit 0) — reports issues as warnings, doesn't halt.
-# The W4 verify step does the blocking check.
-# Emits hook:post-edit:{ok,warn} signal per Rule 1 (see .claude/skills/signal.md).
+#   1. .claude/workflows/*.js  → wf-check.mjs. A syntax error here does not fail
+#      loudly — it stops the workflow launching at all — and `node --check`
+#      exits 0 on any file that starts with `export`.
+#   2. *.ts/*.tsx/*.js/*.jsx    → biome, ONLY when the repo carries a biome
+#      config. Measured 2026-09-05: biome was not installed, so every edit
+#      printed a false "biome: ? issues" line into the model's context and
+#      emitted a warn signal for a tool that never ran. An absent tool is
+#      silent; it is never a verdict.
+#
+# Emits hook:post-edit:{ok,warn} (Rule 1). Exit 0 always — inform, don't gate.
 
 # shellcheck source=lib/signal.sh
 source "$CLAUDE_PROJECT_DIR/.claude/hooks/lib/signal.sh"
 
 FILE=$(echo "$1" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null)
+[[ -z "$FILE" ]] && exit 0
+[[ "$FILE" =~ \.(ts|tsx|js|jsx)$ ]] || exit 0
+BASE=$(basename "$FILE")
 
-# Only check .ts/.tsx/.js/.jsx files
-if [[ -z "$FILE" ]] || [[ ! "$FILE" =~ \.(ts|tsx|js|jsx)$ ]]; then
-  exit 0
-fi
-
-# Dynamic workflow scripts fail SILENTLY — a syntax error doesn't error, it stops
-# the workflow from launching at all. biome won't catch the two structural traps
-# (a second top-level export; a missing `meta` block), and `node --check` exits 0
-# for any file starting with `export`. wf-check parses the body as the runtime
-# does. Non-blocking, per this hook's contract — but loud, because the default
-# failure mode is silence.
+# 1 — workflow scripts
 if [[ "$FILE" == *".claude/workflows/"*.js ]]; then
   if ! WF=$(cd "$CLAUDE_PROJECT_DIR" && node .claude/scripts/wf-check.mjs "$FILE" 2>&1); then
     echo "wf-check: $(echo "$WF" | grep FAIL || echo "$WF")" >&2
     echo "wf-check: this workflow will NOT launch until fixed" >&2
-    emit_signal "hook:post-edit:warn" -1 "file=$(basename "$FILE") wf-check=fail"
+    emit_signal "hook:post-edit:warn" -1 "file=$BASE wf-check=fail"
     exit 0
   fi
-  emit_signal "hook:post-edit:ok" 1 "file=$(basename "$FILE") wf-check=ok"
+  emit_signal "hook:post-edit:ok" 1 "file=$BASE wf-check=ok"
+  exit 0
 fi
 
-# Quick biome lint on the single file (non-blocking)
-RESULT=$(cd "$CLAUDE_PROJECT_DIR" && bun biome check "$FILE" 2>&1)
-EXIT=$?
+# 2 — biome, only if the tree actually configures it
+_biome_root() {
+  local d; d=$(dirname "$FILE")
+  while [[ "$d" != "/" && "$d" != "." ]]; do
+    [[ -f "$d/biome.json" || -f "$d/biome.jsonc" ]] && { printf '%s' "$d"; return 0; }
+    d=$(dirname "$d")
+  done
+  return 1
+}
+ROOT=$(_biome_root) || exit 0
+BIOME="$ROOT/node_modules/.bin/biome"
+[[ -x "$BIOME" ]] || exit 0
 
-BASE=$(basename "$FILE")
-if [ $EXIT -ne 0 ]; then
-  ISSUES=$(echo "$RESULT" | grep -c "━━━" 2>/dev/null || echo "?")
-  echo "biome: ${ISSUES} issues in $BASE" >&2
-  emit_signal "hook:post-edit:warn" -0.5 "file=$BASE issues=$ISSUES"
-else
+if RESULT=$("$BIOME" check "$FILE" 2>&1); then
   emit_signal "hook:post-edit:ok" 1 "file=$BASE"
+else
+  ISSUES=$(echo "$RESULT" | grep -c "━━━" 2>/dev/null || echo 0)
+  echo "biome: ${ISSUES} issue(s) in $BASE" >&2
+  emit_signal "hook:post-edit:warn" -0.5 "file=$BASE issues=$ISSUES"
 fi
-
-exit 0  # Never block — just inform
+exit 0

package/hooks/scripts/session-start.sh

@@ -1,94 +1,35 @@
-#!/usr/bin/env bash
-# SESSION-START — surface unaddressed proposals + module-specific context.
+#!/bin/bash
+# SESSION-START — one job: reclaim what a dead session left behind, then tell
+# the world a session began.
 #
-# Closes the loop with stop-reflect.sh: stop emits proposals into
-# .claude/improvements.queue.md; this surfaces them at next session start so
-# they don't rot. Article calls this the self-improving harness pattern.
+# `_gv_reap` only fires when someone CONTENDS for a lock, so a session that died
+# holding a governor slot would shrink GOVERN_MAX_GATES until the next contender
+# happened along; region claims evaporate the same way. Sweep both here. Silent
+# unless something was actually reclaimed.
 #
-# Also prints the relevant skill list for the most recently touched module,
-# so dev context loads dynamically rather than every-session.
+# What this hook no longer does (removed 2026-09-05, each measured): a find+stat
+# over eight modules for a "hot module" hint (5.8s of the session's first
+# prompt, decorative), and a count of .claude/improvements.queue.md proposals
+# (a queue nothing consumed — 445 unaddressed, zero git history of a drain).
 #
-# Output is brief — every line costs context.
+# Emits hook:session-start:ok and world session:start (Rule 1).
 
 # shellcheck source=lib/signal.sh
 source "$CLAUDE_PROJECT_DIR/.claude/hooks/lib/signal.sh"
-
 cd "$CLAUDE_PROJECT_DIR" || exit 0
 
-QUEUE="$CLAUDE_PROJECT_DIR/.claude/improvements.queue.md"
-PROPOSAL_COUNT=0
-
-# Count unaddressed proposals (every "-" bullet under a session header)
-if [ -f "$QUEUE" ]; then
-  PROPOSAL_COUNT=$(grep -c '^- \*\*' "$QUEUE" 2>/dev/null || echo 0)
+SWEPT=0; CLAIMS_SWEPT=0
+if [ -f "$CLAUDE_PROJECT_DIR/.claude/scripts/lib/govern.sh" ]; then
+  . "$CLAUDE_PROJECT_DIR/.claude/scripts/lib/govern.sh" 2>/dev/null || true
+  SWEPT=$(gate_sweep_stale 2>/dev/null || echo 0)
+  CLAIMS_SWEPT=$(claim_sweep 2>/dev/null || echo 0)
 fi
 
-# Detect most-recently touched module — use mtime on a stable per-module marker.
-# Falls back silently if nothing identifiable.
-HOT_MODULE=""
-HOT_HINT=""
-
-# Parallel arrays — bash 3.2 compatible (macOS default).
-MODULES=(
-  "one.ie/web"
-  "agents"
-  "api"
-  "packages/sdk"
-  "packages/mcp"
-  "packages/cli"
-  "sync"
-  "backup"
-)
-# `/name` = a registered directory skill, invocable via the Skill tool.
-# `name.md` = a flat file under .claude/skills/ — canon, but NOT registered in
-# this tree, so it cannot be invoked by name. Read it by path. (The published
-# oneie-claude plugin registers these, because sync-claude-mirror.sh converts
-# each flat file into <name>/SKILL.md on the way out.)
-HINTS=(
-  "/astro · /react19 · /shadcn · dev.md · build.md"
-  "cloudflare.md · /ai-sdk · signal.md"
-  "cloudflare.md · /typedb · signal.md"
-  "typecheck.md · signal.md (substrate verbs)"
-  "typecheck.md · MCP server"
-  "typecheck.md · CLI bins"
-  "cloudflare.md (Scheduled Worker)"
-  "cloudflare.md (Scheduled Worker)"
-)
-
-NEWEST_TS=0
-i=0
-while [ $i -lt ${#MODULES[@]} ]; do
-  module="${MODULES[$i]}"
-  if [ -d "$module" ]; then
-    TS=$(find "$module" -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.astro' -o -name '*.md' \) \
-      -not -path '*/node_modules/*' -not -path '*/dist/*' -not -path '*/.wrangler/*' \
-      2>/dev/null | head -200 | xargs -I{} stat -f '%m' {} 2>/dev/null | sort -rn | head -1)
-    if [ -n "$TS" ] && [ "$TS" -gt "$NEWEST_TS" ]; then
-      NEWEST_TS=$TS
-      HOT_MODULE=$module
-      HOT_HINT="${HINTS[$i]}"
-    fi
-  fi
-  i=$((i + 1))
-done
-
-# Render — keep it short. Only print if there's something to say.
 OUT=""
+[ "${SWEPT:-0}" -gt 0 ] 2>/dev/null && OUT+="🧹 reclaimed ${SWEPT} stale build slot(s) from a dead session\n"
+[ "${CLAIMS_SWEPT:-0}" -gt 0 ] 2>/dev/null && OUT+="🧹 reclaimed ${CLAIMS_SWEPT} region claim(s) from a dead worker\n"
+[ -n "$OUT" ] && { echo ""; printf "%b" "$OUT"; echo ""; }
 
-if [ "$PROPOSAL_COUNT" -gt 0 ]; then
-  OUT+="📋 ${PROPOSAL_COUNT} unaddressed proposal(s) in .claude/improvements.queue.md\n"
-fi
-
-if [ -n "$HOT_MODULE" ]; then
-  OUT+="🔥 hot module: \`${HOT_MODULE}\` — relevant skills: ${HOT_HINT}\n"
-fi
-
-if [ -n "$OUT" ]; then
-  echo ""
-  printf "%b" "$OUT"
-  echo ""
-fi
-
-emit_signal "hook:session-start:ok" 1 "proposals=$PROPOSAL_COUNT hot=$HOT_MODULE"
-emit_world "session:start" "fyi" "session,start" "session started" "proposals=$PROPOSAL_COUNT" "hot=$HOT_MODULE"
+emit_signal "hook:session-start:ok" 1 "swept=${SWEPT:-0} claims=${CLAIMS_SWEPT:-0}"
+emit_world "session:start" "fyi" "session,start" "session started" "swept=${SWEPT:-0}" "claims=${CLAIMS_SWEPT:-0}"
 exit 0

package/hooks/scripts/task-complete-verify.sh

@@ -1,52 +1,58 @@
 #!/bin/bash
-# TASK-COMPLETE VERIFY — The W4 Gate
+# TASK-COMPLETE VERIFY — a READER, not a runner. Fires on TaskCompleted.
 #
-# Runs on TaskCompleted. Blocks task mark if tests regress.
-# This is the gate between signal and pheromone — prevents corruption.
+# WHAT IT USED TO DO, measured 2026-09-04: `cd "$CLAUDE_PROJECT_DIR" && bun run
+# verify`. The repo root has no package.json, so bun answered "Script not found",
+# EXIT was 1, and this hook — wired `blocking: true` on matcher `*` — printed
+# "W4 GATE BLOCKED: Verification failed" for EVERY task completion in every
+# session, over a suite that never ran (plus an `integer expression expected`
+# from parsing that output). A false red on every task is a gate nobody reads.
 #
-# Exit 0 = task marked (all checks pass)
-# Exit 1 = task blocked (tests regressed or type errors detected)
-# Emits hook:w4-verify:{ok,fail} signal per Rule 1 (see .claude/skills/signal.md).
+# And the version that "worked" would be worse. TaskCompleted fires per subagent
+# task, in every session; twelve sessions completing tasks is twelve full suites
+# — the N-agents-N-full-suites shape that thrashed this box on 2026-08-18
+# (load 57, swap full, 18-minute gates). text/factory-do.md § Deploy is the ship
+# gate names this hook as "one file away from running the full suite on every
+# task completion", and the fix is not a governed run — it is that this hook
+# does not run a suite at all. The suite has owners: W4 runs `verify:fast`
+# through the governor and the memo; /close and ./deploy run the full lane.
+#
+# WHAT IT DOES NOW — two deterministic reads, milliseconds, no gate:
+#   1. the deferred-pin ledger: an outstanding debt on `main` means a plan
+#      landed without reaching its close gate. Named, never paid here.
+#   2. the governor: a slot held by a DEAD pid is an orphaned gate. Named.
+# Both are reports. Neither blocks — a task is not the place to pay a plan's
+# debt, and a hook that blocks on a neighbour's orphan punishes the wrong
+# session. Exit 0 always, with the facts in the signal.
+#
+# Emits hook:w4-verify:{ok,debt,orphan} per Rule 1 (see .claude/skills/signal.md).
 
 # shellcheck source=lib/signal.sh
 source "$CLAUDE_PROJECT_DIR/.claude/hooks/lib/signal.sh"
 
-cd "$CLAUDE_PROJECT_DIR" || exit 1
-
-# Run the full verify suite
-RESULT=$(bun run verify 2>&1)
-EXIT=$?
-
-# Extract test counts (used in both branches for the signal payload)
-PASSED=$(echo "$RESULT" | grep -o '[0-9]* pass' | head -1 | awk '{print $1}')
-FAILED=$(echo "$RESULT" | grep -o '[0-9]* fail' | head -1 | awk '{print $1}')
-ERRORS=$(echo "$RESULT" | grep -c "error TS" || echo "0")
+DEBT_FILE="${VERIFY_FAST_DEBT_FILE:-${TMPDIR:-/tmp}/one-verify-fast-debt}"
+GOVERN_DIR="${GOVERN_DIR:-${TMPDIR:-/tmp}/one-govern}"
 
-if [ $EXIT -eq 0 ]; then
-  # All checks passed — mark with deterministic receipts (Rule 3)
-  emit_signal "hook:w4-verify:ok" 1 "passed=${PASSED:-0} failed=0 errors=0"
-  exit 0
+notes=""
+if [ -s "$DEBT_FILE" ]; then
+  n=$(wc -l < "$DEBT_FILE" | tr -d ' ')
+  br=$(git -C "$CLAUDE_PROJECT_DIR" branch --show-current 2>/dev/null || echo "?")
+  echo "verify: $n deferred pin run(s) owed (branch $br) — paid by a GREEN full lane at /close or ./deploy, never here" >&2
+  emit_signal "hook:w4-verify:debt" 0 "deferred_pins=$n branch=$br"
+  notes="debt=$n"
 fi
 
-# Verify failed — extract details
-echo "W4 GATE BLOCKED: Verification failed" >&2
-echo "" >&2
-
-if [ -n "$FAILED" ] && [ "$FAILED" -gt 0 ]; then
-  echo "Tests: $FAILED failed" >&2
-fi
-if [ "$ERRORS" -gt 0 ]; then
-  echo "TypeScript: $ERRORS type errors" >&2
+orphans=0
+for d in "$GOVERN_DIR"/lock-slot-*; do
+  [ -d "$d" ] || continue
+  pid=$(cat "$d/pid" 2>/dev/null)
+  [ -n "$pid" ] && ! kill -0 "$pid" 2>/dev/null && orphans=$((orphans + 1))
+done
+if [ "$orphans" -gt 0 ]; then
+  echo "verify: $orphans governor slot(s) held by a dead pid — reaped on the next contender; \`bash .claude/scripts/gate-reaper.sh --dry-run\` to see them" >&2
+  emit_signal "hook:w4-verify:orphan" 0 "stale_slots=$orphans"
+  notes="${notes:+$notes }orphans=$orphans"
 fi
 
-# Show last 15 lines of output for context
-echo "" >&2
-echo "Last output:" >&2
-echo "$RESULT" | tail -15 >&2
-echo "" >&2
-echo "Fix baseline before marking task done." >&2
-
-# Full warn — tests actually regressed, agent produced nothing usable
-emit_signal "hook:w4-verify:fail" -1 "passed=${PASSED:-0} failed=${FAILED:-0} errors=${ERRORS:-0}"
-
-exit 1
+[ -z "$notes" ] && emit_signal "hook:w4-verify:ok" 1 "reader: no debt, no orphaned slot"
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneie/claude",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "ONE Claude Code plugin — /do lifecycle, W0-W4 BUILD engine, 7-canon reconcile, ONE substrate via MCP, signals, and rules",
   "files": [
     ".claude-plugin",

package/rules/documentation.md

@@ -1,3 +1,12 @@
+---
+paths:
+  - "text/**/*.md"
+  - "**/*-todo.md"
+  - "**/*-plan.md"
+  - "**/*-docs.md"
+  - ".claude/commands/do*.md"
+---
+
 # Documentation Rules
 
 Apply to all TODOs and `/do` workflows.