harness-audit

harness-audit — テストスイートとハーネス品質の検査ツール

ドメイン評価基準

1. 監査の階層

段階的なアーキテクチャレイヤーにわたって、対象のテストスイートを検査します。

1. ハーネスの基点と基盤レイヤー：
   • .agents/harness-anchor.md にあるプロジェクトの正式なハーネスの基点を検査し、Governing Testing SSOTs のルートに従ってプロジェクトのテスト標準を確認します。
   • 見つからない場合：レガシーなテストガイド（test/AGENTS.md、tests/AGENTS.md）を確認します。見つかった場合は一時的な SSOT として使用し、正式な .agents/harness-anchor.md を確立するために /zenforge-init を実行するよう案内します。見つからない場合は、基点を UNGROUNDED としてマークし、/zenforge-init に案内します。
   • 登録済みのエルミートなプリミティブ（決定論的クロック、ストレージサンドボックス、フィクスチャ／ファクトリー、トランスポート／ネットワークモック、ライフサイクル／クリーンアップ）がディスク上に存在することを確認します。
2. コードスメルと不安定化の落とし穴：
   • references/test-smells.md に記載されたアンチパターンと不安定化の落とし穴に照らしてテストを評価します。
3. 不変条件の次元における盲点：
   • references/invariant-dimensions.md に記載された不変条件の次元に照らして、テストカバレッジを監査します。

2. 必須の参照資料による根拠付け

監査を実行する前に、エージェントは以下を必ず読み、内容に基づいて判断する必要があります。

• 具体的なコードスメルの定義と対処法については references/test-smells.md。
• 不変条件テストの観点については references/invariant-dimensions.md。

3. レビュー判定と引用ルール

• PASS：ハーネスの基点が有効で、エルミートな基盤が検証されており、不安定化のコードスメルがゼロで、不変条件の各次元をバランスよくカバーしています。
• WARN：インフラは存在しますが、保守上の負債が確認されています（セットアップの重複、アサーションメッセージの欠落）。
• CRITICAL：ハーネスの基点がない、基盤が不足している（仮想クロック／一時ストレージがない）、または不安定化のコードスメル（クロックリーク、スリープ）が検出されています。
• 二重引用ルール：各欠陥について、問題のあるコード箇所（file:///path/to/test#L<N>）と、違反している不変条件または対処法の両方を引用する必要があります。

標準出力契約

# Harness Audit Report: <Target Scope>

## 1. Executive Verdict
- **Verdict**: <PASS | WARN | CRITICAL>
- **Target Inspected**: <Directory or Test Files>
- **Harness Anchor (SSOT)**: <Cited anchor pointer or 'UNGROUNDED (Missing .agents/harness-anchor.md)'>
- **Flakiness Risk**: <LOW | MEDIUM | HIGH>
- **Summary**: <Single-sentence technical judgment>

## 2. Infrastructure & Anchor Gaps
*(If clean: 'Harness anchor verified; foundational hermetic primitives active.')*
- **[<Anchor / Primitive>] <Gap Title>**: <Deficit description>
   - Impact: <Why this causes flakiness or maintenance debt>
   - Recommendation: <Architecture fix or seed anchor pointer>

## 3. Findings & Invariant Blind Spots
- **[<Smell / Dimension>] <Title>**: <Defect description>
   - Offending Code: [<file>#L<N>](file:///path/to/test#L<N>)
   - Remediation: <Exact architectural correction required>

振り分け

• ハーネスの基点がなく、セットアップが必要な場合 →（/zenforge-init 経由）。
• 基盤となるエルミートなプリミティブがなく、アーキテクチャ上のトレードオフについて検討が必要な場合 →（/clarify 経由）。
• 修正計画を立てられる状態のギャップや不変条件の盲点が見つかった場合 →（/changeset 経由）。
• 承認済みのチェンジセットにより、局所的なテスト修正とその受け入れ基準／検証が認められます →（/forge 経由）。

実行プロトコル

1. 根拠付けと対象範囲の把握：
   • .agents/harness-anchor.md があれば検査します。
   • references/test-smells.md と references/invariant-dimensions.md を読みます。
2. 規模に応じた監査の割り当て：
   • ターン内での実行（テストファイルが 10 件未満、または対象が局所的なスイート）：監査階層に照らして、ターン内で直接テストスイートを検査します。
   • サブエージェントへの分散（複数パッケージにわたる大規模なテストスイート）：基点と参照資料のパスを渡し、ディレクトリごとに分担する 1～3 個の research サブエージェントを起動します。
3. 統合とターン終了ゲート（集約）：
   • 検出事項を標準出力契約に従って重複なくまとめます。
   • 完了したレポートを会話ストリームに提示し、ただちにターンを終了します。