@chrono-meta/fh-gate 2.0.0 → 2.1.0

package/scripts/fh-gate.sh

@@ -34,7 +34,22 @@ set -euo pipefail
 FH_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 # Single source of truth: read version from the package.json shipped alongside this script.
 # No jq dependency (users may not have it); fall back to "unknown" if unreadable.
-VERSION="$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$FH_ROOT/package.json" 2>/dev/null | head -1)"
+# VERSION — the `|| true` is load-bearing under `set -euo pipefail`, and it is the ONLY part that
+# is. Without it, a package.json that is missing OR unreadable makes this pipeline non-zero, and
+# because the whole thing is an ASSIGNMENT, `set -e` aborts the script right here — so the
+# `:-unknown` fallback on the next line never runs and the gate exits 1 before doing any work.
+# MEASURED 2026-08-16: a sibling harness carries this file verbatim but ships no package.json (it
+# is not an npm package), so its gate was dead on every invocation and its 30-lane regression
+# suite reported 30 failures that were all this one line. One lane appeared to PASS only because
+# its expected exit code happened to be 1 — the textbook signature of a dead control. Nobody had
+# looked, because that repo had no CI. Latent HERE too, not merely a sibling's problem: a copy of
+# this script run from a directory with no package.json died the same way.
+# A `[ -f "$FH_ROOT/package.json" ]` guard was written first and then REMOVED, because a 4-way
+# mutant matrix refuted it: with the file merely absent either mechanism alone suffices, but with
+# the file present-and-unreadable the guard passes and only `|| true` survives. A guard that
+# covers nothing `|| true` does not already cover is decoration, and the first version of this
+# comment claimed both were load-bearing — that claim was false.
+VERSION="$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$FH_ROOT/package.json" 2>/dev/null | head -1 || true)"
 VERSION="${VERSION:-unknown}"
 CALLER_CWD="$(pwd -P)"
 _TMPDIR="${TMPDIR:-/tmp}"

package/scripts/fh_session_load.sh

@@ -200,6 +200,76 @@ if [ -d "$_AUDIT_DIR" ] && fh_cadence_due "$_FH_HOOK_SRC"; then
   fi
 fi
 
+# 1-c) harness-doctor cadence — 위 1-b 와 같은 이유로, 같은 훅에서, 한 블록 더.
+# MEASURED 2026-08-16 (weekly_audit_2026-08-16.md 🟥-3): 직전 감사(07-31)가 «산문 캐던스 미이행»을
+# N=2 로 집계하면서 **주간감사(50일)와 harness-doctor(당시 ~49일) 둘을 함께** 지목했다. 그 뒤 16일
+# 동안 주간감사는 50→16일로 움직였고 — 그건 1-b 가 기계화돼 있기 때문이다 — harness-doctor 는
+# **한 번도 돌지 않아 65일**이 됐다(캐던스 30). 즉 같은 세션이 같은 날 같은 문서에서 지목한 두
+# 캐던스가, 하나는 훅이고 하나는 산문이라는 차이만으로 정반대로 갔다. 그것이 N=3 이고,
+# `operations.md §Recurrence escalation` 은 그때 «새 습관 규칙이 아니라 계기»를 만들라고 한다.
+# 1-b 와 동일하게 **advisory** 다: 밀린 진단은 비가역 표면이 아니므로 표면화하고 절대 막지 않는다.
+#
+# 🟥 not-found ≠ 0 — 이 블록이 1-b 와 다른 유일한 지점이다. 1-b 는 파일이 없으면 조용하고, 그건
+# 갓 클론한 설치를 나그하지 않기 위해 옳다. 그러나 harness-doctor 는 **한 번도 안 돌린 상태가
+# 실재하는 결함**이고(이 레포가 2026-06-12 이후 정확히 그 상태였다), 파일 부재를 침묵으로 렌더하면
+# 「없음」과 「0일 경과」가 같은 출력이 된다 — 이 레포가 반복해 배운 그 클래스다. 그래서 부재를
+# **다른 문장으로** 말하되, «이미 굴러가는 설치인가»를 `fh_completed_*.md` 존재로 판별해 갓
+# 클론한 설치에는 여전히 침묵한다. 그 판별은 1-b 의 audit-dir 존재 검사와 같은 역할이다.
+#
+# 🟥 스코프와 정렬, 둘 다 위 1-b 를 그대로 베끼면 틀린다 — 적대검증 2026-08-16 이 둘 다 잡았다.
+#
+# (1) **노드-로컬만 보면 안 된다.** `tracks/` 는 gitignored 라 노드 간에 안 따라오고, 진단은
+#     `sync-to-be.sh` 로 `$BE/$TM` 에 실린다. 프로에서 돌리고 에어에서 세션을 열면 에어엔
+#     `fh_completed_*.md` 는 있고 진단 리포트만 없어서 **「기록 0건」이라는 거짓 단언**이 난다.
+#     그리고 이건 1-b 보다 나쁘다: 1-b 는 부재를 침묵으로 렌더해 «틀린 말을 안 하는» 쪽으로
+#     degrade 하는데, 이 블록은 부재를 **큰 소리 단언으로 승격**시켰기 때문이다. 스코프가 틀린
+#     채로 소리를 키우면 오보 비용도 같이 커진다. 바로 위 `_fd_ready()`(:129)가 이미 같은 버그를
+#     한 번 겪고 합집합으로 고쳤다 — **같은 형태를 쓴다**(divergent-leniency 금지).
+#
+# (2) **`sort | tail -1` 은 사전순이지 시간순이 아니다.** 1-b 의 글롭 `weekly_audit_*.md` 는
+#     접두어가 고정이라 사전순≈시간순이지만, 여기 글롭은 `*harness_doctor*.md` 로 **양쪽
+#     와일드카드**다. `reference_harness_doctor_notes.md` 가 `harness_doctor_2026-08-16.md` 를
+#     사전순으로 이기고, 그 파일의 mtime 이 나이가 된다 → 거짓 나그 또는 거짓 침묵. **mtime
+#     최대값으로 뽑는다.** (`ls -t` 는 이식성 때문에 안 쓴다 — 이 커밋이 짓는 린트의 P-클래스다.)
+_hd_latest() {  # stdout: 가장 최근 리포트의 mtime (없으면 빈 문자열)
+  _best=""; _bestm=0
+  for _d in "$FH/tracks/_meta" ${BE:+"$BE/$TM"}; do
+    [ -d "$_d" ] || continue
+    while IFS= read -r _f; do
+      [ -n "$_f" ] || continue
+      _m=$(_mtime "$_f")
+      [ "$_m" -gt "$_bestm" ] && { _bestm="$_m"; _best="$_f"; }
+    done < <(find "$_d" -maxdepth 1 -name '*harness_doctor*.md' -print 2>/dev/null)
+  done
+  [ -n "$_best" ] && printf '%s\t%s\n' "$_bestm" "$_best"
+}
+_hd_has_history() {  # «굴러가는 설치인가» — 이것도 합집합으로 본다
+  for _d in "$FH/tracks/_meta" ${BE:+"$BE/$TM"}; do
+    [ -d "$_d" ] || continue
+    find "$_d" -maxdepth 1 -name 'fh_completed_*.md' -print 2>/dev/null | grep -q . && return 0
+  done
+  return 1
+}
+_HD_DIR="$FH/tracks/_meta"
+if [ -d "$_HD_DIR" ] && fh_cadence_due "$_FH_HOOK_SRC"; then
+  _HD_ROW="$(_hd_latest)"
+  _LATEST_HD="${_HD_ROW#*	}"; _HD_MTIME="${_HD_ROW%%	*}"
+  if [ -n "$_HD_ROW" ]; then
+    _HD_AGE_D=$(( ( $(date +%s) - _HD_MTIME ) / 86400 ))
+    if [ "$_HD_AGE_D" -ge 30 ]; then
+      echo "🩺 [harness-doctor] 마지막 구조 진단이 ${_HD_AGE_D}일 전이다($(basename "$_LATEST_HD")) — 캐던스는 30일."
+      echo "    → /harness-doctor (구조·드리프트·끊긴 참조). --lint 는 언어 패턴까지."
+    fi
+  # `-print | grep -q` 이지 `-quit` 이 아니다: `-quit` 은 GNU/BSD 양쪽에 있으나 버전 편차가 있고,
+  # 이 파일이 고치는 결함군에 BSD/GNU 이식성이 들어 있다(감사 🟧-3). 최적화 한 톨을 위해 그 클래스를
+  # 새로 들이지 않는다 — 여기 모집단은 디렉터리 하나이므로 얻을 것도 없다.
+  elif _hd_has_history; then
+    # 세션 이력은 있는데 진단 기록이 0건 = «한 번도 안 돌렸다». 부재를 0 으로 읽지 않는다.
+    echo "🩺 [harness-doctor] 구조 진단 기록이 **0건**이다 — 캐던스 30일이 한 번도 발화한 적 없다."
+    echo "    → /harness-doctor (첫 베이스라인). 부재는 «최신»이 아니다."
+  fi
+fi
+
 # ── branch-claim 자동 기록 (2026-08-09) ────────────────────────────────────────
 # WHY HERE, ABOVE THE COMPANION-STORE EARLY EXIT: 공유 체크아웃 사고는 Mode D 와 무관하다.
 # companion store 가 없는 설치에서도 병렬 세션은 돌고, 그때도 `.git/HEAD` 는 트리당 하나다.

