@joshuafolkken/kit 1.1035.0 → 1.1094.0

package/prompts/collaboration-workflow/turn-batching.md

@@ -24,11 +24,11 @@
 
 **ツール自体が動いていたのは合わせて約 54 秒**である。同じ 66 往復が消費した壁時計は 66 × 9〜13 秒 ≒ 600〜850 秒で、1 桁違う。1 ターンあたりの壁時計は 9〜13 秒の狭い帯に収まるので、**ターン数がそのまま run の下限を決めている。**
 
-epic #1262 の子（#1256〜#1260）がゲートを 133 秒から中央値 5 秒まで削ったのに run 全体が 5% しか縮まなかったのは、これが理由である。削った先が壁時計を決めていなかった。
+ゲート短縮が run を縮めなかった経緯は `docs/maintainers/turn-batching-rationale.md` →「ゲートを削っても run が縮まなかった理由」。
 
 ## 判断基準は「依存の有無」であって、呼び出しの種類ではない
 
-読み取りだけの規則ではない。**`Edit` も同じ規則の対象である** — 同じファイルの離れた領域や、別々のファイルへの編集は、互いの結果を使っていないので同じターンに載る。実測で最大の単一項目が `Edit` 34 回だったのは、そこが最も守られていなかったからである。
+読み取りだけの規則ではない。**`Edit` も同じ規則の対象である** — 同じファイルの離れた領域や、別々のファイルへの編集は、互いの結果を使っていないので同じターンに載る（実測の内訳は `docs/maintainers/turn-batching-rationale.md` →「`Edit` が最大の単一項目だった理由」）。
 
 逆に、**依存があるなら分けるのが正しい。** 次はいずれも 1 つ前の結果を入力に使うので、同じターンに載せてはならない。
 
@@ -50,28 +50,20 @@ epic #1262 の子（#1256〜#1260）がゲートを 133 秒から中央値 5 秒
 
 - **PreToolUse フックが「1 件の呼び出しだけを見て、それが独立かどうかを判定する」。** 採れない。**呼び出しの独立性は、1 件の呼び出しからは観測できない。** フックが見るのはこれから走る 1 件だけで、それが直前の結果に依存しているかどうかはフックの入力に無い。依存している正当な直列実行（`grep` → `sed -n`、Edit の前の読み取り）を止めてしまい、しかも止めた側は理由を説明できない。`output-bounds.md` が「形で見分ける案は実データ上で外れる」として PreToolUse guard を却下したのと同じ形である。
 
-  **却下したのはこの判定のしかたであって、`PreToolUse` という機構そのものではない。** joshuafolkken/kit#1390 は**まさに `PreToolUse` フックとして** `pnpm josh batch:guard` を実装し、`.claude/settings.json` で配布している。判定に使うのは、いま出そうとしている 1 件ではなく**閉じた履歴** — 結果が返り終わったターンの並び — である。単発呼び出しのターンが 2 つ続いたことは 1 件からは見えないが、履歴からは見える。上に並べた懸念は、それぞれ設計で避けてある。依存は**共有ターゲット**で見るので `grep` → `sed -n` は止まらず、**書き込みも読み取りとまったく同じ基準で拒否され**（joshuafolkken/kit#1762）、拒否は 1 つの単発連続につき **1 回だけ**である（フックが読む窓を超えて続く連続では、列の開始が窓の外へ出るため窓ごとに 1 回になる — 詳細は下記の `docs/josh-commands.md`）。機構の全体は `docs/josh-commands.md` →「`josh batch:guard`」にある。
+  **却下したのはこの判定のしかたであって、`PreToolUse` という機構そのものではない。** joshuafolkken/kit#1390 は**まさに `PreToolUse` フックとして** `pnpm josh batch:guard` を実装し、`.claude/settings.json` で配布している。判定に使うのは、いま出そうとしている 1 件ではなく**閉じた履歴** — 結果が返り終わったターンの並び — である。単発呼び出しのターンが 2 つ続いたことは 1 件からは見えないが、履歴からは見える。上に並べた懸念は、それぞれ設計で避けてある。依存は**共有ターゲット**で見るので `grep` → `sed -n` は止まらず、**書き込みも読み取りとまったく同じ基準で拒否され**（joshuafolkken/kit#1762）、**手元の呼び出しが直前の列と共有ターゲットを持つときは拒否を取り下げる**（書き込み同士を含む）。拒否は 1 つの単発連続につき **1 回だけ**である（窓を超える連続は `docs/maintainers/turn-batching-rationale.md` →「`batch:guard` の拒否窓」）。委譲された子やレビューエージェントは、親の記録を共有せず、それぞれに配送される（`docs/maintainers/turn-batching-rationale.md` →「フォークへの配送の実装（joshuafolkken/kit#1424）」）。機構の全体は `docs/josh-commands-automation.md` →「`josh batch:guard`」にある。範囲が `Bash|Edit|Read` に広がった経緯（joshuafolkken/kit#1509 を含む）は `docs/maintainers/turn-batching-rationale.md` →「書き込みが範囲に入った経緯（joshuafolkken/kit#1762）」、`docs/maintainers/turn-batching-rationale.md` →「読み取りが範囲に入った経緯（joshuafolkken/kit#1798）」、`docs/maintainers/turn-batching-rationale.md` →「事務コマンドが範囲に入った経緯（joshuafolkken/kit#1875）」。
 
-  **フックはフォークにも届く。** joshuafolkken/kit#1424 以降、判定も「1 回だけ」の記録も、親ではなく**フォーク自身の transcript** を鍵にする — フックの入力にある `agent_id` から解決する `time_hook_transcript.transcript_of`（`scripts/time-runtime/time-hook-transcript.ts`）が単一ソースで、ガードは `scripts/josh/hook-decision.ts` 経由でそこを通る。委譲された子やレビューエージェントは、親の記録を共有せず、それぞれに配送される。
+  **ガードが見えないところ — ここでは自分で規則を当てる。**
 
-  **書き込みが範囲に入ったのは joshuafolkken/kit#1762 である。** それまでの限界は 2 つあり、どちらも書き込みに一度も届かないという同じ結果になっていた。joshuafolkken/kit#1509 が、同じファイルを続けて編集する区間では共有ターゲットの判定が列を毎回捨てて数え直すため拒否に必要な 2 件に列が届かないことを特定し（`time-bundles.ts` の write→write 例外として解消済み）、そのうえで**配線が `Bash` のみだったので `Edit` の連続にはそもそもフックが呼ばれなかった**。実測 19 run で、回収できる往復 261 件のうち **184 件（70.5%）が書き込み**、`Edit` だけで 158 件（60.5%）— 最大の寄与源が構造上ずっと圏外だった。
+  - **塞ぎきれないのは「いま中断しているターンの中身」であり、これは transcript から観測できないので設計上残る。** 同じファイルへの編集 3 件を 1 ターンにまとめた場合、先頭だけが拒否され残り 2 件が適用されることはある。**ただし壊れるのではなく失敗する** — 再発行された編集は書いたときの本文に一致するか、一致せずに報告されるかのどちらかである。
+  - **ファイル全体を書き出す `Write` だけは拒否しない。** 再発行された `Write` は本文を照合しないので、そのターンの兄弟が適用した編集を無言で上書きしうる。根拠は `docs/maintainers/turn-batching-rationale.md` →「中断中のターンと `Write` の除外の根拠」。
+  - **連続を切るのは「そもそもまとめられない呼び出し」、すなわち結果を次の呼び出しが必要とする委譲である。**
+  - **`pnpm josh …` は読み取り専用サブコマンドの allow-list（`READ_JOSH_SUBCOMMANDS`）に載るものだけが bundleable である。** 書き込む・外部送信するサブコマンド（`run:progress --mark` はマーカーを書き、`notify` は送信し、`main:sync` / `epic` / `run:hold` は状態を書く）は allow-list に**入れない**。連鎖した行（`&&` / `|` / `>` など）は、先頭の `pnpm` が後続の変更を隠すため読みとしては信用せず、通常判定に落とす。
+  - ツールを 1 つも呼ばないターンと、ガードが `off` のレーン子 — それぞれ下の「事後の計測」と「実装中の独立編集に効く合成コマンド」。
 
