From be8a0665231dd9436b53b956f2910d619b0a3ff2 Mon Sep 17 00:00:00 2001
From: Bren Pike <brenpike@gmail.com>
Date: Fri, 25 Sep 2026 15:24:59 -0600
Subject: [PATCH 01/10] fix(policy): add shared checked-discovery helper and
 ADR-0031

---
 docs/adr/0031-checked-discovery-policy.md |  41 ++++++
 tools/policy_check.sh                     | 166 ++++++++++++++++++++++
 2 files changed, 207 insertions(+)
 create mode 100644 docs/adr/0031-checked-discovery-policy.md

diff --git a/docs/adr/0031-checked-discovery-policy.md b/docs/adr/0031-checked-discovery-policy.md
new file mode 100644
index 00000000..0f09dba3
--- /dev/null
+++ b/docs/adr/0031-checked-discovery-policy.md
@@ -0,0 +1,41 @@
+# One discovery policy for policy_check.sh: follow symlinks, fail closed on what can't be followed
+
+**Status:** accepted — 2026-09-25
+
+## Context
+
+`tools/policy_check.sh` finds its input files with plain `find` at roughly thirty call sites. POSIX `find` defaults to `-P`, so it never descends into a symlinked directory. Most of these sites also filter with `-type f`, which drops a name-matching symlink before any read or status check ever sees it. A few sites additionally discard `find`'s exit status with `2>/dev/null` or by piping into another command. The net effect: a check's input set can be narrowed silently, ahead of the layer that is supposed to fail closed, and the check still reports green on input it never saw.
+
+CHECK 15 hit exactly this shape first. Its fix (tracked in the repo's recent history, not named here as a live source of current behavior — see `tools/policy_check.sh` and `tests/policy/README.md` for the maintained description) moved CHECK 15's discovery to name-only matching (dropping `-type f`) behind a checked, status-bearing discovery helper, so every name-matching path reaches CHECK 15's read gate. It recorded the missing `-L` — symlinked directories still going undescended — as a residual, because fixing CHECK 15 alone would leave it disagreeing with every other discovery site in the same script, and adding `-L` changes `find`'s error behavior (dangling links, symlink loops) script-wide.
+
+Issue brenpike/hivemind#377 generalized that residual: the input-narrowing pattern is present at roughly thirty sites, not one, and needs a single script-wide decision rather than a per-site patch.
+
+## Decision
+
+`tools/policy_check.sh` adopts one discovery policy for the whole script: **follow symlinks**. Every discovery site uses `find -L` (or the equivalent checked-discovery helper) instead of default `-P`. Anything a followed traversal cannot resolve — a dangling symlink, a symlink loop — surfaces as a finding. It is never a silent skip and never a suppressed `find` exit status.
+
+The policy is implemented once, as a shared checked-discovery helper generalized from CHECK 15's sentinel-status helper, and every discovery call site is routed through it rather than reimplementing `find` invocations locally. The helper is status-bearing: callers can distinguish "found N paths" from "discovery itself failed," and a status-bearing gate classifies each discovered path (files, directories, or raw/unfiltered) so call sites keep the granularity they had before, without reintroducing a second traversal mechanism to get it.
+
+This is a single discovery engine for the script. No check gets a second, separate way to walk the filesystem.
+
+The policy is witnessed by a committed `DISCOVERY` canary: a committed symlinked-directory fixture (proving a symlinked directory is now descended and its contents reach the read gate) and a committed dangling-symlink fixture (proving an unresolvable target surfaces as a finding rather than vanishing), plus a `-P` negative control (proving the canary fixtures would NOT be caught under the old default, so the canary is actually exercising the new policy and not passing by accident).
+
+## Alternatives rejected
+
+| Option | Rejected because |
+|---|---|
+| Ban symlinks under scanned roots (reject any symlink found, follow none) | Reverses CHECK 15's already-shipped read-through behavior for name-matching symlinks, and forces allowlist entries for the repo's own existing test fixtures that happen to be symlinks. Trades a real gap for a maintenance tax on legitimate fixtures. |
+| Hybrid: read file symlinks, reject directory symlinks | Needs a second, separate symlink sweep to distinguish the two cases ahead of the main discovery pass — i.e., two traversal mechanisms doing overlapping work, which is the coupling this decision is trying to avoid. |
+| Follow symlinks everywhere, fail closed on the unresolvable (chosen) | — |
+
+## Consequences
+
+- Every `tools/policy_check.sh` discovery site sees the same input set a symlink-following traversal would produce; a symlinked directory or a name-matching symlink can no longer make a check report green on input it never read.
+- A dangling symlink or symlink loop under a scanned root is now a loud finding rather than an invisible one.
+- **Residual: symlink loops are not witnessed by a committed fixture.** A committed loop under `tests/` would make any `-L` scan over that tree error, which is disruptive to every other test that walks the same directory. The canary instead witnesses status propagation through the nonexistent-root probe (a root that cannot be discovered at all), which exercises the same fail-closed status path without requiring a permanently-broken fixture on disk.
+- **Residual: a symlinked directory pointing back inside the scanned root** materializes the same underlying file under two path spellings (the real path and the path through the symlink). An allowlist entry keyed to one spelling does not cover the other. This is not addressed by this decision and is left for a future policy fixture if it becomes a real allowlisting problem.
+- **On `core.symlinks=false` checkouts**, the committed symlink fixtures (both the directory fixture and the dangling-link fixture) check out as plain text files containing their target path string, not as symlinks. The canary fails loudly on such a checkout — by design, not as a silent skip — because CI runs on `ubuntu-latest`, where `core.symlinks` is true, and a contributor on a non-symlink-capable checkout needs to know their local run cannot validate this policy rather than have it quietly pass.
+- **Sibling scripts are not migrated by this decision.** `tools/validate.sh`, `tools/validate_workflows.sh`, `tools/validate_reports.sh`, and the `tools/test_*.sh` leak probes have the same discovery shape and are tracked separately in brenpike/hivemind#381.
+- **Symlinks as shipped content inside `plugin/` are a separate question from discovery.** Whether `tools/policy_check.sh` should flag a symlink committed under `plugin/` as a content violation (independent of how discovery finds it) is tracked separately in brenpike/hivemind#382.
+
+References: `tools/policy_check.sh`, `tests/policy/README.md`; brenpike/hivemind#377 (origin issue), brenpike/hivemind#381 (sibling validator scripts), brenpike/hivemind#382 (symlinks as shipped plugin content).
diff --git a/tools/policy_check.sh b/tools/policy_check.sh
index b1975494..6a746075 100644
--- a/tools/policy_check.sh
+++ b/tools/policy_check.sh
@@ -279,6 +279,172 @@ file_candidates() {
     printf '%s' "$out"
 }
 
+# ── Checked discovery ───────────────────────────────────────────────────────
+# The single file-discovery engine for this script. Contract:
+#
+#   Policy: every discovery find runs with DISCOVERY_FIND_BASE (-L), so
+#   symlinks are FOLLOWED script-wide -- a symlinked file or directory is
+#   scanned as its target. Failures are loud, never silently skipped:
+#     - a symlink loop makes find print an error and exit non-zero (it keeps
+#       traversing), so discover_paths returns that status and the caller
+#       reports it through flag_discovery_failure;
+#     - a dangling symlink is printed by find -L with exit 0, so it is the
+#       `files` gate of discovery_gate_status that rejects it (missing), and
+#       the caller reports it through flag_discovery_gate.
+#   Precondition: every ROOT must exist. This is the CALLER's job; there is
+#   no swallow mode and find's stderr is never suppressed, so a missing root
+#   fails discovery with find's non-zero status and must be reported.
+#   Findings: both reporting wrappers emit through add_finding, so --strict
+#   and the allowlist apply. They do NOT set any per-check found/pass flag;
+#   the caller owns that.
+#   Residuals: symlink-loop reporting is not witnessed by a committed fixture;
+#   a symlinked directory that points back inside a scanned root materialises
+#   the same file under two paths (it is scanned twice, never skipped).
+
+DISCOVERY_FIND_BASE=(-L)
+DISCOVERY_FIND_STATUS_TAG='__DISCOVERY_FIND_STATUS='
+DISCOVERY_RC_TRUNCATED=20
+DISCOVERY_RC_USAGE=21
+DISCOVERY_GATE_RC_MISSING=22
+DISCOVERY_GATE_RC_NOT_REGULAR=23
+DISCOVERY_GATE_RC_UNREADABLE=24
+DISCOVERY_GATE_RC_NOT_DIR=25
+DISCOVERY_GATE_RC_UNKNOWN_GATE=26
+
+# discover_paths DEST_ARRAY ROOT... -- FIND_ARGS...
+# Materialises the paths
+#   find "${DISCOVERY_FIND_BASE[@]}" ROOT... FIND_ARGS... -print0
+# emits into the caller-named array DEST_ARRAY (replacing its contents), and
+# returns find's exit status, DISCOVERY_RC_TRUNCATED when the stream does not
+# end in exactly one status record, or DISCOVERY_RC_USAGE (with a stderr
+# message) when no ROOT or no `--` separator is given. Paths found before a
+# failure are still materialised so they are scanned; the non-zero status is
+# what keeps the caller from reading the list as clean.
+#
+# DEST_ARRAY is bound by nameref, so nested discovery (a discovery inside
+# another discovery's loop) must use distinct destination names; it must also
+# not be one of this function's own `discovery_*` locals.
+#
+# INVARIANT: a failing producer inside `< <(...)` is invisible to the reading
+# loop (see the materialisation invariant above), so the producer appends its
+# own status as a trailing NUL-delimited sentinel record. The
+# `|| discovery_find_status=$?` is load-bearing: errexit is inherited by the
+# process substitution, so a bare `find ...; printf ... "$?"` dies before the
+# sentinel is written whenever find fails.
+#
+# INVARIANT: every emitted path begins with one of the ROOTs, so a path record
+# can only collide with DISCOVERY_FIND_STATUS_TAG if a ROOT itself begins with
+# it; callers pass absolute roots.
+discover_paths() {
+    local -n discovery_dest_ref="$1"
+    shift
+    local -a discovery_roots=()
+    local discovery_saw_separator=false
+    while [[ $# -gt 0 ]]; do
+        if [[ "$1" == '--' ]]; then
+            discovery_saw_separator=true
+            shift
+            break
+        fi
+        discovery_roots+=("$1")
+        shift
+    done
+    if [[ "$discovery_saw_separator" != true || "${#discovery_roots[@]}" -eq 0 ]]; then
+        echo "discover_paths: usage: discover_paths DEST_ARRAY ROOT... -- FIND_ARGS..." >&2
+        return "$DISCOVERY_RC_USAGE"
+    fi
+    local discovery_record discovery_status_record=''
+    local discovery_sentinel_total=0 discovery_last_was_sentinel=false
+    discovery_dest_ref=()
+    while IFS= read -r -d '' discovery_record; do
+        if [[ "$discovery_record" == "$DISCOVERY_FIND_STATUS_TAG"* ]]; then
+            discovery_sentinel_total=$((discovery_sentinel_total + 1))
+            discovery_status_record="$discovery_record"
+            discovery_last_was_sentinel=true
+        else
+            discovery_dest_ref+=("$discovery_record")
+            discovery_last_was_sentinel=false
+        fi
+    done < <(discovery_find_status=0; find "${DISCOVERY_FIND_BASE[@]}" "${discovery_roots[@]}" "$@" -print0 || discovery_find_status=$?; printf '%s%d\0' "$DISCOVERY_FIND_STATUS_TAG" "$discovery_find_status")
+    if [[ "$discovery_sentinel_total" -ne 1 || "$discovery_last_was_sentinel" != true ]]; then
+        return "$DISCOVERY_RC_TRUNCATED"
+    fi
+    return "${discovery_status_record#"$DISCOVERY_FIND_STATUS_TAG"}"
+}
+
+# discovery_gate_status PATH GATE
+# Status-bearing classifier for one discovered PATH (symlinks resolved, per
+# the -L policy). GATE is one of:
+#   files -- 0 only for a readable regular file; otherwise
+#            DISCOVERY_GATE_RC_MISSING (missing or dangling symlink),
+#            DISCOVERY_GATE_RC_NOT_REGULAR, or DISCOVERY_GATE_RC_UNREADABLE;
+#   dirs  -- 0 for a directory (a symlinked directory passes); otherwise
+#            DISCOVERY_GATE_RC_MISSING or DISCOVERY_GATE_RC_NOT_DIR;
+#   raw   -- always 0; the caller does its own read gating.
+# An unknown GATE returns DISCOVERY_GATE_RC_UNKNOWN_GATE with a stderr message.
+discovery_gate_status() {
+    local candidate_path="$1" gate_name="$2"
+    case "$gate_name" in
+        files)
+            if [[ ! -e "$candidate_path" ]]; then
+                return "$DISCOVERY_GATE_RC_MISSING"
+            fi
+            if [[ ! -f "$candidate_path" ]]; then
+                return "$DISCOVERY_GATE_RC_NOT_REGULAR"
+            fi
+            if [[ ! -r "$candidate_path" ]]; then
+                return "$DISCOVERY_GATE_RC_UNREADABLE"
+            fi
+            ;;
+        dirs)
+            if [[ ! -e "$candidate_path" ]]; then
+                return "$DISCOVERY_GATE_RC_MISSING"
+            fi
+            if [[ ! -d "$candidate_path" ]]; then
+                return "$DISCOVERY_GATE_RC_NOT_DIR"
+            fi
+            ;;
+        raw)
+            ;;
+        *)
+            echo "discovery_gate_status: unknown gate '${gate_name}' (expected files, dirs, or raw)" >&2
+            return "$DISCOVERY_GATE_RC_UNKNOWN_GATE"
+            ;;
+    esac
+    return 0
+}
+
+# flag_discovery_failure RULE ROOT LABEL STATUS
+# Thin reporting wrapper: records the RULE finding for a discover_paths call
+# (described by LABEL, anchored at ROOT) that returned non-zero STATUS. A
+# partial path list is never a clean one.
+flag_discovery_failure() {
+    local rule_name="$1" discovery_root="$2" discovery_label="$3" discovery_rc="$4" failure_reason
+    case "$discovery_rc" in
+        "$DISCOVERY_RC_TRUNCATED") failure_reason='its path stream ended without exactly one trailing find-status record (truncated)' ;;
+        "$DISCOVERY_RC_USAGE") failure_reason='discover_paths was called without a ROOT or without the -- separator' ;;
+        *) failure_reason="find exited ${discovery_rc} (a missing root, an unreadable directory, or a symlink loop)" ;;
+    esac
+    add_finding "$rule_name" "$discovery_root" 0 \
+        "Discovery of ${discovery_label} failed: ${failure_reason}, so paths in it may never have been checked -- fix the tree; a failed discovery is NOT clean"
+}
+
+# flag_discovery_gate RULE PATH RC
+# Thin reporting wrapper: records the RULE finding for a discovered PATH that
+# discovery_gate_status rejected with non-zero RC.
+flag_discovery_gate() {
+    local rule_name="$1" candidate_path="$2" gate_rc="$3" rejection_reason
+    case "$gate_rc" in
+        "$DISCOVERY_GATE_RC_MISSING") rejection_reason='is missing or is a dangling symlink' ;;
+        "$DISCOVERY_GATE_RC_NOT_REGULAR") rejection_reason='is not a regular file' ;;
+        "$DISCOVERY_GATE_RC_UNREADABLE") rejection_reason='is not readable' ;;
+        "$DISCOVERY_GATE_RC_NOT_DIR") rejection_reason='is not a directory' ;;
+        *) rejection_reason="was rejected by the discovery gate with status ${gate_rc}" ;;
+    esac
+    add_finding "$rule_name" "$candidate_path" 0 \
+        "this discovered path ${rejection_reason}, so it was never checked -- fix or remove it; an unchecked path is NOT clean"
+}
+
 # ── Timing instrumentation ──────────────────────────────────────────────────
 # Permanent per-check profiling (#305, precedent #304). Emits one
 # "[TIME] <label> <elapsed>s" line after each check block and a per-check

From 45f3b1d68b8eb382a22bcee3a6aa2da93fae3235 Mon Sep 17 00:00:00 2001
From: Bren Pike <brenpike@gmail.com>
Date: Fri, 25 Sep 2026 15:33:45 -0600
Subject: [PATCH 02/10] test(policy): add DISCOVERY canary with symlink
 fixtures

---
 .../discovery-canary/broken/dangling.md       |   1 +
 .../fixtures/discovery-canary/tree/link-dir   |   1 +
 .../discovery-canary/tree/real/inner.md       |   1 +
 tools/policy_check.sh                         | 127 ++++++++++++++++++
 4 files changed, 130 insertions(+)
 create mode 120000 tests/policy/fixtures/discovery-canary/broken/dangling.md
 create mode 120000 tests/policy/fixtures/discovery-canary/tree/link-dir
 create mode 100644 tests/policy/fixtures/discovery-canary/tree/real/inner.md

