@joshuafolkken/kit 1.872.0

package/prompts/collaboration-workflow/epic-bundle.md

@@ -0,0 +1,109 @@
+## 後から関連が判明した Issue を epic に束ねる
+
+「2 件以上に分割したら常に epic を作る」は既に効いているが、**発火するのは 1 つの要望をその場で分割したときだけ**である。別々のタイミングで起票された Issue が後から関連していると分かっても、束ねる仕組みが無い。次が漏れる。
+
+- 実装中に Tier A で起票した Issue が、既存の open Issue と順序や依存を持っていた場合
+- 何日か空けて起票した 2 件が、実は同じ作業の前後だった場合
+- 既存 Issue が実行順を必要としていることに、後から気づいた場合
+
+いずれも束ねられないまま個別に実行され、順序が守られず、分割の根拠がどこにも残らない。
+
+### 発火点
+
+**Issue を新規に起票した直後**に、既存の open Issue を調べる。`kickoff` / `fullrun` / `halfrun` が起票したとき、および実装中に Tier A で起票したとき（`backlogrun` 実行中を含む）。
+
+`pnpm josh epic:bundle <N>`（エイリアス `eb`）が候補を探して推奨を表示する。**このコマンドは何も書き込まない** — 候補を出すのが機械、束ねるかを決めるのは AI である。
+
+### 起票の「前」に答えるのは `issue:scout`
+
+`pnpm josh issue:scout "<title>"`（エイリアス `isc`）は、まだ存在しない Issue について同じ配属先の問いに答える（joshuafolkken/kit#1252）。**配属の判定は `epic:bundle` のものをそのまま呼んでおり、実装は 1 つしかない。** 加えて、`epic:bundle` が意図的に採らないシグナル — タイトルの語の重なりによる**重複候補** — を返す。既存 Issue の束ね直しに似た見出しが立つのは強シグナルだけで十分だからだが、「もう起票されていないか」は起票前にしか意味を持たない別の問いであり、しきい値を混ぜていない。
+
+**両方を実行する。順番が違うだけである。**
+
+| いつ                       | コマンド                | 何について答えるか                                 |
+| -------------------------- | ----------------------- | -------------------------------------------------- |
+| `gh api … issues` の**前** | `issue:scout "<title>"` | まだ番号を持たない下書き。タイトルと要約だけがある |
+| 起票の**直後**             | `epic:bundle <N>`       | 実在する Issue。番号と、それに記録された関係がある |
+
+手順上の位置づけと、重複候補が見つかったときに起票せず止まる規則は `.claude/skills/workflow-commands/SKILL.md` → §2e が単一ソースである。
+
+### 後追い Issue は起票した直後に EPIC へ束ね直す
+
+レビュー上限（`prompts/review.md` → "Review round cap"）で切り出す後追い Issue は、**このワークフローで最も件数の多い起票経路**である。それでも手順は長らく「起票して現在の Issue を参照する」までしか定めておらず、束ね直しへの導線が無かった。手順どおりに読むと起票して次へ進んで終わる。
+
+なお 2 巡目を終えた残指摘は、いまは**3 分岐（その場で直す／起票する／PR に 1 行残して落とす）**に振り分ける（`prompts/review.md` → "Review round cap"）。本節が扱うのは**起票する**分岐に入ったものだけであり、その場で直したものと落としたものは Issue にならないので束ね直しの対象にもならない。
+
+**既定は「PR に 1 行残して落とす」側であり、起票する分岐は runtime path に届く確定バグに限る**（joshuafolkken/kit#1469）。この経路はバックログ純増の 3 つの製造元のうち最も件数が多かったため、既定を落とす側へ置き直した。したがって本節が発火する回数自体が以前より少ない — それは手順の省略ではなく、既定が変わった結果である。単一ソースは `prompts/review.md` → "Three-way disposition after the cap"。
+
+手順は 3 段であり、**上の発火点の一適用ではなく、後追い起票の手順そのものに書く**。別の文書を読みに行く前提にしない。
+
+**3 段は CI 待ちの中で実行する。コミットの前ではない。** PR を開くフロー（`fullrun` / `backlogrun`）では `pnpm josh git -y` の後・`pnpm josh followup` の前に置く。PR を開かないフロー（`halfrun`、ワークフロー外のコミット前セルフレビュー）では、隠れる先の CI が無いので振り分けが決まった時点で実行する。**期限は変わらない** — 現在の Issue が閉じるのはマージ時点であり、マージするのは `followup` なので、どの段も親が open のうちに終わる。第 2 段が要求しているのはそれだけである。変わるのは秒が誰のものかだけで、実測では `epic:bundle` 43 秒・`epic --add` 18 秒（joshuafolkken/kit#1229）に対し、joshuafolkken/kit#1238 の `followup` は 122 秒のうち 78 秒を CI の完了待ちに費やしている（joshuafolkken/kit#1239）。
+
+**これは「レビューを CI と並走させる」ではない。**（ここで言うレビューは 1 周目のことであり、2 周目については下の段落で別に扱う。） joshuafolkken/kit#1216 の (b) は不採用と決定済みであり、却下の理由は規則ではなく仕組みである — あちらは**コードを変える作業**を CI と重ねるため、修正を push するたびに CI がやり直しになり、重ねた分をそのまま払い戻す。起票はコードを 1 行も変えないので、走っている CI がそのまま使える。**1 周目のレビュー**はコミットの前のままで、「コミット前セルフレビュー」は書き換えていない。**2 周目だけは CI と並走する**（joshuafolkken/kit#1261）— 同じ仕組みを逆から読んだ結果であり、2 周目は fix delta しか読まず、通常はコードを 1 行も変えない。変えた場合は同一ブランチへの追加コミット 1 つと CI のやり直し 1 回を払う。単一ソースは `.claude/skills/workflow-commands/chain-rule.md` → "The pull request opens between the rounds, so CI runs beside round 2"。
+
+1. 残指摘を後追い Issue として起票し、現在の Issue を参照する
+2. **現在の Issue が閉じる前に** `pnpm josh epic:bundle <新規>` を実行する。候補探索は open Issue しか読まないため、親が閉じた後では恒久的に `none` になる（joshuafolkken/kit#947）
+3. 答えに従う。**`epic:bundle` は推奨するだけで何も書き込まない**ので、「実行する」とは書き込みコマンドを自分で打つことである。**epic 本文の手編集は禁止** — タスクリストと `blocked-by` が食い違い、`epic:next` が `error` を返す
+
+   | 答え                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | すること                                                                                                                                                                                                                                            | Tier             |
+   | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
+   | `add_to_epic`                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `pnpm josh epic --add <E> <新規>`（順序があるなら `--before <M>` / `--after <M>`）                                                                                                                                                                  | **A — 確認不要** |
+   | `create_epic`                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `pnpm josh epic "<title>" <新規> <相手> [--ordered]`                                                                                                                                                                                                | **A — 確認不要** |
+   | `ask`（候補が複数の EPIC に散っている）                                                                                                                                                                                                                                                                                                                                                                                                                                            | **推奨する epic を自分で選び、書き込みコマンドを実行し、採用・却下・理由・決定日を新規 Issue とその epic の `## Decisions` の両方に記録する。停止もせず park もしない**（joshuafolkken/kit#1339）。2 つの epic が本当に甲乙つけがたいときだけ止める | **A — 確認不要** |
+   | `none`                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | 何もしない                                                                                                                                                                                                                                          | —                |
+   | **`Could not confirm which epic already tracks these — do not place this issue in one.`** — epic 一覧が打ち切られていたときの答えで、**Issue を epic に入れる 3 つの答え（`add_to_epic` / `create_epic` / `ask`）すべてに代わって出る**。いずれも「この Issue をまだどの epic も追跡していない」を前提にしており、打ち切られた一覧ではそれを確かめられない。子と宣言順は**意図的に出ない**（それはこの行がするなと言っている配属のレシピそのものだから）（joshuafolkken/kit#1697） | **epic に入れない。** 一覧を最後まで読める状態にしてから訊き直すか、何と言ったかを添えて停止・報告する。`Already in an epic`（追跡している epic を実際に読めた答え）は打ち切りがあっても有効なままである                                            | —                |
+   | **コマンドが答えられなかった** — 非ゼロ終了、または `Nothing to bundle.` の上に出た**あらゆる** ⚠ 警告（一覧の打ち切り、関係を読めなかった Issue）。記録済みの依存は 2 つある強い信号の片方なので、関係の読み取り失敗は本来の `add_to_epic` を `none` に化けさせる。断定的な答え（`Already in an epic` / `Add it to the epic …`）は警告が併記されていても有効である                                                                                                                | 何と言ったかを添えて停止・報告する。**警告の後の `none` は「束ねる相手が無い」ではない** — 探索が不完全なのであり、答えとして読むと本規則が塞ごうとしている経路そのもので Issue が EPIC 無しになる（joshuafolkken/kit#950）                         | —                |
+
+**`none` は正当な答えである。** コミット前セルフレビューをワークフローの外で回した場合、現在の Issue が存在せず参照先が無いため候補は出ない。そのときは束ねずにバックログへ残す — 手順が求めるのは「コマンドを実行して答えに従うこと」であって、必ず EPIC に入れることではない。
+
+**逆に、実行せずに起票だけで終えると、指摘は落ちるのではなく永久に park される。** `epic:next` が返すのは EPIC のタスクリストにある子だけなので、どの EPIC にも属さない Issue は実行中の `backlogrun` に一度も渡らない（拾うには番号を知っている人が要る）。バックログから見れば「落ちた」のと区別が付かない。
+
+実測である。joshuafolkken/kit#943 は 2 回目のレビューから切り出され、本文に `親: joshuafolkken/kit#891` と明記していながら、どの EPIC の子にもなっていなかった。親 #891 が閉じたのはその 3 分後である。同じ経路でも手順が実行された joshuafolkken/kit#911 では `epic:bundle` が EPIC を名指しし、そのまま追加されている。**差は、コマンドを打ったかどうかだけだった**（joshuafolkken/kit#946）。
+
+なお **#943 の取りこぼしには 2 層目の原因もある** — 起票が親の close より後になると、`epic:bundle` の候補探索が open Issue しか読まないため恒久的に `Nothing to bundle.` を返す。そちらは joshuafolkken/kit#947 が扱う。本節が直すのは「手順が守られなかった」側だけである。
+
+### 強い信号だけを根拠にする
+
+- 本文の相互参照（新規 Issue が既存を参照している、または既存が新規を参照している）
+- 既存の `blocked-by` 関係
+
+**タイトル・本文の内容的な類似は、それだけでは束ねる根拠にしない。** 「関連している」は際限なく広がるため、閾値を持たないと無関係な Issue まで巻き込む。類似は AI の判断を補強する材料に留める。
+
+**候補探索は open backlog に限らない。** 対象 Issue の本文が名指ししている番号は、状態を問わず 1 件ずつ読む。open 限定のままだと、後追い Issue が起票されてから親が close するまでの数分間しか正しく答えられない（joshuafolkken/kit#943 では約 3 分。過ぎると `Nothing to bundle.` を exit 0 で返し、「読めなかった」ではなく「無かった」と断定していた）。
+
+- **closed の参照先は、open な EPIC が既に追跡している場合にのみ候補にする。** 回収したい答えは `add_to_epic` である。閉じた Issue を子に持つ新規 EPIC は実行するものが残っていない
+- **open の参照先は無条件に候補にする。** 一覧に出てこなかったのは一覧が打ち切られたからであって、無関係だからではない
+- 追加読み取りは参照 1 件につき 1 リクエストで、件数に上限があり、関係の読み取りと同じ形でバッチ化される。**読み取りの失敗も、上限で読まなかった参照も、欠落として報告し「強い信号なし」に畳み込まない** — 黙って打ち切る guard は、「見るのをやめた」を「関係が無かった」と言い換える元の欠陥そのものである
+- **番号が pull request だった場合は候補にしない。** REST の issue エンドポイントは PR にも答え、マージ済み PR の state は `CLOSED` ではないため、この判定が無いと「修正は #952 で入った」という散文が PR を新規 EPIC の子に混ぜる
+- **実在しない番号は欠落として報告しない。** 打ち間違いや他リポジトリの番号のように GitHub が何にも解決できない参照は、候補にも欠落にも入れず黙って捨てる。これを欠落として報告すると、散文中の `#N` が 1 つ狂っただけで `⚠ Could not read #N.` が verdict の上に出て、上の「打ち切り警告の後の `Nothing to bundle.` は答えではない」規則により**無人実行が停止する** — 存在したことのない参照のために人を呼ぶことになる（joshuafolkken/kit#957）
+- **その判別は `gh` のエラー文言ではなく HTTP ステータスコードで行う。** 実在しない番号は REST で **404**、レート制限は **403 / 429** である。GitHub は権限の無い Issue にも存在を漏らさないため 403 ではなく 404 を返すので両者はステータスからは原理的に区別できないが、このコマンドは **直前に open 一覧を取得したのと同じリポジトリ**を叩くため、そこで見えない番号は存在しない番号である。`gh api` の失敗はステータスコードではなく stderr の文言として届くため、**読み取りが失敗したときにだけ** REST を 1 回叩いて分類する。成功経路と、この区別を必要としない呼び出し元には追加リクエストは発生しない — バックログの関係読み取りは最大 200 件あり、レート制限で全滅したときにさらに 200 リクエストを撃つことになるためである。分類する経路は参照の上限（20 件）で抑えられている
+- 追うのは対象 Issue 自身の本文だけである。逆方向（閉じた Issue が対象を名指しする）は closed 全件走査になり、かつ不要である — 後追い Issue が親を名指しするのは起票手順そのものだからである
+
+候補探索の解析は `josh epic:audit` の「暗黙の依存」検査と**同一の実装を共有する**。あちらは epic 内に閉じた解析、こちらはバックログ全体への適用というだけで、読む対象は同じ「本文中の Issue 参照」である。同じ解析を 2 回書かない。
+
+### 決定木（「常に新規 epic を作る」ではない）
+
+Issue は 1 つの epic にしか属せない（タスクリストで追跡されるため）。したがって分岐が要る。
+
+| 状況                                                                 | 動作                                                                                   | Tier |
+| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ---- |
+| **新規 Issue 自身が既に epic の子**                                  | 何もしない。Issue は 1 つの epic にしか属せず、epic 間の移動はこのルールの担当ではない | —    |
+| 関連候補が**既に epic の子**                                         | **その epic に追加**する（新規 epic を作らない）                                       | A    |
+| 候補が **epic とその親 epic** に分かれている                         | **内側（子）の epic に追加**する。親は既に子を含んでいる                               | A    |
+| 候補が**複数の異なる epic** に散っている                             | **推奨する epic を選んで追加し、理由を記録する**                                       | A    |
+| どの epic にも属さない候補があり、新規 Issue と合わせて **2 件以上** | **新規 epic を作って束ねる**                                                           | A    |
+| 強い信号を持つ候補が無い                                             | 何もしない                                                                             | —    |
+
+束ねるのは可逆（epic は編集でき、子は外せる）なので Tier A で確認を挟まない。**所属先の選択も同じく Tier A である** — `epic --add` 1 回で別の epic に移せるため、候補が複数の epic に散っていても止まらず、推奨する 1 つを選んで理由を記録する（joshuafolkken/kit#1339）。
+
+**所属先を選ぶことは epic の統合ではない。** epic 同士の統合は誰も提案していない別の操作であり、本当に必要なら**そのときに**改めて人に聞けばよい。**記録が自律の対価である** — 採用・却下・理由・決定日を残さない自動決定は、後から誰も辿れない決定を下しただけになる。
+
+**入れ子の親子関係では、この答えはもう出ない**（joshuafolkken/kit#1079）。親 epic は既に子 epic を含んでいるので、両者は選ぶべき対等な 2 択ではない。したがって関与する epic のうち**他の関与 epic の祖先にあたるものを落とし**、内側の 1 件が残ればそこへ追加する。この誤検出は 3 件記録されており、うち 1 件は実装が完了しレビューも収束し PR も mergeable だった Issue のバッチを丸ごと止めた。**落とすのは親だけで、対等な epic は落とさない** — 入れ子の連鎖の横に無関係な epic が 1 つあれば依然として尋ねるし、親子宣言が循環していて内側が定まらない場合も絞り込まずに尋ねる。
+
+### 束ねたら順序も記録する
+
+関連が順序を含む場合、`blocked-by` を付与し、epic 本文の `Dependencies` にも矢印記法で書く。既存 epic への追加時も同じ。**順序を記録しないと、束ねた事実だけが残って束ねた理由が消える。** ただし**誰も宣言していない順序をここで捏造しない** — 既に宣言されている関係だけを引き継ぐ。
+
+### 規模
+
+実測で open Issue は十数件であり、全件を舐めても一瞬なので**索引やキャッシュは用意しない**。件数が問題になってから考える。

