work-exhaust

/work-exhaust — 穷尽式发现，直到饱和

此技能针对规模未知的发现问题，实现了 循环直至枯竭 质量模式。

确定性执行模型（三种形态、结构化输出规则、空值处理、日志记录）位于 ../work/references/workflow-mode.md； 此技能要防范的失败模式位于 ../work/references/anti-error-lessons.md （下文以 L1～L8 引用）。此技能是该模型的规范 LOOP 形态——请先阅读这些文件；本文件仅保留独立运行循环所需的内容。

编排形态（确定性）

此技能采用 LOOP 形态（直至枯竭），并在每一轮中嵌套使用另外两种形态：

• 轮内 → PARALLEL 扇出。 本轮的查找器作为一组独立子 Agent 同时启动（一律只读 → 无需工作树），并使用 .filter(Boolean) 收集结果——已终止或出错的查找器不贡献任何内容，但这不代表空轮次（见空值处理 和误判枯竭防护）。每个查找器从 ../work-sweep/SKILL.md 中选取一个不同的角度。
• 轮末 → 真正的 BARRIER。 对照 seen[] 去重并判断枯竭计数器，需要等待本轮所有查找器 返回（只有收齐所有查找器的结果，才能判定“新增项为 0”）。根据 workflow-mode §1，这是唯一一个因真实的跨项依赖（合并）而 有理由设置屏障的地方。去重本身是纯集合逻辑，绝不调用 Agent。
• 跨轮 → LOOP。 重复执行，直到满足终止条件（连续 K 轮符合条件的枯竭轮次）。 seen[]、anglesUsed[] 和 dryCounter 会在各轮之间持续保留（也会在恢复运行时保留——见日志记录）。

气味测试（workflow-mode §1）：去重／合并是真正的屏障，因为它涉及跨项依赖（需要整轮结果才能计算“新增项与已见项”）。轮内各查找器的扇出不是屏障——绝不要在同一轮内让一个查找器等待另一个查找器。

适用场景

• 结果集的数量事先未知。
• 单次遍历很可能会遗漏内容（漏洞、边缘情况、集成点、数据源、需要迁移的文件等）。
• 希望持续查找，直到连续若干轮都没有发现新项。

与多模态扫描（work-sweep）互为补充：扫描会在一轮中采用不同的搜索角度；work-exhaust 则会重复多轮，直至饱和。

用法

/work-exhaust [K=3] "what we are discovering" [context]

示例：

• /work-exhaust "代码库中所有涉及作业状态转换的位置"
• /work-exhaust 4 "异步作业草稿流程中的边缘情况" "重点关注错误路径和部分失败"
• /work-exhaust "文档解析失败模式"

编排器通常会在研究或审查阶段使用此技能。

神谕在三个位置设门槛（L1）

发现循环并非纯粹的 Agent 面板——一个廉价的确定性神谕（grep/rg、测试、类型检查、运行应用）会在三个不同位置设下门槛。只有在没有神谕可用的领域，才使用有把握的发现器。

1. 循环前的神谕种子（第 1 轮之前）。 运行直接神谕，用精确模式已能枚举的内容为 seen[] 提供种子——例如，用 rg -n "<core-entity>" 查找“所有涉及 X 的位置”。这能让循环以事实为依据，并防止发现器“发现”一次 grep 就能列出的内容（L1：先运行直接神谕）。
2. 在 file:line 处独立重新读取每个条目（L2/L8）。 发现器返回的每个条目都会在其 location 处重新打开，并在进入 seen[] 前根据当前源代码加以确认。绝不直接相信发现器提供的 evidence 引文；应在条目的 reReadSources 中记录重新读取，并设为 workDone:true。如果有可用但尚未运行的神谕，就不接受该条目（默认拒绝）——先运行 grep/测试。
3. 最终完整性神谕，与发现器种子相互独立（L5）。 在宣布无新发现之前，至少运行一个全局神谕，且不得复用发现器的切入角度——例如，对整个代码库运行 rg 查找核心实体、进行范围覆盖差异比较，或检查“模块中哪些文件未出现在任何发现器的列表中”。如果发现了新内容，就将其加入 seen[]，并将 dryCounter 重置为 0（发现器未能覆盖某种形式；该领域尚未穷尽）。这个门槛可以捕捉基础案例中“遗漏 5 个孤立文件”的问题。

