@agentsfleet/orly 0.10.13 → 0.11.0

package/audits/doc-reads.ts

@@ -0,0 +1,41 @@
+import { readFileSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+
+type ReadRow = { ts: number; path: string; blob: string; section: string };
+const DIGEST = /^[a-f0-9]+$/;
+const STRING_TYPE = "string";
+
+function escaped(value: string): string { return JSON.stringify(value).slice(1, -1); }
+
+function readRow(value: unknown): ReadRow | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const row = value as Partial<ReadRow>;
+  if (!Number.isSafeInteger(row.ts) || row.ts! < 0 || typeof row.path !== STRING_TYPE || typeof row.blob !== STRING_TYPE || typeof row.section !== STRING_TYPE) return undefined;
+  if (!DIGEST.test(row.blob) || row.path.includes("\0")) return undefined;
+  return row as ReadRow;
+}
+
+function current(log: string, root: string): void {
+  for (const line of readFileSync(log, "utf8").split("\n")) {
+    let row;
+    try { row = readRow(JSON.parse(line)); } catch { continue; }
+    if (!row) continue;
+    const file = resolve(root, row.path);
+    const within = relative(root, file);
+    if (isAbsolute(within) || within === ".." || within.startsWith("../")) continue;
+    const hash = Bun.spawnSync(["git", "-C", root, "hash-object", file], { stdout: "pipe", stderr: "ignore" });
+    if (hash.exitCode === 0 && hash.stdout.toString().trim() === row.blob) {
+      process.stdout.write(`${escaped(row.path)}\t${row.ts}\t${escaped(row.section)}\n`);
+    }
+  }
+}
+
+const [mode, ...args] = Bun.argv.slice(2);
+if (mode === "escape") process.stdout.write(escaped(args[0] ?? ""));
+else if (mode === "current") current(args[0]!, args[1]!);
+else if (mode === "log") {
+  const [ts, path, blob, section] = args;
+  const row = readRow({ ts: Number(ts), path, blob, section });
+  if (!row) throw new Error("invalid document read record");
+  process.stdout.write(`${JSON.stringify(row)}\n`);
+} else throw new Error("expected log, current or escape");

package/audits/error-codes.sh

@@ -49,7 +49,11 @@
 
 set -euo pipefail
 
-MODE="${1:-${SCOPE:-all}}"
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/scope.sh"
+audit_scope_init --all "$@"
+audit_index_snapshot "$@"
+
+MODE="$AUDIT_MODE"
 ROOT="$(git rev-parse --show-toplevel)"
 cd "$ROOT"
 
@@ -62,8 +66,8 @@ CODE_RE="${PREFIX}-[A-Z][A-Z0-9]*-[0-9]{3,}"
 REGISTRY_PATHS=()
 RUNTIME=""
 if [[ -n "${ORLY_ERROR_REGISTRY:-}" ]]; then
-  while IFS= read -r f; do [[ -n "$f" ]] && REGISTRY_PATHS+=("$f"); done < <(
-    git ls-files -- $ORLY_ERROR_REGISTRY 2>/dev/null || true)
+  while IFS= read -r -d '' f; do [[ -n "$f" ]] && REGISTRY_PATHS+=("$f"); done < <(
+    git ls-files -z -- "$ORLY_ERROR_REGISTRY")
   [[ ${#REGISTRY_PATHS[@]} -gt 0 ]] || {
     printf "FAIL: ORLY_ERROR_REGISTRY matched no tracked file: %s\n" "$ORLY_ERROR_REGISTRY" >&2
     exit 1
@@ -127,27 +131,14 @@ declared_count=$(printf '%s\n' "$declared_codes" | wc -l | tr -d ' ')
 #    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 -- $SOURCE_GLOB 2>/dev/null \
-        | grep -vE "^(${REGISTRY_RE})$" || true
-      ;;
-    --all|all)
-      git ls-files -- $SOURCE_GLOB 2>/dev/null \
-        | grep -vE "^(${REGISTRY_RE})$" || true
-      ;;
-    *)
-      printf "usage: %s [--staged|--all]\n" "$0" >&2
-      exit 64
-      ;;
-  esac
-}
-
-# `while read` rather than mapfile: mapfile is bash 4+ and macOS ships 3.2 —
-# the portability rule scripts/run-playbook-tests.sh already records.
 USED_PATHS=()
