@chrono-meta/fh-gate 3.4.0 → 3.6.0

package/scripts/test_preprep_promise_lanes.sh

@@ -13,7 +13,7 @@
 #   Q4 판정보류 «맞나» 로 사람에게 넘기지 «틀렸다» 고 단정하지 않는다
 set -uo pipefail
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-SKILL="$HERE/plugins/fh-commons/skills/preprep"
+SKILL="$HERE/plugins/fh-preprep/skills/preprep"
 PASS=0; FAIL=0
 ok(){ echo "  ✅ $1"; PASS=$((PASS+1)); }
 ng(){ echo "  ❌ $1"; FAIL=$((FAIL+1)); }

package/scripts/test_preprep_retired_lanes.sh

@@ -12,7 +12,7 @@
 #   R4 처방     대체어를 finding 에 싣나 (처방 없는 판정은 절반이다)
 set -uo pipefail
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-SKILL="$HERE/plugins/fh-commons/skills/preprep"
+SKILL="$HERE/plugins/fh-preprep/skills/preprep"
 PASS=0; FAIL=0
 ok(){ echo "  ✅ $1"; PASS=$((PASS+1)); }
 ng(){ echo "  ❌ $1"; FAIL=$((FAIL+1)); }
@@ -50,5 +50,48 @@ g(){ python3 -c "import json,sys;d=json.loads(sys.argv[1]);print(d[sys.argv[2]][
 case "$(g use msg)" in *측정하다*) ok "R4 처방: 대체어를 finding 에 싣는다" ;;
                        *) ng "R4 실패 — 처방 없는 판정이다: $(g use msg)" ;; esac
 
-echo "retired lanes: $PASS passed, $FAIL failed"
+
+# ── C 갈래 (2026-09-13 신설) — 설정을 못 읽은 것이 «발견» 으로 나가지 않나 ─────────────
+#
+# 실사고: `python3 preprep.py` 를 인자 없이 돌리면 **트레이스백으로 죽고 rc=1** 이었다.
+# 이 도구의 선언(SKILL.md:164)은 「0 통과 · 1 발견 · 2 판정불가(계기오류/미측정)」이므로
+# 🟥 **1 은 「뭔가 찾았다」** 다 — 즉 「한 줄도 못 쟀다」가 「발견 있음」과 **같은 값**으로 나갔고
+# 부르는 쪽이 둘을 못 갈랐다. Done-When #1(「종료코드가 0/1/2 로 확정」)이 잡으라는 바로 그것이다.
+#
+# 여기서 재는 것: 설정 부재·깨짐·계약 미달 셋이 전부 **2** 로 확정되나, 그리고 정상 설정은
+# 여전히 2 가 «아닌» 값을 내나(컨트롤 — 항상 2 면 판별력이 0 이다).
+PP="$HERE/plugins/fh-preprep/skills/preprep/preprep.py"
+CT=$(mktemp -d); trap 'rm -rf "$CT"' EXIT
+
+_rc(){ ( cd "$CT" && python3 "$PP" "$1" >/dev/null 2>&1 ); printf '%s' "$?"; }
+
+C1=$(_rc "$CT/does_not_exist.yaml")
+[ "$C1" = "2" ] && ok "C1 설정 부재 → rc=2 (판정불가 · 발견 아님)"                 || ng "C1 설정 부재가 rc=$C1 — «발견 있음»(1)이나 트레이스백과 안 갈린다"
+
+printf 'root: [ unclosed
+' > "$CT/broken.yaml"
+C2=$(_rc "$CT/broken.yaml")
+[ "$C2" = "2" ] && ok "C2 YAML 깨짐 → rc=2" || ng "C2 깨진 설정이 rc=$C2"
+
+printf '' > "$CT/empty.yaml"
+C3=$(_rc "$CT/empty.yaml")
+[ "$C3" = "2" ] && ok "C3 빈 설정(파싱은 됨 · 계약 미달) → rc=2"                 || ng "C3 빈 설정이 rc=$C3 — 「돌았는데 발견 0」으로 읽힌다"
+
+# 🟥 컨트롤 — 정상 설정에서는 2 가 «안» 나와야 한다. 안 그러면 위 셋은 아무것도 증명 못 한다.
+# 🟥 `kind` 가 빠지면 도구가 **옳게** «기계 어댑터 없음 → UNMEASURED → rc=2» 를 낸다.
+#    초판 픽스처가 그걸 빠뜨려 컨트롤이 죽었고(정상 설정도 2) C1~C3 이 아무것도 증명하지
+#    못했다 — 컨트롤이 대상과 같이 죽으면 차이가 사라진다. 도구가 아니라 픽스처가 틀렸다.
+printf 'root: %s
+surfaces:
+  - id: s1
+    path: deck.md
+    kind: markdown
+' "$CT" > "$CT/ok.yaml"
+printf '# 제목
+본문 한 줄.
+' > "$CT/deck.md"
+C4=$(_rc "$CT/ok.yaml")
+[ "$C4" != "2" ] && ok "C4 컨트롤: 정상 설정은 2 가 아니다 (실측 rc=$C4) — 판별력 있음"                  || ng "C4 컨트롤 죽음: 정상 설정도 rc=2 — 위 셋은 아무것도 증명하지 않는다"
+
+echo "retired + config-verdict lanes: $PASS passed, $FAIL failed"
 [ "$FAIL" -eq 0 ] || exit 1

package/scripts/test_preprep_slide_refs_lanes.sh

@@ -12,7 +12,7 @@
 # 종료코드: 0 pass · 1 레인 실패 · 2 대상 부재 · 10 setup 실패
 set -uo pipefail
 cd "$(dirname "$0")/.." || exit 10
