trace-grader

スキル：trace-grader

エージェントの出力だけでなく、軌跡を評価します。実行が不適切な経路を通って正しい答えを返すことがあります（強制プッシュ、リトライの嵐、読んでいないファイルの編集など）。これは「破損した成功」です。また、再実行で失敗する不安定な実行もあります。答えだけを確認するチェッカーではどちらも検出できませんが、TraceGrader は経路を調べます。

WHAT

目的とコンテキスト

• 目的： エージェントの答えだけでなく、エージェントの経路（ツールの選択、順序、リトライ、再現性、根拠）を評価し、CI でゲートできる確定的なシグナルによって「破損した成功」と不安定さを検出します。
• 使用するタイミング：
• 1 つ以上のエージェント実行（トレース）があり、答えに到達したかどうかだけでなく、どのように到達したかを知りたい場合。
• 再現性のゲート、つまり「このタスクは k 回の再実行すべてで成功するか？」（pass^k）が必要な場合。
• LLM ジャッジを使う前に、ツールの選択／順序／リトライ／ステップ予算について、決定的で CI のゲートに使えるシグナルが必要な場合。
• 対象外： 最終回答の品質は評価しません。設定が verified:false の間は、エージェント・アズ・ジャッジの軸を有効にしません（STUB、未呼び出し）。フラグが付いた実行は修正しません。

メンタルモデル

トレースのソース（traces.json · audit jsonl · session transcript）→ パーサー → run = [{step, tool, args, observation, ok}] → ルールチェック（config）+ pass^k → 実行ごとの判定（clean-pass · pass-with-warnings · corrupt-success · fail）→ corrupt/flaky の場合は exit 3。ルールのパラメーターは adapter harness/trace-grader.config.yaml にのみ記述します（詳細は下記の Reference を参照）。

入力と出力の契約

	フィールド	必須？	意味
入力	--traces / --audit / --transcript	はい（3 つのうち 1 つ）	canonical traces.json、audit jsonl（session_id ごとに 1 実行）、Claude Code セッションの transcript
入力	--task	audit/transcript を使う場合	pass^k の計算に使用するタスクを実行に割り当てます
入力	--json	いいえ	機械可読な出力
入力	harness/trace-grader.config.yaml	はい	禁止ツール、retry_threshold、step_budget、order_constraints、grounding.enabled
出力	実行ごとの判定 + フラグ + pass^k ブロック	はい	レポート
出力	終了コード	はい	corrupt-success またはタスクの不安定さがある場合は 3

ルールと機能

• RULE-01（必須）：ルールのパラメーターを記述する場所は config ファイルのみです。同じ推測値を 2 か所に記述するのは漏れです。
• RULE-02（必須）：推測したしきい値を検証済みとして提示してはいけません。検証されるまでは、ファイルを verified:false のままにします。
• RULE-03（必須）：エージェント・アズ・ジャッジの軸は、設定されて検証されるまでオフにし、呼び出してはいけません。推論によるスコアを捏造してはいけません。
• RULE-04（必須）：audit パーサーでは各ステップの ok／observation を確認できないため、audit ログだけでは retry_storm は発生しません。失敗を考慮したチェックが必要な場合は、完全な traces.json を使用してください。
• 機能：ローカルの trace/log/transcript ファイルを読み取ります。adapter config ファイルを 1 つ読み取ります。モデルは呼び出しません（judge はオフ）。レポート以外には何も書き込みません。

失敗の境界

• corrupt-success の実行があるか、pass^k = FAIL の場合 → exit 3（CI ゲートでは 失敗）になります。これはシグナルであり、ツールのエラーではありません。
• ソースが audit ログのみの場合 → 各ステップの ok／observation を確認できず、retry_storm は発生しません。そのため結果は 部分的 です。必要に応じて完全な traces.json を使用してください。
• Transcript に task-verdict がない場合 → run.ok は強制的に True になります。FLAGS を信頼し、返された verdict は信頼しないでください。
• しきい値を実際の trace でテストしていない場合 → verified:false のままにし、検証済みとして提示しないでください。

HOW

メインワークフロー

ステップ	種類	入力	アクション	出力／終了	失敗／次の処理
W01	deterministic	実行	トレースを収集します（traces.json または --audit／--transcript）	トレースソース	audit のみ → partial（B01）
W02	judgment	プロジェクト	境界を設定します：harness/trace-grader.config.yaml のみを編集します	config	—
W03	deterministic	trace + config	採点します：trace-grader.py を実行します	verdict + flags + pass^k、rc	rc 3 → W04
W04	judgment	レポート	シグナルに対応します：フラグが付いたステップを調査します／flaky なタスクは信頼できないものとして扱います	結論	—
W05	judgment	実際のトレース	（後で）adapter を検証してから verified:true に切り替えます	config verified	証拠が不十分 → false のままにします（B02）

各ステップの詳細（W01～W05 の唯一の信頼できる情報源）：

