@tyhld/conductor 0.12.88 → 0.12.90

package/scripts/hooks/finish_gate.py

@@ -0,0 +1,536 @@
+#!/usr/bin/env python3
+"""finish_gate.py — 便の終わりの関門（職人が「まだ残っているのに終わる」のを仕組みで止める）。
+
+【なぜ要るか（実地・2026-10-02〜03 に3回）】
+  どの便の本文にも「待ちを背景に残したまま手番を閉じない。待ち終わってから、報告を書いて終える」と
+  書いてあったのに、同じ終わり方が3回起きた。★指示の文では止まらない。
+
+  ・915694ac（このPC・conductor）… 最後の発言は「CI を真似た試験はまだ実行中です。終わり次第、
+    結果を確かめます。」で `stop_reason: end_turn`。その直後に背景の仕事 `b32iul78k` が
+    `status: killed` になった（実行の記録で確認）。報告は「報告（作成中）この見出しは最終版で
+    差し替える」の下書きだけ。PR #252 は開いたまま。管制では「終わりました」になった。
+  ・47bdfe00（このPC・ai-kana）… 最後の発言は「Auto-merge is still armed … Waiting.」で end_turn。
+    直後に背景の仕事 `be6b727fc`（合流されるまで待つ）が killed。報告本文は1文字も無い。
+  ・dc1c9ed2（ノートPC・ai-kana）… 同じ形（このPCに記録が無いので実物では確かめていない）。
+
+  ★原因は1つ。画面なし方式（`claude -p`）では【手番の終わり＝処理の終わり】。
+    「背景の待ちが終わったら続ける」つもりで手番を閉じると、その瞬間に背景の待ちは殺され、
+    職人は二度と起きない。対話の画面と違って、誰も起こしてくれない。
+
+【どう止めるか】Stop フック（ADR-024 の報告の関門）を土台に広げる。職人が手番を閉じようとした
+  ときに【実物】を見て、残っていれば `{"decision":"block","reason":…}` を返して続けさせる。
+  ★職人の言葉・報告の文意は読まない。見るのは次の3つだけ。
+    (1) この便で作った PR が開いたまま・合流の予約中のまま … `gh pr list` の実物
+    (2) 報告が無い・下書きのまま                          … 報告ファイルの形（囲み・本文・下書きの印）
+    (3) 背景に回した待ちが残っている                      … 会話の記録の `backgroundTaskId` と
+                                                           `<task-notification>` の差
+
+【止め続けない】同じ理由で止めるのは `CAP_PER_KIND` 回まで（合計 `CAP_TOTAL` 回まで）。
+  上限に達したら止めず、理由を控え（residue）に残して終わらせる。中継がその控えを
+  「終了の事実」の `jobEndDetail` に載せるので、管制には「途中で終わった」と分かる形で届く。
+  ★本体にも歯止めがある（連続 8 回で打ち切り・`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`）。
+    上限はその内側に収める（3 × 2 系統 = 最大 6 < 8）。
+
+【止めない便】
+  ・便の印（CONDUCTOR_JOB）が無い … そもそも便ではない（対話の作業・自己診断）
+  ・画面なし方式でない           … 対話の画面では「手番の終わり」は人への受け渡しなので止めない
+  ・人が答えるべき問いかけで終わった … 人の判断が先（ADR-024 §3 の取りこぼしを作らない）
+  ・便の本文に「合流は人が行う」と書いてある … (1) を見ない（ADR-007）
+  ・PR を作っていない便・読むだけの便 … (1) は当たらない（開いた PR が無いので何も起きない）
+"""
+import json
+import os
+import re
+import subprocess
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 回数の上限（★止め続けて便が終わらなくなる形にしない）
+# ─────────────────────────────────────────────────────────────────────────────
+#: 同じ理由で止める回数の上限。
+CAP_PER_KIND = 3
+#: 全部の理由を合わせた上限。★本体の連続上限（既定 8）より小さくする。
+CAP_TOTAL = 6
+
+#: 残りの種類（控えの数え方の見出し）。
+GATE_KINDS = ('report', 'pr', 'background')
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 置き場
+# ─────────────────────────────────────────────────────────────────────────────
+def _home(env):
+    return (env.get('HOME') or os.path.expanduser('~')).rstrip('/')
+
+
+def _state_root(env):
+    """`~/.local/state`（`XDG_STATE_HOME` があればそちら）。★中継の reportStoreDirs と同じ決め方。"""
+    xdg = (env.get('XDG_STATE_HOME') or '').strip()
+    return xdg if xdg else os.path.join(_home(env), '.local', 'state')
+
+
+def gate_dir(env=None):
+    """関門の控えの置き場。"""
+    env = os.environ if env is None else env
+    return os.path.join(_state_root(env), 'conductor', 'finish-gate')
+
+
+def _safe_id(command_id):
+    return re.sub(r'[^A-Za-z0-9_-]', '', str(command_id or ''))[:128] or 'unknown'
+
+
+def counts_path(command_id, env=None):
+    """その便で「どの理由で何回止めたか」の控え。"""
+    return os.path.join(gate_dir(env), f'{_safe_id(command_id)}.json')
+
+
+def residue_path(command_id, env=None):
+    """上限に達して終わらせたときの理由の控え（中継が終了の事実へ載せる）。"""
+    return os.path.join(gate_dir(env), f'{_safe_id(command_id)}.residue')
+
+
+def report_dirs(env=None):
+    """報告の置き場（★中継の reportStoreDirs と同じ順序・同じ決め方）。"""
+    env = os.environ if env is None else env
+    explicit = (env.get('CONDUCTOR_REPORT_DIR') or '').strip()
+    if explicit:
+        return [explicit]
+    uid = os.getuid() if hasattr(os, 'getuid') else 0
+    return [
+        os.path.join(_state_root(env), 'conductor', 'reports'),
+        os.path.join('/tmp', f'claude-{uid}', 'conductor-report'),
+        os.path.join('/tmp', f'conductor-report-{uid}'),
+    ]
+
+
+def report_files(command_id, env=None):
+    """その便の報告ファイルの候補（未処理 → 処理済みの順）。"""
+    name = f'{_safe_id(command_id)}.md'
+    dirs = report_dirs(env)
+    return [os.path.join(d, name) for d in dirs] + [os.path.join(d, 'processed', name) for d in dirs]
+
+
+def read_report_text(command_id, env=None):
+    """その便の報告の本文（無ければ None）。"""
+    for f in report_files(command_id, env):
+        try:
+            with open(f, encoding='utf-8', errors='replace') as fh:
+                text = fh.read().strip()
+        except Exception:  # noqa: BLE001
+            continue
+        if text:
+            return text
+    return None
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# (2) 報告が無い・下書きのまま
+#
+# 【★形の決まりの正本は1か所（便 461be339）】
+#   「囲みが閉じている／5つの欄が在る／outcome が決まった語／evidence が1件以上／本文が空でない」は
+#   中継（src/relay.ts の parseReport / missingOf）も同じ判定をする。同じ決まりを2か所に書くと、
+#   片方だけ直して食い違う（＝関門は差し戻すのに中継は届いたと数える、またはその逆）。
+#   だから決まりは `report-shape.json`（この python と同じフォルダに配られる）だけに置き、
+#   ここは【読み手】にする。中継の側は定数がこの JSON と同じであることを試験で固定する。
+#   ★読めなかったときは形の判定をしない（fail open＝関門が足される前と同じ動き）。
+#
+# 【★本文の言葉だけは別】下書きの印（作成中・TODO など）は関門だけの決まり。
+#   報告の中身の言葉で完了を判定しない（えふさん確定 2026-09-23）ので、中継からは手が届かない
+#   ところ（この下の DRAFT_MARKERS）に置く。正本はここ1か所。
+# ─────────────────────────────────────────────────────────────────────────────
+#: 「最終版で差し替える前」の印。★決まった字面の一覧だけを見る（文意は読まない）。
+DRAFT_MARKERS = ('作成中', '下書き', '差し替える', 'あとで書く', '（未記入）', '(未記入)', 'TODO', 'TBD')
+
+#: 形の決まりの正本（★この python と同じフォルダに配られる）。
+SHAPE_SPEC_NAME = 'report-shape.json'
+
+#: 足りない物の名前 → 職人へ見せる日本語。
+_SHAPE_JA = {
+    'instruction_id': 'instruction_id の欄',
+    'site': 'site の欄',
+    'outcome': 'outcome（pushed / no_change / blocked のどれか1つ）',
+    'created_at': 'created_at の欄',
+    'evidence': 'evidence（1件以上）',
+    'body': '囲みの下の本文',
+}
+
+
+def shape_spec_path():
+    """形の決まりの正本の置き場（自分と同じフォルダ）。"""
+    return os.path.join(os.path.dirname(os.path.abspath(__file__)), SHAPE_SPEC_NAME)
+
+
+def load_shape_spec(path=None):
+    """形の決まりを読む。読めない・形が違うなら None（＝形の判定をしない）。"""
+    try:
+        with open(path or shape_spec_path(), encoding='utf-8') as f:
+            got = json.load(f)
+    except Exception:  # noqa: BLE001
+        return None
+    if not isinstance(got, dict):
+        return None
+    fields = got.get('requiredFields')
+    outcomes = got.get('validOutcomes')
+    if not isinstance(fields, list) or not fields or not all(isinstance(k, str) for k in fields):
+        return None
+    if not isinstance(outcomes, list) or not outcomes or not all(isinstance(k, str) for k in outcomes):
+        return None
+    return got
+
+
+#: 読み込んだ正本（無ければ None）。
+SHAPE_SPEC = load_shape_spec()
+
+_KV_RE = re.compile(r'^([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(.*)$')
+_BULLET_RE = re.compile(r'^\s*-\s+(.*)$')
+
+
+def _parse_report(text):
+    """報告を欄と本文に分ける（★中継の parseReport と同じ読み方）。
+
+    返り: (欄の辞書, evidence の一覧, 本文)。囲みが無い・閉じていないときは
+    欄も evidence も空で、全文が本文になる（中継と同じ倒れ方）。
+    """
+    raw = '' if text is None else str(text)
+    if raw.startswith(''):
+        raw = raw[1:]
+    lines = raw.split('\n')
+    i = 0
+    while i < len(lines) and lines[i].strip() == '':
+        i += 1
+    if i >= len(lines) or lines[i].strip() != '---':
+        return {}, [], raw.strip()
+    fields, evidence, last_key = {}, [], ''
+    j = i + 1
+    closed = False
+    while j < len(lines):
+        line = lines[j]
+        if line.strip() == '---':
+            closed = True
+            break
+        bullet = _BULLET_RE.match(line)
+        if bullet is not None:
+            if last_key == 'evidence' and bullet.group(1).strip() != '':
+                evidence.append(bullet.group(1).strip())
+            j += 1
+            continue
+        kv = _KV_RE.match(line)
+        if kv is None:
+            j += 1
+            continue
+        last_key = kv.group(1).lower()
+        value = kv.group(2).strip()
+        if last_key == 'evidence':
+            if value != '':
+                evidence.append(value)
+            j += 1
+            continue
+        fields[last_key] = value
+        j += 1
+    if not closed:
+        return {}, [], raw.strip()
+    return fields, evidence, '\n'.join(lines[j + 1:]).strip()
+
+
+def report_shape_missing(text, spec=None):
+    """報告の「形」で足りない物を並べる（空なら整っている）。★純粋関数。
+
+    ★正本が読めないときは [] を返す（形の判定をしない＝退行しない）。
+    """
+    rules = SHAPE_SPEC if spec is None else spec
+    if not rules:
+        return []
+    fields, evidence, body = _parse_report(text)
+    outcomes = tuple(rules['validOutcomes'])
+    out = []
+    for key in rules['requiredFields']:
+        if key == 'body':
+            if body.strip() == '':
+                out.append(key)
+        elif key == 'evidence':
+            if not evidence:
+                out.append(key)
+        elif key == 'outcome':
+            if (fields.get('outcome') or '').strip() not in outcomes:
+                out.append(key)
+        elif not (fields.get(key) or '').strip():
+            out.append(key)
+    return out
+
+
+def report_body(text):
+    """報告の本文（囲みの下）。囲みが無い・閉じていないときは全文。★純粋関数。"""
+    return _parse_report(text)[2]
+
+
+def report_residue(text, spec=None):
+    """報告が「無い・形が整っていない・下書きのまま」なら理由、出来上がっていれば None。"""
+    if text is None or not text.strip():
+        return '報告ファイルが無い（または空）'
+    missing = report_shape_missing(text, spec)
+    if missing:
+        return ('報告の形が整っていない（足りない: '
+                + '・'.join(_SHAPE_JA.get(k, k) for k in missing) + '）')
+    hit = next((m for m in DRAFT_MARKERS if m in report_body(text)), None)
+    if hit is not None:
+        return f'報告が下書きのまま（本文に「{hit}」が残っている）'
+    return None
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# (3) 背景に回した待ちが残っている
+# ─────────────────────────────────────────────────────────────────────────────
+#: 背景に回した仕事が始まった印（道具の戻りに入る・実測 2026-10-03）。
+_BG_START_RE = re.compile(r'"backgroundTaskId"\s*:\s*"([A-Za-z0-9_-]+)"')
+#: 背景の仕事から知らせが届いた印。★`<task-notification>` の塊の中の `<task-id>` だけを拾う
+#:  （道具の説明文に出てくる `<task-notification>` の字面を取り違えない）。
+_BG_NOTIFY_RE = re.compile(r'<task-notification>(.*?)</task-notification>', re.S)
+_BG_TASK_ID_RE = re.compile(r'<task-id>([A-Za-z0-9_-]+)</task-id>')
+
+
+def outstanding_background_tasks(transcript_path):
+    """知らせがまだ届いていない背景の仕事の番号（順番は出てきた順）。読めなければ空。"""
+    if not transcript_path or not os.path.isfile(transcript_path):
+        return []
+    started, settled = [], set()
+    try:
+        with open(transcript_path, encoding='utf-8', errors='replace') as f:
+            for line in f:
+                for m in _BG_START_RE.finditer(line):
+                    if m.group(1) not in started:
+                        started.append(m.group(1))
+                if '<task-notification>' not in line:
+                    continue
+                for blk in _BG_NOTIFY_RE.findall(line.replace('\\n', '\n')):
+                    settled.update(_BG_TASK_ID_RE.findall(blk))
+    except Exception:  # noqa: BLE001
+        return []
+    return [t for t in started if t not in settled]
+
+
+def background_residue(task_ids):
+    """★純粋関数。残っていれば理由、無ければ None。"""
+    if not task_ids:
+        return None
+    return ('背景に回した待ちが ' + str(len(task_ids)) + ' 件残っている（'
+            + '・'.join(task_ids[:5]) + '）')
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# (1) PR が開いたまま・合流の予約中のまま
+# ─────────────────────────────────────────────────────────────────────────────
+#: 便の本文に書かれた「合流は人が行う」（ADR-007）。★これが在れば (1) を見ない。
+#: 「〜する」の言い回し（する・します・行う・行います・やる・やります …）。
+_DO = r'(?:行(?:う|います|います。)|やり(?:ます)?|やる|し(?:ます)?|する)'
+_HUMAN_MERGE_RE = re.compile(
+    r'(?:マージ|合流)は(?:人間|人|えふさん|持ち主)が' + _DO
+    + r'|(?:人間|人|えふさん|持ち主)が(?:マージ|合流)(?:を)?' + _DO
+    + r'|(?:マージ|合流)しない',
+)
+
+
+def human_merge_requested(job_body):
+    """便の本文が「合流は人が行う／合流しない」と言っているか。★純粋関数。"""
+    return bool(_HUMAN_MERGE_RE.search(job_body or ''))
+
+
+def open_pr_residue(prs):
+    """`gh pr list` の結果から理由を作る。★純粋関数（通信はしない）。
+
+    prs は [{'number':…, 'url':…, 'state':'OPEN', 'autoMergeRequest':{…}|None}, …]。
+    """
+    if not isinstance(prs, list):
+        return None
+    out = []
+    for pr in prs:
+        if not isinstance(pr, dict):
+            continue
+        if str(pr.get('state') or 'OPEN').upper() != 'OPEN':
+            continue
+        num = pr.get('number')
+        if pr.get('autoMergeRequest'):
+            out.append(f'#{num}（合流の予約中）')
+        else:
+            out.append(f'#{num}（開いたまま）')
+    if not out:
+        return None
+    return 'この便で作った PR が合流していない: ' + '・'.join(out)
+
+
+def current_branch(work_dir):
+    """いまの作業ブランチ名（読めない・main のときは None）。"""
+    try:
+        r = subprocess.run(
+            ['git', '-C', work_dir, 'rev-parse', '--abbrev-ref', 'HEAD'],
+            capture_output=True, text=True, timeout=15, check=False,
+        )
+    except Exception:  # noqa: BLE001
+        return None
+    b = (r.stdout or '').strip()
+    if r.returncode != 0 or not b or b in ('HEAD', 'main', 'master'):
+        return None
+    return b
+
+
+def read_open_prs(work_dir, branch):
+    """その枝の開いた PR を聞く。聞けなければ None（＝分からない＝止めない側へ倒す）。"""
+    if not branch:
+        return None
+    try:
+        r = subprocess.run(
+            ['gh', 'pr', 'list', '--head', branch, '--state', 'open',
+             '--json', 'number,url,state,autoMergeRequest'],
+            cwd=work_dir, capture_output=True, text=True, timeout=30, check=False,
+        )
+    except Exception:  # noqa: BLE001
+        return None
+    if r.returncode != 0:
+        return None
+    try:
+        got = json.loads(r.stdout or '[]')
+    except Exception:  # noqa: BLE001
+        return None
+    return got if isinstance(got, list) else None
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 回数の数え方
+# ─────────────────────────────────────────────────────────────────────────────
+def load_counts(command_id, env=None):
+    try:
+        with open(counts_path(command_id, env), encoding='utf-8') as f:
+            got = json.load(f)
+    except Exception:  # noqa: BLE001
+        return {}
+    return {k: int(v) for k, v in got.items() if k in GATE_KINDS and isinstance(v, (int, float))} \
+        if isinstance(got, dict) else {}
+
+
+def save_counts(command_id, counts, env=None):
+    p = counts_path(command_id, env)
+    try:
+        os.makedirs(os.path.dirname(p), mode=0o700, exist_ok=True)
+        with open(p, 'w', encoding='utf-8') as f:
+            json.dump(counts, f)
+    except Exception:  # noqa: BLE001
+        pass
+
+
+def save_residue(command_id, record, env=None):
+    """上限に達して終わらせた理由を残す（中継が終了の事実へ載せる）。
+
+    record は `build_residue_record()` の辞書（人向けの1行＋機械が読む形）。
+    ★文字列を渡したときは人向けの1行だけとして扱う（古い呼び方も通る）。
+    """
+    if isinstance(record, str):
+        record = {'text': record}
+    text = str(record.get('text') or '').strip()[:500]
+    out = {'text': text}
+    if isinstance(record.get('reasons'), list):
+        out['reasons'] = [k for k in record['reasons'] if k in GATE_KINDS]
+    if isinstance(record.get('counts'), dict):
+        out['counts'] = {k: int(record['counts'].get(k, 0)) for k in GATE_KINDS}
+    p = residue_path(command_id, env)
+    try:
+        os.makedirs(os.path.dirname(p), mode=0o700, exist_ok=True)
+        with open(p, 'w', encoding='utf-8') as f:
+            json.dump(out, f, ensure_ascii=False)
+    except Exception:  # noqa: BLE001
+        return False
+    return True
+
+
+def cap_per_kind(env=None):
+    env = os.environ if env is None else env
+    try:
+        n = int((env.get('CONDUCTOR_FINISH_GATE_CAP') or '').strip())
+    except Exception:  # noqa: BLE001
+        return CAP_PER_KIND
+    return n if n >= 0 else CAP_PER_KIND
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 判定（★純粋関数。ここに通信もファイル読みも入れない）
+# ─────────────────────────────────────────────────────────────────────────────
+def decide(residues, counts, cap=CAP_PER_KIND, cap_total=CAP_TOTAL):
+    """残り（{種類: 理由}）と今までの回数から、止めるかどうかを決める。
+
+    返り: {'block': bool, 'kinds': [種類], 'reasons': [理由], 'counts': 次の回数, 'last': bool}
+      block=True  … 続けさせる（reason を職人へ返す）
+      block=False … 終わらせる（kinds が空でなければ「途中で終わった」＝控えを残す）
+      last=True   … これが最後の差し戻し（次は止めない）
+    """
+    counts = {k: int(counts.get(k, 0)) for k in GATE_KINDS}
+    live = [k for k in GATE_KINDS if residues.get(k)]
+    if not live:
+        return {'block': False, 'kinds': [], 'reasons': [], 'counts': counts, 'last': False}
+    total = sum(counts.values())
+    allowed = [k for k in live if counts[k] < cap] if total < cap_total else []
+    if not allowed:
+        # 上限に達した。止めずに、理由を付けて終わらせる。
+        return {'block': False, 'kinds': live, 'reasons': [residues[k] for k in live],
+                'counts': counts, 'last': False}
+    nxt = dict(counts)
+    for k in allowed:
+        nxt[k] += 1
+    last = sum(nxt.values()) >= cap_total or all(nxt[k] >= cap for k in allowed)
+    return {'block': True, 'kinds': allowed, 'reasons': [residues[k] for k in allowed],
+            'counts': nxt, 'last': last}
+
+
+#: 残りの種類ごとの「次にやること」。★職人へ返す文（Conductor が報告の中身を作ることはしない）。
+NEXT_STEPS = {
+    'background': (
+        '背景に回した待ちを、いまこの手番の中で終わらせてください。'
+        '★画面なし方式（claude -p）では【手番の終わり＝処理の終わり】です。'
+        '手番を閉じると背景の待ちは殺され、職人は二度と起きません（実地 915694ac・47bdfe00）。'
+        '待つなら Monitor か until ループで、この手番の中で待ち切ってください。'
+    ),
+    'pr': (
+        '鉄則7のとおり、保護の確認 → CI → 合流 → 合流後の確かめ（4段）を終わらせてください。'
+        '合流を予約しただけでは終わりではありません。`gh pr view <番号> --json state` が '
+        'MERGED になり、合流でできたコミットが合流先に入っていることを実物で確かめてから報告します。'
+        '★`--admin` など保護を迂回する旗は使いません。合流できない理由が分かったら、'
+        'その理由を報告に書いて終えてください（それなら止めません）。'
+    ),
+    'report': (
+        '報告を最終版まで書き上げてください（置き場は配達役の1行が指すファイル1か所）。'
+        '1行目から6欄の囲み（instruction_id・site・outcome・created_at・evidence）を置き、'
+        'その下に本文を書きます。★「作成中」「差し替える」などの下書きの印を1つも残さないでください。'
+    ),
+}
+
+
+def build_reason(result):
+    """職人へ返す文（何が残っているか＋次にやること）。"""
+    head = '【便の終わりの関門】まだ終わっていません。この手番を閉じないでください。'
+    lines = [head, '', '■ 残っているもの（実物で確かめた事実）']
+    lines += [f'  ・{r}' for r in result['reasons']]
+    lines += ['', '■ 次にやること']
+    lines += [f'  ・{NEXT_STEPS[k]}' for k in result['kinds']]
+    if result.get('last'):
+        lines += ['', '★これが最後の差し戻しです。次に手番を閉じると便は終わります。'
+                      'どうしても終わらせられないときは、報告の outcome を blocked にして、'
+                      '「どこまで進んだか・何が残っているか・なぜ進められないか」を書いて終えてください。']
+    return '\n'.join(lines)
+
+
+def build_residue_text(result):
+    """上限に達して終わらせたときに控えへ残す1行（管制へ「途中で終わった」として届く）。"""
+    return '途中で終わった（便の終わりの関門の上限）: ' + ' / '.join(result['reasons'])
+
+
+def build_residue_record(result):
+    """控えに残す中身（人向けの1行＋★管制が機械で読む形）。★純粋関数。
+
+    【なぜ機械で読む形も要るか（便 461be339）】上限に達して終わらせた便は、これまで
+      人向けの自由な文（`jobEndDetail`）にしか理由が乗らなかった。管制では「終わった」と
+      「途中で終わった」を機械で見分けられない（実地 7aa63a97 の残った穴）。
+      ★新しい状態は作らず、終了の事実に `finishGate` の欄を足して届ける。
+
+    返り: {'text': 人向けの1行, 'reasons': 残っていた種類, 'counts': 止めた回数}
+    """
+    return {
+        'text': build_residue_text(result),
+        'reasons': [k for k in GATE_KINDS if k in result['kinds']],
+        'counts': {k: int(result['counts'].get(k, 0)) for k in GATE_KINDS},
+    }

