@joshuafolkken/kit 1.872.0

package/prompts/coding-standards.md

@@ -0,0 +1,382 @@
+# ESLint設定ガイド - コーディング支援用
+
+このプロジェクトのESLint設定は非常に厳格で、標準的なJavaScript/TypeScriptプロジェクトとは異なる命名規則を採用しています。新しいコード作成やリファクタリング時は必ずこのガイドを参照してください。
+
+## 📝 基本方針
+
+### コードの書き方
+
+- **シンプルで読みやすく**: 複雑な実装よりも、シンプルで理解しやすいコードを優先する
+- **現在の要件に集中**: 予定のない未来の拡張性を考慮せず、現在必要な機能のみを実装する
+- **適切な分割**: 同一ファイルに無理に実装を詰め込まず、適宜別ファイルにロジックを分割する
+- **意図が不明瞭な処理は関数に抽出**: 条件式がわかりにくい、意図がわかりにくい処理は、たとえ1行でも抽出を行い、関数名等で理解できるようにする
+- **既存のコード体系に寄り添う**: 現在のコード体系に可能な限り寄り添ったうえで、更に良いコードがかけるのであれば目指すこと
+
+### コメントとドキュメント
+
+- **コメントは必要最小限に**: コードで表現できることはコメントにしない。コード自体が説明になるように書く
+- **なぜ書いたかを説明**: 何をしているかではなく、なぜその実装にしたかを説明する場合のみコメントを書く
+- **複雑なロジックのみ**: 複雑な処理や意図が伝わりにくい部分のみにコメントを追加
+- **コメントは英語で記載**: コメントは英語で記載する
+
+### 抽象化と設計
+
+- **過度な抽象化を避ける**: 現在の要件で必要な抽象化のみを行う。将来の拡張性を考慮した抽象化は不要
+- **パターンの強制は避ける**: デザインパターンやアーキテクチャパターンを無理に適用しない
+- **コードの重複は撲滅**: コードクローン（重複）は完全に撲滅する。重複が見つかった場合は関数やモジュールに抽出して共通化する
+- **仕組みを足す前に原因を問う**: これは**書かれたコードの可読性**の規則。仕組み（フック・ガード・ルール）を足すか・どこへ置くかという**設計時の判断**は `prompts/collaboration-workflow/simplicity-first.md` の担当なので、本文を写さずそちらを参照する
+
+### エラーハンドリング
+
+- **シンプルなエラーハンドリング**: 複雑なエラーハンドリングロジックは避け、必要最小限の処理のみを行う
+- **エラーメッセージは明確に**: エラーメッセージは原因が分かるように、簡潔に記述する
+
+### 命名の考え方
+
+- **意図が明確に伝わる命名**: 変数名や関数名から、何をしているかが分かるように命名する
+- **略語は避ける**: 一般的でない略語は使わず、明確な単語を使用する
+- **長すぎる名前も避ける**: 必要以上に長い名前は避け、適切な長さで意図を表現する
+
+## 🚨 最重要：命名規則（標準と大きく異なる）
+
+### ❌ よくある間違い：camelCase を使う
+
+```typescript
+// ❌ 間違い（標準的なTypeScript）
+const userName = 'john'
+const isLoggedIn = true
+const getUserData = () => {}
+
+// ✅ 正しい（このプロジェクト）
+const user_name = 'john'
+const is_logged_in = true
+const get_user_data = () => {}
+```
+
+### 正しい命名規則
+
+- **変数・関数・パラメータ**: `snake_case`
+- **定数（const）**: `UPPER_CASE` または `snake_case`
+- **boolean変数**: `is_`, `has_`, `should_`, `can_`, `will_`, `did_` で始める
+- **型・クラス・インターフェース・Enum**: `PascalCase`
+- **Enumメンバー**: `UPPER_CASE`
+- **クラスプロパティ・メソッド**: `snake_case`
+
+## 🔧 必須：型安全性ルール
+
+### 明示的な型定義が必須
+
+```typescript
+// ❌ 間違い
+const processData = (data) => {
+	return data.map((item) => item.value)
+}
+
+// ✅ 正しい
+const process_data = (data: Array<{ value: string }>): Array<string> => {
+	return data.map((item) => item.value)
+}
+```
+
+### 禁止事項
+
+- `any` の使用は完全禁止
+- 未使用変数は禁止
+- 浮動Promiseは禁止
+- 型アサーションは制限あり
+
+### 早期returnの書き方
+
+- 条件の本体が単一の `return` だけで、かつ行長が100文字未満のときは1行で書く
+  `if (value === undefined) return default_value`
+- 100文字以上になる、または複数ステートメントがある場合はブロック構文を使う
+- **条件式が複雑な場合は関数に抽出**: 条件式の意図が不明瞭な場合は、関数に抽出して関数名で意図を明確にする
+
+  ```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
+  }
+  ```
+
+### マジックナンバーと定数化
+
+- `0`, `1`, `-1` 以外の数値リテラルは原則として定数へ抽出する
+- 繰り返し使用する文字列や識別子は定数化し、意味の分かる名前を付ける
+
+## 📁 新規作成時の手順
+
+### 1. 既存ファイルを必ず参照
+
+```bash
+# 類似機能の既存ファイルを探す
+find src -name "*.ts" -o -name "*.svelte" | grep -i [関連キーワード]
+```
+
+### 2. ファイル作成時の注意点
+
+- **Svelteファイル**: `PascalCase.svelte`（例: `UserProfile.svelte`）
+- **`*.svelte.ts` ファイル**: Svelte のリアクティブな状態やロジックを格納するファイルも `PascalCase.svelte.ts` 形式とする（例: `ThemeStore.svelte.ts`, `LocaleStore.svelte.ts`）
+- **TypeScriptファイル**: `kebab-case.ts`（例: `user-service.ts`）
+- **テストファイル**: ユニット/統合テストは `*.test.ts`（`*.spec.ts` は禁止）、コンポーネント/ブラウザテストは `*.svelte.test.ts`（`.svelte.` の中置は必須・保持する）、E2E は `src/routes/**/*.e2e.ts`。テストは対象モジュールの隣に colocate し、トップレベルの `tests/` ディレクトリは使わない（詳細は `prompts/testing-guide.md` の「Test file naming & placement」を参照）
+- **ルートファイル**: `+page.svelte`, `+layout.svelte` などは例外
+- **関数定義**: `function` で表現できる処理はアロー関数ではなく通常の `function` 構文で記述する
+- **複数関数のエクスポート**: 複数の関数を公開する場合は名前空間オブジェクト（namespace object）にまとめてエクスポートする（定数のみのエクスポートは個別で問題ない）
+
+### ファイル分割の指針
+
+- **複雑度が高い場合**: 関数の認知的複雑度が4を超える、または行数（コード行数）が25行を超える場合は分割を検討
+- **責任が複数ある場合**: 1つのファイルが複数の責任を持つ場合は、責任ごとにファイルを分割
+- **再利用性**: 他のファイルからも使用される可能性があるロジックは、別ファイルに分離
+- **メインファイルの肥大化を避ける**: メインファイルの肥大化を避けることを優先する。再利用可能な機能や独立した責任を持つ機能は、積極的に別ファイルに分割する。メインファイルは主要な処理フローに集中し、詳細な実装は別ファイルに分離する
+- **過度な分割は避ける**: 小さすぎるファイルの分割は避け、関連する機能は同じファイルにまとめる
+
+### 3. インポート/エクスポート規則
+
+```typescript
+// ❌ 間違い
+export default class UserService {}
+
+// ✅ 正しい
+export class UserService {}
+export type { UserData }
+```
+
+#### 名前空間オブジェクトエクスポート（必須）
+
+**重要**: 複数の関数を公開する場合は、必ず名前空間オブジェクト（namespace object）にまとめてエクスポートする。リファクタリング時も同様に適用する。
+
+**注意**: このルールは**関数のみ**に適用される。定数（`const`で定義された値やオブジェクト）は個別エクスポートで問題なく、名前空間オブジェクトにまとめる必要はない。
+
+```typescript
+// ❌ 間違い: 個別の関数エクスポート
+async function exec_git_branch(): Promise<string> {
+	return await exec_git_command('rev-parse --abbrev-ref HEAD')
+}
+
+async function exec_git_status(): Promise<string> {
+	return await exec_git_command('status --porcelain')
+}
+
+export { exec_git_branch, exec_git_status }
+```
+
+```typescript
+// ✅ 正しい: 名前空間オブジェクトエクスポート
+// ファイル名: git-command.ts
+// 名前空間名: git_command
+
+async function branch(): Promise<string> {
+	return await exec_git_command('rev-parse --abbrev-ref HEAD')
+}
+
+async function status(): Promise<string> {
+	return await exec_git_command('status --porcelain')
+}
+
+const git_command = {
+	branch,
+	status,
+}
+
+export { git_command }
+```
+
+**命名の工夫**:
+
+- ファイル名と名前空間名で意図を明確にする（例: `git-command.ts` → `git_command`）
+- メソッド名は短く、名前空間で補完する（例: `exec_git_branch()` → `git_command.branch()`）
+- アロー関数は使わず、通常の`function`構文を使用する
+
+**使用例**:
+
+```typescript
+// インポート
+import { git_command } from './git/git-command.js'
+
+// 使用
+const branch_name = await git_command.branch()
+const status_output = await git_command.status()
+```
+
+## 🧹 必須：Lintチェック手順
+
+### 基本ルール
+
+- **ファイルを変更したときは、最後にかならず lint チェックを行うこと**
+- エラーがある場合は修正してからコミットする
+- 変更したファイルだけでなく、依存関係にあるファイルも含めてチェックする
+
+### チェック対象
+
+- 編集したファイル、新規作成したファイル、削除したファイル（インポート元がある場合）
+- 依存ファイル：変更したファイルからインポートしているファイル、変更したファイルがインポートしているファイル、同じ機能領域のファイル
+
+### 編集後の必須作業
+
+```bash
+# 1. ESLintチェック
+pnpm run lint
+
+# 2. エラーがある場合は修正
+pnpm run lint:fix
+
+# 3. 型チェック
+pnpm run check
+
+# 4. 最終確認
+pnpm run build
+```
+
+### Agentモード運用（報告＝Lintゼロの保証）
+
+1. **変更完了直後にLintを実行**
+   - `read_lints([変更ファイルの絶対パス配列])` で初期確認
+   - **必須**: `pnpm run lint` で検証（`read_lints` は一部のESLintルールやPrettierを検出しないため）
+   - エラーが1件でもあれば修正→再実行。ゼロになるまで報告禁止
+
+2. **複数ファイル変更時**
+   - すべての関与ファイルを明示的に指定してチェック
+   - 大きな変更はファイル群ごとに区切り、群ごとにLintゼロを達成してから次へ
+
+3. **報告文**
+   - 「Lint: 0 errors（確認対象: 変更ファイル/またはsrc配下）」を明記
+   - ゼロ以外は報告不可
+
+**`read_lints` の制限**: 一部のESLintルール（例: `id-length`）やPrettierのフォーマットチェックを検出しない。報告前に必ず `pnpm run lint` で再確認すること。
+
+補足: 本運用ルールの機械可読版は `prompts/agent-lint-protocol.json` に格納。
+
+### よくあるLintエラーと対処法
+
+#### 1. 命名規則エラー
+
+```bash
+# エラー例
+error: Identifier 'userName' is not in snake_case
+
+# 修正
+const user_name = 'john'; // snake_caseに変更
+```
+
+#### 2. 型定義エラー
+
+```bash
+# エラー例
+error: Missing return type on function
+
+# 修正
+const get_user_data = (): UserData => { // 戻り値の型を明記
+```
+
+#### 3. 未使用変数エラー
+
+```bash
+# エラー例
+error: 'unusedVar' is defined but never used
+
+# 修正
+const _unused_var = 'value'; // アンダースコアプレフィックス
+```
+
+## 🎯 プロジェクト固有の設定
+
+### Svelte固有ルール
+
+- `$state` などのリアクティブ変数は再代入可能
+- Propsインターフェース名は `Props` で許可
+- DOM操作は制限あり
+
+### ファイル除外設定
+
+以下のファイルはESLint対象外：
+
+- `.storybook/**`
+- `*.config.js`
+- `src/routes/demo/**`
+- `src/stories/**`
+
+### リファクタリング除外設定
+
+ファイル先頭に `/* @refactor-ignore */` コメントが含まれるファイルは、リファクタリング提案や参考コードとして使用する際の対象から除外されます。
+
+```typescript
+#!/usr/bin/env node
+/* @refactor-ignore */
+// このファイルはリファクタリング対象外です
+```
+
+### 複雑度制限
+
+- **関数の複雑度**: 最大5
+- **認知的複雑度**: 最大4
+- **ネストレベル**: 最大2
+- **関数の行数**: 最大25行（テストファイルは35行）
+- **ファイルの行数**: 最大300行
+- **関数内の文の数**: 最大10
+- **パラメータ数**: 最大4個
+- **行数はコード行数であり物理行数ではない**: `max-lines` / `max-lines-per-function` は `skipBlankLines` と `skipComments` を有効にして動くため、空行とコメントは数えない。`wc -l` ではなく `pnpm josh lint` の報告で判断する（joshuafolkken/kit#1070）
+
+## 🔍 デバッグ用コマンド
+
+### 特定ファイルのLintチェック
+
+```bash
+pnpm exec eslint src/path/to/file.ts
+```
+
+### 自動修正可能なエラーを修正
+
+```bash
+pnpm exec eslint --fix src/path/to/file.ts
+```
+
+### 型チェックのみ
+
+```bash
+pnpm exec tsc --noEmit
+```
+
+## ⚠️ よくある間違いトップ5
+
+1. **camelCase使用** → `snake_case`に変更
+2. **型定義省略** → 明示的な型定義を追加
+3. **any使用** → 適切な型を定義
+4. **Lintチェック忘れ** → 必ず`pnpm run lint`実行
+5. **既存ファイル未参照** → 類似機能のファイルを必ず確認
+
+### その他のよくある間違い
+
+- **過度な抽象化** → 現在の要件に必要な抽象化のみを行う
+- **不要なコメント** → コードで表現できることはコメントにしない
+- **未来の拡張性を考慮** → 現在必要な機能のみを実装する
+- **意図が不明瞭な条件式** → 複雑な条件式や意図が伝わりにくい処理は関数に抽出して関数名で意図を明確にする
+
+## 📋 チェックリスト
+
+新規作成・リファクタリング時：
+
+- [ ] 既存の類似ファイルを参照した
+- [ ] 命名規則（snake_case）を守った
+- [ ] 明示的な型定義を追加した
+- [ ] `any`を使用していない
+- [ ] `pnpm run lint`でエラーがない
+- [ ] `pnpm run check`で型エラーがない
+- [ ] 複雑度制限内に収まっている
+- [ ] コードがシンプルで読みやすいか
+- [ ] 現在の要件に集中しているか（未来の拡張性を考慮していないか）
+- [ ] 過度な抽象化をしていないか
+- [ ] 不要なコメントがないか
+- [ ] 適切にファイル分割されているか
+- [ ] コードの重複（クローン）がないか
+- [ ] 条件式や意図が不明瞭な処理を関数に抽出しているか
+- [ ] 複数の関数を公開する場合は名前空間オブジェクトにまとめてエクスポートしているか（**注意**: 関数のみに適用。定数は個別エクスポートで問題ない）
+
+---
+
+**重要**: このプロジェクトのESLint設定は標準と大きく異なります。必ずこのガイドを参照し、既存ファイルのパターンに従ってコーディングしてください。

