@joshuafolkken/kit 1.1455.0 → 1.1471.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (211) hide show
  1. package/.claude/skills/dependency-update/SKILL.md +26 -55
  2. package/.claude/skills/epic-commands/SKILL.md +87 -148
  3. package/.claude/skills/epic-commands/epic-bundle.md +45 -77
  4. package/.claude/skills/epic-commands/execution-waves.md +44 -81
  5. package/.claude/skills/verify-ui/SKILL.md +25 -50
  6. package/.claude/skills/workflow-commands/background-commands.md +36 -47
  7. package/.claude/skills/workflow-commands/backlogrun-child.md +72 -85
  8. package/.claude/skills/workflow-commands/backlogrun-lanes.md +91 -121
  9. package/.claude/skills/workflow-commands/backlogrun-park.md +73 -117
  10. package/.claude/skills/workflow-commands/backlogrun-progress.md +7 -9
  11. package/.claude/skills/workflow-commands/backlogrun-recovery.md +11 -20
  12. package/.claude/skills/workflow-commands/backlogrun-steps.md +43 -52
  13. package/.claude/skills/workflow-commands/chain-rule.md +24 -34
  14. package/.claude/skills/workflow-commands/followup.md +57 -76
  15. package/.claude/skills/workflow-commands/issue-comments.md +43 -60
  16. package/.claude/skills/workflow-commands/kickoff.md +65 -74
  17. package/.claude/skills/workflow-commands/observation-filing.md +62 -107
  18. package/.claude/skills/workflow-commands/observation-ledger.md +56 -111
  19. package/.claude/skills/workflow-commands/pre-gate-cut.md +89 -138
  20. package/.claude/skills/workflow-commands/prerequisite.md +10 -15
  21. package/.claude/skills/workflow-commands/progress-watcher.md +21 -26
  22. package/.claude/skills/workflow-commands/retrospective.md +31 -50
  23. package/.claude/skills/workflow-commands/split-assessment.md +34 -58
  24. package/.claude/skills/workflow-commands/working-tree-hold.md +54 -71
  25. package/CLAUDE.md +6 -5
  26. package/dist/CLAUDE.md +6 -5
  27. package/dist/hooks/batch-guard.js +6 -6
  28. package/dist/hooks/{chunk-7WQBPLUN.js → chunk-43ZHT22P.js} +31 -15
  29. package/dist/hooks/{chunk-LIAFCXL7.js → chunk-AS74OU3D.js} +23 -7
  30. package/dist/hooks/{chunk-3C4XRYG6.js → chunk-E7OIKX5Z.js} +17 -12
  31. package/dist/hooks/{chunk-Z4XI7CZS.js → chunk-EUMACUK2.js} +18 -12
  32. package/dist/hooks/{chunk-WNLVGT7E.js → chunk-H5HVWYXK.js} +4 -4
  33. package/dist/hooks/{chunk-HHI6FO3R.js → chunk-IIGFYXKC.js} +345 -240
  34. package/dist/hooks/{chunk-GPLGZ6IC.js → chunk-J47HU5H5.js} +14 -3
  35. package/dist/hooks/{chunk-OLMO72ON.js → chunk-K4EOONYM.js} +1 -1
  36. package/dist/hooks/{chunk-D5QBTOCZ.js → chunk-K4LMBQC2.js} +4 -4
  37. package/dist/hooks/{chunk-TBJFTSUY.js → chunk-KC5AK2GF.js} +8 -6
  38. package/dist/hooks/chunk-SHGPANFB.js +56 -0
  39. package/dist/hooks/{chunk-5H4SSDSD.js → chunk-YHBZAJSV.js} +3 -3
  40. package/dist/hooks/{chunk-HFGWYGUV.js → chunk-YYPI7SJZ.js} +5 -5
  41. package/dist/hooks/codex-hook-adapter.js +13 -13
  42. package/dist/hooks/duplicate-read-guard.js +7 -7
  43. package/dist/hooks/format-edited.js +3 -3
  44. package/dist/hooks/inputs.json +216 -214
  45. package/dist/hooks/investigation-guard.js +7 -7
  46. package/dist/hooks/pretool-guard.js +12 -12
  47. package/dist/hooks/session-lang.js +6 -5
  48. package/dist/hooks/stop-guard.js +18 -14
  49. package/dist/josh.js +5 -6
  50. package/dist/managed-marker/index.js +1 -2
  51. package/dist/version/index.js +15 -12
  52. package/eslint/base.js +2 -1
  53. package/eslint/rules/unicorn.js +16 -0
  54. package/package.json +3 -3
  55. package/prompts/coding-standards.md +12 -22
  56. package/prompts/collaboration-workflow/file-edits.md +26 -44
  57. package/prompts/collaboration-workflow/gh-rest.md +20 -36
  58. package/prompts/collaboration-workflow/glossary.md +5 -7
  59. package/prompts/collaboration-workflow/issue-citation.md +7 -13
  60. package/prompts/collaboration-workflow/issue-template.md +29 -29
  61. package/prompts/collaboration-workflow/operating-rules.md +35 -44
  62. package/prompts/collaboration-workflow/output-bounds.md +15 -15
  63. package/prompts/collaboration-workflow/overview.md +14 -19
  64. package/prompts/collaboration-workflow/plan-comment.md +13 -13
  65. package/prompts/collaboration-workflow/principles.md +50 -53
  66. package/prompts/collaboration-workflow/proposal-request.md +1 -9
  67. package/prompts/collaboration-workflow/report-format.md +32 -49
  68. package/prompts/collaboration-workflow/residency.md +10 -10
  69. package/prompts/collaboration-workflow/rule-delivery.md +9 -9
  70. package/prompts/collaboration-workflow/shell-body.md +10 -20
  71. package/prompts/collaboration-workflow/turn-batching.md +8 -14
  72. package/prompts/collaboration-workflow/upstream-interrupt.md +26 -34
  73. package/prompts/collaboration-workflow/wip-cap.md +24 -30
  74. package/prompts/collaboration-workflow.md +24 -25
  75. package/prompts/refactoring.md +33 -43
  76. package/prompts/review-rubric.md +84 -129
  77. package/prompts/review.md +111 -141
  78. package/prompts/sonar-hotspot-handling.md +22 -50
  79. package/prompts/testing-guide.md +48 -99
  80. package/scripts/adopt/adopt-toolkits.ts +2 -4
  81. package/scripts/agent/agent-exit-record.ts +23 -1
  82. package/scripts/agent/codex-agent-argv.ts +7 -2
  83. package/scripts/backlog/backlog-budget-cli.ts +1 -2
  84. package/scripts/backlog/backlog-drive-carried.ts +26 -0
  85. package/scripts/backlog/backlog-drive-cli.ts +10 -5
  86. package/scripts/backlog/backlog-drive-named.ts +2 -4
  87. package/scripts/backlog/backlog-drive-restore.ts +19 -1
  88. package/scripts/backlog/backlog-drive-seats.ts +27 -0
  89. package/scripts/backlog/backlog-drive.ts +11 -6
  90. package/scripts/backlog/backlog-ready.ts +13 -6
  91. package/scripts/behavior/behavior-rules.ts +3 -2
  92. package/scripts/cost-runtime/codex-usage.ts +4 -2
  93. package/scripts/cost-runtime/cost-cli.ts +1 -2
  94. package/scripts/delegation/investigation-guard.ts +1 -1
  95. package/scripts/delegation/investigation-reads.ts +1 -1
  96. package/scripts/discovery/repo-discovery.ts +4 -2
  97. package/scripts/discovery/repo-origin.ts +2 -4
  98. package/scripts/doctor/doctor-logic.ts +6 -3
  99. package/scripts/document/document-byte-budget.ts +27 -27
  100. package/scripts/document/document-byte-check.ts +1 -2
  101. package/scripts/document/entry-read-budget.ts +2 -2
  102. package/scripts/epic/epic-audit-rationale.ts +8 -2
  103. package/scripts/epic/epic-bundle-cli.ts +1 -2
  104. package/scripts/epic/epic-chains.ts +6 -2
  105. package/scripts/epic/epic-close-comment.ts +1 -2
  106. package/scripts/gate/verification-gate.ts +7 -2
  107. package/scripts/gh/git-pr.ts +6 -2
  108. package/scripts/git/git-common-directory.ts +3 -3
  109. package/scripts/git/git-diff-reads.ts +16 -9
  110. package/scripts/git/git-execa-error.ts +1 -2
  111. package/scripts/hooks/format-edited-file.ts +10 -4
  112. package/scripts/hooks/pre-push-unit.ts +15 -4
  113. package/scripts/hooks/pretool-guard.ts +23 -29
  114. package/scripts/hooks/step-zero-notice.ts +3 -2
  115. package/scripts/init/hook-command-rewrite.ts +6 -2
  116. package/scripts/init/init-logic-deploy-vps.ts +4 -2
  117. package/scripts/issue/behavior-change-lint.ts +12 -6
  118. package/scripts/issue/issue-scout-cli.ts +3 -2
  119. package/scripts/josh/file-map-stamp.ts +1 -3
  120. package/scripts/josh/hook-decision.ts +17 -2
  121. package/scripts/lane/lane-await.ts +3 -2
  122. package/scripts/lane/lane-child-invocation.ts +14 -1
  123. package/scripts/lane/lane-guard-policy.ts +4 -4
  124. package/scripts/lane/lane-ledger.ts +9 -0
  125. package/scripts/lane/lane-load.ts +9 -2
  126. package/scripts/lane/lane-measure-cli.ts +2 -0
  127. package/scripts/lane/lane-parked.ts +18 -0
  128. package/scripts/lane/lane-process-load.ts +125 -0
  129. package/scripts/lane/lane-process-stats.ts +93 -0
  130. package/scripts/lane/lane-registry.ts +8 -3
  131. package/scripts/lane/lane-session-broker.ts +29 -5
  132. package/scripts/lane/lane-spent.ts +14 -3
  133. package/scripts/lane/lane-stats.ts +1 -0
  134. package/scripts/managed-marker/managed-marker-logic.ts +1 -2
  135. package/scripts/overrides/lockfile-overrides.ts +1 -3
  136. package/scripts/propagate/propagate.ts +1 -2
  137. package/scripts/release/release-progress.ts +3 -2
  138. package/scripts/report/report-lint.ts +7 -4
  139. package/scripts/review/review-record-cli.ts +6 -2
  140. package/scripts/rules/destructive-command.ts +6 -9
  141. package/scripts/rules/direct-filing.ts +3 -7
  142. package/scripts/rules/early-heartbeat.ts +7 -18
  143. package/scripts/rules/file-body.ts +6 -13
  144. package/scripts/rules/filing-cap.ts +3 -6
  145. package/scripts/rules/git-force.ts +5 -9
  146. package/scripts/rules/implementation-cut.ts +37 -35
  147. package/scripts/rules/index-guard.ts +4 -7
  148. package/scripts/rules/issue-comments.ts +5 -15
  149. package/scripts/rules/josh-git-bare.ts +3 -6
  150. package/scripts/rules/lane-background.ts +10 -21
  151. package/scripts/rules/lane-carry-conflict.ts +7 -17
  152. package/scripts/rules/lane-interactive-ask.ts +6 -11
  153. package/scripts/rules/lane-park.ts +5 -13
  154. package/scripts/rules/lane-split-park.ts +2 -7
  155. package/scripts/rules/lane-switch-main.ts +9 -12
  156. package/scripts/rules/oracle-consulted.ts +4 -5
  157. package/scripts/rules/piped-verification.ts +81 -31
  158. package/scripts/rules/poll-loop.ts +7 -17
  159. package/scripts/rules/pre-gate-cut.ts +7 -21
  160. package/scripts/rules/prior-comment-read.ts +7 -5
  161. package/scripts/rules/protected-files.ts +5 -9
  162. package/scripts/rules/raw-field-body.ts +3 -7
  163. package/scripts/rules/rule-body-guard.ts +4 -11
  164. package/scripts/rules/run-tail-rule.ts +6 -22
  165. package/scripts/rules/shell-body-trigger.ts +4 -6
  166. package/scripts/rules/shell-segments.ts +7 -0
  167. package/scripts/rules/stop-rules.ts +16 -29
  168. package/scripts/rules/test-declared-commit.ts +4 -10
  169. package/scripts/rules/third-party-write.ts +5 -10
  170. package/scripts/rules/worktree-guard.ts +5 -12
  171. package/scripts/run/board/run-board-github.ts +11 -3
  172. package/scripts/run/board/run-board-idle.ts +31 -0
  173. package/scripts/run/board/run-board-read.ts +9 -12
  174. package/scripts/run/board/run-board-reason.ts +7 -3
  175. package/scripts/run/board/run-board-state.ts +4 -0
  176. package/scripts/run/board/run-board-status.ts +18 -3
  177. package/scripts/run/board/run-board-thanks.ts +7 -2
  178. package/scripts/run/board/run-board-tick.ts +32 -7
  179. package/scripts/run/carry/run-carry-args.ts +1 -3
  180. package/scripts/run/carry/run-carry-conversation.ts +7 -2
  181. package/scripts/run/cut/run-cut-cli.ts +15 -20
  182. package/scripts/run/cut/run-cut-decline.ts +72 -0
  183. package/scripts/run/cut/run-cut-ready.ts +74 -0
  184. package/scripts/run/cut/run-cut-report.ts +13 -0
  185. package/scripts/run/cut/run-cut.ts +10 -1
  186. package/scripts/run/hold/run-hold-cli.ts +14 -3
  187. package/scripts/run/hold/run-hold.ts +6 -3
  188. package/scripts/run/merge/run-merge-cli.ts +30 -7
  189. package/scripts/run/merge/run-merge-ship.ts +59 -1
  190. package/scripts/run/merge/run-merge.ts +3 -2
  191. package/scripts/run/run-ending.ts +31 -3
  192. package/scripts/run/run-parent-cut-hook.ts +5 -10
  193. package/scripts/run/run-preflight.ts +1 -2
  194. package/scripts/run/run-stop-notify.ts +1 -2
  195. package/scripts/run/run-watcher-guard.ts +6 -3
  196. package/scripts/run/ship/run-ship-review-steps.ts +13 -4
  197. package/scripts/run/ship/run-ship-review.ts +15 -2
  198. package/scripts/run/tidy/run-tidy-cli.ts +3 -3
  199. package/scripts/run/tidy/run-tidy-lanes.ts +3 -2
  200. package/scripts/safe-chain/project-config.ts +7 -2
  201. package/scripts/sync/sync-hook-safety.ts +8 -2
  202. package/scripts/test/unit-worker-share.ts +3 -2
  203. package/scripts/time-runtime/time-batch-guard.ts +3 -3
  204. package/scripts/time-runtime/time-hook-transcript.ts +3 -2
  205. package/scripts/time-runtime/time-shell.ts +10 -0
  206. package/scripts/version/effective-upstream.ts +3 -4
  207. package/scripts/version/kit-version-config.ts +8 -2
  208. package/scripts/version/latest-corepack.ts +1 -2
  209. package/scripts/version/release-hold.ts +11 -4
  210. package/scripts/version/version-commands.ts +12 -4
  211. package/dist/hooks/chunk-UT7YC3N2.js +0 -56
