chore: PLAN32 の破壊的変更に合わせて 3.0.0 へ上げる

[takemi-ohama]

Summary

project.yml への移行はプロジェクト定義の互換性を壊すため、SemVer に従って major を上げます。

• pyproject.toml: 2.2.0 → 3.0.0
• CHANGELOG.md: [Unreleased] の内容を [3.0.0] - 2026-08-23 として確定し、プラグイン側で requires.devbase: ">=3.0.0" への更新が必要な旨を明記
• ドキュメント中のバージョン表記（アーキテクチャ解説、プラグイン開発クイックスタートの前提）を 3.0.0 へ

背景

クロスレビューで、プラグインの plugin.yml が requires.devbase: ">=2.2.0" を許容したままだと、project.yml を読めない 2.2.0 にインストールできてしまい、インストール時の互換性チェックを通過した後で devbase up が失敗する、という指摘がありました。プラグイン側が下限を上げるには、まず本体側にその版数が必要です。プラグインリポジトリ側の更新は各リポジトリの移行 PR で行います。

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

Test plan

• uv run pytest — 全 1371 件 green
• grep -rn "2\.2\.0" docs README.md lib bin — 残存は CHANGELOG の過去リリース記述のみ

[takemi-ohama]

🤖 cross-review | round 1 | codex | REQUEST_CHANGES

リリース前に、実行時版数・lockfile・CHANGELOG 参照リンクを 3.0.0 基準へ同期してください。

[takemi-ohama]

🤖 cross-review | round 1 | gemini | REQUEST_CHANGES

PR の説明にある grep の結果と異なり、バージョン番号の更新漏れや付随するロックファイルの非同期が見受けられます。
インラインで指摘できない差分外のファイルが含まれるため、以下にまとめて記載します。

• [major / 正確性] lib/devbase/__init__.py (L3), lib/devbase/cli.py (L17), lib/devbase/commands/status.py (L13):
  __version__ = "2.2.0" が残存しています。これらの実行時版数も 3.0.0 へ更新してください。
• [major / 正確性] uv.lock:
  pyproject.toml のバージョンが上がったことで uv lock --check が失敗する状態になっています。uv lock を実行してロックファイルを同期してください。
• [major / 正確性] CHANGELOG.md (末尾):
  Keep a Changelog 形式のリンクが未更新です。[Unreleased] の比較開始点を v3.0.0 に向け、新たに [3.0.0]: https://github.com/devbasex/devbase/compare/v2.2.0...v3.0.0 のリンク定義を追加してください。
• [minor / ドキュメント] docs/user/env-export-import.md (L77付近):
  manifest のサンプルコードにある devbase_version: 2.2.0 も 3.0.0 へ合わせておくことを推奨します（必須ではありません）。

[takemi-ohama]

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

対応件数: critical=0 / major=1 / minor=2 (合計 3 件)
deferred: 0 件 / rejected: 0 件
commit: aef5c90
CI: NONE (このブランチに登録された check はありません)

codex / gemini の指摘はいずれも妥当でした。pyproject.toml だけを 3.0.0 にしたため、実行時の版数表示とロックファイルが 2.2.0 のまま取り残されていたのが根本原因です。PR 本文の Test plan にあった grep 結果は lib / uv.lock を取りこぼしており、誤りでした。

詳細

#	指摘元	対象	重要度	対応
1	codex (inline) / gemini (body)	lib/devbase/__init__.py:3, lib/devbase/cli.py:17, lib/devbase/commands/status.py:13, uv.lock:44	major / 正確性	修正済み
2	codex (inline) / gemini (body)	CHANGELOG.md 末尾の参照定義	minor / ドキュメント	修正済み
3	gemini (body)	docs/user/env-export-import.md:77	minor / ドキュメント	修正済み

• 1: __version__ 実体と 2 箇所の ImportError fallback を 3.0.0 へ同期。uv lock でローカルパッケージ版数も更新し、uv lock --check が通る状態に戻しました。再解決時に exceptiongroup の typing-extensions marker が無関係に書き換わったため、そのハンクのみ差し戻して uv.lock の差分を版数 1 行に限定しています (差し戻し後も uv lock --check green)。
• 2: [3.0.0]: .../compare/v2.2.0...v3.0.0 を追加し、[Unreleased] の比較開始点を v3.0.0 へ。[2.2.0] 以前は履歴のため据え置き。
• 3: manifest サンプルの devbase_version を 3.0.0 へ。