package/prompts/collaboration-workflow/consultation-vs-execution.md

@@ -0,0 +1,8 @@
+## 相談と実行を区別する（議論中にファイルを編集しない）
+
+ユーザーが「どう進めるべきか」「何をすべきか」「なぜそうなったか」を尋ねたり、目標・願望を述べたりした（「どうすべき？」「how should we…」「なぜ」「理由を知りたい」「〜したい」「〜の方が良い？」）ときは、**分析と推奨のみ**で応答する。ファイル編集・Issue 作成・その他の具体的アクションは取らない。
+
+- 具体的アクションを取ってよいのは、明示的な命令（「do it」「書き換えて」「作成して」「implement」）またはワークフローキーワード（`kickoff` / `halfrun` / `fullrun` / `backlogrun`）があるときだけ
+- 曖昧なときは propose-and-wait を既定とする（「これを実行してよいか？」と尋ねる）
+- **目標の表明は「計画の依頼」であって「実行の承認」ではない**
+- このルールは横断ドキュメント（CLAUDE.md「Distinguish consultation from execution」）のカノニカル参照

package/prompts/collaboration-workflow/cross-repo-epic.md

@@ -0,0 +1,54 @@
+## リポジトリをまたぐ EPIC
+
+1 つの要望が kit / app-kit / game-kit / joshuafolkken-com のうち複数にまたがることは珍しくない。EPIC は**他リポジトリの子 Issue を持てる**。
+
+### 書き方
+
+EPIC 本文のタスクリストに、次のどちらかの形で書く。
+
+```md
+## Progress
+
+- [ ] #101
+- [ ] joshuafolkken/app-kit#7
+- [ ] https://github.com/joshuafolkken/game-kit/issues/12
+```
+
+**状態の読み取りにローカルチェックアウトは要らない。** そのリポジトリを指定した REST パス（`gh api repos/<owner>/<repo>/issues/<n>`）で読むため、クローンが必要になるのは実装の段になってからである。
+
+**owner の制限は joshuafolkken/kit#869 のものをそのまま継承する。** 現在のリポジトリと owner が異なるリポジトリの子は、いかなる経路でも対象にならない。
+
+### 自動クローズ
+
+**他リポジトリの子の状態が全て読めた場合に限り**、EPIC は自動でクローズされる。1 件でも読めない子があれば従来どおり据え置かれる。「状態を読めないまま閉じない」という安全側の判断は変わっておらず、読む手段ができただけである。
+
+### 別 repo への依存は「公開の完了」までを条件とする
+
+**`blocked-by` は相手 Issue が closed になれば解決するが、repo をまたぐ依存ではそれでは早すぎる。** kit の Issue が closed になった時点では npm への公開がまだ終わっていない（マージ → auto-tag → publish が非同期）。その瞬間に app-kit の子を着手可能と判定すると、まだ公開されていないバージョンを取りに行って失敗するか、古いバージョンのまま実装して壊れる。**放置すると「たまに壊れる」という最も診断しにくい形で出る。**
+
+- 同一 repo 内の依存 → 相手が closed で解決
+- **別 repo の子への依存 → 相手が closed ＋ その repo が配布するパッケージの新バージョンが npm に出現、で解決**
+
+**評価は AND であり、順序が意味を持つ。** 相手が open のあいだは未解決と判定するだけで npm を見に行かない。EPIC 開始時から公開待ちで固まることはなく、「前の子が終わってから、公開されたら着手する」という待ち方になる。
+
+**待つ標的は具体的な版であり、「新しいバージョン」ではない。** 消費者が数バージョン遅れている場合、「今より新しい版が出た」を条件にすると目的の機能を含まない古い公開で満たされてしまう。相手 repo の default branch の `package.json` が持つバージョンを標的にする（`gh api` でローカルチェックアウト無しに読める）。**ただし子はもうバージョンを上げない**（joshuafolkken/kit#1486）。版が動くのは `pnpm josh release` が走ったときだけなので、標的は「子がマージされた直後の版」ではなく「その子を含むリリースが打たれた後の版」である。マージ直後の default branch の版は前回リリースのものなので、それを標的にすると待ちが即座に満たされてしまう。
+
+**ただし相手 repo が配布物を持たない場合は待たない**（joshuafolkken/kit#1129）。default branch に `package.json` が無い、あるいは `private` を宣言している repo は公開する版そのものが存在しないため、closed な blocker はそこで解決とする。待ち続けると実行上限の 8 時間まで抜けられず、しかも人が編集して解消できるものが無い。
+
+**この判定は相手 repo の manifest から読み、レジストリからは読まない。** レジストリの 404 は「公開されたことがない」だけでなく「このトークンからは見えない」（repo 名の変更、private パッケージ、`read:packages` 権限の欠如）も意味するため、それで解決としてしまうと、blocker の版がまだ公開されていないのに消費者側の子が着手してしまう。manifest の 404 にはその曖昧さが無い — その repo の Issue は既に読めているので権限は確認済みであり、無いのはファイルのほうである。読み取り自体の失敗は HTTP ステータスで区別し、従来どおり待つ。
+
+公開待ちの判定は `josh propagate` の実装を共有する。二重定義を作らない。
+
+### 実行のディスパッチ
+
+`josh epic:next` の出力は各候補の**対象リポジトリとローカルチェックアウトのパス**を含む。パスは joshuafolkken/kit#869 の地図から引く。**チェックアウトが無いリポジトリは、勝手に clone せず「ローカルチェックアウト無し」と表示する。**
+
+### EPIC を別リポジトリから参照する
+
+**クロス repo の EPIC は 1 つの repo にしか存在しない。** app-kit のセッションから kit の EPIC を参照するときは `owner/repo#N` の形で修飾する。
+
+```bash
+pnpm josh epic:next joshuafolkken/kit#858 --repo joshuafolkken/app-kit
+```
+
+**裸の `#N` は自リポジトリの別 Issue に解決される** — 番号が同じだけの、まったく別の Issue である。したがってクロス repo の EPIC には必ず修飾を付ける。`backlogrun joshuafolkken/kit#858 --only` も同じ形。