package/scripts/package_coverage_check.sh

@@ -51,6 +51,16 @@ ACCEPTED_ABSENT=(
   # read as claims about THEIR file. The shipped docs name it as the place verdicts live in the
   # harness repo, which is a pointer for contributors, not a promise of a shipped artifact.
   ".claude/regression/ablation_verdicts.md"
+  # 챔버 **순서 증인 원장**(ship_readiness_gate §② P1). 바로 위 ablation_verdicts 와 **같은
+  # 논거**다: 이건 THIS repo 의 챔버 런이 언제 무엇을 고정했는지에 대한 기록이고, 소비자의
+  # 챔버 런은 그들 것이다 — 출하 문서에서 인용된 채로 딸려가면 소비자가 **자기 런에 대한
+  # 주장**으로 읽는다. 게다가 이 원장은 우리 런 slug·시각을 담은 공개 표면이라 소비자에게
+  # 보내는 것은 정보 유출 방향으로도 틀렸다.
+  # 🟥 **부재가 소비자 쪽 기능을 깨지 않는다** — `chamber_witness.sh do_record` 는 원장이
+  # 없으면 헤더를 만들어 생성한다(같은 파일의 `[ ! -f "$LEDGER" ]` 분기). 즉 스크립트는
+  # 출하되고 원장은 소비자 머신에서 처음 쓸 때 생긴다. 「없으면 죽는다」가 아니라
+  # 「없는 게 정상 초기 상태」다.
+  "knowledge/shared/learnings/chamber_ordering_witness.yaml"
   "scripts/sync-to-be.sh"
   "scripts/sync_guard_check.sh"
   # Return path (companion store → hub) and its anchor. Same reason as the forward path above: the

package/scripts/portability_lint.sh

@@ -0,0 +1,257 @@
+#!/usr/bin/env bash
+# portability_lint.sh — 셸 이식성 · 조용한 즉사 · 레포전제 픽스처 린트 (advisory)
+#
+# 왜 이게 있나 (weekly_audit_2026-08-16 🟧-3):
+#   이 레포의 재발 클래스 중 BSD/GNU · zsh/bash 이식성이 윈도우 16일에 ~12건인데
+#   **전용 계기가 없었고**, 잡힌 경로는 **전부 CI ubuntu 에서 사후**였다. 즉 저자 머신
+#   (macOS)에서는 구조적으로 초록이고, 로컬 초록 / CI 적색이 2026-08-16 하루에 2회 났다.
+#   이 린트는 그 사각을 보라고 지어졌다.
+#
+# 🟥 배선 상태를 헤더가 정직하게 말한다 (적대검증 2026-08-16 이 초판 헤더를 «거짓말»로 지목):
+#   초판 헤더는 "저자 머신에서 **커밋 전에** 한 번 본다" 고 적었는데, 실제 호출부는
+#   `selfcheck.sh` 의 `--self-test` **하나뿐**이다. 즉 **계기의 계기는 도는데 계기 자체는 안 돈다.**
+#   제자리는 pre-commit 의 staged `*.sh` 한정 advisory 인데 아직 안 붙였다(별도 커밋 · 인계됨).
+#   그때까지 본 실행은 **손으로 돌려야 한다**: `bash scripts/portability_lint.sh`.
+#   이 문장을 «커밋 전에 본다»로 되돌리려면 **먼저 pre-commit 에 붙여라.** 헤더가 배선보다
+#   앞서 나가는 것이 이 커밋이 고치고 있는 바로 그 결함이다.
+#
+# 무엇이 아닌가:
+#   · shellcheck 대체가 아니다. shellcheck 는 「성공하는 첫 명령」 패턴(P1)을 못 잡는다 —
+#     문법이 아니라 **플랫폼별 의미 차이**라서다. 둘은 상보적이다.
+#   · 게이트가 아니다. **advisory** 다(exit 0 유지, `--strict` 로만 1). 이유는
+#     degrade_direction_scan 과 같다 — FP 를 감수하는 사전 선별기이고, 과차단은
+#     `--no-verify` 를 근육기억으로 만들어 같은 훅의 비가역 게이트까지 무장해제시킨다.
+#
+# Exit: 0 = 소견 없음 또는 advisory 모드 · 1 = --strict 에서 소견 有 · 10 = 하네스 오류
+# Usage: bash scripts/portability_lint.sh [PATHS...] [--strict] [--quiet]
+#        bash scripts/portability_lint.sh --self-test
+
+set -uo pipefail
+
+STRICT=0; QUIET=0; SELFTEST=0; TARGETS=()
+for a in "$@"; do
+  case "$a" in
+    --strict)    STRICT=1 ;;
+    --quiet)     QUIET=1 ;;
+    --self-test) SELFTEST=1 ;;
+    -*)          echo "unknown flag: $a" >&2; exit 10 ;;
+    *)           TARGETS+=("$a") ;;
+  esac
+done
+
+# ── 규칙표 ────────────────────────────────────────────────────────────────────
+# 각 규칙 = ID§정규식§한 줄 사유§처방
+#
+# 🟥 구분자가 `|` 가 아니라 `§` 인 이유 — 이 린트의 self-test 가 초판에서 잡은 결함이다:
+#    `|` 를 필드 구분자로 쓰면 정규식 안의 **교대(alternation) `|`** 에서 잘린다.
+#    P1 이 `…=\$\((cat` 까지만 남아 known-positive 를 놓쳤다. 계기가 자기 문법에 걸린 것이고,
+#    known-pair 가 없었으면 «소견 0건»이 그냥 초록으로 보였을 것이다.
+# 전부 **오늘 실물에서 나온 것**이거나 이 레포의 기록된 재발이다. 추측 규칙은 넣지 않는다 —
+# FP 가 늘면 이 린트가 무시되고, 무시되는 린트는 없는 린트보다 나쁘다(경고 하나가 0건보다
+# 나쁠 수 있다: 0건은 «아무도 안 봤다»로 남지만 1건은 «봤고 이것만 나왔다»로 접힌다).
+RULES=(
+'P1§^[[:space:]]*[A-Za-z_][A-Za-z0-9_]*=\$\((cat|sed|awk|grep|head|tail|python3?|node|jq)[^)]*\)§[후보] set -e 아래 명령치환 ASSIGNMENT — 파일 부재 시 그 줄에서 즉사. set -e 판별이 파일 스코프라 확정 아님§`|| true` 를 붙여라. 2>/dev/null 도 ${VAR:-기본값} 도 이걸 못 막는다(할당문 자체가 죽으므로). [ -f ] 가드도 present-but-unreadable arm 을 못 막는다 — 2026-08-16 4방 매트릭스가 반증'  # portability-noqa: 규칙표 데이터이지 실행 코드가 아니다
+'P2§stat -f §`stat -f` 가 먼저 오면 GNU 에서 **성공한다** — 파일시스템 정보를 내고 폴백이 영영 안 돈다§stat -c %Y … 2>/dev/null || stat -f %m … 2>/dev/null || echo 0 순서로. GNU-first 가 맞다'  # portability-noqa: 규칙표 데이터이지 실행 코드가 아니다
+'P3§sed -i[[:space:]]+[^-.]§`sed -i` 는 BSD 가 백업 접미사를 요구한다 — GNU 폼은 macOS 에서 다음 토큰을 파일명으로 먹는다§sed -i.bak 후 삭제, 또는 sed … > tmp && mv tmp f'  # portability-noqa: 규칙표 데이터이지 실행 코드가 아니다
+'P4§grep -P§`grep -P` 는 BSD/macOS 기본 grep 에 없다§grep -E 로 낮추거나 perl -ne 로'  # portability-noqa: 규칙표 데이터이지 실행 코드가 아니다
+'P5§\$\{PIPESTATUS§`${PIPESTATUS[…]}` 는 zsh 에서 빈 문자열이다 — 판정이 "" 로 접힌다§bash 전용이면 shebang 확인. 더 나은 형태: 파이프를 빼고 out=$(cmd); rc=$?'  # portability-noqa: 규칙표 데이터이지 실행 코드가 아니다
+'P6§readlink -f§`readlink -f` 는 구형 BSD 에 없다§cd "$(dirname "$f")" && pwd -P 조합으로'  # portability-noqa: 규칙표 데이터이지 실행 코드가 아니다
+'P7§date -d §`date -d` 는 GNU 전용 — BSD 는 date -v§epoch 로 계산하거나 두 폼을 || 로 잇되 GNU-first'  # portability-noqa: 규칙표 데이터이지 실행 코드가 아니다
+'P9§"(package\.json|bin/)§테스트가 **레포 고유 파일**을 픽스처로 참조한다 — 이식된 자산에서 전량 FAIL 한다§자기 픽스처를 mktemp 로 만들어 써라. 2026-08-16 PMH 이식에서 selfcheck 35 FAIL 의 원인'  # portability-noqa: 규칙표 데이터이지 실행 코드가 아니다
+)
+
+_hits=0
+_emit() { [ "$QUIET" = 1 ] || printf '%s\n' "$*"; }
+
+lint_file() {
+  local f="$1" rule id re why fix line n
+  # 🟥 끊어진 심링크는 «소견 없음»이 아니라 **미측정**이다 (cross-family 2026-08-16).
+  if [ -L "$f" ] && [ ! -e "$f" ]; then
+    _emit "  [UNMEASURED] $f — 끊어진 심링크. 읽지 못했다(초록이 아니다)."
+    return 0
+  fi
+  # 🟥 **로케일 fail-open — cross-family 가 양쪽 로케일을 실제로 돌려서 잡았다.**
+  # UTF-8 로케일에서 대상 줄에 비-UTF8 바이트가 있으면 `grep -nE` 가 **매치하지 않고**, 그
+  # 실패가 삼켜져 최종 「소견 없음」으로 접힌다. 같은 입력이 `LC_ALL=C` 에서는 검출됐다.
+  # 즉 «무매치»와 «해석 실패»가 구분되지 않는 fail-open 이고, 이 린트가 잡으라고 만들어진
+  # 클래스 그 자체다. 이 함수의 모든 매칭을 **바이트 기반으로 고정**한다.
+  local LC_ALL=C LANG=C
+  # P1 은 «set -e 계열이 켜져 있는 파일»에서만 의미가 있다. 아니면 FP 폭발.
+  # ⚠️ 이 판별은 **파일 스코프**라 정확하지 않다 (cross-family 실측): 호출되지 않는 함수 안의
+  # `set -e` 로도 켜지고, 뒤따르는 `set +e` 로 꺼지지 않으며, 부모가 `set -e` 상태로 source 하는
+  # 파일은 **놓친다**. 그래서 P1 은 «확정 결함»이 아니라 **후보**다 — 출력 문구도 그렇게 낮춘다.
+  local has_sete=0
+  grep -qE '^[[:space:]]*set -[a-z]*e' "$f" 2>/dev/null && has_sete=1
+  for rule in "${RULES[@]}"; do
+    id="${rule%%§*}"; rest="${rule#*§}"
+    re="${rest%%§*}";  rest="${rest#*§}"
+    why="${rest%%§*}"; fix="${rest#*§}"
+    case "$id" in P1) [ "$has_sete" = 1 ] || continue ;; esac
+    while IFS= read -r line; do
+      n="${line%%:*}"; body="${line#*:}"
+      # noqa 이탈구: 알고 쓴 경우를 위한 문서화된 억제(전부 차단하면 우회를 훈련시킨다)
+      # noqa 는 **사유가 있어야** 억제한다. 초판은 문자열 존재만 봐서 사유 없이도, 심지어
+      # 문자열 리터럴 안에서도 억제됐다 — advisory 인 지금은 경미하나 `--strict` 를 게이트로
+      # 승격하는 순간 무료 우회로가 된다.
+      printf '%s' "$body" | grep -qE '#[[:space:]]*portability-noqa:[[:space:]]*[^[:space:]]' && continue
+      # 주석 전용 줄은 소견이 아니다. 이 레포는 결함을 **주석으로 길게 설명하는** 관습이 있어서
+      # (그 설명이 문제 패턴을 그대로 인용한다) 이걸 안 빼면 FP 가 구조적으로 쌓인다.
+      # 손검증 2026-08-16: 초판 50건 중 8건이 정확히 이 형태였다.
+      case "$(printf '%s' "$body" | sed 's/^[[:space:]]*//')" in '#'*) continue ;; esac
+      # P2 는 **순서**가 결함이지 `stat -f` 의 존재가 아니다. GNU-first(`stat -c … || stat -f …`)는
+      # 이 레포의 올바른 관용구이고, 초판은 그걸 12건 중 대다수로 지적했다 — 즉 규칙이 처방을
+      # 위반으로 렌더했다. 손검증 한 건이 이걸 잡았다(`_mtime()` 두 곳).
+      case "$id" in
+        P2) case "$body" in *'stat -c'*'stat -f'*) continue ;; esac ;;
+        # P7 도 같은 형태다 — `date -d … || date -v…` 는 GNU-first 폴백이라 **올바른 관용구**다.
+        # P2 에서 한 번 겪고도 새 규칙에 같은 오류를 심었다(손검증이 두 번째로 잡음).
+        P7) case "$body" in *'date -d'*'date -v'*) continue ;; esac ;;
+      esac
+      # P1 의 처방이 이미 적용된 줄은 소견이 아니다. 이 이탈구가 없으면 린트가 **자기 처방을
+      # 따른 코드를 계속 지적**하고, 그러면 사람이 린트를 끄게 된다 — self-test 가 잡았다.
+      # ⚠️ `2>/dev/null` 이나 `${VAR:-기본값}` 은 이탈 사유가 **아니다**: 둘 다 할당문의
+      # 즉사를 막지 못한다(2026-08-16 4방 매트릭스). 여기서 인정하는 건 `|| true` 뿐이다.
+      case "$id" in
+        P1) case "$body" in *'|| true'*|*'||true'*) continue ;; esac ;;
+      esac
+      _emit "  [$id] $f:$n"
+      _emit "        $why"
+      _emit "        → $fix"
+      _hits=$((_hits+1))
+    done < <(grep -nE "$re" "$f" 2>/dev/null)
+  done
+
+  # P8 — 가드 없는 glob 루프. 규칙표에 못 넣는다: **판정이 다음 줄에 있기 때문**이다.
+  # 줄 단위 정규식은 `for f in *.sh; do` 만 보고 바로 아래의 `[ -e "$f" ] || continue` 를
+  # 볼 수 없어서, 초판 self-test 가 known-negative 에서 오탐을 냈다(hits=1, expected 0).
+  # 계기의 시야가 한 줄이면 두 줄짜리 관용구를 영영 오판한다 — 그래서 여기만 창을 넓힌다.
+  while IFS= read -r line; do
+    n="${line%%:*}"; body="${line#*:}"
+    printf '%s' "$body" | grep -qE '#[[:space:]]*portability-noqa:[[:space:]]*[^[:space:]]' && continue
+    # 주석 전용 줄 제외 — RULES 루프엔 넣고 여기엔 안 넣어서, 이 블록이 **자기 자신을 설명하는
+    # 주석**을 소견으로 냈다(손검증이 잡음). 같은 이탈구는 두 루프에 **같이** 있어야 한다.
+    case "$(printf '%s' "$body" | sed 's/^[[:space:]]*//')" in '#'*) continue ;; esac
+    # 다음 2줄 안에 가드가 있으면 관용구를 지킨 것이다
+    if sed -n "$((n+1)),$((n+2))p" "$f" 2>/dev/null \
+         | grep -qE '\[ *-[efd] |\|\| *continue|nullglob'; then continue; fi
+    # 파일 어딘가에 nullglob 이 켜져 있으면 전역적으로 해결된 것이다
+    grep -qE '^[[:space:]]*shopt -s [a-z ]*nullglob' "$f" 2>/dev/null && continue
+    _emit "  [P8] $f:$n"
+    _emit "        glob 이 하나도 안 맞으면 **리터럴 문자열 자체**가 루프에 들어온다"
+    _emit "        → 루프 첫 줄에 \`[ -e \"\$f\" ] || continue\`, 또는 shopt -s nullglob"
+    _hits=$((_hits+1))
+  done < <(grep -nE 'for [A-Za-z_][A-Za-z0-9_]* in [^;]*\*[^;)]*; *do' "$f" 2>/dev/null)
+}
+
+# ── self-test (known-pair) ────────────────────────────────────────────────────
+# 이 린트가 «무엇을 못 잡는지»까지 고정한다. 컨트롤이 없으면 초록의 이유를 모른다.
+if [ "$SELFTEST" = 1 ]; then
+  t=$(mktemp -d) || { echo "harness-error: mktemp"; exit 10; }
+  trap 'rm -rf "$t"' EXIT
+  pass=0; failn=0
+  _ck(){ # _ck <label> <expect-hit:0|1> <file>
+    _hits=0; QUIET=1; lint_file "$3"; QUIET=0
+    if { [ "$2" = 1 ] && [ "$_hits" -gt 0 ]; } || { [ "$2" = 0 ] && [ "$_hits" -eq 0 ]; }; then
+      echo "  ✅ $1"; pass=$((pass+1))
+    else echo "  ❌ $1 (hits=$_hits, expected-hit=$2)"; failn=$((failn+1)); fi
+  }
+    # P1 known-positive — 오늘 `scripts/fh-gate.sh` 의 VERSION 할당이 정확히 이 형태였다.
+  # ⚠️ 행번호를 적지 않는다: 초판은 `:37` 이라 적었는데 **같은 세션의 수리가 그걸 :52 로 밀었고**,
+  # Axis 3 이 그 stale 참조를 잡았다. 이 커밋이 지적하는 결함 클래스의 자기재현이라 이름으로만 건다.
+  printf 'set -euo pipefail\nV=$(sed -n s/x/y/p package.json 2>/dev/null | head -1)\n' > "$t/p1_pos.sh"  # portability-noqa: self-test 픽스처 — 일부러 위반형을 쓴다
+  _ck "P1 known-positive (set -e + 명령치환 할당)" 1 "$t/p1_pos.sh"
+  # P1 known-negative — || true 가 붙으면 안 잡아야 한다
+  printf 'set -euo pipefail\nV=$(sed -n s/x/y/p f 2>/dev/null | head -1 || true)\n' > "$t/p1_neg.sh"  # portability-noqa: self-test 픽스처 — 일부러 위반형을 쓴다
+  _ck "P1 known-negative (|| true 있음)" 0 "$t/p1_neg.sh"
+  # P1 컨트롤 — set -e 가 없으면 애초에 해당 없음
+  printf 'V=$(cat package.json)\n' > "$t/p1_nosete.sh"
+  _ck "P1 컨트롤 (set -e 없음 → 해당없음)" 0 "$t/p1_nosete.sh"
+  # P2 stat BSD-first
+  printf 'm=$(stat -f %%m "$1" || stat -c %%Y "$1")\n' > "$t/p2_pos.sh"  # portability-noqa: self-test 픽스처 — 일부러 위반형을 쓴다
+  _ck "P2 known-positive (stat -f 선행)" 1 "$t/p2_pos.sh"
+  printf 'm=$(stat -c %%Y "$1" 2>/dev/null || echo 0)\n' > "$t/p2_neg.sh"  # portability-noqa: self-test 픽스처 — 일부러 위반형을 쓴다
+  _ck "P2 known-negative (GNU-first)" 0 "$t/p2_neg.sh"
+  # P5 PIPESTATUS
+  printf 'cmd | tail -1\nrc=${PIPESTATUS[0]}\n' > "$t/p5_pos.sh"  # portability-noqa: self-test 픽스처 — 일부러 위반형을 쓴다
+  _ck "P5 known-positive (PIPESTATUS)" 1 "$t/p5_pos.sh"
+  # P8 unguarded glob
+  printf 'for f in scripts/*.sh; do\n  echo "$f"\ndone\n' > "$t/p8_pos.sh"  # portability-noqa: self-test 픽스처 — 일부러 위반형을 쓴다
+  _ck "P8 known-positive (가드 없는 glob 루프)" 1 "$t/p8_pos.sh"
+  printf 'for f in scripts/*.sh; do\n  [ -e "$f" ] || continue\ndone\n' > "$t/p8_neg.sh"  # portability-noqa: self-test 픽스처 — 일부러 위반형을 쓴다
+  _ck "P8 known-negative (continue 가드)" 0 "$t/p8_neg.sh"
+  # noqa 이탈구가 실제로 억제하나
+  printf 'set -e\nV=$(cat package.json) # portability-noqa: 이 레포 전용 도구다\n' > "$t/noqa.sh"
+  _ck "noqa 억제 동작" 0 "$t/noqa.sh"
+  # 🟥 P3·P4·P6·P7·P9 는 초판에 레인이 **하나도 없었다** — 적대검증이 잡았다. 레인 없는 규칙은
+  # 정규식에 오타를 내도 self-test 가 `10 pass / 0 fail` 그대로라, 판별력이 미측정이다.
+  printf 'sed -i s/a/b/ f\n'            > "$t/p3_pos.sh"; _ck "P3 known-positive (sed -i GNU폼)" 1 "$t/p3_pos.sh"  # portability-noqa: self-test 픽스처 — 일부러 위반형을 쓴다
+  printf 'sed -i.bak s/a/b/ f\n'        > "$t/p3_neg.sh"; _ck "P3 known-negative (접미사 있음)" 0 "$t/p3_neg.sh"  # portability-noqa: self-test 픽스처 — 일부러 위반형을 쓴다
+  printf 'grep -P "\\d+" f\n'           > "$t/p4_pos.sh"; _ck "P4 known-positive (grep -P)" 1 "$t/p4_pos.sh"  # portability-noqa: self-test 픽스처 — 일부러 위반형을 쓴다
+  printf 'grep -E "[0-9]+" f\n'         > "$t/p4_neg.sh"; _ck "P4 known-negative (grep -E)" 0 "$t/p4_neg.sh"  # portability-noqa: self-test 픽스처 — 일부러 위반형을 쓴다
+  printf 'p=$(readlink -f "$1")\n'      > "$t/p6_pos.sh"; _ck "P6 known-positive (readlink -f)" 1 "$t/p6_pos.sh"  # portability-noqa: self-test 픽스처 — 일부러 위반형을 쓴다
+  printf 'p=$(cd "$(dirname "$1")" && pwd -P)\n' > "$t/p6_neg.sh"; _ck "P6 known-negative (pwd -P)" 0 "$t/p6_neg.sh"  # portability-noqa: self-test 픽스처 — 일부러 위반형을 쓴다
+  printf 'd=$(date -d @123 +%%s)\n'      > "$t/p7_pos.sh"; _ck "P7 known-positive (date -d)" 1 "$t/p7_pos.sh"  # portability-noqa: self-test 픽스처 — 일부러 위반형을 쓴다
+  printf 'd=$(date +%%s)\n'              > "$t/p7_neg.sh"; _ck "P7 known-negative (date +%s)" 0 "$t/p7_neg.sh"  # portability-noqa: self-test 픽스처 — 일부러 위반형을 쓴다
+  printf 'run_review "package.json"\n'  > "$t/p9_pos.sh"; _ck "P9 known-positive (레포고유 픽스처)" 1 "$t/p9_pos.sh"  # portability-noqa: self-test 픽스처 — 일부러 위반형을 쓴다
+  printf 'run_review "$t/fixture.json"\n' > "$t/p9_neg.sh"; _ck "P9 known-negative (자기 픽스처)" 0 "$t/p9_neg.sh"  # portability-noqa: self-test 픽스처 — 일부러 위반형을 쓴다
+
+  # 🟥 로케일 fail-open — cross-family 가 실측으로 잡은 것. 비-UTF8 바이트가 섞인 줄을
+  # UTF-8 로케일에서 돌려도 검출돼야 한다(lint_file 이 LC_ALL=C 로 고정하므로).
+  printf 'set -e\nV=$(cat package.json)\n\xff\n' > "$t/nonutf.sh"
+  ( export LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8; _ck "비-UTF8 바이트 (UTF-8 로케일에서도 검출)" 1 "$t/nonutf.sh" )
+
+  # 끊어진 심링크 — 조용한 «소견 없음» 이 아니라 UNMEASURED 로 나와야 한다
+  ln -s "$t/does_not_exist.sh" "$t/broken.sh" 2>/dev/null
+  _bo=$(QUIET=0; _hits=0; lint_file "$t/broken.sh"); case "$_bo" in
+    *UNMEASURED*) echo "  ✅ 끊어진 심링크 → UNMEASURED"; pass=$((pass+1)) ;;
+    *) echo "  ❌ 끊어진 심링크가 조용히 통과했다"; failn=$((failn+1)) ;;
+  esac
+
+  # 빈 파일 — 계기가 아무 데나 울리지 않는가
+  : > "$t/empty.sh"
+  _ck "빈 파일 (오탐 없음)" 0 "$t/empty.sh"
+  # 종결 verdict 한 줄 — selfcheck.sh 의 --self-test 루프가 이 문자열로 «실제로 돌았다»를 판정한다.
+  # 규약(그 루프의 주석): 이 줄은 **진짜 종결 판정**이어야 하고 한국어 테스트케이스 *제목*이면
+  # 안 된다. 제목이면 그 레인 이름 하나만 바꿔도 진짜 PASS 가 거짓 "dispatcher missing?" 으로
+  # 뒤집힌다(capability_registry_check 가 그 이유로 루프에서 빠졌다). 그래서 여기 딱 한 번,
+  # 요약 자리에서만 쓴다.
+  if [ "$failn" -eq 0 ]; then
+    echo "portability-lint 캘리브레이션 통과: $pass pass / 0 fail"
+    exit 0
+  fi
+  echo "portability-lint 캘리브레이션 실패: $pass pass / $failn fail"
+  exit 1
+fi
+
+# ── 본 실행 ───────────────────────────────────────────────────────────────────
+if [ "${#TARGETS[@]}" -eq 0 ]; then
+  while IFS= read -r f; do TARGETS+=("$f"); done < <(
+    { git ls-files '*.sh' 'templates/.git-hooks/*' 'bin/*' 2>/dev/null \
+      || find . \( -name '*.sh' -o -path './templates/.git-hooks/*' -o -path './bin/*' \) \
+           -not -path './.git/*' 2>/dev/null; } )
+fi
+[ "${#TARGETS[@]}" -gt 0 ] || { _emit "portability-lint: 대상 파일 0 — 잴 것이 없다(초록이 아니라 미측정)"; exit 0; }
+
+_emit "── portability-lint (${#TARGETS[@]} files) ──"
+for f in "${TARGETS[@]}"; do
+  [ -f "$f" ] || { [ -L "$f" ] && lint_file "$f"; continue; }
+  # 🟥 확장자 없는 셸 파일을 넣었으므로(templates/.git-hooks/pre-commit·pre-push, bin/fh-*)
+  # 비-셸 파일(.js 등)을 걸러야 한다. 판별은 확장자가 아니라 **shebang** 이다.
+  # 초판은 `git ls-files '*.sh'` 뿐이라 **이 레포에서 BSD/GNU 결함이 가장 비싼 두 파일**
+  # (pre-commit·pre-push)을 구조적으로 못 봤다 — 그리고 같은 커밋의 selfcheck 주석이
+  # «첫 스캔이 확장자 없는 훅을 놓쳤다»고 적어 놓고서 새 계기에 같은 스코프를 다시 심었다.
+  case "$f" in
+    *.sh) : ;;
+    *) head -1 "$f" 2>/dev/null | grep -qE '^#!.*\b(ba)?sh' || continue ;;
+  esac
+  lint_file "$f"
+done
+
+if [ "$_hits" -eq 0 ]; then
+  _emit "  소견 없음 (${#TARGETS[@]} files 스캔)"
+  exit 0
+fi
+_emit "── 소견 $_hits 건 ──"
+_emit "  advisory 다 — 이 린트만으로 막지 않는다. 알고 쓰는 줄엔 \`# portability-noqa: <사유>\`."
+[ "$STRICT" = 1 ] && exit 1
+exit 0

