codex-readiness-unit-test

LLM Codex 就绪度单元测试

以指令为先，在会话中评估 AGENTS/PLANS 文档质量的“就绪度”，不依赖任何外部 API 或 SDK。所有检查都针对当前工作目录（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，也不会生成执行日志或摘要。
• 执行：包含只读模式的全部内容，另外通过 run_plan.py 执行经过确认的 plan.json。这会启用检查 #6，并生成执行日志和用于评分的 execution_summary.json。

继续之前，务必询问用户要运行哪种模式（只读还是执行）。

检查类型

• 确定性：仅检查文件系统（#1 AGENTS.md 是否存在，#2 PLANS.md 是否存在，#3 AGENTS.md 是否不超过 300 行，#4 config.toml 是否存在于仓库根目录、仓库 .codex/ 或用户 .codex/ 中）
• 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
}

单次确认（必需）

将命令摘要和执行计划合并为一个简洁的确认步骤。展示：

• 提取出的构建／测试／开发循环命令（使用便于阅读的标签）。
• 计划的执行详情（工作目录、按顺序排列的命令、软超时策略、环境变量）。 只需请求一次确认即可继续。不要粘贴原始 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，则为 FAIL；否则，如果存在任何 WARN 或 NOT_RUN，则为 WARN；否则为 PASS。

安全与超时

• 禁止列表中的命令不会执行，并标记为 FAIL。
• 软超时默认为 600s；硬上限默认为软超时的 3 倍。
• 执行日志写入 .codex-readiness-unit-test/<timestamp>/logs/。