package/prompts/collaboration-workflow/distributed-docs.md

@@ -0,0 +1,7 @@
+## 配布ドキュメント・設定の変更は kit に上流化する
+
+`CLAUDE.md` および kit が配布する他のドキュメント／設定は、kit から単一ソースで配布される。
+
+- **消費者リポジトリ（app-kit / game-kit）ではこれらをローカル編集しない**: `josh sync` が編集を上書きするうえ、変更は本来上流（kit）に属する。ドキュメント／設定を編集する前に、それが配布物かどうかを確認し、配布物なら kit 側に変更を提案（Issue／PR）する
+- **kit リポジトリ自身ではあなたが配布元**なので、ここでは編集してよい。編集先は `CLAUDE.md` 1 本である（次節）
+- このルールは横断ドキュメント（CLAUDE.md「Route distributed-doc / config changes upstream to kit」）のカノニカル参照

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

@@ -0,0 +1,24 @@
+## 恒久ルールは MEMORY ではなくプロンプト／ドキュメントに書く
+
+今後のセッションでも守るべき恒久的な振る舞いのルールに気付いたときは、**kit が配布するプロンプト／ドキュメント**（`CLAUDE.md` / `prompts/*`）への変更として記述する。プロジェクト単位の自動 MEMORY（例: `~/.claude/projects/<repo-slug>/memory/`）への保存で済ませてはならない。
+
+なぜプロンプト／ドキュメントが正なのか:
+
+- **共有される**: バージョン管理下にありレビュー可能。PR で意図と経緯が残る
+- **可搬**: `josh sync` で全消費者リポジトリに配布され、別の PC・別のリポジトリ・別の AI ツール（Claude / Gemini / Cursor）にも届く
+- **監査できる**: いつ・なぜそのルールが入ったかを `git log` で追える
+
+自動 MEMORY の性質と使いどころ:
+
+- MEMORY は **1 台のマシン × 1 つのリポジトリ**にスコープされたローカルストアで、コミットされない。他の PC・他のリポジトリ・他の AI ツールからは見えない
+- したがって **MEMORY への保存は最小限に留める**。用途は「本質的にローカルで共有しようがない文脈」だけ（マシン固有のパス、個人の環境の癖など）
+- どこでも適用されるべきルールの唯一の置き場所を MEMORY にしてはならない
+
+運用:
+
+1. 恒久ルールに気付いたら、まず「これは kit のドキュメント／プロンプトに書くべきか？」を判定する。共有価値があるなら答えは常に yes
+2. 現在のターンがドキュメント変更を承認していない（相談中など）場合は、**MEMORY に黙って保存せず、プロンプト／ドキュメント変更を提案する**（→「相談と実行を区別する」「配布ドキュメント・設定の変更は kit に上流化する」）
+3. 消費者リポジトリで気付いた場合は、ローカル編集ではなく kit 側へ Issue／PR として上流化する
+4. 既に MEMORY にあるルールが実は共有すべきものだと分かったときは、プロンプト／ドキュメントへ移し、MEMORY 側の重複エントリは削除する
+
+- このルールは横断ドキュメント（CLAUDE.md「Durable rules belong in prompts/docs, not local MEMORY」）のカノニカル参照

