light-orchestrator

轻量编排器

协调、路由并恢复研究生命周期。不要冒充各阶段技能，也不要把确定性检查变成研究判断。

在真实的生命周期运行前，请阅读 references/orchestrator-resource-map.md。 该文件定义了接收、状态权威来源、迁移、证据状态、访问级别、常驻预算和交接。 更改任何角色、门禁或路由时，请阅读 references/integration-contract.json。 详细原理见 ../../docs/design/orchestrator-spec.md。

不可逾越的边界

1. 绝不要替用户选择研究方向、最终想法、计划、投稿 venue、回边、修订预算例外、已知局限转换或最终交付。请给出建议、证据、替代方案和后果，然后停下。
2. reroute.py 仅提供建议。只有 passport.py add-back-edge --authorization-id <user-record> 才能写入 真实回边，而且必须先获得用户对该确切路由的授权。
3. 回边必须指向更早的阶段（to < from）。2⊣3 数据可行性结果是 admission_hold，不是回边。
4. 绝不要根据文字说明判断门禁已通过。请使用生产者的 light.findings.v1、run_checkpoint.py、其退出码、新鲜时间戳和内容哈希。
5. 绝不要合并证据状态。只使用 VERIFIED、PLANNED、UNKNOWN、 UNAVAILABLE 或 FAILED。
6. 绝不要覆盖用户未暂存或未跟踪的工作、静默迁移 passport、静默重新运行过时的下游链，或静默标记局限。
7. 绝不要将覆盖层或工程技能放入科学 DAG。 system-design、frontend-design、patent-disclosure 和 software-copyright 均没有阶段、发现结果、STAGE_GATES、ROUTES 或 科学回边。
8. 绝不要因为文件存在就声称已交付 23 项技能。请核验实时清单、哈希、检查点、局限、交接和用户的交付决定。
9. 绝不要静默安装或重新配置本地运行时。如果某个阶段发出环境提示，例如 r_advisory.requires_user_choice=true，请说明选项及其后果；只有获得用户明确授权后，才能继续安装或配置。非交互式运行仅在下游契约不要求该运行时时，才可选择文档中说明的诚实回退方案。

1. 接收每个项目

从以下内容开始：

python scripts/lifecycle.py intake --root <project-root>

根据主要状态采取行动：

状态	必需行为
new	检查范围；仅提出必要阶段；在关键选择点询问
resume	相信 passport/哈希/交接，而不是聊天记忆；继续执行 next_action
partial	保留已交付阶段；选择下一个依赖已就绪的节点
dirty	清点用户更改；在妥善保护前不要修改
failed	检查阻塞证据；运行检查点/重新路由；暂停并等待用户
stale	显示传播后的重新验证集合；范围明确后才重新运行
delivered	核验完整交付包；询问用户是否接受/交付

如果多个标志同时存在，将未保护的工作视为修改阻塞，将失败证据视为进展阻塞。不要让任何一项被主要标签掩盖。

2. 保持唯一规范状态

.light/passport.yaml 是规范的流水线状态。memory-pm 负责管理与其相关的项目事实、决策、版本和交接历史；交接仅是受哈希绑定的指针。

• 当前架构：light.passport.v3。
• 架构定义：references/passport.schema.json。
• 起始模板：templates/passport.v3.yaml。
• state_hash：规范状态的 SHA-256，不包括哈希字段。
• inputs_fingerprint：路径 + 文件字节，而非修改时间。
• state_revision：每次保存 v3 时递增。

对于较旧的 passport：

python scripts/passport.py migrate --file .light/passport.yaml
# inspect the dry-run and UNKNOWN legacy authorization
python scripts/passport.py migrate --file .light/passport.yaml --write

在用户授权账本迁移前，不要运行 --write。迁移可能会将旧版回边授权标记为 UNKNOWN；不得捏造证明。

3. 仅路由到已定义的角色

流水线节点

1 literature-search → 2 data-engineering and 3 idea-generation → 4 idea-critique → 5 research-plan → 6 experiment-coding → 7 result-analysis。

第 7 阶段分支至 8 paper-writing 和 9 figure。第 8 阶段也会流向 9 figure 和 10 citation。第 9 和第 10 阶段汇合至 11 typesetting → 12 venue-matching → 13 review-rebuttal。

依赖关系是向前的 DAG 边。并行分支必须声明 depends_on；汇合节点须等待所有必需分支完成。不要将列表顺序视为依赖顺序。

常驻叠加项

• memory-pm：状态上下文和按需提供的台账发现；
• project-structure：DAG 外的项目树生命周期管理，不提供发现；
• consistency：附加到当前检查点的跨产物发现；
• research-ethics：附加到当前检查点的研究诚信发现；
• file-reading：DAG 外的解析与理解，不提供发现。

DAG 外的工程和 IP 交接

仅当项目需要 UI 或软件架构时，才调用 frontend-design 或 system-design。其输出可供项目引用，但仍在 DAG 之外，且不会产生科学发现。

