[hdknr]

利用上限などでターンが止まったその場で、StopFailure の hook が ~/.claude/usage-limit-stops.jsonl に 1 行残し、通知を出す（#456 の陽性対照を取りこぼさないため）。

• scripts/record-stop-failure.py — hook の本体（何を書き、何を書かないかは docstring を正とする）
• scripts/test-record-stop-failure.py — 回帰テスト（一時 HOME・偽の osascript。変異 13 件）
• docs/usage/usage-limit-stop-hook.md — 登録の手順（登録は利用者が行う。matcher なし）
• docs/plugins/dev-loop-cruise.md — 環境の点検の節から指す
• check-all.py・plugins.yml・mkdocs.yml・CLAUDE.md に登録

プラグインの中身は変えていないので版は上げていない。受入基準と関門の記録は docs/plans/issue-468.md。

Fixes #468

🤖 Generated with Claude Code

[hdknr]

関門の結果（dev-loop #468）

関門	結果
1 パス目 Verifier（dev-loop:dev-loop-verifier・sonnet）	反証 2 件・指摘 1 件 → 直した（fbd6c1a）
1 パス目 /code-review high	指摘 10 件（3 件は Verifier と同じ）→ 6 種を直し、4 件は残課題
2 パス目 Verifier	反証 0 件・軽微な所見 3 件（V2-1 は 2 パス目で直した）
2 パス目 /code-review high	指摘 5 件 → 直す 3 件（00930e3）・残課題 2 件
狭いパス（2 パス目で直した 35196a7..00930e3 だけ。Verifier・sonnet）	反証 1 件（軽微）→ 直さず下に渡す

check-all.py 52/52 緑（main の取り込み後も）。mkdocs build --strict（plans/ を外した一時の設定）が通る。生成物なし（図・skill-metrics は Verifier と /code-review が独立に確認）。

2 パス目で直した行と狭いパス

• CR2-1/V2-1: cwd が対にならないサロゲートだと記録全体が unreadable になり、rate_limit なのに通知に「待て」が付かなかった → cwd.encode("utf-8", "surrogatepass")。狭い Verifier を通した
• CR2-4: テストに surrogate-cwd のケースと、変異「surrogatepass を外す」を足した（赤）。狭い Verifier を通した
• CR2-5: docs の「hook が壊れていても、何も表示されません」は確かめていないので「確かめていない」に弱めた（受入基準 9）。狭い Verifier を通した

素通りした変異（狭いパスの Verifier が設計）:

• surrogatepass → replace・ignore。テストは cwd_hash の長さしか見ないので、"\ud800" が "?"／"" と同じハッシュになる衝突を判別しない（陽性対照: replace・ignore は衝突、surrogatepass は衝突しない——著者も確かめた）。現行のコードは正しい。採否はレビューでお願いします。

未証明（コードレビューでの確認をお願いします）

• 利用上限（claude.ai のセッションの上限）で実際に StopFailure が発火し、error が rate_limit（あるいは billing_error）になること・待ちの間の発火回数——上限を狙って起こせない（利用上限の自動継続の陽性対照（true を明示した状態）を取る手段が無い（#454 の BLOCKED） #456 そのもの）。docs と docstring には「確かめていない」と書いた

BLOCKED

• なし（受入基準 8 の陽性対照は、一時 HOME・無効な API キーで claude -p を起こし、authentication_failed の発火を観測した。matcher だけを変えて記録の有無が分かれた）

満たしていない受入基準

• なし

利用者の決定

• 受入基準 4・7: docs の登録は matcher なし（billing_error が「usage limit reached」に対応づけられており、上限がどちらで来るかを確かめていないため）
• main を取り込んだ（cruise: 周の途中で見つかった課題を台帳に足して、同じ cruise の中で直す #464）。環境の点検の節から設定手順を指す行は既にあり、そのままとした

残課題（直していない）

• CR7: テストが長さを見ずに添字で引く（退行時に IndexError で要約が出ない）
• CR8: 「通知が失敗しても記録は残る」の後半を壊す変異が無い
• CR9: assert_not_real_home が素の assert（-O で消える）
• CR10: docs のコマンドがパスをクォートしていない
• CR2-2: main の外側の try/except を外す変異がテストで死なない（いまの入力ではそこに届かない）
• CR2-3: 「オブジェクトでない」「error が無い」の変異が、約束ではなく理由の文言の違いで死んでいる
• V2-2: error が空文字のとき通知が「入力を読めなかった」と出る（記録は正しい）
• V2-3: 上限でない error が osascript の引数にそのまま入る（- で始まる値の扱いは未確認。値は本体の列挙値）

採否の表は docs/plans/issue-468.md の「既知の限界・決着済みの論点」。