@chrono-meta/fh-gate 3.2.0 → 3.5.0

package/plugins/fh-preprep/skills/preprep/usage_ledger.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""사용 원장 — 하네스가 «누구에게 얼마나 쓰이는가» 를 남긴다. 표준 라이브러리만 쓴다.
+
+## 🟥 옵트인이다 — `FH_USAGE_LEDGER` 가 없으면 **완전 무동작**이다.
+
+이 파일은 npm 으로 배포되는 하네스 안에 들어간다. 기본값으로 켜 두면 소비자가 동의한 적 없는
+계측이 남의 머신에서 돌게 되고, 그건 이 저장소가 §Operational Adaptation Loop 에서 금지하는
+형태다(동의는 «부재 ≠ 승인»). 그래서 스위치는 **경로를 직접 주는 것**이고, 경로를 주는 행위
+자체가 동의의 표시다.
+
+```
+export FH_USAGE_LEDGER="$HOME/.local/state/fh-usage"   # 이 줄이 없으면 아무 일도 안 난다
+export FH_USAGE_AUTHOR=1                               # 저자 본인 머신에서만
+```
+
+## 무엇을 적고 무엇을 안 적나 — residency 가 여기서 정해진다
+
+적는다 : 시각(분 단위) · 하네스 이름 · 진입점 이름(화이트리스트 형태) · **actor 해시** ·
+         벽시계 ms · CPU ms · 반환 코드 · 결과 부류
+🟥 안 적는다 : **인자 · 경로 · 파일명 · 티켓 id · URL · 사용자 이름 · 호스트 이름.**
+   접근이 제한된 환경에서도 돌 수 있는 하네스라 이건 취향이 아니라 경계다. 인자 한 칸을
+   열어두면 그 칸으로 조직 내부 식별자가 흘러나간다 — 그래서 인자를 받는 필드가 **아예 없다**.
+
+`actor` = sha256(salt + 사용자 + 호스트)[:12]. salt 는 원장 디렉터리 안 `.salt`(0600)에만 있고
+어디로도 안 나간다. ⚠️ **한계를 이름으로 남긴다**: 같은 사람이 머신 둘을 쓰면 **2 명**으로 세고,
+공용 머신을 여럿이 쓰면 **1 명**으로 센다. 그래서 이 값은 «사람 수»가 아니라 «머신-사용자 수»다.
+
+## degrade 방향 — 호스트를 절대 안 죽인다, 그러나 조용히 죽지도 않는다
+
+원장 쓰기가 실패해도 예외를 호스트로 올리지 않는다(관측이 대상을 죽이면 안 된다). 대신
+같은 디렉터리의 `.errors` 를 1 증가시키고, 리포터가 그 수를 **커버리지 옆에 같이 찍는다** —
+「미측정을 0 으로 렌더하는」 부류를 안 만들기 위해서다.
+"""
+import hashlib
+import json
+import os
+import time
+
+_SCHEMA = 1
+_ENV_DIR = "FH_USAGE_LEDGER"
+_ENV_AUTHOR = "FH_USAGE_AUTHOR"
+_ENV_SALT = "FH_USAGE_SALT"
+
+
+def _dir():
+    d = os.environ.get(_ENV_DIR, "").strip()
+    return d or None
+
+
+def _salt(d):
+    """salt 는 env 우선, 없으면 원장 디렉터리 안 파일. 없으면 만든다(0600)."""
+    s = os.environ.get(_ENV_SALT, "").strip()
+    if s:
+        return s
+    p = os.path.join(d, ".salt")
+    try:
+        # 🟥 cross-family codex 지목(2026-09-13, B-3): `.salt` 가 FIFO 면 열기가 **블록**한다.
+        #    이 함수는 `observe()` 의 finally 에서 불리므로, 그 순간 관측이 호스트를 멈춰 세운다.
+        #    관측은 대상의 타이밍 계약도 바꾸면 안 된다 → 정규 파일이 아니면 읽지 않는다.
+        #    (O_NONBLOCK 은 FIFO 열기가 막히는 것까지 같이 막는 두 번째 자물쇠다.)
+        import stat as _stat
+        st = os.lstat(p)
+        if not _stat.S_ISREG(st.st_mode):
+            raise OSError("salt path is not a regular file")
+        fd = os.open(p, os.O_RDONLY | getattr(os, "O_NONBLOCK", 0))
+        try:
+            v = os.read(fd, 4096).decode("utf-8", "replace").strip()
+        finally:
+            os.close(fd)
+        if v:
+            return v
+    except FileNotFoundError:
+        pass
+    except Exception:
+        # 정규 파일이 아니거나 읽을 수 없다 → 아래 O_EXCL 생성이 실패하고 record() 가
+        # 그 예외를 잡아 `.errors` 를 올린다. 행은 안 남고 호스트는 안 멈춘다(fail-closed).
+        pass
+    import secrets
+    v = secrets.token_hex(16)
+    fd = os.open(p, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    try:
+        os.write(fd, v.encode())
+    finally:
+        os.close(fd)
+    return v
+
+
+def _actor(d):
+    raw = "%s|%s" % (os.environ.get("USER") or os.environ.get("LOGNAME") or "?",
+                     os.uname().nodename if hasattr(os, "uname") else "?")
+    return hashlib.sha256((_salt(d) + "|" + raw).encode()).hexdigest()[:12]
+
+
+def _entry_name(name):
+    """진입점 이름만 받는다. 형태를 벗어나면 «other» — 인자가 이름에 섞여 들어오는 것 차단."""
+    ok = name and len(name) <= 40 and all(c.isalnum() or c in "_.-" for c in name)
+    return name if ok else "other"
+
+
+def _bump_errors(d):
+    try:
+        p = os.path.join(d, ".errors")
+        n = 0
+        try:
+            with open(p) as f:
+                n = int((f.read() or "0").strip() or 0)
+        except Exception:
+            n = 0
+        with open(p, "w") as f:
+            f.write(str(n + 1))
+    except Exception:
+        pass
+
+
+def record(harness, entry, wall_ms, cpu_ms, rc, outcome, counts=None):
+    """원장에 한 줄. 실패해도 예외를 밖으로 안 낸다."""
+    d = _dir()
+    if not d:
+        return False
+    try:
+        os.makedirs(d, exist_ok=True)
+        row = {
+            "v": _SCHEMA,
+            # 🟥 분 단위로 자른다 — 초 단위 타임스탬프는 개인 행동 패턴을 더 세밀히 남긴다.
+            "ts": time.strftime("%Y-%m-%dT%H:%MZ", time.gmtime()),
+            "h": _entry_name(harness),
+            "e": _entry_name(entry),
+            "actor": _actor(d),
+            "author": 1 if os.environ.get(_ENV_AUTHOR, "").strip() in ("1", "true", "yes") else 0,
+            "wall_ms": int(wall_ms),
+            "cpu_ms": int(cpu_ms),
+            "rc": rc if isinstance(rc, int) else None,
+            "out": outcome if outcome in ("DONE", "EXIT", "ERROR") else "ERROR",
+            # LLM 호출이 있는 경로만 채운다. 없으면 null — 🟥 0 이 아니다.
+            "llm": None,
+        }
+        if isinstance(counts, dict):
+            row["n"] = {k: v for k, v in counts.items()
+                        if isinstance(k, str) and isinstance(v, int) and len(k) <= 16}
+        path = os.path.join(d, "%s-%s.jsonl" % (row["h"], time.strftime("%Y-%m", time.gmtime())))
+        # append 는 O_APPEND 라 한 줄이 4 KiB 미만이면 동시 실행에서도 안 섞인다(POSIX).
+        # 🟥 0600 으로 만든다 — 행에 actor 해시와 사용 시각이 남으므로 기본 umask(0644)로
+        #    두면 같은 머신의 다른 계정이 읽는다. `.salt` 만 잠그고 원장을 열어두면 반쪽이다.
+        # 같은 이유로 원장 파일도 정규 파일일 때만 쓴다(FIFO 로 바꿔치기하면 append 가 막힌다).
+        if os.path.exists(path):
+            import stat as _stat
+            if not _stat.S_ISREG(os.lstat(path).st_mode):
+                raise OSError("ledger path is not a regular file")
+        fd = os.open(path, os.O_WRONLY | os.O_APPEND | os.O_CREAT
+                     | getattr(os, "O_NONBLOCK", 0), 0o600)
+        try:
+            os.write(fd, (json.dumps(row, ensure_ascii=False, sort_keys=True) + "\n").encode("utf-8"))
+        finally:
+            os.close(fd)
+        return True
+    except Exception:
+        # 🟥 여기서 예외를 올리지 않는 것은 «관측이 대상을 죽이면 안 되기» 때문이고, 그래서
+        #    default-toward-PASS 로 보인다. 정당화는 **조용하지 않다**는 것이다 — 실패는
+        #    `.errors` 로 세어지고 리포터가 커버리지 옆에 같이 찍는다(안 막는 것과 안 보이는 것은 다르다).
+        # ⚠️ 닫히지 않은 잔여를 이름으로 남긴다: 디렉터리가 통째로 못 쓰이면 `_bump_errors` 도
+        #    같이 실패해서 **카운터조차 안 남는다**. 그 경우는 리포터가 쓰기 권한을 직접 보고 잡는다
+        #    (usage_report.py `--dir` 쓰기 가능 검사). 원장 혼자서는 못 닫는다.
+        _bump_errors(d)
+        return False
+
+
+def observe(harness, entry, fn, *args, **kwargs):
+    """`fn` 을 그대로 실행하고 반환값·예외를 **건드리지 않고** 통과시킨다.
+
+    🟥 이 함수는 판정을 만들지도 바꾸지도 않는다. 종료코드는 `fn` 이 정하고 여기는 읽기만 한다.
+    그래서 게이트 코드가 아니다 — 관측이 판정을 바꾸는 순간 그 숫자는 아무 의미가 없다.
+    """
+    t0, c0 = time.monotonic(), time.process_time()
+    rc, outcome = None, "ERROR"
+    try:
+        rc = fn(*args, **kwargs)
+        outcome = "DONE"
+        return rc
+    except SystemExit as e:
+        rc = e.code if isinstance(e.code, int) else None
+        outcome = "EXIT"
+        raise
+    except BaseException:
+        outcome = "ERROR"
+        raise
+    finally:
+        record(harness, entry,
+               (time.monotonic() - t0) * 1000.0,
+               (time.process_time() - c0) * 1000.0,
+               rc, outcome)

package/plugins/fh-qp/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "fh-qp",
-  "version": "3.2.0",
+  "version": "3.5.0",
   "engines": {
     "claudeCode": ">=1.0.0"
   },

package/scripts/fh-run.sh

@@ -153,10 +153,23 @@ resolve_unit() {
     if [[ -n "$plugin" ]]; then
       candidates+=("$FH_ROOT/plugins/$plugin/skills/$bare/SKILL.md")
     fi
+    # 🟥 2026-09-13 — 종전엔 이 목록이 fh-meta·fh-commons **둘만** 하드코딩했다. 그래서
+    #    `fh-qp` 의 스킬 4개는 **처음부터** 이름만으로 안 잡혔고(선재 갭 — `--skill qp` 가
+    #    «unable to resolve»), preprep 을 자기 플러그인으로 승격하자 거기에 하나가 더 붙었다.
+    #    cross-family(codex)가 그 이동에서 이걸 지목했다 — 레포 어느 검사도 이 해석 경로를
+    #    안 보고 있었다. ⇒ 목록을 **플러그인 전체로 일반화**한다.
+    #    우선순위는 보존한다: 명시 지정 → fh-meta → fh-commons → 나머지(사전순, 결정적).
+    #    이름이 겹칠 때 종전 해석이 안 바뀌게 하려는 것이고, 정렬은 파일시스템 순서에
+    #    기대지 않기 위해서다.
     candidates+=(
       "$FH_ROOT/plugins/fh-meta/skills/$bare/SKILL.md"
       "$FH_ROOT/plugins/fh-commons/skills/$bare/SKILL.md"
     )
+    local _p
+    while IFS= read -r _p; do
+      case "$_p" in */fh-meta/*|*/fh-commons/*) continue ;; esac
+      candidates+=("$_p")
+    done < <(ls -d "$FH_ROOT"/plugins/*/skills/"$bare"/SKILL.md 2>/dev/null | sort)
     for f in "${candidates[@]}"; do
       [[ -f "$f" ]] && printf "%s\n" "$f" && return 0
     done

package/scripts/field_canon_preload.sh

@@ -149,7 +149,7 @@ skill_canon_emit() {
 SKEOF
   [ -z "$SENT_DIR" ] || : > "$SENT_DIR/skill-$_sk" 2>/dev/null || true
 }
-skill_canon_emit preprep "plugins/fh-commons/skills/preprep" \
+skill_canon_emit preprep "plugins/fh-preprep/skills/preprep" \
   "발표" "장표" "슬라이드" "덱" "대본" "리허설" "presentation" "keynote"
 
 # 매핑된 프로젝트 = tracks/ 하위 디렉토리(언더스코어 접두는 메타라 제외)