ln-636-manual-test-auditor

パス： ファイルパス（references/、../ln-*）は、このスキルディレクトリからの相対パスです。

手動エビデンス監査担当（L3 ワーカー）

タイプ： L3 ワーカー

手動テストスクリプトが再現可能で有用なエビデンスを生成するかを監査する専門ワーカーです。

目的と範囲

• 手動エビデンス（カテゴリ 7：中優先度）を監査します
• tests/manual/ の bash テストスクリプトを品質基準に照らして評価します
• REWRITE_MANUAL_EVIDENCE または KEEP_MANUAL_EVIDENCE を出力します
• コンプライアンススコア（X/10）を算出します

入力

必須読み込み： references/audit_worker_core_contract.md を読み込みます。

contextStore で次の情報を受け取ります：tech_stack、testFilesMetadata（type: "manual" にフィルタリング済み）、codebase_root、output_dir。

手動テストのメタデータには、suite_dir、has_expected_dir、harness_sourced が含まれます。

ワークフロー

検出ポリシー：2 層検出（候補スキャン、その後のコンテキスト検証）を使用します。検証方法が曖昧な場合にのみ、references/two_layer_detection.md を読み込みます。

1. コンテキストの解析： contextStore から手動テストファイルのリスト、output_dir、codebase_root を抽出します
2. インフラストラクチャの検出： 共通インフラストラクチャファイルを検出します：
   • tests/manual/config.sh -- 共通設定
   • tests/manual/test_harness.sh -- 共通テストフレームワーク（存在する場合）
   • tests/manual/test-all.sh -- マスターランナー
   • tests/manual/TEMPLATE-*.sh -- テストテンプレート（存在する場合）
   • tests/manual/regenerate-golden.sh -- ゴールデンファイルの再生成（存在する場合）
