# Orchestrator — Advanced Flow Patterns

**Status:** Proposed
**Epic:** orchestrator-flow-advanced
**Depends on:** v2.7.17-orchestrator (flow-runner already shipped)

## Why

The orchestrator (shipped v2.7.17) runs sequential research/analysis flows on local Qwen. Each step is a linear dependency chain: A → B → C. This works for analysis flows (code-review, investigate) but limits three high-value scenarios:

1. **Parallel research** — "Analyze this from 3 angles" currently requires 3 separate runs. A single flow with parallel branches would halve the wall-clock time.
2. **Adaptive depth** — "Investigate bug, and if it's a security issue, escalate to security review" requires conditional branching. Currently all steps run unconditionally.
3. **Human-in-the-loop** — "Review the diff and approve before applying" requires the orchestrator to pause and wait for user input before proceeding.

The patterns from the Ion hybrid workflow engine (trigger rules, event sourcing, approval gates, variable substitution) provide a proven vocabulary for these scenarios — we adapt the patterns without adopting the project.

## What Changes

### Trigger rules on step deps
Add `trigger_rule?: 'all_success' | 'one_success' | 'all_done'` to the `Step` type. Default `all_success` preserves existing behavior.

- `all_success` — step runs when ALL dependencies complete successfully (current behavior)
- `one_success` — step runs when ANY dependency completes (parallel research: whichever finishes first seeds the synthesis)
- `all_done` — step runs when all deps finish regardless of status (cleanup/reporting steps)

### Variable substitution in step prompts
Add `$stepId.output` and `$stepId.output.field` syntax in step prompts. The flow-runner resolves these before dispatching.

- `$research.output` — the full text output of step with id "research"
- `$classify.output.severity` — the "severity" field from step output parsed as YAML/JSON frontmatter

### Human approval gate
New `kind: 'approval'` step type that pauses the flow and publishes a permission frame to the user channel. Flow resumes when the user approves or rejects.

### Event-sourced step log
Append-only event log for each step execution (start, complete, fail, skip, pause, resume). Enables deterministic resume after coder restart without polling.

## Non-Goals
- No YAML DAG format (stay with TypeScript flow definitions)
- No CLI tool (orchestrator stays in-app)
- No replacement of the existing flow definitions — additive changes only
- No VM sandbox or WASM