False-DRY 防护（角度穷尽 ≠ 领域穷尽）

只有当一轮零新增真正完成了新工作时，才计入 K：

• 如果某轮重新使用了已穷尽的角度（即已在 anglesUsed[] 中且上次结果为 0 的角度），则该轮属于软空轮：不会增加 dryCounter。将其记录为 softEmpty，并使用新的角度重试该轮。
• K 只根据符合条件的轮次计算——每轮都引入一个尚未出现在 anglesUsed[] 中的新角度，或运行最终完整性神谕。如果一个角度已穷尽，并不代表一个领域已穷尽。
• 因此，每轮都必须切换到至少一个尚未穷尽的角度（来源：../work-sweep/SKILL.md）。如果没有新角度，也没有尚未运行的神谕，那么该领域确实已无新发现——停止并记录 stoppedReason:"angles-and-oracles-exhausted"。

工作原理

1. 初始化

   • 加载或清空 seen[]、anglesUsed[]、dryCounter（保存在日志中以便恢复 — 绝不要重置 seen[]，L4）。
   • 运行循环前 oracle 种子（gate 1）→ 使用 oracle 可枚举的项目填充 seen[]。
   • 定义本次发现任务的目标和角度池（来自 work-sweep）。
   • 设置 dry 阈值 K（默认值为 3；K≥2）。通过你的 harness 的 todo/plan 工具，公布形态 + K + 种子数量。

2. 轮次循环（每轮都是并行扇出 → 屏障）

   • 选择至少一个未使用过的新角度（不在 anglesUsed[] 中）（False-DRY 防护）。将所选角度添加到 anglesUsed[]。
   • 在一个并行波次中启动本轮的 finder 子 Agent（每个 finder 启动一个具有相应子 Agent 角色的子 Agent， 只读，因此不使用 worktree，并在后台运行）。Finders 不会看到前几轮的具体发现，但会收到高层目标和 seen[] 的摘要，以避免重复。
   • **屏障：**等待所有 finders 完成，然后对每个结果调用 .filter(Boolean) （处理 Null）。已失效的 finder 会被丢弃并记录，不计为无结果。
   • 对每个返回的项目：运行gate 2（在 file:line 处独立重读）。未通过重读的项目会被丢弃并记录；尚未运行 oracle 的项目先运行 oracle。
   • 将通过筛选的项目与全局 seen[] 去重（与曾发现过的所有内容去重，包括已拒绝的项目 — L4；使用普通集合逻辑，不用 Agent）。将真正的新项目添加到 seen[] 和本轮的 newItems[]。
   • 更新 dry 计数器（带 False-DRY 防护）：
     • 本轮引入了新角度/oracle，且产生了 ≥1 个新项目 → dryCounter = 0。
     • 本轮引入了新角度/oracle，但未产生新项目 → dryCounter += 1（一个符合条件的空轮次）。
     • 本轮只重新运行已耗尽的角度 → softEmpty（dryCounter 不变）；使用新角度重试。
   • 通过你的 harness 的 todo/plan 工具记录 Round N: X new (T total) · angle=<a> · dryCounter Y/K。
   • 当 dryCounter 即将达到 K 时，先运行gate 3（最终完整性 oracle）：如果发现任何新内容， 则设置 dryCounter = 0 并继续；否则停止。

3. 收敛

   • 仅在 dryCounter >= K（gate 3 确认没有新内容后）、stoppedReason:"angles-and-oracles-exhausted"， 或调用方明确指定预算/目标（并已记录）时停止。
   • 返回完整的主对象（见结构化 I/O 契约）+ 每轮摘要 + 完整性说明。
   • 明确记录所有因预算/并发/时间而降低优先级的内容，存入 droppedDueToBudget[]（不得静默设限，L7）。

