| name | audit-agent-dock-release |
| description | Agent Dockのリリースを前版タグとの差分で監査し、README、VISION、DESIGN、DEPENDENCIES、リリース文書、実装、テストの整合性と文書内重複、テスト過不足を独立クロスチェックする。リリース前確認、リリース可否判定、リリース文書の仕上げ、回帰範囲確認を依頼されたときに使う。 |
Agent Dockのリリース監査
前回のリリースタグからリリース候補までを一つの監査単位として扱う。
主担当、Claude、サブエージェントが同じcommit範囲を独立に確認し、リリース可否を根拠付きで決める。
比較範囲を固定する
jj status で作業ツリーの状態を確認する。- 前回のリリースタグとリリース候補を、40桁のcommit IDへ解決する。
- 以後の依頼と報告へ、始点、終点、次の確認コマンドを記載する。
jj diff --from <previous-commit> --to <target-commit>
@、Working Copy、短縮IDだけを監査範囲として渡さない。
監査中に終点が変わった場合は、旧結果を流用せず、新しい完全commit IDで再依頼する。
初期証拠は次のスクリプトで収集する。
cargo run --quiet --example collect-release-audit-evidence -- <previous-tag-or-commit> <target-revision>
文書を監査する
文書体系とリリース文書を突合する
READMEの「文書の役割と関係」を文書体系の正本として読み、README、VISION、DESIGN、DEPENDENCIES、対象リリース文書を差分だけでなく全文で確認する。
リリース文書の各決定を、VISIONの規範、DESIGNの責務、不変条件、非目標、版管理、テスト方針、DEPENDENCIESの横断方針へ対応付ける。
VISIONが長期的な規範、DESIGNが0.1.0の目標と設計上の制約、READMEが現在の利用方法、リリース文書が対象リリース時点の事実を述べる違いを保つ。
同じ語が現れるだけで矛盾とせず、主体、対象、時点、決定の効力が一致するかを確認する。
文書の配置について、特に次を確認する。
- VISION、DESIGN、DEPENDENCIESに、個別リリースの実装履歴、現在の完成状況、既知の不具合が混ざっていないか。
- READMEが現在の利用に必要な概要を示し、各版の詳細な履歴をリリース文書へ委ねているか。
- リリース文書が、対象版で採択していない将来仕様や新しい規範を導入していないか。
- ファイル、関数、データ構造、一時的な実装順序が、理由のない設計上の制約として残っていないか。
- 未決事項やIssueの内容を、採択済みの規範、設計、成立済みの挙動として扱っていないか。
内部実装を同じ外部挙動のまま置き換えたときに古くなる記述は、設計上の制約として残す理由が示されているかを確認する。
理由がなければ、実装詳細または成立時点の事実として適切な正本へ移すfindingを出す。
製品の不変条件について、特に次を確認する。
- ユーザー承認前に実行またはイベント記録が始まらないか。
- 訂正が既存イベントの変更ではなく、新しいイベントの追記になっているか。
- ユーザー判断だけが受け入れ判定の教師信号になっているか。
- スコアカードの各母集団がDESIGNの軸と矛盾しないか。
- DESIGNで未実現とした自動評価や再審査を、ユーザー操作による判定訂正と混同していないか。
文書内と文書間の重複を確認する
README、VISION、DESIGN、DEPENDENCIES、リリース文書を個別に読み、同じ決定や事実が複数箇所で正本のように定義されていないかを確認する。
概要、責務、不変条件、具体的挙動のように役割が異なる記述は重複としない。
同じ条件、例外、母集団、優先規則を別々の表現で再定義している場合は、片方へ集約する。
実装を監査する
リリース文書の文ごとに、実装箇所とテストを対応付ける。
正常系だけでなく、無変更終了、入力中断、並行更新、端末制御文字、古い履歴、対象消失を確認する。
DESIGNの不変条件は、今回変更した機能が破っていないことを確認する。
リリース文書にない実装上の決定が公開挙動になっている場合は、文書不足として扱う。
テストの過不足を監査する
前版から追加、削除、改名されたテストを列挙し、次の基準で判定する。
- 採択中の仕様、不変条件、実際に発生した事故を固定しているか。
- 将来仕様や一時的なhelper構造を固定していないか。
- 同じ失敗を複数の長いテストで重複して確認していないか。
- parser、永続化、表示を個別に確認するだけで、対話や状態遷移の接続部分を取りこぼしていないか。
- 無書込で終わる経路と、並行更新後の再確認を検証しているか。
テスト数だけで過剰または不足を判断しない。
一つの表駆動テストや状態遷移テストへまとめられる場合は、テスト関数を増やさずに主要経路を固定する。
独立クロスチェックを行う
Claudeと少なくとも一つのサブエージェントへ、同じ始点、終点、四つの監査項目を渡す。
四つの監査項目は、文書間の整合、文書内の重複、文書と実装の整合、テストの過不足とする。
主担当の結論や疑っている箇所を先に教えず、DESIGN、リリース文書、差分、テストを一次資料として渡す。
各結果には次を要求する。
- findingの重大度、根拠ファイルと行、影響、推奨対応。
- 問題なしと判断した項目の根拠。
- 対象commit上で実行した検証と、その制約。
- 作業中に発生した問題のリポジトリ外記録。
結果が食い違う場合は、対象commitと根拠行を再確認し、推測で多数決を取らない。
検証とリリース判定
リリース候補と同一内容の作業ツリーで次を実行する。
共有Working Copyが監査対象と異なる場合や、並行作業で更新され得る場合は、共有Working Copyを切り替えない。
mktemp -dで専用ディレクトリを作り、固有のworkspace名を指定したjj workspace add --name <name> -r <target-commit> <directory>で対象commitから一時workspaceを作成して検証する。
検証後は元のworkspaceからjj workspace forget <name>を実行し、作成した明示的な一時ディレクトリだけを片付ける。
cargo fmt --check
cargo test --all-targets
cargo clippy --all-targets --all-features -- -D warnings
リリース可とする前に、次を満たす。
- 文書間の矛盾がない。
- 文書内に競合する正本や不要な重複がない。
- リリース文書の主張に実装が対応している。
- 主要な状態遷移と不変条件に、過剰でない回帰テストがある。
- 主担当、Claude、サブエージェントのfindingを統合した。
- 検証コマンドが成功した。
- 作業中の問題をリポジトリ外へ記録した。
findingを重大度順に報告し、リリース阻害か、リリース前に直すLow findingか、後続Issueへ送る観察事項かを明記する。