-  **却下されていたのは「マッチャだけを広げる案」であって、「書き込みを拒否可能にする案」ではない。** 判定述語が書き込みに常に `false` を返す状態でマッチャだけ広げれば、必ず「許可」としか答えられないプロセスが編集ごとに 1 つ増える — この費用の議論は正しく、いまも有効である。joshuafolkken/kit#1762 は**先に述語を広げて**から配線を `Bash|Edit` にしたので、マッチャが届く先には答えのある問いがある。
-
-  **「拒否された編集は兄弟だけが適用されて自分は残らない」という安全側の懸念は、除外ではなく依存判定の絞り込みで塞いである。** 実害が出るのは「いま書き換え中のファイル」を名指す編集だけなので、**手元の呼び出しが直前の列と共有ターゲットを持つときは拒否を取り下げる**（書き込み同士を含む）。残るのは列がまったく触れていないファイルへの編集で、その再発行は書いたときとまったく同じ本文に当たる。
-
-  **塞ぎきれないのは「いま中断しているターンの中身」であり、これは transcript から観測できないので設計上残る。** 同じファイルへの編集 3 件を 1 ターンにまとめた場合、先頭だけが拒否され残り 2 件が適用されることはある。**ただし壊れるのではなく失敗する** — 拒否されうる書き込みはいずれも本文で位置を決める形なので、再発行された編集は書いたときの本文に一致するか、一致せずに報告されるかのどちらかである。誤った位置に当たることはない。通常は 1 往復、この場合でも編集 1 件のやり直しで、読み取り側が既に受け入れている誤検知の代償と同じ大きさである。
-
-  **ファイル全体を書き出す `Write` だけは拒否しない。それがこの上限を成り立たせている。** 再発行された `Write` は本文を照合しないので、そのターンの兄弟が適用した編集を無言で上書きしうる。1 つのファイルを `Write` してから `Edit` するターンは実際に起きる形なので、例外ではなくツール名で除外してある。`>` によるシェルの上書きも同じ性質だが、衝突するには 1 ターンに同じパスへの書き込みが 2 件必要で、そういう形は起きない。
-
-  **読み取りが範囲に入ったのは joshuafolkken/kit#1798 である。** `Read` は述語（`is_guarded_call`）では最初から候補として扱われていた — 配線が `Bash|Edit` のままだったので、フックがそもそも呼ばれなかっただけである。`fullrun #1783` の実測では、本流 76 リクエストのうち **46 が単発**、3 連続以上の塊が **7 つ**あったのに対し、拒否は **2 回**しか発火していない。7 つのうち 4 つが `Read` / `Write` / `Agent` を含み、いずれも配線の外だった。**計数側は正しかった** — 単発ターンが連続を延長するかどうかは `is_bundleable` が決めており、`Read` / `Glob` / `Grep` / `Write` はいずれも延長する。連続を切るのは「そもそもまとめられない呼び出し」、すなわち結果を次の呼び出しが必要とする委譲である。したがって直したのは配線だけで、`Bash|Edit|Read` になった。
-
-  **事務コマンドが範囲に入ったのは joshuafolkken/kit#1875 である。** `is_bundleable` は先頭語の allow-list（`READ_COMMANDS`）と mutation deny-list で判定するので、**`pnpm` で始まる `pnpm josh …` はすべて非バンドル**だった — 書き込む josh コマンド（`gate` / `followup` / `git`）を弾くための `pnpm` が、読み取り専用の `issue:state` / `release:scope` まで一緒に落としていた。結果として事務往復は `Bundling:` の回収可能数にも `batch:guard` の判定にも一度も現れず、run の最も高い終盤で最大の事務カテゴリが構造上ずっと圏外だった。**直したのは判定であって規則ではない**（この Issue の受け入れ条件そのもの）: 読み取り専用サブコマンドの allow-list（`READ_JOSH_SUBCOMMANDS`、別名は正準名に解決してから照合）を足し、これに載る `pnpm josh` を bundleable にした。書き込む・外部送信するサブコマンド（`run:progress --mark` はマーカーを書き、`notify` は送信し、`main:sync` / `epic` / `run:hold` は状態を書く）は allow-list に**入れない** — 取りこぼしは floor、誤って入れれば claim、というこのモジュール一貫の非対称性に従う。連鎖した行（`&&` / `|` / `>` など）は、先頭の `pnpm` が後続の変更を隠すため読みとしては信用せず、通常判定に落とす。**guard を弱めるのではなく、これまで見えていなかった呼び出しに届かせる強化である。**
-
-- **複数編集を 1 呼び出しにまとめるツールを前提にする。** 前提にできない。この repository が対象とする harness には常に存在するとは限らず、存在しない側では規則が一度も発火しない。**同じターンに複数の `Edit` を並べる形はどの harness でも成立する**ので、規則はそちらで書く。**ただし joshuafolkken/kit#2366 が「そちらで書く」前提を実測で反証した** — 直近 6 レーンで 230 ターンすべてが単発（密度 1.000）、native な複数編集は一度も起きていない。却下されたのは _harness の_ ツールを前提にすることで、`pnpm josh` はどの harness にも存在するから、#2366 は合成コマンド `pnpm josh edit:files` を置いた（下節）。却下はそのまま有効で、答えはその外側にある。
+- **複数編集を 1 呼び出しにまとめるツールを前提にする。** 前提にできない。この repository が対象とする harness には常に存在するとは限らず、存在しない側では規則が一度も発火しない。`pnpm josh` はどの harness にも存在するので、書き込みは合成コマンド `pnpm josh edit:files` で畳む（下節）。経緯は `docs/maintainers/turn-batching-rationale.md` →「複数編集ツールの前提を joshuafolkken/kit#2366 が反証した経緯」。
 - **ターンごとに件数の下限を課す。** 却下。依存が連続する区間では 1 件が正しい答えであり、下限は正しい振る舞いを罰する。上限も下限も持たないのが正しく、**代わりに事後の計測を置く**（次節）。
 
-harness 側の一般的な指示（「依存のない呼び出しは同じブロックで出す」）は**すでに存在していて、実測では発火していなかった** — 4 本の run で 1 往復あたり 1.13 / 1.04 / 1.03 / 1.00 呼び出し。一般論だけでは動かないので、この文書は **判断基準を 1 問に固定し、守られていなかった具体形を名指しし、結果を数字で見えるようにする**という 3 点で置き換えている。`file-edits.md` が同じ 3 点で出力トークン側を動かしたのと同じ形である。
+harness 側の一般的な指示（「依存のない呼び出しは同じブロックで出す」）は**すでに存在していて、実測では発火していなかった** — 4 本の run で 1 往復あたり 1.13 / 1.04 / 1.03 / 1.00 呼び出し。帰結は `docs/maintainers/turn-batching-rationale.md` →「一般指示が発火しなかったことの帰結」。
 
 ## 事後の計測 — 実行タイミングレポートの `Round trips:`
 
@@ -86,26 +78,26 @@ Round trips:
 
 - **round trip は「1 ターンがまとめて出した呼び出しのかたまり」1 つ**であって、呼び出し 1 件ではない。まとめて出せば呼び出し数はそのままで往復だけが減る — つまりこの数字は、仕事を減らさずに費用だけ下げたかどうかを直接見せる
 - **しきい値は 1.50 呼び出し/往復。** 下回ると 1 行の指摘が出る。少しでもまとめている run は超えるので、これは程度を採点するのではなく**まとめていないこと**を検出する
-- **`tool-less turns` の行は、ツールを 1 つも呼ばなかったターン数**（`turn_count − round_trips`、joshuafolkken/kit#1875）。`batch:guard` は発話だけのターンを拒否できない — 呼ぶツールが無く `PreToolUse` が発火しないので、唯一の梃子がこの事後計測である。`Bundling:` はこれを構造上見られない（まとめる対象を持たないターンは列に入らない）。実測 run #1864 は 177 ターン中 149 が呼び出しあり、**28 がツールなし**だった
+- **`tool-less turns` の行は、ツールを 1 つも呼ばなかったターン数**（`turn_count − round_trips`、joshuafolkken/kit#1875）。`batch:guard` は発話だけのターンを拒否できない — 呼ぶツールが無く `PreToolUse` が発火しないので、唯一の梃子がこの事後計測である。`Bundling:` はこれを構造上見られない（まとめる対象を持たないターンは列に入らない）。発話だけのターンは自分で減らす（実測は `docs/maintainers/turn-batching-rationale.md` →「`tool-less turns` の実測」）
 - 実装は `scripts/time-runtime/time-round-trips.ts`、詳細は `docs/josh-commands.md` の `time` コマンドの項
 
 ## 実装中の独立編集に効く合成コマンド（joshuafolkken/kit#2202）
 
