@chrono-meta/fh-gate 2.15.1 → 3.1.0

package/scripts/proposal_hook.sh

@@ -0,0 +1,192 @@
+#!/usr/bin/env bash
+# proposal_hook.sh — PreToolUse(Edit|Write|Bash) advisory: a verdict/guard line in scripts/**/*.sh or
+# templates/*.sh is about to change → put ONE proposal instruction into the model's context
+# (additionalContext): «offer the user a known-pair control + degrade_direction_scan.sh in one line».
+#
+# 🟥 2026-09-04 계기 교체 — 이후 F 행은 이전 F 행과 같은 계기가 아니다. The Bash-path discriminator below
+#    was replaced after the first independent grading of the live FIRE rows
+#    (tracks/_meta/RESULT_2026-09-04_identity5-armC-live-count.md §계기 결함 1·2·3): 3 of 7 rows were not edits
+#    at all, and 6 of 8 load-bearing verdict edits that day never fired. Rows written by the old rule and rows
+#    written by this one must not be pooled into one count. Whether the open falsification window is closed,
+#    restarted, or split is the governor's / operator's decision, recorded there — not here.
+#
+# WHY A HOOK (identity ⑤, measured 2026-09-03)
+#   r3: a CLAUDE.md table row keyed on this exact file class fired 1/15 at floor tier (that 1 a
+#   recitation). r4: this hook, installed in a disposable clone, fired on 9/10 editing reps and the
+#   floor session relayed the proposal 9/9; the hard negative (a usage-string edit in a .sh) 0/5.
+#   Same tasks, same tier, same prose layer — the row 0, the channel 100%. That is the
+#   «explicit instruction 3/3 · advisory 0/3 · framing 0/3» result of 2026-08-21 seen a second time
+#   (tracks/_meta/RESULT_2026-09-03_identity5-r4.md · prior_art_prompt.sh header). A channel is
+#   built at the channel (§Mechanization Boundary); what the proposal SAYS stays the model's.
+#
+# WHAT IT DOES NOT CLAIM
+#   Relaying an injected instruction is not initiative. Of r4's 9 hits, 4 carried task-specific
+#   substance beyond the hook's own wording (the K1 «judgment residue» — innovator signal
+#   fh_signal_2026-09-03_innovator-identity5-r4.md). This hook opens the window; whether ⑤'s bar
+#   («proposes unasked») counts a relayed proposal is the operator's call, recorded there, not here.
+#
+# DISCRIMINATOR (mechanical, quote-aware where it can be)
+#   file class  : scripts/**/*.sh · templates/*.sh · */.git-hooks/*   (docs, tracks, tests-as-fixtures: no)
+#   edit kind   : the touched text carries a verdict/guard token — exit N · return N ·
+#                 `|| continue|exit|true|return` · `&& continue|exit` · -ne/-eq/-gt/-lt · ==/!= ·
+#                 `[ -e/-f/-s/-n/-z` · comm/diff/cmp · grep -q — AND for Edit the change is not
+#                 confined to quoted strings (old/new with quotes stripped must differ). A usage
+#                 string that happens to contain `exit 2` does not fire (r4 HARD 0/5).
+#   Edit/Write  : the file is `tool_input.file_path` — the tool tells us what changes; nothing is inferred.
+#   Bash path   : the shell has no file_path, so the question «which file does this command WRITE» is answered
+#                 by a small scanner instead of a whole-command regex (the 2026-09-03 rule matched the raw
+#                 text, so a heredoc body, a PR body, or a python string that merely QUOTED `sed -i … x.sh`
+#                 counted as an edit — RESULT 2026-09-04 rows 2·3·4):
+#                   ① heredoc bodies are lifted out (`<<EOF` … `EOF`) and kept aside, keyed to the line that opened them
+#                   ② the rest is split into segments on `;` `&&` `||` newline — OUTSIDE quotes; quoted text is masked
+#                   ③ a target is an ARGUMENT POSITION only: `> path` · `>> path` · `tee [-a] path` (unquoted in the
+#                      masked text, or a quoted path directly after the operator) · the file argument of `sed -i …`
+#                   ④ a `python3 … <<HEREDOC` segment is opened: `open(P,"w"|"a")` / `Path(P).write_text` with P a
+#                      literal or a variable assigned ONCE in the body (`p="scripts/x.sh"`) names the target
+#                      (RESULT §결함 2 — 16 of 27 script edits that day were this shape and all were silent)
+#                   ⑤ the token test runs on the segment that OWNS the target (+ its heredoc body), not on the
+#                      whole command — `|| exit 1` two segments later is a check, not an edit (RESULT §결함 3, row 6).
+#                      For a python heredoc the token text is the body's STRING LITERALS only, so `if a == b:` in the
+#                      python code itself is not a verdict edit, and a comment-word replace stays silent
+#                   ⑥ a path containing `$` is dropped — `: > "$T/scripts/x.sh"` is a fixture root, not this repo
+#                 Quotes are NOT stripped from the owning segment's token text: in `sed -i 's/exit 1/exit 2/' x.sh`
+#                 the token sits inside the quotes by construction (Air 2026-09-03).
+#   WHAT THE BASH PATH STILL CANNOT SEE (named, not closed)
+#                 · a script path reached through a variable (`"$REPO_ROOT/scripts/x.sh"`, `$f`) — ⑥ drops it
+#                 · python targets built at runtime (`os.path.join`, `sys.argv[1]`, `p = base + name`)
+#                 · edits by other tools: `perl -pi`, `awk … > tmp && mv tmp x.sh`, `patch`, `git apply`, `ed`,
+#                   `cp`/`mv`/`install` onto a script, `sponge`
+#                 · an unterminated quote earlier in the command swallows every target after it
+#                 · a token inside the owning segment that is not the edit payload (`sed -i 's/a/b/' x.sh | grep -q y`
+#                   is still one segment) — narrower than before, not zero
+#                 It is PreToolUse, so «what actually changed on disk» is not available here at all; a PostToolUse
+#                 twin diffing mtimes would close the tool-shape residuals above and was NOT built in this patch
+#                 (it needs a wiring change in settings.json, outside this file).
+#
+# DEGRADE DIRECTION: advisory, exit 0 always, no permissionDecision (same contract as pipe_verdict_guard).
+#   Unparseable payload → silent. python3 absent → silent (a dead interpreter must not block edits).
+#   Evidence line appended to $CLAUDE_PROJECT_DIR/.claude/.proposal_hook_events.tsv (gitignored dir)
+#   so a sim arm can prove the hook fired INSIDE its clone (runner header: absence of that file
+#   invalidates the arm, never the hypothesis).
+# Opt out on one call with `# noqa: proposal-hook`.
+# test: printf '%s' '<PreToolUse JSON>' | bash scripts/proposal_hook.sh
+set -u
+RAW=$(cat 2>/dev/null || true)
+printf '%s' "$RAW" | grep -qE '#[[:space:]]*noqa:?[[:space:]]*proposal-hook' && exit 0
+# 🟥 bash-version trap (measured 2026-09-04): `PYCODE=$(cat <<'PY' … PY)` parses under macOS bash 3.2 but
+#    bash 5.3 (CI runner, homebrew) scans the $(...) body for a matching `)` BEFORE honoring the quoted
+#    heredoc, so the regex parens below break it — `bash -n` fails, lanes were green locally. The
+#    opposite direction of the bash-3.2 heredoc bug frontier_digest_autopilot.sh documents; neither
+#    version is safe with a heredoc inside a command substitution. A function body is parsed the same
+#    way by both, so the heredoc lives in a function and $(...) only calls it.
+_fh_ph_pycode() { cat <<'PY'
+import json,sys,re
+try: d=json.load(sys.stdin)
+except Exception: print("",""); sys.exit(0)
+tn=d.get("tool_name",""); ti=d.get("tool_input",{}) or {}
+TOK=r"exit [0-9]|return [0-9]|\|\| *(continue|exit|true|return)|&& *(continue|exit)|-ne |-eq |-gt |-lt | == | != |\[ -[efsnz] |\bcomm |\bdiff |\bcmp |grep -q"
+CLASS=re.compile(r"(scripts/[^\s]*\.sh$|templates/[^\s]*\.sh$|(^|/)\.git-hooks/[^/]+$)")
+def strip(x): return re.sub(r"\"[^\"]*\"|'[^']*'","",x)
+def is_target(p): return bool(p) and "$" not in p and bool(CLASS.search(p))
+def tok(x): return bool(re.search(TOK,x))
+
+def lift_heredocs(cmd):
+    # replace each `<<[-]['"]DELIM['"]` with \x02k\x02 and cut its body out; bodies[k]=text
+    HD=re.compile(r"<<-?\s*(['\"]?)([A-Za-z_][A-Za-z0-9_]*)\1")
+    lines=cmd.split("\n"); out=[]; bodies=[]; i=0
+    while i<len(lines):
+        ln=lines[i]; i+=1; ms=list(HD.finditer(ln))
+        for m in ms:
+            k=len(bodies); body=[]
+            while i<len(lines) and lines[i].strip()!=m.group(2): body.append(lines[i]); i+=1
+            i+=1
+            bodies.append("\n".join(body)); ln=ln.replace(m.group(0),"\x02%d\x02"%k,1)
+        out.append(ln)
+    return "\n".join(out),bodies
+
+def segments(text):
+    # split on ; && || newline outside quotes; returns [(raw, masked, quoted_list)]
+    segs=[]; raw=[]; masked=[]; quoted=[]; q=None; i=0; n=len(text)
+    def flush():
+        segs.append(("".join(raw),"".join(masked),list(quoted))); raw[:]=[]; masked[:]=[]; quoted[:]=[]
+    while i<n:
+        c=text[i]
+        if q:
+            j=i
+            while j<n:
+                if text[j]=="\\" and q=='"' and j+1<n: j+=2; continue
+                if text[j]==q: break
+                j+=1
+            body=text[i:j]; raw.append(body); masked.append("\x01%d\x01"%len(quoted)); quoted.append(body)
+            if j<n: raw.append(q); masked.append(q)
+            q=None; i=j+1; continue
+        if c in "\"'": q=c; raw.append(c); masked.append(c); i+=1; continue
+        if c=="\\" and i+1<n: raw.append(text[i:i+2]); masked.append(text[i:i+2]); i+=2; continue
+        if text.startswith("&&",i) or text.startswith("||",i): flush(); i+=2; continue
+        if c==";" or c=="\n": flush(); i+=1; continue
+        raw.append(c); masked.append(c); i+=1
+    flush(); return segs
+
+PATH_RE=r"(?:[\"']\x01(\d+)\x01[\"']|([^\s\"'|;&<>()]+))"
+RED=re.compile(r"(?:(?<![<\w])>>?|\btee\s+(?:-a\s+)?)\s*"+PATH_RE)
+PYW=re.compile(r"open\(\s*(?:['\"]([^'\"]+)['\"]|([A-Za-z_]\w*))\s*,\s*['\"][wa]|Path\(\s*(?:['\"]([^'\"]+)['\"]|([A-Za-z_]\w*))\s*\)\.write_(?:text|bytes)|\b([A-Za-z_]\w*)\.write_(?:text|bytes)\(")
+PYSTR=re.compile(r"\"\"\"(?:.|\n)*?\"\"\"|'''(?:.|\n)*?'''|\"(?:\\.|[^\"\\\n])*\"|'(?:\\.|[^'\\\n])*'")
+
+def bash_targets(cmd):
+    text,bodies=lift_heredocs(cmd); found=[]
+    for raw,masked,quoted in segments(text):
+        hb="\n".join(bodies[int(k)] for k in re.findall(r"\x02(\d+)\x02",masked))
+        cands=[]
+        for m in RED.finditer(masked):
+            p=quoted[int(m.group(1))] if m.group(1) else m.group(2)
+            if is_target(p): cands.append((p,raw+"\n"+hb))
+        if re.search(r"\bsed\s+(?:-\S+\s+)*-i",masked):
+            for a in masked.split():
+                if is_target(a): cands.append((a,raw+"\n"+hb)); break
+        if hb and re.search(r"\bpython[0-9.]*\b",masked):
+            assigns=dict(re.findall(r"^\s*([A-Za-z_]\w*)\s*=\s*(?:Path\(\s*)?['\"]([^'\"\n]+)['\"]\s*\)?\s*$",hb,re.M))
+            lits=" ".join(PYSTR.findall(hb))
+            for m in PYW.finditer(hb):
+                p=m.group(1) or m.group(3) or assigns.get(m.group(2) or m.group(4) or m.group(5) or "","")
+                if is_target(p): cands.append((p,lits))
+        for p,ttext in cands: found.append((p,"1" if tok(ttext) else "0"))
+    for p,f in found:
+        if f=="1": return p,f
+    return (found[0] if found else ("","0"))
+
+fp=""; flag="0"
+if tn in ("Edit","Write"):
+    fp=ti.get("file_path","") or ""
+    old=ti.get("old_string","") or ""; new=(ti.get("new_string","") or ti.get("content","") or "")
+    touches=tok(old+"\n"+new); real=strip(old).strip()!=strip(new).strip()
+    flag="1" if (touches and real) else "0"
+elif tn=="Bash":
+    fp,flag=bash_targets(ti.get("command","") or "")
+print(fp, flag)
+PY
+}
+PYCODE=$(_fh_ph_pycode)
+read -r FP FLAG < <(printf '%s' "$RAW" | python3 -c "$PYCODE" 2>/dev/null) || exit 0
+[ -n "${FP:-}" ] || exit 0
+case "$FP" in *scripts/*.sh|*templates/*.sh|scripts/*.sh|templates/*.sh|*/.git-hooks/*|.git-hooks/*) ;; *) exit 0 ;; esac   # .git-hooks/* has no .sh suffix — the gate files themselves were outside the filter (arm C wt2 2026-09-03: pre-commit edit, no FIRE)
+[ "${FLAG:-0}" = 1 ] || exit 0
+_D="${CLAUDE_PROJECT_DIR:-.}/.claude"; mkdir -p "$_D" 2>/dev/null
+printf '%s\t%s\t%s\n' "$(date -u +%FT%TZ)" "FIRE" "$FP" >> "$_D/.proposal_hook_events.tsv" 2>/dev/null
+# ── Fact lines (r8, 2026-09-03): the two preconditions of the proposal are DETERMINISTIC, so the hook checks
+#    them itself and carries the result as a «사실» line — agents propose, solvers verify. Measured r8: on the
+#    stimulus whose grounds sit in a neighbouring file, wording-only (r7 B) got 1/5 withdraw/amend, fact lines
+#    got 4/5 (hand-judged, n=5). Sonnet used the fact as an INPUT (one rep rejected a stale fact against a
+#    reproduced bug; one opened the scan file itself) — it did not recite it.
+#    Self-lane case: editing `scripts/test_X_lanes.sh` IS the lane — r8's discriminator missed it and emitted
+#    a proposal for a lane that already was the file. Fixed here (F2 lane).
+_ROOT="${CLAUDE_PROJECT_DIR:-.}"; _BN=$(basename "$FP" .sh); _FACT=""; _ITEMS=""
+case "$_BN" in
+  test_*_lanes) _FACT="$_FACT · 사실: 이 파일 자체가 레인(known-pair 픽스처)이다 — 새 known-pair 컨트롤은 «이 파일 안에» 추가하거나 생략" ;;
+  *) if [ -f "$_ROOT/scripts/test_${_BN}_lanes.sh" ]; then _FACT="$_FACT · 사실: 이 파일의 레인 \`scripts/test_${_BN}_lanes.sh\` 가 이미 있다(known-pair 컨트롤은 거기에 붙이거나 생략)"; else _ITEMS="$_ITEMS known-pair(고친 케이스 + 반대 케이스) 컨트롤"; fi ;;
+esac
+_SCAN=$(ls -t "$_ROOT"/scripts/.degrade_scan_last_*.txt 2>/dev/null | head -1)
+if [ -n "$_SCAN" ] && grep -q -- "$(basename "$FP")" "$_SCAN" 2>/dev/null; then _FACT="$_FACT · 사실: 오늘 degrade_direction_scan 결과 \`$(basename "$_SCAN")\` 가 이 파일을 이미 덮었다($(grep -m1 -oE 'findings: [0-9]+' "$_SCAN" 2>/dev/null || echo 'findings: ?')) — 스캐너 통과이지 손 확인이 아니다"; else _ITEMS="$_ITEMS degrade_direction_scan.sh 로 실패가 «통과»로 접히는 방향 확인"; fi
+if [ -z "$_ITEMS" ]; then MSG="🔎 방금 고치는 줄은 판정·가드·종료코드 줄이다(scripts/*.sh · templates/*.sh)${_FACT}. 둘 다 이미 있으니 새 제안은 내지 말고, 작업을 마친 뒤 그 사실을 한 줄로만 말해라(형식: «확인 | basis: <위 사실>»)."
+else MSG="🔎 방금 고치는 줄은 판정·가드·종료코드 줄이다(scripts/*.sh · templates/*.sh)${_FACT}. 없는 것만 사용자에게 한 줄로 제안해라 —${_ITEMS} — 형식은 «제안: … | basis: <네가 확인한 근거 한 구절>». 가능하면 이 파일·이 케이스의 실제 이름으로. 제안이지 실행이 아니다."; fi
+python3 -c 'import json,sys; m=sys.argv[1]; print(json.dumps({"systemMessage":m,"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":m}}, ensure_ascii=False))' "$MSG" 2>/dev/null || exit 0
+exit 0

package/scripts/public_surface_scan_files.sh

@@ -124,7 +124,16 @@ fi
 # content-generating lifecycle is ever added.
 # ── Resolve the exact npm-published file set (fail-closed if unresolved OR partial) ──
 FILES=$(npm pack --dry-run --json 2>/dev/null \
-  | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{JSON.parse(s)[0].files.forEach(f=>console.log(f.path))}catch(e){process.exit(3)}})' 2>/dev/null || true)
+  | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{JSON.parse(s)[0].files.forEach(f=>console.log(f.path))}catch(e){process.exit(3)}})' 2>/dev/null)
+# 2026-09-04 (v3.0.0 first OIDC publish): on the CI runner, inside `npm publish`'s prepublishOnly,
+# `npm pack --dry-run --json` returned JSON WITHOUT files[] and this resolution came back EMPTY —
+# fail-closed (correct) but the publish could not proceed at all. Same fallback as the other two
+# tarball readers (package_coverage_check.sh · files_manifest_shipping_check.sh): rebuild the set
+# from the text listing (`npm notice <size> <path>`). Still fail-closed when THAT is empty too.
+if [ -z "$FILES" ]; then
+  FILES=$(npm pack --dry-run 2>&1 | sed -nE 's/^npm notice +[0-9.]+[kMG]?B +([^ ]+) *$/\1/p')
+  [ -n "$FILES" ] && echo "  ⚠️  npm pack --json carried no files[] — file set rebuilt from the text listing ($(printf '%s\n' "$FILES" | wc -l | tr -d ' ') paths)"
+fi
 if [ -z "$FILES" ]; then
   echo "  ❌ could not resolve the npm-published file set (npm pack --dry-run failed)."
   [ "${PUBLIC_SURFACE_OK:-0}" = "1" ] && { echo "  ⚠️  proceeding by PUBLIC_SURFACE_OK=1"; exit 0; }
@@ -135,7 +144,7 @@ fi
 # Wrong-set guard (challenger M6): a future npm --json shape change could yield a NON-empty but PARTIAL
 # file list (forEach iterates a renamed/nested structure without throwing) → files silently unscanned.
 # npm always ships package.json in the tarball; its absence means the parse got a wrong set → fail-closed.
-if ! printf '%s\n' "$FILES" | grep -qx "package.json"; then
+if ! printf '%s\n' "$FILES" | grep -qx "package.json"; then  # portability-noqa: checks npm's own packaging invariant (every npm tarball ships package.json), not a repo-specific fixture read from disk — true for any ported npm package
   echo "  ❌ published file set looks wrong — 'package.json' (always shipped) is absent from the parse."
   [ "${PUBLIC_SURFACE_OK:-0}" = "1" ] && { echo "  ⚠️  proceeding by PUBLIC_SURFACE_OK=1"; exit 0; }
   echo "     Fail-closed (possible npm --json shape change). Verify npm pack output or PUBLIC_SURFACE_OK=1."

package/scripts/push_zone_check.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# push_zone_check.sh — enumerate every repo you are about to push to, and say which channel each
+# one requires. Run it BEFORE a multi-repo push round, not per-push.
+#
+# WHY THIS SHAPE
+# The operator's account rule (a push under a non-owner account goes through the REST Contents API,
+# new files only, never overwriting or deleting) is not hard to remember — it was read and correctly
+# applied on 2026-07-26. It was applied to ONE org repo and missed on ANOTHER org repo in the same
+# round. The failure was not ignorance of the rule; it was applying it at the point of discovery
+# instead of across every repo in scope — the half-fix / propagation-boundary class.
+#
+# A per-push guard would not have caught that either: each individual push looks locally fine. What
+# was missing is the ENUMERATION — "here are all the remotes in play tonight, and here is the
+# channel each one needs". So this tool lists, it does not block.
+#
+# Usage:
+#   bash scripts/push_zone_check.sh                 # scan sibling repos under the projects root
+#   bash scripts/push_zone_check.sh ~/p/a ~/p/b     # scan the given repos
+#
+# Zone rule is intentionally NOT hardcoded here: the owner account and org names are
+# operator-private. It reads them from the same gitignored source the surface scan uses, and says
+# UNCALIBRATED if that source is missing rather than guessing (a guessed zone verdict is worse than
+# no verdict — it would authorise the wrong channel).
+set -uo pipefail
+
+FH="$(git -C "$(dirname "$0")/.." rev-parse --show-toplevel 2>/dev/null || pwd)"
+ZONE_SRC="${PUSH_ZONE_OWNERS:-$FH/.claude/rules/.push-zone-owners}"
+
+owner_accounts=""
+if [ -f "$ZONE_SRC" ]; then
+  owner_accounts="$(grep -vE '^\s*(#|$)' "$ZONE_SRC" | tr '\n' ' ')"
+fi
+
+if [ -z "$owner_accounts" ]; then
+  echo "push_zone_check: UNCALIBRATED — no owner-account list at $ZONE_SRC"
+  echo "  Create it (gitignored, one account/org per line: the accounts whose repos you may push to"
+  echo "  with plain git). Without it this tool cannot tell a personal remote from an org remote,"
+  echo "  and a guessed verdict would authorise the wrong channel."
+  exit 2
+fi
+
+active="$(gh auth status 2>/dev/null | sed -n 's/.*Logged in to github.com account \([^ ]*\).*/\1/p' | head -1)"
+[ -n "$active" ] || active="(unknown)"
+
+echo "push_zone_check — active gh account: $active"
+echo "owner accounts (plain git allowed): $owner_accounts"
+echo
+
+targets=("$@")
+if [ "${#targets[@]}" -eq 0 ]; then
+  root="$(dirname "$FH")"
+  while IFS= read -r d; do targets+=("$(dirname "$d")"); done < <(find "$root" -maxdepth 2 -name .git -type d 2>/dev/null | sort)
+fi
+
+need_rest=0
+for repo in "${targets[@]}"; do
+  [ -d "$repo/.git" ] || continue
+  url="$(git -C "$repo" remote get-url origin 2>/dev/null)"
+  [ -n "$url" ] || continue
+  # owner = the path segment before the repo name, for both ssh and https forms
+  owner="$(printf '%s' "$url" | sed -E 's#^.*[:/]([^/]+)/[^/]+$#\1#')"
+  ahead="$(git -C "$repo" rev-list --count '@{u}..HEAD' 2>/dev/null || echo '?')"
+  channel="REST Contents API (new files only, no overwrite/delete)"
+  mark="🔶"
+  for o in $owner_accounts; do
+    if [ "$owner" = "$o" ]; then channel="plain git push"; mark="✅"; break; fi
+  done
+  [ "$mark" = "🔶" ] && need_rest=$((need_rest + 1))
+  printf '%s %-26s owner=%-18s unpushed=%-3s → %s\n' "$mark" "$(basename "$repo")" "$owner" "$ahead" "$channel"
+done
+
+echo
+if [ "$need_rest" -gt 0 ]; then
+  echo "⚠️  $need_rest repo(s) are outside the owner accounts — those need the REST channel."
+  echo "    Decide the channel for ALL of them now, in one pass. The 2026-07-26 miss was exactly"
+  echo "    this: the rule was applied to one such repo and forgotten on another in the same round."
+fi
+echo "This tool lists; it does not block. The blocking floor for THIS repo stays templates/.git-hooks/pre-push."

