@joshuafolkken/kit 1.1136.0 → 1.1178.0

package/dist/hooks/pretool-guard.js

@@ -1,18 +1,19 @@
 #!/usr/bin/env tsx
 import {
+  pretool_guard,
   pretool_outcome_async
-} from "./chunk-KBXZLMRH.js";
-import "./chunk-JKKTVDAG.js";
+} from "./chunk-G6KRCKEC.js";
+import "./chunk-GDS5N2KB.js";
 import "./chunk-3V37IID6.js";
-import "./chunk-KOKOAV6D.js";
-import "./chunk-RFWWUI5F.js";
-import "./chunk-HBKZLITF.js";
-import "./chunk-LJBLGHEH.js";
-import "./chunk-HANSKHES.js";
+import "./chunk-VQLLNFNT.js";
+import "./chunk-VESKRQOF.js";
+import "./chunk-DO6NWWHU.js";
+import "./chunk-ZAL3NRGL.js";
+import "./chunk-I4XSL4TT.js";
 import {
   hook_decision
-} from "./chunk-NFZGFGOR.js";
-import "./chunk-GDU26K3J.js";
+} from "./chunk-32GQTL4F.js";
+import "./chunk-S6X6WYKR.js";
 import "./chunk-WPALEIRX.js";
 import "./chunk-RKUAD3I6.js";
 
@@ -24,6 +25,6 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
   else {
     const raw_payload = await text(process.stdin);
     hook_decision.load_environment_file();
-    hook_decision.emit_outcome(await pretool_outcome_async(raw_payload));
+    pretool_guard.emit(raw_payload, await pretool_outcome_async(raw_payload));
   }
 }

package/dist/hooks/stop-guard.js

@@ -25,14 +25,14 @@ import {
   run_headless,
   run_hold,
   run_invocation
-} from "./chunk-JKKTVDAG.js";
+} from "./chunk-GDS5N2KB.js";
 import {
   session_language
 } from "./chunk-6V5OPIUU.js";
 import {
   hook_decision,
   lane_child_marker
-} from "./chunk-NFZGFGOR.js";
+} from "./chunk-32GQTL4F.js";
 import {
   PROJECT_ROOT,
   json_value,
@@ -40,7 +40,7 @@ import {
   time_density_hook,
   time_hook_transcript,
   time_reported_failure
-} from "./chunk-GDU26K3J.js";
+} from "./chunk-S6X6WYKR.js";
 import "./chunk-WPALEIRX.js";
 import "./chunk-RKUAD3I6.js";
 
