@chrono-meta/fh-gate 3.1.3 → 3.2.0

package/scripts/finding_pipeline.sh

@@ -0,0 +1,213 @@
+#!/usr/bin/env bash
+# finding_pipeline.sh — the driver that runs fleet → cross-family reject → drop audit end to end.
+# Until this file the two halves existed but nothing called them together outside the lane suite.
+#
+#   bash scripts/finding_pipeline.sh <target-file> --out <dir> [--fleet <table>]
+#
+# WHY THE TWO-SPLIT SHAPE (the load-bearing design decision, not an implementation detail):
+# finding_verify.py refuses to let a family judge its own findings — it stamps them `unverified`
+# rather than judging. With a two-family fleet, ONE verify pass therefore leaves half the findings
+# unjudged, and an `unverified` finding still counts as a survivor. Running it that way and reporting
+# the survivor count would silently mean "half of these were never checked". So the run is split by
+# producer:
+#     gemini-produced  → verifier codex  → drop auditor gemini
+#     codex-produced   → verifier gemini → drop auditor codex
+#
+# 🟥 NAMED RESIDUAL — with only two families the drop auditor is ALWAYS the producer (an appeal),
+# never a disinterested third party. That is weaker than the protocol allows for, and it is a property
+# of the panel size. Do not read `AUDITED` from a two-family run as `independently audited`; the
+# per-finding `audit_role` field says which it was.
+# 🟥 AND A THIRD FAMILY DOES NOT COME FOR FREE. An earlier draft of this comment claimed the driver
+# "picks up a third family automatically". It cannot: finding_verifier.sh only speaks codex|gemini, so
+# an unknown family exits 2 and the drops come back unaudited (rc=4). Routing is therefore restricted
+# to families the wrapper actually implements — SUPPORTED below — and adding one means adding a
+# backend there first. (cross-family review, 2026-09-09; the claim was mine and was wrong.)
+#
+# EXIT  0 every split verified and every drop audited, with survivors · 1 verified but nothing survived
+#       2 usage / schema · 3 UNVERIFIED — some split was not cross-verified (degraded, never a silent
+#       pass) · 4 drops happened that were never audited
+set -uo pipefail
+
+SUPPORTED_FAMILIES="codex gemini"          # must match finding_verifier.sh's own case statement
+
+TARGET=""; OUT=""; FLEET=""
+usage() { echo "usage: finding_pipeline.sh <target-file> --out <dir> [--fleet <table>]" >&2; exit 2; }
+need() { [ $# -ge 2 ] || { echo "finding_pipeline: $1 needs a value" >&2; exit 2; }; }
+[ $# -ge 1 ] || usage
+TARGET="$1"; shift
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --out)   need "$@"; OUT="$2"; shift 2 ;;    # `shift 2` on a trailing flag consumes nothing and
+    --fleet) need "$@"; FLEET="$2"; shift 2 ;;  # spins forever; codex reproduced the hang.
+    *) usage ;;
+  esac
+done
+[ -n "$TARGET" ] && [ -f "$TARGET" ] && [ -r "$TARGET" ] \
+  || { echo "finding_pipeline: target must be a readable file" >&2; exit 2; }
+# 🟥 타깃이 심링크면 체크아웃 «밖»을 가리킬 수 있고, 그 내용은 외부 모델로 전송된다.
+#    리뷰하려던 것은 레포 코드인데 나가는 것은 남의 비밀이 된다 — residency 위반이다.
+#    강행이 필요하면 실제 파일 경로를 직접 주면 된다(그 판단은 사람이 한다).
+if [ -L "$TARGET" ]; then
+  echo "finding_pipeline: target is a symlink — refusing (it may point outside the checkout, and the content is SENT to an external model)" >&2
+  exit 2
+fi
+[ -n "$OUT" ] || usage
+# 🟥 출력물은 프롬프트와 소스를 담는다 — 권한을 좁혀서 만든다(umask 022 면 0644 로 남는다).
+umask 077
+mkdir -p "$OUT" || { echo "finding_pipeline: cannot create --out" >&2; exit 2; }
+# 🟥 미리 깔린 심링크를 따라가면 «출력»이 남의 파일 truncate 가 된다. 리다이렉션도 open() 도
+#    심링크를 따라간다 — 그래서 쓰기 «전»에 거부한다(cross-family review 2026-09-09).
+for _p in "$OUT" "$OUT/fleet" "$OUT/confirmed.jsonl" "$OUT/dropped.jsonl" "$OUT/splits.txt" "$OUT/families.txt"; do
+  if [ -L "$_p" ]; then
+    echo "finding_pipeline: refusing to write through a symlink: $_p" >&2; exit 2
+  fi
+done
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FLEET_SH="$HERE/finding_fleet.sh"; VERIFY_PY="$HERE/finding_verify.py"; VERIFIER_SH="$HERE/finding_verifier.sh"
+for f in "$FLEET_SH" "$VERIFY_PY" "$VERIFIER_SH"; do
+  [ -f "$f" ] || { echo "finding_pipeline: missing $f — skipped, NOT passed" >&2; exit 3; }
+done
+
+# 🟥 NO SHELL IN THIS PATH. An earlier version built a command STRING and quoted the interpolated
+# path with bash's `printf %q`. That was not enough, and the reason matters: finding_verify.py ran
+# the string with `shell=True`, i.e. `/bin/sh`, while `%q` emits **bash-only** `$'...'` quoting for a
+# path containing a newline. On the many Linux systems where `/bin/sh` is dash, that quoting comes
+# apart and a crafted filename executes a second command. 🟥 macOS CANNOT SEE THIS — its /bin/sh is
+# bash-derived, so the local run is green while the shipped package is not (cross-family review
+# 2026-09-09, reproduced on dash). The fix is not better escaping; it is handing argv, never a string.
+argv_json() {  # each argument becomes one JSON string — no shell ever parses these
+  ARGV_PY="$*" /usr/bin/python3 -c 'import json,os,sys; print(json.dumps(sys.argv[1:]))' "$@"
+}
+
+# ── 1. fleet ──────────────────────────────────────────────────────────────────────────────────────
+# A reused --out is not a fresh run: finding_fleet.sh concatenates EVERY part_*.jsonl it finds, so a
+# member that is absent this time still contributes yesterday's findings — which can silently supply
+# the second family and make a single-family run look cross-verified.
+/bin/rm -rf "$OUT/fleet"
+FA=(); [ -n "$FLEET" ] && FA=(--fleet "$FLEET")
+bash "$FLEET_SH" "$TARGET" --out "$OUT/fleet" ${FA[@]+"${FA[@]}"} 2>&1 | tee "$OUT/fleet_run.log"
+FLEET_RC=${PIPESTATUS[0]}
+FINDINGS="$OUT/fleet/findings.jsonl"
+if [ "$FLEET_RC" -ne 0 ] || [ ! -s "$FINDINGS" ]; then
+  echo "PIPELINE target=$(basename "$TARGET") fleet_rc=$FLEET_RC findings=0 status=UNREVIEWED"
+  echo "  🟥 an empty finding list is UNREVIEWED, not clean (finding_fleet.sh says so and this agrees)" >&2
+  exit 3
+fi
+# A fleet is "ok" when ONE member succeeded. A member that crashed after emitting a few findings still
+# leaves its family present, so the split routing below sees two families and the run looks complete.
+FAILED_MEMBERS=$(grep -c '^MEMBER .* rc=[^0]' "$OUT/fleet_run.log" 2>/dev/null); FAILED_MEMBERS=${FAILED_MEMBERS:-0}
+
+# ── 2. split by producer, verify each half with the other family ──────────────────────────────────
+# Families are read into a newline-delimited list and validated. An unquoted space-joined expansion
+# let a family literally named "codex gemini" split into two names that match no record, skipping
+# every finding while the run still exited 0.
+/usr/bin/python3 -c '
+import json,re,sys
+seen=[]
+for l in open(sys.argv[1],encoding="utf-8"):
+    l=l.strip()
+    if not l: continue
+    f=json.loads(l).get("producer_family")
+    if f is None: continue
+    if not re.fullmatch(r"[A-Za-z0-9_.-]+", str(f)):
+        sys.stderr.write("finding_pipeline: illegal producer_family %r — refusing to route\n" % (f,))
+        sys.exit(2)
+    if f not in seen: seen.append(f)
+print("\n".join(seen))' "$FINDINGS" > "$OUT/families.txt" 2>"$OUT/families.err"
+FAMRC=$?
+if [ "$FAMRC" -ne 0 ] || [ ! -s "$OUT/families.txt" ]; then
+  cat "$OUT/families.err" >&2
+  echo "finding_pipeline: findings carry no usable producer_family — cannot route" >&2; exit 3
+fi
+
+supported() { case " $SUPPORTED_FAMILIES " in *" $1 "*) return 0;; *) return 1;; esac; }
+pick_verifier() { # $1=producer — a DIFFERENT family the wrapper can actually run
+  local p="$1" f
+  while IFS= read -r f; do [ -n "$f" ] && [ "$f" != "$p" ] && supported "$f" && { echo "$f"; return; }; done < "$OUT/families.txt"
+  echo ""
+}
+pick_auditor() { # $1=producer $2=verifier — prefer a third party; fall back to producer (appeal)
+  local p="$1" v="$2" f
+  while IFS= read -r f; do
+    [ -n "$f" ] && [ "$f" != "$p" ] && [ "$f" != "$v" ] && supported "$f" && { echo "$f"; return; }
+  done < "$OUT/families.txt"
+  supported "$p" && { echo "$p"; return; }
+  echo ""
+}
+
+# Exit codes are TYPES, not severities — `max(0,1)` turned "one split found nothing" into the whole
+# run's verdict while a confirmed survivor sat in the other split. Rank them explicitly instead, and
+# derive 1-vs-0 from the survivor count at the end, never from a split.
+WORST_RANK=0; WORST_CODE=0
+rank_of() { case "$1" in 2) echo 4;; 3) echo 3;; 4) echo 2;; *) echo 0;; esac; }
+note_rc() { local r; r=$(rank_of "$1"); if [ "$r" -gt "$WORST_RANK" ]; then WORST_RANK="$r"; WORST_CODE="$1"; fi; }
+
+: > "$OUT/confirmed.jsonl"; : > "$OUT/dropped.jsonl"; : > "$OUT/splits.txt"
+
+while IFS= read -r PROD; do
+  [ -n "$PROD" ] || continue
+  VER="$(pick_verifier "$PROD")"
+  if [ -z "$VER" ]; then
+    echo "  ⚠️  split producer=$PROD — no other SUPPORTED family present; its findings cannot be cross-verified" >&2
+    note_rc 3; printf 'split producer=%s verifier=NONE rc=3 (no cross-family)\n' "$PROD" >> "$OUT/splits.txt"; continue
+  fi
+  AUD="$(pick_auditor "$PROD" "$VER")"
+  SD="$OUT/split_$PROD"
+  mkdir -p "$SD" || { echo "finding_pipeline: cannot create $SD" >&2; note_rc 2; continue; }
+  # An extraction that FAILS and an extraction that finds nothing are not the same event; the first
+  # draft's `[ -s ] || continue` read both as "empty partition" and left WORST at 0.
+  if ! /usr/bin/python3 -c '
+import json,sys
+prod=sys.argv[2]
+for l in open(sys.argv[1],encoding="utf-8"):
+    l=l.strip()
+    if l and json.loads(l).get("producer_family")==prod: print(l)' "$FINDINGS" "$PROD" > "$SD/in.jsonl"; then
+    echo "finding_pipeline: split extraction failed for producer=$PROD" >&2; note_rc 3; continue
+  fi
+  if [ ! -s "$SD/in.jsonl" ]; then
+    printf 'split producer=%s verifier=%s rc=0 (no findings)\n' "$PROD" "$VER" >> "$OUT/splits.txt"; continue
+  fi
+
+  AUDARGS=()
+  if [ -n "$AUD" ]; then
+    AUDARGS=(--audit-verifier-argv "$(argv_json bash "$VERIFIER_SH" --family "$AUD" --target "$TARGET" --audit)" --audit-family "$AUD")
+  else
+    echo "  ⚠️  split producer=$PROD — no supported auditor; any drop will come back UNAUDITED" >&2
+  fi
+  /usr/bin/python3 "$VERIFY_PY" "$SD/in.jsonl" --out "$SD" \
+    --verifier-argv "$(argv_json bash "$VERIFIER_SH" --family "$VER" --target "$TARGET")" --family "$VER" \
+    ${AUDARGS[@]+"${AUDARGS[@]}"} > "$SD/summary.txt" 2>"$SD/err.txt"
+  RC=$?
+  note_rc "$RC"
+  cat "$SD/summary.txt"
+  printf 'split producer=%s verifier=%s auditor=%s rc=%s\n' "$PROD" "$VER" "${AUD:-NONE}" "$RC" >> "$OUT/splits.txt"
+  [ -f "$SD/confirmed.jsonl" ] && cat "$SD/confirmed.jsonl" >> "$OUT/confirmed.jsonl"
+  [ -f "$SD/dropped.jsonl" ]   && cat "$SD/dropped.jsonl"   >> "$OUT/dropped.jsonl"
+done < "$OUT/families.txt"
+
+# 🟥 NOT `$(grep -c ... || echo 0)`: grep -c PRINTS "0" and ALSO exits 1 on no match, so the fallback
+# appends a second line and the count becomes "0\n0", which truncates the summary printf.
+count_lines() { local n; n=$(grep -c "$1" "$2" 2>/dev/null); printf '%s' "${n:-0}" | tr -d ' \n'; }
+TOTAL_CONF=$(count_lines '^{' "$OUT/confirmed.jsonl")
+TOTAL_DROP=$(count_lines '^{' "$OUT/dropped.jsonl")
+TOTAL_UNVER=$(count_lines '"verdict": *"unverified"' "$OUT/confirmed.jsonl")
+# An `unaudited` drop is NOT an audited one — counting it as such is how "we checked the deletions"
+# becomes true by wording alone.
+TOTAL_AUD=$(count_lines '"drop_verdict": *"\(correct-drop\|wrong-drop\|uncertain\)"' "$OUT/dropped.jsonl")
+TOTAL_WRONG=$(count_lines '"reinstated": *true' "$OUT/confirmed.jsonl")
+
+if [ "$FAILED_MEMBERS" -gt 0 ]; then
+  echo "  ⚠️  $FAILED_MEMBERS fleet member(s) exited non-zero — a member that crashed after emitting some findings leaves its family looking complete" >&2
+  note_rc 3
+fi
+
+RC_FINAL="$WORST_CODE"
+[ "$WORST_RANK" -eq 0 ] && [ "$TOTAL_CONF" -eq 0 ] && RC_FINAL=1
+
+printf 'PIPELINE target=%s families=%s confirmed=%s dropped=%s unverified=%s audited_drops=%s reinstated=%s failed_members=%s rc=%s\n' \
+  "$(basename "$TARGET")" "$(tr '\n' ',' < "$OUT/families.txt" | sed 's/,$//')" "$TOTAL_CONF" "$TOTAL_DROP" \
+  "$TOTAL_UNVER" "$TOTAL_AUD" "$TOTAL_WRONG" "$FAILED_MEMBERS" "$RC_FINAL"
+# `unverified` is reported on its own line rather than folded into `confirmed`, because folding it is
+# exactly the "not found rendered as zero" family this repo keeps re-finding.
+exit "$RC_FINAL"

