@joshuafolkken/kit 1.1455.0 → 1.1514.0

package/dist/managed-marker/index.js

@@ -18,8 +18,7 @@ function is_marked(text) {
   return text.startsWith(MARKER_PREFIX);
 }
 function apply_marker_for_destination(destination, text, package_name) {
-  if (!is_workflow_destination(destination)) return text;
-  if (is_marked(text)) return text;
+  if (!is_workflow_destination(destination) || is_marked(text)) return text;
   return `${marker_block(package_name)}${text}`;
 }
 var managed_marker_logic = {

package/dist/version/index.js

@@ -141,8 +141,7 @@ function read_matching_version(manifest_path, package_name) {
   const parsed = package_named_version_schema.safeParse(
     json_value.parse_or_undefined(readFileSync(manifest_path, "utf8"))
   );
-  if (!parsed.success) return void 0;
-  if (parsed.data.name !== package_name) return void 0;
+  if (!parsed.success || parsed.data.name !== package_name) return void 0;
   return parsed.data.version;
 }
 function walk_up_for_version(start_directory, package_name) {
@@ -152,9 +151,9 @@ function walk_up_for_version(start_directory, package_name) {
   }
   return void 0;
 }
-function resolve_from_base(base_url, package_name, resolve_marker) {
+function resolve_from_base(base_url, package_name, resolve_marker = package_name) {
   try {
-    return createRequire(base_url).resolve(resolve_marker ?? package_name);
+    return createRequire(base_url).resolve(resolve_marker);
   } catch {
     return void 0;
   }
@@ -281,8 +280,9 @@ function is_latest_withheld(times, latest, minimum_age_minutes, now_ms) {
   return published_ms > now_ms - minimum_age_minutes * MS_PER_MINUTE2;
 }
 function resolve_installable(times, latest, minimum_age_minutes, now_ms) {
-  if (times === void 0) return void 0;
-  if (!is_latest_withheld(times, latest, minimum_age_minutes, now_ms)) return void 0;
+  if (times === void 0 || !is_latest_withheld(times, latest, minimum_age_minutes, now_ms)) {
+    return void 0;
+  }
   const installable = release_age.select_aged_version(times, void 0, minimum_age_minutes, now_ms);
   return installable === latest ? void 0 : installable;
 }
@@ -307,8 +307,9 @@ function format_release_hold_note(version, latest, installable, minimum_age_minu
   return `${head}; an unpinned resolve lands on ${installable}`;
 }
 function build_release_hold_notes(version, latest, installable, minimum_age_minutes) {
-  if (version === void 0 || installable === void 0) return [];
-  if (!is_release_age_hold(version, latest, installable)) return [];
+  if (version === void 0 || installable === void 0 || !is_release_age_hold(version, latest, installable)) {
+    return [];
+  }
   return [format_release_hold_note(version, latest, installable, minimum_age_minutes)];
 }
 var release_hold = {
@@ -1399,8 +1400,9 @@ function build_extras(config) {
 }
 function build_upstream_effective(upstream, context) {
   const { resolve_effective_version, resolve_global_upgrade_command } = upstream;
-  if (resolve_effective_version === void 0) return void 0;
-  if (resolve_global_upgrade_command === void 0) return void 0;
+  if (resolve_effective_version === void 0 || resolve_global_upgrade_command === void 0) {
+    return void 0;
+  }
   return {
     version: resolve_effective_version(context),
     upgrade_command: resolve_global_upgrade_command(context)
@@ -1485,8 +1487,9 @@ function build_idle_message(reports) {
 }
 function describe_effective_outcome(upstream, report, snapshot) {
   const { resolve_effective_version } = upstream;
-  if (resolve_effective_version === void 0 || report === void 0) return [];
-  if (version_check_logic.build_effective_upgrade_commands(report).length === 0) return [];
+  if (resolve_effective_version === void 0 || report === void 0 || version_check_logic.build_effective_upgrade_commands(report).length === 0) {
+    return [];
+  }
   const after = resolve_effective_version({
     latest: snapshot.latest,
     upstream_latest: report.latest

package/eslint/base.js

@@ -29,7 +29,7 @@ import {
 	SPEC_FILENAME_PATTERNS,
 } from './rules/test-filename.js'
 import { typescript_rules } from './rules/typescript.js'
-import { unicorn_rules } from './rules/unicorn.js'
+import { unicorn_rules, unicorn_test_rules } from './rules/unicorn.js'
 
 const FILE_PATTERNS = {
 	d_ts: ['**/*.d.ts'],
@@ -234,6 +234,7 @@ export function create_base_config({ gitignore_path, tsconfig_root_dir }) {
 				// `expect(x).toBe(0.05)` compares deterministic config constants, not computed
 				// floats; working around the rule only weakens the assertion.
 				'sonarjs/no-floating-point-equality': 'off',
+				...unicorn_test_rules,
 			},
 		},
 		{

package/eslint/rules/unicorn.js

@@ -205,3 +205,19 @@ export const unicorn_rules = {
 	// たびにエディタと衝突し、可読性の利得なく差分ノイズだけを生むため無効化する（joshuafolkken/kit#3273）。
 	'unicorn/no-asterisk-prefix-in-documentation-comments': 'off',
 }
+
+// unicorn 78 のベースライン方針（joshuafolkken/kit#3882）: 78 は新ルール 2 つ
+// （no-unnecessary-default-arguments / no-repeated-call-wrappers）に加え、型解決とコメントを含む
+// コードの検査を広げたため、既存ルールが新たに報告する。prefer-combined-guards /
+// prefer-minimal-ternary / no-negated-condition / prefer-default-parameters は正当な
+// クリーンアップなので採用し、コードを直す。consistent-boolean-name だけは下記のとおり
+// テストファイルで外す。
+export const unicorn_test_rules = {
+	// 78 は vi.fn() / vi.spyOn() / vi.mocked() の戻り型を解決できるようになり、真偽値を返す関数の
+	// モックやスパイ（`const write = vi.spyOn(process.stdout, 'write')`）を真偽値の束縛として報告する。
+	// 関数値の const を checkVariables で検査するのはプラグインの文書どおりの仕様（77 でも
+	// `const f = () => true` は報告される）で、誤検知ではない。ただしテストの束縛はほぼすべて
+	// 差し替える関数を名前で示すテストダブルで、`is_write` のような名前は述語の結果のように読めて
+	// 誤解を招く。kit が関数名を検査しない（checkFunctions: 'never'）のと同じ理由でテストでは外す。
+	'unicorn/consistent-boolean-name': 'off',
+}

package/lefthook/base.yml

@@ -5,9 +5,11 @@ pre-commit:
       skip: git diff --cached --quiet
       run: pnpm josh prevent-main-commit
 
+    # cspell, prettier and eslint go through `josh pre-commit-lint`, which owns their flags so each
+    # cache location comes from the constant its ignore rules are asserted against (kit#3948).
     cspell:
       glob: '*.{ts,tsx,js,jsx,md,mdx,html,css,scss,yml,yaml,json,properties}'
-      run: pnpm exec cspell lint --no-must-find-files --no-progress {staged_files}
+      run: pnpm josh pre-commit-lint cspell {staged_files}
 
     # Scans only staged files, so a secret is caught before it ever enters history —
     # GitHub push protection and the CodeRabbit gitleaks pass both fire after the fact,
@@ -22,11 +24,11 @@ pre-commit:
 
     prettier:
       glob: '*.{js,jsx,ts,tsx,mjs,cjs,html,css,scss,md,mdx,json,jsonc,yaml,yml}'
-      run: pnpm exec prettier --check --ignore-unknown {staged_files}
+      run: pnpm josh pre-commit-lint prettier {staged_files}
 
     eslint:
       glob: '*.{js,jsx,ts,tsx,mjs,cjs}'
-      run: pnpm exec eslint --quiet --cache --cache-strategy content {staged_files}
+      run: pnpm josh pre-commit-lint eslint {staged_files}
 
     # Routed through `josh pre-commit-type-check` rather than a bare `pnpm exec tsc --noEmit` so the
     # hook can read the record `pnpm josh gate` leaves behind (kit#1381) — the same reader the

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1455.0",
+  "version": "1.1514.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": [
@@ -72,6 +72,7 @@
     "!scripts/eval",
     "!scripts/time",
     "!scripts/cost",
+    "!scripts/cost-audit",
     "!scripts/retrospective",
     "!scripts/dogfood",
     "!scripts/metrics",
@@ -97,6 +98,7 @@
     "!scripts/exports/namespace-members.ts",
     "!scripts/exports/unused-members.ts",
     "!scripts/document/generate-catalog.ts",
+    "!scripts/document/generate-command-usage.ts",
     "!scripts/document/issue-citation-budget.ts",
     "!scripts/document/retired-phrases.ts",
     "!scripts/document/review-agent-type.ts",
@@ -178,7 +180,7 @@
     "eslint-plugin-import-x": "^4.17.1",
     "eslint-plugin-promise": "^7.3.0",
     "eslint-plugin-sonarjs": "^4.2.1",
-    "eslint-plugin-unicorn": "^77.0.0",
+    "eslint-plugin-unicorn": "^78.0.0",
     "globals": "^17.12.0",
     "prettier": "^3.9.9",
     "prettier-plugin-svelte": "^4.1.1",
@@ -247,12 +249,12 @@
     "@eslint/compat": "^2.1.1",
     "@eslint/js": "^10.0.1",
     "@ianvs/prettier-plugin-sort-imports": "^4.7.1",
-    "@playwright/test": "^1.64.0",
+    "@playwright/test": "^1.64.1",
     "@secretlint/secretlint-rule-preset-recommend": "^13.0.7",
     "@stylistic/eslint-plugin": "^5.10.0",
     "@types/node": "^26.6.5",
     "@types/semver": "^7.8.0",
-    "cspell": "^10.3.6",
+    "cspell": "^10.4.0",
     "esbuild": "^0.28.2",
     "eslint": "^10.12.0",
     "eslint-config-prettier": "^10.1.8",
@@ -260,24 +262,24 @@
     "eslint-plugin-import-x": "^4.17.1",
     "eslint-plugin-promise": "^7.3.0",
     "eslint-plugin-sonarjs": "^4.2.2",
-    "eslint-plugin-unicorn": "^77.0.0",
+    "eslint-plugin-unicorn": "^78.0.0",
     "eslint_d": "^15.0.3",
     "globals": "^17.13.0",
-    "lefthook": "^2.2.1",
+    "lefthook": "^2.2.2",
     "prettier": "^3.9.10",
     "prettier-plugin-svelte": "^4.1.1",
     "prettier-plugin-tailwindcss": "^0.8.1",
-    "rollup": "^4.64.5",
+    "rollup": "^4.64.7",
     "rollup-plugin-dts": "^6.5.1",
     "secretlint": "^13.0.7",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.71.1",
-    "vitest": "^5.0.3"
+    "typescript-eslint": "^8.71.2",
+    "vitest": "^5.0.4"
   },
   "dependencies": {
     "cli-spinners": "^3.4.0",
     "csv-parse": "^7.0.3",
-    "execa": "^10.1.0",
+    "execa": "^10.1.1",
     "js-yaml": "^5.4.3",
     "jsonc-parser": "^3.3.1",
     "ora": "^9.4.1",
@@ -285,12 +287,12 @@
     "string-width": "^8.3.0",
     "terminal-link": "^5.0.0",
     "tsx": "^4.23.15",
-    "zod": "^4.6.6"
+    "zod": "^4.6.7"
   },
   "devEngines": {
     "packageManager": {
       "name": "pnpm",
-      "version": "12.12.1+sha512.b7f98934c0b1f29a65f5da52f2d7f994e7faad573ffdddea1497fb4dcb5aec051590ee7c7d95a38172b4bfae103a5b83edf2ee866e11731c2cafa96063610ac5",
+      "version": "12.13.0+sha512.1e55719bf26e809dce5c5084fdebaa64efb3da9038ae5d68a9f8a68311f1a45841c8c3b76a37298c3b66f6bcc80409a9b7f33c78a7168a3e90fb65a5d8235ae4",
       "onFail": "download"
     }
   },

package/prompts/coding-standards.md

@@ -1,27 +1,21 @@
 # コーディング指針 — lint では表せない書き方
 
-命名・エクスポート・ファイル名・内容の規約の単一ソースは下記「Conventions」、関数の構文・品質上限・型安全・早期 return・マジックナンバーの単一ソースは `CLAUDE.md` → "Critical Conventions (non-standard — always apply)" である。その大半は ESLint が強制する（クラスのプロパティ・メソッドの `snake_case` などここに書いていない細目は `eslint/rules/naming-convention.js` が持つ）。ただし **`function` 構文（アロー関数を使わない）と早期 return の 1 行形式は lint が検査しない**ので、書き手とレビューが確かめる。このファイルは本文を写さず、lint では表せない書き方の指針だけを持つ。
-
-lint・型検査の実行手順は `CLAUDE.md` → "Code Change Rules" の検証ゲート（`pnpm josh gate`、実装中は `pnpm josh lint:related` / `pnpm josh test:related`）が単一ソースである。
+関数の構文・品質上限・型安全・早期 return・マジックナンバーは `CLAUDE.md` → "Critical Conventions (non-standard — always apply)"、lint・型検査の実行は `CLAUDE.md` → "Code Change Rules"（`pnpm josh gate`、実装中は `pnpm josh lint:related` / `pnpm josh test:related`）に従う。ここにない命名の細目（クラスのプロパティ・メソッドの `snake_case` など）は `eslint/rules/naming-convention.js` が持つ。**`function` 構文（アロー関数を使わない）と早期 return の 1 行形式は lint が検査しない**ので、書き手とレビューが確かめる。
 
 ## Conventions
 
-`CLAUDE.md` から移した、lint が強制する規約の単一ソース。
-
-- **Naming**: `snake_case` variables / functions / params · `PascalCase` types / classes / interfaces / enums · `UPPER_CASE` enum members · booleans prefixed `is_` / `has_` / `should_` / `can_` / `will_` / `did_` · constants `UPPER_CASE` or `snake_case`
-- **Functions & exports**: multiple functions → a namespace object `export { my_module }` (constants exempt) · no `export default`
-- **Files**: Svelte `PascalCase.svelte(.ts)` · TypeScript `kebab-case.ts` · tests `*.test.ts` / `*.svelte.test.ts`, colocated, never `*.spec.ts` (`prompts/testing-guide.md`) · in `scripts/`, no `../` imports — use `#scripts/*`
-- **Content rules**: user-visible strings use i18n message keys in every locale · comments / test titles English only (`eslint/rules/` may explain rationale in Japanese) · no duplication; `/* @refactor-ignore */` at file top excludes a file from refactoring
+- Naming: `snake_case` variables / functions / params · `PascalCase` types / classes / interfaces / enums · `UPPER_CASE` enum members · booleans prefixed `is_` / `has_` / `should_` / `can_` / `will_` / `did_` · constants `UPPER_CASE` or `snake_case`
+- Functions & exports: multiple functions → a namespace object `export { my_module }` (constants exempt) · no `export default`
+- Files: Svelte `PascalCase.svelte(.ts)` · TypeScript `kebab-case.ts` · tests `*.test.ts` / `*.svelte.test.ts`, colocated, never `*.spec.ts` (`prompts/testing-guide.md`) · in `scripts/`, no `../` imports — use `#scripts/*`
+- Content rules: user-visible strings use i18n message keys in every locale · comments / test titles English only (`eslint/rules/` may explain rationale in Japanese) · no duplication; `/* @refactor-ignore */` at file top excludes a file from refactoring
 
 ## 📝 基本方針
 
-一般的な書き方の助言（シンプルさ・命名・過度な抽象化の回避など）は繰り返さない。lint が強制せず、一般論でもない指針だけを置く。
-
-- **意図が不明瞭な処理は関数に抽出する**: 条件式や処理の意図がわかりにくければ、たとえ 1 行でも抽出し、関数名で意図を表す（`if (is_eligible_for_service(user))`）
-- **コメントは「なぜ」だけ、経緯は書かない**: 残すのは一行の理由（そのルールの意図）だけ。「以前は…」という経緯、Issue 番号への参照、計測値は git 履歴と Issue が保持している
-- **文字列も定数化する**: 数値リテラルの抽出は lint が強制するが、繰り返し使用する文字列や識別子も定数化し、意味の分かる名前を付ける
+- **意図が不明瞭な処理は関数に抽出する**: 1 行でも抽出し、関数名で意図を表す（`if (is_eligible_for_service(user))`）
+- **コメントは「なぜ」だけ**: 一行の理由だけを残す。「以前は…」の経緯・Issue 番号・計測値は書かない（git 履歴と Issue が持つ）
+- **文字列も定数化する**: 繰り返す文字列や識別子にも意味の分かる名前の定数を付ける
 - **既存のコード体系に寄り添う**: そのうえで、より良く書けるなら目指す
-- **仕組みを足す前に原因を問う**: 設計時の判断は `prompts/collaboration-workflow/principles.md` → "elegant-design" の担当。コメントの英語限定と重複の撲滅は上の「Conventions」と `principles.md` → "no-clones" が単一ソースである
+- **仕組みを足す前に原因を問う**: `prompts/collaboration-workflow/principles.md` → "elegant-design"。重複の撲滅は "no-clones"
 
 ## 📁 新規作成時の手順
 
@@ -34,16 +28,12 @@ find src -name "*.ts" -o -name "*.svelte" | grep -i [関連キーワード]
 
 ### 2. ファイル分割の指針
 
-- **上限に近づいたら分割を検討**: 関数やファイルが `CLAUDE.md` → "Quality limits" の上限に近づいたら分割を検討する。編集前に `pnpm josh lines <path>` で余裕を確認する
-- **責任が複数ある場合**: 1つのファイルが複数の責任を持つ場合は、責任ごとにファイルを分割
-- **再利用性**: 他のファイルからも使用される可能性があるロジックは、別ファイルに分離
-- **メインファイルの肥大化を避ける**: メインファイルの肥大化を避けることを優先する。再利用可能な機能や独立した責任を持つ機能は、積極的に別ファイルに分割する。メインファイルは主要な処理フローに集中し、詳細な実装は別ファイルに分離する
-- **過度な分割は避ける**: 小さすぎるファイルの分割は避け、関連する機能は同じファイルにまとめる
+- `CLAUDE.md` → "Quality limits" の上限に近づいたら分割を検討する。編集前に `pnpm josh lines <path>` で余裕を確認する
+- 責任ごと、また他ファイルからも使われうるロジックごとに別ファイルに分け、メインファイルは主要な処理フローに集中させる
+- 小さすぎる分割は避け、関連する機能は同じファイルにまとめる
 
 ### 3. 名前空間オブジェクトの名付け方
 
-複数の関数を名前空間オブジェクトにまとめてエクスポートする規則そのものは上記「Conventions」にある（定数は個別エクスポートでよい）。ここでは名付け方だけを述べる。
-
 - ファイル名と名前空間名で意図を明確にする（例: `git-command.ts` → `git_command`）
 - メソッド名は短く、名前空間で補完する（例: `exec_git_branch()` → `git_command.branch()`）
 

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

@@ -1,12 +1,12 @@
 ## ファイル編集はコマンド本文に本文を載せない
 
-「ファイル本文をシェルに載せない」規則の正典。`CLAUDE.md` からは [`rule-delivery.md`](./rule-delivery.md) →「配送されている規則」を経て届く。
+`CLAUDE.md` からは [`rule-delivery.md`](./rule-delivery.md) →「配送されている規則」を経て届く。
 
-`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`・書き込むスクリプトを作るヒアドキュメント・`perl -0pi -e` を拒否する。ガードに見えない Edit / Write の全文書き直しと `sed -i` は以下に従う。
 
 ### 何を禁じているか
 
-**編集後のテキストを丸ごとコマンド行に載せる形を禁じる。** 典型は、インタプリタを起動して領域を書き戻す次の形である。
+**編集後のテキストを丸ごとコマンド行に載せる形を禁じる。** 典型（`NEW_REGION` には置換後の本文が載る）:
 
 ```bash
 python3 - <<'PY'          # ← 禁止
@@ -15,64 +15,44 @@ open('CLAUDE.md', 'w').write(text.replace(OLD_REGION, NEW_REGION))
 PY
 ```
 
-`NEW_REGION` は変数ではない。実際には**置換後の本文そのもの**がここに直接書かれ、コマンド行に載る。それがコストの正体である。
-
-領域を指定して書き換える編集は **Edit ツール**（old / new の差分）で行う。`node -e`、`cat > file <<'EOF'`、`tee file <<'EOF'`、`perl -0pi -e` に長い置換文字列を渡す形も同じ理由で禁止される。
+領域を書き換える編集は Edit ツール（old / new の差分）で行う。`node -e`、`cat > file <<'EOF'`、`tee file <<'EOF'`、`perl -0pi -e` に長い置換文字列を渡す形も禁止。
 
 ### 判断基準は「本文を丸ごと運ぶか」であり、ツール名ではない
 
-禁止の対象は**ツールの種類ではない**。判断は 1 問で決まる。
-
 > **そのコマンドは、置換後のテキストを丸ごとコマンド本文に載せているか。**
 
 - yes → 禁止。Edit を使う
-- no → 許可
-
-したがって短い置換に `sed -i` を使うのは**許される**。パターンと置換語しか運ばないので、Edit の `old_string` / `new_string` より本文が小さい。逆に「Edit を使ったから安全」も成り立たない — 300 行のファイルを全文 `new_string` に入れれば、禁じている形と同じコストになる。次節はその後半を条件として書き下したものである。
+- no → 許可（短い置換の `sed -i` は下の 4 条件つきで可）
 
 ### 編集は指摘された箇所だけを対象にする（全文書き直しの条件）
 
-**既定は部分編集である。** 直す行が決まっているなら、`old_string` / `new_string` はその行の周辺までに狭める。数か所を直せば済むファイルを全文書き直しで出力する形は、`python3` の heredoc と同じコストを、ツールを替えただけで払っている。
-
-**ファイルを全文書いてよいのは、ファイルそのものを置き換える意図があるときだけである。** 該当するのは次の 3 つで、それ以外は部分編集にする。
-
-- **新規ファイルの作成** — 既存本文が無いので、運ぶ重複がそもそも発生しない
-- **ファイル全体の作り直し** — 構成の組み替えや生成物の再生成で、変更後の本文が元の本文とほとんど共有しない場合
-- **部分編集のほうが大きくなる場合** — 変更箇所がファイル全域に散っていて、`old_string` / `new_string` の合計が全文を超えるとき。このときも全文は **Write ツール**で書く — ヒアドキュメントやインタプリタで書き戻す形は、この例外でもガードに拒否される
+**既定は部分編集である。** `old_string` / `new_string` は直す行の周辺までに狭める — Edit / Write の全文書き直しは禁じている形と同じコストを払う。全文を書いてよいのは次の 3 つだけ:
 
-**レビュー指摘の修正がこの規則の主戦場である。** 「この行の条件が逆」「この定数を切り出す」といった局所的な指摘ほど、部分編集は小さくなる。一方で全文書き直しのコストはファイルの大きさで決まり、指摘の小ささでは下がらない。**指摘が局所的であるほど、全文書き直しとの差は開く。**
-
-実測では 1 ランで約 2 分 45 秒が、すでに存在する行を打ち直すことに使われていた（joshuafolkken/kit#1260）。内訳は `docs/maintainers/file-edits-rationale.md` → "Measured cost of whole-file rewrites"。
+- 新規ファイルの作成
+- ファイル全体の作り直し — 変更後の本文が元とほとんど共有しない場合
+- 部分編集のほうが大きくなる場合 — `old_string` / `new_string` の合計が全文を超えるとき（このときも Write で書く）
 
 ### `sed -i` を使う前に満たす 4 条件
 
-`sed` が安いのは事実だが、Edit と違って**一致した全行**を書き換え、**一致が 0 件でも黙って成功する**。Edit の一意性検査に相当するものが無いので、使う前に次を満たす。
+`sed` は一致した全行を書き換え、一致 0 件でも黙って成功する。使う前に次を満たす。
 
-1. **出現回数を先に数える** — `grep -o '<pattern>' <file> | wc -l` が `1` であること。**`grep -c` を使ってはならない** — 数えるのは一致した「行数」であって出現回数ではないので、同じ行に 2 回出る場合も `1` を返す。`s///` は 1 行につき 1 回しか置換しないため、そこを一意と読むと**半分だけ書き換わったファイル**が黙って残る。`0` なら何も起きないまま成功して返る
-2. **メタ文字を持ち込まない — パターン側と置換語側の両方** — 区切りの `/`、`&`、`\`、正規表現の `.` `*` `[` `]` `^` `$` のいずれかがどちらかに入るなら Edit を使う。散文が対象のこの repository では `/` とバッククォートが頻出し、**危ないのはむしろパターン側**である（`s/prompts\/…/…/` はエスケープを 1 つ落とすだけで `unterminated 's' command`、`.` は書き手が意図していない箇所に静かに一致する）
-3. **`-i` の引数はプラットフォームで違う** — BSD / macOS は `sed -i '' 's/…/…/' file`、GNU / Linux は `sed -i 's/…/…/' file`。片方の形を他方で走らせると、エラーになるか `''` という名前のバックアップファイルが残る。**配布ドキュメントに手順として書くときは必ずこの差を明示する** — kit の成果物は両方のプラットフォームの consumer に届く
-4. **編集後に自分で整形する** — `.claude/settings.json` の `PostToolUse` フックは `Bash` にも一致する（joshuafolkken/kit#1337）が、渡されるペイロードにはコマンドしか入らずファイルパスが無いため、Bash 経由の編集では整形は走らない。`sed` で表の行や折り返しのある段落に触れたら、続けて `pnpm josh format` を走らせる。**`format:edited` は手で呼べない** — フックが渡す JSON を stdin から読んで `tool_input.file_path` を取り出す設計で、引数にパスを取らないからである。放置すると `pnpm josh lint`（`prettier --check .`）が後から落ちる
+1. **出現回数を先に数える** — `grep -o '<pattern>' <file> | wc -l` が `1` であること。`grep -c` は行数を数えるので使わない
+2. **メタ文字を持ち込まない — パターン側と置換語側の両方** — `/`、`&`、`\`、`.` `*` `[` `]` `^` `$` のいずれかが入るなら Edit を使う
+3. **`-i` の引数はプラットフォームで違う** — BSD / macOS は `sed -i '' 's/…/…/' file`、GNU / Linux は `sed -i 's/…/…/' file`。配布ドキュメントに書くときはこの差を明示する
+4. **編集後に自分で整形する** — Bash 経由の編集では `PostToolUse` の整形が走らない（joshuafolkken/kit#1337）ので `pnpm josh format` を走らせる（`format:edited` は手で呼べない）
 
-**4 条件のどれかが面倒に見えたら、そこが Edit を使う場所である。** `sed` はコストを下げるための例外であって、既定の編集手段ではない。
+**4 条件のどれかが面倒に見えたら、そこが Edit を使う場所である。**
 
-| 形                                                 | 可否         | 理由                                                      |
-| -------------------------------------------------- | ------------ | --------------------------------------------------------- |
-| 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`）        | 可           | 本文を運ばない                                            |
+| 形                                               | 可否                |
+| ------------------------------------------------ | ------------------- |
+| Edit（数行の old / new）                         | 可                  |
+| `sed -i` の短い置換                              | 上の 4 条件つきで可 |
+| `python3 - <<'PY'` で書き戻す                    | 不可                |
+| `cat > file <<'EOF'`（既存ファイル）             | 不可                |
+| `cat > new-file <<'EOF'`（新規、長文なら Write） | 可                  |
+| `cat > edit.py <<'EOF'`（書き込むスクリプト）    | 不可                |
+| 読み取り（`cat` / `sed -n` / `grep`）            | 可                  |
 
 ### なぜコストが二重になるか
 
-インタプリタで書き戻す形は、編集後の本文が**コマンド本文とファイルの両方**に載る。さらに悪いのは持続性である。**コマンド本文は、書いた時点以降のすべてのリクエストで読み直される。** ランの序盤に書いた編集スクリプトほど、そのランの残り全リクエストぶん課金され続ける。ファイル側は次に読んだときだけ載るのに対し、コマンド側は消えない。実測の内訳は `docs/maintainers/file-edits-rationale.md` → "Measured breakdown of command text"。
-
-### なぜ resident に置くか
-
-根拠は `docs/maintainers/file-edits-rationale.md` → "Why it is resident"。
-
-### マーカーテスト
-
-固定している内容は `docs/maintainers/file-edits-rationale.md` → "Marker tests"。
+書き戻す形は本文がコマンドとファイルの両方に載り、コマンドは以降の全リクエストで読み直される。

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

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

package/prompts/collaboration-workflow/glossary.md

@@ -1,17 +1,15 @@
 # ワークフロー用語集
 
-**これは定義集であり、規則を定める場所ではない。** 各語は 1〜2 行の定義と、その語の本文がある単一ソースへのポインタだけを持つ。手順・条件・数値は指し先が持ち、ここでは言い換えない — 言い換えた行は指し先より先に古くなる（joshuafolkken/kit#3080）。
+各語は 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"
+- **lane** — `backlogrun` が子 Issue を並行実行する、専用ブランチ・`.env`・ポートを持つ git worktree。マージは直列。→ `.claude/skills/workflow-commands/backlogrun-lanes.md` → "Lanes — running more than one child at a time"
+- **cut** — プロセスを意図して終わらせ、新しいプロセスが作業を引き継ぐ境界（ゲート前の cut、セッション 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"
+- **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 で対応する"
+- **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` → "decision-autonomy"
 - **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/execution-waves.md` → "Execution waves — parallel, then one alone, then the rest"

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

@@ -2,33 +2,25 @@
 
 ## セッション向け出力で Issue はリンク＋セッション言語の短い要約で参照する（joshuafolkken/kit#1758）
 
-番号だけの言及では、読み手は番号を内容に解決するために毎回 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 つを必ず添える。
+**規則**: セッション向け出力で Issue を指すときは、次の 2 つを必ず添える（対応前の「これから走らせる」「待機中」「対象外」の言及も含む）。
 
 1. 番号にチケットへの markdown リンク
-2. セッション言語（`JOSH_SESSION_LANG`、既定 `ja`）の短い要約タイトル
-
-書き方の例:
+2. セッション言語（`JOSH_SESSION_LANG`、既定 `ja`）の短い要約タイトル（全訳でなくてよい）
 
 - `[#<N>](https://github.com/<owner>/<repo>/issues/<N>) — <その Issue が何をするものかの短い要約>`
 
-**この引用行は手で組み立てるものではなく、`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` を参照。josh がセッション向けに出す警告・進捗行・要約行の Issue 番号は、はじめからリンク形で出るので、転記するときに組み直さなくてよい。コミットメッセージ・PR 本文・イベント行・Telegram 本文など GitHub やプログラムが読むために素の `#N` のまま出る行を写すときは、引用形に直す（`docs/maintainers/issue-citation-rationale.md` → "Why josh prints the citation form itself"）。
-
-**要約タイトルは全訳ではなく要約でよい。** 何をするものか分かれば足りる。長い訳を作ることが目的ではない。`issue:cite` が出すタイトルを、必要ならセッション言語に言い換えて使う。
-
-**対応前の言及も対象である。** 「これから走らせる」「待機中」「対象外」を並べる場面も含む。
+**この引用行は `pnpm josh issue:cite <N> [<N> ...]` が出す。** 複数 Issue は 1 呼び出しにまとめ、他リポジトリは `--repo <owner/repo>` か `owner/repo#N` 表記（詳細は [docs/josh-commands.md](https://github.com/joshuafolkken/kit/blob/main/docs/josh-commands.md) の `josh issue:cite`）。タイトルは必要ならセッション言語に言い換える。素の `#N` の行（コミットメッセージ・PR 本文・イベント行・Telegram 本文）を写すときは引用形に直す。
 
 ### 適用範囲
 
 **対象** — セッション向け出力。会話の説明、計画の提示、進捗報告、完了報告、`AskUserQuestion` の選択肢。
 
-**対象外** — GitHub 上の artifact prose（Issue 本文、Issue / PR コメント）。GitHub は issue 参照を自動でリンクし、ホバーでタイトルを出すため、この規則が解決しようとしている問題がそもそも起きない。
+**対象外** — Issue 本文、Issue / PR コメント。
 
 ### 英語固定の 3 つとは衝突しない
 
-英語のままにするものは従来どおり 3 つ（`overview.md` →「出力の言語（`JOSH_SESSION_LANG`）」）。番号に添えるセッション言語の要約は GitHub 上の**タイトル**ではなく、セッション内の散文の一部なので、タイトルの英語固定とは矛盾しない。
+要約はタイトルではなくセッション内の散文なので、`overview.md` →「出力の言語（`JOSH_SESSION_LANG`）」の英語固定とは矛盾しない。
 
 ### 停止時の担保（joshuafolkken/kit#2247）
 
-`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` を参照。
+`Stop` フック `pnpm josh stop:guard` は返信の地の文に裸の `#N` があると、`issue:cite` と同じ処理で引用行を作り `systemMessage` として表示する（モデルの手番は使わない）。引用できない番号があったときだけ停止をブロックし、`pnpm josh issue:cite <N...>` の実行形を差し戻す。差し戻されたらその実行形で引用し直す（検出が外す範囲は [docs/josh-commands.md](https://github.com/joshuafolkken/kit/blob/main/docs/josh-commands.md) の `josh stop:guard`）。