docs(PLAN61): bin/devbase の位置引数の解決を名前の形・衝突・ヘルプ・グループで正す要求仕様と設計 (#146, #142, #196, #200)

[takemi-ohama]

Summary

bin/devbase の name 解決と build) の分岐にかかる 4 件（#146 名前が projects/ の外へ出る / #142 build <image> がプロジェクト名に吸われる / #196 build --help がビルドを始める / #200 container <sub> <name> が parser を迂回する）を 1 本で直す設計。

• 要求と受け入れ条件: issues/PLAN61_name-resolution.md
• 設計: issues/PLAN61_name-resolution-design.md
• モード: standard。この PR は設計だけを載せる（ドキュメントレビュー）。実装は承認・マージの後に別 PR で行う

決めたこと

issues/PLAN61_name-resolution-design.md

• 決定 1: 名前の形は [A-Za-z0-9][A-Za-z0-9._-]* とし、合わない値は名前として扱わずに素通しする
• 決定 2: Python の規則は utils/names.py の 1 関数に置き、_build_single_image も同じ関数を使う
• 決定 3: 既存の他の名前の検証は寄せない
• 決定 4: shell の比較は LC_ALL=C で行う
• 決定 5: build <x> で containers/<x> と projects/<x> が両方あれば、イメージとしてビルドして知らせる
• 決定 6: 衝突の判定は containers/<x> の実在で分け、maybe_cd_project の前に置く
• 決定 7: build の -h / --help は name 解決より前に判定し、bin/devbase が使い方を出す
• 決定 8: -h / --help は引数のどこにあっても使い方を優先し、--context=-h / --context=--help だけは使い方にしない
• 決定 9: 使い方に --project-no-cache を載せる
• 決定 10: container / ct を name 解決の分岐から外す
• 決定 11: wrapper のテストは bin/devbase を tmp へ複製して実行し、uv だけを PATH で差し替える

Test plan

• 設計の前提を手元で確かめた: projects/ の 38 件がすべて [A-Za-z0-9][A-Za-z0-9._-]* に収まる（ls projects/）、macOS /bin/bash 3.2.57 で local LC_ALL=C の下の [[ =~ ]] の判定
• document-restructuring を通した（平均文長 42.7 → 38.8 字、最長文 150 → 95 字）

🤖 Generated with Claude Code

[takemi-ohama]

🤖 cross-review | round 1 | kiro | REQUEST_CHANGES

設計・要求は概ねコードの現状と整合しており、参照している関数・テスト・ドキュメントパスも実在を確認できた。以下 2 件、要求仕様と設計の間の食い違いを直すこと（いずれも実装者を迷わせる整合性の問題）。詳細はインライン。

• PLAN61_name-resolution.md:137（AC10）と PLAN61_name-resolution-design.md:342（テスト項目 10）が、決定 9・#196 原文が要求する --project-no-cache の使い方掲載を検証していない。
• PLAN61_name-resolution-design.md:40 と PLAN61_name-resolution.md:160 で、#196(F3) の CHANGELOG 帰属節（Fixed か Changed か）が矛盾している。

[takemi-ohama]

🤖 cross-review | round 1 | agy | REQUEST_CHANGES

全体として各 issue の要件と既存実装の制約（bash 3.2、二重管理、引数位置）が精緻に考慮されていますが、決定 9 で採択された --project-no-cache が受け入れ条件 10 およびテスト設計から欠落している点、および決定 8 の -h の扱いの明確化について修正を提案します。

[takemi-ohama]

🔧 /ndf:fix サマリ（round 1）

対応件数: critical=0 / major=3 / minor=2（合計 5 thread、論点 3 件）
deferred: 0 件 / rejected: 0 件
commit: bc981d4

詳細

• --project-no-cache の欠落（issues/PLAN61_name-resolution.md:137 に 2 thread、design.md:342）: 受け入れ条件 10 とテスト設計 10 に追加。条件 10 には 2026-09-18 のドキュメントレビューで追加した旨を添えた
• CHANGELOG の分類（design.md:40）: fix(cli): devbase build --help がヘルプを出さずにビルドを始める #196 はバグ修正なので Fixed。要求仕様の「影響」表を「fix: devbase のプロジェクト名解決が projects/ の外へ出られる #146・fix: devbase build <image> が実在プロジェクト名と衝突して黙って別のイメージをビルドする #142・container / ct グループのサブコマンドが wrapper 経由で [name] を受け付けてしまう #200 は Changed、fix(cli): devbase build --help がヘルプを出さずにビルドを始める #196 は Fixed」に直した
• -h の扱い（design.md:295）: 決定 8 の見出し・本文、入出力の契約（L131）、テスト設計の決定 8 の行に -h を併記

[takemi-ohama]

🤖 cross-review | round 2 | codex | REQUEST_CHANGES

ヘルプの副作用と context 値の受け渡しについて、契約を満たす変更範囲・検証方法を設計へ反映してください。

[takemi-ohama]

🤖 cross-review | round 2 | kiro | APPROVE

設計・要求とも実装（bin/devbase の name 解決 / build) 分岐 / _build_single_image / _resolve_project_name / _named_lifecycle_project）の現状と一致しており、決定の記録の主張も裏付けを確認できた（_IMAGE_NAME_RE と新パターンの同一性、snapshot/manager.py の _VALID_NAME_RE の文字集合一致、_NAME_RESOLVABLE_SHORTCUTS に open を含むこと、scale の [name]+new_scale 順による終了コードを検証）。修正を要する不整合・誤りは見つからなかった。

[takemi-ohama]

🔧 /ndf:fix サマリ（cross-review 最終スイープ）

対応件数: critical=0 / major=1 / minor=1（合計 2 件）
deferred: 0 件 / rejected: 0 件
commit: f1a6b39
CI: PENDING（Ruff lint 実行中、他は pass）

詳細

• [major] design.md:132 build --help が読まない env の範囲 — 契約・決定 7 を「切り替え先プロジェクトの env を読まない。起動時の $DEVBASE_ROOT/env と実行時ディレクトリの env は全コマンド共通で読む」に正した。ヘルプ判定を初期 env の読み込みより前に移す変更は採らない（既存の全コマンド共通の挙動で、fix(cli): devbase build --help がヘルプを出さずにビルドを始める #196 の受け入れ条件はビルドを起こさないこと）
• [minor] design.md:356 --context=--help — 決定 8・契約・テスト設計を「使い方にしない。下流の argparse の usage エラー（終了コード 2）になる。- 始まりの context 名は受け付けない」に直した。= の結合保持は採らない
• 決定 8 の見出しを変えたため PR 本文の決定の節を同期（pr-body-decisions sync exit=0）

open review thread: 0

[takemi-ohama]

🤖 cross-review | round 3 | codex | REQUEST_CHANGES

ヘルプ時の対象 env 非読み込みを検証するテスト設計の修正が 1 件あります。

[takemi-ohama]

🔧 /ndf:fix サマリ

対応件数: critical=0 / major=0 / minor=1 (合計 1 件)
deferred: 0 件 / rejected: 0 件
commit: 4085d69
CI: PENDING

詳細

• issues/PLAN61_name-resolution-design.md:343: 受け入れ条件 11 に projects/carmo/env の読み込み検知（echo CARMO_ENV_READ >&2 が stderr に出ないこと）を追加。PWD: の不在だけでは cd と env 読み込みの未実行を示せないため。resolve 済み