diff --git a/CLAUDE.md b/CLAUDE.md index fe25798..171e5db 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -33,6 +33,7 @@ - [ADR-029: Post-Merge Feedback の自動起動 — pending file + 現セッション起動](docs/adr/adr-029-post-merge-feedback-auto-trigger.md) *(試験運用)* - [ADR-030: 決定論的 Post-Merge Feedback — takt 経由の同期実行 + 失敗マーカーによる recovery](docs/adr/adr-030-deterministic-post-merge-feedback.md) *(試験運用 / Supersedes ADR-014 full, ADR-029 partial)* - [ADR-031: 週次プロジェクト全体レビューパイプライン — whole-tree review の自己改善ループ](docs/adr/adr-031-weekly-review-pipeline.md) *(試験運用)* +- [ADR-033: todo.md 採番管理の簡素化 — 絶対番号は table のみに保持](docs/adr/adr-033-todo-numbering-simplification.md) *(試験運用)* ## Build diff --git a/docs/adr/adr-033-todo-numbering-simplification.md b/docs/adr/adr-033-todo-numbering-simplification.md new file mode 100644 index 0000000..bd230da --- /dev/null +++ b/docs/adr/adr-033-todo-numbering-simplification.md @@ -0,0 +1,207 @@ +# ADR-033: todo.md 採番管理の簡素化 — 絶対番号は table のみに保持 + +## ステータス + +試験運用 (2026-04-29) + +## コンテキスト + +### 問題: cross-reference の追従コストが線形増加 + +`docs/todo.md` の「推奨実行順序サマリー」table は、開発タスクの優先度を絶対番号 (`順位 N`) で管理している。新規タスク追加・既存タスク完了による削除のたびに番号を振り直す (renumber) 必要があるが、本文中の cross-reference (`順位 X (...) は ...`、`(順位 N と補完)` 等) も追従更新する必要がある。 + +タスク数の増加に伴い、毎回の renumber 作業で発生する Edit 数が **線形に増加** している: + +| PR | 追加 task 数 | 本文 cross-ref 修正 | 累計 entry | +|---|---|---|---| +| PR #85 | 4 | 8 箇所 | 18 | +| PR #86 | 3 | 5 箇所 | 21 | +| PR #88 | 5 | 9 箇所 | 24 | +| PR #89 | 2 | 5 箇所 | 25 | +| PR #90 | 1 | 6 箇所 | 25 | +| Bundle 1 (PR #91) | 4 | 8 箇所 | 29 | + +PR #91 では 4 件の新規 entry 追加に対し本文 cross-ref を 8 箇所修正したが、過去 PR では追従漏れによる stale reference (例: `順位 25/26` が `25/25` に更新されないまま merge) が発生し、CodeRabbit Minor 指摘で気付いた経緯がある (PR #91 修正 commit `a15b263` 参照)。 + +### 構造的負債としての顕在化 + +タスク数 29 に達した現時点で、以下が明確になった: + +- **renumber 作業のコストは O(N)**: 新規 entry 1 件追加でも本文中の `順位 N` 言及がほぼ全て影響を受ける可能性がある +- **追従漏れの検出が事後**: pre-push lint や Stop hook では検出できず、CodeRabbit / takt review で初めて発見されることが多い +- **AI レビューでも見落とし得る**: 順位の数字違いは意味的には軽微なため、CodeRabbit が指摘しない PR もある (リスク残存) +- **採番のみが情報源**: 本文の `順位 N (...)` 表記の `(...)` 部分にタスクの本質情報があるが、`順位 N` を読まないと辿り着けない (= 表との往復が発生) + +### 設計上の知見: 絶対番号と相対番号の責務分離 + +renumber 痛点の根本原因は、**「絶対番号 (table のソート順)」と「相対参照 (本文での "あの task")」を同じ表記に詰めている** ことにある。両者は本来別の責務: + +| 責務 | 適切な表現 | renumber 影響 | +|---|---|---| +| **table のソート順** (現時点の優先度) | `順位 N` 列 | 全行が再採番される (本質的) | +| **本文中の参照** (相対関係 / 補完性 / 依存) | タスク名 (`Markdown linter hook 統合`、`ADR-032 PR-β` 等) | renumber に依存しない | + +table と本文を **同じ識別子で結合** していることが線形コストの源泉。両者を切り離せば、renumber は table 内部に閉じる。 + +## 検討した選択肢 + +### 選択肢 A: 自動化 (renumber script を作る) + +`scripts/renumber-todo.ts` 等で table と本文を解析し、entry 追加時に番号を自動振り直すスクリプトを作る案。 + +- **却下**: スクリプト保守コストが新たに発生する、新規 entry 追加時に script 実行を忘れるリスク、新規 entry の本文記法を script が理解する必要がある (パース難易度大)。問題を別の問題に置き換えているだけで、根本治療ではない。 + +### 選択肢 B: 絶対番号を table のみに保持し、本文はタスク名で参照する + +`順位 N` 表記を本文から完全に除去し、参照は task の固有名 (heading text や略称) で行う。表の `順位` 列と `依存` 列のみが絶対番号を保持する。 + +- **採用**。renumber 作業が table 内部に閉じ、本文の参照は drift しない。新規 entry 追加時の Edit 数が **table 1 行追加のみ** になる。 + +### 選択肢 C: 現状維持 + +問題を放置し、renumber 漏れは CodeRabbit に検出してもらう案。 + +- **却下**: PR #91 で実証されたとおり、CodeRabbit Minor 指摘 → fix commit → 再 review という convergence loop の一因になっている。コストは線形に増えており、放置で済む段階を過ぎた。 + +## 決定 + +**選択肢 B を採用する。** + +### ガイドライン + +#### 1. 絶対番号は table のみに保持 + +- 推奨実行順序サマリー table の `順位` 列が **唯一の絶対番号の source of truth** +- 表の `依存` 列は絶対番号を許可 (例: `6, 8, 10`)。表内なので renumber と同期可能 +- それ以外の本文中で `順位 N` 表記を **使用禁止** + +#### 2. 本文での参照はタスク名で行う + +- entry の heading text (例: `### Markdown 非 ASCII GFM アンカー検出 lint rule (PR #89 T1-1)`) を参照アンカーとして使う +- 略称が定着しているものはそれを使う (例: `ADR-032 PR-β`、`Markdown linter hook 統合`) +- inline で参照する場合は **「タスク名」+ 文脈** の形 (例: `Polling anti-pattern 検出 と補完`) + +#### 3. 「実行優先度」行から `(順位 X/Y)` 部分を除去 + +- 既存: `> **実行優先度**: 🚀 **Tier 1 (順位 N/Y)** — ...` +- 新形式: `> **実行優先度**: 🚀 **Tier 1** — ...` +- Tier だけ残せば、相対的な優先度は table を見れば分かる +- 「Y (全 task 数)」も table のサイズと一致するので冗長 + +#### 4. 戦略 section の表記 + +- 既存: `Tier 1 (1〜7) を ...`、`順位 12/13 (rate-limit 系の 2 タスク) は ...` +- 新形式: + - `Tier 1 を 2〜3 セッションで片付け`、`Tier 2 で ADR-032 の前提を埋めつつ rate-limit 改善` (Tier 単位で語る) + - `rate-limit 系の 2 タスク (cli-pr-monitor ポーリング延長 と post-pr-review rate-limit 自動検出) は Tier 2 内で最優先候補` (タスク名で参照) + +### 移行戦略 + +1. 本 ADR と同 PR で `docs/todo.md` / `docs/todo2.md` / `docs/todo3.md` の本文 cross-ref を一括変換 +2. table の `順位` 列と `依存` 列はそのまま維持 +3. 新規 entry の template も同 PR で文書化 (本 ADR 内 or 別 section) +4. 派生プロジェクト (techbook-ledger / auto-review-fix-vc) への展開は **後日独立 PR で対応** (本 PR スコープ外) + +### 検証ルール + +migration 完了の判定: + +```sh +# 推奨実行順序サマリー table の外側で `順位 X` (数値・英字 placeholder 含む) が使われていないこと +grep -nE "順位 [0-9A-Za-z_-]+" docs/todo.md docs/todo2.md docs/todo3.md \ + | grep -vE "推奨実行順序サマリー|^[^:]+:[0-9]+:\| [0-9]+ \|" +# 期待: 0 行 (table 列以外で `順位 X` が使われていない) +# 注: 数値だけでなく英字 placeholder (例: `順位 X`、`順位 N`) も検出対象。 +# ADR の本文中で「絶対番号を示唆する placeholder を本文に書かない」方針を機械検証する。 +``` + +## アンチパターン + +### 「table 内まで採番除去」してはならない + +table の `順位` 列は絶対番号の source of truth であり、ここを除去すると優先度の合意自体が消失する。**table 内の絶対番号は残す**。 + +### 「依存」列をタスク名に変えてはならない + +table の `依存` 列を `順位 6` → `Phase pre` のようにタスク名にすると、cell が長くなり横スクロールが発生する。table 内なので renumber 同期は容易、絶対番号のままで OK。 + +### 自動化 script を後付けで作ってはならない + +選択肢 A で却下したように、script 保守コストが新たな負債になる。table 1 行追加のみで済む規律で十分。 + +### 本文中の番号参照を「許容」してはならない (例外なし) + +「ここだけ便利だから順位 N で参照したい」という例外を許すと、徐々に元の状態に回帰する。**移行後は本文中の `順位 N` 使用を 0 に保つ**。 + +## 影響 + +### Positive + +- **renumber 作業が O(1) 化**: 新規 entry 追加時の Edit が table 1 行のみで済む +- **追従漏れリスクの消滅**: 本文に `順位 N` がないため drift が発生しない +- **CodeRabbit Minor 指摘の削減**: stale reference 起因の指摘が出なくなる (PR #91 で観測された Minor finding pattern が消える) +- **convergence loop の縮小**: docs PR で「renumber 漏れ → 修正 commit → 再 review」のループが構造的に防止される + +### Negative + +- **既存 entry の参照表記の一斉変更**: 本 PR で 30+ 箇所の本文を書き換える必要がある (ただし mechanical な変換) +- **新規 entry 記法のルール周知**: AI / 人間が新規 entry を追加する際に、本文に `順位 N` を書かないルールを守る必要がある (template で誘導) +- **派生プロジェクトとの分岐**: 本リポジトリで先行採用した場合、派生プロジェクトの todo.md は旧形式のまま残るため、別 PR で同期が必要 + +### 将来の展望 + +- **派生プロジェクトへの展開**: 本 ADR の有効性を 1〜2 PR で確認後、派生プロジェクトにバックポート +- **template の自動 lint**: 新規 entry が本文に `順位 N` を含むケースを pre-push hook で検出する custom_lint_rule を追加検討 (ADR-007 拡張) +- **entry 追加自動化**: skill / takt から todo entry を直接追加する経路ができた場合、本ガイドラインを template 反映する + +## 新規エントリ template + +新規タスクを `docs/todo3.md` (または todo2.md / todo.md の既存セクション内) に追加する際は、以下の形式で記述する: + +```markdown +### (出典: PR # T-) + +> **動機**: <既存の問題、or 機会>。 +> +> **本タスクの位置づけ**: <他 task / ADR との関係。`順位 N` 表記は使わず、タスク名で参照>。 +> +> **参照**: `.claude/feedback-reports/.md` Tier # +> +> **実行優先度**: <絵文字> **Tier ** — 、<相対関係をタスク名で書く> +> (`(順位 X/Y)` 表記は使わない) + +#### 設計決定 (案) + +- <配置先、検出ロジック、機構選定 等> + +#### 作業計画 + +- [ ] <具体的な手順、相対関係はタスク名で表現> +- [ ] 本 todo3.md エントリを削除 + +#### 完了基準 + +- <検証可能な完了条件> + +#### 詰まっている箇所 + +なし (or 詰まっている箇所の詳細) +``` + +### 推奨実行順序サマリー table への追加 + +新規 entry を追加したら、`docs/todo.md` の table に 1 行追加する: + +```markdown +| <順位 N> | | -)> | <ファイル名> | | <依存タスク名 or 順位 (table 内なら絶対番号 OK)> | +``` + +`順位 N` の決定基準は本ガイドラインの Tier 別優先度ロジックに従う。本文中の他 entry に対する変更は不要。 + +## References + +- [ADR-013: Merge Pipeline](adr-013-merge-pipeline.md) — 採番の自動化は post-merge 段階では介入しない +- [ADR-022: 自動化コンポーネントの責務分離原則](adr-022-automation-responsibility-separation.md) — table = 自動化機構の source of truth、本文 = 説明、責務が明確分離される +- [ADR-028: 外部可視成果物ゲート](adr-028-pnpm-create-pr-gate.md) — 本 ADR は内部運用ルールのみで対象外 +- `.claude/feedback-reports/86.md` Tier 3 #3 — 起案動機の起源 +- PR #91 a15b263 — stale reference 起因 CodeRabbit Minor 指摘の実例 diff --git a/docs/todo.md b/docs/todo.md index a5b7f20..ea5d84b 100644 --- a/docs/todo.md +++ b/docs/todo.md @@ -12,7 +12,7 @@ --- -## 推奨実行順序サマリー (2026-04-29 更新、Bundle 1 [PR #85 T1-2 + PR #89 T1-1] 完了後) +## 推奨実行順序サマリー (2026-04-29 更新、ADR-033 採番管理簡素化 land 後) 開発環境の作業効率への貢献度を基準にした推奨実行順序。詳細は各タスク冒頭の **「実行優先度」** 行を参照。 @@ -24,36 +24,40 @@ | 4 | 🚀 Tier 1 | **Stop hook の `pnpm lint:md` 統合 (PR #88 T1-1)** | todo3.md | XS | なし (PR #88 直接対策、旧順位 1 完了済の gap closure) | | 5 | 🚀 Tier 1 | **AI 生成一時スクリプト pattern の pre-push 検出 (PR #88 T1-2)** | todo3.md | Small | 順位 1 と関連 (要擦り合わせ) | | 6 | 🚀 Tier 1 | ADR-032 PR-pre: GitHub Branch Protection 整備 | todo2.md | 設定のみ | なし (依存タスクは完了済) | -| 7 | 🔧 Tier 2 | 週次レビュー (ADR-031) Phase B 実装 | todo.md | 中-高 | なし (順位 16 の compensating check 前提) | -| 8 | 🔧 Tier 2 | reviewer facet 改善 (review-simplicity / review-security の DRY/YAGNI/security 軸明文化) | todo2.md | S | なし | -| 9 | 🔧 Tier 2 | ADR-032 PR-broken-link: broken-link-check + 内部アンカー検査 統合 | todo2.md | Small-中 | なし (clean baseline 確立済) | -| 10 | 🔧 Tier 2 | `cli-pr-monitor` プロセス正常終了の integration test (PR #85 T2-2) | todo2.md | S | なし | -| 11 | 🔧 Tier 2 | **`cli-pr-monitor` ポーリング延長 + 重複起動ロック (PR #88 T2-4)** ★ rate-limit critical | todo3.md | Medium | なし (順位 3 と補完) | -| 12 | 🔧 Tier 2 | **post-pr-review に rate-limit 自動検出 + 再トリガー (PR #89 T2-1)** ★ rate-limit critical | todo3.md | Medium | なし (順位 11 と補完) | -| 13 | 🔧 Tier 2 | **`vitest` を devDependencies に固定 (PR #88 T2-3)** | todo3.md | Small | なし | -| 14 | 🔧 Tier 2 | **`pnpm create-pr` 必須引数ヘルプ改善 (PR #88 T2-5)** | todo3.md | Small | なし | -| 15 | 🔧 Tier 2 | **`.failed` marker への recovery 手順自己文書化 (PR #90 T2-2)** | todo3.md | S | なし | -| 16 | 💎 Tier 3 | ADR-032 PR-β: 実装 (enabled=false default) | todo2.md | 中-高 | 6, 7, 9 | -| 17 | 💎 Tier 3 | ADR-032 PR-γ: enablement (1 行 flip) | todo2.md | XS | 順位 7 dogfood + 順位 16 | -| 18 | 💎 Tier 3 | ADR-032 PR-δ: dogfood + メトリクス検証 | todo2.md | (運用) | 順位 17 | -| 19 | 💎 Tier 3 | 日付ベース見出しアンカー更新ルールのグローバル明文化 (PR #85 T3-1) | todo2.md | XS | なし | -| 20 | 💎 Tier 3 | jj conflict リカバリ手順のグローバル明文化 (PR #85 T3-2) | todo2.md | XS | なし | -| 21 | 💎 Tier 3 | `__` prefix scratch file 規約のグローバル明文化 (PR #85 T3-3) | todo2.md | XS | なし | -| 22 | 💎 Tier 3 | **post-pr-monitor polling 禁止のグローバル明文化 (PR #86 T3-2)** | todo2.md | XS | なし | -| 23 | 💎 Tier 3 | **todo.md 採番管理の簡素化 ADR 起案 (PR #86 T3-3)** | todo2.md | S | なし | -| 24 | 🧹 Tier 4 | ADR-030 Phase E/F: 旧機構廃止 + dogfood | todo.md | 中 | なし (cleanup) | -| 25 | ⏳ Tier 5 | (追って) ADR-030 の takt-test-vc 反映 | todo.md | 中 | 順位 24 Phase F | - -**戦略**: Tier 1 (1〜6) を 2〜3 セッションで片付け → Tier 2 (7〜15) で ADR-032 の前提を埋めつつ rate-limit 改善 (順位 11/12) → Tier 3 (16〜23) で ADR-032 を land + ドキュメント整備。Tier 4-5 (24〜25) は cleanup / 外部展開で daily efficiency への直接効果は小さい。 - -**Bundle 1 完了 (2026-04-29)**: 旧順位 3 (PowerShell swallowed error) + 旧順位 7 (Markdown 非 ASCII anchor) を `custom-lint-rules.toml` に追加して 1 PR で統合実装。詳細は git log 参照。**順位 19 (日付ベース見出しアンカー更新ルール) は決定論的防止 (旧順位 7 = `no-mutable-anchor` rule) との二重防衛として継続有効**。 - -**順位 8 (reviewer facet 改善) は全 PR の review 精度を即時向上させ、Tier 2 内で順位 7/9/10 と並列実施可能**。 -**順位 11/12 (rate-limit 系の 2 タスク) は rate-limit 直撃のため Tier 2 内で最優先候補**。順位 11 = ポーリング頻度全体の削減、順位 12 = review 単位での自動再トリガー、順位 3 (Polling anti-pattern 検出) を含む 3 層で rate-limit を抑制する設計。 -**順位 4 (Stop hook の lint:md 統合) は旧順位 1 (Markdown linter hook 統合、PR #88 で merged) の gap closure**。**順位 5 (AI 生成一時スクリプト pattern 検出) は現順位 1 (push 前 untracked `__*` hook、PR #85 T1-4) と関連** (実装前に擦り合わせ要)。 -**順位 15 (`.failed` marker 自己文書化) は ADR-030 soft-fail 機構の運用負荷削減** (PR #89 セッションで recovery が機能した実証から派生、Effort S)。 -**順位 19-22 (T3 グローバルルール 4 件) は `~/.claude/` 配下への XS 追記なので並列実施推奨**。 -**順位 23 (採番管理簡素化 ADR) は本 table の cross-reference 維持コストを構造的に解消するメタタスク** (PR #88/#89/#90/Bundle 1 で連続して 30+ 箇所の renumber が発生し負債が顕在化)。 +| 7 | 🚀 Tier 1 | **PowerShell custom-lint-rule の `(?i)` フラグ自動検証 (PR #91 T1-1)** | todo3.md | S | なし (PR #91 直接対策、code-review.md 追記も同 PR で land) | +| 8 | 🔧 Tier 2 | 週次レビュー (ADR-031) Phase B 実装 | todo.md | 中-高 | なし (順位 20 の compensating check 前提) | +| 9 | 🔧 Tier 2 | reviewer facet 改善 (review-simplicity / review-security の DRY/YAGNI/security 軸明文化) | todo2.md | S | なし | +| 10 | 🔧 Tier 2 | ADR-032 PR-broken-link: broken-link-check + 内部アンカー検査 統合 | todo2.md | Small-中 | なし (clean baseline 確立済) | +| 11 | 🔧 Tier 2 | `cli-pr-monitor` プロセス正常終了の integration test (PR #85 T2-2) | todo2.md | S | なし | +| 12 | 🔧 Tier 2 | **`cli-pr-monitor` ポーリング延長 + 重複起動ロック (PR #88 T2-4)** ★ rate-limit critical | todo3.md | Medium | なし (順位 3 と補完) | +| 13 | 🔧 Tier 2 | **post-pr-review に rate-limit 自動検出 + 再トリガー (PR #89 T2-1)** ★ rate-limit critical | todo3.md | Medium | なし (順位 12 と補完) | +| 14 | 🔧 Tier 2 | **post-pr-review fix loop の `.claude/` filter + ADR-030 制約明記 (PR #91 T2-1 + T3-2 Bundle)** ★ convergence | todo3.md | S + XS | なし (PR #91 直接対策、analyze facet + ADR 追記の同 PR Bundle) | +| 15 | 🔧 Tier 2 | **cli-pr-monitor 通知 Recovery 経路 (SessionStart hook 拡張)** ★ silent loss prevention | todo3.md | S/M | なし (ADR-030 L2 recovery パターンを cli-pr-monitor に適用) | +| 16 | 🔧 Tier 2 | **`vitest` を devDependencies に固定 (PR #88 T2-3)** | todo3.md | Small | なし | +| 17 | 🔧 Tier 2 | **`pnpm create-pr` 必須引数ヘルプ改善 (PR #88 T2-5)** | todo3.md | Small | なし | +| 18 | 🔧 Tier 2 | **`.failed` marker への recovery 手順自己文書化 (PR #90 T2-2)** | todo3.md | S | なし | +| 19 | 🔧 Tier 2 | **takt ハーネスの `REJECT-ESCALATE` terminal verdict 実装 (PR #91 T2-2)** | todo3.md | M | 順位 14 (path-based 解決) land 後推奨 | +| 20 | 💎 Tier 3 | ADR-032 PR-β: 実装 (enabled=false default) | todo2.md | 中-高 | 6, 8, 10 | +| 21 | 💎 Tier 3 | ADR-032 PR-γ: enablement (1 行 flip) | todo2.md | XS | 順位 8 dogfood + 順位 20 | +| 22 | 💎 Tier 3 | ADR-032 PR-δ: dogfood + メトリクス検証 | todo2.md | (運用) | 順位 21 | +| 23 | 💎 Tier 3 | 日付ベース見出しアンカー更新ルールのグローバル明文化 (PR #85 T3-1) | todo2.md | XS | なし | +| 24 | 💎 Tier 3 | jj conflict リカバリ手順のグローバル明文化 (PR #85 T3-2) | todo2.md | XS | なし | +| 25 | 💎 Tier 3 | `__` prefix scratch file 規約のグローバル明文化 (PR #85 T3-3) | todo2.md | XS | なし | +| 26 | 💎 Tier 3 | **post-pr-monitor polling 禁止のグローバル明文化 (PR #86 T3-2)** | todo2.md | XS | なし | +| 27 | 🧹 Tier 4 | ADR-030 Phase E/F: 旧機構廃止 + dogfood | todo.md | 中 | なし (cleanup) | +| 28 | ⏳ Tier 5 | (追って) ADR-030 の takt-test-vc 反映 | todo.md | 中 | 順位 27 Phase F | + +**戦略**: Tier 1 を 2〜3 セッションで片付け → Tier 2 で ADR-032 の前提 + rate-limit + convergence cost 削減を進める → Tier 3 で ADR-032 を land + ドキュメント整備。Tier 4-5 は cleanup / 外部展開で daily efficiency への直接効果は小さい。 + +**Bundle 1 完了 + post-merge-feedback 反映 (2026-04-29)**: PR #91 (Bundle 1: PowerShell + Markdown anchor lint rules) merge 後の post-merge-feedback で **4 件の新規 task を追加** (PowerShell `(?i)` 自動検証 / `.claude/` filter + ADR-030 制約 / cli-pr-monitor 通知 Recovery 経路 / takt REJECT-ESCALATE)。**前 2 件は本 PR で実証された「fix iteration の根因」に対する決定論的防止策で最優先候補**。**日付ベース見出しアンカーのグローバル明文化 task は決定論的防止 (no-mutable-anchor rule) との二重防衛として継続有効**。 + +**reviewer facet 改善 task は全 PR の review 精度を即時向上させ、Tier 2 内で 週次レビュー Phase B / ADR-032 PR-broken-link / cli-pr-monitor exit test と並列実施可能**。 +**rate-limit 系の 2 タスク (cli-pr-monitor ポーリング延長 + 重複起動ロック / post-pr-review rate-limit 自動検出 + 再トリガー) は rate-limit 直撃のため Tier 2 内で最優先候補**。前者 = ポーリング頻度全体の削減、後者 = review 単位での自動再トリガー、Polling anti-pattern 検出 (Tier 1) を含む 3 層で rate-limit を抑制する設計。 +**post-pr-review fix loop の `.claude/` filter + Recovery 経路 (SessionStart hook 拡張) は本 PR #91 の直接観測知見**。前者 = path-based filter で 8 step 空費の pathological loop を防止 / 後者 = SessionStart hook で再起動跨ぎの通知ロスト防止。 +**Stop hook の `pnpm lint:md` 統合 task は Markdown linter hook 統合 (PR #88 で merged) の gap closure**。**AI 生成一時スクリプト pattern 検出は push 前 untracked `__*` hook (PR #85 T1-4) と関連** (実装前に擦り合わせ要)。 +**`.failed` marker 自己文書化 task は ADR-030 soft-fail 機構の運用負荷削減** (PR #89 セッションで recovery が機能した実証から派生、Effort S)。 +**takt REJECT-ESCALATE は post-pr-review fix loop の `.claude/` filter task の verdict-based 一般解**。path-based 解決の land 後に着手することで、補完関係になる。 +**T3 グローバルルール 4 件 (日付ベース見出しアンカー / jj conflict リカバリ / `__` prefix scratch / post-pr-monitor polling 禁止) は `~/.claude/` 配下への XS 追記なので並列実施推奨**。 --- @@ -65,7 +69,7 @@ > > **本タスクの位置づけ**: ADR-029 を partial supersede する新 ADR-030 を起案し、takt 経由の決定論的フィードバック機構へ移行する。本タスク完了で post-merge-feedback skill / pending file / Stop hook (hooks-stop-feedback-dispatch) はすべて廃止される。 > -> **実行優先度**: 🧹 **Tier 4 (順位 24/25)** — Phase A〜D は merged 済で workflow は機能。残る Phase E (旧機構廃止) / Phase F (dogfood) は cleanup 中心で daily efficiency への直接効果は小。Tier 1〜3 完了後の片付けタイミングで実施推奨。 +> **実行優先度**: 🧹 **Tier 4** — Phase A〜D は merged 済で workflow は機能。残る Phase E (旧機構廃止) / Phase F (dogfood) は cleanup 中心で daily efficiency への直接効果は小。Tier 1〜3 完了後の片付けタイミングで実施推奨。 #### 背景: ADR-029 の構造的欠陥 (PR #74 dogfood で実証) @@ -247,7 +251,7 @@ dogfood では PR #74 マージ後、pending file が `dispatched` で stuck し > **参照**: 上位タスク「マージ後フィードバック機構の決定論化」の Phase F 完了が前提。元の 1-F (ADR-014 本採用化 + takt-test-vc 反映) は ADR-014 が ADR-030 で Superseded されるため scope 変更。 > -> **実行優先度**: ⏳ **Tier 5 (順位 25/25)** — 派生プロジェクトへの展開で本リポジトリへの効果はゼロ。順位 24 (ADR-030 Phase F) 完了後の任意タスク。 +> **実行優先度**: ⏳ **Tier 5** — 派生プロジェクトへの展開で本リポジトリへの効果はゼロ。ADR-030 Phase F 完了後の任意タスク。 - **やろうとしたこと**: 本プロジェクトで ADR-030 機構が安定稼働 (Phase F dogfood 完了) した後、takt-test-vc へ機構ごとバックポート - **現在地**: 上位タスクの Phase F 完了待ち @@ -261,7 +265,7 @@ dogfood では PR #74 マージ後、pending file が `dispatched` で stuck し > > **計画ファイル参照**: `~/.claude/plans/1-docs-todo-md-askuserquestion-validated-orbit.md` (本タスク策定時の plan、新セッションでも同じ判断を再現可能) > -> **実行優先度**: 🔧 **Tier 2 (順位 7/25)** — ADR-032 (docs-only fast path) の compensating check 前提。順位 16 (ADR-032 PR-β) 着手前に Phase B dogfood 1 回成功が必要。architecture facet の rubric に docs 整合性観点 (ADR/symbol drift, terminology drift, docs-code 整合, docs 重複/不整合) を含めること。 +> **実行優先度**: 🔧 **Tier 2** — ADR-032 (docs-only fast path) の compensating check 前提。ADR-032 PR-β 着手前に Phase B dogfood 1 回成功が必要。architecture facet の rubric に docs 整合性観点 (ADR/symbol drift, terminology drift, docs-code 整合, docs 重複/不整合) を含めること。 #### 背景: 既存レビューの空白 diff --git a/docs/todo2.md b/docs/todo2.md index 3fabe54..47bd3e5 100644 --- a/docs/todo2.md +++ b/docs/todo2.md @@ -18,13 +18,13 @@ > > **計画ファイル参照**: `~/.claude/plans/1-docs-todo-md-askuserquestion-validated-orbit.md` (本タスク策定時の plan、新セッションでも同じ判断を再現可能) > -> **実行優先度**: タスク全体は **🚀 Tier 1 〜 💎 Tier 3 に分散** (Phase ごとに優先度が異なる、2026-04-28 採番更新)。 -> - Phase pre (branch protection): **Tier 1 (順位 8/26)** — 設定のみ、依存タスクは完了済 -> - Phase α: 既存 todo.md「週次レビュー (ADR-031)」エントリ参照 — **Tier 2 (順位 9/26)** -> - Phase broken-link: **Tier 2 (順位 11/26)** — Markdown linter (PR #88 で merged) の clean baseline 確立済のため即着手可 -> - Phase β (実装、enabled=false): **Tier 3 (順位 17/26)** — 全前提揃ってから -> - Phase γ (enablement): **Tier 3 (順位 18/26)** — 順位 9 dogfood 後の 1 行 flip -> - Phase δ (dogfood): **Tier 3 (順位 19/26)** — 実 docs PR で検証 +> **実行優先度**: タスク全体は **🚀 Tier 1 〜 💎 Tier 3 に分散** (Phase ごとに優先度が異なる)。 +> - Phase pre (branch protection): **Tier 1** — 設定のみ、依存タスクは完了済 +> - Phase α: 既存 todo.md「週次レビュー (ADR-031)」エントリ参照 — **Tier 2** +> - Phase broken-link: **Tier 2** — Markdown linter (PR #88 で merged) の clean baseline 確立済のため即着手可 +> - Phase β (実装、enabled=false): **Tier 3** — 全前提揃ってから +> - Phase γ (enablement): **Tier 3** — 週次レビュー Phase B dogfood 後の 1 行 flip +> - Phase δ (dogfood): **Tier 3** — 実 docs PR で検証 > > **最大 payoff**: Phase γ enable 後、docs PR 所要時間 ~15min → ~30sec (30 倍速)。daily efficiency への貢献は本リポジトリ随一だが、**前提依存が多いため近道はない**。 @@ -370,7 +370,7 @@ Phase 2 (任意、段階的緩和) > > **参照**: `.claude/feedback-reports/82.md` の Tier 3 #2-4 findings (3 件を統合) > -> **実行優先度**: 🔧 **Tier 2 (順位 10/26)** — 全 PR の review 精度を即時向上、false positive iteration の削減効果。Tier 2 内で順位 9 (週次レビュー Phase B) / 順位 11 (ADR-032 PR-broken-link) / 順位 12 (cli-pr-monitor termination test) と並列実施可能。Effort S × 3 = ~S。 +> **実行優先度**: 🔧 **Tier 2** — 全 PR の review 精度を即時向上、false positive iteration の削減効果。Tier 2 内で 週次レビュー Phase B / ADR-032 PR-broken-link / cli-pr-monitor termination test と並列実施可能。Effort S × 3 = ~S。 #### 背景 @@ -420,7 +420,7 @@ Phase 2 (任意、段階的緩和) > > **参照**: `.claude/feedback-reports/85.md` Tier 1 #4 > -> **実行優先度**: 🚀 **Tier 1 (順位 1/26)** — Small 工数、直近インシデントの直接対策。同種事故 (PR scope 外ファイル混入) の再発防止で、混入時の追加コスト (force-push + 再 review) を回避。 +> **実行優先度**: 🚀 **Tier 1** — Small 工数、直近インシデントの直接対策。同種事故 (PR scope 外ファイル混入) の再発防止で、混入時の追加コスト (force-push + 再 review) を回避。 #### 設計決定 (案) @@ -454,7 +454,7 @@ Phase 2 (任意、段階的緩和) > > **参照**: `.claude/feedback-reports/85.md` Tier 1 #3 > -> **実行優先度**: 🚀 **Tier 1 (順位 2/26)** — S 工数、daily efficiency への直接効果 (失敗 push 1 回あたり 2-3 分 + takt review token 消費を節約)。 +> **実行優先度**: 🚀 **Tier 1** — S 工数、daily efficiency への直接効果 (失敗 push 1 回あたり 2-3 分 + takt review token 消費を節約)。 #### 設計決定 (案) @@ -487,7 +487,7 @@ Phase 2 (任意、段階的緩和) > > **参照**: `.claude/feedback-reports/85.md` Tier 2 #2 > -> **実行優先度**: 🔧 **Tier 2 (順位 12/26)** — S 工数、回帰防止が主目的。発生頻度は低いが UX への直接影響あり (手動 kill 必要)。 +> **実行優先度**: 🔧 **Tier 2** — S 工数、回帰防止が主目的。発生頻度は低いが UX への直接影響あり (手動 kill 必要)。 #### 設計決定 (案) @@ -520,7 +520,7 @@ termination 残留の root cause が未調査 (タスク開始時に最初に調 > > **参照**: `.claude/feedback-reports/85.md` Tier 3 #1 > -> **実行優先度**: 💎 **Tier 3 (順位 20/26)** — XS 工数、グローバルなので全プロジェクト即時効果。順位 11 (ADR-032 PR-broken-link) の anchor link CI チェックと補完関係 (CI = 自動検出、本ルール = 編集時の予防)。 +> **実行優先度**: 💎 **Tier 3** — XS 工数、グローバルなので全プロジェクト即時効果。ADR-032 PR-broken-link の anchor link CI チェックと補完関係 (CI = 自動検出、本ルール = 編集時の予防)。 #### 設計決定 (案) @@ -552,7 +552,7 @@ termination 残留の root cause が未調査 (タスク開始時に最初に調 > > **参照**: `.claude/feedback-reports/85.md` Tier 3 #2 > -> **実行優先度**: 💎 **Tier 3 (順位 21/26)** — XS 工数、知見の恒久化のみ。発生頻度は低いが、発生時の試行錯誤コストを削減。 +> **実行優先度**: 💎 **Tier 3** — XS 工数、知見の恒久化のみ。発生頻度は低いが、発生時の試行錯誤コストを削減。 #### 設計決定 (案) @@ -587,7 +587,7 @@ termination 残留の root cause が未調査 (タスク開始時に最初に調 > > **参照**: `.claude/feedback-reports/85.md` Tier 3 #3 > -> **実行優先度**: 💎 **Tier 3 (順位 22/26)** — XS 工数、規約浸透のみ。Tier 1 #1 (`.gitignore` 追加、PR #85 で実装済) の補完。 +> **実行優先度**: 💎 **Tier 3** — XS 工数、規約浸透のみ。Tier 1 #1 (`.gitignore` 追加、PR #85 で実装済) の補完。 #### 設計決定 (案) @@ -623,7 +623,7 @@ termination 残留の root cause が未調査 (タスク開始時に最初に調 > > **参照**: `.claude/feedback-reports/86.md` Tier 1 #1 > -> **実行優先度**: 🚀 **Tier 1 (順位 4/26)** — XS 工数、daily efficiency への直接効果が極めて大 (1 セッションで rate limit 40% 浪費を防止)。順位 23 (post-pr-monitor polling 禁止 rule) と補完関係 (本タスクは決定論的防止、順位 23 はガイドライン)。 +> **実行優先度**: 🚀 **Tier 1** — XS 工数、daily efficiency への直接効果が極めて大 (1 セッションで rate limit 40% 浪費を防止)。post-pr-monitor polling 禁止のグローバル明文化 task と補完関係 (本タスクは決定論的防止、ガイドライン task はドキュメント補完)。 #### 設計決定 (案) @@ -661,7 +661,7 @@ termination 残留の root cause が未調査 (タスク開始時に最初に調 > > **参照**: `.claude/feedback-reports/86.md` Tier 3 #2 > -> **実行優先度**: 💎 **Tier 3 (順位 23/26)** — XS 工数、ルール明文化のみ。順位 4 (polling anti-pattern 検出) と補完関係 (本ルールはガイドライン、順位 4 は決定論的防止)。 +> **実行優先度**: 💎 **Tier 3** — XS 工数、ルール明文化のみ。Polling anti-pattern 検出ルール task と補完関係 (本ルールはガイドライン、検出ルール task は決定論的防止)。 #### 設計決定 (案) @@ -684,43 +684,3 @@ termination 残留の root cause が未調査 (タスク開始時に最初に調 #### 詰まっている箇所 なし - -### todo.md 採番管理の簡素化 ADR 起案 (PR #86 T3-3) - -> **動機**: PR #85 / PR #86 で行った推奨実行順序サマリー table の renumber 作業が、本文 `順位 N/N` 形式 cross-reference の追従更新まで含めると毎回 5+ 件の Edit を要する。タスク数増加に伴い漏れリスクが増大しており、20 件を超えた現時点で構造的負債が顕在化。 -> -> **本タスクの位置づけ**: ADR として「優先度採番はサマリー table のみに持ち、本文の `順位 N/N` cross-reference は廃止する」ガイドラインを文書化。本タスク完了で renumber 作業が table 更新のみになり、cross-ref 追従漏れリスクが消滅。 -> -> **参照**: `.claude/feedback-reports/86.md` Tier 3 #3 -> -> **実行優先度**: 💎 **Tier 3 (順位 24/26)** — S 工数、構造的負債解消。タスク数 26 に達した現時点でリターン大 (renumber 作業時の Edit 数が桁で減る)。 - -#### 設計決定 (案) - -- 配置先: `docs/adr/adr-033-todo-numbering-simplification.md` (新規 ADR) -- ガイドライン (案): - - 優先度の絶対番号 (`順位 N`) は **推奨実行順序サマリー table のみ** に保持 - - 本文では絶対番号を使わず、タスク名 (`Markdown linter`, `ADR-032 PR-β` 等) で参照 - - 「Tier N (順位 X/Y)」の `(順位 X/Y)` 部分も Tier だけ残して採番除去 - - 依存関係表記は table の「依存」列のみで管理、本文では具体的タスク名を引用 -- 移行作業: - - 既存 todo.md / todo2.md の本文 cross-ref を一括変換 (regex 置換 + AI 校正) - - 新規エントリの template 更新 (`順位 N/Y` を含めない雛形に) - -#### 作業計画 - -- [ ] 新規 ADR 起案 (動機 + ガイドライン + 移行戦略 + ADR-013, ADR-022 との整合性) -- [ ] 既存 todo.md / todo2.md の本文 cross-ref を一括変換 -- [ ] 新規エントリ template の文書化 (`docs/CLAUDE.md` または ADR 内に記載) -- [ ] 派生プロジェクトの todo.md 等にも展開検討 -- [ ] 本 todo2.md エントリを削除 - -#### 完了基準 - -- ADR が起案され承認される -- todo.md / todo2.md の本文から `順位 N/Y` 形式 cross-ref が消える (table のみに残る) -- 以後の PR で renumber 作業が table 更新のみで完結 - -#### 詰まっている箇所 - -なし diff --git a/docs/todo3.md b/docs/todo3.md index 1b5d5dd..371e12e 100644 --- a/docs/todo3.md +++ b/docs/todo3.md @@ -14,7 +14,7 @@ > **動機**: PR #88 で `pnpm lint:md` script を導入したが `[[stop_quality.steps]]` への登録が漏れていた。PostToolUse hook は Write/Edit ツール経由の編集にのみ発火するため、jj の auto-snapshot・他 hook 生成・bulk import 等で `.md` が変更された場合に markdownlint 違反が Stop まで未検出になる。`pnpm lint` (TS oxlint) は Stop gate 登録済みだが `pnpm lint:md` は本 PR で追加されたばかりにもかかわらず未登録のまま。 > -> **本タスクの位置づけ**: PR #88 で merged 済の Markdown linter hook 統合 (旧順位 1、現在 master) の補完作業。Stop gate は最後の安全網として PostToolUse 経由しない経路 (auto-snapshot など) もカバーする必要がある。 +> **本タスクの位置づけ**: PR #88 で merged 済の Markdown linter hook 統合 (現在 master) の補完作業。Stop gate は最後の安全網として PostToolUse 経由しない経路 (auto-snapshot など) もカバーする必要がある。 > > **参照**: `.claude/feedback-reports/88.md` の Tier 1 #1 finding > @@ -61,11 +61,11 @@ cmd = "pnpm lint:md" > **動機**: PR #85 で Claude が transcript 確認用に作成した `__parse_transcripts.ps1` が `.gitignore` 漏れにより jj auto-snapshot 経由で commit に意図せず混入。CodeRabbit が発見し除去作業が必要となった。同パターン (`__*.ps1` / `_tmp_*.ps1` / `__*.py` / `_tmp_*.py` 等の AI 生成一時スクリプト) を pre-push で機械的に検出し再発を防止する。post-merge-feedback (PR #88) が同事象を transcript から再検出。 > -> **本タスクの位置づけ**: **既存の 順位 1 (push 前 untracked `__*` ファイル警告 hook、PR #85 T1-4) と同一インシデントへの異なるアプローチによる補完**。順位 1 = working-tree の untracked file 検出 (hook 機構) / 本タスク = pre-push 時の lint ベース検出 (AI 命名 pattern 全体)。両機構を併用するか一方に統合するかは実装時に判断。 +> **本タスクの位置づけ**: **既存の push 前 untracked `__*` ファイル警告 hook task (PR #85 T1-4) と同一インシデントへの異なるアプローチによる補完**。前者 = working-tree の untracked file 検出 (hook 機構) / 本タスク = pre-push 時の lint ベース検出 (AI 命名 pattern 全体)。両機構を併用するか一方に統合するかは実装時に判断。 > > **参照**: `.claude/feedback-reports/88.md` の Tier 1 #2 finding > -> **実行優先度**: 🚀 **Tier 1** — 工数 Small。daily efficiency への影響中 (再発リスクは低いが ADR-007 拡張で確実な再発防止)。**実装前に既存の順位 1 (PR #85 T1-4) と擦り合わせて重複か補完かを判定すること**。 +> **実行優先度**: 🚀 **Tier 1** — 工数 Small。daily efficiency への影響中 (再発リスクは低いが ADR-007 拡張で確実な再発防止)。**実装前に既存の push 前 untracked `__*` ファイル警告 hook task (PR #85 T1-4) と擦り合わせて重複か補完かを判定すること**。 #### 背景 @@ -78,17 +78,17 @@ cmd = "pnpm lint:md" - 候補機構 1: ADR-007 の custom_lint_rule (`.claude/custom-lint-rules.toml`) に AI 生成一時スクリプト pattern を追加 - 候補機構 2: pre-push hook で `jj diff --name-only @` で staged file のうち `__*` / `_tmp_*` パターンに合致するものを検出 -- 候補機構 3: 既存の順位 1 (PR #85 T1-4) の hook を拡張し pattern を増やす +- 候補機構 3: 既存の push 前 untracked `__*` ファイル警告 hook (PR #85 T1-4) を拡張し pattern を増やす - 検出パターン (初稿): `__*.ps1`, `__*.py`, `_tmp_*.ps1`, `_tmp_*.py`, `__*.sh`, `__*.js`, `__*.ts` - 警告メッセージ: 「AI 生成一時スクリプト pattern を検出: ``. `.gitignore` 漏れの可能性。意図的な commit なら override してください。」 #### 作業計画 -- [ ] 既存の順位 1 (PR #85 T1-4「push 前 untracked `__*` ファイル警告 hook」) の実装状況を確認 -- [ ] 重複なら本タスクは順位 1 内へ統合 (pattern を拡張するだけ)、補完なら別実装 +- [ ] 既存の push 前 untracked `__*` ファイル警告 hook (PR #85 T1-4) の実装状況を確認 +- [ ] 重複なら本タスクは前者の hook 内へ統合 (pattern を拡張するだけ)、補完なら別実装 - [ ] 機構決定後に `.claude/custom-lint-rules.toml` または既存 hook を拡張 - [ ] dogfood: 試しに `__test.py` を作って commit 試行 → 警告が出ることを確認 -- [ ] 本 todo3.md エントリを削除 (順位 1 に統合した場合は順位 1 の description も更新) +- [ ] 本 todo3.md エントリを削除 (push 前 untracked hook に統合した場合は description も更新) #### 完了基準 @@ -148,7 +148,7 @@ cmd = "pnpm lint:md" > **動機**: PR #88 作成後の cli-pr-monitor 監視中に、Claude Code Max (5x) のレートリミットを 1 時間で 40% 消費する事象を観測。監視セッション重複起動による累積消費が推定原因。現在の `poll_interval_secs = 120` (2分) はセッション単独では問題ないが、複数セッションで監視が重複起動すると 1 分以下の頻度で polling が走り得る。 > -> **本タスクの位置づけ**: **既存の 順位 4 (Polling anti-pattern 検出ルール、PR #86 T1-1) と補完**。順位 4 = Claude 側の polling 禁止 (preventive)、本タスク = cli-pr-monitor (tool 側) の polling 動作改善 (corrective)。両層で rate-limit を削減する。 +> **本タスクの位置づけ**: **既存の Polling anti-pattern 検出ルール task (PR #86 T1-1) と補完**。前者 = Claude 側の polling 禁止 (preventive)、本タスク = cli-pr-monitor (tool 側) の polling 動作改善 (corrective)。両層で rate-limit を削減する。 > > **参照**: `.claude/feedback-reports/88.md` の Tier 2 #4 finding > @@ -253,7 +253,7 @@ Hint: > > **参照**: `.claude/feedback-reports/89.md` の Tier 2 #1 finding > -> **実行優先度**: 🔧 **Tier 2** — 工数 Medium。daily efficiency への影響中-大 (rate-limit 発生率 × 手動判断時間)。順位 13 (cli-pr-monitor polling 延長 + 重複起動ロック) と補完関係 (本タスクは review 単位の対応、順位 13 はポーリング頻度全体の削減)。順位 4 (Polling anti-pattern 検出) も類似の rate-limit 削減ライン。 +> **実行優先度**: 🔧 **Tier 2** — 工数 Medium。daily efficiency への影響中-大 (rate-limit 発生率 × 手動判断時間)。cli-pr-monitor ポーリング延長 + 重複起動ロック task と補完関係 (本タスクは review 単位の対応、ポーリング延長 task はポーリング頻度全体の削減)。Polling anti-pattern 検出ルール task も類似の rate-limit 削減ライン。 #### 背景 @@ -300,7 +300,7 @@ Hint: > > **参照**: `.claude/feedback-reports/90.md` の Tier 2 #2 finding > -> **実行優先度**: 🔧 **Tier 2** — 工数 S。daily efficiency への影響中 (recovery 発生頻度は低いが、発生時の摩擦を低減)。順位 13/14 (rate-limit 系) ほど critical ではないが、ADR-030 の long-term 運用品質に寄与。 +> **実行優先度**: 🔧 **Tier 2** — 工数 S。daily efficiency への影響中 (recovery 発生頻度は低いが、発生時の摩擦を低減)。rate-limit 系 task (cli-pr-monitor ポーリング延長 + post-pr-review rate-limit 自動検出) ほど critical ではないが、ADR-030 の long-term 運用品質に寄与。 #### 背景 @@ -367,3 +367,184 @@ prompt and prompt Claude to re-run the workflow. #### 詰まっている箇所 なし (Effort S、cli-merge-pipeline の marker 書込み箇所のテンプレート化のみ) + +--- + +### PowerShell custom-lint-rule の `(?i)` フラグ自動検証 (PR #91 T1-1) + +> **動機**: PR #91 で `no-empty-powershell-catch` / `no-silent-error-action` の regex に `(?i)` が欠落し、`Catch {}` / `-erroraction silentlycontinue` 等の大文字バリアントを見逃して CodeRabbit Major 指摘を受けた。PowerShell は言語仕様として keyword + parameter 名 case-insensitive だが、AI 生成 regex はデフォルトで case-sensitive になる構造的な落とし穴がある。本 PR で fix 済 (commit a15b263) だが、次回ルール追加時に同種の漏れが起きないよう自動検証を追加する。 +> +> **本タスクの位置づけ**: hooks-post-tool-linter の起動時 (or 専用 test) で「`extensions = ["ps1"]` を含む全ルールの `pattern` に `(?i)` が含まれる」アサーションを追加。同 PR で `~/.claude/rules/common/code-review.md` に「case-insensitive 言語向け lint rule は `(?i)` 必須」のチェックリスト項目を追記 (report Tier 3 #1 を統合)。 +> +> **参照**: `.claude/feedback-reports/91.md` の Tier 1 #1 + Tier 3 #1 (統合採用) +> +> **実行優先度**: 🚀 **Tier 1** — 工数 S。決定論的な再発防止で本 PR の主要 finding に直結。Bundle 戦略の継続として code-review.md ルール追記も同 PR で land。 + +#### 設計決定 (案) + +- 配置先: `src/hooks-post-tool-linter/src/main.rs` の `load_custom_rules()` か専用 unit test +- 検証ロジック (案 A: 起動時 check): + ```rust + for rule in &rules { + if rule.extensions.iter().any(|e| e == "ps1") && !rule.pattern.contains("(?i)") { + eprintln!("[post-tool-linter] WARN: rule '{}' targets ps1 but lacks (?i) flag", rule.id); + } + } + ``` +- 案 B: cargo test で全 TOML rule をパースして同等検証 (CI で fail させる) +- 推奨: 案 A + 案 B 併用 (起動時 warn は本番運用、test は CI 検出) +- 同 PR 同梱の code-review.md ルール追記 (案): + > **case-insensitive 言語向け lint rule の正規表現には `(?i)` フラグ必須**: PowerShell, Bash 等の case-insensitive 言語向けルールを追加する際、regex pattern に `(?i)` を付与する。テストで小文字 / 大文字 / 混在ケースを最低 1 ずつ検証する。 + +#### 作業計画 + +- [ ] hooks-post-tool-linter に起動時 check 実装 (案 A) +- [ ] cargo test に rule バリデーション test 追加 (案 B) +- [ ] `~/.claude/rules/common/code-review.md` に case-insensitive ルール追記 +- [ ] dogfood: 意図的に `(?i)` を外したルールを TOML に追加して warn 発火を確認 +- [ ] 本 todo3.md エントリを削除 + +#### 完了基準 + +- `.claude/custom-lint-rules.toml` に新規 ps1 ルールを追加した際、`(?i)` 欠落を起動時 warn または cargo test fail で検出できる +- code-review.md に case-insensitive 言語の lint rule 規約が明記される +- 既存 ps1 ルール 2 件 (`no-empty-powershell-catch`, `no-silent-error-action`) が validation を pass する + +#### 詰まっている箇所 + +なし (Effort S、既存 load_custom_rules 拡張のみ) + +--- + +### post-pr-review fix loop の `.claude/` filter + ADR-030 制約明記 (PR #91 T2-1 + T3-2 Bundle) + +> **動機**: PR #91 の post-pr-review で takt fix step が `.claude/` 配下のファイル (本ケースは存在しなかったが原則として) を fix loop 対象として扱った場合、Claude Code の sensitive-file protection により `Edit` ツールが実行時にブロックされ、`fix.1` / `fix_supervisor.1-3` の 4 回すべてが適用不能となり 8 ステップが空費される pathological loop が発生する。本 PR では実害は小さかったが、`.claude/` 配下に変更がある PR で発生すると review feedback の遅延 + rate-limit の早期消費を招く。 +> +> **本タスクの位置づけ**: post-pr-review の analyze step に **path-based filter** (`.claude/` 配下を fix 対象から除外し `user_decision` に分類) を追加。同 PR で ADR-030 (または ADR-022) に制約として「`.claude/` 配下は post-pr-review fix loop の対象外」を明記 (report Tier 3 #2 を統合)。 +> +> **参照**: `.claude/feedback-reports/91.md` の Tier 2 #1 + Tier 3 #2 (Bundle 統合採用) +> +> **実行優先度**: 🔧 **Tier 2** — 工数 S + XS。convergence cost 削減に即効。本 PR で 8 step 空費を直接観測した知見を取り込む。 + +#### 設計決定 (案) + +- 配置先: `.takt/facets/instructions/analyze-coderabbit.md` (または相当する analyze step facet) +- フィルタロジック (案): + - finding の対象 path が `.claude/` で始まる場合 → `verdict = user_decision`、`reason = ".claude/ is sensitive-file protected"` + - 同様に他の Edit-blocked path (`.git/`, `node_modules/` 等) も追加検討 +- ADR 改訂 (同 PR): + - ADR-030 に「post-pr-review fix loop の対象外パス」セクション追加 + - 対象外条件: ① Claude Code sensitive-file protection 配下、② `.git/` 等の VCS 内部、③ `node_modules/` 等の依存物 +- analyze-coderabbit.md と fix.md の read-only zone 定義の齟齬 (todo.md 「スコープ外だが将来検討」内既述) も同時解決の機会 + +#### 作業計画 + +- [ ] analyze step facet にパスフィルタ実装 +- [ ] fix step facet との read-only zone 定義整合性を確認 +- [ ] ADR-030 (または ADR-022) に制約を追記 +- [ ] dogfood: `.claude/` 配下に変更を含む PR を意図的に作って fix loop が回らないことを確認 +- [ ] 本 todo3.md エントリを削除 + +#### 完了基準 + +- analyze step が `.claude/` 配下の finding を `user_decision` 分類し fix loop に渡さない +- ADR-030 (または ADR-022) に制約が明文化される +- 8 step 空費の pathological loop が再発しない + +#### 詰まっている箇所 + +なし (Effort S+XS、analyze facet の path filter 追加 + ADR 追記のみ) + +--- + +### cli-pr-monitor 通知 Recovery 経路 (SessionStart hook 拡張) + +> **動機**: cli-pr-monitor は `pnpm push` / `pnpm create-pr` 内で in-process 同期実行され、CodeRabbit findings の検出結果を **親プロセスの stdout** で Claude shell に渡す設計 (ADR-018)。しかし Claude Code の再起動 / parent shell の orphan 化が起きると stdout が消失し、`.claude/pr-monitor-state.json` の `notified=false` 状態のまま silent loss する。本リポジトリでも PR #91 直後に Claude Code 再起動でこの事象を実体験。 +> +> **本タスクの位置づけ**: ADR-029 → ADR-030 で確立した「`.failed` marker + L2 recovery hook (UserPromptSubmit)」と同型のパターンを cli-pr-monitor 系に適用。SessionStart hook (`hooks-session-start`) を拡張し、`.claude/pr-monitor-state.json` の `notified=false + last_checked が古い (例: > 30 分)` を検出したら additionalContext で「未通知の review findings あり、`gh pr view` で確認推奨」を出力する。 +> +> **参照**: PR #91 セッション中のユーザー言及。post-merge-feedback report には未含、明示的に採用合意あり。 +> +> **実行優先度**: 🔧 **Tier 2** — 工数 S/M。silent loss 防止の保険。rate-limit critical 系 (cli-pr-monitor ポーリング延長 / post-pr-review rate-limit 自動検出) との優先度については rate-limit 系の方が日次影響大だが、本 task は **「再起動跨ぎの確実な通知伝達」** をカバーする補完層。 + +#### 設計決定 (案) + +- 配置先: `src/hooks-session-start/` (既存 SessionStart hook crate に機能追加) +- 検出ロジック (案): + - `.claude/pr-monitor-state.json` を読む (なければ no-op) + - `notified == false` AND `last_checked` が現在時刻から 30 分以上前 → recovery 必要 + - 該当 PR の概要 (action, summary, findings count) を additionalContext で出力 +- 出力例: + ```text + [PR_MONITOR_RECOVERY] + PR #N の cli-pr-monitor 結果が未通知です (last_checked: )。 + action: action_required, findings: 2 件 + 詳細: cat .claude/pr-monitor-state.json または gh pr view N + ``` +- 設計上の選択肢: + - 案 A: `notified=true` への自動更新は行わない (Claude が `pnpm mark-notified` を呼ぶ既存経路を維持) + - 案 B: SessionStart hook が自動的に `notified=true` にする (薄い recovery、二重通知を避ける) + - 推奨: 案 A (Claude の判断に委ねる方が安全) + +#### 作業計画 + +- [ ] hooks-session-start crate に state file 読み込み + recovery 判定ロジック追加 +- [ ] additionalContext 出力フォーマット決定 +- [ ] dogfood: state file を手動で `notified=false + last_checked が古い` 状態にして SessionStart hook 起動 → recovery context 出力確認 +- [ ] 派生プロジェクトに deploy +- [ ] 本 todo3.md エントリを削除 + +#### 完了基準 + +- Claude Code 再起動後の SessionStart で、未通知の cli-pr-monitor 結果があれば additionalContext として届く +- silent loss が再発しない (再起動跨ぎでも recovery 経路で必ず pickup される) +- 派生プロジェクト (techbook-ledger / auto-review-fix-vc) でも同機構が動作 + +#### 詰まっている箇所 + +なし (Effort S/M、ADR-030 の L2 recovery パターンを cli-pr-monitor に適用するだけ) + +--- + +### takt ハーネスの `REJECT-ESCALATE` terminal verdict 実装 (PR #91 T2-2) + +> **動機**: PR #91 の post-pr-review で `supervise` step が 4 回、`fix_supervisor` step が 4 回の計 8 ステップを「修正不可能な制約あり」と繰り返し報告したにもかかわらず、takt harness はループを継続した。`.claude/` filter + ADR-030 制約明記 task (PR #91 T2-1 + T3-2 Bundle) が path-based に解決するのに対し、本 task は **iteration 上限到達前に「人間判断に委譲する」と AI 自身が宣言できる verdict** を提供する一般解。 +> +> **本タスクの位置づけ**: takt の condition routing に新 terminal verdict `reject-escalate` を追加。`supervise` / `fix_supervisor` step がこのシグナルを返したら harness は即終了 + ユーザー committee `.takt/runs/.../reports/escalation.md` を生成し、Claude が次セッションで読んで判断できる経路を提供。 +> +> **参照**: `.claude/feedback-reports/91.md` の Tier 2 #2 +> +> **実行優先度**: 🔧 **Tier 2** — 工数 M (数日)。takt 本体改修なので大きい。**rate-limit 系 task (cli-pr-monitor ポーリング延長 / post-pr-review rate-limit 自動検出) と post-pr-review fix loop の `.claude/` filter Bundle の land 後に実施推奨**。本 task は根本解だが、path-based filter で path-related な pathological loop は先に解決できる。 + +#### 設計決定 (案) + +- takt のループ制御ロジックに新 terminal verdict `reject-escalate` を追加 + - 既存 verdict: `approved` / `needs_fix` / `user_decision` + - 新規: `reject-escalate` (= "AI 自己判断で escalate、harness 即終了") +- supervise / fix_supervisor instruction の verdict 一覧に `reject-escalate` を追加 + - 発火条件: 「修正不可能な制約 (sensitive file / external dependency / philosophical disagreement) を 2 iteration 連続で観測」 +- harness 側の処理: + - `reject-escalate` 検出時は loop break + `escalation.md` 生成 (理由 + 経緯) + - report phase は scoped-down で短縮実行 +- iteration 消費削減効果の測定: 既存 telemetry に `early_terminate_count` を追加 + +#### 作業計画 + +- [ ] takt 本体に `reject-escalate` verdict を追加 +- [ ] facets instruction (`supervise.md` / `fix_supervisor.md`) に発火条件と例文を追記 +- [ ] harness ループ制御ロジックを実装 +- [ ] `escalation.md` テンプレート作成 +- [ ] dogfood: `.claude/` filter (T2-1+T3-2 Bundle) 完了後、本実装前に意図的な reject-escalate ケースを inject して動作確認 +- [ ] takt-test-vc にも反映 (将来) +- [ ] 本 todo3.md エントリを削除 + +#### 完了基準 + +- `supervise` / `fix_supervisor` が `reject-escalate` を返すと harness が即終了 +- iteration 上限到達による空費が削減される (定量化可能) +- escalation.md が次セッションで読める形で生成される + +#### 詰まっている箇所 + +- takt 本体改修のため `~/.claude/projects/takt-test-vc/` 連動も視野に入れる必要あり +- rate-limit 系 task (cli-pr-monitor ポーリング延長 / post-pr-review rate-limit 自動検出) と post-pr-review fix loop の `.claude/` filter Bundle の land 後に着手することで、路径ベースの解決と verdict ベースの解決が補完関係になる