@@ -1,59 +1,51 @@
1
1
  ## 別パッケージ起因の問題は割り込み Issue で対応する
2
2
 
3
- 作業中(実装・検証・レビュー対応のいずれの段階でも)に新たな課題を発見した場合、**即席対応を優先せず根本的な解決を先に行う**。発見した問題が、実は別パッケージ(依存パッケージや、このプロジェクトが消費している配布元 = kit / `josh` ツールなど)に起因する場合でも同様で、現在のリポジトリ内のローカル回避策(ハック・パッチ・回避コード)で押し切ってはならない。根本原因を **対象パッケージ側** で解決する。
3
+ 作業中(実装・検証・レビュー対応のどの段階でも)に見つけた問題が別パッケージ(依存パッケージ、配布元の kit / `josh` ツールなど)に起因するとき、現在のリポジトリ内のローカル回避策(ハック・パッチ・回避コード)で押し切らず、**根本原因を対象パッケージ側で解決する**。`CLAUDE.md` → "Cross-package problems → file the upstream Issue, then stop" の本体。
4
4
 
5
5
  ### 無条件ルール: 起票は確認なし、停止は必ず
6
6
 
7
- **この手順に「これは今の作業をブロックするか?」という判定は一切存在しない。** 上流の欠陥は、ブロックするものもしないものも、**発見した時点で**同じ手順を通る。例外はない。判定を置かない理由は `docs/maintainers/upstream-interrupt-rationale.md` → "Why there is no blocking test" にある。
7
+ **「今の作業をブロックするか」は判定しない。** 上流の欠陥は、発見した時点で例外なく同じ手順を通る(`docs/maintainers/upstream-interrupt-rationale.md` → "Why there is no blocking test")。
8
8
 