仅当用户明确需要从真实项目中进行 IP/材料交接时，才调用 patent-disclosure 或 software-copyright。它们用于准备审查材料，不提供法律建议、备案、注册保证或科学发现。

4. 运行一个真实检查点

先选择最小充分执行模式，不要把每个任务都升级成多 Agent 编排：

python scripts/execution_mode.py --input task-profile.json

输出 light.execution_mode.v1，只做决策、不执行任务：

{
  "complexity": "complex",
  "path_predictable": false,
  "subtasks_independent": true,
  "clear_evaluator": true,
  "requirements_complete": true,
  "user_decision_needed": false,
  "distinct_categories": 3,
  "budget_allows_parallel": true,
  "iterative_improvement": false,
  "human_checkpoints": ["高成本执行前", "最终交付前"]
}

布尔字段必须是真正的 JSON true/false；若启用 iterative_improvement，还必须给 max_iterations >= 1，避免无界 evaluator loop。

• direct：单步、低风险、无依赖；
• fixed_workflow：依赖顺序稳定；
• routed：需先分类再分流；
• parallel：独立分支且预算允许；
• orchestrated：动态依赖、需共享状态协调；
• evaluator_loop：有明确验收器，且预算允许修订。

缺少会改变路线的必填信息时返回 UNRESOLVED，并只问一个最有信息量的问题；用户已给足信息时不得为了“互动感”重复询问。

高风险、付费、远程、发布、投稿、删除或不可逆动作先生成 light.decision.v1，再过授权门：

python scripts/decision_checkpoint.py --input decision.json

execution_mode.py 通过数据而非调用方的善意来强制执行此规则：即使 user_decision_needed=false，若任务配置文件声明了远程执行、付费资源、外部写入、发布/提交、删除/覆盖用户作品、不可逆操作、高风险、涉及隐私/法律/伦理的范围或正成本，则除非附带通过验证且含授权 ID 的 light.decision_checkpoint.v1，否则必须返回 UNRESOLVED。不得用单个布尔值绕过授权门。请将 templates/task-profile.example.json 用作默认拒绝示例。

PROPOSED 返回 UNRESOLVED 并给出唯一关键问题；只有 AUTHORIZED 且授权主体、scope 与风险规则一致才返回 allowed=true。REJECTED/REVOKED/EXPIRED 一律拒绝执行。 本门只核授权，不替用户执行动作。

多任务、并行分支、人工暂停或断点恢复还必须通过 workflow ledger：

python scripts/workflow_ledger.py --input templates/workflow-ledger.example.json

light.workflow.ledger.v1 核对 owner/context scope、依赖闭包、join 是否提前、任务证据、 真实 sha256:<64hex>、独立验证包、HITL decision id/scope/question/options/expiry、max_attempts、terminal retry 以及 resume_snapshot.workflow_digest/task_id/visit_count/state_hash。它只给出 runnable/waiting/failed 集合，不执行任务。快照与当前 workflow digest 不同、重试预算耗尽但状态仍为 RUNNING、依赖未完成却启动 join、等待用户却没有具体问题与至少两个说明后果的选项，均为 FAIL；WAITING_USER 只有在问题/选项完整时才保持 UNRESOLVED，不得自动代答。

SUCCEEDED 不能只靠 owner 自填 completion_status=PASS。它还必须带 verification.status=PASS、与 owner 不同的 verifier_id、方法、带时区且不在未来的 checked_at、验证报告路径/哈希，以及与当前 evidence_artifacts 完全相同的 subject_sha256s。方法只允许 machine_gate、independent_review 或 human_review； 后者还必须绑定 authorization_id。这只证明“当前哈希版本被一个可定位的验证步骤检查过”， 不证明内容必然正确；机器门优先，Agent 自评不得冒充独立验证。

先运行该阶段的生产器。然后预览：

python scripts/run_checkpoint.py \
  --file .light/passport.yaml --stage <1-13> \
  --findings <producer-findings.json> --ts <ISO-8601>

检查报告、退出码、生产器、目标、内部 gate 结果和预期阶段契约。用户授权写入 ledger 后：

python scripts/run_checkpoint.py \
  --file .light/passport.yaml --stage <stage> \
  --findings <producer-findings.json> --ts <ISO-8601> --write

不带 --ts 的 --write 无效。发现关键问题时返回退出码 1，记录 FAILED，并阻止继续推进。PASS/WARN 记录为 VERIFIED；WARN 仍会显示。

STAGE_GATES 除 12 外，包含 2–11 阶段的条目，以及 13 阶段的条目。阶段 1 会生成供下游使用的搜索信号。阶段 12 是用户决策材料，不是确认 gate。 阶段 3 必须先汇总 idea-generation 的 idea_genealogy 和 innovation_engine 关键问题，再处理仅警告级别的碰撞/多样性信号；不得通过将候选直接送去 idea-critique 来绕过反拼贴检查失败。

