pipeline-auditor

Pipeline Auditor（草稿审计 + 回归测试）

触发条件与路由

• 触发词：auditor、audit、regression test、quality report、审计、回归测试。
• 适用场景：output/DRAFT.md 已存在，且你希望在生成 LaTeX/PDF 前获得确定性的 PASS/FAIL 报告。

目的：对写作阶段执行确定性的“回归测试”。

它会回答：

• 是否泄漏了占位符或规划内容？
• 引用范围是否发生偏移？
• 草稿是否退回到生成器腔调（导航/叙述模板）？
• 对于类似综述的草稿，引用密度/质量是否足够？

此技能仅用于分析，不会编辑内容。对于所有综述类配置文件，默认将风格/引用形式违规视为阻断性问题。

输入

• output/DRAFT.md
• outline/outline.yml
• 可选（推荐）：
  • outline/evidence_bindings.jsonl
  • citations/ref.bib

输出

• output/AUDIT_REPORT.md
• output/TEMPLATE_RESIDUE_SCORECARD.json

检查项（确定性）

A150++ 引用目标（供审计器使用）：

• 每个 H3：>=12 条不重复引用（深度模式：>=14）。
• 全局：全文草稿中 >=150 条不重复引用（建议目标：165；深度模式下限：165）。

课程论文目标：

• 每个 H3：>=4 条不重复引用，且 >=1600 个非引用字符。

• 全局：>=24 条不重复引用（建议目标：32）。

• 占位符泄漏：省略号（...、…）、TODO 标记、脚手架标签。

• 大纲对齐：章节/小节顺序与 outline/outline.yml 是否一致。

• 调研表格：course_paper 至少需要 1 个 Markdown 表格，survey/deep 至少需要 2 个（由 section-merger 从 outline/tables_appendix.md 插入；索引表格仍为内部内容）。

• 论文文风反模式：

  • 叙述模板（This subsection ...、In this subsection ...）
  • 幻灯片式导航（Next, we move ...、We now turn to ...）
  • 明显的流水线口吻（this run、this workspace）
  • 含义模糊的术语，例如 this pipeline、this stage 和 quality gate 仅当同一句中包含 Harness 锚点（如检查点、Unit ID、Harness lock、attempt ledger 或模板残留）时才会阻止通过； 普通主题内容中的用法只会触发非阻断警告

• 证据政策免责声明刷屏：在 H3 正文中反复出现“仅摘要／仅标题／暂定”之类的套话。

• 元调研指导措辞：survey synthesis/comparisons should ...。

• 综合表述句式重复：反复使用 Taken together, ... 等高显著性的生成式句式。

• 数值声明上下文：数字缺少最低限度的评估上下文词语（基准测试／数据集／指标／预算／成本）。

• 引用健康度（若存在 citations/ref.bib）：未定义键、重复项、基本格式问题。

• 引用形式硬性门槛：不得出现相邻引用块（[@a] [@b]），同一块中不得有重复键（[@a; @a]）。句中引用比例在 course_paper 中需 >=20%，在 survey/deep 中需 >=30%。

• 引用范围（若存在 outline/evidence_bindings.jsonl）：每个 H3 使用的引用应限定在绑定的证据集合内。

• 全文草稿确定性模板残留：拆分英文和中日韩读者可见文本，将每个句子与本次 Run 所选模板资源中的固定片段进行比对，超过 Workflow 限值则拒绝。

• 模板来源溯源：要求 output/FRONT_MATTER_CONTEXT.json 记录所选前置内容资源及其哈希，然后要求三个拥有模板的 Skill 实现与 .harness/harness.lock.json 匹配；缺少溯源信息、旧版锁文件和仓库偏移都会阻止验收。

JSON 评分卡记录测得的比例、计数、阈值、所选资源哈希、带标题信息的示例以及实现锁定结果。在常规 Harness 执行期间，Completion 会将其判定和各维度写入 .harness/evaluations/ledger.jsonl，包括失败的 Attempts，因此 Run Audit 可以显示最新测量结果，而不只是将其简化为通过／失败。评分卡文件仍是完整的证据对象；ledger 则有意保持精简。当前 10% 的限值是初始政策目标。已发布的 Survey 重放完成了当前包含 31 项检查的契约，残留为 0/226，证明对一组保留的 Artifact 来说可以达到该目标。从头开始的干净执行、无关主题和跨配置校准仍有待解决。

