stelow-workflow-router

Router

The router is the workflow control plane. It runs once per stage transition. It does not implement any stage logic itself; it only moves state forward and loads the next stage skill.

Contract

Input:

• state.md (workflow state with current_stage set)
• The previous skill's ## Hand-off (workflow mode) block
• STELOW_WORKFLOW=1 + STELOW_STATE=<path-to-state.md> markers

Output:

• state.md advanced (via scripts/stelow advance <next-candidate>)
• The next stage's SKILL.md loaded for the next agent turn
• A new ## Hand-off (router) block appended to state.md

Algorithm

# 1. Ask the helper what is legal from here. The helper owns the rule: the
#    intent route, the review-mode policy and the graph all live in
#    stages.yaml, and it is the only implementation of them. Re-deriving the
#    set here was a FOURTH implementation — coarser than the helper's (no
#    intent route, no review mode) — and it accepted moves the helper then
#    refused (`diff-gate` in Auto), so the workflow stalled between the two
#    answers.
current=$(scripts/stelow status --json | jq -r .current_stage)
next=$(extract_hand_off_field next-candidate)

# 2. Validate next against the helper's own answer.
allowed=$(scripts/stelow next --json | jq -r '.allowed[]')
forward=$(scripts/stelow next --json | jq -r '.forward[]')
if ! echo "$allowed" | grep -qx "$next"; then
  echo "router: rejected '$next' (allowed from $current: $allowed)"
  # The forward move is the way out: it is the successor of the current
  # stage, with every stage this review mode skips already accounted for.
  next=$(echo "$forward" | head -1)
  if [ -z "$next" ]; then
    echo "router: no forward move from $current — the workflow is done or blocked"
    exit 1
  fi
  echo "router: taking the forward move '$next'"
fi

# 3. Advance state and load next stage.
scripts/stelow advance "$next"

# 4. Append router Hand-off (audit).
cat >> "$STELOW_STATE" <<EOF
## Hand-off (router) — $(date -Iseconds)
from        : $current
to          : $next
skill loaded: stelow-product-$next
EOF