設計(PLAN64): 機密の参照の見出しにグループの読み替えの前後を出す (#188)

[takemi-ohama]

Summary

#188（env backend test と env list の見出しが、グループ名を読み替え前だけで出す）の設計。
設計文書だけを載せる。lib/ は変えない。

• 要求と受け入れ条件: issues/PLAN64_secret-label-group.md
• 設計: issues/PLAN64_secret-label-group-design.md

base は release/v3.7.0（release Pull Request #212）。モードは standard。

決めたこと

issues/PLAN64_secret-label-group-design.md

• 決定 1: グループの表示の責務を label() の契約へ寄せる（issue の move_responsibility を採る）
• 決定 2: label() の既定の返り値は変えない
• 決定 3: 見出し用の表示を作る口を SecretStore.display_label の 1 つに置く
• 決定 4: env backend migrate の 2 つの一覧も直す
• 決定 5: env encrypt / env decrypt / env rekey の一覧は直さない
• 決定 6: 確定仕様は、どちらか一方を消さずに「文言の種類で分ける」形で解く
• 決定 7: 一覧の桁幅を変えない

Test plan

設計の段階で確かめたこと。

• label() の呼び出しを実測した。grep -rn "\.label()" lib/ → 52 件 / 10 ファイル（issue 本文と一致）。
  内訳は、読み替えのあるグループを持ちうる見出し 5 件（issue 本文の「2 か所で足りる」は実測と合わない）/
  参照が常にグループを持たない見出し 3 件 / エラー文言・警告・ログ・巻き戻しの説明 43 件 / docstring の言及 1 件
• config.openbao が None になる条件を _openbao_from_dict（lib/devbase/env/backend_config.py）で確かめた。
  backend: age でも openbao: 節が残っていれば None にならないため、config.openbao の None で
  backend の種類を判定してはならない。表示の分岐は SecretStore.storage_group に任せる
• OpenBaoSettings.display_group が storage_group 経由で BackendConfigError を送出しうることを確かめた
  （_validate_group_name / _check_reserved）。label() を通すエラー文言の経路では呼ばない設計にした
• _project_group_mismatch（lib/devbase/commands/env.py）が display_group を直接呼び、-p の拒否の
  エラーに今も default → nyle を出すことを確かめた。この文言は対象外（変えない）
• layout: flat でグループ付きの参照を拒む例外を出すのは OpenBaoBackend._check_group
  （OpenBaoSettings.path_of ではない）ことを確かめた
• 桁あふれを実測した。プロジェクト 'carmo-ai'（グループ default） は 31 文字で、env backend test の
  :<28 を読み替えの無い状態でも既に超えている。桁幅は変えない
• env encrypt / env decrypt / env rekey の一覧が組む参照は group= を渡さず ref.group が常に None
  であることを確かめた（env_migrate.py:85-94、env_ops.py:56-63）。対象から外した
• 読み替えのあるグループの fixture が既にあることを確かめた
  （tests/conftest.py の configure_openbao(group_aliases=...)、tests/commands/test_env_user_axis.py の grouped）
• 「変わらないこと」を既存テストでは確かめられないことを確かめた。 env list の見出しを固定している
  既存の assert は '=== グローバル' の前方一致（tests/commands/test_env_user_axis.py:229-253）で、
  見出しに （グループ default → nyle） が付いても通る。受け入れ条件 5・6 は新規の出力テストへ変えた
• 実装とテストは次の Pull Request で行う（この Pull Request には含めない）

検証していないこと

この Pull Request では CI が 1 件も動かない（.github/workflows/ci.yml の対象が main だけ。#216）。
設計文書だけの変更のため、実行する検査も無い。

ドキュメント再構成の前後

指標	要求（前）	要求（後）	設計（前）	設計（後）
結論が定義される位置	11 行目	11 行目	1 行目	1 行目
平均文長	74.4 字	66.0 字	60.6 字	49.1 字
最長文	294 字	294 字	283 字	129 字
章の数	11	11	10	10
行数	222	236	301	323

「後」はレビューの 5 ラウンドを終えた時点の値である（再構成の直後は要求 222 行 / 設計 318 行で、
差はレビューの指摘 9 件の反映による）。

行数の増減の内訳: 設計は再構成で +17 行（「変えないもの」の列挙を表へ、決定 6 の 3 項目を表へ、
テスト設計の道具の列挙を表へ置き換えた）、レビューで +5 行。要求は再構成で差し引き 0 行
（## 依頼（原文） を末尾へ移し、長い文を分けた分を同じ数だけ詰めた）、レビューで +14 行。

目安を超えた項目:

• 要求の最長文 294 字（目安 100 字）。理由: 受け入れ条件の 1 項目は 前提 / 操作 / 結果 / 検証 を
  句点なしで並べる形で、requirements-design の受け入れ条件の雛形と PLAN61・PLAN62 がこの形を採っている。
  1 項目全体が 1 文として数えられる。採らなかった直し方: 項目ごとに句点で区切る（同じまとまりの既存文書と形が変わる）
• 要求の最長文（受け入れ条件を除いた散文だけ）は 120 字。理由: 括弧の中が型注釈とファイルのパスで占められている。
  採らなかった直し方: パスを別の行へ出す（どの行の話かが読めなくなる）
• 設計の最長文 129 字。理由: 括弧の中が 2 つのファイルのパスである。採らなかった直し方: 2 文に分ける
  （同じ動詞を 2 度書くことになる）
• 要求の「結論が定義される位置」が 11 行目なのは、1〜9 行目が題名・対象 issue・モードの根拠・base の参照であるため

範囲外として起票したもの

• env_migrate.Target.label に消費側が無い（デッドコード） #222 — env_migrate.Target.label に消費側が無い（デッドコード）

参照: #188 / #212 / #216

[takemi-ohama]

🤖 cross-review | round 1 | kiro | APPROVE

設計文書のみの PR。lib/ の実コードに対して主要な主張（SecretRef.label()=secret_store.py:151、SecretStore.storage_group/ref_group/same_storage_group、OpenBaoSettings.display_group/storage_group/path_of、_group_of が ref.label() を使う点、cmd_env_backend_test=env_backend.py:472 の :<28、migrate 完了行 594 の :<24、_MigrationPlan._heading、cmd_env_list/_group_suffix、env_migrate.py:85-94/env_ops.py:56-63 が group= 無しで参照を組む点、.label() 52 件/10 ファイル）を実測で照合し、いずれも一致。文言分割（見出し=display_label、エラー/ログ=引数なし label()）の切り分けと桁幅据え置きの根拠も整合している。修正を要するアクションは見つからなかった。

[takemi-ohama]

🤖 cross-review | round 1 | agy | REQUEST_CHANGES

要求・設計ドキュメントにおける既存仕様との整合性、テスト対象クラス名、および影響範囲の記述について 3 点の修正提案を行います。

[takemi-ohama]

🤖 cross-review fix | round 1

agy の REQUEST_CHANGES 3 件をすべて受け入れ、commit d4b97ad で反映しました。kiro は APPROVE（指摘 0 件）です。

対応の内訳

	件数
対応（fixed）	3
見送り（deferred）	0
却下（rejected）	0

重要度別: major 1 件 / minor 2 件

各指摘への対応

#	重要度	ファイル	対応
1	major	issues/PLAN64_secret-label-group.md	受け入れ条件 7 の例示を、実際に SecretRef.label() の既定を使う 2 つの文言（OpenBaoBackend._check_group と runtime.py の DEVBASE_ACCOUNT_GROUP の警告）へ差し替え。display_group を直接呼ぶ文言（_project_group_mismatch）は意図的に読み替えの前後を出すため、対象範囲の「含まない」と設計の決定 2 に区別を明記
2	minor	issues/PLAN64_secret-label-group-design.md	テスト設計 7 の参照先を OpenBaoSettings.path_of から OpenBaoBackend._check_group（lib/devbase/env/openbao.py）へ修正
3	minor	issues/PLAN64_secret-label-group.md	「影響」の公開インタフェースの行に env backend migrate（計画の一覧と --to age の完了表示）を追記

検証

設計文書のみの Pull Request で lib/ の変更を含まないため、テストの追加・実行はありません。.github/workflows/ci.yml の対象は main のみで、この Pull Request では CI は動きません。

未解決のレビュースレッドは 0 件です。

🤖 Generated with Claude Code

[takemi-ohama]

🤖 cross-review | round 2 | codex | REQUEST_CHANGES

修正指摘 2 件（minor 2 件）。

[takemi-ohama]

🤖 cross-review | round 2 | kiro | APPROVE

設計文書のみの PR。lib/ は未変更で、記載どおり。参照する行番号・メソッドの挙動・件数・桁幅（:<28 / :<24）・エラー文言の位置（_check_group L152/163/167、runtime.py L220）・_project_group_mismatch が display_group を使う点・env encrypt/decrypt/rekey の参照が group=None になる点（_select_refs / _encrypted_refs）・決定 4 の migrate 2 一覧（L594 / _MigrationPlan._heading L705）を実コードで照合し、いずれも一致。docs/specifications/secret-backend.md の自己矛盾（L285 vs L304-305）と with 例（L339）も実在を確認。設計の内外の整合が取れており、修正アクションを要する箇所は見つからなかった。

[takemi-ohama]

🤖 cross-review fix | round 2

codex の REQUEST_CHANGES 2 件をすべて受け入れ、commit 096c8ac で反映しました。kiro は APPROVE（指摘 0 件）です。

対応の内訳

	件数
対応（fixed）	2
見送り（deferred）	0
却下（rejected）	0

重要度別: minor 2 件

各指摘への対応

#	重要度	ファイル	対応
1	minor	issues/PLAN64_secret-label-group.md	前提 2 を書き直した。_openbao_from_dict は backend: age でも openbao: 節が残れば設定を返すため、「ファイル backend では config.openbao が常に None」は誤り。config.openbao が None かどうかで backend の種類を判定してはならないを先に置き、None になるのは節が無く version: 1 のときだけである旨に直し、表示の分岐は SecretStore.storage_group(ref.group) に任せる形へ揃えた。設計文書の決定 3 の根拠にも同じ注意を足し、受け入れ条件 6 のテストがこの取り違えをそのまま検査する形にした
2	minor	issues/PLAN64_secret-label-group-design.md	受け入れ条件 5・6 の検証を、既存テストの通過から新規の出力テストへ変えた。既存の assert は '=== グローバル' の前方一致（tests/commands/test_env_user_axis.py:229-253）で、見出しに （グループ default → nyle） が付いても通るため「変わらないこと」を確かめられない。条件 5 は configure_openbao(layout='flat') で cmd_env_list と cmd_env_backend_test を呼び出力全体に （グループ が 1 つも出ないことを見る新規テスト、条件 6 は backend: age に openbao: 節を残した設定で同じことを見る新規テストにした。既存テストの通過は追加の確認として残し、理由を設計文書のテスト設計の前置きに書いた

検証

設計文書だけの Pull Request で lib/ の変更を含まないため、テストの追加も実行もありません（ci.yml の対象は main のみで CI も動きません）。受け入れ条件に書いたテストは実装 Pull Request で置きます。

未解決のレビュースレッドは 0 件です。

🤖 Generated with Claude Code

[takemi-ohama]

🤖 cross-review | round 3 | codex | REQUEST_CHANGES

確定仕様の書き換え指示について、修正提案1件です。

[takemi-ohama]

🤖 cross-review | round 3 | agy | REQUEST_CHANGES

PLAN64の要求仕様および設計方針はコードベースの実装・制約とよく整合していますが、ドキュメント末尾のアーティファクトタグの残存、および env backend migrate 完了表示に対する受け入れ条件・テスト設計の網羅性に修正が必要です。

[takemi-ohama]

🤖 cross-review fix | round 3

codex の REQUEST_CHANGES 1 件と agy の REQUEST_CHANGES 2 件をすべて受け入れ、commit 8cd1800 と 8638814 で反映しました。

対応の内訳

	件数
対応（fixed）	3
見送り（deferred）	0
却下（rejected）	0

重要度別: minor 3 件

各指摘への対応

#	重要度	ファイル	指摘	対応	commit
1	minor	issues/PLAN64_secret-label-group-design.md:280	決定 6 の「エラー文言とログを除く」が、_project_group_mismatch が display_group を使って set -p --group with の拒否エラーにも default → nyle を出す既存の仕様・テストと矛盾する	決定 6 の表の当該行を「除くものを引数なしの SecretRef.label() で参照を表示するエラー文言・ログに限る。display_group を直接呼ぶ文言はエラーであっても前と後を出す」へ直した。機能一覧 F2 と要求文書の「矛盾が解ける」の行にも同じ分かれ目を明記	8638814
2	minor	issues/PLAN64_secret-label-group-design.md:324	ファイル末尾に不要なタグ </content> が残っている	当該行を削除。文書 2 本に他の残骸が無いことも grep で確認（0 件）	8cd1800
3	minor	issues/PLAN64_secret-label-group.md:93	env backend migrate --to age の完了後の一覧の見出しの検証が、受け入れ条件 3 もテスト設計も --dry-run の計画一覧だけになっている	受け入れ条件 3 を「計画の一覧と完了後の『サーバ上の機密はそのまま残っています』の一覧の両方を見る／新規テスト 2 件」へ直し、テスト設計にも dry_run=False（偽サーバ）で完了表示の見出しを見る手順を追加。2 つは別の関数（_MigrationPlan._heading と cmd_env_backend_migrate の完了表示）が出す旨も明記	8cd1800

検証

設計文書だけの Pull Request で lib/ の変更を含まないため、CI は 1 件も動かず、テストの追加・実行もありません。文言の確認のみ:

$ grep -n "</content>\|</invoke>" issues/PLAN64_secret-label-group*.md
（一致なし）

未解決のレビュースレッドは 0 件です（round 1 の 3 件・round 2 の 2 件・round 3 の 3 件すべて Resolve 済み）。

🤖 Generated with Claude Code

[takemi-ohama]

🤖 cross-review | round 4 | kiro | APPROVE

設計・要求の 2 文書を対象に、引用されているシンボル・行番号・振る舞い（SecretRef.label():151、_group_of が label() を使う点、display_group→storage_group の失敗経路、env_backend.py:472/594/703-705 の見出し、_select_refs/_encrypted_refs が group= を渡さない点、test_env_user_axis.py の前方一致 assert が「変わらないこと」を検査できない点）を worktree の実コードで照合し、いずれも一致を確認した。label() 件数の 52/10 も、.pyc を除いたソース基準では整合。実装との不整合・古い参照・文書間の矛盾は見つからず、修正アクションはない。

[takemi-ohama]

🤖 cross-review | round 4 | agy | REQUEST_CHANGES

要求文書と設計文書のテスト設計における受け入れ条件 7 の検証対象に不整合があります。インラインコメントの修正提案をご確認ください。

[takemi-ohama]

🤖 cross-review fix | round 4

agy の REQUEST_CHANGES 1 件を受け入れ、commit c22c9cf で反映しました。kiro は APPROVE（指摘 0 件）です。

対応の内訳

	件数
対応（fixed）	1
見送り（deferred）	0
却下（rejected）	0

重要度別: minor 1 件

各指摘への対応

#	重要度	ファイル	指摘	対応	commit
1	minor	issues/PLAN64_secret-label-group-design.md:309	テスト設計 7 が、要求文書の受け入れ条件 7 が挙げる 2 つの文言のうち例外文言だけを書いており、置き場の DEVBASE_ACCOUNT_GROUP の警告が漏れている	テスト設計 7 の「何で確かめるか」を、要求文書の受け入れ条件 7 と同じ 2 つ（OpenBaoBackend._check_group の例外と lib/devbase/env/runtime.py の警告）を名指しする形へ直した	c22c9cf

テスト

設計文書だけの Pull Request で lib/ の変更を含まないため、テストの追加・実行はありません。CI も動きません。

スレッド

未解決だった 1 件に reply を付けて Resolve しました。round 1〜3 の 8 件は既に対応済みで、未解決のスレッドは残っていません。

🤖 Generated with Claude Code

[takemi-ohama]

🤖 cross-review | round 5 | codex | APPROVE

設計文書と関連実装を照合し、修正が必要な指摘はありません。

[takemi-ohama]

🤖 cross-review | round 5 | kiro | APPROVE

設計文書 2 件のみの変更。要求と設計の決定が整合し、コード参照（label() 52 件/10 ファイル、storage_group/display_group の挙動、_MigrationPlan._heading の server_store 経由、_group_suffix の従属関係、桁幅 :<24/:<28/:<40、_group_of が label() を使う点）を worktree のコードで実測確認した。いずれも一致し、誤りや実装との齟齬は見つからなかった。修正アクションはない。