work

/work（别名：/ultracode、/quality-orchestrator）——完整质量工作流编排器

这是让整套质量模式系统变得实用且自动化的核心编排器。

工作流执行模型（分派前先说明形态）

没有 JS 编排引擎——“工作流模式”是一种由 Agent 手动执行的规范：启动子 Agent（使用正确的子 Agent 角色，在隔离的工作树中，后台运行），等待全部完成，然后收集结果。每次分派前，都要在所用工具的待办事项／计划工具或决策记录中明确说明形态。形态一共只有三种：

• PIPELINE（默认）——每个事项独立地流经各个阶段，阶段之间没有屏障（审查发现 B 的同时验证发现 A）。耗时 = 单个事项链中最慢的耗时。这是大多数多阶段质量工作的形态。
• PARALLEL / BARRIER（并行／屏障）——阻塞，直到阶段 N-1 的所有事项完成；仅当存在真正的跨事项依赖时才合理：对完整集合去重／合并、零结果时提前退出，或跨事项比较（为所有候选项评定排名、综合所有判定）。“这样更整洁”不构成合理理由——拿不准时就用流水线。
• LOOP（直到无新项／直到预算耗尽）——基数未知的工作：重复多轮，直到连续 K≥2 轮都没有产生新的唯一事项（直到无新项），或剩余预算不足以再完成一轮有用工作（直到预算耗尽）。每一轮都要进行分派，并针对持久化的 seen[] 设置去重屏障。

完整模型——机制、气味检查、标准 Review 流程——见 references/workflow-mode.md。这些形态旨在防范的失败模式见 references/anti-error-lessons.md（L1–L8，已在下方各阶段中概述并落实）。不要在此重复这些文档的内容；引用它们即可。

核心理念（内置）

1. 先直接验证——如果存在确定性判定依据（测试、编译器、git rev-list --left-right --count、精确 grep 加人工确认、运行应用、类型检查等），就使用它。Agent 评审小组只用于不存在良好判定依据的领域。
2. 诚实拆解——将工作拆分为正确性可相对独立验证的部分。
3. 按需扩展——小任务（“检查 main 是否同步”）→ 直接执行命令。中高复杂度的实现／评审／审计／设计 → 使用包含各阶段、模式和机制的完整流程。
4. 不设隐性上限／一切明确记录——限制预算、并发数或角度数量时，记录被排除的内容。

反错误经验 L1–L8（本编排器要防范的失败模式）

这些经验来自真实审计，而非理论（作为依据的案例——一个 /improve 索引高估了一个日志漂移问题、错误驳回了一个真实的隔离漏洞，还漏掉了 5 个孤立文件——见 references/anti-error-lessons.md）。每条经验都已在上方对应阶段落实为具体操作；以下是索引：

• L1 — 先使用直接判定依据 → 核心理念 #1；最终关卡对未运行的判定依据采取失败关闭策略。
• L2 — 验证者独立重读源代码 → Review 阶段；契约要求填写 reReadSources[]。
• L3 — 采用视角多元的检查角度，而非 N 个相同的反驳者 → Review 阶段；对安全／身份验证／多租户／数据完整性／正确性，必须如此。
• L4 — 根据 SEEN 去重，而非根据幸存项去重 → Research／Discovery 循环 + 日志中的 seen[] 永不重置。
• L5 — 完整性检查要问“范围内有哪些内容尚未覆盖？” → 最终关卡的全局判定依据范围覆盖检查。
• L6 — 双向校准严重性 → 最终关卡的严重性标准（同时防范误报和漏报）。
• L7 — 不设隐性上限 → 预算／并发机制；明确列出 droppedDueToCaps[] 条目。
• L8 — 只有实际完成工作，判定才有效 → Review 阶段 + 契约验证（敷衍的反驳视为弃权，发现仍然有效）。

何时应使用协调器

