設計(PLAN68): スナップショットの世代をボリュームの組ごとの系列で持つ (#248)

[takemi-ohama]

Summary

• スナップショットの世代がグループを跨ぐたびに増え、3 世代の保持枠を奪い合う（同じグループの履歴が短くなる） #248（スナップショットの世代がグループを跨ぐたびに増え、3 世代の保持枠を奪い合う）の要求と受け入れ条件、および設計だけを載せた Pull Request です。実装は含みません
• 要求と受け入れ条件: issues/PLAN68_snapshot-series.md
• 設計: issues/PLAN68_snapshot-series-design.md
• ワークフローモード: standard。この Pull Request をマージしてから実装へ進みます
• 設計中に範囲外と判断したもの: snapshot restore の復元前バックアップが、復元する世代ではなく実行した場所のグループのボリュームを控える #255 / snapshot-guide が copy・名前付きの世代をローテーションから守ると書き、create が差分を積むと書く #256
• Refs スナップショットの世代がグループを跨ぐたびに増え、3 世代の保持枠を奪い合う（同じグループの履歴が短くなる） #248

決めたこと

issues/PLAN68_snapshot-series-design.md

• 決定 1: 保持は系列ごとに数え、全体の上限を併せて持つ。全体の上限の既定は keep × 3 とし、各系列の最新の世代は上限でも消さない
• 決定 2: 差分は系列の最新の世代へ積む。間に別グループの起動を挟んでも積み直す
• 決定 3: 文言には系列のグループ名と理由を添える。直前の世代を作ったプロジェクトは添えない
• 決定 4: 自動スナップショットの最小間隔を、系列ごとに判定する
• 決定 5: 系列は保存せず、snapshot.yml のエントリの volumes から導く
• 決定 6: --keep の意味を系列ごとへ変え、全体の上限は --max-total で指定する
• 決定 7: ローテーションは、消す前に世代の場所を _safe_snap_dir で検証する。_safe_snap_dir の包含判定はパスの要素の単位にする

Test plan

• 現行コード（lib/devbase/snapshot/manager.py の should_start_new_generation / rotate / last_snapshot_time、commands/container.py の _auto_snapshot、cmd_down、commands/snapshot.py、cli.py、tui/actions_snapshot.py）の呼び出し元を grep -rn で洗い出し、構成要素の表と突き合わせた

• この端末の backups/snapshot.yml（3 エントリ: default 2・with 1）を読み、設計の「例」の表と受け入れ条件 22 の前提に使った

• 設計文書の内部の突き合わせ（受け入れ条件 28 件 ↔ テスト設計、構成要素 ↔ 処理の流れの図、決定で退けた案が他の節に残っていないこと）

• 文書の測定: 平均文長 要求 38.0 字 / 設計 36.5 字、最長文 要求 142 字（受け入れ条件 1 の前提・操作・結果の 3 行を 1 文と数えたもの）/ 設計 95 字

• /ndf:cross-review 6 ラウンド（codex / agy / kiro / claude）で収束。指摘 17 件をすべて反映し、未解決の指摘 0 件（state.py verify-sweep exit=0）

🤖 Generated with Claude Code

[takemi-ohama]

🤖 cross-review | round 1 | codex | REQUEST_CHANGES

修正指摘3件（major 1件、minor 2件）。

[takemi-ohama]

🤖 cross-review | round 1 | agy | APPROVE

要求仕様書および設計書の内容を精査し、既存コード・テスト・ドキュメントとの整合性を確認しました。修正を要する問題はありません。

[takemi-ohama]

🔧 /ndf:fix サマリ | round 1 | commit e16e442

対応件数: critical=0 / major=1 / minor=2（合計 3 件）
決着: 3 件 / 見送り: 0 件 / 却下: 0 件
CI: SUCCESS

[takemi-ohama]

🤖 cross-review | round 2 | agy | APPROVE

要件・設計・テスト設計および既存コード・文書との整合性が確認され、指摘事項はありません。

[takemi-ohama]

🤖 cross-review | round 2 | kiro | REQUEST_CHANGES

設計・要求の内部整合性と現行コードの前提はおおむね一致している。決定 7 で _safe_snap_dir の包含判定を Path.is_relative_to へ変える結果、rotate だけでなく create / restore / copy / delete の 5 操作で backups/ 外を指すシンボリックリンクの世代が SnapshotError で拒否される挙動変化が生じるが、受け入れ条件 21（CHANGELOG）と対象範囲の記述は --keep の意味変更しか挙げていない。この横断的な挙動変化を CHANGELOG／受け入れ条件へ明示することを推奨する。

[takemi-ohama]

🔧 /ndf:fix サマリ | commit 1aac0e4

対応件数: critical=0 / major=0 / minor=1（合計 1 件）
決着: 1 件 / 見送り: 0 件 / 却下: 0 件
CI: SUCCESS

[takemi-ohama]

🤖 cross-review | round 3 | claude | REQUEST_CHANGES

PLAN68 の設計は概ね実装可能な粒度だが、テスト設計の 1 行が --max-total の受け渡しを検出できず、世代の場所の検証が backups/ 内を指すシンボリックリンクを扱っていない。決定 6 の互換性の主張と、文書の変更表・受け入れ条件 20 の食い違いも直す。

[takemi-ohama]

🤖 cross-review | round 3 | kiro | APPROVE

docs-only PR (issues/PLAN68_*)。要求と設計の内部整合、および現行コードとの記述整合を確認した。rotate アルゴリズムを受け入れ条件 10・11・12 で追跡したところ一致し、参照ファイル・test_auto_snapshot.py の last_snapshot_time 5 件・devbase_home_ 命名・snapshot list の対象ボリューム列などの断定も現行コードと一致した。修正を要する指摘は無い。

[takemi-ohama]

🔧 /ndf:fix サマリ | commit ae6c933

対応件数: critical=0 / major=0 / minor=4（合計 4 件）
決着: 4 件 / 見送り: 0 件 / 却下: 0 件
CI: SUCCESS

[takemi-ohama]

🤖 cross-review | round 4 | claude | REQUEST_CHANGES

設計の方針に異論は無い。直すところは 4 つある。系列の最新の世代が自動では消えなくなることを利用者向けの文書に書くこと、ガイドのベストプラクティスとの食い違いを解くこと、status の「最新」の意味を決めること、TUI から rotate を呼ぶときの max_total の既定を決めること。

[takemi-ohama]

🤖 cross-review | round 4 | codex | REQUEST_CHANGES

修正が必要な指摘は minor 1 件です。

[takemi-ohama]

🔧 /ndf:fix サマリ | round 4 | commit 2ef28a6

対応件数: critical=0 / major=1 / minor=4（合計 5 件）
決着: 5 件 / 見送り: 0 件 / 却下: 0 件
CI: SUCCESS

[takemi-ohama]

🤖 cross-review | round 5 | codex | REQUEST_CHANGES

手動検証の再現条件に修正が必要です。

[takemi-ohama]

🤖 cross-review | round 5 | agy | REQUEST_CHANGES

設計の決定 7 および受け入れ条件 21・26 で改訂されたシンボリックリンク世代の拒否仕様（内部を指すリンクも拒否対象であること、および rotate は止まらず警告してエントリを外すこと）と、概要表・ログ文言定義との間に残っている不整合の解消を提案します。

[takemi-ohama]

🔧 /ndf:fix サマリ | round 5 | commit f5411e4

対応件数: critical=0 / major=1 / minor=2（合計 3 件）
決着: 3 件 / 見送り: 0 件 / 却下: 0 件
CI: SUCCESS

[takemi-ohama]

🤖 cross-review | round 6 | agy | APPROVE

指摘事項はありません。要求仕様および設計仕様の整合性を確認しました。

[takemi-ohama]

🤖 cross-review | round 6 | kiro | COMMENT

設計・受け入れ条件ともコード実体（rotate が _safe_snap_dir を通さず shutil.rmtree する現状、_safe_snap_dir の文字列前方一致、should_start_new_generation の snapshots[-1] 依存、_auto_snapshot の list()[-1] / 引数なし last_snapshot_time、既存 docs の記述）と整合しており、系列ローテーションのフロー（受け入れ 8〜13）も内部的に一貫している。指摘は 1 件のみ。決定 7 が create/restore/copy の挙動変更（シンボリックリンクの世代を SnapshotError で止める）を明記しているのに、受け入れ条件がその検証を delete(27)・rotate(26) にしか置いていない点だけ、受け入れ条件側で塞ぐことを勧める。

[takemi-ohama]

🔧 /ndf:fix サマリ | commit bd44ad7

対応件数: critical=0 / major=0 / minor=1（合計 1 件）
決着: 1 件 / 見送り: 0 件 / 却下: 0 件
CI: SUCCESS