feat: PLAN32-docs ドキュメントと CHANGELOG

[takemi-ohama]

Summary

複数リポジトリ構成（project.yml）に合わせて、利用者向けドキュメントを更新します。

• 新規 docs/user/project-yml.md: project.yml のリファレンス。最小構成 / 複数リポジトリの例 / キー一覧 / 検証される内容 / env との使い分け / 旧 env 形式からの移行表 / コンテナへの渡り方
• 環境変数ガイド: env は「コンテナへ渡す環境変数」だけを持つこと、GIT_USER などを書いても効果がないこと、エディタが開く対象が project.yml から決まることを明記
• コンテナ操作ガイド / CLI リファレンス: コンテナ数の設定を CONTAINER_SCALE から project.yml の scale へ。devbase project migrate-config の項を追加
• プラグイン開発クイックスタート / compose.yml ガイドライン / repo 連携ガイド: プロジェクト定義の作り方を project.yml ベースに書き換え
• アーキテクチャ解説: project/ モジュール（config.py / runtime.py / migrate.py）の節を追加
• CHANGELOG: 複数リポジトリ対応と破壊的変更、ベースイメージ再ビルドが必要な点を追記

過去リリース分の CHANGELOG 記述は履歴なので書き換えていません。

• plan: issues/PLAN32_multi-repo-project.md の Task 5
• release PR: release: PLAN32 1 プロジェクト = 複数リポジトリ構成への変更 (v3.0.0) #103

Test plan

• uv run pytest — 全 1322 件 green（ドキュメントのみの変更で影響がないことの確認）
• grep -rn "GIT_REPO\|CONTAINER_SCALE" docs/ — 残存は移行表と過去リリースの履歴のみ
• 追加・変更したリンク先の存在確認（docs/user/project-yml.md、CLI リファレンスのアンカー）

[takemi-ohama]

🤖 cross-review | round 1 | codex | REQUEST_CHANGES

移行コマンドの案内を、この PR のベースで実行可能な内容に揃える必要があります。

[takemi-ohama]

🤖 cross-review | round 1 | gemini | REQUEST_CHANGES

[major / 整合性]
ドキュメントと実装に乖離があります。
CHANGELOG や docs/ には devbase project migrate-config コマンドの追加や、devbase up / devbase project scale が project.yml を読み書きする旨が記載されていますが、本 PR の差分にはそれらの実装（Task 2, Task 4）が含まれていません。
未実装の機能をドキュメント化すると利用者を混乱させるため、issues/PLAN32_multi-repo-project.md の「PR 分割計画」の通り、不足している実装 PR を本ブランチに取り込んでからマージしてください。

[takemi-ohama]

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

対応件数: critical=0 / major=0 / minor=2 (合計 2 件)
deferred: 0 件 / rejected: 2 件
commit: efb6a3a
CI: NONE（このリポジトリの本ブランチには CI チェックが設定されていません）

修正した指摘

#	ファイル	内容
1	docs/plugin-dev/repo-backed-projects.md	185・186 行の旧アンカー #スケール前提-container_scale1 を現在の見出しに対応する #スケール前提-scale-1 へ修正
2	docs/plugin-dev/quickstart.md	見出しを 2.3.1 env ファイル（ファイルは必須・中身は任意） に変更。本文を断定形にし、空ファイルで良い旨と touch 例を追記

あわせて自己点検で見つけた次の 2 点も同コミットで直しました。

• quickstart.md 2.1 の最小構成ツリーに project.yml が抜けていたので追加（env にも「中身は任意だが、ファイルは必須」と注記）
• docs/user/project-yml.md「env との使い分け」の同趣旨の説明を同じ言い回しへ統一

rejected（修正せず、スレッドで理由を説明。Resolve していません）

#	指摘	理由
3	migrate-config がベースに存在しない (docs/user/project-yml.md)	実装は同じ release/PLAN32 宛の PR #107 で先行済み。両 PR が release/PLAN32 上で揃ってから release PR #103 で main へ入るため、利用者に届く時点では CLI と文書が同時に存在します。記述内容が #107 の実装（--dry-run / --projects-dir / 可変長 NAME、既存 project.yml 非上書き）と一致することも確認済みです
4	runtime.py / migrate.py が存在しない (docs/developer/architecture.md)	runtime.py は 既にベース release/PLAN32 にマージ済み（e3a6e36 / #105）。container_env / build_workspace_document / read_scale / write_scale / DEFAULT_SCALE = 2 を持ち、記載した責務と一致します。migrate.py は #3 と同じ理由です

