From 2fc6f7a48b57afdb67837f836efadb2a0f0b54c2 Mon Sep 17 00:00:00 2001 From: aloekun Date: Sun, 19 Jul 2026 03:58:58 +0900 Subject: [PATCH] =?UTF-8?q?fix(observability):=20analyze-takt-timings=20?= =?UTF-8?q?=E3=81=AE=E7=A0=B4=E6=90=8D=20meta=20=E5=A0=85=E7=89=A2?= =?UTF-8?q?=E5=8C=96=20+=20doc=20=E7=9F=9B=E7=9B=BE=E8=A7=A3=E6=B6=88=20+?= =?UTF-8?q?=20follow-up=20todo=20(#295/#296=20post-merge=20feedback)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR #295/#296 の post-merge feedback 採用候補を反映。(1) analyze-takt-timings.ps1 L47 の ConvertFrom-Json を try/catch で保護し、crashed/in-progress run の truncated meta.json 1 件で集計ループ全体が中断しないよう skip (L63 の phase 行 parse と同流儀。CodeRabbit の startTime null ガードが塞げなかった JSON 自体の破損を補完)。(2) takt-step-timings.md の「正規化前提」と述べつつ未正規化 avg を 150s と直接『未達』断定していた矛盾を、diff サイズ交絡を明記し最終判定を R4/ADR-056 に委ねる記述に修正。 あわせて todo 起案: 順位327 (多段コミットの ADR/observability 更新チェックリストを dev-conventions に、Tier3)、順位328 (post-merge feedback が成功後に context.json を残し次マージの feedback を誤 bail させる cleanup gap、#296 マージで実観測、Tier1)。 検証: 正常出力不変 (24 run 203.4s)、truncated meta.json を skip してクラッシュしないことを実機確認。docs-lint / markdownlint OK。 Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/takt-step-timings.md | 9 +++++-- docs/todo-summary.md | 4 ++- docs/todo13.md | 43 ++++++++++++++++++++++++++++++++ scripts/analyze-takt-timings.ps1 | 4 ++- 4 files changed, 56 insertions(+), 4 deletions(-) diff --git a/docs/takt-step-timings.md b/docs/takt-step-timings.md index 42e7d1bd..7c856e16 100644 --- a/docs/takt-step-timings.md +++ b/docs/takt-step-timings.md @@ -71,9 +71,14 @@ pwsh -File scripts/analyze-takt-timings.ps1 -Piece pre-push-review -Since 2000-0 5. **fix の execute は発火時に高価** (baseline 15 run で avg 312s、refute 2 run で 134s)。fix loop の 発生頻度が総所要の最大の変動要因。findings を減らす施策 (anomaly policy 等) が fix コストを直接 下げる。 -6. **execute 時間は diff サイズ支配** (min 36s 〜 max 416s)。run 間比較は diff サイズ正規化が前提。 +6. **execute 時間は diff サイズ支配** (min 36s 〜 max 416s)。したがって **run 間比較は diff サイズ + 正規化が前提**で、生の avg 同士の比較だけで優劣は断定できない。 [ADR-056](adr/adr-056-review-policy-anomaly-shadow.md) の受け入れ基準「simplicity execute - 203s → 150s 以下」に対し、refute 期の実測 avg は **203.4s** で未達 (R4 判定参照)。 + **203s (ADR-056 の基準参照値、単一コード diff の 1 run)** → 150s 以下」に対し、refute 期の生 avg は + **203.4s** で、**raw では未達だが diff サイズ交絡のため policy 起因の未達とは断定できない**。 + ⚠ **この基準参照値 203s は本表の baseline 平均 (164.4s、全期間・全 diff サイズ混在) とは別物** + (基準値は特定の 1 コード diff run、baseline avg は分布の平均)。正規化した比較と最終判定は + R4 (ADR-056 の採否判定ドラフト) に委ねる。 ## 関連 diff --git a/docs/todo-summary.md b/docs/todo-summary.md index 6e775f82..57c7b8c0 100644 --- a/docs/todo-summary.md +++ b/docs/todo-summary.md @@ -5,7 +5,7 @@ > **更新方針**: table への新規行追加・既存行の削除・順位の再採番はすべて本ファイルで実施する。詳細エントリは現行の追加先ファイル (= `docs/todo13.md`、2026-06-29 PR #224 セッションで新設。従来の追加先 `docs/todo10.md` が約 95KB = 50KB 安定読み取り閾値の約 2 倍に達したため移行、todo10.md は以降 既存エントリの編集・完了削除専用) に記録する。なお `docs/todo11.md` は 2026-06-06 todo9.md 分割で新設された専用ファイル (順位 157, 160-173 を収容)、`docs/todo12.md` は 2026-06-12 PR #204 で todo10.md 分割により新設された専用ファイル (順位 176/178/179/180/181/182/193/194 = PR #185 〜 PR #196 era を収容) で、いずれも新規追加先ではない。 -## 推奨実行順序サマリー (2026-07-19 更新、順位 326 追加。323-324 は 07-18 追加、325 = push per-run メトリクス JSONL 永続化は R3 (#294) で実装完了し削除) +## 推奨実行順序サマリー (2026-07-19 更新、順位 326-328 追加。323-324 は 07-18 追加、325 = push per-run メトリクス JSONL 永続化は R3 (#294) で実装完了し削除) 開発環境の作業効率への貢献度を基準にした推奨実行順序。詳細は各タスク冒頭の **「実行優先度」** 行を参照。 @@ -170,6 +170,8 @@ | 323 | 🚀 Tier 1 | **`lib-subprocess` `run_cmd_shell_*` の timeout が wall-clock を縛れない — 孫プロセス残存で join がブロック (push-pipeline-fix-plan §6 backlog 10 移管)** | todo13.md | S | なし (quality_gate step_timeout / push timeout / cli-merge-pipeline のハング打ち切りが実質無効。#286 post-merge-feedback の orphan/stale marker と同根の実害 1 件観測済。回帰テストに経過時間 assert 必須 = T6 教訓) | | 324 | 🚀 Tier 1 | **`cli-pr-monitor::push_to_remote` に push 拒否検知が無く post-PR re-push が無言で失敗し得る (push-pipeline-fix-plan §6 backlog 9 移管)** | todo13.md | XS | なし (T5 = PR #282 が cli-push-runner 側で塞いだ silent-failure push と同型の穴。出力は `run_cmd_direct` で全量取得済のため判定追加のみ) | | 326 | 🔧 Tier 2 | **並列設計レビュアー (design-fit reviewer) の実験起案 — 見落とし実績の事前調査付き (R4/ADR-047 却下分析の代替案)** | todo13.md | S (Phase 0) / M (Phase 1 条件付き) | なし (Phase 0 の需要調査で見落とし実績ゼロなら見送り = negative result 永続化。ADR-047 却下確定 = refute.yaml 削除 revert PR とは独立に進められる) | +| 327 | 🔧 Tier 3 | **多段コミットの ADR/observability 更新チェックリストを dev-conventions に追加 (#295/#296 post-merge feedback 採用: status 同期 / plain-text 参照 / セクション同期)** | todo13.md | S | なし (実害は各 PR review/feedback で捕捉済。doc checklist のみ、機械化は再発観測後にエスカレーション) | +| 328 | 🚀 Tier 1 | **post-merge feedback が成功後に `post-merge-feedback-context.json` を残し次マージの feedback を誤 bail させる (cleanup gap、#296 マージで実観測)** | todo13.md | S | なし (連続マージで後発 PR の再発防止分析が構造的に skip。成功時 cleanup の追加 + 回帰テスト。ADR-030 L2 recovery で今回は手動救済済) | **戦略**: Tier 1 を 2〜3 セッションで片付け → Tier 2 で ADR-032 の前提 + rate-limit + convergence cost 削減を進める → Tier 3 で ADR-032 を land + ドキュメント整備。Tier 4-5 は cleanup / 外部展開で daily efficiency への直接効果は小さい。 diff --git a/docs/todo13.md b/docs/todo13.md index 62d52e55..6a956f35 100644 --- a/docs/todo13.md +++ b/docs/todo13.md @@ -1847,6 +1847,49 @@ --- +### 多段コミットの ADR / observability 更新チェックリストを dev-conventions に追加 (#295/#296 post-merge feedback 採用) + +> **動機**: R4 (ADR-047 却下 / ADR-056 延長) を「判定ドラフト → 却下理由補強 → plan2.md 反映 → 却下確定・撤去 → 観測ツール」と複数コミット・複数 PR に分割して進めた際、齟齬が複数回発生した — (a) timing doc が ADR-047 を「却下」と断定したが該当ブランチの ADR status header は未確定だった (PR #295 の pre-push review が REJECT → fix step が訂正)、(b) timing doc の `docs/takt-step-timings.md` への参照を markdown link にすると中間コミットで cross-ref が壊れるため plain-text に統一する必要があった、(c) ADR status 行と「採否判定」セクションの同期。ADR 58 件超・活発な多段階判定運用の本 repo では同型の反復が見込まれる。#295 と #296 の post-merge feedback がいずれも採用候補と判定。 +> +> **対処案**: `docs/dev-conventions.md` に「多段コミット/多段 PR で ADR・観測 doc を更新するときのチェックリスト」を追加する。項目案: ① doc が外部 ADR の status (試験運用/却下等) に言及する場合は、参照先 ADR の**現行 status header と同期**しているか (未確定を「確定」と書かない)、② 別コミット/別 PR にまたがるファイルへの参照は **markdown link ではなく plain-text パス**にして中間コミットの cross-ref 破壊を避ける (docs-lint cross-ref は markdown link のみ検査)、③ ADR の status 行と「採否判定」セクションの記述を同時更新する。dev-conventions には WP-06/07/08 由来の同種 checklist 先例が複数あり同形式で追加可能。 +> +> **参照**: `.claude/feedback-reports/295.md` Tier3 #2 / `.claude/feedback-reports/296.md` Tier3 #2、`docs/dev-conventions.md`、[ADR-048](adr/adr-048-facet-findings-handoff-markdown-contract.md) (plain-text 参照統一の先例は本 R4 で ADR-047/056 に適用済)、[ADR-030](adr/adr-030-deterministic-post-merge-feedback.md)。 +> +> **実行優先度**: 🔧 Tier 3 — Severity Low / Frequency Medium / Effort S (doc checklist の追加のみ、機械化はしない)。実害は未観測 (齟齬は各 PR の review / feedback で捕捉できている) のため、より重い自動化 (custom lint / pre-push facet checklist) は再発観測後にエスカレーション。 + +#### 作業計画 + +- [ ] `docs/dev-conventions.md` に上記 3 項目のチェックリストを追加 (WP-06/07/08 の既存 checklist と同形式)。 +- [ ] 本エントリ削除 + todo-summary.md 行削除。 + +#### 完了基準 + +- 多段コミットで ADR/observability doc を更新する運用者が、status 同期・plain-text 参照・セクション同期の 3 点を dev-conventions のチェックリストで確認できること。 + +--- + +### post-merge feedback が成功後に `post-merge-feedback-context.json` を残し次マージの feedback を誤 bail させる (cleanup gap、#296 マージで実観測) + +> **動機**: 2026-07-19 の #296 マージで、post_merge_feedback step が「前回の feedback がまだ進行中の可能性 (context.json が 820s 前に書かれた)」と判定して bail し、`.claude/feedback-reports/296.md.failed` marker を残した ([ADR-030](adr/adr-030-deterministic-post-merge-feedback.md) L2 recovery 経路)。原因は **#295 マージの post-merge feedback が正常完了 (295.md 生成) したにもかかわらず自身の `.takt/post-merge-feedback-context.json` を掃除せず残した**こと。約 25 分 (1500s threshold) 以内に次のマージを行うと、前回の leftover context.json を「進行中」と誤判定して feedback が走らない = **連続マージで後発の feedback が構造的に skip される**。今回は手動で context.json 削除 + `--feedback-only 296` で recovery したが、根治は context.json の cleanup。 +> +> **対処案**: post-merge feedback workflow (または cli-merge-pipeline) が feedback の**正常完了時に `post-merge-feedback-context.json` を削除**する。あわせて staleness 判定を「時刻ベース (820s < 1500s)」から「稼働中プロセスの実在確認」等に寄せるか、少なくとも成功時 cleanup で leftover を残さないようにする。fail 時は marker を残す現行 L2 recovery を維持 (真の中断と区別)。 +> +> **参照**: `src/cli-merge-pipeline/src/pipeline.rs` (post_merge_feedback step / context.json の書き出し・cleanup)、[ADR-030](adr/adr-030-deterministic-post-merge-feedback.md) (L1 floor / L2 recovery、marker 運用)、`.takt/post-merge-feedback-context.json`、#296 マージ実観測 (2026-07-19)。 +> +> **実行優先度**: 🚀 Tier 1 — Severity Medium (連続マージで後発 PR の再発防止分析が構造的に skip される。今回は手動 recovery で救済したが、気付かなければ feedback が静かに欠落) / Frequency Low〜Medium (連続マージ運用時) / Effort S (成功時 cleanup の追加)。 + +#### 作業計画 + +- [ ] 再現テスト: leftover context.json がある状態で 2 回目のマージ feedback が誤 bail することを固定 (base_dir 注入等)。 +- [ ] post-merge feedback の**正常完了時に context.json を削除**する (fail 時は marker を残す現行動作を維持)。 +- [ ] 本エントリ削除 + todo-summary.md 行削除。 + +#### 完了基準 + +- 連続マージ (前回 feedback 成功後 25 分以内) でも 2 回目の post-merge feedback が leftover context.json で誤 bail せず実行されること (回帰テストで seal)。 + +--- + ## 既知課題 (記録のみ、本セッションで未対応) (現時点で本ファイルへの既知課題は無し。docs/todo10.md / todo9.md 末尾を参照。) diff --git a/scripts/analyze-takt-timings.ps1 b/scripts/analyze-takt-timings.ps1 index 16c3433b..1aa6f9e1 100644 --- a/scripts/analyze-takt-timings.ps1 +++ b/scripts/analyze-takt-timings.ps1 @@ -44,7 +44,9 @@ $runCount = 0 foreach ($dir in Get-ChildItem -Directory $RunsDir) { $metaPath = Join-Path $dir.FullName "meta.json" if (-not (Test-Path $metaPath)) { continue } - $meta = Get-Content $metaPath -Raw | ConvertFrom-Json + # crashed / in-progress run の truncated・破損 meta.json は ConvertFrom-Json が throw する。 + # 1 件の破損 run で集計ループ全体を止めないよう、その run だけ skip する (下の phase 行 parse と同じ流儀)。 + try { $meta = Get-Content $metaPath -Raw | ConvertFrom-Json } catch { continue } if ($meta.piece -ne $Piece) { continue } # startTime は takt meta モデル上 Option (in-progress / クラッシュ run で欠損し得る)。 # null を ConvertTo-Utc に渡すと全集計がクラッシュするため、その run だけ skip する。