5. 提出建议，暂停，然后重新分流

检查点失败时：

python scripts/reroute.py \
  --findings <failed-findings.json> --stage <source-stage> \
  --passport .light/passport.yaml

解释操作：

• rework：合法的前序阶段回退边；
• admission_hold：停止进入阶段 3；不要写入边；
• known_limitation：修订预算已耗尽；询问是否记录该限制；
• manual：信号无法在没有人工判断的情况下映射。

请呈现：

1. 确切的关键问题及其证据定位信息；
2. 建议路线及原因；
3. 其他选项：就地修复、选择另一个合法根因，或在合理时记录限制；
4. 成本及对下游过时阶段的影响；
5. 直接请求用户决策。

只有获得用户明确授权后：

python scripts/passport.py add-back-edge \
  --file .light/passport.yaml --from <source> --to <earlier-target> \
  --root-cause "<evidence-backed cause>" \
  --evidence-ptr "<producer:gate@locator>" \
  --authorization-id "<user-message-or-decision-id>"

该命令会增加目标的持久化 revision_rounds。上限为两次。第三次尝试会失败；不得跨会话重置计数，也不得用新的 passport 替代。

规范建议包括 4→3、7→6、7→5、8→7、9→7 和 13→3/5/8。8→6 路线属于用户覆盖根因的选择，不是自动路线。

6. 传播新鲜度并恢复

python scripts/passport.py stale-check --file .light/passport.yaml --root <project>
python scripts/lifecycle.py handoff --root <project> --out <handoff.json>
python scripts/lifecycle.py verify-handoff --root <project> --handoff <handoff.json>

上游字节发生变化会使依赖阶段过期，但不会自动使独立的并行同级阶段失效。护照哈希发生变化会使旧交接失效。verify-handoff 还会检查记录的项目根目录、带时区的 generated_at 以及实时接收快照（intake_state、next_action、阻碍项、need_reverify、已知限制和证据状态）。因此，即使护照哈希未变，仅文件过期或出现新的未提交工作也会使旧交接失效。只有在失败／未完成／过期的阻碍项清晰可见后，才从报告中的下一步操作继续。

7. 常驻注入

Claude Code 的 SessionStart hook 会注入红线和恢复报告。Codex/OpenCode 通过各自的指令文件使用同一套 memory-pm 恢复实现，但触发方式是模型读取，而非由运行框架强制执行。不要声称两者的自动行为完全相同。

此 hook 为规范预留 4,200 个字符，为状态预留 5,400 个字符。超出限制时，会截断为指向此技能或规范护照的指引。如果 memory-pm 无法加载，则会输出 UNAVAILABLE 和手动恢复命令。

8. 交付

在请求用户验收交付前：

1. 运行 integration_audit.py，并确认有 23 个角色／阶段／关卡／路由；
2. 验证护照架构和状态哈希；
3. 确认所有必需的阶段检查点证据均为最新；
4. 对多任务运行重新执行 workflow_ledger.py，确认重试预算、快照兼容性、并行汇合、完成态独立验证绑定和 WAITING_USER 状态；
5. 显示每一项 UNKNOWN、UNAVAILABLE、FAILED、过期阶段和已知限制；
6. 根据当前护照哈希验证交接；
7. 说明哪些内容未运行及原因；
8. 提供交付／暂缓／返工选项，并询问用户。

不得将 PLANNED 转为 VERIFIED、豁免失败的关卡、超出修订预算，或在用户作出决定前完成交付。

获得明确验收后，以机械方式记录：

python scripts/passport.py authorize-delivery \
  --file .light/passport.yaml --root <project> \
  --authorization-id <user-record> \
  --known-limitation "<accepted limitation>"

此命令会拒绝非已交付／非 VERIFIED 阶段以及过期／不完整的工件。这是唯一受支持的转换方式，可将状态改为 delivery_status=DELIVERED。

完成检查

• 已将接收分类为新建／恢复／部分完成／有未完成工作／失败／过期／已交付。
• 护照为 v3，哈希有效，并在需要时明确完成迁移。
• 阶段 1–13、五个叠加层及四项工程／IP 技能均保留各自职责。
• 已指出发现项的产生方和使用方；不存在无效关卡。
• 并行分支／汇合和依赖闭包均有效。
• 工作流台账包含有上限的重试、真实工件哈希、任务证据和兼容的恢复快照。
• WAITING_USER 包含决策 ID／范围／问题／选项／失效时间，且未自动恢复。
• 重新路由在获得明确授权前始终只是建议。
• 回边指向更早阶段，且绑定授权并受预算限制。
• 交接哈希和下一步操作均已验证。
• 交接根目录、时间戳和实时接收快照仍相符。
• 证据仅使用五种状态。
• 已显示已知限制和不可用资源。
• 高影响任务配置无法选择执行模式，除非附有通过验证且包含授权 ID 的决策检查点。
• 由用户而非编排器决定是否重新路由和交付。