@chrono-meta/fh-gate 1.4.98 → 2.0.0

package/scripts/consent_registry_check.sh

@@ -66,9 +66,94 @@
 #
 #   "N/A" is printed as N/A, never as PASS — an unmeasured surface is not a clean one.
 #
-# Usage: bash scripts/consent_registry_check.sh [registry.yaml] [uap.md-or-yaml]
+# Usage: bash scripts/consent_registry_check.sh [--require-class NAME] [registry.yaml] [uap.md-or-yaml]
+#
+# `--require-class NAME` narrows the verdict from FILE-WIDE to ONE CLASS, and a caller acting on
+# behalf of a single class MUST use it. Without it, exit 0 means "the registry and the grants are
+# well-formed and the floor join holds" — a property of the FILE. A caller that reads that 0 as
+# "my class is granted" is wrong whenever any OTHER class is validly granted.
+#
+# That is not hypothetical. Measured 2026-08-15 with a live control: fh_node_check.sh gated its
+# auto-fast-forward on this script's file-wide 0 AND a raw `grep` for the class name anywhere in the
+# UAP. With one unrelated class validly granted and `repo-freshness-autopull` appearing only as a
+# prose line saying it had been REVOKED, both conditions passed and the merge ran — while the banner
+# told the operator it was acting on a standing consent that did not exist. The control (a real
+# grant for the class) also returned 0, so the two states were indistinguishable through that channel.
+# With `--require-class` the same pair separates: 0 for the real grant, 3 for the revoked one.
 set -uo pipefail
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+# Flag parsing, hardened by a cross-family round on the first draft. Three defects it found, all
+# reproduced, all fail-OPEN — the flag would appear to be in force while the verdict stayed file-wide:
+#   · `--require-class '   '` passed the `-z` test (non-empty), then Python's `.strip()` reduced it
+#     to "" and the require-class branch silently switched off.
+#   · the flag was read only at argv position 1, so `... reg.yaml uap.md --require-class NAME` was
+#     ignored without a word and returned the old 0.
+#   · an unknown flag was consumed as a path.
+# A gate whose ON switch can be silently OFF is worse than no gate, so all three now fail closed.
+FH_REQUIRE_CLASS=""
+FH_REQUIRE_CLASS_SET=""
+_pos=()
+# `_norm_class` TRIMS the ends. It does NOT delete interior whitespace, and the difference is the
+# whole point: a third round measured `--require-class 'repo-freshness-auto pull'` being squeezed to
+# `repo-freshness-autopull` and returning 0 — i.e. asking about one class and being told about a
+# DIFFERENT one. A name that still contains whitespace after trimming is refused rather than
+# repaired, because silently repairing an identity is how the wrong class gets authorized.
+_norm_class() {
+  local v="$1"
+  v="${v#"${v%%[![:space:]]*}"}"   # strip leading
+  v="${v%"${v##*[![:space:]]}"}"   # strip trailing
+  printf '%s' "$v"
+}
+_set_require_class() {
+  FH_REQUIRE_CLASS_SET=1
+  FH_REQUIRE_CLASS="$(_norm_class "$1")"
+  if [ -z "$FH_REQUIRE_CLASS" ]; then
+    echo "consent-registry: FAIL — --require-class given with an empty or whitespace-only class name; fail-closed" >&2
+    exit 1
+  fi
+  case "$FH_REQUIRE_CLASS" in
+    *[[:space:]]*)
+      echo "consent-registry: FAIL — class name '$FH_REQUIRE_CLASS' contains whitespace; a class identity is not normalised for you (fail-closed)" >&2
+      exit 1 ;;
+  esac
+  # 🟥 NAMED RESIDUAL — invisible and normalisation-confusable identities are still ACCEPTED.
+  # Round 4 measured it: a class whose name carries a zero-width joiner is admitted as an identity,
+  # and `unicodedata` is applied to the effect vocabulary but never to class names or grant keys.
+  # Why it is carried rather than closed here, stated so the next reader does not have to re-derive
+  # it: the same round's controls showed the failure direction is SAFE — `ok` vs `o<ZWJ>k` returns 3,
+  # and an NFC/NFD mismatch returns 3, so no confusable name FALSELY joins a real grant; the residue
+  # is that a weird name can be its own consistent identity. Exploiting that requires write access to
+  # BOTH the registry and the UAP, which are the consent source of truth — anyone holding those has
+  # already granted themselves whatever they wanted, so this is hygiene, not escalation.
+  # The right fix is NFC-normalising both sides and refusing Unicode format/control characters, NOT
+  # a blanket non-ASCII refusal: this harness is language-agnostic and a Korean class name is
+  # legitimate. That is a design decision with its own known-pair, not a line to add during a release.
+}
+# Positionals go into a bash ARRAY. The first draft accumulated them into a newline-delimited string
+# and rebuilt "$@" with `read` — measured not to be argv-preserving: a path containing a newline
+# split into two, and an empty positional was dropped, which silently promoted the UAP path into the
+# registry slot. This file is `#!/usr/bin/env bash`, so an array is available and exact.
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --require-class)
+      if [ "$#" -lt 2 ]; then
+        echo "consent-registry: FAIL — --require-class given with no class name; fail-closed" >&2
+        exit 1
+      fi
+      _set_require_class "$2"; shift 2 ;;
+    --require-class=*)
+      _set_require_class "${1#--require-class=}"; shift ;;
+    --)
+      shift; while [ "$#" -gt 0 ]; do _pos+=("$1"); shift; done ;;
+    --*)
+      echo "consent-registry: FAIL — unknown option '$1'; fail-closed rather than treating it as a path" >&2
+      exit 1 ;;
+    *)
+      _pos+=("$1"); shift ;;
+  esac
+done
+set -- ${_pos[@]+"${_pos[@]}"}
+export FH_REQUIRE_CLASS FH_REQUIRE_CLASS_SET
 REG="${1:-$ROOT/tracks/_meta/consent_classes.yaml}"
 UAP="${2:-$ROOT/tracks/_meta/user_adaptation_profile.md}"
 