4. 直接验证与移交

   • 每个已接受的项目都已包含 gate 2 提供的 reReadSources/workDone。对于可使用更强 oracle 的项目（失败的测试、精确的复现命令），在此处运行并记录。
   • 去重后的集合通常会传递给 ../work-refute/SKILL.md（每个项目都会成为一个待反驳的主张）和 ../work-gaps/SKILL.md。

结构化 I/O 契约

有两种模式。每个 finder 都会输出一个单个 finder 项目对象（经过验证，格式错误时重试一次，之后按 workflow-mode §3 丢弃并记录）。循环会验证并返回一个调用方可审计的主对象。

1. 单个 finder 的返回值（每个 finder 一个，包含项目数组）

{
  "angle": "error-paths",
  "items": [
    {
      "id": "job-state-partial-fail",
      "title": "partial failure leaves job in DRAFT with orphaned artifacts",
      "description": "…",
      "location": "src/jobs/transition.ts:142",
      "evidence": "transition.ts:142 — catch swallows error, no rollback of artifact write",
      "reReadSources": ["src/jobs/transition.ts:142"],
      "workDone": true,
      "severity": "high"
    }
  ],
  "roundNotes": "string — what this angle covered and where it felt thin"
}

• severity 枚举：critical | high | medium | low（根据 L6 校准；这是发现提示，权威严重性以 work-refute 后续确定的为准）。
• location 为 file:line（或在不适用文件时使用命名概念）；reReadSources + workDone 包含 gate 2 的重读信息，以便检测并丢弃敷衍的 finder 提交的项目（L2/L8）。

2. 主返回对象（循环验证并返回的内容）

{
  "rounds": [
    {
      "n": 1,
      "anglesUsed": ["grep-seed", "error-paths"],
      "newItems": ["job-state-partial-fail", "…"],
      "dryCounterAfter": 0
    }
  ],
  "seen": ["job-state-partial-fail", "…"],
  "stoppedReason": "k-consecutive-dry",
  "droppedDueToBudget": [],
  "completenessGaps": ["module X has 3 files no angle swept; ran gate-3 grep — clean"]
}

• stoppedReason 枚举：k-consecutive-dry | angles-and-oracles-exhausted | budget | caller-target。
• seen[] 是持久化去重的事实来源（永不重置，L4）。droppedDueToBudget[] 和 completenessGaps[] 会明确记录上限和范围遗漏（L5/L7）。dryCounterAfter 是符合条件的计数器（软空结果不会推动它）。
• 调用方会验证此对象；若循环结果格式错误，会重新请求一次，然后将其作为失败上报——不会悄悄视为“已完成”。

执行机制

以下是 workflow-mode §3 中专用于 LOOP 的实例——一般规则请参阅该文档。

• 日志记录 / 恢复（确定性）：每轮结束后，将 quality-journals/work-exhaust-<task>.json 写入（位于 Agent 的数据 目录下）：

  { "seen": [], "anglesUsed": [], "dryCounter": 0, "rounds": [], "droppedDueToBudget": [] }
  

  恢复时，加载 seen[]、anglesUsed[] 和 dryCounter 这三项，并从它们继续。绝不重置 seen[]（L4——已拒绝的条目不得重新进入），绝不重置 anglesUsed[]（已耗尽的角度不得 重新运行，否则会制造软空结果并破坏 K）。