1. トレースを収集します。 上記のスキーマで traces.json を出力するか、--audit に hooklib.audit() の jsonl を指定します（session_id ごとに 1 回の実行）。
2. 境界を設定します。 harness/trace-grader.config.yaml のみを編集します — 禁止ツール、retry_threshold、step_budget、order_constraints を設定します。これらの値はすべてこのファイルだけに記述してください。
3. 採点します。 grader を実行し、実行ごとの verdict と flags、および pass^k ブロックを確認します。
4. シグナルに対応します。 corrupt-success = 正解だが、手順に問題または危険あり → フラグが付いたステップを調査します。pass^k = FAIL = flaky → 信頼して依存することはできません。
5. （後で）adapter を検証します。 実際のトレースに対してしきい値を検証してから、verified:true に切り替えます。その後に限り、agent-as-judge 軸の有効化を検討してください。

実行方法

# bundled 3-case self-test (clean / corrupt / flaky)
python3 harness/scripts/trace-grader.py --self-test

# grade canonical traces, an audit log, or a full session transcript; --json for machine output
python3 harness/scripts/trace-grader.py --traces traces.json
python3 harness/scripts/trace-grader.py --audit .claude/audit/<date>.jsonl --task my-task
python3 harness/scripts/trace-grader.py --transcript ~/.claude/projects/<proj>/<session>.jsonl --task my-task

いずれかの実行が corrupt-success であるか、いずれかのタスクが flaky の場合、終了コードは 3 になります（CI でゲートできるようにするためです）。

分岐

ID	種類	条件	動作	スキップ／失敗	再合流
B01	conditional_required	ソースが audit jsonl のみ	採点できますが、retry_storm は発生しません。制限を報告します	failure-aware が必要 → traces.json または --transcript に切り替えます	W03
B02	capability_optional	judge model が設定済み、かつ config が verified:true	その場合に限り、agent-as-judge 軸（judge_trajectory()）の有効化を検討します	不十分 → STUB、呼び出しません	W04

検証と停止

必須：python3 harness/scripts/trace-grader.py --self-test（clean／corrupt／flaky の 3 ケース）。verdict と終了コードは engine が決定します。レビューが必要：実際のトレースとしきい値を比較した後の verified:true への切り替え。W04 の後で停止します。W05 は後で実施するステップであり、実際のトレースがない場合は同じ実行内で行いません。

例

• 成功例： Read したことのないファイルを Edit したセッションで、python3 harness/scripts/trace-grader.py --transcript ~/.claude/projects/<proj>/<session>.jsonl --task my-task を実行すると、edited_without_read（medium）のフラグが付き、verdict は pass-with-warnings となり、フラグが付いたステップが示されます。
• 境界／失敗例： 同じタスクを 3 回実行して 1 回失敗 → pass^k = FAIL → 終了コード 3、タスクは flaky と見なされます。実行が正解を返しても forbidden_tool（force-push、high）がある場合 → corrupt-success、終了コード 3。

リファレンス — その内容（今すぐ構築できる部分とアダプター）

今すぐ構築できる部分 — 決定論的で、不明点はありません：

• トレーススキーマ（契約）： 1 つの実行 = {step, tool, args, observation, ok} のステップのリストです。
• パーサー： 正規の traces.json、llmwiki/.claude/hooks/hooklib.audit() が書き込む監査用 jsonl 形式（およびコードロガーの events.jsonl）、または完全な Claude Code セッショントランスクリプト（--transcript）です。これが最も豊富な情報源です。検索引数（Grep の pattern、Read の file_path）、observation、ステップごとの ok を復元できるため、根拠付けと結果を観測できます。サイドチェーン（サブエージェント）の行はスキップされます。トランスクリプトにはタスクの判定結果が含まれないため、run.ok は強制的に True になります。FLAGS を信頼してください。
• pass^k： 1 つのタスクを k 回実行し、k 回すべてで成果物の提供を必須とします。pass^k として報告します。
• ルールチェック（設定駆動）： forbidden_tool（高）、out_of_order（中、must_precede 経由）、retry_storm（中、同じツールで N 回を超える連続失敗）、excessive_steps（低、予算超過）、edited_without_read（中 — 根拠付けの代理指標：事前に Read/Grep されていない、または Write で作成されていないファイルへの Edit/MultiEdit。grounding.enabled で制御）。
• 実行ごとの判定： clean-pass / pass-with-warnings / corrupt-success（成果物を提供し、かつ重大度の高いフラグがある）/ fail（未提供）。

1 つのアダプターの背後に隔離 — harness/trace-grader.config.yaml、verified:false：

• ルールのパラメーター（禁止リスト、再試行のしきい値、ステップ予算、順序制約）— プロジェクト固有の最善推測で、それぞれに # ASSUMPTION を付記します。
• 推論を伴うエージェントによる判定の軸（タスク完了／ツールの根拠／計画の評価基準）— judge_trajectory() はスタブであり、判定モデルを設定してファイルを verified:true に切り替えるまでは呼び出されません。

後から適応する場合は、エンジンには触れず、そのファイル 1 つだけを編集します。

リファレンス — ファイル

ファイル	役割
harness/scripts/trace-grader.py	決定論的エンジン：スキーマ、パーサー、pass^k、ルールチェック、レポート、判定スタブ
harness/trace-grader.config.yaml	唯一のアダプター（verified:false）— すべての値に # ASSUMPTION を付記
harness/tests/trace-grader.fixtures.json	セルフテスト用フィクスチャ：clean / corrupt-success / flaky