@agentsfleet/orly 0.5.0

package/audits/error-codes.sh

@@ -0,0 +1,221 @@
+#!/usr/bin/env bash
+# error-codes.sh — orphan + dead code detection against the canonical
+# error registry at src/agentsfleetd/errors/error_registry.zig, plus a raw-literal check
+# enforcing that UZ-<CAT>-<NNN> strings only appear in registry/allowlist
+# files (every other call site must reference the registry symbol).
+#
+# Dispatch façade: dispatch/write_any.md (Error Registry Gate)
+# Fires in: CONFORM (via `make harness-verify` in `agentsfleet`).
+#
+# TECHNICAL DEBT (acknowledged on migration to dotfiles, 2026-05-11):
+# The script hard-codes:
+#   - `UZ-` as the error-code prefix (agentsfleet schema)
+#   - `src/agentsfleetd/errors/error_registry.zig` as the canonical registry path
+#   - The raw-literal allowlist below (src/agentsfleetd/errors/**, src/runner/engine/client_errors.zig)
+# A parameterised version that reads prefix + registry path + allowlist
+# from a per-project config (e.g. `.audit-error-codes.toml`) is the right
+# long-term shape; not done yet. Today, this script lives in dotfiles so
+# the gate body and the audit binary stay co-located.
+#
+# Definitions:
+#   - DECLARED  — every UZ-<CAT>-<NNN> string literal in error_registry.zig
+#   - USED      — every UZ-<CAT>-<NNN> reference in src/**/*.zig (excluding
+#                  the registry itself). agentsfleet/src/** is intentionally
+#                  out of scope — the CLI consumes server-emitted UZ-* codes
+#                  as opaque strings from API responses; the dispatcher's
+#                  typed CliError variants are the CLI's named surface.
+#   - ORPHAN    — USED but not DECLARED  (BLOCKING)
+#   - DEAD      — DECLARED but not USED  (INFORMATIONAL)
+#   - RAW LEAK  — UZ-<CAT>-<NNN> string literal in a source file outside
+#                  the registry/allowlist (BLOCKING — RULE UFS at the error
+#                  surface; non-allowlisted call sites must use a registry
+#                  symbol, never duplicate the literal).
+#
+# Raw-literal allowlist (files where UZ-* literals are legitimate):
+#   - src/agentsfleetd/errors/**            (canonical registry + entry tables)
+#   - src/runner/engine/client_errors.zig   (the runner engine's own mirror file
+#                                            — see file header for build-module
+#                                            isolation rationale; deliberate
+#                                            duplication, all other executor
+#                                            sources import from there)
+#   - **/*_test.zig                         (tests)
+#   - src/zbench_fixtures.zig               (benchmark fixture seeds)
+#   - src/agentsfleetd/http/test_harness.zig (HTTP test harness)
+#   - lines starting with `//`              (comments)
+#   - lines annotated `// audit-error-codes: intentional-fake`
+#
+# Tests INCLUDED for orphan detection — same code-registry rules apply to
+# test code. A test referencing a fake code (e.g. UZ-FAKE-999) for
+# negative-path testing must annotate the line:
+# `// audit-error-codes: intentional-fake` and the audit will skip it.
+#
+# Modes:
+#   --staged   diff-scope: only files in `git diff --cached` are checked
+#              for new orphan refs (registry checked unconditionally)
+#   --all      (default) full repo scan
+#
+# Exits 0 clean, 1 on orphans or raw leaks (DEAD findings never block).
+
+set -euo pipefail
+
+MODE="${1:-${SCOPE:-all}}"
+ROOT="$(git rev-parse --show-toplevel)"
+cd "$ROOT"
+
+REGISTRY="src/agentsfleetd/errors/error_registry.zig"
+[[ -f "$REGISTRY" ]] || { printf "FAIL: registry missing: %s\n" "$REGISTRY" >&2; exit 1; }
+
+FAIL=0
+fail() { printf "FAIL: %s\n" "$*" >&2; FAIL=1; }
+ok()   { printf "OK:   %s\n" "$*"; }
+note() { printf "NOTE: %s\n" "$*"; }
+
+# ---------------------------------------------------------------------------
+# 1. Extract DECLARED codes from the registry.
+#    Pattern: literal "UZ-<CAT>-<NNN>" inside the registry file. <CAT> may
+#    contain digits but must start with a letter (e.g. UUIDV7), so the class is
+#    [A-Z][A-Z0-9]* — a bare [A-Z]+ stops at the first digit and silently drops
+#    the entire UZ-UUIDV7-* family (its category ends in a digit), leaving those
+#    codes invisible to the orphan/dead/used passes below.
+# ---------------------------------------------------------------------------
+declared_codes=$(grep -oE 'UZ-[A-Z][A-Z0-9]*-[0-9]{3,}\b' "$REGISTRY" | sort -u)
+if [[ -z "$declared_codes" ]]; then
+  fail "no codes declared in $REGISTRY (registry empty?)"
+  exit 1
+fi
+declared_count=$(printf '%s\n' "$declared_codes" | wc -l | tr -d ' ')
+
+# ---------------------------------------------------------------------------
+# 2. Determine USED codes.
+#    Source set: src/**/*.zig minus *_test.zig minus the registry itself,
+#    plus agentsfleet/src/**.
+# ---------------------------------------------------------------------------
+gather_used_paths() {
+  case "$MODE" in
+    --staged|staged)
+      git diff --cached --name-only --diff-filter=ACMRT \
+        | grep -E '^src/' \
+        | grep -vE '^src/agentsfleetd/errors/error_registry\.zig$' || true
+      ;;
+    --all|all)
+      find src -type f -name '*.zig' 2>/dev/null \
+        | grep -vE '^src/agentsfleetd/errors/error_registry\.zig$'
+      ;;
+    *)
+      printf "usage: %s [--staged|--all]\n" "$0" >&2
+      exit 64
+      ;;
+  esac
+}
+
+mapfile -t USED_PATHS < <(gather_used_paths)
+if [[ ${#USED_PATHS[@]} -eq 0 ]]; then
+  ok "no source files in scope ($MODE)"
+  exit 0
+fi
+
+used_codes=$(awk '
+  # Reset per-file so a trailing intentional-fake marker in the previous
+  # file cannot carry skip_next=1 into the first line of the next file.
+  FNR == 1 { skip_next = 0 }
+  # Skip the line carrying the marker AND the next non-blank line (the
+  # marker sits on the comment line above the code line in Zig style).
+  /audit-error-codes: intentional-fake/ { skip_next = 1; next }
+  /^[[:space:]]*$/ { next }
+  skip_next { skip_next = 0; next }
+  {
+    line = $0;
+    while (match(line, /UZ-[A-Z][A-Z0-9]*-[0-9][0-9][0-9][0-9]*/)) {
+      m = substr(line, RSTART, RLENGTH);
+      # Reject codes whose digit run is followed by a word char (rejects
+      # placeholder forms like UZ-INTERNAL-00X that grep would truncate).
+      tail_pos = RSTART + RLENGTH;
+      if (tail_pos <= length(line)) {
+        tail_char = substr(line, tail_pos, 1);
+        if (tail_char ~ /[A-Za-z0-9_]/) {
+          line = substr(line, tail_pos + 1);
+          continue;
+        }
+      }
+      print m;
+      line = substr(line, tail_pos);
+    }
+  }
+' "${USED_PATHS[@]}" 2>/dev/null | sort -u || true)
+used_count=0
+[[ -n "$used_codes" ]] && used_count=$(printf '%s\n' "$used_codes" | wc -l | tr -d ' ')
+
+# ---------------------------------------------------------------------------
+# 3. Compute orphans (USED − DECLARED). Blocking.
+# ---------------------------------------------------------------------------
+orphans=$(comm -23 <(printf '%s\n' "$used_codes") <(printf '%s\n' "$declared_codes") | grep -v '^$' || true)
+if [[ -n "$orphans" ]]; then
+  fail "orphan codes (used but not declared in $REGISTRY):"
+  while IFS= read -r code; do
+    [[ -z "$code" ]] && continue
+    printf "        %s  refs:\n" "$code" >&2
+    grep -lE "$code" "${USED_PATHS[@]}" 2>/dev/null \
+      | head -3 \
+      | sed 's/^/          - /' >&2 || true
+  done <<<"$orphans"
+fi
+
+# ---------------------------------------------------------------------------
+# 4. Compute dead codes (DECLARED − USED). Informational only.
+#    --staged mode skips this (full set isn't computed against partial diff).
+# ---------------------------------------------------------------------------
+if [[ "$MODE" = "--all" || "$MODE" = "all" ]]; then
+  dead=$(comm -13 <(printf '%s\n' "$used_codes") <(printf '%s\n' "$declared_codes") | grep -v '^$' || true)
+  if [[ -n "$dead" ]]; then
+    dead_count=$(printf '%s\n' "$dead" | wc -l | tr -d ' ')
+    note "dead codes (declared but unreferenced — informational, $dead_count total):"
+    printf '%s\n' "$dead" | head -10 | sed 's/^/        /'
+    [[ "$dead_count" -gt 10 ]] && printf "        ... and %d more\n" "$((dead_count - 10))"
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# 4.5. Raw-literal check.
+#      Any "UZ-…" string literal outside the allowlist (and not inside a
+#      `//` comment or annotated with `audit-error-codes: intentional-fake`)
+#      is a violation: the call site must reference a registry symbol.
+#
+#      Multi-segment codes (e.g. `UZ-OBS-OTEL-LOG-001`) are caught too,
+#      even though the orphan/dead detection above uses a stricter
+#       2-segment pattern. We don't want a "UZ-X-Y-NNN" code reintroduced
+#      via a local const that the orphan pass silently ignores.
+# ---------------------------------------------------------------------------
+raw_leaks=$(awk '
+  FNR == 1 { skip_next = 0 }
+  # Skip the line carrying the marker AND the next non-blank line.
+  /audit-error-codes: intentional-fake/ { skip_next = 1; next }
+  /^[[:space:]]*\/\// { next }
+  /^[[:space:]]*$/ { next }
+  skip_next { skip_next = 0; next }
+  # Match any "UZ-XXX(-YYY)*-NNN" string literal.
+  /"UZ-[A-Z][A-Z0-9-]*-[0-9]+"/ {
+    print FILENAME ":" FNR ":" $0;
+  }
+' $(printf '%s\n' "${USED_PATHS[@]}" | grep -vE \
+    '^src/agentsfleetd/errors/|/_?test_harness\.zig$|_test\.zig$|^src/runner/engine/client_errors\.zig$|^src/zbench_fixtures\.zig$' \
+    || true) 2>/dev/null || true)
+
+if [[ -n "$raw_leaks" ]]; then
+  fail "raw UZ-* literals found outside the registry allowlist (must reference a registry symbol):"
+  printf '%s\n' "$raw_leaks" | head -20 | sed 's/^/        /' >&2
+  raw_count=$(printf '%s\n' "$raw_leaks" | wc -l | tr -d ' ')
+  if [[ "$raw_count" -gt 20 ]]; then
+    printf "        ... and %d more\n" "$((raw_count - 20))" >&2
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# 5. Verdict.
+# ---------------------------------------------------------------------------
+ok "registry: $declared_count declared, $used_count used"
+if [[ $FAIL -ne 0 ]]; then
+  printf "\n🔴 ERROR REGISTRY GATE: violations found. Reference the registry symbol (e.g. \`error_codes.ERR_X\` or \`client_errors.ERR_X\` for the executor crate) instead of duplicating the literal.\n" >&2
+  exit 1
+fi
+ok "ERROR REGISTRY GATE: clean"
+exit 0

package/audits/fixtures/clean.diff

@@ -0,0 +1,15 @@
+diff --git a/src/example.zig b/src/example.zig
+new file mode 100644
+index 0000000..3333333
+--- /dev/null
++++ b/src/example.zig
+@@ -0,0 +1,2 @@
++const example_name = "sample";
++fn run() void {}
+diff --git a/ui/packages/app/page.tsx b/ui/packages/app/page.tsx
+new file mode 100644
+index 0000000..4444444
+--- /dev/null
++++ b/ui/packages/app/page.tsx
+@@ -0,0 +1,1 @@
++import { Button } from "@design-system"; export default () => <Button>ok</Button>;

package/audits/fixtures/dirty.diff

@@ -0,0 +1,16 @@
+diff --git a/src/example.zig b/src/example.zig
+new file mode 100644
+index 0000000..1111111
+--- /dev/null
++++ b/src/example.zig
+@@ -0,0 +1,3 @@
++// M40_001 example
++pub const example_name = "M40_001 sample";
++pub fn run() void {}
+diff --git a/ui/packages/app/page.tsx b/ui/packages/app/page.tsx
+new file mode 100644
+index 0000000..2222222
+--- /dev/null
++++ b/ui/packages/app/page.tsx
+@@ -0,0 +1,1 @@
++export default () => <button>raw</button>;

package/audits/lifecycle-anchors.sh

@@ -0,0 +1,22 @@
+# shellcheck shell=bash
+# lifecycle-anchors.sh — semantic-drift tripwire between the rendered
+# operating model and the lifecycle runbook façade. Dispatch parity proves
+# INVENTORY (files ↔ table ↔ REQUIRED); this proves the load-bearing lifecycle
+# strings exist in BOTH AGENTS.md (each stage's binding essence) and
+# dispatch/lifecycle.md (the runbook), so neither side can drift away from the
+# other while `make audit` stays green. Anchor list: LIFECYCLE_ANCHORS in
+# audits/data.sh — extend it when a new load-bearing string lands in both.
+#
+# Sourced by audits/agents-md.sh (label: "lifecycle anchors").
+#   check_lifecycle_anchors <ROOT>   # echoes FAIL lines, returns 0/1
+
+check_lifecycle_anchors() {
+  local root="$1" rc=0 anchor
+  for anchor in "${LIFECYCLE_ANCHORS[@]}"; do
+    grep -qF -- "$anchor" "$root/AGENTS.md" \
+      || { echo "FAIL: lifecycle anchor missing from AGENTS.md: $anchor"; rc=1; }
+    grep -qF -- "$anchor" "$root/dispatch/lifecycle.md" \
+      || { echo "FAIL: lifecycle anchor missing from dispatch/lifecycle.md: $anchor"; rc=1; }
+  done
+  return $rc
+}

package/audits/logging.sh

@@ -0,0 +1,217 @@
+#!/usr/bin/env bash
+# logging.sh — flag log-emit drift against LOGGING_STANDARD.md.
+#
+# Dispatch façade: dispatch/write_any.md (Logging Gate)
+# Fires in: CONFORM (via `make harness-verify` in `agentsfleet`).
+#
+# TECHNICAL DEBT (acknowledged on migration to dotfiles, 2026-05-11):
+# The script hard-codes:
+#   - agentsfleet scope-prefix format from LOGGING_STANDARD §7 (the
+#     `log.scoped(...)` API path under `src/logging/`)
+#   - `UZ-XXX-NNN` as the `error_code=` substring per LOGGING_STANDARD §5
+#   - `src/` + `agentsfleet/src/` as the scan roots
+# A parameterised version that reads prefix + scope-api path + scan
+# roots from a per-project config is the right long-term shape; not
+# done yet. Today, this script lives in dotfiles so the gate body and
+# the audit binary stay co-located.
+#
+# Two severity tiers:
+#   BLOCK  — exits 1, must fix:
+#            - `std.debug.print(` in non-test source under src/.
+#            - `console.log/debug/info/warn/error` in agentsfleet/src outside tests.
+#   INFO   — surfaced for reviewer/agent attention, doesn't block:
+#            - `std.log.scoped(...)` outside `src/logging/` (LOGGING_STANDARD §7
+#              says only the named-module `log.scoped` API should be used;
+#              today's callers are pre-migration).
+#            - `std.log.{err,warn,info,debug}` calls (positional fmt format) — the
+#              old API. Migration to `log.<level>("event", .{...})` pending.
+#            - `err`/`warn` log calls without an `error_code=` substring nearby.
+#
+# Modes:
+#   --staged   diff-scope: only files in `git diff --cached`
+#   --all      (default) full src/ + agentsfleet/src/ scan
+#   --strict   promote every INFO finding to BLOCK (post-migration use)
+#
+# Exits 0 clean, 1 on BLOCK findings.
+
+set -euo pipefail
+
+MODE="--all"
+STRICT=0
+for arg in "$@"; do
+  case "$arg" in
+    --staged|staged) MODE="--staged" ;;
+    --all|all)       MODE="--all" ;;
+    --strict)        STRICT=1 ;;
+    -h|--help)
+      printf "usage: %s [--staged|--all] [--strict]\n" "$0"
+      exit 0
+      ;;
+    *) printf "unknown arg: %s\n" "$arg" >&2; exit 64 ;;
+  esac
+done
+
+ROOT="$(git rev-parse --show-toplevel)"
+cd "$ROOT"
+
+FAIL=0
+INFO_COUNT=0
+fail() { printf "FAIL: %s\n" "$*" >&2; FAIL=1; }
+ok()   { printf "OK:   %s\n" "$*"; }
+note() { printf "INFO: %s\n" "$*"; INFO_COUNT=$((INFO_COUNT + 1)); }
+
+# Test-file carve-out — skip Zig test sources from every detection
+# pass. Test code legitimately exercises log emits (deliberate err
+# paths, logger smoke tests) and uses raw std.log to keep tests
+# self-contained; the migration discipline applies to production
+# source. Returns 0 (skip) for test paths, 1 (scan) otherwise.
+is_test_zig() {
+  case "$1" in
+    *_test.zig) return 0 ;;
+    *_test_harness.zig) return 0 ;;
+    *_test_helper.zig) return 0 ;;
+    */tests/*) return 0 ;;
+  esac
+  case "$(basename "$1")" in
+    test_harness.zig) return 0 ;;
+    test_helper.zig) return 0 ;;
+  esac
+  return 1
+}
+
+# ---------------------------------------------------------------------------
+# 1. Gather files in scope.
+# ---------------------------------------------------------------------------
+gather_paths() {
+  case "$MODE" in
+    --staged)
+      git diff --cached --name-only --diff-filter=ACMRT \
+        | grep -E '^(src/.*\.zig$|agentsfleet/src/.*\.(js|jsx|ts|tsx)$)' || true
+      ;;
+    --all)
+      find src -type f -name '*.zig' 2>/dev/null
+      find agentsfleet/src -type f \( -name '*.js' -o -name '*.jsx' -o -name '*.ts' -o -name '*.tsx' \) 2>/dev/null
+      ;;
+  esac
+}
+
+mapfile -t FILES < <(gather_paths)
+if [[ ${#FILES[@]} -eq 0 ]]; then
+  ok "no source files in scope ($MODE)"
+  exit 0
+fi
+
+# Build the in-scope file subsets once. The per-section loops below
+# previously ran 3–4 forks × N files; M70 perf pass batches them into
+# single awk/grep passes.
+zig_nontest=()
+js_nontest=()
+for f in "${FILES[@]}"; do
+  if [[ "$f" == *.zig ]] && ! is_test_zig "$f"; then
+    zig_nontest+=("$f")
+  fi
+  case "$f" in
+    agentsfleet/src/*.test.*|agentsfleet/src/*.spec.*|agentsfleet/src/tests/*) ;;
+    agentsfleet/src/*.js|agentsfleet/src/*.jsx|agentsfleet/src/*.ts|agentsfleet/src/*.tsx)
+      js_nontest+=("$f")
+      ;;
+  esac
+done
+
+# ---------------------------------------------------------------------------
+# 2. BLOCKING: std.debug.print in non-test Zig source.
+# ---------------------------------------------------------------------------
+debug_print_hits=0
+if [[ ${#zig_nontest[@]} -gt 0 ]]; then
+  # Single awk across every non-test .zig file; FNR == 1 resets the
+  # `test "..."` block tracker per file. Skips lines inside inline tests.
+  while IFS= read -r match; do
+    [[ -z "$match" ]] && continue
+    f="${match%%:*}"
+    ln="${match#*:}"
+    fail "$f:$ln — \`std.debug.print\` in non-test source (LOGGING_STANDARD §10A.L1)"
+    debug_print_hits=$((debug_print_hits + 1))
+  done < <(awk '
+    FNR == 1 { in_test = 0 }
+    /^test "/ { in_test = 1; next }
+    /^}/ { in_test = 0; next }
+    /(^|[^A-Za-z0-9_])std\.debug\.print\(/ { if (!in_test) printf "%s:%d\n", FILENAME, FNR }
+  ' "${zig_nontest[@]}")
+fi
+
+# ---------------------------------------------------------------------------
+# 3. BLOCKING: console.log/debug/info/warn/error in agentsfleet/src non-test.
+# ---------------------------------------------------------------------------
+console_hits=0
+if [[ ${#js_nontest[@]} -gt 0 ]]; then
+  while IFS= read -r match; do
+    [[ -z "$match" ]] && continue
+    f="${match%%:*}"
+    rest="${match#*:}"
+    ln="${rest%%:*}"
+    fail "$f:$ln — \`console.*\` in non-test source (write_ts_adhere_bun.md §10, LOGGING_STANDARD §8)"
+    console_hits=$((console_hits + 1))
+  done < <(grep -nHE '\bconsole\.(log|debug|info|warn|error)\(' "${js_nontest[@]}" 2>/dev/null || true)
+fi
+
+# ---------------------------------------------------------------------------
+# 4. INFO: std.log.scoped outside src/logging/ (pre-migration to the named
+#    `log` module's scoped API). The audit no longer carves out src/auth/ —
+#    the named module is import-able from layer-isolated trees, so the
+#    portability exception is gone.
+# ---------------------------------------------------------------------------
+scoped_hits=0
+scoped_eligible=()
+for f in "${zig_nontest[@]}"; do
+  case "$f" in
+    src/logging/*) continue ;;
+  esac
+  scoped_eligible+=("$f")
+done
+if [[ ${#scoped_eligible[@]} -gt 0 ]]; then
+  while IFS= read -r line; do
+    [[ -z "$line" ]] && continue
+    count="${line%% *}"
+    f="${line#* }"
+    note "$f — $count call(s) to \`std.log.scoped\` (migrate to \`logging.scoped\` per LOGGING_STANDARD §7)"
+    scoped_hits=$((scoped_hits + count))
+  done < <(grep -cHE '\bstd\.log\.scoped\(' "${scoped_eligible[@]}" 2>/dev/null \
+    | awk -F: '$2 > 0 { print $2, $1 }')
+fi
+
+# ---------------------------------------------------------------------------
+# 5. INFO: err/warn logs without `error_code=` substring on the same line.
+#    Heuristic — captures the common case where an err/warn line should
+#    embed UZ-XXX-NNN per LOGGING_STANDARD §5.
+# ---------------------------------------------------------------------------
+missing_code_hits=0
+if [[ ${#zig_nontest[@]} -gt 0 ]]; then
+  while IFS= read -r line; do
+    [[ -z "$line" ]] && continue
+    [[ "$line" == *error_code=* ]] && continue
+    f="${line%%:*}"
+    rest="${line#*:}"
+    ln="${rest%%:*}"
+    note "$f:$ln — \`std.log.{err,warn}\` without \`error_code=\` (LOGGING_STANDARD §5)"
+    missing_code_hits=$((missing_code_hits + 1))
+  done < <(grep -nHE '\bstd\.log\.(err|warn)\b' "${zig_nontest[@]}" 2>/dev/null || true)
+fi
+
+# ---------------------------------------------------------------------------
+# 6. Promote INFO to BLOCK in --strict mode.
+# ---------------------------------------------------------------------------
+if [[ $STRICT -eq 1 && $INFO_COUNT -gt 0 ]]; then
+  fail "--strict: $INFO_COUNT informational findings promoted to blocking"
+fi
+
+# ---------------------------------------------------------------------------
+# 7. Verdict.
+# ---------------------------------------------------------------------------
+ok "scanned ${#FILES[@]} files; std.debug.print=$debug_print_hits console.*=$console_hits std.log.scoped=$scoped_hits missing-error_code=$missing_code_hits"
+if [[ $FAIL -ne 0 ]]; then
+  printf "\n🔴 LOGGING GATE: blocking violations. See dispatch/write_any.md (Logging Gate).\n" >&2
+  exit 1
+fi
+[[ $INFO_COUNT -gt 0 ]] && note "$INFO_COUNT informational findings; not blocking. Use --strict to enforce."
+ok "LOGGING GATE: clean (blocking layer)"
+exit 0

package/audits/msid-ui.sh

@@ -0,0 +1,144 @@
+#!/usr/bin/env bash
+# msid-ui.sh — single awk pass over the diff, running the two
+# discipline checks that share a regex pass (MS-ID + UI substitution).
+# Previously `combined.sh`; renamed once the PUB clause moved to
+# zlint + agent chat-output discipline (see commit history).
+#
+# Emits per-line hits for:
+#   * MS-ID — milestone-id leak in source/config (M{N}_{NNN}, §X.Y, T{N},
+#             dim {N}.{N}) outside docs/ + node_modules/ + vendor/.
+#             Test files are NOT exempt (RULE TST-NAM).
+#   * UI    — raw HTML element in ui/packages/app/*.{tsx,jsx} where a
+#             design-system primitive exists (UI Component Substitution Gate).
+#
+# Non-empty hit list → exit 1. Otherwise exit 0 + one OK line.
+#
+# Note on PUB:
+#   This script no longer flags `pub` declarations. The PUB GATE
+#   (dispatch/write_zig.md, pub-surface) has two mechanical enforcers and one
+#   human one; this script was a fourth, redundant layer:
+#     * Orphan check ("is anyone using this pub?") → zlint's
+#       `unused-decls: error` rule, run by `make lint` later in the
+#       same pre-commit pass. A `pub` with no in-tree consumer fails
+#       there. The audit's regex was duplicating this signal with
+#       false positives (e.g. variant lines inside private blocks)
+#       and no way to distinguish necessary pubs from gratuitous ones.
+#     * Design call ("is this pub shape right?") → the agent's
+#       chat-printed PUB GATE verdict block, which the script cannot
+#       see by construction. A regex on `^pub ` was approximating
+#       this as friction, but produced unfixable false positives on
+#       every legitimate new public surface and had no override path.
+#   Removing the PUB clause aligns with the gate body's own design
+#   (which already delegates mechanical work to zlint and design work
+#   to the agent's chat output).
+#
+# Per-check scope (M70):
+#   Unlike the rest of the audit-*.sh family, this script stays
+#   diff-shaped (asserts on *added* `^\+` lines, not file state).
+#   Each sub-check's rule is shaped as "don't introduce X" rather than
+#   "X must not exist anywhere", so a full-codebase scan would change
+#   the semantic:
+#     * MS-ID — flags milestone identifiers added in this commit.
+#               Historical docs in `done/` legitimately contain them,
+#               and code comments may reference them in old commits.
+#               Only newly-added M{N}_{NNN} citations should fail.
+#     * UI    — flags raw HTML primitives added now where a design-system
+#               component exists. Legacy raw-HTML in unrelated files is
+#               cleaned by the touch-it-fix-it rule (RULE NLR), not by
+#               this audit's scope.
+#
+#   Conversion to full-codebase scope needs separate research. Pre-commit
+#   sees staged content through `git diff --cached`, so staged-but-uncommitted
+#   content is covered by this script's checks.
+#
+# Modes:
+#   --staged  (default) diff against `git diff --cached -U0`
+#             — pre-commit context; index includes staged content
+#   --diff              diff against origin/main (vs BASE...HEAD)
+#             — used by `make harness-verify-all` periodic deep audit
+#
+# Dispatch façades:
+#   dispatch/write_any.md (Milestone-ID Gate)
+#   dispatch/write_ts_adhere_bun.md (UI Component Substitution)
+#   dispatch/write_zig.md (pub-surface)  (handled by zlint + agent chat output, not this script)
+
+set -euo pipefail
+
+MODE="${1:---staged}"
+ROOT="$(git rev-parse --show-toplevel)"
+cd "$ROOT"
+
+case "$MODE" in
+  --staged|staged)
+    DIFF_CMD="git diff --cached -U0"
+    LABEL="staged"
+    ;;
+  --diff|diff)
+    BASE="${BASE:-origin/main}"
+    if ! git rev-parse --verify "$BASE" >/dev/null 2>&1; then BASE="HEAD"; fi
+    DIFF_CMD="git diff -U0 ${BASE}...HEAD"
+    LABEL="vs $BASE"
+    ;;
+  --all|all)
+    # No "all" mode — this audit is diff-shaped by construction (it
+    # asserts on *added* lines, not file state). Force callers to pick.
+    echo "usage: $0 [--staged|--diff]" >&2
+    exit 2
+    ;;
+  *)
+    echo "usage: $0 [--staged|--diff]" >&2; exit 2 ;;
+esac
+
+# Single awk pass; reads stdin (the unified diff).
+# Override-recognition: an immediately-preceding `+` line in the diff
+# containing the relevant override marker suppresses the next hit for
+# that rule on the current `+` line.
+hits=$($DIFF_CMD | awk '
+  /^\+\+\+ b\// { f=$2; sub("^b/","",f); prev_added=""; next }
+  /^[^+]/ { prev_added=""; next }
+  /^\+/ {
+    line=$0
+    sub(/^\+/,"",line)
+    ms_id_override = (prev_added ~ /MILESTONE ID ALLOWED per user override/)
+    ui_override = (prev_added ~ /UI GATE: SKIPPED per user override/)
+    if (!ms_id_override &&
+        f ~ /\.(zig|sql|ts|tsx|js|jsx|py|rs|go|sh|toml|yaml|json)$/ &&
+        f !~ /^(docs|node_modules|vendor|third_party)\//) {
+      if (match(line, /M[0-9]+_[0-9]+|§[0-9]+(\.[0-9]+)+|(^|[^A-Za-z0-9_])T[0-9]+([^A-Za-z0-9_]|$)|(^|[^A-Za-z0-9_])dim [0-9]+\.[0-9]+([^A-Za-z0-9_]|$)/)) {
+        print "MS-ID  " f ": " line
+      }
+    }
+    # react-hook-form caveat: its prescribed shape is a raw
+    # <form onSubmit={form.handleSubmit(...)}> inside the design-system <Form>
+    # provider (see design-system Form.tsx docstring). No DS form-element
+    # primitive exists to substitute to, so the substitute-if-a-primitive-exists
+    # rule leaves the RHF <form> as the correct raw element. Exempt exactly that
+    # shape; a bare <form> or <form action=...> with no handleSubmit still trips.
+    rhf_form = (line ~ /<form[ \t]/ && line ~ /handleSubmit/)
+    # <section> landmark caveat: a semantic <section aria-label> region has no DS
+    # primitive (Section renders a <div>; role="region" trips oxlint
+    # jsx-a11y/prefer-tag-over-role, which mandates the raw tag). The DS pattern
+    # is <Section asChild><section …>, so exempt a <section> whose immediately
+    # preceding added line opens <Section asChild>. A bare/unwrapped <section>
+    # still trips.
+    ds_section = (line ~ /<section[ \t]/ && prev_added ~ /<Section asChild>/)
+    if (!ui_override && !rhf_form && !ds_section &&
+        f ~ /^ui\/packages\/app\/.*\.(tsx|jsx)$/ &&
+        line ~ /<(section|button|input|dialog|article|nav|header|form)[ \t>\/]/) {
+      print "UI     " f ": " line
+    }
+    prev_added = line
+  }
+')
+
+if [ -n "$hits" ]; then
+  echo "FAIL: audit-msid-ui ($LABEL) — MS-ID / UI hits below"
+  printf '%s\n' "$hits"
+  echo
+  echo "Resolve each hit OR carve out via the relevant gate's override comment."
+  echo "  MS-ID — strip the marker; production code must be milestone-free (RULE TST-NAM)"
+  echo "  UI    — use the design-system primitive; carve out with 'UI GATE: SKIPPED'"
+  exit 1
+fi
+
+echo "OK:   audit-msid-ui ($LABEL) — 0 hits"