@joshuafolkken/kit 1.1050.0 → 1.1094.0

package/dist/version/index.js

@@ -66,6 +66,19 @@ import { existsSync, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 
+// scripts/lib/json-value.ts
+function parse_or_undefined(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+function is_record(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var json_value = { parse_or_undefined, is_record };
+
 // scripts/lib/schemas.ts
 import { z } from "zod";
 var overrides_snapshot_schema = z.record(z.string(), z.string());
@@ -98,22 +111,13 @@ var json_object_schema = z.record(z.string(), z.unknown());
 var string_array_schema = z.array(z.string());
 var string_record_schema = z.record(z.string(), z.string());
 
-// scripts/version/parse-json.ts
-function safe_json_parse(raw) {
-  try {
-    return JSON.parse(raw);
-  } catch {
-    return void 0;
-  }
-}
-
 // scripts/version/effective-upstream.ts
 var PACKAGE_JSON = "package.json";
 var MAX_WALK_DEPTH = 64;
 function read_matching_version(manifest_path, package_name) {
   if (!existsSync(manifest_path)) return void 0;
   const parsed = package_named_version_schema.safeParse(
-    safe_json_parse(readFileSync(manifest_path, "utf8"))
+    json_value.parse_or_undefined(readFileSync(manifest_path, "utf8"))
   );
   if (!parsed.success) return void 0;
   if (parsed.data.name !== package_name) return void 0;
@@ -258,13 +262,9 @@ function build_release_hold_notes(version, latest, installable, minimum_age_minu
   return [format_release_hold_note(version, latest, installable, minimum_age_minutes)];
 }
 var release_hold = {
-  HOLD_LABEL,
-  is_at_or_above,
-  is_latest_withheld,
   resolve_installable,
   is_release_age_hold,
   format_window,
-  format_release_hold_note,
   build_release_hold_notes
 };
 
@@ -283,7 +283,7 @@ function read_running_version(self_directory) {
   const package_path = resolve_self_package_path(self_directory);
   if (!existsSync2(package_path)) return void 0;
   const parsed = package_version_schema.safeParse(
-    safe_json_parse(readFileSync3(package_path, "utf8"))
+    json_value.parse_or_undefined(readFileSync3(package_path, "utf8"))
   );
   return parsed.success ? parsed.data.version : void 0;
 }
@@ -463,19 +463,23 @@ var version_check_logic = {
   format_dual_version_output,
   format_running_line,
   format_upstream_lines,
-  format_upstream_global_line,
   build_dual_upgrade_commands,
   build_upstream_upgrade_commands,
   build_upstream_upgrade_notes,
   build_effective_upgrade_commands,
   build_effective_upgrade_notes,
-  build_project_upgrade_commands,
   format_update_command,
   format_effective_outcome,
   build_upgrade_shell_command,
   unique_upgrade_commands
 };
 
+// scripts/git/git-execa-error.ts
+function has_timed_out(error) {
+  if (typeof error !== "object" || error === null || !("timedOut" in error)) return false;
+  return error.timedOut === true;
+}
+
 // scripts/josh/agent-session-environment.ts
 var SESSION_ID_KEY = "CLAUDE_CODE_SESSION_ID";
 var PARENT_SESSION_KEYS = [
@@ -563,22 +567,19 @@ function message_of(error) {
 }
 var error_text = { message_of };
 
-// scripts/git/git-gh-exec.ts
+// scripts/gh/git-gh-exec.ts
 import { execa as execa2, execaSync } from "execa";
 
-// scripts/git/git-execa-error.ts
-function has_timed_out(error) {
-  if (typeof error !== "object" || error === null || !("timedOut" in error)) return false;
-  return error.timedOut === true;
-}
+// scripts/lib/timeouts.ts
+var COMMAND_TIMEOUT_MS = 3e4;
 
-// scripts/git/git-gh-check.ts
+// scripts/gh/git-gh-check.ts
 import { execa } from "execa";
 var GH_NOT_INSTALLED_MSG = "gh CLI is not installed. Install it from https://cli.github.com/";
 var gh_check = {};
 async function run_gh_check() {
   try {
-    await execa("gh", ["--version"]);
+    await execa("gh", ["--version"], { timeout: COMMAND_TIMEOUT_MS });
   } catch {
     delete gh_check.promise;
     throw new Error(GH_NOT_INSTALLED_MSG);
@@ -589,9 +590,6 @@ async function check_gh_installed() {
   await gh_check.promise;
 }
 
-// scripts/git/git-gh-failure.ts
-import { z as z3 } from "zod";
-
 // scripts/git/parse-json-array.ts
 var MALFORMED_JSON = /* @__PURE__ */ Symbol("malformed-json");
 function parse_json_loose(raw_json) {
@@ -602,37 +600,17 @@ function parse_json_loose(raw_json) {
     throw error;
   }
 }
-function parse_json_array_or_undefined(raw_json, element_schema) {
-  const value = parse_json_loose(raw_json);
-  if (value === MALFORMED_JSON || !Array.isArray(value)) return void 0;
-  return element_schema.array().parse(value);
-}
-function read_json_listing(raw_json, element_schema) {
-  try {
-    const rows = parse_json_array_or_undefined(raw_json, element_schema);
-    return rows === void 0 ? { kind: "unreadable" } : { kind: "read", rows };
-  } catch {
-    return { kind: "unexpected_shape" };
-  }
-}
-function parse_json_array_safe(raw_json, element_schema) {
-  const value = parse_json_loose(raw_json);
-  if (value === MALFORMED_JSON) return [];
-  return element_schema.array().parse(value);
-}
 function parse_json_object_safe(raw_json, schema) {
   const value = parse_json_loose(raw_json);
   if (value === MALFORMED_JSON) return void 0;
   return schema.parse(value);
 }
 var parse_json = {
-  parse_json_array_safe,
-  parse_json_array_or_undefined,
-  parse_json_object_safe,
-  read_json_listing
+  parse_json_object_safe
 };
 
-// scripts/git/git-gh-failure.ts
+// scripts/gh/git-gh-failure.ts
+import { z as z3 } from "zod";
 var error_document_schema = z3.object({ status: z3.union([z3.string(), z3.number()]).optional() }).catch({});
 var GH_FAILURE_FIELD = "gh_failure";
 function has_gh_failure(error) {
@@ -660,7 +638,7 @@ function failure_of(error) {
 }
 var gh_failure = { attach, classify_stdout, failure_of, parse_response_status };
 
-// scripts/git/git-gh-exec.ts
+// scripts/gh/git-gh-exec.ts
 var BODY_FROM_STDIN = "-";
 var GH_REQUEST_TIMEOUT_MS = 6e4;
 function to_timeout_option(timeout_ms) {
@@ -1111,8 +1089,6 @@ var migrate_logic = {
   github_tarballs,
   is_github_tarball,
   rewrite_kit_lockfile,
-  registry_of,
-  scoped_packages,
   scoped_versions
 };
 
@@ -1146,7 +1122,7 @@ function read_packument(package_name, accept) {
     { reject: false, timeout: REQUEST_TIMEOUT_MS }
   );
   if (result.exitCode !== 0) return void 0;
-  return safe_json_parse(result.stdout);
+  return json_value.parse_or_undefined(result.stdout);
 }
 function is_github_scope(scope) {
   const is_cached_github = github_scopes.get(scope);
@@ -1211,7 +1187,7 @@ function read_github_release_times(versions_endpoint) {
   const endpoint = with_page_size(versions_endpoint, TIMES_PAGE_SIZE);
   const stdout = git_gh_exec.read_gh_api_sync({ path: endpoint, jq_filter: TIMES_JQ });
   if (stdout === void 0) return void 0;
-  const parsed = release_age.release_times_schema.safeParse(safe_json_parse(stdout));
+  const parsed = release_age.release_times_schema.safeParse(json_value.parse_or_undefined(stdout));
   return parsed.success ? parsed.data : void 0;
 }
 function fetch_release_times(versions_endpoint, package_name) {
@@ -1256,13 +1232,13 @@ function build_pnpm_ls_arguments(package_name) {
   return ["ls", "-g", "--json", package_name];
 }
 function parse_global_version(stdout, package_name) {
-  const parsed = pnpm_ls_global_schema.safeParse(safe_json_parse(stdout));
+  const parsed = pnpm_ls_global_schema.safeParse(json_value.parse_or_undefined(stdout));
   if (!parsed.success) return void 0;
   return parsed.data[0]?.dependencies?.[package_name]?.version;
 }
 function parse_project_version(raw) {
   if (raw === void 0) return void 0;
-  const parsed = package_version_schema.safeParse(safe_json_parse(raw));
+  const parsed = package_version_schema.safeParse(json_value.parse_or_undefined(raw));
   return parsed.success ? parsed.data.version : void 0;
 }
 function read_global_version(package_name) {

package/eslint/rules/promise.js

@@ -5,6 +5,11 @@ export const promise_rules = {
 	'promise/param-names': 'error',
 	'promise/no-nesting': 'error',
 
+	// ループ内で 1 つずつ await すると、独立した処理まで直列になる。Sonar の S9382 と同じ指摘を
+	// ローカルのゲートで先に出す。ポーリングや順序が意味を持つ処理など意図的な逐次は、
+	// `// eslint-disable-next-line no-await-in-loop -- <理由>` で理由を残して抑止する。
+	'no-await-in-loop': 'error',
+
 	// `promise-function-async` を有効にしている以上、`require-await` は同時に満たせない。
 	// Promise を返す契約の関数（execa モックなど）は async である必要がある一方、
 	// 実際に await する対象を持たないため `require-await` が必ず発火する。

package/package.json

@@ -1,11 +1,12 @@
 {
-  "version": "1.1050.0",
+  "version": "1.1094.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": [
     "ai",
     "claude-code",
     "cli",
+    "codex",
     "developer-tools",
     "eslint",
     "prettier",
@@ -85,12 +86,16 @@
     "!scripts/build/shim-shell.ts",
     "!scripts/claude/skill-meta.ts",
     "!scripts/document/document-scan.ts",
+    "!scripts/exports/member-usage.ts",
+    "!scripts/exports/namespace-escape.ts",
+    "!scripts/exports/namespace-members.ts",
+    "!scripts/exports/unused-members.ts",
     "!scripts/document/generate-catalog.ts",
     "!scripts/document/retired-phrases.ts",
     "!scripts/document/review-agent-type.ts",
     "!scripts/document/single-source.ts",
+    "!scripts/hooks/hook-bundle-ready.ts",
     "!scripts/hooks/prompt-hooks.ts",
-    "!scripts/init/hook-command-bootstrap.ts",
     "!scripts/josh/josh-script-reader.ts",
     "!scripts/package/production-dependency-graph.ts",
     "!scripts/rules/delivered-rules-harness.ts",
@@ -238,7 +243,7 @@
     "prettier": "^3.9.9",
     "prettier-plugin-svelte": "^4.1.1",
     "prettier-plugin-tailwindcss": "^0.8.1",
-    "rollup": "^4.63.6",
+    "rollup": "^4.64.0",
     "rollup-plugin-dts": "^6.5.1",
     "secretlint": "^13.0.6",
     "typescript": "^6.0.3",
@@ -263,7 +268,7 @@
     }
   },
   "scripts": {
-    "build": "tsx scripts/build/build-bin.ts && tsx scripts/build/build-hooks.ts && tsx scripts/build/build-version.ts && tsx scripts/build/build-config-merge.ts && tsx scripts/build/build-managed-marker.ts && tsx scripts/build/build-self-sync-guard.ts && tsx scripts/build/build-claude-md.ts",
+    "build": "tsx scripts/build/build-bin.ts && tsx scripts/build/build-hooks.ts && tsx scripts/build/build-version.ts && tsx scripts/build/build-config-merge.ts && tsx scripts/build/build-managed-marker.ts && tsx scripts/build/build-self-sync-guard.ts && tsx scripts/build/build-claude-md.ts && tsx scripts/build/build-codex-hooks.ts",
     "josh": "tsx scripts/josh/josh.ts"
   }
 }

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

@@ -1,13 +1,13 @@
-# セッション向け出力で Issue はリンク＋短い日本語要約で参照する
+# セッション向け出力で Issue はリンク＋セッション言語の短い要約で参照する
 
-## セッション向け出力で Issue はリンク＋短い日本語要約で参照する（joshuafolkken/kit#1758）
+## セッション向け出力で Issue はリンク＋セッション言語の短い要約で参照する（joshuafolkken/kit#1758）
 
 セッション向けの出力で Issue を指すとき、番号だけを書くと読み手は何の話か判断できず、番号を内容に解決するために毎回 GitHub を開くことになる。実際、実行中の backlogrun の報告が番号の羅列になり、オーナーから「番号だけ言われても詳細がわからない」という指摘を受けた。配布ドキュメントは Issue / PR の**タイトル**を英語に固定しているが、**セッション向け出力の中で Issue をどう言及するか**は定めていなかったため、番号だけの言及が規則に反しない状態だった。
 
 **規則**: セッション向け出力で Issue を指すときは、次の 2 つを必ず添える。
 
 1. 番号にチケットへの markdown リンク
-2. 短い日本語の要約タイトル
+2. セッション言語（`JOSH_SESSION_LANG`、既定 `ja`）の短い要約タイトル
 
 書き方の例:
 
@@ -15,7 +15,7 @@
 
 **この引用行は手で組み立てるものではなく、`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` が出すタイトルを、必要ならセッション言語に言い換えて使う。
+**要約タイトルは全訳ではなく要約でよい。** 何をするものか分かれば足りる。長い訳を作ることが目的ではない。`issue:cite` が出すタイトルを、必要ならセッション言語に言い換えて使う。
 
 **対応前の言及も対象である。** 「これから走らせる」「待機中」「対象外」を並べる場面こそ、読み手が内容を知らないまま番号を読むことになるため、事後の報告だけを対象にすると指摘の半分しか解決しない。
 
@@ -27,7 +27,7 @@
 
 ### 英語固定の 3 つとは衝突しない
 
-英語のままにするものは従来どおり 3 つ — Issue / PR のタイトル、コード内コメント・テスト名・コミットメッセージ、スクリプトが出力する固定文字列。この規則が変えるのは、セッション向け出力の地の文における言及の書き方だけである。番号に添える日本語要約は GitHub 上の**タイトル**ではなく、セッション内の散文の一部なので、タイトルの英語固定とは別物であり矛盾しない。
+英語のままにするものは従来どおり 3 つ — Issue / PR のタイトル、コード内コメント・テスト名・コミットメッセージ、スクリプトが出力する固定文字列。この規則が変えるのは、セッション向け出力の地の文における言及の書き方だけである。番号に添えるセッション言語の要約は GitHub 上の**タイトル**ではなく、セッション内の散文の一部なので、タイトルの英語固定とは別物であり矛盾しない。
 
 ### なぜ CLAUDE.md に常駐させるか
 

package/prompts/collaboration-workflow/operating-rules.md

@@ -30,8 +30,8 @@ PR マージ・ブランチ削除・force push・共有ブランチへの push
 - `fullrun` の auto-merge は `fullrun` の指示自体に含まれるため許可される（本文は [`followup.md`](../../.claude/skills/workflow-commands/followup.md)）。それ以外の状況で勝手にマージしてはならない
 - `kickoff` / `pnpm josh followup` 単独実行は文書化されたスコープで終了する。PR が OPEN のまま完了したら状態を報告して停止する
 - 「チェックが全部 green だから次のステップに進む」は承認ではない
-- **`gh pr merge` の直接実行は kit 配布の `.claude/settings.json` の `deny`（`Bash(gh pr merge*)`）で機械的に遮断されている。** `fullrun` の auto-merge は `pnpm josh followup` が node スクリプト内部から gh を起動するため影響を受けない — Bash マッチャに見えるのは `pnpm josh …` だけである。**ただし deny は実装であって規則ではない** — パターンが取りこぼす綴りを禁じているのは本節の規則のほうである
-- **同じ規則が禁じる force push とブランチ削除も deny に載っている**（joshuafolkken/kit#1062）。`Bash(git push *--force*)` / `Bash(git push * -f)` はフラグを引数の後ろに書いた綴りを、`Bash(git push *--delete*)` / `Bash(git branch -d*)` / `Bash(git branch -D*)` / `Bash(gh api *DELETE*git/refs/heads/*)` はブランチ削除を止める。**deny は規則より狭いが、その差は配送ガードが埋めている** — `git -C` を前置した綴り、短縮フラグをまとめた綴り（`git push -uf`）、`:` をリテラルにできず glob が照合できない `git push origin :branch` は、いずれも `pnpm josh rule:guard` の `git-force` 行が argv を解析して拒否する（joshuafolkken/kit#2120）。**「マージ経路は deny が保証している」とは読まないこと**
+- **`gh pr merge` の直接実行は kit 配布の `.claude/settings.json` の `permissions.deny` で機械的に遮断されている。** パターンの一覧はそのファイルが一次情報であり、ここでは書き写さない。 `fullrun` の auto-merge は `pnpm josh followup` が node スクリプト内部から gh を起動するため影響を受けない — Bash マッチャに見えるのは `pnpm josh …` だけである。**ただし deny は実装であって規則ではない** — パターンが取りこぼす綴りを禁じているのは本節の規則のほうである
+- **同じ規則が禁じる force push とブランチ削除も deny に載っている**（joshuafolkken/kit#1062）。**deny は規則より狭いが、その差は配送ガードが埋めている** — `git -C` を前置した綴り、短縮フラグをまとめた綴り（`git push -uf`）、`:` をリテラルにできず glob が照合できない `git push origin :branch` は、いずれも `pnpm josh rule:guard` の `git-force` 行が argv を解析して拒否する（joshuafolkken/kit#2120）。**「マージ経路は deny が保証している」とは読まないこと**
 - **共有状態に影響する操作（このセクションの対象＝Tier C）は迷ったら確認する。** 確認のコストは低いが、意図しない操作の巻き戻しは高コスト
 - ただしこの「迷ったら確認」は Tier C に限る。**可逆な実装・設計判断（Tier A）は別ルール**（下記「意思決定の自律ポリシー」）に従う
 
@@ -51,8 +51,8 @@ PR マージ・ブランチ削除・force push・共有ブランチへの push
 - **レーンの中で競合を解決したあとの「解決済み」の記録は、ケース 2 に含まれる（Tier A）。** レーンは run 専用の作業ツリーで、守るべき利用者の staging はない。利用者に `git add` の許可を求めず、`pnpm josh git -y` で記録する。手順は `.claude/skills/workflow-commands/chain-rule.md` →「origin/main is merged in before the gate」の 1 か所にだけ書く（joshuafolkken/kit#2445）
 - 同じ理由で、`git reset` / `git checkout -- <path>` / `git restore <path>` など index や作業ツリーを破壊的に書き換える操作も、自分の判断で実行しない
 - **`git stash` は例外的に、明文化されたフローの中でのみ自動実行してよい**: `fullrun new` / `halfrun new` の手順 5（作業ツリーに変更がある状態で `josh latest` を回す前の退避）、`backlogrun` のラン開始時の `josh latest`、「別パッケージ起因の問題は割り込み Issue で対応する」、および `backlogrun` が epic の子を始める前の preflight（`pnpm josh run:hold <N>` が `reclaim` と答えたときの回収 — joshuafolkken/kit#926, joshuafolkken/kit#1965）。**この 5 番目だけが復元を伴わない。前の 4 つはいずれも直後に `pnpm josh stash:pop "<メッセージ>"` で復元することが手順に含まれている**（stash はリポジトリ単位の 1 本のスタックを全 work tree が共有するため、位置指定や引数なしの `git stash pop` は別のレーンが最後に積んだ stash を取り込む — メッセージで対象を特定する。joshuafolkken/kit#2050）。 回収するのは異常終了したランの置き土産であって、いま実行中のランの作業ではないから、pop して戻す先がない。**代わりに stash を子の Issue にコメントで記録する** — 前提 Issue で中断するときの stash（`SKILL.md` §2d）と同じく、**その記録だけが後で pop させられる唯一の手がかり**であり、記録し忘れた stash は誰にも拾われない。これら以外の場面で退避したくなったときは、実行せずに先に確認する
-- **この禁止は kit 配布の `.claude/settings.json` の `deny`（`Bash(git add*)` / `Bash(git stage*)` / `Bash(git rm*)` / `Bash(git mv*)` / `Bash(git reset*)` / `Bash(git restore --staged*)` / `Bash(git restore -S*)` / `Bash(git commit*)`）で機械的にも遮断されている。** `pnpm josh git` は node スクリプト内部から git を起動するため影響を受けず、承認済みのコミットフロー（上記ケース 2）は従来どおり動く。**deny には「そのターンでユーザーが明示指示した」という例外がないため、上記ケース 1 も AI 側では実行できない** — その場合はユーザー自身の端末で実行してもらう。**ユーザーが明示的にコミットを指示した場合も同じで**、承認済みのコミットは `pnpm josh git` を通す（`git commit` まで deny に入れた理由は `docs/maintainers/operating-rules-rationale.md` → "Why the index is the user's"）
-- **「拒否される操作」と「禁止された操作」は同じ集合ではない。** deny に載っているのは上記の直接実行だけだが、このセクションが同じく禁じている `git checkout -- <path>` / `git restore <path>` / 認可外の `git stash`（bare・メッセージ無し push・位置指定 pop など。メッセージ付き `git stash push -m` と `pnpm josh stash:pop` は認可済みなので通る）は、`pnpm josh rule:guard` の `worktree-mutation` 行が拒否する（joshuafolkken/kit#2120）。**ツールが通したことを許可と読み替えてはならない** — 何をしてよいかを決めるのは deny でも配送ガードでもなくこのルールである（フックは Claude Code にしか届かない）
+- **この禁止は kit 配布の `.claude/settings.json` の `permissions.deny`（staging・index の書き換え・`git commit` の直接実行）で機械的にも遮断されている。** `pnpm josh git` は node スクリプト内部から git を起動するため影響を受けず、承認済みのコミットフロー（上記ケース 2）は従来どおり動く。**deny には「そのターンでユーザーが明示指示した」という例外がないため、上記ケース 1 も AI 側では実行できない** — その場合はユーザー自身の端末で実行してもらう。**ユーザーが明示的にコミットを指示した場合も同じで**、承認済みのコミットは `pnpm josh git` を通す（`git commit` まで deny に入れた理由は `docs/maintainers/operating-rules-rationale.md` → "Why the index is the user's"）
+- **「拒否される操作」と「禁止された操作」は同じ集合ではない。** deny に載っているのは上記の直接実行だけだが、このセクションが同じく禁じている `git checkout -- <path>` / `git restore <path>` / 認可外の `git stash`（bare・メッセージ無し push・位置指定 pop など。メッセージ付き `git stash push -m` と `pnpm josh stash:pop` は認可済みなので通る）は、`pnpm josh rule:guard` の `worktree-mutation` 行が拒否する（joshuafolkken/kit#2120）。同じ配送ガードは、`index-mutation` 行（`git add` / `commit` / `reset` / `rm` / `mv` / `restore --staged`）、`worktree-mutation` 行の強制 `git clean -f`、`destructive-command` 行（`rm -rf`・`gh repo delete` / `archive`・`gh pr close`・`gh api -X DELETE`。Issue ラベルの削除だけは除く）、`protected-file` 行（`.env` の読み取りと kit 以外での `.claude/settings.json` の編集）も拒否する（joshuafolkken/kit#2983）。これらは事故防止のためであり、回避を防ぐ境界ではない。**ツールが通したことを許可と読み替えてはならない** — 何をしてよいかを決めるのは deny でも配送ガードでもなくこのルールである（フックは Claude Code にしか届かない）
 
 ### 意思決定の自律ポリシー（確認停止を減らす）
 

package/prompts/collaboration-workflow/overview.md

@@ -19,7 +19,7 @@
 
 `kickoff` / `fullrun` / `halfrun` / `backlogrun` の**操作手順**は、常時ロードされる `CLAUDE.md` からは外され、`.claude/skills/workflow-commands/` に置かれている（joshuafolkken/kit#854）。`CLAUDE.md` に残るのはキーワードとスキルへの導線、およびスキルが読み込まれていない状態でも効く必要のある規則だけである。依存更新後の overrides / `devEngines` 検証手順も同様に `.claude/skills/dependency-update/` へ移した。**どの規則が「残す」側かは →「常駐ドキュメントと skill の分担（何を常駐に残すか）」が判定基準と全 4 件を定義する。**
 
-このドキュメントは引き続き**正典の詳細版**であり、スキルは操作手順である。両者は一致していなければならないので、片方だけを更新してはならない。
+規則の本文は話題ファイルか skill のどちらか 1 か所にだけ置き（どちらに置くかは →「常駐ドキュメントと skill の分担」）、規則が使う数字はコードの定数と、それを述べる 1 文書にだけ置く。**他の文書はその置き場所を指すだけで言い直さない** — 同じ内容を 2 か所に書くと、片方を変えた瞬間にもう片方が古くなる（joshuafolkken/kit#2996）。
 
 ### 出力の言語（`JOSH_SESSION_LANG`）
 
@@ -33,3 +33,15 @@
   3. **スクリプトが出力する固定文字列**: Telegram のヘッダーラベル（`Planning` / `Completion` など）、`Issue:` / `PR:` の URL ラベル、`--notify-message` 省略時の既定メッセージ。AI が書く文面ではなく、翻訳の仕組みも持たない。
 
 `JOSH_SESSION_LANG` は **開発者個人の設定**であり、`.env`（gitignore 済み・非コミット）に置く。リポジトリ共有の設定ではないため、consumer ごと・開発者ごとに自由に変えてよい。`josh sync` で上書きされることもない。**解決値は毎ターン、`UserPromptSubmit` フック（`pnpm josh session:lang`）が 1 度だけコンテキストへ差し込む**ので、エージェントが `.env` を読まなくても言語を取り違えない（最初のターンで二重解決していたため `SessionStart` からは外した）。フック出力を表示しないハーネス（Codex / Gemini / Cursor）は従来どおり `.env` を読んで解決する。この変数がスクリプトの挙動を変えることはなく（`session:lang` が解決値を表示のために読むだけ）、制御するのは AI が書く文面の言語だけである。
+
+### 配布ドキュメントの層ごとの言語（joshuafolkken/kit#2997）
+
+`JOSH_SESSION_LANG` が決めるのはセッションと成果物の散文であり、配布ドキュメントそのものの言語ではない。ドキュメントは**層ごとに 1 つの言語**で書き、1 つの層の中で言語を混ぜない。
+
+| 層                                                                                      | 言語   |
+| --------------------------------------------------------------------------------------- | ------ |
+| `CLAUDE.md`、`AGENTS.md` / `GEMINI.md`、スキル（`.claude/skills/`）、フックが差し込む文 | 英語   |
+| `prompts/` のトピックファイル（次の行の 3 文書を除く）                                  | 日本語 |
+| `prompts/review.md`、`prompts/review-rubric.md`、`prompts/sonar-hotspot-handling.md`    | 英語   |
+
+英語の層から日本語のトピックファイルの節を指すポインターは、その**見出しを原文のまま**引く（例: `principles.md` → 「クローン禁止」）。見出しは `pnpm josh doc:section` が節を引くキーであり、訳すと解決しなくなるため、これは言語の混在ではない。

package/prompts/collaboration-workflow/report-format.md

@@ -102,7 +102,7 @@ pnpm josh read:files <path> [<path> ...]   # 変更対象を 1 ターンでま
 - **読み取りが 1 ターンに畳まれると、続く別ファイルへの編集は互いに依存しなくなり同じターンに載る。** #2178 の「1 ファイルずつ読んで直す」9 ターンの並びが、まとめ読み 1 ターン＋まとめ編集 1 ターンの 2 ターンになる。読み取りと編集を交互に出すのをやめ、読み取りを先に畳むのが梃子である。
 - **助言でないのは、密度を動かした実績があるのが合成コマンドだけだからである**（#2165 / #2162）。助言（#1304）・実行中の提示（#1329 / #1337）・レーン子の通知（#2164）はいずれも動かさず、バッチガードは子で `off`（#2178）なので、実装中の独立編集に効く梃子はこの入口が唯一。
 - 上限超過時は本文を出さず「Read ツールで 1 ターンにまとめて読め」と返す。根拠と前後は [`turn-batching.md`](turn-batching.md) →「実装中の独立編集に効く合成コマンド」。
-- **読んだ後の独立した編集は、1 回の `pnpm josh edit:files -` で送る（joshuafolkken/kit#2493）。** 計画ファイルを作らず、クォート付きヒアドキュメント（`<<'EDITS'`）で old/new の組を標準入力に渡す。形式と拒否条件は `docs/josh-commands.md` →「`josh edit:files`」。**個別の `Edit` に戻すのは**、前の編集結果に依存する編集（`dependent` で拒否される）、編集が 1 件だけのとき、ファイル全体を書くとき（`Write`）の 3 つ。
+- **読んだ後の独立した編集は、1 回の `pnpm josh edit:files -` で送る（joshuafolkken/kit#2493）。** 計画ファイルを作らず、クォート付きヒアドキュメント（`<<'EDITS'`）で old/new の組を標準入力に渡す。形式と拒否条件は `docs/josh-commands-automation.md` →「`josh edit:files`」。**個別の `Edit` に戻すのは**、前の編集結果に依存する編集（`dependent` で拒否される）、編集が 1 件だけのとき、ファイル全体を書くとき（`Write`）の 3 つ。
 
 ### 完了報告（セッション向け）
 

package/prompts/collaboration-workflow/residency.md

@@ -82,7 +82,7 @@
 **第 1 問で「名指しできる」となり、引き金つき配送へ移したもの**（joshuafolkken/kit#1524）。いずれも本文は消えておらず、規則が効く瞬間にフックが突きつける。下は常駐に 1 行を残した、またはその判断に理由が要った行だけであり、配送されている規則の全体ではない。**列挙表と、引き金が発火しないターンの意味の単一ソースは [`rule-delivery.md`](./rule-delivery.md) であり、ここには行数を写さない** — 2 か所に置いた数は必ずずれる（joshuafolkken/kit#1525）。
 
 - **独立した呼び出しを同じターンに載せる規則** — 引き金は `pnpm josh batch:guard`（単発呼び出しのターンが 3 つ続いた次の `Bash` / `Edit` / `Read`）。常駐していた間の実測が示したのは、**常駐は効いていなかった**という事実である（数値は指し先）。実測値・却下した機構案・ゲートを弱めない条件は [`turn-batching.md`](./turn-batching.md) にある（joshuafolkken/kit#1304、#1390、#1524、`Edit` は #1762、`Read` は #1798 で加わった）
-- **バックログの WIP 上限（オープン 30 件）** — 引き金は `pnpm josh rule:guard`（Issue を作成する `Bash`）。配送文が件数の数え方・起票しない判断・2 つの免除・**割り込みの 3 条件**をそのまま運ぶ。3 条件を落とすと「重大かどうか」が判断に戻るため、配送文からも削っていない（joshuafolkken/kit#1518）。コメントの投稿は起票ではないので対象外である。手順と数字を動かす条件は [`wip-cap.md`](./wip-cap.md) にある（joshuafolkken/kit#1469、#1524）
+- **バックログの WIP 上限** — 引き金は `pnpm josh rule:guard`（Issue を作成する `Bash`）。配送文が件数の数え方・起票しない判断・2 つの免除・**割り込みの 3 条件**をそのまま運ぶ。3 条件を落とすと「重大かどうか」が判断に戻るため、配送文からも削っていない（joshuafolkken/kit#1518）。コメントの投稿は起票ではないので対象外である。手順と数字を動かす条件は [`wip-cap.md`](./wip-cap.md) にある（joshuafolkken/kit#1469、#1524）
 - **Issue コメントの読み取り** — 引き金は `pnpm josh rule:guard`（Issue 本文だけを読む `Bash`）。拒否文はコメント込みの読み直しと、本文と食い違うコメントの扱いを渡す。前提を満たすまで毎回拒否するので、`batch:guard` と引き金が重なるターンでも拒否する。手順は `SKILL.md` → §2g に残る — フックを走らせないセッションにも読み取りの義務は残るからである
 - **本文をシェルの二重引用符に載せない** — 引き金は `pnpm josh rule:guard`（本文値にバッククォートか `$` を含む `Bash`）。**引き金はフラグではなく本文を読む** — 作例はどれも無害なプレースホルダを渡しているので、フラグで引くと規則を既に守っているターンで拒否することになる。**常駐側に 1 行が残っているのは、ここが「削除してよい」側ではないからである** — 配送は Claude Code にしか届かず、正規表現が知っている綴り（`-f body=` ／ `--body` ／ `--notify-message`）だけが規則の適用範囲になってはならない。実測・安全な綴り・引き金の死角は [`shell-body.md`](./shell-body.md) にある（joshuafolkken/kit#1198）
 
@@ -107,9 +107,9 @@ no になり skill 側に本体を置くものの例:
 
 **指し先を「カノニカル参照」として名指すと、2 回読みが戻ってくる。** 索引を指してから節名を書く形を禁じたのと同じ欠陥であり、しかも今度は本文が 1 行も無いファイルを経由させる。読み手は指し先を開き、そこに書かれた skill の名前を読み、もう一度開くことになる。**節名まで書いてある引用はさらに悪い** — 指し先には本文が無いのだから、その節はもうそこには無い。
 
-**話題ファイル自体は残す。** 索引（`prompts/collaboration-workflow.md`）は全話題ファイルを列挙しており、正典を人が読むときの入口はそこにある。指し先になった話題ファイルは「本文がどこへ行ったか」の記録として索引から辿られるものであり、他の文書からの引用で辿られるものではない。例外は単一ソースである skill 自身で、自分の指し先を名指すのは逆向きの参照だから 2 回読みを生まない。
+**指し先だけになった話題ファイルは残さない。** 本文が skill へ移り、案内の 1 段落しか持たなくなった話題ファイルは削除し、索引（`prompts/collaboration-workflow.md`）の行も消す（joshuafolkken/kit#1925、joshuafolkken/kit#2996）。削除までの間に残る指し先は「本文がどこへ行ったか」の記録として索引から辿られるものであり、他の文書からの引用で辿られるものではない。例外は単一ソースである skill 自身で、自分の指し先を名指すのは逆向きの参照だから 2 回読みを生まない。
 
-`scripts/rules/pointer-citation-document-rule.test.ts` がこれを固定する。**縮小した話題ファイルは冒頭に「この規則の単一ソースは …」の宣言文を置くこと** — 検査はこの宣言文で指し先を機械的に検出し、そこに書かれた skill が実在すること、および他の文書がその話題ファイルを引用していないことを確かめる。宣言文が入口なので、横展開で新しく縮小された話題も、この規則の対象へ自動で入る。
+`scripts/rules/pointer-citation-document-rule.test.ts` がこれを固定する。**削除までの間に残る、縮小した話題ファイルは冒頭に「この規則の単一ソースは …」の宣言文を置くこと** — 検査はこの宣言文で指し先を機械的に検出し、そこに書かれた skill が実在すること、および他の文書がその話題ファイルを引用していないことを確かめる。宣言文が入口なので、横展開で新しく縮小された話題も、この規則の対象へ自動で入る。
 
 ### 常駐予算
 

package/prompts/collaboration-workflow/rule-delivery.md

@@ -37,7 +37,7 @@
 | **ターン内バッチング**（`turn-batching.md`）                                                                                                                           | `pnpm josh batch:guard` — 単発呼び出しのターンが 3 つ続いた次の `Bash` / `Edit` / `Read`                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | 往復あたりの呼び出し数が下限を上回っている ＝ 規則は既に守られている                                                                                                                                                            |
 | **調査の委譲しきい値**（`SKILL.md` → §2b）                                                                                                                             | `pnpm josh investigation:guard` — 編集しないファイルの読み取りが 3 件目に達した `Read` / `Bash`                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | 読み取りがしきい値未満 ＝ 委譲する対象がまだ無い                                                                                                                                                                                |
 | **バックログ WIP 上限**（`wip-cap.md`）                                                                                                                                | `pnpm josh rule:guard` — Issue を起票する `Bash`（`pnpm josh issue:file`）                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Issue が起票されていない ＝ 上限に触れる行為が無い                                                                                                                                                                              |
-| **直接起票の禁止**（`docs/josh-commands.md` → `josh issue:file`、joshuafolkken/kit#2808）                                                                              | `pnpm josh rule:guard` — `josh issue:file` を通さずに Issue を作成する `Bash`（`gh issue create`、または `…/issues` への `title` 付き POST）。拒否文は `pnpm josh issue:file` の書式を渡す。重複探し・本文の検査と分類ラベル・`## Origin` の確認・`epic:bundle` はこのコマンドが実行するので、それぞれを別の行で見張らない。**毎回発火する**                                                                                                                                                                                                                           | `pnpm josh issue:file` で起票している ＝ 起票の全段がそろっている                                                                                                                                                               |
+| **直接起票の禁止**（`docs/josh-commands-automation.md` → `josh issue:file`、joshuafolkken/kit#2808）                                                                   | `pnpm josh rule:guard` — `josh issue:file` を通さずに Issue を作成する `Bash`（`gh issue create`、または `…/issues` への `title` 付き POST）。拒否文は `pnpm josh issue:file` の書式を渡す。重複探し・本文の検査と分類ラベル・`## Origin` の確認・`epic:bundle` はこのコマンドが実行するので、それぞれを別の行で見張らない。**毎回発火する**                                                                                                                                                                                                                           | `pnpm josh issue:file` で起票している ＝ 起票の全段がそろっている                                                                                                                                                               |
 | **1 ラン 10 件の起票上限**（`.claude/skills/workflow-commands/SKILL.md` → §2d、`observation-filing.md`）                                                               | `pnpm josh rule:guard` — Issue を起票する `Bash`（`pnpm josh issue:file`）。そのランで**拒否されていない**起票が既に 10 件あるとき、11 件目を拒否する。終了コードが 0 でない `issue:file` 呼び出しは起票に数えない。`is_issue_filing` を再利用し、新しい述語は作らない                                                                                                                                                                                                                                                                                                 | 拒否されていない起票が 10 件未満 ＝ 上限に触れていない。**繰り返す行為を止める行なので毎回発火する**（下の「例外」に従う）                                                                                                      |
 | **Issue コメントの読み取り**（`SKILL.md` → §2g）                                                                                                                       | `pnpm josh rule:guard` — Issue 本文だけを読む `Bash`（`gh issue view <N>`、または `…/issues/<N>` で終わる GET）                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Issue を読んでいない、または最初から `--comments` 付きで読んでいる                                                                                                                                                              |
 | **本文をシェルに載せない**（`shell-body.md`）                                                                                                                          | `pnpm josh rule:guard` — 二重引用符の本文値（`-f body="…"` ／ `-f "body=…"` ／ `--body "…"` ／ `--notify-message "…"`）にバッククォートか `$` を含む `Bash`                                                                                                                                                                                                                                                                                                                                                                                                            | 本文がシェルに評価されない ＝ 規則は既に守られている                                                                                                                                                                            |

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

@@ -50,7 +50,7 @@
 
 - **PreToolUse フックが「1 件の呼び出しだけを見て、それが独立かどうかを判定する」。** 採れない。**呼び出しの独立性は、1 件の呼び出しからは観測できない。** フックが見るのはこれから走る 1 件だけで、それが直前の結果に依存しているかどうかはフックの入力に無い。依存している正当な直列実行（`grep` → `sed -n`、Edit の前の読み取り）を止めてしまい、しかも止めた側は理由を説明できない。`output-bounds.md` が「形で見分ける案は実データ上で外れる」として PreToolUse guard を却下したのと同じ形である。
 
-  **却下したのはこの判定のしかたであって、`PreToolUse` という機構そのものではない。** joshuafolkken/kit#1390 は**まさに `PreToolUse` フックとして** `pnpm josh batch:guard` を実装し、`.claude/settings.json` で配布している。判定に使うのは、いま出そうとしている 1 件ではなく**閉じた履歴** — 結果が返り終わったターンの並び — である。単発呼び出しのターンが 2 つ続いたことは 1 件からは見えないが、履歴からは見える。上に並べた懸念は、それぞれ設計で避けてある。依存は**共有ターゲット**で見るので `grep` → `sed -n` は止まらず、**書き込みも読み取りとまったく同じ基準で拒否され**（joshuafolkken/kit#1762）、**手元の呼び出しが直前の列と共有ターゲットを持つときは拒否を取り下げる**（書き込み同士を含む）。拒否は 1 つの単発連続につき **1 回だけ**である（窓を超える連続は `docs/maintainers/turn-batching-rationale.md` →「`batch:guard` の拒否窓」）。委譲された子やレビューエージェントは、親の記録を共有せず、それぞれに配送される（`docs/maintainers/turn-batching-rationale.md` →「フォークへの配送の実装（joshuafolkken/kit#1424）」）。機構の全体は `docs/josh-commands.md` →「`josh batch:guard`」にある。範囲が `Bash|Edit|Read` に広がった経緯（joshuafolkken/kit#1509 を含む）は `docs/maintainers/turn-batching-rationale.md` →「書き込みが範囲に入った経緯（joshuafolkken/kit#1762）」、`docs/maintainers/turn-batching-rationale.md` →「読み取りが範囲に入った経緯（joshuafolkken/kit#1798）」、`docs/maintainers/turn-batching-rationale.md` →「事務コマンドが範囲に入った経緯（joshuafolkken/kit#1875）」。
+  **却下したのはこの判定のしかたであって、`PreToolUse` という機構そのものではない。** joshuafolkken/kit#1390 は**まさに `PreToolUse` フックとして** `pnpm josh batch:guard` を実装し、`.claude/settings.json` で配布している。判定に使うのは、いま出そうとしている 1 件ではなく**閉じた履歴** — 結果が返り終わったターンの並び — である。単発呼び出しのターンが 2 つ続いたことは 1 件からは見えないが、履歴からは見える。上に並べた懸念は、それぞれ設計で避けてある。依存は**共有ターゲット**で見るので `grep` → `sed -n` は止まらず、**書き込みも読み取りとまったく同じ基準で拒否され**（joshuafolkken/kit#1762）、**手元の呼び出しが直前の列と共有ターゲットを持つときは拒否を取り下げる**（書き込み同士を含む）。拒否は 1 つの単発連続につき **1 回だけ**である（窓を超える連続は `docs/maintainers/turn-batching-rationale.md` →「`batch:guard` の拒否窓」）。委譲された子やレビューエージェントは、親の記録を共有せず、それぞれに配送される（`docs/maintainers/turn-batching-rationale.md` →「フォークへの配送の実装（joshuafolkken/kit#1424）」）。機構の全体は `docs/josh-commands-automation.md` →「`josh batch:guard`」にある。範囲が `Bash|Edit|Read` に広がった経緯（joshuafolkken/kit#1509 を含む）は `docs/maintainers/turn-batching-rationale.md` →「書き込みが範囲に入った経緯（joshuafolkken/kit#1762）」、`docs/maintainers/turn-batching-rationale.md` →「読み取りが範囲に入った経緯（joshuafolkken/kit#1798）」、`docs/maintainers/turn-batching-rationale.md` →「事務コマンドが範囲に入った経緯（joshuafolkken/kit#1875）」。
 
   **ガードが見えないところ — ここでは自分で規則を当てる。**
 
@@ -89,9 +89,9 @@ Round trips:
 
 **梃子の本体は読み取りと編集の脱交互化（de-interleave）。** 交互の並びで編集を分けているのは直前の読み取りへの依存で、読み取りを 1 回に畳めば続く別ファイルへの編集は互いにも直前の読み取りにも依存せず 1 ターンに載る。#2178 の並び — `Read A` / `Edit A` / `Read B` / `Edit B` … の **9 ターン** — が、`read:files A B C D` → `Edit A` ＋ `Edit B` ＋ `Edit C` ＋ `Edit D` の **2 ターン**になる。
 
-上限超過時は `read:files` が「Read ツールで 1 ターンにまとめて読め」と返しフォールバックでも読み取りは畳まれたまま。詳細は `docs/josh-commands.md` →「`josh read:files`」。
+上限超過時は `read:files` が「Read ツールで 1 ターンにまとめて読め」と返しフォールバックでも読み取りは畳まれたまま。詳細は `docs/josh-commands-automation.md` →「`josh read:files`」。
 
-書き込みは `pnpm josh edit:files` で畳む（joshuafolkken/kit#2366） — 編集を **プラン（`=====` のパスヘッダ＋ git conflict マーカー対）** として受け取り 1 呼び出しで適用し、各編集は content-addressed なので `old` が 1 箇所に一致しなければ拒否して報告する。#2493 で `-`（標準入力）を受け、依存編集は `dependent` で拒否する。詳細は `docs/josh-commands.md` →「`josh edit:files`」。
+書き込みは `pnpm josh edit:files` で畳む（joshuafolkken/kit#2366） — 編集を **プラン（`=====` のパスヘッダ＋ git conflict マーカー対）** として受け取り 1 呼び出しで適用し、各編集は content-addressed なので `old` が 1 箇所に一致しなければ拒否して報告する。#2493 で `-`（標準入力）を受け、依存編集は `dependent` で拒否する。詳細は `docs/josh-commands-automation.md` →「`josh edit:files`」。
 
 ## ガード発火時にも合成コマンドを手渡す（joshuafolkken/kit#2311）
 

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

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