package/prompts/collaboration-workflow/epic-audit.md

@@ -0,0 +1,56 @@
+## `josh epic:audit` — 子 Issue 群を横断して矛盾を検出する
+
+`pnpm josh epic:check` は epic **1 件の形式**を検査するが、**子 Issue 群を横断した整合性**は誰も検査していなかった。joshuafolkken/kit#858 の子を人手で監査したところ、実装を始めれば必ず詰まる矛盾が 2 件見つかり、その間ずっと `epic:check` は 4 要件すべて通過と報告していた。
+
+- **循環依存** — #863 の本文が「#864 の発見結果を使う」と書き、#864 の本文が「公開の判定は #863 と同一実装を共有する」と書いていた。どちらも `blocked-by` は空で、epic 本文は両方を「独立」と宣言していた
+- **順序矛盾** — #860 の受け入れ条件が #863 / #864 の成果物を要求していたが、依存グラフ上 #860 はその 2 件より先に走る
+
+人が「バグを探して」と指示して初めて見つかる状態では、無人実行の前提が成り立たない。
+
+### 検査項目
+
+グラフそのものの性質（循環依存、本文の宣言と `blocked-by` の食い違い）は `josh epic:next` が着手可否の計算のために既に検出しており、**その判定を利用する。検出を作り直さない。** 本コマンドが新たに担うのは、子 Issue の**本文の中身**を横断して読む 4 つと、そのうち孤立した子の検索が何を読めなかったかを報告する 2 つである。
+
+| 検査         | 種別   | 内容                                                                                                                                          |
+| ------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| 暗黙の依存   | 警告   | 子 A の本文が同じ epic の子 B を参照しているのに、どちら向きにも依存が宣言されていない                                                        |
+| 順序矛盾     | エラー | 子 A の**受け入れ条件**が子 B の成果物を参照しているのに、A が B に依存していない（先に走れる）。ただし A・B がどちらも closed なら警告に降格 |
+| 未解決の参照 | 警告   | 本文が参照する Issue が存在しない、または既にクローズ済み                                                                                     |
+| 孤立した子   | 警告   | epic を親として参照しているのに epic のタスクリストに載っていない Issue                                                                       |
+| 孤児検索     | エラー | 上記を探すための open issue 一覧そのものが読めなかった（レート制限、認証切れ）                                                                |
+| 孤児検索     | 警告   | その検索が backlog の末尾に届く前に打ち切られた（500 件のページ上限、または 50 件の一致上限）                                                 |
+
+### 警告とエラーを区別する
+
+**警告は exit code を左右せず、エラーだけが exit 1 になる。** 暗黙の依存の検査は「参照している」ことしか見ないため、後続の子への前方参照（「この部分は #864 が埋める」）にも当たる。これをエラーにすると正当な設計メモが書けなくなるので、**判断は読み手に委ね、機械は見落としを防ぐ側に徹する**。
+
+一方、受け入れ条件が後から作られるものを要求している状態は誰がどう決めても満たせないため、エラーとする。
+
+### 両端が closed の順序矛盾は警告に落とす
+
+順序矛盾がエラーである根拠は「**先に走れてしまう**」という一点にある。子が 2 件とも closed になった時点でどちらにも実行が残っておらず、その根拠は成立しない。にもかかわらずエラーのままにすると、**過去に一度でも順序を宣言し忘れた EPIC は永久に監査を通らなくなる** — `backlogrun` は epic の最初の子より前に監査を走らせるため、その EPIC は再開のたびに一歩目で止まる。joshuafolkken/kit#908 で実際に起きており、同じ状態で `epic:next` は次の子を問題無く返していた。すなわち**エラーが止める根拠と、実際に実行を阻むかどうかが食い違っていた**（joshuafolkken/kit#1010）。
+
+**「報告しない」ではなく「警告に降格」を採る。** 受け入れ条件は本文の一部なので、同じ組は暗黙の依存の検査にも当たっており、順序矛盾がその組を報告している間だけ重複が抑止されている。落とせばその組は 1 行下に `implicit dependency` として現れるだけで、**出力は 1 行も短くならず**、「受け入れ条件に書かれている」という唯一読む価値のある情報だけが失われる。短さという利点が実在しない以上、履歴を残す側を採る。closed かどうかは**確認できた場合にのみ**降格する — `epic_issue.normalize_state` は `CLOSED` 以外（`MERGED` を含む）をすべて `OPEN` に写すため、確認できない状態はエラーのまま残る。
+
+### 孤児検索の 2 件は「子の矛盾」ではない
+
+孤立した子の検査は open issue を一覧して本文をクライアント側で照合する。**一覧が読めなかった場合、以前はそれが空の結果として届いていた** — レート制限が「孤児ゼロ」という綺麗な監査結果を生み、何も読んでいないことが出力から分からなかった（joshuafolkken/kit#1033）。
+
+- **`✖ orphan search: Could not list the open issues…`** — 検査そのものが走っていないので、`epic:audit` は exit 1 になり `backlogrun` は相 0 で止まる。**対応は監査の再実行だけ**で、直すべき矛盾も決めるべき設計判断も無い — 下記の Tier A にも `needs-decision` park にも当たらない。繰り返し失敗するなら `gh auth status` とレート制限の回復を確認する
+- **`⚠ orphan search: The open-issue scan hit its …`** — 検索は走ったが backlog の新しい側だけを見た（500 件のページ上限、または epic に言及する本文 50 件で打ち切り）。監査自体は通るので、行を読んだうえで、より古い位置に孤児が予想される場合だけ人手で確認する
+
+### 実行される場所（人が指示しなくても回る）
+
+- **`backlogrun` の判断パスの前** — 一括決定の前に矛盾を洗い出す
+- **`backlogrun` が epic 項目を始めるとき** — 矛盾を抱えたまま無人実行を始めない
+- **子 Issue を追加した直後、依存を変更した直後**
+
+### 検出した矛盾は Tier A（確認せず直す）
+
+依存の付け直しも本文の記述修正も可逆であり、放置すれば必ず実装時に詰まる。**確認を挟む価値がないので、人に尋ねず修正して根拠を Issue に記録する。** 例外は「どちらの設計を採るべきかが決まらない」種類の矛盾で、これに限り該当の子に `needs-decision` を付けて park する。
+
+### 波及先の点検（計画段階の手順）
+
+機械的検査では捕まらない欠陥として、**新しい概念を導入したのに既存コードの参照箇所が更新されない**というものがある。#858 の監査では 3 件見つかった — `needs-decision` ラベルを導入するのに除外集合への追加担当が無かった、`epicrun` を導入するのに epic 本文が古いコマンドを案内し続ける点の担当が無かった、`in-progress` を付ける処理はあるが外す処理が無かった。
+
+したがって計画段階で次を行う。**新しいラベル・コマンド・状態・成果物を導入する子 Issue がある場合、既存コードでその概念を参照している箇所を列挙し、更新の担当がいずれかの子 Issue に割り当てられていることを確認する。** ラベル名は `scripts/git/issue-labels.ts` に単一ソース化されているので、そこを起点に消費者を辿れる。