@agentsfleet/orly 0.5.0

package/audits/deinit-pairs.sh

@@ -0,0 +1,224 @@
+#!/usr/bin/env bash
+# deinit-pairs.sh — verify init/deinit pairing for Zig structs.
+#
+# Dispatch façade: dispatch/write_zig.md (lifecycle / LIFECYCLE GATE)
+# Standalone tool — not wired into make lint or pre-commit (per Indy's
+# direction, gates fire pre-emptively via printed proof-blocks during
+# agent work; lint integration is intentionally absent).
+#
+# Lifecycle methods recognized (per LIFECYCLE_PATTERNS.md §10A.LC2):
+#   init / deinit / close / release / destroy / shutdown / dispose / free
+#
+# Refined pairing rule:
+#   A `pub fn init` requires a matching cleanup method (deinit / close /
+#   release / destroy / shutdown / dispose / free) IN THE SAME FILE only
+#   when the init either:
+#     (a) allocates inside its body
+#         (alloc/create/dupe/dupeZ/initCapacity/allocPrint/realloc, plus
+#          std.fs.File.open|create, std.Thread.spawn, etc.), OR
+#     (b) returns a heap pointer (`*T` or `!*T` or `*Self` or `!*Self`).
+#
+#   Pure value-type init (e.g. `pub fn init() Self` returning a struct
+#   literal with no heap state) is permitted without deinit per
+#   LIFECYCLE_PATTERNS.md §4 decision matrix. Reviewer responsibility for
+#   the harder case where a struct stores ArrayList/HashMap fields whose
+#   first append/insert happens at use-site rather than init time.
+#
+# Heuristics implemented:
+#   1. Init/deinit pair existence (with allocation refinement) — BLOCKING.
+#   2. defer X.free(buf) + errdefer X.free(buf) on same target adjacent
+#      lines — BLOCKING (per §10A.LC4).
+#      Skips trivial optional bindings (`if (X) |v| free(v)`) where the
+#      captured name is a single 1-2 char identifier — those are loop-
+#      style bindings, not the same allocation.
+#
+# Heuristics deferred to reviewer:
+#   - Errdefer placement (last errdefer must precede last protected alloc).
+#   - Idempotency of deinit (requires test inspection).
+#   - Arena leakage into long-lived structs.
+#   - ArrayList/HashMap field with no init-time alloc but use-time growth.
+#
+# Modes:
+#   --staged   diff-scope: only files in `git diff --cached`
+#   --all      (default) src/ scan including *_test.zig
+#
+# Exits 0 clean, 1 on blocking findings.
+
+set -euo pipefail
+
+MODE="${1:-${SCOPE:-all}}"
+ROOT="$(git rev-parse --show-toplevel)"
+cd "$ROOT"
+
+FAIL=0
+fail() { printf "FAIL: %s\n" "$*" >&2; FAIL=1; }
+ok()   { printf "OK:   %s\n" "$*"; }
+note() { printf "NOTE: %s\n" "$*"; }
+
+# ---------------------------------------------------------------------------
+# 1. Gather Zig files in scope. Tests INCLUDED — same lifecycle rules apply.
+# ---------------------------------------------------------------------------
+case "$MODE" in
+  --staged|staged)
+    mapfile -t FILES < <(git diff --cached --name-only --diff-filter=ACMRT \
+      | grep -E '^src/.*\.zig$' || true)
+    ;;
+  --all|all)
+    mapfile -t FILES < <(find src -type f -name '*.zig' 2>/dev/null || true)
+    ;;
+  *)
+    printf "usage: %s [--staged|--all]\n" "$0" >&2
+    exit 64
+    ;;
+esac
+
+if [[ ${#FILES[@]} -eq 0 ]]; then
+  ok "no zig source files in scope ($MODE)"
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Helper regexes.
+# ---------------------------------------------------------------------------
+CLEANUP_RE='pub fn (deinit|close|release|destroy|shutdown|dispose|free)\('
+# Heap-pointer return on init signature: `) *T` or `) !*T` or returning *Self.
+HEAP_RETURN_RE='\)[[:space:]]*!?\*([A-Z@]|Self\b)'
+# Allocation patterns inside init body.
+ALLOC_RE='\.(alloc|create|dupe|dupeZ|initCapacity|allocPrint|allocSentinel|reAlloc|realloc)\(|std\.fs\.(File|cwd\(\))\.(open|create)|Thread\.spawn|\.allocator\(\)|ArrayList(Unmanaged)?\(.*\)\.init|HashMap(Unmanaged)?\(.*\)\.init|StringHashMap(Unmanaged)?\(.*\)\.init'
+
+# ---------------------------------------------------------------------------
+# 2. Per-init evaluation. Each `pub fn init` is checked individually:
+#    look at the signature for heap-return; look at next ~50 lines of body
+#    for allocation. Either positive triggers the deinit requirement.
+# ---------------------------------------------------------------------------
+files_scanned=0
+inits_total=0
+inits_value_type=0
+inits_requires_cleanup=0
+inits_unpaired=0
+
+# Filter to existing files once.
+present_files=()
+for f in "${FILES[@]}"; do
+  [[ -f "$f" ]] && present_files+=("$f") && files_scanned=$((files_scanned + 1))
+done
+
+# M70 perf: pre-compute file sets in batched greps instead of one grep
+# per file (~760 forks → 2 forks). Reads as "membership sets" for the
+# per-init loop below.
+declare -A files_with_cleanup=()
+if [[ ${#present_files[@]} -gt 0 ]]; then
+  while IFS= read -r f; do
+    [[ -n "$f" ]] && files_with_cleanup["$f"]=1
+  done < <(grep -lE "$CLEANUP_RE" "${present_files[@]}" 2>/dev/null || true)
+fi
+
+# Enumerate every `pub fn init(` site in one batched grep. Output shape:
+# `<file>:<line>:<sig>` — same as the per-file `grep -nE` produced, just
+# with the filename prepended by `-H`.
+inits_list=$(grep -nHE 'pub fn init\(' "${present_files[@]}" 2>/dev/null || true)
+
+if [[ -n "$inits_list" ]]; then
+  while IFS= read -r row; do
+    [[ -z "$row" ]] && continue
+    f="${row%%:*}"
+    rest="${row#*:}"
+    ln="${rest%%:*}"
+    sig="${rest#*:}"
+    inits_total=$((inits_total + 1))
+
+    heap=0
+    if [[ "$sig" =~ \)[[:space:]]*\!?\*([A-Z@]|Self) ]]; then
+      heap=1
+    fi
+
+    # Body window: from sig line to next pub-fn / fn / EOF, capped at +50.
+    body=$(awk -v start="$ln" '
+      NR <= start { next }
+      /^[[:space:]]*(pub )?fn [a-zA-Z_]/ { exit }
+      NR > start + 50 { exit }
+      { print }
+    ' "$f")
+
+    allocates=0
+    if grep -qE "$ALLOC_RE" <<<"$body"; then
+      allocates=1
+    fi
+
+    if [[ $heap -eq 0 && $allocates -eq 0 ]]; then
+      inits_value_type=$((inits_value_type + 1))
+      continue
+    fi
+
+    inits_requires_cleanup=$((inits_requires_cleanup + 1))
+    if [[ -z "${files_with_cleanup[$f]+x}" ]]; then
+      inits_unpaired=$((inits_unpaired + 1))
+      reason=""
+      [[ $heap -eq 1 ]] && reason="heap-return"
+      [[ $allocates -eq 1 ]] && reason="${reason:+$reason+}allocates"
+      fail "$f:$ln — \`pub fn init\` requires cleanup ($reason) but no cleanup method in file"
+      printf "        > %s\n" "$(echo "$sig" | sed 's/^[[:space:]]*//')" >&2
+    fi
+  done <<< "$inits_list"
+fi
+
+# ---------------------------------------------------------------------------
+# 3. Detect defer/errdefer conflicts on the same allocation target.
+#    Skip trivial optional-binding names (1-2 char like `v`, `it`) which
+#    are local to each `if (x) |v|` scope and not actual conflicts.
+# ---------------------------------------------------------------------------
+# M70 perf: single awk across every file. File-local state (defers[]
+# and errdefers[] arrays) resets on FNR == 1 via process_file() flush.
+if [[ ${#present_files[@]} -gt 0 ]]; then
+  while IFS= read -r line; do
+    [[ -z "$line" ]] && continue
+    fail "defer/errdefer conflict (same target, ≤4 line window): $line"
+  done < <(awk '
+    function extract_target(line,    s, p, q) {
+      p = index(line, ".free(");
+      if (p == 0) p = index(line, ".destroy(");
+      if (p == 0) return "";
+      s = substr(line, p);
+      p = index(s, "(");
+      q = index(s, ")");
+      if (p == 0 || q == 0 || q <= p + 1) return "";
+      return substr(s, p + 1, q - p - 1);
+    }
+    function is_optional_binding(line) {
+      return (line ~ /\|[a-z_]+\|/);
+    }
+    function flush() {
+      for (d in defers) {
+        for (e in errdefers) {
+          gap = d - e; if (gap < 0) gap = -gap;
+          if (defers[d] == errdefers[e] && gap <= 4) {
+            printf "%s:%d:%d: defer/errdefer conflict on %s\n", current_file, d, e, defers[d];
+          }
+        }
+      }
+      delete defers; delete errdefers
+    }
+    FNR == 1 && current_file != "" { flush() }
+    FNR == 1 { current_file = FILENAME }
+    /^[[:space:]]*defer[[:space:]].*\.(free|destroy)\(/ {
+      tgt = extract_target($0);
+      if (tgt != "" && length(tgt) > 2 && !is_optional_binding($0)) defers[FNR] = tgt;
+    }
+    /^[[:space:]]*errdefer[[:space:]].*\.(free|destroy)\(/ {
+      tgt = extract_target($0);
+      if (tgt != "" && length(tgt) > 2 && !is_optional_binding($0)) errdefers[FNR] = tgt;
+    }
+    END { if (current_file != "") flush() }
+  ' "${present_files[@]}")
+fi
+
+# ---------------------------------------------------------------------------
+# 4. Verdict.
+# ---------------------------------------------------------------------------
+ok "scanned $files_scanned files; $inits_total init methods ($inits_value_type value-type, $inits_requires_cleanup require cleanup, $inits_unpaired unpaired)"
+if [[ $FAIL -ne 0 ]]; then
+  printf "\n🔴 LIFECYCLE GATE: violations found. See dispatch/write_zig.md (lifecycle).\n" >&2
+  exit 1
+fi
+ok "LIFECYCLE GATE: clean"
+exit 0

package/audits/design-tokens.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# design-tokens.sh — enforce design-system token discipline across
+# ui/packages/{app,website}/**/*.tsx.
+#
+# Dispatch façade: dispatch/write_ts_adhere_bun.md (Design Tokens / DESIGN TOKEN GATE)
+# Fires in: CONFORM (via `make harness-verify` in `agentsfleet`).
+#
+# Rejects arbitrary Tailwind classes when an equivalent design-system
+# token utility exists in ui/packages/design-system/src/theme.css.
+# The token set is encoded below; when the design system adds a token,
+# add the matching grep here in the same commit.
+#
+# TECHNICAL DEBT (acknowledged on migration to dotfiles, 2026-05-11):
+# The PATTERNS array hard-codes agentsfleet-specific token names
+# (text-fluid-hero, max-w-prose, tracking-display-md, etc.). If a second
+# project adopts this dotfiles set, it must either:
+#   (a) share agentsfleet's exact token vocabulary, or
+#   (b) fork the PATTERNS array, or
+#   (c) wait for the parameterised version that reads token names from
+#       $REPO/ui/packages/design-system/src/theme.css at runtime.
+# Path (c) is the right long-term shape; not done yet.
+#
+# Scope (M70):
+#   Walks the full working tree via `git ls-files` — sees staged content
+#   because the index is what `ls-files` reports. Pre-commit-safe: a fix
+#   staged but not yet committed satisfies the check on the same hook run.
+#   The previous `--diff` (BASE...HEAD) default was retired with M70
+#   because it was blind to the index at pre-commit time.
+#
+# Modes:
+#   (no flag) / --all  full-codebase scan via `git ls-files` (default)
+#   --staged           narrow to files in `git diff --cached --name-only`
+#                      — opt-in fast loop for iterative dev
+#
+# Exits 0 clean, 1 on any violation. Test files exempt
+# (snapshot/E2E assert on rendered DOM).
+
+set -euo pipefail
+
+MODE="${1:---all}"
+ROOT="$(git rev-parse --show-toplevel)"
+cd "$ROOT"
+
+# ── Patterns ─────────────────────────────────────────────────────────────
+#
+# Each pattern flags an arbitrary CSS class that has a token equivalent.
+# Format: <regex>|<suggestion>. The suggestion column is hint-only — the
+# closest token depends on context; the audit just blocks the arbitrary.
+#
+# Tailwind base utilities (m-0, w-full, flex, gap-N, etc.) are not flagged
+# — only arbitrary-value classes (the `text-[...]`, `leading-[...]`,
+# `max-w-[...]`, `tracking-[...]` shape).
+
+# Format: <regex>:::<suggestion>. The `:::` delimiter is unambiguous —
+# regex content frequently contains `|` (alternation), so we can't use it.
+PATTERNS=(
+  'text-\[[0-9]+(px|rem)\]:::text-{label,eyebrow,body-sm,body,body-lg,heading,display-md,display-lg,display-xl}'
+  'text-\[clamp\(:::text-fluid-{display-md,display-lg,hero}'
+  'tracking-\[-?[0-9]:::tracking-{display-xl,display-lg,display-md,eyebrow,label}'
+  'leading-\[[0-9]:::leading-{display-xl,display-lg,display-md,heading,eyebrow,body-lg,body,body-sm,label,mono,prose}'
+  'max-w-\[[0-9]+(px|rem|ch)\]:::max-w-{trim,narrow,measure,form,wide,content,tagline,prose}'
+  '(text|bg|border)-(red|blue|green|yellow|purple|indigo|violet|pink|orange|gray|slate|zinc|neutral)-[0-9]:::use semantic tokens (text-destructive, text-error, text-success, …)'
+)
+
+# ── File scope ───────────────────────────────────────────────────────────
+in_scope() {
+  local f="$1"
+  case "$f" in
+    *.test.tsx|*.test.jsx) return 1 ;;
+    *tests/e2e/*) return 1 ;;
+    ui/packages/app/*.tsx|ui/packages/app/*.jsx) return 0 ;;
+    ui/packages/website/*.tsx|ui/packages/website/*.jsx) return 0 ;;
+    ui/packages/app/**/*.tsx|ui/packages/app/**/*.jsx) return 0 ;;
+    ui/packages/website/**/*.tsx|ui/packages/website/**/*.jsx) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+case "$MODE" in
+  --staged|staged)
+    FILES=$(git diff --cached --name-only --diff-filter=ACMRT 2>/dev/null || true)
+    ;;
+  --all|all)
+    # `git ls-files` reports the index, which includes staged content —
+    # so pre-commit-style invocations see staged-but-not-committed files
+    # without needing a `--staged` flag.
+    FILES=$(git ls-files -- 'ui/packages/app/*.tsx' 'ui/packages/app/*.jsx' 'ui/packages/website/*.tsx' 'ui/packages/website/*.jsx' 2>/dev/null || true)
+    ;;
+  *)
+    echo "usage: $0 [--all|--staged]" >&2
+    echo "note: --diff was retired in M70 — see dispatch/write_ts_adhere_bun.md (Design Tokens → Scope)." >&2
+    exit 2 ;;
+esac
+
+FAIL=0
+SEEN_FILES_LIST=""
+
+# Pre-filter FILES list once (drop blanks, non-existent, out-of-scope).
+SCOPED_FILES=()
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  [ ! -f "$f" ] && continue
+  in_scope "$f" || continue
+  SCOPED_FILES+=("$f")
+done <<< "$FILES"
+
+if [ "${#SCOPED_FILES[@]}" -gt 0 ]; then
+  for entry in "${PATTERNS[@]}"; do
+    regex="${entry%%:::*}"
+    suggestion="${entry#*:::}"
+    # Single grep across all scoped files per pattern.
+    # `grep -nHE` always prefixes with filename + line; `-H` is required
+    # when a single file is supplied so the parser sees a uniform shape.
+    while IFS= read -r match; do
+      [ -z "$match" ] && continue
+      f="${match%%:*}"
+      rest="${match#*:}"
+      ln="${rest%%:*}"
+      # Honor inline override `// DESIGN TOKEN: SKIPPED per user override (reason: ...)`
+      # by checking the matched line and the line above.
+      ctx=$(awk -v n="$ln" 'NR>=n-1 && NR<=n' "$f" 2>/dev/null || true)
+      if printf '%s' "$ctx" | grep -q 'DESIGN TOKEN: SKIPPED'; then continue; fi
+      printf '%s\n  -> %s\n' "$match" "$suggestion"
+      SEEN_FILES_LIST="${SEEN_FILES_LIST}${f}"$'\n'
+      FAIL=1
+    done < <(grep -nHE "$regex" "${SCOPED_FILES[@]}" 2>/dev/null || true)
+  done
+fi
+
+FILES_WITH_VIOLATIONS=$(printf '%s' "$SEEN_FILES_LIST" | sort -u | grep -c . || true)
+
+if [ "$FAIL" = "0" ]; then
+  echo "OK: design-token discipline — no arbitraries that have a token equivalent (mode=$MODE)"
+  exit 0
+fi
+
+echo
+echo "FAIL: design-token discipline ($FILES_WITH_VIOLATIONS file(s) with violations)"
+echo "      Replace each match with the suggested token utility, or add the inline override:"
+echo "        // DESIGN TOKEN: SKIPPED per user override (reason: <concrete reason>)"
+echo "      Token source: ui/packages/design-system/src/theme.css"
+echo "      Rule body:    dispatch/write_ts_adhere_bun.md (Design Tokens)"
+exit 1

package/audits/doc-read.sh

@@ -0,0 +1,183 @@
+#!/usr/bin/env bash
+# doc-read.sh — turn the 📖 DOC READ proof-line into a set comparison.
+#
+#   audits/doc-read.sh log <path>   record that a file was read (hook target)
+#   audits/doc-read.sh check        staged source vs recorded reads
+#
+# The DOC READ GATE asks an agent to read the façade its edit triggers, and
+# then asks the same agent whether it did. That is a claim about itself
+# compared against nothing. `log` records the read and `check` compares the
+# record against the façades the staged files trigger.
+#
+# NOTHING HERE MAY DEPEND ON AN AGENT RUNTIME. `log` is a shell command any
+# agent can run; a runtime that also has a read hook (Claude Code today) can
+# call it automatically, and a runtime that removes that feature tomorrow
+# changes nothing — the agent runs the command, the record is identical, the
+# gate behaves the same. Vendor-shaped configuration stays out of this file and
+# out of .githooks/, and an eval fails the build if it appears
+# (evals/ledger/run.sh, ledger_doc_read_runtime_neutral).
+#
+# The record lives in the git directory, never in the tree: it is evidence
+# about one working copy, not shared history. When it is absent — an agent
+# runtime with no hook support — `check` warns and exits 0. Partial
+# mechanization stated honestly beats a red that means nothing.
+#
+# Exit: 0 clean or unenforceable · 1 unread trigger · 2 usage error.
+set -uo pipefail
+
+# A hook exports GIT_DIR/GIT_INDEX_FILE at the repository it fired in. This
+# script IS a hook target, so the scope dies before the first git call.
+unset GIT_DIR GIT_INDEX_FILE GIT_WORK_TREE GIT_COMMON_DIR GIT_PREFIX \
+      GIT_OBJECT_DIRECTORY GIT_ALTERNATE_OBJECT_DIRECTORIES
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=audits/rule-ledger-lib.sh
+source "$HERE/rule-ledger-lib.sh"
+
+MODE_LOG="log"
+MODE_CHECK="check"
+LOG_RELATIVE_PATH="orly/doc-reads.jsonl"
+USAGE="usage: $0 log <path> | $0 check"
+
+if [[ -t 1 ]]; then G=$'\033[32m'; R=$'\033[31m'; Y=$'\033[33m'; X=$'\033[0m'
+else G=''; R=''; Y=''; X=''; fi
+
+# Where the record lives for this working copy. Empty when the caller is not
+# inside a repository at all, which only `log` tolerates.
+read_log_path() {
+  local git_dir
+  git_dir="$(git -C "$LEDGER_ROOT" rev-parse --absolute-git-dir 2>/dev/null)" || return 1
+  printf '%s/%s' "$git_dir" "$LOG_RELATIVE_PATH"
+}
+
+# Repo-relative form of a path, or nothing when it sits outside the tree — an
+# agent reading its own notes elsewhere on disk is not a doc read.
+repo_relative() {
+  local path="$1"
+  case "$path" in
+    "$LEDGER_ROOT"/*) printf '%s' "${path#"$LEDGER_ROOT"/}" ;;
+    /*) return 1 ;;
+    *) [ -e "$LEDGER_ROOT/$path" ] && printf '%s' "$path" ;;
+  esac
+}
+
+# One JSON Lines row per call, appended. Append-only with a single write per
+# invocation is why two agents in two sessions cannot corrupt each other: the
+# order rows land in does not change which paths the set contains.
+run_log() {
+  local path="$1" relative log blob
+  relative="$(repo_relative "$path")" || return 0
+  [ -n "$relative" ] || return 0
+  log="$(read_log_path)" || return 0
+  mkdir -p "$(dirname "$log")" 2>/dev/null || return 0
+  blob="$(content_hash "$relative")"
+  # A hash we could not compute proves nothing was read at a known version.
+  # Recording it would let two failures compare equal and validate a read of a
+  # file that is no longer there.
+  [ -n "$blob" ] || return 0
+  printf '{"ts":%s,"path":"%s","blob":"%s"}\n' "$(date +%s)" "$(json_escape "$relative")" "$blob" >> "$log"
+  return 0
+}
+
+# Backslash and double quote are legal in a POSIX filename and illegal raw in a
+# JSON string. Unescaped, `we"ird.md` writes a row no parser can read — and this
+# one mis-splits it, reporting a path that was never read.
+json_escape() {
+  printf '%s' "$1" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g'
+}
+
+# The content a read actually saw. Validity is keyed to this rather than to a
+# clock: an unchanged document does not need re-reading because a commit
+# happened, and a changed one voids every prior read the same second it is
+# edited — which a timestamp window silently fails to do.
+content_hash() {
+  git -C "$LEDGER_ROOT" hash-object "$LEDGER_ROOT/$1" 2>/dev/null || printf ''
+}
+
+# Façade pages the staged files trigger, one per line. Same glob map the
+# reachability report uses: a façade's scope is its dispatch_init line, so this
+# check and the ledger can never disagree about what fires.
+expected_facade_pages() {
+  local staged="$1" script stem globs
+  while IFS= read -r script; do
+    [ -n "$script" ] || continue
+    stem="$(basename "$script" .sh)"
+    [ -f "$LEDGER_ROOT/dispatch/$stem.md" ] || continue
+    globs="$(ledger_facade_globs "$script")"
+    [ -n "$globs" ] || continue
+    [ "$(ledger_match_count "$globs" < "$staged")" -gt 0 ] && printf 'dispatch/%s.md\n' "$stem"
+  done < <(ledger_facade_scripts)
+}
+
+json_unescape() {
+  printf '%s' "$1" | sed -e 's/\\"/"/g' -e 's/\\\\/\\/g'
+}
+
+# Paths whose recorded read saw the content that is on disk now. A row written
+# against an older version of the document proves the agent read something
+# else, so it does not count — and rows from before this milestone, which carry
+# no blob, cannot prove anything and are ignored.
+current_reads() {
+  local log="$1" line path blob
+  while IFS= read -r line; do
+    case "$line" in *'"blob":"'*) ;; *) continue ;; esac
+    blob="${line##*\"blob\":\"}"; blob="${blob%%\"*}"
+    [ -n "$blob" ] || continue
+    path="${line#*\"path\":\"}"; path="${path%\",\"blob\":\"$blob\"\}}"
+    path="$(json_unescape "$path")"
+    [ "$blob" = "$(content_hash "$path")" ] && printf '%s\n' "$path"
+  done < "$log"
+}
+
+# File-scope so the EXIT trap can still see them: a trap fires after a
+# function's locals are gone, and `set -u` turns that into a spurious error on
+# the way out of a clean run.
+STAGED_FILE=""
+EXPECTED_FILE=""
+RECORDED_FILE=""
+cleanup_temporaries() { rm -f "$STAGED_FILE" "$EXPECTED_FILE" "$RECORDED_FILE"; }
+
+run_check() {
+  local log unread=0 page staged expected recorded
+  STAGED_FILE="$(mktemp)"; EXPECTED_FILE="$(mktemp)"; RECORDED_FILE="$(mktemp)"
+  staged="$STAGED_FILE"; expected="$EXPECTED_FILE"; recorded="$RECORDED_FILE"
+  trap cleanup_temporaries EXIT
+  git -C "$LEDGER_ROOT" diff --cached --name-only --diff-filter=ACMRT > "$staged" 2>/dev/null
+  expected_facade_pages "$staged" | sort -u > "$expected"
+
+  if [ ! -s "$expected" ]; then
+    printf '  %s🟢%s DOC READ: nothing staged triggers a façade\n' "$G" "$X"
+    return 0
+  fi
+  if ! log="$(read_log_path)" || [ ! -f "$log" ]; then
+    printf '  %s🟠%s DOC READ: no read record for this working copy — the agent runtime\n' "$Y" "$X"
+    printf '     has no Read hook, so the proof-line stays self-reported here\n'
+    return 0
+  fi
+
+  # Materialised once, and never piped into `grep -q`: under `pipefail` the
+  # producer takes SIGPIPE the moment grep matches and exits, and the pipeline
+  # then reports 141 — which reads exactly like "not found" and reds a doc that
+  # was read.
+  current_reads "$log" | sort -u > "$recorded"
+
+  while IFS= read -r page; do
+    grep -qxF "$page" "$recorded" && continue
+    printf '  %s🔴%s DOC READ: %s triggered by the staged diff, not read at its current content\n' "$R" "$X" "$page"
+    unread=1
+  done < "$expected"
+  [ "$unread" -eq 0 ] && printf '  %s🟢%s DOC READ: every triggered façade was read at its current content\n' "$G" "$X"
+  return "$unread"
+}
+
+case "${1:-}" in
+  "$MODE_LOG")
+    [ "$#" -eq 2 ] || { printf '%s\n' "$USAGE" >&2; exit 2; }
+    run_log "$2"
+    ;;
+  "$MODE_CHECK")
+    [ "$#" -eq 1 ] || { printf '%s\n' "$USAGE" >&2; exit 2; }
+    run_check
+    ;;
+  *) printf '%s\n' "$USAGE" >&2; exit 2 ;;
+esac