-**フックが届かない一区間が残っていた — レーン子の実装中の独立編集である。** `pnpm josh batch:guard`（拒否）は本流で密度を動かしたが、レーン子（headless `claude -p`）では拒否がターンを終わらせて子を殺すため発火できず（#2138）、代わりの通知も数字を動かさなかった（#2164）ので #2178 は子でガードを `off` にした。残ったのが、別々のファイルへ `Read` → `Edit` を交互に出す 9 ターンの並び（#2178 計測）で、編集集合が事前確定の定型でないため既存の合成コマンドでは畳めなかった。
+**フックが届かない一区間が残っていた — レーン子の実装中の独立編集である。** レーン子（headless `claude -p`）ではガードが `off` なので（#2178）、別々のファイルへ `Read` → `Edit` を交互に出す並びは誰にも止められない。経緯は `docs/maintainers/turn-batching-rationale.md` →「合成コマンドに至った経緯（joshuafolkken/kit#2202）」。
 
-**しかし 1 手前に確定している — Step 0 が変更ごとに対象ファイルを列挙する。** `pnpm josh read:files` はその点で読み取りを畳む合成コマンドである（密度を動かした実績があるのは合成コマンドだけ — #2165 / #2162 — で、助言・提示・通知はいずれも動かさなかった）。「もう一度言う」形ではなく、`report-format.md` が Step 0 の継ぎ目（`josh lines` の隣）でランをここへ導く**手順**である。
+**しかし 1 手前に確定している — Step 0 が変更ごとに対象ファイルを列挙する。** `pnpm josh read:files` はその点で読み取りを畳む合成コマンドである。`report-format.md` が Step 0 の継ぎ目（`josh lines` の隣）でランをここへ導く**手順**である。
 
 **梃子の本体は読み取りと編集の脱交互化（de-interleave）。** 交互の並びで編集を分けているのは直前の読み取りへの依存で、読み取りを 1 回に畳めば続く別ファイルへの編集は互いにも直前の読み取りにも依存せず 1 ターンに載る。#2178 の並び — `Read A` / `Edit A` / `Read B` / `Edit B` … の **9 ターン** — が、`read:files A B C D` → `Edit A` ＋ `Edit B` ＋ `Edit C` ＋ `Edit D` の **2 ターン**になる。
 
-**#2164 / #2178 の成果は後退しない** — バッチガードにもレーンガードポリシーにも触れないので、子は拒否で殺されず、効かない助言の毎ターンの文脈費用も払わない。上限超過時は `read:files` が「Read ツールで 1 ターンにまとめて読め」と返しフォールバックでも読み取りは畳まれたまま。詳細は `docs/josh-commands.md` →「`josh read:files`」。
+上限超過時は `read:files` が「Read ツールで 1 ターンにまとめて読め」と返しフォールバックでも読み取りは畳まれたまま。詳細は `docs/josh-commands-automation.md` →「`josh read:files`」。
 
-**編集自体を畳むコマンドは #2202 では置かず（native な複数編集を優先、上の却下案第 1 項）、joshuafolkken/kit#2366 がそれを置いた。** #2202 の「native に委ねる」判断は 230/230・密度 1.000 で反証済み。合成コマンドだけが密度を動かしたのと同じ理由で、書き込みは `pnpm josh edit:files` で畳む — 編集を **プラン（`=====` のパスヘッダ＋ git conflict マーカー対）** として受け取り 1 呼び出しで適用し、各編集は content-addressed なので `old` が 1 箇所に一致しなければ拒否して報告する。#2493 で `-`（標準入力）を受け、依存編集は `dependent` で拒否する。詳細は `docs/josh-commands.md` →「`josh edit:files`」。
+書き込みは `pnpm josh edit:files` で畳む（joshuafolkken/kit#2366） — 編集を **プラン（`=====` のパスヘッダ＋ git conflict マーカー対）** として受け取り 1 呼び出しで適用し、各編集は content-addressed なので `old` が 1 箇所に一致しなければ拒否して報告する。#2493 で `-`（標準入力）を受け、依存編集は `dependent` で拒否する。詳細は `docs/josh-commands-automation.md` →「`josh edit:files`」。
 
 ## ガード発火時にも合成コマンドを手渡す（joshuafolkken/kit#2311）
 
-**#2276 は通知に「直前に 1 件ずつ出した具体的な呼び出し」を名指しさせたが、密度は動かなかった（実測 1.084、ベースライン 1.147 を下回った）。** 名指しても通知は依然「1 ターンにまとめて出し直せ」と求めており、これはモデルが構造的に苦手とする並列 `tool_use` ブロックの要求である。梃子として実績があるのは合成コマンドだけ（上節・#2165 / #2162）なので、ガードが**単発の読み取り連続**で発火したとき、通知はその読み取りを畳む `pnpm josh read:files <path> …` を貼り付け可能な形で手渡す — モデルが 1 ターンで確実に出せる単一の呼び出しである。
+ガードが**単発の読み取り連続**で発火したとき、通知はその読み取りを畳む `pnpm josh read:files <path> …` を貼り付け可能な形で手渡す — モデルが 1 ターンで確実に出せる単一の呼び出しである。経緯は `docs/maintainers/turn-batching-rationale.md` →「ガード通知に合成コマンドを載せた経緯（joshuafolkken/kit#2311）」。
 
-**読み取りに限り、2 件以上のときだけ。** 書き込みは `read:files` の対象外なので除外し、読み取り 1 件は既に単発なので畳むものがない。実装は `scripts/time-runtime/time-batch-guard.ts` の `recent_candidates`（`read_fold_directive`）で、全通知配送が通る唯一の地点である。密度が計測されるのはレーン子（`notice` モード）なので、ここに合成コマンドを差し込むのが計測面に一致する。#2202 の Step 0 継ぎ目での畳み込みを、ガードが発火する実装中の一点へ広げたものであり、「もう一度言う」形の追加ではない。
+**読み取りに限り、2 件以上のときだけ。** 書き込みは `read:files` の対象外なので除外し、読み取り 1 件は既に単発なので畳むものがない。
 
 **書き込み側も同じ地点で手渡す（joshuafolkken/kit#2366）。** 単発 `Edit` の連続でガードが発火したとき、通知はその編集を名指し、それらのファイルにわたる `pnpm josh edit:files` の畳み込みを添える（`write_fold_directive`）。読み取りはパスだけで畳めるが編集は本文を伴うので、貼り付け可能なのはコマンドとファイル名までで、プラン本体はモデルが書く — それでも並列 `tool_use` ブロックではなく 1 ターンで出せる単一呼び出しに落ちる。`Edit` だけを数え、content-address できない `Write`（既に独自の通知を持つ）は除く。
 
@@ -113,7 +105,7 @@ Round trips:
 
 **この規則は常駐から外れている。** `pnpm josh batch:guard` が、単発呼び出しのターンが 3 つ続いた次の呼び出し（`Bash` / `Edit` / `Read`）を拒否し、そこで規則本文を突きつける — 規則が効く瞬間そのものである。配送の判定基準と機構は `rule-delivery.md` にある。
 
-**移設で失われた散文は、そもそも効いていなかった。** 上の「却下した案」の直後に記録したとおり、常駐の一般指示があった状態での実測は 1 往復あたり 1.13 / 1.04 / 1.03 / 1.00 呼び出しであり、常駐している間ずっと守られていなかった。数値を動かしたのは joshuafolkken/kit#1390 のフックである。したがって**常駐をやめても失われるのは「読み飛ばされていた文」だけ**で、実際に効いていた経路は残る。
+常駐から外した根拠は `docs/maintainers/turn-batching-rationale.md` →「常駐から外した根拠（joshuafolkken/kit#1524）」。
 
 **引き金が発火しないターンでは何も起きず、それが正しい。** 発火しないということは往復あたりの呼び出し数が下限（1.50）を上回っているということであり、規則が守られている状態と一致する。
 
@@ -122,16 +114,8 @@ Round trips:
 1. 別の呼び出しの結果に依存しない呼び出しは、同じターンに載せる
 2. 判断基準は「依存の有無」であって呼び出しの種類ではない（読み取りも編集も同じ）。かつ、往復を減らすことは仕事を減らすことではない
 
-実測値・却下した機構案・計測の読み方はこのファイルにあり、配送文からは落としている。
-
-**上の「却下した案」の第 1 項と矛盾しない。** あれが却下したのは「1 件の呼び出しだけを見て独立性を判定する」形であり、joshuafolkken/kit#1390 が実装したのは**閉じた履歴**（既に終わったターンの並び）から判定する形である。単発呼び出しのターンが 3 つ続いたことは 1 件の呼び出しからは見えないが、履歴からは見える。
+実測値・却下した機構案・計測の読み方はこのファイルと `docs/maintainers/turn-batching-rationale.md` にあり、配送文からは落としている。
 
 ## マーカーテスト
 