検証

• uv run pytest — 1322 passed（ドキュメントのみの変更で回帰なし）
• 変更した Markdown 内の相対リンク・見出しアンカーをスクリプトで全件照合。この PR で追加・変更した参照に切れが無いことを確認

@takemi-ohama 再レビューをお願いします。

[takemi-ohama]

🤖 cross-review | round 2 | codex | REQUEST_CHANGES

DEVBASE_OPEN_EDITOR の収集方法と既定値を実装に合わせて修正する必要があります。

[takemi-ohama]

🤖 cross-review | round 2 | gemini | APPROVE

1点のドキュメントの正確性に関するインラインコメントを記載しました。

[takemi-ohama]

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

対応件数: critical=0 / major=1 / minor=3 (合計 4 件)
deferred: 0 件 / rejected: 0 件
commit: 4e2b76e（ベース取り込みの merge commit a12851a を含む）
CI: NONE（このブランチに CI チェックは設定されていません）

1. ベースの取り込み — round 1 で rejected とした 2 件が解消

PR #107 が release/PLAN32 へ merge（cd22257）されたため、origin/release/PLAN32 を本ブランチへ取り込みました（コンフリクトなし）。これで round 1 に「ベースへ存在しない」として保留していた指摘の前提が解消しています。

#	スレッド	状態
1	docs/user/project-yml.md:105 — migrate-config がベースに無い	解消。lib/devbase/cli.py:248 の登録、lib/devbase/commands/project.py:175 の cmd_project_migrate_config、lib/devbase/project/migrate.py が実在。リンク先アンカー cli-reference/02-project.md#devbase-project-migrate-config の見出しも実在を確認
2	docs/developer/architecture.md:151 — runtime.py / migrate.py が無い	解消。lib/devbase/project/ に config.py / runtime.py / migrate.py が揃い、モジュール表の記載（container_env / build_workspace_document / read_scale / write_scale / migrate_project）と一致

いずれも文面の変更は不要で、Resolve 済みです。

2. 修正した指摘 (round 2)

#	ファイル	内容
3	docs/user/environment-variables.md:155	「これらは devbase env init の収集対象外で」→ DEVBASE_OPEN_EDITOR だけは editor コレクターが対話収集し（対話既定 1 = 有効）$DEVBASE_ROOT/.env に書かれる旨と、残りが収集対象外である旨へ書き分け
4	docs/user/environment-variables.md:159	表の「既定: OFF」→「devbase env init の対話既定は 1（有効）なので init 済み環境では通常 ON。キー自体が未設定のときのみ OFF に倒れる」へ修正

実装の裏取り:

• lib/devbase/env/collectors/editor.py の collect_open_editor — 既存値が 0 / 1 以外なら対話既定は 1
• lib/devbase/env/collector.py:39 — COLLECTOR 定数を持つモジュールを走査して自動登録するため editor も env init の対象
• lib/devbase/editor/opener.py の is_open_enabled — env 未設定時のみ False

検証

• uv run pytest — 1371 passed（ベース取り込み後・ドキュメントのみの変更で回帰なし）
• docs/**/*.md + README.md + CHANGELOG.md の相対リンクと見出しアンカーを全件照合 — 切れ 0 件

@takemi-ohama 再レビューをお願いします。

[takemi-ohama]

🤖 cross-review | round 3 | codex | REQUEST_CHANGES

ドキュメント上の実行頻度と設定の有効範囲を、実装挙動に合わせて修正してください。

[takemi-ohama]

🤖 cross-review | round 3 | gemini | APPROVE

ドキュメント全体を通した変更を確認しました。
各機能 (project.yml への移行、env の役割の分離、複数リポジトリ設定、VS Code 自動オープンの仕組みなど) の実装仕様が正確に反映されており、不整合やリンク切れも見当たりません。特に env ファイルを必須としつつも役割を明確に分けた点、移行時の挙動などが網羅的で読者を迷わせない素晴らしい構成です。

[takemi-ohama]

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

対応件数: critical=0 / major=0 / minor=2 (合計 2 件)
deferred: 0 件 / rejected: 0 件
commit: 5dbe870
CI: NONE（このブランチに CI チェックは設定されていません — gh pr checks 108 は "no checks reported"）

round 3 の未解決スレッドは codex の 2 件（gemini は APPROVE / 指摘なし）。いずれも実装を読んで正しい指摘と確認したうえで修正しました。

