diff --git a/.github/workflows/sdlc-hitl.yml b/.github/workflows/sdlc-hitl.yml
new file mode 100644
index 0000000000..7c9914704d
--- /dev/null
+++ b/.github/workflows/sdlc-hitl.yml
@@ -0,0 +1,520 @@
+name: "egg: SDLC HITL Decision Handler"
+
+# This workflow handles Human-In-The-Loop (HITL) decisions for the SDLC pipeline.
+# It triggers when issue comments are edited (checkbox state changes) and
+# updates the contract state accordingly.
+#
+# The workflow implements a 30-second debounce to prevent rapid-fire updates
+# when humans check/uncheck multiple boxes in quick succession.
+
+on:
+  issue_comment:
+    types: [edited]
+
+permissions:
+  contents: write
+  issues: write
+
+# Prevent concurrent HITL runs for the same issue
+concurrency:
+  group: sdlc-hitl-${{ github.event.issue.number }}
+  cancel-in-progress: false
+
+jobs:
+  handle-decision:
+    name: Handle HITL decision
+    runs-on: ubuntu-latest
+    # Only trigger on comments that contain HITL decision markers
+    # Authorization: Only jwbron can trigger HITL decisions, and bot cannot trigger itself
+    if: >-
+      contains(github.event.comment.body, '<!-- egg-hitl-decision') &&
+      github.event.sender.login == 'jwbron' &&
+      github.event.sender.login != 'james-in-a-box' &&
+      github.event.sender.login != 'james-in-a-box[bot]'
+
+    env:
+      BOT_USERNAME: james-in-a-box
+      ISSUE_NUMBER: ${{ github.event.issue.number }}
+
+    steps:
+      - name: Generate bot token
+        id: bot-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.BOT_APP_ID }}
+          private-key: ${{ secrets.BOT_APP_PRIVATE_KEY }}
+
+      - name: Parse decision changes
+        id: parse
+        env:
+          COMMENT_BODY: ${{ github.event.comment.body }}
+          PREVIOUS_BODY: ${{ github.event.changes.body.from }}
+        run: |
+          set -euo pipefail
+          # Extract decision ID from marker
+          # Format: <!-- egg-hitl-decision id=decision-N -->
+          DECISION_ID=$(echo "$COMMENT_BODY" | grep -oP '<!-- egg-hitl-decision id=\K[a-z0-9-]+' | head -1)
+
+          if [[ -z "$DECISION_ID" ]]; then
+            echo "No decision ID found in comment"
+            echo "has_decision=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          echo "decision_id=${DECISION_ID}" >> "$GITHUB_OUTPUT"
+          echo "has_decision=true" >> "$GITHUB_OUTPUT"
+
+          # Parse checkbox states from current and previous body
+          # Format: - [x] Option label or - [ ] Option label
+
+          # Extract selected options from current body
+          SELECTED_CURRENT=$(echo "$COMMENT_BODY" | grep -oP '^\s*-\s*\[x\]\s*\K.+' || true)
+          SELECTED_PREVIOUS=$(echo "$PREVIOUS_BODY" | grep -oP '^\s*-\s*\[x\]\s*\K.+' || true)
+
+          # Compare to detect changes
+          if [[ "$SELECTED_CURRENT" != "$SELECTED_PREVIOUS" ]]; then
+            echo "checkbox_changed=true" >> "$GITHUB_OUTPUT"
+            echo "selected_option=${SELECTED_CURRENT}" >> "$GITHUB_OUTPUT"
+          else
+            echo "checkbox_changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Check debounce
+        if: steps.parse.outputs.has_decision == 'true' && steps.parse.outputs.checkbox_changed == 'true'
+        id: debounce
+        env:
+          GH_TOKEN: ${{ steps.bot-token.outputs.token }}
+          DECISION_ID: ${{ steps.parse.outputs.decision_id }}
+        run: |
+          set -euo pipefail
+
+          DEBOUNCE_SECONDS=30
+
+          # Wait for debounce period FIRST to allow rapid edits to settle
+          echo "Waiting ${DEBOUNCE_SECONDS}s for debounce..."
+          sleep "$DEBOUNCE_SECONDS"
+
+          # After waiting, check if we're the only run still processing
+          JQ_FILTER='[.workflow_runs[] | select(.status == "in_progress" or .status == "queued")'
+          JQ_FILTER+=' | select(.head_branch == "main")] | length'
+          RECENT_RUNS=$(gh api "repos/${{ github.repository }}/actions/workflows/sdlc-hitl.yml/runs" \
+            --jq "$JQ_FILTER")
+
+          # Validate RECENT_RUNS is numeric (issue #6)
+          RECENT_RUNS=${RECENT_RUNS:-0}
+          if ! [[ "$RECENT_RUNS" =~ ^[0-9]+$ ]]; then
+            echo "Warning: RECENT_RUNS is not numeric, defaulting to 0"
+            RECENT_RUNS=0
+          fi
+
+          if [[ "$RECENT_RUNS" -gt 1 ]]; then
+            echo "Debounce: Another run is in progress, skipping"
+            echo "should_process=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "should_process=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Checkout repository
+        if: steps.debounce.outputs.should_process == 'true'
+        uses: actions/checkout@v4
+        with:
+          token: ${{ steps.bot-token.outputs.token }}
+          fetch-depth: 0
+
+      - name: Find and checkout issue branch
+        if: steps.debounce.outputs.should_process == 'true'
+        id: branch
+        env:
+          GH_TOKEN: ${{ steps.bot-token.outputs.token }}
+        run: |
+          set -euo pipefail
+
+          # Validate issue number is numeric (issue #10 - path traversal prevention)
+          if ! [[ "$ISSUE_NUMBER" =~ ^[0-9]+$ ]]; then
+            echo "Invalid issue number: ${ISSUE_NUMBER}"
+            exit 1
+          fi
+
+          BRANCH_NAME="egg/issue-${ISSUE_NUMBER}"
+
+          if git ls-remote --heads origin "${BRANCH_NAME}" | grep -q "${BRANCH_NAME}"; then
+            echo "branch_name=${BRANCH_NAME}" >> "$GITHUB_OUTPUT"
+            echo "branch_exists=true" >> "$GITHUB_OUTPUT"
+            git checkout "${BRANCH_NAME}"
+            git pull origin "${BRANCH_NAME}"
+          else
+            echo "Branch ${BRANCH_NAME} not found"
+            echo "branch_exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Update contract with decision
+        if: steps.branch.outputs.branch_exists == 'true'
+        id: update
+        env:
+          GH_TOKEN: ${{ steps.bot-token.outputs.token }}
+          DECISION_ID: ${{ steps.parse.outputs.decision_id }}
+          SELECTED_OPTION: ${{ steps.parse.outputs.selected_option }}
+          BRANCH_NAME: ${{ steps.branch.outputs.branch_name }}
+        run: |
+          set -euo pipefail
+          CONTRACT_PATH=".egg-state/contracts/${ISSUE_NUMBER}.json"
+
+          if [[ ! -f "$CONTRACT_PATH" ]]; then
+            echo "Contract not found at ${CONTRACT_PATH}"
+            echo "contract_updated=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # Find the decision by ID and update it
+          DECISION_INDEX=$(jq --arg id "$DECISION_ID" \
+            '.decisions | to_entries | .[] | select(.value.id == $id) | .key' \
+            "$CONTRACT_PATH")
+
+          if [[ -z "$DECISION_INDEX" ]]; then
+            echo "Decision ${DECISION_ID} not found in contract"
+            echo "contract_updated=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # Update the decision
+          TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+          jq --arg idx "$DECISION_INDEX" \
+             --arg resolution "$SELECTED_OPTION" \
+             --arg timestamp "$TIMESTAMP" \
+             --arg actor "${{ github.event.sender.login }}" \
+            '.decisions[$idx | tonumber].resolved = true |
+             .decisions[$idx | tonumber].resolution = $resolution |
+             .decisions[$idx | tonumber].resolved_by = $actor |
+             .decisions[$idx | tonumber].resolved_at = $timestamp' \
+            "$CONTRACT_PATH" > /tmp/contract.json
+
+          mv /tmp/contract.json "$CONTRACT_PATH"
+
+          # Add audit entry
+          AUDIT_ENTRY=$(jq -n \
+            --arg timestamp "$TIMESTAMP" \
+            --arg actor "${{ github.event.sender.login }}" \
+            --arg decision "$DECISION_ID" \
+            --arg resolution "$SELECTED_OPTION" \
+            '{
+              timestamp: $timestamp,
+              actor: $actor,
+              role: "human",
+              action: "update",
+              field_path: ("decisions." + $decision),
+              old_value: null,
+              new_value: $resolution,
+              reason: "HITL decision resolved"
+            }')
+
+          jq --argjson entry "$AUDIT_ENTRY" '.audit_log += [$entry]' \
+            "$CONTRACT_PATH" > /tmp/contract.json
+          mv /tmp/contract.json "$CONTRACT_PATH"
+
+          # Commit the update with retry logic to handle race conditions
+          git add "$CONTRACT_PATH"
+          git commit -m "Resolve HITL decision ${DECISION_ID} for issue #${ISSUE_NUMBER}"
+
+          # Retry push with rebase on conflict (handles race conditions)
+          MAX_RETRIES=3
+          for i in $(seq 1 $MAX_RETRIES); do
+            if git push origin "${BRANCH_NAME}"; then
+              echo "Push succeeded"
+              break
+            elif [[ $i -eq $MAX_RETRIES ]]; then
+              echo "Push failed after $MAX_RETRIES attempts"
+              echo "contract_updated=false" >> "$GITHUB_OUTPUT"
+              exit 1
+            else
+              echo "Push failed (attempt $i/$MAX_RETRIES), trying rebase..."
+              git pull --rebase origin "${BRANCH_NAME}" || {
+                echo "Rebase failed, cannot resolve conflict automatically"
+                echo "contract_updated=false" >> "$GITHUB_OUTPUT"
+                exit 1
+              }
+            fi
+          done
+
+          echo "contract_updated=true" >> "$GITHUB_OUTPUT"
+
+      - name: Check for phase advancement
+        if: steps.update.outputs.contract_updated == 'true'
+        id: advance
+        env:
+          GH_TOKEN: ${{ steps.bot-token.outputs.token }}
+          BRANCH_NAME: ${{ steps.branch.outputs.branch_name }}
+        run: |
+          set -euo pipefail
+          CONTRACT_PATH=".egg-state/contracts/${ISSUE_NUMBER}.json"
+          CURRENT_PHASE=$(jq -r '.current_phase' "$CONTRACT_PATH")
+
+          # Check if all decisions for current phase are resolved
+          UNRESOLVED=$(jq '[.decisions[] | select(.resolved == false)] | length' "$CONTRACT_PATH")
+
+          if [[ "$UNRESOLVED" -eq "0" ]]; then
+            echo "All decisions resolved"
+
+            # Determine next phase
+            case "$CURRENT_PHASE" in
+              refine)
+                NEXT_PHASE="plan"
+                ;;
+              plan)
+                NEXT_PHASE="implement"
+                ;;
+              implement)
+                # Implement doesn't advance via HITL - uses review cycle
+                NEXT_PHASE=""
+                ;;
+              *)
+                NEXT_PHASE=""
+                ;;
+            esac
+
+            if [[ -n "$NEXT_PHASE" ]]; then
+              echo "Advancing to ${NEXT_PHASE} phase"
+              echo "next_phase=${NEXT_PHASE}" >> "$GITHUB_OUTPUT"
+              echo "should_advance=true" >> "$GITHUB_OUTPUT"
+
+              # Update contract phase
+              jq --arg phase "$NEXT_PHASE" '.current_phase = $phase' \
+                "$CONTRACT_PATH" > /tmp/contract.json
+              mv /tmp/contract.json "$CONTRACT_PATH"
+
+              git add "$CONTRACT_PATH"
+              git commit -m "Advance to ${NEXT_PHASE} phase for issue #${ISSUE_NUMBER}"
+
+              # Retry push with rebase on conflict
+              MAX_RETRIES=3
+              for i in $(seq 1 $MAX_RETRIES); do
+                if git push origin "${BRANCH_NAME}"; then
+                  echo "Push succeeded"
+                  break
+                elif [[ $i -eq $MAX_RETRIES ]]; then
+                  echo "Push failed after $MAX_RETRIES attempts"
+                  exit 1
+                else
+                  echo "Push failed (attempt $i/$MAX_RETRIES), trying rebase..."
+                  git pull --rebase origin "${BRANCH_NAME}" || {
+                    echo "Rebase failed, cannot resolve conflict automatically"
+                    exit 1
+                  }
+                fi
+              done
+            else
+              echo "should_advance=false" >> "$GITHUB_OUTPUT"
+            fi
+          else
+            echo "${UNRESOLVED} decisions still pending"
+            echo "should_advance=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Post status comment
+        if: steps.update.outputs.contract_updated == 'true'
+        env:
+          GH_TOKEN: ${{ steps.bot-token.outputs.token }}
+          DECISION_ID: ${{ steps.parse.outputs.decision_id }}
+          SELECTED_OPTION: ${{ steps.parse.outputs.selected_option }}
+          SHOULD_ADVANCE: ${{ steps.advance.outputs.should_advance }}
+          NEXT_PHASE: ${{ steps.advance.outputs.next_phase }}
+        run: |
+          set -euo pipefail
+          # Use printf to safely construct comment body (prevents command injection)
+          if [[ "$SHOULD_ADVANCE" == "true" ]]; then
+            BODY=$(printf 'Decision **%s** resolved: %s\n\nAll pending decisions resolved. Advancing to **%s** phase.\n\n--- Authored by egg' \
+              "$DECISION_ID" "$SELECTED_OPTION" "$NEXT_PHASE")
+          else
+            BODY=$(printf 'Decision **%s** resolved: %s\n\n--- Authored by egg' \
+              "$DECISION_ID" "$SELECTED_OPTION")
+          fi
+
+          gh issue comment "${ISSUE_NUMBER}" --body "$BODY"
+
+      - name: Trigger pipeline continuation
+        if: steps.advance.outputs.should_advance == 'true'
+        env:
+          GH_TOKEN: ${{ steps.bot-token.outputs.token }}
+          NEXT_PHASE: ${{ steps.advance.outputs.next_phase }}
+        run: |
+          set -euo pipefail
+          # Trigger the SDLC pipeline workflow to continue with the next phase
+          if ! gh workflow run sdlc-pipeline.yml \
+            --field issue_number="${ISSUE_NUMBER}" \
+            --field starting_phase="${NEXT_PHASE}"; then
+            echo "::error::Failed to trigger sdlc-pipeline.yml workflow"
+            exit 1
+          fi
+
+  # ============================================================
+  # Handle phase approval comments
+  # ============================================================
+  handle-approval:
+    name: Handle phase approval
+    runs-on: ubuntu-latest
+    # Trigger on comments that approve a phase (e.g., "LGTM", "approved", checkbox approval)
+    # Authorization: Only jwbron can trigger approvals, and bot cannot trigger itself
+    if: >-
+      !contains(github.event.comment.body, '<!-- egg-hitl-decision') &&
+      (
+        contains(github.event.comment.body, '<!-- egg-phase-approval') ||
+        contains(github.event.comment.body, '[x] Approve')
+      ) &&
+      github.event.sender.login == 'jwbron' &&
+      github.event.sender.login != 'james-in-a-box' &&
+      github.event.sender.login != 'james-in-a-box[bot]'
+
+    env:
+      ISSUE_NUMBER: ${{ github.event.issue.number }}
+
+    steps:
+      - name: Generate bot token
+        id: bot-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.BOT_APP_ID }}
+          private-key: ${{ secrets.BOT_APP_PRIVATE_KEY }}
+
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          token: ${{ steps.bot-token.outputs.token }}
+          fetch-depth: 0
+
+      - name: Find and checkout issue branch
+        id: branch
+        env:
+          GH_TOKEN: ${{ steps.bot-token.outputs.token }}
+        run: |
+          set -euo pipefail
+
+          # Validate issue number is numeric (path traversal prevention)
+          if ! [[ "$ISSUE_NUMBER" =~ ^[0-9]+$ ]]; then
+            echo "Invalid issue number: ${ISSUE_NUMBER}"
+            exit 1
+          fi
+
+          BRANCH_NAME="egg/issue-${ISSUE_NUMBER}"
+
+          if git ls-remote --heads origin "${BRANCH_NAME}" | grep -q "${BRANCH_NAME}"; then
+            echo "branch_name=${BRANCH_NAME}" >> "$GITHUB_OUTPUT"
+            echo "branch_exists=true" >> "$GITHUB_OUTPUT"
+            git checkout "${BRANCH_NAME}"
+            git pull origin "${BRANCH_NAME}"
+          else
+            echo "Branch ${BRANCH_NAME} not found"
+            echo "branch_exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Process approval
+        if: steps.branch.outputs.branch_exists == 'true'
+        id: approve
+        env:
+          GH_TOKEN: ${{ steps.bot-token.outputs.token }}
+          BRANCH_NAME: ${{ steps.branch.outputs.branch_name }}
+        run: |
+          set -euo pipefail
+          CONTRACT_PATH=".egg-state/contracts/${ISSUE_NUMBER}.json"
+
+          if [[ ! -f "$CONTRACT_PATH" ]]; then
+            echo "Contract not found"
+            echo "approved=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          CURRENT_PHASE=$(jq -r '.current_phase' "$CONTRACT_PATH")
+
+          # Determine next phase
+          case "$CURRENT_PHASE" in
+            refine)
+              NEXT_PHASE="plan"
+              ;;
+            plan)
+              NEXT_PHASE="implement"
+              ;;
+            *)
+              echo "Cannot advance from ${CURRENT_PHASE} via approval"
+              echo "approved=false" >> "$GITHUB_OUTPUT"
+              exit 0
+              ;;
+          esac
+
+          echo "Advancing from ${CURRENT_PHASE} to ${NEXT_PHASE}"
+
+          # Update contract (capture old phase before update to fix audit log)
+          TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+          jq --arg phase "$NEXT_PHASE" \
+             --arg old_phase "$CURRENT_PHASE" \
+             --arg timestamp "$TIMESTAMP" \
+             --arg actor "${{ github.event.sender.login }}" \
+            '.current_phase = $phase |
+             .audit_log += [{
+               timestamp: $timestamp,
+               actor: $actor,
+               role: "human",
+               action: "transition",
+               field_path: "current_phase",
+               old_value: $old_phase,
+               new_value: $phase,
+               reason: "Phase approved by human"
+             }]' \
+            "$CONTRACT_PATH" > /tmp/contract.json
+
+          mv /tmp/contract.json "$CONTRACT_PATH"
+
+          git add "$CONTRACT_PATH"
+          git commit -m "Approve and advance to ${NEXT_PHASE} phase for issue #${ISSUE_NUMBER}"
+
+          # Retry push with rebase on conflict (handles race conditions)
+          MAX_RETRIES=3
+          for i in $(seq 1 $MAX_RETRIES); do
+            if git push origin "${BRANCH_NAME}"; then
+              echo "Push succeeded"
+              break
+            elif [[ $i -eq $MAX_RETRIES ]]; then
+              echo "Push failed after $MAX_RETRIES attempts"
+              echo "approved=false" >> "$GITHUB_OUTPUT"
+              exit 1
+            else
+              echo "Push failed (attempt $i/$MAX_RETRIES), trying rebase..."
+              git pull --rebase origin "${BRANCH_NAME}" || {
+                echo "Rebase failed, cannot resolve conflict automatically"
+                echo "approved=false" >> "$GITHUB_OUTPUT"
+                exit 1
+              }
+            fi
+          done
+
+          {
+            echo "approved=true"
+            echo "next_phase=${NEXT_PHASE}"
+            echo "previous_phase=${CURRENT_PHASE}"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Post approval comment
+        if: steps.approve.outputs.approved == 'true'
+        env:
+          GH_TOKEN: ${{ steps.bot-token.outputs.token }}
+          NEXT_PHASE: ${{ steps.approve.outputs.next_phase }}
+          PREVIOUS_PHASE: ${{ steps.approve.outputs.previous_phase }}
+          SENDER_LOGIN: ${{ github.event.sender.login }}
+        run: |
+          set -euo pipefail
+          # Use printf to safely construct comment body (prevents command injection)
+          BODY=$(printf 'Phase **%s** approved by @%s.\n\nAdvancing to **%s** phase.\n\n--- Authored by egg' \
+            "$PREVIOUS_PHASE" "$SENDER_LOGIN" "$NEXT_PHASE")
+
+          gh issue comment "${ISSUE_NUMBER}" --body "$BODY"
+
+      - name: Trigger pipeline continuation
+        if: steps.approve.outputs.approved == 'true'
+        env:
+          GH_TOKEN: ${{ steps.bot-token.outputs.token }}
+          NEXT_PHASE: ${{ steps.approve.outputs.next_phase }}
+        run: |
+          set -euo pipefail
+          if ! gh workflow run sdlc-pipeline.yml \
+            --field issue_number="${ISSUE_NUMBER}" \
+            --field starting_phase="${NEXT_PHASE}"; then
+            echo "::error::Failed to trigger sdlc-pipeline.yml workflow"
+            exit 1
+          fi
diff --git a/.github/workflows/sdlc-pipeline.yml b/.github/workflows/sdlc-pipeline.yml
new file mode 100644
index 0000000000..6ad2dd11fa
--- /dev/null
+++ b/.github/workflows/sdlc-pipeline.yml
@@ -0,0 +1,849 @@
+name: "egg: SDLC Pipeline"
+
+on:
+  workflow_dispatch:
+    inputs:
+      issue_number:
+        description: 'GitHub issue number to process'
+        required: true
+        type: number
+      starting_phase:
+        description: 'Pipeline phase to start from'
+        required: false
+        type: choice
+        options:
+          - refine
+          - plan
+          - implement
+          - pr
+        default: refine
+  issues:
+    types: [labeled]
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+
+# Prevent concurrent pipeline runs for the same issue
+concurrency:
+  group: sdlc-pipeline-${{ github.event.inputs.issue_number || github.event.issue.number }}
+  cancel-in-progress: false
+
+jobs:
+  # ============================================================
+  # Initialization: Create contract and branch
+  # ============================================================
+  init:
+    name: Initialize pipeline
+    runs-on: ubuntu-latest
+    # Only trigger on egg-sdlc label or workflow_dispatch
+    if: >-
+      (github.event_name == 'workflow_dispatch') ||
+      (github.event_name == 'issues' && github.event.label.name == 'egg-sdlc')
+    outputs:
+      issue_number: ${{ steps.setup.outputs.issue_number }}
+      issue_title: ${{ steps.setup.outputs.issue_title }}
+      branch_name: ${{ steps.setup.outputs.branch_name }}
+      current_phase: ${{ steps.setup.outputs.current_phase }}
+      contract_exists: ${{ steps.setup.outputs.contract_exists }}
+
+    steps:
+      - name: Generate bot token
+        id: bot-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.BOT_APP_ID }}
+          private-key: ${{ secrets.BOT_APP_PRIVATE_KEY }}
+
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          token: ${{ steps.bot-token.outputs.token }}
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          set -euo pipefail
+          pip install pydantic==2.10.* pyyaml==6.0.*
+
+      - name: Setup pipeline
+        id: setup
+        env:
+          GH_TOKEN: ${{ steps.bot-token.outputs.token }}
+          DISPATCH_ISSUE: ${{ github.event.inputs.issue_number }}
+          LABELED_ISSUE: ${{ github.event.issue.number }}
+          STARTING_PHASE: ${{ github.event.inputs.starting_phase || 'refine' }}
+        run: |
+          set -euo pipefail
+
+          # Determine issue number based on trigger
+          if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
+            ISSUE_NUMBER="${DISPATCH_ISSUE}"
+          else
+            ISSUE_NUMBER="${LABELED_ISSUE}"
+          fi
+
+          # Validate issue number is numeric (path traversal prevention)
+          if ! [[ "$ISSUE_NUMBER" =~ ^[0-9]+$ ]]; then
+            echo "::error::Invalid issue number: ${ISSUE_NUMBER}"
+            exit 1
+          fi
+
+          echo "issue_number=${ISSUE_NUMBER}" >> "$GITHUB_OUTPUT"
+
+          # Fetch issue metadata
+          ISSUE_DATA=$(gh api "repos/${{ github.repository }}/issues/${ISSUE_NUMBER}")
+          ISSUE_TITLE=$(echo "$ISSUE_DATA" | jq -r '.title')
+          ISSUE_URL=$(echo "$ISSUE_DATA" | jq -r '.html_url')
+
+          echo "issue_title=${ISSUE_TITLE}" >> "$GITHUB_OUTPUT"
+
+          # Branch name for this issue
+          BRANCH_NAME="egg/issue-${ISSUE_NUMBER}"
+          echo "branch_name=${BRANCH_NAME}" >> "$GITHUB_OUTPUT"
+
+          # Check if branch exists
+          if git ls-remote --heads origin "${BRANCH_NAME}" | grep -q "${BRANCH_NAME}"; then
+            echo "Branch ${BRANCH_NAME} already exists"
+            git checkout "${BRANCH_NAME}"
+            git pull origin "${BRANCH_NAME}"
+          else
+            echo "Creating new branch ${BRANCH_NAME}"
+            git checkout -b "${BRANCH_NAME}"
+          fi
+
+          # Create contracts directory
+          mkdir -p .egg-state/contracts
+
+          # Check if contract exists
+          CONTRACT_PATH=".egg-state/contracts/${ISSUE_NUMBER}.json"
+          if [[ -f "$CONTRACT_PATH" ]]; then
+            echo "contract_exists=true" >> "$GITHUB_OUTPUT"
+            CURRENT_PHASE=$(jq -r '.current_phase' "$CONTRACT_PATH")
+            echo "current_phase=${CURRENT_PHASE}" >> "$GITHUB_OUTPUT"
+          else
+            echo "contract_exists=false" >> "$GITHUB_OUTPUT"
+            echo "current_phase=${STARTING_PHASE}" >> "$GITHUB_OUTPUT"
+
+            # Create initial contract
+            cat > "$CONTRACT_PATH" << EOF
+          {
+            "schemaVersion": "1.0",
+            "issue": {
+              "number": ${ISSUE_NUMBER},
+              "title": $(echo "$ISSUE_TITLE" | jq -R),
+              "url": "${ISSUE_URL}"
+            },
+            "current_phase": "${STARTING_PHASE}",
+            "acceptance_criteria": [],
+            "phases": [],
+            "decisions": [],
+            "circuit_breaker": {
+              "total_cycles": 0,
+              "max_total_cycles": 10,
+              "status": "closed"
+            },
+            "audit_log": []
+          }
+          EOF
+
+            # Commit the contract
+            git add "$CONTRACT_PATH"
+            git commit -m "Initialize SDLC contract for issue #${ISSUE_NUMBER}"
+          fi
+
+      - name: Push branch
+        env:
+          GH_TOKEN: ${{ steps.bot-token.outputs.token }}
+          BRANCH_NAME: ${{ steps.setup.outputs.branch_name }}
+        run: |
+          set -euo pipefail
+          # Retry push with rebase on conflict
+          MAX_RETRIES=3
+          for i in $(seq 1 $MAX_RETRIES); do
+            if git push -u origin "${BRANCH_NAME}"; then
+              echo "Push succeeded"
+              break
+            elif [[ $i -eq $MAX_RETRIES ]]; then
+              echo "Push failed after $MAX_RETRIES attempts"
+              exit 1
+            else
+              echo "Push failed (attempt $i/$MAX_RETRIES), trying rebase..."
+              git pull --rebase origin "${BRANCH_NAME}" || {
+                echo "Rebase failed, cannot resolve conflict automatically"
+                exit 1
+              }
+            fi
+          done
+
+      - name: Post initialization comment
+        if: steps.setup.outputs.contract_exists == 'false'
+        env:
+          GH_TOKEN: ${{ steps.bot-token.outputs.token }}
+        run: |
+          set -euo pipefail
+          BODY="SDLC Pipeline initialized for this issue.
+
+          **Branch:** \`${{ steps.setup.outputs.branch_name }}\`
+          **Starting phase:** \`${{ steps.setup.outputs.current_phase }}\`
+
+          The pipeline will now begin the **${{ steps.setup.outputs.current_phase }}** phase.
+
+          --- Authored by egg"
+
+          gh issue comment "${{ steps.setup.outputs.issue_number }}" --body "$BODY"
+
+  # ============================================================
+  # Implement: Execute tasks in plan
+  # ============================================================
+  implement:
+    name: Implement tasks
+    needs: init
+    if: needs.init.outputs.current_phase == 'implement'
+    runs-on: ubuntu-latest
+    outputs:
+      implementation_complete: ${{ steps.implement.outputs.complete }}
+      tasks_completed: ${{ steps.implement.outputs.tasks_completed }}
+
+    env:
+      BOT_USERNAME: james-in-a-box
+      ISSUE_NUMBER: ${{ needs.init.outputs.issue_number }}
+      BRANCH_NAME: ${{ needs.init.outputs.branch_name }}
+
+    steps:
+      - name: Generate bot token
+        id: bot-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.BOT_APP_ID }}
+          private-key: ${{ secrets.BOT_APP_PRIVATE_KEY }}
+
+      - name: Checkout main (trusted)
+        uses: actions/checkout@v4
+        with:
+          ref: main
+          persist-credentials: false
+
+      - name: Save trusted action scripts
+        run: cp -r action "$RUNNER_TEMP/trusted-action"
+
+      - name: Build implement prompt
+        id: prompt
+        run: bash action/build-sdlc-prompt.sh
+        env:
+          GH_TOKEN: ${{ steps.bot-token.outputs.token }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+          EGG_ISSUE_NUMBER: ${{ env.ISSUE_NUMBER }}
+          EGG_PIPELINE_PHASE: implement
+          EGG_BRANCH_NAME: ${{ env.BRANCH_NAME }}
+
+      - name: Checkout issue branch
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ env.BRANCH_NAME }}
+          token: ${{ steps.bot-token.outputs.token }}
+
+      - name: Run egg implementer
+        id: egg
+        uses: jwbron/egg/action@main
+        with:
+          prompt: ${{ steps.prompt.outputs.prompt }}
+          anthropic-oauth-token: ${{ secrets.ANTHROPIC_OAUTH_TOKEN }}
+          bot-app-id: ${{ secrets.BOT_APP_ID }}
+          bot-app-private-key: ${{ secrets.BOT_APP_PRIVATE_KEY }}
+          bot-app-installation-id: ${{ secrets.BOT_APP_INSTALLATION_ID }}
+          bot-username: ${{ env.BOT_USERNAME }}
+          timeout: "60"
+        env:
+          EGG_AGENT_ROLE: implementer
+          EGG_ISSUE_NUMBER: ${{ env.ISSUE_NUMBER }}
+
+      - name: Update contract state
+        id: implement
+        run: bash "$RUNNER_TEMP/trusted-action/contract-state.sh" update-after-implement
+        env:
+          GH_TOKEN: ${{ steps.bot-token.outputs.token }}
+          ISSUE_NUMBER: ${{ env.ISSUE_NUMBER }}
+          REPO_PATH: ${{ github.workspace }}
+
+      - name: Post status comment
+        if: always()
+        env:
+          GH_TOKEN: ${{ steps.bot-token.outputs.token }}
+          EGG_EXIT_CODE: ${{ steps.egg.outputs.exit-code }}
+        run: |
+          set -euo pipefail
+          RUN_URL="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+
+          if [[ "${EGG_EXIT_CODE:-1}" == "0" ]]; then
+            BODY="Implementation phase completed. [View run logs](${RUN_URL})
+
+          --- Authored by egg"
+          else
+            BODY="Implementation phase encountered issues (exit code: ${EGG_EXIT_CODE:-unknown}).
+          [View run logs](${RUN_URL})
+
+          --- Authored by egg"
+          fi
+
+          gh issue comment "${ISSUE_NUMBER}" --body "$BODY"
+
+  # ============================================================
+  # Review: Evaluate implementation against acceptance criteria
+  # ============================================================
+  review:
+    name: Review implementation
+    needs: [init, implement]
+    if: always() && needs.implement.result == 'success'
+    runs-on: ubuntu-latest
+    outputs:
+      review_passed: ${{ steps.review.outputs.passed }}
+      tasks_incomplete: ${{ steps.review.outputs.tasks_incomplete }}
+
+    env:
+      BOT_USERNAME: james-in-a-box
+      ISSUE_NUMBER: ${{ needs.init.outputs.issue_number }}
+      BRANCH_NAME: ${{ needs.init.outputs.branch_name }}
+
+    steps:
+      - name: Generate bot token
+        id: bot-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.BOT_APP_ID }}
+          private-key: ${{ secrets.BOT_APP_PRIVATE_KEY }}
+
+      - name: Checkout main (trusted)
+        uses: actions/checkout@v4
+        with:
+          ref: main
+          persist-credentials: false
+
+      - name: Save trusted action scripts
+        run: cp -r action "$RUNNER_TEMP/trusted-action"
+
+      - name: Build review prompt
+        id: prompt
+        run: |
+          set -euo pipefail
+          # Build a review-specific prompt
+          cat > /tmp/review-prompt.txt << 'EOF'
+          You are a REVIEWER agent in the SDLC pipeline.
+
+          Your task is to review the implementation completed by the implementer agent.
+          For each task in the contract:
+
+          1. Check if the task has a linked commit
+          2. Review the code changes in that commit
+          3. Verify the implementation meets the acceptance criteria
+          4. Mark the task as complete or incomplete with feedback
+
+          Use the egg-contract CLI to update task statuses:
+          - `egg-contract mark-task --task task-1-1 --status complete` (if meets criteria)
+          - `egg-contract mark-task --task task-1-1 --status incomplete` (if needs work)
+          - `egg-contract update-notes --task task-1-1 --notes "Feedback: ..."` (add feedback)
+
+          Be thorough but fair. Focus on whether the implementation meets the stated
+          acceptance criteria, not on stylistic preferences.
+          EOF
+
+          {
+            echo "prompt<<EOF"
+            cat /tmp/review-prompt.txt
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Checkout issue branch
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ env.BRANCH_NAME }}
+          token: ${{ steps.bot-token.outputs.token }}
+
+      - name: Run egg reviewer
+        id: egg
+        uses: jwbron/egg/action@main
+        with:
+          prompt: ${{ steps.prompt.outputs.prompt }}
+          anthropic-oauth-token: ${{ secrets.ANTHROPIC_OAUTH_TOKEN }}
+          bot-app-id: ${{ secrets.BOT_APP_ID }}
+          bot-app-private-key: ${{ secrets.BOT_APP_PRIVATE_KEY }}
+          bot-app-installation-id: ${{ secrets.BOT_APP_INSTALLATION_ID }}
+          bot-username: ${{ env.BOT_USERNAME }}
+          timeout: "30"
+        env:
+          EGG_AGENT_ROLE: reviewer
+          EGG_ISSUE_NUMBER: ${{ env.ISSUE_NUMBER }}
+
+      - name: Check review results
+        id: review
+        run: bash "$RUNNER_TEMP/trusted-action/contract-state.sh" check-review-status
+        env:
+          GH_TOKEN: ${{ steps.bot-token.outputs.token }}
+          ISSUE_NUMBER: ${{ env.ISSUE_NUMBER }}
+          REPO_PATH: ${{ github.workspace }}
+
+  # ============================================================
+  # Loop: Repeat implement->review if needed
+  # ============================================================
+  loop:
+    name: Check loop condition
+    needs: [init, implement, review]
+    if: always() && needs.review.result == 'success'
+    runs-on: ubuntu-latest
+    outputs:
+      should_continue: ${{ steps.check.outputs.should_continue }}
+      next_action: ${{ steps.check.outputs.next_action }}
+      cycle_count: ${{ steps.check.outputs.cycle_count }}
+
+    env:
+      ISSUE_NUMBER: ${{ needs.init.outputs.issue_number }}
+      BRANCH_NAME: ${{ needs.init.outputs.branch_name }}
+      REVIEW_PASSED: ${{ needs.review.outputs.review_passed }}
+      TASKS_INCOMPLETE: ${{ needs.review.outputs.tasks_incomplete }}
+
+    steps:
+      - name: Generate bot token
+        id: bot-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.BOT_APP_ID }}
+          private-key: ${{ secrets.BOT_APP_PRIVATE_KEY }}
+
+      - name: Checkout issue branch
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ env.BRANCH_NAME }}
+          token: ${{ steps.bot-token.outputs.token }}
+
+      - name: Check loop condition
+        id: check
+        run: |
+          set -euo pipefail
+          CONTRACT_PATH=".egg-state/contracts/${ISSUE_NUMBER}.json"
+
+          if [[ ! -f "$CONTRACT_PATH" ]]; then
+            echo "Contract not found"
+            echo "should_continue=false" >> "$GITHUB_OUTPUT"
+            echo "next_action=error" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # Get circuit breaker state
+          TOTAL_CYCLES=$(jq -r '.circuit_breaker.total_cycles' "$CONTRACT_PATH")
+          MAX_CYCLES=$(jq -r '.circuit_breaker.max_total_cycles' "$CONTRACT_PATH")
+          CB_STATUS=$(jq -r '.circuit_breaker.status' "$CONTRACT_PATH")
+
+          # Validate numeric values (issue #6)
+          TOTAL_CYCLES=${TOTAL_CYCLES:-0}
+          MAX_CYCLES=${MAX_CYCLES:-10}
+          if ! [[ "$TOTAL_CYCLES" =~ ^[0-9]+$ ]]; then
+            echo "Warning: TOTAL_CYCLES is not numeric, defaulting to 0"
+            TOTAL_CYCLES=0
+          fi
+          if ! [[ "$MAX_CYCLES" =~ ^[0-9]+$ ]]; then
+            echo "Warning: MAX_CYCLES is not numeric, defaulting to 10"
+            MAX_CYCLES=10
+          fi
+
+          echo "cycle_count=${TOTAL_CYCLES}" >> "$GITHUB_OUTPUT"
+
+          # Check if circuit breaker is open
+          if [[ "$CB_STATUS" == "open" ]]; then
+            echo "Circuit breaker is OPEN - human intervention required"
+            echo "should_continue=false" >> "$GITHUB_OUTPUT"
+            echo "next_action=escalate" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # Check if review passed
+          if [[ "$REVIEW_PASSED" == "true" ]]; then
+            echo "Review passed - advancing to PR phase"
+            echo "should_continue=true" >> "$GITHUB_OUTPUT"
+            echo "next_action=pr" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # Check if max cycles exceeded
+          if [[ "$TOTAL_CYCLES" -ge "$MAX_CYCLES" ]]; then
+            echo "Max cycles ($MAX_CYCLES) exceeded - triggering escalation"
+            echo "should_continue=false" >> "$GITHUB_OUTPUT"
+            echo "next_action=escalate" >> "$GITHUB_OUTPUT"
+
+            # Update circuit breaker status
+            jq '.circuit_breaker.status = "open"' "$CONTRACT_PATH" > /tmp/contract.json
+            mv /tmp/contract.json "$CONTRACT_PATH"
+            git add "$CONTRACT_PATH"
+            git commit -m "Open circuit breaker after ${TOTAL_CYCLES} cycles"
+
+            # Retry push with rebase on conflict
+            MAX_RETRIES=3
+            for i in $(seq 1 $MAX_RETRIES); do
+              if git push origin "${BRANCH_NAME}"; then
+                echo "Push succeeded"
+                break
+              elif [[ $i -eq $MAX_RETRIES ]]; then
+                echo "Push failed after $MAX_RETRIES attempts"
+                exit 1
+              else
+                echo "Push failed (attempt $i/$MAX_RETRIES), trying rebase..."
+                git pull --rebase origin "${BRANCH_NAME}" || {
+                  echo "Rebase failed, cannot resolve conflict automatically"
+                  exit 1
+                }
+              fi
+            done
+            exit 0
+          fi
+
+          # Continue with another implement cycle
+          echo "Review found incomplete tasks - continuing implementation"
+          echo "should_continue=true" >> "$GITHUB_OUTPUT"
+          echo "next_action=implement" >> "$GITHUB_OUTPUT"
+
+          # Increment cycle count
+          NEW_CYCLES=$((TOTAL_CYCLES + 1))
+          jq ".circuit_breaker.total_cycles = ${NEW_CYCLES}" "$CONTRACT_PATH" > /tmp/contract.json
+          mv /tmp/contract.json "$CONTRACT_PATH"
+          git add "$CONTRACT_PATH"
+          git commit -m "Increment pipeline cycle to ${NEW_CYCLES}"
+
+          # Retry push with rebase on conflict
+          MAX_RETRIES=3
+          for i in $(seq 1 $MAX_RETRIES); do
+            if git push origin "${BRANCH_NAME}"; then
+              echo "Push succeeded"
+              break
+            elif [[ $i -eq $MAX_RETRIES ]]; then
+              echo "Push failed after $MAX_RETRIES attempts"
+              exit 1
+            else
+              echo "Push failed (attempt $i/$MAX_RETRIES), trying rebase..."
+              git pull --rebase origin "${BRANCH_NAME}" || {
+                echo "Rebase failed, cannot resolve conflict automatically"
+                exit 1
+              }
+            fi
+          done
+
+      - name: Post loop status
+        env:
+          GH_TOKEN: ${{ steps.bot-token.outputs.token }}
+          NEXT_ACTION: ${{ steps.check.outputs.next_action }}
+          CYCLE_COUNT: ${{ steps.check.outputs.cycle_count }}
+        run: |
+          set -euo pipefail
+          case "$NEXT_ACTION" in
+            pr)
+              BODY="All tasks verified by reviewer. Advancing to PR phase.
+
+          --- Authored by egg"
+              ;;
+            implement)
+              BODY="Review cycle ${CYCLE_COUNT} complete. Some tasks need additional work.
+          Continuing implementation...
+
+          --- Authored by egg"
+              ;;
+            escalate)
+              BODY="**SDLC Pipeline Escalation Required**
+
+          The pipeline has reached its cycle limit or encountered a blocking issue.
+          Human intervention is required to proceed.
+
+          **Cycle count:** ${CYCLE_COUNT}
+          **Status:** Circuit breaker OPEN
+
+          Please review the contract state and incomplete tasks, then provide guidance.
+
+          --- Authored by egg"
+              gh issue label add "needs-human-intervention" --issue "${ISSUE_NUMBER}" 2>/dev/null || true
+              ;;
+            *)
+              BODY="Pipeline check complete.
+
+          --- Authored by egg"
+              ;;
+          esac
+
+          gh issue comment "${ISSUE_NUMBER}" --body "$BODY"
+
+  # ============================================================
+  # PR: Create pull request
+  # ============================================================
+  create-pr:
+    name: Create pull request
+    needs: [init, loop]
+    if: always() && needs.loop.outputs.next_action == 'pr'
+    runs-on: ubuntu-latest
+
+    env:
+      BOT_USERNAME: james-in-a-box
+      ISSUE_NUMBER: ${{ needs.init.outputs.issue_number }}
+      ISSUE_TITLE: ${{ needs.init.outputs.issue_title }}
+      BRANCH_NAME: ${{ needs.init.outputs.branch_name }}
+
+    steps:
+      - name: Generate bot token
+        id: bot-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.BOT_APP_ID }}
+          private-key: ${{ secrets.BOT_APP_PRIVATE_KEY }}
+
+      - name: Checkout main (trusted)
+        uses: actions/checkout@v4
+        with:
+          ref: main
+          persist-credentials: false
+
+      - name: Build PR prompt
+        id: prompt
+        run: bash action/build-sdlc-prompt.sh
+        env:
+          GH_TOKEN: ${{ steps.bot-token.outputs.token }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+          EGG_ISSUE_NUMBER: ${{ env.ISSUE_NUMBER }}
+          EGG_PIPELINE_PHASE: pr
+          EGG_BRANCH_NAME: ${{ env.BRANCH_NAME }}
+
+      - name: Checkout issue branch
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ env.BRANCH_NAME }}
+          token: ${{ steps.bot-token.outputs.token }}
+
+      - name: Run egg to create PR
+        id: egg
+        uses: jwbron/egg/action@main
+        with:
+          prompt: ${{ steps.prompt.outputs.prompt }}
+          anthropic-oauth-token: ${{ secrets.ANTHROPIC_OAUTH_TOKEN }}
+          bot-app-id: ${{ secrets.BOT_APP_ID }}
+          bot-app-private-key: ${{ secrets.BOT_APP_PRIVATE_KEY }}
+          bot-app-installation-id: ${{ secrets.BOT_APP_INSTALLATION_ID }}
+          bot-username: ${{ env.BOT_USERNAME }}
+          timeout: "15"
+        env:
+          EGG_AGENT_ROLE: implementer
+          EGG_ISSUE_NUMBER: ${{ env.ISSUE_NUMBER }}
+
+      - name: Update contract phase
+        env:
+          GH_TOKEN: ${{ steps.bot-token.outputs.token }}
+        run: |
+          set -euo pipefail
+          CONTRACT_PATH=".egg-state/contracts/${ISSUE_NUMBER}.json"
+          if [[ -f "$CONTRACT_PATH" ]]; then
+            jq '.current_phase = "pr"' "$CONTRACT_PATH" > /tmp/contract.json
+            mv /tmp/contract.json "$CONTRACT_PATH"
+            git add "$CONTRACT_PATH"
+            git commit -m "Advance to PR phase for issue #${ISSUE_NUMBER}"
+
+            # Retry push with rebase on conflict
+            MAX_RETRIES=3
+            for i in $(seq 1 $MAX_RETRIES); do
+              if git push origin "${BRANCH_NAME}"; then
+                echo "Push succeeded"
+                break
+              elif [[ $i -eq $MAX_RETRIES ]]; then
+                echo "Push failed after $MAX_RETRIES attempts"
+                exit 1
+              else
+                echo "Push failed (attempt $i/$MAX_RETRIES), trying rebase..."
+                git pull --rebase origin "${BRANCH_NAME}" || {
+                  echo "Rebase failed, cannot resolve conflict automatically"
+                  exit 1
+                }
+              fi
+            done
+          fi
+
+      - name: Post completion comment
+        env:
+          GH_TOKEN: ${{ steps.bot-token.outputs.token }}
+          PR_URL: ${{ steps.egg.outputs.pr-url }}
+        run: |
+          set -euo pipefail
+          if [[ -n "$PR_URL" ]]; then
+            BODY="Pull request created: ${PR_URL}
+
+          The implementation is ready for human review and merge.
+
+          --- Authored by egg"
+          else
+            BODY="PR phase completed. Please check the repository for the pull request.
+
+          --- Authored by egg"
+          fi
+
+          gh issue comment "${ISSUE_NUMBER}" --body "$BODY"
+
+  # ============================================================
+  # Refine: Analyze issue and produce analysis document
+  # ============================================================
+  refine:
+    name: Refine issue
+    needs: init
+    if: needs.init.outputs.current_phase == 'refine'
+    runs-on: ubuntu-latest
+
+    env:
+      BOT_USERNAME: james-in-a-box
+      ISSUE_NUMBER: ${{ needs.init.outputs.issue_number }}
+      BRANCH_NAME: ${{ needs.init.outputs.branch_name }}
+
+    steps:
+      - name: Generate bot token
+        id: bot-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.BOT_APP_ID }}
+          private-key: ${{ secrets.BOT_APP_PRIVATE_KEY }}
+
+      - name: Checkout main (trusted)
+        uses: actions/checkout@v4
+        with:
+          ref: main
+          persist-credentials: false
+
+      - name: Build refine prompt
+        id: prompt
+        run: bash action/build-sdlc-prompt.sh
+        env:
+          GH_TOKEN: ${{ steps.bot-token.outputs.token }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+          EGG_ISSUE_NUMBER: ${{ env.ISSUE_NUMBER }}
+          EGG_PIPELINE_PHASE: refine
+          EGG_BRANCH_NAME: ${{ env.BRANCH_NAME }}
+
+      - name: Checkout issue branch
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ env.BRANCH_NAME }}
+          token: ${{ steps.bot-token.outputs.token }}
+
+      - name: Run egg refiner
+        id: egg
+        uses: jwbron/egg/action@main
+        with:
+          prompt: ${{ steps.prompt.outputs.prompt }}
+          anthropic-oauth-token: ${{ secrets.ANTHROPIC_OAUTH_TOKEN }}
+          bot-app-id: ${{ secrets.BOT_APP_ID }}
+          bot-app-private-key: ${{ secrets.BOT_APP_PRIVATE_KEY }}
+          bot-app-installation-id: ${{ secrets.BOT_APP_INSTALLATION_ID }}
+          bot-username: ${{ env.BOT_USERNAME }}
+          timeout: "30"
+        env:
+          EGG_AGENT_ROLE: implementer
+          EGG_ISSUE_NUMBER: ${{ env.ISSUE_NUMBER }}
+
+      - name: Post completion comment
+        if: always()
+        env:
+          GH_TOKEN: ${{ steps.bot-token.outputs.token }}
+          EGG_EXIT_CODE: ${{ steps.egg.outputs.exit-code }}
+        run: |
+          set -euo pipefail
+          RUN_URL="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+
+          if [[ "${EGG_EXIT_CODE:-1}" == "0" ]]; then
+            BODY="Refine phase completed. [View run logs](${RUN_URL})
+
+          Please review the analysis and approve to advance to the **plan** phase.
+
+          --- Authored by egg"
+          else
+            BODY="Refine phase encountered issues (exit code: ${EGG_EXIT_CODE:-unknown}). [View run logs](${RUN_URL})
+
+          --- Authored by egg"
+          fi
+
+          gh issue comment "${ISSUE_NUMBER}" --body "$BODY"
+
+  # ============================================================
+  # Plan: Create implementation plan
+  # ============================================================
+  plan:
+    name: Create plan
+    needs: init
+    if: needs.init.outputs.current_phase == 'plan'
+    runs-on: ubuntu-latest
+
+    env:
+      BOT_USERNAME: james-in-a-box
+      ISSUE_NUMBER: ${{ needs.init.outputs.issue_number }}
+      BRANCH_NAME: ${{ needs.init.outputs.branch_name }}
+
+    steps:
+      - name: Generate bot token
+        id: bot-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.BOT_APP_ID }}
+          private-key: ${{ secrets.BOT_APP_PRIVATE_KEY }}
+
+      - name: Checkout main (trusted)
+        uses: actions/checkout@v4
+        with:
+          ref: main
+          persist-credentials: false
+
+      - name: Build plan prompt
+        id: prompt
+        run: bash action/build-sdlc-prompt.sh
+        env:
+          GH_TOKEN: ${{ steps.bot-token.outputs.token }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+          EGG_ISSUE_NUMBER: ${{ env.ISSUE_NUMBER }}
+          EGG_PIPELINE_PHASE: plan
+          EGG_BRANCH_NAME: ${{ env.BRANCH_NAME }}
+
+      - name: Checkout issue branch
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ env.BRANCH_NAME }}
+          token: ${{ steps.bot-token.outputs.token }}
+
+      - name: Run egg planner
+        id: egg
+        uses: jwbron/egg/action@main
+        with:
+          prompt: ${{ steps.prompt.outputs.prompt }}
+          anthropic-oauth-token: ${{ secrets.ANTHROPIC_OAUTH_TOKEN }}
+          bot-app-id: ${{ secrets.BOT_APP_ID }}
+          bot-app-private-key: ${{ secrets.BOT_APP_PRIVATE_KEY }}
+          bot-app-installation-id: ${{ secrets.BOT_APP_INSTALLATION_ID }}
+          bot-username: ${{ env.BOT_USERNAME }}
+          timeout: "30"
+        env:
+          EGG_AGENT_ROLE: implementer
+          EGG_ISSUE_NUMBER: ${{ env.ISSUE_NUMBER }}
+
+      - name: Post completion comment
+        if: always()
+        env:
+          GH_TOKEN: ${{ steps.bot-token.outputs.token }}
+          EGG_EXIT_CODE: ${{ steps.egg.outputs.exit-code }}
+        run: |
+          set -euo pipefail
+          RUN_URL="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+
+          if [[ "${EGG_EXIT_CODE:-1}" == "0" ]]; then
+            BODY="Plan phase completed. [View run logs](${RUN_URL})
+
+          Please review the implementation plan and approve to advance to the **implement** phase.
+
+          --- Authored by egg"
+          else
+            BODY="Plan phase encountered issues (exit code: ${EGG_EXIT_CODE:-unknown}). [View run logs](${RUN_URL})
+
+          --- Authored by egg"
+          fi
+
+          gh issue comment "${ISSUE_NUMBER}" --body "$BODY"
diff --git a/action/contract-state.sh b/action/contract-state.sh
new file mode 100755
index 0000000000..e3c8a0bd77
--- /dev/null
+++ b/action/contract-state.sh
@@ -0,0 +1,485 @@
+#!/usr/bin/env bash
+# contract-state.sh — Contract state management for SDLC pipeline
+#
+# This script provides functions for managing contract state during
+# the SDLC pipeline execution. It handles loading, updating, and
+# committing contract changes.
+#
+# Usage:
+#   contract-state.sh <command> [options]
+#
+# Commands:
+#   load              Load and display contract state
+#   update-after-implement  Update contract after implementation phase
+#   check-review-status    Check review results and determine next action
+#   increment-cycle   Increment the pipeline cycle counter
+#   get-current-phase Get the current pipeline phase
+#
+# Environment variables:
+#   ISSUE_NUMBER    — GitHub issue number (required)
+#   REPO_PATH       — Path to repository (defaults to current directory)
+#   BRANCH_NAME     — Current branch name
+#   GH_TOKEN        — GitHub token for git operations
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+CONTRACTS_DIR=".egg-state/contracts"
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+log_info() {
+  echo "[contract-state] $1"
+}
+
+log_error() {
+  echo "[contract-state] ERROR: $1" >&2
+}
+
+get_contract_path() {
+  local issue="${1:?ISSUE_NUMBER required}"
+  local repo_path="${REPO_PATH:-$(pwd)}"
+  echo "${repo_path}/${CONTRACTS_DIR}/${issue}.json"
+}
+
+ensure_contract_exists() {
+  local contract_path="$1"
+  if [[ ! -f "$contract_path" ]]; then
+    log_error "Contract not found at ${contract_path}"
+    return 1
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+cmd_load() {
+  local issue="${ISSUE_NUMBER:?ISSUE_NUMBER required}"
+  local contract_path
+  contract_path=$(get_contract_path "$issue")
+
+  ensure_contract_exists "$contract_path"
+
+  # Output contract state
+  jq '.' "$contract_path"
+}
+
+cmd_update_after_implement() {
+  local issue="${ISSUE_NUMBER:?ISSUE_NUMBER required}"
+  local contract_path
+  contract_path=$(get_contract_path "$issue")
+
+  ensure_contract_exists "$contract_path"
+
+  # Check if all tasks have commits linked
+  local tasks_without_commits
+  tasks_without_commits=$(jq '[.phases[].tasks[] | select(.commit == null or .commit == "")] | length' "$contract_path")
+
+  # Count tasks by status
+  local pending_tasks in_progress_tasks completed_tasks
+  pending_tasks=$(jq '[.phases[].tasks[] | select(.status == "pending")] | length' "$contract_path")
+  in_progress_tasks=$(jq '[.phases[].tasks[] | select(.status == "in_progress")] | length' "$contract_path")
+  completed_tasks=$(jq '[.phases[].tasks[] | select(.status == "complete")] | length' "$contract_path")
+  local total_tasks
+  total_tasks=$(jq '[.phases[].tasks[]] | length' "$contract_path")
+
+  log_info "Task summary: ${completed_tasks}/${total_tasks} complete, ${in_progress_tasks} in progress, ${pending_tasks} pending"
+  log_info "Tasks without commits: ${tasks_without_commits}"
+
+  # Update any tasks that have commits but are still pending to in_progress
+  local updated_contract
+  updated_contract=$(jq '
+    .phases |= map(
+      .tasks |= map(
+        if .commit != null and .commit != "" and .status == "pending" then
+          .status = "in_progress"
+        else
+          .
+        end
+      )
+    )
+  ' "$contract_path")
+
+  echo "$updated_contract" > "$contract_path"
+
+  # Determine if implementation is complete (all tasks have commits)
+  if [[ "$tasks_without_commits" -eq 0 ]]; then
+    log_info "All tasks have linked commits"
+    echo "complete=true" >> "${GITHUB_OUTPUT:-/dev/null}"
+    echo "tasks_completed=${total_tasks}" >> "${GITHUB_OUTPUT:-/dev/null}"
+  else
+    log_info "Implementation incomplete: ${tasks_without_commits} tasks need commits"
+    echo "complete=false" >> "${GITHUB_OUTPUT:-/dev/null}"
+    echo "tasks_completed=${completed_tasks}" >> "${GITHUB_OUTPUT:-/dev/null}"
+  fi
+}
+
+cmd_check_review_status() {
+  local issue="${ISSUE_NUMBER:?ISSUE_NUMBER required}"
+  local contract_path
+  contract_path=$(get_contract_path "$issue")
+
+  ensure_contract_exists "$contract_path"
+
+  # Count tasks by status
+  local complete_tasks incomplete_tasks blocked_tasks total_tasks
+  complete_tasks=$(jq '[.phases[].tasks[] | select(.status == "complete")] | length' "$contract_path")
+  incomplete_tasks=$(jq '[.phases[].tasks[] | select(.status == "incomplete")] | length' "$contract_path")
+  blocked_tasks=$(jq '[.phases[].tasks[] | select(.status == "blocked")] | length' "$contract_path")
+  total_tasks=$(jq '[.phases[].tasks[]] | length' "$contract_path")
+
+  log_info "Review status: ${complete_tasks}/${total_tasks} complete, ${incomplete_tasks} incomplete, ${blocked_tasks} blocked"
+
+  # Check if any tasks are escalated
+  local escalated_tasks
+  escalated_tasks=$(jq '[.phases[].tasks[] | select(.escalated == true)] | length' "$contract_path")
+
+  if [[ "$escalated_tasks" -gt 0 ]]; then
+    log_info "Found ${escalated_tasks} escalated tasks"
+    echo "passed=false" >> "${GITHUB_OUTPUT:-/dev/null}"
+    echo "tasks_incomplete=${incomplete_tasks}" >> "${GITHUB_OUTPUT:-/dev/null}"
+    echo "escalated=true" >> "${GITHUB_OUTPUT:-/dev/null}"
+    return 0
+  fi
+
+  # Check if all tasks are complete
+  if [[ "$complete_tasks" -eq "$total_tasks" && "$total_tasks" -gt 0 ]]; then
+    log_info "All tasks passed review"
+    echo "passed=true" >> "${GITHUB_OUTPUT:-/dev/null}"
+    echo "tasks_incomplete=0" >> "${GITHUB_OUTPUT:-/dev/null}"
+    echo "escalated=false" >> "${GITHUB_OUTPUT:-/dev/null}"
+  else
+    log_info "Review found incomplete tasks"
+    echo "passed=false" >> "${GITHUB_OUTPUT:-/dev/null}"
+    echo "tasks_incomplete=${incomplete_tasks}" >> "${GITHUB_OUTPUT:-/dev/null}"
+    echo "escalated=false" >> "${GITHUB_OUTPUT:-/dev/null}"
+
+    # Check per-task cycle counts and escalate if needed
+    local tasks_needing_escalation
+    tasks_needing_escalation=$(jq '[.phases[].tasks[] | select(.review_cycles >= .max_cycles and .status != "complete")] | length' "$contract_path")
+
+    if [[ "$tasks_needing_escalation" -gt 0 ]]; then
+      log_info "Found ${tasks_needing_escalation} tasks exceeding max cycles - escalating"
+
+      # Mark tasks as escalated
+      local updated_contract
+      updated_contract=$(jq '
+        .phases |= map(
+          .tasks |= map(
+            if .review_cycles >= .max_cycles and .status != "complete" then
+              .escalated = true
+            else
+              .
+            end
+          )
+        )
+      ' "$contract_path")
+
+      echo "$updated_contract" > "$contract_path"
+      echo "escalated=true" >> "${GITHUB_OUTPUT:-/dev/null}"
+    fi
+
+    # Increment review cycles for incomplete tasks
+    local updated_contract
+    updated_contract=$(jq '
+      .phases |= map(
+        .tasks |= map(
+          if .status == "incomplete" then
+            .review_cycles = (.review_cycles + 1) |
+            .status = "pending"
+          else
+            .
+          end
+        )
+      )
+    ' "$contract_path")
+
+    echo "$updated_contract" > "$contract_path"
+  fi
+}
+
+cmd_increment_cycle() {
+  local issue="${ISSUE_NUMBER:?ISSUE_NUMBER required}"
+  local contract_path
+  contract_path=$(get_contract_path "$issue")
+
+  ensure_contract_exists "$contract_path"
+
+  # Increment total cycles
+  local updated_contract
+  updated_contract=$(jq '.circuit_breaker.total_cycles += 1' "$contract_path")
+  echo "$updated_contract" > "$contract_path"
+
+  local new_count
+  new_count=$(jq '.circuit_breaker.total_cycles' "$contract_path")
+  log_info "Pipeline cycle incremented to ${new_count}"
+
+  echo "cycle_count=${new_count}" >> "${GITHUB_OUTPUT:-/dev/null}"
+}
+
+cmd_get_current_phase() {
+  local issue="${ISSUE_NUMBER:?ISSUE_NUMBER required}"
+  local contract_path
+  contract_path=$(get_contract_path "$issue")
+
+  ensure_contract_exists "$contract_path"
+
+  local phase
+  phase=$(jq -r '.current_phase' "$contract_path")
+
+  log_info "Current phase: ${phase}"
+  echo "current_phase=${phase}" >> "${GITHUB_OUTPUT:-/dev/null}"
+  echo "$phase"
+}
+
+cmd_set_phase() {
+  local issue="${ISSUE_NUMBER:?ISSUE_NUMBER required}"
+  local new_phase="${1:?new phase required}"
+  local contract_path
+  contract_path=$(get_contract_path "$issue")
+
+  ensure_contract_exists "$contract_path"
+
+  local old_phase
+  old_phase=$(jq -r '.current_phase' "$contract_path")
+
+  if [[ "$old_phase" == "$new_phase" ]]; then
+    log_info "Already in ${new_phase} phase"
+    return 0
+  fi
+
+  # Update phase with audit entry
+  local timestamp
+  timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  local updated_contract
+  updated_contract=$(jq --arg phase "$new_phase" \
+                        --arg old "$old_phase" \
+                        --arg ts "$timestamp" '
+    .current_phase = $phase |
+    .audit_log += [{
+      timestamp: $ts,
+      actor: "system",
+      role: "system",
+      action: "transition",
+      field_path: "current_phase",
+      old_value: $old,
+      new_value: $phase,
+      reason: "Phase transition"
+    }]
+  ' "$contract_path")
+
+  echo "$updated_contract" > "$contract_path"
+  log_info "Phase changed from ${old_phase} to ${new_phase}"
+}
+
+cmd_check_circuit_breaker() {
+  local issue="${ISSUE_NUMBER:?ISSUE_NUMBER required}"
+  local contract_path
+  contract_path=$(get_contract_path "$issue")
+
+  ensure_contract_exists "$contract_path"
+
+  local total_cycles max_cycles status
+  total_cycles=$(jq '.circuit_breaker.total_cycles' "$contract_path")
+  max_cycles=$(jq '.circuit_breaker.max_total_cycles' "$contract_path")
+  status=$(jq -r '.circuit_breaker.status' "$contract_path")
+
+  log_info "Circuit breaker: ${status} (${total_cycles}/${max_cycles} cycles)"
+
+  echo "status=${status}" >> "${GITHUB_OUTPUT:-/dev/null}"
+  echo "total_cycles=${total_cycles}" >> "${GITHUB_OUTPUT:-/dev/null}"
+  echo "max_cycles=${max_cycles}" >> "${GITHUB_OUTPUT:-/dev/null}"
+
+  if [[ "$status" == "open" ]]; then
+    echo "tripped=true" >> "${GITHUB_OUTPUT:-/dev/null}"
+    return 1
+  elif [[ "$total_cycles" -ge "$max_cycles" ]]; then
+    log_info "Circuit breaker tripped: max cycles exceeded"
+    echo "tripped=true" >> "${GITHUB_OUTPUT:-/dev/null}"
+
+    # Open the circuit breaker
+    local updated_contract
+    updated_contract=$(jq '.circuit_breaker.status = "open"' "$contract_path")
+    echo "$updated_contract" > "$contract_path"
+    return 1
+  else
+    echo "tripped=false" >> "${GITHUB_OUTPUT:-/dev/null}"
+    return 0
+  fi
+}
+
+cmd_open_circuit_breaker() {
+  local issue="${ISSUE_NUMBER:?ISSUE_NUMBER required}"
+  local reason="${1:-Manual trigger}"
+  local contract_path
+  contract_path=$(get_contract_path "$issue")
+
+  ensure_contract_exists "$contract_path"
+
+  local timestamp
+  timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  local updated_contract
+  updated_contract=$(jq --arg ts "$timestamp" --arg reason "$reason" '
+    .circuit_breaker.status = "open" |
+    .audit_log += [{
+      timestamp: $ts,
+      actor: "system",
+      role: "system",
+      action: "update",
+      field_path: "circuit_breaker.status",
+      old_value: "closed",
+      new_value: "open",
+      reason: $reason
+    }]
+  ' "$contract_path")
+
+  echo "$updated_contract" > "$contract_path"
+  log_info "Circuit breaker opened: ${reason}"
+}
+
+cmd_close_circuit_breaker() {
+  local issue="${ISSUE_NUMBER:?ISSUE_NUMBER required}"
+  local contract_path
+  contract_path=$(get_contract_path "$issue")
+
+  ensure_contract_exists "$contract_path"
+
+  local timestamp
+  timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  local updated_contract
+  updated_contract=$(jq --arg ts "$timestamp" '
+    .circuit_breaker.status = "closed" |
+    .audit_log += [{
+      timestamp: $ts,
+      actor: "human",
+      role: "human",
+      action: "update",
+      field_path: "circuit_breaker.status",
+      old_value: "open",
+      new_value: "closed",
+      reason: "Human intervention"
+    }]
+  ' "$contract_path")
+
+  echo "$updated_contract" > "$contract_path"
+  log_info "Circuit breaker closed by human intervention"
+}
+
+cmd_summary() {
+  local issue="${ISSUE_NUMBER:?ISSUE_NUMBER required}"
+  local contract_path
+  contract_path=$(get_contract_path "$issue")
+
+  ensure_contract_exists "$contract_path"
+
+  echo "=== Contract Summary for Issue #${issue} ==="
+  echo ""
+
+  local phase
+  phase=$(jq -r '.current_phase' "$contract_path")
+  echo "Current Phase: ${phase}"
+
+  local total_phases
+  total_phases=$(jq '.phases | length' "$contract_path")
+  echo "Total Phases: ${total_phases}"
+
+  echo ""
+  echo "Tasks by Status:"
+  jq -r '
+    .phases[].tasks[] |
+    .status
+  ' "$contract_path" | sort | uniq -c | while read -r count status; do
+    echo "  ${status}: ${count}"
+  done
+
+  echo ""
+  local cb_status cb_cycles cb_max
+  cb_status=$(jq -r '.circuit_breaker.status' "$contract_path")
+  cb_cycles=$(jq '.circuit_breaker.total_cycles' "$contract_path")
+  cb_max=$(jq '.circuit_breaker.max_total_cycles' "$contract_path")
+  echo "Circuit Breaker: ${cb_status} (${cb_cycles}/${cb_max} cycles)"
+
+  local pending_decisions
+  pending_decisions=$(jq '[.decisions[] | select(.resolved == false)] | length' "$contract_path")
+  echo "Pending Decisions: ${pending_decisions}"
+
+  echo ""
+  echo "=== End Summary ==="
+}
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+main() {
+  local command="${1:-help}"
+  shift || true
+
+  case "$command" in
+    load)
+      cmd_load "$@"
+      ;;
+    update-after-implement)
+      cmd_update_after_implement "$@"
+      ;;
+    check-review-status)
+      cmd_check_review_status "$@"
+      ;;
+    increment-cycle)
+      cmd_increment_cycle "$@"
+      ;;
+    get-current-phase)
+      cmd_get_current_phase "$@"
+      ;;
+    set-phase)
+      cmd_set_phase "$@"
+      ;;
+    check-circuit-breaker)
+      cmd_check_circuit_breaker "$@"
+      ;;
+    open-circuit-breaker)
+      cmd_open_circuit_breaker "$@"
+      ;;
+    close-circuit-breaker)
+      cmd_close_circuit_breaker "$@"
+      ;;
+    summary)
+      cmd_summary "$@"
+      ;;
+    help|--help|-h)
+      echo "Usage: contract-state.sh <command> [options]"
+      echo ""
+      echo "Commands:"
+      echo "  load                    Load and display contract state"
+      echo "  update-after-implement  Update contract after implementation phase"
+      echo "  check-review-status     Check review results and determine next action"
+      echo "  increment-cycle         Increment the pipeline cycle counter"
+      echo "  get-current-phase       Get the current pipeline phase"
+      echo "  set-phase <phase>       Set the current pipeline phase"
+      echo "  check-circuit-breaker   Check circuit breaker status"
+      echo "  open-circuit-breaker    Open the circuit breaker"
+      echo "  close-circuit-breaker   Close the circuit breaker"
+      echo "  summary                 Print contract summary"
+      echo ""
+      echo "Environment variables:"
+      echo "  ISSUE_NUMBER  — GitHub issue number (required)"
+      echo "  REPO_PATH     — Path to repository (defaults to current directory)"
+      ;;
+    *)
+      log_error "Unknown command: $command"
+      echo "Run 'contract-state.sh help' for usage information"
+      exit 1
+      ;;
+  esac
+}
+
+main "$@"