light-orchestrator

Light orchestrator

Coordinate, route and recover the research lifecycle. Do not impersonate the

stage skills and do not turn a deterministic check into a research judgment.

Read

[references/orchestrator-resource-map.md](references/orchestrator-resource-map.md)

before a real lifecycle run. It defines intake, state authority, migration,

evidence states, access tiers, resident budget and handoff. Read

[references/integration-contract.json](references/integration-contract.json)

when changing any role, gate or route. The detailed rationale is

[../../docs/design/orchestrator-spec.md](../../docs/design/orchestrator-spec.md).

Non-negotiable boundaries

1. Never choose the research direction, final idea, plan, venue, back-edge,

revision-budget exception, known-limitation conversion or final delivery

for the user. Present a recommendation, evidence, alternatives and

consequences, then stop.

1. reroute.py is advisory. Only

passport.py add-back-edge --authorization-id <user-record> may write a

real back-edge, and only after the user authorizes that exact route.

1. A back-edge must go to an earlier stage (to < from). The 2⊣3 data

feasibility result is an admission_hold, not a back-edge.

1. Never call a gate passed from prose. Use a producer's

light.findings.v1, run_checkpoint.py, its exit code, a fresh timestamp

and a content hash.

1. Never collapse evidence states. Use only VERIFIED, PLANNED, UNKNOWN,

UNAVAILABLE or FAILED.

1. Never overwrite dirty/untracked user work, silently migrate a passport,

silently rerun a stale downstream chain, or silently mark a limitation.

1. Never put an overlay or engineering skill in the scientific DAG.

system-design, frontend-design, patent-disclosure and

software-copyright have no stage, findings, STAGE_GATES, ROUTES or

scientific back-edge.

1. Never claim 23-skill delivery because files exist. Verify the live

inventory, hashes, checkpoints, limitations, handoff and user delivery

decision.

1. Never silently install or reconfigure local runtimes. If a stage emits an

environment advisory such as r_advisory.requires_user_choice=true, present

the choices and consequences; only continue with install/config after an

explicit user authorization. Non-interactive runs may choose the documented

honest fallback only when the downstream contract does not require that

runtime.

1. Intake every project

Start with:

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

Act on the primary state:

| State | Required behavior |

|---|---|

| new | inspect scope; propose only needed stages; ask at strategic choices |

| resume | trust passport/hash/handoff over chat memory; continue next_action |

| partial | preserve delivered stages; choose the next dependency-ready node |

| dirty | inventory user changes; do not mutate until they are protected |

| failed | inspect blocking evidence; run checkpoint/reroute; stop for user |

| stale | show the propagated reverify set; rerun only after scope is clear |

| delivered | verify the full delivery package; ask the user to accept/deliver |

If multiple flags coexist, treat dirty work as a mutation blocker and failed

evidence as a progression blocker. Do not hide either behind the primary label.

2. Keep one canonical state

.light/passport.yaml is the canonical pipeline state. memory-pm owns project

facts, decisions, versions and handoff history around it; a handoff is only a

hash-bound pointer.

• Current schema: light.passport.v3.
• Schema: references/passport.schema.json.
• Starter: templates/passport.v3.yaml.
• state_hash: SHA-256 of canonical state excluding the hash field.
• inputs_fingerprint: path + file bytes, not mtime.
• state_revision: increments on every v3 save.

For an older 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

Do not run --write until the user authorizes ledger migration. Migration may

mark a legacy back-edge authorization UNKNOWN; it must not invent proof.

3. Route only the defined roles

Pipeline nodes

1 literature-search → 2 data-engineering and 3 idea-generation → 4

idea-critique → 5 research-plan → 6 experiment-coding → 7 result-analysis.

Stage 7 forks to 8 paper-writing and 9 figure. Stage 8 also feeds 9 figure and

10 citation. Stages 9 and 10 join at 11 typesetting → 12 venue-matching → 13

review-rebuttal.

Dependencies are forward DAG edges. Parallel branches must declare

depends_on; a join waits for every required branch. Do not treat list order

as dependency order.

Resident overlays

• memory-pm: state context and on-demand ledger findings;
• project-structure: off-DAG project-tree lifecycle, no findings;
• consistency: cross-artifact findings attached to the current checkpoint;
• research-ethics: integrity findings attached to the current checkpoint;
• file-reading: off-DAG parsing/understanding, no findings.

Off-DAG engineering and IP handoff

Invoke frontend-design or system-design only when the project needs a UI or

software architecture. Their outputs may be referenced by the project, but

they remain off-DAG and do not produce scientific findings.

Invoke patent-disclosure or software-copyright only when the user explicitly

needs IP/material handoff from a real project. They prepare review materials,

not legal advice, filings, registration guarantees or scientific findings.

4. Run a real checkpoint

先选择最小充分执行模式，不要把每个任务都升级成多 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 enforces this rule by data, not by caller goodwill: even

when user_decision_needed=false, a task profile that declares remote

execution, paid resources, external writes, publish/submit, delete/overwrite

