@joshuafolkken/kit 1.1010.0 → 1.1050.0

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

@@ -2,7 +2,9 @@
 
 **単一ソースはこのファイルである。**
 
-**この規則は常駐していない — 引き金つき配送に移った**（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` にあり、ラン中に読む必要はない。
 
 ## 規則
 
@@ -19,11 +21,11 @@ gh api "repos/{owner}/{repo}/issues?state=open&per_page=100" --paginate \
 - epic も子も含める。epic を除外すると、epic を作ることで上限を回避できてしまう。
 - **上限は 30。** 31 件目以降を作る前に 1 件閉じる。
 - **プルリクエストは数えない。** 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 回考えさせる、そこだけが役割である。
 
@@ -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,7 +67,7 @@ gh api "repos/{owner}/{repo}/issues?state=open&per_page=100" --paginate \
 
 **3 つのいずれにも当たらない発見は、従来どおり裁量側の出口を取る。** 改善案、設計上の好み、未検証の疑い、「あとで直したい」はここに入らない — レビュー指摘なら branch 3（PR 本文に 1 行残して落とす）であり、それは既定の出口であって上限に阻まれたときの代替ではない。
 
-**深刻さの自己申告は条件ではない。** 「重大だと思う」を条件に加えた瞬間、割り込みは誰でも通れる抜け道になり、上限そのものが無意味になる。3 条件は、当たるか当たらないかを **他人が同じ答えに到達できる**形で書いてあり、そこが唯一の役割である。
+**深刻さの自己申告は条件ではない。** 理由は `docs/maintainers/wip-cap-rationale.md` →「深刻さの自己申告を条件にしない理由」。
 
 #### 該当したときの手順
 
@@ -76,14 +78,14 @@ gh api "repos/{owner}/{repo}/issues?state=open&per_page=100" --paginate \
    ```
 
 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.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 を開いた時点でもレビューが収束した時点でもない — 壊れた検証の上でバッチを回せないというのがこの節の前提なので、**修正が効き始めるのはマージの瞬間**だからである。
+**割り込みの対象が検証経路そのものの欠陥であるとき、その Issue は単独で実行し、バッチを再開するのはそれが `main` へマージされてからとする。** 「着地」はマージであって、PR を開いた時点でもレビューが収束した時点でもない。
 
 **該当するかは判断ではなく、影響先の列挙で決まる。** 欠陥が次のいずれかに影響するか:
 
@@ -92,14 +94,9 @@ gh api "repos/{owner}/{repo}/issues?state=open&per_page=100" --paginate \
 - **push 時のフック**
 - **マージ時のチェック**
 
-**いずれかに当たれば単独実行。** その Issue に `run:solo` を付け、強制はそれを読む `backlog:next` と `epic:next --lanes` が行う（joshuafolkken/kit#2776）。当たらなければ（機能追加、文書修正など）`run:lane` を付け、並列バッチの一員として走らせてよい。どちらもなければ `triage` が返り何も始まらない（joshuafolkken/kit#2779）ので、run が起票する Issue（割り込み・分割・前提）は起票時にどちらかを付ける。**「重大だと感じるか」は判定条件ではない** — 3 条件と同じ理由で、深刻さの自己申告を条件に加えた瞬間、この区分も抜け道になる。
-
-**理由は 2 つあり、どちらか一方だけでも単独実行の根拠として十分である。**
-
-1. **壊れた検証の上でバッチを回すと、全員の結果が信用できない。** 6 レーンを並列で走らせれば、6 件分のゲートまたはレビューがまとめて無意味になる。直したあとに全部やり直すことになるので、単独実行は遅い選択ですらない。
-2. **割り込み自身の検証が、その割り込みが直そうとしている欠陥の影響下にある。** joshuafolkken/kit#1515（テストが実ネットワークを叩いていた）と joshuafolkken/kit#1517（同時実行のスイートが一時ディレクトリを共有していた）はどちらもこの自己言及の罠を抱えており、両者とも単独実行で扱った。
+**いずれかに当たれば単独実行。** その Issue に `run:solo` を付け、強制はそれを読む `backlog:next` と `epic:next --lanes` が行う（joshuafolkken/kit#2776）。当たらなければ（機能追加、文書修正など）`run:lane` を付け、並列バッチの一員として走らせてよい。どちらもなければ `triage` が返り何も始まらない（joshuafolkken/kit#2779）ので、run が起票する Issue（割り込み・分割・前提）は起票時にどちらかを付ける。**「重大だと感じるか」は判定条件ではない**（3 条件と同じ理由）。
 