3. スクリプトのスキャン（レイヤー 1）： 各手動テストスクリプトについて、7 つの品質基準を確認します（「監査ルール」を参照） 3b) コンテキスト分析（レイヤー 2 -- 必須）： 指摘候補ごとに、次の点を確認します：
   • セットアップ／ユーティリティスクリプト（例：00-setup/*.sh、tools/*.sh）ですか？ セットアップスクリプトには異なる要件があるため、ハーネス／ゴールデンファイルのチェックをスキップします
   • マスターランナー（test-all.sh）ですか？ マスターランナーはテストを実行するもので、テスト自体は行わないため、fail-fast 以外のすべてのチェックをスキップします
   • プロジェクトでは共通ハーネスをまったく使用していませんか？ test_harness.sh が存在しない場合、ハーネス導入のチェックは該当しません
4. 指摘事項の収集： 違反を、重大度、場所（file:line）、作業量、アクション、推奨事項とともに記録します
5. スコアの算出： 重大度別に違反数を数え、コンプライアンススコア（X/10）を算出します
6. レポートの作成： references/templates/audit_worker_report_template.md に従って完全な Markdown レポートをメモリ内で作成し、単一の Write 呼び出しで {output_dir}/ln-636--global.md に書き込みます
7. 要約の返却： コーディネーターに最小限の要約を返します（出力形式を参照）

監査ルール

1. ハーネスの採用

内容： テストスクリプトが、独自のアサーションロジックではなく、共通フレームワーク（run_test、init_test_state）を使用していること

検出方法：

• スクリプト内で run_test、init_test_state を Grep します
• 存在せず、かつスクリプトに独自のテストループ／アサーションが含まれる場合 -> 独自ロジックと判断します
• プロジェクトに test_harness.sh が存在しない場合 -> このチェック全体をスキップします

重大度： 高（独自ロジックは保守負担となり、報告の一貫性を損ないます）

推奨事項： test_harness.sh の共通 run_test を使用するようリファクタリングします アクション： REWRITE_MANUAL_EVIDENCE

作業量： M

2. ゴールデンファイルの完全性

内容： テストスイートに、テストシナリオに対応する参照ファイルを含む expected/ ディレクトリがあること

検出方法：

• スイートディレクトリに expected/ サブディレクトリがあるか確認します
• テストシナリオの数（run_test 呼び出しを grep して確認）と expected ファイルの数を比較します
• テストで expected ファイルとの diff を使用しているにもかかわらず expected ディレクトリがない場合 -> 指摘事項とします

レイヤー 2： すべてのテストにゴールデンファイルが必要なわけではありません。HTTP ステータスコード、タイミング、動的データを検証するテストでは、ゴールデンファイルとの比較を正当に省略できる場合があります -> テストで diff またはファイルとの比較を行っていない場合はスキップします

重大度： 高（ゴールデンファイルがないと、出力の正確性に関するリグレッションを検出できません）

推奨事項： 参照出力ファイルを含む expected/ ディレクトリを追加します アクション： REWRITE_MANUAL_EVIDENCE

作業量： M

3. 設定の読み込み

内容： 一貫した設定を行うため、スクリプトで共通の config.sh を読み込みます。

検出方法：

• source.*config.sh または . .*config.sh を grep します。
• 見つからない場合 -> スクリプトが独自に BASE_URL、トークンなどを管理しています。

レイヤー 2： スクリプトが自己完結型のユーティリティ（例：tools/*.sh）の場合 -> スキップします。

重大度： MEDIUM

推奨事項： 共通設定を利用するため、source "$THIS_DIR/../config.sh" を追加します。 アクション： REWRITE_MANUAL_EVIDENCE

作業量： S

4. フェイルファストへの準拠

内容： スクリプトで set -e を使用し、失敗時に終了コード 1 を返します。

検出方法：

• set -e（または set -eo pipefail）を grep します。
• 失敗時の処理がゼロ以外の終了コードにつながることを確認します（どこでも || true を使って失敗を握りつぶしていないこと）。

重大度： HIGH（エラーが通知されないと、テストの不具合が見逃されます）

推奨事項： スクリプトの冒頭に set -e を追加し、テストの失敗が伝播するようにします。 アクション： REWRITE_MANUAL_EVIDENCE

作業量： S

5. テンプレートへの準拠

内容： スクリプトがプロジェクトのテストテンプレート（TEMPLATE-api-endpoint.sh、TEMPLATE-document-format.sh）に従っています。

検出方法：

• tests/manual/ に TEMPLATE ファイルがある場合は、構造が一致しているか確認します。
  • 説明、テスト対象の AC、前提条件を記載したヘッダーコメントブロック
  • 標準の変数名（THIS_DIR、EXPECTED_DIR）
  • 標準のセットアップパターン（source config.sh、check_jq、setup_auth）
• プロジェクトにテンプレートがない場合は、このチェックを完全にスキップします。

レイヤー 2： テンプレートが作成される前に書かれた古いスクリプトは、テンプレートと異なる場合があります。重大度は HIGH ではなく MEDIUM とします。

重大度： MEDIUM

推奨事項： スクリプトの構造をプロジェクトの TEMPLATE ファイルに合わせます。 アクション： REWRITE_MANUAL_EVIDENCE

作業量： M

6. 冪等性

内容： 前回の実行による副作用を起こさず、安全に再実行できるスクリプトです。

検出方法：

• クリーンアップパターン（trap.*EXIT、rm -f、cleanup 関数）を grep します。
• 一時ファイルがクリーンアップされずに作成されていないか確認します。
• 再実行時に競合する、ハードコードされたリソース名がないか確認します（例：存在確認をせず、固定のメールアドレスでユーザーを作成する）。

レイヤー 2： データを読み取るだけのスクリプト（GET リクエスト、クエリ）は本質的に冪等です -> スキップします。

重大度： MEDIUM

推奨事項： クリーンアップ用の trap を追加するか、実行ごとに一意の識別子を使用します。 アクション： REWRITE_MANUAL_EVIDENCE

作業量： S-M

7. ドキュメント

内容： テストスイートのディレクトリに、目的と前提条件を説明する README.md があります。

検出方法：

• スイートのディレクトリ（NN-feature/）に README.md があるか確認します。
• ない場合 -> 指摘事項とします。

レイヤー 2： セットアップ用ディレクトリ（00-setup/）やユーティリティ用ディレクトリ（tools/）では、README が不要な場合があります -> スキップします。

重大度： LOW

推奨事項： テストの目的、前提条件、使用方法を記載した README.md を追加します。 アクション： REWRITE_MANUAL_EVIDENCE

作業量： S

スコアリングアルゴリズム

必ず読むこと： references/audit_scoring.md を読み込みます。

重大度の対応付け：

• ハーネスの採用漏れ（ハーネスが存在する場合）、ゴールデンファイルの欠如（期待値ベースの場合）、フェイルファストの欠如 -> HIGH
• 設定の読み込み漏れ、テンプレートとの不一致、冪等性の欠如 -> MEDIUM
• README の欠如 -> LOW

出力形式

必ず読むこと： references/templates/audit_worker_report_template.md を読み込みます。

references/audit_summary_contract.md に従って JSON サマリーを作成します。管理モードでは、呼び出し元から runId と summaryArtifactPath の両方が渡されます。スタンドアロンモードでは、共通コントラクトに従って、ワーカーが実行スコープのアーティファクトパスを生成します。

{output_dir}/ln-636--global.md に、category: "Manual Evidence" と、次のチェック項目を記載したレポートを作成します：harness_adoption、golden_file_completeness、config_sourcing、fail_fast_compliance、template_compliance、idempotency、documentation。

references/audit_summary_contract.md に従ってサマリーを返します。

summaryArtifactPath がない場合は、スタンドアロン実行時のサマリーを .hex-skills/runtime-artifacts/runs/{run_id}/evaluation-worker/{worker}--{identifier}.json に書き込み、必要に応じて構造化出力にも同じサマリーを出力します。

Report written: .hex-skills/runtime-artifacts/runs/{run_id}/audit-report/ln-636--global.md
Score: X.X/10 | Issues: N (C:N H:N M:N L:N)

重要なルール

すでに読み込まれている references/audit_worker_core_contract.md を適用してください。

• 自動修正は禁止： 報告のみ
• 作業時間の目安： S = 1時間未満、M = 1～4時間、L = 4時間超
• 空の場合はスキップ： tests/manual/ ディレクトリが存在しない場合は、スコアを10/10、指摘事項を0件として返してください
• テスト以外のファイルを除外： config.sh、test_harness.sh、test-all.sh、regenerate-golden.sh、TEMPLATE-*.sh、tools/、results/、test-runs/ 内のファイルをスキップしてください
• コンテキストを考慮： セットアップスクリプト（00-setup/）は要件を緩和してください（ゴールデンファイル不要、ハーネス不要）
• 独自の観点： 手動テストのエビデンスのみを監査してください。自動テストの価値、E2E の優先度、製品の動作、網羅性の不足、信頼性、オラクルの強度、構造について評価してはいけません
• 対応必須： 指摘事項には REWRITE_MANUAL_EVIDENCE を使用してください。準拠しているスクリプトは指摘事項ではなく、レポートのサマリーで KEEP_MANUAL_EVIDENCE として要約してください

完了条件

すでに読み込まれている references/audit_worker_core_contract.md を適用してください。

• contextStore の解析が正常に完了している（output_dir を含む）
• 手動テストのインフラストラクチャ（config.sh、ハーネス、テンプレート）を確認している
• 各テストスクリプトについて、7つのチェックをすべて完了している
• レイヤー2のコンテキスト分析（セットアップ／ユーティリティの除外）を適用している
• 重要度、場所、作業時間、アクション、推奨事項を含む指摘事項を収集している
• ペナルティアルゴリズムを使用してスコアを算出している
• レポートを {output_dir}/ln-636--global.md に書き込んでいる（Write 呼び出し1回でアトミックに実行）
• コントラクトに従ってサマリーを記載している

参考ファイル

• 監査出力スキーマ： references/audit_output_schema.md

---

バージョン： 1.0.0 最終更新日： 2026-03-13