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.
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:

```bash
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:

```bash
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 编排：

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

输出 `light.execution_mode.v1`，只做决策、不执行任务：

```json
{
  "complexity": "complex",
  "path_predictable": false,
  "subtasks_independent": true,
  "clear_evaluator": true,
  "requirements_complete": true,
  "user_decision_needed": false,
  "distinct_cate