package/scripts/hooks/policy.py

@@ -2343,6 +2343,14 @@ def _real_segments(command: str):
 GUARD_PLACES = (
     ('site-file', '.claude/settings'),
     ('home-tree', '.claude/skills'),
+    # ★~/.tyhld は【まるごと】守る（便 7aa63a97）。
+    #   【実地の穴（便 b7bd5e43 の発見・2026-10-03 に再現）】Write・Edit は前から ~/.tyhld の
+    #   どこでも止めていた（下の「前からの広い守り」）。ところが Bash は hooks と bin の下しか
+    #   止めず、~/.tyhld の直下（kc の実体・ブラウザの道具・控え）は職人の touch・rm・リダイレクト・
+    #   cp・mv・sed -i から書けた（実測で allow）。＝道具によって結果が違う穴。
+    #   ★hooks・bin の2行は【消さない】。一覧は OR で照らすので、残しておけば
+    #   「前から止まっていた物が通る」ことが構造的に起きない（守りを強める方向だけ）。
+    ('home-tree', '.tyhld'),
     ('home-tree', '.tyhld/hooks'),
     ('home-tree', '.tyhld/bin'),
     ('home-tree', '.config/systemd'),
@@ -3297,7 +3305,9 @@ def _expand_vars(text: str, env) -> str:
 #   ★報告の文の中に場所の名前が出てくるだけ（空白を含む文字列）は場所と読まない。
 _CODE_GUARD_JOIN_RE = re.compile(
     r'''['"]\.claude['"]\s*[,/+]\s*['"](settings[\w.]*\.json|skills)['"/]'''
-    r'''|['"]\.tyhld['"]\s*[,/+]\s*['"](hooks|bin)['"/]'''
+    # ★`'.tyhld'` に【何を】つないでも場所と読む（便 7aa63a97）。前は hooks|bin だけだったので、
+    #   Path.home() / '.tyhld' / 'kc.sh' のような組み立てが素通りしていた。広げる方向だけ。
+    r'''|['"]\.tyhld['"]\s*[,/+]\s*['"]'''
     r'''|['"]\.[\w-]+['"]\s*[,/+]\s*['"](hooks\.json|config\.toml)['"]'''
     r'''|['"]\.config['"]\s*[,/+]\s*['"]systemd['"/]''')
 _CODE_PATH_LITERAL_RE = re.compile(r'''['"`]>{0,2}([^'"`\s*?\[\]]{1,300})['"`]''')