@@ -474,6 +559,16 @@ else:
                 fails += 1; grants = None
 
 no_active_grant = False
+# Names that survived EVERY per-grant check. `--require-class` joins against this set, never against
+# `validated` (a count that includes names which then failed) and never against the file-wide verdict.
+clean_grants = set()
+REQUIRE_CLASS = os.environ.get("FH_REQUIRE_CLASS", "").strip()
+# "was the flag given" is tracked separately from "is the name non-empty". Collapsing them is how
+# the first draft turned a whitespace-only name into a silent fall-back to the file-wide verdict.
+REQUIRE_SET = os.environ.get("FH_REQUIRE_CLASS_SET", "") == "1"
+if REQUIRE_SET and not REQUIRE_CLASS:
+    print("consent-registry: FAIL — --require-class resolved to an empty class name; fail-closed")
+    sys.exit(1)
 if grants is None:
     pass
 elif not grants:
@@ -522,6 +617,12 @@ else:
             if st.strip().lower() in NON_GRANT:
                 continue
         validated += 1
+        # Failure count at the START of this grant's checks. A name joins `clean_grants` at the end
+        # of the body only if nothing was recorded against it in between — `validated` cannot serve
+        # that purpose, because it is incremented HERE and every failing branch below still counted.
+        # Each of those branches also `continue`s after `fails += 1`, so a failing name never reaches
+        # the add; this counter covers the non-continuing ones.
+        _f0 = fails
         c = by_name.get(name)
         if c is None:
             out("❌", f"R3 `{name}` granted but NOT in the registry (unregistered == unknown)"); fails += 1; continue
@@ -669,6 +770,8 @@ else:
                 out("❌", f"R7 `{name}` grant target {tgt!r} does not match the registered target "
                           f"{c['target']!r} — scope drift between grant and class")
                 fails += 1
+        if fails == _f0:
+            clean_grants.add(name)
     skipped = len(grants) - validated
     if validated == 0:
         # Same state as the empty-grants branch above, reached differently: every key present was
@@ -682,6 +785,11 @@ else:
         out("✅", f"R3-R6 all {validated} active grant(s) registered, eligible, unexpired, "
                   f"scope-recorded{note}")
 
+# The class-scoped verdict is decided BEFORE the summary, so the summary can agree with it. The
+# first draft printed it after, which produced `consent-registry: PASS` on a run that then exited 3
+# for the requested class — the exact contradiction this file's own comment below calls a false
+# green with extra steps (cross-family, 2026-08-16).
+_class_missing = bool(REQUIRE_CLASS) and not fails and REQUIRE_CLASS not in clean_grants
 print("----")
 # The human-facing summary must agree with the typed exit. It previously printed PASS on a run whose
 # own line above said "nothing granted, keep asking (not a PASS)" and whose exit code was 3 — so an
@@ -690,8 +798,15 @@ print("----")
 # false green with extra steps. (Caught by hand 2026-08-02 while verifying the exit-3 fix.)
 if fails:
     print(f"consent-registry: {fails} violation(s)")
+elif _class_missing:
+    seen = "none" if not clean_grants else ", ".join(sorted(clean_grants))
+    print(f"consent-registry: UNMEASURED for class `{REQUIRE_CLASS}` — nothing granted for it, "
+          f"keep asking (exit 3). Active grants that DID join: {seen}. A grant for another class, "
+          f"or the name merely appearing in the file, is not consent for this one.")
 elif no_active_grant:
     print("consent-registry: UNMEASURED — nothing granted, keep asking (exit 3)")
+elif REQUIRE_CLASS:
+    print(f"consent-registry: PASS for class `{REQUIRE_CLASS}` (active, registered, unexpired)")
 else:
     print("consent-registry: PASS")
 # BROKEN outranks UNMEASURED: a violation is a decided negative, "nothing granted" is merely nothing
@@ -703,5 +818,13 @@ if ZERO_CLASSES and not fails:
         print("consent-registry: FAIL — a standing grant exists but the registry declares zero "
               "classes; every such grant is UNREGISTERED (R3), which is BROKEN, not unmeasured")
         sys.exit(1)
+# ── --require-class: narrow the verdict to ONE class ───────────────────────────────────────────
+# Ordering is deliberate and matches the existing precedence: BROKEN (1) outranks everything, so a
+# violation anywhere still exits 1 even when the required class itself looks fine — an unparseable
+# neighbour means the file could not be decided, and "cannot decide == not allowed" is this script's
+# own rule. Below that, a required class that did not join is UNMEASURED (3), the same code as
+# "nothing granted", because to the caller they are the same instruction: KEEP ASKING.
+if _class_missing:
+    sys.exit(3)
 sys.exit(1 if fails else (3 if no_active_grant else 0))
 PY

package/scripts/fh_node_check.sh

@@ -199,7 +199,75 @@ if git -C "$FH" rev-parse --git-dir >/dev/null 2>&1 && git -C "$FH" remote get-u
       case "$_BEHIND" in
         ''|*[!0-9]*) : ;;   # not measurable — silent, not a claim
         0) : ;;
