Evolution Gate

Evolution Gate

Two-step gate for evolution cycles: first deploy a preview for review, then approve or reject.

Instructions

CRITICAL — NON-INTERACTIVE: Parse the command argument and execute. Never ask follow-up questions. If argument is missing or invalid, display usage and stop.

Step 0: Parse Command

Read $ARGS:

• deploy → Run Pre-Deploy Flow (create preview branch, push, notify)
• approve → Run Approve Flow
• reject [reason] → Run Reject Flow
• No argument or invalid → Display usage:

  Usage:
    /evolution-gate deploy           — create preview branch and push for review
    /evolution-gate approve          — merge preview to production
    /evolution-gate reject [reason]  — discard preview and retry
  
  Current Status:
    [read and display evolution-state.json status]
  

Pre-Deploy Flow

Runs when $ARGS is deploy. Creates a preview branch and pushes to trigger auto-deploy.

D1: Initialize

1. Read factory/evolution-state.json
2. Verify status is "building" or build is complete (all tasks done)
3. Set CYCLE to current_cycle, read deploy_target, get hypothesis info from cycles[]

D2: Pre-Flight Verification

Run quality checks — if blocking issues found, update status to "building", display issues, stop.

Security & quality (from verify-work rubric):

• Hardcoded secrets, SQL injection, XSS, missing input validation
• Debug code, TypeScript any, empty catch blocks

Performance (from verify-performance rubric):

• N+1 queries, unbounded queries, data fetching in loops

Build check:

npm run build 2>&1 || yarn build 2>&1 || pnpm build 2>&1

D3: Create Preview Branch

git checkout -b preview/evolution-cycle-{CYCLE}-{slug}
git add -A
git commit -m "feat: evolution cycle {CYCLE} — {hypothesis titles}

Hypotheses:
- {hyp-id-1}: {title-1}
- {hyp-id-2}: {title-2}

Predicted score change: {baseline} → {predicted} (+{delta})
Stage plan: {stage_plan_ref}
"
git push -u origin preview/evolution-cycle-{CYCLE}-{slug}

Where {slug} is a kebab-case summary of the primary hypothesis (max 30 chars).

D4: Update State

Update factory/evolution-state.json:

• Status: "preview_deployed"
• Current cycle: preview_branch, preview_url (based on Vercel/Netlify pattern from deploy_target.platform)

D5: Slack Notification (if configured)

Send using temp file pattern:

TMPFILE=$(mktemp)
cat > "$TMPFILE" << 'PAYLOAD'
{"text": "🔍 Preview Ready — Cycle {CYCLE}", "blocks": [{"type": "section", "text": {"type": "mrkdwn", "text": "*Preview Deployed* — Cycle {CYCLE}\n\n*Hypotheses:*\n• {title-1}\n• {title-2}\n\n*Preview:* {preview_url}\n\n*Actions:*\n`/evolution-gate approve` or `/evolution-gate reject`"}}]}
PAYLOAD
curl -s -X POST -H 'Content-type: application/json' -d @"$TMPFILE" "$SLACK_WEBHOOK"
rm -f "$TMPFILE"

D6: Switch Back & Display

git checkout {production_branch}

================================================================
  Preview Deployed — Awaiting Human Approval
================================================================
  Cycle:    {CYCLE}
  Branch:   preview/evolution-cycle-{CYCLE}-{slug}
  Preview:  {preview_url}

  Pre-Flight:  verify-work PASS | verify-performance PASS | build PASS

  Actions:
    /evolution-gate approve   — merge to production
    /evolution-gate reject    — discard and try next
================================================================

Approve Flow

Runs when $ARGS is approve.

• approve → Step 1 (Approve Flow)
• reject [reason] → Step 2 (Reject Flow)
• No argument or invalid → Display usage and stop:

  Usage:
    /evolution-gate approve           — merge preview to production
    /evolution-gate reject [reason]   — discard preview and retry
  
  Current Status:
    [read and display evolution-state.json status]
  

Step 1: Approve Flow

1A: Validate State

1. Read factory/evolution-state.json
2. Verify status is "preview_deployed" or "awaiting_approval"
   • If not, display error: "No preview awaiting approval. Current status: [status]"
3. Get current cycle entry from cycles[]
4. Get preview_branch and production_branch from state

1B: Merge to Production

# Switch to production branch
git checkout {production_branch}

# Merge the preview branch
git merge preview/evolution-cycle-{CYCLE}-{slug} --no-ff -m "feat: merge evolution cycle {CYCLE} — {hypothesis titles}

Approved optimization cycle {CYCLE}.
Hypotheses: {hypothesis titles}
Predicted score improvement: +{delta}
"

1C: Tag Release

git tag -a "evolution-cycle-{CYCLE}" -m "Evolution cycle {CYCLE}: {hypothesis titles}"

