@chrono-meta/fh-gate 1.4.96 → 1.4.98

package/scripts/package_coverage_check.sh

@@ -21,28 +21,6 @@ set -uo pipefail
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$REPO_ROOT" || exit 1
 
-# Source-checkout test uses `-e`, not `-d`. In a git WORKTREE `.git` is a FILE (a gitdir pointer),
-# so the old `-d` test read every worktree as "installed package" and skipped the check entirely —
-# silently, with exit 0. Measured 2026-07-31: a worktree created specifically to approximate CI
-# reported PASS while this check had not run at all, i.e. the instrument used to justify wiring CI
-# was itself fail-open on the surface it was standing in. `-e` covers both the ordinary checkout
-# (dir) and the worktree (file); genuine package mode has no `.git` of either kind, so it still
-# skips. Anchored by scripts/test_package_coverage_lanes.sh.
-if [ ! -e .git ]; then
-  echo "SKIP  package-coverage (not a source checkout)"
-  exit 0
-fi
-# PREDICATE SPLIT (cross-family review, 2026-07-31). These were one condition, and folding them
-# together meant `.git` present + manifest missing returned SKIP + exit 0 — "we are in a checkout
-# and cannot read what ships" reported as "nothing to check here". Absence of the input is not
-# absence of the defect; `not found != 0` (CLAUDE.md §Instrument-Calibration). Only the no-.git
-# case is a legitimate skip (an installed package, where the un-shipped files are correctly gone).
-if [ ! -f package.json ]; then
-  echo "FAIL  package-coverage: source checkout with no package.json — the shipped file list is"
-  echo "      unreadable, so coverage is UNMEASURED, not clean"
-  exit 1
-fi
-
 # ── Accepted-absent, with the reason each one is NOT a defect ────────────────────────────────
 # Adding a line here is a decision, not a silencer: each entry states why shipping it would be
 # wrong. If you cannot write that sentence, the file probably belongs in files[].
@@ -58,6 +36,8 @@ fi
 #        a file of that name to exercise the LOW allowlist — not a pointer to this file at all.)
 #   scripts/sync_guard_check.sh             — anchor for that same operator-private mirror sync;
 #       no shipped hook invokes it.