-`scripts/rules/turn-batching-rule.test.ts` が次を固定する。
-
-- 配送文が規則のトリガ文と判断基準の一文を運んでいること
-- 配送文の指し先が `CLAUDE.md` ではなくこのファイルであること（規則が常駐していない以上、`CLAUDE.md` を指す参照は何も指していない）
-- このファイルが判断基準・却下した機構案・ゲートを弱めない条件・計測の読み方を持っていること
-- 実測値（`600〜850`、`1.13`）が常駐側にも residency 一覧にも貼り戻されていないこと
-- 配送されている規則の一覧（`rule-delivery.md`）と residency の一覧（`.claude/skills/workflow-commands/SKILL.md` とこのディレクトリの `residency.md`）にこの規則が載っていること
+`scripts/rules/turn-batching-rule.test.ts` が固定する。内訳は `docs/maintainers/turn-batching-rationale.md` →「マーカーテストが固定するもの」。

package/prompts/collaboration-workflow/upstream-interrupt.md

@@ -16,7 +16,7 @@
 
 1. **現在の作業を退避する**: `git stash push -u -m "upstream-interrupt: paused #<N>"`（WIP コミットでも可）。退避したことを忘れないよう、この時点で stash を作る。メッセージ付きで積むのは、復元をメッセージで特定するため（下記ステップ 5）
 2. **進行中の Issue に状況を明記する**: `pnpm josh issue:comment <N> --body-file <path>` で、(a) 作業を stash したこと、(b) 中断理由（どの別パッケージの・どんな問題で中断したか）、(c) 対象パッケージに作成した新 Issue へのリンクを `## Upstream issues` 見出しの下に `owner/repo#N` 形式で、を記載する。これにより「なぜこの Issue が一時停止しているか」と「何を待っているのか」が後から監査できる（→「起票元へのバックリンク」）
-3. **対象パッケージのリポジトリに新しい Issue を作成する（確認なし）**: `pnpm josh issue:file "<root-cause title>" --body-file <body-file> --depth <n> --route tier-a --repo <owner>/<repo>`（`route:tier-a` は実装中の Tier A 起票を経路として集計するためのラベル — joshuafolkken/kit#1083。付与するのは first-party の場合だけで、third-party はコマンド自身が拒否し起票しない）。本文の検査、本文が宣言する分類ラベルの付与、`## Origin` 節の確認、起票先での重複探し、`epic:bundle` はこのコマンドが実行する（`docs/josh-commands.md` → `josh issue:file`）。分類の単一ソースは `prompts/collaboration-workflow/issue-template.md`。根本原因・再現・期待結果を Step 1 のテンプレに沿って記載し、**本文に `## Origin` 節を置いて起票元 Issue を `owner/repo#N` 形式で書く**（→「起票元へのバックリンク」）。上流 Issue は欠陥を、起票元 Issue は証拠を持つため、リンクがないと上流 Issue は後から解釈できなくなる。ここで「起票してよいか」を尋ねて停止してはならない。**ただし確認なしで起票してよいのは対象が first-party のときだけ**で、third-party（owner が自リポジトリと一致しないリポジトリ）なら起票せずに停止する（→「第三者リポジトリへの書き込みは Tier C（明示指示が必要）」）
+3. **対象パッケージのリポジトリに新しい Issue を作成する（確認なし）**: `pnpm josh issue:file "<root-cause title>" --body-file <body-file> --depth <n> --route tier-a --repo <owner>/<repo>`（`route:tier-a` は実装中の Tier A 起票を経路として集計するためのラベル — joshuafolkken/kit#1083。付与するのは first-party の場合だけで、third-party はコマンド自身が拒否し起票しない）。本文の検査、本文が宣言する分類ラベルの付与、`## Origin` 節の確認、起票先での重複探し、`epic:bundle` はこのコマンドが実行する（`docs/josh-commands-automation.md` → `josh issue:file`）。分類の単一ソースは `prompts/collaboration-workflow/issue-template.md`。根本原因・再現・期待結果を Step 1 のテンプレに沿って記載し、**本文に `## Origin` 節を置いて起票元 Issue を `owner/repo#N` 形式で書く**（→「起票元へのバックリンク」）。上流 Issue は欠陥を、起票元 Issue は証拠を持つため、リンクがないと上流 Issue は後から解釈できなくなる。ここで「起票してよいか」を尋ねて停止してはならない。**ただし確認なしで起票してよいのは対象が first-party のときだけ**で、third-party（owner が自リポジトリと一致しないリポジトリ）なら起票せずに停止する（→「第三者リポジトリへの書き込みは Tier C（明示指示が必要）」）
 4. **`confirmation` Telegram を送って停止する**: 上流 Issue の URL と、何が止まっているかを本文に書く（→ `CLAUDE.md` → "Mid-workflow stop notification (`confirmation`)"）。無人実行でも画面外でユーザーが気付ける。停止は Issue が既に存在する状態で行うので、ユーザーは「待つ / 先送りする」を Issue を見ながら 1 語で答えられる
 5. **元の作業を再開する**: 上流の修正がマージされた、または**ユーザーが先送りを明示判断した**後に `pnpm josh stash:pop "upstream-interrupt: paused #<N>"`（位置指定や引数なしの `git stash pop` は使わない — stash は全 work tree が共有する 1 本のスタックで、別のレーンの stash を取り込む恐れがある）して、退避していた元タスクを続行する。上流 Issue を割り込みで実装するかどうかもユーザーの判断（上流パッケージの実装・PR・マージはそれぞれのワークフロー規則に従う）
 

package/prompts/collaboration-workflow/wip-cap.md

@@ -1,12 +1,14 @@
-# オープン Issue の WIP 上限（30 件）
+# オープン Issue の WIP 上限
 
 **単一ソースはこのファイルである。**
 
-**この規則は常駐していない — 引き金つき配送に移った**（joshuafolkken/kit#1524）。`pnpm josh rule:guard` が Issue を作成する `Bash` 呼び出し（`pnpm josh issue:file`。`gh issue create` や `…/issues` への `title` 付き POST による直接起票は `direct-filing` が毎回拒否する）を拒否し、そこで数え方・拒否・2 つの免除・免除を決める 3 条件を突きつける。起票が無いターンでは何も起きず、それは上限に触れる行為が無いということである。配送は**ラン 1 回につき 1 度**なので、数えたうえで同じ呼び出しをもう一度出せばよい。機構と列挙表は `rule-delivery.md`、配送文の実体は `scripts/rules/delivered-rules.ts` の `WIP_CAP_REASON` にあり、`scripts/backlog/backlog-manufacturing-rule.test.ts` がその中身を固定している。
+**この規則は常駐していない — 引き金つき配送に移った**（joshuafolkken/kit#1524）。`pnpm josh rule:guard` が Issue を作成する `Bash` 呼び出し（`pnpm josh issue:file`。`gh issue create` や `…/issues` への `title` 付き POST による直接起票は `direct-filing` が毎回拒否する）を拒否し、そこで数え方・拒否・2 つの免除・免除を決める 3 条件を突きつける。起票が無いターンでは何も起きず、それは上限に触れる行為が無いということである。配送は**ラン 1 回につき 1 度**なので、数えたうえで同じ呼び出しをもう一度出せばよい。機構と列挙表は `rule-delivery.md`、配送文の実体は `scripts/rules/delivered-rules.ts` の `WIP_CAP_REASON` にある（固定するテストは `docs/maintainers/wip-cap-rationale.md` →「文言を固定しているテスト」）。
+
+背景・測定・経緯は保守者向けの `docs/maintainers/wip-cap-rationale.md` にあり、ラン中に読む必要はない。
 
 ## 規則
 
-**オープン Issue が 30 件を超えている状態で新しく起票するときは、先に 1 件閉じる。**
+**オープン Issue が上限を超えている状態で新しく起票するときは、先に 1 件閉じる。**
 
 件数は毎回数える。見積もりでも記憶でもない。
 
@@ -17,19 +19,19 @@ gh api "repos/{owner}/{repo}/issues?state=open&per_page=100" --paginate \
 
 - **数えるのは「起票しようとしているリポジトリ」のオープン Issue 全件**である。`{owner}/{repo}` はカレントリポジトリに展開されるので、**別リポジトリへ起票するときはそのリポジトリのパスを直接書く**（例: `repos/joshuafolkken/app-kit/issues?...`）。自リポジトリの件数で他リポジトリへの起票を判断するのは、別のバックログを見ているのと同じである。
 - epic も子も含める。epic を除外すると、epic を作ることで上限を回避できてしまう。