1D: Clean Up Preview Branch

# Delete local preview branch
git branch -d preview/evolution-cycle-{CYCLE}-{slug}

# Delete remote preview branch
git push origin --delete preview/evolution-cycle-{CYCLE}-{slug}

1E: Archive Stage Plan

mkdir -p plans/archive
mv plans/active/stage-opt-{CYCLE}.md plans/archive/stage-opt-{CYCLE}.md

1F: Update Evolution State

1. Read factory/evolution-state.json
2. Update status to "idle" (ready for next evaluation)
3. Update current cycle entry:

   {
     "status": "approved",
     "score_delta": null
   }
   

   (Score delta will be filled by next /evaluate-product run)
4. Increment current_cycle by 1
5. Increment total_cycles_completed by 1
6. Write back

1G: Push to Remote

git push origin {production_branch}
git push origin --tags

1H: Send Slack Notification (if configured)

SLACK_WEBHOOK="${SLACK_WEBHOOK:-}"

If available:

TMPFILE=$(mktemp)
cat > "$TMPFILE" << 'PAYLOAD'
{
  "text": "✅ Evolution Cycle {CYCLE} Approved",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Cycle {CYCLE} Merged to Production*\n\n*Hypotheses:*\n• {title-1}\n• {title-2}\n\nTagged: `evolution-cycle-{CYCLE}`\nNext: Re-run `/factory evolve` to start next cycle"
      }
    }
  ]
}
PAYLOAD
curl -s -X POST -H 'Content-type: application/json' -d @"$TMPFILE" "$SLACK_WEBHOOK"
rm -f "$TMPFILE"

1I: Display Summary

================================================================
  Evolution Cycle [CYCLE] — Approved
================================================================

  Merged:      preview/evolution-cycle-{CYCLE}-{slug} → {production_branch}
  Tag:         evolution-cycle-{CYCLE}
  Plan:        Archived to plans/archive/stage-opt-{CYCLE}.md

  Hypotheses Applied:
    - [title 1]
    - [title 2]

  Next: Run /factory evolve to evaluate and start next cycle
================================================================

Step 2: Reject Flow

2A: Validate State

1. Read factory/evolution-state.json
2. Verify status is "preview_deployed" or "awaiting_approval"
   • If not, display error: "No preview awaiting approval. Current status: [status]"
3. Get current cycle entry from cycles[]
4. Get preview_branch from state
5. Parse rejection reason from $ARGS (everything after "reject")
   • If no reason provided, use "Rejected without reason"

2B: Delete Preview Branch

# Switch to production branch
git checkout {production_branch}

# Delete local preview branch
git branch -D preview/evolution-cycle-{CYCLE}-{slug}

# Delete remote preview branch
git push origin --delete preview/evolution-cycle-{CYCLE}-{slug}

2C: Archive Stage Plan

mkdir -p plans/archive
mv plans/active/stage-opt-{CYCLE}.md plans/archive/stage-opt-{CYCLE}.md

2D: Update Evolution State

1. Read factory/evolution-state.json
2. Update status to "hypothesizing" (signals: generate new hypotheses)
3. Update current cycle entry:

   {
     "status": "rejected",
     "rejection_reason": "[reason]"
   }
   

4. Add rejected hypotheses to rejected_hypotheses[]:

   {
     "id": "hyp-{CYCLE}-001",
     "title": "[title]",
     "reason": "[rejection reason]",
     "cycle": [CYCLE]
   }
   

   (Add one entry per hypothesis in the rejected batch)
5. Increment current_cycle by 1 (move to next cycle for retry)
6. Write back

2E: Send Slack Notification (if configured)

If SLACK_WEBHOOK is available:

TMPFILE=$(mktemp)
cat > "$TMPFILE" << 'PAYLOAD'
{
  "text": "❌ Evolution Cycle {CYCLE} Rejected",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Cycle {CYCLE} Rejected*\n\n*Reason:* {reason}\n\n*Rejected Hypotheses:*\n• {title-1}\n• {title-2}\n\nNext: Re-run `/factory evolve` to generate new hypotheses"
      }
    }
  ]
}
PAYLOAD
curl -s -X POST -H 'Content-type: application/json' -d @"$TMPFILE" "$SLACK_WEBHOOK"
rm -f "$TMPFILE"

2F: Display Summary

================================================================
  Evolution Cycle [CYCLE] — Rejected
================================================================

  Reason:      [rejection reason]
  Branch:      Deleted preview/evolution-cycle-{CYCLE}-{slug}
  Plan:        Archived to plans/archive/stage-opt-{CYCLE}.md

  Rejected Hypotheses (will not be retried):
    - [title 1]
    - [title 2]

  Next: Run /factory evolve to generate new hypotheses
================================================================

Error Recovery