+#   scripts/sync_to_be_lanes.sh             — forward-path lane suite for sync-to-be.sh, itself
+#       ACCEPTED_ABSENT above; added 2026-08-14, pmh-dev#69.
 ACCEPTED_ABSENT=(
   ".claude/registry/LOCAL_SKILL_REGISTRY.md"
   # An INSTALL DESTINATION the user creates (`cp templates/local_fh_context.md
@@ -79,6 +59,60 @@ ACCEPTED_ABSENT=(
   # anchor but guards on the subject's presence, so package mode SKIPs rather than falling through.
   "scripts/sync-from-be.sh"
   "scripts/sync_from_be_lanes.sh"
+  # Forward path's own lane suite (added 2026-08-14, pmh-dev#69). Same reason as its return-path
+  # sibling directly above: it exercises scripts/sync-to-be.sh, itself ACCEPTED_ABSENT — a lane
+  # suite for a script that never ships has nothing to verify on a consumer's machine either.
+  "scripts/sync_to_be_lanes.sh"
+  # Shared identity resolver for the two transports directly above (added to files[] by #368,
+  # REMOVED from it 2026-08-15). It was the odd one out: its own callers — sync-to-be.sh and
+  # sync-from-be.sh — are ACCEPTED_ABSENT here for a reason that applies to it verbatim (the
+  # namespacing it computes only means anything on a machine that HAS the operator's companion
+  # store), yet it alone was listed for shipping. The pre-publish confidentiality scan is what
+  # surfaced the misclassification: it carries the companion store's own directory vocabulary,
+  # which would have reached the registry for the first time in 1.4.98. The one shipped caller,
+  # fh_session_load.sh, sources it behind `[ -f ]` and documents its own degrade ("an unresolved
+  # identity degrades to the historical unsuffixed tracks-meta rather than erroring — that is the
+  # pre-fix behavior, not a new failure mode"), so a consumer loses nothing that consumer ever had.
+  "scripts/fh_hub_identity.sh"
+  # ── The three lane suites selfcheck.sh's DEBT-12 pair-loop names but does not ship ────────────
+  # Added 2026-08-13, and the way they got here is the point: this check CAUGHT them. Before that
+  # loop existed, these names lived in lane_runner_check.sh's DEBT array as bare basenames
+  # ("test_chamber_run_lanes.sh"), which the extractor's `scripts/…\.(sh|py)` pattern does not
+  # match. Writing the same names as full paths in a SHIPPED file (selfcheck.sh) is what turned
+  # them into phantoms — a shipped document pointing at a file the package omits. The source-tree
+  # selfcheck went red on the first full run after the wiring, exactly as an adversarial review had
+  # predicted from static reading alone. Recorded here rather than "fixed" by dropping the prefix,
+  # because the prefix is what makes lane_runner_check.sh's direct-invocation detector see the
+  # wiring at all; removing it would trade a loud failure for a silent blind spot.
+  #
+  # Why each is legitimately unshipped — and one of them is a NAMED RESIDUAL, not a clean answer:
+  #   · test_frontier_digest_retry.sh — its subject, scripts/frontier_digest_daily.sh, is itself
+  #     ACCEPTED_ABSENT (a launchd cadence runner for this operator's machine). Anchor follows
+  #     subject; a consumer has nothing for it to measure.
+  #   · test_residency_closure_lanes.sh — same shape: residency_closure_scan.py does not ship, so
+  #     its calibration has no subject on a consumer machine.
+  #   · test_chamber_run_lanes.sh — 🟥 NOT the same shape. Its subject scripts/chamber_run.sh DOES
+  #     ship. So a consumer receives the chamber runner and no calibration for it: a shipped gate
+  #     whose known-pair cannot execute on the machine that runs the gate. That is the defect class
+  #     this whole campaign is closing, one layer over. It is entered here rather than shipped
+  #     because adding an anchor to files[] is a consumer-facing change that needs its own
+  #     tarball-mode run to prove it does not false-FAIL, and this delta is a WIRING delta. The
+  #     honest state is "declared, and the declaration records a debt" — carried to the card.
+  "scripts/test_chamber_run_lanes.sh"
+  "scripts/test_frontier_digest_retry.sh"
+  "scripts/residency_closure_scan.py"
+  "scripts/test_residency_closure_lanes.sh"
+  # ── The two settings destinations, surfaced 2026-08-13 by fixing this file's own extractor ────
+  # These were invisible until the `js|json` alternation below was corrected: every `.json`
+  # reference in every shipped doc was being truncated to `.js`, a path that exists nowhere, so
+  # `os.path.exists()` dropped it in silence. `.claude/settings.json` alone is named by TWENTY-SIX
+  # shipped documents and had never once been examined by the check that exists to examine exactly
+  # this. Both are INSTALL DESTINATIONS the consumer owns — the whole point of the docs that name
+  # them is "put this in YOUR settings" — so shipping either would overwrite the reader's own
+  # configuration with this harness's. Same reasoning as .claude/rules/local_fh_context.md above:
+  # the template is what ships, the destination is what the user creates.
+  ".claude/settings.json"
+  ".claude/settings.local.json"
   # Its only input is `.claude/regression/probes.md`, itself ACCEPTED_ABSENT above (a consumer's
   # regression run must not compare against this harness's probe set). Shipping the reader without
   # its corpus would put a script in the package that can only ever report "instrument error".
@@ -99,10 +133,13 @@ ACCEPTED_ABSENT=(
   # selfcheck goes red on a subject they do not have.
   "scripts/test_probe_scope_lanes.sh"
   # Measures what the LIVE `claude` CLI does with several SessionStart hooks on one matcher —
-  # so every run needs the CLI, auth, and spends tokens on the consumer's account. Same reason
-  # `ablation_calibrate.sh` is absent: shipping a script whose only effect on a consumer's
-  # machine is a bill is worse than omitting it. selfcheck reports it NOT EXERCISED (exit 2)
-  # where the CLI is missing, so the package stays green without pretending the lanes ran.
+  # so every run needs the CLI, auth, and spends tokens on the consumer's account. This anchor DOES
+  # get a live run attempt when its subject ships and the file itself is present (selfcheck reports
+  # NOT EXERCISED, exit 2, when that run finds no CLI). This entry covers the OTHER case: the anchor
+  # FILE ITSELF is not shipped, so selfcheck never gets far enough to attempt the run at all — that
+  # case renders SKIP, not NOT EXERCISED (the two are for missing-file vs. present-file-no-CLI,
+  # not interchangeable; corrected 2026-08-12, cross-family review — the two exit paths were
+  # conflated in an earlier revision of this comment).
   "scripts/test_sessionstart_multihook_lanes.sh"
   # The launchd-driven daily cadence runner. Two independent reasons it must not ship: it is half of
   # a pair whose other half is a machine-local plist (`scripts/com.forge-harness.frontier-digest.plist`),
@@ -114,28 +151,142 @@ ACCEPTED_ABSENT=(
   "scripts/frontier_digest_daily.sh"
 )
 
-out=$(python3 - "${ACCEPTED_ABSENT[@]}" <<'PY'
-import re, os, json, sys
+# `--list-accepted`: print the ACCEPTED_ABSENT paths, one per line, and exit — no git/package.json
+# dependency, deliberately callable from a context this script's own coverage scan cannot run in
+# (package mode, or a vendored tree with `.git` present but no `package.json` at this root). This is
+# the single declared source of "known-legitimately-unshipped" for OTHER checks to consult instead of
+# re-deriving the same judgment from an environment predicate (`.git` presence, directory existence)
+# that answers a different question and can diverge from this list's actual coverage. Added
+# 2026-08-12 (reship axis, cross-family review of card §🔱⑮ G/D) after selfcheck.sh's ref-path block
+# was found re-deriving "is this legitimately absent" from `[ -e .git ]` — which reproduces the
+# original bug in any git-tracked tree that vendors this package (a monorepo committing
+# node_modules, or a consumer who runs `git init` after install): `.git` exists there, so the old
+# predicate ran the check, found these exact paths missing, and FAILed — the same false-FAIL this
+# array already declares correct to omit.
+if [ "${1:-}" = "--list-accepted" ]; then
+  printf '%s\n' "${ACCEPTED_ABSENT[@]}"
+  exit 0
+fi
+
+# `--vs-tarball` swaps the coverage oracle from package.json files[] (a DECLARATION about the
+# tarball) to `npm pack --dry-run --json` (the tarball). See the two-oracle comment in the python
+# block. Kept as a flag rather than made the default for one reason: the default runs anywhere,
+# offline, in ~1s, while this one shells out to npm and takes seconds — so the strict oracle belongs
+# on the publish path, where the question "what does the consumer actually receive" is the one being
+# asked, and the cheap one stays on every commit.
+if [ "${1:-}" = "--vs-tarball" ]; then
+  export FH_PKG_ORACLE=tarball
+  shift
+fi
+
+# Source-checkout test uses `-e`, not `-d`. In a git WORKTREE `.git` is a FILE (a gitdir pointer),
+# so the old `-d` test read every worktree as "installed package" and skipped the check entirely —
+# silently, with exit 0. Measured 2026-07-31: a worktree created specifically to approximate CI
+# reported PASS while this check had not run at all, i.e. the instrument used to justify wiring CI
+# was itself fail-open on the surface it was standing in. `-e` covers both the ordinary checkout
+# (dir) and the worktree (file); genuine package mode has no `.git` of either kind, so it still
+# skips. Anchored by scripts/test_package_coverage_lanes.sh.
+if [ ! -e .git ]; then
+  echo "SKIP  package-coverage (not a source checkout)"
+  exit 0
+fi
+# PREDICATE SPLIT (cross-family review, 2026-07-31). These were one condition, and folding them
+# together meant `.git` present + manifest missing returned SKIP + exit 0 — "we are in a checkout
+# and cannot read what ships" reported as "nothing to check here". Absence of the input is not
+# absence of the defect; `not found != 0` (CLAUDE.md §Instrument-Calibration). Only the no-.git
+# case is a legitimate skip (an installed package, where the un-shipped files are correctly gone).
+if [ ! -f package.json ]; then
+  echo "FAIL  package-coverage: source checkout with no package.json — the shipped file list is"
+  echo "      unreadable, so coverage is UNMEASURED, not clean"
+  exit 1
+fi
+
+out=$(FH_PKG_ORACLE="${FH_PKG_ORACLE:-declaration}" python3 - "${ACCEPTED_ABSENT[@]}" <<'PY'
+import re, os, json, sys, subprocess
 accepted = set(sys.argv[1:])
 files = json.load(open('package.json'))['files']
 
+# ── TWO ORACLES, and the difference between them is the whole reason the second one exists ────
+# `declaration` (default): a path is covered if package.json files[] says so. That is a CLAIM about
+#     the tarball, checkable without npm, and it is what every caller before 2026-08-13 used.
+# `tarball`: a path is covered if it is actually in `npm pack --dry-run --json`. That is the tarball
+#     ITSELF.
+# They come apart, and this repo has measured them coming apart (card §🔱⑮ G/C: repo ✅ / files[] ❌
+# for two paths). A files[] entry can name a file that does not pack — .npmignore precedence, a
+# pattern that no longer matches, a file deleted while its declaration stayed. In every one of those
+# the declaration oracle says PASS and the consumer gets a broken reference, because the consumer
+# receives the tarball and not the manifest. This is the general solution the campaign card has
+# carried as open under "참조 ↔ 실제 출하 파일셋": the earlier repairs (A–D) routed AROUND it by
+# consulting declarations, which was correct for those cases and is not the same thing as building
+# it.
+# FAIL-CLOSED, and deliberately not "fall back to the declaration": npm missing, a non-zero exit, or
+# JSON that does not parse means the tarball is UNKNOWN, and a lenient fallback would silently
+# convert the stricter oracle back into the weaker one — while still printing the stricter one's
+# name. That is the "미측정을 통과로 렌더" class this whole file is an instrument against.
+ORACLE = os.environ.get('FH_PKG_ORACLE', 'declaration')
+packed = None
+if ORACLE == 'tarball':
+    try:
+        r = subprocess.run(['npm', 'pack', '--dry-run', '--json'],
+                           capture_output=True, text=True, timeout=180)
+        if r.returncode != 0:
+            print(f"ORACLE_UNAVAILABLE\tnpm pack exited {r.returncode}")
+            raise SystemExit(2)
+        packed = {f['path'] for f in json.loads(r.stdout)[0]['files']}
+    except FileNotFoundError:
+        print("ORACLE_UNAVAILABLE\tnpm is not on PATH — the tarball cannot be read")
+        raise SystemExit(2)
+    except (json.JSONDecodeError, KeyError, IndexError) as e:
+        print(f"ORACLE_UNAVAILABLE\tnpm pack --json did not parse ({type(e).__name__})")
+        raise SystemExit(2)
+    except subprocess.TimeoutExpired:
+        print("ORACLE_UNAVAILABLE\tnpm pack timed out")
+        raise SystemExit(2)
+    # An empty or absurdly small packed set means the instrument broke, not that the package is
+    # empty — same impossible-zero rule the shipped-doc guard below applies to its own extractor.
+    if not packed or len(packed) < 10:
+        print(f"ORACLE_UNAVAILABLE\tnpm pack reported {len(packed or [])} files — implausible")
+        raise SystemExit(2)
+
 def covered(p):
+    if packed is not None:
+        return p in packed
     return any(p == f or p.startswith(f.rstrip('/') + '/') for f in files)
 
 shipped = []
-for f in files:
-    if os.path.isfile(f):
-        shipped.append(f)
-    elif os.path.isdir(f):
-        for root, _, names in os.walk(f):
-            shipped.extend(os.path.join(root, n) for n in names)
+if packed is not None:
+    # In tarball mode the set of SCANNED documents is the tarball too, not the declaration. Both
+    # halves have to move together: scanning a doc that does not actually ship would report a
+    # phantom no consumer can encounter, and that false positive is what would get the stricter
+    # oracle switched back off.
+    shipped = sorted(packed)
+else:
+    for f in files:
+        if os.path.isfile(f):
+            shipped.append(f)
+        elif os.path.isdir(f):
+            for root, _, names in os.walk(f):
+                shipped.extend(os.path.join(root, n) for n in names)
 
 # Only text surfaces can carry a reference a human or agent would follow.
 shipped = [s for s in shipped if s.endswith(('.md', '.sh', '.js', '.json', '.yaml', '.yml'))]
 
 pat = re.compile(
     r'(?<![\w/.-])((?:scripts|templates|bin|docs|knowledge|plugins|\.claude)'
-    r'/[A-Za-z0-9_./-]+\.(?:sh|py|js|md|yaml|yml|json|defaults))'
+    # LONGEST-FIRST, and the order is the whole fix. Python's `|` is leftmost-first, not
+    # longest-match, so the previous order `sh|py|js|md|yaml|yml|json|defaults` matched `.js`
+    # inside `.json` and truncated every JSON reference: `templates/settings.json` was extracted as
+    # `templates/settings.js`, a path that exists nowhere, so `os.path.exists()` said False and the
+    # reference was dropped in silence. This check has therefore NEVER examined a shipped doc's
+    # JSON references. Same trap in `yml|yaml` (harmless by luck: neither is a prefix of the other)
+    # and it would bite again for any future pair like `md`/`mdx`.
+    # Known-pair, run before the fix: `templates/settings.json` → `templates/settings.js` (broken)
+    # while `scripts/foo.sh` → `scripts/foo.sh` (control, intact). After: both intact.
+    # The `(?![A-Za-z0-9])` tail is the belt to the longest-first braces: it stops a correct
+    # alternative from matching a PREFIX of a longer real extension that nobody listed yet, so the
+    # next person who adds an extension cannot silently reintroduce this by putting it in the wrong
+    # place. Ordering alone is a convention; the lookahead is the mechanism.
+    r'/[A-Za-z0-9_./-]+\.(?:defaults|json|yaml|yml|sh|py|js|md)(?![A-Za-z0-9]))'
 )
 
 phantom = {}
@@ -192,6 +343,19 @@ PY
 )
 rc=$?
 
+case "$out" in
+  ORACLE_UNAVAILABLE*)
+    # Only reachable with --vs-tarball. The stricter oracle could not be read, and the ONLY wrong
+    # answer here is to quietly re-run with the weaker one and print a pass — the caller asked
+    # "what does the consumer actually receive", and "I could not look" is not an answer to that.
+    echo "FAIL  package-coverage (--vs-tarball): the tarball oracle is UNAVAILABLE, so coverage"
+    echo "      against the real packed file set is UNMEASURED — not clean."
+    printf '%s\n' "$out" | sed 's/^ORACLE_UNAVAILABLE\t/      reason: /'
+    echo "      Re-run without --vs-tarball to check against package.json files[] instead, but note"
+    echo "      that is a DIFFERENT and weaker question (a declaration, not the tarball)."
+    exit 2 ;;
+esac
+
 if [ "$rc" -eq 2 ] || [ "$out" = "EXTRACTOR_BROKE" ]; then
   echo "FAIL  package-coverage: extractor scanned 0 shipped docs — the check broke, it did not pass"
   exit 1

package/scripts/postinstall_notice.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+'use strict';
+// postinstall_notice.js — one-line, stderr-only, CI-silent install notice.
+//
+// WHY: 16k+ npm downloads (measured live, 2026-08-15) vs 7 GitHub stars on the same day —
+// people are using fh-gate and have no reason to ever see the GitHub repo, since `npx
+// @chrono-meta/fh-gate` never surfaces it. This closes that gap at the one moment every
+// installer passes through, without touching fh-gate.js's own stdout (that IS the CI
+// contract per its own header comment — this notice must never risk polluting it).
+//
+// WHY stderr, not stdout: npm's own install-time output already goes to stderr by
+// convention (npm's progress/warnings), and more importantly this keeps it structurally
+// impossible for the notice to ever be mistaken for gate output — a script piping
+// `npx @chrono-meta/fh-gate`'s stdout for FH_GATE_VERDICT: parsing never sees this line,
+// even if this file were somehow invoked in the same process (it isn't — separate
+// lifecycle script, separate process).
+//
+// WHY CI-silent: postinstall banners are a known source of npm-ecosystem noise complaints,
+// and this package explicitly markets itself for CI use (CHEATSHEET.md §9.5). A line that
+// reprints on every CI run install is exactly the annoyance that gets a package reported,
+// not starred. Skip whenever a CI environment is plausible OR the operator opts out.
+if (process.env.CI || process.env.FH_NO_BANNER || process.env.CONTINUOUS_INTEGRATION) {
+  process.exit(0);
+}
+try {
+  process.stderr.write(
+    '\n⭐ forge-harness (fh-gate) — if this is useful, a star helps others find it:\n' +
+    '   https://github.com/chrono-meta/forge-harness\n' +
+    '   (set FH_NO_BANNER=1 to silence this message)\n\n'
+  );
+} catch (_) {
+  // Never fail an install over a courtesy message.
+}
+process.exit(0);

package/scripts/psa_scan_lib.sh

@@ -239,3 +239,167 @@ $PSA_STREAM
 PSA_PAT
   return $hit
 }
+
+# _psa_can_assign <name> <value> — 0 = "this exact assignment will succeed", 1 = it will not.
+#
+# Rounds 4→7 walked this from a declaration parse to a proxy probe to the real thing:
+#   R4  parsed `readonly -p` for `NAME=` — missed `readonly FOO` (prints `declare -r FOO`, no `=`)
+#       and false-positived on an unrelated readonly whose VALUE contained the string.
+#   R5  replaced it with a behavioural probe — but the probe assigned the variable's OWN CURRENT
+#       VALUE, while the caller then assigns something else.
+#   R7  found the gap that leaves: `declare -i PSA_ALLOWLIST` makes the self-assignment succeed and
+#       `PSA_ALLOWLIST=/dev/null` fail. Measured — probe=writable, real=FAIL. The caller then died
+#       mid-run, and on the psa_scan_file path a hit that psa_scan_tagged WOULD have reported was
+#       lost with it.
+# So the probe now takes the value: it tests the operation that is actually about to happen, in a
+# subshell where failure cannot reach the caller. Every earlier version tested a stand-in for it.
+_psa_can_assign() {
+  case "$1" in
+    ''|*[!A-Za-z0-9_]*|[0-9]*)
+      echo "  ❌ _psa_can_assign: refusing non-identifier argument" >&2
+      return 1 ;;   # cannot-assign → the caller refuses to mutate. Degrades away from mutating.
+  esac
+  ( eval "$1=\"\$2\"" ) 2>/dev/null
+}
+
+# psa_require_live — prove the scanner actually RUNS before a 0 from it is allowed to mean "clean".
+# Returns 0 = alive, 1 = dead (and says so on stderr).
+#
+# Why this exists (measured 2026-08-12): a caller hand-built the path-tagged stream and piped it into
+# psa_scan_tagged from a shell whose PATH lacked `cat`. The function died on its first line, printed
+# `command not found` into the captured output, and returned 0 — so the caller's known-positive
+# (a file dense with operator literals) reported **0 hits**, indistinguishable from clean. The control
+# is what caught it: the run was only recognisable as dead because a file that MUST hit did not.
+# This function makes that control intrinsic instead of remembered — it does not check that binaries
+# exist (a presence check is the weaker instrument this repo keeps re-learning), it checks that a
+# synthetic token which MUST be reported IS reported, end to end through the real matcher.
+#
+# Cross-family round 1 (2026-08-12) refuted three things about the first draft; all three are fixed
+# here and named so the next reader does not re-introduce them:
+#   · it exercised only the stdin path, so a missing `awk` — the binary the file path actually needs —
+#     was outside what "alive" certified. The self-test now goes through the SAME tagging path
+#     `psa_scan_file` uses, from a real temp file.
+#   · the canary was allowlistable: a `psa/selftest<TAB>PSA_SELFTEST_CANARY` row would mute it and a
+#     healthy scanner would report itself dead. The self-test now runs with the allowlist disabled.
+#   · it was not `errexit`-safe: under `set -e` the nonzero return from the hit-reporting path exited
+#     the caller's shell before the restore line. Status capture is now inside an `if`.
+psa_require_live() {
+  local saved_stream saved_allow saved_stream_set saved_allow_set tmpd out rc _canary
+  saved_stream="${PSA_STREAM-}"; saved_allow="${PSA_ALLOWLIST-}"
+  saved_stream_set=""; saved_allow_set=""
+  [ "${PSA_STREAM+x}" = "x" ] && saved_stream_set=1
+  [ "${PSA_ALLOWLIST+x}" = "x" ] && saved_allow_set=1
+  tmpd=$(mktemp -d 2>/dev/null) || { echo "  ❌ INSTRUMENT DEAD — mktemp unavailable." >&2; return 1; }
+  # Round 4 refuted the round-3 fix: `|| :` does NOT rescue an assignment to a readonly variable —
+  # bash aborts the shell before the `||` is ever considered. So the only safe move is to REFUSE
+  # before mutating anything. Detected, reported as DEAD, and the caller survives.
+  _canary=$(printf 'HIGH\tPSA_SELFTEST_CANARY')
+  if ! _psa_can_assign PSA_STREAM "$_canary" || ! _psa_can_assign PSA_ALLOWLIST /dev/null; then
+    echo "  ❌ INSTRUMENT DEAD — PSA_STREAM/PSA_ALLOWLIST cannot take the values the self-test needs." >&2
+    echo "     (readonly, or an attribute such as \`declare -i\` that rejects the value)" >&2
+    echo "     Not attempting it: a failed assignment aborts an errexit caller outright." >&2
+    rm -rf "$tmpd" 2>/dev/null || :
+    return 1
+  fi
+  PSA_STREAM="$_canary"
+  PSA_ALLOWLIST=/dev/null
+  printf 'PSA_SELFTEST_CANARY\n' > "$tmpd/canary" 2>/dev/null
+  # Same pipeline shape as psa_scan_file: awk tags the file, psa_scan_tagged matches it.
+  if out=$(awk -v P="psa/selftest" '{print P "\t" $0}' "$tmpd/canary" 2>&1 | psa_scan_tagged 2>&1); then
+    rc=0
+  else
+    rc=$?
+  fi
+  rm -rf "$tmpd" 2>/dev/null || :
+  # Restore EXACTLY, including the difference between unset and set-empty (round 2): the first draft
+  # always re-set PSA_STREAM, turning an unset variable into an empty one — which the very guard in
+  # psa_scan_file below keys on. A restore that changes state is not a restore.
+  if [ -n "${saved_stream_set:-}" ]; then PSA_STREAM="$saved_stream"; else unset PSA_STREAM; fi
+  if [ -n "${saved_allow_set:-}" ]; then PSA_ALLOWLIST="$saved_allow"; else unset PSA_ALLOWLIST; fi
+  case "$out" in
+    *PSA_SELFTEST_CANARY*) [ "$rc" -eq 1 ] && return 0 ;;
+  esac
+  echo "  ❌ INSTRUMENT DEAD — the scanner did not report a synthetic known-positive." >&2
+  echo "     self-test rc=$rc out=[$out]" >&2
+  echo "     A 0 from this scanner is UNMEASURED, not clean — do not report or publish a count from it." >&2
+  return 1
+}
+
+# psa_scan_file <path> — scan ONE file through the shared matcher.
+#
+# Three-valued on purpose: 0 = scanned, nothing reportable · 1 = scanned, hit(s) reported ·
+# 3 = NOT SCANNED (instrument dead, bad usage, or missing file). Folding 3 into 0 is the exact defect
+# this repo keeps meeting — `not found` is not `0`, and a file that does not exist is not an empty file.
+# Callers that only branch on `if psa_scan_file f; then clean; fi` would read 3 as dirty (safe) and
+# never as clean; callers that check `-eq 0` must treat 3 as unmeasured.
+#
+# ⚠️ The caller still owns the DISPLAY. A hit line (❌) and an allowlisted line (⚪) are different
+# outcomes, and a display filter that greps only ❌ renders "allowlisted" as "no match" — measured
+# on 2026-08-12, which is how an existing operator allowlist decision was misread as an absent
+# pattern. If you filter this function's output, keep both markers or state which you dropped.
+psa_scan_file() {
+  local out rc
+  if [ "$#" -ne 1 ]; then
+    echo "  ⚠️  USAGE — psa_scan_file <path> (got $# argument(s)); NOT SCANNED" >&2
+    return 3
+  fi
+  # Patterns-not-loaded is the highest-value guard here, and it was missing from the first draft.
+  # Cross-family round 1 found it by simply following THIS FILE'S OWN advertised usage line, which
+  # said `. psa_scan_lib.sh && psa_scan_file <path>` and omitted psa_load — reproduced: a file dense
+  # with a known-positive token returned rc=0 with empty output. An empty pattern stream scans
+  # everything and reports nothing, which is the false-clean this whole change exists to remove.
+  if [ -z "${PSA_STREAM:-}" ]; then
+    echo "  ⚠️  PATTERNS NOT LOADED — call psa_load <defaults> <override> first; NOT SCANNED" >&2
+    echo "     (an empty pattern stream reports nothing, which is indistinguishable from clean)" >&2
+    return 3
+  fi
+  # A NON-EMPTY stream is not a COMPLETE one (round 2). If the committed defaults failed to load, or
+  # rows were dropped as unusable, the stream still matches *something* and a clean verdict from it
+  # is a verdict about a partial instrument.
+  #
+  # `case`, not `[ -ne ]` (round 3): a non-numeric value made `[` return 2, the `if` read that as
+  # false, and the guard fell through — reproduced with PSA_DEFAULTS_OK=x, which scanned a file to
+  # rc=0 CLEAN using a stream that did not contain the token. A guard that a garbage value walks
+  # straight past is not a guard, and the shell's own error line scrolled by unnoticed.
+  local _incomplete=""
+  case "${PSA_DEFAULTS_OK:-}" in 1) ;; *) _incomplete="defaults_ok=${PSA_DEFAULTS_OK:-unset}" ;; esac
+  case "${PSA_BAD_ROWS:-0}" in 0) ;; *) _incomplete="${_incomplete:+$_incomplete }bad_rows=${PSA_BAD_ROWS}" ;; esac
+  # The operator override carries the HIGH company/companion literals. Its absence is survivable for a
+  # single-file query (the committed defaults still apply) but the caller must never read the result as
+  # a full clean — so it is announced, not silently folded in.
+  # Round 4: this used to WARN and still return 0. That is the exact false-clean this change exists to
+  # remove — the override carries the HIGH company/companion literals, so without it the scan did not
+  # look at the highest-severity class at all, and "clean" is a claim the run cannot support. It now
+  # joins _incomplete. (No existing caller breaks: psa_scan_file is new in this change.)
+  case "${PSA_OVERRIDE_PRESENT:-}" in
+    1) ;;
+    *) _incomplete="${_incomplete:+$_incomplete }override_absent(HIGH operator literals unscanned)" ;;
+  esac
+  psa_require_live || return 3
+  if [ ! -f "$1" ]; then
+    echo "  ⚠️  MISSING — $1 : NOT SCANNED (unmeasured, not 0 hits)" >&2
+    return 3
+  fi
+  # `awk | psa_scan_tagged` hides an awk read failure when the caller has no pipefail: awk fails,
+  # psa_scan_tagged sees an empty stream and returns 0 = clean. Materialise the tagged stream first
+  # so the read is a checkable step of its own (cross-family round 1).
+  local tmpf
+  tmpf=$(mktemp 2>/dev/null) || { echo "  ⚠️  mktemp failed; NOT SCANNED" >&2; return 3; }
+  if ! awk -v P="$1" '{print P "\t" $0}' "$1" > "$tmpf" 2>/dev/null; then
+    rm -f "$tmpf" || :
+    echo "  ⚠️  READ FAILED — $1 could not be tagged for scanning; NOT SCANNED" >&2
+    return 3
+  fi
+  if out=$(psa_scan_tagged < "$tmpf"); then rc=0; else rc=$?; fi
+  rm -f "$tmpf" || :
+  # Print findings FIRST, verdict second — round 3 caught the previous order suppressing real hits:
+  # an incomplete instrument returned 3 and emitted nothing, so a token the loaded patterns DID match
+  # was lost. "I could not certify this" and "I saw nothing" are different, and the fix for the second
+  # must not create the first. Partial evidence is reported; the verdict still refuses to say clean.
+  [ -n "$out" ] && printf '%s\n' "$out"
+  if [ -n "$_incomplete" ]; then
+    echo "  ⚠️  INCOMPLETE PATTERN INSTRUMENT — $_incomplete : verdict is NOT SCANNED (any hits above are partial)" >&2
+    return 3
+  fi
+  return "$rc"
+}

