codex-readiness-unit-test

LLM Codex の準備状況ユニットテスト

外部 API や SDK を使わず、AGENTS／PLANS ドキュメントの品質を評価するための、指示優先型のセッション内「準備状況」評価です。すべてのチェックは現在の作業ディレクトリ（cwd）を対象に実行され、モノレポの検出は行いません。実行ごとに .codex-readiness-unit-test/<timestamp>/ に出力し、.codex-readiness-unit-test/latest.json を更新します。実行は決定論的に行ってください（ファイルシステムのスキャンとローカルコマンドの実行のみ）。LLM による評価はすべてセッション内で行い、提供されたリファレンスに従って厳密な JSON を出力する必要があります。

クイックスタート

1. 証拠を収集します。
   • python skills/codex-readiness-unit-test/bin/collect_evidence.py
2. 決定論的なチェックを実行します。
   • python skills/codex-readiness-unit-test/bin/deterministic_rules.py
3. references/ 内のリファレンスを使って LLM チェックを実行し、結果を .codex-readiness-unit-test/<timestamp>/llm_results.json に保存します。
4. 実行モードが要求された場合は、計画を作成して確認を得たうえで、次を実行します。
   • python skills/codex-readiness-unit-test/bin/run_plan.py --plan .codex-readiness-unit-test/<timestamp>/plan.json
5. レポートを生成します。
   • python skills/codex-readiness-unit-test/bin/scoring.py --mode read-only|execute

出力（実行ごとに .codex-readiness-unit-test/<timestamp>/ 内に作成）：