@@ -419,6 +419,9 @@ async function timed_fetch(url, init = {}, timeout_ms = FETCH_TIMEOUT_MS) {
 // scripts/notify/telegram-notify.ts
 import { z } from "zod";
 var TELEGRAM_API_BASE = "https://api.telegram.org";
+var TELEGRAM_TEXT_LIMIT = 4096;
+var BODY_TRUNCATION_MARK = "\n...";
+var TRAILING_HIGH_SURROGATE = /[\uD800-\uDBFF]$/u;
 var telegram_environment_schema = z.object({
   telegram_bot_token: z.string().min(1, { message: "TELEGRAM_BOT_TOKEN is required" }),
   telegram_chat_id: z.string().min(1, { message: "TELEGRAM_CHAT_ID is required" })
@@ -502,9 +505,20 @@ function build_blocks(input) {
   blocks.push(...build_url_parts(input));
   return blocks;
 }
-function build_text(input) {
+function join_blocks(input) {
   return build_blocks(input).join("\n\n");
 }
+function head_of(body, kept) {
+  const head = body.slice(0, kept);
+  return TRAILING_HIGH_SURROGATE.test(head) ? head.slice(0, -1) : head;
+}
+function build_text(input) {
+  const text2 = join_blocks(input);
+  const overflow = text2.length - TELEGRAM_TEXT_LIMIT;
+  if (overflow <= 0 || input.body === void 0) return text2;
+  const kept = Math.max(0, input.body.length - overflow - BODY_TRUNCATION_MARK.length);
+  return join_blocks({ ...input, body: `${head_of(input.body, kept)}${BODY_TRUNCATION_MARK}` });
+}
 async function post_message(config, text2) {
   const url = `${TELEGRAM_API_BASE}/bot${config.bot_token}/sendMessage`;
   const response = await timed_fetch(url, {
@@ -835,14 +849,14 @@ var stop_payload_schema = z3.object({
 });
 var NO_OUTCOME = { reason: void 0 };
 var STOP_NOTIFY_REASON = '\u26D4 mid-workflow stop notification: this working tree is still held by a run and no `confirmation` Telegram was sent this turn, so a person is being left to wait off-screen without knowing the run paused. `CLAUDE.md` \u2192 "Mid-workflow stop notification" requires `pnpm josh notify --task-type confirmation --issue-url "<url>" --body=$\'<reason>\'` before any mid-workflow pause. Send it, then end with a one-line confirmation that it was sent \u2014 do not repeat your previous reply. This fires only while the hold is held and no notify is on the transcript, and `stop_hook_active` lets a second stop through so a run is never wedged.';
-var HOLD_RELEASE_REASON = "\u26D4 working-tree hold not released: this working tree is clean but its `run:hold` record is still in place, so the next run here runs `git switch main && git pull` believing the tree is free while you hold it. `.claude/skills/workflow-commands/SKILL.md` \u2192 \xA72f: a stop that leaves the tree clean releases the hold with `pnpm josh run:release <N>` (bare for a `new` entry). A `halfrun` pre-commit stop and a `needs-human-review` stop keep the hold because their tree is dirty, and a `prrun` stop keeps it by its stop mark \u2014 this row is silent there. Release it, then end with a one-line confirmation that it was released \u2014 do not repeat your previous reply.";
+var HOLD_RELEASE_REASON = "\u26D4 working-tree hold not released: this working tree is clean but its `run:hold` record is still in place, so the next run here runs `git switch main && git pull` believing the tree is free while you hold it. The workflow-commands skill \u2192 `working-tree-hold.md`: a stop that leaves the tree clean releases the hold with `pnpm josh run:release <N>` (bare for a `new` entry). A `halfrun` pre-commit stop and a `needs-human-review` stop keep the hold because their tree is dirty, and a `prrun` stop keeps it by its stop mark \u2014 this row is silent there. Release it, then end with a one-line confirmation that it was released \u2014 do not repeat your previous reply.";
 var ISSUE_CITATION_REASON = "Session-facing output cites an Issue as a number-link so the reader can click through and see which repository it is (`CLAUDE.md`, `prompts/collaboration-workflow/issue-citation.md`).";
 function build_citation_reason(references) {
   const numbers = references.join(", ");
   const command = `pnpm josh issue:cite ${issue_citation.cite_arguments(references).join(" ")}`;
   return `\u26D4 issue citation: your reply names an Issue as a bare \`#N\` (${numbers}). Run \`${command}\` to print the paste-ready citation lines, then print the corrected citation lines alone \u2014 do not repeat your previous reply. ${ISSUE_CITATION_REASON}`;
 }
-var FILING_OFFER_REASON = '\u26D4 filing offer: your reply offers to file an Issue instead of filing it. Filing into a first-party repository is Tier A \u2014 the trigger is the judgement that it is worth filing, not the run\'s progress (`.claude/skills/workflow-commands/SKILL.md` \u2192 \xA72i, `observation-filing.md`). Run `pnpm josh issue:file "<title>" --body-file <path> --depth <0|1|2>` \u2014 it scouts, lints, labels and runs `epic:bundle` itself \u2014 then end with the one-line citation of what was filed; do not repeat your previous reply. If it is not worth filing after all, say so in one line instead.';
+var FILING_OFFER_REASON = '\u26D4 filing offer: your reply offers to file an Issue instead of filing it. Filing into a first-party repository is Tier A \u2014 the trigger is the judgement that it is worth filing, not the run\'s progress (the workflow-commands skill \u2192 `observation-filing.md`). Run `pnpm josh issue:file "<title>" --body-file <path> --depth <0|1|2>` \u2014 it scouts, lints, labels and runs `epic:bundle` itself \u2014 then end with the one-line citation of what was filed; do not repeat your previous reply. If it is not worth filing after all, say so in one line instead.';
 var HEADLESS_WAIT_MARKER = "\u26D4 headless parent:";
 var HEADLESS_REFUSAL_CAP = 3;
 var HEADLESS_WAIT_CALLS = ['"command":"pnpm josh lane:await'];

package/dist/josh.js

@@ -26,6 +26,7 @@ import { execaSync } from "execa";
 // scripts/git/constants.ts
 import { platform } from "node:os";
 var GIT_COMMAND_UNIX = "/usr/bin/git";
+var GIT_BINARY_KEY = "JOSH_GIT_BINARY";
 function get_git_command() {
   if (platform() === "win32") {
     return String.raw`"C:\Program Files\Git\cmd\git.exe"`;
@@ -33,6 +34,8 @@ function get_git_command() {
   return GIT_COMMAND_UNIX;
 }
 function get_git_command_for_spawn() {
+  const binary = process.env[GIT_BINARY_KEY];
+  if (binary !== void 0 && binary !== "") return binary;
   if (platform() === "win32") {
     return String.raw`C:\Program Files\Git\cmd\git.exe`;
   }
@@ -528,10 +531,10 @@ var ISSUE_COMMANDS = {
   },
   "issue:file": {
     script: "scripts/issue/issue-file-cli.ts",
-    description: "File an Issue with every filing step: lint, Origin, duplicate scout, labels, then epic:bundle",
+    description: "File an Issue with every filing step: lint, Origin, WIP cap, duplicate scout, labels, then epic:bundle",
     category: "AI tools",
     reference: [
-      "<title> --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,\u2026>]",
+      "<title> --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,\u2026>] [--over-cap] [--no-auto-ok]",
       "automation",
       ["network"]
     ]
@@ -1042,6 +1045,15 @@ var DEV_COMMANDS = {
     // `UserPromptSubmit`, so it must stay eligible for in-process dispatch rather than pay a second
     // tsx start each turn. It calls `process.loadEnvFile` itself through the shared loader.
   },
+  "codex:hook-adapter": {
+    script: "scripts/hooks/codex-hook-adapter.ts",
+    description: "Codex hook: run the pretool or posttool guard on a Codex payload (reads the tool call on stdin)",
+    category: "Development",
+    reference: ["<pretool|posttool>", "automation", ["none"]]
+    // The live-source fallback `scripts/hooks/run-hook.sh` derives from the `codex-hook-adapter`
+    // bundle name (joshuafolkken/kit#3184). **No `tsx_arguments`**, the same as `pretool:guard`
+    // above: it runs before every guarded Codex call.
+  },
   "cspell:dot": {
     script: "scripts/lint/cspell-cached.ts",
     description: "Run spell check including dotfiles",
@@ -1080,7 +1092,7 @@ var DEV_COMMANDS = {
   },
   "test:red": {
     script: "scripts/test/test-red.ts",
-    description: "Run the changed unit tests against the pre-fix tree (merge-base worktree) and report red/green/no-test",
+    description: "Run the changed unit tests against the pre-fix tree (merge-base worktree) and report red/green/no-test/test-only",
     category: "Development",
     reference: ["", "developer", ["git", "processes"]]
   },
@@ -1688,6 +1700,7 @@ var REPO_PATH_SEGMENTS = 2;
 var NOT_FOUND = -1;
 var SECTION_PREFIX = "[";
 var ORIGIN_SECTION = /^\[remote\s+"origin"\]$/u;
+var REMOTE_SECTION = /^\[remote\s+"[^"]+"\]$/u;
 var URL_KEY = "url";
 function is_github_hostname(host) {
   return host.toLowerCase() === GITHUB_HOST;
@@ -1747,6 +1760,18 @@ function parse_origin_from_config(content) {
   const lines = content.split("\n").map((line) => line.trim());
   return origin_section_lines(lines).map((line) => entry_value(line, URL_KEY)).find((url) => url !== void 0);
 }
+function section_groups(lines) {
+  const groups = [];
+  for (const line of lines) {
+    if (is_section_header(line)) groups.push([line]);
+    else groups.at(-1)?.push(line);
+  }
+  return groups;
+}
+function parse_remote_urls_from_config(content) {
+  const lines = content.split("\n").map((line) => line.trim());
+  return section_groups(lines).filter((group) => REMOTE_SECTION.test(group[0] ?? "")).flatMap((group) => group.map((line) => entry_value(line, URL_KEY))).filter((url) => url !== void 0);
+}
 function format_identity(identity) {
   return `${identity.owner}${PATH_SEPARATOR2}${identity.repo}`.toLowerCase();
 }
@@ -1756,6 +1781,7 @@ var repo_origin = {
   is_github_ssh_host,
   parse_origin_from_config,
   parse_origin_url,
+  parse_remote_urls_from_config,
   format_identity
 };
 

package/dist/version/index.js

@@ -1160,7 +1160,11 @@ function read_release_times(package_name) {
   const parsed = times_schema.safeParse(read_packument(package_name, FULL_ACCEPT));
   return parsed.success ? parsed.data.time : void 0;
 }
-var npm_registry = { packument_url, read_latest, read_release_times };
+function has_public_version(package_name, version) {
+  const parsed = times_schema.safeParse(read_packument(package_name, FULL_ACCEPT));
+  return parsed.success && parsed.data.time[version] !== void 0;
+}
+var npm_registry = { has_public_version, packument_url, read_latest, read_release_times };
 
 // scripts/version/version-remote.ts
 var TIMES_PAGE_SIZE = 100;

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1136.0",
+  "version": "1.1178.0",
   "name": "@joshuafolkken/kit",
   "description": "Development toolkit for AI-assisted projects: formatting, AI assistant rules and a Git/GitHub Issue workflow for any repository, plus lint, type check, tests and hooks for Node projects",
   "keywords": [
@@ -94,6 +94,7 @@
     "!scripts/exports/namespace-members.ts",
     "!scripts/exports/unused-members.ts",
     "!scripts/document/generate-catalog.ts",
+    "!scripts/document/issue-citation-budget.ts",
     "!scripts/document/retired-phrases.ts",
     "!scripts/document/review-agent-type.ts",
     "!scripts/document/single-source.ts",

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

@@ -2,7 +2,7 @@
 
 `CLAUDE.md` →「Never carry a file's new text inside a shell command.」の正典。
 
-`pnpm josh rule:guard`（file-body の行）が、既存ファイルを書き戻すヒアドキュメント・書き込みを伴うインタプリタ heredoc / `node -e`・in-place `perl -0pi -e` をその呼び出しで拒否し、規則を述べる。**このファイルが担うのはガードに見えないもの**である — Bash を通らない Edit / Write の全文書き直し、ガードを素通りする `sed -i` の 4 条件、そしてコストである。
+`pnpm josh rule:guard`（file-body の行）が、既存ファイルを書き戻すヒアドキュメント・書き込みを伴うインタプリタ heredoc / `node -e`・書き込むスクリプトファイルを作るヒアドキュメント・in-place `perl -0pi -e` を、コマンドの何行目にあってもその呼び出しで拒否し、規則を述べる。**このファイルが担うのはガードに見えないもの**である — Bash を通らない Edit / Write の全文書き直し、ガードを素通りする `sed -i` の 4 条件、そしてコストである。
 
 ### 何を禁じているか
 
@@ -38,7 +38,7 @@ PY
 
 - **新規ファイルの作成** — 既存本文が無いので、運ぶ重複がそもそも発生しない
 - **ファイル全体の作り直し** — 構成の組み替えや生成物の再生成で、変更後の本文が元の本文とほとんど共有しない場合
-- **部分編集のほうが大きくなる場合** — 変更箇所がファイル全域に散っていて、`old_string` / `new_string` の合計が全文を超えるとき
+- **部分編集のほうが大きくなる場合** — 変更箇所がファイル全域に散っていて、`old_string` / `new_string` の合計が全文を超えるとき。このときも全文は **Write ツール**で書く — ヒアドキュメントやインタプリタで書き戻す形は、この例外でもガードに拒否される
 
 **レビュー指摘の修正がこの規則の主戦場である。** 「この行の条件が逆」「この定数を切り出す」といった局所的な指摘ほど、部分編集は小さくなる。一方で全文書き直しのコストはファイルの大きさで決まり、指摘の小ささでは下がらない。**指摘が局所的であるほど、全文書き直しとの差は開く。**
 
@@ -55,14 +55,15 @@ PY
 
 **4 条件のどれかが面倒に見えたら、そこが Edit を使う場所である。** `sed` はコストを下げるための例外であって、既定の編集手段ではない。
 
-| 形                                            | 可否         | 理由                                                      |
-| --------------------------------------------- | ------------ | --------------------------------------------------------- |
-| Edit（数行の old / new）                      | 可           | 差分だけが本文に載る                                      |
-| `sed -i` の短い置換                           | 条件付きで可 | パターンと置換語しか載らない。上の 4 条件を満たすこと     |
-| `python3 - <<'PY'` で領域を書き戻す           | 不可         | 置換後の本文が丸ごと載る                                  |
-| `cat > file <<'EOF'` で既存ファイルを書き直す | 不可         | 同上                                                      |
-| `cat > new-file <<'EOF'` で新規ファイルを作る | 可           | 既存本文を運んでいない。ただし長文なら Write のほうが安い |
-| 読み取り・検索（`cat` / `sed -n` / `grep`）   | 可           | 本文を運ばない                                            |
+| 形                                                 | 可否         | 理由                                                      |
+| -------------------------------------------------- | ------------ | --------------------------------------------------------- |
+| Edit（数行の old / new）                           | 可           | 差分だけが本文に載る                                      |
+| `sed -i` の短い置換                                | 条件付きで可 | パターンと置換語しか載らない。上の 4 条件を満たすこと     |
+| `python3 - <<'PY'` で領域を書き戻す                | 不可         | 置換後の本文が丸ごと載る                                  |
+| `cat > file <<'EOF'` で既存ファイルを書き直す      | 不可         | 同上                                                      |
+| `cat > new-file <<'EOF'` で新規ファイルを作る      | 可           | 既存本文を運んでいない。ただし長文なら Write のほうが安い |
+| `cat > edit.py <<'EOF'` で書き込むスクリプトを作る | 不可         | 実行を 1 呼び出し後ろにずらしただけで、置換後の本文が載る |
+| 読み取り・検索（`cat` / `sed -n` / `grep`）        | 可           | 本文を運ばない                                            |
 
 ### なぜコストが二重になるか
 

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

@@ -32,10 +32,8 @@ egress が `403` で拒否されるため、GraphQL を経由するサブコマ
 - **引用の形**（そのままでよい）— 「`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` のマーカーテストで押さえる。
+**この区別は機械には引けない** — 文書ガードはフェンス付きコードブロックだけを走査するので、散文の側は
+書き手がこの区別で守る（`docs/maintainers/gh-rest-rationale.md` → "Why the document guard scans fences only"）。
 
 **書き換えるときは `pnpm josh` のコマンドで置き換えられないかを先に見る。** 例えば Issue の状態を読むのは
 `gh issue view` ではなく `pnpm josh issue:state <N>` で、これはラベルと `human_review` まで一度に返す。

package/prompts/collaboration-workflow/glossary.md

@@ -14,4 +14,4 @@
 - **interrupt** — WIP 上限を超えても起票できる、3 条件で決まる発見。別パッケージ起因の上流起票（割り込み Issue）とは別の区分。→ `prompts/collaboration-workflow/wip-cap.md` → "割り込み起票"、`prompts/collaboration-workflow/upstream-interrupt.md` → "別パッケージ起因の問題は割り込み Issue で対応する"
 - **Tier** — 判断点の 3 区分。A は可逆で自分で決める、B は拮抗していて人に聞く、C は不可逆・共有状態で明示指示が要る。→ `CLAUDE.md` → "Decision autonomy"、`prompts/collaboration-workflow/operating-rules.md` → "意思決定の自律ポリシー"
 - **carry** — `backlogrun` の 1 回の起動の予算と進捗を、セッション cut をまたいで引き継ぐ記録（`pnpm josh run:carry`）。→ `.claude/skills/workflow-commands/backlogrun-steps.md` → "The session cut is inside the invocation"
-- **wave** — エピックの子をまとめて並行実行する組。仕組みではなく、依存宣言で表す形。→ `.claude/skills/epic-commands/SKILL.md` → "Execution waves"
+- **wave** — エピックの子をまとめて並行実行する組。仕組みではなく、依存宣言で表す形。→ `.claude/skills/epic-commands/execution-waves.md` → "Execution waves — parallel, then one alone, then the rest"

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

@@ -2,7 +2,7 @@
 
 ## セッション向け出力で Issue はリンク＋セッション言語の短い要約で参照する（joshuafolkken/kit#1758）
 
-セッション向けの出力で Issue を指すとき、番号だけを書くと読み手は何の話か判断できず、番号を内容に解決するために毎回 GitHub を開くことになる。実際、実行中の backlogrun の報告が番号の羅列になり、オーナーから「番号だけ言われても詳細がわからない」という指摘を受けた。配布ドキュメントは Issue / PR の**タイトル**を英語に固定しているが、**セッション向け出力の中で Issue をどう言及するか**は定めていなかったため、番号だけの言及が規則に反しない状態だった。
+番号だけの言及では、読み手は番号を内容に解決するために毎回 GitHub を開くことになる（`docs/maintainers/issue-citation-rationale.md` → "Why the rule exists"）。発火点が `CLAUDE.md` に常駐している理由は `docs/maintainers/issue-citation-rationale.md` → "Why the trigger is resident in CLAUDE.md" にある。
 
 **規則**: セッション向け出力で Issue を指すときは、次の 2 つを必ず添える。
 
@@ -13,11 +13,11 @@
 
 - `[#<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` を参照。
+**この引用行は手で組み立てるものではなく、`pnpm josh issue:cite <N> [<N> ...]` が出す。** 番号を並べて渡すと、貼れる引用行を 1 呼び出しでまとめて出す（複数 Issue に 1 回、他リポジトリは `--repo <owner/repo>` あるいは `owner/repo#N` 表記。`docs/maintainers/issue-citation-rationale.md` → "Why issue:cite prints the line"）。要約はその Issue のタイトルをそのまま用いる。詳細は [docs/josh-commands.md](https://github.com/joshuafolkken/kit/blob/main/docs/josh-commands.md) の `josh issue:cite` を参照。
 
 **要約タイトルは全訳ではなく要約でよい。** 何をするものか分かれば足りる。長い訳を作ることが目的ではない。`issue:cite` が出すタイトルを、必要ならセッション言語に言い換えて使う。
 
-**対応前の言及も対象である。** 「これから走らせる」「待機中」「対象外」を並べる場面こそ、読み手が内容を知らないまま番号を読むことになるため、事後の報告だけを対象にすると指摘の半分しか解決しない。
+**対応前の言及も対象である。** 「これから走らせる」「待機中」「対象外」を並べる場面も含む。
 
 ### 適用範囲
 
@@ -27,12 +27,8 @@
 
 ### 英語固定の 3 つとは衝突しない
 
-英語のままにするものは従来どおり 3 つ — Issue / PR のタイトル、コード内コメント・テスト名・コミットメッセージ、スクリプトが出力する固定文字列。この規則が変えるのは、セッション向け出力の地の文における言及の書き方だけである。番号に添えるセッション言語の要約は GitHub 上の**タイトル**ではなく、セッション内の散文の一部なので、タイトルの英語固定とは別物であり矛盾しない。
-
-### なぜ CLAUDE.md に常駐させるか
-
-規則の発火点は「セッション向け出力で Issue 番号を書こうとした瞬間」であり、これはワークフローのスキルを読んでいないターンでも起こる。したがって発火点（引き金）と形式は `CLAUDE.md` の Communication 節に常駐させ、本文（この節）を話題ファイルに置く。常駐側は短く保ち、詳細はここから読む。
+英語のままにするものは従来どおり 3 つ（`overview.md` →「出力の言語（`JOSH_SESSION_LANG`）」）。番号に添えるセッション言語の要約は GitHub 上の**タイトル**ではなく、セッション内の散文の一部なので、タイトルの英語固定とは矛盾しない。
 
 ### 停止時の担保（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` を参照。
+`Stop` フック `pnpm josh stop:guard` が返信の地の文に裸の `#N` を見つけると**停止をブロックし**、その番号と `pnpm josh issue:cite <N...>` の実行形を差し戻す。差し戻されたら、その実行形で引用し直す（仕組みは `docs/maintainers/issue-citation-rationale.md` → "How the Stop hook delivers it"）。検出が外す範囲は [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

@@ -2,7 +2,7 @@
 
 Issue には次の要素を必ず含める。
 
-- タイトルは簡潔で明瞭な英語で記載する（本文やコメントと違い、タイトルは「出力の言語（`JOSH_SESSION_LANG`）」の例外として常に英語。日本語で作成した場合は、AIツールが実装開始前に英語タイトルへ変換する。すでに英語で書かれている場合でも、文法・明確さ・簡潔さの観点で改善できるなら書き換えて良い。いずれの場合も GitHub Issue のタイトルを `gh api -X PATCH repos/{owner}/{repo}/issues/<N> -f title="<title>"` で合わせて更新する）
+- タイトルは簡潔で明瞭な英語で記載する（「出力の言語（`JOSH_SESSION_LANG`）」の例外）。日本語のタイトルや改善できる英語のタイトルは、実装開始前に書き換え、`gh api -X PATCH repos/{owner}/{repo}/issues/<N> -f title="<title>"` で GitHub 側も合わせる
 - 目的（何を改善したいか）
 - 現象（現在の不具合や課題）
 - 期待結果（完了時の状態）
@@ -32,17 +32,17 @@ Issue には次の要素を必ず含める。
 
 ## 発火点
 
-<AI の振る舞いを変える Issue のみ。その規則が破れる瞬間に最初に呼ばれるツールコール名を 1 つだけ書く（例 `Bash` / `Edit` / `Read` / `Write` / `AskUserQuestion`）。配送表に載らない名前は、フックで配送できない発火点として印字される>
+<AI の振る舞いを変える Issue のみ。その規則が破れる瞬間に最初に呼ばれるツールコール名を 1 つだけ書く（例 `Bash` / `Edit` / `Read` / `Write` / `AskUserQuestion`）>
 
 ## ベースライン
 
-<AI の振る舞いを変える Issue のみ。測定コマンドと現在の値を「コマンド + 値」で書く。自然文の測定説明は再実行できないため受け付けない>
+<AI の振る舞いを変える Issue のみ。「コマンド + 値」で書く>
 
 - `<測定コマンド>` → <現在の値>
 
 ## 再現
 
-<AI の振る舞いを変える Issue のみ。現象を再現したコマンドとその実際の出力を「コマンド + 出力」で書く。自然文は再実行できないため不可。出力はフェンス（``` または ~~~）で囲む>
+<AI の振る舞いを変える Issue のみ。「コマンド + 実際の出力」で書き、出力はフェンス（``` または ~~~）で囲む>
 
 - `<再現コマンド>`
 
@@ -55,36 +55,26 @@ Issue には次の要素を必ず含める。
 <別リポジトリのセッションから起票した場合のみ。起票元 Issue を `owner/repo#N` 形式で書く。自リポジトリ発の Issue では節ごと省略する>
 ````
 
-### 振る舞い変更 Issue の宣言と 3 つの必須見出し（`## 発火点` / `## ベースライン` / `## 再現`）
+### `## 背景` 直下の宣言と分類ラベル
 
-**AI の振る舞いを変えると主張する Issue は、`## 発火点` と `## ベースライン` と `## 再現` の 3 見出しを必ず含める。** 散文の規則は「配って終わり」になりやすく、効いたかどうかがマージ後に読み直されないためである（joshuafolkken/kit#2178）。読みだけを根拠にした起票（既に直った現象の起票・壊れたままの現象の誤読）を防ぐため、再現の実測も課す（joshuafolkken/kit#2353）。
+起票は `pnpm josh issue:file "<title>" --body-file <本文ファイル> --depth <n>` で行う。本文の検査（`pnpm josh issue:lint <path>` と同じ）と、下表の宣言から決まる分類ラベルの付与は、このコマンドが 1 回の作成リクエストで行う。**宣言を選ぶのは起票者の判断であり、コマンドは単語から推測しない。**
 
-- **対象かどうかは本文の宣言から読み、判断させない。** 本文に `- 種別: 振る舞い変更` の行がある Issue だけが対象で、コードだけを変える Issue（`- 種別: コードのみ`、または振る舞い変更の宣言なし）には 3 見出しを課さない。宣言は `## 背景` の直下に置く
+| 宣言                   | 付くラベル        | 選ぶ基準                                                                                   |
+| ---------------------- | ----------------- | ------------------------------------------------------------------------------------------ |
+| `- 種別: 不具合`       | `bug`             | 報告された症状を直す。`- 種別: 非不具合` とどちらか一方を必ず置く                          |
+| `- 目的: 機能追加`     | `enhancement`     | 新しい機能。不具合修正・文書のみ・依存更新・保守作業には書かない                           |
+| `- 目的: 機能改善`     | `enhancement`     | 既存機能の改善。目的が曖昧なら期待結果と受け入れ条件を具体化してから選ぶ                   |
+| `- 互換性: 破壊的変更` | `breaking-change` | 既存の利用者・API・設定の契約を変える。移行措置があっても書き、廃止対象と影響を説明する    |
+| `- 種別: 振る舞い変更` | なし              | AI の振る舞いを変える。`## 発火点` / `## ベースライン` / `## 再現` の 3 見出しが必須になる |
 
-  ```md
-  ## 背景
-
-  - 種別: 振る舞い変更
-
-  <なぜ必要か>
-  ```
-
-- **起票前に不具合かどうかを必ず選ぶ。** `## 背景` の直下に、不具合なら `- 種別: 不具合`、非不具合なら `- 種別: 非不具合` を置く。両方の併記も省略も `pnpm josh issue:lint` が拒否する。故障を述べる本文でも単語から自動判定せず、起票者が判断する。振る舞い変更、機能改善、互換性の宣言はこの判断と併記できる
-- **不具合修正の Issue は `- 種別: 不具合` を宣言する。** この宣言がある Issue では、`pnpm josh git -y` が追加・変更したテストを修正前のツリー（merge-base）に当てて `pnpm josh test:red` で実行し、1 本も赤にならない（`green`）ときはコミットを拒否する。修正前でも緑の回帰テストは、報告された症状を再現していないためである（joshuafolkken/kit#2448）。回帰テストは、利用者が症状を見たのと同じ粒度で書く
-- **起票時の `bug` ラベルは本文の宣言から決める。** 起票は `pnpm josh issue:file "<title>" --body-file <本文ファイル> --depth <n>` で行い、このコマンドが `issue:lint` と同じ検査をしたうえで、`- 種別: 不具合` の宣言があれば `bug` ラベルを同じ作成リクエストに付ける。`depth`・`route` も同じ呼び出しで付く。`bugfix` は PR のリリース分類であり、Issue の `bug` の代わりにしない
-- **機能追加・機能改善は目的を本文で宣言する。** `## 背景` の直下に `- 目的: 機能追加` または `- 目的: 機能改善` を書く。この宣言があれば `pnpm josh issue:file` が `enhancement` ラベルを同じ作成リクエストに付ける。不具合修正、文書のみ、依存更新、保守作業はタイトルの単語から推測して宣言しない。目的が曖昧なら起票文案の期待結果と受け入れ条件を具体化してから分類する
-- **互換性を壊す変更は影響を本文で宣言する。** 既存の利用者、API、設定の契約を変える場合は、`## 背景` の直下に `- 互換性: 破壊的変更` を書き、廃止対象と影響を説明する。移行措置や事前案内があっても破壊的変更なら宣言する。この宣言があれば `pnpm josh issue:file` が `breaking-change` ラベルを同じ作成リクエストに付ける。互換性を保つ変更には付けない。影響が曖昧なら起票文案で対象の利用者と契約を明確にしてから分類する
-- **本文が宣言する分類ラベルは `pnpm josh issue:file` がすべて起票時に付ける。** `bug`、`enhancement`、`breaking-change` は組み合わせて付くことがある。`depth`・`route` などのラベルと併せて 1 回の作成リクエストで付け、宣言が無いとき（`issue:lint` の `labels: none`）は分類ラベルを付けない。Issue が `enhancement` と `breaking-change` の両方を持つとき、PR のリリース分類は `breaking-change` 一つにする。Issue の目的の分類と PR のリリース分類を区別する
-- **`## 発火点`** には、その規則が破れる瞬間に最初に呼ばれるツールコール名を 1 つ書く。名前は `prompts/collaboration-workflow/rule-delivery.md` の配送表に載る、フックで配送可能なツール（`Bash` / `Edit` / `Read` / `Write` / `AskUserQuestion`）と突き合わせる。**表に無い名前**（そもそもツールコール名でない）と**不一致**（既知のツールだが配送できない）は区別して印字され、joshuafolkken/kit#2201 の「規則は正しいが名指ししたコールが実際に破れるコールの 1 つ後ろ」を起票時に検出する
-- **`## ベースライン`** は **「コマンド + 値」** で書く。``- `<測定コマンド>` → <現在の値>`` の形に限り、自然文だけの測定説明は受け付けない（再実行できないため）。マージ後に `pnpm josh measure:rerun <N>` が同じコマンドをやり直し（本文は shell として実行されるため、作者が `OWNER` / `MEMBER` / `COLLABORATOR` の Issue に限る）、**before / after の対**を印字する。値が動かなかったとき、反証された前提として `docs/maintainers/observations/` の、その時点のブランチが指す Issue のファイルに 1 行追記される（既存の append-only 台帳を使い、別の台帳は作らない）
-- **`## 再現`** は **「コマンド + 実際の出力」** で書く。コマンドを backtick、出力をフェンス（``` または ~~~）で囲む。自然文の「確認した」は再実行できないため受け付けない（`## ベースライン` と同じ理由）。読みだけの起票を起票時に弾くためである
-- **検査は `pnpm josh issue:lint <path>` が行う。** 対象判定・3 見出しの有無・発火点の配送可否・ベースラインが「コマンド + 値」か・再現が「コマンド + 実際の出力」かと、起票時に必要な分類ラベルを、起票前の本文ファイルからまとめて答える（`pnpm josh issue:file` は起票前に同じ検査を行い、問題があれば起票しない）
+- **`- 種別: 不具合` の Issue の回帰テストは、利用者が症状を見たのと同じ粒度で書く。** 修正前のツリーでも緑になるテストは `pnpm josh git -y` がコミットを拒否する（joshuafolkken/kit#2448）
+- **`bugfix` は PR のリリース分類であり、Issue の `bug` の代わりにしない。** `enhancement` と `breaking-change` の両方を持つ Issue の PR は `breaking-change` 一つに分類する
+- **`## 発火点`** の名前は `prompts/collaboration-workflow/rule-delivery.md` の配送表と突き合わされる
+- **`## ベースライン`** の測定コマンドは、マージ後に `pnpm josh measure:rerun <N>` が再実行して before / after を印字する（作者が `OWNER` / `MEMBER` / `COLLABORATOR` の Issue に限る）
 
 ### 起票元へのバックリンク（`## Origin` / `## Upstream issues`）
 
-**別リポジトリのセッションから起票した Issue には、起票元へのリンクを必ず書く。** 上流 Issue は欠陥そのものを述べるが、その欠陥が「どのプロジェクトで・どのバージョンの組み合わせで・どんな出力として現れたか」という証拠は消費者側の Issue にしかない。リンクはその証拠へ戻る唯一の経路であり、半年後にその Issue を読む人にとっては本文と同じだけ重要である。
-
-**双方向とも必須**（片方向では、上流の修正を待っている消費者側が「何を待っているのか」を辿れない）:
+**別リポジトリのセッションから起票した Issue には、起票元へのリンクを双方向で必ず書く。** 欠陥がどのプロジェクトでどう現れたかの証拠は起票元にしかない。
 
 | 方向                  | 置き場所                      | 固定見出し              | 内容                                                 |
 | --------------------- | ----------------------------- | ----------------------- | ---------------------------------------------------- |
@@ -92,106 +82,41 @@ Issue には次の要素を必ず含める。
 | 起票元 Issue → 上流   | 起票元 Issue の本文かコメント | `## Upstream issues`    | そこから起票した上流 Issue を全件列挙する            |
 | 起票元 Issue → 未起票 | 起票元 Issue の本文かコメント | `## Upstream candidate` | 第三者リポジトリへ報告する候補（**未起票**）と下書き |
 
-- **見出しは固定する**。「書いた人が置いた場所」ではなく grep で機械的に見つかるようにするため。起票元 Issue 側は、その場で本文を書いている最中なら本文に、既に本文が確定しているなら同じ見出しでコメントに書く
-- **リンクは必ずリポジトリ修飾する**（`owner/repo#N` または完全 URL）。**裸の `#N` を使ってはならない** — 上流リポジトリ内では同番号の別 Issue に解決され、黙って誤ったものを指す
-- **チェックボックス行（`- [ ] owner/repo#N`）で書いてはならない。散文か素の箇条書き（`- owner/repo#N`）にする。** `scripts/epic/epic-parse.ts` の `has_external_task_list_entry` は「チェックボックス付きで他リポジトリを参照する行」を検出すると epic の自動クローズを無効化する。これは**本物の他リポジトリ子 Issue に対しては正しい挙動**（その状態は別リポジトリを指定しないと読めないため）だが、単なる後方参照をその記法で書くと epic が永久に open のまま残る。判定はチェックボックスの有無だけを見るので、素の箇条書きは安全である
-- **未起票の候補には `## Upstream candidate` を使い、`## Upstream issues` を使わない**。後者は「既に起票した」ことを主張する見出しであり、third-party リポジトリへの報告はユーザーの明示指示があるまで起票しないため、両者は必ず別の見出しに置く（→「第三者リポジトリへの書き込みは Tier C（明示指示が必要）」）
-- 割り込みで起票する場合の手順は「別パッケージ起因の問題は割り込み Issue で対応する」、分割で起票する場合は下記 epic 節を参照
+- **見出しは固定する**（grep で見つかるように）。起票元の本文が確定済みなら、同じ見出しでコメントに書く
+- **リンクは必ずリポジトリ修飾する**（`owner/repo#N` または完全 URL）。裸の `#N` は上流側で別 Issue に解決される
+- **チェックボックス行（`- [ ] owner/repo#N`）で書かない。** 散文か素の箇条書き（`- owner/repo#N`）にする — チェックボックス付きの他リポジトリ参照は epic の自動クローズを止める
+- **未起票の候補は `## Upstream candidate` に置く。** third-party への報告はユーザーの明示指示まで起票しない（→「第三者リポジトリへの書き込みは Tier C（明示指示が必要）」）
+- 割り込みで起票する手順は `upstream-interrupt.md`
 
 ### 複数 Issue に分割するときの epic Issue
 
-`kickoff new` が 1 つの要望を **2 件以上**の Issue に分割したとき、**常に**それらを束ねる epic Issue を作成する。件数や実行順序の有無で分岐しない。
+**1 つの要望を 2 件以上の Issue に分割したら、件数や順序の有無にかかわらず常に epic を作る。** 分割の設計図を、最初にクローズされる子 Issue ではなく閉じない置き場に残すためである。作成は `pnpm josh epic`、点検は `pnpm josh epic:check <E>`、子の追加は `pnpm josh epic --add` で行い、本文を手で編集しない。epic 自体を実装ランに渡さない（`backlogrun #<E> --only` が子を回す）。コマンドと本文の記法は `epic-commands` スキル →「Creating an epic」。
 
-なぜ必要か: 分割の根拠を「最初の Issue のコメント」に置くと、その Issue はバッチが最初にマージしてクローズする対象でもあるため、残りの作業の設計図がクローズ済み Issue の中に埋もれる。epic の役割は、その情報の**閉じない置き場**を用意することにある。実行順序は epic が載せられる情報の一つであって、epic が存在する理由ではない。埋没は順序の有無と無関係に、複数分割のたびに起きる。
+**`josh` が使えない環境での手作業手順:**
 
-- **条件分岐を置かない。** 「件数が少ないうちは epic の管理コストが情報整理の利益を上回る」という以前の但し書きは、`scripts/epic/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 を作る以上、依存関係ゼロ件は正常な状態でもありうる
+1. 子 Issue をすべて起票し、番号を控える。
+2. ラベルを用意する: `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 を作り、`id` ではなく **number** を控える: `gh api repos/{owner}/{repo}/issues -f title="<epic-title>" -f 'labels[]=epic' -F body=@<body-file> --jq .number`。本文は次の形にする（順序がなければ `Dependencies` に `None — the children are independent; any execution order works.` と書く）:
 
-作成手順（既定）: **`pnpm josh epic` を使う。**
+   ```md
+   ## Split rationale
 
-```bash
-# 順序不問のバッチ
-pnpm josh epic "<epic-title>" <N1> <N2> ...
+   <why this split>
 
-# 実行順序があるバッチ（引数の並び順＝依存順）
-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>
-```
+   ## Dependencies
 
-このコマンドは上記 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 とタスクリストは既に正しい）。
+   #101 -> #102
 
-作成済みの epic は `pnpm josh epic:check <E>` で 4 要件を点検できる。手書きした epic、コマンド導入以前の epic、本文を手で編集した後の確認に使う。全要件を満たせば exit 0、満たさなければ exit 1 なのでゲートとしても使える。判定は自動クローズが読むのと**同じパーサ**（`scripts/epic/epic-parse.ts`）を使うため、「自動クローズが読める形式」と「点検が通る形式」は定義上一致する。
+   ## Execution
 
-作成手順（フォールバック）: **`josh` が使えない環境でのみ**、以下を手で行う。
+   backlogrun #<E> --only
 
-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-file> --jq .number`（`--jq` を落とすと Issue の JSON 全体が出る。そこには `id` も含まれるが、**控えるのは `number` である** — `id` はデータベース id で、手順 4 が要求する値ではあっても epic の番号ではない）
-4. 実行順序が**ある場合のみ**、子 Issue に依存関係を付与する（後述の理由により**作成後の独立ステップ**として行う）:
+   ## Progress
 
-   ```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)"
+   - [ ] #101 <title>
+   - [ ] #102 <title>
    ```
 
-   **エンドポイントが受け取るのは 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` 行は、関係が付かなかった場合でも読める冗長な記録として残す。
+4. 順序があるときだけ、別ステップで依存を足す（Issue 番号ではなく database id を渡す）: `gh api repos/{owner}/{repo}/issues/<N2>/dependencies/blocked_by -F issue_id="$(gh api repos/{owner}/{repo}/issues/<N1> --jq .id)"`
 
-**sub-issues（親子関係）は採用しない。** 理由は 2 点 — 親子関係は「包含」を表すだけで実行順序を表現できない、および親子関係は同一リポジトリオーナー内に限られる。いずれも CLI の対応状況とは無関係で、2.94.0 以降でも変わらない。
+各手順の理由と経緯は kit の `docs/maintainers/epic-commands-rationale.md` →「Creating an epic by hand」。