package/scripts/finding_verifier.sh

@@ -0,0 +1,144 @@
+#!/usr/bin/env bash
+# finding_verifier.sh — the wrapper finding_verify.py's --verifier contract asks for, and which did
+# not exist. Reads findings JSONL on stdin, writes verdict JSONL on stdout:
+#     {"id","verdict":"confirmed|false-positive|needs-debate","why"}
+# With --audit it answers the drop-audit protocol instead:
+#     {"id","verdict":"correct-drop|wrong-drop|uncertain","why"}
+#
+# WHY THIS EXISTS: finding_verify.py runs whatever shell command you hand it. Until this file, the
+# only commands that satisfied its protocol were the hardcoded stubs inside the lane suite, so the
+# pipeline could only ever report status=UNVERIFIED (rc=3) against real findings. A pipeline whose
+# only live path is its own fixture is not wired (CLAUDE.md §built-but-not-wired).
+#
+# 🟥 THE VERIFIER MUST SEE THE CODE, NOT ONLY THE CLAIM. A verdict on "is this finding real" that is
+# reached from the claim text alone measures plausibility, not truth — the model agrees with a
+# well-written wrong claim. So --target is REQUIRED and its content is put in front of the model.
+#
+# EXIT  0 answered · 2 usage · 3 the CLI failed or produced no parsable verdict (caller degrades;
+#       finding_verify.py turns an empty answer into `unverified`, never into a silent pass)
+set -uo pipefail
+
+CODEX="${FH_CODEX_BIN:-$(command -v codex 2>/dev/null || echo "$HOME/.npm-global/bin/codex")}"
+AGY="${FH_AGY_BIN:-$(command -v agy 2>/dev/null || echo "$HOME/.local/bin/agy")}"
+
+FAMILY=""; TARGET=""; MODE="verify"; KEEP=""
+usage() { echo "usage: finding_verifier.sh --family codex|gemini --target <file> [--audit] [--keep <dir>]" >&2; exit 2; }
+# `shift 2` with only one word left FAILS and consumes nothing, so the loop spins forever. Under
+# `set -uo pipefail` (no errexit) nothing stops it. codex reproduced a hang on a trailing --family.
+need() { [ $# -ge 2 ] || { echo "finding_verifier: $1 needs a value" >&2; exit 2; }; }
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --family) need "$@"; FAMILY="$2"; shift 2 ;;
+    --target) need "$@"; TARGET="$2"; shift 2 ;;
+    --audit)  MODE="audit"; shift ;;
+    --keep)   need "$@"; KEEP="$2"; shift 2 ;;
+    *) usage ;;
+  esac
+done
+[ -n "$FAMILY" ] || usage
+# `-f` is a TYPE test, not a readability test: an unreadable regular file passes it, the later `cat`
+# fails silently, and the model then judges claims WITHOUT the source — which is the one thing the
+# header above says must never happen. Test readability, and check the read itself below.
+[ -n "$TARGET" ] && [ -f "$TARGET" ] && [ -r "$TARGET" ] \
+  || { echo "finding_verifier: --target must name a readable file" >&2; exit 2; }
+# 🟥 심링크 거부 — 이 파일의 내용은 «외부 모델로 전송»된다. 체크아웃 안의 링크가 바깥
+#    자격증명을 가리키면, 리뷰하려던 코드 대신 그 비밀이 프롬프트가 된다(residency 위반).
+#    cross-family security review 2026-09-09.
+if [ -L "$TARGET" ]; then
+  echo "finding_verifier: --target is a symlink — refusing (content is SENT to an external model)" >&2
+  exit 2
+fi
+# 프롬프트 파일은 소스 전문을 담는다 — 0644 로 남기지 않는다.
+umask 077
+
+WORK="$(mktemp -d 2>/dev/null)" || { echo "finding_verifier: mktemp failed" >&2; exit 3; }
+cleanup() { [ -n "$KEEP" ] && cp "$WORK"/* "$KEEP"/ 2>/dev/null; rm -rf "$WORK"; }
+trap cleanup EXIT
+
+cat > "$WORK/findings.jsonl"
+if [ ! -s "$WORK/findings.jsonl" ]; then exit 0; fi   # nothing asked, nothing to answer
+
+if [ "$MODE" = "verify" ]; then
+  HEAD='You are an independent verifier from a different model family than the reviewer who wrote the
+claims below. For EACH claim decide whether it is real, judged against the file itself.
+
+Output ONLY JSON Lines, one object per claim id, nothing else — no prose, no code fences:
+{"id":"<the id verbatim>","verdict":"confirmed|false-positive|needs-debate","why":"<one line, cite the line number you checked>"}
+
+confirmed      = you read the cited location and the described failure can actually occur there.
+false-positive = the location does not say what the claim says, or the failure cannot occur.
+needs-debate   = it depends on a caller or config you cannot see from this file alone.
+
+Answer for EVERY id. Do not invent ids. Do not add findings of your own.'
+else
+  HEAD='You are auditing DELETIONS made by a different reviewer. Each record below is a claim that was
+dropped as a false positive. For EACH one decide whether dropping it was right, judged against the file.
+
+Output ONLY JSON Lines, one object per id, nothing else — no prose, no code fences:
+{"id":"<the id verbatim>","verdict":"correct-drop|wrong-drop|uncertain","why":"<one line, cite the line number you checked>"}
+
+correct-drop = the claim really was wrong; deleting it was right.
+wrong-drop   = the claim was true and was deleted in error (it will be reinstated).
+uncertain    = you cannot tell from this file alone.
+
+Answer for EVERY id. A drop you cannot justify is not "correct" by default.'
+fi
+
+{ printf '%s\n\n===== CLAIMS =====\n' "$HEAD"; cat "$WORK/findings.jsonl"
+  printf '\n===== FILE: %s =====\n' "$(basename "$TARGET")"; cat "$TARGET"; } > "$WORK/prompt.txt" \
+  || { echo "finding_verifier: could not build the prompt (source unreadable?)" >&2; exit 3; }
+# A prompt that does not actually contain the file is a verdict reached from the claim text alone.
+if ! grep -q "===== FILE: $(basename "$TARGET") =====" "$WORK/prompt.txt"; then
+  echo "finding_verifier: source did not reach the prompt — refusing to ask" >&2; exit 3
+fi
+
+case "$FAMILY" in
+  codex)  "$CODEX" exec --sandbox read-only --skip-git-repo-check -m gpt-6-astra \
+            -c model_reasoning_effort="high" < "$WORK/prompt.txt" > "$WORK/raw.txt" 2>"$WORK/err.txt" ;;
+  gemini) "$AGY" --model gemini-3.8-flash-high --output-format text --print-timeout 5m \
+            -p "$(cat "$WORK/prompt.txt")" < /dev/null > "$WORK/raw.txt" 2>"$WORK/err.txt" ;;
+  *) echo "finding_verifier: unknown family '$FAMILY' (codex|gemini)" >&2; exit 2 ;;
+esac
+RC=$?
+
+# The CLI's own exit code is not the WHOLE verdict — codex has exited non-zero while still printing
+# usable output, and zero while printing none — but the first draft used it for nothing at all, which
+# made the "cli failed" guard decorative (cross-family finding, 2026-09-09). It is now one of two
+# inputs: a non-zero CLI that nevertheless answered EVERY claim asked is reported and allowed; a
+# non-zero CLI that answered only some is a degraded run (exit 3), because the missing answers and the
+# crash have the same cause and "fewer verdicts" would otherwise read as "fewer problems".
+ASKED=$(grep -c '^{' "$WORK/findings.jsonl" 2>/dev/null); ASKED=${ASKED:-0}
+MODE="$MODE" /usr/bin/python3 - "$WORK/raw.txt" <<'PY'
+import json, os, sys
+allowed = (("confirmed", "false-positive", "needs-debate") if os.environ["MODE"] == "verify"
+           else ("correct-drop", "wrong-drop", "uncertain"))
+n = 0
+for line in open(sys.argv[1], encoding="utf-8", errors="replace"):
+    line = line.strip().lstrip("")
+    if not line.startswith("{"):
+        continue                       # tolerate banners and fences, same as finding_fleet.sh
+    try:
+        d = json.loads(line)
+    except json.JSONDecodeError:
+        continue
+    if not d.get("id") or d.get("verdict") not in allowed:
+        continue                       # an out-of-enum verdict is dropped, never coerced
+    n += 1
+    print(json.dumps({"id": d["id"], "verdict": d["verdict"], "why": d.get("why", "")},
+                     ensure_ascii=False))
+open(os.path.join(os.path.dirname(sys.argv[1]), "n_answered"), "w").write(str(n))
+sys.exit(0 if n else 3)
+PY
+PRC=$?
+if [ "$PRC" -ne 0 ]; then
+  echo "finding_verifier: family=$FAMILY mode=$MODE cli_rc=$RC — no parsable verdict" >&2
+  head -c 400 "$WORK/err.txt" >&2 2>/dev/null
+  exit 3
+fi
+ANSWERED=$(cat "$WORK/n_answered" 2>/dev/null); ANSWERED=${ANSWERED:-0}
+if [ "$RC" -ne 0 ] && [ "$ANSWERED" -lt "$ASKED" ]; then
+  echo "finding_verifier: family=$FAMILY mode=$MODE cli_rc=$RC answered=$ANSWERED/$ASKED — partial answer from a failed CLI, degrading" >&2
+  exit 3
+fi
+[ "$RC" -ne 0 ] && echo "finding_verifier: family=$FAMILY cli_rc=$RC but answered $ANSWERED/$ASKED — allowed, recorded" >&2
+exit 0

package/scripts/finding_verify.py

@@ -0,0 +1,283 @@
+#!/usr/bin/env python3
+"""finding_verify.py — typed review findings in, cross-family verdicts on, false positives dropped BY CODE.
+
+WHY THIS EXISTS. FH's review output is prose end to end: a governor reads, judges, and writes. Nothing
+in that path can be counted, filtered, or handed to a second family, because a prose finding has no
+fields. Measured 2026-09-08 on eight GHSA cases x3: FH's review made 52 claims of which 5 were wrong
+about the code (9.6%); a sibling harness (octo) made 73 claims -- 40% MORE -- with 2 wrong (2.7%). Its
+advantage is not better reading. Its pipeline emits findings as typed JSON, has a different-family
+agent stamp each one `confirmed|false-positive|needs-debate`, and then DELETES the false positives with
+a filter. Judgment stays with a model; the drop is mechanical. This script is that stage for FH.
+
+WHAT IS MECHANIZED AND WHAT IS NOT (CLAUDE.md 'Mechanization Boundary'). The channel is mechanized:
+every finding carries a verdict, the verdict comes from a command that is not the author, the drop is
+performed by code, and what was dropped is written down. The judgment -- is this claim true of the
+source -- is made by whatever model the verifier command runs, never frozen here. This file contains
+no rule about what makes a finding wrong.
+
+DEGRADE DIRECTION. A review surface is reversible, so an unreachable verifier does not block. It must
+not be silent either: with no verifier every finding is stamped `unverified`, NOTHING is dropped, the
+status is UNVERIFIED and the exit code says so. An unverified run must never read as a clean one.
+
+THE DROP SIDE IS MEASURED TOO, OR THE RUN SAYS IT WAS NOT. A stage that deletes claims improves any
+precision number for free: delete enough and nothing wrong survives. So the error rate of the SURVIVORS
+is not a result on its own — it is only meaningful beside the error rate of the DELETIONS. Measured on
+this pipeline's first real use, 2026-09-08: the verifier dropped a claim that the project's own earlier
+record grades a real A-tier defect. One drop, one wrong. That is why `--audit-verifier` exists and why
+the summary line carries `drop_audit=UNAUDITED` in bold terms when drops happened and nobody checked
+them. The auditor must not be the family that made the drop; when it is the family that PRODUCED the
+finding, that is an appeal by an interested party and is recorded as `audit_role=appeal`, not hidden.
+
+INPUT   JSONL, one finding per line:
+        {"id","file","line","severity","category","title","detail","confidence","producer_family"}
+        `id` and `title` are required; the rest are optional and pass through untouched.
+        When `producer_family` is present and equals the verifier's family, that finding is stamped
+        `unverified` rather than judged -- see the note above VERDICTS.
+AUDITOR   Optional, and required for the drop-side number to exist. Same protocol as the verifier, but
+        it receives only the DROPPED findings and answers {"id","verdict":"correct-drop|wrong-drop|
+        uncertain","why"}. A `wrong-drop` finding is moved back into confirmed.jsonl with
+        `reinstated: true` -- the audit is not advisory, it reverses the deletion.
+VERIFIER  A command that reads the findings JSONL on stdin and writes JSONL verdicts on stdout:
+        {"id","verdict":"confirmed|false-positive|needs-debate","why"}
+        Set it with --verifier or FH_VERIFY_CMD. Run it as a DIFFERENT model family than the author;
+        this script cannot check that, and says so rather than pretending to.
+OUTPUT  <out>/confirmed.jsonl  survivors (confirmed + needs-debate, the latter flagged)
+        <out>/dropped.jsonl    false positives, with the verifier's reason -- never silent
+        stdout                 one summary line, machine-readable
+EXIT    0 verified and (no drops, or drops audited) with >=1 survivor · 1 same but nothing survives
+        3 UNVERIFIED (degraded) · 4 drops happened and were never audited · 2 usage or schema error
+"""
+import argparse, json, os, subprocess, sys
+
+REQUIRED = ("id", "title")
+VERDICTS = ("confirmed", "false-positive", "needs-debate")
+AUDIT_VERDICTS = ("correct-drop", "wrong-drop", "uncertain")
+
+# A finding is never verified by the family that produced it. That is the one property of the record
+# this file enforces on its own: same-family review shares the author's blind spot, so a verdict from
+# the producer is not a second opinion. It is a channel rule, not a judgment -- the script does not
+# decide whether the claim is true, only that the party answering must not be the party asking.
+
+
+def read_findings(path):
+    out, seen = [], set()
+    src = sys.stdin if path == "-" else open(path, encoding="utf-8")
+    for n, line in enumerate(src, 1):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            d = json.loads(line)
+        except json.JSONDecodeError as e:
+            raise SystemExit(f"finding_verify: line {n} is not JSON: {e}")
+        for k in REQUIRED:
+            if not d.get(k):
+                raise SystemExit(f"finding_verify: line {n} missing required field '{k}'")
+        if d["id"] in seen:
+            raise SystemExit(f"finding_verify: duplicate id {d['id']!r} on line {n}")
+        seen.add(d["id"])
+        out.append(d)
+    return out
+
+
+def run_verifier(cmd, findings, allowed=VERDICTS):
+    """Returns (verdicts_by_id, error_or_None). Any failure degrades; it never raises.
+
+    `allowed` is the verdict vocabulary. The audit pass speaks a different one, and a verdict outside
+    the expected set is dropped rather than coerced -- a stage that silently reinterprets an unknown
+    label is how an unanswered question becomes an answer."""
+    payload = "\n".join(json.dumps(f, ensure_ascii=False) for f in findings) + "\n"
+    # 🟥 A LIST MEANS argv; A STRING MEANS A SHELL. The caller decides, and the shipped caller
+    # (finding_pipeline.sh) now hands a list, so no shell parses our paths.
+    #
+    # Why this branch exists (cross-family security review, 2026-09-09, reproduced on dash):
+    # the string form is executed with `shell=True`, i.e. by `/bin/sh`. Quoting the interpolated
+    # path with bash's `printf %q` is NOT enough, because %q emits bash-only `$'...'` for a path
+    # containing a newline, and `/bin/sh` on most Linux distributions is **dash**, which does not
+    # understand that syntax -- the quoting comes apart and a crafted filename executes a second
+    # command. macOS cannot observe this at all: its /bin/sh is bash-derived, so a local run is
+    # green while the shipped npm package is not. The fix is not better escaping; it is not
+    # handing a shell the string in the first place.
+    shell = isinstance(cmd, str)
+    try:
+        p = subprocess.run(cmd, shell=shell, input=payload, capture_output=True,
+                           text=True, timeout=int(os.environ.get("FH_VERIFY_TIMEOUT", "600")))
+    except Exception as e:                                   # noqa: BLE001 - degrade on anything
+        return {}, f"verifier did not run: {e}"
+    if p.returncode != 0:
+        return {}, f"verifier exit {p.returncode}: {(p.stderr or '').strip()[:200]}"
+    got = {}
+    for line in p.stdout.splitlines():
+        line = line.strip()
+        if not line or not line.startswith("{"):
+            continue                                          # tolerate chatter around the JSONL
+        try:
+            d = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if d.get("id") and d.get("verdict") in allowed:
+            got[d["id"]] = d
+    if not got:
+        return {}, "verifier returned no parseable verdict"
+    return got, None
+
+
+def main():
+    ap = argparse.ArgumentParser(add_help=True)
+    ap.add_argument("findings", help="JSONL file, or - for stdin")
+    ap.add_argument("--out", required=True, help="directory for confirmed.jsonl / dropped.jsonl")
+    ap.add_argument("--verifier-argv", default=None,
+                    help="JSON array form of --verifier. Executed as argv (no shell), which is the "
+                         "only form immune to path-shaped injection. Wins over --verifier.")
+    ap.add_argument("--audit-verifier-argv", default=None,
+                    help="JSON array form of --audit-verifier. Same reason.")
+    ap.add_argument("--verifier", default=os.environ.get("FH_VERIFY_CMD", ""),
+                    help="shell command; findings JSONL on stdin, verdict JSONL on stdout")
+    ap.add_argument("--family", default=os.environ.get("FH_VERIFY_FAMILY", "unstated"),
+                    help="model family of the verifier, recorded verbatim and never checked")
+    ap.add_argument("--audit-verifier", default=os.environ.get("FH_AUDIT_CMD", ""),
+                    help="command that re-checks the DROPPED findings; without it the run is UNAUDITED")
+    ap.add_argument("--audit-family", default=os.environ.get("FH_AUDIT_FAMILY", "unstated"),
+                    help="model family of the auditor; must differ from the verifier's")
+    a = ap.parse_args()
+
+    # argv 형태가 있으면 그것이 실행 형태다 — 문자열은 셸을 타므로 후순위다.
+    def _as_argv(raw, label):
+        if not raw:
+            return None
+        try:
+            v = json.loads(raw)
+        except json.JSONDecodeError as e:
+            raise SystemExit("%s must be a JSON array: %s" % (label, e))
+        if not (isinstance(v, list) and v and all(isinstance(x, str) for x in v)):
+            raise SystemExit("%s must be a non-empty JSON array of strings" % label)
+        return v
+
+    a.verifier = _as_argv(a.verifier_argv, "--verifier-argv") or a.verifier
+    a.audit_verifier = _as_argv(a.audit_verifier_argv, "--audit-verifier-argv") or a.audit_verifier
+
+    # 문자열이든 리스트든 «비어 있나»를 같은 방법으로 묻는다 — 리스트에 .strip() 은 없다.
+    def _configured(cmd):
+        return bool(cmd) if isinstance(cmd, list) else bool(str(cmd or "").strip())
+
+    findings = read_findings(a.findings)
+    os.makedirs(a.out, exist_ok=True)
+
+    if not _configured(a.verifier):
+        verdicts, err = {}, "no verifier configured (--verifier / FH_VERIFY_CMD)"
+    else:
+        verdicts, err = run_verifier(a.verifier, findings)
+
+    confirmed, dropped, debate, unverified = [], [], 0, 0
+    for f in findings:
+        v = verdicts.get(f["id"])
+        if v is None:
+            # Degraded, or the verifier skipped this one. Keep it, mark it, never drop it silently.
+            f = dict(f, verdict="unverified",
+                     verify_note=err or "verifier returned no verdict for this finding")
+            unverified += 1
+            confirmed.append(f)
+            continue
+        prod = f.get("producer_family")
+        # 🟥 ABSENT is not CLEAN. This guard is the one property this file claims to enforce, and
+        # until 2026-09-09 it hung on an OPTIONAL field: omit `producer_family` and the check was
+        # skipped entirely, so a family verified its own findings and the run reported
+        # `status=VERIFIED rc=0`. Reproduced with a known pair — same table, same verifier, the
+        # field the only difference: with it `unverified=1 rc=3`, without it `confirmed=1 rc=0`.
+        # A missing producer cannot PROVE the verifier is not the author, so the fail-closed
+        # answer is the same one an actual self-verification gets: `unverified`, never a silent
+        # pass. (The wired path never reached this — `finding_pipeline.sh` refuses to route a
+        # table with no usable `producer_family` (exit 3) and `finding_fleet.sh` always stamps it
+        # — but this script ships its own CLI, and a hand-built table is a supported entry point.)
+        if not prod:
+            f = dict(f, verdict="unverified", verify_note="finding declares no producer_family; "
+                     f"cannot establish that the verifier ({a.family}) is not its author")
+            unverified += 1
+            confirmed.append(f)
+            continue
+        if prod == a.family:
+            f = dict(f, verdict="unverified", verify_note="verifier is the producing family "
+                     f"({a.family}); a finding is not verified by its own author")
+            unverified += 1
+            confirmed.append(f)
+            continue
+        f = dict(f, verdict=v["verdict"], verify_why=v.get("why", ""), verify_family=a.family)
+        if v["verdict"] == "false-positive":
+            dropped.append(f)
+        else:
+            if v["verdict"] == "needs-debate":
+                debate += 1
+            confirmed.append(f)
+
+    # ── drop audit ────────────────────────────────────────────────────────────────────────────────
+    # Nothing here judges whether a drop was right; it routes the question to a party that did not make
+    # the drop, and moves a reversed drop back. The refusal to report a bare precision number when this
+    # did not run is the mechanized part.
+    audited = wrong_drops = reinstated = 0
+    audit_status = "UNAUDITED"
+    audit_note = ""
+    if dropped and _configured(a.audit_verifier):
+        if a.audit_family == a.family:
+            audit_note = ("auditor is the family that made the drop (%s) -- refused; a deletion is not "
+                          "checked by the party that made it" % a.family)
+        else:
+            av, aerr = run_verifier(a.audit_verifier, dropped, AUDIT_VERDICTS)
+            if aerr:
+                audit_note = "auditor did not answer: " + aerr
+            else:
+                kept = []
+                for d in dropped:
+                    r = av.get(d["id"])
+                    if r is None:
+                        kept.append(dict(d, drop_verdict="unaudited"))
+                        continue
+                    audited += 1
+                    role = "appeal" if d.get("producer_family") == a.audit_family else "independent"
+                    d = dict(d, drop_verdict=r["verdict"], drop_why=r.get("why", ""),
+                             audit_family=a.audit_family, audit_role=role)
+                    if r["verdict"] == "wrong-drop":
+                        wrong_drops += 1
+                        reinstated += 1
+                        confirmed.append(dict(d, reinstated=True))
+                    else:
+                        kept.append(d)
+                dropped = kept
+                # 🟥 AUDITED must mean EVERY drop was answered. Setting it unconditionally let an
+                # auditor that answered one unrelated id produce `audited=0 drop_audit=AUDITED` and
+                # exit 0 — the deletions went unchecked while the record said they were checked.
+                # (cross-family review 2026-09-09, reproduced; an EMPTY audit already returned 4, so
+                # the hole was specifically the PARTIAL answer.) A partial audit is not an audit.
+                unanswered = sum(1 for d in dropped if d.get("drop_verdict") == "unaudited")
+                if unanswered:
+                    audit_status = "PARTIAL"
+                    audit_note = ("auditor answered %d of %d drops; %d unanswered — a partial audit "
+                                  "is not an audit" % (audited, audited + unanswered, unanswered))
+                else:
+                    audit_status = "AUDITED"
+    elif not dropped:
+        audit_status = "NO-DROPS"
+
+    for name, rows in (("confirmed.jsonl", confirmed), ("dropped.jsonl", dropped)):
+        with open(os.path.join(a.out, name), "w", encoding="utf-8") as fh:
+            for r in rows:
+                fh.write(json.dumps(r, ensure_ascii=False) + "\n")
+
+    status = "UNVERIFIED" if unverified else "VERIFIED"
+    print("FINDINGS in={} confirmed={} dropped={} debate={} unverified={} family={} status={}{}".format(
+        len(findings), len(confirmed) - unverified, len(dropped), debate, unverified,
+        a.family, status, "" if not err else " reason=" + err.replace("\n", " ")))
+    # 🟥 The drop line is unconditional. A survivor-side number without it is a precision claim made by
+    # deleting, and this pipeline does not let a reader compute one without seeing whether the
+    # deletions were checked.
+    print("DROPS dropped={} audited={} wrong_drops={} reinstated={} auditor={} drop_audit={}{}".format(
+        len(dropped), audited, wrong_drops, reinstated, a.audit_family, audit_status,
+        "" if not audit_note else " reason=" + audit_note.replace("\n", " ")))
+    if unverified:
+        return 3
+    if audit_status in ("UNAUDITED", "PARTIAL"):
+        return 4                      # drops happened and nobody checked them: not a completed run
+    return 0 if confirmed else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/gate_pathspec_check.sh

@@ -230,6 +230,7 @@ else
     'CLAUDE.md|CLAUDE\.md' \
     'AGENTS.md|AGENTS\.md' \
     'scripts/**/*.sh|scripts/\*\*/\*\.sh' \
+    'scripts/**/*.py|scripts/\*\*/\*\.py' \
     'agent definitions (plugins/*/agents)|plugins/\*/agents/' \
     'agent definitions (.claude/agents)|\.claude/agents/'
   do