debug-my-harness

フライトレコーダーからハーネスの誤動作を診断します。これは、ハーネスの実行中に vigiles が書き込む、.vigiles/runs.jsonl にあるローカルの追記専用台帳です。実際に何が起きたかを記録するため、推測ではなく証拠に基づいてデバッグできます。

台帳の内容

1 行につき 1 つの JSON レコードがあり、それぞれに kind が含まれます。

• hook — コンパイル済みフックによるゲート判定：{event, decision: allow|deny|ask, mode: enforce|observe, rule, cmd, reason}。
• agent — サブエージェントのツール契約に関する判定：{name, tool, allowed, reason}（false は、エージェントが許可された範囲を逸脱したことを示します）。
• skill — スキルの起動：{name, fired}。
• eval — 測定されたメトリクス：{name, metric, value}（例：トリガー率の再現率／適合率）。
• capability-diff — 影響範囲の変化：{pr, added, removed, widened}。

手順

ステップ 1：台帳を読む

.vigiles/runs.jsonl を読み込みます（JSONL — 1 行につき 1 レコード。末尾の不完全な行は許容します）。ファイルが存在しない、または空の場合は、その旨を伝えます。まだ記録がないため、まずハーネス（または vigiles audit）を実行するよう提案してください。記録を捏造してはいけません。

ステップ 2：具体的な質問に、まず証拠に基づいて回答する

ユーザーの質問を台帳と照合します。

• 「スキル X が起動しなくなったのはなぜですか／間違ったスキルが実行されるのはなぜですか？」 — skill の起動数を名前ごとに時系列で数えます。X の起動率が低下している場合は、同種のプロンプトで起動した兄弟スキルを探し、選択の競合がないか確認します。説明文に重複があれば、違いを明確にするか、統合することを提案してください。
• 「フックがブロックしなかったのはなぜですか？」 — 該当するイベントの hook レコードを探します。本来拒否すべきものに対する decision: allow、ブロックが行われないシャドーモードの mode: observe、またはレコードが存在しないことから原因を特定できます。observe を enforce に切り替えるか、ゲートのロジックを修正するよう提案してください。
• 「サブエージェントは不適切な動作をしましたか？」 — allowed: false の agent レコードを列挙します。エージェントが宣言済みの契約外のツールを使おうとしたことを示します。厳格化または緩和すべき契約を指摘してください。
• 「悪化していますか？」 — 複数の実行における eval メトリクス値（再現率／適合率）を比較します。下降傾向はドリフトを示しており、多くの場合、ハーネスやモデルのアップグレード後に発生します。

ステップ 3：証拠に基づいて修正を提案する

無視されているものの判定可能なルールは、文章での指示から決定論的なゲートへの昇格を優先してください。agent の違反が繰り返される場合や、エージェントが何度も破るルールがある場合は、コンパイル済みフックまたはより厳格なツール契約にします（strengthen スキルが役立ちます）。説明文の競合がある場合は、スキルの説明文を区別してください。診断の根拠とした具体的なレコードを必ず示してください。

ステップ 4：次の手順を案内する

修正に仕様の変更が必要な場合は、edit-spec に引き継ぎます。ガイダンスをリンタールールに昇格させる場合は、strengthen に引き継ぎます。動作に関する主張の測定（スキルが今も起動するかなど）が必要な場合は、test-harness（measureTriggerRate）に引き継ぎます。