/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`](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. 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