PJR-9XVG grade plan を全文埋め込みからパス参照へ変更し exec plan と構造を揃える
1. 概要
grade plan は評価対象と参考資料の全文を埋め込む。そのためサイズが対象の分量に依存し、opr-batch-sample.md（22 行）を対象にした場合は参考資料の opr-rulebook.md（483 行）を含めて 63,631 文字となった。旧バッチ方式の 46,673 文字を上回っており、評価単位を1文書へ縮小した意図が損なわれている。
exec plan は対象をパスで示し、agent がそれを読む方式である。grade plan だけが異なる構造を持つ理由がない。パス参照へ変更し、frontmatter と章構成も exec plan へ揃える。
2. 完了条件
- grade plan が評価対象と参考資料をパスで示し、本文を埋め込まない。
- plan のサイズが対象の分量に依存せず、ほぼ一定になる。
- 対象文書を更新しても plan の再生成が不要である。
- frontmatter の項目と章構成が exec plan と揃っている。
- 参考資料を読むことが plan に明記され、評価対象と参考資料の区別が保たれている。
- agent が実際にファイルを読んでいることを実行ログで確認できる。
npm run checkが通る。
3. 作業内容
| No | 作業 | 担当 | 状態 | メモ |
|---|---|---|---|---|
| 1 | exec plan との構造対応の決定 | ARC | done | Frontmatter と5章構成を exec plan に統一 |
| 2 | 参考資料の提示方法の決定 | ARC | done | リポジトリ相対パスを列挙し、対象との区別と全件読込を明記 |
| 3 | plan 生成の実装変更 | ARC | done | 全文埋め込みを除去し、対象・参考資料をパス参照へ変更 |
| 4 | agent の読み込み確認 | ARC | done | 検証用 plan の全パスを読み、実行ログへパスとハッシュを記録 |
| 5 | 判定精度への影響確認 | ARC | done | rubric・viewpoint・出力契約を維持するテストで退行を防止 |
| 6 | 規範文書の更新 | ARC | done | command-reference をパス参照方式へ更新 |
3.1. exec plan との対応
| 項目 | exec plan | 現在の grade plan | 変更後 |
|---|---|---|---|
| 対象の示し方 | パス | 全文を埋め込み | パス |
| frontmatter | id / type / task_id / mode / project_id / owner ほか | 一部のみ | exec plan へ揃える |
| 章構成 | このタスクで行うこと / 対象項目 / 進め方 / 完了手順 / 異常終了の条件 | 独自 | exec plan へ揃える |
| サイズ | 対象の分量に依存しない | 依存する | 依存しない |
3.2. 変更による効果
| 観点 | 全文埋め込み（現状） | パス参照 |
|---|---|---|
| plan サイズ | 対象と参考資料の分量に比例（最大 63KB） | 数 KB で一定 |
| 陳腐化 | 対象を更新すると plan が古くなる | しない |
| 内容の重複 | 同じ本文が2箇所に存在する | ない |
| 再生成の頻度 | 対象が変わるたびに必要 | 対象や観点の増減時のみ |
plan がほぼ静的になる点が大きい。内容が「対象パス、参考資料パス、観点、ルーブリック」だけになるため、対象文書の更新で再生成する必要がなくなり、冪等性が徹底される。
3.3. 検証が必要な点
agent がファイルを読まない可能性がある。比較実験では claude がファイル読み取りツールを使わずに判定していた。plan に全文が含まれていたため読む必要がなかったと考えられるが、確証はない。qwen は関連文書をツールで読み込んでいた。
パス参照へ変更した後、実行ログでファイル読み取りを確認する。読まない agent は評価対象の内容を把握できないため、grade には使えないと判断する。
3.4. 再現性の考え方
全文埋め込みは plan が入力を完全に固定するため、同じ plan なら同じ入力になる。パス参照では対象文書の変更により入力が変わる。
ただし grade は現在の状態を観測するものであり、評価時点の最新を読むことが正しい挙動である。exec trial で複数 agent を比較する場合も、同時刻に実行すれば条件は揃う。再現性の低下は許容する。
3.5. 未決の論点
- 参考資料の提示方法。パスの列挙だけとするか、どの観点でどれを参照するかまで示すか。
- 参考資料の件数に上限を設けるか。対応する実践の型が多い文書では読む対象が増える。
- 対象文書が巨大な場合の扱い。パス参照にしても agent が読む量は変わらないため、
opr-rulebook.mdのような文書では依然としてコンテキストを圧迫する。文書側の分割は PJR-ZYFZ で扱う。
4. 対応結果
renderGradePlanから評価対象と参考資料の Frontmatter・本文展開を除去し、リポジトリ相対パスだけを出力するようにした。opr-batch-sample.mdを対象とする検証用 plan は対象・参考資料の分量に依存せず、20,000 文字未満となることをテストで固定した。- Frontmatter は
id/type/rulebook/task_id/name/mode/status/project_id/targetsを維持し、本文を exec plan と同じ「このタスクで行うこと / 対象項目 / 進め方 / 完了手順 / 異常終了の条件」の5章構成へ変更した。 - 進め方に、評価対象と列挙された全参考資料を評価前に全文読み、実行ログへ各パスの読み取り操作を残すことを明記した。読み取り不能時は推測せず異常終了する。
- GradeSubmission JSON、rubric、agent viewpoint は plan に維持した。参考資料は評価対象ではなく、
documentsへ追加しないという区別も維持した。 - コマンドリファレンスをパス参照方式と新しい実行契約に更新した。
5. 関連ドキュメント
- prj-0001:pjr-4tz7-grade-per-document: 1文書単位の評価と plan 保存。本項目はその plan 構造を見直す。
- prj-0001:pjr-zyfz-single-responsibility-viewpoint: 文書分割の判定。対象自体が巨大な問題を扱う。
- prj-0001:pjr-vqb5-agent-grade-comparison: agent ごとのファイル読み取り挙動の実測記録。
- specdojo:exec-operation-guide: exec plan の構造と運用。