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 before a real lifecycle run. It defines intake, state authority, migration, evidence states, access tiers, resident budget and handoff. Read references/integration-contract.json when changing any role, gate or route. The detailed rationale is ../../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.
2. 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.
3. 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.
4. 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.
5. Never collapse evidence states. Use only VERIFIED, PLANNED, UNKNOWN, UNAVAILABLE or FAILED.
6. Never overwrite dirty/untracked user work, silently migrate a passport, silently rerun a stale downstream chain, or silently mark a limitation.
7. 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.
8. Never claim 23-skill delivery because files exist. Verify the live inventory, hashes, checkpoints, limitations, handoff and user delivery decision.
9. 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;
4. cost and effect on downstream stale stages;
5. 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 状态；
5. surface every UNKNOWN, UNAVAILABLE, FAILED, stale stage and known limitation;
6. verify the handoff against the current passport hash;
7. state what was not run and why;
8. 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.