/wave-execute

name: wave-execute
description: >
  EXECUTE a lean wave — plan story DAG + file-ownership batches via CLI,
  dispatch full-sdc per story, fan-in check, hand off merge to @devops.
  Use when: wave-execute, run wave, epic wave, parallel stories SDC.
user-invocable: true
argument-hint: "{wave-id} --stories s1.md,s2.md [yolo|interactive] [--dry-run] [--no-confirm]"
agent: aiox-master
depends_on: ["full-sdc"]

wave-execute (lean EXECUTE)

Run a **wave of stories**: deterministic plan (DAG + file partition) → dispatch `/full-sdc` (or `aiox sdc` + skills) per story → fan-in → `@devops` merge-back.

**Not in scope:** cockpit `wave launch`, conductor loops, product worktree WL registry, companion spawn surface.

Depends on skill **full-sdc** and CLI `aiox wave` / `aiox sdc`.

Invocation

/wave-execute {wave-id} --stories path1.md,path2.md [yolo|interactive] [--dry-run] [--no-confirm]

# pure CLI plan
aiox wave plan --stories path1.md,path2.md --wave-id {wave-id} --mode yolo --save
aiox wave next {wave-id}

Yolo/parallel dispatch requires a positive explicit `AIOX_MODEL_BUDGET_CEILING_USD`. Each child intent is scanned and bound to its existing story before a model executor is invoked.

CLI (mechanical)

# From epic directory (C3) — preferred
aiox wave from-epic --epic-dir docs/framework/epics/core-super-update \
  --filter 'CORE-SU.C' --wave-id CORE-SU-C --mode yolo

# Or explicit paths
aiox wave plan --stories a.md,b.md,c.md --wave-id WAVE-1 --mode yolo --save

# Advance / next batch (auto-completes stories already Done / sdc completed)
aiox wave advance WAVE-1
aiox wave next WAVE-1

# After a child full-sdc finishes or fails
aiox wave mark WAVE-1 {story-id} --status completed
aiox wave mark WAVE-1 {story-id} --status failed --notes "qg breaker"

# Report
aiox wave report WAVE-1
aiox wave status WAVE-1

# Per story (child full-sdc)
aiox sdc plan {story} --mode yolo
aiox sdc next {story}
# … run skill for phase …
aiox sdc verify {story} {phase} --mark

State: `.aiox/waves/{wave-id}/state.json` Controller: `wave-run.js` + `dispatch-adapter.js` (C2) + `epic-glue.js` (C3)

EXECUTE stages

Stage 1 — Preflight (CLI computes)

1. Resolve story paths (must exist). 2. Before automated dispatch, validate the shared budget ceiling and scan each story-bound child intent; any rejection blocks that child before model use. 3. `aiox wave plan … --save` — do **not** re-invent the DAG by grepping in prose. 4. Judge the plan: Ready stories only for develop-heavy waves; flag Draft that still need validate; halt if `executor == quality_gate` when those fields exist. 5. `--dry-run` → print plan and **stop**.

Stage 2 — Confirm

Show batches (parallel vs sequenced by file ownership). Get human OK unless `--no-confirm` or mode `yolo`.

Stage 3 — Dispatch batches

For each batch **in order**:

1. For **each story in the batch** (parallel when multi-agent available):

• Run **full-sdc** execute protocol (skill `full-sdc` / `/aiox-full-sdc`)
• Preferred: `spawn_subagent` with `aiox-master` (or dedicated coordinator) prompt:

`Execute full-sdc on {story-path} mode={mode}. Use aiox sdc plan/next/verify. Do not git push.`

• Sequential fallback: run full-sdc inline one story at a time

2. Wait for all stories in the batch to reach SDC `completed` (or HALT). 3. On a blocked/failed story: do **not** dispatch dependents still waiting on it; continue independent later batches only if their deps are satisfied. 4. Cascade: if story B `dependsOn` A and A failed → mark B blocked in the wave report (do not fake green).

Stage 4 — Fan-in

Before merge:

• Re-check File List overlap across branches/stories that ran in parallel (partition should prevent; verify).
• Surface conflicts to human + `@devops`; never silent overwrite.

Stage 5 — Merge-back

Hand off to **`@devops` only** (push/PR/merge exclusive). Provide handoff:

handoff:
  from: wave-execute
  to: devops
  wave_id: "{wave-id}"
  stories: ["…"]
  branches: ["feat/…"]
  next_action: "create/merge PRs per repo policy"

Partition rules (same as CLI)

• Topological sort on `depends_on` (deps outside the wave = already satisfied).
• Within a ready set: max non-overlapping File List subset runs in one batch; overlapping remainder in later batches.
• Empty File List → treated as non-conflicting (still may be sequential by deps).

Modes

| Mode | Behavior | |------|----------| | `interactive` | Confirm plan; pause between batches | | `yolo` | Auto-confirm plan; autonomous full-sdc children | | `--dry-run` | Plan only |

Blocking conditions

• Wave plan `errors` non-empty (cycle)
• Story path missing
• full-sdc integrity HALT (Done before close)
• QG circuit breaker on a story
• Fan-in conflict unresolved

Strip checklist

• [x] No cockpit-only spawn commands required
• [x] CLI First plan/partition
• [x] full-sdc children only (no invented parallel AC)
• [x] @devops exclusive merge