9
- - **トリガーは「発見」であって「ブロックし始めたとき」ではない**
10
- - **起票は Tier A(確認なし)**。起票してよいか、どのリポジトリへ起票するか、いずれもユーザー確認を取らない。対象は first-party に限る(→「第三者リポジトリへの書き込みは Tier C(明示指示が必要)」)
11
- - **停止は無条件**。Issue が存在する状態にしてから停止する。上流の修正を待つか先送りするかは、Issue を目の前にしたユーザーが決める
12
- - **`backlogrun` の中では、停止の範囲がセッション全体ではなくその子 Issue に限定される**。起票と回避策の禁止は変わらない。上流の修正を待つか先送りするかは人の判断なので、該当の子に `needs-decision` を付けて park し、依存していない他の子へ進む(→ `.claude/skills/workflow-commands/backlogrun-park.md` → "Only a person's judgement carries `needs-decision`")
9
+ - 起票は Tier A — 起票するか・どこへ起票するかをユーザーに確認しない。対象は first-party に限る(→「第三者リポジトリへの書き込みは Tier C(明示指示が必要)」)
10
+ - **停止は無条件**。Issue を作ってから停止し、待つか先送りするかはユーザーが決める
11
+ - `backlogrun` の中では、停止はその子 Issue に限る。起票と回避策の禁止は変わらない。該当の子に `needs-decision` を付けて park し、依存していない他の子へ進む(→ `.claude/skills/workflow-commands/backlogrun-park.md` → "Only a person's judgement carries `needs-decision`")
13
12
 
14
13
  ### 実行中のリポジトリ自身のラン機構の不具合
15
14
 
16
- **この手順の対象は別パッケージであり、実行中のリポジトリ自身は含まない。** kit の中で kit のラン機構(`backlog:drive`、`run:wake`、`run:carry`、レーン、分類、カウンタ、ガードなど)の不具合を見つけた場合、それは上流の欠陥ではなく**このリポジトリの割り込み**である。上流 Issue を立てて停止する代わりに、次の手順を取る。この節がその単一ソースである。
15
+ **実行中のリポジトリ自身はこの手順の対象外である。** kit の中で kit のラン機構(`backlog:drive`、`run:wake`、`run:carry`、レーン、分類、カウンタ、ガードなど)の不具合を見つけたら、上流 Issue で停止する代わりに、このリポジトリの割り込みとして次を行う。
17
16
 
18
17
  1. **起票する** — `pnpm josh issue:file "<title>" --body-file <path> --depth <n> --route interrupt --label priority:high`。上限は効かない(`wip-cap.md` →「割り込み起票 — 上限が効かない側」の条件 2)
19
- 2. **止まらずに直す** — 壊れた機構を迂回しない(回避策の禁止と、検証ゲートを緩めない規則はここでも変わらない)。`backlogrun` の中では、その割り込みを次の子にし、修正が着地してから塞がれていた子へ戻る。プールから選ぶランでは `priority:high` が先頭に並べ、epic の下では `wip-cap.md` の手順 3 で挿入する。名前を指定したランのドライバーは指定された Issue しか出さないので、`pnpm josh lane:launch <N>` で自分で dispatch する。バッチの外では `wip-cap.md` の手順 4 が変わらず効く — 起票まで済ませ、打つべき `fullrun #<N>` を報告して止まる
20
- 3. **再開できるなら自分で再開し、動くことを確かめる** — 修正のマージ後、再開の手段がある答えには人の打ち直しを求めない。手渡し済みの記録、所有者が死んだ記録、監督プロセスの停止(`warning` Telegram)には `pnpm josh run:wake --start`、`run:carry` の `standing` には `pnpm josh run:carry --resume "<invocation>" --owner "$PPID"` を自分で打つ。そのあと `pnpm josh run:wake --list` が監督プロセスを示し、そのログに次の子の dispatch が現れることを確かめて報告する
21
- 4. **人に打ち直しを求めるのは再開の手段が無いときだけ** — `mismatch`(別の起動の記録)、別の生きた所有者の `busy`。新しい承認を宣言するのは人だけ、という規則も変わらない
22
- 5. **`needs-decision` を付けない** — ランが自分で直せる不具合は人の判断を要さない(`.claude/skills/workflow-commands/backlogrun-park.md` → "Only a person's judgement carries `needs-decision`")
18
+ 2. **止まらずに直す** — 壊れた機構を迂回せず、検証ゲートも緩めない。`backlogrun` の中では割り込みを次の子にし、着地後に塞がれていた子へ戻る(プールでは `priority:high` が先頭、epic の下では `wip-cap.md` の手順 3 で挿入、名前指定のランでは `pnpm josh lane:launch <N>` で自分で dispatch)。バッチの外では `wip-cap.md` の手順 4 どおり、打つべき `fullrun #<N>` を報告して止まる
19
+ 3. **再開できるなら自分で再開し、動くことを確かめる** — 修正のマージ後、手渡し済み・所有者が死んだ記録・監督プロセスの停止(`warning` Telegram)には `pnpm josh run:wake --start`、`run:carry` の `standing` には `pnpm josh run:carry --resume "<invocation>" --owner "$PPID"` を打つ。`pnpm josh run:wake --list` が監督プロセスを示し、ログに次の子の dispatch が現れることを確かめて報告する
20
+ 4. **人に打ち直しを求めるのは再開の手段が無いときだけ** — `mismatch`(別の起動の記録)、別の生きた所有者の `busy`。新しい承認を宣言するのは人だけ
21
+ 5. **`needs-decision` を付けない**(`.claude/skills/workflow-commands/backlogrun-park.md` → "Only a person's judgement carries `needs-decision`")
23
22
 
24
23
  手順:
25
24
 
