light-orchestrator

name

light-orchestrator

description

Coordinate and recover multi-stage Light research projects through the canonical .light/passport.yaml state, stages 1-13, resident overlays, checkpoints, findings, parallel joins, stale propagation, handoffs and user-authorized reroutes. Use for a new/resumed/partial/dirty/failed/stale/delivered research project; when the user says continue, resume, take over, checkpoint, reroute, recover or deliver; or when work crosses two or more Light research stages. Never turn frontend-design/system-design/patent-disclosure/software-copyright or overlays into stages, never execute a suggested back-edge without explicit user authorization, and never declare delivery from file existence alone.

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.