-**判定が揺れた実例がこの節の由来である。** joshuafolkken/kit#1522（レーンで走る子のレビューが、レーンではなくセッションのチェックアウトを読む）は #1515 / #1517 と同じ形なのに、起票直後は並列バッチの一員として扱われ、利用者の指摘で単独に戻された。同じ判断者が同じ週に逆の答えを出しており、**列挙が無ければ一貫しない**ことがそこで示された。しかも #1522 は嘘の赤ではなく**嘘の緑**を返す側で、より危険である。
+**理由は 2 つあり、どちらか一方だけでも単独実行の根拠として十分である。** その 2 つと、判定を列挙にした由来は `docs/maintainers/wip-cap-rationale.md` →「単独実行の理由と由来」。
 
 ## 上限そのものを変えるとき
 
@@ -109,7 +106,7 @@ gh api "repos/{owner}/{repo}/issues?state=open&per_page=100" --paginate \
 
 ## 3 つは一緒に動く
 
-上限は単独では効かない。**製造側を止めないまま上限だけ入れると、製造は続いたまま実行だけが止まる。** だから joshuafolkken/kit#1469 は 3 つを 1 コミットで着地させた。
+上限は単独では効かない。**製造側を止めないまま上限だけ入れると、製造は続いたまま実行だけが止まる。** 経緯は `docs/maintainers/wip-cap-rationale.md` →「3 つを 1 コミットで着地させた経緯」。
 
 | 製造元                    | 変更                                              | 単一ソース                                                              |
 | ------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------- |

package/prompts/collaboration-workflow.md

@@ -10,34 +10,28 @@
 
 **話題ごとにファイルが分かれている。** 以前はこの内容が 1 本の 169KB のファイルにあり、1 つの節を確かめるだけでも全体を読む必要があった。読んだものはそのセッションの残り全ターンで積み上がった前置きとして課金され続けるため、確認 1 回の費用が会話の長さに比例して効いていた（joshuafolkken/kit#965）。**必要な 1 本だけを開くこと。この索引を入口に、下の表から選ぶ。**
 