• 任何实现、大规模重构、审查、安全性／性能／正确性分析、架构决策，或中高复杂度的迁移。
• 项目中的 AGENTS.md 和质量钩子会在达到此门槛时提醒你（并尽量确保这一点显而易见）。

低复杂度的机械性更改可以跳过协调器，或采用非常轻量的流程。

协调器遵循的高级流程

1. 任务接收 + 复杂度评估

   • 理解用户的目标。
   • 收集信号（当前 git diff --stat、最近几轮中修改的文件、请求用语的性质：“实现”“审计”“修复”“设计如何……”、涉及的环节数量）。
   • 分类：低／中／高。
   • 如果是低复杂度 → 直接处理 + 最少限度的验证。记录决策。
   • 如果是中／高复杂度 → 继续完整工作流。

2. 阶段选择（常见且实用的阶段；协调器可以串联这些阶段，也可以只运行其中一部分）。每个阶段都会说明其形式，以及落实的经验教训。

   • 理解 — PARALLEL/BARRIER：并行阅读者／对相关子系统使用 work-sweep → 整理出该领域的结构化图谱（设置屏障，确保图谱完整后再做决策）。
   • 设计（选择方案时）— PARALLEL/BARRIER：work-judge 对所有候选方案排序（跨条目比较 ⇒ 设置屏障）。
   • 研究／探索 — LOOP：work-sweep + work-exhaust，每轮都与 seen[] 去重（L4：与 SEEN 去重，绝不与 survivors 去重——否则被评审驳回的条目会重新出现，循环将永远无法收敛）。
   • 实现 — 正常的 Agent 工作；若并行 Agent 会修改代码，则使用工作树隔离（独立的工作树）+ 频繁直接进行 oracle 检查（L1）。对于“尝试 N 种方法”，调用 work-tournament。
   • 审查 — PIPELINE：查找（work-sweep）→ 与所有曾见过的内容去重（设置屏障；使用普通集合逻辑，绝不交给 Agent）→ 针对 CODE 差异：先运行 work-check（优先 oracle 的 PASS/FAIL；它会将深入的可维护性审查委托给 work-review）→ 审查一有结果，就立即用 work-refute 逐项反驳发现（采用不同视角）→ work-gaps。代码更改必须先运行 work-check，再运行 work-refute。work-review 通过 work-check 启动，并且只能按名称调用（disable-model-invocation: true）——直接调用 /work-review；它不会自动触发。落实以下经验教训：
     • L2 — 每位验证者都必须重新打开每个 file:line，并从当前源码中确认；绝不接受调查者引用的证据。记录 reReadSources[]。
     • L3 — 对于安全／身份验证／多租户／数据完整性／正确性相关的主张，必须分配不同的审查视角（伪造／欺骗、配置或 Realm 混淆、替代代码路径、下游影响、回归）——这是强制要求，不可选择跳过。N 个相同的反驳者只是重复劳动，并非视角多样。
     • L8 — refuted 判定（用于否定一项发现）只有在 workDone: true 且 reReadSources 非空时才有效。敷衍的驳回属于弃权：过滤并记录，且该发现保留到下一轮。needs_oracle 判定采用失败关闭策略——先运行 L1 oracle，再做决定。投票按证据权重计算（一项证据充分的反驳 > 两项空洞的“毫无疑问”投票）。
   • 迁移／转换 — PIPELINE：发现位置 → 在隔离的工作树中进行转换 → 逐项验证。
   • 最终关卡（work-gaps，PARALLEL/BARRIER）：见下文“最终关卡”——对未运行的 oracle 采用失败关闭策略，并进行双向严重性 + 范围覆盖检查。