-        *) GIT_BEHIND_NOTE="local $_DEFAULT_BRANCH is ${_BEHIND} commit(s) behind origin/$_DEFAULT_BRANCH — run: git checkout $_DEFAULT_BRANCH && git pull --ff-only (or: git merge --ff-only origin/$_DEFAULT_BRANCH)" ;;
+        *)
+          # ── auto-apply, consent-gated, inside a deliberately narrow envelope ───────────────
+          # Operator request 2026-08-15, verbatim: "사람이 일일이 수동으로 깃풀해서 최신화해야하는지를
+          # 판단하지않고 … 세션 시작 시 레포체크를 클로드가 알아서 하고 최신화 제안하는 기능이 있으면
+          # 좋을것같아. 그리고 앞으로도 자동으로 이렇게 동기화할지 물어보는 것도."
+          #
+          # 🟥 IT NEVER SWITCHES BRANCHES, and that is the whole safety envelope — not a nicety.
+          # The recommendation this line used to print told the reader to `git checkout
+          # $_DEFAULT_BRANCH && git pull`. In a SHARED CHECKOUT a checkout yanks the ground out from
+          # under a peer session: measured on this repo 2026-08-09 (two sessions, one worktree, one
+          # committed onto the other's branch), which is why scripts/branch_claim.sh exists at all.
+          # As prose advice a human weighed that; automated, nobody would. So the apply arm fires
+          # ONLY when the default branch is ALREADY checked out, and `--ff-only` means it can
+          # neither rewrite history nor absorb a divergence — it refuses instead.
+          #
+          # Consent is a LEASE, joined mechanically, never inferred: the class must be registered
+          # promotion_eligible in tracks/_meta/consent_classes.yaml AND granted unexpired in the
+          # UAP frontmatter. scripts/consent_registry_check.sh is the single decider (exit 0 = a
+          # real grant was joined; 3 = nothing granted; 1 = broken). Absent, expired, unreadable, or
+          # unknown all take the same branch as "no": surface, do not apply. absent ≠ granted.
+          # 🟥 The two conditions this replaced did NOT ask whether THIS class was granted, and a
+          # security pass before the 1.4.99 publish caught it with a live control (2026-08-15).
+          #   · a bare run of consent_registry_check.sh returns 0 for a FILE-WIDE property — "the
+          #     registry and the grants are well-formed and the floor join holds". One validly
+          #     granted UNRELATED class produces that 0.
+          #   · the second condition was `grep -q '^\s*repo-freshness-autopull:'` over the WHOLE UAP,
+          #     which does not distinguish `granted` from `revoked` and does not care whether the
+          #     hit is inside the machine-read frontmatter or in a prose paragraph.
+          # Reproduced: one unrelated class granted + the line `  repo-freshness-autopull: 안 쓰기로
+          # 했다` in prose → both conditions passed, the merge ran, and the banner told the operator
+          # it was acting on a standing consent that had never existed. The revoke path was the one
+          # that broke, which is the exact floor `absent ≠ granted` exists to hold.
+          # `--require-class` joins the ONE class: 0 only if it is an active, registered, unexpired
+          # grant; 3 otherwise. Same known pair now separates 0 from 3.
+          _AUTOPULL=""
+          if [ -x "$FH/scripts/consent_registry_check.sh" ] \
+             && bash "$FH/scripts/consent_registry_check.sh" --require-class repo-freshness-autopull >/dev/null 2>&1; then
+            _AUTOPULL=1
+          fi
+          _ON_DEFAULT=""
+          [ "$(git -C "$FH" symbolic-ref --short -q HEAD 2>/dev/null)" = "$_DEFAULT_BRANCH" ] && _ON_DEFAULT=1
+          # 🟥 NO DEADLINE HERE, AND THAT IS A DECISION — read before adding one back.
+          # A deadline was added here and then REMOVED the same session, because a cross-family
+          # review measured that the watchdog does not do what its name says: wrapping
+          # `git merge --ff-only` in `perl -e 'alarm N; exec @ARGV'` with N=2, against an upstream
+          # adding 20 files behind a slow smudge filter, took ~7.9s and returned 0. The alarm did
+          # not bound git. Shipping it would have added the appearance of a bound with none of the
+          # behaviour — the same false-green shape this release exists to fix.
+          # ⚠️ The consequence reaches further than this line: `_fh_gitcheck_deadline` guards the
+          # FETCH above too, and that guard predates this change. Whether it actually bounds a
+          # stalled fetch is now UNVERIFIED rather than assumed — a network stall may differ from a
+          # CPU-bound checkout, and neither was measured. Recorded as a residual instead of being
+          # quietly relied on.
+          # The exposure that motivated the attempt is real but unmeasured: the fetch may spend its
+          # full 8s inside a SessionStart hook budgeted at 10s, leaving ~2s for a merge whose true
+          # duration nobody has timed. Fixing it properly means measuring that duration and then
+          # bounding with something that actually bounds — not re-adding this line.
+          if [ -n "$_AUTOPULL" ] && [ -n "$_ON_DEFAULT" ] \
+             && git -C "$FH" merge --ff-only "refs/remotes/origin/$_DEFAULT_BRANCH" >/dev/null 2>&1; then
+            # Announce every unprompted run — §Operational Adaptation Loop requires it of a standing
+            # grant, and a sync the reader never saw is indistinguishable from one that never ran.
+            GIT_BEHIND_NOTE="local $_DEFAULT_BRANCH was ${_BEHIND} commit(s) behind — fast-forwarded automatically (standing consent: repo-freshness-autopull). Nothing else was touched; your gitignored state is out of git's reach by construction."
+          else
+            # Every not-applied path lands here and says the same thing: what to run. It does NOT
+            # say why it did not apply, on purpose — "no grant" and "wrong branch" and "ff refused"
+            # would each need their own true sentence, and a wrong reason printed confidently is
+            # worse than none (this file's own §absent-subject rule).
+            GIT_BEHIND_NOTE="local $_DEFAULT_BRANCH is ${_BEHIND} commit(s) behind origin/$_DEFAULT_BRANCH — while ON that branch run: git merge --ff-only origin/$_DEFAULT_BRANCH"
+          fi ;;
       esac
     fi
     # no local branch named $_DEFAULT_BRANCH at all (e.g. a fork never checked it out) → silent,

