diff --git a/CLAUDE.md b/CLAUDE.md index 8e6eb271..b06e0131 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -62,6 +62,7 @@ - [ADR-059: hook 通知の可視化チャネル分離 (systemMessage = ユーザー向け / additionalContext = モデル向け)](docs/adr/adr-059-hook-system-message-visibility.md) *(試験運用)* - [ADR-060: Cloud ハーネス有効化 — tracked dispatcher 登録 + SessionStart 実体確保の 2 層分離](docs/adr/adr-060-cloud-harness-sessionstart-dispatcher.md) *(試験運用)* - [ADR-061: tool call leak の hard-fail 経路対応 — Stop 不発火の回収層 + scan_tail 合成エントリ耐性](docs/adr/adr-061-tool-call-leak-hardfail-recovery.md) *(試験運用)* +- [ADR-062: 月次ハーネス ROI レビュー — telemetry 発火実績によるハーネス複雑度の棚卸し (WP-12 step 2/3)](docs/adr/adr-062-monthly-harness-roi-review.md) *(試験運用)* ## 開発 convention / チェックリスト diff --git a/docs/adr/adr-053-stop-tool-call-leak-detection.md b/docs/adr/adr-053-stop-tool-call-leak-detection.md index 8c1566f5..d376ad9c 100644 --- a/docs/adr/adr-053-stop-tool-call-leak-detection.md +++ b/docs/adr/adr-053-stop-tool-call-leak-detection.md @@ -139,14 +139,25 @@ section 不在 / `enabled` 未設定 / `false` では完全 skip。本リポジ 根本原因は上流の不具合であり、本 hook は上流が修正されるまでの時限的な防御層である。 撤去判定 trigger: -- **撤去**: 上流 (Claude Code / モデル) の修正が確認できた、または leak が - **4 週間観測されなくなった**時点で、hook 登録解除 + crate 削除の revert PR を作成 +- **撤去**: 上流 (Claude Code / モデル) の修正が確認できた、または **月次レビュー (ADR-062) が + leak を連続 2 か月発火 0 で非アクティブ化候補として promote した**時点で、hook 登録解除 + + crate 削除の revert PR を作成 (旧「4 週間非観測」基準は ADR-062 の 2 か月基準へ正式置換。 + 2 か月は 4 週間より保守的。詳細は本 § 末尾の追記を参照) - **継続**: leak が観測され続ける間は維持。block 発火が透明になるよう stderr / reason に検知回数を明示している dogfood 計測項目: block 発火数、fail-open (上限到達) 数、誤検知報告 (正当なテキスト 出力が block された件数、期待値 0)。 +**撤去判定の機械 promote (2026-07-30 追記、[ADR-062](adr-062-monthly-harness-roi-review.md))**: +上記「4 週間観測されなくなった」の判定は人間の記憶に依存していたが、 +[ADR-062 (月次ハーネス ROI レビュー)](adr-062-monthly-harness-roi-review.md) が +telemetry 発火実績 (id `hooks-stop-tool-call-leak` + ADR-061 の `prompt-recovery` warn) から +**連続 2 か月発火 0 で非アクティブ化候補として機械 promote** する (config `zero_streak_months`、 +既定 2。4 週間より保守的な置き換え)。promote は `/monthly-review` skill の AskUserQuestion を +経てユーザーが採否し、自動無効化はしない。最終的な hook 登録解除 + crate 削除の revert PR は +本 § の手順に従う。 + ## 帰結 ### 利点 @@ -187,6 +198,7 @@ ADR-061 と連動する。約 150 セッションの corpus 調査で hard-fail ## 関連 ADR +- [ADR-062](adr-062-monthly-harness-roi-review.md) — 月次 ROI レビュー (撤去判定「4 週間非観測」を発火実績で機械 promote) - [ADR-061](adr-061-tool-call-leak-hardfail-recovery.md) — hard-fail 経路対応 (本 ADR の拡張) - [ADR-039](adr-039-experimental-feature-standard-pattern.md) — 試験運用標準パターン - [ADR-004](adr-004-stop-hook-quality-gate.md) — Stop 品質ゲート (ループ防止方式の逸脱元) diff --git a/docs/adr/adr-055-firing-telemetry-collection.md b/docs/adr/adr-055-firing-telemetry-collection.md index 9afcaeb8..7c81e2fd 100644 --- a/docs/adr/adr-055-firing-telemetry-collection.md +++ b/docs/adr/adr-055-firing-telemetry-collection.md @@ -279,8 +279,46 @@ thread panic (join の `Err`) は実 quality 違反ではないため `InfraErro - fail-open 原則は不変。telemetry 記録の有無に関わらず block decision 自体は emit するため、 infra エラー時も Claude への block 通知は従来どおり行われ、ゲート挙動は変わらない。 +## Amendment (2026-07-30): WP-12 step 2/3 消化 + 出力先の週次→月次変更 (ADR-062) + +初版 § コンテキスト / § Bounded lifetime は、step 2 (ROI 棚卸し pre-step) の出力先を +**週次レビュー ([ADR-031](adr-031-weekly-review-pipeline.md)) の facet** と想定していた。 +[ADR-062 (月次ハーネス ROI レビュー)](adr-062-monthly-harness-roi-review.md) の実装にあたり、 +この想定を **月次レビューへ変更**し、WP-12 step 2/3 を ADR-062 で消化する。 + +### 出力先を週次→月次に変更 + +テレメトリ傾向は週次では変化が小さくノイズになり、ADR-053/061 の leak 撤去粒度「4 週間」とも +月次が一致する。よって step 2 の集計は週次 facet ではなく **月次の決定論 exe +`cli-telemetry-report`** (ADR-062 § 決定 2) が担い、出力は `.claude/monthly-reviews/` + +月次 rollup (`.claude/telemetry/monthly-.json`) とする。週次 = whole-tree コード +レビュー / 月次 = telemetry/ROI 棚卸し、の役割分担で ADR-031 と併存する。 + +### step 2 / step 3 の消化内容 (ADR-062 に詳細) + +- **step 2 (棚卸し pre-step)**: `cli-telemetry-report` が workspace 横断で `firings-*.jsonl` を + 集計し、月別 × id 別カウント + 発火 0 リスト + config enabled / exe 配備 snapshot + incident 由来 + ルール ([ADR-049](adr-049-incident-eval-regression-suite.md)) の維持推奨マークを出力する。 + incident 由来の区別は初版 § Bounded lifetime の想定どおり `[rules.incident]` を真実源とする。 +- **step 3 (bounded lifetime 判定の機械化)**: config `[[telemetry_report.mechanisms]]` の静的 + マッピングで「連続 `zero_streak_months` (既定 2) か月発火 0 → 非アクティブ化候補として promote」を + MVP 実装。初期マッピングは ADR-053/061 の leak 検知 1 件。自動無効化はせず採否は + `/monthly-review` skill の AskUserQuestion を経る (ADR-022/028)。 + +### retention (順位 312) の相乗り + +初版 § Windows 並行書き込み安全性 の per-pid × 日次 partition は削除機構が無かった。 +`cli-telemetry-report` に retention (`[telemetry_report] retention_days`、code default 未設定 = +削除無効の opt-in) を相乗りさせ、rollup 確定後の raw daily ファイルを削除する (複数月トレンドは +rollup から読むため判定に影響しない)。 + +なお、初版 (別 § に既述) の 2026-07-29 amendment「block 記録を実 quality 違反に限定 (順位309)」は、 +ADR-062 の Phase 0 (ユーザー決定事項 3) として先行実装したものであり、本 step 2/3 の ROI 信号 +精度向上の一部である。 + ## 関連 ADR +- [ADR-062](adr-062-monthly-harness-roi-review.md) — 月次ハーネス ROI レビュー (WP-12 step 2/3 の実装、出力先を月次に変更) - [ADR-039](adr-039-experimental-feature-standard-pattern.md) — 試験運用標準パターン (opt-in / kill-switch / bounded lifetime) - [ADR-043](adr-043-security-gates-fail-closed.md) — fail-closed 原則 (本 telemetry は observation 層で適用外 = fail-open) - [ADR-044](adr-044-subprocess-utility-extraction-boundary.md) — utility extraction 境界 (UTC ヘルパー抽出トリガ到達) diff --git a/docs/adr/adr-061-tool-call-leak-hardfail-recovery.md b/docs/adr/adr-061-tool-call-leak-hardfail-recovery.md index 11db4c21..aa169a4a 100644 --- a/docs/adr/adr-061-tool-call-leak-hardfail-recovery.md +++ b/docs/adr/adr-061-tool-call-leak-hardfail-recovery.md @@ -163,13 +163,24 @@ code default OFF を継承する。 根本原因は上流の不具合であり、本 hook は上流が修正されるまでの時限的な防御層である。 [ADR-053](adr-053-stop-tool-call-leak-detection.md) と連動して撤去を判定する: -- **撤去**: 上流 (Claude Code / モデル) の修正が確認できた、または leak が **4 週間観測されなく - なった**時点で、ADR-053 とまとめて hook 登録解除 + crate 削除の revert PR を作成 +- **撤去**: 上流 (Claude Code / モデル) の修正が確認できた、または **月次レビュー (ADR-062) が + leak (Stop block + 本回収 warn の合算) を連続 2 か月発火 0 で promote した**時点で、ADR-053 と + まとめて hook 登録解除 + crate 削除の revert PR を作成 (旧「4 週間非観測」基準は ADR-062 の + 2 か月基準へ正式置換) - **継続**: leak が観測され続ける間は維持 dogfood 計測項目: 回収発火数 (telemetry の `hooks-stop-tool-call-leak/prompt-recovery`)、 UserPromptSubmit の発火順 (ハーネス自身の isMeta 注入との前後関係の実観測)、誤発火報告 (期待値 0)。 +**撤去判定の機械 promote (2026-07-30 追記、[ADR-062](adr-062-monthly-harness-roi-review.md))**: +ADR-053 と連動する「4 週間観測されなくなった」の撤去判定は、 +[ADR-062 (月次ハーネス ROI レビュー)](adr-062-monthly-harness-roi-review.md) が telemetry 発火 +実績から機械 promote する。本 ADR の回収層は id `hooks-stop-tool-call-leak/prompt-recovery` +(decision = warn) で記録されるため、leak トレンドは ADR-053 の Stop block と本 warn の**合算と +内訳**で見る。両 id が連続 2 か月発火 0 (config `zero_streak_months`、既定 2) で非アクティブ化候補と +なり、`/monthly-review` skill の AskUserQuestion を経てユーザーが採否する (自動無効化しない)。 +撤去は ADR-053 とまとめた revert PR で行う。 + ## 帰結 ### 利点 @@ -192,6 +203,7 @@ UserPromptSubmit の発火順 (ハーネス自身の isMeta 注入との前後 ## 関連 ADR +- [ADR-062](adr-062-monthly-harness-roi-review.md) — 月次 ROI レビュー (撤去判定を発火実績で機械 promote、回収 warn を合算) - [ADR-053](adr-053-stop-tool-call-leak-detection.md) — 既存の Stop hook 検知 (本 ADR の拡張元) - [ADR-039](adr-039-experimental-feature-standard-pattern.md) — 試験運用標準パターン - [ADR-049](adr-049-incident-eval-regression-suite.md) — incident→eval 回帰スイート (fixture 方針) diff --git a/docs/adr/adr-062-monthly-harness-roi-review.md b/docs/adr/adr-062-monthly-harness-roi-review.md new file mode 100644 index 00000000..27ce2e49 --- /dev/null +++ b/docs/adr/adr-062-monthly-harness-roi-review.md @@ -0,0 +1,212 @@ +# ADR-062: 月次ハーネス ROI レビュー — telemetry 発火実績によるハーネス複雑度の棚卸し + +## ステータス + +試験運用 (2026-07-30) + +> 本 ADR は [ADR-039 (試験運用標準パターン)](adr-039-experimental-feature-standard-pattern.md) に従う。 +> Config opt-in / kill-switch / bounded lifetime の 3 点を満たす。 +> [ADR-055 (発火テレメトリ収集層)](adr-055-firing-telemetry-collection.md) の WP-12 step 2/3 の +> 実装ビークルであり、step 2/3 を本 ADR で消化する。 + +## コンテキスト + +[ADR-055](adr-055-firing-telemetry-collection.md) の WP-12 は 3 ステップ構成で、step 1 (収集層) を +先行マージ済みである。本 ADR は残る **step 2 (ROI 棚卸し pre-step) / step 3 (bounded lifetime 判定の +発火数機械化)** を実装する。 + +### 動機となった問題 + +[ADR-053](adr-053-stop-tool-call-leak-detection.md) / +[ADR-061](adr-061-tool-call-leak-hardfail-recovery.md) の tool call leak 検知は上流 (Claude Code) +不具合への時限的な防御層であり、上流修正後も検出を続けると Stop hooks の実行時間が塵積し開発 +イテレーションを遅くする (leak hook 単体で実測 83〜829ms/Stop)。ADR-053/061 の bounded lifetime は +「leak 4 週間非観測で撤去判定」と定めるが、この判定を機械的に promote する仕組みが無く、人間の記憶に +依存していた。本 ADR の月次レビューを**この判定の最初のユースケース**にする。 + +### 週次レビューとの役割分担 + +[ADR-031 (週次レビュー)](adr-031-weekly-review-pipeline.md) が whole-tree コードレビューを担うのに +対し、本 ADR の月次レビューは **telemetry / ROI 棚卸し**を担う。ADR-055 は step 2 の出力先を +「週次レビュー facet」と想定していたが、テレメトリ傾向は週次では変化が小さくノイズになり、 +ADR-053 の撤去粒度「4 週間」とも月次が一致するため、**出力先を月次に変更する** +(ADR-055 に amendment、本 ADR § 決定 5)。 + +### warm-up 制約 + +telemetry はマージ後に初めてデータが溜まるため、ADR-055 収集開始 (2026-07-15) から 28 日 = +**2026-08-12** が初回の有意義な月次レビュー実行時期である。実装 land はそれ以前でよいが、初回実行は +08-12 以降が有意義。 + +## ユーザー決定事項 + +1. **非アクティブ化の提案閾値 = 連続 2 か月発火 0** (config で変更可能なデフォルト値)。減少傾向は + 1 か月目から参考情報として提示する。この「2 か月」は ADR-053/061 の「4 週間非観測」基準を + 置き換える正式基準であり (§ 決定 4)、2 か月は 4 週間より保守的な置き換えである (判定主体が + 人間の記憶から月次レビューへ移る)。 +2. **採用アクションはハイブリッド**: config 1〜2 行で済む軽量変更 (`enabled = false` 等) はレビュー + セッション内でその場で通常 push/PR フローで実施。大型作業 (rule 削除・crate 撤去 revert PR 等) は + weekly-review と同型の todo 登録に回す。 +3. **順位 309 (telemetry block 記録への infra エラー混入除去) をスコープに含める** (Phase 0 として + 先行実装済み。ADR-055 の 2026-07-29 amendment で消化)。 + +## 決定 + +### 1. 3 層構成 (ADR-030/031 パターンの 5 例目) + +[ADR-030](adr-030-deterministic-post-merge-feedback.md) / +[ADR-031](adr-031-weekly-review-pipeline.md) の「L1 reminder / L2 実処理 / L3 skill」パターンを +踏襲する。ただし **L2 は takt ではなく決定論 Rust exe** とする。判断材料が数表であり AI 並列 +レビューの必然性が無いため (YAGNI。必要になれば後から takt facet を追加できる)。よって +weekly-review にあった `.failed` marker / resume 機構は**不採用**とする (L2 が高速・決定論のため。 +失敗時は skill がエラー報告するのみの best-effort)。 + +### 2. L2: 新規 exe `cli-telemetry-report` + +`src/cli-telemetry-report/` ([ADR-012](adr-012-src-naming-convention.md) の `cli-` prefix)。 + +- **入力**: 各 root の `.claude/telemetry/firings-*.jsonl`。root 発見は `jj workspace list` の動的 + 列挙 (パース失敗・workspace 未使用環境は現 root のみに fail-open) + config `extra_roots` で追加可。 + テレメトリは workspace ローカル (exe 隣の `.claude/` に書かれる) で、実測上 leak 発火は improve + workspace に偏在するため **workspace 横断集計が必須**。 +- **root 発見不完全時の promote 抑止**: root 発見が不完全な場合 (`jj workspace list` 失敗 / + 現 workspace 以外の未解決 / `extra_roots` の到達不能) はレポートに **degraded を明示**し、当該 + 実行では判定候補の promote を抑止する。集計・レポート生成は fail-open で継続するが、「発火 0」 + 判定は完全な root 集合を前提とする (発見漏れ + 発火 0 の組合せは誤 promote に直結するため)。 + この環境の `ccht-improve` workspace は jj 格納パス不整合で `self.root()` が解決不能なため、 + main workspace から実行すると improve が未解決 → degraded → promote 抑止となる (leak 発火が + improve 偏在のため誤 promote を防ぐ正しい挙動)。運用上は improve workspace から実行するか + `extra_roots` に improve を追加する。 +- **月次 rollup + retention**: 月ごとの id 別集計を `.claude/telemetry/monthly-.json` + (main workspace 側) に永続化。raw daily ファイルは retention (config `retention_days`。**code + default は未設定 = 削除無効**、ADR-039 opt-in。本 repo は `retention_days = 90` で dogfood) 超過分を + 削除する。**複数月トレンドは rollup から読む**ため raw 削除後も判定可能。rollup は集計済み月を + 再集計しない (確定月は不変。当月は毎回再計算)。 +- **レポート出力** (`.claude/monthly-reviews/.md` + 機械可読 JSON): + (a) 月別 × id 別カウント + 前月比、(b) 直近 N か月の発火 0 リスト、(c) config enabled / exe 配備 + 状態の **snapshot** (「0 = 上流修正」と「0 = 無効化・未配備」の誤読防止)、(d) incident 由来ルール + ([ADR-049](adr-049-incident-eval-regression-suite.md)) の「発火 0 でも維持推奨」マーク、 + (e) 判定候補。incident 由来ルールの真実源は `.claude/custom-lint-rules.toml` の `[rules.incident]` + サブテーブル (id を exe 側に複製しない、ADR-049 思想と整合)。snapshot は集計実行時点の状態であり + 単体では月内の有効性を証明しないため、**月次 rollup 確定時に当月の snapshot を rollup JSON にも + 保存**し、判定はこの月別記録を参照する。 + +### 3. L1: SessionStart reminder + +`hooks-session-start` の `[session_start.monthly_review_reminder]` (`enabled` / `threshold_days` +既定 28 / `system_message_enabled`)。`weekly_review.rs` のパターンを踏襲し、以下の教訓を適用する: + +- staleness は state file `.claude/monthly-review-last-run.json` の `last_run_at` **内容 timestamp** + のみで判定し mtime に一切依存しない (ADR-031 の silent-fresh バグ教訓)。 +- state file の読み書きは `lib_jj_helpers::resolve_main_workspace_root` で **main workspace root に + canonical 化** ([ADR-045](adr-045-jj-workspace-parallel-sessions.md) 分裂対策。hook 読み側と + skill 書き側の両方)。 +- systemMessage は [ADR-059](adr-059-hook-system-message-visibility.md) の opt-in + 1 行 + (`lib_hook_output::SingleLineMessage` を使用)。 +- 発火は telemetry に id `monthly_review_reminder` / warn で計装 (ADR-055 amendment PR-N3 と同型)。 + +weekly と異なり **failed marker 経路は持たない** (§ 決定 1 の marker 不採用)。weekly + monthly が +同時発火した場合、systemMessage スロットは出力 JSON に 1 つのため ` / ` 区切りで 1 行に合成する +(additionalContext は両 reminder を独立に付す)。 + +### 4. 判定候補 (step 3 MVP) + +「機構 → 監視対象 id 群 → 成立時の提案」の静的マッピングを config +(`hooks-config.toml [[telemetry_report.mechanisms]]`) に持ち、**連続 `zero_streak_months` (既定 2) +か月発火 0 で非アクティブ化候補として promote** する (ユーザー決定事項 1)。promote の成立条件には +「対象の各月 rollup に `enabled = true` + 配備ありの snapshot 記録があること」を含める (無効化・ +未配備の月を「発火 0」と誤読しない)。**月中の一時無効化までは snapshot では検出できない**が、 +最終判断が必ずユーザー採否 (AskUserQuestion) を経る前提で受容する。 + +初期マッピングは 1 件: ADR-053/061 (leak 検知) → ids +`[hooks-stop-tool-call-leak, hooks-stop-tool-call-leak/prompt-recovery]` → 提案 = +`[stop_tool_call_leak] enabled = false` + `prompt_recovery_enabled = false` (最終的な crate 撤去 +revert PR は ADR-053/061 bounded lifetime の手順に従う)。ADR-061 の回収層は id +`hooks-stop-tool-call-leak/prompt-recovery` (decision = warn) で記録されるため、leak のトレンドは +block + この warn の合算と内訳で見る。全試験運用 ADR の網羅登録は将来拡張とし、MVP はこの 1 件 + +発火 0 リスト全般で足りる。 + +### 5. L3: skill `/monthly-review` + +skills repo (`$CLAUDE_SKILLS_REPO`) で作成し `~/.claude/skills/` へ deploy する +(weekly-review skill の構成を template にする): + +- Phase 1: 起動条件確認 → Phase 2: `pnpm telemetry-report` (exe) を同期実行 → Phase 3: レポート + 提示 + AskUserQuestion で判定候補・削除候補の採否 → Phase 4: **ハイブリッド実行** (軽量 config + 変更は即時に通常 push/PR フロー、大型は `docs/todo.md` 登録) + last-run 更新 (ユーザー決定事項 2)。 +- **last-run 更新契約 (L1 reminder の誤抑制防止)**: `.claude/monthly-review-last-run.json` の + `last_run_at` は、**exe が完全な (degraded でない) レポート生成に成功し、Phase 3 (レビュー) に + 到達した場合にのみ**更新する。**exe 失敗** (Phase 2 で非 0 exit = レポート不在。skill は Phase 4 + に到達しない) と **degraded** (root 発見不完全で promote 抑止) の場合は last-run を**更新せず + stale のまま**にし、次回セッションで L1 reminder を再発火させる。degraded を「レビュー完了」と + みなして更新すると、root 発見漏れ (leak 発火が improve に偏在) のまま催促が止まるため。degraded は + improve workspace 実行 / `extra_roots` 追加で解消するまで催促を継続する (§ 決定 2 の運用指針と整合)。 +- **候補が 4 件を超える場合は AskUserQuestion を複数質問に分割**する (1 質問 4 option の制約。 + severity / 機構種別順にグループ化。ADR-031 Phase E dogfood で確立した weekly-review と同方式)。 +- 自動で無効化しない。採否は必ず AskUserQuestion を経る + ([ADR-022](adr-022-automation-responsibility-separation.md) / + [ADR-028](adr-028-pnpm-create-pr-gate.md))。 + +## ADR-039 3 点セット + +### Config opt-in (default OFF) + +- **L1 reminder**: `[session_start.monthly_review_reminder]` の code default は + `enabled = unwrap_or(false)`。section 省略で完全 skip。本 repo は dogfood のため `enabled = true`。 +- **L2 retention**: `[telemetry_report] retention_days` 未設定で削除無効 (レポート生成のみは継続)。 + 本 repo は `retention_days = 90` で dogfood。 +- 派生プロジェクトへの deploy 時は各 section 省略で OFF を継承する。 + +### Kill-switch + +| 停止手段 | 影響範囲 | +|---|---| +| `[session_start.monthly_review_reminder] enabled = false` | L1 reminder を恒久停止 | +| `[session_start.monthly_review_reminder] system_message_enabled = false` | systemMessage のみ停止 (additionalContext の nudge は継続) | +| `[telemetry_report]` section 削除 | L2 集計を停止 (収集層 `[telemetry]` とは独立) | +| 上流 `[telemetry]` の kill-switch (`enabled = false` / env `CLAUDE_TELEMETRY_DISABLE`) | 収集層ごと停止 = 本集計の入力が枯れる | + +### Bounded lifetime + +telemetry の ROI 棚卸しは dogfood で有用性を検証する。明示的な decision trigger: + +- **dogfood 3 回** (月次のため約 3 か月) で採否判定 (本採用化 or 撤去)。 +- 撤去時は L1 reminder + L2 exe + L3 skill をまとめて revert する。 +- 本 ADR が消化する ADR-053/061 の leak 撤去判定は、初回有意義な実行 (2026-08-12 以降) から連続 + 2 か月発火 0 の成立をもって promote する。 + +## 帰結 + +### 利点 + +- 試験運用機構 (rule/preset/hook) の維持・撤去判断を、人間の記憶ではなく発火実績で機械化する + 基盤ができる。ADR-053/061 の「4 週間非観測」の記憶依存判定が月次レビューの機械 promote に移る。 +- L2 が決定論 exe (LLM 不使用) で高速なため、takt facet の失敗/resume 機構 (`.failed` marker) を + 持たずに済み、weekly-review より簡素。 +- workspace 横断集計 + degraded 時の promote 抑止により、telemetry が workspace ローカル + (leak 発火が improve に偏在) でも誤 promote を構造的に防ぐ。 + +### 欠点 / 留意点 + +- **telemetry はローカル運用データ** (gitignore): rollup もローカル。マシン移行でトレンドが + 消える点は ADR-055 と同じ位置づけで受容する。 +- **発火 0 の解釈**は snapshot (config enabled + exe 配備の月別記録) で緩和するが確定はしない。 + **月中の一時無効化は snapshot では検出できない**限界があり、最終判断は必ずユーザー採否を経る + (自動無効化しない)。 +- **初回実行は 2026-08-12 以降を推奨** (warm-up)。実装 land はそれ以前でよい。 +- root 発見が不完全な実行では degraded を明示し promote を抑止するが、集計・レポート自体は + fail-open で継続する ([ADR-043](adr-043-security-gates-fail-closed.md) の fail-closed は + ゲート限定であり、本 observation 層は適用外)。 + +## 関連 ADR + +- [ADR-055](adr-055-firing-telemetry-collection.md) — テレメトリ収集層 (WP-12 step 1、本 ADR の土台。step 2/3 消化 + 出力先の週次→月次変更を amendment) +- [ADR-031](adr-031-weekly-review-pipeline.md) — 週次レビュー (3 層パターンの直接の先例、役割分担 = whole-tree コードレビュー) +- [ADR-030](adr-030-deterministic-post-merge-feedback.md) — 決定論的 post-merge feedback (3 層パターンの先例) +- [ADR-053](adr-053-stop-tool-call-leak-detection.md) / [ADR-061](adr-061-tool-call-leak-hardfail-recovery.md) — 第一ユースケース (leak 検知の bounded lifetime、撤去判定を本 ADR が機械 promote) +- [ADR-039](adr-039-experimental-feature-standard-pattern.md) — 試験運用 3 点セット +- [ADR-045](adr-045-jj-workspace-parallel-sessions.md) — workspace 状態分裂 (main-root canonical 化 / workspace 横断集計の根拠) +- [ADR-059](adr-059-hook-system-message-visibility.md) — systemMessage / SingleLineMessage (L1 reminder の可視化チャネル) +- [ADR-049](adr-049-incident-eval-regression-suite.md) — incident 由来ルールの維持推奨区別 +- [ADR-022](adr-022-automation-responsibility-separation.md) / [ADR-028](adr-028-pnpm-create-pr-gate.md) — 承認ゲート (自動無効化しない根拠) +- [ADR-012](adr-012-src-naming-convention.md) — src/ 命名規約 (`cli-` prefix) diff --git a/docs/harness-improvement-plan.md b/docs/harness-improvement-plan.md index ed8cae12..49627153 100644 --- a/docs/harness-improvement-plan.md +++ b/docs/harness-improvement-plan.md @@ -71,7 +71,7 @@ Anthropic 公式のハーネスエンジニアリング指針（決定論的基 | WP-09 | 1-C | PR 監視の GitHub Actions 化 Phase A（読み取り専用） | M | なし | 観測中（`.github/workflows/pr-monitor.yml` + ADR-022 原則 6、PR #258 マージ済で master 上で本稼働。トリガーはレビュアー非依存〔pull_request_review 全レビュアー + pull_request opened/ready + issue_comment は coderabbitai 発のみ〕、sonnet。読み取り専用は「エージェント書き込み能力ゼロ + 非エージェント step のデータ投稿」の 2 不変条件で担保〔pre-push security review が token-exfil 含む 3 件を land 前に修正〕。secrets 登録済・スモークテスト成功。dogfood: セッション閉鎖中の無人分析コメント + wakeup 失効の取りこぼしゼロを確認したら完了。follow-up〔pagination ギャップ等〕は WP-10 feedback 時に採否判断） | | WP-10 | 1-C | 自律境界ポリシー ADR（ADR-028 の 2 段化） | S | なし | 実装済（ADR-052 起票: 自律 actor 限定の 2 クラス分類〔自動実行可: docs-only / Tier3 cleanup / `claude/` push / draft PR 作成、ゲート必須: ready 化 / マージ / master push〕+ 分類不能は fail-closed〔ADR-043〕。ADR-028 のゲートを commitment 点へ移設するのが 2 段化の本質。試験運用。Rust 分類関数は呼び手〔自律実行経路〕不在で今回見送り＝ WP-17/18 着手時に gate.rs の docs-only 判定を lib 切り出しで実装） | | WP-11 | 2 | prompt injection 信頼境界の 3 層防御 | M-L | WP-08 | 実装済（[ADR-054](adr/adr-054-prompt-injection-trust-boundary-defense.md): 分類/指示/決定論の 3 層 + security facet + fixture。決定論層は default OFF opt-in、本リポジトリは observe で dogfood 開始。誤検知ゼロ確認後 enforce 昇格が採否判定〔3-5 PR〕） | -| WP-12 | 2 | 発火テレメトリ + ハーネス ROI 棚卸し | M | なし | 実装済（step1 収集層のみ: ADR-055 + lib-telemetry + 6 hook 計装。step2-3〔集計 pre-step / 卒業判定機械化〕は 28 日 warm-up 後着手のため todo 順位 307/308 へ移管） | +| WP-12 | 2 | 発火テレメトリ + ハーネス ROI 棚卸し | M | なし | 実装済（step1 収集層: ADR-055 + lib-telemetry + 6 hook 計装。step2-3〔集計 pre-step / 卒業判定機械化〕+ retention は [ADR-062](adr/adr-062-monthly-harness-roi-review.md) 月次ハーネス ROI レビュー〔cli-telemetry-report + /monthly-review skill〕で消化。出力先は当初想定の週次から月次へ変更。初回有意義な実行は 28 日 warm-up 後 2026-08-12 以降） | | WP-13 | 3 | EXE_SUFFIX 抽象化 | M | なし | 実装済（build/実行 scripts を deploy-artifacts.mjs / run-artifact.mjs 経由に、settings を `/` 区切り + `{{EXE_SUFFIX}}` 化、Rust の機能的 exe 解決を EXE_SUFFIX 化。ADR-005 amendment。cargo test 全 pass・build:all/deploy:hooks/lint:docs 退行なし実測。config TOML の cmd.exe 依存は WP-15 へ。`完了` は初回 push/PR で launcher 経路の実走確認後） | | WP-14 | 3 | PowerShell 3 本の Rust 化 | S-M ×2 | なし | 実装済（3 本すべて Rust 化: fix-metrics-check→comment-lint `--fix-metrics-check` / prepare-pr-body→cli-pr-monitor サブコマンド / analyze-takt-timings→新規 cli-takt-timings crate。cargo test カバレッジ下・実データで旧 ps1 と出力一致確認。`完了` は初回 push/PR で fix step metrics-check と prepare-pr-body 経路の実走確認後） | | WP-15 | 3 | Linux バイナリビルド + クラウド setup script | M | WP-13, 14 | 実装済（release-binaries.yml〔master push → rolling `nightly` prerelease に単一 tarball〕+ scripts/cloud-setup.sh 新設。前提として Linux 実行時に壊れる可搬性欠陥を修正: `cmd /c` 決め打ちの唯一の shell spawn 点を `shell_command`〔Windows=cmd /c / 他=sh -c〕へ集約、taskkill のみだった timeout kill に unix 分岐、cmd.exe 構文テストの OS 中立化、config の `.exe`/backslash 依存を `{{CLAUDE_DIR}}`/`{{EXE_SUFFIX}}` 展開へ。**WSL Ubuntu 24.04 で実測**: cargo test --workspace 全 pass・ignored 含め全 pass・clippy clean・hooks 実発火・push pipeline が sh -c 経路で完走。Linux 実測により lock の同時取得レース〔8 中 6 取得〕も発見・修正。`完了` は release 実生成 + 実クラウドセッションでの cloud-setup.sh 実走確認後） | @@ -219,7 +219,7 @@ Anthropic 公式のハーネスエンジニアリング指針（決定論的基 ### WP-12: 発火テレメトリ + ハーネス ROI 棚卸し -> **実装済 (2026-07-15、step1 収集層のみ、[ADR-055](adr/adr-055-firing-telemetry-collection.md))**: ヒアリングで「収集層のみ先行 PR」と確定。共通 lib `lib-telemetry` を新設し、6 hook（pre-tool-validate preset / post-tool-linter custom rule / jj-op-verify warn / stop-quality / stop-tool-call-leak / comment-lint-rust file-length gate）を計装。発火を `.claude/telemetry/firings--.jsonl` に per-process/per-day partition で append（Windows 並行競合を pid+日次+Mutex の 3 重で排除）。記録はメタデータのみ（hook/kind/id/decision/timestamp、パス・内容は非記録）。**記録対象は裁量発火に限定**（常時 ON の構造チェック〔非 doc コメント/関数長/file_size/utf8〕と nudge-only hook は ROI ノイズのため除外）。ADR-039 3 点セット（opt-in default OFF・kill-switch `CLAUDE_TELEMETRY_DISABLE`・bounded lifetime）+ fail-open（ADR-043 の fail-closed はゲート限定）。step 1 の理由: telemetry はマージ後に初めてデータが溜まるため、この PR 単体では必ず発火 0（データ無し）になる。**step 2（集計 pre-step）/ step 3（卒業判定機械化）は 28 日 warm-up 後に実データで着手するため todo 順位 307/308 へ移管**。以下は当初ステップ（記録用）。 +> **実装済 (2026-07-15、step1 収集層のみ、[ADR-055](adr/adr-055-firing-telemetry-collection.md))**: ヒアリングで「収集層のみ先行 PR」と確定。共通 lib `lib-telemetry` を新設し、6 hook（pre-tool-validate preset / post-tool-linter custom rule / jj-op-verify warn / stop-quality / stop-tool-call-leak / comment-lint-rust file-length gate）を計装。発火を `.claude/telemetry/firings--.jsonl` に per-process/per-day partition で append（Windows 並行競合を pid+日次+Mutex の 3 重で排除）。記録はメタデータのみ（hook/kind/id/decision/timestamp、パス・内容は非記録）。**記録対象は裁量発火に限定**（常時 ON の構造チェック〔非 doc コメント/関数長/file_size/utf8〕と nudge-only hook は ROI ノイズのため除外）。ADR-039 3 点セット（opt-in default OFF・kill-switch `CLAUDE_TELEMETRY_DISABLE`・bounded lifetime）+ fail-open（ADR-043 の fail-closed はゲート限定）。step 1 の理由: telemetry はマージ後に初めてデータが溜まるため、この PR 単体では必ず発火 0（データ無し）になる。**step 2（集計 pre-step）/ step 3（卒業判定機械化）+ retention は [ADR-062](adr/adr-062-monthly-harness-roi-review.md)（月次ハーネス ROI レビュー: `cli-telemetry-report` exe + `/monthly-review` skill + SessionStart reminder の 3 層）で消化済み**。当初は step 2 の出力先を週次レビュー facet と想定していたが、テレメトリ傾向は週次ではノイズになり ADR-053/061 の leak 撤去粒度「4 週間」と月次が一致するため**出力先を月次に変更**（ADR-055 に amendment）。初回有意義な実行は 28 日 warm-up 後の 2026-08-12 以降。以下は当初ステップ（記録用、出力先は現在は月次）。 - **目的**: ハーネス複雑度（hooks 7 本・ルール 12 本・crate 19 個）の維持判断を発火実績で機械化する。 - **ステップ**: diff --git a/docs/monthly-harness-roi-review-plan.md b/docs/monthly-harness-roi-review-plan.md index e68782fa..bf6658bb 100644 --- a/docs/monthly-harness-roi-review-plan.md +++ b/docs/monthly-harness-roi-review-plan.md @@ -206,9 +206,12 @@ worker thread panic を `QualityViolation` として誤計上しないよう `St → 実測で improve+main 横断集計・leak 13 block / recovery 2 warn の内訳分離・degraded 抑止を確認 (実測時点では main 側にも leak 発火が蓄積し 0 ではなくなっていたが、横断集計は正しく合算)。 -### Phase 2 (PR-3 前半): L1 reminder ✅ 実装完了 (未 push、2026-07-30) +### Phase 2 (PR-3 前半): L1 reminder ✅ 完了 (PR #331, merged 2026-07-30) -**実施結果**: `hooks-session-start` に月次レビュー reminder を実装。 +**実施結果**: `hooks-session-start` に月次レビュー reminder を実装。PR #331 として push → +CI (analyze) pass / CodeRabbit pass (Walkthrough のみ、actionable 指摘なし・未解決スレッド 0) → +squash merge 済み (merge commit `453620ed`)。post-merge-feedback (ADR-030) は takt で同期実行され、 +findings の採否は本プラン完了時にまとめてユーザー判断で実施予定 (ADR-014/030、未採用)。 - `hooks_config.rs`: `MonthlyReviewReminderConfig` (`enabled` / `threshold_days` / `system_message_enabled`) を追加し `SessionStartConfig.monthly_review_reminder` に配線 + @@ -231,9 +234,10 @@ worker thread panic を `QualityViolation` として誤計上しないよう `St default は OFF、派生 deploy では section を置かず完全 skip)。 検証: `cargo test --workspace` (全 crate green、hooks-session-start 120 件) / -`cargo clippy --workspace --all-targets -- -D warnings` / `pnpm lint:md` 全通。 -**push / PR 作成は未実施** (通常フロー・ADR-028 ゲート待ち)。実 hook 発火の確認は dogfood に委ねる -(unit テストで閾値境界を固定済み、検証要件どおり)。 +`cargo clippy --workspace --all-targets -- -D warnings` / `pnpm lint:md` 全通。push は +`pnpm push` (takt push-runner、pre-push-review APPROVE) → PR #331 作成 (ADR-028 ゲート、ユーザー承認) → +merge pipeline (ADR-013、squash merge + `jj new master@origin` 同期) で完了。実 hook 発火の確認は +dogfood に委ねる (unit テストで閾値境界を固定済み、検証要件どおり)。 実装上の決定 (プラン未指定箇所、Phase 4 で ADR-062 へ反映): @@ -247,22 +251,43 @@ worker thread panic を `QualityViolation` として誤計上しないよう `St (書き手は L3 skill、exe/hook 側は読むのみ)。当初計画どおり (すべて完了): 設計決定 3 の全教訓 (a)〜(d) を適用、hooks-config.toml で dogfood。 -### Phase 3 (PR-3 後半 + skills repo): L3 skill + docs - -- **skills repo 側**: `$CLAUDE_SKILLS_REPO/monthly-review/SKILL.md` を新規作成 (weekly-review - skill を template に、設計決定 4 の Phase 構成)。skills repo の規約 - (`$CLAUDE_SKILLS_REPO/docs/adr/0002` 等) に従い、deploy 方式は既存 skill と同じにする。 - skills repo は別リポジトリのため PR フローも当該 repo の流儀に従う。 -- **本 repo docs**: - - ADR-062 新規: 本ドキュメントの「背景」「設計決定」「ユーザー決定事項」を正式記録。 - ステータス試験運用、ADR-039 3 点セット (opt-in: reminder/retention は default OFF、 - kill-switch: 各 enabled = false + telemetry 側 kill-switch が上流に存在、bounded lifetime: - dogfood 3 回で採否判定)。 - - ADR-055 amendment: step 2/3 消化 + 出力先の週次→月次変更 + (Phase 0 の) block 記録限定。 - - ADR-053 / ADR-061 追記: 「撤去判定 (4 週間非観測) は月次レビュー (ADR-062) が機械 promote - する」1 段落ずつ。 - - CLAUDE.md index に ADR-062 追加。todo-summary2.md / todo16.md の順位 307/308/312 entry を - 消化・削除 (harness-improvement-plan.md の WP-12 状態も更新)。 +### Phase 3 (PR-3 後半 + skills repo): L3 skill + docs ✅ 実装完了 (未 push / skills repo 未 commit、2026-07-30) + +**実施結果**: L3 skill (skills repo) + 本 repo docs をすべて実装。 + +- **skills repo 側** (`$CLAUDE_SKILLS_REPO` = `C:\Users\owner\work\claude-code-skills`、git・別リポ): + `monthly-review/SKILL.md` + `evals/evals.json` (5 ケース) + `evals/trigger_eval.json` + (22 件: 正 8 / 負 14) を新規作成。weekly-review を template にしつつ、設計決定 1 に従い takt でなく + `pnpm telemetry-report` (`cli-telemetry-report`) を同期実行、failed marker / resume 機構なしの + 簡素版。設計決定 4/5 の Phase 構成 (起動条件確認 → exe 同期実行 → レポート提示 + AskUserQuestion + 採否〔4 件超は分割〕→ ハイブリッド実行〔軽量 config 即時 push/PR / 大型 docs/todo.md 登録〕+ + last-run 更新)。degraded / warm-up 時の promote 抑止も明記。ADR-0002 規約に従い + `~/.claude/skills/monthly-review/SKILL.md` へ deploy 済み (repo と in sync、skill として登録確認)。 + **skills repo の commit / PR は未実施** (git はこの workspace の hook で block されるため、当該 repo の + flow で別途)。 +- **本 repo docs** (すべて完了): + - ✅ ADR-062 新規 (`docs/adr/adr-062-monthly-harness-roi-review.md`): 本ドキュメントの「背景」 + 「設計決定」「ユーザー決定事項」を正式記録。試験運用、ADR-039 3 点セット (opt-in: + reminder/retention は default OFF、kill-switch: 各 enabled = false + 上流 telemetry の + kill-switch、bounded lifetime: dogfood 3 回で採否判定)。 + - ✅ ADR-055 amendment (2026-07-30): step 2/3 消化 + 出力先の週次→月次変更 (既存 2026-07-29 の + block 記録限定を Phase 0 分として本 amendment で言及)。 + - ✅ ADR-053 / ADR-061 追記: 「撤去判定 (4 週間非観測) は月次レビュー (ADR-062) が連続 2 か月発火 0 で + 機械 promote する」を 1 段落ずつ + 関連 ADR リンク。 + - ✅ CLAUDE.md index に ADR-062 追加。todo-summary2.md の順位 307/308/312 行削除、todo16.md の該当 + 3 セクション (WP-12 step 2 / step 3 / retention) 削除、harness-improvement-plan.md の WP-12 状態 + 更新 (step 2-3 + retention を ADR-062 で消化、出力先 週次→月次)。 + +検証: `pnpm lint:md` 全通 (skills repo の SKILL.md も markdownlint 0 error、eval JSON は妥当性確認済)。 +**push / PR 作成は未実施** (通常フロー・ADR-028 ゲート待ち)。 + +実装上の決定 (プラン未指定箇所、Phase 4 で ADR-062 へ反映): + +- skill の大型作業の登録先は `docs/todo.md` (weekly-review と同一慣行)。優先度 table への行追加は + skill では行わずユーザー判断。 +- eval は fixture 不使用の 5 シナリオ (正常 config 採用 / degraded 抑止 / warm-up 保留 / + exe 失敗 best-effort / 大型 todo 登録)。trigger 負例に weekly-review との弁別 (「週次」「/weekly-review」) + と config 編集依頼を含める。 ### Phase 4 (最終): ADR 記載漏れ確認 + 本ドキュメント削除 diff --git a/docs/todo-summary2.md b/docs/todo-summary2.md index 3183f2a5..d29c0b6d 100644 --- a/docs/todo-summary2.md +++ b/docs/todo-summary2.md @@ -67,14 +67,11 @@ | 304 | 💎 Tier 3 | **quality gate 実行中に発見したバグ修正が別 PR に混入した際の jj split + jj rebase 復旧パターンを記録 (273.md T3-3 採用)** | todo16.md | XS | なし (PR #272/#273 分離で実証済みの復旧手順、ADR-045 の並列 workspace リスクとは別種の単一 session 内混入事故。復旧は事後対応であり、分離後は混在した変更に対する gate 実行結果を無効化し各 PR で再実行する手順を含む) | | 305 | 💎 Tier 3 | **Metrics violation の pre-existing 判定基準の明文化 (273.md T3-4 採用)** | todo16.md | XS | なし (file_size_check / file_length_gate 等 metrics 系 gate が複数稼働中で反復しうる override 正当性の判定基準を明文化) | | 306 | 💎 Tier 3 | **quality gate isolation 機構を見送り、recovery による risk acceptance とした判断の記録 (negative result) (273.md T3-5 採用)** | todo16.md | S | なし (spike 見送り convention に従い、isolation 機構を却下し recovery コストの低さ (順位304) を理由に risk acceptance した根拠を記録。recovery は isolation の代替ではなく、予防機能の欠如という残存リスクと再検討条件を明記する) | -| 307 | 🔧 Tier 2 | **WP-12 step 2: 発火テレメトリ ROI 棚卸し pre-step (発火 0 の rule/preset/hook を削除候補提示)** | todo16.md | M | なし (**着手条件 = ADR-055 収集層マージから 28 日 warm-up 後**。それ以前は全項目が発火 0 = データ無しで判定無意味。集計は Rust exe、weekly-review に file-length-watchlist 同型 facet で接続、incident 由来ルールは発火 0 でも維持推奨の区別) | -| 308 | 💎 Tier 3 | **WP-12 step 3: ADR-039 bounded lifetime 判定の発火数機械化** | todo16.md | S | 順位 307 (step 2 の集計基盤に依存)。試験運用 ADR 機構の卒業/廃止検討を発火数で自動 promote。step 3 完了で WP-12 完了 | | 310 | 🚀 Tier 1 | **custom-regex preset の生 regex が telemetry id に流れる privacy footgun 是正（非ブロッキング follow-up 統合）(275.md T1-2 採用)** | todo16.md | S | なし (現行 config は named preset のみで非発火だが派生プロジェクトの latent footgun。fallback を合成 id〔"custom-block"〕に正規化 + ADR-055 に config privacy 注記) | | 311 | 🚀 Tier 1 | **逐語的関数複製（3+ コピー）を pre-push 検出する DRY lint rule (275.md T1-3 採用)** | todo16.md | M | なし (is_truthy 三重複製事案。ADR-007 regex 層に threshold 検出追加。順位 313 の fixture と抱き合わせ) | -| 312 | 🔧 Tier 2 | **`.claude/telemetry/` の per-pid×日次 partition ファイル retention/cleanup (275.md T2-1 採用)** | todo16.md | M | 順位 307 (WP-12 step 2 と同時期＝step1 マージから 28 日後 2026-08-12 頃に着手) | | 313 | 🔧 Tier 2 | **is_truthy 三重複製を ADR-049 incident fixture 化 (275.md T2-4 採用)** | todo16.md | XS | 順位 311 (DRY lint rule と抱き合わせ) | | 314 | 🔧 Tier 2 | **bookmark 未作成での push 失敗（exit 7）のエラーメッセージ改善 (275.md T2-5 採用)** | todo16.md | S | なし (本セッションで実発生。bookmark 自動作成は ADR-011 の明示命名意図と緊張するためメッセージ改善のみ) | -| 315 | 💎 Tier 3 | **ADR-055 telemetry の bounded lifetime 期限を config コメントに明記 (275.md T3-1 採用)** | todo16.md | XS | なし (warm-up 期限 2026-08-12 頃 + 順位 307/308 リンクを `[telemetry]` section コメントに追記) | +| 315 | 💎 Tier 3 | **ADR-055 telemetry の bounded lifetime 期限を config コメントに明記 (275.md T3-1 採用)** | todo16.md | XS | なし (warm-up 期限 2026-08-12 頃 + ADR-062 リンクを `[telemetry]` section コメントに追記。step2/3 は ADR-062 で消化済み) | | 316 | 💎 Tier 3 | **ADR-044「2nd consumer で共通化」原則の明確化・判定基準の例示 (275.md T3-2 採用)** | todo16.md | S | なし (is_truthy の非対称性を case study 化。順位 317 と対) | | 317 | 💎 Tier 3 | **utility 関数追加前のチェックリスト（workspace grep）(275.md T3-3 採用)** | todo16.md | XS | 順位 316 (ADR-044 明確化と対) | | 318 | 🚀 Tier 1 | **CR rate-limit 第3 format (`Next review available in: N minutes`) 未対応 + marker 一致/regex 不一致の silent 化 (PR #287 で実観測)** | todo16.md | S | なし (ADR-034 § 検出 logic 更新手順 の 4-6 をそのまま適用可。silent 化解消は追加設計) | diff --git a/docs/todo16.md b/docs/todo16.md index 6bb4d893..ae485cc3 100644 --- a/docs/todo16.md +++ b/docs/todo16.md @@ -216,62 +216,6 @@ --- - - - -### WP-12 step 2: 発火テレメトリ ROI 棚卸し pre-step (28 日 warm-up 後着手) - -> **動機**: WP-12 step 1 ([ADR-055](adr/adr-055-firing-telemetry-collection.md)) で `lib-telemetry` が `.claude/telemetry/firings-*.jsonl` に発火を収集し始めた。その実データを使って「直近 28 日で発火 0 の rule/preset/hook」を削除候補として機械抽出し、ハーネス複雑度の維持判断を発火実績で機械化する (WP-12 の本来目的)。 -> -> **本タスクの位置づけ**: WP-12 step 1 の後続 PR。**着手条件 = step 1 マージから 28 日経過** (warm-up。それ以前は全項目が発火 0 = データ無しになり削除候補判定が無意味)。 -> -> **参照**: [ADR-055](adr/adr-055-firing-telemetry-collection.md) (収集層)、[ADR-031](adr/adr-031-weekly-review-pipeline.md) (棚卸しの出力先 = weekly-review)、`.takt/facets/instructions/file-length-watchlist.md` (同型の「機械層」pre-step = takt facet + Bash パターン)、`.takt/facets/instructions/aggregate-weekly.md` (`### File Length Watchlist (機械的観測)` セクションの隣に発火統計セクションを追加)、[ADR-049](adr/adr-049-incident-eval-regression-suite.md) (incident 由来ルールは発火 0 でも維持推奨の区別)。 -> -> **実行優先度**: 🔧 Tier 2 — Effort M。step 1 の投資回収に必須だが warm-up 待ちのため即着手不可。 - -#### 設計決定 (案) - -- **集計は Rust exe** (ヒアリング確定)。`firings-*.jsonl` を glob 走査し、rule/preset/hook ごとに直近 28 日の発火数を集計する `cli-*` exe (または既存 crate のサブコマンド)。全 rule/preset/hook の一覧 (custom-lint-rules.toml / preset レジストリ / hook レジストリ) との差分で「発火 0 の項目」を導出する。 -- **takt facet + Bash で weekly-review に接続**。file-length-watchlist と同型で、facet の Bash step が集計 exe を呼び watchlist markdown を出力 → aggregate-weekly が `### 発火統計 (機械的観測)` セクションとして転載する。 -- **incident 由来ルールの区別**: `custom-lint-rules.toml` の `[rules.incident]` を持つルールは発火 0 でも「抑止力として維持推奨」とし、非 incident ルールのみ削除候補にする (ADR-049 の思想)。 -- **warm-up 表示**: 収集開始日から 28 日未満の項目は「観測期間中・判定保留」と出力し、誤って削除候補に出さない。 - -#### 作業計画 - -- [ ] 集計 Rust exe を実装 (28 日窓の発火数集計 + 全項目レジストリとの差分 + incident 区別 + warm-up 判定)。ユニットテストで固定 JSONL fixture から集計値を assert。 -- [ ] takt facet (`file-length-watchlist.md` 同型) を新設し weekly-review.yaml の reviewers parallel block に追加。 -- [ ] aggregate-weekly.md に `### 発火統計 (機械的観測)` セクション転載を追加。 -- [ ] dogfood: 週次レビューレポートに発火統計セクションが出力され、初回実行で削除候補 (または全維持の根拠) が特定されることを確認。 -- [ ] 本エントリ削除 + todo-summary2.md 行削除 + [harness-improvement-plan.md](harness-improvement-plan.md) の WP-12 状態更新 (step 2 消化)。 - -#### 完了基準 - -- 週次レビューレポートに発火統計セクションが出力され、直近 28 日で発火 0 の rule/preset/hook が (incident 由来を除いて) 削除候補として、または全維持の根拠とともに特定されること。 - ---- - -### WP-12 step 3: ADR-039 bounded lifetime 判定の発火数機械化 (step 2 に依存) - -> **動機**: ADR-039 の試験運用機能の卒業/廃止判定は現状「手動で観測値を閾値照合」する方式で、機械集計機構が無い。WP-12 step 2 で発火数の集計基盤ができるので、これを使って「試験運用 ADR の機構が N 日発火 0 → 卒業 (廃止 or 本採用) の検討を promote」を機械化する。 -> -> **本タスクの位置づけ**: WP-12 step 3。**step 2 (集計基盤) に依存**。step 2 完了後に着手。 -> -> **参照**: [ADR-039](adr/adr-039-experimental-feature-standard-pattern.md) (§ 3 bounded lifetime、現状は手動 3 値判定)、[ADR-055](adr/adr-055-firing-telemetry-collection.md) (収集層)、WP-12 step 2 (集計基盤、本ファイル内)。 -> -> **実行優先度**: 💎 Tier 3 — Effort S。step 2 の集計結果に卒業/廃止判定ロジックを重ねる薄い層。 - -#### 作業計画 - -- [ ] step 2 の集計出力に「試験運用 ADR の機構ごとの発火数 + bounded lifetime 期限との照合」を追加し、卒業/廃止の検討を promote する判定を機械化する。 -- [ ] ADR-039 に「bounded lifetime 判定の発火数機械化」を amendment として記録。 -- [ ] 本エントリ削除 + todo-summary2.md 行削除 + harness-improvement-plan.md の WP-12 状態更新 (step 3 消化 = WP-12 完了)。 - -#### 完了基準 - -- 試験運用機能の卒業/廃止検討が発火数に基づいて週次で自動 promote され、ADR-039 の手動閾値照合が機械化されること。 - ---- - ### custom-regex preset の生 regex が telemetry id に流れる privacy footgun の是正（非ブロッキング follow-up 統合）(275.md T1-2 採用) > **動機**: PR #275 の pre-push simplicity review 非ブロッキング warning（= セッション中に検出された「非ブロッキング follow-up」）。`tag_source(name, ...)` の `name` が named preset 名でなく `blocked_patterns` の生正規表現文字列の場合、その regex テキストがそのまま telemetry の `id` フィールドに載り、ADR-055 の「コマンド本文・内容は非記録」プライバシー原則と緊張する。現行 `hooks-config.toml` は named preset のみのため**非発火**だが、派生プロジェクトが raw-regex エントリを足すと該当する latent footgun。 @@ -315,26 +259,6 @@ --- -### `.claude/telemetry/` の per-pid×日次 partition ファイルの retention/cleanup (275.md T2-1 採用) - -> **動機**: WP-12 step 1 の Windows 並行安全性設計（per-pid × 日次 partition）は warm-up 期間中に小さな `firings-*.jsonl` を多数蓄積する。28 日超過分を削除する retention/cleanup を入れる。WP-12 step 2（集計 pre-step）の前提作業。 -> -> **参照**: `.claude/feedback-reports/275.md` Tier 2 #1、`src/lib-telemetry/src/lib.rs`、WP-12 step 2（順位 307）。 -> -> **実行優先度**: 🔧 Tier 2 — Severity Medium / Effort M。**着手条件 = WP-12 step 2 と同時期（step 1 マージから 28 日後、2026-08-12 頃）**。 - -#### 作業計画 - -- [ ] `lib-telemetry` に retention ロジック（N 日超過の firings ファイル削除）を追加、ユニットテスト。 -- [ ] WP-12 step 2 の集計 pre-step と統合（順位 307 と同一 PR 消化が自然）。 -- [ ] 本エントリ削除 + todo-summary2.md 行削除。 - -#### 完了基準 - -- 28 日を超えた telemetry partition ファイルが自動削除され、warm-up 蓄積が bounded であること。 - ---- - ### `is_truthy` 三重複製を ADR-049 incident suite の fixture として記録 (275.md T2-4 採用) > **動機**: PR #275 の `is_truthy` 三重複製を [ADR-049](adr/adr-049-incident-eval-regression-suite.md) の「カスタムルールの由来 incident 再現テスト」convention に沿って fixture 化する。順位 311（DRY lint rule）実装時に good/bad fixture として抱き合わせるのが自然。 @@ -375,15 +299,15 @@ ### ADR-055 telemetry の bounded lifetime 期限を config コメントに明記 (275.md T3-1 採用) -> **動機**: ADR-055 の telemetry は 28 日 warm-up 後に WP-12 step 2/3 で棚卸しする bounded lifetime 機能。運用者が期限を見落とさないよう、具体日付（step 1 マージ 2026-07-16 + 28 日 = 2026-08-12 頃）と todo-summary.md 順位 307/308 へのリンクを `.claude/hooks-config.toml` の `[telemetry]` section コメントに追記する。 +> **動機**: ADR-055 の telemetry は 28 日 warm-up 後に WP-12 step 2/3 で棚卸しする bounded lifetime 機能。運用者が期限を見落とさないよう、具体日付（収集開始 2026-07-15 + 28 日 = 2026-08-12 頃、ADR-062 と統一）と [ADR-062](adr/adr-062-monthly-harness-roi-review.md)（step 2/3 を消化した月次レビュー）へのリンクを `.claude/hooks-config.toml` の `[telemetry]` section コメントに追記する。 > -> **参照**: `.claude/feedback-reports/275.md` Tier 3 #1、`.claude/hooks-config.toml`（`[telemetry]` section）、順位 307/308。 +> **参照**: `.claude/feedback-reports/275.md` Tier 3 #1、`.claude/hooks-config.toml`（`[telemetry]` section）、[ADR-062](adr/adr-062-monthly-harness-roi-review.md)。 > > **実行優先度**: 💎 Tier 3 — Severity Low / Effort XS。 #### 作業計画 -- [ ] `[telemetry]` section コメントに warm-up 期限（2026-08-12 頃）と順位 307/308 を追記。 +- [ ] `[telemetry]` section コメントに warm-up 期限（2026-08-12 頃）と [ADR-062](adr/adr-062-monthly-harness-roi-review.md) を追記。 - [ ] 本エントリ削除 + todo-summary2.md 行削除。 #### 完了基準