-- **上限は 30。** 31 件目以降を作る前に 1 件閉じる。
+- **上限は 30。** これを超える 1 件を作る前に 1 件閉じる。エージェントが読む文書（`CLAUDE.md`・`prompts/`・配布 skill）がこの数字を書くのはこの行だけで、一次情報は `scripts/rules/delivered-rules.ts` の `WIP_CAP` である（一致はテストが固定する）。
 - **プルリクエストは数えない。** REST の `issues` エンドポイントは PR も返すため、`select(.pull_request == null)` で落とす。この 1 句を省くと、PR が開いているだけで上限に達する。
-- **`gh issue list` は使わない。** 配布ドキュメントの実行可能ブロックに置ける `gh` は REST のものだけで、`gh issue list` は GraphQL 経由のためクラウドセッションで 403 になる（`scripts/gh/gh-document-guard.test.ts`）。
+- **`gh issue list` は使わない。** 配布ドキュメントの実行可能ブロックに置ける `gh` は REST のものだけで、`gh issue list` は GraphQL 経由のためクラウドセッションで 403 になる。
 
 ## なぜ上限が要るのか
 
-2026-09-06 までの 7 日間で起票 257 件・クローズ 163 件、**1 日あたり +13.4 件**。直近 14 日は 14 日すべてで起票がクローズを上回った。一方 `fullrun` は PR 作成からマージまで中央値およそ 10 分で、**処理速度は問題ではなかった**。到着側が処理側を上回り続けていたのであり、オープン件数に上限が無いため、その増加は誰にも見えないまま蓄積した。
+測定は `docs/maintainers/wip-cap-rationale.md` →「なぜ上限が要るのか — 測定」。
 
-**上限は、増加を見えるようにするための強制装置である。** 数を減らすこと自体が目的ではない。30 を超えた状態で起票しようとしたときに「本当にこれは 1 件増やす価値があるか」を必ず 1 回考えさせる、そこだけが役割である。
+**上限は、増加を見えるようにするための強制装置である。** 数を減らすこと自体が目的ではない。上限を超えた状態で起票しようとしたときに「本当にこれは 1 件増やす価値があるか」を必ず 1 回考えさせる、そこだけが役割である。
 
 ## 超過時の手順
 
-起票しようとした時点で 30 件を超えていたら、**その起票が裁量によるものか、実行がそれに詰まっているか、割り込みか**の 3 つに分岐する。判断ではなく、起票の種類で決まる。**上限が効くのは裁量側だけである。**
+起票しようとした時点で上限を超えていたら、**その起票が裁量によるものか、実行がそれに詰まっているか、割り込みか**の 3 つに分岐する。判断ではなく、起票の種類で決まる。**上限が効くのは裁量側だけである。**
 
 **判定するのは「起票 1 件」ではなく「起票のひとまとまり」である。** 分割判定が作る子 N 件とその epic、割り込み Issue とその上流バックリンク、起票直後の `epic:bundle` が `create_epic` と答えたときの epic — これらは 1 回の起票行為であり、途中で上限に当たって半分だけ作るのが最悪の結果になる。**ひとまとまりの先頭で 1 回だけ判定し、通ったらまとまり全体を作り切る。**
 
@@ -45,15 +47,15 @@ gh api "repos/{owner}/{repo}/issues?state=open&per_page=100" --paginate \
 
 前提 Issue（`SKILL.md` → §2d）、別パッケージ起因の割り込み Issue、ユーザーが `new` と打った入口、`issue:scout` が重複無しと答えた新規作業、**そして分割判定が作る子 Issue と epic**。**これらは起票しないと実行が進まない。**
 
-- **上限を理由に止めない。** 止めれば、製造を減らす規則が実行を止めることになり、Issue が言うとおり「今より悪い状態」になる。
-- **分割の子がここに入る理由**: 分割を検出した `fullrun` / `halfrun` は「子と epic を起票して **STOP**」と定められている（`fullrun.md` / `halfrun.md`）。起票を止めて 1 Issue のまま実装へ進むのは、その停止規則を破って 1 Issue 分の承認を N 件分に広げることであり、上限が防ぐはずだったものより重い。**分割するかどうかを決めるのは分割判定の側**で、既定はもう「分割しない」に上がっている — 上限が二重に効く必要はない。
+- **上限を理由に止めない。** 理由は `docs/maintainers/wip-cap-rationale.md` →「実行が詰まる起票を止めない理由」。
+- **分割の子がここに入る理由**: 分割を検出した `fullrun` / `halfrun` は「子と epic を起票して **STOP**」と定められている（`fullrun.md` / `halfrun.md`）。**分割するかどうかを決めるのは分割判定の側**で、既定はもう「分割しない」に上がっている — 上限が二重に効く必要はない。
 - **超過した事実は完了報告に 1 行書く**（例: 「オープン 34 件で起票した」）。上限は可視化のための装置なので、超えたことが見えていれば役割は果たしている。
 
 ### 割り込み起票 — 上限が効かない側（3 条件で機械的に決める）
 
-**重大な欠陥の発見は、それが現在のランを止めていなくても捨ててはならない。** joshuafolkken/kit#1517 は並列実行を成立させない欠陥だったが、発見した実行単位のランをその瞬間ブロックしてはいなかったため裁量側に落ち、**別 Issue のコメント本文の中にだけ**残った。利用者が偶然そのコメントを読まなければ失われていた。上限の目的は増加を見えるようにすることであって、**発見を捨てることではない**（上の「なぜ上限が要るのか」）。
+**重大な欠陥の発見は、それが現在のランを止めていなくても捨ててはならない。** 上限の目的は増加を見えるようにすることであって、**発見を捨てることではない**（上の「なぜ上限が要るのか」）。由来は `docs/maintainers/wip-cap-rationale.md` →「割り込み区分の由来 — joshuafolkken/kit#1517」。
 
-**別パッケージ起因の割り込みとは別の区分である。** あちらは上流リポジトリへ起票して停止する手順（`upstream-interrupt.md`、`route:tier-a`）で、実行が詰まる側に属する。ここで言う割り込みは、**このリポジトリの欠陥で、発見したランをブロックしていないもの**を指す。両者を同じものとして読んだことが joshuafolkken/kit#1517 を落とした経路そのものである。
+**別パッケージ起因の割り込みとは別の区分である。** あちらは上流リポジトリへ起票して停止する手順（`upstream-interrupt.md`、`route:tier-a`）で、実行が詰まる側に属する。ここで言う割り込みは、**このリポジトリの欠陥で、発見したランをブロックしていないもの**を指す。
 
 #### 3 条件 — 該当するかは判断ではない
 
@@ -65,54 +67,52 @@ gh api "repos/{owner}/{repo}/issues?state=open&per_page=100" --paginate \
 
 **3 つのいずれにも当たらない発見は、従来どおり裁量側の出口を取る。** 改善案、設計上の好み、未検証の疑い、「あとで直したい」はここに入らない — レビュー指摘なら branch 3（PR 本文に 1 行残して落とす）であり、それは既定の出口であって上限に阻まれたときの代替ではない。
 
-**深刻さの自己申告は条件ではない。** 「重大だと思う」を条件に加えた瞬間、割り込みは誰でも通れる抜け道になり、上限そのものが無意味になる。3 条件は、当たるか当たらないかを **他人が同じ答えに到達できる**形で書いてあり、そこが唯一の役割である。
+**深刻さの自己申告は条件ではない。** 理由は `docs/maintainers/wip-cap-rationale.md` →「深刻さの自己申告を条件にしない理由」。
 
 #### 該当したときの手順
 
-1. **上限に関係なく起票する。** 1 件閉じることを条件にしない。起票は `pnpm josh issue:file` で行う。本文の検査、本文が宣言する分類ラベルの付与、重複探し、`epic:bundle` はこのコマンドが実行する（`docs/josh-commands.md` → `josh issue:file`）。
+1. **上限に関係なく起票する。** 1 件閉じることを条件にしない。起票は `pnpm josh issue:file` で行う。本文の検査、本文が宣言する分類ラベルの付与、重複探し、`epic:bundle` はこのコマンドが実行する（`docs/josh-commands-automation.md` → `josh issue:file`）。
 
    ```bash
    pnpm josh issue:file "<title>" --body-file <body-file> --depth <n> --route interrupt
    ```
 
 2. **超過している事実と、当たった条件の番号を本文に 1 行書く**（例:「オープン 37 件で起票。3 条件のうち 2（文書化された手順が完了できない）に該当」）。**どちらか一方では足りない** — 件数だけでは判定が再現できず、条件だけでは上限の可視化が効かない。