意図的に据え置いた箇所

• docs/user/plugin-registries.md:7「devbase v2.2.0 以降、「公式レジストリ」固定の概念は廃止されました」— 当該仕様が導入された版を指す履歴記述であり、現行版数ではないため変更しません。
• CHANGELOG.md の [2.2.0] 以前のセクション、issues/old/PLAN03-1.md — いずれも履歴。

検証

$ uv run pytest
1371 passed in 46.20s
$ uv lock --check
Resolved 23 packages # 差分なし
$ uv run python -c "..."
init 3.0.0 cli 3.0.0 status 3.0.0
$ grep -rn "2\.2\.0" docs README.md lib bin pyproject.toml uv.lock
docs/user/plugin-registries.md:7: # 履歴記述のため意図的に据え置き

@codex@gemini 再レビューをお願いします。

[takemi-ohama]

🤖 cross-review | round 2 | codex | APPROVE

版数・lockfile・リリース履歴の同期に修正が必要な問題はありません。

[takemi-ohama]

🤖 cross-review | round 2 | gemini | REQUEST_CHANGES

v3.0.0 の破壊的変更 (PLAN32) に伴うドキュメントの更新漏れがあります。新規ユーザーがチュートリアル通りに実行するとエラーになる状態のため、リリース前に修正をお願いします。

• [critical / 正確性] docs/plugin-dev/quickstart.md: project.yml への更新漏れ
  CHANGELOG に「プロジェクト設定を project.yml へ移行する破壊的変更を含みます」とありますが、本ファイルの「2.3 env ファイルの作成」セクション（76行目付近）が旧仕様（env ファイルに GIT_USER 等を書く内容）のままです。v3.0.0 では project.yml がないと up 時にエラーになるため、チュートリアルを project.yml を作成する手順に更新してください。ディレクトリ構成ツリー（34行目付近）の修正も必要です。

• [major / 網羅性] docs/plugin-dev/plugin-yml-reference.md: requires 定義の不足
  CHANGELOG でプラグイン側の requires.devbase: ">=3.0.0" 更新が必須とアナウンスされていますが、リファレンスのフィールド一覧に requires に関するスキーマ定義や説明が記載されていません。ユーザーが正しく設定できるよう追記が必要です。

• [major / 正確性] docs/plugin-dev/quickstart.md: plugin.yml サンプルへの requires 追記
  上記に関連し、本ファイルの「1.2 plugin.yml の配置」（23行目付近）にあるサンプルコードにも requires: ... のセクションを追記し、ユーザーがコピペしても新しい必須要件を満たせるようにしてください。

[takemi-ohama]

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

対応件数: critical=1 / major=2 / minor=0 (合計 3 件)
deferred: 1 件 / rejected: 0 件
commit: 94f6fea (merge) / 028175a (docs)
CI: NONE (このブランチに登録された check はありません)

round 2 は gemini のみ REQUEST_CHANGES で、指摘はレビュー body の 3 点（インラインなし）でした。3 点とも妥当と再判定し、すべて対応しています。

詳細

#	指摘元	対象	gemini 判定	独自再判定	対応
1	gemini (body)	docs/plugin-dev/quickstart.md が旧 env 仕様のまま	critical / 正確性	critical 妥当	対応済み（#108 を merge）
2	gemini (body)	docs/plugin-dev/plugin-yml-reference.md に requires の説明が無い	major / 網羅性	major 妥当	対応済み
3	gemini (body)	quickstart.md 1.2 の plugin.yml サンプルに requires が無い	major / 正確性	major 妥当	対応済み

---

1. quickstart.md の project.yml 移行漏れ — 指摘のとおりでしたが、修正自体は同じ release/PLAN32 を base とする PR #108 (feature/PLAN32-docs) で既に済んでいました。本 PR だけを見ると未修正に見えてしまうため、feature/PLAN32-docs を本ブランチへ merge して同一ブランチ上で整合させています (94f6fea)。

現在の quickstart.md は以下の状態です。

• 2.1 ディレクトリ構成ツリー: project.yml を含む
• 2.3: 「project.yml の作成」（旧「2.3 env ファイルの作成」を置き換え）
• 2.3.1: env は「コンテナへ渡す環境変数」のみを持つ旨に変更
• GIT_USER / GIT_REPO / WORK_DIR / CONTAINER_SCALE の記述は残っていません