如何使用报告（路由表）

将 output/AUDIT_REPORT.md 视为“下一步修复事项”路由器。

常见 FAIL 类型 -> 负责阶段/技能：

• 占位符 / 泄漏的脚手架内容

  • 修复：C2–C4 产物不干净。转交给 subsection-briefs / evidence-draft / writer-context-pack，然后重写受影响的章节。

• 缺少概述表（低于所选配置文件的表格最低要求）

  • 修复：确保 table-schema + appendix-table-writer 已生成 outline/tables_appendix.md（课程论文至少 1 张表；综述/深度论文至少 2 张表；需有引用支持，且无占位符），然后重新运行 section-merger。

• 过渡段 / 叙述者衔接语中出现规划内容

  • 修复：重新运行 transition-weaver（并确保简报包含 bridge_terms / contrast_hook），然后重新合并。

• H3 中出现叙述模板 / 幻灯片导航

  • 修复：通过 writer-selfloop（局部、章节级）或 subsection-polisher 重写未通过检查的 sections/S*.md。

• 证据政策免责声明泛滥

  • 修复：在引言/相关工作（前置内容）中保留一次证据政策说明，删除 H3 中的重复内容（使用 draft-polisher 或局部章节重写）。

• 引用范围偏移（超出范围的 bibkey）

  • 修复：或者（a）重写小节，使其保持在范围内；或者（b）修正映射/绑定（section-mapper → evidence-binder）并重新生成内容包。

• 全文唯一引用数量过低

  • 修复：citation-diversifier → citation-injector（不得添加新事实），然后运行 draft-polisher。

• 引言/相关工作过于单薄 / 引用过少

  • 修复：通过 writer-selfloop（前置内容路径）重写相应的 sections/S<sec_id>.md 前置内容文件，采用密集的研究定位说明 + 方法段落。

• 整篇草稿中的模板残留超出 Workflow 限制

  • 修复：根据每个评分卡示例的标题、章节类型、章节负责人和模板负责人，定位相应的前置内容、章节开篇或 H3 区域；重写其源章节，重新生成合并后的草稿，然后重新运行审计器。不要通过弱化或重命名模板资源来让现有 Run 通过。

预防指南（上游写作者应采取的做法）

如果你希望审计器无需大量润色就能通过：

• 每个 H3 都以内容主张 + 论点开篇（避免叙述模板）。
• 明确呈现对比，并至少加入一个评估基准段落。
• 每项主张都嵌入引用（避免在段末堆砌引用）。
• 在前置内容中说明一次证据政策限制，不要在每个 H3 中重复。

脚本

快速开始

• uv run python .codex/skills/pipeline-auditor/scripts/run.py --help
• uv run python .codex/skills/pipeline-auditor/scripts/run.py --workspace <workspace>

所有选项

• --workspace <dir>
• --unit-id <U###>（可选；用于日志）
• --inputs <semicolon-separated>（很少需要覆盖；优先使用默认值）
• --outputs <semicolon-separated>（很少需要覆盖；默认写入 output/AUDIT_REPORT.md 和 output/TEMPLATE_RESIDUE_SCORECARD.json）
• --checkpoint <C#>（可选）

示例

• 在 global-reviewer 之后、LaTeX/PDF 之前运行审计：
  • uv run python .codex/skills/pipeline-auditor/scripts/run.py --workspace <workspace>

故障排除

问题：审计因引用未定义而失败

修复：

• 使用 citation-verifier 重新生成引用，并确保 citations/ref.bib 包含每个被引用的键。

问题：审计因叙述风格的导航短语而失败

修复：

• 在未通过检查的 sections/* 文件中，将其改写为论证衔接语（承载内容的过渡，不含导航评论），然后重新合并。

问题：审计因“唯一引用数量过低”而失败

修复：

• 运行 citation-diversifier，生成 output/CITATION_BUDGET_REPORT.md。
• 通过 citation-injector 应用该报告（编辑 output/DRAFT.md，写入 output/CITATION_INJECTION_REPORT.md）。
• 然后依次运行 draft-polisher → global-reviewer → 审计器。