package/prompts/collaboration-workflow/file-edits.md

@@ -0,0 +1,124 @@
+## ファイル編集はコマンド本文に本文を載せない
+
+`CLAUDE.md` →「Never carry a file's new text inside a shell command.」の正典。
+
+### 何を禁じているか
+
+**編集後のテキストを丸ごとコマンド行に載せる形を禁じる。** 典型は、インタプリタを起動して領域を書き戻す次の形である。
+
+```bash
+python3 - <<'PY'          # ← 禁止
+text = open('CLAUDE.md').read()
+open('CLAUDE.md', 'w').write(text.replace(OLD_REGION, NEW_REGION))
+PY
+```
+
+`NEW_REGION` は変数ではない。実際には**置換後の本文そのもの**がここに直接書かれ、コマンド行に載る。それがコストの正体である。
+
+領域を指定して書き換える編集は **Edit ツール**（old / new の差分）で行う。`node -e`、`cat > file <<'EOF'`、`tee file <<'EOF'`、`perl -0pi -e` に長い置換文字列を渡す形も同じ理由で禁止される。
+
+### 判断基準は「本文を丸ごと運ぶか」であり、ツール名ではない
+
+禁止の対象は**ツールの種類ではない**。判断は 1 問で決まる。
+
+> **そのコマンドは、置換後のテキストを丸ごとコマンド本文に載せているか。**
+
+- yes → 禁止。Edit を使う
+- no → 許可
+
+したがって短い置換に `sed -i` を使うのは**許される**。パターンと置換語しか運ばないので、Edit の `old_string` / `new_string` より本文が小さい。逆に「Edit を使ったから安全」も成り立たない — 300 行のファイルを全文 `new_string` に入れれば、禁じている形と同じコストになる。次節はその後半を条件として書き下したものである。
+
+### 編集は指摘された箇所だけを対象にする（全文書き直しの条件）
+
+**既定は部分編集である。** 直す行が決まっているなら、`old_string` / `new_string` はその行の周辺までに狭める。数か所を直せば済むファイルを全文書き直しで出力する形は、`python3` の heredoc と同じコストを、ツールを替えただけで払っている。
+
+**ファイルを全文書いてよいのは、ファイルそのものを置き換える意図があるときだけである。** 該当するのは次の 3 つで、それ以外は部分編集にする。
+
+- **新規ファイルの作成** — 既存本文が無いので、運ぶ重複がそもそも発生しない
+- **ファイル全体の作り直し** — 構成の組み替えや生成物の再生成で、変更後の本文が元の本文とほとんど共有しない場合
+- **部分編集のほうが大きくなる場合** — 変更箇所がファイル全域に散っていて、`old_string` / `new_string` の合計が全文を超えるとき
+
+**レビュー指摘の修正がこの規則の主戦場である。** 「この行の条件が逆」「この定数を切り出す」といった局所的な指摘ほど、部分編集は小さくなる。一方で全文書き直しのコストはファイルの大きさで決まり、指摘の小ささでは下がらない。**指摘が局所的であるほど、全文書き直しとの差は開く。**
+
+joshuafolkken/kit#1251 のランで実測した値（joshuafolkken/kit#1260）:
+
+| ターン             | 出力トークン | 内容                                                     |
+| ------------------ | ------------ | -------------------------------------------------------- |
+| レビュー指摘の修正 | 11,104       | 2 ファイルの全文書き直し。そのランの単一ターンとして最大 |
+| 同じランの別ターン | 3,282        | 全文書き直し                                             |
+
+実効生成速度は約 87 トークン/秒なので、**この 1 ランで約 2 分 45 秒が、すでに存在する行を打ち直すことに使われている。**
+
+### `sed -i` を使う前に満たす 4 条件
+
+`sed` が安いのは事実だが、Edit と違って**一致した全行**を書き換え、**一致が 0 件でも黙って成功する**。Edit の一意性検査に相当するものが無いので、使う前に次を満たす。
+
+1. **出現回数を先に数える** — `grep -o '<pattern>' <file> | wc -l` が `1` であること。**`grep -c` を使ってはならない** — 数えるのは一致した「行数」であって出現回数ではないので、同じ行に 2 回出る場合も `1` を返す。`s///` は 1 行につき 1 回しか置換しないため、そこを一意と読むと**半分だけ書き換わったファイル**が黙って残る。`0` なら何も起きないまま成功して返る
+2. **メタ文字を持ち込まない — パターン側と置換語側の両方** — 区切りの `/`、`&`、`\`、正規表現の `.` `*` `[` `]` `^` `$` のいずれかがどちらかに入るなら Edit を使う。散文が対象のこの repository では `/` とバッククォートが頻出し、**危ないのはむしろパターン側**である（`s/prompts\/…/…/` はエスケープを 1 つ落とすだけで `unterminated 's' command`、`.` は書き手が意図していない箇所に静かに一致する）
+3. **`-i` の引数はプラットフォームで違う** — BSD / macOS は `sed -i '' 's/…/…/' file`、GNU / Linux は `sed -i 's/…/…/' file`。片方の形を他方で走らせると、エラーになるか `''` という名前のバックアップファイルが残る。**配布ドキュメントに手順として書くときは必ずこの差を明示する** — kit の成果物は両方のプラットフォームの consumer に届く
+4. **編集後に自分で整形する** — `.claude/settings.json` の `PostToolUse` フックは `Bash` にも一致する（joshuafolkken/kit#1337）が、渡されるペイロードにはコマンドしか入らずファイルパスが無いため、Bash 経由の編集では整形は走らない。`sed` で表の行や折り返しのある段落に触れたら、続けて `pnpm josh format` を走らせる。**`format:edited` は手で呼べない** — フックが渡す JSON を stdin から読んで `tool_input.file_path` を取り出す設計で、引数にパスを取らないからである。放置すると `pnpm josh lint`（`prettier --check .`）が後から落ちる
+
+**4 条件のどれかが面倒に見えたら、そこが Edit を使う場所である。** `sed` はコストを下げるための例外であって、既定の編集手段ではない。
+
+| 形                                            | 可否         | 理由                                                      |
+| --------------------------------------------- | ------------ | --------------------------------------------------------- |
+| Edit（数行の old / new）                      | 可           | 差分だけが本文に載る                                      |
+| `sed -i` の短い置換                           | 条件付きで可 | パターンと置換語しか載らない。上の 4 条件を満たすこと     |
+| `python3 - <<'PY'` で領域を書き戻す           | 不可         | 置換後の本文が丸ごと載る                                  |
+| `cat > file <<'EOF'` で既存ファイルを書き直す | 不可         | 同上                                                      |
+| `cat > new-file <<'EOF'` で新規ファイルを作る | 可           | 既存本文を運んでいない。ただし長文なら Write のほうが安い |
+| 読み取り・検索（`cat` / `sed -n` / `grep`）   | 可           | 本文を運ばない                                            |
+
+### なぜコストが二重になるか
+
+インタプリタで書き戻す形は、編集後の本文が**コマンド本文とファイルの両方**に載る。さらに悪いのは持続性である。**コマンド本文は、書いた時点以降のすべてのリクエストで読み直される。** ランの序盤に書いた編集スクリプトほど、そのランの残り全リクエストぶん課金され続ける。ファイル側は次に読んだときだけ載るのに対し、コマンド側は消えない。
+
+joshuafolkken/kit#1144 のランのトランスクリプトで実測した内訳（joshuafolkken/kit#1150）:
+
+| 種別                    | 割合      |
+| ----------------------- | --------- |
+| tool_result             | 37.7%     |
+| **Bash のコマンド本文** | **30.2%** |
+| thinking                | 24.9%     |
+| text                    | 4.7%      |
+
+Bash コマンド本文 97,042 tok・427 呼び出しの内訳:
+
+| 種別                                  | 呼び出し数 | トークン   | 割合      |
+| ------------------------------------- | ---------- | ---------- | --------- |
+| `python3 - <<'PY'` 形式のファイル編集 | 145        | **79,317** | **81.7%** |
+| git / gh / pnpm                       | 140        | 12,716     | 13.1%     |
+| 読み取り・検索                        | 110        | 3,215      | 3.3%      |
+| その他                                | 32         | 1,794      | 1.8%      |
+
+**編集スクリプトだけでセッション全体のコンテキストの約 2 割を占めていた。** 1 回あたり平均 547 tok、上位は 1,200〜1,800 tok。総量そのものより、二重計上と持続が効いている。
+
+適用後の再計測は joshuafolkken/kit#1159 が担当する。
+
+### なぜ resident に置くか
+
+residency 基準（`residency.md`）は 1 問で決まる。
+
+> **その規則は、skill がロードされていないターンでも効く必要があるか。**
+
+答えは yes である。ファイル編集はワークフローのキーワードが打たれていないターンでも起き、**編集の直前にロードされる skill は存在しない。** skill 側に本体を置いた場合、この規則は一度も発火しない — 規則を書いたのに削除したのと同じ振る舞いになる。
+
+そのうえで、常駐側に置くのは**トリガと導線だけ**である。常駐側に残すのは次の 3 点で、それだけで正しく振る舞える。
+
+1. 領域を指定する編集は Edit で行い、インタプリタや heredoc で領域を書き戻さない
+2. **Edit 自体を全文へ広げない**（joshuafolkken/kit#1260）
+3. 判断基準は「本文を丸ごと運ぶか」であってツール名ではない（短い `sed -i` は許される）
+
+実測値・可否表・二重計上の説明・全文書き直しが許される 3 条件、そして**インタプリタの具体形**（`python3 - <<'PY'` / `node -e` / `cat > file <<'EOF'`）はこのファイルにあり、常駐側からは落としている。これらは「読まなくても正しく振る舞えるが、読めばより納得できる」種類の記述だからである。**具体形を指し先へ移したのは削除ではなく移動である** — 禁止の区分は常駐側の「インタプリタや heredoc」が担い、個々の形はこのファイルの可否表が担う。
+
+### マーカーテスト
+
+`scripts/document/document-markers.test.ts` が次を固定する。
+
+- `CLAUDE.md` に規則のトリガ文と判断基準の一文が resident で存在すること
+- `CLAUDE.md` に全文書き直しの禁止（「Edit を全文へ広げない」）が resident で存在すること
+- 常駐側がこのファイルを導線として指していること
+- このファイルが判断基準・可否表・`sed -i` の 4 条件・全文書き直しの 3 条件を持っていること
+- インタプリタの具体形 3 つ（`python3 - <<'PY'` / `node -e` / `cat > file <<'EOF'`）が常駐側にも residency 一覧にも残っておらず、このファイルにあること
+- 実測値（79,317 / 81.7% / 30.2% / 11,104 / 3,282）が常駐側にも residency 一覧にも貼り戻されていないこと
+- residency の一覧（`.claude/skills/workflow-commands/SKILL.md` とこのディレクトリの `residency.md`）にこの規則が載っていること

package/prompts/collaboration-workflow/gh-rest.md

@@ -0,0 +1,57 @@
+# `gh` は REST（`gh api`）で書く — 散文の指示も含む
+
+## 規則
+
+**GitHub への操作は `gh api`（REST）で書く。`gh issue …` / `gh pr …` / `gh repo …` といったサブコマンド
+形は使わない。** クラウドセッション（エージェントのコンテナ）では GitHub の GraphQL エンドポイントへの
+egress が `403` で拒否されるため、GraphQL を経由するサブコマンドはそこで一切動かない。
+
+例外は 2 つだけである。
+
+- **`gh auth token`** — ローカルの CLI が既に持っている認証情報を返すだけで、どのエンドポイントにも
+  接続しない。REST で書き換えられる呼び出しが存在しない。読み出すのはローカルの認証情報だけである。
+- **GitHub Actions のワークフロー** — ランナー上では `gh` が通常どおり動き、`gh pr merge --auto` が使う
+  API は GraphQL にしか存在しない。
+
+## 認証は環境によって別物である
+
+**手元では `gh auth login` を一度実行すれば足り、`GH_TOKEN` は要らない。** 認証情報は OS のキーチェーンに
+入り、`gh auth status` が読めるのはそれである。
+
+**CI とクラウドセッションにはそのキーチェーンが無いので、`GH_TOKEN` を設定する。** どちらか一方しか書かない
+説明は、もう一方の環境で誤った案内になる —— 手元で `gh auth login` 済みの機械に `GH_TOKEN` を設定させたり、
+クラウドで存在しないキーチェーンを探させたりする。
+
+## 散文でも「指示の形」なら REST で書く
+
+**この規則はフェンス付きコードブロックの中だけの話ではない。文書の散文に書かれたコマンドでも、読み手に
+実行を指示する形であれば REST で書く。**
+
+- **指示の形**（REST で書く）— 「数えるのはコマンド 1 つで済む: `…`」「各子 Issue に `…` でコメントを
+  書く」のように、読み手がそのまま打つことを期待している書き方。
+- **引用の形**（そのままでよい）— 「`gh issue create` は使わない」のような禁止の引用や、「このサブコマンドは
+  GraphQL を経由する」のような CLI の対応状況の記録。書き換えると、何を禁じているのかが読めなくなる。
+
+**この区別は機械には引けない。** `scripts/gh/gh-document-guard.test.ts` はフェンス付きコードブロックだけを
+走査する。散文まで広げると、41 箇所のうち 39 箇所が「禁止の引用」か「対応状況の記録」であるため、
+allowlist に 25 件を並べることになり、それは何も守らない（joshuafolkken/kit#1505）。そこでガードは
+フェンスに留め、散文の側はこの規則と `scripts/gh/gh-document-guard.test.ts` のマーカーテストで押さえる。
+
+**書き換えるときは `pnpm josh` のコマンドで置き換えられないかを先に見る。** 例えば Issue の状態を読むのは
+`gh issue view` ではなく `pnpm josh issue:state <N>` で、これはラベルと `human_review` まで一度に返す。
+
+## REST 化は `gh` を不要にしない
+
+**すべての REST 呼び出しは今も `execa('gh', ['api', …])` である。** サブコマンドをやめたことで消えたのは
+GraphQL への依存であって、バイナリへの依存ではない。**`gh` が入っていないコンテナは実在する** — その環境
+では `pnpm josh epic:next` も `pnpm josh pr` も `pnpm josh followup` も完了できず、`fullrun`
+は GitHub に一切到達しない。`git push` が通り `GH_TOKEN` が効いていても、である。
+
+`check_gh_installed` は `gh CLI is not installed` と明示するが、git remote からリポジトリを読む側の
+コマンド（`epic:next` / `epic:bundle` / `issue:scout` / `epic --add`）は「Could not read this
+repository from `git remote`, so the children cannot be keyed by repository — check `gh auth status`
+and that this is a checkout with an `origin` remote.」と出るため、原因が `gh` の不在であることが読み取り
+にくい。**そのメッセージを見たら、まず `gh` の有無を確かめる。**
+
+環境ごとの前提と、開けるべきホストの一覧は
+[`docs/cloud-session.md`](https://github.com/joshuafolkken/kit/blob/main/docs/cloud-session.md) にある。

package/prompts/collaboration-workflow/issue-citation.md

@@ -0,0 +1,38 @@
+# セッション向け出力で Issue はリンク＋短い日本語要約で参照する
+
+## セッション向け出力で Issue はリンク＋短い日本語要約で参照する（joshuafolkken/kit#1758）
+
+セッション向けの出力で Issue を指すとき、番号だけを書くと読み手は何の話か判断できず、番号を内容に解決するために毎回 GitHub を開くことになる。実際、実行中の backlogrun の報告が番号の羅列になり、オーナーから「番号だけ言われても詳細がわからない」という指摘を受けた。配布ドキュメントは Issue / PR の**タイトル**を英語に固定しているが、**セッション向け出力の中で Issue をどう言及するか**は定めていなかったため、番号だけの言及が規則に反しない状態だった。
+
+**規則**: セッション向け出力で Issue を指すときは、次の 2 つを必ず添える。
+
+1. 番号にチケットへの markdown リンク
+2. 短い日本語の要約タイトル
+
+書き方の例:
+
+- `[#<N>](https://github.com/<owner>/<repo>/issues/<N>) — <その Issue が何をするものかの短い要約>`
+
+**この引用行は手で組み立てるものではなく、`pnpm josh issue:cite <N> [<N> ...]` が出す。** 番号を並べて渡すと、貼れる引用行を 1 呼び出しでまとめて出す（複数 Issue に 1 回、他リポジトリは `--repo <owner/repo>` あるいは `owner/repo#N` 表記）。正しい形にタイトル取得の往復が要るために裸の `#N` に落ちていたので、安い道と正しい道を同じコマンドにした。要約はその Issue のタイトルをそのまま用いる。詳細は [docs/josh-commands.md](https://github.com/joshuafolkken/kit/blob/main/docs/josh-commands.md) の `josh issue:cite` を参照。
+
+**日本語タイトルは全訳ではなく要約でよい。** 何をするものか分かれば足りる。長い訳を作ることが目的ではない。`issue:cite` が出すタイトルを、必要ならセッション言語に言い換えて使う。
+
+**対応前の言及も対象である。** 「これから走らせる」「待機中」「対象外」を並べる場面こそ、読み手が内容を知らないまま番号を読むことになるため、事後の報告だけを対象にすると指摘の半分しか解決しない。
+
+### 適用範囲
+
+**対象** — セッション向け出力。会話の説明、計画の提示、進捗報告、完了報告、`AskUserQuestion` の選択肢。
+
+**対象外** — GitHub 上の artifact prose（Issue 本文、Issue / PR コメント）。GitHub は issue 参照を自動でリンクし、ホバーでタイトルを出すため、この規則が解決しようとしている問題がそもそも起きない。
+
+### 英語固定の 3 つとは衝突しない
+
+英語のままにするものは従来どおり 3 つ — Issue / PR のタイトル、コード内コメント・テスト名・コミットメッセージ、スクリプトが出力する固定文字列。この規則が変えるのは、セッション向け出力の地の文における言及の書き方だけである。番号に添える日本語要約は GitHub 上の**タイトル**ではなく、セッション内の散文の一部なので、タイトルの英語固定とは別物であり矛盾しない。
+
+### なぜ CLAUDE.md に常駐させるか
+
+規則の発火点は「セッション向け出力で Issue 番号を書こうとした瞬間」であり、これはワークフローのスキルを読んでいないターンでも起こる。したがって発火点（引き金）と形式は `CLAUDE.md` の Communication 節に常駐させ、本文（この節）を話題ファイルに置く。常駐側は短く保ち、詳細はここから読む。
+
+### 停止時の担保（joshuafolkken/kit#2247）
+
+`Stop` フック `pnpm josh stop:guard` が返信の地の文に裸の `#N` を見つけると**停止をブロックし**、その番号と `pnpm josh issue:cite <N...>` の実行形をモデルへ差し戻す。`{"decision":"block"}` は `Stop` からモデルへ文字を届ける唯一の経路で、`stop_hook_active` がループを断つので誤検出でも空転は 1 ターンで止まる。検出が外す範囲（リンク形式・コード・引用行・PR 参照）は [docs/josh-commands.md](https://github.com/joshuafolkken/kit/blob/main/docs/josh-commands.md) の `josh stop:guard` を参照。

package/prompts/collaboration-workflow/issue-template.md

@@ -0,0 +1,190 @@
+## Step 1: Issue 作成テンプレ
+
+Issue には次の要素を必ず含める。
+
+- タイトルは簡潔で明瞭な英語で記載する（本文やコメントと違い、タイトルは「出力の言語（`JOSH_SESSION_LANG`）」の例外として常に英語。日本語で作成した場合は、AIツールが実装開始前に英語タイトルへ変換する。すでに英語で書かれている場合でも、文法・明確さ・簡潔さの観点で改善できるなら書き換えて良い。いずれの場合も GitHub Issue のタイトルを `gh api -X PATCH repos/{owner}/{repo}/issues/<N> -f title="<title>"` で合わせて更新する）
+- 目的（何を改善したいか）
+- 現象（現在の不具合や課題）
+- 期待結果（完了時の状態）
+- 受け入れ条件（検証方法、対象画面/機能）
+
+最小テンプレート:
+
+````md
+## 背景
+
+<なぜ必要か>
+
+## 現象
+
+<現在の問題>
+
+## 期待結果
+
+<どうなれば完了か>
+
+## 受け入れ条件
+
+- [ ] 条件1
+- [ ] 条件2
+
+## 発火点
+
+<AI の振る舞いを変える Issue のみ。その規則が破れる瞬間に最初に呼ばれるツールコール名を 1 つだけ書く（例 `Bash` / `Edit` / `Read` / `Write` / `AskUserQuestion`）。配送表に載らない名前は、フックで配送できない発火点として印字される>
+
+## ベースライン
+
+<AI の振る舞いを変える Issue のみ。測定コマンドと現在の値を「コマンド + 値」で書く。自然文の測定説明は再実行できないため受け付けない>
+
+- `<測定コマンド>` → <現在の値>
+
+## 再現
+
+<AI の振る舞いを変える Issue のみ。現象を再現したコマンドとその実際の出力を「コマンド + 出力」で書く。自然文は再実行できないため不可。出力はフェンス（``` または ~~~）で囲む>
+
+- `<再現コマンド>`
+
+```
+<実際の出力>
+```
+
+## Origin
+
+<別リポジトリのセッションから起票した場合のみ。起票元 Issue を `owner/repo#N` 形式で書く。自リポジトリ発の Issue では節ごと省略する>
+````
+
+### 振る舞い変更 Issue の宣言と 3 つの必須見出し（`## 発火点` / `## ベースライン` / `## 再現`）
+
+**AI の振る舞いを変えると主張する Issue は、`## 発火点` と `## ベースライン` と `## 再現` の 3 見出しを必ず含める。** 散文の規則は「配って終わり」になりやすく、効いたかどうかがマージ後に読み直されないためである（joshuafolkken/kit#2178）。読みだけを根拠にした起票（既に直った現象の起票・壊れたままの現象の誤読）を防ぐため、再現の実測も課す（joshuafolkken/kit#2353）。
+
+- **対象かどうかは本文の宣言から読み、判断させない。** 本文に `- 種別: 振る舞い変更` の行がある Issue だけが対象で、コードだけを変える Issue（`- 種別: コードのみ`、または宣言なし）には 3 見出しを課さない。宣言は `## 背景` の直下に置く
+
+  ```md
+  ## 背景
+
+  - 種別: 振る舞い変更
+
+  <なぜ必要か>
+  ```
+
+- **不具合修正の Issue は `- 種別: 不具合` を宣言する。** 同じ位置（`## 背景` の直下）に置く。この宣言がある Issue では、`pnpm josh git -y` が追加・変更したテストを修正前のツリー（merge-base）に当てて `pnpm josh test:red` で実行し、1 本も赤にならない（`green`）ときはコミットを拒否する。修正前でも緑の回帰テストは、報告された症状を再現していないためである（joshuafolkken/kit#2448）。回帰テストは、利用者が症状を見たのと同じ粒度で書く
+- **`## 発火点`** には、その規則が破れる瞬間に最初に呼ばれるツールコール名を 1 つ書く。名前は `prompts/collaboration-workflow/rule-delivery.md` の配送表に載る、フックで配送可能なツール（`Bash` / `Edit` / `Read` / `Write` / `AskUserQuestion`）と突き合わせる。**表に無い名前**（そもそもツールコール名でない）と**不一致**（既知のツールだが配送できない）は区別して印字され、joshuafolkken/kit#2201 の「規則は正しいが名指ししたコールが実際に破れるコールの 1 つ後ろ」を起票時に検出する
+- **`## ベースライン`** は **「コマンド + 値」** で書く。``- `<測定コマンド>` → <現在の値>`` の形に限り、自然文だけの測定説明は受け付けない（再実行できないため）。マージ後に `pnpm josh measure:rerun` が同じコマンドをやり直し、**before / after の対**を印字する。値が動かなかったとき、反証された前提として `docs/observations.md` に 1 行追記される（既存の append-only 台帳をそのまま使い、第 2 の台帳は作らない）
+- **`## 再現`** は **「コマンド + 実際の出力」** で書く。コマンドを backtick、出力をフェンス（``` または ~~~）で囲む。自然文の「確認した」は再実行できないため受け付けない（`## ベースライン` と同じ理由）。読みだけの起票を起票時に弾くためである
+- **検査は `pnpm josh issue:lint <path>` が行う。** 対象判定・3 見出しの有無・発火点の配送可否・ベースラインが「コマンド + 値」か・再現が「コマンド + 実際の出力」かを、起票前の本文ファイルにまとめて検査する（未リントの起票は `pnpm josh rule:guard` が拒否する）
+
+### 起票元へのバックリンク（`## Origin` / `## Upstream issues`）
+
+**別リポジトリのセッションから起票した Issue には、起票元へのリンクを必ず書く。** 上流 Issue は欠陥そのものを述べるが、その欠陥が「どのプロジェクトで・どのバージョンの組み合わせで・どんな出力として現れたか」という証拠は消費者側の Issue にしかない。リンクはその証拠へ戻る唯一の経路であり、半年後にその Issue を読む人にとっては本文と同じだけ重要である。
+
+**双方向とも必須**（片方向では、上流の修正を待っている消費者側が「何を待っているのか」を辿れない）:
+
+| 方向                  | 置き場所                      | 固定見出し              | 内容                                                 |
+| --------------------- | ----------------------------- | ----------------------- | ---------------------------------------------------- |
+| 上流 Issue → 起票元   | 上流 Issue の本文             | `## Origin`             | 起票元 Issue（`owner/repo#N` または URL）            |
+| 起票元 Issue → 上流   | 起票元 Issue の本文かコメント | `## Upstream issues`    | そこから起票した上流 Issue を全件列挙する            |
+| 起票元 Issue → 未起票 | 起票元 Issue の本文かコメント | `## Upstream candidate` | 第三者リポジトリへ報告する候補（**未起票**）と下書き |
+
+- **見出しは固定する**。「書いた人が置いた場所」ではなく grep で機械的に見つかるようにするため。起票元 Issue 側は、その場で本文を書いている最中なら本文に、既に本文が確定しているなら同じ見出しでコメントに書く
+- **リンクは必ずリポジトリ修飾する**（`owner/repo#N` または完全 URL）。**裸の `#N` を使ってはならない** — 上流リポジトリ内では同番号の別 Issue に解決され、黙って誤ったものを指す
+- **チェックボックス行（`- [ ] owner/repo#N`）で書いてはならない。散文か素の箇条書き（`- owner/repo#N`）にする。** `scripts/git/git-epic-parse.ts` の `has_external_task_list_entry` は「チェックボックス付きで他リポジトリを参照する行」を検出すると epic の自動クローズを無効化する。これは**本物の他リポジトリ子 Issue に対しては正しい挙動**（その状態は別リポジトリを指定しないと読めないため）だが、単なる後方参照をその記法で書くと epic が永久に open のまま残る。判定はチェックボックスの有無だけを見るので、素の箇条書きは安全である
+- **未起票の候補には `## Upstream candidate` を使い、`## Upstream issues` を使わない**。後者は「既に起票した」ことを主張する見出しであり、third-party リポジトリへの報告はユーザーの明示指示があるまで起票しないため、両者は必ず別の見出しに置く（→「第三者リポジトリへの書き込みは Tier C（明示指示が必要）」）
+- 割り込みで起票する場合の手順は「別パッケージ起因の問題は割り込み Issue で対応する」、分割で起票する場合は下記 epic 節を参照
+
+### 複数 Issue に分割するときの epic Issue
+
+`kickoff new` が 1 つの要望を **2 件以上**の Issue に分割したとき、**常に**それらを束ねる epic Issue を作成する。件数や実行順序の有無で分岐しない。
+
+なぜ必要か: 分割の根拠を「最初の Issue のコメント」に置くと、その Issue はバッチが最初にマージしてクローズする対象でもあるため、残りの作業の設計図がクローズ済み Issue の中に埋もれる。epic の役割は、その情報の**閉じない置き場**を用意することにある。実行順序は epic が載せられる情報の一つであって、epic が存在する理由ではない。埋没は順序の有無と無関係に、複数分割のたびに起きる。
+
+- **条件分岐を置かない。** 「件数が少ないうちは epic の管理コストが情報整理の利益を上回る」という以前の但し書きは、`scripts/git/git-epic-close.ts`（`pnpm josh followup` から駆動）が子 Issue の全クローズを検知して epic を自動クローズするようになった時点で根拠を失った。放置される epic という管理コストがもう存在しない以上、避けるべきは分岐の誤判定だけである。2 件・順序不問の分割に epic が付く冗長さは軽微で、分岐の見落としによる情報消失より常に安い
+- epic には `epic` ラベルを付ける（未作成なら `gh api repos/{owner}/{repo}/labels -f name=epic -f color=5319e7 -f description="Tracks a batch of child issues from one split" --silent 2>/dev/null || true`）。放置された open epic を `gh api "repos/{owner}/{repo}/issues?labels=epic&state=open"` で棚卸しできるようにするため
+- **epic 自体を実装ランに渡してはならない。** epic には成果物がなく、`backlogrun #<E> --only` がその子 Issue を回す
+- epic は最後の子 Issue がクローズされた時点で `pnpm josh followup` が自動クローズする。マージ後に `epic` ラベルの open な Issue を探し、タスクリストの子が全てクローズ済みなら子を列挙したコメント付きで閉じる。1 件でも open なら放置し、この処理の失敗は警告のみでランを止めない。最終 PR に `closes #<epic>` を書く方法は、バッチが途中で失敗したときにも発火して未完了を完了扱いにするため採用しない
+- 自動クローズは `epic` ラベルとタスクリスト記法の両方に依存する。どちらかを欠くと epic は open のまま残るので、手動でクローズする
+- タスクリストが**他リポジトリの子 Issue**（`owner/repo#N` や URL 形式）を含む場合、自動クローズは行われない。その子の状態は別リポジトリを指定しないと読めず、無視すると open のまま epic を閉じてしまうため。この場合も手動でクローズする
+- **分割そのものが別リポジトリのセッション発である場合**（消費者リポジトリでの `kickoff new` が上流に子 Issue を起票したなど）、各子 Issue の本文に `## Origin` を、epic 本文にも同じ起票元へのリンクを書く（→「起票元へのバックリンク」）。epic 側は `Split rationale` の直後に散文か素の箇条書きで置く。**チェックボックス行で書くと直前の項目に該当して自動クローズが止まる**ため、この 1 点だけは形式を守る。起票元 Issue 側にも `## Upstream issues` として起票した子 Issue と epic を列挙する
+- epic 本文の `Dependencies` に依存の連鎖（`#N -> #M`）が書かれているのに、手順 4 の依存関係が**一件も付いていない**場合、`pnpm josh followup` が子 Issue のマージごとに警告する。連鎖の形は検査しない（タスクリストの並び順を依存順と推測することになり誤検知を生むため）。判定の起点を本文の宣言に置くのは、epic の存在がもう順序ありを意味しないため — 順序不問のバッチにも epic を作る以上、依存関係ゼロ件は正常な状態でもありうる
+
+作成手順（既定）: **`pnpm josh epic` を使う。**
+
+```bash
+# 順序不問のバッチ
+pnpm josh epic "<epic-title>" <N1> <N2> ...
+
+# 実行順序があるバッチ（引数の並び順＝依存順）
+pnpm josh epic "<epic-title>" <N1> <N2> ... --ordered
+
+# 分割理由の散文を渡す（`-` で標準入力）
+pnpm josh epic "<epic-title>" <N1> <N2> --rationale-file <path|->
+
+# 別リポジトリのセッション発である場合のバックリンク
+pnpm josh epic "<epic-title>" <N1> <N2> --origin <owner/repo#N>
+```
+
+このコマンドは上記 4 要件を**構成上**満たす。ラベルを用意してから付与し、子をタスクリスト記法で描画し、`Dependencies` を `--ordered` の有無で矢印連鎖／`None — ...` 固定文に振り分け、`Execution` の実行コマンド（`backlogrun #<E> --only`）を組み立てる。`--ordered` のときは同じ入力から native な依存関係も付与するので、**本文の宣言と native な依存関係が食い違うことがない**（手順 4 の付け忘れが構造的に起きなくなる）。付与は REST の依存関係エンドポイント（`gh api`）を通るため、**`gh` CLI のバージョンには依存しない**（joshuafolkken/kit#1026）。このエンドポイントはブロッカーを Issue 番号ではなく **database id** で受け取り、しかもその id が自リポジトリの Issue かを検証しないため、コマンドは書き込み前に番号から id を解決する。付与は Issue の作成後に独立して行うので、失敗しても件数を報告して続行する（失われるのは関係だけで、Issue とタスクリストは既に正しい）。
+
+作成済みの epic は `pnpm josh epic:check <E>` で 4 要件を点検できる。手書きした epic、コマンド導入以前の epic、本文を手で編集した後の確認に使う。全要件を満たせば exit 0、満たさなければ exit 1 なのでゲートとしても使える。判定は自動クローズが読むのと**同じパーサ**（`scripts/git/git-epic-parse.ts`）を使うため、「自動クローズが読める形式」と「点検が通る形式」は定義上一致する。
+
+作成手順（フォールバック）: **`josh` が使えない環境でのみ**、以下を手で行う。
+
+1. 子 Issue を全て作成し、番号 `<N1> <N2> ...` を控える
+2. `epic` ラベルを用意する（未作成なら `gh api repos/{owner}/{repo}/labels -f name=epic -f color=5319e7 -f description="Tracks a batch of child issues from one split" --silent 2>/dev/null || true`）
+3. epic を作成し、番号 `<E>` を控える: `gh api repos/{owner}/{repo}/issues -f title="<epic-title>" -f 'labels[]=epic' -f body="<body>" --jq .number`（`--jq` を落とすと Issue の JSON 全体が出る。そこには `id` も含まれるが、**控えるのは `number` である** — `id` はデータベース id で、手順 4 が要求する値ではあっても epic の番号ではない）
+4. 実行順序が**ある場合のみ**、子 Issue に依存関係を付与する（後述の理由により**作成後の独立ステップ**として行う）:
+
+   ```bash
+   gh api repos/{owner}/{repo}/issues/<N2>/dependencies/blocked_by -F issue_id="$(gh api repos/{owner}/{repo}/issues/<N1> --jq .id)"
+   gh api repos/{owner}/{repo}/issues/<N3>/dependencies/blocked_by -F issue_id="$(gh api repos/{owner}/{repo}/issues/<N2> --jq .id)"
+   ```
+
+   **エンドポイントが受け取るのは Issue 番号ではなくデータベース id である。** 番号をそのまま送っても 200 が返るが、記録されるのは「その数値を id に持つ、まったく無関係なリポジトリの Issue」である（joshuafolkken/kit#1026 が実測）。`--jq .id` の一段はこの取り違えを防ぐためにあり、省略できない。
+
+   順序が不問なら手順 4 は行わない。epic の作成は無条件だが、依存関係の記録は順序が実在するときだけで、両者は独立している。
+
+手順 2 の `|| true` はラベルが既に存在する場合（REST は 422 `already_exists` を返す）を無視するためのものである。**握り潰しの代償は `gh` の頃と変わっており、安全な方向に変わっている。** `gh issue create --label epic` はラベルを解決できずに失敗したため、異常は手順 3 で顕在化した。REST の `POST /issues` は `labels` に無いラベルを**その場で作る**（色と説明は既定値、joshuafolkken/kit#1026 が実測）ので、握り潰しが失うのは色と説明だけでラベル自体ではない。`epic:next` と自動クローズは名前だけを見るため、追跡は成立する。
+
+手順 4 は REST の依存関係エンドポイントを直接叩くので `gh` のバージョンに依存しない。**失敗しても続行してよい**（付かないのは関係だけで、Issue とタスクリストは無傷）。関係付与は作成と分けて行う — 作成呼び出しに畳み込むと、関係の失敗が Issue の失敗になり、**Issue 自体が作られない**。分けておけば劣化は「Issue が消える」ではなく「関係が付かない」で済む。
+
+epic 本文のテンプレート:
+
+```md
+## Split rationale
+
+<なぜこの分割にしたか>
+
+## Dependencies
+
+#101 -> #102 -> #103
+
+## Execution
+
+backlogrun #<E> --only
+
+## Progress
+
+- [ ] #101 <title>
+- [ ] #102 <title>
+- [ ] #103 <title>
+```
+
+`Progress` は**必ずタスクリスト記法**（`- [ ] #N`）で書く。GitHub は参照先 Issue がクローズされた時点でこの記法のチェックボックスのみを自動で埋めるため、素のリンク（`#N` の直書き）では進捗が追跡されない。ただし全項目が埋まっても GitHub が epic 自体をクローズすることはない。
+
+`Dependencies` は順序があるなら**必ず矢印記法**（`#101 -> #102`、`->` または `→`）で書く。`pnpm josh followup` の順序未記録チェックはこの記法を検出して初めて発火するため、`#102 depends on #101` のような散文で書くと、手順 4 を飛ばしても警告されない。順序が不問なら節ごと省略せず `None — the children are independent; any execution order works.` と明示する。空欄や節の削除では「順序がない」のか「書き忘れた」のかが読み手にもチェックにも区別できない。
+
+**宣言の行は矢印の連鎖だけで構成する。** 理由の注記を同じ行の末尾に付けた `#101 -> #102 (#102 は #101 の API を使う)` は宣言として読まれず、`epic:check` が「機械可読な宣言が無い」と報告する。読み取り側が「連鎖しか書かれていない行」だけを宣言と見なすのは、節の外にある散文の推奨実行順（`推奨実行順: #869 -> #863 -> …`）を宣言と誤読しないためで、この判定は本文を読む 3 経路（`epic:check` の存在判定・`epic:next` のリンク読み取り・`josh epic --add` の書き換え）で共有されている（joshuafolkken/kit#858、joshuafolkken/kit#1155）。理由は連鎖の**次の行**か `Split rationale` に書く。**連鎖と `None — ...` 固定文を両方書いてはならない** — 順序があると同時に無いと宣言することになり、`epic:check` は矛盾として ✖ を返す。
+
+#### ネイティブの依存関係と sub-issues
+
+`gh` は Issue 間の関係をネイティブに扱える。下表のフラグと JSON フィールドは **2.97.0 の実バイナリで存在を確認済み**。導入バージョンを 2.94.0 とするのは `cli/cli` のリリースノート記載によるもので、2.94.0 自体での動作確認は行っていない。GitHub Enterprise Server では依存関係に 3.19 以降が必要（github.com では制約なし）。
+
+**下表は `gh` CLI の対応状況の記録であり、本ドキュメントのどの手順もこれを経由しない。** `pnpm josh epic` も上記のフォールバック手順 4 も、REST の依存関係エンドポイントを `gh api` で直接叩くため、下表のフラグにも 2.94.0 要件にも依存しない（joshuafolkken/kit#1026）。**下表の形は `gh issue edit` / `gh issue view` であり、いずれも GraphQL を通るためクラウドセッションでは 403 になる**（joshuafolkken/kit#1022）。表を残すのは、sub-issues を採らなかった理由が CLI の対応状況とは無関係であることを示すためである。
+
+| 種別     | 書き込み                                                                   | 読み取り                                                     |
+| -------- | -------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| 依存関係 | `gh issue edit <N> --add-blocked-by <M>` / `--add-blocking` / `--remove-*` | `gh issue view <N> --json blockedBy,blocking`                |
+| 親子関係 | `gh issue edit <N> --parent <M>` / `--add-sub-issue`                       | `gh issue view <N> --json parent,subIssues,subIssuesSummary` |
+
+**依存関係は採用する**（上記の作成手順 4）。子 Issue 単体を見たときに何を待っているかが GitHub の UI と API の両方から分かるようになり、epic 本文の `Dependencies` 行が人間向けの散文でしかなかった問題が解消する。ただし依存関係は**表示するだけで着手を防がない**ため、順序を守る責任は引き続き依存関係の宣言（`--ordered`）と、それを読む `backlogrun` にある。epic 本文の `Dependencies` 行は、関係が付かなかった場合でも読める冗長な記録として残す。
+
+**sub-issues（親子関係）は採用しない。** 理由は 2 点 — 親子関係は「包含」を表すだけで実行順序を表現できない、および親子関係は同一リポジトリオーナー内に限られる。いずれも CLI の対応状況とは無関係で、2.94.0 以降でも変わらない。

package/prompts/collaboration-workflow/latest-first.md

@@ -0,0 +1,14 @@
+## 最新優先・fix-forward（pin-back は最終手段）
+
+依存パッケージ・ツールチェーンは**既定で最新版を採用する**。バンプが lint クラッシュ・新規有効化ルール・型エラーなどの破壊を引き起こしても、古いバージョンへ留まる／戻すことを既定の「安全策」にしてはならない。破壊は**前向きに（fix-forward）速やかに**解消する。
+
+1. **最新優先（latest-first）**: 依存・ツールチェーンは新しいバージョンを既定で採用する。適応の手間を避けるためだけに古いバージョンに留まったり戻したりしない
+2. **破壊は fix-forward**: バンプで lint クラッシュ・新規ルール・型エラー等が出たら、前向きに解消する:
+   - 新ルール／エラーが正当なら **消費者コードを直す**
+   - ルール上書きが要るなら **正しいレイヤー**（kit / app-kit の共有設定）でスコープする。消費者リポジトリでの場当たり的な一回限りの disable にしない
+   - 破壊が first-party パッケージ（kit / app-kit）起因なら、**そこに Issue を立てて適切な altitude で直す**。消費者側の回避だけで済ませない（→「別パッケージ起因の問題は割り込み Issue で対応する」参照）
+3. **pin-back は最終手段**: fix-forward が本当に不可能／ブロックされている（例: 未リリースの上流修正待ち）ときだけ、古いバージョンへ固定する。固定するときは **理由を記録し、最新へ戻すためのトラッキング Issue を立てる**。pin-back を既定の推奨として提示してはならない
+4. **既存の保護を尊重する**: この方針は overrides / `devEngines` の承認ゲートを上書きしない。fix-forward は _「最新を優先し破壊を直す」_ であって _「保護された pin を黙って書き換える」_ ではない。overrides（`pnpm-workspace.yaml` / `package.json` のいずれも）と `devEngines` の変更は従来どおりユーザーの明示承認を要する（→「overrides の保護（`pnpm-workspace.yaml` / `package.json` の両方を見る）」、および CLAUDE.md の `devEngines` 保護ルール参照）
+5. **タイムリーに**: バンプ起因の破壊は、可能な限り同じ作業セッション内で速やかに対処し、pin の裏に先送りしない
+
+- このルールは横断ドキュメント（CLAUDE.md「Latest-first, fix forward — pin back only as a last resort」）のカノニカル参照

package/prompts/collaboration-workflow/no-clones.md

@@ -0,0 +1,11 @@
+## クローン禁止・単一ソース化（パッケージ境界を越えても）
+
+既存の非自明なロジックを「ソースを変えずに済ませる」ために**コピー・移植・再実装することは既定で禁止**する。すでにどこか（別ファイル・別モジュール・別**パッケージ＝上流依存を含む**）に存在するロジックを複製しようとした瞬間が、**単一ソース化**（全消費者が import する共有モジュール／export／パッケージ）のシグナルである。コピーではなく単一ソース化する。
+
+- **既存の重複は再重複の免罪符にならない**: すでに一度クローンされている（例: jgame が kit をコピー）なら、共有抽象化はとっくに必要だったということ。3 つ目のコピーを足さず、重複の存在を surface する
+- **「上流を参照する」は「再利用する」の意**であって、「そのコードを貼り付ける」ではない
+- **「X を触るな」という制約はクローンを黙って正当化しない**: クリーンな修正には上流（kit）の変更が要る／代替はクローン、というトレードオフを先にユーザーへ提示する（「クリーンな修正は kit の変更が必要、代替はクローン、どちらにする？」）
+- 複製は、単一ソース化の代替案とそのコストを提示し、**ユーザーの明示承認を得た後にのみ**行う
+- このルールは横断ドキュメント（CLAUDE.md「No clones — single-source」）のカノニカル参照
+
+**計測は `pnpm josh clone:scan`。** 引き金は「複製しようとした瞬間」という自覚頼みで、守られているか確かめる手段がなかった（`sonarjs/no-identical-functions` は同一ファイル内しか見ない）。このコマンドは同一リポジトリ内および `JOSH_REPO_PATHS` の他リポジトリを跨いだ複製を検出し、**件数**と各複製の `file:line`（`[same-file|cross-file|cross-repo]` 分類つき、複製なしは `clean`）を印字する。`pnpm josh oracle:list` に載る決定オラクルでもある。