@mmerterden/multi-agent-pipeline 16.20.0 → 16.23.0

package/pipeline/scripts/bulk-read.sh

@@ -0,0 +1,277 @@
+#!/usr/bin/env bash
+# bulk-read.sh  -  read a large file on the cheap rung and return a summary.
+#
+# The worker behind `check-read-size.sh`. The gate says a file is too big to be
+# worth reading whole at this phase's rung; this is where that read goes instead.
+# The full text reaches a haiku-rung worker, the worker returns a structured
+# summary WITH LINE NUMBERS, and only the summary enters the caller's context.
+#
+# Line numbers are the whole design, not a nicety. A summary without them is a
+# dead end: the caller cannot edit from it, cannot verify it, and ends up reading
+# the file anyway - having now paid twice. With them, the intended next step is a
+# bounded `Read(file, offset:, limit:)` around the region that matters, which is
+# both cheap and exact, and which the gate lets through.
+#
+# Usage:
+#   bulk-read.sh --file <path> [--question "<what you need>"] [--phase N]
+#                [--model <rung>] [--timeout <seconds>] [--json]
+#
+# Output: a human-readable summary on stdout, plus the ref id that buys the full
+# text back. `--json` prints the worker's raw object instead, for a caller that
+# wants to parse it.
+#
+# Degradation is explicit and always safe. No CLI, no auth, a timeout, or a
+# non-JSON answer -> this prints WHY and tells the caller to fall back to a
+# bounded read. It never invents a summary, and it never silently succeeds: a
+# fabricated summary of a file nobody read is the one outcome worse than paying
+# full price for the file.
+#
+# Exit codes: 0 summary produced · 3 degraded (caller should read it directly)
+#             1 usage error.
+
+set -uo pipefail
+
+FILE=""
+QUESTION="Summarize this file so a reader can decide which regions to open."
+PHASE="${MULTI_AGENT_PHASE:-0}"
+MODEL=""
+TIMEOUT=""
+AS_JSON=0
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --file) FILE="${2:?--file needs a value}"; shift 2 ;;
+    --question) QUESTION="${2:?--question needs a value}"; shift 2 ;;
+    --phase) PHASE="${2:?--phase needs a value}"; shift 2 ;;
+    --model) MODEL="${2:?--model needs a value}"; shift 2 ;;
+    --timeout) TIMEOUT="${2:?--timeout needs a value}"; shift 2 ;;
+    --json) AS_JSON=1; shift ;;
+    -h|--help) sed -n '2,30p' "$0"; exit 0 ;;
+    *) echo "bulk-read: unknown argument '$1'" >&2; exit 1 ;;
+  esac
+done
+
+[ -n "$FILE" ] || { echo "bulk-read: --file is required" >&2; exit 1; }
+[ -f "$FILE" ] || { echo "bulk-read: not a readable file: $FILE" >&2; exit 1; }
+
+HERE="$(cd "$(dirname "$0")" 2>/dev/null && pwd || true)"
+
+degrade() {
+  echo "bulk-read: DEGRADED  -  $1" >&2
+  echo "Read the region you need directly instead: Read('$FILE', offset: <n>, limit: <n>)." >&2
+  [ -x "$HERE/log-metric.sh" ] && \
+    "$HERE/log-metric.sh" "${MULTI_AGENT_TASK_ID:-unknown}" "$PHASE" bulk_read.degraded \
+      reason="$1" >/dev/null 2>&1
+  exit 3
+}
+
+# Resolve the three prefs this script honours - `bulkRead.model` (which rung the
+# delegated read runs on), `bulkRead.timeoutSeconds` (how long it may take) and
+# `bulkRead.maxBytes` (the ceiling past which delegation stops being a saving).
+# Same search order and the same positive-integer rule as offload-ref.sh: a zero
+# or a string takes the default rather than silently disabling the control.
+PREF_MODEL=""
+PREF_TIMEOUT=""
+PREF_MAX_BYTES=""
+if command -v jq >/dev/null 2>&1; then
+  for prefs in \
+    "$HOME/.claude/multi-agent-preferences.json" \
+    "$HOME/.config/multi-agent-pipeline/multi-agent-preferences.json" \
+    "$HOME/.claude/preferences.json" \
+    "$HOME/.config/multi-agent-pipeline/preferences.json"
+  do
+    [ -f "$prefs" ] || continue
+    values=$(jq -r '.global.bulkRead // {} | [(.model // ""), (.timeoutSeconds // ""), (.maxBytes // "")] | @tsv' \
+      "$prefs" 2>/dev/null) || true
+    PREF_MODEL=$(printf '%s' "$values" | cut -f1)
+    PREF_TIMEOUT=$(printf '%s' "$values" | cut -f2)
+    PREF_MAX_BYTES=$(printf '%s' "$values" | cut -f3)
+    break
+  done
+fi
+[ -n "$MODEL" ] || MODEL="${PREF_MODEL:-haiku}"
+case "$TIMEOUT" in "" ) TIMEOUT="$PREF_TIMEOUT" ;; esac
+case "$TIMEOUT" in ""|*[!0-9]*|0) TIMEOUT=60 ;; esac
+
+command -v claude >/dev/null 2>&1 || degrade "the claude CLI is not on PATH"
+
+LINES=$(wc -l < "$FILE" | tr -d ' ')
+BYTES=$(wc -c < "$FILE" | tr -d ' ')
+
+# A ceiling, because delegation is not free either. Past some size the worker's
+# own input bill approaches the read it replaced, and a file large enough to
+# strain the worker's window would come back truncated - a partial summary
+# presented as a whole one is exactly what this must never produce. Degrading
+# here hands the caller a cheaper move (grep for the symbol, then read around it)
+# instead of an expensive round trip to a worse answer.
+case "$PREF_MAX_BYTES" in ""|*[!0-9]*|0) MAX_BYTES=1048576 ;; *) MAX_BYTES="$PREF_MAX_BYTES" ;; esac
+if [ "$BYTES" -gt "$MAX_BYTES" ]; then
+  echo "bulk-read: DEGRADED  -  ${FILE} is ${BYTES} bytes, past the ${MAX_BYTES}-byte ceiling" >&2
+  echo "At this size the delegated read costs about what reading it would, and risks a truncated" >&2
+  echo "summary presented as a whole one. Narrow it first: grep for the symbol you need, then" >&2
+  echo "Read('${FILE}', offset: <n>, limit: <n>) around the hit." >&2
+  [ -x "$HERE/log-metric.sh" ] && \
+    "$HERE/log-metric.sh" "${MULTI_AGENT_TASK_ID:-unknown}" "$PHASE" bulk_read.degraded \
+      reason=over-ceiling file_bytes="$BYTES" >/dev/null 2>&1
+  exit 3
+fi
+
+# Measured and accepted, so park the full text before asking anything: the
+# pointer in the summary is then a promise that is already kept. The caller buys the rest back by reading this file - the same
+# contract offload-ref.sh makes for build logs, and the same directory.
+ROOT=$(git rev-parse --show-toplevel 2>/dev/null || true)
+[ -n "$ROOT" ] || ROOT="$PWD"
+REFS_DIR="$ROOT/.multi-agent/refs"
+NODE_ID=""
+if mkdir -p "$REFS_DIR" 2>/dev/null; then
+  GITIGNORE="$ROOT/.multi-agent/.gitignore"
+  if [ ! -f "$GITIGNORE" ]; then
+    printf '# Local run artefacts  -  never commit.\nmemory/\nrefs/\n' > "$GITIGNORE"
+  elif ! grep -q '^refs/$' "$GITIGNORE" 2>/dev/null; then
+    printf 'refs/\n' >> "$GITIGNORE"
+  fi
+  if command -v shasum >/dev/null 2>&1; then
+    DIGEST=$(shasum -a 256 "$FILE" | awk '{print substr($1,1,8)}')
+  elif command -v sha256sum >/dev/null 2>&1; then
+    DIGEST=$(sha256sum "$FILE" | awk '{print substr($1,1,8)}')
+  else
+    DIGEST=$(cksum < "$FILE" | awk '{print $1}')
+  fi
+  SLUG=$(basename "$FILE" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9' '-' | sed 's/-\{1,\}/-/g; s/^-//; s/-$//')
+  NODE_ID="p${PHASE}-read-${SLUG:-file}-${DIGEST}"
+  cp "$FILE" "$REFS_DIR/${NODE_ID}.txt" 2>/dev/null || NODE_ID=""
+fi
+
+PROMPT_FILE="$(mktemp -t bulk-read.XXXXXX)"
+OUT_FILE="$(mktemp -t bulk-read-out.XXXXXX)"
+trap 'rm -f "$PROMPT_FILE" "$OUT_FILE"' EXIT
+
+# The worker gets numbered lines because every claim it makes has to be
+# addressable afterwards. `nl -ba` numbers blank lines too, so the numbers match
+# the file's own and an offset computed from them is correct.
+# The worker's contract is the bulk-reader PERSONA, loaded from disk rather than
+# restated here. Two copies of the same prompt is the drift this repo keeps
+# catching elsewhere: the copy that gets edited is never the copy that runs.
+PERSONA=""
+for candidate in \
+  "$HOME/.claude/agents/bulk-reader.md" \
+  "$HERE/../agents/bulk-reader.md"
+do
+  [ -f "$candidate" ] && { PERSONA="$candidate"; break; }
+done
+[ -n "$PERSONA" ] || degrade "the bulk-reader persona is not installed"
+
+# The frontmatter is dispatch metadata for the Agent tool, not instruction text;
+# strip it and send the body.
+{
+  awk 'BEGIN{fm=0} /^---$/{fm++; next} fm>=2{print}' "$PERSONA"
+  printf '\n<question>\n%s\n</question>\n\n' "$QUESTION"
+  printf '<file path="%s" lines="%s">\n' "$FILE" "$LINES"
+  nl -ba "$FILE"
+  printf '\n</file>\n'
+} > "$PROMPT_FILE"
+
+START=$(date +%s)
+# `claude -p` reads the prompt from stdin; the model flag names the rung. A
+# non-zero exit, an empty answer and a non-JSON answer are all degradations, and
+# each one names itself rather than falling through to a generic failure.
+# macOS ships no `timeout`; coreutils installs it as `gtimeout`. Naming only the
+# GNU spelling would leave the budget silently unenforced on the platform most of
+# these runs happen on - a pref that does nothing, which is the class
+# smoke-prefs-consumed exists to catch.
+TIMEOUT_BIN=""
+for candidate in timeout gtimeout; do
+  command -v "$candidate" >/dev/null 2>&1 && { TIMEOUT_BIN="$candidate"; break; }
+done
+if [ -n "$TIMEOUT_BIN" ]; then
+  "$TIMEOUT_BIN" "$TIMEOUT" claude -p --model "$MODEL" < "$PROMPT_FILE" > "$OUT_FILE" 2>/dev/null
+  STATUS=$?
+else
+  # No timeout binary: the budget cannot be enforced, so say so rather than
+  # letting the caller believe timeoutSeconds is holding.
+  echo "bulk-read: no timeout binary found; bulkRead.timeoutSeconds is not enforced on this host" >&2
+  claude -p --model "$MODEL" < "$PROMPT_FILE" > "$OUT_FILE" 2>/dev/null
+  STATUS=$?
+fi
+ELAPSED=$(( $(date +%s) - START ))
+
+[ "$STATUS" -eq 124 ] && degrade "the worker did not answer within ${TIMEOUT}s"
+[ "$STATUS" -ne 0 ] && degrade "the worker exited $STATUS"
+[ -s "$OUT_FILE" ] || degrade "the worker returned nothing"
+
+RENDER=$(FILE="$FILE" LINES="$LINES" BYTES="$BYTES" NODE_ID="$NODE_ID" \
+         MODEL="$MODEL" ELAPSED="$ELAPSED" AS_JSON="$AS_JSON" \
+         python3 - "$OUT_FILE" <<'PYEOF'
+import json, os, re, sys
+
+raw = open(sys.argv[1], encoding="utf-8", errors="replace").read()
+try:
+    data = json.loads(raw)
+except Exception:
+    # A worker that wrapped its object in prose or a fence is still usable; a
+    # worker that answered in prose is not, and falls through to the degrade path.
+    m = re.search(r"\{[\s\S]*\}", raw)
+    if not m:
+        sys.exit(7)
+    try:
+        data = json.loads(m.group(0))
+    except Exception:
+        sys.exit(7)
+
+if not isinstance(data, dict) or "summary" not in data:
+    sys.exit(7)
+
+if os.environ.get("AS_JSON") == "1":
+    print(json.dumps(data, indent=2))
+    sys.exit(0)
+
+out = []
+out.append("bulk-read: %s (%s lines, %s bytes) via %s in %ss"
+           % (os.environ["FILE"], os.environ["LINES"], os.environ["BYTES"],
+              os.environ["MODEL"], os.environ["ELAPSED"]))
+answer = (data.get("answer") or "").strip()
+if answer:
+    out.append("")
+    out.append("ANSWER: " + answer)
+out.append("")
+out.append((data.get("summary") or "").strip())
+
+symbols = [s for s in (data.get("symbols") or []) if isinstance(s, dict)]
+if symbols:
+    out.append("")
+    out.append("Symbols:")
+    for s in symbols[:40]:
+        out.append("  %-6s %s  (line %s)" % (s.get("kind", "?"), s.get("name", "?"), s.get("line", "?")))
+
+regions = [r for r in (data.get("regions") or []) if isinstance(r, dict)]
+if regions:
+    out.append("")
+    out.append("Read next (bounded, and this gate allows it):")
+    for r in regions[:8]:
+        start, end = r.get("start"), r.get("end")
+        span = ""
+        try:
+            span = "  Read(offset: %d, limit: %d)" % (int(start), int(end) - int(start) + 1)
+        except Exception:
+            pass
+        out.append("  %s-%s  %s%s" % (start, end, r.get("why", ""), span))
+
+node = os.environ.get("NODE_ID") or ""
+if node:
+    out.append("")
+    out.append("Full text: .multi-agent/refs/%s.txt  [[ref:%s]]" % (node, node))
+if data.get("truncated"):
+    out.append("")
+    out.append("NOTE: the worker reports it did not see the whole file.")
+print("\n".join(out))
+PYEOF
+) || degrade "the worker's answer was not the requested JSON object"
+
+printf '%s\n' "$RENDER"
+
+[ -x "$HERE/log-metric.sh" ] && \
+  "$HERE/log-metric.sh" "${MULTI_AGENT_TASK_ID:-unknown}" "$PHASE" bulk_read.delegated \
+    file_lines="$LINES" file_bytes="$BYTES" model="$MODEL" duration_ms="$(( ELAPSED * 1000 ))" \
+    >/dev/null 2>&1
+
+exit 0

package/pipeline/scripts/check-read-size.py

@@ -0,0 +1,335 @@
+#!/usr/bin/env python3
+"""check-read-size.py  -  decision core for the read-size PreToolUse gate.
+
+Reads a Claude Code hook payload on stdin and prints ONE line:
+
+    PASS
+    OBSERVE\t<path>\t<lines>\t<why>
+    BLOCK\t<path>\t<lines>\t<why>
+
+It decides only. The wrapper (check-read-size.sh) owns telemetry, the message
+the model sees, and the exit code. Splitting them is what lets the smoke gate
+drive the decision without a hook harness, and it keeps the blocking path in
+shell where the other two gates already live.
+
+Why a gate at all: a phase that reads six 900-line files pays for 5,400 lines of
+Swift at the phase's own rung, and the useful content is a handful of symbols.
+`offload-ref.sh` already caught the other half of that bill - the build log - but
+nothing looked at reads.
+
+Why it must not simply block: in Claude Code, `Edit` requires that the SAME file
+was read first. A gate that blocks reads during development stops the pipeline
+from editing anything. So the development phase is exempt by default, and so is
+any file already in the run's edit set. The gate exists for the phases that read
+to UNDERSTAND (analysis, review), not for the one that reads to change.
+
+Modes (prefs `global.bulkRead.mode`):
+    off       nothing is inspected                      (default)
+    observe   decide, log, never block  -  the baseline measurement
+    enforce   block a read over the threshold
+
+Fail-open everywhere: any error prints PASS. A gate that guesses wrong must cost
+a log line, never a tool call.
+"""
+
+import json
+import os
+import re
+import shlex
+import sys
+
+# Shipped defaults for the two prefs read below: `bulkRead.minLines` and
+# `bulkRead.exemptPhases`. A pref that resolves to anything else - absent, zero,
+# a string - takes these rather than silently turning the gate off.
+DEFAULT_MIN_LINES = 350
+DEFAULT_EXEMPT_PHASES = ["3"]
+
+PREF_PATHS = [
+    "~/.claude/multi-agent-preferences.json",
+    "~/.config/multi-agent-pipeline/multi-agent-preferences.json",
+    "~/.claude/preferences.json",
+    "~/.config/multi-agent-pipeline/preferences.json",
+]
+
+# Commands that read a whole file to stdout. `sed` is here for `sed -n '1,900p'`,
+# which is the spelling an agent reaches for when Read is unavailable.
+READ_COMMANDS = {"cat", "head", "tail", "sed", "bat", "less", "more"}
+
+# `1,900p` / `1,$p` / `900p` - a sed print script with a line range.
+SED_RANGE = re.compile(r"^'?(\d+)(?:,(\d+|\$))?p'?$")
+
+
+def emit(verdict, path="", lines=0, why=""):
+    sys.stdout.write("%s\t%s\t%s\t%s\n" % (verdict, path, lines, why))
+    sys.exit(0)
+
+
+def load_prefs():
+    for raw in PREF_PATHS:
+        p = os.path.expanduser(raw)
+        if not os.path.isfile(p):
+            continue
+        try:
+            with open(p, "r", encoding="utf-8") as fh:
+                return json.load(fh).get("global", {}).get("bulkRead", {}) or {}
+        except Exception:
+            return {}
+    return {}
+
+
+def positive_int(value, default):
+    """A pref counts only as a positive integer; anything else takes the default.
+
+    Same rule as offload-ref.sh: a zero or a string must not silently disable
+    the threshold, because that reads as "the gate is off" when it is broken.
+    """
+    try:
+        n = int(value)
+    except (TypeError, ValueError):
+        return default
+    return n if n > 0 else default
+
+
+def find_state():
+    """Walk up from cwd for the run's agent-state.json.
+
+    A hook runs in the worktree where the tool call happens, so the state file
+    is at cwd or above it. The env override exists for the smoke gate.
+    """
+    override = os.environ.get("MULTI_AGENT_STATE")
+    if override:
+        return override if os.path.isfile(override) else None
+    here = os.path.abspath(os.getcwd())
+    while True:
+        candidate = os.path.join(here, "agent-state.json")
+        if os.path.isfile(candidate):
+            return candidate
+        parent = os.path.dirname(here)
+        if parent == here:
+            return None
+        here = parent
+
+
+def run_context():
+    """(phase, edit_set) for the current run, both best-effort.
+
+    Both come from agent-state.json's REAL shape, checked against
+    pipeline/schemas/agent-state.schema.json: the phase is the top-level
+    `currentPhase` integer, and the files a phase has touched are
+    `phases["<n>"].files[]` - the same list semantic revert uses. An earlier
+    draft of this read `run.phase` and `dev.editSet`, neither of which the
+    schema declares, so the exemption could never have engaged from state and
+    the gate would have blocked development. smoke-bulk-read.sh asserts the
+    field names against the schema now, so that cannot come back quietly.
+    """
+    phase = os.environ.get("MULTI_AGENT_PHASE", "")
+    edit_set = set()
+    path = find_state()
+    if not path:
+        return phase, edit_set
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            state = json.load(fh)
+    except Exception:
+        return phase, edit_set
+    if not phase:
+        current = state.get("currentPhase")
+        phase = str(current) if isinstance(current, int) else ""
+    # Every phase's file list counts, not only the current one: a review that
+    # re-reads what development just wrote is reading the run's own work.
+    phases = state.get("phases")
+    if isinstance(phases, dict):
+        for entry in phases.values():
+            if not isinstance(entry, dict):
+                continue
+            for f in entry.get("files") or []:
+                if isinstance(f, str):
+                    edit_set.add(os.path.basename(f))
+    return phase, edit_set
+
+
+def count_lines(path):
+    """Line count, or -1 when the file cannot be measured.
+
+    Binary-safe and streamed: the gate must not itself load the payload it
+    exists to keep out of memory.
+    """
+    try:
+        total = 0
+        with open(path, "rb") as fh:
+            while True:
+                chunk = fh.read(1 << 20)
+                if not chunk:
+                    break
+                total += chunk.count(b"\n")
+        return total
+    except Exception:
+        return -1
+
+
+def as_count(token):
+    """A flag's numeric argument, or a large sentinel when it is not a number.
+
+    Not-a-number must read as UNBOUNDED, not as 1: treating an unparseable
+    count as a tiny one is how a gate lets through exactly the reads it exists
+    to catch.
+    """
+    try:
+        n = int(token)
+    except (TypeError, ValueError):
+        return 1 << 30
+    return abs(n)
+
+
+def looks_like_sed_script(token):
+    return bool(SED_RANGE.match(token or ""))
+
+
+def sed_span(script):
+    """Lines a `sed` print script covers, or a large sentinel when unclear."""
+    m = SED_RANGE.match(script or "")
+    if not m:
+        return 1 << 30
+    start, end = m.group(1), m.group(2)
+    try:
+        if end in (None, "", "$"):
+            return 1 << 30
+        return abs(int(end) - int(start)) + 1
+    except (TypeError, ValueError):
+        return 1 << 30
+
+
+def read_target(payload):
+    """The file a tool call would read whole, or None.
+
+    Returns None for every call that is already bounded - a Read with a small
+    `limit`, a `head -n 50` - because those are not what this gate is for.
+    """
+    tool = payload.get("tool_name", "")
+    args = payload.get("tool_input", {}) or {}
+
+    if tool == "Read":
+        path = args.get("file_path")
+        if not path:
+            return None
+        limit = args.get("limit")
+        if isinstance(limit, int) and limit > 0:
+            return (path, limit)
+        return (path, None)
+
+    if tool != "Bash":
+        return None
+
+    command = args.get("command", "")
+    if not command:
+        return None
+    # A compound command is not decided here: splitting on shell operators
+    # correctly is the kind of parsing that goes wrong quietly, and a wrong
+    # block is worse than a missed one.
+    for operator in ("&&", "||", "|", ";", "$(", "`", ">", "<"):
+        if operator in command:
+            return None
+    try:
+        tokens = shlex.split(command)
+    except ValueError:
+        return None
+    if not tokens or os.path.basename(tokens[0]) not in READ_COMMANDS:
+        return None
+
+    tool = os.path.basename(tokens[0])
+    bound = None
+    operands = []
+    i = 1
+    while i < len(tokens):
+        token = tokens[i]
+
+        if not token.startswith("-") or token == "-":
+            if tool == "sed" and not operands and looks_like_sed_script(token):
+                # `sed '1,900p' file` - the script, not the file.
+                bound = max(bound or 0, sed_span(token))
+            else:
+                operands.append(token)
+            i += 1
+            continue
+
+        # A following-tail stream is not a bulk read at all; blocking it would
+        # be a false positive with no cheap alternative to offer.
+        if tool == "tail" and token in ("-f", "-F", "--follow"):
+            return None
+
+        # Only head/tail take a separate count operand. `cat -n` NUMBERS LINES -
+        # reading its next token as a count swallowed the filename, left no
+        # operand, and let `cat -n <bigfile>` through the gate entirely.
+        if tool in ("head", "tail") and token in ("-n", "-c"):
+            nxt = tokens[i + 1] if i + 1 < len(tokens) else ""
+            bound = max(bound or 0, as_count(nxt))
+            i += 2
+            continue
+
+        # `sed -n` suppresses default output; the range lives in the script,
+        # which arrives as the next operand and is handled above.
+        if tool == "head" or tool == "tail":
+            attached = token.lstrip("-")
+            if attached.isdigit():
+                bound = max(bound or 0, as_count(attached))
+            elif attached[:1] in ("n", "c") and attached[1:].isdigit():
+                bound = max(bound or 0, as_count(attached[1:]))
+        i += 1
+
+    if len(operands) != 1:
+        return None
+    return (operands[0], bound)
+
+
+def main():
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        emit("PASS", why="unparseable payload")
+
+    # `bulkRead.mode` decides whether this gate does anything at all.
+    prefs = load_prefs()
+    mode = str(prefs.get("mode", "off") or "off").lower()
+    if mode not in ("observe", "enforce"):
+        emit("PASS", why="mode=%s" % mode)
+
+    target = read_target(payload)
+    if target is None:
+        emit("PASS", why="not a whole-file read")
+    path, bound = target
+
+    min_lines = positive_int(prefs.get("minLines"), DEFAULT_MIN_LINES)
+    if bound is not None and bound < min_lines:
+        emit("PASS", path, 0, "bounded read")
+
+    if not os.path.isfile(path):
+        emit("PASS", path, 0, "not a readable file")
+
+    lines = count_lines(path)
+    if lines < 0:
+        emit("PASS", path, 0, "unmeasurable")
+    if lines < min_lines:
+        emit("PASS", path, lines, "under threshold")
+
+    phase, edit_set = run_context()
+    exempt = prefs.get("exemptPhases")
+    if not isinstance(exempt, list) or not exempt:
+        exempt = DEFAULT_EXEMPT_PHASES
+    exempt = [str(x) for x in exempt]
+
+    # The two exemptions that keep Edit working. Both are stated as PASS with a
+    # reason rather than skipped silently, so the telemetry shows how often the
+    # gate declined to act and why.
+    if phase and phase in exempt:
+        emit("PASS", path, lines, "phase %s exempt" % phase)
+    if os.path.basename(path) in edit_set:
+        emit("PASS", path, lines, "in edit set")
+
+    emit("OBSERVE" if mode == "observe" else "BLOCK", path, lines, "over threshold")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        emit("PASS", why="internal error")