package/scripts/lane_runner_check.sh

@@ -356,10 +356,16 @@ wired = {s for s in suites if has_runner(s)}
 # ── Embedded --self-test dispatchers — a class the name-pattern `suites` glob cannot see ──────
 # Measured 2026-08-13, the header of this file, §WHAT DEBT:0 DOES NOT MEAN: a lane suite that
 # lives INSIDE its subject as a `--self-test` flag — not a separate `test_*.sh`/`*_lanes.sh` file
-# — is structurally invisible to the glob above. 4 scripts carry one — chamber_witness.sh ·
-# capability_registry_check.sh · digest_landing_check.sh · directional_diff_gate.sh — and none
-# showed up as WIRED or UNWIRED anywhere in this report; the wiring line for the 3 that ARE wired,
-# the `for _subj in ...` loop at scripts/selfcheck.sh:478, could be deleted and nothing here would
+# — is structurally invisible to the glob above. When this block was written, 4 such scripts were
+# known and none showed up as WIRED or UNWIRED anywhere in this report.
+# ⚠️ Do not read that 4 as a current figure, and do not re-list the names here. The set is
+# DISCOVERED at run time by `_st_candidates` below and the live figure is printed in this file's
+# own SELFTEST_COUNTS line, so a hand-maintained example list beside a self-discovering scan is a
+# second source of truth that goes stale in silence. That is not hypothetical: the previous
+# version of this comment named a 4th example the code no longer agreed with, and the session that
+# noticed had to trace the discrepancy to ground by hand.
+# The wiring line for the subjects that ARE wired,
+# the `for _subj in ...` loop in scripts/selfcheck.sh, could be deleted and nothing here would
 # go red. found→extend, not a new file: same idiom as `suites`/`has_runner` above — discover
 # subjects, detect dispatch, report undeclared — new predicates for the shape this pattern uses.
 #
@@ -378,7 +384,7 @@ wired = {s for s in suites if has_runner(s)}
 # literal paren out as an escape sequence instead of a bare character, rather than splitting it
 # across lines.
 # A bare substring match on --self-test would also catch prose that only DISCUSSES the flag
-# (measured: scripts/selfcheck.sh:482 has a comment naming it as an example of what NOT to grep
+# (measured: scripts/selfcheck.sh's `_subj` loop carries a comment naming it as what NOT to grep
 # for, which is exactly the false positive this narrower check exists to avoid). Require one of
 # the two real dispatcher shapes instead: `"--self-test"` in a quoted comparison, or `--self-test)`
 # as a bare case-pattern. The close-paren is built via chr — see the paren-trap note above; a
@@ -392,6 +398,21 @@ def _read(path):
     except OSError:
         return ''
 
+# 🟥 NAMED RESIDUALS in the self-test branch — two asymmetries the 2026-08-15 repair did NOT close,
+# written here because this file names its other residuals and silence would read as coverage.
+#   1. Comment-stripping is LINE-PREFIX only. A dispatch line living inside a heredoc body or
+#      inside an echoed string is not a comment and still counts as a live caller. Symmetric with
+#      runner_dispatches, which has the same limit — so "symmetry restored" is true, and the shared
+#      blind spot survives in both. In-tree example of the shape: the heredoc fixtures in
+#      scripts/test_lane_runner_lanes.sh. Harmless today only because those name a fixture subject.
+#   2. Subject DISCOVERY below still reads comments. `_st_names` matches the raw dispatcher forms
+#      anywhere in the file, so a comment that merely mentions the flag can enrol a script as a
+#      self-test subject. Real case: chamber_witness.sh carries the flag inside a usage comment.
+#      Harmless today because that file also has a real dispatcher — but it means "a mention is not
+#      a declaration" is enforced on the RUNNER side and not on the SUBJECT side.
+# Neither is mechanized: closing them means parsing shell rather than scanning lines, which is the
+# Grep-Collision Treadmill this repo has already logged. Fix on the first case that actually bites.
+#
 # One line on purpose — see the paren-trap note above the SELFTEST_PAT definition.
 _st_candidates = [f for f in glob.glob('scripts/*.sh') if os.path.basename(f) not in suites and os.path.basename(f) != 'lane_runner_check.sh']
 _st_names = [os.path.basename(f)[:-3] for f in _st_candidates if any(_form in _read(f) for _form in SELFTEST_DISPATCH_FORMS)]