-| 話題                                                                           | ファイル                                                                                |
-| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
-| Overview                                                                       | [`overview.md`](./collaboration-workflow/overview.md)                                   |
-| Step 1: Issue 作成テンプレ                                                     | [`issue-template.md`](./collaboration-workflow/issue-template.md)                       |
-| 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-bundle.md`](./collaboration-workflow/epic-bundle.md)                             |
-| オープン Issue の WIP 上限（30 件）                                            | [`wip-cap.md`](./collaboration-workflow/wip-cap.md)                                     |
-| リポジトリをまたぐ EPIC                                                        | [`cross-repo-epic.md`](./collaboration-workflow/cross-repo-epic.md)                     |
-| `josh epic:audit` — 子 Issue 群を横断して矛盾を検出する                        | [`epic-audit.md`](./collaboration-workflow/epic-audit.md)                               |
-| 別パッケージ起因の問題は割り込み Issue で対応する                              | [`upstream-interrupt.md`](./collaboration-workflow/upstream-interrupt.md)               |
-| クローン禁止・単一ソース化（パッケージ境界を越えても）                         | [`no-clones.md`](./collaboration-workflow/no-clones.md)                                 |
-| 設計はエレガント・シンプルを第一目標にする（仕組みを足す前に原因を問う）       | [`simplicity-first.md`](./collaboration-workflow/simplicity-first.md)                   |
-| 相談と実行を区別する（議論中にファイルを編集しない）                           | [`consultation-vs-execution.md`](./collaboration-workflow/consultation-vs-execution.md) |
-| 配布ドキュメント・設定の変更は kit に上流化する                                | [`distributed-docs.md`](./collaboration-workflow/distributed-docs.md)                   |
-| エージェント規則の単一ソースは `CLAUDE.md`（`AGENTS.md` / `GEMINI.md` は導線） | [`single-source-rules.md`](./collaboration-workflow/single-source-rules.md)             |
-| 最新優先・fix-forward（pin-back は最終手段）                                   | [`latest-first.md`](./collaboration-workflow/latest-first.md)                           |
-| 恒久ルールは MEMORY ではなくプロンプト／ドキュメントに書く                     | [`durable-rules.md`](./collaboration-workflow/durable-rules.md)                         |
-| ファイル編集はコマンド本文に本文を載せない                                     | [`file-edits.md`](./collaboration-workflow/file-edits.md)                               |
-| 本文をシェルの二重引用符に載せない                                             | [`shell-body.md`](./collaboration-workflow/shell-body.md)                               |
-| 独立した呼び出しは同じターンに載せる                                           | [`turn-batching.md`](./collaboration-workflow/turn-batching.md)                         |
-| `gh` は REST（`gh api`）で書く — 散文の指示も含む                              | [`gh-rest.md`](./collaboration-workflow/gh-rest.md)                                     |
-| 常駐ドキュメントと skill の分担（何を常駐に残すか）                            | [`residency.md`](./collaboration-workflow/residency.md)                                 |
-| 引き金つき配送 — 規則を効く瞬間に届ける                                        | [`rule-delivery.md`](./collaboration-workflow/rule-delivery.md)                         |
-| コマンド出力が文脈へ持ち込む量の上限                                           | [`output-bounds.md`](./collaboration-workflow/output-bounds.md)                         |
-| 運用ルール                                                                     | [`operating-rules.md`](./collaboration-workflow/operating-rules.md)                     |
+| 話題                                                                                              | ファイル                                                                  |
+| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| Overview                                                                                          | [`overview.md`](./collaboration-workflow/overview.md)                     |
+| Step 1: Issue 作成テンプレ                                                                        | [`issue-template.md`](./collaboration-workflow/issue-template.md)         |
+| 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 で対応する                                                 | [`upstream-interrupt.md`](./collaboration-workflow/upstream-interrupt.md) |
+| 原則 — クローン禁止・シンプル第一・相談と実行の区別・最新優先・恒久ルールと配布物と規則の置き場所 | [`principles.md`](./collaboration-workflow/principles.md)                 |
+| ファイル編集はコマンド本文に本文を載せない                                                        | [`file-edits.md`](./collaboration-workflow/file-edits.md)                 |
+| 本文をシェルの二重引用符に載せない                                                                | [`shell-body.md`](./collaboration-workflow/shell-body.md)                 |
+| 独立した呼び出しは同じターンに載せる                                                              | [`turn-batching.md`](./collaboration-workflow/turn-batching.md)           |
+| `gh` は REST（`gh api`）で書く — 散文の指示も含む                                                 | [`gh-rest.md`](./collaboration-workflow/gh-rest.md)                       |
+| 常駐ドキュメントと skill の分担（何を常駐に残すか）                                               | [`residency.md`](./collaboration-workflow/residency.md)                   |
+| 引き金つき配送 — 規則を効く瞬間に届ける                                                           | [`rule-delivery.md`](./collaboration-workflow/rule-delivery.md)           |
+| コマンド出力が文脈へ持ち込む量の上限                                                              | [`output-bounds.md`](./collaboration-workflow/output-bounds.md)           |
+| 運用ルール                                                                                        | [`operating-rules.md`](./collaboration-workflow/operating-rules.md)       |
 
 **どの 1 本を開けばよいかを決めるのに必要なのは、この索引だけである。** バイト数はここに書かない — 手で保守した数字は本文より先に古くなり、古い数字は無いより悪い。実サイズは `ls -l prompts/collaboration-workflow/` が答える。
 

package/prompts/sonar-hotspot-handling.md

@@ -42,7 +42,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/scripts/adopt/adopt-logic.ts

@@ -12,7 +12,7 @@ const ADOPT_ORIGIN = 'Opened by `josh adopt` in this repository.'
 const INCOMPLETE_HEADLINE =
 	'Refusing to adopt: these declared toolkits would fall out of the plan, and the run would sync the rest without them.'
 const INCOMPLETE_EFFECT =
-	"The toolkits overlay files derived from kit's own (see docs/sync.md), so syncing kit without one rewrites that overlay back to kit's original — a wrong diff wearing kit's face."
+	"The toolkits overlay files derived from kit's own (see docs/maintainers/sync-rationale.md), so syncing kit without one rewrites that overlay back to kit's original — a wrong diff wearing kit's face."
 const MISPLACED_CAUSE =
 	'declared under `dependencies`; the upgrade installs with `pnpm add -D` and would relocate it. Move it to `devDependencies`.'
 const ABSENT_CAUSE =
@@ -60,7 +60,7 @@ function name_causes(package_names: ReadonlyArray<string>, cause: string): Array
 
 // A declared toolkit that falls out of the plan is a refusal rather than a warning
 // (joshuafolkken/kit#1540). kit distributes the base files and every other toolkit overlays files
-// *derived* from them (`docs/sync.md` → two distribution tiers), so a run that syncs kit without the
+// *derived* from them (`docs/maintainers/sync-rationale.md` → "The managed-workflow stamp"), so a run that syncs kit without the
 // overlay does not merely do less — it writes the overlay's paths back to kit's originals. That diff
 // then wears kit's own face in the pull request, which is exactly what a reviewer cannot spot.
 //

package/scripts/adopt/adopt-toolkits.ts

@@ -32,7 +32,7 @@ function is_toolkit_package(package_name: string): boolean {
 
 // kit is the base tier and every other toolkit distributes files *derived* from kit's, so the two
 // can manage the same path and whichever `sync` ran last decides its contents
-// (`docs/sync.md` → "two distribution tiers"). Ordering is therefore base-first: kit syncs, then the
+// (`docs/maintainers/sync-rationale.md` → "The managed-workflow stamp"). Ordering is therefore base-first: kit syncs, then the
 // toolkits that overlay it. Sorting by name would put kit last and have it overwrite the overlay
 // with the original every single run.
 function toolkit_rank(package_name: string): number {
@@ -171,7 +171,9 @@ const adopt_toolkits = {
 	declared_toolkits,
 	misplaced_toolkits,
 	pick_bin_name,
+	bin_name_of,
 	read_bin_name,
+	all_declared_toolkits,
 	is_unreachable_toolkit,
 	resolve_toolkit,
 	discover_toolkits,

package/scripts/adopt/adopt.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
-import { refuse_unknown_flags } from '#scripts/lib/cli-flags'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { propagate_run, type TargetResult } from '#scripts/propagate/propagate-run'
 import { propagate_steps, type Release, type ReleasePlan } from '#scripts/propagate/propagate-steps'
 import type { PropagateTarget } from '#scripts/propagate/propagate-targets'
@@ -40,7 +40,7 @@ interface RunOptions {
 
 function parse_options(argv: ReadonlyArray<string>): RunOptions {
 	const options: RunOptions = { is_dry_run: argv.includes(DRY_RUN_FLAG) }
-	const usage = refuse_unknown_flags(argv, KNOWN_FLAGS, 'adopt')
+	const usage = cli_flags.refuse_unknown_flags(argv, KNOWN_FLAGS, 'adopt')
 
 	return usage === undefined ? options : { ...options, usage }
 }

package/scripts/agent/agent-event.ts

@@ -1,3 +1,4 @@
+import { json_value } from '#scripts/lib/json-value'
 import { z } from 'zod'
 import type { AgentProvider } from './agent-role-profile'
 import { claude_result_event } from './claude-result-event'
@@ -53,14 +54,6 @@ const EMPTY_STATE: AgentEventState = {
 const LAUNCH_HEADER_PREFIX = '=== '
 const LAUNCH_HEADER_MARKER = ' · started by process '
 
-function parse_line(line: string): unknown {
-	try {
-		return JSON.parse(line)
-	} catch {
-		return undefined
-	}
-}
-
 function usable_text(value: unknown): string | undefined {
 	return typeof value === 'string' && value.trim() !== '' ? value : undefined
 }
@@ -149,7 +142,7 @@ function next_state(line: string, state: AgentEventState): AgentEventState {
 	const is_header = line.startsWith(LAUNCH_HEADER_PREFIX) && line.includes(LAUNCH_HEADER_MARKER)
 	if (is_header) return EMPTY_STATE
 
-	return normalized(parse_line(line), state)
+	return normalized(json_value.parse_or_undefined(line), state)
 }
 
 function read(transcript: string): AgentEventState {

package/scripts/agent/agent-exit-record.ts

@@ -1,3 +1,4 @@
+import { json_value } from '#scripts/lib/json-value'
 import { claude_result_event, type ClaudeResultEvent } from './claude-result-event'
 
 // The exit record of a dispatched lane child — the terminal `result` event a `claude -p` session
@@ -12,18 +13,10 @@ import { claude_result_event, type ClaudeResultEvent } from './claude-result-eve
 // over; a transcript with no result event at all reads as `undefined`, which the classifier treats as
 // an unreadable ending rather than guessing one.
 
-function parse_line(line: string): unknown {
-	try {
-		return JSON.parse(line)
-	} catch {
-		return undefined
-	}
-}
-
 function read_exit_record(transcript: string): ClaudeResultEvent | undefined {
 	return transcript
 		.split('\n')
-		.map((line) => claude_result_event.decode(parse_line(line)))
+		.map((line) => claude_result_event.decode(json_value.parse_or_undefined(line)))
 		.findLast((record) => record !== undefined)
 }
 

package/scripts/auto-ok/auto-ok-cli.ts

@@ -310,9 +310,8 @@ async function fetch_tracking(count: number): Promise<TrackingRead> {
 	}
 }
 
-// The pickup *order* is `git_next_issues.prioritize` itself, not a copy of it: newest first, with the
-// `epic` / `in-progress` / `needs-decision` exclusions. Its display cap does not reach this caller,
-// which reads only the first row.
+// The pickup *order* is `git_next_issues.order` itself, not a copy of it: the ranking `prioritize`
+// shows, with the `epic` / `in-progress` / `needs-decision` exclusions, before its display cap.
 //
 // The two are no longer the same *set*, and deliberately so: since joshuafolkken/kit#996 the pickup
 // also drops a candidate whose prerequisite is still open, while `🗒 Next issues` shows every open
@@ -323,9 +322,12 @@ async function fetch_tracking(count: number): Promise<TrackingRead> {
 // Membership of the label is the *query's* job, not this function's: `--label` is what makes the
 // listing the opted-in set, so re-testing it here would be a second definition of opting in.
 //
-// The exclusions are applied **before** `prioritize`, not after: it keeps only its first few rows,
-// so filtering its output would answer `none` whenever those rows happen to be blocked while a
-// runnable issue sits below them.
+// The exclusions are applied to `git_next_issues.order`'s **uncapped** ranking, never to
+// `prioritize`'s capped one, which would answer `none` whenever its first rows happen to be blocked
+// while a runnable issue sits below them. They are applied **after** the ranking, not before it: the
+// dependents key counts the issues waiting on a row, and a waiting issue is by definition blocked —
+// filtered first, every row would count zero and the key would never decide anything
+// (joshuafolkken/kit#2928).
 //
 // The `🗒 Next issues` display is deliberately *not* filtered this way; `git-next-issues.ts` records
 // why, and the short version is that a person can see a blocked issue and choose to start it anyway
@@ -354,9 +356,7 @@ function pick_next(
 	tracked: ReadonlyMap<number, number> = new Map(),
 	exclude: ReadonlyArray<number> = [],
 ): OpenIssueData | undefined {
-	const runnable = issues.filter((issue) => is_runnable(issue, tracked, exclude))
-
-	return git_next_issues.prioritize(runnable)[0]
+	return git_next_issues.order(issues).find((issue) => is_runnable(issue, tracked, exclude))
 }
 
 // Why there is nothing to run. "No open issue carries the label" and "every opted-in issue is

package/scripts/backlog/backlog-budget-cli.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
 import { path_decision } from '#scripts/josh/path-decision'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { backlog_budget, type BacklogAnswer, type BudgetInput } from './backlog-budget'
 
 // The thin half of `josh backlog:budget` (joshuafolkken/kit#1632): read the loop's state off the
@@ -32,11 +32,7 @@ type ParsedValues = Partial<Record<OptionName, string | boolean>>
 // A misspelled flag is refused rather than defaulted, the contract `path_decision.has_unknown_flag`
 // states for the path-decided commands: an invocation nobody can read is never answered.
 function read_arguments(argv: ReadonlyArray<string>): ParsedValues | undefined {
-	try {
-		return parseArgs({ args: [...argv], options: OPTIONS, strict: true }).values
-	} catch {
-		return undefined
-	}
+	return cli_flags.parse_or_undefined({ args: [...argv], options: OPTIONS, strict: true })?.values
 }
 
 function text_of(value: string | boolean | undefined): string | undefined {

package/scripts/backlog/backlog-drive-cli.ts

@@ -1,13 +1,14 @@
 #!/usr/bin/env tsx
 import { setTimeout as sleep } from 'node:timers/promises'
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
 import { CONTEXT_CUT_THRESHOLD } from '#scripts/cost-runtime/context-cut-threshold'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { josh_command } from '#scripts/josh/josh-run'
 import { lane_await, type AwaitState } from '#scripts/lane/lane-await'
 import { lane_launch_cli } from '#scripts/lane/lane-launch-cli'
 import { lane_registry } from '#scripts/lane/lane-registry'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { error_text } from '#scripts/lib/error-message'
 import { run_carry, type RunCarry } from '#scripts/run/run-carry'
 import { run_event_stream_emit } from '#scripts/run/run-event-stream-emit'
 import { run_merge_cli } from '#scripts/run/run-merge-cli'
@@ -49,7 +50,7 @@ const LIST_SEPARATOR = ','
 const COUNT_PATTERN = /^\d+$/u
 const ISSUE_PATTERN = /^[1-9]\d*$/u
 const USAGE =
-	'Usage: josh backlog:drive --owner <pid> [--active <ISO-8601>] [--max <n>] [--idle <minutes>] [--only] [--exclude <n>[,<n>...]] [--await <n>[,<n>...]] [--window <minutes>]'
+	'Usage: josh backlog:drive --owner <pid> [--active <ISO-8601>] [--max <n>] [--idle <minutes>] [--only] [--exclude <n>[,<n>...]] [--await <n>[,<n>...]] [--window <minutes>] [--stopped <n>]'
 
 const OPTIONS = {
 	active: { type: 'string' },
@@ -59,6 +60,7 @@ const OPTIONS = {
 	max: { type: 'string' },
 	only: { type: 'boolean' },
 	owner: { type: 'string' },
+	stopped: { type: 'string' },
 	window: { type: 'string' },
 } as const
 
@@ -72,16 +74,14 @@ interface DriveContext {
 	window_ms: number | undefined
 	window: string | undefined
 	is_only: boolean
+	// The child whose merge answered `stop` before the hand-back: the resumed run starts already stopping.
+	stopped: string | undefined
 }
 
 type Values = Partial<Record<Exclude<keyof typeof OPTIONS, 'only'>, string>> & { only?: boolean }
 
 function read_values(argv: ReadonlyArray<string>): Values | undefined {
-	try {
-		return parseArgs({ args: [...argv], options: OPTIONS, strict: true }).values
-	} catch {
-		return undefined
-	}
+	return cli_flags.parse_or_undefined({ args: [...argv], options: OPTIONS, strict: true })?.values
 }
 
 // A comma list of issue numbers; one entry that is not an issue number refuses the whole list.
@@ -110,6 +110,12 @@ function is_valid_window(raw: string | undefined): boolean {
 	return raw === undefined || COUNT_PATTERN.test(raw)
 }
 
+function is_valid_single(values: Values): boolean {
+	const is_valid_stopped = values.stopped === undefined || ISSUE_PATTERN.test(values.stopped)
+
+	return is_valid_stopped && is_valid_window(values.window)
+}
+
 function owner_of(values: Values | undefined): string | undefined {
 	const owner = values?.owner
 
@@ -117,7 +123,7 @@ function owner_of(values: Values | undefined): string | undefined {
 }
 
 function to_context(values: Values, owner: string): DriveContext | undefined {
-	if (!is_valid_window(values.window)) return undefined
+	if (!is_valid_single(values)) return undefined
 
 	const forwarded = forwarded_of(values)
 	const exclude = to_issues(values.exclude)
@@ -136,6 +142,7 @@ function to_context(values: Values, owner: string): DriveContext | undefined {
 		window_ms,
 		window: values.window,
 		is_only: values.only === true,
+		stopped: values.stopped,
 	}
 }
 
@@ -274,6 +281,7 @@ function resume_line(state: DriveState, context: DriveContext): string {
 
 	if (exclude.length > 0) flags.push('--exclude', exclude.join(LIST_SEPARATOR))
 	if (context.window !== undefined) flags.push('--window', context.window)
+	if (state.stopped_by !== undefined) flags.push('--stopped', state.stopped_by)
 
 	return `resume: ${flags.join(' ')}`
 }
@@ -325,7 +333,9 @@ async function drive(context: DriveContext): Promise<number> {
 	const seeded = await seeded_lanes(context)
 
 	if (seeded === undefined) return FAILURE_EXIT_CODE
-	const initial = backlog_drive.initial_state(seeded, context.active ?? new Date().toISOString())
+	const fresh = backlog_drive.initial_state(seeded, context.active ?? new Date().toISOString())
+	const initial =
+		context.stopped === undefined ? fresh : backlog_drive.merge_stopped(context.stopped, fresh)
 	const last = { state: { ...initial, exclude: [...context.exclude] } }
 	const config = { poll_ms: POLL_MS, offer_ms: OFFER_MS, window_ms: context.window_ms }
 	const end = await backlog_drive.run_loop(last.state, config, ports_of(context, seeded, last))
@@ -340,7 +350,7 @@ async function run_safe(context: DriveContext): Promise<number> {
 	try {
 		return await drive(context)
 	} catch (error) {
-		console.info(`error ${error instanceof Error ? error.message : String(error)}`)
+		console.info(`error ${error_text.message_of(error)}`)
 
 		return FAILURE_EXIT_CODE
 	}

package/scripts/backlog/backlog-drive.ts

@@ -16,19 +16,22 @@
 // **Everything it touches is a port**, the pattern `run-wake-loop.ts` set, so the sequencing is pinned
 // without a process, a network or a clock.
 
-// The `run:merge` tokens that need the parent: a hand-off, a person's stop, a tripped guard, a foreign
-// owner, an unreadable state. `resumed` is not among them — the same lane is awaited again.
-const HANDOFF_TOKENS: ReadonlySet<string> = new Set([
+const RUN_VERDICT = 'run'
+const STOP_VERDICT = 'stop'
+// The `run:merge` tokens that end the loop at once: a hand-off, a person's stop, the environment down,
+// a foreign owner, an unreadable state. `resumed` is not among them — the same lane is awaited again.
+const IMMEDIATE_TOKENS: ReadonlySet<string> = new Set([
 	'over',
 	'human-review',
-	'stop',
 	'environment',
 	'busy',
 	'retry',
 ])
+// Every token `run:merge` prints first even on a non-zero exit. `stop` — a parked backlog or the failure
+// guard — is the offer's `stop` reached through a merge: the child is collected, nothing more starts,
+// and the children still in flight are collected before the loop ends (joshuafolkken/kit#2881).
+const HANDOFF_TOKENS: ReadonlySet<string> = new Set([...IMMEDIATE_TOKENS, STOP_VERDICT])
 const RESUMED_TOKEN = 'resumed'
-const RUN_VERDICT = 'run'
-const STOP_VERDICT = 'stop'
 const WATCH_VERDICT = 'watch'
 // The verdicts the loop acts on without the parent. Any other is handed back as it was printed.
 const KNOWN_VERDICTS: ReadonlySet<string> = new Set([
@@ -63,6 +66,8 @@ interface DriveState {
 	is_stopping: boolean
 	stop_reason?: string | undefined
 	stop_is_finish?: boolean | undefined
+	// The child whose merge answered `stop`, carried on the resume line: no offer re-derives that stop.
+	stopped_by?: string | undefined
 }
 
 interface DriveEnd {
@@ -133,22 +138,43 @@ function initial_state(in_flight: ReadonlyArray<string>, active: string): DriveS
 	}
 }
 
-// One finished child: collected, excluded, and — unless its cut was resumed in place — out of flight.
+// The stop a merge reached: kept as the first stop's reason when an offer already stopped the run.
+function merge_stopped(issue: string, state: DriveState): DriveState {
+	if (state.is_stopping) return state
+
+	return {
+		...state,
+		is_stopping: true,
+		stop_reason: `run:merge #${issue} answered stop`,
+		stopped_by: issue,
+	}
+}
+
+// The child collected and excluded, and — unless its cut was resumed in place — out of flight.
+function collected_state(
+	issue: string,
+	token: string,
+	state: DriveState,
+	active: string,
+): DriveState {
+	const in_flight =
+		token === RESUMED_TOKEN ? state.in_flight : state.in_flight.filter((item) => item !== issue)
+	const exclude = state.exclude.includes(issue) ? state.exclude : [...state.exclude, issue]
+
+	return { ...state, in_flight, exclude, active }
+}
+
+// One finished child: handed back on an immediate token, otherwise collected.
 async function collect(issue: string, state: DriveState, ports: DrivePorts): Promise<PassResult> {
 	const token = await ports.merge(issue)
 
 	// An empty first line is a `run:merge` that failed before printing one: never read as a collection.
 	if (token === '') return ended('merge', state, undefined, issue)
-	if (HANDOFF_TOKENS.has(token)) return ended('merge', state, token, issue)
+	if (IMMEDIATE_TOKENS.has(token)) return ended('merge', state, token, issue)
 
-	const in_flight =
-		token === RESUMED_TOKEN ? state.in_flight : state.in_flight.filter((item) => item !== issue)
-	const exclude = state.exclude.includes(issue) ? state.exclude : [...state.exclude, issue]
+	const next = collected_state(issue, token, state, ports.now().toISOString())
 
-	return {
-		kind: 'continue',
-		state: { ...state, in_flight, exclude, active: ports.now().toISOString() },
-	}
+	return { kind: 'continue', state: token === STOP_VERDICT ? merge_stopped(issue, next) : next }
 }
 
 async function collect_finished(state: DriveState, ports: DrivePorts): Promise<PassResult> {
@@ -320,7 +346,15 @@ async function run_loop(
 	return step.end
 }
 
-const backlog_drive = { HANDOFF_TOKENS, collect, initial_state, on_verdict, run_loop, run_pass }
+const backlog_drive = {
+	HANDOFF_TOKENS,
+	collect,
+	initial_state,
+	merge_stopped,
+	on_verdict,
+	run_loop,
+	run_pass,
+}
 
 export type { DriveEnd, DrivePorts, DriveState, LoopConfig, LoopPorts, OfferRead, PassResult }
 export { backlog_drive }