From 05ed5d0dbb58c92f42fe88eaa7baa4c52e25f1f8 Mon Sep 17 00:00:00 2001 From: aloekun Date: Sun, 2 Aug 2026 14:36:41 +0900 Subject: [PATCH] =?UTF-8?q?docs(todo):=20WP-16=20=E7=B3=BB=20post-merge=20?= =?UTF-8?q?feedback=20=E6=8E=A1=E7=94=A8=205=20=E4=BB=B6=E3=82=92=20todo14?= =?UTF-8?q?=20=E3=81=AB=E7=99=BB=E9=8C=B2=20(=E9=A0=86=E4=BD=8D=20359-363)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR #342/#343/#344 の post-merge feedback 採用候補 14 件のうち、2026-08-02 の 方針決定 (文書系 10 件 = 1 docs バッチ PR、実装系 4 件 = A/B 系統別 PR) に従い 5 エントリとして登録: - 順位 359: 文書系 10 件の docs バッチ (dev-conventions 集中、Severity High 2 件含む) - 順位 360: cargo test コマンド等価性検証テスト (#342/#343 で連続指摘 = Frequency High) - 順位 361: JJ_VERSION の 2 ファイル一致検証テスト (順位 360 と同一 PR 可) - 順位 362: git subprocess ブランチ名依存引数の custom lint rule (#343 incident 由来) - 順位 363: check-ci-coderabbit の detached HEAD 回帰統合テスト (順位 362 と同一 PR 可) --- docs/todo-summary2.md | 5 ++ docs/todo14.md | 121 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 126 insertions(+) diff --git a/docs/todo-summary2.md b/docs/todo-summary2.md index ccad82a7..15a6bf29 100644 --- a/docs/todo-summary2.md +++ b/docs/todo-summary2.md @@ -114,6 +114,11 @@ | 356 | 🔧 Tier 2 | **weekly/monthly staleness 判定の共通 fixture parametrized test を追加 (#331 post-merge feedback T2-1 採用)** | todo14.md | S | なし (monthly_review.rs の staleness 判定が weekly_review.rs と逐語重複、片方修正で挙動乖離するリスク。同一 fixture〔threshold 境界/Missing/Stale/Unreadable/未来値/main-root canonical〕で両流路を検証、inline test module に配置) | | 357 | 🔧 Tier 2 | **CLAUDE.md の ADR index ステータスタグと ADR 本体の整合チェックを追加 (#340 post-merge feedback T1-1 採用)** | todo14.md | M | なし (ADR-047 の index タグが `試験運用` のまま本体の `却下` と乖離した実害が残存。ADR-007 の 2 層は単一ファイル起点のため独立 doc-consistency チェックとして実装。責務はステータスタグ整合のみで採番/索引存在/番号一致は順位 272、実装は同一 module 同居可。着手時に ADR-047 タグ即修正を含む) | | 358 | 💎 Tier 3 | **Cross-File Reference Lifecycle (ephemeral→permanent 移行手順) を dev-conventions.md に明文化 (#340 post-merge feedback T3-1 採用)** | todo14.md | S | なし (PR #340 で移管先未記載 3 件を CodeRabbit が指摘。順位 261 の見送り限定 convention を完了/委譲ケースへ拡張し、退役条件を含む 3 段階プロトコルを checklist 化) | +| 359 | 💎 Tier 3 | **WP-16 系 post-merge feedback 文書系 10 件の docs バッチ (dev-conventions 集中、#342/#343/#344 採用)** | todo14.md | M | なし (2026-08-02 方針決定: 文書系 10 件を 1 PR に集約。paths×required-check gotcha / exe-spawn staging 規約の Severity High 2 件を含むため早めが望ましい) | +| 360 | 🔧 Tier 2 | **push-runner と ci.yml の cargo test コマンド等価性検証テスト (#342/#343 post-merge feedback 採用)** | todo14.md | S | なし (連続 2 PR で独立指摘 = Frequency High。`[workspace] default-members` 不在への暗黙依存を機械検証。順位 361 と同一 PR 可) | +| 361 | 🔧 Tier 2 | **JJ_VERSION の ci.yml / cloud-setup.sh 一致検証テスト (#342 post-merge feedback 採用)** | todo14.md | S | なし (ADR-051 型の 2 ファイル結合「上げるときは必ず揃える」を機械検証へ。順位 360 と同一 PR 可) | +| 362 | 🔧 Tier 2 | **git subprocess のブランチ名依存引数を検出する custom lint rule (#343 post-merge feedback 採用)** | todo14.md | S | なし (detached HEAD で CI 観測が silent pending 化した PR #343 incident 由来。ADR-049 fixture 3 点セット整備込み。順位 363 と同一 PR 可) | +| 363 | 🔧 Tier 2 | **check-ci-coderabbit の detached HEAD 回帰統合テスト (#343 post-merge feedback 採用)** | todo14.md | M | なし (修正済み silent pending バグの regression test が皆無。順位 362 と同一 PR 可) | **戦略**: 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/todo14.md b/docs/todo14.md index c543a107..3d765758 100644 --- a/docs/todo14.md +++ b/docs/todo14.md @@ -669,3 +669,124 @@ #### 完了基準 - ephemeral 計画文書の完了/委譲/見送りいずれのケースでも、永続移管先の明記と参照方向の規律が checklist で確認できること。 + +--- + +### WP-16 系 post-merge feedback 文書系 10 件の docs バッチ (dev-conventions 集中) + +> **動機**: PR #342 (CI matrix / ADR-065)・#343 (監視 CI 観測修正)・#344 (pipeline_lock レース修正) の post-merge feedback で採用確定した文書系 10 件を、1 本の docs バッチ PR に集約する (2026-08-02 方針決定。per-PR の細切れ doc PR を避け milestone でまとめる運用)。全件 `docs/dev-conventions.md` 中心の追記で、GitHub 仕様の gotcha など Severity High 2 件を含む。 +> +> **内容 (10 件)**: +> +> 1. `[workspace] default-members` 不在で `cargo test` = `cargo test --workspace` という暗黙不変条件の明記 + `push-runner-config.toml` への inline comment (#342 T3-1。順位 360 のテストと対) +> 2. ADR-051 (cross-system config coupling) をチェックリストに登録 — 3 系統以上のインフラ設定を跨ぐ変更時の確認項目 (#342 T3-3) +> 3. ambient/auto-detect 環境状態 (git ブランチ名・`GH_REPO`・cwd) に依存せず明示引数を使う設計原則 — PR #238/#247/#343 の 3 例目で systemic (#343 T3-1) +> 4. 並行バグ調査の標準テストパターン — 決定論再現テスト + stress の aggregate 計測 + low-core CI でのみ再現するレースの扱い (#344 T2-1) +> 5. TOCTOU + 2 層防御 (verify-before-destroy + deferred cleanup、最終 fallback は `create_new` 排他へ収束) の設計原則 (#344 T3-1) +> 6. CI 失敗の introduced-by-this-change / pre-existing を diff で切り分けるチェックリスト (#344 T3-2) +> 7. `paths:` フィルタ付き check を required 化すると skip が pending 扱いで PR が永久ブロックされる GitHub gotcha + early-success 代替 (#342 T3-2、Severity High) +> 8. exe-spawn テストは exe + deploy 済 config を temp dir へ staging する規約 — 既存 bounded wait 規約と対 (#342 T3-4、Severity High) +> 9. cross-platform matrix の `fail-fast: false` 既定 (#342 T3-5) +> 10. shell 抽象化確認済み cfg ガードの除去可否ガイダンス + レビュー層がコード内コメント根拠で false positive 判定する際の前提再検証手順 (#342 T3-7) +> +> **参照**: `.claude/feedback-reports/342.md` / `343.md` / `344.md` (各 Rationale)、[ADR-065](adr/adr-065-ci-matrix-cross-os-regression.md)、[ADR-051](adr/adr-051-cross-system-config-coupling.md)、[ADR-063](adr/adr-063-linux-portability-release-binaries.md)。 +> +> **実行優先度**: 💎 Tier 3 — 各件 Effort XS〜S・合計 M / Adoption Risk None。Severity High 2 件 (#7, #8) を含むため docs バッチとしては早めの実施が望ましい。 + +#### 作業計画 + +- [ ] `docs/dev-conventions.md` へ 10 件を追記 (既存 convention の書式に合わせる) +- [ ] `push-runner-config.toml` へ #1 対応の inline comment を追加 +- [ ] 本エントリ削除 + todo-summary2.md 行削除 + +#### 完了基準 + +- 10 件すべてが dev-conventions.md (+ inline comment 1 箇所) に反映され、`pnpm lint:docs` / markdownlint が clean であること。 + +--- + +### push-runner と ci.yml の cargo test コマンド等価性検証テスト + +> **動機**: `push-runner-config.toml` の rust-test group は `cargo test`、`.github/workflows/ci.yml` は `cargo test --workspace` を使い、両者は root `Cargo.toml` に `[workspace] default-members` が**無い**ことに依存して偶然等価になっている。ADR-065 § 決定 2 は「CI とローカルでコマンドが違うと、どちらかの緑が嘘になる」を設計原則とするが、この等価は機械検証されていない。#342 T2-1 と #343 T2-3 が連続 2 PR で独立に指摘し Frequency High。 +> +> **対処案**: `Cargo.toml` に `default-members` が導入されたら fail する検証テストを追加する (例: cargo metadata で default-members 不在を assert、または両コマンドの対象 crate 集合の一致を比較)。実装位置は `src/cli-push-runner` の config 検証テスト近傍が候補。 +> +> **参照**: `.claude/feedback-reports/342.md` Tier2 #1 / `.claude/feedback-reports/343.md` Tier2 #3、`push-runner-config.toml` (rust-test group)、[ADR-065](adr/adr-065-ci-matrix-cross-os-regression.md) § 決定 2。順位 359 の #1 (文書化) と対。順位 361 と同一 PR (A 系統) にまとめてよい。 +> +> **実行優先度**: 🔧 Tier 2 — Severity Medium / Frequency High / Effort S / Adoption Risk None。 + +#### 作業計画 + +- [ ] default-members 不在 (または両コマンドの対象集合一致) を assert する検証テストを追加 +- [ ] 意図的に default-members を足した状態で fail することを確認 +- [ ] 本エントリ削除 + todo-summary2.md 行削除 + +#### 完了基準 + +- `cargo test` (push-runner) と `cargo test --workspace` (CI) の等価が破れる変更が、テスト失敗として land 前に検出されること。 + +--- + +### JJ_VERSION の ci.yml / cloud-setup.sh 一致検証テスト + +> **動機**: jj バージョン (0.42.0) は `.github/workflows/ci.yml` と `scripts/cloud-setup.sh` の 2 ファイル + ローカル検証環境の 3 箇所論理結合 (ADR-065 § 決定 3、ADR-051 型)。「上げるときは必ず揃える」の手動運用に依存しており、片方だけの更新は「テストが緑でも本番挙動が違う」を生む。#342 T2-2 採用 (supervisor 補正: 版文字列を持つのは 2 ファイルのみ、3 箇所目 = ローカル環境は静的検出不可)。 +> +> **対処案**: 2 ファイルから jj 版文字列を抽出して一致を assert するテストを追加する (repo-root `tests/` の配備検証系 or CI step)。 +> +> **参照**: `.claude/feedback-reports/342.md` Tier2 #2、[ADR-065](adr/adr-065-ci-matrix-cross-os-regression.md) § 決定 3、[ADR-051](adr/adr-051-cross-system-config-coupling.md)。順位 360 と同一 PR (A 系統) にまとめてよい。 +> +> **実行優先度**: 🔧 Tier 2 — Severity Medium / Frequency Medium / Effort S / Adoption Risk None。 + +#### 作業計画 + +- [ ] 2 ファイルの版文字列一致を assert するテスト/step を追加 +- [ ] 片方だけ変更した状態で fail することを確認 +- [ ] 本エントリ削除 + todo-summary2.md 行削除 + +#### 完了基準 + +- ci.yml と cloud-setup.sh の jj 版が乖離した変更が land 前に機械検出されること。 + +--- + +### git subprocess のブランチ名依存引数を検出する custom lint rule + +> **動機**: PR #343 で、exe 内部の `git branch --show-current` subprocess が jj colocated 環境 (git HEAD が detached) で常に空文字を返し、CI 観測が恒久 pending 化する silent 欠陥が実在した。PreToolUse hook は Claude の tool 呼び出し層にのみ効き exe 内部の subprocess には無効なため、`src/**/*.rs` を対象とする custom lint rule (正規表現層、ADR-007) で同型再発を防ぐ。#343 T1-1 採用 (supervisor が PreToolUse 案から再構成済み)。 +> +> **対処案**: `.claude/custom-lint-rules.toml` に new rule — git subprocess 呼び出しのブランチ名依存引数 (`branch` + `--show-current` 等) を検出する。ADR-049 に従い incident fixture (bad/good) + `[rules.incident]` provenance (pr = 343) + incident_eval CASES entry を整備する。 +> +> **参照**: `.claude/feedback-reports/343.md` Tier1 #1、[ADR-007](adr/adr-007-custom-linter-layer-boundary.md)、[ADR-049](adr/adr-049-incident-eval-regression-suite.md)、[ADR-064](adr/adr-064-monitor-success-positive-evidence.md) Amendment (欠測と正常が同じ出力になる構成の教訓)。順位 363 と同一 PR (B 系統) にまとめてよい。 +> +> **実行優先度**: 🔧 Tier 2 — Severity Medium / Frequency Low / Effort S / Adoption Risk None。 + +#### 作業計画 + +- [ ] custom-lint-rules.toml に rule を追加 (regex + 除外条件の設計) +- [ ] ADR-049 の 3 点セット (bad/good fixture + `[rules.incident]` + CASES entry) を整備 +- [ ] 本エントリ削除 + todo-summary2.md 行削除 + +#### 完了基準 + +- `src/**/*.rs` にブランチ名依存の git subprocess が追加された場合に custom lint が発火し、good fixture では発火しないこと (incident_eval で回帰保証)。 + +--- + +### check-ci-coderabbit の detached HEAD 回帰統合テスト + +> **動機**: PR #343 で修正した「jj colocated (detached HEAD) 環境で CI 状態が恒久 pending 化する」バグの regression test が皆無 (`src/check-ci-coderabbit/tests/` 自体が不在)。再発時は監視の自律ループが再び silent に破綻する。#343 T2-1 採用。 +> +> **対処案**: temp dir に jj colocated repo (detached HEAD) を組み、CI 状態解決が statusCheckRollup ベースで機能すること (旧経路のようにブランチ名解決依存で空にならないこと) を検証する統合テストを新設する。gh 呼び出しは実 API に依存しない形 (parse 層の既存単体テスト + 経路の構造検証) を基本とし、実 jj spawn が必要な部分は lib-jj-helpers の `#[ignore]` + 直列実行パターンを踏襲する。 +> +> **参照**: `.claude/feedback-reports/343.md` Tier2 #1、`src/check-ci-coderabbit/src/main.rs` (`fetch_ci`) / `src/check-ci-coderabbit/src/parsers.rs` (`parse_ci_rollup` 単体テスト群 = 既存資産)。順位 362 と同一 PR (B 系統) にまとめてよい。 +> +> **実行優先度**: 🔧 Tier 2 — Severity Medium / Frequency Low / Effort M / Adoption Risk None。 + +#### 作業計画 + +- [ ] detached HEAD 環境での CI 状態解決を検証する統合テストを新設 +- [ ] ブランチ名依存の旧経路への回帰が fail することを確認 +- [ ] 本エントリ削除 + todo-summary2.md 行削除 + +#### 完了基準 + +- detached HEAD 環境で CI 状態が pending に固着する回帰が、テスト失敗として land 前に検出されること。