@@ -399,8 +420,8 @@ selftest_subjects = sorted(set(_st_names))
 
 def selftest_dispatched(bare_name, txt):
     """Two shapes, both real in this repo. Cross-family review (2026-08-14) caught the first draft
-    shipping only the second — it read scripts/selfcheck.sh:478's `_subj` for-loop but missed
-    :898/:933's direct `bash scripts/probe_scope_check.sh --self-test` / `bash scripts/
+    shipping only the second — it read scripts/selfcheck.sh's `_subj` for-loop but missed that
+    file's direct `bash scripts/probe_scope_check.sh --self-test` / `bash scripts/
     utterance_landing_check.sh --self-test`, so those two subjects were reported UNDECLARED while
     selfcheck.sh runs them every time. This is the exact failure the header above names by cite —
     a reader trusting the count over the source would have been told a false thing with confidence.
@@ -410,11 +431,17 @@ def selftest_dispatched(bare_name, txt):
     Shape 2 (indirect): bare_name sits in a `for VAR in ... bare_name ...; do` loop whose body
     dispatches $VAR with --self-test — mirrors the indirect-branch reasoning of runner_dispatches:
     the literal name is in a list construct, the invocation runs through the loop variable, so a
-    direct-dispatch grep alone structurally cannot see it (scripts/selfcheck.sh:478)."""
-    if re.search(rf'\bbash\s+scripts/{re.escape(bare_name)}\.sh\b[^\n]*--self-test', txt):
+    direct-dispatch grep alone structurally cannot see it (selfcheck.sh's `for _subj in ...` loop).
+
+    Comment lines are dropped first, exactly as runner_dispatches does for ordinary suites: "a
+    mention is not an invocation" applies identically here, and until 2026-08-15 it was enforced in
+    only one of the two predicates. Measured: a `#   bash scripts/x.sh --self-test` usage line
+    matched the direct regex and certified a subject nothing ran."""
+    _body = '\n'.join(_l for _l in txt.split('\n') if not _l.strip().startswith('#'))
+    if re.search(rf'\bbash\s+scripts/{re.escape(bare_name)}\.sh\b[^\n]*--self-test', _body):
         return True
     in_loop = False; loop_var = None; has_name = False
-    for ln in txt.split('\n'):
+    for ln in _body.split('\n'):
         s = ln.strip()
         m = re.match(r'for\s+(\w+)\s+in\b(.*)', s)
         if m:
@@ -430,7 +457,20 @@ def selftest_dispatched(bare_name, txt):
     return False
 
 def has_selftest_runner(bare_name):
-    return any(selftest_dispatched(bare_name, _read(r)) for r in runners)
+    # A subject does not wire itself. has_runner() has skipped a suite's own file since this file
+    # was written; this branch did not, and the asymmetry was invisible because nothing exercised
+    # it — the only in-file control drove selftest_dispatched with synthetic text, never the
+    # runner set.
+    # ⚠️ Attribution, kept precise because a cross-family round caught it being loose: the 2026-08-15
+    # incident — directional_diff_gate.sh dispatched by nothing while the report said 10/10 — was
+    # caused by the COMMENT half, and comment-stripping alone closes it. Every self-reference in
+    # this tree at that date was a `#` line; a non-comment one existed nowhere. So this guard is
+    # SYMMETRY, not a repair of an observed case: it covers the shape where a subject names its own
+    # dispatch in live code, such as a usage helper. That shape is pinned by lane L16, which was
+    # added at the same time and for the same reason — without it this line is a repair no control
+    # drives, which is the failure mode this file exists to name.
+    _own = bare_name + '.sh'
+    return any(selftest_dispatched(bare_name, _read(r)) for r in runners if os.path.basename(r) != _own)
 
 selftest_wired = {s for s in selftest_subjects if has_selftest_runner(s)}
 selftest_undeclared = sorted(s for s in selftest_subjects if s not in selftest_wired)
@@ -445,12 +485,18 @@ if not selftest_dispatched('alpha', _ST_POS_FIXTURE):
 if selftest_dispatched('alpha', _ST_NEG_FIXTURE):
     print("CONTROL_FAILED\tself-test known-negative fixture with no --self-test flag read as dispatched")
     raise SystemExit(2)
+# Second known-negative, added 2026-08-15 with the comment-skip repair. Without it the repair is a
+# line of code no control drives — the failure mode this whole file exists to name.
+_ST_CMT_FIXTURE = '#   bash scripts/alpha.sh --self-test   # usage example, not a caller\n'
+if selftest_dispatched('alpha', _ST_CMT_FIXTURE):
+    print("CONTROL_FAILED\tself-test commented usage line read as a live dispatcher")
+    raise SystemExit(2)
 
 # ── CONTROL: the instrument must be able to see a suite known to be wired, and must NOT see one
 # known to be dead. Without both arms a broken detector reports "all clean" or "all broken" and
 # either reads as a verdict. [[feedback_absence_measurement_needs_control]]
 CTL_POS  = 'test_selfcheck_state_lanes.sh'    # selfcheck.sh invokes this DIRECTLY
-CTL_POS2 = 'test_session_close_lanes.sh'      # selfcheck.sh:613 for-list + `bash "$_anchor"` — the
+CTL_POS2 = 'test_session_close_lanes.sh'      # selfcheck.sh's `_anchor` for-list + `bash "$_anchor"` — the
                                               # INDIRECT arm. Pins the second detection branch: the
                                               # strict detector called this UNWIRED and a hand-check
                                               # showed it runs. Without this control that branch
@@ -628,8 +674,18 @@ if [ -n "$SELFTEST_UNDECLARED" ]; then
   echo "    dispatcher anywhere (self-test code exists, nothing calls it — see this file's own"
   echo "    §Embedded --self-test comment for why the suites glob above cannot see this class):"
   printf '%s\n' "$SELFTEST_UNDECLARED" | sed 's/^/        /'
-  echo "    Fix by wiring \`bash scripts/<name>.sh --self-test\` into scripts/selfcheck.sh's"
-  echo "    _subj for-loop (scripts/selfcheck.sh:478), same shape as the 3 already there."
+  echo "    Fix by wiring \`bash scripts/<name>.sh --self-test\` into scripts/selfcheck.sh, by"
+  echo "    ONE of its two shapes — and the choice is decided by the subject's own output, not"
+  echo "    by which is shorter. The \`for _subj in ...\` loop gates on the substring 캘리브레이션;"
+  echo "    a subject whose terminal verdict is worded any other way goes red there for a reason"
+  echo "    that has nothing to do with its lanes — capability_registry_check was added to that"
+  echo "    loop and reverted for exactly this. Such a subject takes the second shape: its own"
+  echo "    direct-dispatch block, as capability_registry_check.sh and relay_channel.sh do there."
+  echo "    🟥 In that second shape do NOT gate on the exit code alone. Measured 2026-08-15 on"
+  echo "    directional_diff_gate: a suite whose lanes were all deleted still printed a PASS"
+  echo "    verdict and exited 0, and a usage banner carrying the same words satisfied a"
+  echo "    substring match. Require the terminal verdict AS A WHOLE LINE, with a non-zero count"
+  echo "    in it, or exit 0 will certify a suite that ran nothing."
 fi
 
 echo "PASS  lane-runner: ${TOTAL} suites — ${WIRED} wired · ${N_EXEMPT} exempt · ${N_DEBT} declared debt" \

package/scripts/publish_freshness_check.sh

@@ -0,0 +1,204 @@
+#!/usr/bin/env bash
+# publish_freshness_check.sh — «지금 팩되는 트리가 커밋된 통합 브랜치인가».
+#
+# ─────────────────────────────────────────────────────────────────────────────
+# 왜 지어졌나 — 같은 표면에서 두 번 터졌고, 둘 다 «출하 후»에 알았다
+# ─────────────────────────────────────────────────────────────────────────────
+# `npm publish` 는 **커밋이 아니라 워킹트리를 팩한다.** 그 한 줄이 두 사고를 만들었다:
+#
+#   2026-08-13  6세션 공유 체크아웃에서 publish → **남의 미커밋 초안이 출하됐다.**
+#   2026-08-16  main 에 머지된 M6 가 tarball 에 없었다 — 출하한 트리가 그 커밋 이전이었다.
+#               소비자가 받은 registry_check 에는 `M6` 가 **0회** 등장한다.
+#
+# 둘 다 «출하물이 main 보다 뒤처지거나 앞서는» 한 클래스다. 기존 publish 게이트
+# (`version_lockstep_check` · `selfcheck` · `package_coverage_check --vs-tarball` ·
+# `public_surface_scan_files`)는 전부 **파일 내용**을 본다 — 그 내용이 **어느 커밋의 것인가**를
+# 묻는 검사는 하나도 없었다. 그래서 이 파일은 기존 검사의 중복이 아니다.
+#
+# ─────────────────────────────────────────────────────────────────────────────
+# 무엇을 보증하지 않는가 (과잉주장 금지)
+# ─────────────────────────────────────────────────────────────────────────────
+# · **내용이 옳다는 보증이 아니다.** «커밋됐고 origin 과 같다» 만 본다.
+# · **gitignored 파일은 못 본다.** `git status` 가 안 보므로 dirty 로 안 잡힌다.
+#   다만 gitignored 파일은 `files[]` 로 출하되지 않는 것이 정상이고, 그 축은
+#   `package_coverage_check --vs-tarball` 이 본다.
+# · **원격이 그 사이 움직이는 것은 못 막는다.** fetch 시점의 스냅샷이다.
+#
+# 비가역 표면(publish)이므로 **fail-CLOSED**: 판정할 수 없으면 막는다.
+# 명시적 우회는 `PUBLISH_FRESHNESS_OK=1` — 로그를 남긴다.
+#
+# Usage:  bash scripts/publish_freshness_check.sh [--self-test]
+# Exit:   0 = 출하해도 되는 상태 · 1 = 막힘 · 2 = 판정 불가(역시 막힘)
+set -uo pipefail
+
+INTEGRATION_BRANCH="${FH_INTEGRATION_BRANCH:-main}"
+pass=0; fail=0
+ok()  { printf '  \342\234\205 %s\n' "$1"; pass=$((pass+1)); }
+bad() { printf '  \342\235\214 %s\n' "$1"; fail=$((fail+1)); }
+
+run_checks() {
+  echo "publish freshness check (branch=$INTEGRATION_BRANCH)"
+
+  git rev-parse --git-dir >/dev/null 2>&1 || {
+    echo "  INSTRUMENT ERROR: not a git repository — freshness cannot be judged. NOT a pass."
+    return 2; }
+
+  # ── ① 워킹트리가 깨끗한가 ────────────────────────────────────────────────
+  # `--porcelain` 은 추적 파일의 수정·스테이징·미추적을 전부 낸다. 미추적까지 세는 것은
+  # 의도적이다 — 2026-08-13 사고는 **남의 미커밋 파일**이 팩된 것이었다.
+  local dirty
+  dirty=$(git status --porcelain 2>/dev/null | grep -vE '^\?\? tracks/' || true)
+  if [ -n "$dirty" ]; then
+    bad "워킹트리가 깨끗하지 않다 — publish 는 커밋이 아니라 이 트리를 팩한다:"
+    printf '%s\n' "$dirty" | head -10 | sed 's/^/      /'
+    local n; n=$(printf '%s\n' "$dirty" | grep -c . || true)
+    [ "${n:-0}" -gt 10 ] && echo "      … 외 $(( n - 10 ))건"
+  else
+    ok "워킹트리 깨끗 (tracks/ 미추적은 gitignored 운영 산출물이라 제외)"
+  fi
+
+  # ── ② 통합 브랜치 위인가 ────────────────────────────────────────────────
+  local head_branch
+  head_branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+  if [ "$head_branch" = "$INTEGRATION_BRANCH" ]; then
+    ok "HEAD 가 $INTEGRATION_BRANCH"
+  else
+    bad "HEAD 가 '$head_branch' — 통합 브랜치('$INTEGRATION_BRANCH')가 아니다. 피처 브랜치의 트리가 출하된다"
+  fi
+
+  # ── ③ origin 과 같은 커밋인가 ────────────────────────────────────────────
+  # 앞서든 뒤처지든 둘 다 막는다. **뒤처짐**이 2026-08-16 사고(머지된 M6 미출하)이고,
+  # **앞섬**은 «리뷰를 안 거친 로컬 커밋이 출하되는» 반대편 사고다. 방향이 아니라
+  # 불일치 자체가 판정 대상이다.
+  git fetch -q origin "$INTEGRATION_BRANCH" 2>/dev/null || {
+    bad "origin/$INTEGRATION_BRANCH 를 fetch 할 수 없다 — 신선도를 **못 쟀다**. 비가역 표면이므로 막는다"
+    return 1; }
+  local local_sha remote_sha
+  local_sha=$(git rev-parse HEAD 2>/dev/null || echo "")
+  remote_sha=$(git rev-parse "origin/$INTEGRATION_BRANCH" 2>/dev/null || echo "")
+  if [ -z "$local_sha" ] || [ -z "$remote_sha" ]; then
+    bad "커밋 해시를 읽을 수 없다 — 판정 불가"
+  elif [ "$local_sha" = "$remote_sha" ]; then
+    ok "HEAD == origin/$INTEGRATION_BRANCH (${local_sha:0:7})"
+  else
+    local ahead behind
+    ahead=$(git rev-list --count "origin/$INTEGRATION_BRANCH..HEAD" 2>/dev/null || echo "?")
+    behind=$(git rev-list --count "HEAD..origin/$INTEGRATION_BRANCH" 2>/dev/null || echo "?")
+    bad "HEAD(${local_sha:0:7}) != origin/$INTEGRATION_BRANCH(${remote_sha:0:7}) — ahead $ahead · behind $behind. behind 면 머지된 변경이 출하에서 빠진다(2026-08-16 사고 형태)"
+  fi
+
+  echo "----"
+  echo "publish freshness: $pass passed, $fail failed"
+  [ "$fail" -eq 0 ] || return 1
+  return 0
+}
+
+# ── self-test — known-pair. «막는가» 가 아니라 «옳게 막는가» 를 본다 ────────
+self_test() {
+  local T rc sp=0 sf=0
+  T=$(mktemp -d)
+  # $4(선택) = 출력에 반드시 있어야 할 문자열 = **차단 귀속**. rc 만 보는 레인은 «막혔는가» 만
+  # 재고 «옳은 축이 막았는가» 를 못 잰다 — 오늘 이 레포에서 실제로, 사고 재현 픽스처가 엉뚱한
+  # 축(M1)에 걸려 통과한 적이 있다. 기대 축의 문자열까지 확인해야 «막았다» 가 증거가 된다.
+  _lane() { # $1=이름 $2=기대rc $3=실제rc $4=기대문자열(선택) $5=출력
+    local why=""
+    if [ -n "${4:-}" ] && ! printf '%s' "${5:-}" | grep -q -- "$4"; then
+      why=" — rc 는 맞지만 귀속이 틀렸다: '$4' 가 출력에 없다"
+    fi
+    if [ "$3" = "$2" ] && [ -z "$why" ]; then sp=$((sp+1)); printf '  ✅ %-40s rc=%s\n' "$1" "$3"
+    else sf=$((sf+1)); printf '  ❌ %-40s rc=%s (기대 %s)%s\n' "$1" "$3" "$2" "$why"; fi; }
+
+  echo "publish_freshness_check --self-test"
+
+  # 격리된 known-pair 레포를 만든다. 이 레포 자신을 대상으로 삼으면 «오늘 이 트리가 어떤
+  # 상태인가» 에 따라 결과가 바뀌어 레인이 계기가 아니라 날씨가 된다.
+  local UP="$T/upstream" WK="$T/work"
+  git init -q --bare "$UP"
+  # HEAD 를 명시적으로 main 에 건다. `-b main` 은 git>=2.28 전용이라 안 쓰고 symbolic-ref 로 건다.
+  # 🟥 이 두 줄이 없으면 CI 에서만 깨진다(실측 2026-08-16): 이 머신은 전역
+  # `init.defaultBranch=main` 이라 bare 의 HEAD 가 main 이지만, 러너는 보통 설정이 없어
+  # HEAD 가 `master` 를 가리킨다. 그러면 아래 `git clone` 이 **존재하지 않는 브랜치를 가리키는
+  # HEAD** 를 만나 체크아웃 없이 끝나고, 이어지는 커밋·푸시가 전부 실패하며, origin 이 전진하지
+  # 않아 「뒤처짐」 arm 이 **rc=0 으로 조용히 통과**한다. 계기가 환경에 따라 다른 걸 재고 있었다.
+  git -C "$UP" symbolic-ref HEAD refs/heads/main
+  git init -q "$WK"
+  ( cd "$WK"
+    git config user.email t@t; git config user.name t
+    echo one > a.txt; git add a.txt; git commit -qm one
+    git branch -M main; git remote add origin "$UP"; git push -q -u origin main ) >/dev/null 2>&1
+  # 셋업이 실제로 섰는지 **단언한다.** 위 블록은 출력을 버리므로 실패해도 조용하고, 그러면
+  # 뒤따르는 모든 arm 이 «검사기가 통과시켰다» 가 아니라 «검사할 게 없었다» 로 초록이 된다
+  # ([[feedback_absence_measurement_needs_control]] — 부재 측정엔 컨트롤을 동반한다).
+  if ! git -C "$UP" rev-parse --verify -q refs/heads/main >/dev/null; then
+    sf=$((sf+1)); echo "  ❌ SETUP 실패 — upstream 에 main 이 서지 않았다. 아래 레인들은 무의미하다"
+    rm -rf "$T"; echo "── publish_freshness 캘리브레이션 실패: $sp PASS / $sf FAIL ──"; return 1
+  fi
+
+  # ── known-negative: 깨끗 · main · origin 과 동일 → 통과해야 한다 ──────────
+  o=$( cd "$WK" && bash "$SELF" 2>&1 ); rc=$?
+  _lane "깨끗한 main 은 통과" 0 "$rc" "" "$o"
+
+  # ── known-positive A: 더러운 트리 ────────────────────────────────────────
+  o=$( cd "$WK" && echo dirty > b.txt && bash "$SELF" 2>&1 ); rc=$?
+  _lane "미추적 파일이 있으면 막는다" 1 "$rc" "워킹트리가 깨끗하지 않다" "$o"
+  rm -f "$WK/b.txt"
+
+  # ── known-positive B: 피처 브랜치 ────────────────────────────────────────
+  o=$( cd "$WK" && git switch -q -c feat/x && bash "$SELF" 2>&1 ); rc=$?
+  _lane "피처 브랜치에서는 막는다" 1 "$rc" "통합 브랜치" "$o"
+
+  # ── known-positive C: main 이 origin 보다 뒤처짐 (2026-08-16 사고 형태) ──
+  # 다른 클론에서 커밋을 올려 origin 을 전진시킨 뒤, 원래 워킹트리에서 검사한다.
+  ( cd "$T" && git clone -q "$UP" other && cd other
+    git config user.email t@t; git config user.name t
+    git checkout -q -B main origin/main
+    echo two > c.txt; git add c.txt; git commit -qm two; git push -q origin main ) >/dev/null 2>&1
+  # 같은 이유로 **전진했는지 단언한다**. 이 arm 은 이 파일이 존재하는 이유(08-16 사고 형태)라
+  # 조용히 통과하면 정확히 그 사고를 못 잡는 상태로 돌아간다.
+  if [ "$(git -C "$UP" rev-list --count refs/heads/main)" -lt 2 ]; then
+    sf=$((sf+1)); echo "  ❌ SETUP 실패 — origin 이 전진하지 않았다. 「뒤처짐」 arm 을 실행할 수 없다"
+    rm -rf "$T"; echo "── publish_freshness 캘리브레이션 실패: $sp PASS / $sf FAIL ──"; return 1
+  fi
+  o=$( cd "$WK" && git switch -q main && bash "$SELF" 2>&1 ); rc=$?
+  _lane "origin 보다 뒤처지면 막는다(08-16 사고형)" 1 "$rc" "behind" "$o"
+
+  # ── 컨트롤: 따라잡으면 다시 통과해야 한다 (전부 막는 계기가 아님) ────────
+  o=$( cd "$WK" && git pull -q --ff-only origin main && bash "$SELF" 2>&1 ); rc=$?
+  _lane "따라잡으면 다시 통과 (컨트롤)" 0 "$rc" "" "$o"
+
+  rm -rf "$T"
+  # 이 줄은 `selfcheck.sh` 의 embedded --self-test 루프가 «실행이 실제로 일어났다» 를 판정하는
+  # 앵커다(`*캘리브레이션*` 매치). 종단 판정줄이지 테스트 케이스 제목이 아니다 — 그 구분이
+  # 중요한 이유는 `capability_registry_check` 가 정확히 그 이유로 이 루프에서 빠져 있기 때문이다
+  # (그쪽의 캘리브레이션은 한국어 테스트 제목 안에만 있어서, 제목을 바꾸면 진짜 PASS 가
+  # «디스패처 없음» 으로 뒤집힌다).
+  echo "── publish_freshness 캘리브레이션 $([ "$sf" -eq 0 ] && echo 통과 || echo 실패): $sp PASS / $sf FAIL ──"
+  [ "$sf" -eq 0 ]
+}
+
+SELF="$(cd -P "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/$(basename "${BASH_SOURCE[0]:-$0}")"
+
+case "${1:-}" in
+  --self-test) self_test; exit $?;;
+esac
+
+if [ -n "${PUBLISH_FRESHNESS_OK:-}" ]; then
+  echo "⚠️  publish-freshness: PUBLISH_FRESHNESS_OK=1 — 명시적 우회. 무엇을 우회했는지 아래에 남긴다:"
+  run_checks || true
+  echo "⚠️  우회하고 진행한다. 이 줄이 그 기록이다."
+  exit 0
+fi
+
+run_checks
+rc=$?
+if [ "$rc" -ne 0 ]; then
+  cat <<'EOF'
+
+🚫 publish 중단 — 지금 팩되는 트리가 «커밋된 통합 브랜치» 가 아니다.
+   publish 는 커밋이 아니라 워킹트리를 팩한다. 이 상태로 내보내면 출하물과 main 이 갈린다.
+
+   ▸ 정상 경로   : 변경을 커밋 → PR → 머지 → main 에서 pull → 다시 publish
+   ▸ 알고도 강행 : PUBLISH_FRESHNESS_OK=1 npm publish   (무엇을 우회했는지 출력에 남는다)
+EOF
+fi
+exit "$rc"