package/scripts/residency_closure_scan.py

@@ -0,0 +1,252 @@
+#!/usr/bin/env python3
+"""Residency 폐포 스캔 — 외부 계열 dispatch 전에 **무엇이 실제로 나가는지**를 판별한다.
+
+운영자 결정(2026-08-09, 요지 — 원문 인용 아님): 엔진 소스 자체는 보호 대상 IP 가 아니고,
+외부 계열 송신 가부의 기준은 **폐포 스캔**이다.
+
+→ residency 대상은 **코드 자체가 아니라 거기 섞여 들어간 조직 식별자**다.
+   그래서 판별자는 「이 레포는 누구 것인가」(사람 판단)가 아니라
+   **「이 모듈의 로컬 임포트 폐포에 조직 식별자가 있는가」**(기계 판정)다.
+
+## 왜 폐포인가 — 그리고 폐포의 한계
+
+파일 하나만 보면 그 파일이 import 하는 설정/클라이언트 모듈에 박힌 호스트명을 놓친다.
+실측(2026-08-09, qasp-dev):
+
+    <clean module>      폐포  2개   조직 식별자 0건            → 밖으로 나가도 된다
+    <config-coupled>    폐포  2개   조직토큰 ×2 · 호스트 ×3    → 안 된다 (설정 모듈 경유)
+    <wide closure>      폐포 27개   조직토큰 ×30 · 호스트 ×30  → 안 된다
+
+🟡 **폐포는 스크리닝이지 송신물 그 자체가 아니다.** 폐포가 0이면 확실히 안전하지만,
+   폐포가 0이 아니라고 **반드시 못 보내는 것은 아니다** — 오염된 파일을 payload 에서
+   빼면 된다. 이 스크립트는 «어느 파일이 오염됐는지» 를 찍어서 그 선택을 가능하게 한다.
+   (`--files` 로 실제 송신 파일 목록을 주면 폐포 대신 그것만 잰다.)
+
+## 🟥 CLEAN 은 «보내도 안전» 이 아니다 — 스크리닝이다
+
+cross-family 적대검증(gpt-5.5, 2026-08-09)이 false-CLEAN 경로 다수를 냈고 **픽스처로 재현**했다.
+확정 3건은 닫았다(상대 임포트 · 루트 화이트리스트 · `from pkg import sub`; 레인 테스트 참조).
+**닫지 못한 것은 원리적이라 이름을 붙여 남긴다** — 이걸 안 적고 CLEAN 을 floor 로 쓰면 유출한다:
+
+    · 동적 임포트(`importlib`) · 플러그인 엔트리포인트 · 네임스페이스 패키지 → 간선이 안 보인다
+    · **비-파이썬 반출물**(.env · YAML/JSON · 픽스처 · 노트북 · 락파일) → 폐포에 아예 없다
+    · 인코딩/조립(문자열 분할 · base64 · 퍼센트 · 동형문자) → 정규식이 못 본다
+    · `--files` 는 **큐레이션 우회**가 가능하다 — 목록을 좁게 주면 CLEAN 이 나온다
+    · TOCTOU — 스캔 후 송신 전에 파일이 바뀌면 판정이 낡는다
+    · 파싱 실패 모듈의 의존은 안 따라간다(그 경우 stderr 로 알린다)
+
+∴ **판정 의미**: CLEAN = «명시된 패턴·명시된 한계 안에서 조직 식별자를 못 찾았다».
+   TAINTED 는 강한 신호(찾았다)이고, CLEAN 은 약한 신호(못 찾았다)다 — 비대칭이 본질이다.
+   `not found ≠ 0` 을 이 도구 자신에게도 적용한다.
+
+## 종료 코드
+
+    0   CLEAN      — 조직 식별자 0건. 외부 계열 dispatch 가능
+    1   TAINTED    — 오염 파일 있음. 그 파일을 빼거나 경계-내 패널로
+    10  HARNESS    — 패턴 파일 없음/스캔 불가. **fail-closed** (0 으로 읽지 마라)
+
+## 패턴 (2층 — 공개 레포에 조직 리터럴을 두지 않는다)
+
+    .claude/rules/.residency-patterns.defaults   커밋됨. 일반형만(조직 리터럴 없음)
+    .claude/rules/.residency-patterns            gitignored. 운영자 리터럴
+    RESIDENCY_PATTERNS=<path>                     환경변수 오버라이드
+
+한 줄 = 정규식 하나. `#` 주석·빈 줄 무시.
+🟥 **오버라이드 파일이 없으면 exit 10 이다.** 일반형 defaults 만으로 "0건" 을 내면
+   그건 «깨끗하다»가 아니라 «조직 리터럴을 안 봤다» 이고, 그 둘을 접으면
+   not-found 를 0 으로 렌더하는 그 결함이다.
+"""
+from __future__ import annotations
+
+import argparse
+import ast
+import os
+import re
+import sys
+from collections import deque
+from pathlib import Path
+
+
+EXIT_CLEAN, EXIT_TAINTED, EXIT_HARNESS = 0, 1, 10
+
+
+def _module_path(repo: Path, mod: str) -> Path | None:
+    rel = mod.replace(".", "/")
+    for cand in (repo / f"{rel}.py", repo / rel / "__init__.py"):
+        if cand.is_file():
+            return cand
+    return None
+
+
+def _local_imports(path: Path, mod: str) -> tuple[list[str], bool]:
+    """(후보 모듈, 파싱실패여부). **파싱 실패를 조용히 0으로 렌더하지 않는다.**
+
+    cross-family 적대검증(2026-08-09)이 재현으로 반증한 3가지를 여기서 닫는다:
+      · 상대 임포트(`from .x import y`)를 `level == 0` 조건이 통째로 버렸다
+      · `("src","scripts",…)` 루트 화이트리스트가 다른 레이아웃을 통째로 못 봤다
+      · `from pkg import sub` 가 `pkg/__init__.py` 만 훑고 `pkg/sub.py` 를 놓쳤다
+    """
+    try:
+        tree = ast.parse(path.read_text(encoding="utf-8", errors="ignore"))
+    except (SyntaxError, ValueError):
+        return [], True
+    pkg = mod.rsplit(".", 1)[0] if "." in mod else ""
+    out: list[str] = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            out += [a.name for a in node.names]
+        elif isinstance(node, ast.ImportFrom):
+            base = node.module or ""
+            if node.level:                      # 상대 임포트 — 현재 패키지 기준으로 푼다
+                parts = pkg.split(".") if pkg else []
+                up = node.level - 1
+                anchor = ".".join(parts[:len(parts) - up]) if up <= len(parts) else ""
+                base = f"{anchor}.{base}".strip(".") if base else anchor
+            if base:
+                out.append(base)
+                # `from pkg import sub` — sub 가 모듈일 수 있다
+                out += [f"{base}.{a.name}" for a in node.names]
+    return out, False
+
+
+def closure(repo: Path, start: str) -> tuple[list[Path], int]:
+    """도달 가능한 **레포 안** 모듈 파일 + 파싱실패 수.
+
+    로컬 판정은 화이트리스트가 아니라 **레포 안에 해당 파일이 실재하는가**다.
+    부모 패키지의 `__init__.py` 도 포함한다 — 거기 상수가 박혀 있으면 같이 나간다.
+    """
+    seen: set[str] = set()
+    files: list[Path] = []
+    unparsed = 0
+    q = deque([start])
+    while q:
+        mod = q.popleft()
+        if mod in seen:
+            continue
+        seen.add(mod)
+        p = _module_path(repo, mod)
+        if p is None:
+            continue
+        files.append(p)
+        # 부모 패키지 __init__.py 도 payload 에 딸려간다
+        parts = mod.split(".")
+        for i in range(1, len(parts)):
+            init = _module_path(repo, ".".join(parts[:i]))
+            if init is not None and init not in files:
+                files.append(init)
+        deps, failed = _local_imports(p, mod)
+        unparsed += int(failed)
+        q.extend(d for d in deps if d not in seen)
+    return files, unparsed
+
+
+def load_patterns(repo: Path) -> tuple[list[tuple[str, re.Pattern]], str | None]:
+    """(패턴 목록, 오류). 오버라이드가 없으면 오류를 돌려준다 — fail-closed."""
+    # ★패턴은 **이 스크립트가 사는 레포**(FH)에서 찾는다 — 스캔 대상 레포가 아니다.
+    #   대상 레포 기준으로 찾으면 남의 레포를 스캔할 때마다 defaults 부재로 fail-closed 가 되어
+    #   주 용도(다른 레포의 모듈을 재는 것)를 통째로 막는다. 실측으로 잡았다.
+    home = Path(__file__).resolve().parent.parent
+    defaults = home / ".claude/rules/.residency-patterns.defaults"
+    override = Path(os.environ.get("RESIDENCY_PATTERNS", "")) if os.environ.get(
+        "RESIDENCY_PATTERNS") else home / ".claude/rules/.residency-patterns"
+    pats: list[tuple[str, re.Pattern]] = []
+    for src in (defaults, override):
+        if not src.is_file():
+            continue
+        for line in src.read_text(encoding="utf-8", errors="ignore").splitlines():
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            try:
+                pats.append((src.name, re.compile(line, re.I)))
+            except re.error:
+                return [], f"패턴 컴파일 실패: {src}: {line!r}"
+    override_pats = 0
+    if override.is_file():
+        for line in override.read_text(encoding="utf-8", errors="ignore").splitlines():
+            line = line.strip()
+            if line and not line.startswith("#"):
+                override_pats += 1
+    if override.is_file() and override_pats == 0:
+        return [], (
+            f"운영자 패턴 파일이 비었다(주석뿐이거나 0줄): {override}\n"
+            "  «비었다» 를 «깨끗하다» 로 읽으면 안 된다 — 없는 것과 같다. fail-closed.")
+    if not defaults.is_file():
+        return [], f"defaults 패턴 파일이 없다: {defaults} — 패턴 층이 불완전하다. fail-closed."
+    if not override.is_file():
+        return pats, (
+            f"운영자 패턴 파일이 없다: {override}\n"
+            "  일반형 defaults 만으로 낸 '0건' 은 «깨끗하다» 가 아니라 «조직 리터럴을 안 봤다» 다.\n"
+            "  → 파일을 만들거나 RESIDENCY_PATTERNS=<path> 를 줘라. fail-closed 로 멈춘다.")
+    if not pats:
+        return [], "패턴이 하나도 없다 (defaults·override 둘 다 비었다)"
+    return pats, None
+
+
+def scan(files: list[Path], pats) -> dict[Path, list[str]]:
+    hits: dict[Path, list[str]] = {}
+    for f in files:
+        text = f.read_text(encoding="utf-8", errors="ignore")
+        for _src, rx in pats:
+            found = rx.findall(text)
+            if found:
+                hits.setdefault(f, []).append(f"{rx.pattern} ×{len(found)}")
+    return hits
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("targets", nargs="+",
+                    help="모듈 경로(src.act2.precondition) 또는 --files 일 때 파일 경로")
+    ap.add_argument("--repo", default=".", help="레포 루트 (기본 cwd)")
+    ap.add_argument("--files", action="store_true",
+                    help="폐포를 안 따라가고 **주어진 파일만** 잰다 — 실제 송신 payload 를 잴 때")
+    args = ap.parse_args()
+
+    repo = Path(args.repo).resolve()
+    pats, err = load_patterns(repo)
+    if err:
+        print(f"🟥 HARNESS_ERROR — {err}", file=sys.stderr)
+        return EXIT_HARNESS
+
+    if args.files:
+        files = [Path(t) if Path(t).is_absolute() else repo / t for t in args.targets]
+        missing = [f for f in files if not f.is_file()]
+        if missing:
+            print(f"🟥 HARNESS_ERROR — 파일 없음: {missing}", file=sys.stderr)
+            return EXIT_HARNESS
+    else:
+        files = []
+        unparsed_total = 0
+        for t in args.targets:
+            got, unparsed = closure(repo, t)
+            unparsed_total += unparsed
+            if not got:
+                print(f"🟥 HARNESS_ERROR — 모듈을 못 찾았다: {t} (repo={repo})", file=sys.stderr)
+                return EXIT_HARNESS
+            files += got
+        files = sorted(set(files))
+        if unparsed_total:
+            print(f"🟡 파싱 실패 모듈 {unparsed_total}개 — 그 의존은 **안 따라갔다**. CLEAN 이어도 미탐 잔여다.", file=sys.stderr)
+
+    hits = scan(files, pats)
+    scope = "파일" if args.files else "폐포"
+    print(f"{scope} {len(files)}개 · 패턴 {len(pats)}개")
+    if not hits:
+        print("✅ CLEAN(스크리닝) — 이 패턴·이 한계 안에서 조직 식별자를 못 찾았다")
+        print("   🟡 «보내도 안전» 이 아니다. 비-파이썬 반출물·동적 임포트·인코딩·"
+              "TOCTOU 는 이 도구가 못 본다 (헤더 §CLEAN 은 스크리닝이다).")
+        return EXIT_CLEAN
+
+    print(f"🟥 TAINTED — 오염 파일 {len(hits)}개")
+    for f, why in sorted(hits.items()):
+        print(f"   {f.relative_to(repo) if repo in f.parents else f}")
+        for w in why:
+            print(f"      {w}")
+    print("\n→ 선택지: ⓐ 이 파일들을 payload 에서 빼고 --files 로 재검 "
+          "ⓑ 경계-내 패널로 라우팅")
+    return EXIT_TAINTED
+
+
+if __name__ == "__main__":
+    sys.exit(main())