-3. **次に実行されるものとして挿入する。** epic の下にあるなら `pnpm josh epic --add <E> <N>` で、**位置を指定せずに**追加する（`<E>` が epic、`<N>` が起票した割り込み）。**`--before` / `--after` を使ってはならない。** それらは `blocked-by` 関係を実際に書き込むため（`docs/josh-commands.md` →「`josh epic --add`」）、「発見したランをブロックしていない欠陥」という割り込みの定義と矛盾する**偽の依存関係**になり、`epic:next` が実装中の子を「割り込みにブロックされている」として出さなくなる。位置を指定しない追加は依存を一切宣言しない（joshuafolkken/kit#1253）ので、**順序は実行側が持つ** — 次に取り上げるのは実行側の選択であって、宣言された関係ではない（位置無し追加が依存を作らなくなったのは joshuafolkken/kit#1253 であり、`--after` の継ぎ足しなど残りの経路は joshuafolkken/kit#1080 で**まだ開いている** — 塞がった側を自分から迂回して、開いている側と同じ欠陥をここで作り直さないため）。**先に提示させたいときは `--order-before <M>` を使う**（joshuafolkken/kit#1738）— これはタスクリストの行だけを動かし、依存宣言も `blocked-by` も一切書かないので、上の禁止には当たらない。**禁止しているのは依存を書き込む `--before` / `--after` であって、順序そのものではない。** `epic:next` は runnable な子をタスクリスト順に提示する（joshuafolkken/kit#1583）ため、位置を指定しない追加は「末尾に提示される」を意味する — 割り込みを次に取り上げてほしいなら、行だけを前に出すこの指定がその手段である。**epic の下に無いなら挿入先そのものが無い**ので、この手順は飛ばして 4 だけを行う。
+3. **次に実行されるものとして挿入する。** epic の下にあるなら `pnpm josh epic --add <E> <N>` で、**位置を指定せずに**追加する（`<E>` が epic、`<N>` が起票した割り込み）。**`--before` / `--after` を使ってはならない。** それらは `blocked-by` 関係を実際に書き込むため（`docs/josh-commands-automation.md` →「`josh epic --add`」）、「発見したランをブロックしていない欠陥」という割り込みの定義と矛盾する**偽の依存関係**になり、`epic:next` が実装中の子を「割り込みにブロックされている」として出さなくなる。位置を指定しない追加は依存を一切宣言しない（joshuafolkken/kit#1253）ので、**順序は実行側が持つ** — 次に取り上げるのは実行側の選択であって、宣言された関係ではない（経緯は `docs/maintainers/wip-cap-rationale.md` →「位置を指定しない追加の経緯」）。**先に提示させたいときは `--order-before <M>` を使う**（joshuafolkken/kit#1738）— これはタスクリストの行だけを動かし、依存宣言も `blocked-by` も一切書かないので、上の禁止には当たらない。**禁止しているのは依存を書き込む `--before` / `--after` であって、順序そのものではない。** `epic:next` は runnable な子をタスクリスト順に提示する（joshuafolkken/kit#1583）ため、位置を指定しない追加は「末尾に提示される」を意味する — 割り込みを次に取り上げてほしいなら、行だけを前に出すこの指定がその手段である。**epic の下に無いなら挿入先そのものが無い**ので、この手順は飛ばして 4 だけを行う。
 4. **着手は、既にある承認の内側でのみ、指示を待たずに行う。** `backlogrun` の中なら、打たれたキーワードがバッチを承認しているので、割り込みは次の子として着手してよい。**バッチの外では `CLAUDE.md` →「Explicit invocation required」が変わらず効く** — 起票と挿入まで済ませたうえで、利用者に打つべきコマンド（`fullrun #<N>`）を報告して止まる。**割り込みは上限の例外であって、明示起動規則の例外ではない。**
 
 **起票と、実行されるようにするところまでが 1 つのまとまりである。** epic の下にある割り込みを起票だけして追加しなければ、`epic:next` はそれを候補にすら出さない — Issue は残るが実行されないという、コメントに埋もれるのと大差ない状態になる。**epic の外にある割り込みでは、まとまりの後半は 4 の報告そのもの**であり、打つべきコマンドを利用者に渡すまでが 1 回の行為である。上の「ひとまとまりで判定する」がここにも効く。
 
-#### 実行のしかた — 検証経路そのものの欠陥は単独で走らせる
-
-**割り込みの対象が検証経路そのものの欠陥であるとき、その Issue は単独で実行し、バッチを再開するのはそれが `main` へマージされてからとする。** 「着地」はマージであって、PR を開いた時点でもレビューが収束した時点でもない — 壊れた検証の上でバッチを回せないというのがこの節の前提なので、**修正が効き始めるのはマージの瞬間**だからである。
-
-**該当するかは判断ではなく、影響先の列挙で決まる。** 欠陥が次のいずれかに影響するか:
+#### 実行のしかた — `main` で誤答している検証の欠陥は単独で走らせる
 
-- **検証ゲート**（lint / 型チェック / スペルチェック / 単体テスト）
-- **コードレビュー**
-- **push 時のフック**
-- **マージ時のチェック**
+**kit 自身の検証が今の `main` で無関係な PR の判定まで誤らせている欠陥を直す Issue は単独で実行し、バッチを再開するのはそれが `main` へマージされてからとする。** 「着地」はマージであって、PR を開いた時点でもレビューが収束した時点でもない。
 
-**いずれかに当たれば単独実行。** その Issue に `run:solo` を付け、強制はそれを読む `backlog:next` と `epic:next --lanes` が行う（joshuafolkken/kit#2776）。当たらなければ（機能追加、文書修正など）`run:lane` を付け、並列バッチの一員として走らせてよい。どちらもなければ `triage` が返り何も始まらない（joshuafolkken/kit#2779）ので、run が起票する Issue（割り込み・分割・前提）は起票時にどちらかを付ける。**「重大だと感じるか」は判定条件ではない** — 3 条件と同じ理由で、深刻さの自己申告を条件に加えた瞬間、この区分も抜け道になる。
+**該当するかは判断ではなく、次の 3 条件で決まる。**
 
-**理由は 2 つあり、どちらか一方だけでも単独実行の根拠として十分である。**
+1. **欠陥である**（`- 種別: 不具合`）。改善・リファクタ・削除・機能追加は当たらない。
+2. **kit 自身の検証の欠陥である。** 検証とは次の 4 つを指し、配布先リポジトリ向けの CI・テンプレートの不具合は当たらない。
+   - **検証ゲート**（lint / 型チェック / スペルチェック / 単体テスト）
+   - **コードレビュー**
+   - **push 時のフック**
+   - **マージ時のチェック**
+3. **今の `main` で、その Issue と無関係な PR の判定まで誤らせている**（嘘の緑 / 嘘の赤）。効率の問題や、特定の条件でしか起きないものは当たらない。
 
-1. **壊れた検証の上でバッチを回すと、全員の結果が信用できない。** 6 レーンを並列で走らせれば、6 件分のゲートまたはレビューがまとめて無意味になる。直したあとに全部やり直すことになるので、単独実行は遅い選択ですらない。
-2. **割り込み自身の検証が、その割り込みが直そうとしている欠陥の影響下にある。** joshuafolkken/kit#1515（テストが実ネットワークを叩いていた）と joshuafolkken/kit#1517（同時実行のスイートが一時ディレクトリを共有していた）はどちらもこの自己言及の罠を抱えており、両者とも単独実行で扱った。
+**3 条件すべてに当たれば単独実行、1 つでも外れれば `run:lane`。** 単独実行なら `run:solo` を付け、強制はそれを読む `backlog:next` と `epic:next --lanes` が行う（joshuafolkken/kit#2776）。外れれば（改善、機能追加、文書修正、配布先 CI の修正など）`run:lane` を付け、並列バッチの一員として走らせてよい。どちらもなければ `triage` が返り何も始まらない（joshuafolkken/kit#2779）ので、run が起票する Issue（割り込み・分割・前提）は起票時にどちらかを付ける。**「重大だと感じるか」は判定条件ではない**（起票側の 3 条件と同じ理由）。
 
