@joshuafolkken/kit 1.1240.0 → 1.1373.0

package/dist/version/index.js

@@ -91,10 +91,16 @@ function parse_or_undefined(text) {
     return void 0;
   }
 }
+function parse_with(text, schema) {
+  const value = parse_or_undefined(text);
+  if (value === void 0) return void 0;
+  const parsed = schema.safeParse(value);
+  return parsed.success ? parsed.data : void 0;
+}
 function is_record(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-var json_value = { parse_or_undefined, is_record };
+var json_value = { parse_or_undefined, parse_with, is_record };
 
 // scripts/lib/schemas.ts
 import { z } from "zod";
@@ -536,6 +542,7 @@ function has_timed_out(error) {
 
 // scripts/josh/agent-session-environment.ts
 var SESSION_ID_KEY = "CLAUDE_CODE_SESSION_ID";
+var AGENT_PID_KEY = "CLAUDE_PID";
 var PARENT_SESSION_KEYS = [
   "CLAUDE_CODE_MESSAGING_SOCKET",
   "CLAUDE_CODE_MESSAGING_TOKEN",
@@ -606,6 +613,7 @@ function removed_proxy_environment(source = process.env) {
   return to_removed(loopback_proxy_keys(source, is_scanner_proxy(source)));
 }
 var agent_session_environment = {
+  AGENT_PID_KEY,
   LOOPBACK_HOSTS,
   PARENT_SESSION_KEYS,
   PROXY_CERTIFICATE_KEY,
@@ -648,22 +656,16 @@ async function check_gh_installed() {
 }
 
 // scripts/git/parse-json-array.ts
-var MALFORMED_JSON = /* @__PURE__ */ Symbol("malformed-json");
 function parse_json_loose(raw_json) {
-  try {
-    return JSON.parse(raw_json);
-  } catch (error) {
-    if (error instanceof SyntaxError) return MALFORMED_JSON;
-    throw error;
-  }
+  return json_value.parse_or_undefined(raw_json);
 }
-function parse_json_object_safe(raw_json, schema) {
+function parse_json_object_or_undefined(raw_json, schema) {
   const value = parse_json_loose(raw_json);
-  if (value === MALFORMED_JSON) return void 0;
+  if (value === void 0) return void 0;
   return schema.parse(value);
 }
 var parse_json = {
-  parse_json_object_safe
+  parse_json_object_or_undefined
 };
 
 // scripts/gh/git-gh-failure.ts
@@ -674,7 +676,7 @@ function has_gh_failure(error) {
   return error instanceof Error && Object.hasOwn(error, GH_FAILURE_FIELD);
 }
 function parse_response_status(stdout) {
-  const document = parse_json.parse_json_object_safe(stdout, error_document_schema);
+  const document = parse_json.parse_json_object_or_undefined(stdout, error_document_schema);
   if (document?.status === void 0) return void 0;
   const status = Number(document.status);
   return Number.isSafeInteger(status) ? status : void 0;
@@ -1352,7 +1354,7 @@ var version_targets = {
   project_package_path,
   read_workspace_version,
   // The manifest's filename. Exported rather than re-declared in each of `josh release`'s two
-  // halves (joshuafolkken/kit#1169): the module that already owns "where the project's manifest is"
+  // halves: the module that already owns "where the project's manifest is"
   // is where the name belongs.
   PACKAGE_JSON: PACKAGE_JSON3
 };

package/eslint/base.js

@@ -1,13 +1,14 @@
+import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
-import { includeIgnoreFile } from '@eslint/compat'
 import js from '@eslint/js'
 import stylistic from '@stylistic/eslint-plugin'
 import prettier from 'eslint-config-prettier'
-import importPlugin from 'eslint-plugin-import-x'
+import { createTypeScriptImportResolver } from 'eslint-import-resolver-typescript'
+import importPlugin, { createNodeResolver } from 'eslint-plugin-import-x'
 import promise from 'eslint-plugin-promise'
 import sonarjs from 'eslint-plugin-sonarjs'
 import unicorn from 'eslint-plugin-unicorn'
-import { defineConfig } from 'eslint/config'
+import { defineConfig, includeIgnoreFile } from 'eslint/config'
 import globals from 'globals'
 import ts from 'typescript-eslint'
 import { checkout_rooted_parser } from './checkout-rooted-parser.js'
@@ -84,9 +85,20 @@ function create_test_filename_ban_block(files, ban_entry) {
 	}
 }
 
+// joshuafolkken/kit#3653: a project `josh init` set up without Git has no `.gitignore` — init
+// leaves the Git files out there — while the generated `eslint.config.js` still names one.
+// `includeIgnoreFile` reads the file eagerly and throws ENOENT, so lint failed before it read a
+// line of the project's code. A missing file carries no patterns, which is what it means here.
+function create_gitignore_blocks(gitignore_path) {
+	const file_path = fileURLToPath(gitignore_path)
+	if (!existsSync(file_path)) return []
+
+	return [includeIgnoreFile(file_path)]
+}
+
 export function create_base_config({ gitignore_path, tsconfig_root_dir }) {
 	return defineConfig(
-		includeIgnoreFile(fileURLToPath(gitignore_path)),
+		create_gitignore_blocks(gitignore_path),
 		{
 			// joshuafolkken/kit#1112: `.claude/worktrees/` is where Claude Code puts its bridge work
 			// trees — a full checkout of the project, carrying its own repository root. Linted, every
@@ -125,7 +137,23 @@ export function create_base_config({ gitignore_path, tsconfig_root_dir }) {
 		{
 			plugins: { import: importPlugin },
 			settings: {
-				'import/resolver': { typescript: { alwaysTryTypes: true }, node: true },
+				// joshuafolkken/kit#3599: `import-x/resolver-next` is the key eslint-plugin-import-x
+				// reads. The resolvers used to sit under `import/resolver`, which the plugin ignores —
+				// the rules are only *named* `import/` here, the settings namespace stays the plugin's
+				// own — so every import fell back to the default node resolver, which does not follow
+				// an extensionless `.ts` specifier, and `no-cycle` was green over cycles it never saw.
+				'import-x/resolver-next': [
+					// `project` roots the resolver's tsconfig where the parser's is. Left out, the
+					// resolver reads the one in `process.cwd()`, so a run started anywhere else resolves
+					// no `paths` alias — the same silent miss, for every cycle that goes through one.
+					createTypeScriptImportResolver({ alwaysTryTypes: true, project: tsconfig_root_dir }),
+					createNodeResolver(),
+				],
+				// The other half of the same defect: the plugin reads the exports only of files whose
+				// extension is listed here, and its default list is JavaScript-only. A `.ts` import
+				// that resolves but is not listed is skipped just as silently as one that never
+				// resolved. The list is the plugin's own TypeScript preset's.
+				'import-x/extensions': importPlugin.flatConfigs.typescript.settings['import-x/extensions'],
 				'import-x/ignore': ['node_modules'],
 			},
 		},
@@ -228,6 +256,16 @@ export function create_base_config({ gitignore_path, tsconfig_root_dir }) {
 				// the annotation (JSDoc does not satisfy them), making them unsatisfiable there.
 				'@typescript-eslint/explicit-function-return-type': 'off',
 				'@typescript-eslint/explicit-module-boundary-types': 'off',
+				// joshuafolkken/kit#3599: `rules/import.js` switches these off because the compiler runs
+				// the same checks — which holds only for a file the compiler checks. Nothing else reads
+				// a hand-authored module's imports against the exports they name, so here they stay at
+				// the severities of the plugin's recommended preset.
+				'import-x/named': 'error',
+				'import-x/namespace': 'error',
+				'import-x/default': 'error',
+				'import-x/export': 'error',
+				'import-x/no-named-as-default': 'warn',
+				'import-x/no-named-as-default-member': 'warn',
 			},
 		},
 		// joshuafolkken/kit#1233: the test-filename bans are wired into the shared base config

package/eslint/rules/english-only-prose.js

@@ -1,5 +1,5 @@
 // Enforce the Content rule that comments and test titles are English only (Issue #2124). Every other
-// convention in CLAUDE.md's Content-rules block — naming, complexity limits, magic numbers, early
+// convention in prompts/coding-standards.md → Conventions and CLAUDE.md — naming, complexity limits, magic numbers, early
 // return, test filenames, the `../` import ban — is machine-enforced; this one alone stayed prose, so
 // a stray Japanese comment or test title linted green and could only be caught by review. The decision
 // is an AST-and-codepoint one: look at comment tokens and the title/message string literals of
@@ -95,9 +95,9 @@ const english_only_prose_rule = {
 		},
 		messages: {
 			comment:
-				'Write this comment in English. CJK codepoints are not allowed in comments (CLAUDE.md Content rules); the only exception is eslint/rules/.',
+				'Write this comment in English. CJK codepoints are not allowed in comments (prompts/coding-standards.md → Conventions); the only exception is eslint/rules/.',
 			prose:
-				'Write this test title/message in English. CJK codepoints are not allowed in describe/it/test titles or expect messages (CLAUDE.md Content rules).',
+				'Write this test title/message in English. CJK codepoints are not allowed in describe/it/test titles or expect messages (prompts/coding-standards.md → Conventions).',
 		},
 		schema: [],
 	},

package/eslint/rules/import.js

@@ -2,6 +2,18 @@ export const import_rules = {
 	// TypeScriptコンパイラが既にチェックするため無効化
 	'import/no-unresolved': 'off',
 	'import-x/no-unresolved': 'off',
+	// joshuafolkken/kit#3599: off for the same reason, and for one more. These six read the exports of
+	// the imported file, so a per-file content cache keeps a stale "no problem" for an unchanged
+	// importer after the file it imports changes. The compiler runs the first four checks on every
+	// file it type-checks; the last two never ran on a `.ts` import before the resolver was wired, so
+	// nothing that used to be reported is lost. `base.js` switches all six back on for hand-authored
+	// JavaScript, which the compiler does not check.
+	'import-x/named': 'off',
+	'import-x/namespace': 'off',
+	'import-x/default': 'off',
+	'import-x/export': 'off',
+	'import-x/no-named-as-default': 'off',
+	'import-x/no-named-as-default-member': 'off',
 	// Prettier: "@ianvs/prettier-plugin-sort-imports" と競合する
 	// インポートの順序を強制
 	// 'import/order': [

package/eslint/rules/namespace-object-export.js

@@ -2,7 +2,7 @@
 // （joshuafolkken/kit#2180）。kit の規約は「複数の関数は名前空間オブジェクト（`export { my_module }`）
 // にまとめる。定数は対象外」で、これは §4.2 のチェックリスト7項目のうち唯一 lint ルールが無く、
 // 目視でしか判定できなかった項目だった。散文の指示に頼るとドリフトするため、声高に失敗する lint
-// ルールでガードする。詳細は CLAUDE.md の Critical Conventions → Functions & exports。
+// ルールでガードする。詳細は prompts/coding-standards.md → Conventions。
 //
 // 検出対象は「インラインで export された関数定義」に限る。`export function foo` と
 // `export const foo = () => {}` / `export const foo = function () {}` を数え、2 件以上あれば違反。
@@ -13,7 +13,7 @@
 // 個別 export を許可しているため除外する。
 
 const RULE_MESSAGE =
-	'Group these exported functions into a single namespace object (`export { my_module }`). Individual function exports are only allowed when a file exports exactly one. See CLAUDE.md → Functions & exports.'
+	'Group these exported functions into a single namespace object (`export { my_module }`). Individual function exports are only allowed when a file exports exactly one. See prompts/coding-standards.md → Conventions.'
 
 // 2 件以上で違反。1 件の個別 export は許容される。
 const MIN_INDIVIDUAL_EXPORTS = 2

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1240.0",
+  "version": "1.1373.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": [
@@ -74,10 +74,13 @@
     "!scripts/cost",
     "!scripts/retrospective",
     "!scripts/dogfood",
+    "!scripts/metrics",
     "!scripts/test/classify-isolation.ts",
+    "!scripts/test/hanging-execa.ts",
     "!scripts/test/http-fault-injection.ts",
     "!scripts/test/josh-harness*.ts",
     "!scripts/test/pure-files.ts",
+    "!scripts/test/test-machine-guard.ts",
     "!scripts/test/test-network-guard.ts",
     "!scripts/test/test-repository-guard.ts",
     "!scripts/test/test-state-guard.ts",
@@ -169,7 +172,7 @@
     "@ianvs/prettier-plugin-sort-imports": "^4.7.1",
     "@playwright/test": ">=1.0.0",
     "@stylistic/eslint-plugin": "^5.10.0",
-    "eslint": "^10.0.0",
+    "eslint": "^10.4.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-import-x": "^4.17.1",
@@ -244,10 +247,10 @@
     "@eslint/compat": "^2.1.1",
     "@eslint/js": "^10.0.1",
     "@ianvs/prettier-plugin-sort-imports": "^4.7.1",
-    "@playwright/test": "^1.63.0",
+    "@playwright/test": "^1.64.0",
     "@secretlint/secretlint-rule-preset-recommend": "^13.0.7",
     "@stylistic/eslint-plugin": "^5.10.0",
-    "@types/node": "^26.6.4",
+    "@types/node": "^26.6.5",
     "@types/semver": "^7.8.0",
     "cspell": "^10.3.6",
     "esbuild": "^0.28.2",
@@ -260,31 +263,34 @@
     "eslint-plugin-unicorn": "^77.0.0",
     "eslint_d": "^15.0.3",
     "globals": "^17.13.0",
-    "lefthook": "^2.1.16",
+    "lefthook": "^2.2.1",
     "prettier": "^3.9.9",
     "prettier-plugin-svelte": "^4.1.1",
     "prettier-plugin-tailwindcss": "^0.8.1",
-    "rollup": "^4.64.0",
+    "rollup": "^4.64.4",
     "rollup-plugin-dts": "^6.5.1",
     "secretlint": "^13.0.7",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.71.0",
+    "typescript-eslint": "^8.71.1",
     "vitest": "^5.0.3"
   },
   "dependencies": {
-    "execa": "^10.0.1",
-    "js-yaml": "^5.4.2",
+    "cli-spinners": "^3.4.0",
+    "execa": "^10.1.0",
+    "js-yaml": "^5.4.3",
     "jsonc-parser": "^3.3.1",
     "ora": "^9.4.1",
     "semver": "^7.8.5",
+    "string-width": "^8.3.0",
+    "terminal-link": "^5.0.0",
     "tsx": "^4.23.15",
     "zod": "^4.6.5"
   },
   "devEngines": {
     "packageManager": {
       "name": "pnpm",
-      "version": "12.6.0+sha512.3ef68f951cb111ac204b4a5a16f0b2ddf0da56a96e0413e81d855d9f0b55ef926714709028e1cd00c405c2c5fb7b9e8ec4dc46777c805d0373c2f2ff00fd20ec",
-      "onFail": "error"
+      "version": "12.11.2+sha512.25a51652a196785af5f28bda6dfe8dc582ebefa4ac1d180221ce1390231c5fb76637822ea4b6e4633ce74acdcb0a77f725af11bad38177fdeddaee818a955cb9",
+      "onFail": "download"
     }
   },
   "scripts": {

package/pnpm-workspace.yaml

@@ -20,16 +20,14 @@ engineStrict: true
 trustLockfile: true
 
 # Security fixes often require same-day vite releases; minimumReleaseAge would block them.
-# `@types/node` and `tsx` are also excluded so routine Dependabot-style bumps are not
-# delayed by the minimumReleaseAge window.
+# Nothing else is excluded: `tsx` runs every `josh` command, so it waits out the window like any
+# other dependency (kit #3602).
 #
 # `josh init` / `josh sync` mirror this list to Safe Chain's .aikido project config (kit #2618).
 # Older Safe Chain shims ignore .aikido and can still hide an excluded release. `josh ranges`
 # checks published dependency ranges through that filtered view before a release (kit #742).
 minimumReleaseAgeExclude:
   - vite
-  - '@types/node'
-  - tsx
 
 overrides:
   svelte: ^5.55.7

package/prompts/coding-standards.md

@@ -1,61 +1,27 @@
 # コーディング指針 — lint では表せない書き方
 
-命名・関数の構文・エクスポート・ファイル名・品質上限・型安全・早期 return・マジックナンバーといった機械的な規約の単一ソースは `CLAUDE.md` → "Critical Conventions (non-standard — always apply)" である。その大半は ESLint が強制する（クラスのプロパティ・メソッドの `snake_case` など `CLAUDE.md` に書いていない細目は `eslint/rules/naming-convention.js` が持つ）。ただし **`function` 構文（アロー関数を使わない）と早期 return の 1 行形式は lint が検査しない**ので、書き手とレビューが確かめる。このファイルは本文を写さず、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`）が単一ソースである。
 
-## 📝 基本方針
-
-### コードの書き方
-
-- **シンプルで読みやすく**: 複雑な実装よりも、シンプルで理解しやすいコードを優先する
-- **現在の要件に集中**: 予定のない未来の拡張性を考慮せず、現在必要な機能のみを実装する
-- **適切な分割**: 同一ファイルに無理に実装を詰め込まず、適宜別ファイルにロジックを分割する
-- **意図が不明瞭な処理は関数に抽出**: 条件式がわかりにくい、意図がわかりにくい処理は、たとえ1行でも抽出を行い、関数名等で理解できるようにする
-- **既存のコード体系に寄り添う**: 現在のコード体系に可能な限り寄り添ったうえで、更に良いコードがかけるのであれば目指すこと
-
-### コメントとドキュメント
-
-- **コメントは必要最小限に**: コードで表現できることはコメントにしない。コード自体が説明になるように書く
-- **なぜ書いたかを説明**: 何をしているかではなく、なぜその実装にしたかを説明する場合のみコメントを書く
-- **複雑なロジックのみ**: 複雑な処理や意図が伝わりにくい部分のみにコメントを追加
-- **コメントは英語で記載**: コメントは英語で記載する
-
-### 抽象化と設計
-
-- **過度な抽象化を避ける**: 現在の要件で必要な抽象化のみを行う。将来の拡張性を考慮した抽象化は不要
-- **パターンの強制は避ける**: デザインパターンやアーキテクチャパターンを無理に適用しない
-- **コードの重複は撲滅**: コードクローン（重複）は完全に撲滅する。重複が見つかった場合は関数やモジュールに抽出して共通化する
-- **仕組みを足す前に原因を問う**: これは**書かれたコードの可読性**の規則。仕組み（フック・ガード・ルール）を足すか・どこへ置くかという**設計時の判断**は `prompts/collaboration-workflow/principles.md` → "elegant-design" の担当なので、本文を写さずそちらを参照する
+## 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
 
-### 命名の考え方
-
-- **意図が明確に伝わる命名**: 変数名や関数名から、何をしているかが分かるように命名する
-- **略語は避ける**: 一般的でない略語は使わず、明確な単語を使用する
-- **長すぎる名前も避ける**: 必要以上に長い名前は避け、適切な長さで意図を表現する
-
-### 条件式と定数
-
-- **条件式が複雑な場合は関数に抽出**: 条件式の意図が不明瞭な場合は、関数に抽出して関数名で意図を明確にする
-
-  ```typescript
-  // ❌ 意図が不明瞭
-  if (user.age >= 18 && user.country === 'JP' && user.verified === true) { ... }
-
-  // ✅ 関数に抽出して意図を明確化
-  if (is_eligible_for_service(user)) { ... }
+## 📝 基本方針
 
-  function is_eligible_for_service(user: User): boolean {
-    return user.age >= 18 && user.country === 'JP' && user.verified === true
-  }
-  ```
+一般的な書き方の助言（シンプルさ・命名・過度な抽象化の回避など）は繰り返さない。lint が強制せず、一般論でもない指針だけを置く。
 
+- **意図が不明瞭な処理は関数に抽出する**: 条件式や処理の意図がわかりにくければ、たとえ 1 行でも抽出し、関数名で意図を表す（`if (is_eligible_for_service(user))`）
+- **コメントは「なぜ」だけ、経緯は書かない**: 残すのは一行の理由（そのルールの意図）だけ。「以前は…」という経緯、Issue 番号への参照、計測値は git 履歴と Issue が保持している
 - **文字列も定数化する**: 数値リテラルの抽出は lint が強制するが、繰り返し使用する文字列や識別子も定数化し、意味の分かる名前を付ける
+- **既存のコード体系に寄り添う**: そのうえで、より良く書けるなら目指す
+- **仕組みを足す前に原因を問う**: 設計時の判断は `prompts/collaboration-workflow/principles.md` → "elegant-design" の担当。コメントの英語限定と重複の撲滅は上の「Conventions」と `principles.md` → "no-clones" が単一ソースである
 
 ## 📁 新規作成時の手順
 
@@ -76,7 +42,7 @@ find src -name "*.ts" -o -name "*.svelte" | grep -i [関連キーワード]
 
 ### 3. 名前空間オブジェクトの名付け方
 
-複数の関数を名前空間オブジェクトにまとめてエクスポートする規則そのものは `CLAUDE.md` → "Functions & exports" にある（定数は個別エクスポートでよい）。ここでは名付け方だけを述べる。
+複数の関数を名前空間オブジェクトにまとめてエクスポートする規則そのものは上記「Conventions」にある（定数は個別エクスポートでよい）。ここでは名付け方だけを述べる。
 
 - ファイル名と名前空間名で意図を明確にする（例: `git-command.ts` → `git_command`）
 - メソッド名は短く、名前空間で補完する（例: `exec_git_branch()` → `git_command.branch()`）

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

@@ -1,6 +1,6 @@
 ## ファイル編集はコマンド本文に本文を載せない
 
-`CLAUDE.md` →「Never carry a file's new text inside a shell command.」の正典。
+「ファイル本文をシェルに載せない」規則の正典。`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 条件、そしてコストである。
 

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

@@ -13,7 +13,7 @@
 
 - `[#<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` を参照。
+**この引用行は手で組み立てるものではなく、`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` が出すタイトルを、必要ならセッション言語に言い換えて使う。
 

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

@@ -1,14 +1,6 @@
 ## Step 1: Issue 作成テンプレ
 
-Issue には次の要素を必ず含める。
-
-- タイトルは簡潔で明瞭な英語で記載する（「出力の言語（`JOSH_SESSION_LANG`）」の例外）。日本語のタイトルや改善できる英語のタイトルは、実装開始前に書き換え、`gh api -X PATCH repos/{owner}/{repo}/issues/<N> -f title="<title>"` で GitHub 側も合わせる
-- 目的（何を改善したいか）
-- 現象（現在の不具合や課題）
-- 期待結果（完了時の状態）
-- 受け入れ条件（検証方法、対象画面/機能）
-
-最小テンプレート:
+タイトルは簡潔で明瞭な英語で記載する（「出力の言語（`JOSH_SESSION_LANG`）」の例外）。日本語のタイトルや改善できる英語のタイトルは、実装開始前に書き換え、`gh api -X PATCH repos/{owner}/{repo}/issues/<N> -f title="<title>"` で GitHub 側も合わせる。本文は次の最小テンプレートの節をすべて含める:
 
 ````md
 ## 背景
@@ -57,7 +49,7 @@ Issue には次の要素を必ず含める。
 
 ### `## 背景` 直下の宣言と分類ラベル
 
-起票は `pnpm josh issue:file "<title>" --body-file <本文ファイル> --depth <n>` で行う。本文の検査（`pnpm josh issue:lint <path>` と同じ）と、下表の宣言から決まる分類ラベルの付与は、このコマンドが 1 回の作成リクエストで行う。**宣言を選ぶのは起票者の判断であり、コマンドは単語から推測しない。**
+起票は `pnpm josh issue:file "<title>" --body-file <本文ファイル> --depth <n>` で行う。本文の検査（`pnpm josh issue:lint <path>` と同じ）と、下表の宣言から決まる分類ラベルの付与は、このコマンドが 1 回の作成リクエストで行う。**宣言を選ぶのは起票者の判断であり、コマンドは単語から推測しない。** 人が依頼した起票（会話での依頼も含む）には `--requested` を付ける（`kickoff.md` → "Words typed after `new`"）。
 
 | 宣言                   | 付くラベル        | 選ぶ基準                                                                                   |
 | ---------------------- | ----------------- | ------------------------------------------------------------------------------------------ |
@@ -67,6 +59,7 @@ Issue には次の要素を必ず含める。
 | `- 互換性: 破壊的変更` | `breaking-change` | 既存の利用者・API・設定の契約を変える。移行措置があっても書き、廃止対象と影響を説明する    |
 | `- 種別: 振る舞い変更` | なし              | AI の振る舞いを変える。`## 発火点` / `## ベースライン` / `## 再現` の 3 見出しが必須になる |
 
+- **持ち主の意図と違う動きは、コード・コメント・テストに書かれた設計どおりでも `- 種別: 不具合` とする。** コードは意図を写したもので、意図そのものではない。変更の形（コードか文書か）でも決めない。例: コメントとテストに固定されたまま意図より広く働く自動付与、文書だけでも意図と違う分類を生む基準
 - **`- 種別: 不具合` の Issue の回帰テストは、利用者が症状を見たのと同じ粒度で書く。** 修正前のツリーでも緑になるテストは `pnpm josh git -y` がコミットを拒否する（joshuafolkken/kit#2448）
 - **`bugfix` は PR のリリース分類であり、Issue の `bug` の代わりにしない。** `enhancement` と `breaking-change` の両方を持つ Issue の PR は `breaking-change` 一つに分類する
 - **`## 発火点`** の名前は `prompts/collaboration-workflow/rule-delivery.md` の配送表と突き合わされる

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

@@ -15,13 +15,7 @@
 
 ### ほかの単一ソースにある規則
 
-このファイルにかつて書き直されていた規則は、次の単一ソースにある。ここには繰り返さない。単一ソース化の経緯は `docs/maintainers/operating-rules-rationale.md` → "Rules that moved to their single source" にある。
-
-- **auto-merge と `completion` 通知** — `.claude/skills/workflow-commands/followup.md` → "`auto-merge` — Default `fullrun` behavior" と `.claude/skills/workflow-commands/followup.md` → "Completion notifications: always via `pnpm josh followup`"
-- **明示的な起動が必須** — `CLAUDE.md` → "Explicit invocation required (MANDATORY)"（常駐）と `.claude/skills/workflow-commands/SKILL.md` → "0. The rule that fires before any of them — explicit invocation"（スキル側の単一ソース）
-- **確認待ちで停止するときの Telegram 通知** — `CLAUDE.md` → "Mid-workflow stop notification (`confirmation`)"
-- **作業ツリーは 1 本のランが保持する（`josh run:hold`）** — `.claude/skills/workflow-commands/working-tree-hold.md` → "The working-tree hold — one run per tree"
-- **overrides の保護** — `.claude/skills/dependency-update/SKILL.md` → "1. Effective overrides live in the workspace — inspect both files"
+auto-merge と `completion` 通知・明示的な起動・`confirmation` 通知・作業ツリーの保持・overrides の保護は、それぞれの単一ソースにあり、ここには繰り返さない。移動先の一覧は `docs/maintainers/operating-rules-rationale.md` → "Rules that moved to their single source"。
 
 ### 指示されていない行動は取らない
 
@@ -57,6 +51,11 @@
 
   **4 番目だけが復元を伴わない。1〜3 はいずれも直後に `pnpm josh stash:pop "<メッセージ>"` で復元することが手順に含まれている**（stash はリポジトリ単位の 1 本のスタックを全 work tree が共有するため、位置指定や引数なしの `git stash pop` は別のレーンが最後に積んだ stash を取り込む — メッセージで対象を特定する。joshuafolkken/kit#2050）。 回収するのは異常終了したランの置き土産であって、いま実行中のランの作業ではないから、pop して戻す先がない。**代わりに stash を子の Issue にコメントで記録する** — 前提 Issue で中断するときの stash（`prerequisite.md`）と同じく、**その記録だけが後で pop させられる唯一の手がかり**であり、記録し忘れた stash は誰にも拾われない。これら以外の場面で退避したくなったときは、実行せずに先に確認する
 
+- **会話で作った実装をランへ渡す「引き渡し用の stash」も `pnpm josh stash:pop "<メッセージ>"` で復元する。当てたあと stash は消える**（経緯は `docs/maintainers/operating-rules-rationale.md` → "Why a handed-over stash is popped"）
+  - **計画には復元手順としてこの 1 行だけを書く。** `git stash apply` / `git stash pop` も「drop しない」という条件も書かない
+  - **計画がガードの拒否する復元形を指していたら、実行側は `stash:pop` に読み替えて続行し、Issue コメントに残す（Tier A）。** `needs-decision` では止まらない
+  - **stash を残すのは持ち主の判断だけである。** 持ち主が計画に理由を書き、ランはそこで止まって確認する
+
 - **staging・index の書き換え・`git commit` の直接実行は deny されており、deny には「そのターンでユーザーが明示指示した」という例外がない。** だから上記ケース 1 は AI 側では実行できず、ユーザー自身の端末で実行してもらう。ユーザーが明示的にコミットを指示した場合も、承認済みのコミットは `pnpm josh git` を通す（理由は `docs/maintainers/operating-rules-rationale.md` → "Why the index is the user's"）
 - index を守る deny と `pnpm josh rule:guard`（`worktree-mutation`・`index-mutation`・`destructive-command`・`protected-file` 行）も事故防止の実装である — 上記「指示されていない行動は取らない」→「deny と配送ガードは実装であって規則ではない」
 
@@ -69,5 +68,5 @@
 - **自己修正**は設計判断ではなく後始末である — 自分が公開した成果物の事実誤り（誤った帰属を含む）の訂正と、同じセッションで自分が特定した自分の作業の抜けの穴埋め（例: 欠けていると自分で指摘した相互リンクの追加）。どちらも可逆で、望ましい結果が 1 つしかなく、問題を迂回せず既に行った作業を修復するだけなので、回避策のリスクはない
 - **「相談と実行を区別する」との境界**: ここでの Tier A は **すでに承認され実行された作業を完了・修復する**ことに限られる。目標の表明（「〜したい」）や進め方への問い（「どうすべき？」）に対して勝手に動いてよい、という意味ではない（→ `principles.md` → "consult-vs-execute"）
 - **Tier C との境界**: 自分のコメントの訂正は Tier A。マージ・ブランチ削除・force push・スコープ外の変更は、**その問題を招いたのが自分自身であっても** Tier C のまま。確認を外しても監査証跡は外さない
-- **major のバージョン bump は Tier C**: `pnpm josh bump major` は自分の判断で実行せず、提案もしない。破壊的な変更に見えても既定は minor / patch で、major はユーザーがそのターンで明示したときだけ（0.x の major は 1.0.0 になり、戻せない公開を伴う）
+- **major のバージョン bump は Tier C**: `pnpm josh bump major` は自分の判断で実行せず、提案もしない。破壊的な変更に見えても既定は minor / patch で、major はユーザーがそのターンで明示したときだけ（0.x の major は 1.0.0 になり、戻せない公開を伴う）。`josh bump` が版を変えたら、変わった挙動の `docs/` をコミット前に更新する
 - **自動判断の記録の書き方**: Issue 駆動ワークフロー内では `pnpm josh issue:comment <N> --body-file <path>` で、採用案・不採用の代替案・なぜ採用案が明確に優位かを記載する

package/prompts/collaboration-workflow/output-bounds.md

@@ -34,7 +34,7 @@
 - パイプが避けられないなら `set -o pipefail` を前置する
 - **どの形でも、印字された判定行を読む。終了コードだけを答えにしない**
 
-**対象は結果が合否を意味するコマンドだけ** — `gate` ／ `check` ／ `lint*` ／ `cspell*` ／ `test*` ／ `eval`。**`git log | head` や `gh issue list | head` は対象外であり、意図的にそうしている。** `latest:scope` ／ `review:brief` も、判定ではなく答えを印字するので `$(...)` で受けてよい。`pnpm josh rule:guard` がパイプの手前に検証コマンドを置いた `Bash` をその場で拒否する（`rule-delivery.md`）。経緯・却下した案・検査は `docs/maintainers/output-bounds-rationale.md` → "Why the pipe rule is delivered by a trigger"。
+**対象は結果が合否を意味するコマンドだけ** — `gate` ／ `check` ／ `lint*` ／ `cspell*` ／ `test*` ／ `eval`。**`git log | head` や `gh issue list | head` は対象外であり、意図的にそうしている。** `latest:scope` ／ `review:brief` も、判定ではなく答えを印字するので `$(...)` で受けてよい。`pnpm josh pretool:guard` は検証コマンドをパイプした `Bash` を、行が検証と後段の `tail` ／全行読みの `grep` だけなら `pipefail` 前置に書き換え、他は拒否する（`rule-delivery.md`）。経緯・却下した案・検査は `docs/maintainers/output-bounds-rationale.md` → "Why the pipe rule is delivered by a trigger"。
 
 ## 検査
 

package/prompts/collaboration-workflow/overview.md

@@ -26,7 +26,7 @@
   2. **コード内コメント、テストタイトル（`describe` / `it` / `expect`）、コミットメッセージ**。
   3. **スクリプトが出力する固定文字列**: Telegram のヘッダーラベル（`Planning` / `Completion` など）、`Issue:` / `PR:` の URL ラベル、`--notify-message` 省略時の既定メッセージ。
 
-`JOSH_SESSION_LANG` は **開発者個人の設定**であり、`.env`（gitignore 済み・非コミット）に置く。**解決値は毎ターン、`UserPromptSubmit` フック（`scripts/hooks/run-hook.sh session-lang`）がコンテキストへ差し込む。** Codex も `.codex/hooks.json` で同じフックを実行する。フックが走らないハーネス（Gemini / Cursor）は `.env` を読んで解決する。各既定の理由は `docs/maintainers/overview-rationale.md` → "Why the session language defaults the way it does" にある。
+`JOSH_SESSION_LANG` は **開発者個人の設定**であり、`.env`（gitignore 済み・非コミット）に置く。**設定値は毎ターン `UserPromptSubmit` フック（`scripts/hooks/run-hook.sh session-lang`）が差し込み、未設定なら出さない。** Codex も `.codex/hooks.json` で同じフックを実行する。フックが走らないハーネス（Gemini / Cursor）は `.env` を読む。各既定の理由は `docs/maintainers/overview-rationale.md` → "Why the session language defaults the way it does" にある。
 
 ### 配布ドキュメントの層ごとの言語（joshuafolkken/kit#2997）
 

package/prompts/collaboration-workflow/plan-comment.md

@@ -2,6 +2,7 @@
 
 1. 提案を人間が判断する
 2. 採用した計画を Issue に記録する（Issue body が空の場合は計画をファイルに書き、`gh api -X PATCH repos/{owner}/{repo}/issues/<N> --field body=@<path>` で body に書き込む — 本文はパスで渡し、シェルの二重引用符には載せない（`shell-body.md`）。body が既にある場合は `pnpm josh issue:comment <N> --body-file <path>` でコメント追加する）
+   - **計画が stash の復元を含むとき（会話で先に作った実装を stash でランへ渡す場合を含む）、復元手順には `pnpm josh stash:pop "<メッセージ>"` だけを書く。** `git stash apply` / `git stash pop` と「drop しない」という条件は書かない — 単一ソースは `operating-rules.md` → "no-self-staging"
 3. Telegram で計画開始を通知する:
 
    ```bash
@@ -20,7 +21,7 @@
    ```
 5. メインブランチへ切り替えて最新を取得する:
    ```bash
-   git switch main && git pull
+   pnpm josh ms
    ```
 6. 依存関係の更新はコマンドに問う — `pnpm josh latest:scope` が `required` と答えたときだけ `pnpm josh latest` を実行し、`dependency-update` スキルに従う（単一ソースは `.claude/skills/workflow-commands/latest-gate.md`）。脆弱性への override は `pnpm-workspace.yaml` の `overrides` に書く（pnpm 11/12 は `package.json` の `pnpm.overrides` を無視する）。
    ステップ 4 で stash した場合は、ここでメッセージ指定で復元する（stash は全 work tree が共有するため、位置指定や引数なしの `git stash pop` は使わない — joshuafolkken/kit#2050）:

package/prompts/collaboration-workflow/principles.md

@@ -1,12 +1,12 @@
 # 原則
 
-**このファイルは、`CLAUDE.md` の Communication 節が指す 7 つの原則の単一ソースである。** 各節は `CLAUDE.md` から `prompts/collaboration-workflow/principles.md` → "見出し" の形で引かれ、`pnpm josh doc:section` で解決する。経緯と適用例は各節が指す [`docs/maintainers/principles-rationale.md`](../../docs/maintainers/principles-rationale.md) の節にあり、実行中には読まない。
+**このファイルは、`CLAUDE.md` の Communication 節が指す原則の単一ソースである。** 各節は `CLAUDE.md` から `prompts/collaboration-workflow/principles.md` → "見出し" の形で引かれ、`pnpm josh doc:section` で解決する。経緯と適用例は各節が指す [`docs/maintainers/principles-rationale.md`](../../docs/maintainers/principles-rationale.md) の節にあり、実行中には読まない。
 
 ## no-clones — クローン禁止・単一ソース化
 
 既存の非自明なロジックを「ソースを変えずに済ませる」ために**コピー・移植・再実装することは既定で禁止**する。すでにどこか（別ファイル・別モジュール・別**パッケージ＝上流依存を含む**）に存在するロジックを複製しようとした瞬間が、**単一ソース化**（全消費者が import する共有モジュール／export／パッケージ）のシグナルである。コピーではなく単一ソース化する。
 
-- **既存の重複は再重複の免罪符にならない**: すでに一度クローンされている（例: jgame が kit をコピー）なら、共有抽象化はとっくに必要だったということ。3 つ目のコピーを足さず、重複の存在を surface する
+- **既存の重複は再重複の免罪符にならない**: すでに一度クローンされている（例: josh-game が kit をコピー）なら、共有抽象化はとっくに必要だったということ。3 つ目のコピーを足さず、重複の存在を surface する
 - **「上流を参照する」は「再利用する」の意**であって、「そのコードを貼り付ける」ではない
 - **「X を触るな」という制約はクローンを黙って正当化しない**: クリーンな修正には上流（kit）の変更が要る／代替はクローン、というトレードオフを先にユーザーへ提示する（「クリーンな修正は kit の変更が必要、代替はクローン、どちらにする？」）
 - 複製は、単一ソース化の代替案とそのコストを提示し、**ユーザーの明示承認を得た後にのみ**行う
@@ -22,6 +22,24 @@
 
 **書かれたコードの可読性**（意図が伝わる命名、過度な抽象化を避ける、など）は `prompts/coding-standards.md` の担当で、こちらは**設計時にどの仕組みを足すか・どこへ置くかを決める**規則。両者は別レイヤーなので、片方の本文をもう片方へ写さず、互いを指すだけにする。
 
+## quality-priority — 品質目標が衝突したときの優先順位
+
+品質目標は 3 段に分かれる。上の段は、下の段のために犠牲にしない。
+
+1. **正しさ** — 仕様どおりに動き、検証ゲートが緑であること。ほかのどの目標のためにも犠牲にしない
+2. **同列で、どれも悪化させない** — 次の 4 つに上下はない
+   - **複雑さ**（読みやすさを含む）— 初見の読み手が、前提知識なしに意図を追えること。部品や間接層を足すのは、それで読む量が減るときだけにする
+   - **冗長さ**（重複を含む）— 同じ知識を 1 か所に置く（no-clones）。既存の非自明なロジックを複製するときは、no-clones どおり代替案を提示して明示承認を得てから行う
+   - **パフォーマンス** — gate・CI・josh 起動・テストの所要時間
+   - **AI コスト** — エージェントが読み込み・出力するトークン量
+3. **コメント最小** — コメントを書きたくなったら、まず命名・分割・型で表現できないかを試す。残すのは「なぜ」だけにする
+
+2 段目の目標同士が衝突したら、次の順で決める。
+
+1. **まず、全部を満たす方法を探す** — 処理を減らす変更は、多くの場合すべてを良くする
+2. **1 つを悪くするなら、同じ変更の中で別の場所を削って埋め合わせる** — 合計を悪化させない
+3. **それでも両立しないときは、数字を示して利用者に聞く**（Tier B）— 何をどれだけ悪くして、何を得るか
+
 ## consult-vs-execute — 相談と実行を区別する
 
 ユーザーが「どう進めるべきか」「何をすべきか」「なぜそうなったか」を尋ねたり、目標・願望を述べたりした（「どうすべき？」「how should we…」「なぜ」「理由を知りたい」「〜したい」「〜の方が良い？」）ときは、**分析と推奨のみ**で応答する。ファイル編集・Issue 作成・その他の具体的アクションは取らない。
@@ -42,7 +60,7 @@
    - ルール上書きが要るなら **正しいレイヤー**（kit / app-kit の共有設定）でスコープする。消費者リポジトリでの場当たり的な一回限りの disable にしない
    - 破壊が first-party パッケージ（kit / app-kit）起因なら、**そこに Issue を立てて適切な altitude で直す**。消費者側の回避だけで済ませない（→ `upstream-interrupt.md`）
 3. **pin-back は最終手段**: fix-forward が本当に不可能／ブロックされている（例: 未リリースの上流修正待ち）ときだけ、古いバージョンへ固定する。固定するときは **理由を記録し、最新へ戻すためのトラッキング Issue を立てる**。pin-back を既定の推奨として提示してはならない
-4. **既存の保護を尊重する**: fix-forward は保護された pin を黙って書き換える許可ではない。overrides と `devEngines` の承認ゲートの単一ソースは `CLAUDE.md` → "Dependency overrides" と `dependency-update` skill である
+4. **既存の保護を尊重する**: fix-forward は保護された pin を黙って書き換える許可ではない。overrides と `devEngines` の承認ゲートの単一ソースは `CLAUDE.md` → "Decision autonomy" と `dependency-update` skill である
 5. **タイムリーに**: バンプ起因の破壊は、可能な限り同じ作業セッション内で速やかに対処し、pin の裏に先送りしない
 
 ## durable-rules — 恒久ルールは MEMORY ではなくプロンプト／ドキュメントに書く