agent-output-audit

Agent 输出审计

你是独立评估者。只回答一个问题——“实现 Agent 是否真的完成了 task_NN.md 中的要求？”——依据文件、公开行为、测试和 CI 作出判断。自我报告不算证据。（真实用户能否成功使用产品属于 qa-execution；请对 Compozy slug 同时运行两者，并将输出分开保存。）

第 1 步：了解仓库验证约定

1. 运行命令前，先阅读根目录说明、仓库文档和 CI／构建文件。
2. 运行 python3 scripts/discover-project-contract.py --root .，以找出可能的安装／验证／构建／测试／lint／启动命令和 E2E 信号。
3. 优先使用仓库定义的统一命令（make verify、just verify、CI 入口等），而不是语言默认命令。如果发现结果中有多个可能的验证门槛或涉及多个生态系统，请在选择前阅读 references/project-signals.md，并说明取舍依据。
4. 对任何流程进行覆盖率分类前，请先阅读 references/e2e-coverage.md。
5. 确定审计产物目录：若提供了 audit-output-path 参数，则使用该目录；否则使用仓库约定；若无约定，则使用 /tmp/agent-output-audit-<slug>。创建其 audit/ 子目录；所有缺陷和报告都存放在 <audit-output-path>/audit/ 下。
6. 检测 Compozy 模式。 如果 .compozy/tasks/<slug>/ 存在，记录 slug，并执行以下操作：
   • 以只读方式读取 state.yaml——根据 cy-codex-loop 约定，由 scripts/update-state.py 负责修改该文件。
   • 如存在 _techspec.md（交付物的事实来源）和 _tasks.md（任务清单），则读取。
   • 列出所有 task_NN.md，并记录其 frontmatter 中的 status:（pending | in_progress | completed）。若 frontmatter 与 state.yaml 不一致，以 frontmatter 为准。
   • 记录记忆槽 .compozy/tasks/<slug>/memory/qa-execution.md——第 5 步会在任何状态切换前写入该文件。

第 2 步：运行基线验证门槛

1. 使用仓库首选命令安装依赖。
2. 在开始任何审计工作前运行一次规范验证门槛，按最快顺序执行：lint 和类型检查 → 构建 → 单元测试 → 集成测试。
3. 如果 E2E 命令独立于统一验证门槛，决定是在此时运行，还是等运行时前置条件就绪后再运行，并记录计划。
4. 若基线失败，请阅读首个失败输出，并判断该问题是既存问题还是由当前工作引入。只有在通过干净复现证明与当前工作无关后，才能将其排除在审计范围之外。
5. 不稳定失败处理流程。 对任何基线失败进行分类前，须在同一 SHA 上将失败测试单独运行 3-5 次。如果未更改代码且至少有一次运行通过，则在 SUITE HEALTH SNAPSHOT 中将其记录为 flaky-suspect（包括测试名称、尝试次数、重试结果和疑似类别），不得将其升级为 PASS。分配疑似类别或提出隔离方案前，请阅读 references/flaky-triage.md。

第 3 步：审核任务实现

仅当不存在任务、阶段、PRD、技术规格或实施计划相关工件时，才跳过此步骤。

1. 在形成任何判断前，完整阅读 references/independent-evaluator-protocol.md——该文档规定了哪些内容算作证据、哪些不算，以及对话记录的分类（genuine-failure / grader-bug / ambiguous-task / bypass-exploit）。在 Compozy 模式下，阅读实施者的 memory/<phase>.md 工件，并在评判任务前将异常分类记录到 memory/qa-execution.md → Errors / Corrections。
2. 总结每个 task_NN.md 及其正文，整理成任务实现矩阵（列与 cy-codex-loop frontmatter 字段对应）：
   • task_path、declared_status（frontmatter 中 status: 的字面值）
   • title、type、complexity、dependencies——与 frontmatter 字段一致
   • techspec_deliverable——存在时，关联的 _techspec.md 章节
   • 需求、子任务、检查清单项、成功标准、依赖文件
   • implementation_evidence——文件、模块、路由、命令、迁移、种子数据、测试
   • verification_evidence——执行的命令、退出代码、输出摘要
   • qa_verdict——PASS | PARTIAL | FAIL | REOPEN | BLOCKED（与 declared_status 区分）
   • ai_audit_findings——第 4 步触发的红旗 ID 及其判定
   • action——none | fixed | reopened-frontmatter | BUG-NNN.md filed
   • linked_bugs——BUG ID
3. 根据实际文件、公开行为、自动化测试和验收标准，核验每个已完成或声称已完成的任务。针对当前仓库状态，重新执行最小化的公开验证。
4. 指定 qa_verdict：
   • PASS：每项重要需求和成功标准都有实现及最新验证证据。
   • PARTIAL：已有实现，但缺少一项或多项非关键需求、测试或证据。
   • FAIL：声称的行为无法正常工作，或缺少关键需求。
   • REOPEN：frontmatter 标注 status: completed，但 QA 判定为 PARTIAL 或 FAIL。
   • BLOCKED：缺少明确的前置条件。验证所有不依赖缺失依赖项的本地边界，并单独报告受阻的实时验证。