-**判定が揺れた実例がこの節の由来である。** joshuafolkken/kit#1522（レーンで走る子のレビューが、レーンではなくセッションのチェックアウトを読む）は #1515 / #1517 と同じ形なのに、起票直後は並列バッチの一員として扱われ、利用者の指摘で単独に戻された。同じ判断者が同じ週に逆の答えを出しており、**列挙が無ければ一貫しない**ことがそこで示された。しかも #1522 は嘘の赤ではなく**嘘の緑**を返す側で、より危険である。
+**他レーンを止める根拠は 1 つ — 壊れた検証の上でバッチを回すと、全員の結果が信用できないこと。** 割り込み自身の検証が欠陥の影響下にあることはその Issue 自身の扱い（修正後の検証で確かめる）であって、他レーンを止める根拠にはしない。根拠と、判定を条件にした由来・狭めた経緯は `docs/maintainers/wip-cap-rationale.md` →「単独実行の理由と由来」。
 
 ## 上限そのものを変えるとき
 
-**30 という数字は Tier C ではない** — 引き上げも引き下げも、測定を添えて提案してよい。ただし**変更は必ずこのファイルとマーカーテストの両方を同じコミットで動かす**。片方だけ動かすと、常駐側が存在しない数字を指す。
+**上限の数字は Tier C ではない** — 引き上げも引き下げも、測定を添えて提案してよい。ただし**変更は必ず `WIP_CAP` と「規則」節の 1 行を同じコミットで動かす**。片方だけ動かすと一致を固定するテストが落ちる。
 
 **引き上げる条件は「窮屈だから」ではない。** オープン件数が 7 日移動平均で減り続けていて、なお上限が起票を止めているとき — つまり装置が目的を果たし終えたときだけである。
 
 ## 3 つは一緒に動く
 
-上限は単独では効かない。**製造側を止めないまま上限だけ入れると、製造は続いたまま実行だけが止まる。** だから joshuafolkken/kit#1469 は 3 つを 1 コミットで着地させた。
+上限は単独では効かない。**製造側を止めないまま上限だけ入れると、製造は続いたまま実行だけが止まる。** 経緯は `docs/maintainers/wip-cap-rationale.md` →「3 つを 1 コミットで着地させた経緯」。
 
-| 製造元                    | 変更                                              | 単一ソース                                                              |
-| ------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------- |
-| 分割判定                  | 既定を「分割しない」に。目安 10 ファイル / 400 行 | `.claude/skills/workflow-commands/split-assessment.md` → "The question" |
-| レビュー round 2 の残指摘 | 既定を branch 3（PR に 1 行残して落とす）に       | `prompts/review.md` → "Three-way disposition after the cap"             |
-| オープン件数              | 30 件の WIP 上限                                  | このファイル                                                            |
+| 製造元                    | 変更                                           | 単一ソース                                                              |
+| ------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------- |
+| 分割判定                  | 既定を「分割しない」に。目安は単一ソースにある | `.claude/skills/workflow-commands/split-assessment.md` → "The question" |
+| レビュー round 2 の残指摘 | 既定を branch 3（PR に 1 行残して落とす）に    | `prompts/review.md` → "Three-way disposition after the cap"             |
+| オープン件数              | WIP 上限                                       | このファイル                                                            |

package/prompts/collaboration-workflow.md

@@ -2,11 +2,11 @@
 
 <!-- cspell:words coderabbit -->
 
-このドキュメントは、Claude / Cursor / Gemini を含む複数の AI ツールで共通に使う Issue 駆動の共同作業ワークフローの**正典**である。
+このドキュメントは、Claude / Cursor / Gemini を含む複数の AI ツールで共通に使う Issue 駆動の共同作業ワークフローの**索引**である。
 
 ## この索引の使い方
 
-**これは人間が読むための正典であり、実行中の参照先ではない。** 実行中の操作手順は `.claude/skills/workflow-commands/` にあり、規則そのものは `CLAUDE.md` にある。両者とこの正典は一致していなければならない。実行中にこの正典を開く必要があるのは、skill と規則の言い分が食い違ったときだけである。
+**これは人間が読むための索引であり、規則を定める場所ではない。** 常駐の引き金は `CLAUDE.md` に、実行中の操作手順は `.claude/skills/workflow-commands/` に、各話題の規則は下の表のファイルにあり、それぞれが自分の規則の一次情報である。この索引はそれらを言い直さない。
 
 **話題ごとにファイルが分かれている。** 以前はこの内容が 1 本の 169KB のファイルにあり、1 つの節を確かめるだけでも全体を読む必要があった。読んだものはそのセッションの残り全ターンで積み上がった前置きとして課金され続けるため、確認 1 回の費用が会話の長さに比例して効いていた（joshuafolkken/kit#965）。**必要な 1 本だけを開くこと。この索引を入口に、下の表から選ぶ。**
 
@@ -17,11 +17,8 @@
 | Step 2: 提案依頼（AI 共通）                                                                       | [`proposal-request.md`](./collaboration-workflow/proposal-request.md)     |
 | Step 3: 計画コメントを記録して通知する                                                            | [`plan-comment.md`](./collaboration-workflow/plan-comment.md)             |
 | 報告フォーマット（平易な概要 ＋ 技術詳細）                                                        | [`report-format.md`](./collaboration-workflow/report-format.md)           |
-| セッション向け出力で Issue はリンク＋短い日本語要約で参照する                                     | [`issue-citation.md`](./collaboration-workflow/issue-citation.md)         |
-| 後から関連が判明した Issue を epic に束ねる（本文は `epic-commands` skill）                       | [`epic-bundle.md`](./collaboration-workflow/epic-bundle.md)               |
-| オープン Issue の WIP 上限（30 件）                                                               | [`wip-cap.md`](./collaboration-workflow/wip-cap.md)                       |
-| リポジトリをまたぐ EPIC（本文は `epic-commands` skill）                                           | [`cross-repo-epic.md`](./collaboration-workflow/cross-repo-epic.md)       |
-| `josh epic:audit` — 子 Issue 群を横断して矛盾を検出する（本文は `epic-commands` skill）           | [`epic-audit.md`](./collaboration-workflow/epic-audit.md)                 |
+| セッション向け出力で Issue はリンク＋セッション言語の短い要約で参照する                           | [`issue-citation.md`](./collaboration-workflow/issue-citation.md)         |
+| オープン Issue の WIP 上限                                                                        | [`wip-cap.md`](./collaboration-workflow/wip-cap.md)                       |
 | 別パッケージ起因の問題は割り込み Issue で対応する                                                 | [`upstream-interrupt.md`](./collaboration-workflow/upstream-interrupt.md) |
 | 原則 — クローン禁止・シンプル第一・相談と実行の区別・最新優先・恒久ルールと配布物と規則の置き場所 | [`principles.md`](./collaboration-workflow/principles.md)                 |
 | ファイル編集はコマンド本文に本文を載せない                                                        | [`file-edits.md`](./collaboration-workflow/file-edits.md)                 |
@@ -37,7 +34,7 @@
 
 ## 参照の書き方
 