3. 模式组合

   • 编排器会为每个阶段决定具体采用的模式。
   • 标准 Review 流程（PIPELINE；完整版本见 references/workflow-mode.md §2）：work-sweep → 与此前见过的所有内容去重（屏障，纯集合逻辑）→ 对于 CODE 差异：先运行 work-check（先由预言机判定 PASS/FAIL；它会将深入的可维护性审查委托给 work-review）→ work-refute（如果是生成式，则运行 work-judge）→ work-gaps。代码变更中，work-check 会在 work-refute 之前运行；work-review 通过 work-check 调用，且只能按名称调用（disable-model-invocation: true — 直接调用 /work-review）。可组合技能的完整列表：work-refute、work-judge、work-exhaust、work-sweep、work-gaps、work-tournament、work-check、work-review。
   • 它可以嵌套工作流（将另一个工作流运行或专注的模式技能作为子步骤调用）。对于“此变更是否实现了其声称的效果？”这类轻量检查，可以委托给 work-check。

4. 执行机制应用（这些机制让模式更可靠；完整表格见 references/workflow-mode.md §3）

   • 结构化输出 + 重试：每个子 Agent 都返回经过架构验证的 ```json 对象（见下方契约），绝不返回供调用方用 grep 检索的散文。调用方验证结构，并在输出格式错误时重新请求一次；若结果仍然格式错误，则丢弃并记录日志，绝不默默接受。
   • 工作树隔离：任何会并行创建或修改文件的子 Agent，都在自己的隔离工作树中运行。只读扇出无需隔离。
   • 空值处理（具体要求）：已退出 / 出错 / 结果为空 / 弃权（L8）的子 Agent 都会被过滤掉（.filter(Boolean)）——不计作一票。过滤后，根据剩余投票者重新计算判定门槛，并记录被剔除项（决策记录 + 你的执行框架的 todo/plan 工具）。绝不能把一个已退出的反驳者算作“反驳”或“通过”。例如，一个需要多数反驳的 3 人验证小组中，若 1 个 Agent 退出，门槛应重新计算为“剩余 2 人中 2 人都必须反驳”；记录 droppedVoters: ["v2:errored"]。
   • 并发上限：分波次受控启动，每波约为 min(16, cores−2)（或使用配置的上限）。超出部分排队；上限本身也必须记录（若隐藏，就是静默上限）。
   • 预算 → 无静默上限（明确约束）：跟踪大致的 token 消耗。预算不足时，明确减少 N 或提前停止——绝不能默默缩减。每次缩减都要在决策记录中写为具名条目（droppedDueToCaps[]），并且通过你的执行框架的 todo/plan 工具呈现（例如，"budget: capped verify panel 5→3, dropped lenses [regression, downstream]"）。读者必须能够分辨结果是“完整”还是“已截断”。
   • 日志记录 / 恢复：长时间运行时，将日志写入 quality-journals/<task-id>.json（位于 Agent 的数据目录下；架构见下文）。恢复时，加载 seen[] 且绝不重置（L4），避免已拒绝的发现重新进入，以及已穷尽的方向被重复运行。
   • 模型 / Agent 角色覆盖：为子 Agent 选择合适的角色（扫描时使用广泛探索角色，验证时使用通用 / 专用审查角色，设计时使用规划角色），并为每个步骤选择合适的人设。
   • log() / phase()：通过你的执行框架的 todo/plan 工具宣布每个阶段和关键决策，确保实时计划、当前阶段和发现清晰可见，且可由人工中断。
   • 无静默上限（L7）：每项 top-N 限制、抽样、未运行的方向、跳过的轮次、因预算而丢弃的发现，或未呈现的次要问题，都必须作为具名条目记录（决策记录 + 你的执行框架的 todo/plan 工具），说明丢弃了什么以及原因。

5. 可见性与人工检查点

   • 大量使用你的执行框架的 todo/plan 工具，公开实时计划、当前阶段和关键发现。
   • 编排器在每个阶段结束后生成清晰的产物，供人工阅读，并决定继续、调整还是停止。
   • 由于采用日志记录机制，可以在工作中途调用（“继续我之前开始的质量审查”）。

6. 标记「完成」前的最终关卡（PARALLEL/BARRIER — 需要完整的存活项集合）

   • 对未运行的验证器采取失败关闭策略（L1）：扫描每个存活的发现，检查是否存在可用但尚未运行的验证器（测试、类型检查、精确 grep + 手动确认、git、运行应用）。如果存在，关卡会阻止标记为 done — 先运行验证器，再重新评估。存在可用但未运行验证器的存活项，尚未完成。
   • 范围覆盖（L5）：至少运行一个全局验证器（针对核心实体的全仓库 grep、范围覆盖 diff），以找出扇出列表之外的项目 — 即孤立文件／未触及模态这一类。记录 seen[] 与已扫描项。
   • 双向严重性评估（L6）：根据已验证的现实影响重新校准每个存活项的严重性，并防范两类错误 — 推测性缺口不能标为 high，可被利用的问题不能标为 low。评估标准：high = 确实可触达 + 造成损害 + 当前未覆盖（说明可触达的依据）；medium = 有可能但未经验证／没有验证器；low = 仅影响外观／已缓解。
   • work-gaps 会询问「LIST／SCOPE 未覆盖哪些内容？」；剩余的高优先级缺口应记为待办事项，或作为明确风险写入决策记录。

结构化 I/O 契约（围栏 JSON — 必填字段 + 枚举值）

每个子 Agent 都会输出一个围栏式 ```json 代码块，由调用方验证。自由格式字符串会破坏校准；severity 和 verdict 是枚举值。证据需以 file:line 和调用方可重新打开核查的简短引文形式提供。各技能的 schema 位于对应的模式技能中；以下是编排器共用的发现格式及其维护的记录。