package/scripts/prepublish_scope_note.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# prepublish_scope_note.sh — the publish gate must test the ARTIFACT, not this machine.
+#
+# ── 왜 이 파일이 있나 (package.json 은 주석을 못 단다) ────────────────────────────
+# 2026-08-17 실측: `prepublishOnly` 체인이 `scripts/selfcheck.sh` 를 통과 조건으로 삼고
+# 있었고, 그 안의 **peer 하네스 어댑터 레인**은 «이 머신에 어떤 레포가 깔려 있는가» 에 따라
+# 판정이 갈린다. 결과:
+#
+#     CI (peer 레포 0개)      selfcheck 초록 — PEER_ABSENT 로 SKIP  → 출하 가능
+#     클러스터를 쓰는 노드     selfcheck 적색 — 어댑터 없는 peer 계기 → 출하 차단
+#
+# **peer 를 안 깐 머신은 출하할 수 있고, 실제로 클러스터를 쓰는 머신은 출하할 수 없다.**
+# 방향이 거꾸로다. 그리고 이 클래스는 같은 날 반대 방향으로도 밟혔다(픽스처가 gitignored
+# 파일을 인용 → 로컬 초록·CI 적색). 뿌리는 하나다:
+#
+#   > 검정이 «저장소에 무엇이 있는가» 가 아니라 «이 머신에 무엇이 있는가» 를 재고 있었다.
+#
+# ── 처방 (`fh_signal_2026-08-17_publish-depends-on-local-env.md` ⓑ) ─────────────
+# `prepublishOnly` 는 **출하물의 성질만** 본다:
+#     publish_freshness_check · version_lockstep_check · package_coverage --vs-tarball
+#     · public_surface_scan_files
+# peer 클러스터 상태는 출하물의 성질이 아니다. 그래서 selfcheck 는 이 체인에서 빠졌다.
+#
+# 🟥 **빠진 것이 «커버리지 상실» 이 되지 않게 하는 것이 이 스크립트의 실제 일이다.**
+# selfcheck 는 여전히 `npm test` 이고, **CI `validate` 잡이 매 푸시마다 돌린다** — 그리고
+# `validate` 는 main 의 **required check** 다(2026-08-12 실측: legacy
+# `required_status_checks.contexts = ["validate"]`). 즉 출하되는 커밋은 이미 selfcheck 를
+# 통과한 커밋이다. 그 전제가 참인지를 **여기서 기계로 확인한다** — 워크플로에서
+# selfcheck 호출이 사라지면 이 스크립트가 출하를 막는다. 산문 약속이 아니라 채널 검사다.
+#
+# ⚠️ **명시 잔여 — 축소해서 읽지 마라. 아래 넷은 cross-family 실측으로 확정된 구멍이다.**
+#   ⓐ 이 검사는 «워크플로가 selfcheck 를 호출한다» 는 **존재**를 볼 뿐, 그 잡이 이 커밋에서
+#      실제로 **초록이었는지**는 안 본다. 그건 ⓒ(CI 태그 출하 배선)의 일이고 미구축이다.
+#   ⓐ-2 🟥 **`if: false` 로 꺼진 잡은 못 잡는다**(codex 지적 #2, S). 호출 문자열은 살아 있고
+#      잡은 절대 안 돈다 — 이 게이트는 «커버리지 있음» 을 낸다. YAML 파서 없이는 조건식을
+#      평가할 수 없고, 파서를 여기 넣는 것은 이 스크립트의 일이 아니다. **미봉이라 적는다.**
+#   ⓐ-3 🟥 **어느 잡인지 안 본다**(codex 지적 #4, A). 위 주석은 `validate` 잡을 말하는데
+#      술어는 **파일 안 아무 잡이나** 받는다. required check 는 `validate` 하나뿐이므로
+#      다른 잡에 옮겨진 selfcheck 는 필수가 아니게 되지만 이 검사는 통과시킨다.
+#   ⓐ-4 🟥 **트리거를 안 본다**(codex 지적 #3, A). `on: pull_request` 만 있어도 통과한다 —
+#      그러면 출하되는 main 커밋 자체는 selfcheck 를 한 번도 안 탄다.
+#   ⇒ ⓐ-2~4 를 닫는 정직한 형태는 문자열 검사가 아니라 **`gh api` 로 실제 required check 와
+#      그 커밋의 conclusion 을 읽는 것**이다. 그건 네트워크 의존이라 출하 경로에 넣을지가
+#      별도 결정이고(오프라인 fail-closed 는 또 다른 과차단), 여기서 정하지 않는다.
+#   ⓑ `validate` 의 `strict: false` 는 그대로다 — 초록인 체크가 지금의 main 을 본 적이
+#      없을 수 있다(CLAUDE.md §4축 게이트 기계층에 이미 기록된 잔여).
+#   ⓒ 어댑터 레인 자체의 수리(레인 분리, 계기 부재 → SKIP)는 **qasp AX-ready 세션으로
+#      라우팅**됐다(`fh_signal_2026-08-17_qasp-adapter-phantom-air.md`). 여기서 손대지 않는다.
+#
+# 종료코드: 0 통과 · 1 커버리지 전제 파손(출하 차단) · 3 계기가 측정 불가(fail-closed)
+
+set -u
+
+WF=".github/workflows/validate.yml"
+SUBJ="scripts/selfcheck.sh"
+
+_note() {
+  echo "── prepublish scope ─────────────────────────────────────────────"
+  echo "   이 체인은 **출하물의 성질만** 검사한다 (freshness · lockstep ·"
+  echo "   tarball coverage · public surface). peer 클러스터 상태는 출하물의"
+  echo "   성질이 아니므로 selfcheck 는 여기 없다 — CI 'validate' 가 돌린다."
+}
+
+check() {
+  if [ ! -f "$WF" ]; then
+    echo "❌ INSTRUMENT ERROR  $WF 가 없다 — selfcheck 의 CI 커버리지를 확인할 수 없다."
+    echo "   측정 불가는 통과가 아니다(미측정 ≠ 0). 출하를 막는다."
+    return 3
+  fi
+  # 🟥 주석을 먼저 벗긴다. cross-family(codex/gpt-5.5) 실측 지적 #1(S): 초판은 `grep -qE
+  # "selfcheck\.sh"` 였고 **주석 처리된 호출에도 매칭**됐다 — 즉 `# - run: bash
+  # scripts/selfcheck.sh` 로 레인을 꺼놓아도 이 게이트는 «커버리지 있음» 을 냈다.
+  # 그리고 **언급이 아니라 호출**이어야 한다 — `echo "… scripts/selfcheck.sh …"` 는 실행이
+  # 아니다(실물 워크플로에 그런 줄이 실제로 있다). 그래서 줄의 **첫 토큰이 실행자**인 것만 센다.
+  # 🟥 첫 수리는 `run:` 을 같은 줄에서 요구했고 **실물에서 즉시 적색**이었다 — 실물은
+  #    `run: |` 블록 스칼라 안에서 호출한다(`validate.yml:150`). self-test 6/6 초록인데
+  #    실물이 빨간 상태였고, 그게 «픽스처가 실물을 대표하지 못한다» 의 교과서 형태다.
+  #    그래서 아래 known-pair 는 **실물 형태(블록 스칼라)를 그대로 뜬다.**
+  if ! sed 's/#.*//' "$WF" \
+     | grep -qE '^[[:space:]]*(-[[:space:]]+run:[[:space:]]*)?(bash|sh|source|\.)[[:space:]]+[^[:space:]]*selfcheck\.sh'; then
+    echo "❌ PUBLISH BLOCKED  $WF 가 더 이상 $SUBJ 를 호출하지 않는다."
+    echo ""
+    echo "   prepublishOnly 에서 selfcheck 를 뺀 근거는 «CI 가 대신 돌린다» 였다."
+    echo "   그 전제가 깨졌으므로 지금 출하하면 selfcheck 커버리지가 **어디에도 없다**."
+    echo ""
+    echo "   고르는 길 둘:"
+    echo "     ① $WF 에 selfcheck 호출을 복구한다 (원래 자리)"
+    echo "     ② selfcheck 를 prepublishOnly 로 되돌린다 — 단 그러면 2026-08-17 의"
+    echo "        «출하 가능 여부 = 이 머신의 디렉터리 구성» 결함이 함께 돌아온다"
+    return 1
+  fi
+  _note
+  echo "   ✅ CI 커버리지 확인: $WF 가 $SUBJ 를 호출한다"
+  return 0
+}
+
+# ── known-pair self-test — 컨트롤이 살아 있는지 보여주는 실행 출력 ────────────────
+if [ "${1:-}" = "--self-test" ]; then
+  t=$(mktemp -d) || exit 3
+  trap 'rm -rf "$t"' EXIT
+  pass=0; fail=0
+  _lane() { # $1 = 이름, $2 = 기대 rc, $3 = 워크플로 내용(빈 문자열이면 파일 없음)
+    local name="$1" want="$2" body="$3" got
+    ( cd "$t" && rm -rf .github && if [ -n "$body" ]; then
+        mkdir -p .github/workflows && printf '%s\n' "$body" > "$WF"
+      fi
+      WF="$WF" SUBJ="$SUBJ"; check >/dev/null 2>&1 ); got=$?
+    if [ "$got" = "$want" ]; then pass=$((pass+1)); echo "  PASS $name (rc=$got)"
+    else fail=$((fail+1)); echo "  FAIL $name — 기대 rc=$want, 실제 rc=$got"; fi
+  }
+  echo "prepublish_scope_note.sh --self-test"
+  _lane "known-positive: 워크플로가 selfcheck 호출"  0 "      - run: bash scripts/selfcheck.sh"
+  _lane "known-negative: 호출이 사라짐"              1 "      - run: echo hi"
+  _lane "계기 부재: 워크플로 파일 자체가 없음"        3 ""
+  # ★ cross-family 지적 #1(S) 회귀 앵커 — 주석 처리된 호출은 커버리지가 아니다.
+  _lane "★주석 처리된 호출은 커버리지 아님"          1 "      # - run: bash scripts/selfcheck.sh
+      - run: echo no selfcheck"
+  # ★ 과차단 컨트롤 — 주석을 벗기는 수리가 **정상 호출까지** 죽이지 않았는지. 이게 없으면
+  #   위 레인은 «전부 차단하는 계기» 로도 초록이 된다(컨트롤 있음 ≠ 판별력 있음).
+  _lane "★컨트롤: 주석과 실호출이 같이 있으면 통과"  0 "      # - run: bash scripts/selfcheck.sh   (구버전)
+      - run: bash scripts/selfcheck.sh"
+  # ★ 실물 형태 — `run: |` 블록 스칼라 안에서의 호출. 이게 실제 validate.yml 의 모양이고,
+  #   초판 정규식은 여기서 죽었다(self-test 는 초록인데 실물이 적색이었다).
+  _lane "★실물 형태: run: | 블록 안 호출"            0 "      - name: Selfcheck
+        run: |
+          echo \"=== scripts/selfcheck.sh ===\"
+          bash scripts/selfcheck.sh"
+  # ★ 언급 ≠ 실행. 같은 블록 안에 echo 로만 이름이 있으면 커버리지가 아니다.
+  _lane "★echo 언급만 있으면 커버리지 아님"          1 "      - name: Selfcheck
+        run: |
+          echo \"=== scripts/selfcheck.sh 는 로컬에서 돌린다 ===\"
+          echo done"
+  echo "  ── $pass pass / $fail fail"
+  [ "$fail" -eq 0 ] || exit 1
+  exit 0
+fi
+
+check
+exit $?