[takemi-ohama]

スプリント m7a の課題を main へ取り込む。

関連: #357 #215 #224 #371 #334

利用者向けの変化

• スプリント m7a の課題を main へ取り込む。

課題と設計

• 課題: 同じアカウントグループのコンテナを同時に起動すると entrypoint の symlink 作成が競合して 1 つが落ちる #357 plugin-yml-reference の requires 契機表を正本にし、新機能 PR で 1 行足す手順を PR テンプレートへ入れる #215 devbase scale で増やしたインスタンスに _report_missing_repos / _apply_window_titles が行われない #224 up でコンテナが 1 台でも落ちると、起きているコンテナにも起動の後の処理（window.title・token・エディタ）が行われない #371 env init の AWS の方法 3 が取り込みの方針によらず AWS_DEFAULT_REGION をホストから書く #334
• 無し

コミット

• fix(entrypoint): 同時起動でもリンクの段が失敗しないようにする (同じアカウントグループのコンテナを同時に起動すると entrypoint の symlink 作成が競合して 1 つが落ちる #357)
• docs(plugin-dev): quickstart のアカウントグループを宣言必須の書き方へ直す (plugin-yml-reference の requires 契機表を正本にし、新機能 PR で 1 行足す手順を PR テンプレートへ入れる #215)
• docs(plugin-dev): requires の契機表を正本にし、PR テンプレートへ 1 行足す手順を入れる (plugin-yml-reference の requires 契機表を正本にし、新機能 PR で 1 行足す手順を PR テンプレートへ入れる #215)
• Merge pull request #215 を実装する（スプリント m7a） #377 from devbasex/feat/issue-215-m7a
• fix(up): 起動の待ちで 1 台が落ちても残りを待ち、起動の結果を例外で返す (devbase scale で増やしたインスタンスに _report_missing_repos / _apply_window_titles が行われない #224 up でコンテナが 1 台でも落ちると、起きているコンテナにも起動の後の処理（window.title・token・エディタ）が行われない #371)
• fix(up,scale): 起動の後の処理を 1 つの段にまとめ、起動できたインスタンスへ届ける (devbase scale で増やしたインスタンスに _report_missing_repos / _apply_window_titles が行われない #224 up でコンテナが 1 台でも落ちると、起きているコンテナにも起動の後の処理（window.title・token・エディタ）が行われない #371)
• feat(project): project post-start を登録する (up でコンテナが 1 台でも落ちると、起きているコンテナにも起動の後の処理（window.title・token・エディタ）が行われない #371)
• docs: scale の後処理・起動できなかったときの扱い・project post-start を書く (devbase scale で増やしたインスタンスに _report_missing_repos / _apply_window_titles が行われない #224 up でコンテナが 1 台でも落ちると、起きているコンテナにも起動の後の処理（window.title・token・エディタ）が行われない #371)
• Merge pull request #224 #371 を実装する（スプリント m7a） #378 from devbasex/feat/issue-224-m7a
• fix(env): AWS の region と GCP の正規化の警告を取り込みの方針に従わせる (env init の AWS の方法 3 が取り込みの方針によらず AWS_DEFAULT_REGION をホストから書く #334)
• test(env): AWS の region と GCP の警告の回数を方針ごとに縛る (env init の AWS の方法 3 が取り込みの方針によらず AWS_DEFAULT_REGION をホストから書く #334)
• docs: AWS の region と GCP の正規化の警告が取り込みの方針に従うことを書く (env init の AWS の方法 3 が取り込みの方針によらず AWS_DEFAULT_REGION をホストから書く #334)
• Merge pull request #334 を実装する（スプリント m7a） #379 from devbasex/feat/issue-334-m7a
• test(entrypoint): 同時起動のテストの所要を減らし、性能の比較を並列の負荷に揺れないようにする (同じアカウントグループのコンテナを同時に起動すると entrypoint の symlink 作成が競合して 1 つが落ちる #357)
• Merge remote-tracking branch 'origin/sprint/m7a' into feat/issue-357-m7a
• Merge pull request #357 を実装する（スプリント m7a） #380 from devbasex/feat/issue-357-m7a

変更の統計

 lib/devbase/commands/env.py                        |  30 +-
 lib/devbase/env/collectors/aws.py                  |  90 ++-
 lib/devbase/env/collectors/google.py               |  99 ++-
 lib/devbase/env/host_import.py                     |   9 +-
 lib/devbase/utils/docker.py                        | 188 ++++--
 tests/cli/test_post_start_command.py               | 124 ++++
 tests/commands/test_container_post_start.py        | 548 +++++++++++++++
 tests/commands/test_container_scale_order.py       |  18 +-
 tests/commands/test_env_host_import.py             |  79 +++
 tests/containers/test_base_image_link_stage.py     | 211 ++++++
 .../test_entrypoint_ai_settings_concurrent.py      | 748 +++++++++++++++++++++
 tests/env/test_aws_region_policy.py                | 303 +++++++++
 tests/env/test_gcp_credential_files.py             | 112 +++
 tests/utils/test_wait_for_containers.py            | 165 +++++
 32 files changed, 3067 insertions(+), 266 deletions(-)

テスト（supervise.py の run のステップ）

ステップ	exit	最後の行
collect	0

モード: standard / 通した工程: 実装 → Pull Request

🤖 Generated with Claude Code

[takemi-ohama]

改修計画 — devbasex/devbase #381

/ndf:cross-refactoring が提案し、改修計画し、適用した改善項目の記録である。
理由と手順は提案の時点でしか残らないため、公開の直前に書き出している。

• 対象範囲: .github, bin, containers/base, docs/plugin-dev, docs/specifications, docs/user, docs/user/cli-reference, etc, lib/devbase, lib/devbase/commands, lib/devbase/env, lib/devbase/env/collectors, lib/devbase/utils, tests/cli, tests/commands, tests/containers, tests/env, tests/utils
• テストの戦略: local-full（根拠 test.strategy）
• 範囲テストの雛形: env -u DEVBASE_ROOT uv run --locked pytest -q -o junit_family=xunit1 --junitxml=build/ndf/junit.xml {paths}
• 着手前のテスト: env -u DEVBASE_ROOT uv run --locked pytest tests/ -q -o junit_family=xunit1 --junitxml=build/ndf/junit.xml（whole）
• 着手前のテストの結果: 通過（114.7 秒 / HEAD d85f225）
• 既存失敗の件数: 0
• 想定最大時間: 30 分 / 改修計画の時点で使えた時間: 6.08 分
• 実装担当: claude

改善項目

I-001 — lib/devbase/commands/container.py#cmd_scale

兆候	手法	重要度	等級	提案元	状態	コミット
duplication	extract_method	major	high	claude	採用	1

なぜ: cmd_up と cmd_scale が、パイプラインを try で呼び ContainerStartupError を捕まえて startup_error / override_file=_SCALE_COMPOSE_FILE / started=list(e.ready) を組み、_run_post_start の後に startup_error があれば _report_startup_failure して 1 を返す、という同じ手順を別々に持つ（#371 で両方に足された）。部分起動の扱いを変えるたびに 2 か所を揃える必要がある

手順: 1. 起動の結果を表す小さな組 (override_file, started, startup_error) を返す _start_or_partial(run_pipeline, scale) を抽出する。pipeline 呼び出しを受け取り、成功なら (file, [1..scale], None)、ContainerStartupError なら (_SCALE_COMPOSE_FILE, list(e.ready), e) を返す
2. cmd_up の内側 try/except をこの呼び出しに置き換える（_warn_partial_start は cmd_up 側に残す）
3. cmd_scale も同じ呼び出しに置き換える。override_file is None で 1 を返す分岐は呼び出し側に残す
4. 末尾の『startup_error があれば _report_startup_failure(label, …) して 1』を _finish_partial(label, error, project_name) として抽出し両方から呼ぶ
5. tests/commands/test_container_post_start.py・test_container_up_order.py・test_container_scale_order.py を流す

締め切り: 実装の着手 2026-10-02T16:33:13+09:00

I-002 — lib/devbase/env/collectors/aws.py#_collect_profile_and_region

兆候	手法	重要度	等級	提案元	状態	コミット
magic_value	introduce_named_constant	minor	high	claude	採用	1

なぜ: #334 で DEFAULT_REGION = "ap-northeast-1" を定義したが、_collect_profile_and_region（方法 1）はまだ文字列 'ap-northeast-1' を入力の文言と既定値に 2 回直書きしている

手順: 1. _collect_profile_and_region の safe_input を f"{keys.AWS_DEFAULT_REGION} (デフォルト: {DEFAULT_REGION}): ", DEFAULT_REGION に置き換える
2. tests/env/test_aws_region_policy.py と env 関連テストを流す

締め切り: 実装の着手 2026-10-02T16:34:14+09:00

I-003 — lib/devbase/commands/container.py#_ENTRYPOINT_READY_FILE

兆候	手法	重要度	等級	提案元	状態	コミット
magic_value	centralize_configuration	minor	high	claude	採用	1

なぜ: entrypoint の完了の印 '/tmp/entrypoint-ready' を container.py の _ENTRYPOINT_READY_FILE と utils/docker.py の wait_for_containers_ready の既定引数が別々に持つ。片方だけ変えると post-start が完了を確かめられなくなる

手順: 1. utils/docker.py に ENTRYPOINT_READY_FILE = '/tmp/entrypoint-ready' を定義し、wait_for_containers_ready の既定引数をそれにする
2. container.py の _ENTRYPOINT_READY_FILE を削り、docker から import して使う
3. test_container_post_start.py と test_wait_for_containers.py を流す

締め切り: 実装の着手 2026-10-02T16:34:39+09:00

I-004 — etc/devbase-completion.bash#_devbase_completions

兆候	手法	重要度	等級	提案元	状態	コミット
duplication	extract_method	minor	medium	claude / codex / kiro	採用	2

なぜ: ps/logs のフラグ候補と compgen 呼び出しが旧 container/ct の第3引数と project の第4引数で重複する。top-level/project の open・ps にも同じ候補生成がある。同じ CLI オプション変更を複数箇所へ反映する必要がある。旧 container は名前を補完しないため、グループ全体を統合してはいけない。

手順: 1. tests/cli/test_completion.py で container/ct の ps/logs、名前入力位置と名前入力後、空文字とハイフンの候補を現状固定する。
2. ps/logs/open の候補文字列を関数内の名前付き変数へ集め、同一のフラグ候補生成だけを小さな補助関数へ抽出する。
3. 位置・グループ判定と名前補完の有無は各呼び出し側に残し、元と同じ条件で補助関数を呼ぶ。
4. completion と post-start の既存テスト、bash -n を実行する。

締め切り: テストの追加の着手 2026-10-02T16:32:33+09:00 / 実装の着手 2026-10-02T16:35:26+09:00

指標の測定

• 状態: written / 言語とツールの対応: 既定（.ndf/code-metrics.json は無い） / 所要: 11.1 秒（使えた時間 90 秒 / 上限 90 秒）
• 指標のファイル: /var/folders/qz/qxt0p_y15xv5jg4x77zmtxj80000gp/T/ndf-worktrees/devbasex--devbase/rf381/work/.cross_refactoring/code-metrics-rf381.md

言語	ツール	版	ランナー	ファイル	秒	結果
python	ruff-complexipy	ruff 0.16.9 / complexipy 8.0.1	uvx	234	1.0	測った
shell	—	—	—	4	—	unsupported_language
重複: python	symilar	pylint 4.0.9	uvx	234	8.7	測った（2 箇所）
重複: shell	jscpd	jscpd 4.3.0	npx	4	1.0	測った（2 箇所）

時間の上限

値	中身
提案の枠の終わり（監視の上限 = 残り + 余裕）	2026-10-02T16:28:52+09:00
改修計画の枠の終わり（同上）	2026-10-02T16:31:52+09:00
テストの追加の終わり = 最後の項目の完了の締め切り	2026-10-02T16:33:13+09:00
実装の終わり = 最後の項目の完了の締め切り	2026-10-02T16:36:27+09:00
直しの試行の打ち切り	2026-10-02T16:43:32+09:00
最終ゲートの修正の打ち切り（想定最大時間の終わり）	2026-10-02T16:52:52+09:00
最終ゲートの修正の 1 回目に必ず渡す長さ（秒。予備時間の final_fix）	330
指標の測定の上限（秒。提案の枠の中から割く）	90
着手前のテスト 1 回の上限（秒）	190
範囲テスト 1 回の上限（秒）	345
手元の全体テスト 1 回の上限（秒）	190
CI の待ちの上限（秒）	246
余裕（秒。手順の上限と CLI の上限に足す）	90

入力: 予算 30 分 / 全体テストの所要 w 63.1（ndf-record） / 着手前の実測 x 114.7 / CI の壁時計 c 82.0 / 戦略 local-full

無音の打ち切りは手順の監視の上限と同じ値である。項目ごとの締め切りは各項目の節にある。

見送った提案

対象	兆候	理由	根拠（MVV）	補足
lib/devbase/editor/window_title.py#strip_jsonc	long_method	no_target	Value 2 / Vision	範囲テストを組み立てられない（test_targets が --scope のテストの置き場所に無いか、雛形を持つ suite が無い）
lib/devbase/plugin/syncer.py#sync_projects	long_method	no_target	Value 3	範囲テストを組み立てられない（test_targets が --scope のテストの置き場所に無いか、雛形を持つ suite が無い）
lib/devbase/env/collectors/google.py#collect_google_credentials	long_method	budget	Value 3	見積り 2.1 分が残りに入らない
lib/devbase/commands/container.py#_push_bao_token	dead_code	budget	Vision	見積り 0.6 分が残りに入らない
lib/devbase/commands/container.py#_run_post_start	long_parameter_list	budget	Vision	見積り 0.6 分が残りに入らない
lib/devbase/commands/container.py#cmd_post_start	duplication	budget	Vision	見積り 1.0 分が残りに入らない
lib/devbase/commands/container.py#_SCALE_COMPOSE_FILE	duplication	budget	Vision	見積り 1.4 分が残りに入らない
lib/devbase/commands/container.py#cmd_post_start	long_method	budget	Vision	見積り 1.4 分が残りに入らない
lib/devbase/utils/docker.py#wait_for_containers_ready	long_method	budget	Vision	見積り 1.4 分が残りに入らない
lib/devbase/commands/env.py#_target_group	circular_dependency	budget	Value 3 / Vision	見積り 1.2 分が残りに入らない
tests/cli/test_open_command.py#_run_wrapper	test_coupled_to_internals	budget	Vision / Value 3	見積り 1.2 分が残りに入らない
lib/devbase/commands/env_backend.py#cmd_env_backend_migrate	long_method	budget	C1 / Value 3 / C2	見積り 1.4 分が残りに入らない
lib/devbase/commands/env_ops.py#_check_backend	long_method	budget	Value 3 / C1	見積り 1.4 分が残りに入らない
lib/devbase/env/aws_profiles.py#_split	long_method	budget	Value 3 / C1	見積り 1.4 分が残りに入らない
tests/containers/test_lfm_base_settings.py#summarize	long_method	budget	Value 1 / Vision	見積り 1.4 分が残りに入らない
lib/devbase/commands/env_backend.py#cmd_env_backend_migrate	magic_value	budget	Value 2	見積り 0.8 分が残りに入らない
lib/devbase/env/aws_profiles.py#profiles_in_value	duplication	budget	Value 2	見積り 1.0 分が残りに入らない
lib/devbase/utils/docker.py#StartupFailure	primitive_obsession	budget	Vision	見積り 1.2 分が残りに入らない
lib/devbase/commands/env.py#_sync_source	long_parameter_list	budget	Value 3 / Vision	見積り 1.2 分が残りに入らない
lib/devbase/commands/env.py#_record_gcp_source	duplication	budget	Vision	見積り 1.4 分が残りに入らない
lib/devbase/env/compose_migrate.py#enable	long_method	budget	Value 2 / Value 3	見積り 1.4 分が残りに入らない

[takemi-ohama]

🤖 cross-review | round 1 | codex | REQUEST_CHANGES

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

[takemi-ohama]

🤖 cross-review | round 1 | kiro | APPROVE

4 件の挙動保存リファクタ（container.py の _start_or_partial/_finish_partial 抽出、aws.py と docker.py の定数化、completion.bash の _devbase_complete_flags 抽出）と現状固定テストの追加。cmd_up / cmd_scale の分岐（override_file is None の早期 return、_warn_partial_start の位置、ContainerStartupError 捕捉時の started=list(e.ready)）、定数 DEFAULT_REGION / ENTRYPOINT_READY_FILE の値とスコープ、bash 補完の各位置（container/ct=旗のみ、project/トップレベル=旗+名前）がいずれも元と一致することを git show / grep / ソース精読で確認した。critical / major の基準（利用者経路の破壊・秘密/認可/データ/不可逆操作・設計文書の食い違い）に当たる指摘は見つからなかった。

[takemi-ohama]

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

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

[takemi-ohama]

🤖 cross-review | round 2 | claude | APPROVE

critical / major に当たる指摘なし。a756a31 の完了の印の削除は関数定義の直後・最初の初期化処理の前にあり、_start_or_partial / _finish_partial の抽出、定数化、補完の補助関数抽出はいずれも元の分岐と一致する。

[takemi-ohama]

🤖 cross-review | round 2 | kiro | APPROVE

entrypoint の完了の印を起動ごとに消す修正 (a756a31) と、round 1 のリファクタ 4 件 (container.py の _start_or_partial/_finish_partial 抽出、aws.py / docker.py の定数化、completion.bash の _devbase_complete_flags 抽出) を精査した。entrypoint.sh の rm -f は lib-only ガードの後・最初の setup の前に置かれ、touch は exec 直前に残る（test_entrypoint_ready_marker.py が guard<remove<first_setup<touch<exec を固定）。これにより docker start で再起動したコンテナの再初期化中に post-start / wait_for_containers_ready が前回の印を完了と誤読する既存の指摘が解消される。ENTRYPOINT_READY_FILE は docker.py・container.py・entrypoint.sh で同一値に揃い、現状固定テストが一致を確認する。completion.bash の抽出はフラグのみ経路（container/ct）と名前補完あり経路（project/top-level）を分けて再現し、test_completion.py が container ps '' → 空集合、project ps '' → 名前集合で挙動保存を固定する。利用者経路の破壊・秘密/認可/データ/不可逆操作・設計文書の食い違いに当たる critical/major の指摘は見つからなかった。CHANGELOG が明記する「base イメージを建て直した後のコンテナから効く」制約は正確で、既存コンテナは旧 entrypoint を焼き込んでいるため当然の挙動であり欠陥ではない。

[takemi-ohama]

🔧 /ndf:fix サマリ | commit (なし)

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

[takemi-ohama]

振り返り（2026-10-03）

対象: PR #381（スプリント m7a: #357 #215 #224 #371 #334）と、同じ機会に行った #311（operation。記録は PR #384）

スプリント m7a では、次の 4 つを main へ入れた。

• 同じグループのコンテナを同時に起動してもリンクの段が落ちない（同じアカウントグループのコンテナを同時に起動すると entrypoint の symlink 作成が競合して 1 つが落ちる #357）
• up / scale の起動の後の処理を、起動できたインスタンス・増やしたインスタンスだけに行う。やり直しの devbase project post-start を足した（devbase scale で増やしたインスタンスに _report_missing_repos / _apply_window_titles が行われない #224・up でコンテナが 1 台でも落ちると、起きているコンテナにも起動の後の処理（window.title・token・エディタ）が行われない #371）
• env init の region を取り込みの方針に従わせる（env init の AWS の方法 3 が取り込みの方針によらず AWS_DEFAULT_REGION をホストから書く #334）
• plugin-yml-reference の requires 契機表を正本にし、新機能 PR で 1 行足す手順を PR テンプレートへ入れる #215

確定仕様は PR #383 で docs/specifications/container-link-stage.md・post-start.md・secret-backend.md に置いた。
リリース後テストは #311 の実機の確認と一緒に行い、すべて合格した。

何が起きたか

観点	事実
受け入れ条件	途中の変更は 1 つ。#371 を #224 と同じスプリントで直すと利用者が決め、要求の文書を 1 本にまとめた
手戻り	実装 #357 は遅れの打ち切りで 2 回走り直した（4-impl-357.rerun*.log）。設計 #357 はステップの上限 12 に再試行が数えられ、判定の前に止まった（上限を 16 へ上げて回避）。スプリントの検査の段で「entrypoint の完了の印を起動ごとに消す」修正（a756a31）がスプリントの中で入った
見落とし	リリース後テストで、マージ前に踏めなかった経路を実機で踏んだ。不具合は出ていない。1 台が起動に失敗したときの後処理（#371）は、実環境で落とす手段が無く、テストに任せた
範囲	範囲外へ出したのは #372（settings.json が運用中に通常のファイルへ置き換わる）と #374（起動の待ちの制限時間を巡の回数で数えている）。#311 からはテストの穴 #382 を起票した
工程	確定仕様化は normal のプランに雛形が無く、supervisor で回した。#311 の取り消しの手段のうち scale 1 が使えず（scale は台数を減らせない）、承認した手段と違う手段（コンテナの直接の削除）で戻した。#311 の記録は固有の語の検査に当たり、CI を 1 巡やり直した

context window の大きさ

この会話（#311・リリース後テスト・確定仕様化・振り返り）の測定。スプリントの前半のセッションは含まない。

層	フェーズ	モデル	件数	固定費の中央値	実作業の中央値	実作業 < 固定費	最大充填の最大	目印
conductor	-	claude-opus-5-5	1	32450	174895	0	207345	割る候補
supervisor	その他	claude-opus-5-5	1	33137	216917	0	250054	割る候補

層	件数	固定費の合計	実作業の合計	総消費
conductor	1	32450	174895	207345
supervisor	1	33137	216917	250054
合計	2	65587	391812	457399

• conductor の「割る候補」はそのままにする。実機の確認は承認を挟んで端末の状態を順に変えるため、途中で会話を切ると控えの値と状態の対応が追いにくい
• supervisor（確定仕様化）の「割る候補」もそのままにする。3 課題・9 文書を 1 本の PR にまとめる作業で、割ると用語集の出所の付け替えがぶつかる

MVV を見直すか

project-mvv.py signals: 版 1、覆し 0 件（閾値 3）、判定できない 0 件（閾値 5）、流出不具合 0 件（閾値 3）。改訂の提案は無い。
利用者の答えは「改訂しない」。

main へのマージの扱いには食い違いがある。MVV の補足は main へのマージを「必ず人の承認が要る操作」に含めていない。一方、merged-steps.py は .ndf/project.json の delivery（auto main）から、main を自動反映の本番チャネルとして承認ゲート 2 で止める。今回は承認を取って進め、実害は無かった。

次に変えること

変えること	落とし先	状態
operation の取り消しのコマンドが実在して効くかを、承認の前に読み取りの手段で確かめる	development-workflow の operation-run.md の手順	devbasex/ai-plugins#1622 として起票
遅れの見張りが設計・要求の worker を作業中に打ち切り、再試行がステップの上限を食う	supervise.py の雛形と見張り	devbasex/ai-plugins#1623 として起票
実機の記録を中立の呼び名で書き、手元で固有の語の検査を打てるようにする	プロジェクトの取り決め（AGENTS.md）と検査の知らせ	#385 として起票

運用の知見のうち、run --from が {pr} を引き継がない件（ai-plugins#1296）、並行する設計 PR の用語集の衝突（ai-plugins#1493、閉）、requirements-check の exit 2 の読み（ai-plugins#1502）は起票済みのため足していない。

途中で起票した課題

番号	何を見つけたか	見つけた場面
#372	.claude/settings.json が運用中に symlink から通常のファイルへ置き換わる	設計（#357）
#374	起動の待ちの制限時間が実際の時間ではなく巡の回数で数えられている	設計（#224）
#382	TUI の OpenBao の接続設定で url だけ変えたときの version 2 のテストが無い	#311 の実行