26
- 1. **現在の作業を退避する**: `git stash push -u -m "upstream-interrupt: paused #<N>"`(WIP コミットでも可)。退避したことを忘れないよう、この時点で stash を作る。メッセージ付きで積むのは、復元をメッセージで特定するため(下記ステップ 5)
27
- 2. **進行中の Issue に状況を明記する**: `pnpm josh issue:comment <N> --body-file <path>` で、(a) 作業を stash したこと、(b) 中断理由(どの別パッケージの・どんな問題で中断したか)、(c) 対象パッケージに作成した新 Issue へのリンクを `## Upstream issues` 見出しの下に `owner/repo#N` 形式で、を記載する。これにより「なぜこの Issue が一時停止しているか」と「何を待っているのか」が後から監査できる(→「起票元へのバックリンク」)
28
- 3. **対象パッケージのリポジトリに新しい Issue を作成する(確認なし)**: `pnpm josh issue:file "<root-cause title>" --body-file <body-file> --depth <n> --route tier-a --repo <owner>/<repo>`(`route:tier-a` は実装中の Tier A 起票を経路として集計するためのラベル — joshuafolkken/kit#1083)。本文の検査、本文が宣言する分類ラベルの付与、`## Origin` 節の確認、起票先での重複探し、`epic:bundle` はこのコマンドが実行する(`docs/josh-commands-backlog.md` → `josh issue:file`)。分類の単一ソースは `prompts/collaboration-workflow/issue-template.md`。根本原因・再現・期待結果を Step 1 のテンプレに沿って記載し、**本文に `## Origin` 節を置いて起票元 Issue を `owner/repo#N` 形式で書く**(→「起票元へのバックリンク」)。ここで「起票してよいか」を尋ねて停止してはならない
29
- 4. **`confirmation` Telegram を送って停止する**: 上流 Issue の URL と、何が止まっているかを本文に書く(→ `CLAUDE.md` → "Mid-workflow stop notification (`confirmation`)")。無人実行でも画面外でユーザーが気付ける。停止は Issue が既に存在する状態で行うので、ユーザーは「待つ / 先送りする」を Issue を見ながら 1 語で答えられる
30
- 5. **元の作業を再開する**: 上流の修正がマージされた、または**ユーザーが先送りを明示判断した**後に `pnpm josh stash:pop "upstream-interrupt: paused #<N>"`(位置指定や引数なしの `git stash pop` は使わない — stash は全 work tree が共有する 1 本のスタックで、別のレーンの stash を取り込む恐れがある)して、退避していた元タスクを続行する。上流 Issue を割り込みで実装するかどうかもユーザーの判断(上流パッケージの実装・PR・マージはそれぞれのワークフロー規則に従う)
25
+ 1. **現在の作業を退避する**: `git stash push -u -m "upstream-interrupt: paused #<N>"`(WIP コミットでも可)
26
+ 2. **進行中の Issue に状況を書く**: `pnpm josh issue:comment <N> --body-file <path>` で、stash したこと、中断理由(どの別パッケージのどんな問題か)、新 Issue へのリンク(`## Upstream issues` 見出しの下に `owner/repo#N` 形式、→「起票元へのバックリンク」)
27
+ 3. **対象パッケージのリポジトリに Issue を作成する(確認なし)**: `pnpm josh issue:file "<root-cause title>" --body-file <body-file> --depth <n> --route tier-a --repo <owner>/<repo>`(joshuafolkken/kit#1083)。検査・分類ラベル・重複探し・`epic:bundle` はコマンドが行う(`docs/josh-commands-backlog.md` → `josh issue:file`)。根本原因・再現・期待結果を `prompts/collaboration-workflow/issue-template.md` の Step 1 のテンプレで書き、`## Origin` 節に起票元 Issue を `owner/repo#N` 形式で書く
28
+ 4. **`confirmation` Telegram を送って停止する**: 上流 Issue の URL と何が止まっているかを書く(→ `CLAUDE.md` → "Mid-workflow stop notification (`confirmation`)")
29
+ 5. **元の作業を再開する**: 上流の修正がマージされた、またはユーザーが先送りを明示判断した後に `pnpm josh stash:pop "upstream-interrupt: paused #<N>"` で復元する(`operating-rules.md` → "no-self-staging")。上流 Issue を割り込みで実装するかもユーザーが決める
31
30
 
32
31
  ### 第三者リポジトリへの書き込みは Tier C(明示指示が必要)
33
32
 
34
- 上の「起票は確認なし」は **first-party**(`pnpm josh repo:party` が `first-party` と答えるリポジトリ)だけに成り立つ。**自分たちが所有しないリポジトリへの書き込みは、これとは別物**として扱う。
33
+ 「起票は確認なし」は first-party だけに成り立つ。
35
34
 
36
- - **判定は機械的に行い、判断に委ねない**: `pnpm josh repo:party [<owner/repo>]` が `first-party` / `third-party` / `unknown` の 1 語で答える(対象リポジトリの owner がセッションのリポジトリの owner と一致すれば **first-party**、owner を読めなければ **unknown** で third-party 扱いはしない)。**それ以外は全て third-party** で、fork も、単に contribute しているだけの org リポジトリも third-party に入る
37
- - **first-party は従来どおり**: Tier A。確認なしで起票し、双方向バックリンクを書き、停止する
38
- - **third-party は書き込みの種別を問わず Tier C**: Issue・コメント・PR・Discussion・レビューのいずれも、**その turn におけるユーザーの明示指示**なしに行ってはならない。公開は外向きかつ実質不可逆である(`docs/maintainers/upstream-interrupt-rationale.md` → "Why third-party writes are Tier C")
39
- - **third-party だと判明したときの手順**: (1) **自分たちの側の Issue** に証拠込みで所見を記録する。見出しは `## Upstream candidate` を使い、`## Upstream issues` は使わない(後者は「起票済み」を主張する見出しであるため)。(2) 報告本文の下書きをその Issue 内に用意し、ユーザーが 1 メッセージで承認できる状態にする。(3) 対象プロジェクト名と報告しようとしている内容を書いた `confirmation` Telegram を送って**停止する**
40
- - **third-party 報告の証拠バー**(下書きを提示する前に満たす):
41
- - **自プロジェクトの外で成立する最小再現**(対象の依存だけを入れた素の scaffold)。用意できない場合は「プロジェクト組み込みの再現しかない」ことを下書きに明記する
42
- - **本文の全主張が検証済み**であること。推測を事実として書かない
43
- - 同じ欠陥を扱う**既存 Issue の検索**
44
- - **取り下げも外向きの行為**: 既に起票した third-party Issue のクローズ・編集・コメントも、同じく明示指示を要する
45
- - **正しい診断は公開の許可ではない**。所見の正しさは、この節のどの要求も免除しない(事例: `docs/maintainers/upstream-interrupt-rationale.md` → "Why a correct diagnosis is not authorization")
35
+ - **判定は `pnpm josh repo:party [<owner/repo>]` が答える**: `first-party` / `third-party` / `unknown`(unknown は third-party 扱いしない)。fork や contribute しているだけの org リポジトリも third-party
36
+ - **third-party への書き込みは種別を問わず Tier C**: Issue・コメント・PR・Discussion・レビュー、既存 Issue のクローズ・編集も、その turn のユーザーの明示指示なしに行わない。正しい診断も許可ではない(`docs/maintainers/upstream-interrupt-rationale.md` → "Why third-party writes are Tier C"、`docs/maintainers/upstream-interrupt-rationale.md` → "Why a correct diagnosis is not authorization")
37
+ - third-party と判明したら: (1) 自分たちの側の Issue に証拠込みで所見を `## Upstream candidate` 見出しで記録する(`## Upstream issues` は使わない)。(2) 報告本文の下書きをその Issue 内に用意する。(3) 対象プロジェクト名と報告内容を書いた `confirmation` Telegram を送って停止する
38
+ - 下書きの前に揃える証拠: 自プロジェクトの外で成立する最小再現(無ければ「プロジェクト組み込みの再現しかない」と明記)、全主張の検証、既存 Issue の検索
46
39
 
47
40
  ### 検証ゲートを緩めることも「回避策」である
48
41
 
49
- ローカルに回避コードを書くことだけが違反ではない。**上流の欠陥に合わせて `lint` / `tsc` / `cspell` / unit / E2E の出力を絞り込む・狭める・読み替える行為も、ローカルパッチを書くのと同じ違反**であり、同じ停止を引き起こす。
42
+ **上流の欠陥に合わせて `lint` / `tsc` / `cspell` / unit / E2E の出力を絞り込む・狭める・読み替えることは、ローカルパッチと同じ違反**で、同じ停止を引き起こす。
50
43
 
51
- - 典型例: 上流が配布する設定によって生成されるディレクトリ由来の型エラーを除外し、「プロジェクトソースはエラー 0」として完了ゲートを通過したことにする
52
- - **絞り込んだことを正直に開示しても、ルールを満たしたことにはならない**。完了報告の読者は「緑ではない型チェック」を緑として受け取る
53
- - 検証ゲートは上流の欠陥に合わせて調整しない。**調整したくなった時点が、このルールの発火点**である
44
+ - 例: 上流が配布する設定で生成されるディレクトリ由来の型エラーを除外し、「プロジェクトソースはエラー 0」としてゲートを通す
45
+ - 絞り込みを開示しても、ルールを満たしたことにはならない
46
+ - ゲートを調整したくなった時点が、このルールの発火点である
54
47
 
55
48
  注意:
56
49
 
57
- - **即席回避と根本対応は「迷って選ぶもの」ではない**。上流起因と分かった時点で選択肢は根本対応だけであり、「今回は軽いから即席で」という判断はこの手順に存在しない
58
- - 上流パッケージの **マージ等の共有状態操作** は、起票と違って Tier A ではない。通常どおりそれぞれのワークフローの明示起動を要する
59
- - このルールは横断ドキュメント(CLAUDE.md「Cross-package problems → file the upstream Issue, then stop」)のカノニカル参照
50
+ - 上流起因と分かったら選択肢は根本対応だけ。「今回は軽いから即席で」はない
51
+ - 上流パッケージのマージ等の共有状態操作は Tier A ではない。それぞれのワークフローの明示起動を要する
@@ -1,73 +1,67 @@
1
1
  # オープン Issue の WIP 上限
2
2
 
3
- **単一ソースはこのファイルである。**
4
-
5
- **この規則は常駐しておらず、配送もされない — 起票するコマンドそのものが守らせる**(joshuafolkken/kit#1524 で常駐を外し、その後 `rule:guard` の配送行も外した)。`pnpm josh issue:file` が起票の前に件数を数え、上限を超えて免除が無ければ何も送らずに保留し、そこで拒否・2 つの免除・免除を決める 3 条件を印字する(`gh issue create` や `…/issues` への `title` 付き POST による直接起票は `direct-filing` が毎回拒否するので、起票は必ずこのコマンドを通る)。事前の拒否と出し直しの往復は無い。保留文の実体は `scripts/issue/issue-wip.ts` の `HELD_MESSAGE` にある(固定するテストは `docs/maintainers/wip-cap-rationale.md` → "Tests that pin the wording")。
6
-
7
- 背景・測定・経緯は保守者向けの文書にあり(上限が要る理由は `docs/maintainers/wip-cap-rationale.md` → "Why a cap is needed — the measurement")、ラン中に読む必要はない。
3
+ 常駐も配送もされず(joshuafolkken/kit#1524)、起票コマンドが守らせる(直接起票は `direct-filing` が拒否する)。保留文は `scripts/issue/issue-wip.ts` の `HELD_MESSAGE`(`docs/maintainers/wip-cap-rationale.md` → "Tests that pin the wording")、背景は `docs/maintainers/wip-cap-rationale.md` → "Why a cap is needed — the measurement"。
8
4
 
9
5
  ## 規則
10
6
 
11
7
  **オープン Issue が上限を超えている状態で新しく起票するときは、先に 1 件閉じる。**
12
8
 
13
- **件数は `pnpm josh issue:file` が起票の前に数える**(joshuafolkken/kit#3181)。手で数えることも、見積もりや記憶で済ませることもない。数え方・印字・保留の詳細は `docs/josh-commands-backlog.md` → "`josh issue:file`" にある。
9
+ **件数は `pnpm josh issue:file` が起票の前に数える**(joshuafolkken/kit#3181、`docs/josh-commands-backlog.md` → "`josh issue:file`")。手や記憶で数えない。
14
10
 
15
- - **上限は 30。** これを超える 1 件を作る前に 1 件閉じる。エージェントが読む文書(`CLAUDE.md`・`prompts/`・配布 skill)がこの数字を書くのはこの行だけで、一次情報は `scripts/issue/issue-wip.ts` の `WIP_CAP` である(一致はテストが固定する)。
16
- - コマンドは起票先(`--repo` を付ければそのリポジトリ)のオープン Issue を epic も含めて数え、`wip:` 行に件数・上限・判定を印字する。上限を超えて免除が宣言されていなければ**何も送らずに保留し、免除の問いを印字する**。
17
- - **免除を宣言するのはこのファイルの判断である** — `--route interrupt`(下の 3 条件)、`--route split` / `--route tier-a`(実行が詰まる起票)はルートそのものが宣言になる。ルートの無い実行が詰まる起票(利用者が `new` と打った入口など)は `--over-cap` を付けて出し直す。裁量起票(`--route review-cap` を含む)に `--over-cap` を付けてはならない。
11
+ - **上限は 30。** 一次情報は `scripts/issue/issue-wip.ts` の `WIP_CAP`(他の文書にこの数字を書かない)。
12
+ - コマンドは起票先(`--repo` 指定時はそのリポジトリ)のオープン Issue を epic 込みで数えて `wip:` 行に印字し、超過して免除が無ければ何も送らずに保留し、免除の問いを印字する。
13
+ - 免除の宣言: `--route interrupt`(下の 3 条件)、`--route split` / `--route tier-a`(実行が詰まる起票)はルート自体が宣言になる。ルートの無い実行が詰まる起票(利用者が `new` と打った入口など)は `--over-cap` を付けて出し直す。裁量起票(`--route review-cap` を含む)に `--over-cap` を付けてはならない。
18
14
 
19
15
  ## 超過時の手順
20
16
 
21
- 起票しようとした時点で上限を超えていたら、**その起票が裁量によるものか、実行がそれに詰まっているか、割り込みか**の 3 つに分岐する。判断ではなく、起票の種類で決まる。**上限が効くのは裁量側だけである。**
17
+ 起票の種類で分岐する。**上限が効くのは裁量側だけである。**
22
18
 
23
- **判定するのは「起票 1 件」ではなく「起票のひとまとまり」である。** 分割判定が作る子 N 件とその epic、割り込み Issue とその上流バックリンク、起票直後の `epic:bundle` が `create_epic` と答えたときの epic — これらは 1 回の起票行為であり、途中で上限に当たって半分だけ作るのが最悪の結果になる。**ひとまとまりの先頭で 1 回だけ判定し、通ったらまとまり全体を作り切る。**
19
+ **判定するのは「起票 1 件」ではなく「起票のひとまとまり」である。** 分割の子と epic、割り込みと上流バックリンク、`epic:bundle` が `create_epic` と答えた epic は、先頭で 1 回だけ判定し、通ったら全体を作り切る。
24
20
 
25
21
  ### 裁量起票 — 上限が効く側
26
22
 
27
- レビュー上限の branch 2 と、思いついた改善や気付きの記録。**起票しなくても現在の実行が完了するもの**が該当する。
23
+ レビュー上限の branch 2 と、改善や気付きの記録 — 起票しなくても現在の実行が完了するもの。
28
24
 
29
- 1. **まず 1 件閉じる。** 閉じてよいのは、実際に終わっているもの・重複・別の Issue に取って代わられたもの・もう要らないと判断できるものだけである。クローズコメントにどれに当たるかを 1 行書く。
30
- 2. **正直に閉じられるものが無いなら、起票しない。** 場所を空けるために、まだ意味のある Issue を閉じてはならない。それは上限を満たしたことにはならず、記録を壊すだけである。
31
- 3. **起票しない場合、その指摘は起票以外の出口を取る。** レビュー指摘なら branch 3(PR 本文に 1 行残して落とす)である。**これは既定の出口であり、上限に阻まれたときの代替ではない。**
25
+ 1. まず 1 件閉じる(終わった・重複・取って代わられた・不要のものだけ。クローズコメントにどれかを 1 行書く)。
26
+ 2. **正直に閉じられるものが無いなら、起票しない。** 場所を空けるために、まだ意味のある Issue を閉じてはならない。
27
+ 3. 起票しない指摘は起票以外の出口を取る。レビュー指摘なら branch 3(PR 本文に 1 行残して落とす)で、これは既定の出口であり上限に阻まれたときの代替ではない。
32
28
 
33
29
  ### 実行が詰まる起票 — 上限が効かない側
34
30
 
35
- 前提 Issue(`prerequisite.md`)、別パッケージ起因の割り込み Issue、ユーザーが `new` と打った入口、`issue:scout` が重複無しと答えた新規作業、**そして分割判定が作る子 Issue と epic**。**これらは起票しないと実行が進まない。**
31
+ 前提 Issue(`prerequisite.md`)、別パッケージ起因の割り込み Issue、ユーザーが `new` と打った入口、`issue:scout` が重複無しと答えた新規作業、そして分割判定が作る子 Issue と epic。
36
32
 
37
33
  - **上限を理由に止めない。** 理由は `docs/maintainers/wip-cap-rationale.md` → "Why a filing a run is blocked by is not stopped"。
38
- - **分割の子がここに入る理由**: 分割を検出した `fullrun` / `halfrun` は「子と epic を起票して **STOP**」と定められている(`fullrun.md` / `halfrun.md`)。**分割するかどうかを決めるのは分割判定の側**で、既定はもう「分割しない」に上がっている — 上限が二重に効く必要はない。
39
- - **超過した事実は完了報告に 1 行書く**(例: 「オープン 34 件で起票した」)。上限は可視化のための装置なので、超えたことが見えていれば役割は果たしている。
34
+ - **分割の子がここに入る理由**: 分割を検出した `fullrun` / `halfrun` は「子と epic を起票して STOP」と定められており(`fullrun.md` / `halfrun.md`)、分割するかは分割判定の側が決める。
35
+ - 超過した事実は完了報告に 1 行書く(例: 「オープン 34 件で起票した」)。
40
36
 
41
37
  ### 割り込み起票 — 上限が効かない側(3 条件で機械的に決める)
42
38
 
43
- **重大な欠陥の発見は、それが現在のランを止めていなくても捨ててはならない。** 上限の目的は増加を見えるようにすることであって、**発見を捨てることではない**(`docs/maintainers/wip-cap-rationale.md` → "Why a cap is needed — the measurement")。由来は `docs/maintainers/wip-cap-rationale.md` → "Where the interrupt category comes from"。
44
-
45
- **別パッケージ起因の割り込みとは別の区分である。** あちらは上流リポジトリへ起票して停止する手順(`upstream-interrupt.md`、`route:tier-a`)で、実行が詰まる側に属する。ここで言う割り込みは、**このリポジトリの欠陥で、発見したランをブロックしていないもの**を指す。
39
+ 重大な欠陥の発見は、ランを止めていなくても捨てない(`docs/maintainers/wip-cap-rationale.md` → "Where the interrupt category comes from")。対象はこのリポジトリの欠陥で、発見したランをブロックしていないもの(別パッケージ起因は `upstream-interrupt.md`、実行が詰まる側)。
46
40
 
47
41
  #### 3 条件 — 該当するかは判断ではない
48
42
 
49
- **次の 3 つのいずれかを満たすかどうかだけで決める。**
43
+ 次のいずれかを満たすかだけで決める。
50
44
 
51
45
  1. **検証が誤った答えを返す** — 緑であってはならないものが緑になる、または無実の変更が赤にされる
52
- 2. **文書化された作業手順が完了できなくなる** — 並列レーン、`josh propagate` など、ドキュメントに書かれた手順が現状のコードでは通らない
46
+ 2. **文書化された作業手順が完了できなくなる** — 並列レーン、`josh propagate` など、ドキュメントの手順が現状のコードでは通らない
53
47
  3. **データが失われる、またはリポジトリの外に書き込む**
54
48
 
55
- **3 つのいずれにも当たらない発見は、従来どおり裁量側の出口を取る。** 改善案、設計上の好み、未検証の疑い、「あとで直したい」はここに入らない — レビュー指摘なら branch 3(PR 本文に 1 行残して落とす)であり、それは既定の出口であって上限に阻まれたときの代替ではない。
49
+ **3 つのいずれにも当たらない発見は、従来どおり裁量側の出口を取る。** 改善案、設計上の好み、未検証の疑い、「あとで直したい」がこれに当たる。
56
50
 
57
51
  **深刻さの自己申告は条件ではない。** 理由は `docs/maintainers/wip-cap-rationale.md` → "Why self-reported severity is not a condition"。
58
52
 
59
53
  #### 該当したときの手順
60
54
 
61
- 1. **上限に関係なく起票する。** 1 件閉じることを条件にしない。起票は `pnpm josh issue:file` で行う。本文の検査、本文が宣言する分類ラベルの付与、重複探し、`epic:bundle` はこのコマンドが実行する(`docs/josh-commands-backlog.md` → `josh issue:file`)。
55
+ 1. **上限に関係なく起票する。** 1 件閉じることを条件にしない。本文の検査、分類ラベルの付与、重複探し、`epic:bundle` はコマンドが行う(`docs/josh-commands-backlog.md` → `josh issue:file`)。
62
56
 
63
57
  ```bash
64
58
  pnpm josh issue:file "<title>" --body-file <body-file> --depth <n> --route interrupt
65
59
  ```
66
60
 
67
- 2. **超過している事実と、当たった条件の番号を本文に 1 行書く**(例:「オープン 37 件で起票。3 条件のうち 2(文書化された手順が完了できない)に該当」)。**どちらか一方では足りない** — 件数だけでは判定が再現できず、条件だけでは上限の可視化が効かない。
68
- 3. **次に実行されるものとして挿入する。** epic の下にあるなら `pnpm josh epic --add <E> <N>` で、**位置を指定せずに**追加する(`<E>` が epic、`<N>` が起票した割り込み)。**`--before` / `--after` を使ってはならない。** それらは `blocked-by` を書き込み、「発見したランをブロックしていない欠陥」という割り込みの定義と矛盾する**偽の依存関係**になる。**順序は実行側が持つ** — 先に提示させたいときは、行だけを動かす `--order-before <M>` を使う。仕組みと経緯は `docs/maintainers/wip-cap-rationale.md` → "Why an addition names no position"。**epic の下に無いなら挿入先そのものが無い**ので、この手順は飛ばして 4 だけを行う。
69
- 4. **着手は、既にある承認の内側でのみ、指示を待たずに行う。** `backlogrun` の中なら、打たれたキーワードがバッチを承認しているので、割り込みは次の子として着手してよい。**バッチの外では `CLAUDE.md` →「Explicit invocation required」が変わらず効く** — 起票と挿入まで済ませたうえで、利用者に打つべきコマンド(`fullrun #<N>`)を報告して止まる。**割り込みは上限の例外であって、明示起動規則の例外ではない。**
61
+ 2. 超過している事実と当たった条件の番号を、両方とも本文に 1 行書く(例:「オープン 37 件で起票。3 条件のうち 2(文書化された手順が完了できない)に該当」)。
62
+ 3. 次に実行されるものとして挿入する。epic の下なら `pnpm josh epic --add <E> <N>` で**位置を指定せずに**追加する(`<E>` が epic、`<N>` が割り込み)。**`--before` / `--after` を使ってはならない。** それらは `blocked-by` を書き込み、**偽の依存関係**になる。**順序は実行側が持つ** — 先に提示させたいときは行だけを動かす `--order-before <M>` を使う(`docs/maintainers/wip-cap-rationale.md` → "Why an addition names no position")。**epic の下に無いなら挿入先そのものが無い**ので、4 だけを行う。
63
+ 4. 着手は既にある承認の内側でのみ、指示を待たずに行う。`backlogrun` の中なら次の子として着手してよい。バッチの外では `CLAUDE.md` →「Explicit invocation required」が効き、起票と挿入まで済ませて打つべきコマンド(`fullrun #<N>`)を報告して止まる。**割り込みは上限の例外であって、明示起動規則の例外ではない。**
70
64
 
71
- **起票と、実行されるようにするところまでが 1 つのまとまりである。** epic の下にある割り込みを起票だけして追加しなければ、`epic:next` はそれを候補にすら出さない — Issue は残るが実行されないという、コメントに埋もれるのと大差ない状態になる。**epic の外にある割り込みでは、まとまりの後半は 4 の報告そのもの**であり、打つべきコマンドを利用者に渡すまでが 1 回の行為である。上の「ひとまとまりで判定する」がここにも効く。
65
+ 起票と、実行されるようにするところまでが 1 つのまとまりである — epic の下で追加しなければ `epic:next` は候補に出さない。**epic の外にある割り込みでは、まとまりの後半は 4 の報告そのもの**である。
72
66
 
73
- **割り込みをバッチの中で単独で走らせるか、並列のレーンで走らせるか**は `.claude/skills/workflow-commands/backlogrun-lanes.md` → "A solo run" が単一ソースである(理由は `docs/maintainers/wip-cap-rationale.md` → "Why a solo run")。上限の数字の変え方は `docs/maintainers/wip-cap-rationale.md` → "Changing the cap itself"、上限が分割判定・レビュー上限と一緒に動く理由は `docs/maintainers/wip-cap-rationale.md` → "The three move together"と `docs/maintainers/wip-cap-rationale.md` → "Why the three landed in one commit"にある。
67
+ 割り込みを単独で走らせるか並列レーンで走らせるかは `.claude/skills/workflow-commands/backlogrun-lanes.md` → "A solo run" に従う(`docs/maintainers/wip-cap-rationale.md` → "Why a solo run")。上限の数字の変え方は `docs/maintainers/wip-cap-rationale.md` → "Changing the cap itself"、分割判定・レビュー上限と一緒に動く理由は `docs/maintainers/wip-cap-rationale.md` → "The three move together" と `docs/maintainers/wip-cap-rationale.md` → "Why the three landed in one commit"。
@@ -1,32 +1,31 @@
1
1
  # Issue-Driven Collaboration Workflow
2
2
 
3
- <!-- cspell:words coderabbit -->
4
-
5
- このドキュメントは、Claude / Cursor / Gemini を含む複数の AI ツールで共通に使う Issue 駆動の共同作業ワークフローの**索引**である。
3
+ 複数の AI ツール(Claude / Cursor / Gemini)で共通に使う Issue 駆動ワークフローの**索引**。
6
4
 
7
5
  ## この索引の使い方
8
6
 
9
- **これは人間が読むための索引であり、規則を定める場所ではない。** 常駐の引き金は `CLAUDE.md` に、実行中の操作手順は `.claude/skills/workflow-commands/` に、各話題の規則は下の表のファイルにあり、それぞれが自分の規則の一次情報である。この索引はそれらを言い直さない。
7
+ 人間が読むための索引であり、規則を定める場所ではない。常駐の引き金は `CLAUDE.md`、実行中の手順は `.claude/skills/workflow-commands/`、各話題の規則は下表のファイルが一次情報である。
10
8
 
11
- **必要な 1 本だけを開くこと。この索引を入口に、下の表から選ぶ。** 他の文書からこれらの話題を指すときは、索引を経由せず**本文があるファイルを直接指す**([`residency.md`](./collaboration-workflow/residency.md))。
9
+ - 下表から必要な 1 本だけを開く。
10
+ - 他の文書から話題を指すときは、索引でなく**本文があるファイルを直接指す**([`residency.md`](./collaboration-workflow/residency.md))。
12
11
 
13
- | 話題 | ファイル |
14
- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
15
- | Overview | [`overview.md`](./collaboration-workflow/overview.md) |
16
- | Step 1: Issue 作成テンプレ | [`issue-template.md`](./collaboration-workflow/issue-template.md) |
17
- | Step 2: 提案依頼(AI 共通) | [`proposal-request.md`](./collaboration-workflow/proposal-request.md) |
18
- | Step 3: 計画コメントを記録して通知する | [`plan-comment.md`](./collaboration-workflow/plan-comment.md) |
19
- | 報告フォーマット(平易な概要 + 技術詳細) | [`report-format.md`](./collaboration-workflow/report-format.md) |
20
- | セッション向け出力で Issue はリンク+セッション言語の短い要約で参照する | [`issue-citation.md`](./collaboration-workflow/issue-citation.md) |
21
- | オープン Issue の WIP 上限 | [`wip-cap.md`](./collaboration-workflow/wip-cap.md) |
22
- | 別パッケージ起因の問題は割り込み Issue で対応する | [`upstream-interrupt.md`](./collaboration-workflow/upstream-interrupt.md) |
23
- | 原則 — クローン禁止・シンプル第一・相談と実行の区別・最新優先・恒久ルールと配布物と規則の置き場所 | [`principles.md`](./collaboration-workflow/principles.md) |
24
- | ファイル編集はコマンド本文に本文を載せない | [`file-edits.md`](./collaboration-workflow/file-edits.md) |
25
- | 本文をシェルの二重引用符に載せない | [`shell-body.md`](./collaboration-workflow/shell-body.md) |
26
- | 独立した呼び出しは同じターンに載せる | [`turn-batching.md`](./collaboration-workflow/turn-batching.md) |
27
- | `gh` は REST(`gh api`)で書く — 散文の指示も含む | [`gh-rest.md`](./collaboration-workflow/gh-rest.md) |
28
- | 常駐ドキュメントと skill の分担(何を常駐に残すか) | [`residency.md`](./collaboration-workflow/residency.md) |
29
- | 引き金つき配送 — 規則を効く瞬間に届ける | [`rule-delivery.md`](./collaboration-workflow/rule-delivery.md) |
30
- | コマンド出力が文脈へ持ち込む量の上限 | [`output-bounds.md`](./collaboration-workflow/output-bounds.md) |
31
- | 運用ルール | [`operating-rules.md`](./collaboration-workflow/operating-rules.md) |
32
- | 用語集 — lane・cut・hold・park などの定義と単一ソース | [`glossary.md`](./collaboration-workflow/glossary.md) |
12
+ | 話題 | ファイル |
13
+ | ---------------------------------------------------------- | ------------------------------------------------------------------------- |
14
+ | Overview | [`overview.md`](./collaboration-workflow/overview.md) |
15
+ | Step 1: Issue 作成テンプレ | [`issue-template.md`](./collaboration-workflow/issue-template.md) |
16
+ | Step 2: 提案依頼(AI 共通) | [`proposal-request.md`](./collaboration-workflow/proposal-request.md) |
17
+ | Step 3: 計画コメントの記録と通知 | [`plan-comment.md`](./collaboration-workflow/plan-comment.md) |
18
+ | 報告フォーマット(平易な概要 + 技術詳細) | [`report-format.md`](./collaboration-workflow/report-format.md) |
19
+ | Issue はリンク+セッション言語の短い要約で参照する | [`issue-citation.md`](./collaboration-workflow/issue-citation.md) |
20
+ | オープン Issue の WIP 上限 | [`wip-cap.md`](./collaboration-workflow/wip-cap.md) |
21
+ | 別パッケージ起因の問題は割り込み Issue | [`upstream-interrupt.md`](./collaboration-workflow/upstream-interrupt.md) |
22
+ | 原則 — クローン禁止・シンプル第一・相談と実行・最新優先 等 | [`principles.md`](./collaboration-workflow/principles.md) |
23
+ | ファイル編集はコマンド本文に本文を載せない | [`file-edits.md`](./collaboration-workflow/file-edits.md) |
24
+ | 本文をシェルの二重引用符に載せない | [`shell-body.md`](./collaboration-workflow/shell-body.md) |
25
+ | 独立した呼び出しは同じターンに載せる | [`turn-batching.md`](./collaboration-workflow/turn-batching.md) |
26
+ | `gh` は REST(`gh api`)で書く | [`gh-rest.md`](./collaboration-workflow/gh-rest.md) |
27
+ | 常駐ドキュメントと skill の分担 | [`residency.md`](./collaboration-workflow/residency.md) |
28
+ | 引き金つき配送 — 規則を効く瞬間に届ける | [`rule-delivery.md`](./collaboration-workflow/rule-delivery.md) |
29
+ | コマンド出力が文脈へ持ち込む量の上限 | [`output-bounds.md`](./collaboration-workflow/output-bounds.md) |
30
+ | 運用ルール | [`operating-rules.md`](./collaboration-workflow/operating-rules.md) |
31
+ | 用語集 — lane・cut・hold・park など | [`glossary.md`](./collaboration-workflow/glossary.md) |
@@ -1,103 +1,93 @@
1
1
  # リファクタリング支援プロンプト
2
2
 
3
- このプロンプトは AI へのリファクタリング指示書です。
4
-
5
- - **「リファクタリングを提案して」** → 分析・提案のみ行い、実装はユーザーに委ねる
6
- - **「リファクタリングして」** → 優先度高・中を自動実施し、同一セッション内で収束するまで繰り返す
3
+ - 「リファクタリングを提案して」→ 分析・提案のみ。実装はユーザーに委ねる
4
+ - 「リファクタリングして」→ 優先度高・中を自動実施し、同一セッション内で収束するまで繰り返す
7
5
 
8
6
  ---
9
7
 
10
8
  ## 対象と候補の算出(`pnpm josh refactor:scan`)
11
9
 
12
- 対象ファイルの特定・スコープ拡張・lint で決まる候補の集計・収束判定は、すべて `pnpm josh refactor:scan` が計算する。手作業で grep せず、まずこのコマンドを実行する(joshuafolkken/kit#2180)。詳細は `docs/josh-commands.md` の `josh refactor:scan`。
10
+ 対象ファイル・スコープ拡張・lint 候補の集計・収束判定は `pnpm josh refactor:scan` が計算する。手作業で grep せず、まずこれを実行する(joshuafolkken/kit#2180、詳細は `docs/josh-commands.md` の `josh refactor:scan`)。
13
11
 
14
12
  ```bash
15
13
  pnpm josh refactor:scan
16
14
  ```
17
15
 
18
- コマンドが行うこと:
19
-
20
- - **対象ファイルの特定**: 作業ツリーの変更+main との差分+未追跡ファイルを起点とし、いずれも無ければ `scripts/` 配下。`demo`・`src/routes/stories`・先頭に `/* @refactor-ignore */` を持つファイルは除外する。
21
- - **スコープ拡張**: 起点ファイルから import グラフを双方向(import 元・import 先)に最大3段階たどり、新規0件で止める。拡張後のファイル集合を印字する。
22
- - **候補の集計**: プロジェクト自身の eslint に JSON で問い合わせ、次を件数と file:line で印字する — 行数・複雑度(`max-lines` / `max-lines-per-function` / `complexity` / `sonarjs/cognitive-complexity`)、型の安全性(`@typescript-eslint/no-explicit-any`)、名前空間エクスポート(`local/namespace-object-export`)、重複コード(`sonarjs/no-identical-functions`)、変数名の書式(`@typescript-eslint/naming-convention`)、重複文字列(`sonarjs/no-duplicate-string`)、マジックナンバー(`@typescript-eslint/no-magic-numbers`)、未使用コード(低優先度: `@typescript-eslint/no-unused-vars`)。件数は gate の eslint と同一なので `pnpm josh gate` と食い違わない。
23
- - **収束判定**: 高・中優先度の候補が0件なら `verdict: clear`、残っていれば `verdict: candidates`。これが「優先度高・中が0件」の判定である。低優先度(未使用コード)は報告のみで収束判定には数えない。
16
+ - 対象ファイル: 作業ツリーの変更+main との差分+未追跡ファイル。いずれも無ければ `scripts/` 配下。`demo`・`src/routes/stories`・先頭に `/* @refactor-ignore */` を持つファイルは除外。
17
+ - スコープ拡張: import グラフを双方向に最大3段階たどり、新規0件で止める。拡張後の集合を印字する。
18
+ - **候補の集計**: eslint の件数と file:line — 行数・複雑度(`max-lines` / `max-lines-per-function` / `complexity` / `sonarjs/cognitive-complexity`)、型の安全性(`@typescript-eslint/no-explicit-any`)、名前空間エクスポート(`local/namespace-object-export`)、重複コード(`sonarjs/no-identical-functions`)、変数名の書式(`@typescript-eslint/naming-convention`)、重複文字列(`sonarjs/no-duplicate-string`)、マジックナンバー(`@typescript-eslint/no-magic-numbers`)、未使用コード(低優先度: `@typescript-eslint/no-unused-vars`)。件数は `pnpm josh gate` の eslint と同一。
19
+ - 収束判定: 高・中優先度の候補が0件なら `verdict: clear`、残れば `verdict: candidates`。低優先度は報告のみで数えない。
24
20
 
25
- 行数はコード行数であり物理行数ではない — `max-lines` / `max-lines-per-function` は `skipBlankLines` と `skipComments` を有効にして数えるので、`wc -l` ではなくこのコマンド(gate と同じ eslint)の報告で判断する。
21
+ 行数はコード行数(`max-lines` / `max-lines-per-function` は `skipBlankLines` と `skipComments` 有効)。`wc -l` ではなくこのコマンドの報告で判断する。
26
22
 
27
23
  ---
28
24
 
29
25
  ## コマンドが見ない、目視で残すもの
30
26
 
31
- `refactor:scan` は決定的に読める入力(lint と import グラフ)だけを扱う。次の2つは機械的に判定できないため、コマンドの結果に加えて必ず目視で確認する:
27
+ 次の2つは機械判定できないため、コマンドの結果に加えて必ず目視で確認する:
32
28
 
33
- - **副作用の冪等性**: intersection observer・イベントハンドラ・コールバックなど、一度だけ実行すべき副作用に、状態チェックによる早期 return のガード節があるか確認する。
34
- - **似た UI 構造**: 同じ UI パターン・振る舞いが複数箇所にあり、props で差を吸収する共通コンポーネントにまとめられないか確認する。
29
+ - **副作用の冪等性**: 一度だけ実行すべき副作用(intersection observer・イベントハンドラ・コールバック)に、状態チェックで早期 return するガード節があるか。
30
+ - **似た UI 構造**: 複数箇所の同じ UI パターンを、props で差を吸収する共通コンポーネントにまとめられないか。
35
31
 
36
32
  ---
37
33
 
38
34
  ## 「リファクタリングを提案して」の動作
39
35
 
40
- 1. `pnpm josh refactor:scan` を実行して候補を網羅的に洗い出し、コマンドが見ない2項目(副作用の冪等性・似た UI 構造)を目視で補う
41
- 2. 高・中優先度の候補 → すべて提案(件数制限なし)/すべて低優先度の場合のみ → 最大3つまで提案
42
- 3. 提案のみ行い、実装はユーザーに委ねる
43
- 4. コメント提案は不要。実装可能なサンプルコードを提供する
44
- 5. このプロンプトの内容説明は不要。直接提案に移る
36
+ 1. `refactor:scan` で候補を洗い出し、目視2項目で補う
37
+ 2. 高・中優先度 → すべて提案(件数制限なし)/すべて低優先度なら最大3つ
38
+ 3. 実装はせず、コメントでなく実装可能なサンプルコードを示す
39
+ 4. このプロンプトの説明はせず、直接提案に移る
45
40
 
46
41
  ---
47
42
 
48
43
  ## 「リファクタリングして」の動作
49
44
 
50
- **対象範囲**は「対象ファイルの特定」と同一(変更しない)。
45
+ 対象範囲は「対象ファイル」と同一。
51
46
 
52
47
  ```text
53
- [対象の特定] `pnpm josh refactor:scan` が対象範囲を決める
54
- [テスト準備] 対象のふるまいを検証する unit/E2E テストを先に実装し、すべてグリーンを確認してから構造変更を始める
55
- [1回目] refactor:scan の候補 + 目視2項目で網羅的分析 → 優先度高・中をすべて実施
48
+ [テスト準備] 対象のふるまいを検証する unit/E2E テストを先に実装し、グリーンを確認してから構造変更を始める
49
+ [1回目] refactor:scan の候補 + 目視2項目 → 優先度高・中をすべて実施
56
50
  [2回目以降] refactor:scan を再実行 → 漏れがあれば実施
57
- [収束判定] refactor:scan が `verdict: clear` を返す(優先度高・中が0件)
58
- [完了] verdict: clear かつ目視2項目も0件 → 低優先度のみ報告して完了
51
+ [完了] `verdict: clear` かつ目視2項目も0件 → 低優先度のみ報告して完了
59
52
  ```
60
53
 
61
- - 優先度高・中が **0件になるまで**、同一セッション内で繰り返す(ユーザー再依頼不要)
62
- - 低優先度は自動実施せず、ユーザーへの報告のみ
63
- - 繰り返しのたびに「N回目の分析」「残り候補: X件」など進捗を簡潔に示す
64
-
65
- ---
54
+ - 高・中が0件になるまで、ユーザーの再依頼なしに繰り返す
55
+ - 低優先度は自動実施せず報告のみ
56
+ - 毎回「N回目の分析」「残り候補: X件」と進捗を示す
66
57
 
67
58
  ## 部分的に lint が当たる項目(目視で補う)
68
59
 
69
- lint が完全に検出できる項目は `pnpm josh refactor:scan` が件数と file:line で報告する(上記「候補の集計」)。ここに挙げるのは、**規則が一部の面しか当たらず、残る面を人が判断する項目**だけである。コーディング規約・命名規則は `CLAUDE.md` を参照(規則の単一ソース。`AGENTS.md` / `GEMINI.md` はそこへの導線でしかない)。
60
+ lint が一部の面しか見ない項目だけを挙げる。コーディング規約・命名規則は `CLAUDE.md` を参照。
70
61
 
71
62
  ### 高優先度
72
63
 
73
- - **責務の分離**: 再利用可能・独立した責任を持つ機能を別ファイルに分離する。`max-lines` は大きさだけを見るので、行数が収まっていても複数責任が混在していないかは目視で判断する。
74
- - **リテラル型の保持**: データ配列はリテラル型を保つために `as const satisfies T` を使っているか確認する(型注釈のみでは `string` に widen される)。`prefer-as-const` は別の場面の規則で、この判断は肩代わりしない。
64
+ - **責務の分離**: 行数が収まっていても複数責任が混在していれば、再利用可能・独立した機能を別ファイルに分ける(`max-lines` は大きさだけを見る)。
65
+ - **リテラル型の保持**: データ配列は `as const satisfies T` でリテラル型を保つ(型注釈のみでは `string` に widen される。`prefer-as-const` は肩代わりしない)。
75
66
 
76
67
  ### 中優先度
77
68
 
78
- - **変数名の意味**: `@typescript-eslint/naming-convention` は書式(snake_case など)だけを見る。意味が不明確な名前・実態と合わない名前は目視で見直す。
79
- - **類似コードの共通化**: `sonarjs/no-identical-functions` は完全一致だけを検出する。似ているが同一でないコードの共通化は目視で判断する。
69
+ - **変数名の意味**: `@typescript-eslint/naming-convention` は書式だけを見る。意味が不明確・実態と合わない名前は見直す。
70
+ - **類似コードの共通化**: `sonarjs/no-identical-functions` は完全一致だけを検出する。似ているが同一でないコードは目視で共通化を判断する。
80
71
 
81
72
  ### 低優先度
82
73
 
83
- - **不要コメントの整理**: 冗長・陳腐化したコメントを削除する。未使用の変数・関数は `@typescript-eslint/no-unused-vars` が検出し、`refactor:scan` が低優先度として報告する。
74
+ - **不要コメントの整理**: 冗長・陳腐化したコメントを削除する。
84
75
 
85
76
  ---
86
77
 
87
78
  ## 基本方針
88
79
 
89
- - **構造変更の前にテストを書く**: リファクタリング実施前に、対象のふるまいを検証する unit/E2E テストを先に実装し、グリーンを確認する。デグレを防ぐための安全網として機能する
90
- - **可読性・保守性・パフォーマンス・AI コストは同列で、どれも悪化させない**(`prompts/collaboration-workflow/principles.md` → "quality-priority")
80
+ - 可読性・保守性・パフォーマンス・AI コストは同列で、どれも悪化させない(`prompts/collaboration-workflow/principles.md` → "quality-priority")
91
81
  - コードクローンの排除・メソッド抽出・共通コンポーネント化は必ず分析・提案に含める
92
- - **提案しないパターン**: `async () => await fn()` → `() => fn()` への簡素化は行わない
93
- - 提案が特にない場合は、無理に提案しない
82
+ - `async () => await fn()` → `() => fn()` の簡素化は提案しない
83
+ - 提案が無ければ無理に提案しない
94
84
 
95
85
  ---
96
86
 
97
87
  ## 提案の形式
98
88
 
99
- 各提案: **優先度** / **問題点** / **改善案と効果** / **サンプルコード**(プロジェクト規約準拠、lint エラーなし)/ **影響ファイル**
89
+ 各提案: 優先度 / 問題点 / 改善案と効果 / サンプルコード(プロジェクト規約準拠、lint エラーなし)/ 影響ファイル
100
90
 
101
91
  ## 実装後の品質保証(絶対遵守)
102
92
 
103
- 実装後は `read_lints` → `pnpm run lint` の順で全関与ファイルを確認し、エラーが0件になるまで修正する。エラーが残った状態での完了報告は禁止。
93
+ 実装後は `read_lints` → `pnpm run lint` の順で全関与ファイルを確認し、エラー0件になるまで修正する。エラーが残ったまま完了報告しない。