@agentsfleet/orly 0.5.0

package/audits/spec-template.sh

@@ -0,0 +1,258 @@
+#!/usr/bin/env bash
+# spec-template.sh — enforce docs/TEMPLATE.md across every spec under
+# docs/v*/{pending,active,done}/. Two check families:
+#
+#   1. PROHIBITED patterns (negative space) — TEMPLATE.md "Prohibited" section:
+#      time/effort estimates, effort/complexity columns, %-complete, owners, dates.
+#      Always BLOCK.
+#   2. REQUIRED-PRESENT + NO-PLACEHOLDER (positive space) — the determinism
+#      sections the agent-facing template mandates (PR Intent, Applicable Gates,
+#      Prior-Art, Metrics, Decomposition, tiered Test Spec, Product Clarity,
+#      Discovery, …) must EXIST and be FILLED: no unfilled {slot} sentinels and
+#      no surviving "tpl:" guidance comments (template fill grammar). A spec
+#      that omits them forces the executing agent to guess intent. This is the
+#      half that makes a spec "built for the agent".
+#   2b. DECLARED-COMMAND PARITY — a pending/active spec's Acceptance Rubric
+#      must quote the repository's declared conform + verify.unit commands
+#      (.oracle/orly.json) verbatim: the rubric and `orly gate` grade one
+#      boundary. Staged/file scope only; done/ specs stay historical.
+#
+# Dispatch façade: dispatch/write_spec.md (SPEC TEMPLATE GATE)
+# Fires in: make lint (after audit-logging, before audit-error-codes).
+#
+# Modes:
+#   --staged         diff-scope: only specs in `git diff --cached`
+#   --all            (default) pending+active specs only — current/in-flight work
+#   --include-done   adds done/ specs to the scan (one-time sweep tool)
+#
+# Family 2 runs ONLY in --staged scope — the spec being authored/edited right
+# now, which is exactly the agent's own output. The bulk scans (--all /
+# --include-done) run Family 1 only, so they behave identically over the whole
+# corpus and never break an existing spec. No legacy carve-out, no heuristics:
+# author a spec → full template required; scan the tree → prohibited-only.
+#
+# Done specs are excluded by default: historical artifacts, not work product.
+# Exits 0 clean, 1 on any blocking finding.
+
+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" "$*"; }
+
+# Discover spec files in scope.
+case "$MODE" in
+  --staged|staged)
+    mapfile -t SPECS < <(git diff --cached --name-only --diff-filter=ACMRT | grep -E '^docs/v[0-9]+/(pending|active|done)/.*\.md$' || true)
+    ;;
+  --all|all)
+    mapfile -t SPECS < <(find docs/v[0-9]* -type f -name '*.md' 2>/dev/null | grep -E '/(pending|active)/' || true)
+    ;;
+  --include-done|include-done)
+    mapfile -t SPECS < <(find docs/v[0-9]* -type f -name '*.md' 2>/dev/null | grep -E '/(pending|active|done)/' || true)
+    ;;
+  --file|file)
+    # Single named spec, both families — the lifecycle engine's spec.gate
+    # criterion calls this so the engine and pre-commit share one enforcer.
+    [[ -n "${2:-}" ]] || { printf "usage: %s --file <spec path>\n" "$0" >&2; exit 64; }
+    [[ -f "$2" ]] || { printf "FAIL: spec not found: %s\n" "$2" >&2; exit 1; }
+    SPECS=("$2")
+    ;;
+  *)
+    printf "usage: %s [--staged|--all|--include-done|--file <path>]\n" "$0" >&2
+    exit 64
+    ;;
+esac
+
+if [[ ${#SPECS[@]} -eq 0 ]]; then
+  ok "no spec files in scope ($MODE)"
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Family 1 — Prohibited patterns from docs/TEMPLATE.md "Prohibited" section.
+# Each pattern: <severity>:<one-line description>:<regex> — the regex comes
+# LAST because it may contain colons (e.g. the [:|] label-row class); read(1)
+# assigns the remainder of the line to the final field, so the regex survives
+# intact. Descriptions must stay colon-free.
+# Severity: BLOCK = exit 1; INFO = stdout note only. Patterns use ERE (egrep -E)
+# only — no PCRE constructs like (?:...), which grep -E rejects.
+#
+# DESIGN NOTE — patterns are deliberately structural, not prose-level.
+# Bare regex like `\b\d+\s*days?\b` false-positives on legitimate prose
+# ("Day 50", "≥7 days uptime", "within 3 days of install"). Instead we
+# match where time/effort estimates LIVE structurally:
+#   - Section headings: `## Estimated effort`, `## Effort`, `## Sizing`
+#   - Label rows:       `**Effort:** medium`, `**Owner:** alice`
+#   - Tilde-bulleted:   `- ~2 h survey`, `* ~5 days OAuth setup`
+#                       (the `~` prefix is Indy's idiom for effort estimates;
+#                       legitimate prose doesn't use it)
+# This catches the actual drift class without churning real content.
+# ---------------------------------------------------------------------------
+PATTERNS=(
+  'BLOCK:Estimated effort section heading:^#+ .*Estimated [Ee]ffort'
+  'BLOCK:Effort/Complexity/Sizing section heading:^#+ .*\b(Effort|Complexity|Sizing|Cost)\b\s*$'
+  'BLOCK:Scale estimate section heading:^#+ .*\bScale\b.*estimate'
+  'BLOCK:Tilde-bulleted hour estimate (e.g. "- ~2 h"):^[-*]\s*~\s*[0-9]+\s*h\b'
+  'BLOCK:Tilde-bulleted time estimate:^[-*]\s*~\s*[0-9]+\s*(hours?|days?|min(utes?)?)\b'
+  'BLOCK:Effort/Estimate label row:^\s*\*\*\s*(Effort|Estimate|Sizing|Complexity|Cost)\s*(:\s*\*\*|\*\*\s*[:|])'
+  'BLOCK:Owner label row:^\s*\*\*\s*Owner\s*(:\s*\*\*|\*\*\s*[:|])'
+  'BLOCK:Assigned-to label row:^\s*\*\*\s*Assigned to\s*(:\s*\*\*|\*\*\s*[:|])'
+  'BLOCK:Date-bound deadline label:^\s*\*\*\s*(Due|Deadline)\s*(:\s*\*\*|\*\*\s*[:|])\s*[0-9]'
+  'BLOCK:Percentage-complete metric:^[-*\|]?\s*\*?\*?\s*[0-9]+\s*%\s*complete'
+  'BLOCK:Hour-range estimate in effort context:\b(effort|estimate|takes?|spend)\b[^.]{0,40}\b[0-9]+\s*[-–]\s*[0-9]+\s*h\b'
+  'BLOCK:Effort/complexity rating:\b(low|medium|high|small|large)\s*[/|-]\s*(effort|complexity)\b'
+)
+
+# Carve-outs — lines that look prohibited but are legitimate. Skip any match.
+SAFE_LINES_RE='^\*\*Date:\*\*|^\s*```|<!--|^\s*//|"[0-9]+\s*(h|hour|day|min)"'
+
+# ---------------------------------------------------------------------------
+# Family 2 — Required determinism sections (agent-facing docs/TEMPLATE.md).
+# Each entry: <heading ERE>:<human description>
+# ---------------------------------------------------------------------------
+REQUIRED_SECTIONS=(
+  '^#+ .*PR Intent:PR Intent & comprehension handshake'
+  '^#+ .*Applicable Rules:Applicable Rules'
+  '^#+ .*Applicable Gates:Applicable Gates'
+  '^#+ .*Overview:Overview'
+  '^#+ .*(Prior-Art|Reference Implementation):Prior-Art / Reference Implementations'
+  '^#+ .*Files Changed:Files Changed (blast radius)'
+  '^#+ .*(Decomposition|Alternatives):Decomposition & alternatives (patch vs refactor)'
+  '^#+ .*Sections:Sections (implementation slices)'
+  '^#+ .*Metrics.*Observability:Metrics & Observability'
+  '^#+ .*Interfaces:Interfaces'
+  '^#+ .*Failure Modes:Failure Modes'
+  '^#+ .*Invariants:Invariants'
+  '^#+ .*Test Specification:Test Specification'
+  '^#+ .*Acceptance (Criteria|Rubric):Acceptance Rubric (legacy heading Acceptance Criteria accepted)'
+  '^#+ .*Product Clarity:Product Clarity (authoring record)'
+  '^#+ .*Discovery:Discovery (consult log)'
+)
+
+# Template residue — strings that exist ONLY in the unfilled template. Their
+# survival in a pending/active spec means the section was never filled. The
+# "<!-- tpl:" marker is the template's fill grammar: every guidance comment is
+# deleted at authoring, so any survivor is residue by construction.
+PLACEHOLDER_SENTINELS=(
+  '<!-- tpl:'
+  'Title — testable, not vague'
+  'one-line reason}'
+  'Slice title}'
+  'path/to/file.ext'
+  'test_<short_name>'
+  'why this is the right pattern to mirror'
+  '{outcome the user can observe}'
+  '{exit 0 / substring / 0 matches}'
+  'path/to/spec_or_doc.md'
+  '{path/to/old_file.ext}'
+  '{old_symbol}'
+  '{one sentence that could be a test name}'
+  '{smallest verifiable behaviour}'
+  '{one-line behavioural claim}'
+  '{conform command from .oracle/orly.json'
+  '{verify.unit command from .oracle/orly.json'
+  "{gate from this repository's AGENTS.md dispatch index}"
+)
+
+# ---------------------------------------------------------------------------
+# Family 2b — declared-command parity (TEMPLATE.md "Command source rule").
+# A pending/active spec's Acceptance Rubric must quote the repository's
+# declared conform + verify.unit commands VERBATIM — the same set `orly gate`
+# runs — so the spec's ship gate and the mechanical PR gate grade one
+# boundary. Reads .oracle/orly.json with bun (orly's own runtime). Done specs
+# are historical records and are never retrofitted. No config, no bun, or no
+# declared commands → NOTE and skip; this check never guesses.
+# ---------------------------------------------------------------------------
+scan_commands() {
+  local spec="$1" cfg=".oracle/orly.json" cmds
+  case "$spec" in
+    */pending/*|*/active/*) ;;
+    *) return 0 ;;
+  esac
+  [[ -f "$cfg" ]] || { note "$spec — no $cfg; declared-command parity skipped"; return 0; }
+  command -v bun >/dev/null 2>&1 || { note "$spec — bun unavailable; declared-command parity skipped"; return 0; }
+  cmds="$(bun -e '
+    const cfg = await Bun.file(".oracle/orly.json").json().catch(() => null);
+    const commands = cfg && typeof cfg.commands === "object" && cfg.commands !== null ? cfg.commands : {};
+    for (const key of ["conform", "verify.unit"]) {
+      for (const argv of Array.isArray(commands[key]) ? commands[key] : []) {
+        if (Array.isArray(argv) && argv.length > 0) console.log(argv.join(" "));
+      }
+    }' 2>/dev/null || true)"
+  [[ -n "$cmds" ]] || { note "$spec — no declared conform/verify.unit commands; parity skipped"; return 0; }
+  local miss=0 cmd
+  while IFS= read -r cmd; do
+    [[ -z "$cmd" ]] && continue
+    grep -qF "$cmd" "$spec" && continue
+    fail "$spec — rubric misses declared command verbatim: \"$cmd\" (.oracle/orly.json — the set orly gate runs)"
+    miss=$((miss + 1))
+  done <<<"$cmds"
+  if [[ $miss -eq 0 ]]; then ok "$spec — rubric quotes the declared conform/verify.unit commands"; fi
+  return 0
+}
+
+scan_spec() {
+  local spec="$1"
+  local hits=0
+  local pattern desc severity line content
+  while IFS=: read -r severity desc pattern; do
+    while IFS= read -r match; do
+      [[ -z "$match" ]] && continue
+      if grep -qE "$SAFE_LINES_RE" <<<"$match"; then
+        continue
+      fi
+      line="${match%%:*}"
+      content="${match#*:}"
+      content="${content%$'\r'}"
+      if [[ "$severity" = "BLOCK" ]]; then
+        fail "$spec:$line — $desc"
+        printf "        > %s\n" "$content" >&2
+      else
+        note "$spec:$line — $desc"
+      fi
+      hits=$((hits + 1))
+    done < <(grep -nE "$pattern" "$spec" 2>/dev/null || true)
+  done < <(printf '%s\n' "${PATTERNS[@]}")
+  if [[ $hits -eq 0 ]]; then ok "$spec — no prohibited patterns"; fi
+  return 0
+}
+
+# Family 2 — required determinism sections present + no template residue.
+# BLOCK only; called solely in --staged scope (a spec being authored now).
+scan_required() {
+  local spec="$1"
+  local miss=0 entry sec desc sentinel
+  for entry in "${REQUIRED_SECTIONS[@]}"; do
+    sec="${entry%%:*}"; desc="${entry#*:}"
+    grep -qE "$sec" "$spec" && continue
+    fail "$spec — missing required section: $desc"
+    miss=$((miss + 1))
+  done
+  for sentinel in "${PLACEHOLDER_SENTINELS[@]}"; do
+    grep -qF "$sentinel" "$spec" || continue
+    fail "$spec — unfilled template placeholder: \"$sentinel\""
+    miss=$((miss + 1))
+  done
+  if [[ $miss -eq 0 ]]; then ok "$spec — required sections present, no placeholders"; fi
+  return 0
+}
+
+for spec in "${SPECS[@]}"; do
+  [[ -f "$spec" ]] || continue
+  scan_spec "$spec"
+  case "$MODE" in --staged|staged|--file|file) scan_required "$spec"; scan_commands "$spec" ;; esac
+done
+
+if [[ $FAIL -ne 0 ]]; then
+  printf "\n🔴 SPEC TEMPLATE GATE: violations found. See dispatch/write_spec.md.\n" >&2
+  exit 1
+fi
+
+ok "SPEC TEMPLATE GATE: clean (${#SPECS[@]} specs)"
+exit 0

package/audits/sql-mod.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# sql-mod.sh — SQL statements must live in domain sql.zig, not inline in Zig source.
+#
+# Dispatch façade: dispatch/write_zig.md (SQLMOD). Extracted from write_zig.sh's
+# former inline `zig_sql_module_gate` so the Zig dispatch DELEGATES to a leaf
+# rather than doing the work itself (the dispatch/lib.sh contract: "It never does
+# the work itself — the leaf helpers in audits/ do"). This is what lets
+# evals/dispatch/coverage.sh see SQLMOD as a wired dispatch_run_helper row.
+#
+# Rule: a *.zig file (excluding sql.zig, *_test.zig, test_fixtures_*.zig) must
+# not DEFINE SQL — neither
+#   - a `const <SQL-ish name> = …` (SELECT_/INSERT_/…/_SQL/_QUERY), nor
+#   - a Zig multiline-string body opening with `\\WITH|SELECT|INSERT|…`.
+# New files are whole-file scanned; existing files are scanned only for newly
+# ADDED lines (staged diff), so pre-existing inline SQL is not retroactively
+# flagged — only new SQL must land in a domain sql.zig.
+#
+# Modes:
+#   --staged   diff-scope: staged *.zig (new files whole-scanned, existing diff-scanned)
+#   --all      (default) every src/*.zig whole-scanned
+#
+# Exits 0 clean, 1 on any inline-SQL hit.
+
+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" "$*"; }
+
+# Kept byte-identical to the former write_zig.sh regexes so behaviour is
+# unchanged by the extraction.
+DEF_RE='^[[:space:]]*(pub[[:space:]]+)?const[[:space:]]+(SELECT|INSERT|UPDATE|DELETE|UPSERT|LIST|COUNT|EXISTS|[A-Z0-9_]+_(SQL|QUERY)|(SELECT|INSERT|UPDATE|DELETE|UPSERT|LIST|COUNT|EXISTS)_[A-Z0-9_]+)[[:space:]]*='
+BODY_RE='^[[:space:]]*\\\\(WITH|SELECT|INSERT|UPDATE|DELETE|CREATE|ALTER|DROP)[[:space:]]'
+
+definition_hit() { grep -nE "$DEF_RE" "$1" | head -1 || true; }
+body_hit()       { grep -nE "$BODY_RE" "$1" | head -1 || true; }
+added_hit() {
+  git diff --cached -U0 -- "$1" \
+    | awk '/^\+[^+]/ { sub(/^\+/, ""); print }' \
+    | grep -nE "$DEF_RE|$BODY_RE" | head -1 || true
+}
+
+case "$MODE" in
+  --staged|staged)
+    mapfile -t FILES < <(git diff --cached --name-only --diff-filter=ACMRT -- '*.zig' || true)
+    STAGED=1 ;;
+  --all|all)
+    mapfile -t FILES < <(find src -type f -name '*.zig' 2>/dev/null || true)
+    STAGED=0 ;;
+  *)
+    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
+
+scanned=0
+for f in "${FILES[@]}"; do
+  [[ -n "$f" ]] || continue
+  case "$(basename "$f")" in
+    sql.zig|*_test.zig|test_fixtures_*.zig) continue ;;
+  esac
+  [[ -f "$f" ]] || continue
+  scanned=$((scanned + 1))
+
+  is_new=0
+  if [[ "$STAGED" -eq 1 ]]; then
+    status="$(git diff --cached --name-status -- "$f" | awk 'NR==1 {print $1}')"
+    if [[ "$status" == A* ]]; then
+      is_new=1
+    elif ! git ls-files --error-unmatch "$f" >/dev/null 2>&1; then
+      is_new=1
+    fi
+  else
+    is_new=1   # --all: no diff context — whole-file scan
+  fi
+
+  if [[ "$is_new" -eq 1 ]]; then
+    line="$(definition_hit "$f")"
+    [[ -n "$line" ]] || line="$(body_hit "$f")"
+  else
+    line="$(added_hit "$f")"
+  fi
+
+  if [[ -n "$line" ]]; then
+    fail "$f adds inline SQL ($line); move statements to domain sql.zig"
+  fi
+done
+
+if [[ "$FAIL" -ne 0 ]]; then
+  printf "\n🔴 SQLMOD: inline SQL found — move statements to a domain sql.zig. See dispatch/write_zig.md.\n" >&2
+  exit 1
+fi
+ok "SQLMOD: clean ($scanned file(s) scanned, no new inline SQL)"
+exit 0

package/audits/ufs.sh

@@ -0,0 +1,303 @@
+#!/usr/bin/env bash
+# ufs.sh — enforce RULE UFS (Unified Form for Symbols) across the worktree.
+#
+# Dispatch façade: dispatch/write_any.md (UFS Gate)
+# Fires in: make lint, CONFORM.
+#
+# Generic detection — no manifest of known literals, so the audit scales
+# as the codebase grows. Three classes of violation:
+#
+#   1. string-dup-file   — same string literal ≥2× in one source file
+#   2. numeric-suspect   — power-of-ten or unit-factor numeric not bound
+#                          to a const, not on a pin-test carve-out line
+#   3. cross-runtime-orphan — SCREAMING_SNAKE const defined in one runtime
+#                          but missing from a sibling runtime the diff touches
+#
+# Carve-out: any `// pin test: literal is the contract` comment on or
+# above the offending line excludes that line from numeric-suspect.
+# A `const` / `pub const` / `export const` declaration line is likewise
+# exempt for both per-file checks (is_const_decl + its string-dup mirror
+# below) — binding the literal to a name on a const line clears the hit.
+#
+# Staged-scope semantics: --staged narrows WHICH FILES are scanned, not
+# how much of each — a staged file is audited in FULL, so staging a file
+# for an unrelated one-line change drags its pre-existing literal debt
+# into the commit. Broad sweeps (renames touching N files) surface N
+# files' latent hits at once; plan that cleanup before staging.
+#
+# 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.
+#   Deterministic negative fixtures under `evals/dispatch/fixtures/` are
+#   excluded from storage scans. The dispatch evaluator copies each fixture
+#   into `src/` before asserting its expected pass or failure result.
+#   The previous `--diff` (BASE...HEAD) mode was retired with M70 because
+#   it was blind to the index at pre-commit time.
+#
+# Usage:
+#   ufs.sh           # full-codebase scan (default)
+#   ufs.sh --all     # alias for default
+#   ufs.sh --staged  # narrow per-file checks (string-dup, numeric) to
+#                    # `git diff --cached`; cross-runtime parity stays full-tree
+#
+# Exits 0 clean, 1 on any blocking violation.
+
+set -euo pipefail
+
+# Default: full-codebase scan (`--all` is an explicit alias). `--staged` is the
+# pre-commit lens — it narrows the per-file checks to `git diff --cached`. The
+# retired `--diff` (BASE...HEAD) mode stays rejected; `--staged` reads the index
+# and so is not blind to staged-but-uncommitted fixes (M70's concern).
+MODE="${1:-}"
+case "$MODE" in
+  ""|--all|all)    MODE="--all" ;;
+  --staged|staged) MODE="--staged" ;;
+  *)
+    printf "usage: %s [--all|--staged]\n" "$0" >&2
+    printf "note: --diff was retired in M70 — see dispatch/write_any.md (UFS Gate → Scope). Use --staged for the pre-commit (index) lens.\n" >&2
+    exit 2
+    ;;
+esac
+ROOT="$(git rev-parse --show-toplevel)"
+cd "$ROOT"
+
+FAIL=0
+violations=()
+record() { violations+=("$*"); FAIL=1; }
+ok()     { printf "OK:   %s\n" "$*"; }
+
+# ── File scope ──────────────────────────────────────────────────────────────
+
+is_source() {
+  local f="$1"
+  case "$f" in
+    vendor/*|third_party/*|.zig-cache/*|*/node_modules/*|evals/dispatch/fixtures/*|*.tsbuildinfo) return 1 ;;
+    *_test.zig|*.test.ts|*.test.tsx|*.test.js|*.test.jsx|*.unit.test.js|*.spec.ts) ;; # tests in scope
+  esac
+  case "$f" in
+    *.zig|*.ts|*.tsx|*.js|*.jsx) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# Per-file check scope (string-dup-file, numeric-suspect). --staged narrows to
+# the commit; cross-runtime-orphan (below) always scans the full tree.
+if [ "$MODE" = "--staged" ]; then
+  scope_files() { git diff --cached --name-only --diff-filter=ACMRT; }
+else
+  scope_files() { git ls-files; }
+fi
+mapfile -t FILES < <(scope_files | while read -r f; do
+  is_source "$f" && echo "$f"
+done)
+
+[ "${#FILES[@]}" -eq 0 ] && { ok "audit-ufs: no source files in scope"; exit 0; }
+
+# ── 1. string-dup-file ──────────────────────────────────────────────────────
+# Extract double-quoted string literals (best-effort regex; ignores escapes
+# inside strings — fine for this discipline check, not a parser). Skip
+# 1-char strings, common short labels, doc-strings, JSON keys.
+
+# Perf (M70): single awk over all files instead of per-file pipeline
+# (was 5 forks × ~760 files = ~20s). Group counts by FILENAME so the
+# "≥2 occurrences in one file" semantic is preserved.
+#
+# Subshell-propagation fix (M70): the loop reads from a process
+# substitution (not a pipe) so `record` mutates FAIL / violations in
+# the parent shell. The previous pipe-into-while form ran the loop in
+# a subshell and silently dropped violations.
+while IFS= read -r row; do
+  record "$row"
+done < <(awk '
+  FNR == 1 {
+    prev_file = FILENAME
+    # Test files: repetition is fixture data, not magic strings.
+    # Skip string-dup-file for tests; other checks still apply.
+    is_test = (FILENAME ~ /(_test\.zig|\.test\.|\.spec\.|\.unit\.test|\.integration\.test|\/test\/|\/tests\/)/)
+  }
+  is_test { next }
+  # ui/ files: extracting class-strings or short literals to file-local
+  # consts is fragile in TypeScript (type-position uses widen string|
+  # literal types, and the cleanup belongs in a UI-aware spec). Skip
+  # string-dup-file for ui/packages/*/src; cross-runtime-orphan still
+  # runs against ui/ to catch ERR_* parity drift.
+  # macOS/BSD awk aborts on a `/` inside a `[...]` class in a regex *literal*
+  # ("nonterminated character class"); use a dynamic-regex STRING — identical
+  # match on gawk, portable on BWK awk (the macOS default). Do not re-inline.
+  FILENAME ~ "^ui/packages/[^/]+/(src|app|tests|components|lib|hooks)/" { next }
+  FNR == 1 { in_test_block = 0; test_depth = 0; in_block_comment = 0 }
+  {
+    line = $0
+    # Block-comment exclusion (TS/JS/Zig non-applicable): skip lines inside /* ... */
+    if (in_block_comment) {
+      if (line ~ /\*\//) in_block_comment = 0
+      next
+    }
+    if (line ~ /\/\*/ && line !~ /\*\//) {
+      in_block_comment = 1
+      next
+    }
+    # Zig multi-line string literal — lines start with `\\` after whitespace.
+    if (FILENAME ~ /\.zig$/ && line ~ /^[[:space:]]*\\\\/) next
+    # Inline-test exclusion (Zig): track depth across `test "..." {` blocks.
+    if (FILENAME ~ /\.zig$/) {
+      if (in_test_block) {
+        test_depth += gsub(/\{/, "{", line) - gsub(/\}/, "}", line)
+        if (test_depth <= 0) in_test_block = 0
+        line = $0  # restore
+        next
+      }
+      if (line ~ /^test[[:space:]]+"/) {
+        in_test_block = 1
+        tmp = line
+        test_depth = gsub(/\{/, "{", tmp) - gsub(/\}/, "}", tmp)
+        if (test_depth <= 0) in_test_block = 0
+        next
+      }
+    }
+    sub(/\/\/.*$/, "", line)
+    # Strip single-line /* ... */ inline block comments (jsdoc/etc) so
+    # literals inside them are not counted.
+    gsub(/\/\*[^*]*\*+([^\/*][^*]*\*+)*\//, "", line)
+    # Const-BINDING carve-out (narrower than the numeric-suspect is_const_decl
+    # exemption below — deliberately): a literal that IS the right-hand side of a
+    # `const`/`pub const`/`export const` binding is its single-source DEFINITION,
+    # not a magic-string use. Two distinct named constants may legitimately share
+    # a value across domains (e.g. a runner status and a lease status both
+    # "active") — RULE UFS targets UN-named repetition, and both sites there are
+    # already named. But a literal passed as a CALL ARGUMENT on a const line
+    # (`const x = foo("lit");`) is NOT named by that const — it counts and flags
+    # like any other use. (A prior line-level skip exempted those too and silently
+    # gutted the check for most Zig code; the ufs_dup_string eval fixture pins the
+    # binding-level semantic.)
+    if (line ~ /(^|[[:space:]])(pub[[:space:]]+const|export[[:space:]]+const|const)[[:space:]]+[A-Za-z_$][A-Za-z0-9_$]*([[:space:]]*:[^=]*)?[[:space:]]*=[[:space:]]*"((\\.)|[^\\"])+"[[:space:]]*(as[[:space:]]+const)?[[:space:]]*[;,]?[[:space:]]*$/) next
+    rest = line
+    # Strip Zig identifier-escape syntax @"name" — body is an identifier,
+    # not a string literal, but the regex below would otherwise match it.
+    gsub(/@"[^"]*"/, "", rest)
+    # Strip empty string literals so the regex below cannot fuse
+    # two adjacent Zig literals through their inner gap.
+    gsub(/""/, "", rest)
+    # Match a quoted string literal honouring \" escapes: open quote,
+    # then runs of (backslash+any-char) | (non-backslash-non-quote),
+    # then close quote. Min 3 chars total ensures literal body ≥1 char
+    # (back-compat with the {2,} body-min from the prior regex).
+    while (match(rest, /"((\\.)|[^\\"])+"/)) {
+      lit = substr(rest, RSTART, RLENGTH)
+      rest = substr(rest, RSTART + RLENGTH)
+      if (length(lit) < 4) continue
+      if (lit ~ /^"(http|https|file|\/|\\\\|\\\\n)/) continue
+      key = FILENAME "\034" lit
+      count[key]++
+      file_of[key] = FILENAME
+      lit_of[key] = lit
+    }
+  }
+  END {
+    for (k in count) {
+      if (count[k] >= 2) {
+        printf "string-dup-file %s %s %d\n", file_of[k], lit_of[k], count[k]
+      }
+    }
+  }
+' "${FILES[@]}")
+
+# ── 2. numeric-suspect ──────────────────────────────────────────────────────
+# Flag bare power-of-ten and unit-factor numerics in expressions.
+# Pattern matches: 1_000, 1_000_000, 1_000_000_000, 1e3, 1e6, 1e9,
+# 60, 3600, 86400, 1024, 1048576, 10_000_000, 100_000.
+# A line is a violation if:
+#  - it contains one of those patterns
+#  - the line is NOT a const declaration (`pub const`, `export const`, `const`)
+#  - the line is NOT marked `// pin test: literal is the contract`
+#  - the line above is NOT marked `// pin test: literal is the contract`
+
+# Boundaries are capturing groups, not \b: macOS/BSD awk treats \b as a backspace,
+# so word-boundary anchors silently match nothing. The leading/trailing boundary
+# chars are trimmed back off the extracted token below (see RSTART/RLENGTH use).
+NUMERIC_RE='(^|[^0-9A-Za-z_])(1[_e]?0{3,12}|1_000(_000)*|10_000_000|100_000|1024|1048576|3600|86400)([^0-9A-Za-z_]|$)'
+
+# Perf (M70): single awk across all files; FNR == 1 detects file boundary
+# so the "prev line carve-out" stays per-file. Process substitution keeps
+# the while loop in the parent shell so record() mutates FAIL.
+while IFS= read -r row; do
+  record "$row"
+done < <(awk -v re="$NUMERIC_RE" '
+  FNR == 1 { prev = "" }
+  {
+    line = $0
+    is_pin_now   = (line ~ /pin test: literal is the contract/)
+    is_pin_above = (prev ~ /pin test: literal is the contract/)
+    is_const_decl = (line ~ /(^|[[:space:]])(pub[[:space:]]+const|export[[:space:]]+const|const)[[:space:]]/)
+    stripped = line
+    sub(/\/\/.*$/, "", stripped)
+    sub(/#.*$/, "", stripped)
+    if (!is_pin_now && !is_pin_above && !is_const_decl && match(stripped, re)) {
+      tok = substr(stripped, RSTART, RLENGTH)
+      gsub(/^[^0-9]+|[^0-9_e]+$/, "", tok)   # trim the captured boundary chars
+      printf "numeric-suspect %s:%d %s\n", FILENAME, FNR, tok
+    }
+    prev = line
+  }
+' "${FILES[@]}")
+
+# ── 3. cross-runtime-orphan ─────────────────────────────────────────────────
+# Full-codebase ERR_* parity check. Scoped to ERR_* prefix because that's
+# the cross-runtime contract surface (server error codes consumed by
+# clients). Server (Zig) is the source of truth — every JS/TS ERR_* must
+# have a matching Zig pub const ERR_*. Zig-only ERR_* consts are fine
+# (server-internal codes don't need a client mirror).
+#
+# Scans the *working tree* via `git ls-files` — sees staged content even
+# before it lands in HEAD, closing the previous diff-mode blindspot where
+# a fix staged in pre-commit couldn't satisfy a check that only read
+# committed history.
+#
+# Perf (M70): batched `xargs grep` (single process across all files)
+# instead of `xargs -I{} grep` (one process per file). On agentsfleet the
+# server-side scan dropped from ~30s to <2s.
+
+zig_err=$(git ls-files -z -- 'src/*.zig' 2>/dev/null \
+  | { grep -zvE '_test\.zig$|^src/zbench_fixtures\.zig$' || true; } \
+  | xargs -0 grep -hE '^pub const ERR_[A-Z][A-Z0-9_]+[[:space:]]*=' 2>/dev/null \
+  | grep -oE 'ERR_[A-Z][A-Z0-9_]+' | sort -u || true)
+
+js_err=$(git ls-files -z -- 'agentsfleet/src/*.js' 'agentsfleet/src/*.jsx' 'agentsfleet/src/*.ts' 'agentsfleet/src/*.tsx' 2>/dev/null \
+  | { grep -zvE '\.test\.|\.spec\.' || true; } \
+  | xargs -0 grep -hE '^export const ERR_[A-Z][A-Z0-9_]+[[:space:]]*=' 2>/dev/null \
+  | grep -oE 'ERR_[A-Z][A-Z0-9_]+' | sort -u || true)
+
+ui_err=$(git ls-files -z -- 'ui/packages/*/src/*.ts' 'ui/packages/*/src/*.tsx' 2>/dev/null \
+  | { grep -zvE '\.test\.|\.spec\.' || true; } \
+  | xargs -0 grep -hE '^export const ERR_[A-Z][A-Z0-9_]+[[:space:]]*=' 2>/dev/null \
+  | grep -oE 'ERR_[A-Z][A-Z0-9_]+' | sort -u || true)
+
+# Every JS ERR_* must exist in Zig.
+for c in $js_err; do
+  if ! echo "$zig_err" | grep -qx "$c"; then
+    record "cross-runtime-orphan $c absent-in-zig"
+  fi
+done
+# Every TS (UI) ERR_* must exist in Zig.
+for c in $ui_err; do
+  if ! echo "$zig_err" | grep -qx "$c"; then
+    record "cross-runtime-orphan $c absent-in-zig"
+  fi
+done
+
+# ── Report ──────────────────────────────────────────────────────────────────
+
+if [ "$FAIL" -eq 0 ]; then
+  ok "audit-ufs: no violations across ${#FILES[@]} file(s)"
+  exit 0
+fi
+
+printf "🔴 UFS GATE — %d violation(s):\n" "${#violations[@]}" >&2
+for v in "${violations[@]}"; do
+  printf "  %s\n" "$v" >&2
+done
+printf "\nResolve by either (1) extract to a named const + replace all sites,\n" >&2
+printf "(2) add the matching const in the missing sibling runtime same-commit,\n" >&2
+printf "or (3) annotate '// pin test: literal is the contract' on/above the line.\n" >&2
+exit 1