CHANGELOG.md は merge でコンフリクトしたため union で解決しました（[3.0.0] 見出し + 注記は本 PR 側、project.yml 移行の ### Changed は #108 側）。[2.2.0] 以前の履歴記述は変更していません。

2 / 3. requires の文書化 — 追記にあたって実装 (lib/devbase/plugin/syncer.py の load_plugin_info) を確認したところ、リファレンスとクイックスタートが載せていた plugins[] 配列 + projects[] 列挙の構造は、実装のどこからも読まれていませんでした。

# lib/devbase/plugin/syncer.pyreturnPluginInfo(
name=data.get('name', plugin_dir.name),
version=data.get('version', '0.1.0'),
description=data.get('description', ''),
priority=data.get('priority', 0),
requires_devbase=data.get('requires', {}).get('devbase') ifisinstance(data.get('requires'), dict) elseNone,
)

実際の plugin.yml はフラット形式で、プロジェクトは projects/ 配下のディレクトリから自動検出されます (discover_projects)。ドキュメントどおりに書いた plugin.yml は name がディレクトリ名、version が 0.1.0 に落ちるだけで、plugins[] の中身は無視されます。

旧構造のまま requires だけ足すと誤った位置を案内してしまうため、スキーマ記述を実装に合わせて訂正した上で追記しました。

• plugin-yml-reference.md
  • 基本構造・フィールド一覧・使用例をフラット形式へ訂正（name / version / description / requires.devbase / priority の 1 表に統合、既定値の列を追加）
  • requires の詳細節を追加 — 「devbase 本体の最低バージョン。project.yml 形式のプロジェクト定義は devbase 3.0.0 以降でしか読めないため、project.yml を持つ Plugin は ">=3.0.0" を指定する」。要件を書かずに 2.x へ入れるとインストールは通るのに devbase up で初めて失敗する、という理由も明記
  • priority の詳細節を追加（衝突時は projects/<name>.<owner>--<repo> へ退避）
  • 「プロジェクトの検出」節を追加（plugin.yml に列挙不要）
  • 「1 リポジトリに複数 Plugin」を registry.yml を使う実際の構成へ差し替え
  • 実在しないエラーメッセージ (Invalid plugin name / Duplicate project name 等) を並べていたバリデーション表を、実際に送出される PluginError へ訂正
• quickstart.md 1.2: サンプルをフラット形式 + requires.devbase: ">=3.0.0" へ更新し、自動検出と requires の意味をポイントとして併記

deferred

• quickstart.md に registry.yml の作成手順が無い — 「4.2 レジストリへの登録」の devbase plugin repo add はリポジトリルートの registry.yml を要求します (No registry.yml found in repository) が、1.x の手順に作成ステップがありません。本 PR (版数引き上げ) の範囲を超え、3.0.0 の破壊的変更とも独立した既存の不足のため、別 PR とします。

検証

$ uv run pytest
1371 passed in 45.18s
$ uv run python -c "load_plugin_info(<リファレンス記載のサンプル>)"
PluginInfo(name='my-plugin', version='1.0.0', description='サンプルプラグイン',
priority=0, requires_devbase='>=3.0.0')
$ git ls-remote origin feature/PLAN32-version
028175a26f4aa5f7cb826e336a5c0659bf009a24 refs/heads/feature/PLAN32-version

記載サンプルが実装のローダを実際に通り、requires_devbase が取れることを確認しています。

Note: 本 PR は feature/PLAN32-docs (#108) を取り込んだため、diff に #108 の変更が含まれます。#108 が先に merge されれば解消します。

@codex@gemini 再レビューをお願いします。

[takemi-ohama]

（上のサマリの補足）セルフレビューで見つけた 2 点を 2165ad6 で追加修正しました。ブランチ先端は 2165ad6 です。

• name の説明が「バリデーションルール」となっていましたが、実装に名前の検証は無いため「命名規則（推奨）」へ改め、省略時はディレクトリ名が使われることを追記
• version サンプルの引用符の有無を基本構造の例と統一

uv run pytest は 1371 passed のままです。

[takemi-ohama]

🤖 cross-review | round 3 | codex | APPROVE

修正が必要な指摘はありません。

[takemi-ohama]

🤖 cross-review | round 3 | gemini | APPROVE

変更内容を確認しました。project.yml の導入 (PLAN32) に伴う各モジュールの変更、マイグレーション機能 (migrate-config)、entrypoint.sh の複数リポジトリ対応などすべて目的通り設計・実装されています。境界値やエラーハンドリングに関するテストも十分に書かれており、懸念点はありません。