diff --git a/tests/policy/fixtures/discovery-canary/broken/dangling.md b/tests/policy/fixtures/discovery-canary/broken/dangling.md
new file mode 120000
index 00000000..d540f0fb
--- /dev/null
+++ b/tests/policy/fixtures/discovery-canary/broken/dangling.md
@@ -0,0 +1 @@
+does-not-exist.md
\ No newline at end of file
diff --git a/tests/policy/fixtures/discovery-canary/tree/link-dir b/tests/policy/fixtures/discovery-canary/tree/link-dir
new file mode 120000
index 00000000..ac558a3e
--- /dev/null
+++ b/tests/policy/fixtures/discovery-canary/tree/link-dir
@@ -0,0 +1 @@
+real
\ No newline at end of file
diff --git a/tests/policy/fixtures/discovery-canary/tree/real/inner.md b/tests/policy/fixtures/discovery-canary/tree/real/inner.md
new file mode 100644
index 00000000..aebef4a6
--- /dev/null
+++ b/tests/policy/fixtures/discovery-canary/tree/real/inner.md
@@ -0,0 +1 @@
+discovery-canary: plain regular file reached through both tree/real and the tree/link-dir symlink.
diff --git a/tools/policy_check.sh b/tools/policy_check.sh
index 6a746075..fd2cefba 100644
--- a/tools/policy_check.sh
+++ b/tools/policy_check.sh
@@ -499,6 +499,133 @@ print_timing_table() {
 CHECKS_PASSED=0
 CHECKS_FAILED=0
 
+# ── DISCOVERY CANARY ────────────────────────────────────────────────────────
+# Witnesses the checked-discovery helpers (see the Checked discovery section).
+# It sits directly after State, the first point where its CHECKS_PASSED /
+# CHECKS_FAILED accounting survives the counter initialisation. Assertions:
+#   * precondition: the committed fixture symlinks ARE symlinks in this checkout
+#     (a core.symlinks=false checkout turns them into plain files) -- a loud
+#     finding, never a self-skip;
+#   * args pin: DISCOVERY_FIND_BASE is exactly the single element `-L`;
+#   * positive: discover_paths over the canary tree materialises exactly
+#     real/inner.md and link-dir/inner.md, both accepted by the `files` gate --
+#     proving -L descends a symlinked directory;
+#   * negative control: one raw `find -P` over the same tree materialises only
+#     real/inner.md, so the positive probe discriminates -L from -P;
+#   * gates in both directions, against the status-bearing classifier
+#     discovery_gate_status (never the reporting wrappers, so no probe emits a
+#     real finding), each probe path chosen so no earlier gate arm shadows the
+#     arm under test; a regular fixture accepted by `files` is the positive
+#     control, so the failure arms cannot all pass by the gate failing
+#     unconditionally;
+#   * status propagation: discover_paths over a nonexistent root returns
+#     find's own non-zero status (not TRUNCATED or USAGE).
+# The fixtures are committed, so no probe creates a filesystem object at run
+# time. stderr is discarded only for the nonexistent-root probe, whose find
+# error is the expected outcome.
+# Residuals: the symlink-loop case is not witnessed by a committed fixture --
+# find reports a loop through the same non-zero exit status the
+# nonexistent-root probe witnesses; a symlinked directory that points back
+# inside a scanned root materialises the same file under two paths (scanned
+# twice, never skipped), which this canary does not assert.
+
+echo ''
+echo '=== DISCOVERY: Checked-discovery canary ==='
+
+DISCOVERY_CANARY_REL='tests/policy/fixtures/discovery-canary'
+dcanary_root="$REPO_ROOT/$DISCOVERY_CANARY_REL"
+dcanary_tree="$dcanary_root/tree"
+dcanary_real_dir="$dcanary_tree/real"
+dcanary_link_dir="$dcanary_tree/link-dir"
+dcanary_real_file="$dcanary_real_dir/inner.md"
+dcanary_linked_file="$dcanary_link_dir/inner.md"
+dcanary_dangling_file="$dcanary_root/broken/dangling.md"
+dcanary_missing_root="$dcanary_root/__discovery_nonexistent__"
+dcanary_found=false
+
+# flag_discovery_canary DESCRIPTION
+# Records a DISCOVERY finding for a canary assertion that came back wrong.
+flag_discovery_canary() {
+    dcanary_found=true
+    add_finding 'DISCOVERY' 'tools/policy_check.sh' 0 \
+        "discovery canary: $1 -- the checked-discovery engine no longer holds its follow-symlinks, fail-loud contract, so a symlinked, dangling, or undiscoverable path could be read as clean"
+}
+
+# expect_discovery_gate PATH_LABEL PATH GATE EXPECTED_RC
+# Asserts discovery_gate_status PATH GATE returns exactly EXPECTED_RC.
+expect_discovery_gate() {
+    local path_label="$1" candidate_path="$2" gate_name="$3" expected_rc="$4" gate_rc=0
+    discovery_gate_status "$candidate_path" "$gate_name" || gate_rc=$?
+    if [[ "$gate_rc" -ne "$expected_rc" ]]; then
+        flag_discovery_canary "discovery_gate_status on ${path_label} under the '${gate_name}' gate returned ${gate_rc}, expected ${expected_rc}"
+    fi
+}
+
+if [[ ! -L "$dcanary_link_dir" || ! -L "$dcanary_dangling_file" ]]; then
+    flag_discovery_canary "precondition: ${DISCOVERY_CANARY_REL}/tree/link-dir and ${DISCOVERY_CANARY_REL}/broken/dangling.md must both be symlinks in this checkout, but at least one is not -- the likely cause is core.symlinks=false materialising them as plain files; set core.symlinks=true and re-checkout, never skip this canary"
+fi
+
+if [[ "${#DISCOVERY_FIND_BASE[@]}" -ne 1 || "${DISCOVERY_FIND_BASE[0]}" != '-L' ]]; then
+    flag_discovery_canary "DISCOVERY_FIND_BASE is '${DISCOVERY_FIND_BASE[*]}' (${#DISCOVERY_FIND_BASE[@]} element(s)) but must be exactly the single element '-L' -- discovery must follow symlinks script-wide"
+fi
+
+declare -a dcanary_paths=()
+dcanary_rc=0
+discover_paths dcanary_paths "$dcanary_tree" -- -name '*.md' || dcanary_rc=$?
+dcanary_accepted_total=0
+dcanary_saw_real=false
+dcanary_saw_linked=false
+for dcanary_path in "${dcanary_paths[@]}"; do
+    dcanary_gate_rc=0
+    discovery_gate_status "$dcanary_path" files || dcanary_gate_rc=$?
+    if [[ "$dcanary_gate_rc" -eq 0 ]]; then
+        dcanary_accepted_total=$((dcanary_accepted_total + 1))
+    fi
+    if [[ "$dcanary_path" == "$dcanary_real_file" ]]; then
+        dcanary_saw_real=true
+    elif [[ "$dcanary_path" == "$dcanary_linked_file" ]]; then
+        dcanary_saw_linked=true
+    fi
+done
+if [[ "$dcanary_rc" -ne 0 || "${#dcanary_paths[@]}" -ne 2 || "$dcanary_accepted_total" -ne 2 \
+   || "$dcanary_saw_real" != true || "$dcanary_saw_linked" != true ]]; then
+    flag_discovery_canary "discover_paths over ${DISCOVERY_CANARY_REL}/tree returned status ${dcanary_rc} and materialised ${#dcanary_paths[@]} path(s) [${dcanary_paths[*]}], ${dcanary_accepted_total} accepted by the 'files' gate; expected status 0 and exactly real/inner.md and link-dir/inner.md, both accepted -- -L no longer descends a symlinked directory"
+fi
+
+# INTENTIONAL NON-HELPER FIND: the only raw find in this canary, run with an
+# explicit -P as the negative control for the -L probe above; it is not a
+# discovery call site and must never be migrated to discover_paths.
+dcanary_raw_rc=0
+dcanary_raw_listing="$(find -P "$dcanary_tree" -name '*.md' -print)" || dcanary_raw_rc=$?
+if [[ "$dcanary_raw_rc" -ne 0 || "$dcanary_raw_listing" != "$dcanary_real_file" ]]; then
+    dcanary_raw_flat="${dcanary_raw_listing//$'\n'/ | }"
+    flag_discovery_canary "negative control: find -P over ${DISCOVERY_CANARY_REL}/tree returned status ${dcanary_raw_rc} and [${dcanary_raw_flat}], expected status 0 and exactly real/inner.md -- the positive probe no longer discriminates -L from -P"
+fi
+
+expect_discovery_gate 'broken/dangling.md' "$dcanary_dangling_file" files "$DISCOVERY_GATE_RC_MISSING"
+expect_discovery_gate 'broken/dangling.md' "$dcanary_dangling_file" raw 0
+expect_discovery_gate 'tree/real (a directory)' "$dcanary_real_dir" files "$DISCOVERY_GATE_RC_NOT_REGULAR"
+expect_discovery_gate 'tree/link-dir (a symlinked directory)' "$dcanary_link_dir" dirs 0
+expect_discovery_gate 'tree/real/inner.md (a regular file)' "$dcanary_real_file" dirs "$DISCOVERY_GATE_RC_NOT_DIR"
+expect_discovery_gate 'tree/real/inner.md (positive control)' "$dcanary_real_file" files 0
+
+dcanary_missing_rc=0
+discover_paths dcanary_paths "$dcanary_missing_root" -- -name '*.md' 2>/dev/null || dcanary_missing_rc=$?
+if [[ "$dcanary_missing_rc" -eq 0 || "$dcanary_missing_rc" -eq "$DISCOVERY_RC_TRUNCATED" \
+   || "$dcanary_missing_rc" -eq "$DISCOVERY_RC_USAGE" ]]; then
+    flag_discovery_canary "discover_paths over the nonexistent root ${DISCOVERY_CANARY_REL}/__discovery_nonexistent__ returned ${dcanary_missing_rc}, expected find's own non-zero status -- a failing find (a missing root or a symlink loop) no longer propagates, so it would read as a clean tree"
+fi
+
+if [[ "$dcanary_found" == false ]]; then
+    echo '[PASS] DISCOVERY: checked discovery follows symlinked directories, gates dangling and wrong-type paths, and propagates find failures'
+    CHECKS_PASSED=$((CHECKS_PASSED + 1))
+else
+    echo '[FAIL] DISCOVERY: checked-discovery canary'
+    CHECKS_FAILED=$((CHECKS_FAILED + 1))
+fi
+
+mark_time 'DISCOVERY'
+
 # ── CHECK 1: Forbidden hedge ───────────────────────────────────────────────
 
 echo ''

From fe2dad9b62a85538ef09eba872e1f73fa883ff84 Mon Sep 17 00:00:00 2001
From: Bren Pike <brenpike@gmail.com>
Date: Fri, 25 Sep 2026 15:43:17 -0600
Subject: [PATCH 03/10] fix(policy): route CHECK 1-14 discovery through checked
 helper

---
 tools/policy_check.sh | 290 ++++++++++++++++++++++++++++++++++++------
 1 file changed, 250 insertions(+), 40 deletions(-)

diff --git a/tools/policy_check.sh b/tools/policy_check.sh
index fd2cefba..6ae7ca36 100644
--- a/tools/policy_check.sh
+++ b/tools/policy_check.sh
@@ -633,7 +633,21 @@ echo '=== CHECK 1: Forbidden hedge ==='
 
 check1_found=false
 
-while IFS= read -r -d '' md_file; do
+declare -a check1_md_files=()
+check1_discovery_rc=0
+discover_paths check1_md_files "$PLUGIN_ROOT" -- -name '*.md' || check1_discovery_rc=$?
+if [[ "$check1_discovery_rc" -ne 0 ]]; then
+    check1_found=true
+    flag_discovery_failure 'CHECK1' "$PLUGIN_ROOT" 'plugin Markdown files' "$check1_discovery_rc"
+fi
+for md_file in "${check1_md_files[@]}"; do
+    check1_gate_rc=0
+    discovery_gate_status "$md_file" files || check1_gate_rc=$?
+    if [[ "$check1_gate_rc" -ne 0 ]]; then
+        check1_found=true
+        flag_discovery_gate 'CHECK1' "$md_file" "$check1_gate_rc"
+        continue
+    fi
     # Candidate prefilter (#305): one grep per FILE on the BROADEST pattern.
     # Every finding-producing line must pass the ladder's \bambiguous\b gate
     # below, so non-matching lines can never add a finding; the
@@ -696,7 +710,7 @@ while IFS= read -r -d '' md_file; do
         add_finding 'CHECK1' "$md_file" "$line_num" \
             "Forbidden hedge: 'ambiguous' used as gate-level uncertainty"
     done <<< "$candidates"
-done < <(find "$PLUGIN_ROOT" -name '*.md' -type f -print0)
+done
 
 if [[ "$check1_found" == false ]]; then
     echo '[PASS] Check 1: No forbidden hedge violations found'
@@ -751,17 +765,41 @@ echo '=== CHECK 3: Skill names exist ==='
 
 AGENT_NAMES=('cerebrate' 'overlord' 'drone' 'changeling' 'local-reviewer' 'github-reviewer')
 
+check3_found=false
+
 # Collect scan sources
 declare -a SCAN_FILES=()
-while IFS= read -r -d '' f; do
-    SCAN_FILES+=("$f")
-done < <(find "$PLUGIN_ROOT/agents" -maxdepth 1 -name '*.md' -type f -print0 2>/dev/null)
-while IFS= read -r -d '' f; do
-    SCAN_FILES+=("$f")
-done < <(find "$PLUGIN_ROOT/skills" -name 'SKILL.md' -type f -print0 2>/dev/null)
-while IFS= read -r -d '' f; do
-    SCAN_FILES+=("$f")
-done < <(find "$PLUGIN_ROOT/governance" -maxdepth 1 -name '*.md' -type f -print0 2>/dev/null)
+declare -a check3_agent_files=()
+check3_discovery_rc=0
+discover_paths check3_agent_files "$PLUGIN_ROOT/agents" -- -maxdepth 1 -name '*.md' || check3_discovery_rc=$?
+if [[ "$check3_discovery_rc" -ne 0 ]]; then
+    check3_found=true
+    flag_discovery_failure 'CHECK3' "$PLUGIN_ROOT/agents" 'agent Markdown files' "$check3_discovery_rc"
+fi
+declare -a check3_skill_files=()
+check3_discovery_rc=0
+discover_paths check3_skill_files "$PLUGIN_ROOT/skills" -- -name 'SKILL.md' || check3_discovery_rc=$?
+if [[ "$check3_discovery_rc" -ne 0 ]]; then
+    check3_found=true
+    flag_discovery_failure 'CHECK3' "$PLUGIN_ROOT/skills" 'skill SKILL.md files' "$check3_discovery_rc"
+fi
+declare -a check3_governance_files=()
+check3_discovery_rc=0
+discover_paths check3_governance_files "$PLUGIN_ROOT/governance" -- -maxdepth 1 -name '*.md' || check3_discovery_rc=$?
+if [[ "$check3_discovery_rc" -ne 0 ]]; then
+    check3_found=true
+    flag_discovery_failure 'CHECK3' "$PLUGIN_ROOT/governance" 'governance Markdown files' "$check3_discovery_rc"
+fi
+for scan_candidate in "${check3_agent_files[@]}" "${check3_skill_files[@]}" "${check3_governance_files[@]}"; do
+    check3_gate_rc=0
+    discovery_gate_status "$scan_candidate" files || check3_gate_rc=$?
+    if [[ "$check3_gate_rc" -ne 0 ]]; then
+        check3_found=true
+        flag_discovery_gate 'CHECK3' "$scan_candidate" "$check3_gate_rc"
+        continue
+    fi
+    SCAN_FILES+=("$scan_candidate")
+done
 
 # Extract all hivemind:* references.
 # skill_refs: associative array mapping skill name -> space-separated source file paths
@@ -800,7 +838,6 @@ for scan_file in "${SCAN_FILES[@]}"; do
     done < <(echo "$scan_content" | grep -oP 'hivemind:\K[a-zA-Z0-9_-]+' | sort -u)
 done
 
-check3_found=false
 skill_ref_count=${#SKILL_REF_SOURCES[@]}
 for skill_name in "${!SKILL_REF_SOURCES[@]}"; do
     skill_md_path="$PLUGIN_ROOT/skills/$skill_name/SKILL.md"
@@ -857,7 +894,21 @@ echo ''
 echo '=== CHECK 5: Unsupported frontmatter fields ==='
 
 check5_found=false
-while IFS= read -r -d '' agent_file; do
+declare -a check5_agent_files=()
+check5_discovery_rc=0
+discover_paths check5_agent_files "$PLUGIN_ROOT/agents" -- -maxdepth 1 -name '*.md' || check5_discovery_rc=$?
+if [[ "$check5_discovery_rc" -ne 0 ]]; then
+    check5_found=true
+    flag_discovery_failure 'CHECK5' "$PLUGIN_ROOT/agents" 'agent Markdown files' "$check5_discovery_rc"
+fi
+for agent_file in "${check5_agent_files[@]}"; do
+    check5_gate_rc=0
+    discovery_gate_status "$agent_file" files || check5_gate_rc=$?
+    if [[ "$check5_gate_rc" -ne 0 ]]; then
+        check5_found=true
+        flag_discovery_gate 'CHECK5' "$agent_file" "$check5_gate_rc"
+        continue
+    fi
     in_frontmatter=false
     frontmatter_started=false
     line_num=0
@@ -889,7 +940,7 @@ while IFS= read -r -d '' agent_file; do
                 'Unsupported frontmatter field: permissionMode'
         fi
     done < "$agent_file"
-done < <(find "$PLUGIN_ROOT/agents" -maxdepth 1 -name '*.md' -type f -print0)
+done
 
 if [[ "$check5_found" == false ]]; then
     echo '[PASS] Check 5: No unsupported frontmatter fields found'
@@ -908,7 +959,21 @@ echo '=== CHECK 6: Governance reference paths resolve ==='
 check6_found=false
 # PLUGIN_ROOT is invariant across the scan; resolve it once (#305).
 normalized_plugin_root="$(realpath -m "$PLUGIN_ROOT")"
-while IFS= read -r -d '' md_file; do
+declare -a check6_md_files=()
+check6_discovery_rc=0
+discover_paths check6_md_files "$PLUGIN_ROOT" -- -name '*.md' || check6_discovery_rc=$?
+if [[ "$check6_discovery_rc" -ne 0 ]]; then
+    check6_found=true
+    flag_discovery_failure 'CHECK6' "$PLUGIN_ROOT" 'plugin Markdown files' "$check6_discovery_rc"
+fi
+for md_file in "${check6_md_files[@]}"; do
+    check6_gate_rc=0
+    discovery_gate_status "$md_file" files || check6_gate_rc=$?
+    if [[ "$check6_gate_rc" -ne 0 ]]; then
+        check6_found=true
+        flag_discovery_gate 'CHECK6' "$md_file" "$check6_gate_rc"
+        continue
+    fi
     # Candidate prefilter (#305): the extraction below requires the literal
     # ${CLAUDE_PLUGIN_ROOT}/ prefix, so one fixed-string grep per FILE finds
     # every line that can yield a reference.
@@ -943,7 +1008,7 @@ while IFS= read -r -d '' md_file; do
             fi
         done < <(echo "$textline" | grep -oP '\$\{CLAUDE_PLUGIN_ROOT\}/\K[^\s`\)]+' || true)
     done <<< "$candidates"
-done < <(find "$PLUGIN_ROOT" -name '*.md' -type f -print0)
+done
 
 if [[ "$check6_found" == false ]]; then
     echo '[PASS] Check 6: All governance reference paths resolve'
@@ -963,7 +1028,21 @@ REQUIRED_FRONTMATTER_FIELDS=('name' 'description' 'allowed-tools' 'shell')
 check7_found=false
 skill_file_count=0
 
-while IFS= read -r -d '' skill_file; do
+declare -a check7_skill_files=()
+check7_discovery_rc=0
+discover_paths check7_skill_files "$PLUGIN_ROOT/skills" -- -name 'SKILL.md' || check7_discovery_rc=$?
+if [[ "$check7_discovery_rc" -ne 0 ]]; then
+    check7_found=true
+    flag_discovery_failure 'CHECK7' "$PLUGIN_ROOT/skills" 'skill SKILL.md files' "$check7_discovery_rc"
+fi
+for skill_file in "${check7_skill_files[@]}"; do
+    check7_gate_rc=0
+    discovery_gate_status "$skill_file" files || check7_gate_rc=$?
+    if [[ "$check7_gate_rc" -ne 0 ]]; then
+        check7_found=true
+        flag_discovery_gate 'CHECK7' "$skill_file" "$check7_gate_rc"
+        continue
+    fi
     skill_file_count=$((skill_file_count + 1))
 
     fm_content="$(get_frontmatter "$skill_file")"
@@ -974,7 +1053,7 @@ while IFS= read -r -d '' skill_file; do
                 "Missing required frontmatter field: $field_name"
         fi
     done
-done < <(find "$PLUGIN_ROOT/skills" -name 'SKILL.md' -type f -print0)
+done
 
 if [[ "$check7_found" == false ]]; then
     echo "[PASS] Check 7: All $skill_file_count skill files have complete frontmatter"
@@ -991,7 +1070,21 @@ echo ''
 echo '=== CHECK 8: No bare governance/agents/skills path refs ==='
 
 check8_found=false
-while IFS= read -r -d '' md_file; do
+declare -a check8_md_files=()
+check8_discovery_rc=0
+discover_paths check8_md_files "$PLUGIN_ROOT" -- -name '*.md' || check8_discovery_rc=$?
+if [[ "$check8_discovery_rc" -ne 0 ]]; then
+    check8_found=true
+    flag_discovery_failure 'CHECK8' "$PLUGIN_ROOT" 'plugin Markdown files' "$check8_discovery_rc"
+fi
+for md_file in "${check8_md_files[@]}"; do
+    check8_gate_rc=0
+    discovery_gate_status "$md_file" files || check8_gate_rc=$?
+    if [[ "$check8_gate_rc" -ne 0 ]]; then
+        check8_found=true
+        flag_discovery_gate 'CHECK8' "$md_file" "$check8_gate_rc"
+        continue
+    fi
     # Candidate prefilter (#305): one grep per FILE for the bare-ref shape
     # WITHOUT the left-boundary group. Sound superset: every flagged ref is
     # built solely of characters inside the strip-token class below, and the
@@ -1015,7 +1108,7 @@ while IFS= read -r -d '' md_file; do
                 "Bare path ref (missing \${CLAUDE_PLUGIN_ROOT}/ prefix): $bare_ref"
         done < <(echo "$stripped" | grep -oP '(^|[^A-Za-z0-9_./-])\K(agents|skills|governance|references|workflows)/([A-Za-z0-9_-]+/)*[A-Za-z0-9_-]+\.(md|sh|json)' || true)
     done <<< "$candidates"
-done < <(find "$PLUGIN_ROOT" -name '*.md' -type f -print0)
+done
 
 if [[ "$check8_found" == false ]]; then
     echo '[PASS] Check 8: No bare governance/agents/skills path refs'
@@ -1113,7 +1206,21 @@ first_match_line() {
 check9_found=false
 check9_script_count=0
 
-while IFS= read -r -d '' engine_script; do
+declare -a check9_engine_scripts=()
+check9_discovery_rc=0
+discover_paths check9_engine_scripts "$PLUGIN_ROOT/skills" -- -path '*/scripts/*.sh' || check9_discovery_rc=$?
+if [[ "$check9_discovery_rc" -ne 0 ]]; then
+    check9_found=true
+    flag_discovery_failure 'CHECK9' "$PLUGIN_ROOT/skills" 'skill engine scripts' "$check9_discovery_rc"
+fi
+for engine_script in "${check9_engine_scripts[@]}"; do
+    check9_gate_rc=0
+    discovery_gate_status "$engine_script" files || check9_gate_rc=$?
+    if [[ "$check9_gate_rc" -ne 0 ]]; then
+        check9_found=true
+        flag_discovery_gate 'CHECK9' "$engine_script" "$check9_gate_rc"
+        continue
+    fi
     # Only engine scripts that source the containment helper participate.
     if ! grep -qE '(^|[[:space:]])(\.|source)[[:space:]][^#]*containment\.sh' "$engine_script"; then
         continue
@@ -1183,7 +1290,7 @@ while IFS= read -r -d '' engine_script; do
     done
 
     unset token_labels token_guards token_reads token_read_excludes
-done < <(find "$PLUGIN_ROOT/skills" -path '*/scripts/*.sh' -type f -print0)
+done
 
 if [[ "$check9_found" == false ]]; then
     echo "[PASS] Check 9: All $check9_script_count containment-sourcing engine scripts guard each token before its first read"
@@ -1206,14 +1313,28 @@ echo '=== CHECK 10: No literal NUL byte in plugin Markdown payload ==='
 
 check10_found=false
 check10_md_count=0
-while IFS= read -r -d '' md_file; do
+declare -a check10_md_files=()
+check10_discovery_rc=0
+discover_paths check10_md_files "$PLUGIN_ROOT" -- -name '*.md' || check10_discovery_rc=$?
+if [[ "$check10_discovery_rc" -ne 0 ]]; then
+    check10_found=true
+    flag_discovery_failure 'CHECK10' "$PLUGIN_ROOT" 'plugin Markdown files' "$check10_discovery_rc"
+fi
+for md_file in "${check10_md_files[@]}"; do
+    check10_gate_rc=0
+    discovery_gate_status "$md_file" files || check10_gate_rc=$?
+    if [[ "$check10_gate_rc" -ne 0 ]]; then
+        check10_found=true
+        flag_discovery_gate 'CHECK10' "$md_file" "$check10_gate_rc"
+        continue
+    fi
     check10_md_count=$((check10_md_count + 1))
     if LC_ALL=C grep -qaP '\x00' "$md_file" 2>/dev/null; then
         check10_found=true
         add_finding 'CHECK10' "$md_file" 0 \
             "Literal NUL byte in plugin Markdown payload — replace with a textual escape (e.g. \\u0000 or <NUL>); NUL makes the file binary and breaks Markdown/shell tooling and plugin consumers"
     fi
-done < <(find "$PLUGIN_ROOT" -name '*.md' -type f -print0)
+done
 
 if [[ "$check10_found" == false ]]; then
     echo "[PASS] Check 10: All $check10_md_count plugin Markdown payload files are free of literal NUL bytes"
@@ -1254,7 +1375,21 @@ declare -a CHECK11_CANDIDATE_WORDS=()
 IFS='|' read -ra CHECK11_CANDIDATE_WORDS <<< "${BIOFORM_DENYLIST,,}|${CHECK11_KEEP_REGEX,,}"
 
 check11_found=false
-while IFS= read -r -d '' skill_file; do
+declare -a check11_skill_files=()
+check11_discovery_rc=0
+discover_paths check11_skill_files "$PLUGIN_ROOT/skills" -- -name 'SKILL.md' || check11_discovery_rc=$?
+if [[ "$check11_discovery_rc" -ne 0 ]]; then
+    check11_found=true
+    flag_discovery_failure 'CHECK11' "$PLUGIN_ROOT/skills" 'skill SKILL.md files' "$check11_discovery_rc"
+fi
+for skill_file in "${check11_skill_files[@]}"; do
+    check11_gate_rc=0
+    discovery_gate_status "$skill_file" files || check11_gate_rc=$?
+    if [[ "$check11_gate_rc" -ne 0 ]]; then
+        check11_found=true
+        flag_discovery_gate 'CHECK11' "$skill_file" "$check11_gate_rc"
+        continue
+    fi
     # One-pass awk state machine emits surviving BODY lines as "line_num<TAB>line",
     # excluding YAML frontmatter, fenced code blocks, and markdown table rows.
     while IFS=$'\t' read -r line_num textline; do
@@ -1297,7 +1432,7 @@ while IFS= read -r -d '' skill_file; do
             print NR "\t" $0
         }
     ' "$skill_file")
-done < <(find "$PLUGIN_ROOT/skills" -name 'SKILL.md' -type f -print0)
+done
 
 if [[ "$check11_found" == false ]]; then
     echo '[PASS] Check 11: No bare calling-bioform name in skill body prose (P14)'
@@ -1331,7 +1466,21 @@ echo '=== CHECK 12: No bare validation-tool/manifest token in governance/agents
 CHECK12_DENYLIST='tools/validate\.sh|bash -n|python3 -m json\.tool|test_[a-z0-9_]+\.sh|package\.json|pyproject\.toml|Cargo\.toml|go\.mod|requirements\.txt|plugin\.json|marketplace\.json'
 
 check12_found=false
-while IFS= read -r -d '' doc_file; do
+declare -a check12_doc_files=()
+check12_discovery_rc=0
+discover_paths check12_doc_files "$PLUGIN_ROOT/governance" "$PLUGIN_ROOT/agents" -- -maxdepth 1 -name '*.md' || check12_discovery_rc=$?
+if [[ "$check12_discovery_rc" -ne 0 ]]; then
+    check12_found=true
+    flag_discovery_failure 'CHECK12' "$PLUGIN_ROOT" 'governance and agent Markdown files' "$check12_discovery_rc"
+fi
+for doc_file in "${check12_doc_files[@]}"; do
+    check12_gate_rc=0
+    discovery_gate_status "$doc_file" files || check12_gate_rc=$?
+    if [[ "$check12_gate_rc" -ne 0 ]]; then
+        check12_found=true
+        flag_discovery_gate 'CHECK12' "$doc_file" "$check12_gate_rc"
+        continue
+    fi
     # One-pass awk state machine emits surviving BODY lines as "line_num<TAB>line",
     # excluding YAML frontmatter, fenced code blocks, and >=4-space indented lines.
     while IFS=$'\t' read -r line_num textline; do
@@ -1376,7 +1525,7 @@ while IFS= read -r -d '' doc_file; do
             print NR "\t" $0
         }
     ' "$doc_file")
-done < <(find "$PLUGIN_ROOT/governance" "$PLUGIN_ROOT/agents" -maxdepth 1 -name '*.md' -type f -print0)
+done
 
 if [[ "$check12_found" == false ]]; then
     echo '[PASS] Check 12: No bare validation-tool/manifest token in governance/agents prose'
@@ -1431,7 +1580,21 @@ echo ''
 echo '=== CHECK 13: P18 fail-closed shell floor ==='
 
 check13_found=false
-while IFS= read -r -d '' shell_script; do
+declare -a check13_shell_scripts=()
+check13_discovery_rc=0
+discover_paths check13_shell_scripts "$PLUGIN_ROOT" -- -name '*.sh' || check13_discovery_rc=$?
+if [[ "$check13_discovery_rc" -ne 0 ]]; then
+    check13_found=true
+    flag_discovery_failure 'CHECK13' "$PLUGIN_ROOT" 'plugin shell scripts' "$check13_discovery_rc"
+fi
+for shell_script in "${check13_shell_scripts[@]}"; do
+    check13_gate_rc=0
+    discovery_gate_status "$shell_script" files || check13_gate_rc=$?
+    if [[ "$check13_gate_rc" -ne 0 ]]; then
+        check13_found=true
+        flag_discovery_gate 'CHECK13' "$shell_script" "$check13_gate_rc"
+        continue
+    fi
     has_errexit=false
     has_nounset=false
     has_pipefail=false
@@ -1659,7 +1822,7 @@ while IFS= read -r -d '' shell_script; do
     fi
     add_finding 'CHECK13' "$shell_script" "$finding_line" \
         "missing P18 fail-closed shell floor (set -euo pipefail) -- add the floor or document a justified CHECK13 allowlist exception"
-done < <(find "$PLUGIN_ROOT" -name '*.sh' -type f -print0)
+done
 
 if [[ "$check13_found" == false ]]; then
     echo '[PASS] Check 13: All plugin shell scripts carry the P18 fail-closed floor or a CHECK13 exception'
@@ -1751,24 +1914,70 @@ skill_declares_navigator_marker() {
 }
 
 # skill_sources_containment SKILL_DIR
-# Echoes "true" when any engine script under SKILL_DIR/scripts sources
-# containment.sh under CHECK 9's enrollment predicate (reused verbatim).
+# Sets SKILL_SOURCES_CONTAINMENT_RESULT to "true" when any engine script under
+# SKILL_DIR/scripts sources containment.sh under CHECK 9's enrollment predicate
+# (reused verbatim), "false" otherwise -- including when SKILL_DIR/scripts is
+# absent. A scripts path that exists but is not a followable directory, a
+# failed discovery, or a rejected script is reported as a CHECK14 finding (and
+# sets check14_found), so the result is returned in a global rather than by
+# command substitution: a subshell would drop those findings.
+SKILL_SOURCES_CONTAINMENT_RESULT=""
 skill_sources_containment() {
     local skill_dir="$1"
+    local scripts_dir="$skill_dir/scripts"
     local engine_script
-    while IFS= read -r -d '' engine_script; do
+    SKILL_SOURCES_CONTAINMENT_RESULT="false"
+    if [[ ! -e "$scripts_dir" && ! -L "$scripts_dir" ]]; then
+        return 0
+    fi
+    local scripts_dir_rc=0
+    discovery_gate_status "$scripts_dir" dirs || scripts_dir_rc=$?
+    if [[ "$scripts_dir_rc" -ne 0 ]]; then
+        check14_found=true
+        flag_discovery_gate 'CHECK14' "$scripts_dir" "$scripts_dir_rc"
+        return 0
+    fi
+    local -a check14_engine_scripts=()
+    local check14_scripts_rc=0
+    discover_paths check14_engine_scripts "$scripts_dir" -- -maxdepth 1 -name '*.sh' || check14_scripts_rc=$?
+    if [[ "$check14_scripts_rc" -ne 0 ]]; then
+        check14_found=true
+        flag_discovery_failure 'CHECK14' "$scripts_dir" 'skill engine scripts' "$check14_scripts_rc"
+    fi
+    local engine_gate_rc
+    for engine_script in "${check14_engine_scripts[@]}"; do
+        engine_gate_rc=0
+        discovery_gate_status "$engine_script" files || engine_gate_rc=$?
+        if [[ "$engine_gate_rc" -ne 0 ]]; then
+            check14_found=true
+            flag_discovery_gate 'CHECK14' "$engine_script" "$engine_gate_rc"
+            continue
+        fi
         if grep -qE '(^|[[:space:]])(\.|source)[[:space:]][^#]*containment\.sh' "$engine_script"; then
-            echo "true"
-            return
+            SKILL_SOURCES_CONTAINMENT_RESULT="true"
+            return 0
         fi
-    done < <(find "$skill_dir/scripts" -maxdepth 1 -name '*.sh' -type f -print0 2>/dev/null || true)
-    echo "false"
+    done
 }
 
 check14_found=false
 check14_navigator_count=0
 
-while IFS= read -r -d '' skill_file; do
+declare -a check14_skill_files=()
+check14_discovery_rc=0
+discover_paths check14_skill_files "$PLUGIN_ROOT/skills" -- -maxdepth 2 -name 'SKILL.md' || check14_discovery_rc=$?
+if [[ "$check14_discovery_rc" -ne 0 ]]; then
+    check14_found=true
+    flag_discovery_failure 'CHECK14' "$PLUGIN_ROOT/skills" 'skill SKILL.md files' "$check14_discovery_rc"
+fi
+for skill_file in "${check14_skill_files[@]}"; do
+    check14_gate_rc=0
+    discovery_gate_status "$skill_file" files || check14_gate_rc=$?
+    if [[ "$check14_gate_rc" -ne 0 ]]; then
+        check14_found=true
+        flag_discovery_gate 'CHECK14' "$skill_file" "$check14_gate_rc"
+        continue
+    fi
     if [[ "$(skill_declares_navigator_marker "$skill_file")" != "true" ]]; then
         continue
     fi
@@ -1779,7 +1988,8 @@ while IFS= read -r -d '' skill_file; do
     marker_line="$(grep -nF "$CHECK14_MARKER" "$skill_file" 2>/dev/null | head -n1 | cut -d: -f1 || true)"
     [[ -z "$marker_line" ]] && marker_line=0
 
-    if [[ "$(skill_sources_containment "$skill_dir")" != "true" ]]; then
+    skill_sources_containment "$skill_dir"
+    if [[ "$SKILL_SOURCES_CONTAINMENT_RESULT" != "true" ]]; then
         check14_found=true
         add_finding 'CHECK14' "$skill_file" "$marker_line" \
             "Inert inputs-file navigator hivemind:${skill_name} fails obligation (a): no plugin/skills/${skill_name}/scripts/*.sh sources containment.sh in the direct '. <path>/containment.sh' form CHECK 9 enrolls on (an indirect loop-variable source does not enroll) -- until it does, CHECK 9's guard-before-read enforcement never applies to this navigator"
@@ -1790,7 +2000,7 @@ while IFS= read -r -d '' skill_file; do
         add_finding 'CHECK14' "$skill_file" "$marker_line" \
             "Inert inputs-file navigator hivemind:${skill_name} fails obligation (b): literal 'hivemind:${skill_name}' is absent from the '${CHECK14_SECTION_HEADING}' section of plugin/governance/security-policy.md -- add it to the covered-set enumeration"
     fi
-done < <(find "$PLUGIN_ROOT/skills" -maxdepth 2 -name 'SKILL.md' -type f -print0)
+done
 
 # FAIL-CLOSED on the discovery key itself: zero navigators means the marker was
 # renamed or dropped, which would silently disarm this check rather than fail it.

From 2fe288cd2fd5bee599e666c60c163fb1d14372c3 Mon Sep 17 00:00:00 2001
From: Bren Pike <brenpike@gmail.com>
Date: Fri, 25 Sep 2026 15:57:47 -0600
Subject: [PATCH 04/10] refactor(policy): single discovery engine incl. CHECK
 15

---
 tools/policy_check.sh | 490 +++++++++++++++++++-----------------------
 1 file changed, 217 insertions(+), 273 deletions(-)

diff --git a/tools/policy_check.sh b/tools/policy_check.sh
index 6ae7ca36..c522122a 100644
--- a/tools/policy_check.sh
+++ b/tools/policy_check.sh
@@ -286,17 +286,22 @@ file_candidates() {
 #   symlinks are FOLLOWED script-wide -- a symlinked file or directory is
 #   scanned as its target. Failures are loud, never silently skipped:
 #     - a symlink loop makes find print an error and exit non-zero (it keeps
-#       traversing), so discover_paths returns that status and the caller
-#       reports it through flag_discovery_failure;
+#       traversing), so discover_paths returns that status and
+#       discover_checked_paths reports it through flag_discovery_failure;
 #     - a dangling symlink is printed by find -L with exit 0, so it is the
 #       `files` gate of discovery_gate_status that rejects it (missing), and
-#       the caller reports it through flag_discovery_gate.
+#       discover_checked_paths reports it through flag_discovery_gate.
+#   Call sites: every scanning check discovers through discover_checked_paths,
+#   the one composition of the pieces below. discover_paths and
+#   discovery_gate_status are called directly only by canaries, which assert
+#   their statuses without emitting a real finding.
 #   Precondition: every ROOT must exist. This is the CALLER's job; there is
 #   no swallow mode and find's stderr is never suppressed, so a missing root
 #   fails discovery with find's non-zero status and must be reported.
 #   Findings: both reporting wrappers emit through add_finding, so --strict
-#   and the allowlist apply. They do NOT set any per-check found/pass flag;
-#   the caller owns that.
+#   and the allowlist apply. Neither they nor discover_checked_paths set any
+#   per-check found/pass flag; discover_checked_paths returns non-zero when it
+#   emitted a finding, and the caller owns its flag.
 #   Residuals: symlink-loop reporting is not witnessed by a committed fixture;
 #   a symlinked directory that points back inside a scanned root materialises
 #   the same file under two paths (it is scanned twice, never skipped).
@@ -445,6 +450,50 @@ flag_discovery_gate() {
         "this discovered path ${rejection_reason}, so it was never checked -- fix or remove it; an unchecked path is NOT clean"
 }
 
+# discover_checked_paths RULE DEST_ARRAY GATE LABEL ROOT... -- FIND_ARGS...
+# The checked discovery every scanning check calls. Runs
+#   discover_paths ROOT... -- FIND_ARGS...
+# and reports a non-zero status through flag_discovery_failure (anchored at
+# the first ROOT, described by LABEL); then gates each materialised path with
+# discovery_gate_status PATH GATE and reports each rejection through
+# flag_discovery_gate. DEST_ARRAY is replaced with ONLY the accepted paths, in
+# find order. Returns 1 when it emitted any RULE finding, else 0, so the
+# caller sets its own flag: `discover_checked_paths ... || checkN_found=true`.
+#
+# INVARIANT: DEST_ARRAY is bound by nameref, so it must not be one of this
+# function's own `checked_discovery_*` locals (the nameref would bind the
+# local, not the caller's array) and, like every discover_paths DEST, must not
+# be `discovery_*`-prefixed. Nested use -- a discovery inside another
+# discovery's loop -- needs distinct DEST names.
+discover_checked_paths() {
+    local checked_discovery_rule="$1" checked_discovery_gate="$3" checked_discovery_label="$4"
+    local -n checked_discovery_dest_ref="$2"
+    shift 4
+    local -a checked_discovery_materialised=()
+    local checked_discovery_rc=0 checked_discovery_flagged=false
+    local checked_discovery_path checked_discovery_gate_rc
+    discover_paths checked_discovery_materialised "$@" || checked_discovery_rc=$?
+    if [[ "$checked_discovery_rc" -ne 0 ]]; then
+        checked_discovery_flagged=true
+        flag_discovery_failure "$checked_discovery_rule" "$1" "$checked_discovery_label" "$checked_discovery_rc"
+    fi
+    checked_discovery_dest_ref=()
+    for checked_discovery_path in "${checked_discovery_materialised[@]}"; do
+        checked_discovery_gate_rc=0
+        discovery_gate_status "$checked_discovery_path" "$checked_discovery_gate" || checked_discovery_gate_rc=$?
+        if [[ "$checked_discovery_gate_rc" -ne 0 ]]; then
+            checked_discovery_flagged=true
+            flag_discovery_gate "$checked_discovery_rule" "$checked_discovery_path" "$checked_discovery_gate_rc"
+            continue
+        fi
+        checked_discovery_dest_ref+=("$checked_discovery_path")
+    done
+    if [[ "$checked_discovery_flagged" == true ]]; then
+        return 1
+    fi
+    return 0
+}
+
 # ── Timing instrumentation ──────────────────────────────────────────────────
 # Permanent per-check profiling (#305, precedent #304). Emits one
 # "[TIME] <label> <elapsed>s" line after each check block and a per-check
@@ -519,7 +568,12 @@ CHECKS_FAILED=0
 #     control, so the failure arms cannot all pass by the gate failing
 #     unconditionally;
 #   * status propagation: discover_paths over a nonexistent root returns
-#     find's own non-zero status (not TRUNCATED or USAGE).
+#     find's own non-zero status (not TRUNCATED or USAGE);
+#   * composition: discover_checked_paths over the whole canary root under the
+#     `files` gate keeps exactly real/inner.md and link-dir/inner.md, returns
+#     non-zero, and emits exactly one finding, naming broken/dangling.md. It
+#     runs inside a command substitution so that finding is captured as text
+#     and its FINDING_* append dies with the subshell -- no real finding.
 # The fixtures are committed, so no probe creates a filesystem object at run
 # time. stderr is discarded only for the nonexistent-root probe, whose find
 # error is the expected outcome.
@@ -616,6 +670,55 @@ if [[ "$dcanary_missing_rc" -eq 0 || "$dcanary_missing_rc" -eq "$DISCOVERY_RC_TR
     flag_discovery_canary "discover_paths over the nonexistent root ${DISCOVERY_CANARY_REL}/__discovery_nonexistent__ returned ${dcanary_missing_rc}, expected find's own non-zero status -- a failing find (a missing root or a symlink loop) no longer propagates, so it would read as a clean tree"
 fi
 
+# probe_checked_discovery_composition
+# Prints discover_checked_paths' output over the canary root (its findings),
+# then `rc=STATUS` and one `accepted=PATH` line per accepted path. Called only
+# inside a command substitution, so the finding it emits stays in the subshell.
+probe_checked_discovery_composition() {
+    local -a dcanary_checked_paths=()
+    local dcanary_checked_rc=0 dcanary_checked_path
+    discover_checked_paths 'DISCOVERY' dcanary_checked_paths files 'discovery canary Markdown files' "$dcanary_root" -- -name '*.md' || dcanary_checked_rc=$?
+    printf 'rc=%d\n' "$dcanary_checked_rc"
+    for dcanary_checked_path in "${dcanary_checked_paths[@]}"; do
+        printf 'accepted=%s\n' "$dcanary_checked_path"
+    done
+}
+
+dcanary_composition_output="$(probe_checked_discovery_composition)"
+dcanary_composition_rc=''
+dcanary_composition_finding_total=0
+dcanary_composition_saw_dangling=false
+dcanary_composition_accepted_total=0
+dcanary_composition_saw_real=false
+dcanary_composition_saw_linked=false
+while IFS= read -r dcanary_composition_line; do
+    case "$dcanary_composition_line" in
+        'rc='*)
+            dcanary_composition_rc="${dcanary_composition_line#rc=}"
+            ;;
+        'accepted='*)
+            dcanary_composition_accepted_total=$((dcanary_composition_accepted_total + 1))
+            if [[ "${dcanary_composition_line#accepted=}" == "$dcanary_real_file" ]]; then
+                dcanary_composition_saw_real=true
+            elif [[ "${dcanary_composition_line#accepted=}" == "$dcanary_linked_file" ]]; then
+                dcanary_composition_saw_linked=true
+            fi
+            ;;
+        *'[DISCOVERY] '*)
+            dcanary_composition_finding_total=$((dcanary_composition_finding_total + 1))
+            if [[ "$dcanary_composition_line" == *"[DISCOVERY] ${DISCOVERY_CANARY_REL}/broken/dangling.md -- "* ]]; then
+                dcanary_composition_saw_dangling=true
+            fi
+            ;;
+    esac
+done <<< "$dcanary_composition_output"
+if [[ "$dcanary_composition_rc" != 1 || "$dcanary_composition_accepted_total" -ne 2 \
+   || "$dcanary_composition_saw_real" != true || "$dcanary_composition_saw_linked" != true \
+   || "$dcanary_composition_finding_total" -ne 1 || "$dcanary_composition_saw_dangling" != true ]]; then
+    dcanary_composition_flat="${dcanary_composition_output//$'\n'/ | }"
+    flag_discovery_canary "discover_checked_paths over ${DISCOVERY_CANARY_REL} under the 'files' gate produced [${dcanary_composition_flat}]; expected rc=1, exactly real/inner.md and link-dir/inner.md accepted, and exactly one finding naming broken/dangling.md -- the call-site composition no longer gates, reports, or returns its findings"
+fi
+
 if [[ "$dcanary_found" == false ]]; then
     echo '[PASS] DISCOVERY: checked discovery follows symlinked directories, gates dangling and wrong-type paths, and propagates find failures'
     CHECKS_PASSED=$((CHECKS_PASSED + 1))
@@ -634,20 +737,8 @@ echo '=== CHECK 1: Forbidden hedge ==='
 check1_found=false
 
 declare -a check1_md_files=()
-check1_discovery_rc=0
-discover_paths check1_md_files "$PLUGIN_ROOT" -- -name '*.md' || check1_discovery_rc=$?
-if [[ "$check1_discovery_rc" -ne 0 ]]; then
-    check1_found=true
-    flag_discovery_failure 'CHECK1' "$PLUGIN_ROOT" 'plugin Markdown files' "$check1_discovery_rc"
-fi
+discover_checked_paths 'CHECK1' check1_md_files files 'plugin Markdown files' "$PLUGIN_ROOT" -- -name '*.md' || check1_found=true
 for md_file in "${check1_md_files[@]}"; do
-    check1_gate_rc=0
-    discovery_gate_status "$md_file" files || check1_gate_rc=$?
-    if [[ "$check1_gate_rc" -ne 0 ]]; then
-        check1_found=true
-        flag_discovery_gate 'CHECK1' "$md_file" "$check1_gate_rc"
-        continue
-    fi
     # Candidate prefilter (#305): one grep per FILE on the BROADEST pattern.
     # Every finding-producing line must pass the ladder's \bambiguous\b gate
     # below, so non-matching lines can never add a finding; the
@@ -770,36 +861,12 @@ check3_found=false
 # Collect scan sources
 declare -a SCAN_FILES=()
 declare -a check3_agent_files=()
-check3_discovery_rc=0
-discover_paths check3_agent_files "$PLUGIN_ROOT/agents" -- -maxdepth 1 -name '*.md' || check3_discovery_rc=$?
-if [[ "$check3_discovery_rc" -ne 0 ]]; then
-    check3_found=true
-    flag_discovery_failure 'CHECK3' "$PLUGIN_ROOT/agents" 'agent Markdown files' "$check3_discovery_rc"
-fi
+discover_checked_paths 'CHECK3' check3_agent_files files 'agent Markdown files' "$PLUGIN_ROOT/agents" -- -maxdepth 1 -name '*.md' || check3_found=true
 declare -a check3_skill_files=()
-check3_discovery_rc=0
-discover_paths check3_skill_files "$PLUGIN_ROOT/skills" -- -name 'SKILL.md' || check3_discovery_rc=$?
-if [[ "$check3_discovery_rc" -ne 0 ]]; then
-    check3_found=true
-    flag_discovery_failure 'CHECK3' "$PLUGIN_ROOT/skills" 'skill SKILL.md files' "$check3_discovery_rc"
-fi
+discover_checked_paths 'CHECK3' check3_skill_files files 'skill SKILL.md files' "$PLUGIN_ROOT/skills" -- -name 'SKILL.md' || check3_found=true
 declare -a check3_governance_files=()
-check3_discovery_rc=0
-discover_paths check3_governance_files "$PLUGIN_ROOT/governance" -- -maxdepth 1 -name '*.md' || check3_discovery_rc=$?
-if [[ "$check3_discovery_rc" -ne 0 ]]; then
-    check3_found=true
-    flag_discovery_failure 'CHECK3' "$PLUGIN_ROOT/governance" 'governance Markdown files' "$check3_discovery_rc"
-fi
-for scan_candidate in "${check3_agent_files[@]}" "${check3_skill_files[@]}" "${check3_governance_files[@]}"; do
-    check3_gate_rc=0
-    discovery_gate_status "$scan_candidate" files || check3_gate_rc=$?
-    if [[ "$check3_gate_rc" -ne 0 ]]; then
-        check3_found=true
-        flag_discovery_gate 'CHECK3' "$scan_candidate" "$check3_gate_rc"
-        continue
-    fi
-    SCAN_FILES+=("$scan_candidate")
-done
+discover_checked_paths 'CHECK3' check3_governance_files files 'governance Markdown files' "$PLUGIN_ROOT/governance" -- -maxdepth 1 -name '*.md' || check3_found=true
+SCAN_FILES+=("${check3_agent_files[@]}" "${check3_skill_files[@]}" "${check3_governance_files[@]}")
 
 # Extract all hivemind:* references.
 # skill_refs: associative array mapping skill name -> space-separated source file paths
@@ -895,20 +962,8 @@ echo '=== CHECK 5: Unsupported frontmatter fields ==='
 
 check5_found=false
 declare -a check5_agent_files=()
-check5_discovery_rc=0
-discover_paths check5_agent_files "$PLUGIN_ROOT/agents" -- -maxdepth 1 -name '*.md' || check5_discovery_rc=$?
-if [[ "$check5_discovery_rc" -ne 0 ]]; then
-    check5_found=true
-    flag_discovery_failure 'CHECK5' "$PLUGIN_ROOT/agents" 'agent Markdown files' "$check5_discovery_rc"
-fi
+discover_checked_paths 'CHECK5' check5_agent_files files 'agent Markdown files' "$PLUGIN_ROOT/agents" -- -maxdepth 1 -name '*.md' || check5_found=true
 for agent_file in "${check5_agent_files[@]}"; do
-    check5_gate_rc=0
-    discovery_gate_status "$agent_file" files || check5_gate_rc=$?
-    if [[ "$check5_gate_rc" -ne 0 ]]; then
-        check5_found=true
-        flag_discovery_gate 'CHECK5' "$agent_file" "$check5_gate_rc"
-        continue
-    fi
     in_frontmatter=false
     frontmatter_started=false
     line_num=0
@@ -960,20 +1015,8 @@ check6_found=false
 # PLUGIN_ROOT is invariant across the scan; resolve it once (#305).
 normalized_plugin_root="$(realpath -m "$PLUGIN_ROOT")"
 declare -a check6_md_files=()
-check6_discovery_rc=0
-discover_paths check6_md_files "$PLUGIN_ROOT" -- -name '*.md' || check6_discovery_rc=$?
-if [[ "$check6_discovery_rc" -ne 0 ]]; then
-    check6_found=true
-    flag_discovery_failure 'CHECK6' "$PLUGIN_ROOT" 'plugin Markdown files' "$check6_discovery_rc"
-fi
+discover_checked_paths 'CHECK6' check6_md_files files 'plugin Markdown files' "$PLUGIN_ROOT" -- -name '*.md' || check6_found=true
 for md_file in "${check6_md_files[@]}"; do
-    check6_gate_rc=0
-    discovery_gate_status "$md_file" files || check6_gate_rc=$?
-    if [[ "$check6_gate_rc" -ne 0 ]]; then
-        check6_found=true
-        flag_discovery_gate 'CHECK6' "$md_file" "$check6_gate_rc"
-        continue
-    fi
     # Candidate prefilter (#305): the extraction below requires the literal
     # ${CLAUDE_PLUGIN_ROOT}/ prefix, so one fixed-string grep per FILE finds
     # every line that can yield a reference.
@@ -1029,20 +1072,8 @@ check7_found=false
 skill_file_count=0
 
 declare -a check7_skill_files=()
-check7_discovery_rc=0
-discover_paths check7_skill_files "$PLUGIN_ROOT/skills" -- -name 'SKILL.md' || check7_discovery_rc=$?
-if [[ "$check7_discovery_rc" -ne 0 ]]; then
-    check7_found=true
-    flag_discovery_failure 'CHECK7' "$PLUGIN_ROOT/skills" 'skill SKILL.md files' "$check7_discovery_rc"
-fi
+discover_checked_paths 'CHECK7' check7_skill_files files 'skill SKILL.md files' "$PLUGIN_ROOT/skills" -- -name 'SKILL.md' || check7_found=true
 for skill_file in "${check7_skill_files[@]}"; do
-    check7_gate_rc=0
-    discovery_gate_status "$skill_file" files || check7_gate_rc=$?
-    if [[ "$check7_gate_rc" -ne 0 ]]; then
-        check7_found=true
-        flag_discovery_gate 'CHECK7' "$skill_file" "$check7_gate_rc"
-        continue
-    fi
     skill_file_count=$((skill_file_count + 1))
 
     fm_content="$(get_frontmatter "$skill_file")"
@@ -1071,20 +1102,8 @@ echo '=== CHECK 8: No bare governance/agents/skills path refs ==='
 
 check8_found=false
 declare -a check8_md_files=()
-check8_discovery_rc=0
-discover_paths check8_md_files "$PLUGIN_ROOT" -- -name '*.md' || check8_discovery_rc=$?
-if [[ "$check8_discovery_rc" -ne 0 ]]; then
-    check8_found=true
-    flag_discovery_failure 'CHECK8' "$PLUGIN_ROOT" 'plugin Markdown files' "$check8_discovery_rc"
-fi
+discover_checked_paths 'CHECK8' check8_md_files files 'plugin Markdown files' "$PLUGIN_ROOT" -- -name '*.md' || check8_found=true
 for md_file in "${check8_md_files[@]}"; do
-    check8_gate_rc=0
-    discovery_gate_status "$md_file" files || check8_gate_rc=$?
-    if [[ "$check8_gate_rc" -ne 0 ]]; then
-        check8_found=true
-        flag_discovery_gate 'CHECK8' "$md_file" "$check8_gate_rc"
-        continue
-    fi
     # Candidate prefilter (#305): one grep per FILE for the bare-ref shape
     # WITHOUT the left-boundary group. Sound superset: every flagged ref is
     # built solely of characters inside the strip-token class below, and the
@@ -1207,20 +1226,8 @@ check9_found=false
 check9_script_count=0
 
 declare -a check9_engine_scripts=()
-check9_discovery_rc=0
-discover_paths check9_engine_scripts "$PLUGIN_ROOT/skills" -- -path '*/scripts/*.sh' || check9_discovery_rc=$?
-if [[ "$check9_discovery_rc" -ne 0 ]]; then
-    check9_found=true
-    flag_discovery_failure 'CHECK9' "$PLUGIN_ROOT/skills" 'skill engine scripts' "$check9_discovery_rc"
-fi
+discover_checked_paths 'CHECK9' check9_engine_scripts files 'skill engine scripts' "$PLUGIN_ROOT/skills" -- -path '*/scripts/*.sh' || check9_found=true
 for engine_script in "${check9_engine_scripts[@]}"; do
-    check9_gate_rc=0
-    discovery_gate_status "$engine_script" files || check9_gate_rc=$?
-    if [[ "$check9_gate_rc" -ne 0 ]]; then
-        check9_found=true
-        flag_discovery_gate 'CHECK9' "$engine_script" "$check9_gate_rc"
-        continue
-    fi
     # Only engine scripts that source the containment helper participate.
     if ! grep -qE '(^|[[:space:]])(\.|source)[[:space:]][^#]*containment\.sh' "$engine_script"; then
         continue
@@ -1314,20 +1321,8 @@ echo '=== CHECK 10: No literal NUL byte in plugin Markdown payload ==='
 check10_found=false
 check10_md_count=0
 declare -a check10_md_files=()
-check10_discovery_rc=0
-discover_paths check10_md_files "$PLUGIN_ROOT" -- -name '*.md' || check10_discovery_rc=$?
-if [[ "$check10_discovery_rc" -ne 0 ]]; then
-    check10_found=true
-    flag_discovery_failure 'CHECK10' "$PLUGIN_ROOT" 'plugin Markdown files' "$check10_discovery_rc"
-fi
+discover_checked_paths 'CHECK10' check10_md_files files 'plugin Markdown files' "$PLUGIN_ROOT" -- -name '*.md' || check10_found=true
 for md_file in "${check10_md_files[@]}"; do
-    check10_gate_rc=0
-    discovery_gate_status "$md_file" files || check10_gate_rc=$?
-    if [[ "$check10_gate_rc" -ne 0 ]]; then
-        check10_found=true
-        flag_discovery_gate 'CHECK10' "$md_file" "$check10_gate_rc"
-        continue
-    fi
     check10_md_count=$((check10_md_count + 1))
     if LC_ALL=C grep -qaP '\x00' "$md_file" 2>/dev/null; then
         check10_found=true
@@ -1376,20 +1371,8 @@ IFS='|' read -ra CHECK11_CANDIDATE_WORDS <<< "${BIOFORM_DENYLIST,,}|${CHECK11_KE
 
 check11_found=false
 declare -a check11_skill_files=()
-check11_discovery_rc=0
-discover_paths check11_skill_files "$PLUGIN_ROOT/skills" -- -name 'SKILL.md' || check11_discovery_rc=$?
-if [[ "$check11_discovery_rc" -ne 0 ]]; then
-    check11_found=true
-    flag_discovery_failure 'CHECK11' "$PLUGIN_ROOT/skills" 'skill SKILL.md files' "$check11_discovery_rc"
-fi
+discover_checked_paths 'CHECK11' check11_skill_files files 'skill SKILL.md files' "$PLUGIN_ROOT/skills" -- -name 'SKILL.md' || check11_found=true
 for skill_file in "${check11_skill_files[@]}"; do
-    check11_gate_rc=0
-    discovery_gate_status "$skill_file" files || check11_gate_rc=$?
-    if [[ "$check11_gate_rc" -ne 0 ]]; then
-        check11_found=true
-        flag_discovery_gate 'CHECK11' "$skill_file" "$check11_gate_rc"
-        continue
-    fi
     # One-pass awk state machine emits surviving BODY lines as "line_num<TAB>line",
     # excluding YAML frontmatter, fenced code blocks, and markdown table rows.
     while IFS=$'\t' read -r line_num textline; do
@@ -1467,20 +1450,8 @@ CHECK12_DENYLIST='tools/validate\.sh|bash -n|python3 -m json\.tool|test_[a-z0-9_
 
 check12_found=false
 declare -a check12_doc_files=()
-check12_discovery_rc=0
-discover_paths check12_doc_files "$PLUGIN_ROOT/governance" "$PLUGIN_ROOT/agents" -- -maxdepth 1 -name '*.md' || check12_discovery_rc=$?
-if [[ "$check12_discovery_rc" -ne 0 ]]; then
-    check12_found=true
-    flag_discovery_failure 'CHECK12' "$PLUGIN_ROOT" 'governance and agent Markdown files' "$check12_discovery_rc"
-fi
+discover_checked_paths 'CHECK12' check12_doc_files files 'governance and agent Markdown files' "$PLUGIN_ROOT/governance" "$PLUGIN_ROOT/agents" -- -maxdepth 1 -name '*.md' || check12_found=true
 for doc_file in "${check12_doc_files[@]}"; do
-    check12_gate_rc=0
-    discovery_gate_status "$doc_file" files || check12_gate_rc=$?
-    if [[ "$check12_gate_rc" -ne 0 ]]; then
-        check12_found=true
-        flag_discovery_gate 'CHECK12' "$doc_file" "$check12_gate_rc"
-        continue
-    fi
     # One-pass awk state machine emits surviving BODY lines as "line_num<TAB>line",
     # excluding YAML frontmatter, fenced code blocks, and >=4-space indented lines.
     while IFS=$'\t' read -r line_num textline; do
@@ -1581,20 +1552,8 @@ echo '=== CHECK 13: P18 fail-closed shell floor ==='
 
 check13_found=false
 declare -a check13_shell_scripts=()
-check13_discovery_rc=0
-discover_paths check13_shell_scripts "$PLUGIN_ROOT" -- -name '*.sh' || check13_discovery_rc=$?
-if [[ "$check13_discovery_rc" -ne 0 ]]; then
-    check13_found=true
-    flag_discovery_failure 'CHECK13' "$PLUGIN_ROOT" 'plugin shell scripts' "$check13_discovery_rc"
-fi
+discover_checked_paths 'CHECK13' check13_shell_scripts files 'plugin shell scripts' "$PLUGIN_ROOT" -- -name '*.sh' || check13_found=true
 for shell_script in "${check13_shell_scripts[@]}"; do
-    check13_gate_rc=0
-    discovery_gate_status "$shell_script" files || check13_gate_rc=$?
-    if [[ "$check13_gate_rc" -ne 0 ]]; then
-        check13_found=true
-        flag_discovery_gate 'CHECK13' "$shell_script" "$check13_gate_rc"
-        continue
-    fi
     has_errexit=false
     has_nounset=false
     has_pipefail=false
@@ -1938,21 +1897,8 @@ skill_sources_containment() {
         return 0
     fi
     local -a check14_engine_scripts=()
-    local check14_scripts_rc=0
-    discover_paths check14_engine_scripts "$scripts_dir" -- -maxdepth 1 -name '*.sh' || check14_scripts_rc=$?
-    if [[ "$check14_scripts_rc" -ne 0 ]]; then
-        check14_found=true
-        flag_discovery_failure 'CHECK14' "$scripts_dir" 'skill engine scripts' "$check14_scripts_rc"
-    fi
-    local engine_gate_rc
+    discover_checked_paths 'CHECK14' check14_engine_scripts files 'skill engine scripts' "$scripts_dir" -- -maxdepth 1 -name '*.sh' || check14_found=true
     for engine_script in "${check14_engine_scripts[@]}"; do
-        engine_gate_rc=0
-        discovery_gate_status "$engine_script" files || engine_gate_rc=$?
-        if [[ "$engine_gate_rc" -ne 0 ]]; then
-            check14_found=true
-            flag_discovery_gate 'CHECK14' "$engine_script" "$engine_gate_rc"
-            continue
-        fi
         if grep -qE '(^|[[:space:]])(\.|source)[[:space:]][^#]*containment\.sh' "$engine_script"; then
             SKILL_SOURCES_CONTAINMENT_RESULT="true"
             return 0
@@ -1964,20 +1910,8 @@ check14_found=false
 check14_navigator_count=0
 
 declare -a check14_skill_files=()
-check14_discovery_rc=0
-discover_paths check14_skill_files "$PLUGIN_ROOT/skills" -- -maxdepth 2 -name 'SKILL.md' || check14_discovery_rc=$?
-if [[ "$check14_discovery_rc" -ne 0 ]]; then
-    check14_found=true
-    flag_discovery_failure 'CHECK14' "$PLUGIN_ROOT/skills" 'skill SKILL.md files' "$check14_discovery_rc"
-fi
+discover_checked_paths 'CHECK14' check14_skill_files files 'skill SKILL.md files' "$PLUGIN_ROOT/skills" -- -maxdepth 2 -name 'SKILL.md' || check14_found=true
 for skill_file in "${check14_skill_files[@]}"; do
-    check14_gate_rc=0
-    discovery_gate_status "$skill_file" files || check14_gate_rc=$?
-    if [[ "$check14_gate_rc" -ne 0 ]]; then
-        check14_found=true
-        flag_discovery_gate 'CHECK14' "$skill_file" "$check14_gate_rc"
-        continue
-    fi
     if [[ "$(skill_declares_navigator_marker "$skill_file")" != "true" ]]; then
         continue
     fi
@@ -2284,12 +2218,11 @@ tracker_ref_tokens() {
     printf '%s' "${record#*$'\t'}"
 }
 
-# Status codes the read and discovery layers return for their own failures,
-# distinct from each other and from the 0/1/2 that awk and find exit with.
+# Status codes the read layer returns for its own failures, distinct from each
+# other and from the 0/1/2 that awk exits with. Discovery status is the shared
+# checked-discovery engine's (see the Checked discovery section).
 CHECK15_RC_NOT_REGULAR=10
 CHECK15_RC_UNREADABLE=11
-CHECK15_RC_TRUNCATED=12
-CHECK15_FIND_STATUS_TAG='__CHECK15_FIND_STATUS='
 
 # check15_awk_records FILE
 # Runs the classifier over FILE, ungated, and returns awk's own exit status.
@@ -2360,55 +2293,6 @@ scan_file_for_tracker_refs() {
     done <<< "$records"
 }
 
-# check15_discover_files ROOT FIND_ARGS...
-# Materialises the paths `find ROOT FIND_ARGS... -print0` emits into the global
-# array check15_discovered_files, and returns find's exit status, or
-# CHECK15_RC_TRUNCATED when the stream does not end in exactly one status
-# record. Paths found before a failure are still materialised so they are
-# scanned; the non-zero status is what keeps the arm from reading as clean.
-#
-# INVARIANT: a failing producer inside `< <(...)` is invisible to the reading
-# loop (see the materialisation invariant under Helpers), so the producer
-# appends its own status as a trailing NUL-delimited sentinel record. The
-# `|| find_status=$?` is load-bearing: errexit is inherited by the process
-# substitution, so a bare `find ...; printf ... "$?"` dies before the sentinel
-# is written whenever find fails.
-check15_discover_files() {
-    local search_root="$1" stream_record status_record=''
-    local sentinel_total=0 last_was_sentinel=false
-    shift
-    check15_discovered_files=()
-    while IFS= read -r -d '' stream_record; do
-        if [[ "$stream_record" == "$CHECK15_FIND_STATUS_TAG"* ]]; then
-            sentinel_total=$((sentinel_total + 1))
-            status_record="$stream_record"
-            last_was_sentinel=true
-        else
-            check15_discovered_files+=("$stream_record")
-            last_was_sentinel=false
-        fi
-    done < <(find_status=0; find "$search_root" "$@" -print0 || find_status=$?; printf '__CHECK15_FIND_STATUS=%d\0' "$find_status")
-    if [[ "$sentinel_total" -ne 1 || "$last_was_sentinel" != true ]]; then
-        return "$CHECK15_RC_TRUNCATED"
-    fi
-    return "${status_record#"$CHECK15_FIND_STATUS_TAG"}"
-}
-
-# check15_flag_discovery_failure ARM_ROOT ARM_LABEL STATUS
-# Records the finding for a discovery arm whose find failed or whose stream
-# was truncated: a partial file list is never a clean one.
-check15_flag_discovery_failure() {
-    local arm_root="$1" arm_label="$2" discovery_rc="$3" failure_reason
-    if [[ "$discovery_rc" -eq "$CHECK15_RC_TRUNCATED" ]]; then
-        failure_reason='its path stream ended without exactly one trailing find-status record (truncated)'
-    else
-        failure_reason="find exited ${discovery_rc}"
-    fi
-    check15_found=true
-    add_finding 'CHECK15' "$arm_root" 0 \
-        "Tracker-reference discovery of ${arm_label} failed: ${failure_reason}, so files in that arm may never have been scanned -- fix the tree's readability; a failed discovery is NOT clean"
-}
-
 # INVARIANT: discovery selects by NAME only, never by type: every name-matching
 # path reaches the read gate, where a path that is missing or not a regular file becomes a
 # finding instead of being dropped silently by find. The traversal canary pins
@@ -2416,23 +2300,24 @@ check15_flag_discovery_failure() {
 CHECK15_MD_FIND_ARGS=(-name '*.md')
 CHECK15_JSON_FIND_ARGS=(-maxdepth 1 -name '*.json')
 
-check15_discovery_rc=0
-check15_discover_files "$PLUGIN_ROOT" "${CHECK15_MD_FIND_ARGS[@]}" || check15_discovery_rc=$?
-if [[ "$check15_discovery_rc" -ne 0 ]]; then
-    check15_flag_discovery_failure "$PLUGIN_ROOT" 'plugin/**/*.md' "$check15_discovery_rc"
-fi
-check15_md_count="${#check15_discovered_files[@]}"
-for prose_file in "${check15_discovered_files[@]}"; do
+# INVARIANT: both arms discover under the `raw` gate. check15_read_records is
+# CHECK 15's type gate; a `files` gate ahead of it would reject a directory or
+# dangling link before the read gate, leaving the traversal canary's read-gate
+# probes guarding a path production never reaches. The traversal canary pins
+# this value and runs its discovery probes under it.
+CHECK15_DISCOVERY_GATE='raw'
+
+declare -a check15_md_files=()
+discover_checked_paths 'CHECK15' check15_md_files "$CHECK15_DISCOVERY_GATE" 'plugin/**/*.md' "$PLUGIN_ROOT" -- "${CHECK15_MD_FIND_ARGS[@]}" || check15_found=true
+check15_md_count="${#check15_md_files[@]}"
+for prose_file in "${check15_md_files[@]}"; do
     scan_file_for_tracker_refs "$prose_file"
 done
 
-check15_discovery_rc=0
-check15_discover_files "$PLUGIN_ROOT/workflows" "${CHECK15_JSON_FIND_ARGS[@]}" || check15_discovery_rc=$?
-if [[ "$check15_discovery_rc" -ne 0 ]]; then
-    check15_flag_discovery_failure "$PLUGIN_ROOT/workflows" 'plugin/workflows/*.json' "$check15_discovery_rc"
-fi
-check15_json_count="${#check15_discovered_files[@]}"
-for prose_file in "${check15_discovered_files[@]}"; do
+declare -a check15_json_files=()
+discover_checked_paths 'CHECK15' check15_json_files "$CHECK15_DISCOVERY_GATE" 'plugin/workflows/*.json' "$PLUGIN_ROOT/workflows" -- "${CHECK15_JSON_FIND_ARGS[@]}" || check15_found=true
+check15_json_count="${#check15_json_files[@]}"
+for prose_file in "${check15_json_files[@]}"; do
     scan_file_for_tracker_refs "$prose_file"
 done
 
@@ -2631,12 +2516,23 @@ check15_expect_scan 'tests/policy/fixtures/tracker-ref-allowlist-canary.md' \
 # the failure arms cannot all pass by the layer failing unconditionally. Each
 # probe runs under `if !` so set -euo pipefail cannot abort the run; stderr is
 # discarded only here, because these failures are the expected outcome.
-# Discovery coverage is split across two witnesses: the args pin below witnesses
-# the production CALL SITES (their arrays select by name only), and the symlink
-# probe witnesses the discovery FUNCTION (a name-matching symlink is
-# materialised, and the same probe with `-type f` appended drops it -- the
-# negative control). The symlink fixture is committed, so no probe creates a
-# filesystem object at run time.
+# Discovery coverage is split across two witnesses: the args and gate pins
+# below witness the production CALL SITES (their arrays select by name only,
+# under the `raw` gate), and the discovery probes witness the production
+# COMPOSITION -- discover_checked_paths under CHECK15_DISCOVERY_GATE, over the
+# shared discover_paths engine:
+#   * a nonexistent root makes it return non-zero and emit a CHECK15
+#     find-failure finding, run inside a command substitution so the finding is
+#     captured as text and dies with the subshell;
+#   * a name-matching committed symlink is materialised; a raw `find -P` with
+#     `-type f` drops it -- the negative control proving that fixture is still
+#     a symlink rather than a plain file;
+#   * over the DISCOVERY canary root, CHECK15_MD_FIND_ARGS materialise the file
+#     under a symlinked directory (the -L policy) and a dangling link (name-only
+#     selection plus the raw gate hand it to the read gate); the same probe with
+#     `-type f` appended drops only the dangling link -- the negative control.
+# Every fixture is committed, so no probe creates a filesystem object at run
+# time.
 # Residual: the reporting wrapper's finding emission on a read failure has no
 # canary -- asserting it would emit a real finding -- and it is a thin
 # translation of the status-bearing layer these probes do witness.
@@ -2668,9 +2564,26 @@ check15_expect_find_args() {
 
 check15_expect_find_args 'CHECK15_MD_FIND_ARGS' '-name *.md' "${CHECK15_MD_FIND_ARGS[@]}"
 check15_expect_find_args 'CHECK15_JSON_FIND_ARGS' '-maxdepth 1 -name *.json' "${CHECK15_JSON_FIND_ARGS[@]}"
+if [[ "$CHECK15_DISCOVERY_GATE" != 'raw' ]]; then
+    check15_flag_traversal_canary "CHECK15_DISCOVERY_GATE is '${CHECK15_DISCOVERY_GATE}' but must be exactly 'raw' -- check15_read_records is the type gate, so a discovery gate ahead of it rejects a directory or dangling link before the read gate ever sees it"
+fi
+
+# probe_check15_missing_root_discovery
+# Prints the findings the production discovery composition emits over the
+# nonexistent canary root, then `rc=STATUS`. Called only inside a command
+# substitution, so the finding stays in the subshell.
+probe_check15_missing_root_discovery() {
+    local -a check15_canary_missing_paths=()
+    local check15_canary_missing_rc=0
+    discover_checked_paths 'CHECK15' check15_canary_missing_paths "$CHECK15_DISCOVERY_GATE" 'the traversal canary nonexistent root' "$check15_canary_missing_path" -- "${CHECK15_MD_FIND_ARGS[@]}" 2>/dev/null || check15_canary_missing_rc=$?
+    printf 'rc=%d\n' "$check15_canary_missing_rc"
+}
 
-if check15_discover_files "$check15_canary_missing_path" -type f 2>/dev/null; then
-    check15_flag_traversal_canary "check15_discover_files returned 0 for the nonexistent root ${check15_canary_missing_path}, so a failing find is read as an empty tree"
+check15_canary_missing_output="$(probe_check15_missing_root_discovery)"
+check15_canary_missing_rel="${check15_canary_missing_path#"$REPO_ROOT"/}"
+if [[ "$check15_canary_missing_output" != *'rc=1' \
+   || "$check15_canary_missing_output" != *"[CHECK15] ${check15_canary_missing_rel} -- Discovery of the traversal canary nonexistent root failed: find exited "* ]]; then
+    check15_flag_traversal_canary "discover_checked_paths over the nonexistent root ${check15_canary_missing_path} produced [${check15_canary_missing_output//$'\n'/ | }], expected rc=1 and a CHECK15 finding that find exited non-zero, so a failing find is read as an empty tree"
 fi
 if check15_read_records "$check15_canary_missing_path" >/dev/null 2>&1; then
     check15_flag_traversal_canary "check15_read_records returned 0 for the nonexistent path ${check15_canary_missing_path}"
@@ -2686,16 +2599,47 @@ if ! check15_canary_records="$(check15_read_records "$check15_canary_fixture_pat
 elif [[ -z "$check15_canary_records" ]]; then
     check15_flag_traversal_canary "positive control: check15_read_records returned no records for the committed fixture ${check15_canary_fixture_path}, which carries known references"
 fi
+declare -a check15_canary_paths=()
 check15_canary_discovery_rc=0
-check15_discover_files "$REPO_ROOT/tests/policy/fixtures" -maxdepth 1 -name "$check15_canary_symlink_name" || check15_canary_discovery_rc=$?
-if [[ "$check15_canary_discovery_rc" -ne 0 || "${#check15_discovered_files[@]}" -ne 1 ]]; then
-    check15_flag_traversal_canary "check15_discover_files materialised ${#check15_discovered_files[@]} path(s) with status ${check15_canary_discovery_rc} for the committed symlink ${check15_canary_symlink_path}, expected exactly 1 with status 0, so discovery drops a name-matching path before the read gate"
+discover_checked_paths 'CHECK15' check15_canary_paths "$CHECK15_DISCOVERY_GATE" 'the committed symlink canary' "$REPO_ROOT/tests/policy/fixtures" -- -maxdepth 1 -name "$check15_canary_symlink_name" || check15_canary_discovery_rc=$?
+if [[ "$check15_canary_discovery_rc" -ne 0 || "${#check15_canary_paths[@]}" -ne 1 ]]; then
+    check15_flag_traversal_canary "discover_checked_paths materialised ${#check15_canary_paths[@]} path(s) with status ${check15_canary_discovery_rc} for the committed symlink ${check15_canary_symlink_path}, expected exactly 1 with status 0, so discovery drops a name-matching path before the read gate"
 fi
-check15_canary_discovery_rc=0
-check15_discover_files "$REPO_ROOT/tests/policy/fixtures" -maxdepth 1 -name "$check15_canary_symlink_name" -type f || check15_canary_discovery_rc=$?
-if [[ "$check15_canary_discovery_rc" -ne 0 || "${#check15_discovered_files[@]}" -ne 0 ]]; then
-    check15_flag_traversal_canary "negative control: check15_discover_files with -type f materialised ${#check15_discovered_files[@]} path(s) with status ${check15_canary_discovery_rc} for the committed symlink ${check15_canary_symlink_path}, expected 0 with status 0, so the symlink probe above no longer distinguishes name-only from type-filtered discovery"
+# INTENTIONAL NON-HELPER FIND: run with an explicit -P as the negative control
+# for the committed-symlink probe above (under -L, `-type f` matches a symlink
+# to a regular file, so no helper call can drop it); it is not a discovery call
+# site and must never be migrated to discover_paths.
+check15_canary_raw_rc=0
+check15_canary_raw_listing="$(find -P "$REPO_ROOT/tests/policy/fixtures" -maxdepth 1 -name "$check15_canary_symlink_name" -type f -print)" || check15_canary_raw_rc=$?
+if [[ "$check15_canary_raw_rc" -ne 0 || -n "$check15_canary_raw_listing" ]]; then
+    check15_flag_traversal_canary "negative control: find -P with -type f listed [${check15_canary_raw_listing//$'\n'/ | }] with status ${check15_canary_raw_rc} for the committed symlink ${check15_canary_symlink_path}, expected nothing with status 0, so that fixture is no longer a symlink and the probe above no longer exercises a symlinked runtime-prose file"
 fi
+
+# expect_check15_canary_tree_discovery LABEL EXPECTED_TOTAL EXPECT_DANGLING FIND_ARGS...
+# Asserts the production composition over the DISCOVERY canary root returns 0
+# and materialises exactly EXPECTED_TOTAL paths, always including the file
+# under the symlinked directory, and the dangling link iff EXPECT_DANGLING.
+expect_check15_canary_tree_discovery() {
+    local probe_label="$1" expected_total="$2" expect_dangling="$3"
+    shift 3
+    local -a check15_tree_paths=()
+    local check15_tree_rc=0 check15_tree_path saw_linked=false saw_dangling=false
+    discover_checked_paths 'CHECK15' check15_tree_paths "$CHECK15_DISCOVERY_GATE" 'the DISCOVERY canary tree' "$dcanary_root" -- "$@" || check15_tree_rc=$?
+    for check15_tree_path in "${check15_tree_paths[@]}"; do
+        if [[ "$check15_tree_path" == "$dcanary_linked_file" ]]; then
+            saw_linked=true
+        elif [[ "$check15_tree_path" == "$dcanary_dangling_file" ]]; then
+            saw_dangling=true
+        fi
+    done
+    if [[ "$check15_tree_rc" -ne 0 || "${#check15_tree_paths[@]}" -ne "$expected_total" \
+       || "$saw_linked" != true || "$saw_dangling" != "$expect_dangling" ]]; then
+        check15_flag_traversal_canary "${probe_label}: discover_checked_paths over ${DISCOVERY_CANARY_REL} with '$*' returned ${check15_tree_rc} and materialised ${#check15_tree_paths[@]} path(s) [${check15_tree_paths[*]}], expected status 0 and exactly ${expected_total} including tree/link-dir/inner.md, with broken/dangling.md present=${expect_dangling} -- CHECK 15 discovery no longer follows a symlinked directory, or no longer hands a dangling link to the read gate"
+    fi
+}
+
+expect_check15_canary_tree_discovery 'symlinked-directory and dangling-link probe' 3 true "${CHECK15_MD_FIND_ARGS[@]}"
+expect_check15_canary_tree_discovery 'negative control' 2 false "${CHECK15_MD_FIND_ARGS[@]}" -type f
 check15_canary_symlink_rc=0
 check15_canary_symlink_records="$(check15_read_records "$check15_canary_symlink_path")" || check15_canary_symlink_rc=$?
 if [[ "$check15_canary_symlink_rc" -ne 0 || "$check15_canary_symlink_records" != $'10\t#77' ]]; then

From 0b736f908380f5a71be55d4b82c803e860445f0b Mon Sep 17 00:00:00 2001
From: Bren Pike <brenpike@gmail.com>
Date: Fri, 25 Sep 2026 16:07:43 -0600
Subject: [PATCH 05/10] fix(policy): route SAFETY, COMPAT, workflow fixture
 discovery via helper

---
 tools/policy_check.sh | 77 ++++++++++++++++++++++++++++---------------
 1 file changed, 50 insertions(+), 27 deletions(-)

diff --git a/tools/policy_check.sh b/tools/policy_check.sh
index c522122a..70d30470 100644
--- a/tools/policy_check.sh
+++ b/tools/policy_check.sh
@@ -2662,14 +2662,17 @@ echo '=== SAFETY: Regression fixture tests ==='
 
 SAFETY_DIR="$REPO_ROOT/tests/policy"
 declare -a SAFETY_FIXTURES=()
+SAFETY_DISCOVERY_FAILED=false
 if [[ -d "$SAFETY_DIR" ]]; then
-    while IFS= read -r -d '' f; do
-        SAFETY_FIXTURES+=("$f")
-    done < <(find "$SAFETY_DIR" -maxdepth 1 -name 'safety-*.json' -type f -print0)
+    discover_checked_paths 'SAFETY' SAFETY_FIXTURES files 'safety-*.json fixture files' "$SAFETY_DIR" -- -maxdepth 1 -name 'safety-*.json' || SAFETY_DISCOVERY_FAILED=true
 fi
 
 SAFETY_PASSED=0
 SAFETY_FAILED=0
+if [[ "$SAFETY_DISCOVERY_FAILED" == true ]]; then
+    echo '[FAIL] SAFETY: safety-*.json fixture discovery'
+    SAFETY_FAILED=$((SAFETY_FAILED + 1))
+fi
 
 test_set_check() {
     local rule_name="$1"
@@ -2981,10 +2984,10 @@ for fixture_file in "${SAFETY_FIXTURES[@]}"; do
     fi
 done
 
-if [[ ${#SAFETY_FIXTURES[@]} -eq 0 ]]; then
+if [[ ${#SAFETY_FIXTURES[@]} -eq 0 && "$SAFETY_FAILED" -eq 0 ]]; then
     echo '[SKIP] No safety fixture files found'
 else
-    echo "Safety fixtures: $SAFETY_PASSED passed, $SAFETY_FAILED failed out of ${#SAFETY_FIXTURES[@]}"
+    echo "Safety fixtures: $SAFETY_PASSED passed, $SAFETY_FAILED failed out of $((SAFETY_PASSED + SAFETY_FAILED))"
     CHECKS_PASSED=$((CHECKS_PASSED + SAFETY_PASSED))
     CHECKS_FAILED=$((CHECKS_FAILED + SAFETY_FAILED))
 fi
@@ -3220,14 +3223,17 @@ echo '=== COMPAT: Plugin compatibility fixture tests ==='
 
 COMPAT_DIR="$REPO_ROOT/tests/plugin"
 declare -a COMPAT_FIXTURES=()
+COMPAT_DISCOVERY_FAILED=false
 if [[ -d "$COMPAT_DIR" ]]; then
-    while IFS= read -r -d '' f; do
-        COMPAT_FIXTURES+=("$f")
-    done < <(find "$COMPAT_DIR" -maxdepth 1 -name '*.json' -type f -print0)
+    discover_checked_paths 'COMPAT' COMPAT_FIXTURES files 'compatibility fixture files' "$COMPAT_DIR" -- -maxdepth 1 -name '*.json' || COMPAT_DISCOVERY_FAILED=true
 fi
 
 COMPAT_PASSED=0
 COMPAT_FAILED=0
+if [[ "$COMPAT_DISCOVERY_FAILED" == true ]]; then
+    echo '[FAIL] COMPAT: compatibility fixture discovery'
+    COMPAT_FAILED=$((COMPAT_FAILED + 1))
+fi
 
 for fixture_file in "${COMPAT_FIXTURES[@]}"; do
     fixture_raw="$(<"$fixture_file")"
@@ -3355,13 +3361,9 @@ for fixture_file in "${COMPAT_FIXTURES[@]}"; do
                 if [[ "$glob_pattern" == *"/"* ]]; then
                     # Glob with subdirectory (e.g. */SKILL.md) — recurse and filter
                     local_filter="${glob_pattern##*/}"
-                    while IFS= read -r -d '' tf; do
-                        target_files+=("$tf")
-                    done < <(find "$target_dir" -name "$local_filter" -type f -print0)
+                    discover_checked_paths 'COMPAT' target_files files "[$check_desc] files named '$local_filter' under $target_dir_rel" "$target_dir" -- -name "$local_filter" || fixture_passed=false
                 else
-                    while IFS= read -r -d '' tf; do
-                        target_files+=("$tf")
-                    done < <(find "$target_dir" -maxdepth 1 -name "$glob_pattern" -type f -print0)
+                    discover_checked_paths 'COMPAT' target_files files "[$check_desc] files matching '$glob_pattern' in $target_dir_rel" "$target_dir" -- -maxdepth 1 -name "$glob_pattern" || fixture_passed=false
                 fi
 
                 if [[ -n "$exclude_pattern" ]]; then
@@ -3407,7 +3409,9 @@ for fixture_file in "${COMPAT_FIXTURES[@]}"; do
                 add_finding 'COMPAT' "$target_dir_rel" 0 \
                     "[$check_desc] Directory missing: $target_dir_rel"
             else
-                while IFS= read -r -d '' target_file; do
+                declare -a field_absent_files=()
+                discover_checked_paths 'COMPAT' field_absent_files files "[$check_desc] Markdown files in $target_dir_rel" "$target_dir" -- -maxdepth 1 -name '*.md' || fixture_passed=false
+                for target_file in "${field_absent_files[@]}"; do
                     fm_content="$(get_frontmatter "$target_file")"
                     absent_count="$(echo "$fixture_raw" | jq '.absent | length')"
                     ai=0
@@ -3422,7 +3426,7 @@ for fixture_file in "${COMPAT_FIXTURES[@]}"; do
                         fi
                         ai=$((ai + 1))
                     done
-                done < <(find "$target_dir" -maxdepth 1 -name '*.md' -type f -print0)
+                done
             fi
             ;;
 
@@ -3443,7 +3447,14 @@ for fixture_file in "${COMPAT_FIXTURES[@]}"; do
                     "[$check_desc] Reference file missing: $ref_file_rel"
             else
                 ref_content="$(<"$ref_file_path")"
-                while IFS= read -r -d '' subdir; do
+                # INVARIANT: under DISCOVERY_FIND_BASE (-L) `-type d` is true for
+                # a directory AND a symlink to one, and `-type l` is true only for
+                # a symlink find cannot follow (dangling), so this predicate hands
+                # every subdirectory plus every dangling entry to the `dirs` gate,
+                # which rejects the dangling ones loudly; plain files stay out.
+                declare -a named_subdirs=()
+                discover_checked_paths 'COMPAT' named_subdirs dirs "[$check_desc] subdirectories of $target_dir_rel" "$target_dir" -- -mindepth 1 -maxdepth 1 '(' -type d -o -type l ')' || fixture_passed=false
+                for subdir in "${named_subdirs[@]}"; do
                     dir_name="$(basename "$subdir")"
                     if [[ -n "$exclude_pattern" && "$dir_name" == "$exclude_pattern" ]]; then
                         continue
@@ -3462,7 +3473,7 @@ for fixture_file in "${COMPAT_FIXTURES[@]}"; do
                         add_finding 'COMPAT' "$ref_file_rel" 0 \
                             "[$check_desc] Directory name not found in $ref_file_rel: $dir_name"
                     fi
-                done < <(find "$target_dir" -mindepth 1 -maxdepth 1 -type d -print0)
+                done
             fi
             ;;
 
@@ -3482,7 +3493,9 @@ for fixture_file in "${COMPAT_FIXTURES[@]}"; do
                     "[$check_desc] Reference file missing: $ref_file_rel"
             else
                 ref_content="$(<"$ref_file_path")"
-                while IFS= read -r -d '' file_in_dir; do
+                declare -a named_md_files=()
+                discover_checked_paths 'COMPAT' named_md_files files "[$check_desc] Markdown files in $target_dir_rel" "$target_dir" -- -maxdepth 1 -name '*.md' || fixture_passed=false
+                for file_in_dir in "${named_md_files[@]}"; do
                     base_name="$(basename "$file_in_dir" .md)"
                     # Builtin fixed-string test — same EPIPE/pipefail false-negative class as the
                     # dir-names-in-file arm above (see its comment).
@@ -3491,7 +3504,7 @@ for fixture_file in "${COMPAT_FIXTURES[@]}"; do
                         add_finding 'COMPAT' "$ref_file_rel" 0 \
                             "[$check_desc] Filename not found in $ref_file_rel: $base_name"
                     fi
-                done < <(find "$target_dir" -maxdepth 1 -name '*.md' -type f -print0)
+                done
             fi
             ;;
 
@@ -3534,7 +3547,14 @@ for fixture_file in "${COMPAT_FIXTURES[@]}"; do
                 add_finding 'COMPAT' "$target_dir_rel" 0 \
                     "[$check_desc] Directory missing: $target_dir_rel"
             else
-                while IFS= read -r -d '' scan_file; do
+                # INVARIANT: under DISCOVERY_FIND_BASE (-L) `-type d` is true for
+                # a directory AND a symlink to one, so `! -type d` keeps every
+                # directory out while regular files, symlinks to files, dangling
+                # symlinks, and special files all reach the `files` gate, which
+                # rejects all but readable regular files loudly.
+                declare -a pattern_scan_files=()
+                discover_checked_paths 'COMPAT' pattern_scan_files files "[$check_desc] files under $target_dir_rel" "$target_dir" -- '!' -type d || fixture_passed=false
+                for scan_file in "${pattern_scan_files[@]}"; do
                     scan_content="$(<"$scan_file")"
                     if [[ "$scan_content" == *"$search_pattern"* ]]; then
                         fixture_passed=false
@@ -3543,7 +3563,7 @@ for fixture_file in "${COMPAT_FIXTURES[@]}"; do
                         add_finding 'COMPAT' "$rel_file" 0 \
                             "[$check_desc] Forbidden pattern found: $search_pattern"
                     fi
-                done < <(find "$target_dir" -type f -print0)
+                done
             fi
             ;;
 
@@ -3563,10 +3583,10 @@ for fixture_file in "${COMPAT_FIXTURES[@]}"; do
     fi
 done
 
-if [[ ${#COMPAT_FIXTURES[@]} -eq 0 ]]; then
+if [[ ${#COMPAT_FIXTURES[@]} -eq 0 && "$COMPAT_FAILED" -eq 0 ]]; then
     echo '[SKIP] No compatibility fixture files found'
 else
-    echo "Compatibility fixtures: $COMPAT_PASSED passed, $COMPAT_FAILED failed out of ${#COMPAT_FIXTURES[@]}"
+    echo "Compatibility fixtures: $COMPAT_PASSED passed, $COMPAT_FAILED failed out of $((COMPAT_PASSED + COMPAT_FAILED))"
     CHECKS_PASSED=$((CHECKS_PASSED + COMPAT_PASSED))
     CHECKS_FAILED=$((CHECKS_FAILED + COMPAT_FAILED))
 fi
@@ -3581,14 +3601,17 @@ echo '=== WORKFLOW-FIXTURES: Golden-path workflow tests ==='
 test_workflow_fixtures() {
     local fixtures_dir="$REPO_ROOT/tests/workflows"
     declare -a fixtures=()
+    local wf_discovery_failed=false
     if [[ -d "$fixtures_dir" ]]; then
-        while IFS= read -r -d '' f; do
-            fixtures+=("$f")
-        done < <(find "$fixtures_dir" -maxdepth 1 -name 'golden-*.json' -type f -print0)
+        discover_checked_paths 'WORKFLOW-FIXTURES' fixtures files 'golden-*.json workflow fixture files' "$fixtures_dir" -- -maxdepth 1 -name 'golden-*.json' || wf_discovery_failed=true
     fi
 
     WF_PASSED=0
     WF_FAILED=0
+    if [[ "$wf_discovery_failed" == true ]]; then
+        echo 'FAIL [WORKFLOW-FIXTURES] golden-*.json fixture discovery'
+        WF_FAILED=$((WF_FAILED + 1))
+    fi
 
     if [[ ${#fixtures[@]} -eq 0 ]]; then
         echo "FAIL [WORKFLOW-FIXTURES] No golden-*.json fixtures found in tests/workflows/"

From 2aa9f13509216dfbf34e3fb07ca51870036d87f0 Mon Sep 17 00:00:00 2001
From: Bren Pike <brenpike@gmail.com>
Date: Fri, 25 Sep 2026 16:20:26 -0600
Subject: [PATCH 06/10] test(policy): pin discovery policy; correct stale -L
 residual prose

---
 docs/adr/0031-checked-discovery-policy.md  |  8 ++--
 tests/policy/README.md                     |  9 +++--
 tests/policy/safety-discovery-policy.json  | 21 ++++++++++
 tests/policy/safety-tracker-ref-guard.json |  2 +-
 tools/policy_check.sh                      | 47 +++++++++++++---------
 5 files changed, 61 insertions(+), 26 deletions(-)
 create mode 100644 tests/policy/safety-discovery-policy.json

diff --git a/docs/adr/0031-checked-discovery-policy.md b/docs/adr/0031-checked-discovery-policy.md
index 0f09dba3..63f1aaa6 100644
--- a/docs/adr/0031-checked-discovery-policy.md
+++ b/docs/adr/0031-checked-discovery-policy.md
@@ -12,13 +12,13 @@ Issue brenpike/hivemind#377 generalized that residual: the input-narrowing patte
 
 ## Decision
 
-`tools/policy_check.sh` adopts one discovery policy for the whole script: **follow symlinks**. Every discovery site uses `find -L` (or the equivalent checked-discovery helper) instead of default `-P`. Anything a followed traversal cannot resolve — a dangling symlink, a symlink loop — surfaces as a finding. It is never a silent skip and never a suppressed `find` exit status.
+`tools/policy_check.sh` adopts one discovery policy for the whole script: **follow symlinks**. Every discovery site goes through the shared checked-discovery engine, whose one `find` invocation runs with `-L` (the `DISCOVERY_FIND_BASE` array) instead of the default `-P`. Anything a followed traversal cannot resolve — a dangling symlink, a symlink loop — surfaces as a finding. It is never a silent skip and never a suppressed `find` exit status.
 
-The policy is implemented once, as a shared checked-discovery helper generalized from CHECK 15's sentinel-status helper, and every discovery call site is routed through it rather than reimplementing `find` invocations locally. The helper is status-bearing: callers can distinguish "found N paths" from "discovery itself failed," and a status-bearing gate classifies each discovered path (files, directories, or raw/unfiltered) so call sites keep the granularity they had before, without reintroducing a second traversal mechanism to get it.
+The policy is implemented once, generalized from CHECK 15's sentinel-status helper, and every discovery call site is routed through it rather than reimplementing `find` invocations locally. The engine, `discover_paths`, is status-bearing: its NUL-delimited path stream ends in a find-status sentinel record, so callers can distinguish "found N paths" from "discovery itself failed," including a truncated stream. A status-bearing classifier, `discovery_gate_status`, gates each discovered path under one of three gates — `files` (a readable regular file), `dirs` (a directory), or `raw` (no gating; the caller does its own read gating, which is how CHECK 15 hands a dangling link or a directory to its own read gate) — so call sites keep the granularity they had before, without reintroducing a second traversal mechanism to get it. Call sites use the wrapper `discover_checked_paths`, which composes the engine and the classifier and reports through two thin reporters, `flag_discovery_failure` (discovery itself failed) and `flag_discovery_gate` (a path was rejected by its gate), both emitting through the script's shared finding machinery.
 
-This is a single discovery engine for the script. No check gets a second, separate way to walk the filesystem.
+This is a single discovery engine for the script. No check gets a second, separate way to walk the filesystem. The only other `find` invocations in the script are two comment-marked `INTENTIONAL NON-HELPER FIND` negative controls — one in the `DISCOVERY` canary, one in CHECK 15's traversal canary — each run with an explicit `-P` as the negative control for a canary probe; neither is a discovery call site.
 
-The policy is witnessed by a committed `DISCOVERY` canary: a committed symlinked-directory fixture (proving a symlinked directory is now descended and its contents reach the read gate) and a committed dangling-symlink fixture (proving an unresolvable target surfaces as a finding rather than vanishing), plus a `-P` negative control (proving the canary fixtures would NOT be caught under the old default, so the canary is actually exercising the new policy and not passing by accident).
+The policy is witnessed by a `DISCOVERY` canary over committed fixtures under `tests/policy/fixtures/discovery-canary/`: a real directory (`tree/real`, holding `inner.md`), a symlinked directory pointing at it (`tree/link-dir`), and a dangling symlink (`broken/dangling.md`). It asserts that `DISCOVERY_FIND_BASE` is exactly the single element `-L`; that the engine descends the symlinked directory, with a raw `-P` negative control proving the fixtures would NOT be caught under the old default, so the canary is actually exercising the new policy and not passing by accident; that the gates classify in both directions, against a positive control; that a nonexistent root propagates `find`'s own non-zero status; and that the wrapper, over the whole fixture root under the `files` gate, keeps exactly the two regular files and emits exactly one finding, naming the dangling link, so an unresolvable target surfaces as a finding rather than vanishing. A precondition fails the canary loudly when the fixture symlinks are not symlinks in the checkout.
 
 ## Alternatives rejected
 
diff --git a/tests/policy/README.md b/tests/policy/README.md
index b80eae75..8061dd48 100644
--- a/tests/policy/README.md
+++ b/tests/policy/README.md
@@ -6,9 +6,12 @@ You are reading this because you are about to add or edit a fixture. This file i
 authoring contract: every rule below states the invariant it enforces first, then the
 mechanism that enforces it. Read the whole thing before pinning anything.
 
-This README is invisible to the fixture loader: discovery is
-`find tests/policy -maxdepth 1 -name 'safety-*.json'` (the `SAFETY_FIXTURES` discovery block in `tools/policy_check.sh`),
-so only `safety-*.json` files are ever evaluated.
+This README is invisible to the fixture loader: the SAFETY suite discovers its
+fixtures through the script's shared checked discovery (`discover_checked_paths`
+selecting `-maxdepth 1 -name 'safety-*.json'` under `tests/policy`, in the
+`SAFETY_FIXTURES` discovery block of `tools/policy_check.sh`), so only
+`safety-*.json` files are ever evaluated, and a name-matching path that is not a
+readable regular file is a SAFETY finding rather than a silently skipped fixture.
 
 ## 1. Honest capability statement
 
diff --git a/tests/policy/safety-discovery-policy.json b/tests/policy/safety-discovery-policy.json
new file mode 100644
index 00000000..7a88165d
--- /dev/null
+++ b/tests/policy/safety-discovery-policy.json
@@ -0,0 +1,21 @@
+{
+  "rule": "discovery-policy-checked-engine-present",
+  "description": "P3 consumer-assertion: the checked-discovery engine in tools/policy_check.sh is the single place the script's discovery policy lives -- every discovery find follows symlinks with `-L`, and anything a followed traversal cannot resolve is a finding, never a silent skip. Every scanning check discovers through it, so weakening it narrows every check's input set at once while each check still reports green. This fixture pins nine literals, each a single occurrence in the file, so deleting or rewriting any one of them is loud: `DISCOVERY_FIND_BASE=(-L)` (the policy itself -- without `-L`, find's default `-P` never descends a symlinked directory); the engine's find invocation `find \"${DISCOVERY_FIND_BASE[@]}\" \"${discovery_roots[@]}\" \"$@\" -print0` (the base array still reaches the one find the engine runs, so the `-L` assignment cannot stay in place while going unused); `discover_checked_paths() {` (the shared wrapper every call site uses is still defined under that name; deleting or renaming it also breaks every call site at run time, SAFETY's own fixture discovery included, so the run then fails through discovery findings before this fixture is evaluated -- this literal therefore turns red on its own only when the wrapper is re-declared in another form (such as `function discover_checked_paths {`), and a wrapper hollowed out under the same name is caught by the two call literals below, not by this one); inside it, `discovery_gate_status \"$checked_discovery_path\" \"$checked_discovery_gate\"` and `flag_discovery_gate \"$checked_discovery_rule\" \"$checked_discovery_path\" \"$checked_discovery_gate_rc\"` (each discovered path is still gated, and each rejection is still reported rather than dropped); `return \"$DISCOVERY_GATE_RC_NOT_REGULAR\"` (the `files` gate still rejects a name match that is not a regular file); `add_finding \"$rule_name\" \"$candidate_path\" 0` (the gate reporter still emits through the shared finding machinery, so --strict and the allowlist apply to it); the `=== DISCOVERY: Checked-discovery canary ===` banner and `add_finding 'DISCOVERY'` (the DISCOVERY canary section still exists and still reports through the shared finding machinery). superset mode fails if any literal is removed; extras elsewhere in the file are ignored. Behaviour this pin does not itself carry, but which the DISCOVERY canary asserts at run time over the committed fixtures under tests/policy/fixtures/discovery-canary (a real directory, a symlinked directory pointing at it, and a dangling link): that DISCOVERY_FIND_BASE is exactly the single element `-L`; that the engine descends the symlinked directory where a raw `find -P` does not; that the `files` gate rejects the dangling link as missing and a directory as not regular; that a nonexistent root propagates find's non-zero status; and that the wrapper keeps exactly the two regular files and emits exactly one finding, naming the dangling link. Residuals, stated plainly: a presence pin cannot prove meaning, and this fixture proves only that the canary section still announces itself and reports, not that its assertions still run correctly. Deleting the whole DISCOVERY canary section also aborts the run at CHECK 15's traversal canary, which reuses the canary's fixture paths, so the run fails before this fixture is evaluated; the two canary literals are the witness for a partial deletion that leaves those paths defined. The `files` gate's missing-path rejection is not pinned: its `return \"$DISCOVERY_GATE_RC_MISSING\"` line also appears in the `dirs` gate, so deleting one copy leaves the literal present -- only the canary's dangling-link gate probe witnesses it. A call site switched from the `files` gate to `raw`, or a new call site that discovers with its own find instead of the wrapper, leaves every pinned literal intact and this fixture green; no structural check counts raw finds, and the only raw finds outside the engine are the two comment-marked INTENTIONAL NON-HELPER FIND negative controls. A copy of a pinned literal added elsewhere in the file, such as a comment quoting it, masks deletion of the original. A symlink loop is not witnessed by any committed fixture; the canary witnesses the same non-zero find status through its nonexistent-root probe. A symlinked directory that points back inside a scanned root materialises the same file under two paths: it is scanned twice, no canary asserts that, and an allowlist entry keyed to one path does not cover the other. On a checkout with core.symlinks=false the committed symlink fixtures become plain files and the DISCOVERY canary fails loudly by design; this fixture itself stays green there. The sibling scripts under tools/ (validate.sh, validate_workflows.sh, validate_reports.sh, and the test_*.sh probes) do not use this engine, and nothing here covers their discovery.",
+  "set_check": {
+    "extract_regex": "(DISCOVERY_FIND_BASE=\\(-L\\)|find \"\\$\\{DISCOVERY_FIND_BASE\\[@\\]\\}\" \"\\$\\{discovery_roots\\[@\\]\\}\" \"\\$@\" -print0|discover_checked_paths\\(\\) \\{|discovery_gate_status \"\\$checked_discovery_path\" \"\\$checked_discovery_gate\"|flag_discovery_gate \"\\$checked_discovery_rule\" \"\\$checked_discovery_path\" \"\\$checked_discovery_gate_rc\"|return \"\\$DISCOVERY_GATE_RC_NOT_REGULAR\"|add_finding \"\\$rule_name\" \"\\$candidate_path\" 0|=== DISCOVERY: Checked-discovery canary ===|add_finding 'DISCOVERY')",
+    "expected_set": [
+      "DISCOVERY_FIND_BASE=(-L)",
+      "find \"${DISCOVERY_FIND_BASE[@]}\" \"${discovery_roots[@]}\" \"$@\" -print0",
+      "discover_checked_paths() {",
+      "discovery_gate_status \"$checked_discovery_path\" \"$checked_discovery_gate\"",
+      "flag_discovery_gate \"$checked_discovery_rule\" \"$checked_discovery_path\" \"$checked_discovery_gate_rc\"",
+      "return \"$DISCOVERY_GATE_RC_NOT_REGULAR\"",
+      "add_finding \"$rule_name\" \"$candidate_path\" 0",
+      "=== DISCOVERY: Checked-discovery canary ===",
+      "add_finding 'DISCOVERY'"
+    ],
+    "files": [
+      { "path": "tools/policy_check.sh", "mode": "superset" }
+    ]
+  }
+}
diff --git a/tests/policy/safety-tracker-ref-guard.json b/tests/policy/safety-tracker-ref-guard.json
index 2eff52eb..57e8482c 100644
--- a/tests/policy/safety-tracker-ref-guard.json
+++ b/tests/policy/safety-tracker-ref-guard.json
@@ -1,6 +1,6 @@
 {
   "rule": "check15-tracker-ref-guard-present",
-  "description": "P3 consumer-assertion: CHECK 15 (No tracker references in plugin runtime prose) in tools/policy_check.sh is the CI guard that makes P19 (doctrine anchors on durable records, not tracker IDs) real rather than decoration, per P17. This fixture pins four literals that prove the guard still exists, still emits CHECK15 findings through the shared finding machinery, and still carries both of its file-level canaries: the `=== CHECK 15:` section header (the block is present and still announces itself), `add_finding 'CHECK15'` (it still reports through the shared finding machinery, so --strict and the allowlist still apply to it), the `CHECK 15 SCANNER CANARY` section banner, and the `CHECK 15 TRAVERSAL CANARY` section banner (neither canary block has been deleted alongside its assertions). superset mode fails if any literal is removed; extras elsewhere in the file are ignored. Structural coverage this pin does not itself carry, but which exists inside tools/policy_check.sh: detection is a positive allowlist in one POSIX awk program, CHECK15_CLASSIFY_AWK. A `#` followed directly by a digit run is a candidate UNCONDITIONALLY -- whatever character follows the run -- and every candidate is a finding unless one of exactly four safe shapes consumes it whole: an inline code span closed by a backtick run of the same length, a `](#...)` in-page anchor, a single-segment owner/repo#N citation at a left boundary, or a bounded hex-colour run of 3, 4, 6 or 8 hex digits carrying at least one letter. There is no normalizer and no deletion pass over the line, so no exemption reaches past its own span. A detection canary asserts exact token sets through `tracker_ref_tokens`. A scanner canary asserts exact per-file records -- including line numbers -- through `scan_prose_file_refs` over the committed fixtures tests/policy/fixtures/tracker-ref-scan-canary.md, tests/policy/fixtures/tracker-ref-unclosed-frontmatter.md, and tests/policy/fixtures/tracker-ref-allowlist-canary.md. A traversal canary asserts that discovery, the read gate, and the awk layer each return non-zero for a nonexistent root, a missing path, or a directory, with a positive control on a committed fixture, plus a committed symlink fixture (tests/policy/fixtures/tracker-ref-symlink-canary.md, pointing at tracker-ref-unclosed-frontmatter.md) that proves discovery materialises a name-matching symlink and the read gate scans it through to its target's records. Discovery is checked: each of the two discovery arms runs through check15_discover_files, whose NUL-delimited path stream ends in a find-status sentinel record, so a failed find or a truncated stream is a CHECK15 finding, and each arm carries its own zero-file assertion. Discovery selects by NAME only, never by type, so a missing path (a dangling symlink), a path that is not a regular file (a directory, or a symlink to one), or an unreadable file all reach the read gate and are CHECK15 findings rather than silently dropped by find; a symlink to a regular file is read through to that file's own records. Reads are gated: a missing, non-regular, or unreadable file, or a classifier that exits non-zero, is a CHECK15 finding, never a clean file. Residuals, stated plainly: a presence pin can never prove the pattern still detects anything -- that is exactly what the in-check canaries carry, and this fixture only proves the canary sections still exist, not that their assertions still run correctly. It is blind to a narrowed shape set: narrowing the candidate rule, changing which safe shapes exist or what they admit, or narrowing the discovery globs leaves all four pinned literals intact and this fixture green. Allowlist granularity is a separate residual: an entry covers its whole line, so a reference added later to an already-allowlisted line would be hidden by it; zero CHECK15 allowlist entries exist today, so nothing is absolved in practice. Token granularity is a separate residual: the reported token for a reference glued to trailing word characters is only its `#`-plus-digits prefix (`#123g` reports `#123`, and left-glued `word#1a2b3c` reports `#1` because S4 does not apply left-glued) -- this fixture does not witness that shape, only that the canary sections asserting it still exist. Symlinked-directory traversal is a separate residual: discovery does not pass `-L`, so a symlinked directory under plugin/ is not traversed and any `*.md` beneath it is absent from the scan set; this fixture cannot see that gap widen or close. The reporting wrapper that turns a read failure into a finding, scan_file_for_tracker_refs, has no canary, because asserting it would emit a real finding; the traversal canary witnesses only the status-bearing layers beneath it.",
+  "description": "P3 consumer-assertion: CHECK 15 (No tracker references in plugin runtime prose) in tools/policy_check.sh is the CI guard that makes P19 (doctrine anchors on durable records, not tracker IDs) real rather than decoration, per P17. This fixture pins four literals that prove the guard still exists, still emits CHECK15 findings through the shared finding machinery, and still carries both of its file-level canaries: the `=== CHECK 15:` section header (the block is present and still announces itself), `add_finding 'CHECK15'` (it still reports through the shared finding machinery, so --strict and the allowlist still apply to it), the `CHECK 15 SCANNER CANARY` section banner, and the `CHECK 15 TRAVERSAL CANARY` section banner (neither canary block has been deleted alongside its assertions). superset mode fails if any literal is removed; extras elsewhere in the file are ignored. Structural coverage this pin does not itself carry, but which exists inside tools/policy_check.sh: detection is a positive allowlist in one POSIX awk program, CHECK15_CLASSIFY_AWK. A `#` followed directly by a digit run is a candidate UNCONDITIONALLY -- whatever character follows the run -- and every candidate is a finding unless one of exactly four safe shapes consumes it whole: an inline code span closed by a backtick run of the same length, a `](#...)` in-page anchor, a single-segment owner/repo#N citation at a left boundary, or a bounded hex-colour run of 3, 4, 6 or 8 hex digits carrying at least one letter. There is no normalizer and no deletion pass over the line, so no exemption reaches past its own span. A detection canary asserts exact token sets through `tracker_ref_tokens`. A scanner canary asserts exact per-file records -- including line numbers -- through `scan_prose_file_refs` over the committed fixtures tests/policy/fixtures/tracker-ref-scan-canary.md, tests/policy/fixtures/tracker-ref-unclosed-frontmatter.md, and tests/policy/fixtures/tracker-ref-allowlist-canary.md. A traversal canary asserts that discovery, the read gate, and the awk layer each return non-zero for a nonexistent root, a missing path, or a directory, with a positive control on a committed fixture, plus a committed symlink fixture (tests/policy/fixtures/tracker-ref-symlink-canary.md, pointing at tracker-ref-unclosed-frontmatter.md) that proves discovery materialises a name-matching symlink and the read gate scans it through to its target's records, and probes over the committed DISCOVERY canary tree (tests/policy/fixtures/discovery-canary) that prove CHECK 15's discovery descends a symlinked directory and hands a dangling link to the read gate. Discovery is checked: each of the two discovery arms runs through the shared checked-discovery engine -- discover_checked_paths under the `raw` gate, over discover_paths, whose NUL-delimited path stream ends in a find-status sentinel record -- so a failed find, a symlink loop, or a truncated stream is a CHECK15 finding, and each arm carries its own zero-file assertion. Discovery follows symlinks with `-L`, so a symlinked directory under plugin/ is descended and every name-matching path beneath it is scanned. Discovery selects by NAME only, never by type, so a missing path (a dangling symlink), a path that is not a regular file (a directory, or a symlink to one), or an unreadable file all reach the read gate and are CHECK15 findings rather than silently dropped by find; a symlink to a regular file is read through to that file's own records. Reads are gated: a missing, non-regular, or unreadable file, or a classifier that exits non-zero, is a CHECK15 finding, never a clean file. Residuals, stated plainly: a presence pin can never prove the pattern still detects anything -- that is exactly what the in-check canaries carry, and this fixture only proves the canary sections still exist, not that their assertions still run correctly. It is blind to a narrowed shape set: narrowing the candidate rule, changing which safe shapes exist or what they admit, or narrowing the discovery globs leaves all four pinned literals intact and this fixture green. Allowlist granularity is a separate residual: an entry covers its whole line, so a reference added later to an already-allowlisted line would be hidden by it; zero CHECK15 allowlist entries exist today, so nothing is absolved in practice. Token granularity is a separate residual: the reported token for a reference glued to trailing word characters is only its `#`-plus-digits prefix (`#123g` reports `#123`, and left-glued `word#1a2b3c` reports `#1` because S4 does not apply left-glued) -- this fixture does not witness that shape, only that the canary sections asserting it still exist. Path spelling is a separate residual: a symlinked directory that points back inside plugin/ materialises the same file under two paths, so it is scanned twice and an allowlist entry keyed to one path does not cover the other; a symlink loop is not witnessed by a committed fixture. This fixture pins none of the shared discovery engine's literals, so it cannot see `-L` removed from discovery -- tests/policy/safety-discovery-policy.json carries those pins. The reporting wrapper that turns a read failure into a finding, scan_file_for_tracker_refs, has no canary, because asserting it would emit a real finding; the traversal canary witnesses only the status-bearing layers beneath it.",
   "set_check": {
     "extract_regex": "(=== CHECK 15:|CHECK 15 SCANNER CANARY|CHECK 15 TRAVERSAL CANARY|add_finding 'CHECK15')",
     "expected_set": [
diff --git a/tools/policy_check.sh b/tools/policy_check.sh
index 70d30470..a6f4fd5c 100644
--- a/tools/policy_check.sh
+++ b/tools/policy_check.sh
@@ -292,9 +292,12 @@ file_candidates() {
 #       `files` gate of discovery_gate_status that rejects it (missing), and
 #       discover_checked_paths reports it through flag_discovery_gate.
 #   Call sites: every scanning check discovers through discover_checked_paths,
-#   the one composition of the pieces below. discover_paths and
-#   discovery_gate_status are called directly only by canaries, which assert
-#   their statuses without emitting a real finding.
+#   the one composition of the pieces below. discover_paths is called directly
+#   only by canaries, which assert its status without emitting a real finding.
+#   discovery_gate_status is called directly by canaries and, outside a
+#   discovery, only to classify an optional ROOT before discovering under it
+#   (CHECK 14's skill scripts directory), whose rejection is still reported
+#   through flag_discovery_gate.
 #   Precondition: every ROOT must exist. This is the CALLER's job; there is
 #   no swallow mode and find's stderr is never suppressed, so a missing root
 #   fails discovery with find's non-zero status and must be reported.
@@ -2035,9 +2038,10 @@ mark_time 'CHECK14'
 # layers shrinks what the check reads. The candidate rule has no right-boundary
 # condition, so `#123g`, `#123_` and `_#123_` are candidates rather than silently
 # dropped; the only narrowing is by a named safe shape. Discovery selects by
-# NAME only, never by type, so every name-matching path -- a symlink, a
-# directory named `*.md`, a dangling link -- reaches the read gate, where it is
-# read or becomes a finding instead of vanishing inside find.
+# NAME only, never by type, and follows symlinks, so every name-matching path
+# -- a symlink, a directory named `*.md`, a dangling link, a file beneath a
+# symlinked directory -- reaches the read gate, where it is read or becomes a
+# finding instead of vanishing inside find.
 #
 # CARDINALITY. A candidate consumes only its own token and never the separator
 # after it, so every reference on a line is reported, not just the first. A
@@ -2056,7 +2060,7 @@ mark_time 'CHECK14'
 #     (including an unclosed-frontmatter fixture that no predicate test reaches).
 #   * the TRAVERSAL CANARY asserts that discovery, the read gate, and the awk
 #     layer each return non-zero on failure instead of empty output, and that
-#     discovery selects by name only.
+#     discovery selects by name only and descends a symlinked directory.
 #
 # Discovery FAILS CLOSED PER ARM: each of the two discovery arms (`plugin/**/*.md`
 # and `plugin/workflows/*.json`) carries its OWN zero-file assertion. An aggregate
@@ -2070,6 +2074,14 @@ mark_time 'CHECK14'
 # symlink to one), or unreadable is a finding, as is a classifier that exits
 # non-zero on a file -- never a clean file.
 #
+# Both arms discover through the shared checked-discovery engine
+# (discover_checked_paths under CHECK15_DISCOVERY_GATE, see the Checked
+# discovery section), which follows symlinks with -L script-wide: a symlinked
+# directory under plugin/ is descended and every name-matching path beneath it
+# is scanned; a dangling link is materialised and, under the `raw` gate,
+# reaches CHECK 15's own read gate, where it is a finding; a symlink loop makes
+# find exit non-zero, which is a CHECK15 discovery-failure finding.
+#
 # RESIDUALS, stated plainly:
 #   * allowlist granularity is the LINE, not the token. An entry added for one
 #     reference on a line would also absolve a reference added to that same line
@@ -2092,17 +2104,16 @@ mark_time 'CHECK14'
 #     letter, so `#12ab` is indistinguishable from a tracker id glued to letters
 #     and is exempt. Bounded: a tracker id is pure digits, and a pure-digit run
 #     is never S4.
-#   * RECORDED RESIDUAL, same root class as silent input-set narrowing:
-#     discovery does not pass `-L`, so a symlinked DIRECTORY under plugin/ is
-#     not traversed and any `*.md` beneath it is absent from the scan set.
-#     Bounded: zero symlinks exist under plugin/ today, and the input is the
-#     repo's own committed tree. Remediation is rejected for now because an
-#     honest witness needs a filesystem object created at run time, and `-L`
-#     changes find's dangling-link and loop error semantics for the whole
-#     check. Promote this to a tracked issue if a symlink lands under plugin/.
-#   * discovery coverage is split: the traversal canary's behavioural symlink
-#     probe witnesses the discovery FUNCTION, and its exact args pin witnesses
-#     the production CALL SITES. Neither alone covers both.
+#   * a symlinked directory that points back inside plugin/ materialises the
+#     same file under two paths: it is scanned twice, never skipped, but an
+#     allowlist entry keyed to one path does not cover the other. A symlink
+#     loop is not witnessed by a committed fixture; it reports through the same
+#     non-zero find status the traversal canary's nonexistent-root probe
+#     witnesses.
+#   * discovery coverage is split: the traversal canary's exact args and gate
+#     pins witness the production CALL SITES, and its discovery probes witness
+#     the production COMPOSITION (discover_checked_paths under
+#     CHECK15_DISCOVERY_GATE over the shared engine). Neither alone covers both.
 #   * an inline code span broken across physical lines is not recognized: each
 #     line is classified alone, so a reference on either half is reported.
 #   * the scanner canary pins fixture LINE NUMBERS in this file. The fixtures say

From 0d98927d7949b1f5fecab5a3e413786ffa82dc90 Mon Sep 17 00:00:00 2001
From: Bren Pike <brenpike@gmail.com>
Date: Fri, 25 Sep 2026 16:38:19 -0600
Subject: [PATCH 07/10] fix(policy): gate required fixture roots through the
 dirs gate

---
 tools/policy_check.sh | 42 ++++++++++++++++++++++++++++++++++++------
 1 file changed, 36 insertions(+), 6 deletions(-)

diff --git a/tools/policy_check.sh b/tools/policy_check.sh
index a6f4fd5c..17869a97 100644
--- a/tools/policy_check.sh
+++ b/tools/policy_check.sh
@@ -295,9 +295,13 @@ file_candidates() {
 #   the one composition of the pieces below. discover_paths is called directly
 #   only by canaries, which assert its status without emitting a real finding.
 #   discovery_gate_status is called directly by canaries and, outside a
-#   discovery, only to classify an optional ROOT before discovering under it
-#   (CHECK 14's skill scripts directory), whose rejection is still reported
-#   through flag_discovery_gate.
+#   discovery, to classify a ROOT before discovering under it -- CHECK 14's
+#   OPTIONAL skill scripts directory, and the REQUIRED SAFETY, COMPAT and
+#   WORKFLOW-FIXTURES fixture roots -- whose rejection is still reported
+#   through flag_discovery_gate. A root is never pre-guarded by a bare `-d`
+#   test: that skips the discovery entirely, so a missing or non-directory
+#   root would become a silent green run over an empty set instead of a
+#   finding.
 #   Precondition: every ROOT must exist. This is the CALLER's job; there is
 #   no swallow mode and find's stderr is never suppressed, so a missing root
 #   fails discovery with find's non-zero status and must be reported.
@@ -2674,7 +2678,17 @@ echo '=== SAFETY: Regression fixture tests ==='
 SAFETY_DIR="$REPO_ROOT/tests/policy"
 declare -a SAFETY_FIXTURES=()
 SAFETY_DISCOVERY_FAILED=false
-if [[ -d "$SAFETY_DIR" ]]; then
+# REQUIRED root: classify it with the status-bearing `dirs` gate rather than a
+# bare `-d` pre-guard. A `-d` test that simply skips the discovery makes a
+# missing or non-directory root a silent green run over an empty fixture set --
+# the exact input-set narrowing ahead of the fail-closed layer this engine
+# exists to prevent.
+SAFETY_DIR_RC=0
+discovery_gate_status "$SAFETY_DIR" dirs || SAFETY_DIR_RC=$?
+if [[ "$SAFETY_DIR_RC" -ne 0 ]]; then
+    SAFETY_DISCOVERY_FAILED=true
+    flag_discovery_gate 'SAFETY' "$SAFETY_DIR" "$SAFETY_DIR_RC"
+else
     discover_checked_paths 'SAFETY' SAFETY_FIXTURES files 'safety-*.json fixture files' "$SAFETY_DIR" -- -maxdepth 1 -name 'safety-*.json' || SAFETY_DISCOVERY_FAILED=true
 fi
 
@@ -3235,7 +3249,14 @@ echo '=== COMPAT: Plugin compatibility fixture tests ==='
 COMPAT_DIR="$REPO_ROOT/tests/plugin"
 declare -a COMPAT_FIXTURES=()
 COMPAT_DISCOVERY_FAILED=false
-if [[ -d "$COMPAT_DIR" ]]; then
+# REQUIRED root: see the SAFETY root gate above -- a bare `-d` pre-guard would
+# turn a missing or non-directory root into a silent SKIP over zero fixtures.
+COMPAT_DIR_RC=0
+discovery_gate_status "$COMPAT_DIR" dirs || COMPAT_DIR_RC=$?
+if [[ "$COMPAT_DIR_RC" -ne 0 ]]; then
+    COMPAT_DISCOVERY_FAILED=true
+    flag_discovery_gate 'COMPAT' "$COMPAT_DIR" "$COMPAT_DIR_RC"
+else
     discover_checked_paths 'COMPAT' COMPAT_FIXTURES files 'compatibility fixture files' "$COMPAT_DIR" -- -maxdepth 1 -name '*.json' || COMPAT_DISCOVERY_FAILED=true
 fi
 
@@ -3613,7 +3634,16 @@ test_workflow_fixtures() {
     local fixtures_dir="$REPO_ROOT/tests/workflows"
     declare -a fixtures=()
     local wf_discovery_failed=false
-    if [[ -d "$fixtures_dir" ]]; then
+    # REQUIRED root: see the SAFETY root gate above. This site already failed
+    # loudly on zero fixtures, but it is gated the same way so the `-d`
+    # pre-guard shape exists nowhere in this script and cannot be copied
+    # forward into a call site that has no such backstop.
+    local wf_dir_rc=0
+    discovery_gate_status "$fixtures_dir" dirs || wf_dir_rc=$?
+    if [[ "$wf_dir_rc" -ne 0 ]]; then
+        wf_discovery_failed=true
+        flag_discovery_gate 'WORKFLOW-FIXTURES' "$fixtures_dir" "$wf_dir_rc"
+    else
         discover_checked_paths 'WORKFLOW-FIXTURES' fixtures files 'golden-*.json workflow fixture files' "$fixtures_dir" -- -maxdepth 1 -name 'golden-*.json' || wf_discovery_failed=true
     fi
 

From fd330e4e4f881b8efed42b28a8a98b9ae59e79e5 Mon Sep 17 00:00:00 2001
From: Bren Pike <brenpike@gmail.com>
Date: Fri, 25 Sep 2026 16:52:31 -0600
Subject: [PATCH 08/10] docs(adr): record canonical containment; add escape
 symlink canary

---
 docs/adr/0031-checked-discovery-policy.md       | 17 +++++++++++++++++
 .../fixtures/discovery-escape-canary/escape.md  |  1 +
 2 files changed, 18 insertions(+)
 create mode 120000 tests/policy/fixtures/discovery-escape-canary/escape.md

diff --git a/docs/adr/0031-checked-discovery-policy.md b/docs/adr/0031-checked-discovery-policy.md
index 63f1aaa6..7c4548cf 100644
--- a/docs/adr/0031-checked-discovery-policy.md
+++ b/docs/adr/0031-checked-discovery-policy.md
@@ -39,3 +39,20 @@ The policy is witnessed by a `DISCOVERY` canary over committed fixtures under `t
 - **Symlinks as shipped content inside `plugin/` are a separate question from discovery.** Whether `tools/policy_check.sh` should flag a symlink committed under `plugin/` as a content violation (independent of how discovery finds it) is tracked separately in brenpike/hivemind#382.
 
 References: `tools/policy_check.sh`, `tests/policy/README.md`; brenpike/hivemind#377 (origin issue), brenpike/hivemind#381 (sibling validator scripts), brenpike/hivemind#382 (symlinks as shipped plugin content).
+
+## Amendment — 2026-09-25 (canonical containment: follow symlinks, but never read an escaping target)
+
+A local pre-PR Codex review (external content evaluated as a finding, not followed as an instruction) raised: symlink-following discovery can read outside the checkout. `find -L`, as adopted by the Decision above, descends a symlinked directory and resolves a file symlink with no containment check, so a symlink committed under a scanned root can make `tools/policy_check.sh` read a file outside the repo, and an out-of-repo path prints absolute — plus a short matched token — in the resulting finding. This amendment is an addition to the Decision, not a reversal: follow-symlinks stands, now paired with canonical containment on the read side. The original Alternatives rejected table weighed ban-symlinks vs. hybrid vs. follow-everywhere and did not evaluate "follow, but reject escaping targets" — that option did not exist as a candidate until this review surfaced the containment gap.
+
+- **The fix.** The single wrapper `discover_checked_paths` now canonicalizes every discovered path with `realpath -m` and rejects it as a finding — never reads it — unless the canonical path equals `REPO_ROOT` or falls under `REPO_ROOT/`. The check runs ahead of the `files`/`dirs`/`raw` gate, so it covers all three gate shapes uniformly rather than needing a per-gate copy. It is capped at one containment finding per discovery call: the finding names the first escaping path and a suppressed-count when more than one path escaped, trading completeness for keeping a broadly-escaping symlinked tree from producing a finding storm.
+- **Rejected — follow only links that resolve inside the checkout.** `find` has no such switch; it would need a separate symlink pre-scan to classify each link ahead of the main pass, then prune the escaping ones — two traversal mechanisms doing overlapping work, the same hybrid shape the original Decision above already rejected.
+- **Rejected — warn-only `find -type l` pre-scan.** A second traversal that detects an escaping link without preventing the read that follows it, and still misses a link that lives inside a directory reached only through an already-followed external tree — such a pre-scan would itself need to follow symlinks to see it, at which point it carries the same escape exposure it is meant to warn about.
+- **Threat model.** CI runs PR-authored shell on `pull_request` (`contents: read`, no secrets), so containment is not a security boundary against a hostile PR — a PR able to add a script under `tools/` can already read whatever the runner can read, symlink or not. The value is against accident: a stray link into a large external tree (time cost, log noise) and out-of-repo paths surfacing in CI logs.
+- **Residual — containment stops the read, not the walk.** `find -L` still traverses an external tree reached through a followed symlink before the classifier rejects what it finds there; the traversal's time cost is not eliminated by this amendment.
+- **Residual — only the first escaping path per call is named,** by the one-per-call cap described above; this is a deliberate completeness/noise trade, not an oversight.
+- **Residual — symlink loops remain unwitnessed,** unchanged from the original Decision's residual above; the escape canary added by this amendment (below) is a file symlink, not a loop, so it does not touch that residual.
+- **Witness.** A committed escape canary, `tests/policy/fixtures/discovery-escape-canary/escape.md`, is a file symlink whose relative `../` chain collapses at `/` onto a nonexistent out-of-repo name. Being a file link rather than a directory link, the canary exercises the containment rejection at the leaf without walking an external tree, so it does not exercise the traversal-cost residual noted above.
+- **Portability.** `tools/policy_check.sh` already uses `realpath` — `SCRIPT_DIR` is derived with `realpath "$0"`, and CHECK 6 already canonicalizes with `realpath -m` — so this amendment follows the script's own existing, maintained convention. The no-`realpath`/`readlink` portability constraint (BSD/macOS lack it or spell it differently) governs plugin runtime shell shipped to consumers — see `plugin/skills/_shared/containment.sh`, which documents and follows that constraint for shipped code — and does not apply to repo tooling under `tools/`, which already targets the CI runner's own GNU environment.
+- **Deferred tail, updated.** brenpike/hivemind#381 (sibling `tools/` validator/test scripts): the follow-symlinks migration tracked there now also needs the same canonical-containment treatment landed here, not just the discovery-narrowing fix it was originally scoped for. brenpike/hivemind#382 (unchanged in substance): this amendment makes `tools/policy_check.sh` reject an *escaping* symlink at scan time as a finding, never a read — it still does not forbid committing a symlink under `plugin/` that resolves inside the checkout, so that content question stays open.
+
+References: `tools/policy_check.sh`; `tests/policy/fixtures/discovery-escape-canary/escape.md`; brenpike/hivemind#381, brenpike/hivemind#382.
diff --git a/tests/policy/fixtures/discovery-escape-canary/escape.md b/tests/policy/fixtures/discovery-escape-canary/escape.md
new file mode 120000
index 00000000..d63534e6
--- /dev/null
+++ b/tests/policy/fixtures/discovery-escape-canary/escape.md
@@ -0,0 +1 @@
+../../../../../../../../../../../../../../../../../../../../__hivemind_escape_canary_outside__
\ No newline at end of file

From 2e0cade00a351f37d941b09c201f69f200ec14ba Mon Sep 17 00:00:00 2001
From: Bren Pike <brenpike@gmail.com>
Date: Fri, 25 Sep 2026 17:02:40 -0600
Subject: [PATCH 09/10] fix(policy): reject discovered paths resolving outside
 the checkout

---
 tools/policy_check.sh | 148 ++++++++++++++++++++++++++++++++++++++----
 1 file changed, 137 insertions(+), 11 deletions(-)

diff --git a/tools/policy_check.sh b/tools/policy_check.sh
index 17869a97..93c9f929 100644
--- a/tools/policy_check.sh
+++ b/tools/policy_check.sh
@@ -305,6 +305,19 @@ file_candidates() {
 #   Precondition: every ROOT must exist. This is the CALLER's job; there is
 #   no swallow mode and find's stderr is never suppressed, so a missing root
 #   fails discovery with find's non-zero status and must be reported.
+#   Containment: every path discover_checked_paths accepts resolves inside
+#   the checkout. Because -L follows symlinks, a link can lead discovery out
+#   of the repository, so discovery_containment_status canonicalises each
+#   materialised path with `realpath -m` and rejects any that does not
+#   resolve to REPO_ROOT or under it (a realpath failure is a rejection,
+#   never an accept). It runs AHEAD of discovery_gate_status for every gate,
+#   `raw` included, so an escaping path is never classified, never accepted,
+#   and never read by any check -- an escape is reported as an escape even
+#   when the gate would also have rejected it. The report is capped at ONE
+#   finding per discover_checked_paths call: it names the first escaping path
+#   (its in-checkout path, never its external target) and counts the further
+#   escaping paths it suppressed, so a link to a large external tree cannot
+#   flood the log; the call still returns non-zero.
 #   Findings: both reporting wrappers emit through add_finding, so --strict
 #   and the allowlist apply. Neither they nor discover_checked_paths set any
 #   per-check found/pass flag; discover_checked_paths returns non-zero when it
@@ -312,6 +325,11 @@ file_candidates() {
 #   Residuals: symlink-loop reporting is not witnessed by a committed fixture;
 #   a symlinked directory that points back inside a scanned root materialises
 #   the same file under two paths (it is scanned twice, never skipped).
+#   Containment stops the READ, not the WALK: find -L still traverses an
+#   external tree a link leads into (only its paths are rejected), and a
+#   loop there still surfaces as find's non-zero status. Only the first
+#   escaping path is named; the rest are counted, not listed. discover_paths
+#   itself applies no containment -- only its canaries call it directly.
 
 DISCOVERY_FIND_BASE=(-L)
 DISCOVERY_FIND_STATUS_TAG='__DISCOVERY_FIND_STATUS='
@@ -322,6 +340,7 @@ DISCOVERY_GATE_RC_NOT_REGULAR=23
 DISCOVERY_GATE_RC_UNREADABLE=24
 DISCOVERY_GATE_RC_NOT_DIR=25
 DISCOVERY_GATE_RC_UNKNOWN_GATE=26
+DISCOVERY_GATE_RC_ESCAPES=27
 
 # discover_paths DEST_ARRAY ROOT... -- FIND_ARGS...
 # Materialises the paths
@@ -426,6 +445,21 @@ discovery_gate_status() {
     return 0
 }
 
+# discovery_containment_status PATH
+# Status-bearing containment classifier for one discovered PATH: 0 only when
+# `realpath -m -- PATH` succeeds and its result equals REPO_ROOT or begins with
+# REPO_ROOT/; otherwise DISCOVERY_GATE_RC_ESCAPES. A realpath failure is a
+# rejection, never an accept.
+discovery_containment_status() {
+    local containment_candidate="$1" containment_canonical
+    local containment_prefix="${REPO_ROOT%/}/"
+    containment_canonical="$(realpath -m -- "$containment_candidate")" || return "$DISCOVERY_GATE_RC_ESCAPES"
+    if [[ "$containment_canonical" == "$REPO_ROOT" || "$containment_canonical" == "$containment_prefix"* ]]; then
+        return 0
+    fi
+    return "$DISCOVERY_GATE_RC_ESCAPES"
+}
+
 # flag_discovery_failure RULE ROOT LABEL STATUS
 # Thin reporting wrapper: records the RULE finding for a discover_paths call
 # (described by LABEL, anchored at ROOT) that returned non-zero STATUS. A
@@ -441,16 +475,19 @@ flag_discovery_failure() {
         "Discovery of ${discovery_label} failed: ${failure_reason}, so paths in it may never have been checked -- fix the tree; a failed discovery is NOT clean"
 }
 
-# flag_discovery_gate RULE PATH RC
+# flag_discovery_gate RULE PATH RC [SUPPRESSED_TOTAL]
 # Thin reporting wrapper: records the RULE finding for a discovered PATH that
-# discovery_gate_status rejected with non-zero RC.
+# discovery_gate_status or discovery_containment_status rejected with non-zero
+# RC. SUPPRESSED_TOTAL (default 0) is read only for DISCOVERY_GATE_RC_ESCAPES:
+# the count of further escaping paths the capped containment report withheld.
 flag_discovery_gate() {
-    local rule_name="$1" candidate_path="$2" gate_rc="$3" rejection_reason
+    local rule_name="$1" candidate_path="$2" gate_rc="$3" suppressed_total="${4:-0}" rejection_reason
     case "$gate_rc" in
         "$DISCOVERY_GATE_RC_MISSING") rejection_reason='is missing or is a dangling symlink' ;;
         "$DISCOVERY_GATE_RC_NOT_REGULAR") rejection_reason='is not a regular file' ;;
         "$DISCOVERY_GATE_RC_UNREADABLE") rejection_reason='is not readable' ;;
         "$DISCOVERY_GATE_RC_NOT_DIR") rejection_reason='is not a directory' ;;
+        "$DISCOVERY_GATE_RC_ESCAPES") rejection_reason="does not resolve inside the checkout (a symlink leads it outside the repository root, or realpath could not canonicalise it) [${suppressed_total} further escaping path(s) from the same discovery suppressed]" ;;
         *) rejection_reason="was rejected by the discovery gate with status ${gate_rc}" ;;
     esac
     add_finding "$rule_name" "$candidate_path" 0 \
@@ -461,11 +498,19 @@ flag_discovery_gate() {
 # The checked discovery every scanning check calls. Runs
 #   discover_paths ROOT... -- FIND_ARGS...
 # and reports a non-zero status through flag_discovery_failure (anchored at
-# the first ROOT, described by LABEL); then gates each materialised path with
-# discovery_gate_status PATH GATE and reports each rejection through
-# flag_discovery_gate. DEST_ARRAY is replaced with ONLY the accepted paths, in
-# find order. Returns 1 when it emitted any RULE finding, else 0, so the
-# caller sets its own flag: `discover_checked_paths ... || checkN_found=true`.
+# the first ROOT, described by LABEL); then, for each materialised path,
+# first checks discovery_containment_status PATH and, only when it is
+# contained, gates it with discovery_gate_status PATH GATE, reporting each
+# gate rejection through flag_discovery_gate. Escaping paths are counted and
+# reported after the loop as ONE flag_discovery_gate finding naming the first
+# of them with the suppressed remainder. DEST_ARRAY is replaced with ONLY the
+# accepted paths, in find order. Returns 1 when it emitted any RULE finding,
+# else 0, so the caller sets its own flag:
+# `discover_checked_paths ... || checkN_found=true`.
+#
+# INVARIANT: every path added to DEST_ARRAY passed discovery_containment_status
+# before discovery_gate_status, so no gate -- `raw` included -- hands a check
+# a path that resolves outside the checkout.
 #
 # INVARIANT: DEST_ARRAY is bound by nameref, so it must not be one of this
 # function's own `checked_discovery_*` locals (the nameref would bind the
@@ -479,6 +524,7 @@ discover_checked_paths() {
     local -a checked_discovery_materialised=()
     local checked_discovery_rc=0 checked_discovery_flagged=false
     local checked_discovery_path checked_discovery_gate_rc
+    local checked_discovery_escape_first='' checked_discovery_escape_total=0
     discover_paths checked_discovery_materialised "$@" || checked_discovery_rc=$?
     if [[ "$checked_discovery_rc" -ne 0 ]]; then
         checked_discovery_flagged=true
@@ -487,6 +533,14 @@ discover_checked_paths() {
     checked_discovery_dest_ref=()
     for checked_discovery_path in "${checked_discovery_materialised[@]}"; do
         checked_discovery_gate_rc=0
+        discovery_containment_status "$checked_discovery_path" || checked_discovery_gate_rc=$?
+        if [[ "$checked_discovery_gate_rc" -ne 0 ]]; then
+            if [[ "$checked_discovery_escape_total" -eq 0 ]]; then
+                checked_discovery_escape_first="$checked_discovery_path"
+            fi
+            checked_discovery_escape_total=$((checked_discovery_escape_total + 1))
+            continue
+        fi
         discovery_gate_status "$checked_discovery_path" "$checked_discovery_gate" || checked_discovery_gate_rc=$?
         if [[ "$checked_discovery_gate_rc" -ne 0 ]]; then
             checked_discovery_flagged=true
@@ -495,6 +549,10 @@ discover_checked_paths() {
         fi
         checked_discovery_dest_ref+=("$checked_discovery_path")
     done
+    if [[ "$checked_discovery_escape_total" -gt 0 ]]; then
+        checked_discovery_flagged=true
+        flag_discovery_gate "$checked_discovery_rule" "$checked_discovery_escape_first" "$DISCOVERY_GATE_RC_ESCAPES" "$((checked_discovery_escape_total - 1))"
+    fi
     if [[ "$checked_discovery_flagged" == true ]]; then
         return 1
     fi
@@ -580,7 +638,20 @@ CHECKS_FAILED=0
 #     `files` gate keeps exactly real/inner.md and link-dir/inner.md, returns
 #     non-zero, and emits exactly one finding, naming broken/dangling.md. It
 #     runs inside a command substitution so that finding is captured as text
-#     and its FINDING_* append dies with the subshell -- no real finding.
+#     and its FINDING_* append dies with the subshell -- no real finding. Its
+#     two accepted paths are also the positive control for containment: a
+#     containment check that rejected unconditionally would drop them;
+#   * containment: discover_checked_paths over the escape canary root (a FILE
+#     symlink whose target lies outside the repository root), once under the
+#     `files` gate and once under `raw`, returns non-zero, accepts ZERO paths,
+#     and emits exactly one finding naming escape.md with the containment
+#     reason and 0 suppressed -- `raw` proves containment runs ahead of every
+#     gate, and the reason text proves `files` rejected it as an escape, not
+#     as the dangling link it also is;
+#   * cap: the same discovery with the escape root passed twice materialises
+#     escape.md twice yet emits exactly one containment finding, with 1
+#     suppressed. Both probes run in command substitutions like the
+#     composition probe, so no real finding is emitted.
 # The fixtures are committed, so no probe creates a filesystem object at run
 # time. stderr is discarded only for the nonexistent-root probe, whose find
 # error is the expected outcome.
@@ -602,6 +673,9 @@ dcanary_real_file="$dcanary_real_dir/inner.md"
 dcanary_linked_file="$dcanary_link_dir/inner.md"
 dcanary_dangling_file="$dcanary_root/broken/dangling.md"
 dcanary_missing_root="$dcanary_root/__discovery_nonexistent__"
+DISCOVERY_ESCAPE_CANARY_REL='tests/policy/fixtures/discovery-escape-canary'
+dcanary_escape_root="$REPO_ROOT/$DISCOVERY_ESCAPE_CANARY_REL"
+dcanary_escape_file="$dcanary_escape_root/escape.md"
 dcanary_found=false
 
 # flag_discovery_canary DESCRIPTION
@@ -622,8 +696,8 @@ expect_discovery_gate() {
     fi
 }
 
-if [[ ! -L "$dcanary_link_dir" || ! -L "$dcanary_dangling_file" ]]; then
-    flag_discovery_canary "precondition: ${DISCOVERY_CANARY_REL}/tree/link-dir and ${DISCOVERY_CANARY_REL}/broken/dangling.md must both be symlinks in this checkout, but at least one is not -- the likely cause is core.symlinks=false materialising them as plain files; set core.symlinks=true and re-checkout, never skip this canary"
+if [[ ! -L "$dcanary_link_dir" || ! -L "$dcanary_dangling_file" || ! -L "$dcanary_escape_file" ]]; then
+    flag_discovery_canary "precondition: ${DISCOVERY_CANARY_REL}/tree/link-dir, ${DISCOVERY_CANARY_REL}/broken/dangling.md and ${DISCOVERY_ESCAPE_CANARY_REL}/escape.md must all be symlinks in this checkout, but at least one is not -- the likely cause is core.symlinks=false materialising them as plain files; set core.symlinks=true and re-checkout, never skip this canary"
 fi
 
 if [[ "${#DISCOVERY_FIND_BASE[@]}" -ne 1 || "${DISCOVERY_FIND_BASE[0]}" != '-L' ]]; then
@@ -726,6 +800,58 @@ if [[ "$dcanary_composition_rc" != 1 || "$dcanary_composition_accepted_total" -n
     flag_discovery_canary "discover_checked_paths over ${DISCOVERY_CANARY_REL} under the 'files' gate produced [${dcanary_composition_flat}]; expected rc=1, exactly real/inner.md and link-dir/inner.md accepted, and exactly one finding naming broken/dangling.md -- the call-site composition no longer gates, reports, or returns its findings"
 fi
 
+# probe_checked_discovery_containment GATE ROOT...
+# Prints discover_checked_paths' output over ROOT... under GATE (its findings),
+# then `rc=STATUS` and one `accepted=PATH` line per accepted path. Called only
+# inside a command substitution, so the finding it emits stays in the subshell.
+probe_checked_discovery_containment() {
+    local containment_probe_gate="$1"
+    shift
+    local -a dcanary_contained_paths=()
+    local dcanary_contained_rc=0 dcanary_contained_path
+    discover_checked_paths 'DISCOVERY' dcanary_contained_paths "$containment_probe_gate" 'discovery escape canary Markdown files' "$@" -- -name '*.md' || dcanary_contained_rc=$?
+    printf 'rc=%d\n' "$dcanary_contained_rc"
+    for dcanary_contained_path in "${dcanary_contained_paths[@]}"; do
+        printf 'accepted=%s\n' "$dcanary_contained_path"
+    done
+}
+
+# expect_discovery_containment PROBE_LABEL EXPECTED_SUPPRESSED GATE ROOT...
+# Runs probe_checked_discovery_containment GATE ROOT... in a command
+# substitution and asserts rc=1, zero accepted paths, and exactly one
+# DISCOVERY finding: the containment finding naming escape.md with
+# EXPECTED_SUPPRESSED further escaping paths suppressed.
+expect_discovery_containment() {
+    local probe_label="$1" expected_suppressed="$2" probe_output probe_line
+    local probe_rc='' probe_accepted_total=0 probe_finding_total=0 probe_saw_escape=false
+    shift 2
+    probe_output="$(probe_checked_discovery_containment "$@")"
+    while IFS= read -r probe_line; do
+        case "$probe_line" in
+            'rc='*)
+                probe_rc="${probe_line#rc=}"
+                ;;
+            'accepted='*)
+                probe_accepted_total=$((probe_accepted_total + 1))
+                ;;
+            *'[DISCOVERY] '*)
+                probe_finding_total=$((probe_finding_total + 1))
+                if [[ "$probe_line" == *"[DISCOVERY] ${DISCOVERY_ESCAPE_CANARY_REL}/escape.md -- this discovered path does not resolve inside the checkout "*"[${expected_suppressed} further escaping path(s) "* ]]; then
+                    probe_saw_escape=true
+                fi
+                ;;
+        esac
+    done <<< "$probe_output"
+    if [[ "$probe_rc" != 1 || "$probe_accepted_total" -ne 0 \
+       || "$probe_finding_total" -ne 1 || "$probe_saw_escape" != true ]]; then
+        flag_discovery_canary "${probe_label}: discover_checked_paths over ${DISCOVERY_ESCAPE_CANARY_REL} produced [${probe_output//$'\n'/ | }]; expected rc=1, zero accepted paths, and exactly one finding naming escape.md as a containment escape with ${expected_suppressed} further path(s) suppressed -- discovery no longer confines accepted paths to the checkout, or no longer caps its containment report"
+    fi
+}
+
+expect_discovery_containment "containment under the 'files' gate" 0 files "$dcanary_escape_root"
+expect_discovery_containment "containment under the 'raw' gate" 0 raw "$dcanary_escape_root"
+expect_discovery_containment 'containment cap (escape root passed twice)' 1 files "$dcanary_escape_root" "$dcanary_escape_root"
+
 if [[ "$dcanary_found" == false ]]; then
     echo '[PASS] DISCOVERY: checked discovery follows symlinked directories, gates dangling and wrong-type paths, and propagates find failures'
     CHECKS_PASSED=$((CHECKS_PASSED + 1))

From 1b0f6a9a5c27ad7c952f6fbcc5aef0a001289c4a Mon Sep 17 00:00:00 2001
From: Bren Pike <brenpike@gmail.com>
Date: Fri, 25 Sep 2026 17:20:09 -0600
Subject: [PATCH 10/10] test(policy): pin checked-discovery containment

---
 tests/policy/safety-discovery-policy.json | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/tests/policy/safety-discovery-policy.json b/tests/policy/safety-discovery-policy.json
index 7a88165d..e990e0b4 100644
--- a/tests/policy/safety-discovery-policy.json
+++ b/tests/policy/safety-discovery-policy.json
@@ -1,8 +1,8 @@
 {
   "rule": "discovery-policy-checked-engine-present",
-  "description": "P3 consumer-assertion: the checked-discovery engine in tools/policy_check.sh is the single place the script's discovery policy lives -- every discovery find follows symlinks with `-L`, and anything a followed traversal cannot resolve is a finding, never a silent skip. Every scanning check discovers through it, so weakening it narrows every check's input set at once while each check still reports green. This fixture pins nine literals, each a single occurrence in the file, so deleting or rewriting any one of them is loud: `DISCOVERY_FIND_BASE=(-L)` (the policy itself -- without `-L`, find's default `-P` never descends a symlinked directory); the engine's find invocation `find \"${DISCOVERY_FIND_BASE[@]}\" \"${discovery_roots[@]}\" \"$@\" -print0` (the base array still reaches the one find the engine runs, so the `-L` assignment cannot stay in place while going unused); `discover_checked_paths() {` (the shared wrapper every call site uses is still defined under that name; deleting or renaming it also breaks every call site at run time, SAFETY's own fixture discovery included, so the run then fails through discovery findings before this fixture is evaluated -- this literal therefore turns red on its own only when the wrapper is re-declared in another form (such as `function discover_checked_paths {`), and a wrapper hollowed out under the same name is caught by the two call literals below, not by this one); inside it, `discovery_gate_status \"$checked_discovery_path\" \"$checked_discovery_gate\"` and `flag_discovery_gate \"$checked_discovery_rule\" \"$checked_discovery_path\" \"$checked_discovery_gate_rc\"` (each discovered path is still gated, and each rejection is still reported rather than dropped); `return \"$DISCOVERY_GATE_RC_NOT_REGULAR\"` (the `files` gate still rejects a name match that is not a regular file); `add_finding \"$rule_name\" \"$candidate_path\" 0` (the gate reporter still emits through the shared finding machinery, so --strict and the allowlist apply to it); the `=== DISCOVERY: Checked-discovery canary ===` banner and `add_finding 'DISCOVERY'` (the DISCOVERY canary section still exists and still reports through the shared finding machinery). superset mode fails if any literal is removed; extras elsewhere in the file are ignored. Behaviour this pin does not itself carry, but which the DISCOVERY canary asserts at run time over the committed fixtures under tests/policy/fixtures/discovery-canary (a real directory, a symlinked directory pointing at it, and a dangling link): that DISCOVERY_FIND_BASE is exactly the single element `-L`; that the engine descends the symlinked directory where a raw `find -P` does not; that the `files` gate rejects the dangling link as missing and a directory as not regular; that a nonexistent root propagates find's non-zero status; and that the wrapper keeps exactly the two regular files and emits exactly one finding, naming the dangling link. Residuals, stated plainly: a presence pin cannot prove meaning, and this fixture proves only that the canary section still announces itself and reports, not that its assertions still run correctly. Deleting the whole DISCOVERY canary section also aborts the run at CHECK 15's traversal canary, which reuses the canary's fixture paths, so the run fails before this fixture is evaluated; the two canary literals are the witness for a partial deletion that leaves those paths defined. The `files` gate's missing-path rejection is not pinned: its `return \"$DISCOVERY_GATE_RC_MISSING\"` line also appears in the `dirs` gate, so deleting one copy leaves the literal present -- only the canary's dangling-link gate probe witnesses it. A call site switched from the `files` gate to `raw`, or a new call site that discovers with its own find instead of the wrapper, leaves every pinned literal intact and this fixture green; no structural check counts raw finds, and the only raw finds outside the engine are the two comment-marked INTENTIONAL NON-HELPER FIND negative controls. A copy of a pinned literal added elsewhere in the file, such as a comment quoting it, masks deletion of the original. A symlink loop is not witnessed by any committed fixture; the canary witnesses the same non-zero find status through its nonexistent-root probe. A symlinked directory that points back inside a scanned root materialises the same file under two paths: it is scanned twice, no canary asserts that, and an allowlist entry keyed to one path does not cover the other. On a checkout with core.symlinks=false the committed symlink fixtures become plain files and the DISCOVERY canary fails loudly by design; this fixture itself stays green there. The sibling scripts under tools/ (validate.sh, validate_workflows.sh, validate_reports.sh, and the test_*.sh probes) do not use this engine, and nothing here covers their discovery.",
+  "description": "P3 consumer-assertion: the checked-discovery engine in tools/policy_check.sh is the single place the script's discovery policy lives -- every discovery find follows symlinks with `-L`, anything a followed traversal cannot resolve is a finding, never a silent skip, and no discovered path that resolves outside the checkout is ever handed to a check. Every scanning check discovers through it, so weakening it narrows every check's input set at once while each check still reports green. This fixture pins eighteen literals, each a single occurrence in the file, so deleting or rewriting any one of them is loud: `DISCOVERY_FIND_BASE=(-L)` (the policy itself -- without `-L`, find's default `-P` never descends a symlinked directory); the engine's find invocation `find \"${DISCOVERY_FIND_BASE[@]}\" \"${discovery_roots[@]}\" \"$@\" -print0` (the base array still reaches the one find the engine runs, so the `-L` assignment cannot stay in place while going unused); `discover_checked_paths() {` (the shared wrapper every call site uses is still defined under that name; deleting or renaming it also breaks every call site at run time, SAFETY's own fixture discovery included, so the run then fails through discovery findings before this fixture is evaluated -- this literal therefore turns red on its own only when the wrapper is re-declared in another form (such as `function discover_checked_paths {`), and a wrapper hollowed out under the same name is caught by the call literals below, not by this one); inside it, `discovery_gate_status \"$checked_discovery_path\" \"$checked_discovery_gate\"` and `flag_discovery_gate \"$checked_discovery_rule\" \"$checked_discovery_path\" \"$checked_discovery_gate_rc\"` (each discovered path is still gated, and each rejection is still reported rather than dropped); `return \"$DISCOVERY_GATE_RC_NOT_REGULAR\"` (the `files` gate still rejects a name match that is not a regular file); `add_finding \"$rule_name\" \"$candidate_path\" 0` (the gate reporter still emits through the shared finding machinery, so --strict and the allowlist apply to it); the `=== DISCOVERY: Checked-discovery canary ===` banner and `add_finding 'DISCOVERY'` (the DISCOVERY canary section still exists and still reports through the shared finding machinery); `DISCOVERY_GATE_RC_ESCAPES=27` (the containment rejection status keeps its own non-zero value, so it cannot be redefined to 0, which would turn every containment rejection into an accept); in the containment helper, `local containment_prefix=\"${REPO_ROOT%/}/\"` and `if [[ \"$containment_canonical\" == \"$REPO_ROOT\" || \"$containment_canonical\" == \"$containment_prefix\"* ]]; then` (the accept test still admits only the repository root itself or a path under the root followed by a slash, so a sibling directory whose name merely begins with the root's name does not match it), and `containment_canonical=\"$(realpath -m -- \"$containment_candidate\")\" || return \"$DISCOVERY_GATE_RC_ESCAPES\"` (each path is still canonicalised with `realpath -m` before the accept test, and a realpath failure is still a rejection, never an accept); inside the wrapper, `discovery_containment_status \"$checked_discovery_path\"` (every materialised path is still classified for containment) and `flag_discovery_gate \"$checked_discovery_rule\" \"$checked_discovery_escape_first\" \"$DISCOVERY_GATE_RC_ESCAPES\"` (escaping paths are still reported, as one capped finding, rather than silently dropped); and the three DISCOVERY escape-probe calls `expect_discovery_containment \"containment under the 'files' gate\" 0 files \"$dcanary_escape_root\"`, `expect_discovery_containment \"containment under the 'raw' gate\" 0 raw \"$dcanary_escape_root\"` and `expect_discovery_containment 'containment cap (escape root passed twice)' 1 files \"$dcanary_escape_root\" \"$dcanary_escape_root\"` (each is the only runtime witness of its case, and deleting one leaves every other assertion green). superset mode fails if any literal is removed; extras elsewhere in the file are ignored. Behaviour this pin does not itself carry, but which the DISCOVERY canary asserts at run time over the committed fixtures under tests/policy/fixtures/discovery-canary (a real directory, a symlinked directory pointing at it, and a dangling link): that DISCOVERY_FIND_BASE is exactly the single element `-L`; that the engine descends the symlinked directory where a raw `find -P` does not; that the `files` gate rejects the dangling link as missing and a directory as not regular; that a nonexistent root propagates find's non-zero status; and that the wrapper keeps exactly the two regular files and emits exactly one finding, naming the dangling link -- those two accepted in-checkout files are also the positive control for containment, so a containment step that rejected every path fails the canary. Over the committed fixture tests/policy/fixtures/discovery-escape-canary (escape.md, a file symlink whose target resolves outside the repository root), the canary asserts that under both the `files` and the `raw` gate the wrapper accepts nothing, returns 1, and emits exactly one finding, naming escape.md with the containment reason and zero further paths suppressed; and that with that root passed twice, so escape.md materialises twice, it still emits exactly one containment finding, counting one suppressed path. Residuals, stated plainly: a presence pin cannot prove meaning, and this fixture proves only that the canary section and its escape probes still exist, not that their assertions still run correctly. The containment pins prove the containment lines exist, not their order or reach: a helper hollowed by an early `return 0` ahead of its pinned lines, a containment call moved after the gate call, or a dropped `continue` that lets an escaping path fall through to the gate all leave every pinned literal intact; only the escape probes witness those. Containment stops the read, not the walk: find -L still traverses an external tree an escaping link leads into, and only the paths it materialises there are rejected. Only the first escaping path per wrapper call is named in the finding; the rest are counted, not listed. The realpath-failure branch is unreachable from find's output, because `realpath -m` canonicalises paths whose components need not exist; it has been exercised only by an out-of-suite unit probe, no committed canary witnesses it, and the pinned `|| return` on its line is its only standing guard. No committed fixture witnesses the sibling-prefix case either -- a path resolving under a directory beside the checkout whose name begins with the root's name -- so the pinned prefix and accept-test lines are its only standing guard. The root pre-classification gates -- the `dirs` checks on the SAFETY, COMPAT and workflow fixture roots and on each skill's scripts directory in CHECK 14 -- call discovery_gate_status directly and have no separate containment step, so a root that itself resolves outside the checkout passes its `dirs` check; every path discovered under it is still rejected by the wrapper's containment. Deleting the whole DISCOVERY canary section also aborts the run at CHECK 15's traversal canary, which reuses the canary's fixture paths, so the run fails before this fixture is evaluated; the canary literals are the witness for a partial deletion that leaves those paths defined. The `files` gate's missing-path rejection is not pinned: its `return \"$DISCOVERY_GATE_RC_MISSING\"` line also appears in the `dirs` gate, so deleting one copy leaves the literal present -- only the canary's dangling-link gate probe witnesses it. A call site switched from the `files` gate to `raw`, or a new call site that discovers with its own find instead of the wrapper, leaves every pinned literal intact and this fixture green; no structural check counts raw finds, and the only raw finds outside the engine are the two comment-marked INTENTIONAL NON-HELPER FIND negative controls. A copy of a pinned literal added elsewhere in the file, such as a comment quoting it, masks deletion of the original. A symlink loop is not witnessed by any committed fixture, whether inside the checkout or inside an external tree an escaping link leads into; the canary witnesses the same non-zero find status through its nonexistent-root probe. A symlinked directory that points back inside a scanned root materialises the same file under two paths: it is scanned twice, no canary asserts that, and an allowlist entry keyed to one path does not cover the other. On a checkout with core.symlinks=false the committed symlink fixtures, escape.md included, become plain files and the DISCOVERY canary fails loudly by design; this fixture itself stays green there. The sibling scripts under tools/ (validate.sh, validate_workflows.sh, validate_reports.sh, and the test_*.sh probes) do not use this engine, and nothing here covers their discovery.",
   "set_check": {
-    "extract_regex": "(DISCOVERY_FIND_BASE=\\(-L\\)|find \"\\$\\{DISCOVERY_FIND_BASE\\[@\\]\\}\" \"\\$\\{discovery_roots\\[@\\]\\}\" \"\\$@\" -print0|discover_checked_paths\\(\\) \\{|discovery_gate_status \"\\$checked_discovery_path\" \"\\$checked_discovery_gate\"|flag_discovery_gate \"\\$checked_discovery_rule\" \"\\$checked_discovery_path\" \"\\$checked_discovery_gate_rc\"|return \"\\$DISCOVERY_GATE_RC_NOT_REGULAR\"|add_finding \"\\$rule_name\" \"\\$candidate_path\" 0|=== DISCOVERY: Checked-discovery canary ===|add_finding 'DISCOVERY')",
+    "extract_regex": "(DISCOVERY_FIND_BASE=\\(-L\\)|find \"\\$\\{DISCOVERY_FIND_BASE\\[@\\]\\}\" \"\\$\\{discovery_roots\\[@\\]\\}\" \"\\$@\" -print0|discover_checked_paths\\(\\) \\{|discovery_gate_status \"\\$checked_discovery_path\" \"\\$checked_discovery_gate\"|flag_discovery_gate \"\\$checked_discovery_rule\" \"\\$checked_discovery_path\" \"\\$checked_discovery_gate_rc\"|return \"\\$DISCOVERY_GATE_RC_NOT_REGULAR\"|add_finding \"\\$rule_name\" \"\\$candidate_path\" 0|=== DISCOVERY: Checked-discovery canary ===|add_finding 'DISCOVERY'|DISCOVERY_GATE_RC_ESCAPES=27|local containment_prefix=\"\\$\\{REPO_ROOT%/\\}/\"|containment_canonical=\"\\$\\(realpath -m -- \"\\$containment_candidate\"\\)\" \\|\\| return \"\\$DISCOVERY_GATE_RC_ESCAPES\"|if \\[\\[ \"\\$containment_canonical\" == \"\\$REPO_ROOT\" \\|\\| \"\\$containment_canonical\" == \"\\$containment_prefix\"\\* \\]\\]; then|discovery_containment_status \"\\$checked_discovery_path\"|flag_discovery_gate \"\\$checked_discovery_rule\" \"\\$checked_discovery_escape_first\" \"\\$DISCOVERY_GATE_RC_ESCAPES\"|expect_discovery_containment \"containment under the 'files' gate\" 0 files \"\\$dcanary_escape_root\"|expect_discovery_containment \"containment under the 'raw' gate\" 0 raw \"\\$dcanary_escape_root\"|expect_discovery_containment 'containment cap \\(escape root passed twice\\)' 1 files \"\\$dcanary_escape_root\" \"\\$dcanary_escape_root\")",
     "expected_set": [
       "DISCOVERY_FIND_BASE=(-L)",
       "find \"${DISCOVERY_FIND_BASE[@]}\" \"${discovery_roots[@]}\" \"$@\" -print0",
@@ -12,7 +12,16 @@
       "return \"$DISCOVERY_GATE_RC_NOT_REGULAR\"",
       "add_finding \"$rule_name\" \"$candidate_path\" 0",
       "=== DISCOVERY: Checked-discovery canary ===",
-      "add_finding 'DISCOVERY'"
+      "add_finding 'DISCOVERY'",
+      "DISCOVERY_GATE_RC_ESCAPES=27",
+      "local containment_prefix=\"${REPO_ROOT%/}/\"",
+      "containment_canonical=\"$(realpath -m -- \"$containment_candidate\")\" || return \"$DISCOVERY_GATE_RC_ESCAPES\"",
+      "if [[ \"$containment_canonical\" == \"$REPO_ROOT\" || \"$containment_canonical\" == \"$containment_prefix\"* ]]; then",
+      "discovery_containment_status \"$checked_discovery_path\"",
+      "flag_discovery_gate \"$checked_discovery_rule\" \"$checked_discovery_escape_first\" \"$DISCOVERY_GATE_RC_ESCAPES\"",
+      "expect_discovery_containment \"containment under the 'files' gate\" 0 files \"$dcanary_escape_root\"",
+      "expect_discovery_containment \"containment under the 'raw' gate\" 0 raw \"$dcanary_escape_root\"",
+      "expect_discovery_containment 'containment cap (escape root passed twice)' 1 files \"$dcanary_escape_root\" \"$dcanary_escape_root\""
     ],
     "files": [
       { "path": "tools/policy_check.sh", "mode": "superset" }