• 空值处理：失败、出错或为空的 finder 会被过滤（.filter(Boolean)）并记录日志——它不算作零新增轮次，也不会触及 dryCounter。只有当一个符合条件的轮次中所有剩余 finder 都未返回任何新增内容时，干涸计数器才会递增。绝不能把一个失效的 finder 理解为“该领域已无内容”。
• 并发上限：以受控批次启动 finder，批次大小为 min(16, cores−2)（或已配置的上限）；超出的角度排入下一批次。会记录所应用的上限（不静默限流）。
• 预算意识：预算不足时，明确减少角度数量或提前停止，并将其记录在 stoppedReason/droppedDueToBudget[] 中。绝不静默缩减轮次。
• 轮次内的多模态搜索：角度来源于 ../work-sweep/SKILL.md； False-DRY 防护要求每个符合条件的轮次至少使用该集合中的一个全新角度。
• 不设静默上限（L7）：任何未运行的角度、跳过的轮次、丢弃的条目（重新读取失败、预算不足）或降低优先级的尾项，都必须作为一条具名记录写入决策记录，并通过你的 harness todo/plan 工具上报。
• 日志 / 阶段：通过你的 harness todo/plan 工具输出 Round N: X new (T total) · angle=<a> · dryCounter Y/K、softEmpty (exhausted angle) — retry、 gate-3 completeness: +Z new → dryCounter reset 等信息，使循环可以由人工中断。

示例（K=2，“所有 job 状态转换位置”）

Gate 1 (oracle seed): rg -n "transition\(|setState\(" → 4 sites → seen=[s1..s4]
Round 1 · angle=grep-seed + error-paths (fresh)
  finders → 3 items; gate-2 re-read drops 1 (line moved, not a transition)
  dedup vs seen → +2 new (s5,s6)            → dryCounter 0/2
Round 2 · angle=concurrency/races (fresh)
  finders → 1 item; gate-2 OK; +1 new (s7)  → dryCounter 0/2
Round 3 · angle=error-paths (ALREADY in anglesUsed) → 0 new
  → softEmpty (exhausted angle), NOT a dry round → retry with fresh angle
Round 3' · angle=event-emitters (fresh) → 0 new (qualifying) → dryCounter 1/2
Round 4 · angle=cron/background-jobs (fresh) → 0 new → dryCounter would hit 2/2
  → run Gate 3 (final completeness): rg across whole module for the entity,
    independent of finder angles → finds s8 in a file no angle swept
  → s8 enters seen, dryCounter RESET to 0/2, continue
Round 5 · angle=migrations (fresh) → 0 new → dryCounter 1/2
Round 6 · angle=admin-tooling (fresh) → 0 new → Gate 3 clean → dryCounter 2/2 → STOP
stoppedReason="k-consecutive-dry"; seen=[s1..s8]; completenessGaps logged.

请注意，Round 3 没有推进 K（False-DRY 防护：角度耗尽 ≠ 领域已穷尽）；Round 4 中的 Gate 3 重置了计数器（L5：完整性检查独立于 finder 种子）。

集成

• 每轮的角度来源于 ../work-sweep/SKILL.md（该 sweep 的一轮 ≈ 此处的一轮；此技能会重复执行，直到内容干涸）。
• 去重后的集合会传入 ../work-refute/SKILL.md（每个发现的条目 都会成为一项待反驳的主张）和 ../work-gaps/SKILL.md（gate 3 是它的轻量内联版本；完整的 critic 会在收敛后运行）。
• 由 ../work/SKILL.md 编排，它会决定发现集合是否足够庞大或未知，以至于值得运行循环，而非仅执行一次 sweep（workflow-mode §5“按需求调整规模”——如果一次 grep 就能解决一个仅含 3 项的枚举问题，就不要运行循环）。

停止规则（严格）

仅当 dryCounter >= K 时停止，其中 K 只统计符合条件的轮次：

• 符合条件的轮次引入了新的角度（不在 anglesUsed[] 中），或运行了第 3 关完整性预言机， 并且在与 seen[] 去重后产生了 0 个新条目。
• 空结果轮次（重新运行已耗尽的角度）不计入，并且会使用新的角度重试。
• 在第 K 个符合条件的空结果轮次提交前，必须运行第 3 关并确认结果干净；如果发现任何新内容， 则将 dryCounter 重置为 0。
• 仅有的其他停止条件是 angles-and-oracles-exhausted（没有新的角度，也没有尚未运行的预言机）以及 调用方明确指定的 budget/target——两者都记录在 stoppedReason 中。不要因为“已经够了”而提前停止。

这是可靠解决“找出所有内容”问题的方法，不会假装单次扫描——或几次使用相同角度的扫描——就能穷尽所有内容。