@joshuafolkken/kit 1.1050.0 → 1.1128.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 = [
@@ -561,24 +565,27 @@ var agent_session_environment = {
 function message_of(error) {
   return error instanceof Error ? error.message : String(error);
 }
-var error_text = { message_of };
+var DEBUG_ENV_KEY = "JOSH_DEBUG";
+function trace_swallowed(where, error) {
+  if ((process.env[DEBUG_ENV_KEY] ?? "").trim() === "") return;
+  process.stderr.write(`josh debug: ${where}: ${message_of(error)}
+`);
+}
+var error_text = { message_of, trace_swallowed };
 
-// 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 +596,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 +606,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 +644,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) {
@@ -1031,18 +1015,23 @@ function is_package_entry(line) {
 function is_github_tarball_line(line) {
   return line.trimStart().startsWith("tarball: https://npm.pkg.github.com/");
 }
-function clean_kit_line(line, version, integrities) {
-  if (!version) return line;
+function package_id(key) {
+  const name = fix_gh_packages_logic.package_path_from_key(key);
+  return `${name}@${fix_gh_packages_logic.package_version_from_key(key)}`;
+}
+function clean_scoped_line(line, id, integrities) {
+  if (!id) return line;
   if (is_github_tarball_line(line)) return void 0;
   const cleaned = remove_flow_tarball(line);
-  const pair = integrities.get(version);
+  const pair = integrities.get(id);
   if (pair === void 0) return cleaned;
   return cleaned.split(`integrity: ${pair[0]}`).join(`integrity: ${pair[1]}`);
 }
-function next_kit_version(line, version) {
-  if (!is_package_entry(line)) return version;
-  const prefix = "  '@joshuafolkken/kit@";
-  return line.startsWith(prefix) ? line.slice(prefix.length).split("'", 1)[0] ?? "" : "";
+function next_scoped_id(line, id) {
+  if (!is_package_entry(line)) return id;
+  const prefix = `  '${SCOPE}/`;
+  if (!line.startsWith(prefix)) return "";
+  return package_id(line.slice("  '".length).split("'", 1)[0] ?? "");
 }
 function integrity_pair(old_integrity, npm_integrity) {
   if (old_integrity === void 0 || npm_integrity === void 0) return void 0;
@@ -1051,24 +1040,24 @@ function integrity_pair(old_integrity, npm_integrity) {
 function lock_integrities(lockfile, npm_integrities) {
   const packages = fix_gh_packages_logic.parse_lockfile_packages(lockfile);
   const pairs = /* @__PURE__ */ new Map();
-  const kit_entries = Object.entries(packages).filter(([key]) => key.startsWith(`${SCOPE}/kit@`));
-  for (const [key, entry] of kit_entries) {
-    const version = fix_gh_packages_logic.package_version_from_key(key);
-    const pair = integrity_pair(entry.resolution?.integrity, npm_integrities.get(version));
-    if (pair !== void 0) pairs.set(version, pair);
+  const scoped_entries = Object.entries(packages).filter(([key]) => key.startsWith(`${SCOPE}/`));
+  for (const [key, entry] of scoped_entries) {
+    const id = package_id(key);
+    const pair = integrity_pair(entry.resolution?.integrity, npm_integrities.get(id));
+    if (pair !== void 0) pairs.set(id, pair);
   }
   return pairs;
 }
 function push_if_defined(lines, cleaned) {
   if (cleaned !== void 0) lines.push(cleaned);
 }
-function rewrite_kit_lockfile(lockfile, npm_integrities) {
-  let kit_version = "";
+function rewrite_scoped_lockfile(lockfile, npm_integrities) {
+  let id = "";
   const lines = [];
   const integrities = lock_integrities(lockfile, npm_integrities);
   for (const line of lockfile.split("\n")) {
-    kit_version = next_kit_version(line, kit_version);
-    const cleaned = clean_kit_line(line, kit_version, integrities);
+    id = next_scoped_id(line, id);
+    const cleaned = clean_scoped_line(line, id, integrities);
     push_if_defined(lines, cleaned);
   }
   return lines.join("\n");
@@ -1098,7 +1087,7 @@ function previous_registry(project_npmrc, user_npmrc) {
 }
 function plan(project_npmrc, user_npmrc, lockfile) {
   const packages = scoped_packages(lockfile);
-  const blocked = packages.filter((name) => name !== `${SCOPE}/kit`);
+  const blocked = [];
   if (has_duplicate_mapping(project_npmrc, user_npmrc)) blocked.push("duplicate registry mappings");
   const unsupported = unsupported_registry(project_npmrc);
   if (unsupported !== void 0) blocked.push(unsupported);
@@ -1110,9 +1099,7 @@ var migrate_logic = {
   plan,
   github_tarballs,
   is_github_tarball,
-  rewrite_kit_lockfile,
-  registry_of,
-  scoped_packages,
+  rewrite_scoped_lockfile,
   scoped_versions
 };
 
@@ -1146,7 +1133,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 +1198,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 +1243,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) {
@@ -1300,6 +1287,7 @@ var version_targets = {
 var FAILURE_EXIT_CODE = 1;
 var ALREADY_UP_TO_DATE = "Already up to date";
 var NO_QUARANTINE_MINUTES2 = 0;
+var UPGRADE_TIMEOUT_MS = 6e5;
 function read_release_hold(package_config, latest, versions) {
   if (versions.every((version) => version === void 0 || version === latest)) return void 0;
   const minimum_age_minutes = release_age.read_nearest_minimum_release_age(process.cwd());
@@ -1384,7 +1372,11 @@ function run_check(config) {
   );
 }
 function run_upgrade_command(command) {
-  const result = execaSync4("sh", ["-c", command], { stdio: "inherit", reject: false });
+  const result = execaSync4("sh", ["-c", command], {
+    stdio: "inherit",
+    reject: false,
+    timeout: UPGRADE_TIMEOUT_MS
+  });
   return result.exitCode ?? FAILURE_EXIT_CODE;
 }
 function run_all_upgrade_commands(commands) {

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/eslint/rules/unicorn.js

@@ -80,8 +80,9 @@ export const unicorn_rules = {
 	'unicorn/custom-error-definition': 'error',
 	// throw new Error()の形式を強制
 	'unicorn/throw-new-error': 'error',
-	// 空の配列をチェック
-	'unicorn/no-empty-file': 'error',
+	// 空ファイルを禁止する。コメントだけのファイルは許可する: `sv create` の足場 `src/lib/index.ts` は
+	// コメント 1 行だけで、手を加えていないプロジェクトで lint が落ちてしまうため（#3069）
+	'unicorn/no-empty-file': ['error', { allowComments: true }],
 	// 静的なみずからのみのクラスを禁止
 	'unicorn/no-static-only-class': 'error',
 	// this別名を禁止（arrow functionを使うべき）

package/package.json

@@ -1,11 +1,12 @@
 {
-  "version": "1.1050.0",
+  "version": "1.1128.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",
@@ -58,6 +59,7 @@
     ".ncurc.json",
     ".prettierignore",
     "pnpm-workspace.yaml",
+    ".pnpmfile.mjs",
     "tsconfig.sonar.json",
     "playwright.config.ts",
     "!**/*.test.ts",
@@ -85,12 +87,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",
@@ -156,6 +162,7 @@
   "peerDependencies": {
     "@eslint/compat": "^2.1.1",
     "@eslint/js": "^10.0.1",
+    "@ianvs/prettier-plugin-sort-imports": "^4.7.1",
     "@playwright/test": ">=1.0.0",
     "@stylistic/eslint-plugin": "^5.10.0",
     "eslint": "^10.0.0",
@@ -166,6 +173,9 @@
     "eslint-plugin-sonarjs": "^4.2.1",
     "eslint-plugin-unicorn": "^76.0.0",
     "globals": "^17.12.0",
+    "prettier": "^3.9.9",
+    "prettier-plugin-svelte": "^4.1.1",
+    "prettier-plugin-tailwindcss": "^0.8.1",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.70.1"
   },
@@ -179,6 +189,9 @@
     "@eslint/js": {
       "optional": true
     },
+    "@ianvs/prettier-plugin-sort-imports": {
+      "optional": true
+    },
     "@stylistic/eslint-plugin": {
       "optional": true
     },
@@ -206,6 +219,15 @@
     "globals": {
       "optional": true
     },
+    "prettier": {
+      "optional": true
+    },
+    "prettier-plugin-svelte": {
+      "optional": true
+    },
+    "prettier-plugin-tailwindcss": {
+      "optional": true
+    },
     "typescript": {
       "optional": true
     },
@@ -238,7 +260,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",
@@ -251,7 +273,6 @@
     "jsonc-parser": "^3.3.1",
     "ora": "^9.4.1",
     "semver": "^7.8.5",
-    "strip-json-comments": "^5.0.3",
     "tsx": "^4.23.15",
     "zod": "^4.6.5"
   },
@@ -263,7 +284,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/pnpm-workspace.yaml

@@ -28,11 +28,9 @@ minimumReleaseAgeExclude:
 
 overrides:
   svelte: ^5.55.7
-  devalue: ^5.8.1
-  # Indirect deps a within-range re-resolution could not lift past their parents' pins, floored at the
-  # smallest release clearing each OSV advisory (joshuafolkken/kit#2200; user-approved 2026-09-21 to
-  # override indirect packages). Carets so `josh latest`'s re-resolution keeps them current within the
-  # major without reintroducing the advisory.
+  # An indirect dep a within-range re-resolution could not lift past its parents' pins, floored at the
+  # smallest release clearing its OSV advisory (joshuafolkken/kit#2200; user-approved 2026-09-21 to
+  # override indirect packages). A caret so `josh latest`'s re-resolution keeps it current within the
+  # major without reintroducing the advisory. The devalue, postcss and nanoid floors were removed once
+  # their parents' ranges exceeded them (joshuafolkken/kit#3091).
   vite: ^8.0.16 # OSV — vite 8.0.8 → 8.0.16
-  postcss: ^8.5.23 # OSV — postcss 8.5.16 → 8.5.23
-  nanoid: ^3.3.18 # OSV — nanoid 3.3.15 → 3.3.18

package/prompts/collaboration-workflow/glossary.md

@@ -0,0 +1,17 @@
+# ワークフロー用語集
+
+**これは定義集であり、規則を定める場所ではない。** 各語は 1〜2 行の定義と、その語の本文がある単一ソースへのポインタだけを持つ。手順・条件・数値は指し先が持ち、ここでは言い換えない — 言い換えた行は指し先より先に古くなる（joshuafolkken/kit#3080）。
+
+`scripts/document/workflow-glossary.test.ts` が、下の主要語が定義されていることと、各ポインタが実在する節に解決することを検査する。
+
+- **lane** — `backlogrun` が子 Issue を並行実行するための、専用ブランチ・`.env`・ポートを持つ git worktree。実装・ゲート・レビューは並行し、マージは直列。→ `.claude/skills/workflow-commands/backlogrun-lanes.md` → "Lanes — running more than one child at a time"
+- **cut** — 実行中のプロセスを意図して終わらせ、新しいプロセスが同じ作業を引き継ぐ境界。レーン子のゲート前の cut と、`backlogrun` のセッション cut がある。→ `.claude/skills/workflow-commands/pre-gate-cut.md` → "The pre-gate cut"、`.claude/skills/workflow-commands/backlogrun-progress.md` → "The hand-off"
+- **hold** — 1 つの作業ツリーを 1 つのランが占有しているという記録。`pnpm josh run:hold` が取り、`pnpm josh run:release` が外す。→ `.claude/skills/workflow-commands/working-tree-hold.md` → "The working-tree hold"
+- **park** — `backlogrun` が自分で決められない子を `needs-decision` で止め、バッチ全体は止めずに次の子へ進むこと。→ `.claude/skills/workflow-commands/backlogrun-park.md` → "park and continue"
+- **point of use** — 文書を入口ではなく、その文書に従うべき操作と同じターンで、その操作の直前に読むこと。→ `.claude/skills/workflow-commands/SKILL.md` → "Four documents are read at the point of use, not at the entry"
+- **entry read** — コマンド起動時に読む文書の集合。`pnpm josh read:set` がその集合と費用を答える。→ `.claude/skills/workflow-commands/SKILL.md` → "Which file to read"
+- **oracle** — 機械的に読める入力だけから規則の答えを計算するコマンド。一覧は `pnpm josh oracle:list`。→ `prompts/collaboration-workflow/residency.md` → "第 0 問"
+- **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"

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/issue-template.md

@@ -76,7 +76,7 @@ Issue には次の要素を必ず含める。
 - **互換性を壊す変更は影響を本文で宣言する。** 既存の利用者、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` が同じコマンドをやり直し、**before / after の対**を印字する。値が動かなかったとき、反証された前提として `docs/maintainers/observations/` の、その時点のブランチが指す Issue のファイルに 1 行追記される（既存の append-only 台帳を使い、別の台帳は作らない）
+- **`## ベースライン`** は **「コマンド + 値」** で書く。``- `<測定コマンド>` → <現在の値>`` の形に限り、自然文だけの測定説明は受け付けない（再実行できないため）。マージ後に `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` は起票前に同じ検査を行い、問題があれば起票しない）
 

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

@@ -27,11 +27,11 @@
 
 PR マージ・ブランチ削除・force push・共有ブランチへの push・外部通知の追加送信・リポジトリ設定の変更など、**共有状態に影響する操作はその場でユーザーに明示指示されたものだけ実行する**。
 
-- `fullrun` の auto-merge は `fullrun` の指示自体に含まれるため許可される（本文は [`followup.md`](../../.claude/skills/workflow-commands/followup.md)）。それ以外の状況で勝手にマージしてはならない
+- `fullrun` と `backlogrun` の auto-merge は、それぞれの指示自体に含まれるため許可される（本文は [`followup.md`](../../.claude/skills/workflow-commands/followup.md)、`backlogrun` の子への継承は [`backlogrun-child.md`](../../.claude/skills/workflow-commands/backlogrun-child.md)）。`prrun` はマージを認可しない。それ以外の状況で勝手にマージしてはならない
 - `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/principles.md

@@ -72,3 +72,12 @@
 - **導線文書に規則を書き戻さない。** そこに書かれた規則は、次の改訂で更新し忘れる 4 つ目の置き場になる
 - `scripts/document/ai-document-pointers.test.ts` が機械的に守る。導線文書に規則本体が再出現した場合、導線の一文が消えた場合、`CLAUDE.md` が単一ソースであることの記述が消えた場合に落ちる
 - 経緯は `docs/maintainers/principles-rationale.md` → "Why AGENTS and GEMINI are pointers"、`@CLAUDE.md` 行と他ツールでの未検証は `docs/maintainers/principles-rationale.md` → "The include line, and what has not been verified"
+
+### Claude Code 以外のエージェントでの読み替え
+
+`CLAUDE.md` は Claude Code 向けに書かれており、その機能を名指しする。Codex・Gemini CLI など別のエージェントは次のように読み替える。導線文書が持つのはツール固有の 1 行だけで、共通の読み替えはこの節にしか無い（joshuafolkken/kit#3079）。
+
+- **フック**: フックが走らない、または出力が見えないツールでは、フックが届ける規則を自分で適用する。その一覧は手書きせず、[`rule-delivery.md`](./rule-delivery.md) →「配送されている規則」の表を正とする — 表の各行が、そのツールでは自分で守る規則である。表の外でフックが担う 3 つも同じく自分で行う — 最初の実行時コード編集の前に Step 0 の作業サマリを提示する、編集ごとの整形フックに頼らず編集後に `pnpm josh lint:related` と `pnpm josh cspell:dot` を走らせる、`JOSH_SESSION_LANG` は注入を待たずに `.env` から解決する。フックの全体は `.claude/settings.json` の `hooks` が正である
+- **Skill・`/verify-ui`・`/code-review`**: `CLAUDE.md` が skill のロードやサブエージェントでの実行を指示する箇所では、その skill の `SKILL.md` を読み、自分のセッションで従う
+- **`.claude/settings.json` の deny list** は効かない。それが裏付ける規則 — 指示なしのコミット・マージ・ステージングその他の共有状態変更をしない — はそのまま拘束する
+- **`AskUserQuestion`** は、ユーザーに平文で尋ねることを指す