-LANE=plugins/fh-commons/skills/preprep/lane_slide_refs.py
+LANE=plugins/fh-preprep/skills/preprep/lane_slide_refs.py
 [ -f "$LANE" ] || { echo "ⓘ $LANE absent — subject missing (NOT a pass)"; exit 2; }
 command -v python3 >/dev/null 2>&1 || { echo "ⓘ python3 absent — setup broke"; exit 10; }
 T=$(mktemp -d) || exit 10; trap 'rm -rf "$T"' EXIT
@@ -20,7 +20,7 @@ T=$(mktemp -d) || exit 10; trap 'rm -rf "$T"' EXIT
 #    판별자를 뮤턴트로 바꿨다가 원본을 복원했는데 **스테일 __pycache__ 가 뮤턴트를 계속
 #    먹여** 「복원했는데도 적색」이 나왔다. 반대 방향이 더 위험하다 — 뮤턴트를 넣었는데
 #    캐시가 원본을 먹이면 «되돌려도 초록» 이 되어 **앵커가 죽은 것을 못 본다**.
-rm -rf plugins/fh-commons/skills/preprep/__pycache__
+rm -rf plugins/fh-preprep/skills/preprep/__pycache__
 PASS=0; FAIL=0
 ok(){ echo "  ✅ $1"; PASS=$((PASS+1)); }
 ng(){ echo "  ❌ $1"; FAIL=$((FAIL+1)); }
@@ -28,7 +28,7 @@ ng(){ echo "  ❌ $1"; FAIL=$((FAIL+1)); }
 RUN=$T/run.py
 cat > "$RUN" <<'PY'
 import sys, os, types
-sys.path.insert(0, 'plugins/fh-commons/skills/preprep')
+sys.path.insert(0, 'plugins/fh-preprep/skills/preprep')
 
 # 🟥 python-pptx 를 **의존하지 않는다**. 이 스위트는 «분류» 를 재는 것이고, 그 입력은
 #    「장 → 화면 텍스트 · 노트」라는 **작은 오리 타입**이 전부다(lane 의 _texts/