package/scripts/public_surface_scan_files.sh

@@ -24,6 +24,36 @@
 
 set -uo pipefail
 
+# ── Misuse fails CLOSED, before the banner ──────────────────────────────────────────────────────
+# This script scans the npm-published file set (derived from `npm pack --dry-run`). It takes NO
+# positional arguments, and until 2026-08-12 it did not parse any either — it silently ignored them
+# and printed its normal green. That turned a misuse into a false certification: a caller who ran
+#   bash scripts/public_surface_scan_files.sh <some/path>
+# to ask "is THIS file clean?" got `✅ PASS`, about a file set that never contained <some/path>.
+# Measured known-pair: no args → rc=0 PASS; `/nonexistent/definitely_not_a_file_zzz.md` → byte-identical
+# rc=0 PASS; `PSA_PATTERNS=/nonexistent/nope` → rc=1 (so the green was a live green, not a dead one).
+# The first person to hit it was not the author but the first real user, who nearly recorded
+# "paper/forge_harness_v1.0.html is clean" from a scan that never opened that file.
+# On an irreversible surface (publish) an instrument that cannot answer the question it was asked
+# must refuse, not answer a different question in the affirmative.
+# rc=2 is deliberately distinct from rc=1 (a real leak/incomplete instrument) and rc=0 (clean):
+# "you used it wrong" and "your content is dirty" are different states and must not be collapsed.
+if [ "$#" -gt 0 ]; then
+  echo "[Pre-Publish] public-surface scan — ✋ USAGE ERROR: this script takes no arguments (got $#: $*)" >&2
+  echo "     It scans the npm-published file set only (npm pack --dry-run), never a path you pass in." >&2
+  # The psa_load call is NOT optional and is spelled out here on purpose: the first draft of this
+  # message omitted it, and cross-family review found that following it verbatim scans a
+  # known-positive file to rc=0/clean (empty pattern stream). An instruction that produces a false
+  # clean is the same defect as the guard above, one layer out.
+  echo "     To scan ONE file:" >&2
+  echo "       . scripts/psa_scan_lib.sh \\" >&2
+  echo "         && psa_load .claude/rules/.public-surface-patterns.defaults .claude/rules/.public-surface-patterns \\" >&2
+  echo "         && psa_scan_file <path>        # rc: 0 clean · 1 hit(s) · 3 NOT SCANNED" >&2
+  echo "     To scan tracked files: use the /public-surface-audit skill." >&2
+  echo "     Refusing rather than reporting a PASS about a different file set (fail-closed)." >&2
+  exit 2
+fi
+
 REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
 PSA_DEFAULTS="$REPO_ROOT/.claude/rules/.public-surface-patterns.defaults"
 PSA_OVERRIDE="${PSA_PATTERNS:-$REPO_ROOT/.claude/rules/.public-surface-patterns}"