• report.json
• report.html
• summary.json
• logs/*（実行モード）

実行手順

このスキルは、決定論的な証拠ファイルとセッション内の LLM 評価を生成し、それらをまとめて JSON レポートと HTML スコアカードを作成します。OpenAI API キーは不要で、外部への HTTP 呼び出しも行いません。

最小限の入力

• mode：read-only または execute（必須）
• soft_timeout_seconds：任意（デフォルトは 600）

モード（読み取り専用と実行）

• 読み取り専用：証拠を収集し、決定論的なルールを実行して、LLM チェック #3～#5 を実行します。コマンドは実行されず、チェック #6 は NOT_RUN としてマークされ、実行ログ／サマリーも生成されません。
• 実行：読み取り専用のすべての処理に加え、確認済みの plan.json を run_plan.py で実行します。これによりチェック #6 が有効になり、スコアリング用の実行ログと execution_summary.json が生成されます。

続行する前に、必ずユーザーに実行モード（読み取り専用と実行）のどちらで行うかを尋ねてください。

チェックの種類

• 決定論的：ファイルシステムのみを対象にしたチェック（#1 AGENTS.md が存在する、#2 PLANS.md が存在する、#3 AGENTS.md が 300 行以下、#4 リポジトリルート、リポジトリの .codex/、またはユーザーの .codex/ に config.toml が存在する）
• LLM：セッション内での Codex 評価（#3 プロジェクトのコンテキスト、#4 コマンド、#5 ループ。コマンドは AGENTS または参照先のスキル内に記載されている場合があります）
• ハイブリッド：決定論的な実行と LLM による根拠の提示（#6 実行）

スキルのリファレンスは、AGENTS.md 内の $SkillName または .codex/skills/<name> のパターンから検出されます。該当する SKILL.md ファイルは、LLM チェック用の証拠に追加されます。

すべてのチェックは現在の作業ディレクトリを基準に実行され、skills/codex-readiness-unit-test/references/checks/checks.json で定義されています。デフォルトでは、各チェックの重みは同じです。実行ごとに .codex-readiness-unit-test/<timestamp>/ に出力し、.codex-readiness-unit-test/latest.json を更新します。 ヘルパースクリプトは、デフォルトで .codex-readiness-unit-test/latest.json を読み取り、最新の実行ディレクトリを特定します。

厳密な JSON と再試行ループ（必須）

LLM／ハイブリッドの各チェックについて、次の手順を実行します。

1. 厳密な JSON の出力を求める専用プロンプトを実行します。
2. JSON が無効であるか、キーが不足している場合は、生の出力を使って skills/codex-readiness-unit-test/references/json_fix.md を実行します。
3. 追加で最大 2 回再試行します（合計最大 3 回）。
4. それでも無効な場合は、チェックを WARN とし、根拠に「再試行後も評価器から無効な JSON が出力されました」と記載します。

JSON スキーマは次のとおりです。

{
  "status": "PASS|WARN|FAIL|NOT_RUN",
  "rationale": "string",
  "evidence_quotes": [{"path":"...","quote":"..."}],
  "recommendations": ["..."],
  "confidence": 0.0
}

単一の確認（必須）

コマンドの概要と実行計画を1つの簡潔な確認ステップにまとめます。以下を提示します。

• 抽出したビルド／テスト／開発ループのコマンド（人が読みやすい形式でラベル付き）。
• 実行予定の詳細（作業ディレクトリ、順序付きコマンド、ソフトタイムアウトポリシー、環境変数）。 実行を続行するための確認を1回だけ求めます。生の JSON、証拠の全文、または plan.json の全文は貼り付けないでください。 拒否された場合、実行が必須のチェックは NOT_RUN とします。

必須ファイル

• .codex-readiness-unit-test/<timestamp>/evidence.json（collect_evidence.py で生成）
• .codex-readiness-unit-test/<timestamp>/deterministic_results.json（deterministic_rules.py で生成）
• .codex-readiness-unit-test/<timestamp>/llm_results.json（セッション内の参照から生成）
• .codex-readiness-unit-test/<timestamp>/execution_summary.json（実行モードのみ）
• .codex-readiness-unit-test/<timestamp>/report.json および .codex-readiness-unit-test/<timestamp>/report.html（scoring.py で生成）
• .codex-readiness-unit-test/<timestamp>/summary.json（scoring.py による構造化された合否サマリー）
• .codex-readiness-unit-test/latest.json（最新の実行ディレクトリへの固定ポインター）

プロンプトの対応関係

• #3 project_context_specified → skills/codex-readiness-unit-test/references/project_context.md
• #4 build_test_commands_exist → skills/codex-readiness-unit-test/references/commands.md
• #5 dev_build_test_loops_documented → skills/codex-readiness-unit-test/references/loop_quality.md
• #6 dev_build_test_loop_execution → skills/codex-readiness-unit-test/references/execution_explanation.md

plan.json スキーマ（実行モード）

{
  "project_dir": "relative/or/absolute/path (optional)",
  "cwd": "optional/absolute/path (defaults to current directory)",
  "commands": [
    {"label": "setup", "cmd": "npm install"},
    {"label": "build", "cmd": "npm run build"},
    {"label": "test", "cmd": "npm test"}
  ],
  "env": {
    "EXAMPLE": "value"
  }
}

plan.json は実行ディレクトリ内に配置します（例：.codex-readiness-unit-test/<timestamp>/plan.json）。

llm_results.json スキーマ

{
  "project_context_specified": {"status":"PASS","rationale":"...","evidence_quotes":[],"recommendations":[],"confidence":0.7},
  "build_test_commands_exist": {"status":"PASS","rationale":"...","evidence_quotes":[],"recommendations":[],"confidence":0.7},
  "dev_build_test_loops_documented": {"status":"WARN","rationale":"...","evidence_quotes":[],"recommendations":[],"confidence":0.6},
  "dev_build_test_loop_execution": {"status":"PASS","rationale":"...","evidence_quotes":[],"recommendations":[],"confidence":0.6}
}

スコアリングルール

• PASS = 配点の100%
• WARN = 配点の50%
• FAIL/NOT_RUN = 0%
• 総合ステータス：FAIL が1つでもあれば FAIL、そうでなく WARN または NOT_RUN が1つでもあれば WARN、それ以外は PASS。

安全性とタイムアウト

• 拒否リストにあるコマンドは実行せず、FAIL としてマークします。
• ソフトタイムアウトのデフォルトは600秒、ハード上限のデフォルトはソフトタイムアウトの3倍です。
• 実行ログは .codex-readiness-unit-test/<timestamp>/logs/ に書き込まれます。