单条发现契约（验证器返回的内容）

{
  "id": "host-derived-tenant",
  "claim": "string — the asserted finding",
  "verdict": "confirmed_bug | refuted | survives | needs_oracle",
  "severity": "critical | high | medium | low",
  "evidence": ["upload-handler.ts:171 — storage tenant from ?hostname, post-auth, no session binding"],
  "reReadSources": ["src/http/routes/upload-handler.ts:171"],
  "lensesUsed": ["spoofing", "alternative-code-path", "downstream-effect"],
  "workDone": true,
  "oracleAvailable": "string | null — e.g. 'read the migration runner' / null if none",
  "oracleRun": true,
  "reasoning": "string",
  "scenario": "concrete repro / why-not-exploitable"
}

调用方强制执行的验证规则：refuted verdict（即否定一条发现的 verdict）只有在 workDone: true 且 reReadSources 非空时才有效（L8）；否则视为弃权 — 过滤并记录日志，且该发现继续存活。needs_oracle verdict ⇒ 失败关闭：先运行 L1 验证器，再作决定（在验证器运行之前，不要将其视为已否定或仍存活）。oracleAvailable != null && !oracleRun 会阻止标记为 done（L1，失败关闭）。格式错误 → 重新请求一次，然后丢弃并记录日志。

决策记录（关于「如何达到高置信度」的唯一真实来源）

{
  "complexity": "low | medium | high",
  "complexityJustification": "string",
  "phasesDone": ["understand", "review", "final-gate"],
  "shapePerPhase": { "understand": "barrier", "review": "pipeline" },
  "patternsApplied": [
    { "phase": "review", "skill": "work-refute", "params": { "N": 3, "lenses": ["spoofing","realm-confusion","alt-path"], "K": 2 } }
  ],
  "seen": ["host-derived-tenant", "journal-drift"],
  "anglesUsed": ["storage-path", "token-issuer", "design-doc-intent"],
  "oraclesAttempted": [{ "oracle": "read the migration runner", "result": "apply path is fs scan, never reads journal" }],
  "survivors": [{ "id": "host-derived-tenant", "severity": "high" }],
  "droppedDueToCaps": [
    { "what": "lenses [regression, downstream]", "why": "budget", "where": "todo/plan tool + record" }
  ],
  "remainingGaps": ["string"]
}

日志（<task-id>.json，位于 Agent 的数据目录下的 quality-journals/ 中）— 用于恢复工作

