PR #442 の構造改善で時間の枠を超えて見送った提案の残り 13 件（_aws_sync_plan の _SyncContext 化・env list / keygen の長い関数・テストの補助の重複） #444

何を見つけたか

PR #442（スプリント m10a）の構造改善（cross-refactoring）は、提案のうち 4 件を適用し、13 件を PR に入れなかった。内訳は、時間の枠（budget）を超えた見送りが 12 件、締め切りまでにコミットが無かったものが 1 件である（重複として外した 1 行は数えない）。main = 54c1c27（2026-10-07）で、次の 13 件がそのまま残っている。

着手の注意:

• _aws_sync_plan の手順は改修計画の I-001 にある（入れ子の report の関数を外へ出す → aws_profiles の分岐と控えの無い分岐を抽出 → (ctx) を受けて振り分けるだけにする）。確かめるテストは tests/commands/test_env_host_import.py・test_env_sync_group.py・test_env_sync_owner.py
• tests/volume/ の 2 つの _mount_source は同じ補助の重複。まとめるなら共通の置き場（conftest.py など）へ移す

提案ごとの理由と手順は改修計画にある（I-001 と「見送った提案」の節）: #442 (comment)

どこで見つけたか

PR #442 の検査のプランの cross-refactoring。想定最大時間は 30 分で、改修計画を立てた時点で使える時間は 6.92 分だった。スプリント m10a の振り返りで、見送った提案が起票されていないことを見つけた（#310 は同じ形で PR #308 から起票したもの）。

なぜこの変更の範囲外なのか

構造改善は時間の枠の中で入る分だけを適用する。13 件は枠に入らなかった。振る舞いの不具合ではなく、#425 #397 #310 #333 の受け入れ条件のどれにも関わらない。

直さないと何が起きるか

振る舞いは変わらない。env sync の AWS の経路と env list・env keygen は、次に触る変更で読み解く手間がかかる。_aws_sync_plan だけが _SyncContext を受けない形のまま残り、#310 で揃えた sync の関数の受け方が 1 か所だけ違う。

由来

PR #442（issue #310 と同じスプリント m10a）の振り返りで見つけた。

依頼（原文）

起票の時点の受け入れ条件を、そのまま写す。下の「受け入れ条件」はこれを観測できる形へ言い換えたもの。

• 表の 13 件のそれぞれを、直す（Pull Request に入れる）か直さない（理由を本文に書く）かに分け、直したものは表の兆候が消えている
• 直しても本番の振る舞い（env のコマンドと TUI、snapshot restore、up の起動の後の処理の出力・終了コード・書き込み）は変わらない。既存のテストが手を入れずに通るか、テストを直したときは理由を本文に書く
• 全体のテスト（env -u DEVBASE_ROOT uv run --locked pytest tests/ -q）と CI と同じ lint が通る

目的

• PR スプリント m10a #442 の構造改善で時間の枠に入らなかった提案を片付け、env sync の AWS の経路・env list・env keygen などを、次に触る変更で読み解ける大きさにする
• sync の関数の受け方を _SyncContext に揃え、PR #308 の構造改善で時間の枠を超えて見送った提案の残り 14 件（env sync の同期関数の引数の束ね・grouped 判定の重複・TUI テストの内部依存） #310 で揃えた形の例外を無くす

前提

• 前提 1: 「13 件」は改修計画（PR スプリント m10a #442 のコメント）の「見送った提案」の行のうち、重複として外した 1 行を除いた 13 行で、1 件は「対象の関数 × 兆候」の組である。起票の表は 11 行だが、cmd_env_list と _mask_secret_environment が兆候を 2 つ持つため 13 件になる。下の「提案の一覧」の R1〜R13 がその 13 件である
• 前提 2: 「兆候が消えている」は、兆候ごとに下の「兆候が消えたと見なす基準」で判定する。基準の数値は、この課題で決めた値である（NDF の構造改善に兆候ごとの決まった閾値は無い）。設計で基準を変えるときは、変えた事実と理由を本文に残す
• 前提 3: 行数は def の行から関数の最後の行までを数える（docstring を含む）。認知的複雑度は complexipy、循環的複雑度は ruff の C901（McCabe）の値を使う。現状の値は main = 54c1c27 で測った
• 前提 4: 長い関数から抜き出した関数も、同じ基準（行数・認知的複雑度）を満たす。抜き出した先へ長さを移しただけのものは、兆候が消えたと見なさない
• 前提 5: R2（group_attrs の duplication）の重複の相手は、lib/devbase/commands/env.py#_target_group の --group の名前の検証（openbao.storage_group(group) を通し、通らなければ「--group に使えない名前です: …」を出す）である。提案の時点の記録に相手が書かれていないため、要求の時点でコードから特定した
• 前提 6: tests/volume/test_compose.py にも _write_compose・_load_scaled があるが、引数の形が違い、表に無い。この課題では扱わない
• 前提 7: 直さないと決めた件は、その件の行に「直さない」と理由を本文（Pull Request の本文か、この課題の本文）に書く。理由の無い「直さない」は受け入れない