修正した指摘

#	ファイル	内容	裏取り
1	docs/user/project-yml.md	repos[].init を「clone 後に実行」→「clone 直後だけでなくコンテナ起動のたび（既存 clone があっても）実行」へ修正。branch（clone 直後の 1 回だけ）との実行タイミング差を理由付きの表で追記し、init.sh は冪等に書くこと／繰り返すと壊れる処理は実行済み判定を入れること／重い場合は init: false を明記。失敗が警告に留まる点も追記	containers/base/entrypoint.sh:83 の init.sh 実行は cloned フラグで囲まれていない（同 75 行の checkout は cloned = 1 のときだけ）
2	docs/user/environment-variables.md:161	DEVBASE_WORKSPACE を「効くのはリポジトリ 1 件の構成だけ。2 件以上では devbase up が自動生成した /work/<プロジェクト名>.code-workspace を直接開くため、この env を設定しても上書きできない」へ修正	lib/devbase/commands/container.py:606-608 が repo 2 件以上のときだけ workspace= を渡し、lib/devbase/editor/opener.py:688 は workspace = workspace or resolve_workspace(env)（引数優先）

あわせて同じ挙動に触れている次の箇所も表現を揃えました。

• docs/plugin-dev/quickstart.md — init: false のコメントとキー説明表を「起動のたびに実行。冪等に書くこと」「branch は clone 直後のみ」へ
• docs/user/container-operations.md:186 — DEVBASE_WORKSPACE の言及に「リポジトリ 1 件の構成のみ」を補足

#2 で示された「複数構成でも明示値を優先する実装に合わせる」案は採らず、文書側を実装に合わせています。複数リポジトリの workspace ファイルは entrypoint が DEVBASE_WORKSPACE_B64 から所定パスへ書き出す生成物で、開く先だけを env でずらしても中身が連動しないため、優先順位を入れ替えると「存在しない／古いワークスペースを開く」事故になりやすいと判断しました（本 PR はドキュメント PR のため実装変更の範囲外でもあります）。

検証

• uv run pytest — 1371 passed（ドキュメントのみの変更で回帰なし）
• docs/**/*.md + README.md + CHANGELOG.md の相対リンク・見出しアンカーを全件照合 — 切れ 0 件

対応した 2 スレッドは Resolve 済みです。@takemi-ohama 再レビューをお願いします。

[takemi-ohama]

🤖 cross-review | round 4 | codex | REQUEST_CHANGES

• docs/user/environment-variables.md:23: 「読み込み順序」の projects/*/env の用途がまだ「リポジトリ名・コンテナ数等」となっており、直下で追加された「これらは project.yml に書き、env に書いても効果がない」という説明と矛盾します。この行もコンテナへ渡すプロジェクト固有の環境変数（例: ENABLE_SSH）へ更新してください。

[takemi-ohama]

🤖 cross-review | round 4 | gemini | APPROVE

修正内容は適切で、前回のレビューから追加された変更（init.sh の実行タイミングの明確化や、DEVBASE_WORKSPACE の有効範囲の追記など）も実装仕様を正しく反映しており問題ありません。読者の誤解を防ぐための良い改善です。

[takemi-ohama]

🔧 対応 (round 4)

• docs/user/environment-variables.md の「読み込み順序」表の projects/*/env の用途を、直下の説明と揃えて「コンテナへ渡すプロジェクト固有の環境変数（ENABLE_SSH 等）」へ修正しました。

指摘はレビュー body のみでインラインコメントが無かったため、Resolve 対象のスレッドはありません。

[takemi-ohama]

🤖 cross-review | round 5 | codex | REQUEST_CHANGES

project.yml リファレンスの適用範囲と検証仕様を実装に一致させてください。

[takemi-ohama]

🤖 cross-review | round 5 | gemini | APPROVE

ドキュメントの構成、旧形式からの移行手順、関連する環境変数の説明など、各所の整合性が取れており問題ありません。

[takemi-ohama]

🤖 cross-review | round 6 | codex | APPROVE

修正が必要な問題は見つかりませんでした。

[takemi-ohama]

🤖 cross-review | round 6 | gemini | APPROVE

PR の目的（project.yml への移行と複数リポジトリ対応）とドキュメントの変更範囲が完全に一致しており、旧形式（env）からの移行手段や各設定値の優先順位が非常に明確に記述されています。
追加・更新された記述に矛盾や曖昧さは見当たらず、コード実装とも整合しているため問題ありません。