docs(PLAN55): devbase up の機密の注入を 1 回にし、サーバ backend の往復を設計の想定へ収める要求仕様と設計 (#168)

[takemi-ohama]

Summary

#168 の設計 Pull Request。実装は含まない（設計 PR のマージ後に実装用の作業ツリーで行う）。

• 要求仕様: issues/PLAN55_up-single-injection.md（受け入れ条件 7 件、非機能 2 項目、未決 1 件は設計で決定）
• 設計文書: issues/PLAN55_up-single-injection-design.md（機能 3 件、構成要素 10 件、決定 4 件、テスト設計 8 行、未確認 2 件）
• モード: standard（devbase up の起動経路の振る舞い変更。公開インタフェースは変えない）
• 関連: devbase up が機密を 2 度注入し、サーバ backend では HTTP 往復が設計の想定の 2 倍になる #168（自動で閉じない）、docs/specifications/secret-backend.md「OpenBao との契約」、PLAN54 (base イメージに OpenBao の CLI（bao）を入れ、起動中のコンテナから機密を取得・変更できるようにする #169) との順序は設計の「未確認のまま残ること」に記載

決めたこと

issues/PLAN55_up-single-injection-design.md

• 決定 1: 注入の回数ではなく SecretStore の寿命を変える
• 決定 2: 控えの置き場は runtime モジュールに置き、_dispatch_lifecycle の finally で捨てる
• 決定 3: TUI は操作の入口で控えを捨て、操作ごとに現物を読む
• 決定 4: _ensure_env_files の存在判定の意味は変えない
• 決定 5: 子プロセスの env init がストアへ書いたら、控えを捨てて読み直す

Test plan

設計の段階で確かめたこと:

• 現状の往復の数え上げ（up <name> の経路で SecretStore が作られる 4 か所と、それぞれの認証・GET。lib/devbase/cli.py / commands/container.py / env/openbao.py を読んだ）
• OpenBaoBackend._seen が同じインスタンスの中で exists → load の 2 度取りを防いでいること（env/openbao.py load() / exists()、tests/env/test_openbao.py::test_load_is_fetched_once_per_store_instance）
• _dispatch_lifecycle の finally に docker_context.reset() があり、同じ場所へ release_store() を並べられること
• ドキュメント再構成の前後: 設計文書 平均文長 51.9 → 45.3 字 / 最長文 185 → 89 字 / 行数 221 → 229 / 章 8 → 8 / 結論の位置 5 行目（変更なし）。目安を超えた項目: 「決定の記録」43 行（目安 40）。理由: 4 件の決定を 1 節に集める形を保った
• 仕様: 平均文長 67.4 字 / 最長文 229 字（引用した issue 本文と「前提・操作・結果」の 1 項目を分けないため）

🤖 Generated with Claude Code

https://claude.ai/code/session_01S9okWVz1S7VGUsCQWVMhb3

[takemi-ohama]

🤖 cross-review | round 1 | kiro | APPROVE

設計・要求仕様ともにコードと整合していることを確認した。修正を要する指摘は無い。

検証した主な整合点:

• _seen による exists→load の 2 度取り防止（lib/devbase/env/openbao.py:347-368 の load()/exists()）と、docs/specifications/secret-backend.md:164-185「OpenBao との契約」の記述が一致。
• _dispatch_lifecycle の finally に docker_context.reset() があり release_store() を並べられる（lib/devbase/commands/container.py:500-565）。決定 2 の「入口で捨てない」根拠（CLI では _load_secret_env の store を捨て認証が 2 回に戻る）も入口 reset() の存在と整合。
• 置き換え対象 SecretStore(devbase_root) は _ensure_env_files（container.py:1308）の 1 箇所のみで、設計の構成要素表と一致。
• runtime.resolve/inject/child_env は既に store=None の kwarg を持ち、設計の「引数の形は変えない・None 時に store_for を使う」と矛盾しない（runtime.py:138,255,284）。
• 新設予定の store_for/release_store は未実装（"足す" と整合）。参照テスト（tests/env/test_openbao.py::test_load_is_fetched_once_per_store_instance、tests/cli/・tests/commands/ 各ファイル）と FakeOpenBao（.logins / requests_of('GET') / Received.kv_path）は実在し、テスト設計が成立する。

[takemi-ohama]

🤖 cross-review | round 1 | agy | REQUEST_CHANGES

要求仕様書（issues/PLAN55_up-single-injection.md）内の対象範囲の記述に、前提および設計文書（決定 4）での結論と矛盾する箇所が 1 件残存しています。インラインコメントの修正アクションに従い、記述の整合性を取ってください。

[takemi-ohama]

🔧 /ndf:fix サマリ (round 1)

対象: 未解決 thread 1 件（agy major 1 / kiro 0）。CI（55ec920 時点）: 失敗なし。

#	指摘	重要度	対応
1	PLAN55_up-single-injection.md L68 対象範囲「含む」の _ensure_env_files の記述が前提 3・決定 4 と矛盾	major	修正済み（5d94667）。「注入と同じ SecretStore（runtime.store_for）で往復を無くす。判定の意味は変えない」に改め、旧文言は取り消し線で残した。Resolve 済み

deferred / rejected: なし。設計の決定（## 決定の記録 の見出し）は変えていない。設計文書は 228 行。

🤖 Generated with Claude Code

https://claude.ai/code/session_01S9okWVz1S7VGUsCQWVMhb3

[takemi-ohama]

🤖 cross-review | round 2 | codex | REQUEST_CHANGES

初期化による書き込み後のキャッシュ更新について、修正を 1 件お願いします。

[takemi-ohama]

🤖 cross-review | round 2 | kiro | COMMENT

設計は実装（env/runtime.py の store=None フォールバック、_dispatch_lifecycle の finally の docker_context.reset()、OpenBaoBackend._seen）と整合しており、SecretStore の寿命を延ばす方針・finally での release_store() 配置は既存の docker_context パターンに揃っています。設計判断そのものへの修正提案はありません。現状分析の GET 回数の前提に 1 点だけ精度の指摘をインラインで付けました。

[takemi-ohama]

🔧 /ndf:fix サマリ (round 2)

対象: 未解決 thread 2 件（codex major 1 / kiro minor 1）。CI（5d94667 時点）: 失敗なし。

対応件数: critical=0 / major=1 / minor=1 (合計 2 件)
deferred: 0 件 / rejected: 0 件
commit: 6a69d28
CI: PENDING（push 後の再実行は待たない）

#	指摘	重要度	対応
1	design L204 env init の子プロセスが書いた後も親の _seen に空が残り、_run_deploy_pipeline が空の共通機密を使う	major	修正済み。設計に 決定 5（env init から戻ったら runtime.release_store() で控えを捨て、現物を読み直す）を追加。F4、往復表の「team/global 未作成」行（認証 2 / GET 8）、テスト設計 8、pre-up の未確認事項を足し、仕様の前提 1 の例外・前提 5・受け入れ条件 8・影響の行を揃えた。Resolve 済み
2	spec L42 _ensure_env_files の exists は 2 回固定ではない	minor	修正済み。表を「GET 1〜2（ローカル .env が無ければ 2）」、合計を「12〜14 → 11〜14」に改め、設計の処理の流れも × 1〜2 に揃えた。Resolve 済み

設計の決定の見出しを 1 つ足した（決定 5）ため、PR 本文の「決めたこと」を pr-body-decisions.sh sync で揃える。設計文書は 251 行。返信と Resolve の後の未解決 thread: 0 件。

🤖 Generated with Claude Code

https://claude.ai/code/session_01S9okWVz1S7VGUsCQWVMhb3

[takemi-ohama]

🤖 cross-review | round 3 | codex | REQUEST_CHANGES

TUI 内の機密書き込み後にも共有ストアを無効化する規則を追加してください。

[takemi-ohama]

🤖 cross-review | round 3 | agy | APPROVE

要求仕様（PLAN55）および設計文書（PLAN55-design）を精査しました。往復回数の数え上げ、runtime.store_for/release_store のライフサイクル、決定 5 による env init 実行後のキャッシュ破棄規則、テスト設計および受け入れ条件の対応関係に不整合や欠落は見当たらず、このまま実装フェーズへ進めて問題ありません。

[takemi-ohama]

🤖 cross-review | round 3 | agy | APPROVE

要求仕様書（issues/PLAN55_up-single-injection.md）および設計書（issues/PLAN55_up-single-injection-design.md）の最新コミット（6a69d28）を精査しました。

• 前提 5 および受け入れ条件 8（共通機密未作成時の env init 実行と読み直し）、設計の決定 5（env init 実行後の runtime.release_store() 呼び出し）の追加により、子プロセス書き込み時の整合性が正確に設計されています。
• _ensure_env_files でのプロジェクト側 .env 判定ロジック（ローカル .env が存在しない場合のみストアを参照する挙動）と往復数の内訳表（11〜14回、初回 8回以下等）の整合性が確認できました。
• TUI 実行時、プロジェクト切替時（api から web 等）、age バックエンド利用時、未作成時など各境界条件の設計が既存コードベース（lib/devbase/cli.py, lib/devbase/commands/container.py, lib/devbase/env/runtime.py 等）および仕様書（docs/specifications/secret-backend.md）と矛盾なく整合しています。

修正を要する問題点は認められず、このまま実装に進めて問題ありません。

[takemi-ohama]

🔧 /ndf:fix サマリ (round 3)

対象: 未解決 thread 1 件（codex major 1 / agy 0）。CI（6a69d28 時点）: 失敗なし（5 check すべて success）。

対応件数: critical=0 / major=1 / minor=0 (合計 1 件)
deferred: 0 件 / rejected: 0 件
commit: e9547f3
CI: PENDING（push 後の再実行は待たない）

#	指摘	重要度	対応
1	design L198 TUI で env edit してから最初の up を実行すると、編集は別の SecretStore と dispatch_group を通るため起動時の _seen が残り、編集前の値でコンテナが起動する	major	修正済み。決定 3 を「TUI は操作の入口で控えを捨て、操作ごとに現物を読む」に改め（旧見出しは取り消し線で残す）、tui/dispatch.py の _preserve_cwd_env の入口で runtime.release_store() を呼ぶ規則にした。F5、構成要素（tui/dispatch.py / tests/cli/tui/test_dispatch.py）、往復の表の TUI 行、テスト設計 9 と決定 3 の規則のテストを足し、仕様は前提 6・受け入れ条件 9・対象範囲・影響を揃えた。Resolve 済み

設計の決定の見出しを 1 つ変えた（決定 3）ため、PR 本文の「決めたこと」を pr-body-decisions.sh sync で揃える。設計文書は 279 行。返信と Resolve の後の未解決 thread: 0 件。

🤖 Generated with Claude Code

https://claude.ai/code/session_01S9okWVz1S7VGUsCQWVMhb3

[takemi-ohama]

🤖 cross-review | round 4 | kiro | APPROVE

設計・要求の記述と実コードを突き合わせて検証した（_dispatch_lifecycle の finally の docker_context.reset()、_preserve_cwd_env の contextmanager 構造、OpenBaoBackend._seen/fetch の 404→空記憶、_ensure_env_files の SecretStore(devbase_root)、runtime.resolve/inject/child_env の store=None 既定、_inject_secrets が明示 store を渡さないこと）。決定 1〜5・前提 1〜6・往復回数（認証4/GET 11〜14、各経路の内訳、AC #8 の認証2/GET≤8）はいずれも整合しており、参照先ファイル・テスト名も実在を確認した。修正を要する不整合・誤記・仕様矛盾は見つからなかったため、指摘なしで承認する。

[takemi-ohama]

🤖 cross-review | round 4 | agy | APPROVE

要求仕様と設計文書の間で前提・受け入れ条件・決定事項（決定 1〜5）およびテスト設計が整合しており、修正が必要な指摘事項はありません。