-while IFS= read -r p; do USED_PATHS+=("$p"); done < <(gather_used_paths)
+RAW_PATHS=()
+while IFS= read -r -d '' p; do
+  [ -f "$p" ] || continue
+  if printf '%s\n' "$p" | grep -qE "^(${REGISTRY_RE})$"; then continue; fi
+  USED_PATHS+=("$p")
+  if ! printf '%s\n' "$p" | grep -qE "$ALLOWLIST_RE"; then RAW_PATHS+=("$p"); fi
+done < <(audit_scope_paths "$SOURCE_GLOB")
 if [[ ${#USED_PATHS[@]} -eq 0 ]]; then
   ok "no source files in scope ($MODE)"
   exit 0
@@ -246,6 +237,8 @@ fi
 #       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=""
+if [ "${#RAW_PATHS[@]}" -gt 0 ]; then
 raw_leaks=$(awk -v prefix="$PREFIX" '
   FNR == 1 { skip_next = 0; in_rs_test = 0; rs_open = 0; rs_depth = 0 }
   # Rust keeps its unit tests INSIDE the file they cover, under
@@ -275,8 +268,8 @@ raw_leaks=$(awk -v prefix="$PREFIX" '
   $0 ~ "\"" prefix "-[A-Z][A-Z0-9-]*-[0-9]+\"" {
     print FILENAME ":" FNR ":" $0;
   }
-' $(printf '%s\n' "${USED_PATHS[@]}" | grep -vE \
-    "$ALLOWLIST_RE" || true) 2>/dev/null || true)
+' "${RAW_PATHS[@]}" 2>/dev/null || true)
+fi
 
 if [[ -n "$raw_leaks" ]]; then
   fail "raw UZ-* literals found outside the registry allowlist (must reference a registry symbol):"

package/audits/logging-rust.awk

@@ -0,0 +1,145 @@
+# Rust tracing and diagnostic detection; the shell owns scope and findings.
+    function count_char(text, char, copy, count) {
+      copy = text
+      count = gsub(char, "", copy)
+      return count
+    }
+    function code_only(text, output, cursor, char, escaped, quoted) {
+      output = ""
+      escaped = 0
+      quoted = 0
+      for (cursor = 1; cursor <= length(text); cursor++) {
+        char = substr(text, cursor, 1)
+        if (quoted) {
+          if (escaped) escaped = 0
+          else if (char == "\\") escaped = 1
+          else if (char == "\"") quoted = 0
+          continue
+        }
+        if (char == "\"") {
+          quoted = 1
+          continue
+        }
+        if (char == "/" && substr(text, cursor + 1, 1) == "/") break
+        output = output char
+      }
+      return output
+    }
+    function without_comment(text, output, cursor, char, escaped, quoted) {
+      output = ""
+      escaped = 0
+      quoted = 0
+      for (cursor = 1; cursor <= length(text); cursor++) {
+        char = substr(text, cursor, 1)
+        if (quoted) {
+          output = output char
+          if (escaped) escaped = 0
+          else if (char == "\\") escaped = 1
+          else if (char == "\"") quoted = 0
+          continue
+        }
+        if (char == "\"") {
+          quoted = 1
+          output = output char
+          continue
+        }
+        if (char == "/" && substr(text, cursor + 1, 1) == "/") break
+        output = output char
+      }
+      return output
+    }
+    function comment_text(text, cursor, char, escaped, quoted) {
+      escaped = 0
+      quoted = 0
+      for (cursor = 1; cursor <= length(text); cursor++) {
+        char = substr(text, cursor, 1)
+        if (quoted) {
+          if (escaped) escaped = 0
+          else if (char == "\\") escaped = 1
+          else if (char == "\"") quoted = 0
+          continue
+        }
+        if (char == "\"") {
+          quoted = 1
+          continue
+        }
+        if (char == "/" && substr(text, cursor + 1, 1) == "/")
+          return substr(text, cursor + 2)
+      }
+      return ""
+    }
+    function has_logging_reason(text, comment) {
+      comment = comment_text(text)
+      return comment ~ /^[[:space:]]*logging:[[:space:]]*[^[:space:]]/
+    }
+    function check_emit() {
+      if (emit_code !~ /event[[:space:]]*=/ && emit_code !~ /[(,][[:space:]]*event[[:space:]]*[,)]/)
+        printf "event|%s|%d\n", FILENAME, emit_line
+      if (emit_source ~ /"[^"\n]*\{[^"\n]*\}[^"\n]*"/)
+        printf "positional|%s|%d\n", FILENAME, emit_line
+      emit_code = ""
+      emit_source = ""
+      in_emit = 0
+    }
+    FNR == 1 {
+      depth = 0
+      test_depth = 0
+      cfg_test = 0
+      in_emit = 0
+      emit_parens = 0
+      emit_code = ""
+      emit_source = ""
+      previous_annotation = 0
+    }
+    {
+      current_annotation = has_logging_reason($0)
+      code = code_only($0)
+      if (!in_emit && code ~ /^[[:space:]]*$/) {
+        previous_annotation = current_annotation
+        next
+      }
+      opens = count_char(code, "\\{")
+      closes = count_char(code, "\\}")
+      if (test_depth > 0) {
+        depth += opens - closes
+        if (depth < test_depth) test_depth = 0
+        previous_annotation = current_annotation
+        next
+      }
+      if (code ~ /^[[:space:]]*#\[cfg\(test\)\]/) {
+        if (opens > 0) {
+          test_depth = depth + 1
+          depth += opens - closes
+          if (depth < test_depth) test_depth = 0
+        } else cfg_test = 1
+        previous_annotation = current_annotation
+        next
+      }
+      if (cfg_test) {
+        if (opens > 0) {
+          test_depth = depth + 1
+          depth += opens - closes
+          if (depth < test_depth) test_depth = 0
+          cfg_test = 0
+        } else if (code ~ /;/) cfg_test = 0
+        previous_annotation = current_annotation
+        next
+      }
+      if (code ~ /(^|[^[:alnum:]_])(println|eprintln|dbg)!/ && !current_annotation && !previous_annotation)
+        printf "direct|%s|%d\n", FILENAME, FNR
+      if (!in_emit && match(code, /tracing::(error|warn|info|debug|trace)!/)) {
+        in_emit = 1
+        emit_line = FNR
+        emit_code = code
+        emit_source = without_comment($0)
+        macro = substr(code, RSTART)
+        emit_parens = count_char(macro, "\\(") - count_char(macro, "\\)")
+      } else if (in_emit) {
+        emit_code = emit_code " " code
+        emit_source = emit_source " " without_comment($0)
+        emit_parens += count_char(code, "\\(") - count_char(code, "\\)")
+      }
+      if (in_emit && emit_parens <= 0) check_emit()
+      depth += opens - closes
+      previous_annotation = current_annotation
+    }

package/audits/logging.sh

@@ -41,6 +41,10 @@
 
 set -euo pipefail
 
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/scope.sh"
+audit_scope_init --all "$@"
+audit_index_snapshot "$@"
+
 MODE="--all"
 STRICT=0
 for arg in "$@"; do
@@ -52,7 +56,8 @@ for arg in "$@"; do
       printf "usage: %s [--staged|--all] [--strict]\n" "$0"
       exit 0
       ;;
-    *) printf "unknown arg: %s\n" "$arg" >&2; exit 64 ;;
+    -*) printf "unknown arg: %s\n" "$arg" >&2; exit 2 ;;
+    *) MODE=explicit ;;
   esac
 done
 
@@ -94,26 +99,10 @@ is_non_runtime_rust_path() {
 # ---------------------------------------------------------------------------
 # 1. Gather files in scope.
 # ---------------------------------------------------------------------------
-gather_paths() {
-  case "$MODE" in
-    --staged)
-      git diff --cached --name-only --diff-filter=ACMRT \
-        | grep -E '(^src/.*\.zig$|\.rs$|^agentsfleet/src/.*\.(js|jsx|ts|tsx)$)' || true
-      ;;
-    --all)
-      find src -type f -name '*.zig' 2>/dev/null || true
-      while IFS= read -r path; do
-        [[ -f "$path" ]] && printf '%s\n' "$path"
-      done < <(git ls-files --cached --others --exclude-standard -- '*.rs')
-      find agentsfleet/src -type f \( -name '*.js' -o -name '*.jsx' -o -name '*.ts' -o -name '*.tsx' \) 2>/dev/null || true
-      ;;
-  esac
-}
-
-# `while read` rather than mapfile: mapfile is bash 4+ and macOS ships 3.2 —
-# the portability rule scripts/run-playbook-tests.sh already records.
 FILES=()
-while IFS= read -r p; do FILES+=("$p"); done < <(gather_paths)
+while IFS= read -r -d '' p; do
+  [ ! -f "$p" ] || FILES+=("$p")
+done < <(audit_scope_paths '*.zig' '*.rs' 'agentsfleet/src/*.js' 'agentsfleet/src/*.jsx' 'agentsfleet/src/*.ts' 'agentsfleet/src/*.tsx')
 if [[ ${#FILES[@]} -eq 0 ]]; then
   ok "no source files in scope ($MODE)"
   exit 0
@@ -222,152 +211,7 @@ if [[ ${#rust_candidates[@]} -gt 0 ]]; then
         rust_positional_hits=$((rust_positional_hits + 1))
         ;;
     esac
-  done < <(awk '
-    function count_char(text, char, copy, count) {
-      copy = text
-      count = gsub(char, "", copy)
-      return count
-    }
-    function code_only(text, output, cursor, char, escaped, quoted) {
-      output = ""
-      escaped = 0
-      quoted = 0
-      for (cursor = 1; cursor <= length(text); cursor++) {
-        char = substr(text, cursor, 1)
-        if (quoted) {
-          if (escaped) escaped = 0
-          else if (char == "\\") escaped = 1
-          else if (char == "\"") quoted = 0
-          continue
-        }
-        if (char == "\"") {
-          quoted = 1
-          continue
-        }
-        if (char == "/" && substr(text, cursor + 1, 1) == "/") break
-        output = output char
-      }
-      return output
-    }
-    function without_comment(text, output, cursor, char, escaped, quoted) {
-      output = ""
-      escaped = 0
-      quoted = 0
-      for (cursor = 1; cursor <= length(text); cursor++) {
-        char = substr(text, cursor, 1)
-        if (quoted) {
-          output = output char
-          if (escaped) escaped = 0
-          else if (char == "\\") escaped = 1
-          else if (char == "\"") quoted = 0
-          continue
-        }
-        if (char == "\"") {
-          quoted = 1
-          output = output char
-          continue
-        }
-        if (char == "/" && substr(text, cursor + 1, 1) == "/") break
-        output = output char
-      }
-      return output
-    }
-    function comment_text(text, cursor, char, escaped, quoted) {
-      escaped = 0
-      quoted = 0
-      for (cursor = 1; cursor <= length(text); cursor++) {
-        char = substr(text, cursor, 1)
-        if (quoted) {
-          if (escaped) escaped = 0
-          else if (char == "\\") escaped = 1
-          else if (char == "\"") quoted = 0
-          continue
-        }
-        if (char == "\"") {
-          quoted = 1
-          continue
-        }
-        if (char == "/" && substr(text, cursor + 1, 1) == "/")
-          return substr(text, cursor + 2)
-      }
-      return ""
-    }
-    function has_logging_reason(text, comment) {
-      comment = comment_text(text)
-      return comment ~ /^[[:space:]]*logging:[[:space:]]*[^[:space:]]/
-    }
-    function check_emit() {
-      if (emit_code !~ /event[[:space:]]*=/ && emit_code !~ /[(,][[:space:]]*event[[:space:]]*[,)]/)
-        printf "event|%s|%d\n", FILENAME, emit_line
-      if (emit_source ~ /"[^"\n]*\{[^"\n]*\}[^"\n]*"/)
-        printf "positional|%s|%d\n", FILENAME, emit_line
-      emit_code = ""
-      emit_source = ""
-      in_emit = 0
-    }
-    FNR == 1 {
-      depth = 0
-      test_depth = 0
-      cfg_test = 0
-      in_emit = 0
-      emit_parens = 0
-      emit_code = ""
-      emit_source = ""
-      previous_annotation = 0
-    }
-    {
-      current_annotation = has_logging_reason($0)
-      code = code_only($0)
-      if (!in_emit && code ~ /^[[:space:]]*$/) {
-        previous_annotation = current_annotation
-        next
-      }
-      opens = count_char(code, "\\{")
-      closes = count_char(code, "\\}")
-      if (test_depth > 0) {
-        depth += opens - closes
-        if (depth < test_depth) test_depth = 0
-        previous_annotation = current_annotation
-        next
-      }
-      if (code ~ /^[[:space:]]*#\[cfg\(test\)\]/) {
-        if (opens > 0) {
-          test_depth = depth + 1
-          depth += opens - closes
-          if (depth < test_depth) test_depth = 0
-        } else cfg_test = 1
-        previous_annotation = current_annotation
-        next
-      }
-      if (cfg_test) {
-        if (opens > 0) {
-          test_depth = depth + 1
-          depth += opens - closes
-          if (depth < test_depth) test_depth = 0
-          cfg_test = 0
-        } else if (code ~ /;/) cfg_test = 0
-        previous_annotation = current_annotation
-        next
-      }
-      if (code ~ /(^|[^[:alnum:]_])(println|eprintln|dbg)!/ && !current_annotation && !previous_annotation)
-        printf "direct|%s|%d\n", FILENAME, FNR
-      if (!in_emit && match(code, /tracing::(error|warn|info|debug|trace)!/)) {
-        in_emit = 1
-        emit_line = FNR
-        emit_code = code
-        emit_source = without_comment($0)
-        macro = substr(code, RSTART)
-        emit_parens = count_char(macro, "\\(") - count_char(macro, "\\)")
-      } else if (in_emit) {
-        emit_code = emit_code " " code
-        emit_source = emit_source " " without_comment($0)
-        emit_parens += count_char(code, "\\(") - count_char(code, "\\)")
-      }
-      if (in_emit && emit_parens <= 0) check_emit()
-      depth += opens - closes
-      previous_annotation = current_annotation
-    }
-  ' "${rust_candidates[@]}")
+  done < <(awk -f "$AUDIT_HOME/logging-rust.awk" "${rust_candidates[@]}")
 fi
 
 # ---------------------------------------------------------------------------

package/audits/msid-ui.sh

@@ -72,27 +72,31 @@ MODE="${1:---staged}"
 ROOT="$(git rev-parse --show-toplevel)"
 cd "$ROOT"
 
+EXPLICIT=()
 case "$MODE" in
   --staged|staged)
-    DIFF_CMD="git diff --cached -U0"
+    [ "$#" -le 1 ] || { printf 'choose a mode or explicit files\n' >&2; exit 2; }
+    DIFF_ARGS=(--cached)
     POST_REF=":"
     LABEL="staged"
     ;;
   --diff|diff)
+    [ "$#" -le 1 ] || { printf 'choose a mode or explicit files\n' >&2; exit 2; }
     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"
+    if ! git rev-parse --verify "${BASE}^{commit}" >/dev/null 2>&1; then
+      printf 'FAIL: comparison revision is missing: %s\n' "$BASE" >&2; exit 2
+    fi
+    DIFF_ARGS=("${BASE}...HEAD")
     POST_REF="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
-    ;;
+  -h|--help) printf 'usage: %s [--staged|--diff|file ...]\n' "$0"; exit 0 ;;
+  -*) printf 'usage: %s [--staged|--diff|file ...]\n' "$0" >&2; exit 2 ;;
   *)
-    echo "usage: $0 [--staged|--diff]" >&2; exit 2 ;;
+    for path in "$@"; do
+      case "$path" in -*) printf 'unknown audit option: %s\n' "$path" >&2; exit 2 ;; esac
+    done
+    EXPLICIT=("$@"); POST_REF=""; LABEL="explicit files" ;;
 esac
 
 # Single awk pass; reads stdin (the unified diff).
@@ -111,10 +115,11 @@ esac
 # The hunk header carries the post-image line number, so `line_above` can fetch
 # the neighbouring line out of the post-image the mode named. Same shape as
 # audits/design-tokens.sh, which has always read its override out of the file.
-hits=$($DIFF_CMD | awk -v post_ref="$POST_REF" '
+scan_diff() {
+ORLY_AUDIT_PATH="$1" awk -v post_ref="$POST_REF" '
   # BWK awk (macOS) has no gensub and no --posix quoting help; APOSTROPHE is
   # built rather than written, because this program is inside single quotes.
-  BEGIN { APOSTROPHE = sprintf("%c", 39) }
+  BEGIN { APOSTROPHE = sprintf("%c", 39); f = ENVIRON["ORLY_AUDIT_PATH"] }
 
   # The source line above line `n` of `path`, from the post-image, or "" when
   # there is none. Cached: a hunk may ask about the same neighbour repeatedly,
@@ -124,16 +129,23 @@ hits=$($DIFF_CMD | awk -v post_ref="$POST_REF" '
     key = path SUBSEP n
     if (key in above) return above[key]
     above[key] = ""
-    # A path holding an apostrophe cannot go through the quoting below. No
-    # carve-out beats a mis-quoted shell command built from a filename.
-    if (index(path, APOSTROPHE) > 0) return ""
-    cmd = "git show " APOSTROPHE post_ref path APOSTROPHE " 2>/dev/null | sed -n " (n - 1) "p"
+    if (post_ref == "") cmd = "sed -n " (n - 1) "p " shell_quote(path)
+    else cmd = "git show " shell_quote(post_ref path) " 2>/dev/null | sed -n " (n - 1) "p"
     if ((cmd | getline out) > 0) above[key] = out
     close(cmd)
     return above[key]
   }
 
-  /^\+\+\+ b\// { f=$2; sub("^b/","",f); next }
+  function shell_quote(s,    i,c,out) {
+    out = APOSTROPHE
+    for (i = 1; i <= length(s); i++) {
+      c = substr(s, i, 1)
+      if (c == APOSTROPHE) out = out APOSTROPHE "\\" APOSTROPHE APOSTROPHE
+      else out = out c
+    }
+    return out APOSTROPHE
+  }
+  /^\+\+\+/ { next }
   # `@@ -a,b +c,d @@` — $3 is the post-image start line for this hunk.
   /^@@/ { start=$3; sub(/^\+/,"",start); split(start,parts,","); nl=parts[1]+0; next }
   /^[^+]/ { next }
@@ -173,7 +185,22 @@ hits=$($DIFF_CMD | awk -v post_ref="$POST_REF" '
       print "UI     " f ": " line
     }
   }
-')
+'
+}
+
+hits=$(
+  if [ "${#EXPLICIT[@]}" -gt 0 ]; then
+    for path in "${EXPLICIT[@]}"; do
+      [ -f "$path" ] || continue
+      # diff returns one for differences; that is expected input here.
+      { git diff --no-index --no-ext-diff -U0 -- /dev/null "$path" || [ "$?" -eq 1 ]; } | scan_diff "$path"
+    done
+  else
+    while IFS= read -r -d '' path; do
+      git diff --no-ext-diff -U0 "${DIFF_ARGS[@]}" -- "$path" | scan_diff "$path"
+    done < <(git diff --name-only -z --diff-filter=ACMRT "${DIFF_ARGS[@]}")
+  fi
+)
 
 if [ -n "$hits" ]; then
   echo "FAIL: audit-msid-ui ($LABEL) — MS-ID / UI hits below"

package/audits/rule-ledger-lib.sh

@@ -63,6 +63,9 @@ JUDGMENT_TAG='\[JUDGMENT → [A-Za-z0-9_:-]+\]'
 UNENFORCED_TAG='\[UNENFORCED → [^]]+\]'
 
 LEDGER_ROOT="${ORLY_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+LEDGER_SOURCE_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+LEDGER_RULES_ROOT="$LEDGER_ROOT"
+case "$LEDGER_SOURCE_ROOT" in */.orly) LEDGER_RULES_ROOT="$LEDGER_SOURCE_ROOT" ;; esac
 
 # A tag alone on its line (the `> [DETERMINISTIC → FLL]` form dispatch/*.md
 # already uses) covers every clause under it until the next heading. A tag at
@@ -139,7 +142,7 @@ ledger_doc_codes() {
 # code that loses its helper stops claiming enforcement here the same commit.
 ledger_code_script() {
   local code="$1" script
-  script="$(grep -hoE "^dispatch_run_helper +\"$code\" +\"[^\"]+\"" "$LEDGER_ROOT"/dispatch/*.sh 2>/dev/null \
+  script="$(grep -hoE "^dispatch_run_helper +\"$code\" +\"[^\"]+\"" "$LEDGER_RULES_ROOT"/dispatch/*.sh 2>/dev/null \
     | sed -E 's/.*"([^"]+)"$/\1/' | head -1)"
   printf '%s' "${script:-$UNWIRED_CODE_LABEL}"
 }
@@ -153,7 +156,7 @@ UNWIRED_CODE_LABEL="no helper row"
 # form and the ~/Projects/dotfiles/-anchored form appear in the corpus, so the
 # anchor is stripped before comparison.
 ledger_cited_docs() {
-  grep -rhoE '(~/Projects/dotfiles/)?docs/[A-Za-z0-9_/-]+\.md' "$LEDGER_ROOT"/dispatch/*.md 2>/dev/null \
+  grep -rhoE '(~/Projects/dotfiles/)?docs/[A-Za-z0-9_/-]+\.md' "$LEDGER_RULES_ROOT"/dispatch/*.md 2>/dev/null \
     | sed -E 's|^~/Projects/dotfiles/||' \
     | sort -u
 }
@@ -199,7 +202,7 @@ FACADE_SCOPE_TAG='^[[:space:]]*<!--[[:space:]]*oracle-scope:[^>]*-->[[:space:]]*
 
 ledger_facade_pages() {
   local file
-  for file in "$LEDGER_ROOT"/dispatch/*.md; do
+  for file in "$LEDGER_RULES_ROOT"/dispatch/*.md; do
     [ -f "$file" ] || continue
     printf '%s\n' "$file"
   done
@@ -223,7 +226,7 @@ ledger_facade_scope() {
 
 ledger_facade_scripts() {
   local file
-  for file in "$LEDGER_ROOT"/dispatch/*.sh; do
+  for file in "$LEDGER_RULES_ROOT"/dispatch/*.sh; do
     [ -f "$file" ] || continue
     [ "$(basename "$file")" = "$DISPATCH_LIB_BASENAME" ] && continue
     printf '%s\n' "$file"
@@ -267,7 +270,7 @@ ledger_match_count() {
 # the bare and the ~/Projects/dotfiles/-anchored spelling of the same path.
 ledger_facades_citing() {
   local doc="$1" page
-  for page in "$LEDGER_ROOT"/dispatch/*.md; do
+  for page in "$LEDGER_RULES_ROOT"/dispatch/*.md; do
     [ -f "$page" ] || continue
     grep -qF "$doc" "$page" 2>/dev/null && printf '%s\n' "$(basename "$page" .md)"
   done
@@ -288,7 +291,7 @@ ledger_doc_trigger() {
   while IFS= read -r stem; do
     [ -n "$stem" ] || continue
     cited=0
-    script="$LEDGER_ROOT/dispatch/$stem.sh"
+    script="$LEDGER_RULES_ROOT/dispatch/$stem.sh"
     [ -f "$script" ] || continue
     [ -n "$(ledger_facade_globs "$script")" ] || continue
     printf '%s' "$TRIGGER_MECHANICAL"