対象範囲

含む:

• 提案の一覧の R1〜R13 の、直すか直さないかの判断と、直すものの構造の変更
• 構造の変更に合わせた、関数の呼び出し元の書き換え（同じモジュールの中と、R2 の _target_group）
• テストの補助を tests/volume/ の共通の置き場へ移すこと（R11・R12）

含まない:

• 本番の振る舞いの変更（出力の文言・終了コード・置き場やファイルへの書き込み・ログの文言）
• 表に無い関数の構造改善（SnapshotManager._backup_before_restore・tests/volume/test_compose.py の補助など、測ると値が高いものも含めない）
• 公開のコマンドの引数・オプションの変更
• CHANGELOG.md の記入（利用者に見える変更が無いため。AGENTS.md の Pull Request の節）

提案の一覧

R1 は改修計画の not_done の行（I-001）で、手順 4 の「(ctx) を受けて振り分けるだけにする」を含む。R11 と R12 は同じ補助の重複だが、改修計画では 2 行に分かれているため 2 件に数え、それぞれ判定する。

兆候が消えたと見なす基準

ドメインイベント

受け入れ条件

• R1〜R13 の 13 件のそれぞれが「直す」か「直さない」に分かれ、「直さない」の件には理由が本文に書かれている
• 「直す」とした件は、「兆候が消えたと見なす基準」の該当の行を満たす。基準の値を測ったコマンドと結果が Pull Request の本文にある
• 直した関数から抜き出した関数も、long_method の基準（50 行以下・認知的複雑度 15 以下）を満たす
• env sync（AWS の経路）・env list・env keygen・env の TUI のグループの選択・snapshot restore・up の起動の後の処理（post-start）の、標準出力・標準エラー・終了コード・ファイルと置き場への書き込みが変更の前と同じである。既存のテストが手を入れずに通ることで確かめる
• R11・R12 のテストの補助の移動を除き、tests/ の既存のテストの期待値（assert の中身）を変えていない。変えたときは、変えたテストと理由が Pull Request の本文にある
• --group に使えない名前を渡したときの文（CLI の --group に使えない名前です: … と TUI で選択へ戻る前のエラーの行）が変更の前と同じである
• compose のスケールで作るファイル（.docker-compose.scale.yml）で、機密のキーの値が書かれず、非機密の値が残る振る舞いが変わらない（tests/volume/test_compose_secret_env.py が手を入れずに通る）
• 全体のテスト（env -u DEVBASE_ROOT uv run --locked pytest tests/ -q）が通る
• CI と同じ lint（uvx ruff check --select=E9,F63,F7,F82 lib）と固有の語の検査（python3 .github/scripts/proper_term_check.py）が通る
• 表に無い関数（「含まない」に挙げたもの）を変えていない

非機能の条件

影響

検証手段

前提とする取り決め

境界

未決

進行

モード: —

• 要求と受け入れ条件 — 2026-10-08 01:33
• 作業場所の用意 — 2026-10-08 17:03
• 設計 — 2026-10-08 01:37
• 素材の収集と出典の確定
• ドキュメント再構成
• ドキュメントレビュー
• 計画 — 2026-10-08 17:02
• 実装 — 2026-10-08 17:03
• 構造改善 — 2026-10-08 17:46
• 実装レビュー — 2026-10-08 18:05
• 完了判定 — 2026-10-08 17:25
• Pull Request — 2026-10-08 17:27
• 確定仕様化 — 2026-10-08 23:36
• 後片付け
• 配布 — 2026-10-08 23:44
• 体裁レビュー
• リリース後テスト — 2026-10-08 23:44
• 振り返り — 2026-10-08 23:44
• 棚卸し — 2026-10-08 23:48

振り返り: #450 (comment)