列挙の正本を一元化し、argparse と文書の一致をテストで固定する（[name] / --context）

[takemi-ohama]

何を見つけたか

[name] 引数と --context を取るサブコマンドの集合が、5 か所に手で複製されている。

複製先	実体
bin/devbase	_PROJECT_NAME_SUBCOMMANDS / _NAME_RESOLVABLE_SHORTCUTS（:484-485）
lib/devbase/cli.py	_add_project_parser などでの name positional と --context の付与
文書 7 ファイル	docs/user/cli-reference/02-project.md / docs/user/cli-reference/README.md / docs/user/container-operations.md / docs/user/environment-variables.md / docs/specifications/compose-profiles.md / docs/specifications/remote-docker-context.md / docs/specifications/cli-argument-resolution.md
補完 2 ファイル	etc/devbase-completion.bash / etc/_devbase

同期はコメントの申し合わせ（bin/devbase:474-483、lib/devbase/cli.py:32-37 と :287-291）だけで担保されている。集合の一致を固定するテストは無い。 tests/cli/test_rebuild.py:152-153 が bin/devbase の 2 つのリストに rebuild が含まれることを見ているだけで、_PROJECT_NAME_SUBCOMMANDS と argparse の一致も、文書・補完との一致も固定されていない。

lib/devbase/cli.py の _create_parser() を走査すると、集合は次のとおりである（bf2b929）。

対象	サブコマンド
project で name positional を持つ	up down ps logs scale rebuild open
project / container で --context を持つ	up down ps logs login scale build rebuild open
container で name positional を持つ	なし

profile は [name] と --context を入れ子の parser（profile up / profile down）で持つため、上の走査では拾えない。文書は profile も [name] / --context を取るものとして並べている。

その結果、PLAN49（rebuild の追加）と PLAN59（open の追加）の 2 回とも、コードと補完だけが更新され文書が取り残された。同じ漏れが 2 度起きている。

現象レイヤー

文書 7 ファイルの列挙、bin/devbase の 2 つのリスト、補完 2 ファイル。どれも argparse の定義を手で写したもので、写し漏れが起きる。

修正レイヤー

列挙の**正本は argparse（lib/devbase/cli.py の _create_parser()）**に置く。定義そのものがそこにあり、他の複製はすべてそこから派生する。

1. tests/cli/ 配下に一致テストを足し、_create_parser() を走査して得た集合に次を合わせる
   • bin/devbase の _PROJECT_NAME_SUBCOMMANDS / _NAME_RESOLVABLE_SHORTCUTS（login / build を意図的に除く・含める規則はコメントのとおり）
   • 補完 2 ファイル（etc/devbase-completion.bash / etc/_devbase）
   • docs/specifications/cli-argument-resolution.md の表
   • 入れ子の profile も走査の対象に含める
2. 他の文書は列挙を持たず、docs/specifications/cli-argument-resolution.md へのリンクにする

走査の実装は PR #213 で使った、_create_parser() から name positional と --context を持つ parser を集める形がそのまま使える。

どこで見つけたか

#208 の本文「修正レイヤー」。PR #213 は現象レイヤー（文書への追記）だけを直した。

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

#208 の本文が「恒久策（正本の一元化と一致テスト）は、この issue の範囲を超えるため着手の時点で分ける」と明示している。PR #213 の受け入れ条件は文書の列挙が argparse と一致することまでで、正本の移動とテストの追加は含まない。また PR #213 は docs/ 配下だけに閉じる light の変更で、tests/ を触らない。

直さないと何が起きるか

[name] または --context を取るサブコマンドを次に増やしたとき、3 度目の取り残しが起きる。文書だけが古いため CI も補完も気づかず、利用者が「そのコマンドは名前を取れない」と読んで遠回りする。影響の範囲は文書の読み手全体で、コードの振る舞いには及ばない。

由来

PR #213（#208 / #195 の現象レイヤーの修正）

直す場所

項目	内容
現れている場所	文書 7 ファイルの列挙・bin/devbase の _PROJECT_NAME_SUBCOMMANDS / _NAME_RESOLVABLE_SHORTCUTS・補完 2 ファイル（etc/devbase-completion.bash / etc/_devbase）
直す場所	lib/devbase/cli.py の _create_parser() を正本にし、tests/cli に一致テストを新設（手: 統合 consolidate_duplication + 新設）。他の文書は cli-argument-resolution.md へのリンクにする