{
  "taskId": "audit-2026-06-14-isolation",
  "phasesDone": ["understand", "find", "verify"],
  "seen": ["host-derived-tenant", "journal-drift", "orphan-refs"],
  "anglesUsed": ["storage-path", "token-issuer", "design-doc-intent"],
  "survivors": [{ "id": "host-derived-tenant", "severity": "high" }],
  "droppedDueToCaps": [{ "what": "round 4", "why": "until-dry K=2 met", "where": "record" }]
}

恢复时：加载 seen[]，且绝不重置（L4）— 被拒绝的发现继续排除在外，已穷尽的分析角度不再重复运行。

实例——多租户隔离审计（流水线 + 屏障 + 循环）

/work "audit the upload + storage paths of a multi-tenant app for tenant isolation" → 高复杂度（数据边界、判断、范围未知）。

1. 理解（BARRIER）：3 个读取者分别检查身份验证中间件、上传处理程序（存储）和租户隔离设计文档。屏障 → 先获得完整地图，再做决定。输出：子系统地图；anglesUsed += [storage-path, token-issuer, design-doc-intent]。
2. 查找（work-sweep）→ 对照 seen[] 执行去重屏障（普通集合逻辑）。发现：host-derived-tenant（一个 ?hostname 存储覆盖项 + 共享身份提供方导致的令牌混淆）和 journal-drift。
3. 验证（PIPELINE，L2/L3/L8）：随着每项发现的审查完成，逐项验证。
   • journal-drift：有判定依据 → 读取迁移运行器。应用路径是一次文件系统扫描，从不读取日志 ⇒ { "verdict": "refuted", "severity": "low", "oracleRun": true, "workDone": true }（L1/L6 防范误报）。
   • host-derived-tenant：透镜 [spoofing, realm-confusion, alternative-code-path]。一个草率的“发行方检查可以解决问题”结论没有提供 reReadSources → 弃权（L8），被过滤并记录，该发现仍然保留。不同视角的透镜重新读取存储处理程序 + 设计文档 ⇒ { "verdict": "confirmed_bug", "severity": "high", "reReadSources": ["upload-handler.ts:171"], "workDone": true }（防范漏报）。
4. 完整性（LOOP，持续到无新发现，K=2）：对租户实体进行全局 grep，发现5 个孤立引用文件从未出现在扇出列表中（L5）；将其加入 seen[]，第 4 轮没有新发现 ⇒ 停止，记录 droppedDueToCaps += [{ "what": "round 4", "why": "until-dry K=2 met" }]。
5. 最终关卡：每个保留项的 oracleAvailable 均已运行（L1 故障时默认关闭检查通过）；严重程度已重新锚定（L6）。决策记录：survivors: [host-derived-tenant:high]，seen = 3 项发现 + 5 个孤立文件，droppedDueToCaps 已记录。

与钩子和 AGENTS.md 集成

• 项目质量钩子会在复杂工作中检测重要编辑或任务完成，并发出醒目标注，强烈建议调用编排器。
• AGENTS.md 包含强制策略：对于中等/高复杂度的实现/审查/修复/设计/审计，在宣布工作完成前必须使用编排器（或以同等严谨度明确组合这些模式）。
• 编排器本身遵循“按需升级”规则——对于琐碎任务，它会拒绝运行繁重机制，并说明原因。

高层调用示例

• 完成长时间的实现后：/work "review the changes I just made to the draft-generation flow for correctness, robustness, and state issues"
• 设计决策：/work "help me choose the right architecture for real-time updates in a kanban board"
• 完整审计：/work "perform an end-to-end audit of the upload-handling and SLA-calculation paths"

编排器会拆解任务，运行适当的子模式（可能将 work-refute、work-judge、work-exhaust 等作为子技能调用），应用相应机制，并给出高置信度结果及推理轨迹。

这是完整 ultracode 风格质量系统的实际实现，可跨不同工具环境移植。请使用它。