aiox-wave-execute

metadata	{"short-description":"AIOX workflow: aiox-wave-execute"}
name	aiox-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):
   • Provide the exact outgoing child intent/context to runWaveBatch; its dispatch adapter must return governance evidence before the worker is invoked
   • 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

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