@@ -151,7 +151,7 @@ echo "$OUT" | grep -q 'SLIDE 1' \
 
 echo "== 배선·퇴화 =="
 OUT=$(python3 -c "
-import sys; sys.path.insert(0,'plugins/fh-commons/skills/preprep')
+import sys; sys.path.insert(0,'plugins/fh-preprep/skills/preprep')
 import lane_slide_refs as L
 print(L.scan({}, '.')[1][0])
 print(L.scan({'surfaces_by_id':{'built_deck':{'path':'/nope/none.pptx'}}}, '.')[1][0])
@@ -160,7 +160,7 @@ echo "$OUT" | grep -q 'NOT_CONFIGURED' && echo "$OUT" | grep -q 'UNMEASURED' \
   && ok "L8 미선언 → NOT_CONFIGURED · 실물 없음 → UNMEASURED (둘 다 0 아님)" \
   || ng "L8 퇴화 표기가 0 으로 접힌다: $OUT"
 
-grep -q "import lane_slide_refs" plugins/fh-commons/skills/preprep/preprep.py \
+grep -q "import lane_slide_refs" plugins/fh-preprep/skills/preprep/preprep.py \
   && ok "L9 배선: preprep.py 가 이 레인을 부른다" \
   || ng "L9 배선 없음 — 정의만 있고 아무도 안 부른다(built-but-not-wired)"
 

package/scripts/test_usage_ledger_lanes.sh

@@ -0,0 +1,284 @@
+#!/usr/bin/env bash
+# 사용 원장 계기 보정 레인 — 「행이 0 줄」이 무엇을 뜻하는지 가르는 것이 이 레인의 전부다.
+#
+# ## 왜 이 레인이 있나
+#
+# 사용 지표는 **부재를 0 으로 렌더하기 가장 쉬운 계기**다. 원장이 비어 있을 때 가능한 원인이 넷이고
+# 넷 다 출력이 똑같이 「0」이다:
+#   ① 옵트인을 안 켰다(설계대로)  ② 켰는데 쓰기가 실패했다  ③ 배선이 끊겼다  ④ 진짜로 아무도 안 썼다
+# 이 레인은 ①②③ 을 ④ 와 갈라내는 장치다. 그리고 마지막 레인(되돌림)은 **이 레인 자신이 장식인지**를
+# 묻는다 — 배선을 떼면 known-positive 가 정확히 빨개져야 한다.
+#
+# 실행: bash scripts/test_usage_ledger_lanes.sh
+set -u
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PREPREP="$REPO_ROOT/plugins/fh-preprep/skills/preprep"
+PASS=0; FAIL=0; SKIP=0
+ok(){ printf '  ✅ %s\n' "$1"; PASS=$((PASS+1)); }
+ng(){ printf '  ❌ %s\n' "$1"; FAIL=$((FAIL+1)); }
+sk(){ printf '  ⬜ SKIP %s\n' "$1"; SKIP=$((SKIP+1)); }
+
+TMPROOT=$(mktemp -d); trap 'rm -rf "$TMPROOT"' EXIT
+# 🟥 `|| true` 를 안 쓴다 — 폴백은 계기 고장을 「0」으로 접는다(이 저장소가 이름으로 관리하는 부류).
+#    `grep -c .` 는 입력이 비면 «0» 을 찍고 rc=1 을 낸다: 값은 이미 옳으므로 rc 를 삼킬 이유가 없다.
+#    값이 아예 안 나오는 경우(계기 고장)는 HARNESS-ERROR 를 돌려 **모든 비교를 실패**시킨다.
+# 🟥 grep 경로를 변수로 뺀다 — 레인 ⑦ 이 **테스트 더블이 아니라 이 함수 자신**에 고장을 주입해
+#    HARNESS-ERROR 가지가 실제로 밟히는지 보기 위해서다(안 밟힌 가드는 장식이다).
+GREP_BIN="${GREP_BIN:-/usr/bin/grep}"
+rows(){ local n; n=$(cat "$1"/*.jsonl 2>/dev/null | "$GREP_BIN" -c . 2>/dev/null); [ -n "${n:-}" ] || n="HARNESS-ERROR"; printf '%s' "$n"; }
+
+echo "== ① known-pair — 무엇이 행을 만들고 무엇이 안 만드나 =="
+
+D1="$TMPROOT/pos"; mkdir -p "$D1"
+( cd "$PREPREP" && FH_USAGE_LEDGER="$D1" python3 preprep.py --self-test >/dev/null 2>&1 )
+[ "$(rows "$D1")" = "1" ] \
+  && ok "known-positive: 옵트인 켜고 1회 실행 → 행 1 (실측 $(rows "$D1"))" \
+  || ng "known-positive 실패 — 행 $(rows "$D1") · 🟥 이 레인은 UNCALIBRATED 다"
+
+D2="$TMPROOT/neg1"; mkdir -p "$D2"
+( cd "$PREPREP" && env -u FH_USAGE_LEDGER python3 preprep.py --self-test >/dev/null 2>&1 )
+[ "$(rows "$D2")" = "0" ] && [ -z "$(ls -A "$D2" 2>/dev/null)" ] \
+  && ok "known-negative ①: 옵트인 끄면 파일 자체가 안 생긴다(배포본 무동작)" \
+  || ng "known-negative ① — 옵트인 없이 뭔가 남았다: $(ls -A "$D2" | tr '\n' ' ')"
+
+D3="$TMPROOT/neg2"; mkdir -p "$D3"
+( cd "$PREPREP" && FH_USAGE_LEDGER="$D3" python3 -c "import preprep" >/dev/null 2>&1 )
+[ "$(rows "$D3")" = "0" ] \
+  && ok "known-negative ②: import 만 하면 행 0 (라이브러리 사용은 실행이 아니다)" \
+  || ng "known-negative ②: import 가 행을 만들었다 — 배선 지점이 __main__ 이 아니다"
+
+echo
+echo "== ② 부재는 0 이 아니다 =="
+OUT=$(env -u FH_USAGE_LEDGER python3 "$REPO_ROOT/scripts/usage_report.py" --harness preprep 2>&1); RC=$?
+if [ "$RC" = "9" ] && printf '%s' "$OUT" | /usr/bin/grep -q "NOT-INSTRUMENTED"; then
+  ok "known-negative ③: 원장 없음 → rc=9 · NOT-INSTRUMENTED (「사용자 0 명」 아님)"
+else
+  ng "known-negative ③: 부재를 0 으로 렌더한다 — rc=$RC"
+fi
+OUT2=$(FH_USAGE_LEDGER="$D1" python3 "$REPO_ROOT/scripts/usage_report.py" --harness preprep 2>&1); RC2=$?
+if [ "$RC2" = "0" ] && printf '%s' "$OUT2" | /usr/bin/grep -q "INSTRUMENTED"; then
+  ok "대칭 컨트롤: 원장 있음 → rc=0 · INSTRUMENTED (부재 판정이 항상 나오는 게 아니다)"
+else
+  ng "대칭 컨트롤 실패 — 원장이 있는데도 부재로 읽는다 (rc=$RC2)"
+fi
+
+echo
+echo "== ③ residency — 인자가 담길 «칸»이 아예 없나 =="
+# 🟥 픽스처의 홈 경로는 **런타임 $HOME 으로 만든다** — 리터럴로 박으면 이 레인 파일 자신이
+#    공개 표면에 절대 홈 경로를 남긴다(공개표면 스캔이 내 커밋을 막았고, 옳게 막았다).
+#    런타임 조립이 더 강한 픽스처이기도 하다: 이 머신의 «진짜» 홈 경로로 시험한다.
+R=$( cd "$PREPREP" && python3 - "$PREPREP" <<'PY'
+import json, os, sys, tempfile, time
+sys.path.insert(0, sys.argv[1]); import usage_ledger as U
+ALLOWED={"v","ts","h","e","actor","author","wall_ms","cpu_ms","rc","out","llm","n"}
+d=tempfile.mkdtemp(); os.environ["FH_USAGE_LEDGER"]=d
+U.record("preprep", os.path.expanduser("~") + "/internal/TCKT-12345?token=abc", 1, 1, 0, "DONE")
+row=json.loads(open(os.path.join(d,"preprep-"+time.strftime("%Y-%m",time.gmtime())+".jsonl")).read().strip())
+blob=json.dumps(row,ensure_ascii=False)
+bad=[t for t in ("internal","TCKT-12345","token",os.path.expanduser("~"),os.environ.get("USER",""),os.uname().nodename) if t and t in blob]
+print("%s|%s|%s" % (",".join(sorted(set(row)-ALLOWED)) or "none", ",".join(bad) or "none", row.get("e")))
+PY
+)
+EXTRA="${R%%|*}"; REST="${R#*|}"; LEAK="${REST%%|*}"; ENTRY="${REST##*|}"
+[ "$EXTRA" = "none" ] && ok "스키마 화이트리스트: 정의 밖 키 0 (인자를 담을 칸이 없다)" \
+                      || ng "스키마에 미정의 키가 있다: $EXTRA"
+[ "$LEAK" = "none" ]  && ok "유출 없음: 홈 경로·내부 식별자·사용자명·호스트명 어느 것도 행에 없다" \
+                      || ng "🟥 행에 남았다: $LEAK"
+[ "$ENTRY" = "other" ] && ok "진입점 이름 새니타이즈: 형태 벗어난 값 → «other» (실측 «${ENTRY}»)" \
+                       || ng "진입점 이름이 그대로 통과했다: «${ENTRY}»"
+
+echo
+echo "== ④ 관측이 판정을 바꾸지 않는다 =="
+( cd "$PREPREP" && env -u FH_USAGE_LEDGER python3 preprep.py --self-test >/dev/null 2>&1 ); RC_OFF=$?
+D4="$TMPROOT/rc"; mkdir -p "$D4"
+( cd "$PREPREP" && FH_USAGE_LEDGER="$D4" python3 preprep.py --self-test >/dev/null 2>&1 ); RC_ON=$?
+[ "$RC_OFF" = "$RC_ON" ] \
+  && ok "종료코드 동일: 원장 off=$RC_OFF · on=$RC_ON (observe 는 판정을 통과시킨다)" \
+  || ng "🟥 원장이 종료코드를 바꿨다: off=$RC_OFF on=$RC_ON — 즉시 배선을 떼라"
+
+echo
+echo "== ⑤ 두 사본이 갈리지 않았나 =="
+QA_COPY="$HOME/projects/qasp-dev/scripts/usage_ledger.py"
+if [ -f "$QA_COPY" ]; then
+  A=$(shasum -a 256 "$PREPREP/usage_ledger.py" | awk '{print $1}')
+  B=$(shasum -a 256 "$QA_COPY" | awk '{print $1}')
+  [ "$A" = "$B" ] && ok "사본 동일 (sha256 ${A:0:12}…) — 관대함이 갈린 중복 정규화 없음" \
+                  || ng "🟥 두 사본이 갈렸다 — ${A:0:12}… vs ${B:0:12}…"
+else
+  sk "qasp 사본 없음 — 이 머신에 그 레포가 없다(부재이지 통과가 아니다)"
+fi
+
+echo
+echo "== ⑥ 되돌림 프로브 — 이 레인이 장식인가 =="
+BK="$TMPROOT/preprep.py.bak"; cp "$PREPREP/preprep.py" "$BK"
+python3 - "$PREPREP/preprep.py" <<'PY'
+import io,sys
+F=sys.argv[1]; s=io.open(F,encoding="utf-8").read()
+OLD="sys.exit(_observe('preprep', 'cli', main) if _observe else main())"
+assert s.count(OLD)==1, "되돌림 앵커 없음(%d) — 프로브가 대상을 못 찾았다" % s.count(OLD)
+io.open(F,"w",encoding="utf-8").write(s.replace(OLD,"sys.exit(main())",1))
+PY
+if [ $? -ne 0 ]; then ng "되돌림 프로브가 배선을 못 찾았다 — 프로브 자체가 죽었다"; else
+  D9="$TMPROOT/revert"; mkdir -p "$D9"
+  ( cd "$PREPREP" && FH_USAGE_LEDGER="$D9" python3 preprep.py --self-test >/dev/null 2>&1 )
+  [ "$(rows "$D9")" = "0" ] \
+    && ok "배선을 떼니 known-positive 가 정확히 빨개진다(행 0) — 레인이 실물을 본다" \
+    || ng "🟥 배선을 뗐는데도 행이 남는다($(rows "$D9")) — 이 레인은 다른 것을 보고 있다"
+fi
+cp "$BK" "$PREPREP/preprep.py"
+CUR=$(shasum -a 256 "$PREPREP/preprep.py" | awk '{print $1}')
+ORIG=$(shasum -a 256 "$BK" | awk '{print $1}')
+[ "$CUR" = "$ORIG" ] && ok "복원 확인: preprep.py 원상복구" || ng "🟥 복원 실패 — 손으로 확인해라"
+
+echo
+echo "== ⑦ 계기 고장이 «0» 으로 접히지 않나 (폴백 제거의 짝) =="
+# 종전 코드는 `|| true` 라 grep 이 죽어도 rc 0 이었다. 지금은 값이 안 나오면 HARNESS-ERROR 다.
+HE=$(GREP_BIN=/nonexistent/grep rows "$D1")
+[ "$HE" = "HARNESS-ERROR" ] \
+  && ok "grep 을 죽이면 «HARNESS-ERROR» — 0 으로 접히지 않는다(실측 «${HE}»)" \
+  || ng "🟥 계기가 죽었는데 «${HE}» 를 돌려준다 — 고장이 「행 0」으로 접힌다"
+# 그리고 그 값이 **비교를 실패시키는지**까지 본다 — 접히지만 않고 조용하면 같은 결함이다
+if [ "$HE" = "1" ] || [ "$HE" = "0" ]; then
+  ng "🟥 HARNESS-ERROR 가 정상값과 구분되지 않는다"
+else
+  ok "그 값은 known-positive(1)·known-negative(0) 어느 비교도 통과 못 한다 — 크게 실패한다"
+fi
+
+echo
+echo "== ⑧ 관측 손실이 있으면 숫자가 «하한»이 되나 (codex A-1/A-2 수리의 짝) =="
+RPT="$REPO_ROOT/scripts/usage_report.py"
+# 컨트롤 먼저 — 깨끗한 원장에서는 하한 표시가 «안» 나와야 한다(항상 나오면 판별력 0)
+CLEAN=$(FH_USAGE_LEDGER="$D1" python3 "$RPT" --harness preprep 2>&1)
+printf '%s' "$CLEAN" | /usr/bin/grep -q "관측 손실" \
+  && ng "🟥 깨끗한 원장에서도 «관측 손실»이 뜬다 — 표시가 항상 켜져 있다(판별력 0)" \
+  || ok "컨트롤: 깨끗한 원장 → 하한 표시 없음"
+
+# 🟥 픽스처가 **20 행 이상**이어야 한다. 되돌림 프로브가 잡았다: 행이 적으면 수리를 되돌려도
+#    p95 가 «n<20 → UNCALIBRATED» 로 어차피 초록이라, 그 레인이 «다른 이유로» 통과한다
+#    (레인이 초록인 이유는 셋이고, 이건 ②「입력이 그 분기를 안 지나감」이다).
+D8="$TMPROOT/broken"; mkdir -p "$D8"; cp "$D1"/.salt "$D8"/ 2>/dev/null
+LF="$D8/preprep-$(date -u +%Y-%m).jsonl"
+i=0; while [ $i -lt 22 ]; do
+  printf '{"actor":"aa%02d","author":0,"cpu_ms":4,"e":"cli","h":"preprep","llm":null,"out":"DONE","rc":0,"ts":"%sT00:00Z","v":1,"wall_ms":%d}\n' \
+    "$i" "$(date -u +%Y-%m-%d)" "$((10+i))" >> "$LF"
+  i=$((i+1))
+done
+printf 'THIS IS NOT JSON\n' >> "$LF"
+B8=$(FH_USAGE_LEDGER="$D8" python3 "$RPT" --harness preprep 2>&1)
+printf '%s' "$B8" | /usr/bin/grep -q "관측 손실" \
+  && ok "깨진 줄 1 주입 → «관측 손실» 선언" \
+  || ng "🟥 깨진 줄이 있는데 조용하다 — 버린 관측이 작은 숫자가 된다"
+printf '%s' "$B8" | /usr/bin/grep -qE "비저자 ≥|저자 ≥" \
+  && ok "개수가 하한(≥)으로 렌더된다" \
+  || ng "🟥 개수가 여전히 확정값처럼 찍힌다"
+printf '%s' "$B8" | /usr/bin/grep -q "p95 지연   : UNCALIBRATED" \
+  && ok "p95 는 아예 안 낸다(손실 표본의 분위수는 의미 없다)" \
+  || ng "🟥 손실 표본에서 p95 를 냈다"
+
+echo
+echo "== ⑨ 쓰기 실패 카운터도 같은 강등을 일으키나 =="
+# 🟥 여기서 «쓰기 실패 3» 을 grep 하면 안 된다 — 그 문구는 커버리지 줄이라 수리 전에도 있었다.
+#    되돌림 프로브가 그걸 잡았다(수리를 되돌려도 초록). 봐야 할 것은 **강등이 실제로 걸렸나**다.
+D9E="$TMPROOT/errs"; mkdir -p "$D9E"; cp "$D1"/.salt "$D9E"/ 2>/dev/null
+i=0; LF9="$D9E/preprep-$(date -u +%Y-%m).jsonl"
+while [ $i -lt 22 ]; do
+  printf '{"actor":"bb%02d","author":0,"cpu_ms":4,"e":"cli","h":"preprep","llm":null,"out":"DONE","rc":0,"ts":"%sT00:00Z","v":1,"wall_ms":%d}\n' \
+    "$i" "$(date -u +%Y-%m-%d)" "$((10+i))" >> "$LF9"
+  i=$((i+1))
+done
+printf '3' > "$D9E/.errors"
+E9=$(FH_USAGE_LEDGER="$D9E" python3 "$RPT" --harness preprep 2>&1)
+printf '%s' "$E9" | /usr/bin/grep -q "관측 손실" \
+  && ok ".errors=3 (깨진 줄 0) → 강등이 걸린다" \
+  || ng "🟥 쓰기 실패를 알고도 숫자를 확정값으로 낸다"
+printf '%s' "$E9" | /usr/bin/grep -q "p95 지연   : UNCALIBRATED — 관측 손실" \
+  && ok "그 표본(n=22)에서도 p95 를 «관측 손실» 사유로 거른다" \
+  || ng "🟥 n≥20 인데 손실 표본의 p95 를 냈다"
+
+echo
+echo "== ⑩ 막히는 파일이 호스트를 멈춰 세우나 (codex B-3 수리의 짝) =="
+DF="$TMPROOT/fifo"; mkdir -p "$DF"; mkfifo "$DF/.salt" 2>/dev/null
+if [ -p "$DF/.salt" ]; then
+  START=$(date +%s)
+  ( cd "$PREPREP" && FH_USAGE_LEDGER="$DF" timeout 20 python3 preprep.py --self-test >/dev/null 2>&1 ); RC_F=$?
+  EL=$(( $(date +%s) - START ))
+  [ "$RC_F" = "0" ] && [ "$EL" -lt 15 ] \
+    && ok "«.salt 가 FIFO» 인데 ${EL}s 에 rc=0 으로 끝난다 — 관측이 호스트를 안 멈춘다" \
+    || ng "🟥 rc=$RC_F · ${EL}s — 관측이 호스트의 타이밍/종료를 바꿨다(124=timeout)"
+  [ "$(rows "$DF")" = "0" ] && ok "그 실행은 행을 안 남긴다(fail-closed — 조용한 성공 아님)" \
+                           || ng "🟥 막힌 경로인데 행이 남았다"
+  [ -s "$DF/.errors" ] && ok "실패가 .errors 에 세어졌다(값 $(cat "$DF/.errors")) — 안 막지만 안 조용하다" \
+                       || ng "🟥 실패가 아무 데도 안 세어졌다 — 조용한 0 이다"
+else
+  ng "mkfifo 실패 — 이 레인을 못 돌렸다(부재이지 통과가 아니다)"
+fi
+
+echo
+echo "== ⑪ «비저자 0» 분기도 강등되나 (codex R2 가 이름 댄, 레인이 안 밟던 자리) =="
+# 🟥 ⑧⑨ 의 픽스처는 비저자 22 행이라 이 분기를 **구조적으로 못 밟았다**. 저자 행만 + 깨진 줄.
+D11="$TMPROOT/zero"; mkdir -p "$D11"; cp "$D1"/.salt "$D11"/ 2>/dev/null
+LF11="$D11/preprep-$(date -u +%Y-%m).jsonl"
+printf '{"actor":"zz01","author":1,"cpu_ms":4,"e":"cli","h":"preprep","llm":null,"out":"DONE","rc":0,"ts":"%sT00:00Z","v":1,"wall_ms":11}\n' "$(date -u +%Y-%m-%d)" > "$LF11"
+# 컨트롤: 손실 없음 → «미관측» 문구(확정)가 맞다
+Z0=$(FH_USAGE_LEDGER="$D11" python3 "$RPT" --harness preprep 2>&1)
+printf '%s' "$Z0" | /usr/bin/grep -q "비저자 사용 \*\*미관측\*\*" \
+  && ok "컨트롤: 손실 없이 비저자 0 → 「미관측」(모른다 아님)" \
+  || ng "컨트롤이 깨졌다 — 손실 없는 0 도 「모른다」로 찍는다(항상 강등 = 판별력 0)"
+printf 'NOT JSON\n' >> "$LF11"
+Z1=$(FH_USAGE_LEDGER="$D11" python3 "$RPT" --harness preprep 2>&1)
+# 🟥 바늘을 «모른다» 로 잡으면 안 된다 — 그 낱말은 ② 재사용률 줄에도 있어서 **다른 줄을 문다**.
+#    되돌림 프로브(적용 확인 포함)가 그걸 잡았다: ① 을 죽였는데 레인이 초록이었다.
+printf '%s' "$Z1" | /usr/bin/grep -qE "① 사용자 +: 🟥 \*\*모른다\*\*" \
+  && ok "깨진 줄 추가 → ① 이 확정값에서 「모른다」로 바뀐다" \
+  || ng "🟥 비저자 0 분기가 손실을 무시하고 확정값을 낸다(codex A-1/A-2 잔여)"
+printf '%s' "$Z1" | /usr/bin/grep -q "비저자 표본 ≥0" \
+  && ok "재사용률도 같은 분기에서 강등된다" \
+  || ng "🟥 재사용률이 「표본 0」을 확정값으로 낸다"
+
+
+echo "== ⑫ 첫 실행 안내 — 세 상태가 갈리나 (미정 / 동의 / 거절) =="
+# 🟥 이 저장소의 동의 규율 그대로다: 부재 ≠ 승인, 그리고 **거절도 기록이다**.
+#    미설정은 «아직 안 정함» 이라 계속 뜨고, `off` 는 «싫다» 라 조용해진다. 나가는 문이
+#    거짓말(«도구가 고장난다»)이 아니라 `off` 여야 동의의 값이 안 떨어진다.
+_N_OUT(){ ( cd "$PREPREP" && env $1 python3 preprep.py 2>/dev/null ); }
+_N_ERR(){ ( cd "$PREPREP" && env $1 python3 preprep.py 2>&1 >/dev/null ); }
+
+if printf '%s' "$(_N_ERR "-u FH_USAGE_LEDGER")" | /usr/bin/grep -q '\[usage\]'; then
+  ok "⑫-1 미설정 → stderr 에 안내 (아직 안 정한 사람에게는 계속 뜬다)"
+else
+  ng "⑫-1 미설정인데 안내가 없다 — 아무도 켤 이유를 못 듣는다"
+fi
+if printf '%s' "$(_N_OUT "-u FH_USAGE_LEDGER")" | /usr/bin/grep -q '\[usage\]'; then
+  ng "🟥 ⑫-2 안내가 **stdout 을 오염**시킨다 — 부르는 쪽의 판정 파싱이 깨진다"
+else
+  ok "⑫-2 stdout 은 깨끗하다 (안내는 stderr 전용 — 관측이 대상을 안 바꾼다)"
+fi
+if printf '%s' "$(_N_ERR "FH_USAGE_LEDGER=off")" | /usr/bin/grep -q '\[usage\]'; then
+  ng "🟥 ⑫-3 `off` 로 거절했는데도 계속 뜬다 — 거절이 기록으로 안 받아들여진다"
+else
+  ok "⑫-3 off → 조용 (명시적 거절도 «정한 것»이다)"
+fi
+D12="$TMPROOT/notice"; mkdir -p "$D12"
+if printf '%s' "$(_N_ERR "FH_USAGE_LEDGER=$D12")" | /usr/bin/grep -q '\[usage\]'; then
+  ng "🟥 ⑫-4 경로를 줬는데도 안내가 뜬다"
+else
+  ok "⑫-4 경로 지정 → 조용 + 기록 시작 (행 $(rows "$D12"))"
+fi
+D12b="$TMPROOT/notice_off"; mkdir -p "$D12b"
+( cd "$PREPREP" && FH_USAGE_LEDGER=off python3 preprep.py >/dev/null 2>&1 )
+[ -z "$(ls -A "$D12b" 2>/dev/null)" ] && ok "⑫-5 off 는 행을 안 남긴다 (거절이 곧 무동작)" \
+                                      || ng "🟥 ⑫-5 off 인데 뭔가 남았다"
+( cd "$PREPREP" && env -u FH_USAGE_LEDGER python3 preprep.py >/dev/null 2>&1 ); _r1=$?
+( cd "$PREPREP" && FH_USAGE_LEDGER=off       python3 preprep.py >/dev/null 2>&1 ); _r2=$?
+( cd "$PREPREP" && FH_USAGE_LEDGER="$D12"    python3 preprep.py >/dev/null 2>&1 ); _r3=$?
+if [ "$_r1" = "$_r2" ] && [ "$_r2" = "$_r3" ]; then
+  ok "⑫-6 종료코드가 세 상태에서 동일 ($_r1) — «안 켜면 제대로 안 돈다» 는 **거짓**이다"
+else
+  ng "🟥 ⑫-6 상태마다 종료코드가 다르다 (미정=$_r1 off=$_r2 켜짐=$_r3)"
+fi
+echo
+echo "════════════════════════════════════════"
+printf '  PASS %s   FAIL %s   SKIP %s\n' "$PASS" "$FAIL" "$SKIP"
+echo "  ⚠️ SKIP 은 통과가 아니다."
+echo "════════════════════════════════════════"
+[ "$FAIL" -eq 0 ] || exit 1

package/scripts/usage_report.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""사용 원장 리포터 — 네 줄(사용자 · 재사용률 · p95 · 단가)을 낸다.
+
+🟥 **부재는 0 이 아니다.** 원장 디렉터리가 없거나 비면 `NOT-INSTRUMENTED` 로 끝내고 rc=9 를 낸다
+   — 「사용자 0 명」이라고 쓰지 않는다. 그 둘을 같은 얼굴로 렌더하는 것이 이 저장소가
+   이름으로 관리하는 결함 부류다.
+
+🟥 **표본이 작으면 p95 를 숫자로 주지 않는다.** n<20 이면 `UNCALIBRATED` 로 적고 최대·중앙만 준다.
+
+🟥 **두 번째 신호** — `--expect-dirs <glob>` 를 주면 산출 디렉터리 수와 원장 행 수를 대조한다.
+   한쪽만 보면 「계기가 안 돌았다」와 「아무도 안 썼다」가 같은 0 으로 보인다.
+
+사용:
+  python3 usage_report.py --harness preprep --days 30
+  python3 usage_report.py --harness act2 --expect-dirs 'outputs/act2/*/'
+"""
+import argparse
+import glob as globmod
+import json
+import os
+import sys
+import time
+
+
+def pct(vals, p):
+    if not vals:
+        return None
+    s = sorted(vals)
+    k = max(0, min(len(s) - 1, int(round(p / 100.0 * len(s) + 0.5)) - 1))
+    return s[k]
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--dir", default=os.environ.get("FH_USAGE_LEDGER", ""))
+    ap.add_argument("--harness", default=None)
+    ap.add_argument("--days", type=int, default=30)
+    ap.add_argument("--expect-dirs", default=None,
+                    help="두 번째 신호: 산출 디렉터리 glob. 행 수와 대조한다")
+    a = ap.parse_args(argv)
+
+    print("═" * 58)
+    if not a.dir:
+        print("  커버리지 : NOT-INSTRUMENTED — FH_USAGE_LEDGER 미설정")
+        print("  🟥 이것은 「사용자 0 명」이 아니다. 아무것도 안 쟀다는 뜻이다.")
+        print("═" * 58)
+        return 9
+    if not os.path.isdir(a.dir):
+        print("  커버리지 : NOT-INSTRUMENTED — 원장 디렉터리 없음 (%s)" % a.dir)
+        print("  🟥 이것은 「사용자 0 명」이 아니다.")
+        print("═" * 58)
+        return 9
+
+    pat = os.path.join(a.dir, ("%s-*.jsonl" % a.harness) if a.harness else "*.jsonl")
+    files = sorted(globmod.glob(pat))
+    if not files:
+        print("  커버리지 : NOT-INSTRUMENTED — 해당 하네스 원장 파일 없음")
+        print("             찾은 패턴: %s" % pat)
+        print("  🟥 이것은 「사용자 0 명」이 아니다.")
+        print("═" * 58)
+        return 9
+
+    cutoff = time.strftime("%Y-%m-%dT%H:%MZ",
+                           time.gmtime(time.time() - a.days * 86400))
+    rows, bad = [], 0
+    for f in files:
+        for line in open(f, encoding="utf-8"):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                r = json.loads(line)
+            except Exception:
+                bad += 1
+                continue
+            if r.get("ts", "") >= cutoff:
+                rows.append(r)
+
+    errs = 0
+    try:
+        errs = int(open(os.path.join(a.dir, ".errors")).read().strip() or 0)
+    except Exception:
+        errs = 0
+    # 🟥 `.errors` 는 자기 실패를 못 센다 — 디렉터리가 통째로 못 쓰이면 원장도 카운터도 안 남고
+    #    출력은 「행 0」이라는 깨끗한 얼굴이 된다. 그래서 쓰기 가능 여부를 **여기서 직접** 본다.
+    writable = os.access(a.dir, os.W_OK | os.X_OK)
+
+    work = [r for r in rows if r.get("out") == "DONE"]
+    skipped = len(rows) - len(work)
+    authors = {r["actor"] for r in rows if r.get("author")}
+    others = {}
+    for r in rows:
+        if not r.get("author"):
+            others[r["actor"]] = others.get(r["actor"], 0) + 1
+
+    # 🟥 원장 지문 — actor 해시는 **이 디렉터리의 salt** 로 만들어진다. 지문이 다른 두 리포트의
+    #    actor id 는 **같은 사람이라도 다르다**. 합치면 한 사람이 둘로 세어진다. 그래서 판정과
+    #    같은 실행에 지문을 찍는다(합칠 수 있는지는 이 줄이 답한다).
+    fp = "unknown"
+    try:
+        import hashlib
+        fp = hashlib.sha256(open(os.path.join(a.dir, ".salt")).read().strip().encode()).hexdigest()[:8]
+    except Exception:
+        pass
+    print("  하네스 %s · 최근 %d 일 · 원장 파일 %d · 원장 지문 %s"
+          % (a.harness or "(전체)", a.days, len(files), fp))
+    cov = "INSTRUMENTED"
+    if errs:
+        cov += " · 🟥 쓰기 실패 %d 건 (아래 수치는 그만큼 적게 셌다)" % errs
+    if bad:
+        cov += " · 깨진 줄 %d" % bad
+    if not writable:
+        cov += " · 🟥 원장 디렉터리에 쓸 수 없다 — 아래 「행 0」은 «안 썼다»가 아니라 «못 적었다»일 수 있다"
+    print("  커버리지 : %s" % cov)
+    # 🟥 cross-family codex 지목(2026-09-13, A-1/A-2): 종전엔 «깨진 줄 N» 을 커버리지에 적어놓고
+    #    아래 네 줄은 **살아남은 부분집합으로 확정값처럼** 찍었다. 버려진 관측은 더 작은 그럴듯한
+    #    숫자가 되지 「안 쟀다」가 되지 않는다 — 이 파일이 막겠다고 선언한 바로 그 부류다.
+    #    그래서 관측 손실이 하나라도 있으면 **모든 개수는 하한(≥)**이 되고 p95 는 강제 UNCALIBRATED 다.
+    incomplete = bool(bad) or bool(errs) or (not writable)
+    GE = "≥" if incomplete else ""
+    if incomplete:
+        print("  🟥 관측 손실 확인 — 아래 개수는 **하한(≥)**이고 p95 는 내지 않는다.")
+        print("     (깨진 줄 %d · 쓰기 실패 %d · 쓰기 가능 %s) 잃은 행이 몇인지는 «모른다»가 정답이다."
+              % (bad, errs, "예" if writable else "아니오"))
+    print("─" * 58)
+
+    # ① 사용자
+    if not others:
+        # 🟥 cross-family codex R2 지목(2026-09-13): 여기가 A-1/A-2 의 **남은 절반**이었다.
+        #    본선은 하한(≥)으로 고쳤는데 이 «비저자 0» 분기는 여전히 확정값을 찍고 있었다 —
+        #    그리고 레인 ⑧⑨ 의 픽스처가 비저자 22 행이라 **이 분기를 구조적으로 안 밟았다**.
+        #    관측 손실이 있으면 「0」이 아니라 「모른다」다.
+        if incomplete:
+            print("  ① 사용자     : 🟥 **모른다** — 비저자 행이 0 인데 관측 손실도 있다.")
+            print("                 「아무도 안 썼다」와 「쓴 것을 못 적었다」를 이 표본으로는 못 가른다.")
+            print("                 저자 ≥%d · 비저자 ≥0 (둘 다 하한)" % len(authors))
+        else:
+            print("  ① 사용자     : 🟥 비저자 사용 **미관측** (저자 %d · 비저자 0)" % len(authors))
+            print("                 → §04① 미충족. 「0 명」이 아니라 「아직 안 잡혔다」다 —")
+            print("                   남이 쓰려면 그쪽에서 FH_USAGE_LEDGER 를 켜야 한다(옵트인).")
+    else:
+        print("  ① 사용자     : 비저자 %s%d (머신-사용자 기준) · 저자 %s%d"
+              % (GE, len(others), GE, len(authors)))
+
+    # ② 재사용률
+    if others:
+        rep = sum(1 for v in others.values() if v >= 2)
+        vals = sorted(others.values())
+        if incomplete:
+            print("  ② 재사용률   : 산출 안 함 — 관측 손실이 있으면 비율은 분모가 틀린다"
+                  " (2회 이상 %s%d / 관측된 %s%d)" % (GE, rep, GE, len(others)))
+        else:
+            print("  ② 재사용률   : %d/%d = %.0f%% (2회 이상) · 1인당 실행 중앙 %d · 최대 %d"
+                  % (rep, len(others), 100.0 * rep / len(others),
+                     vals[len(vals) // 2], vals[-1]))
+    elif incomplete:
+        print("  ② 재사용률   : 산출 불가 — 비저자 표본 ≥0 이고 관측 손실도 있다(분모를 모른다)")
+    else:
+        print("  ② 재사용률   : 산출 불가 — 비저자 표본 0")
+
+    # ③ p95 (작업 행만)
+    w = [r.get("wall_ms", 0) for r in work if isinstance(r.get("wall_ms"), int)]
+    if incomplete:
+        print("  ③ p95 지연   : UNCALIBRATED — 관측 손실이 있는 표본에서 분위수는 못 낸다")
+    elif not w:
+        print("  ③ p95 지연   : 산출 불가 — 작업 행 0")
+    elif len(w) < 20:
+        print("  ③ p95 지연   : UNCALIBRATED (n=%d < 20) · 중앙 %d ms · 최대 %d ms"
+              % (len(w), pct(w, 50), max(w)))
+    else:
+        print("  ③ p95 지연   : %d ms (n=%d) · 중앙 %d ms · 최대 %d ms"
+              % (pct(w, 95), len(w), pct(w, 50), max(w)))
+    if skipped:
+        print("                 (비작업 행 %d 개 제외 — --help·조기 종료. 버린 게 아니라 갈랐다)"
+              % skipped)
+
+    # ④ 단가
+    llm_rows = [r for r in work if isinstance(r.get("llm"), dict)]
+    if not llm_rows:
+        cpu = [r.get("cpu_ms", 0) for r in work if isinstance(r.get("cpu_ms"), int)]
+        print("  ④ 판정 단가  : LLM 호출 **N/A — 결정적 경로**(이 진입점은 모델을 안 부른다)")
+        if cpu:
+            print("                 실행당 CPU 중앙 %d ms · 최대 %d ms" % (pct(cpu, 50), max(cpu)))
+        print("                 🟥 «0 원»이라고 쓰지 마라 — 안 부른 것과 공짜인 것은 다르다.")
+        print("                    쓸 수 있는 문장: 「이 판정은 모델을 안 부르므로 건당 토큰 비용이")
+        print("                    발생하지 않는다」. 그게 LLM 심판 대비 우위의 정확한 형태다.")
+    else:
+        tok = sum(r["llm"].get("tokens", 0) for r in llm_rows)
+        print("  ④ 판정 단가  : 실행당 토큰 평균 %.0f (LLM 실행 %d/%d)"
+              % (tok / float(len(llm_rows)), len(llm_rows), len(work)))
+
+    # 두 번째 신호
+    if a.expect_dirs:
+        n_dirs = len([p for p in globmod.glob(a.expect_dirs) if os.path.isdir(p)])
+        print("─" * 58)
+        mark = "✅ 일치" if n_dirs == len(work) else "🟥 어긋남"
+        print("  두 번째 신호 : 산출 디렉터리 %d vs 작업 행 %d — %s" % (n_dirs, len(work), mark))
+        if n_dirs != len(work):
+            print("                 둘이 다르면 「아무도 안 썼다」와 「계기가 안 돌았다」가")
+            print("                 갈린다. 디렉터리가 많으면 원장이 못 잡은 실행이 있다.")
+    else:
+        print("─" * 58)
+        print("  두 번째 신호 : 없음 — 이 수치는 원장 한 곳에만 기댄다(--expect-dirs 로 붙일 수 있다)")
+
+    print("═" * 58)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())