of user work, irreversible action, high risk, private/legal/ethics-sensitive

scope, or positive cost must return UNRESOLVED unless it carries a passing

light.decision_checkpoint.v1 with an authorization ID. A single boolean must

not bypass the authorization gate. Use

templates/task-profile.example.json as the fail-closed example.

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 自评不得冒充独立验证。

Run the stage's producer first. Then preview:

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

Inspect report, exit code, producer, target, inner gate findings and expected

stage contract. After the user authorizes the ledger write:

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

--write without --ts is invalid. A critical finding returns exit 1,

records FAILED, and blocks progression. PASS/WARN records VERIFIED; WARN

still remains visible.

STAGE_GATES has entries for 2–11 except 12, plus 13. Stage 1 produces search

signals for downstream consumption. Stage 12 is a user decision packet, not a

confirmation gate.

Stage 3 must aggregate idea-generation's idea_genealogy and

innovation_engine critical findings before the warn-only collision/diversity

signals; anti-collage failures cannot be bypassed by sending the candidate

straight to idea-critique.

5. Suggest, stop, then reroute

On a failed checkpoint:

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

Interpret actions:

• rework: a legal earlier-stage back-edge;
• admission_hold: stop entry to stage 3; do not write an edge;
• known_limitation: revision budget is exhausted; ask whether to record it;
• manual: the signal cannot be mapped without human judgment.

Present:

1. the exact critical finding and evidence locator;
2. the recommended route and why;
3. alternatives: repair in place, choose another legal root cause, or record a

limitation when justified;

1. cost and effect on downstream stale stages;
2. a direct user decision request.

Only after the user's exact authorization:

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>"

The command increments the target's durable revision_rounds. The limit is

two. A third attempt fails; do not reset the count across sessions or replace

it with a fresh passport.

Canonical suggestions are 4→3, 7→6, 7→5, 8→7, 9→7, and

13→3/5/8. An 8→6 route is a user root-cause override, not an automatic route.

6. Propagate freshness and recover

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>

An upstream byte change stales dependent stages. It does not automatically

invalidate independent parallel siblings. A changed passport hash invalidates

the old handoff. verify-handoff also checks the recorded project root,

timezone-bearing generated_at and the live intake snapshot

(intake_state, next_action, blockers, need_reverify,

known limitations and evidence state). A file-only stale change or new dirty

work therefore invalidates an old handoff even when the passport hash did not

change. Resume from the reported next action only after failed/dirty/stale

blockers are visible.

7. Resident injection

Claude Code's SessionStart hook injects red lines plus the resume report.

Codex/OpenCode consume the same memory-pm resume implementation through their

instruction files, but their trigger is model-read rather than harness-forced.

Do not claim identical automatic behavior.

The hook budgets 4,200 characters for discipline and 5,400 for state. On

overflow it truncates to a pointer to this skill or the canonical passport. If

memory-pm cannot load, it emits UNAVAILABLE and the manual resume command.

8. Delivery

Before asking the user to accept delivery:

1. run integration_audit.py and confirm 23 roles/stages/gates/routes;
2. validate passport schema and state hash;
3. verify all required stage checkpoint evidence is current;
4. 对多任务运行重新执行 workflow_ledger.py，确认 retry budget、snapshot compatibility、

parallel join、完成态独立验证绑定和 WAITING_USER 状态；

1. surface every UNKNOWN, UNAVAILABLE, FAILED, stale stage and known

limitation;

1. verify the handoff against the current passport hash;
2. state what was not run and why;
3. present delivery/hold/rework choices and ask the user.

Do not convert PLANNED to VERIFIED, waive a failed gate, exceed the revision

budget, or finalize delivery without the user's decision.

After explicit acceptance, record it mechanically:

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

The command refuses non-delivered/non-VERIFIED stages and stale/incomplete

artifacts. It is the only supported transition to delivery_status=DELIVERED.

Completion check

• [ ] Intake classified new/resume/partial/dirty/failed/stale/delivered.
• [ ] Passport is v3, hash-valid and explicitly migrated if needed.
• [ ] Stages 1–13, five overlays and four engineering/IP skills retained their roles.
• [ ] Findings producer and consumer are named; no dead gate exists.
• [ ] Parallel fork/join and dependency closure are valid.
• [ ] Workflow ledger has bounded retries, real artifact hashes, task evidence and compatible resume snapshot.
• [ ] WAITING_USER carries decision id/scope/question/options/expiry and was not auto-resumed.
• [ ] Reroute remained advice until explicit authorization.
• [ ] Back-edge is earlier-directed, authorization-bound and budgeted.
• [ ] Handoff hash and next action verify.
• [ ] Handoff root, timestamp and live intake snapshot still match.
• [ ] Evidence uses only the five states.
• [ ] Known limitations and unavailable resources are visible.
• [ ] High-impact task profiles cannot select an execution mode until a passing decision checkpoint with authorization ID is attached.
• [ ] User, not orchestrator, decided reroute and delivery.