-`CLAUDE.md` と `.claude/skills/` からこの正典を指すときは、**本文があるファイルを直接指す**（話題ファイル、skill へ単一ソース化済みならその skill。[`residency.md`](./collaboration-workflow/residency.md)）。索引や指し先を経由させる形（`prompts/collaboration-workflow.md` → 「節名」）は、読み手に 2 回読みを強いるうえ、節名が変わると黙って行き止まりになる。
+`CLAUDE.md` と `.claude/skills/` からこれらの話題を指すときは、**本文があるファイルを直接指す**（話題ファイル、skill へ単一ソース化済みならその skill。[`residency.md`](./collaboration-workflow/residency.md)）。索引や指し先を経由させる形（`prompts/collaboration-workflow.md` → 「節名」）は、読み手に 2 回読みを強いるうえ、節名が変わると黙って行き止まりになる。
 
 ```md
 See `prompts/collaboration-workflow/upstream-interrupt.md`.

package/prompts/review-rubric.md

@@ -74,7 +74,7 @@ code changed, because returning none is what the instruction rules out. So a Med
 the second round even where the fixes were sufficient. The second round is narrowed to remove that.
 
 **What changes is the question, never the standard.** A confirmed High still blocks the merge
-whatever the round count, the cap is still two rounds, and every rule here applies to this pass
+whatever the round count, the cap in `prompts/review.md` → "Review round cap" still holds, and every rule here applies to this pass
 unchanged.
 
 |                | The first round      | The second round                                                                                                                                                               |

package/prompts/review.md

@@ -27,8 +27,8 @@ points to them rather than restating them:
 The workflow review uses the `reviewer` role profile printed by `pnpm josh review:brief`. Pass its
 model and effort explicitly to the review subagent; do not substitute the review level for effort.
 
-Re-run after applying fixes until **no high or medium findings remain — or until two reviews have run
-in total, the first included — whichever comes first.** The cap below is not optional. The second round
+Re-run after applying fixes until **no high or medium findings remain — or until the round cap below is
+reached, the first review included — whichever comes first.** The cap below is not optional. The second round
 is a verification pass over the fixes, not the first review again
 (`prompts/review-rubric.md` → "The second round is a verification pass, not a second full review").
 
@@ -197,7 +197,7 @@ Only branch 2 files an Issue. What follows applies to that branch.
   1. File the follow-up Issue referencing the current one, tagged `route:review-cap` — **before the current Issue closes.**
      `pnpm josh issue:file "<title>" --body-file <body-file> --depth <n> --route review-cap`.
      The command lints the body, applies the classification labels it declares, runs the duplicate scan
-     and then `epic:bundle` on the new Issue (`docs/josh-commands.md` → `josh issue:file`). The
+     and then `epic:bundle` on the new Issue (`docs/josh-commands-automation.md` → `josh issue:file`). The
      `epic:bundle` candidate search reads open issues only, so once the parent has closed it answers
      `none` permanently.
   2. Act on the `epic:bundle` answer it prints. **`epic:bundle` recommends and writes nothing**, so acting means running the

package/prompts/sonar-hotspot-handling.md

@@ -9,9 +9,13 @@ AI tools cannot perform OAuth browser login to SonarCloud, so this guide assumes
 ## Quality Gate enforcement (CI blocks PRs)
 
 The distributed `.github/workflows/sonar-qube.yml` runs the SonarCloud scan with
-`-Dsonar.qualitygate.wait=true`. The scanner waits for SonarCloud to evaluate the project's
-Quality Gate and **fails the `SonarQube` job — a required PR check — when the gate is red**, so a
-PR that introduces a finding cannot be merged green. This is the single enforcement point:
+`-Dsonar.qualitygate.wait=true`, so the `SonarQube` job — a required PR check — fails when the
+Quality Gate is red. **The gate alone is not enough**: `Sonar way` judges ratings and ratios, so a
+few MINOR code smells keep the maintainability rating at A and a small copied block stays under the
+duplication threshold. On a pull request the job therefore ends with `pnpm josh sonar:new-code <PR>`,
+which **fails on a single new issue of any type or severity, or a single new duplicated block**
+(joshuafolkken/kit#3045). An issue resolved in SonarCloud as accepted or a false positive is not
+counted — that resolution is the route for a deliberate exception. This job is the single enforcement point:
 `josh followup` does **not** scan SonarCloud findings (it only scans CodeRabbit / Claude Review
 comments), but it **does** wait on the required `SonarQube` CI check, so a red gate also blocks the
 `followup` merge. Consumers pick the workflow up verbatim via `josh sync`; do not re-implement the
@@ -25,6 +29,10 @@ run without the secret in the Dependabot store), so a repository that relies on
 
 ### New Code vs Overall Code semantics
 
+The scan passes `package.json`'s `version` as `sonar.projectVersion`, so New Code — "since the
+previous version" — restarts at every `josh bump` that reaches main instead of growing from the
+first analysis on.
+
 SonarCloud's default **Sonar way** Quality Gate evaluates **New Code only** — conditions
 (new bugs, new code smells above the Maintainability rating, new coverage/duplication) apply to
 lines changed in the PR's New Code period, not the whole codebase. Consequences:
@@ -42,7 +50,7 @@ per the table below, and do not let it silently block an unrelated change).
 ## Step A / Step B: fetch the hotspots and read each one's disposition
 
 ```bash
-pnpm josh sonar:hotspots <PR>   # alias: josh shs
+pnpm josh sonar:hotspots <PR>
 ```
 
 The command fetches the hotspots on the pull request from SonarCloud's public API (no auth), reading

package/prompts/testing-guide.md

@@ -264,9 +264,9 @@ a repository whose CI reports no `E2E` context at all resolves the required entr
 which is never `pass`, so the evaluation stays `pending` until the 32-minute wait times out with
 nothing actually wrong. What guarantees the job runs is the detection rule above, not the required
 list. A project that wants it required opts in through `JOSH_REQUIRED_CHECKS`, which
-`scripts/git/git-pr-checks-eval.test.ts` covers; the decision itself — `E2E` off the default list,
+`scripts/gh/git-pr-checks-eval.test.ts` covers; the decision itself — `E2E` off the default list,
 and a repository reporting no `E2E` check still mergeable — is pinned in
-`scripts/git/git-pr-checks-e2e-gate.test.ts`.
+`scripts/gh/git-pr-checks-e2e-gate.test.ts`.
 
 **A red E2E is reported as soon as it goes red, and by name.** `E2E` is not on the required list, so
 until joshuafolkken/kit#990 nothing ended the wait when it failed: the rollup read as pending,
@@ -275,4 +275,4 @@ to complete.` — a message naming neither the job nor the cause. Any failing ch
 on the poll that sees it, and the error names it (`PR checks failed (failed checks: E2E).`).
 The poll loop keeps CodeRabbit exempt under the temporary kit#753 policy. **This is a change to how fast the gate
 reports, never to what it lets through** — no failing check gained a path to `success`, which
-`scripts/git/git-pr-checks-e2e-gate.test.ts` continues to assert.
+`scripts/gh/git-pr-checks-e2e-gate.test.ts` continues to assert.

package/scripts/adopt/adopt-toolkits.ts

@@ -167,13 +167,13 @@ const adopt_toolkits = {
 	TOOLKIT_SCOPE,
 	LATEST_VERSION,
 	is_toolkit_package,
-	compare_toolkits,
 	declared_toolkits,
 	misplaced_toolkits,
 	pick_bin_name,
+	bin_name_of,
 	read_bin_name,
+	all_declared_toolkits,
 	is_unreachable_toolkit,
-	resolve_toolkit,
 	discover_toolkits,
 	unresolved_toolkits,
 }

package/scripts/adopt/adopt.ts

@@ -156,13 +156,11 @@ function main(argv: ReadonlyArray<string>): void {
 }
 
 const adopt = {
-	DRY_RUN_REASON,
 	KNOWN_FLAGS,
 	NOTHING_TO_ADOPT,
 	parse_options,
 	run_here,
 	run,
-	main,
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))

package/scripts/agent/agent-argv.ts

@@ -126,8 +126,6 @@ function resolve_in(
 }
 
 const agent_argv = {
-	build,
-	build_resume,
 	resolve,
 	resolve_in,
 	resume_argv,

package/scripts/agent/agent-diagnostics.ts

@@ -115,7 +115,7 @@ function check(profile: AgentProfile, ports: DiagnosticPorts = default_ports): D
 	return check_auth(cli, ports)
 }
 
-const agent_diagnostics = { AUTH_ARGS, MODEL_CLI_FLOORS, PROVIDER_CLI_TABLE, VERSION_ARGS, check }
+const agent_diagnostics = { check }
 
 export type { DiagnosticPorts, DiagnosticResult, ProcessOutcome }
 export { agent_diagnostics }

package/scripts/agent/agent-role-profile.ts

@@ -302,17 +302,11 @@ function parse(value: unknown): AgentProfile | undefined {
 
 const agent_role_profile = {
 	DEFAULT_PROFILES,
-	EFFORT_SCHEMA,
-	ENV_KEYS,
 	HANDED_PROVIDER_KEY,
 	IMPLEMENTATION_PHASE,
-	LEGACY_WORKER_KEYS,
 	MAX_VALUE_LENGTH,
 	OPENAI_PROFILES,
-	PHASE_EFFORT,
-	PHASE_SCHEMA,
 	PRE_GATE_PHASE,
-	PROVIDER_SCHEMA,
 	PROFILE_SCHEMA,
 	REVIEWER,
 	SCHEDULER,
@@ -322,7 +316,6 @@ const agent_role_profile = {
 	has_completion_callback,
 	is_safe_value,
 	parse,
-	phase_effort,
 	resolve,
 	resolve_provider,
 	with_phase_effort,

package/scripts/agent/claude-agent-argv.ts

@@ -143,8 +143,6 @@ const claude_agent_argv = {
 	build,
 	build_resume,
 	resolve,
-	tool_flags,
-	with_profile,
 }
 
 export type { ClaudeArgv, ClaudeArgvResult }

package/scripts/agent/codex-agent-argv.ts

@@ -88,7 +88,7 @@ function build(invocation: string, profile: AgentProfile, cwd?: string): CodexAr
 	}
 }
 
-const codex_agent_argv = { AGENT_COMMAND, AGENT_FLAGS, build }
+const codex_agent_argv = { build }
 
 export type { CodexArgv }
 export { codex_agent_argv }