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

First choosethe minimal sufficient execution mode, and do not escalate every task into multi-agent orchestration:

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

Output light.execution_mode.v1, only make decisions, do not execute tasks:

{
  "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": ["高成本执行前", "最终交付前"]
}

Boolean fields must be真正的 JSON true/false; if enabled iterative_improvement, you must also provide max_iterations >= 1, to avoid an unbounded evaluator loop.

• direct: single-step, low-risk, no dependencies;
• fixed_workflow: dependency order is stable;
• routed: needs classification first, then routing;
• parallel: independent branches and budget allows;
• orchestrated: dynamic dependencies, requires shared-state coordination;
• evaluator_loop: has a clear verifier, and budget allows revision.

When required information that would change the route is missing, return UNRESOLVED, and ask only one most informative question; when the user has already provided enough information, do not repeatedly ask for the sake of a “sense of interaction.”

For high-risk, paid, remote, publishing, submission, deletion, or irreversible actions, first generate light.decision.v1, then pass the authorization gate:

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 returns UNRESOLVED and gives the single key question; only when AUTHORIZED and the authorization subject, scope, and risk rules are consistent does it return allowed=true。REJECTED/REVOKED/EXPIRED is always refused execution. This gate only checks authorization; it does not execute actions on the user’s behalf.

Multi-task, parallel branches, human pause, or checkpoint recovery must also pass the workflow ledger:

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

light.workflow.ledger.v1 Check owner/context scope, dependency closure, whether join is early, task evidence, real sha256:<64hex>, independent verification package, HITL decision id/scope/question/options/expiry,max_attempts, terminal retry, and resume_snapshot.workflow_digest/task_id/visit_count/state_hash. It only provides the runnable/waiting/failed sets and does not execute tasks. If the snapshot differs from the current workflow digest, retry budget is exhausted but still RUNNING, dependencies are incomplete yet join is started, or it is waiting for the user but has no specific question and at least two options with consequence explanations, all are FAIL;WAITING_USER Only when the question/options are complete does it remain UNRESOLVED, and it must not automatically answer on the user’s behalf.

SUCCEEDED cannot rely only on the owner’s self-filled completion_status=PASS. It must also carry verification.status=PASS, a verifier_iddifferent from the owner, method, a timezone-aware and not-in-the-future checked_at, verification report path/hash, and the same as the current evidence_artifacts exactly identicalof subject_sha256s. The method only allows machine_gate、independent_review or human_review; the latter must also bind authorization_id. This only proves that “the current hash version has been checked by a locatable verification step,” not that the content is necessarily correct; machine gates take priority, and agent self-assessment must not masquerade as independent verification.

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. Re-execute for multi-task runs workflow_ledger.py, confirming retry budget, snapshot compatibility, parallel join, completion-state independent verification binding, and WAITING_USER status;
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.