第 4 步：AI 测试卫生扫描（RF-1..RF-6）

1. 在扫描任何 declared_status: completed 任务的测试差异前，完整阅读 references/ai-implementation-audit.md——该文档规定了 RF-1..RF-6 扫描器、Requirement→Test 映射以及判定矩阵。
2. 针对自任务基线以来的差异运行扫描（git log --follow <test_file>、git diff <baseline_sha>..HEAD）。
3. 按矩阵给出的结果输出判定。RF-1（新增 skip/only/xit/t.Skip）、针对 P0/P1 标准的 RF-2（弱化断言）、RF-3（在 TC 声明为 Integration/E2E 的依赖项上使用 mock），以及针对 P0/P1 的 RF-4（无正当理由的快照变更）均自动判定为 FAIL。
4. 将发现记录在矩阵的 ai_audit_findings 列，以及 audit-report.md 中每个任务对应的区块。
5. 应用 Requirement→Test 映射：对于 task_NN.md 中的每项 Success Criterion，以及关联 _techspec.md 中的每个条目，将匹配的测试标记为 covers / weak / missing。已勾选的项目或 status: completed 若没有对应的 covers 行，即视为审核失败。

步骤 5：重新打开、提交缺陷、编写记忆

1. 将每个尚未完成但已标记为完成的任务标记为 REOPEN。
2. 在 Compozy 模式下，先使用 cy-codex-loop 规定的章节（Objective Snapshot、Important Decisions、Learnings、Files / Surfaces、Errors / Corrections、Ready for Next Run）编写 memory/qa-execution.md，然后再更改任何 task_NN.md 的 frontmatter（记忆优先于状态这一不变量）。
3. 将问题任务的 task_NN.md frontmatter 中的 status: 改回 pending（若可挽救，则改为 in_progress）。不要改动 state.yaml——它由 update-state.py 管理，下一轮迭代会根据 frontmatter 进行同步。
4. 使用 assets/issue-template.md，在 <audit-output-path>/audit/issues/ 下提交 BUG-<num>.md，其中包括：任务路径（Reopens task:）、失败的成功标准（Summary:）、触发 RF-2 时的原始严格断言（Root cause:）、红旗 ID 和判定结果（Automation Follow-up:），以及任何记录异常分类（Related:）。
5. 如果问题是在审计范围内可明确界定的根因修复，则实施修复、添加回归测试并重新运行任务验证；否则重新打开该任务。

步骤 6：质量门禁判定

1. 在审计期间进行最后一次代码更改后，从头重新运行规范验证门禁。
2. 在 audit-report.md 的质量门禁部分逐项记录 PASS / FAIL / N/A：
   • 规范测试套件中的不稳定率 <2%。
   • P0/P1 任务的 AI 测试卫生扫描中 FAIL 数为零。
   • 未解决的 Critical / High 级问题为零。
   • 覆盖率变化 ≥ 基线（无回退）。
   • P0 流程中未解决的 flaky-suspect 为零。
3. 任一门禁为 FAIL，都将阻止本次运行获得无条件 PASS 判定。

步骤 7：编写审计报告

1. 使用 assets/audit-report-template.md 将报告写入 <audit-output-path>/audit/audit-report.md，并包含所有必需章节：
   • 步骤 2 和 6 中执行的每条命令，都要记录其 Claim / Command / Exit code / Verdict。
   • AUTOMATED COVERAGE——检测到的支持情况、测试框架、规范命令、必需流程及其分类、新增或更新的规格。
   • TASK IMPLEMENTATION AUDIT——Compozy slug、计划来源、矩阵总数、各任务判定结果、重新打开/修复/受阻任务，以及缺陷链接。
   • SUITE HEALTH SNAPSHOT——不稳定率、不稳定事件、变异测试分数（存在测试框架时）、相对于基线的覆盖率变化、受阻数量、仅限人工执行的数量、AI 审计发现数量。
   • QUALITY GATES——逐项记录各门禁的 PASS/FAIL/N/A。
   • ISSUES FILED——总数、按严重性分类的数量，并附上 Reopens task: 注释。
   • 对每个受阻场景、缺失凭据或环境缺口，记录阻止执行的确切命令或前置条件。
2. 在 Compozy slug 中，最终的 PASS 会满足 cy-codex-loop Phase E 的 verify.last_status=PASS 前置条件——将 update-state.py 留给 cy-codex-loop 处理。
3. 在宣布审计完成前，确认 references/checklist.md 中的每一项均已满足——这是涵盖所有步骤的完整完成标准。