@agentsfleet/orly 0.5.0

package/audits/parity-dispatch.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# parity-dispatch.sh — the Stage-2 replacement for agents-md.sh's gate parity.
+#
+# Model B dissolves docs/gates/ (20 cards) into dispatch/ (10 entries). At the
+# Stage-2 switchover, agents-md.sh's gate-parity block (`index ↔ disk ↔
+# REQUIRED_GATES`, over docs/gates/) is deleted and this is sourced + called in
+# its place — line-neutral, so the ≤350 length gate on agents-md.sh still holds.
+#
+# Until then it is exercised only by evals/test-dispatch-parity.sh against a
+# model-B sandbox, proving the switchover audit goes GREEN and BITES before any
+# card is deleted. It does not run on the live (gate-mode) tree.
+#
+#   check_dispatch_parity <ROOT>   # echoes PASS/FAIL lines, returns 0/1
+#
+# Sources of truth (must agree):
+#   (a) disk     — dispatch/*.md   (each entry has exactly one latent .md)
+#   (b) index    — AGENTS.md dispatch-table rows (2nd cell a backticked entry)
+#   (c) expected — REQUIRED_DISPATCH (audits/data.sh)
+
+check_dispatch_parity() {
+  local root="$1" rc=0 e
+  local agents="$root/AGENTS.md"   # separate line: $root must be set before it expands here
+  local bt='`'                     # backtick held in a var (literal ` is fine, but keep it explicit)
+
+  local disk_count table_rows required_count
+  disk_count=$(find "$root/dispatch" -maxdepth 1 -name '*.md' 2>/dev/null | wc -l | tr -d ' ')
+  table_rows=$(grep -cE "^\|[^|]*\| *${bt}[a-z_]+${bt} *\|" "$agents" 2>/dev/null)
+  required_count=${#REQUIRED_DISPATCH[@]}
+
+  if [[ "$disk_count" -ne "$table_rows" || "$table_rows" -ne "$required_count" ]]; then
+    echo "FAIL: dispatch parity — disk=$disk_count ↔ table=$table_rows ↔ REQUIRED=$required_count (all three must match)"
+    rc=1
+  fi
+
+  for e in "${REQUIRED_DISPATCH[@]}"; do
+    [[ -f "$root/dispatch/$e.md" ]] \
+      || { echo "FAIL: dispatch entry has no body: dispatch/$e.md"; rc=1; }
+    grep -qE "^\|[^|]*\| *${bt}$e${bt} *\|" "$agents" 2>/dev/null \
+      || { echo "FAIL: dispatch entry absent from AGENTS.md table: $e"; rc=1; }
+  done
+
+  # docs/gates/ must be EMPTY in the dispatch model (the old empty-set guard
+  # inverts: a leftover card means the switchover is half-done).
+  local leftover
+  leftover=$(find "$root/docs/gates" -maxdepth 1 -name '*.md' 2>/dev/null | wc -l | tr -d ' ')
+  [[ "$leftover" -eq 0 ]] \
+    || { echo "FAIL: docs/gates/ still holds $leftover card(s) — switchover incomplete"; rc=1; }
+
+  [[ $rc -eq 0 ]] && echo "PASS: dispatch parity (disk=$disk_count ↔ table=$table_rows ↔ REQUIRED=$required_count; docs/gates/ empty)"
+  return $rc
+}

package/audits/rule-ledger-lib.sh

@@ -0,0 +1,264 @@
+#!/usr/bin/env bash
+# rule-ledger-lib.sh — shared extractors for audits/rule-ledger.sh.
+#
+# Sourced, never executed. Split from the leaf per dispatch/write_any.md
+# §File & Function Length Gate so both stay well under the cap.
+#
+# The docs/ rule tier is the half of the corpus that dispatch/'s coverage audit
+# cannot see: evals/dispatch/coverage.sh globs dispatch/*.md only. This library
+# supplies the same kind of extraction for docs/, plus the UNENFORCED class that
+# makes "prose nobody checks" a counted number instead of an unknown.
+
+# Rule documents whose enforcement this ledger reports. A docs/*.md cited as a
+# rule read by a dispatch façade but absent from BOTH lists is a parity red:
+# either it belongs here, or it is not a rule doc and belongs in EXCLUDED.
+REGISTERED_DOCS=(
+  "docs/LOGGING_STANDARD.md"
+  "docs/REST_API_DESIGN_GUIDELINES.md"
+  "docs/SCHEMA_CONVENTIONS.md"
+  "docs/DOCUMENTATION_RULES.md"
+  "docs/LIFECYCLE_PATTERNS.md"
+  "docs/CHANGELOG_VOICE.md"
+  "docs/VERIFY_TIERS.md"
+  "docs/greptile-learnings/RULES.md"
+)
+
+# Cited by a façade but deliberately not a rule doc: architecture (describes
+# shape, enforces nothing), the spec template (a form, gated by
+# audits/spec-template.sh), the trigger index, an output-format reference, and
+# product-repo docs that do not exist in this checkout at all.
+EXCLUDED_DOCS=(
+  "docs/DISPATCH_ARCHITECTURE.md"
+  "docs/ORLY_ARCHITECTURE.md"
+  "docs/TEMPLATE.md"
+  "docs/EXECUTE_DOC_READS.md"
+  "docs/HARNESS_VERIFY_OUTPUT.md"
+  "docs/AUTH.md"
+  "docs/changelog.md"
+)
+
+# Prefix-matched exclusions for open-ended trees owned by other repositories.
+EXCLUDED_PREFIXES=(
+  "docs/architecture/"
+)
+
+# A normative clause is a line that binds behaviour. This is a keyword
+# heuristic, not a parse: counts INFORM the reader and never gate a build, so a
+# keyword inside an example block costs nothing but a slightly high number.
+NORMATIVE_PATTERN='\b(MUST|NEVER|ALWAYS|Forbidden|Required|SHALL|Do not|Don.t)\b'
+
+# Markdown table rows are excluded from the clause count. In a rule doc a table
+# is usually a field reference — `| ts_ms | u64 | always | ... |` — where the
+# keyword is a column VALUE, not an obligation, and counting those makes a
+# fully-triaged document look permanently unfinished. Rules stated inside a
+# table restate prose stated elsewhere; they are still read, just not counted.
+TABLE_ROW_PATTERN='^[[:space:]]*\|'
+
+# Enforcement classes. The first two already exist in dispatch/*.md
+# (docs/DISPATCH_ARCHITECTURE.md §6); UNENFORCED is added by this milestone so
+# an acknowledged-prose clause is distinguishable from one nobody has triaged.
+DETERMINISTIC_TAG='\[DETERMINISTIC → [A-Za-z0-9_:-]+\]'
+JUDGMENT_TAG='\[JUDGMENT → [A-Za-z0-9_:-]+\]'
+UNENFORCED_TAG='\[UNENFORCED → [^]]+\]'
+
+LEDGER_ROOT="${ORLY_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+
+# 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
+# the end of a sentence covers that sentence only. Both are needed: a rule doc
+# states some rules as a tagged section and others as one-line asides, and
+# forcing either shape onto the other would mean editing prose to satisfy a
+# counter.
+STANDALONE_TAG_PATTERN='^[[:space:]]*>?[[:space:]]*\[(DETERMINISTIC|JUDGMENT|UNENFORCED) → [^]]+\][[:space:]]*$'
+HEADING_PATTERN='^#{1,6} '
+CLASS_DETERMINISTIC="det"
+CLASS_JUDGMENT="judgment"
+CLASS_UNENFORCED="unenforced"
+
+# Line numbers of every line in a file matching a pattern, one per line.
+ledger_line_numbers() {
+  grep -nE "$2" "$1" 2>/dev/null | cut -d: -f1
+}
+
+# Clause line numbers: keyword lines that are not table rows. Case-insensitive,
+# because a rule reads the same whether the author shouted it or not.
+ledger_clause_lines() {
+  grep -niE "$NORMATIVE_PATTERN" "$1" 2>/dev/null \
+    | grep -vE '^[0-9]+:[[:space:]]*\|' | cut -d: -f1
+}
+
+# The five census numbers for one document, space-separated:
+#   clauses det judgment unenforced untagged
+# Returns 1 without output when the path is absent, so a caller reports the
+# missing registration rather than printing zeroes that look like a clean doc.
+#
+# One pass down the file carrying the section's block tag: a heading clears it,
+# a standalone tag sets it, and every clause takes the tag on its own line
+# first, the block's second, nothing third. Nothing third is the backlog.
+ledger_doc_counts() {
+  local path="$1"
+  local line total block="" class
+  local clauses=0 det=0 judgment=0 unenforced=0 untagged=0
+  [ -f "$path" ] || return 1
+  local is_heading=() is_clause=() line_class=() standalone=()
+  for line in $(ledger_line_numbers "$path" "$HEADING_PATTERN"); do is_heading[$line]=1; done
+  for line in $(ledger_clause_lines "$path"); do is_clause[$line]=1; done
+  for line in $(ledger_line_numbers "$path" "$STANDALONE_TAG_PATTERN"); do standalone[$line]=1; done
+  for line in $(ledger_line_numbers "$path" "$DETERMINISTIC_TAG"); do line_class[$line]="$CLASS_DETERMINISTIC"; done
+  for line in $(ledger_line_numbers "$path" "$JUDGMENT_TAG"); do line_class[$line]="$CLASS_JUDGMENT"; done
+  for line in $(ledger_line_numbers "$path" "$UNENFORCED_TAG"); do line_class[$line]="$CLASS_UNENFORCED"; done
+
+  total="$(wc -l < "$path" | tr -d ' ')"
+  for (( line = 1; line <= total; line++ )); do
+    [ -n "${is_heading[$line]:-}" ] && { block=""; continue; }
+    [ -n "${standalone[$line]:-}" ] && { block="${line_class[$line]:-}"; continue; }
+    [ -n "${is_clause[$line]:-}" ] || continue
+    class="${line_class[$line]:-$block}"
+    clauses=$(( clauses + 1 ))
+    case "$class" in
+      "$CLASS_DETERMINISTIC") det=$(( det + 1 )) ;;
+      "$CLASS_JUDGMENT") judgment=$(( judgment + 1 )) ;;
+      "$CLASS_UNENFORCED") unenforced=$(( unenforced + 1 )) ;;
+      *) untagged=$(( untagged + 1 )) ;;
+    esac
+  done
+  printf '%s %s %s %s %s' "$clauses" "$det" "$judgment" "$unenforced" "$untagged"
+}
+
+# The DETERMINISTIC codes a document's tags name, deduplicated, in the order
+# they appear. This is the actionable half of the scoreboard: not "how many
+# clauses exist" but "which rules here are decided by a script".
+ledger_doc_codes() {
+  grep -oE "$DETERMINISTIC_TAG" "$1" 2>/dev/null \
+    | sed -E 's/.* → ([A-Za-z0-9_:-]+)\]/\1/' | sort -u
+}
+
+# The leaf audit a dispatch façade runs for a code, e.g. LOG → logging.sh. The
+# .sh row is the single source of truth for which script decides a code, so a
+# 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 \
+    | sed -E 's/.*"([^"]+)"$/\1/' | head -1)"
+  printf '%s' "${script:-$UNWIRED_CODE_LABEL}"
+}
+
+# A DETERMINISTIC tag whose code has no helper row is a claim with nothing
+# behind it — named rather than hidden, because that is exactly the drift this
+# ledger exists to surface.
+UNWIRED_CODE_LABEL="no helper row"
+
+# docs/*.md paths any dispatch façade tells the agent to read. Both the bare
+# 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 \
+    | sed -E 's|^~/Projects/dotfiles/||' \
+    | sort -u
+}
+
+# Membership test against a registry array passed by name-expansion.
+ledger_in_list() {
+  local needle="$1"; shift
+  local item
+  for item in "$@"; do [ "$item" = "$needle" ] && return 0; done
+  return 1
+}
+
+# True when a cited path sits under a tree another repository owns.
+ledger_has_prefix() {
+  local doc="$1" prefix
+  for prefix in "${EXCLUDED_PREFIXES[@]}"; do
+    case "$doc" in "$prefix"*) return 0 ;; esac
+  done
+  return 1
+}
+
+# --- trigger scope ------------------------------------------------------------
+#
+# A rule can only fire when something the agent edits matches its façade's
+# scope, and that scope is declared exactly once: the `dispatch_init` line of
+# the façade's executable. Reading it here means the ledger, the doc-read
+# check, and the dispatcher itself can never disagree about what fires.
+
+# dispatch/lib.sh is the shared sourcing target rather than a façade: it
+# declares no scope of its own and must never be read as a glob-less one.
+DISPATCH_LIB_BASENAME="lib.sh"
+
+# The executable façades: dispatch/*.sh minus the shared library.
+ledger_facade_scripts() {
+  local file
+  for file in "$LEDGER_ROOT"/dispatch/*.sh; do
+    [ -f "$file" ] || continue
+    [ "$(basename "$file")" = "$DISPATCH_LIB_BASENAME" ] && continue
+    printf '%s\n' "$file"
+  done
+}
+
+# The file globs a façade declares, space-separated. dispatch_init quotes its
+# language double and every glob single, so the single-quoted run IS the scope.
+# Empty output means the façade declares no scope — the caller reds on that.
+ledger_facade_globs() {
+  grep -hE '^[[:space:]]*dispatch_init[[:space:]]' "$1" 2>/dev/null \
+    | head -1 | grep -oE "'[^']+'" | tr -d "'" | tr '\n' ' '
+}
+
+# How many paths on stdin fall inside a glob set. The unquoted `case` pattern
+# is the match itself — the same expansion dispatch_resolve_files applies to
+# explicit file arguments, so a fire count means what the dispatcher means.
+ledger_match_count() {
+  local globs="$1" path glob matches=0
+  while IFS= read -r path; do
+    [ -n "$path" ] || continue
+    for glob in $globs; do
+      # shellcheck disable=SC2254  # the glob is data; expansion performs the match
+      case "$path" in $glob) matches=$((matches + 1)); break ;; esac
+    done
+  done
+  printf '%d' "$matches"
+}
+
+# The façade stems whose page cites a rule doc. Substring matching catches both
+# 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
+    [ -f "$page" ] || continue
+    grep -qF "$doc" "$page" 2>/dev/null && printf '%s\n' "$(basename "$page" .md)"
+  done
+}
+
+# Whether anything can carry a rule doc into a diff mechanically:
+#   mechanical — a citing façade declares a file scope
+#   latent     — every citing façade is prose the agent must choose to read
+#   uncited    — no façade page names the doc at all
+# Tree-only, with no history in it, so the scoreboard stays a pure function of
+# the checkout.
+TRIGGER_MECHANICAL="mechanical"
+TRIGGER_LATENT="latent"
+TRIGGER_UNCITED="uncited"
+
+ledger_doc_trigger() {
+  local doc="$1" stem script cited=1
+  while IFS= read -r stem; do
+    [ -n "$stem" ] || continue
+    cited=0
+    script="$LEDGER_ROOT/dispatch/$stem.sh"
+    [ -f "$script" ] || continue
+    [ -n "$(ledger_facade_globs "$script")" ] || continue
+    printf '%s' "$TRIGGER_MECHANICAL"
+    return
+  done < <(ledger_facades_citing "$doc")
+  [ "$cited" -eq 0 ] && { printf '%s' "$TRIGGER_LATENT"; return; }
+  printf '%s' "$TRIGGER_UNCITED"
+}
+
+# The citing façade stems as one comma-joined field, or an em dash when none.
+ledger_doc_facade_list() {
+  local doc="$1" stem stems=""
+  while IFS= read -r stem; do
+    [ -n "$stem" ] || continue
+    stems="${stems:+$stems,}$stem"
+  done < <(ledger_facades_citing "$doc")
+  printf '%s' "${stems:-—}"
+}

package/audits/rule-ledger.sh

@@ -0,0 +1,225 @@
+#!/usr/bin/env bash
+# rule-ledger.sh — what each rule document actually enforces.
+#
+#   audits/rule-ledger.sh --census        one row per registered rule doc
+#
+# Reports the enforcement shape of the docs/ rule tier: how many normative
+# clauses a document carries, and how many of those are machine-checked
+# (DETERMINISTIC), agent-judged (JUDGMENT), acknowledged prose (UNENFORCED), or
+# untriaged (untagged). Counts INFORM and never fail the build. The only census
+# failure is STRUCTURAL: a rule doc cited by a dispatch façade that appears in
+# neither the registry nor the exclusion list, or a registered path missing from
+# disk — both mean the ledger is lying about coverage.
+#
+# The census answers the other half too: a rule that reads perfectly still
+# governs nothing if its façade declares no scope, because nothing it says can
+# ever reach a diff. That is structural, and answerable from the tree.
+#
+# Exit: 0 clean · 1 structural violation · 2 usage error. Writes nothing.
+set -uo pipefail
+
+# `sort` orders by locale, and this script's output is byte-compared by
+# `make audit`. Without a pinned collation the scoreboard is a function of the
+# tree AND the contributor's LC_ALL: `LC_ALL=C` sorts `A-Z B-X a_y`, en_US.UTF-8
+# sorts `a_y A-Z B-X`. Invisible while every document carries one code, and a
+# guaranteed spurious red the moment one carries two.
+export LC_ALL=C
+
+# A hook exports GIT_DIR/GIT_INDEX_FILE at the repository it fired in; any git
+# a child runs would silently retarget there. The library resolves LEDGER_ROOT
+# with git, so the scope dies here, before it is sourced.
+unset GIT_DIR GIT_INDEX_FILE GIT_WORK_TREE GIT_COMMON_DIR GIT_PREFIX \
+      GIT_OBJECT_DIRECTORY GIT_ALTERNATE_OBJECT_DIRECTORIES
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=audits/rule-ledger-lib.sh
+source "$HERE/rule-ledger-lib.sh"
+
+MODE_CENSUS="census"
+MODE_WRITE="write"
+MODE_CHECK="check"
+SCOREBOARD_PATH="docs/RULE_ENFORCEMENT.md"
+SCOREBOARD_FIX_COMMAND="bash audits/rule-ledger.sh --write $SCOREBOARD_PATH"
+USAGE="usage: $0 --census | --write <file> | --check"
+
+MODE=""
+WRITE_TARGET=""
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --census) MODE="$MODE_CENSUS" ;;
+    --check) MODE="$MODE_CHECK" ;;
+    --write)
+      shift
+      WRITE_TARGET="${1:-}"
+      [ -n "$WRITE_TARGET" ] || { printf '%s\n--write takes a target file\n' "$USAGE" >&2; exit 2; }
+      MODE="$MODE_WRITE"
+      ;;
+    -h|--help) printf '%s\n' "$USAGE"; exit 0 ;;
+    *) printf 'unknown arg: %s\n%s\n' "$1" "$USAGE" >&2; exit 2 ;;
+  esac
+  shift
+done
+[ -n "$MODE" ] || { printf '%s\n' "$USAGE" >&2; exit 2; }
+
+if [[ -t 1 ]]; then G=$'\033[32m'; R=$'\033[31m'; BO=$'\033[1m'; X=$'\033[0m'
+else G=''; R=''; BO=''; X=''; fi
+RC=0
+fail() { printf '  %s🔴 %s%s\n' "$R" "$1" "$X" >&2; RC=1; }
+okln() { printf '  %s🟢%s %s\n' "$G" "$X" "$1"; }
+
+# One machine-parseable row per registered document. Field order is stable and
+# every value is a bare integer, so a caller greps `untagged=0` rather than
+# parsing a table.
+census_row() {
+  local doc="$1"
+  local counts clauses det judgment unenforced untagged
+  if ! counts="$(ledger_doc_counts "$LEDGER_ROOT/$doc")"; then
+    fail "doc=$doc MISSING from disk — registered in rule-ledger-lib.sh REGISTERED_DOCS"
+    return
+  fi
+  read -r clauses det judgment unenforced untagged <<< "$counts"
+  printf '  doc=%-44s clauses=%-4s det=%-4s judgment=%-4s unenforced=%-4s untagged=%s\n' \
+    "$doc" "$clauses" "$det" "$judgment" "$unenforced" "$untagged"
+}
+
+# A façade that tells the agent to read a rule doc the ledger does not know
+# about means the scoreboard under-reports the corpus. Either register it or
+# declare it a non-rule document — silence is the one outcome not allowed.
+check_registry_parity() {
+  local doc
+  while IFS= read -r doc; do
+    [ -n "$doc" ] || continue
+    ledger_in_list "$doc" "${REGISTERED_DOCS[@]}" && continue
+    ledger_in_list "$doc" "${EXCLUDED_DOCS[@]}" && continue
+    ledger_has_prefix "$doc" && continue
+    fail "doc=$doc cited by a dispatch façade but in neither REGISTERED_DOCS nor EXCLUDED_DOCS (audits/rule-ledger-lib.sh)"
+  done < <(ledger_cited_docs)
+}
+
+# A façade executable that declares no `dispatch_init` scope carries rules no
+# diff can ever reach. It is the one trigger question worth failing on, and it
+# is answerable from the tree — unlike "has this fired lately", which depends on
+# what happened to get committed recently and gates nothing.
+check_facade_scopes() {
+  local script stem
+  while IFS= read -r script; do
+    [ -n "$script" ] || continue
+    [ -n "$(ledger_facade_globs "$script")" ] && continue
+    stem="$(basename "$script" .sh)"
+    fail "facade=$stem declares no dispatch_init scope — dispatch/$stem.sh (nothing it carries can ever fire)"
+  done < <(ledger_facade_scripts)
+}
+
+run_census() {
+  printf '%sRULE ENFORCEMENT LEDGER — census%s\n' "$BO" "$X"
+  for entry in "${REGISTERED_DOCS[@]}"; do census_row "$entry"; done
+  printf '\n%sstructural checks%s\n' "$BO" "$X"
+  check_registry_parity
+  check_facade_scopes
+  [ "$RC" -eq 0 ] && okln "every cited rule doc is registered; every façade declares a scope"
+  return 0
+}
+
+scoreboard_legend() {
+  cat <<'LEGEND'
+## How to read this
+
+- **enforced by** — the rules in this document a script decides, and the script
+  that decides each. This is the column worth acting on: it is the difference
+  between a rule that holds and a rule that is merely written down. A code
+  reading `no helper row` is a `[DETERMINISTIC → …]` tag with nothing behind it.
+- **judged / acknowledged** — clauses an agent must weigh (`[JUDGMENT → CODE]`)
+  and clauses nobody checks on purpose (`[UNENFORCED → reason]`, the reason
+  stated where a reader meets it).
+- **classified** — how much of the document has been triaged at all. The
+  denominator counts lines carrying a normative keyword outside headings and
+  tables — a keyword heuristic, not a parse. It informs; it never gates.
+- **trigger** — `mechanical` when a citing façade declares a file scope,
+  `latent` when every citing façade is prose the agent must choose to read,
+  `uncited` when no façade names the document at all.
+
+A tag alone on its line covers every clause under it until the next heading; a
+tag at the end of a sentence covers that sentence. Same grammar the
+`dispatch/*.md` façades use, read by the same code.
+
+Everything here is a function of the tree alone — no timestamps, no commit
+hashes, no history — so the file reproduces from a checkout and any diff means
+the corpus moved.
+LEGEND
+}
+
+# The scoreboard body: what each document actually enforces, then how much of it
+# has been triaged. Deterministic by construction — registry order in, content
+# out — so `--check` can regenerate and byte-compare.
+render_scoreboard() {
+  local doc counts clauses det judgment unenforced untagged code codes
+  local sum_clauses=0 sum_classified=0
+  printf '# Rule enforcement ledger\n\n'
+  printf 'Generated by `audits/rule-ledger.sh`. Never hand-edit: `make audit`\n'
+  printf 'regenerates this file and fails on any difference. To update it, run\n'
+  printf '`%s`.\n\n' "$SCOREBOARD_FIX_COMMAND"
+  printf '| Rule document | enforced by | judged | acknowledged | classified | trigger |\n'
+  printf '|---|---|--:|--:|--:|---|\n'
+  for doc in "${REGISTERED_DOCS[@]}"; do
+    counts="$(ledger_doc_counts "$LEDGER_ROOT/$doc")" || return 1
+    read -r clauses det judgment unenforced untagged <<< "$counts"
+    codes=""
+    while IFS= read -r code; do
+      [ -n "$code" ] || continue
+      codes="${codes:+$codes<br>}\`$code\` → \`$(ledger_code_script "$code")\`"
+    done < <(ledger_doc_codes "$LEDGER_ROOT/$doc")
+    printf '| `%s` | %s | %s | %s | %s/%s | %s |\n' \
+      "$doc" "${codes:-—}" "$judgment" "$unenforced" \
+      "$(( clauses - untagged ))" "$clauses" "$(ledger_doc_trigger "$doc")"
+    sum_clauses=$(( sum_clauses + clauses ))
+    sum_classified=$(( sum_classified + clauses - untagged ))
+  done
+  printf '| **corpus** | | | | **%s/%s** | |\n\n' "$sum_classified" "$sum_clauses"
+  scoreboard_legend
+}
+
+run_write() {
+  local target="$1" rendered
+  case "$target" in /*) ;; *) target="$LEDGER_ROOT/$target" ;; esac
+  rendered="$(mktemp)"
+  trap 'rm -f "$rendered"' EXIT
+  if render_scoreboard > "$rendered"; then
+    cat "$rendered" > "$target"
+    printf 'wrote %s\n' "$target"
+  else
+    fail "render aborted — a registered doc is missing from disk; run --census for the name"
+  fi
+  rm -f "$rendered"
+  trap - EXIT
+  return 0
+}
+
+# Currency, not content: the committed file must equal what this tree renders.
+# A stale scoreboard is a red because a wrong number read as fact is worse than
+# no number at all.
+run_check() {
+  local target="$LEDGER_ROOT/$SCOREBOARD_PATH" rendered
+  rendered="$(mktemp)"
+  trap 'rm -f "$rendered"' EXIT
+  printf '%sRULE ENFORCEMENT LEDGER — scoreboard currency%s\n' "$BO" "$X"
+  if ! render_scoreboard > "$rendered"; then
+    fail "a registered doc is missing from disk — run --census for the name"
+  elif [ ! -f "$target" ]; then
+    fail "$SCOREBOARD_PATH does not exist — regenerate: $SCOREBOARD_FIX_COMMAND"
+  elif ! cmp -s "$rendered" "$target"; then
+    fail "$SCOREBOARD_PATH is stale — regenerate: $SCOREBOARD_FIX_COMMAND"
+  else
+    okln "$SCOREBOARD_PATH matches the tree"
+  fi
+  rm -f "$rendered"
+  trap - EXIT
+  return 0
+}
+
+case "$MODE" in
+  "$MODE_CENSUS") run_census ;;
+  "$MODE_WRITE") run_write "$WRITE_TARGET" ;;
+  "$MODE_CHECK") run_check ;;
+esac
+
+exit "$RC"

package/audits/rule-paths.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# rule-paths.sh — residence checks: rule citations resolve inside the repository
+# that installed them.
+#
+# The incident this encodes (M143): an agent in an agentsfleet worktree
+# resolved "reads docs/REST_API_DESIGN_GUIDELINES.md" against its own
+# repository, found nothing — under the old thin-distribution model, consumer
+# repos carried no rule copies at all — and designed an HTTP surface from
+# memory instead of the guide.
+#
+# M03_001 closed that gap by materialising rule docs into every consuming
+# repository (`orly init`/`orly update`, keyed by the profile's selected
+# packs). A citation now resolving to a real local file IS the fix, so the
+# invariant inverts: the ~/Projects/dotfiles/ anchor becomes wrong wherever
+# it appears in a surface a materialised repository also carries — it names a
+# path that will not exist on any machine but this one.
+#
+#   residence    — dotfiles-resident rule docs are cited relative to the
+#                  installing repository, never through the
+#                  ~/Projects/dotfiles/ anchor, in every surface `orly init`
+#                  materialises. AGENTS.md (byte-capped) carries the new
+#                  resolution doctrine, zero CWD-relative hrefs, and no
+#                  residence-contradicting rows. Files that never leave this
+#                  checkout (RULE_PATH_ENGINE_ONLY — governance-editing
+#                  façades genuinely about the engine's own source) are
+#                  exempt; their absolute citations are correct.
+#   (Reachability was the other half of this file: a settings allow-rule
+#   granting Read(~/Projects/dotfiles/**) so an agent could read rule docs out
+#   of a dotfiles checkout. M03_001 inverted the model — rules resolve inside
+#   the repository that installed them — and the engine now lives in its own
+#   repository, where there is no dotfiles anchor to reach and no personal
+#   settings file to assert against. It went with the split.)
+#
+# Sourced by audits/agents-md.sh (labels: "rule-path residence",
+# Classifier: DOTFILES_RESIDENT in audits/data.sh.
+#
+#   check_rule_residence <ROOT>     # echoes FAIL lines, returns 0/1
+
+# Non-dispatch surfaces read from consumer-repo CWDs; dispatch/*.md is globbed.
+RULE_PATH_SURFACES=(
+  "docs/TEMPLATE.md"
+  "docs/EXECUTE_DOC_READS.md"
+  "docs/greptile-learnings/RULES.md"
+)
+
+# Governance-editing façades describe how to edit THIS engine's own source
+# (core/**, packs/**, schemas/**, src/**, the registry, the rendered AGENTS.md) — a workflow that only ever
+# runs inside this checkout. Their absolute citations are correct, not a
+# residual of the old model; a materialised copy would never satisfy them
+# because there is nothing to materialise (a consumer never receives
+# core/, registry.json, or this checkout's own dispatch/edit_rules.md).
+RULE_PATH_ENGINE_ONLY=(
+  "dispatch/edit_rules.md"
+)
+
+check_rule_residence() {
+  local root="$1" rc=0
+  local agents="$root/AGENTS.md"   # separate line: $root must be set before it expands here
+
+  # (a) resolution doctrine present in the rendered rules.
+  grep -qF 'Rule paths resolve relative to this repository' "$agents" \
+    || { echo "FAIL: resolution doctrine missing from AGENTS.md"; rc=1; }
+
+  # (b) zero CWD-relative markdown hrefs — AGENTS.md is served as
+  # ~/.claude/CLAUDE.md, so ](./…) and ](../…) resolve against garbage.
+  if grep -qE '\]\((\./|\.\./)' "$agents"; then
+    echo "FAIL: AGENTS.md carries $(grep -cE '\]\((\./|\.\./)' "$agents") CWD-relative markdown href(s)"
+    rc=1
+  fi
+
+  # Resident docs/… names derived from DOTFILES_RESIDENT (single classifier).
+  local d names=()
+  for d in "${DOTFILES_RESIDENT[@]}"; do
+    [[ "$d" == docs/* ]] && names+=("${d#docs/}")
+  done
+
+  # (c) no AGENTS.md line may pair a resident doc with "(product repo)" — the
+  # misread that sent the M143 agent to the wrong repository. Still a real
+  # mistake under the new model: a doc this array names IS materialised here.
+  local alt
+  alt=$(IFS='|'; printf '%s' "${names[*]%.md}")
+  if grep -E "docs/(${alt})\.md" "$agents" | grep -qF '(product repo)'; then
+    echo "FAIL: AGENTS.md line pairs a dotfiles-resident doc with '(product repo)'"
+    rc=1
+  fi
+
+  # (d) surfaces materialised by orly init must cite resident docs relative to
+  # the installing repository — never through the ~/Projects/dotfiles/ anchor,
+  # which names a path absent on every machine but this one. Engine-only
+  # façades (RULE_PATH_ENGINE_ONLY) are exempt: their absolute citations are
+  # correct because nothing is ever materialised to satisfy them.
+  local f rel is_exempt e hits
+  for f in "$agents" "$root"/dispatch/*.md "${RULE_PATH_SURFACES[@]/#/${root}/}"; do
+    [[ -f "$f" ]] || continue
+    rel="${f#"$root"/}"
+    is_exempt=0
+    for e in "${RULE_PATH_ENGINE_ONLY[@]}"; do [[ "$e" == "$rel" ]] && is_exempt=1; done
+    [[ "$is_exempt" -eq 1 ]] && continue
+    hits=$(LC_ALL=C grep -noE '~/Projects/dotfiles/(docs|dispatch|audits)/[A-Za-z0-9_./-]+\.(md|sh)' "$f" | head -5)
+    if [[ -n "$hits" ]]; then
+      echo "FAIL: anchored citation in $rel (should resolve relative to the installing repository):"
+      printf '  %s\n' "$hits"
+      rc=1
+    fi
+  done
+
+  return $rc
+}