autonomous-coding-toolkit 1.0.0

package/scripts/quality-gate.sh

@@ -0,0 +1,266 @@
+#!/usr/bin/env bash
+# quality-gate.sh — Composite quality gate for Ralph loop --quality-checks
+# Runs lesson check + project test suite in sequence, fails fast on first failure.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")" && pwd)"
+source "$SCRIPT_DIR/lib/common.sh"
+PROJECT_ROOT=""
+QUICK=false
+WITH_LICENSE=false
+
+usage() {
+    cat <<'USAGE'
+Usage: quality-gate.sh --project-root <dir> [--quick] [--with-license]
+
+Composite quality gate for the Ralph loop. Runs checks in order, stops at first failure.
+
+Checks:
+  0. Toolkit validation — runs validate-all.sh if present (toolkit self-check)
+  1. Lesson check — runs lesson-check.sh on git-changed files in project root
+  2. Lint check — ruff (Python) or eslint (Node) if available (skipped with --quick)
+  3. Project test suite — auto-detects pytest / npm test / make test
+  4. License check — flags GPL/AGPL deps (only with --with-license, skipped with --quick)
+  5. Memory warning — warns if available memory < 4G (never fails)
+
+Options:
+  --project-root <dir>  Project directory to check (required)
+  --quick               Skip lint and license checks (fast inner-loop mode)
+  --with-license        Include dependency license audit
+  --help, -h            Show this help
+
+Exit: 0 if all pass, 1 on first failure
+USAGE
+    exit 0
+}
+
+# --- Parse args ---
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --project-root)
+            PROJECT_ROOT="${2:-}"
+            shift 2
+            ;;
+        --quick)
+            QUICK=true
+            shift
+            ;;
+        --with-license)
+            WITH_LICENSE=true
+            shift
+            ;;
+        --help|-h)
+            usage
+            ;;
+        *)
+            echo "quality-gate: unknown option: $1" >&2
+            echo "Run with --help for usage." >&2
+            exit 1
+            ;;
+    esac
+done
+
+if [[ -z "$PROJECT_ROOT" ]]; then
+    echo "quality-gate: --project-root is required" >&2
+    exit 1
+fi
+
+if [[ ! -d "$PROJECT_ROOT" ]]; then
+    echo "quality-gate: directory not found: $PROJECT_ROOT" >&2
+    exit 1
+fi
+
+cd "$PROJECT_ROOT"
+
+# === Check 0: Toolkit Self-Validation ===
+# Only runs when quality-gate is invoked from the toolkit itself
+if [[ -f "$PROJECT_ROOT/scripts/validate-all.sh" ]]; then
+    echo "=== Quality Gate: Toolkit Validation ==="
+    if ! bash "$PROJECT_ROOT/scripts/validate-all.sh"; then
+        echo ""
+        echo "quality-gate: FAILED at toolkit validation"
+        exit 1
+    fi
+fi
+
+# === Check 1: Lesson check on changed files ===
+echo "=== Quality Gate: Lesson Check ==="
+changed_files=$(git diff --name-only 2>/dev/null || true)
+if [[ -n "$changed_files" ]]; then
+    # Use an array to avoid word-splitting on filenames with spaces (#5).
+    readarray -t changed_array <<< "$changed_files"
+    if ! "$SCRIPT_DIR/lesson-check.sh" "${changed_array[@]}"; then
+        echo ""
+        echo "quality-gate: FAILED at lesson check"
+        exit 1
+    fi
+else
+    echo "lesson-check: no changed files — skipped"
+fi
+
+# === Check 2: Lint Check (skipped with --quick) ===
+if [[ "$QUICK" != true ]]; then
+    echo ""
+    echo "=== Quality Gate: Lint Check ==="
+    lint_ran=0
+
+    case "$(detect_project_type "$PROJECT_ROOT")" in
+        python)
+            if command -v ruff >/dev/null 2>&1; then
+                echo "Running: ruff check --select E,W,F"
+                if ! ruff check --select E,W,F "$PROJECT_ROOT" 2>/dev/null; then
+                    echo ""
+                    echo "quality-gate: FAILED at lint check"
+                    exit 1
+                fi
+                lint_ran=1
+            else
+                echo "ruff not installed — skipping Python lint"
+            fi
+            ;;
+        node)
+            if [[ -f "$PROJECT_ROOT/.eslintrc" || -f "$PROJECT_ROOT/.eslintrc.js" || -f "$PROJECT_ROOT/.eslintrc.json" || -f "$PROJECT_ROOT/eslint.config.js" ]]; then
+                echo "Running: npx eslint"
+                if ! npx eslint "$PROJECT_ROOT" 2>/dev/null; then
+                    echo ""
+                    echo "quality-gate: FAILED at lint check"
+                    exit 1
+                fi
+                lint_ran=1
+            else
+                echo "No eslint config found — skipping Node lint"
+            fi
+            ;;
+    esac
+
+    if [[ $lint_ran -eq 0 ]]; then
+        echo "No linter configured — skipped"
+    fi
+fi
+
+# === Check 2.5: ast-grep structural analysis (optional, advisory) ===
+if [[ "$QUICK" != true ]]; then
+    echo ""
+    echo "=== Quality Gate: Structural Analysis (ast-grep) ==="
+    if command -v ast-grep >/dev/null 2>&1; then
+        PATTERNS_DIR="$SCRIPT_DIR/patterns"
+        ast_violations=0
+        if [[ -d "$PATTERNS_DIR" ]]; then
+            for pattern_file in "$PATTERNS_DIR"/*.yml; do
+                [[ -f "$pattern_file" ]] || continue
+                matches=$(ast-grep scan --rule "$pattern_file" "$PROJECT_ROOT" 2>/dev/null || true)
+                if [[ -n "$matches" ]]; then
+                    echo "WARNING: $(basename "$pattern_file" .yml): $(echo "$matches" | wc -l) matches"
+                    echo "$matches" | head -3
+                    ast_violations=$((ast_violations + 1))
+                fi
+            done
+        fi
+        if [[ $ast_violations -gt 0 ]]; then
+            echo "ast-grep: $ast_violations pattern(s) matched (advisory)"
+        else
+            echo "ast-grep: clean"
+        fi
+    else
+        echo "ast-grep not installed — skipping structural analysis"
+    fi
+fi
+
+# === Check 2.7: Module size check (advisory) ===
+if [[ "$QUICK" != true ]]; then
+    echo ""
+    echo "=== Quality Gate: Module Size Check ==="
+    if [[ -x "$SCRIPT_DIR/module-size-check.sh" ]]; then
+        _size_exit=0
+        "$SCRIPT_DIR/module-size-check.sh" --project-root "$PROJECT_ROOT" || _size_exit=$?
+        if [[ $_size_exit -ne 0 ]]; then
+            echo "module-size-check: $( [ $_size_exit -eq 1 ] && echo "oversized modules detected (advisory)" || echo "error (exit $_size_exit)")"
+        fi
+    else
+        echo "module-size-check.sh not found — skipped"
+    fi
+fi
+
+# === Check 3: Project test suite (auto-detect) ===
+echo ""
+echo "=== Quality Gate: Test Suite ==="
+test_ran=0
+
+project_type=$(detect_project_type "$PROJECT_ROOT")
+case "$project_type" in
+    python)
+        echo "Detected: pytest project"
+        .venv/bin/python -m pytest --timeout=120 -x -q
+        test_ran=1
+        ;;
+    node)
+        if grep -q '"test"' "$PROJECT_ROOT/package.json" 2>/dev/null; then
+            echo "Detected: npm project"
+            npm test
+            test_ran=1
+        fi
+        ;;
+    make)
+        if grep -q '^test:' "$PROJECT_ROOT/Makefile" 2>/dev/null; then
+            echo "Detected: Makefile project"
+            make test
+            test_ran=1
+        fi
+        ;;
+    bash)
+        if [[ -x "$PROJECT_ROOT/scripts/tests/run-all-tests.sh" ]]; then
+            echo "Detected: bash project (run-all-tests.sh)"
+            "$PROJECT_ROOT/scripts/tests/run-all-tests.sh"
+            test_ran=1
+        fi
+        ;;
+esac
+
+if [[ $test_ran -eq 0 ]]; then
+    echo "No test suite detected (no pyproject.toml/setup.py/pytest.ini, no npm test script, no Makefile test target) — skipped"
+fi
+
+# === Check 4: License Check (only with --with-license, skipped with --quick) ===
+if [[ "$WITH_LICENSE" == true ]]; then
+    echo ""
+    echo "=== Quality Gate: License Check ==="
+    if ! "$SCRIPT_DIR/license-check.sh" --project-root "$PROJECT_ROOT"; then
+        echo "quality-gate: FAILED at license check"
+        exit 1
+    fi
+fi
+
+# === Check 5: Memory warning (advisory only) ===
+echo ""
+echo "=== Quality Gate: Memory Check ==="
+_mem_exit=0
+check_memory_available 4 || _mem_exit=$?
+if [[ $_mem_exit -eq 0 ]]; then
+    available_mb=$(free -m 2>/dev/null | awk '/Mem:/{print $7}')
+    available_display=$(awk "BEGIN {printf \"%.1f\", ${available_mb:-0} / 1024}")
+    echo "Memory OK (${available_display}G available)"
+elif [[ $_mem_exit -eq 2 ]]; then
+    echo "WARNING: Memory check skipped (cannot determine available memory)"
+else
+    echo "WARNING: Consider -n 0 for pytest"
+fi
+
+echo ""
+echo "quality-gate: ALL PASSED"
+
+# === Telemetry capture (append batch result) ===
+# Only record if TELEMETRY_BATCH_NUMBER is set (called from run-plan context)
+if [[ -n "${TELEMETRY_BATCH_NUMBER:-}" ]]; then
+    "$SCRIPT_DIR/telemetry.sh" record \
+        --project-root "$PROJECT_ROOT" \
+        --batch-number "${TELEMETRY_BATCH_NUMBER}" \
+        --passed true \
+        --strategy "${TELEMETRY_STRATEGY:-unknown}" \
+        --duration "${TELEMETRY_DURATION:-0}" \
+        --cost "${TELEMETRY_COST:-0}" \
+        --test-delta "${TELEMETRY_TEST_DELTA:-0}" \
+        --batch-type "${TELEMETRY_BATCH_TYPE:-unknown}" \
+        2>/dev/null || true  # Never fail the gate for telemetry errors
+fi
+
+exit 0

package/scripts/research-gate.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# research-gate.sh — Blocks PRD generation if research has unresolved blocking issues
+#
+# Usage: research-gate.sh <research-json> [--force]
+#
+# Reads tasks/research-<slug>.json and checks:
+#   - File exists and is valid JSON
+#   - No blocking_issues with resolved: false
+#
+# Exit 0 = clear (proceed to PRD)
+# Exit 1 = blocked (unresolved issues)
+# --force = override (exit 0 regardless, with warning)
+
+set -euo pipefail
+
+FORCE=false
+
+usage() {
+    cat <<'EOF'
+research-gate.sh — Research phase gate for PRD generation
+
+USAGE:
+  research-gate.sh <research-json> [--force]
+
+OPTIONS:
+  --force    Override blocking issues (exit 0 with warning)
+  -h, --help Show this help
+
+EXIT CODES:
+  0  Clear — no unresolved blocking issues
+  1  Blocked — unresolved blocking issues found
+EOF
+}
+
+# Parse args
+RESEARCH_FILE=""
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --force) FORCE=true; shift ;;
+        -h|--help) usage; exit 0 ;;
+        -*) echo "Unknown option: $1" >&2; exit 1 ;;
+        *) RESEARCH_FILE="$1"; shift ;;
+    esac
+done
+
+if [[ -z "$RESEARCH_FILE" ]]; then
+    echo "Error: research JSON file required" >&2
+    echo "Usage: research-gate.sh <research-json> [--force]" >&2
+    exit 1
+fi
+
+if [[ ! -f "$RESEARCH_FILE" ]]; then
+    echo "Error: file not found: $RESEARCH_FILE" >&2
+    exit 1
+fi
+
+# Validate JSON
+if ! jq empty "$RESEARCH_FILE" 2>/dev/null; then
+    echo "Error: invalid JSON: $RESEARCH_FILE" >&2
+    exit 1
+fi
+
+# Check for unresolved blocking issues
+unresolved_count=$(jq '[.blocking_issues[]? | select(.resolved == false)] | length' "$RESEARCH_FILE" 2>/dev/null || echo "0")
+
+if [[ "$unresolved_count" -gt 0 ]]; then
+    echo "RESEARCH GATE: $unresolved_count unresolved blocking issue(s)"
+    jq -r '.blocking_issues[]? | select(.resolved == false) | "  - \(.issue)"' "$RESEARCH_FILE" 2>/dev/null
+
+    if [[ "$FORCE" == "true" ]]; then
+        echo ""
+        echo "WARNING: --force used, proceeding despite blocking issues"
+        exit 0
+    else
+        echo ""
+        echo "Resolve blocking issues or use --force to override"
+        exit 1
+    fi
+fi
+
+# Check for warnings (informational, never blocks)
+warning_count=$(jq '[.warnings[]?] | length' "$RESEARCH_FILE" 2>/dev/null || echo "0")
+if [[ "$warning_count" -gt 0 ]]; then
+    echo "RESEARCH GATE: clear ($warning_count warning(s))"
+    jq -r '.warnings[]? | "  ⚠ \(.)"' "$RESEARCH_FILE" 2>/dev/null
+else
+    echo "RESEARCH GATE: clear (no blocking issues, no warnings)"
+fi
+
+exit 0

package/scripts/run-plan.sh

@@ -0,0 +1,329 @@
+#!/usr/bin/env bash
+# run-plan.sh — Execute implementation plans via headless Claude batches
+#
+# Usage:
+#   run-plan.sh <plan-file> [options]
+#   run-plan.sh --resume [options]
+#
+# Modes:
+#   headless     (default) — bash loop calling claude -p per batch
+#   team         — prints launch command for Claude agent team mode
+#   competitive  — prints launch command for competitive agent mode
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")" && pwd)"
+
+# --- Signal handling ---
+# Log unexpected exits for diagnostics (silent death prevention)
+_run_plan_exit_code=0
+_run_plan_exit_logged=false
+_log_exit() {
+    local code=${1:-$?}
+    [[ "$_run_plan_exit_logged" == true ]] && return
+    _run_plan_exit_logged=true
+    if [[ $code -ne 0 ]]; then
+        echo "" >&2
+        echo "run-plan: EXIT with code $code at $(date -u +%Y-%m-%dT%H:%M:%SZ)" >&2
+        # Print last few lines of bash call stack
+        local i
+        for ((i = 0; i < ${#FUNCNAME[@]}; i++)); do
+            echo "  ${BASH_SOURCE[$i]:-unknown}:${BASH_LINENO[$i]:-?} in ${FUNCNAME[$i]:-main}" >&2
+        done
+    fi
+}
+trap '_log_exit $?' EXIT
+
+# Ignore HUP and PIPE so background execution survives terminal disconnect
+# and broken pipe from task manager stdout (confirmed root cause: exit 141 = SIGPIPE)
+trap '' HUP PIPE
+
+# Source all lib functions
+source "$SCRIPT_DIR/lib/run-plan-parser.sh"
+source "$SCRIPT_DIR/lib/run-plan-state.sh"
+source "$SCRIPT_DIR/lib/run-plan-quality-gate.sh"
+source "$SCRIPT_DIR/lib/run-plan-notify.sh"
+source "$SCRIPT_DIR/lib/run-plan-prompt.sh"
+source "$SCRIPT_DIR/lib/progress-writer.sh"
+source "$SCRIPT_DIR/lib/run-plan-echo-back.sh"
+source "$SCRIPT_DIR/lib/run-plan-sampling.sh"
+source "$SCRIPT_DIR/lib/run-plan-headless.sh"
+source "$SCRIPT_DIR/lib/run-plan-context.sh"
+source "$SCRIPT_DIR/lib/progress-writer.sh"
+source "$SCRIPT_DIR/lib/run-plan-scoring.sh"
+source "$SCRIPT_DIR/lib/cost-tracking.sh"
+source "$SCRIPT_DIR/lib/run-plan-team.sh"
+source "$SCRIPT_DIR/lib/thompson-sampling.sh"
+
+# --- Defaults ---
+PLAN_FILE=""
+MODE="headless"
+START_BATCH=""
+END_BATCH=""
+WORKTREE="$(pwd)"
+PYTHON="python3"
+QUALITY_GATE_CMD="$SCRIPT_DIR/quality-gate.sh --project-root ."
+ON_FAILURE="stop"
+MAX_RETRIES=2
+COMPETITIVE_BATCHES=""
+SAMPLE_COUNT=0  # 0 = disabled
+NOTIFY=false
+VERIFY=false
+RESUME=false
+SKIP_PLAN_QUALITY=false
+SKIP_ECHO_BACK=false
+STRICT_ECHO_BACK=false
+MAB=false
+MAX_BUDGET=""
+
+# --- Usage ---
+usage() {
+    cat <<'USAGE'
+run-plan — Execute implementation plans via headless Claude batches
+
+Usage:
+  run-plan.sh <plan-file> [options]
+  run-plan.sh --resume [options]
+
+Options:
+  --mode <headless|team|competitive>   Execution mode (default: headless)
+  --start-batch N                      First batch to execute
+  --end-batch N                        Last batch to execute
+  --worktree <path>                    Working directory (default: cwd)
+  --python <path>                      Python interpreter (default: python3)
+  --quality-gate <cmd>                 Quality gate command
+                                       (default: "scripts/quality-gate.sh --project-root .")
+  --on-failure <stop|skip|retry>       Failure handling (default: stop)
+  --max-retries N                      Max retries per batch (default: 2)
+  --competitive-batches N,N,...        Batches for competitive mode
+  --sample N                           Parallel patch sampling (N candidates, default 3)
+  --no-sample                          Disable sampling (default)
+  --notify                             Send Telegram notifications
+  --verify                             Run verification after all batches
+  --skip-plan-quality                  Skip plan quality scorecard check
+  --skip-echo-back                     Skip spec echo-back verification
+  --resume                             Resume from saved state
+  --max-budget <dollars>               Stop if total cost exceeds this amount
+  --skip-echo-back                     Disable echo-back spec check entirely
+  --strict-echo-back                   Make echo-back blocking (aborts batch on mismatch)
+  --mab                                Enable MAB routing (competing agents via Thompson Sampling)
+  -h, --help                           Show this help message
+
+Modes:
+  headless      Bash loop calling claude -p per batch (runs locally)
+  team          Multi-agent team mode (prints Claude launch command)
+  competitive   Competitive agent mode (prints Claude launch command)
+
+Examples:
+  run-plan.sh docs/plans/2026-02-20-feature.md
+  run-plan.sh docs/plans/2026-02-20-feature.md --mode headless --start-batch 2
+  run-plan.sh --resume --worktree /path/to/worktree
+  run-plan.sh docs/plans/feature.md --on-failure retry --max-retries 3 --notify
+USAGE
+}
+
+# --- Argument parsing ---
+# shellcheck disable=SC2034  # Globals consumed by sourced lib scripts
+parse_args() {
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            -h|--help)
+                usage
+                exit 0
+                ;;
+            --mode)
+                MODE="$2"; shift 2
+                ;;
+            --start-batch)
+                START_BATCH="$2"; shift 2
+                ;;
+            --end-batch)
+                END_BATCH="$2"; shift 2
+                ;;
+            --worktree)
+                WORKTREE="$2"; shift 2
+                ;;
+            --python)
+                PYTHON="$2"; shift 2
+                ;;
+            --quality-gate)
+                QUALITY_GATE_CMD="$2"; shift 2
+                ;;
+            --on-failure)
+                ON_FAILURE="$2"; shift 2
+                ;;
+            --max-retries)
+                MAX_RETRIES="$2"; shift 2
+                ;;
+            --competitive-batches)
+                COMPETITIVE_BATCHES="$2"; shift 2
+                ;;
+            --sample)
+                SAMPLE_COUNT="${2:-3}"; shift 2
+                ;;
+            --no-sample)
+                SAMPLE_COUNT=0; shift
+                ;;
+            --notify)
+                NOTIFY=true; shift
+                ;;
+            --verify)
+                VERIFY=true; shift
+                ;;
+            --skip-plan-quality)
+                SKIP_PLAN_QUALITY=true; shift
+                ;;
+            --skip-echo-back)
+                SKIP_ECHO_BACK=true; shift
+                ;;
+            --resume)
+                RESUME=true; shift
+                ;;
+            --max-budget)
+                MAX_BUDGET="$2"; shift 2
+                ;;
+            --skip-echo-back) SKIP_ECHO_BACK=true; shift ;;
+            --strict-echo-back) STRICT_ECHO_BACK=true; shift ;;
+            --mab) MAB=true; shift ;;
+            -*)
+                echo "ERROR: Unknown option: $1" >&2
+                usage >&2
+                exit 1
+                ;;
+            *)
+                # Positional arg = plan file
+                if [[ -z "$PLAN_FILE" ]]; then
+                    PLAN_FILE="$1"
+                else
+                    echo "ERROR: Unexpected argument: $1" >&2
+                    exit 1
+                fi
+                shift
+                ;;
+        esac
+    done
+}
+
+# --- Validation ---
+validate_args() {
+    # Resume mode: load state file
+    if [[ "$RESUME" == true ]]; then
+        local state_file="$WORKTREE/.run-plan-state.json"
+        if [[ ! -f "$state_file" ]]; then
+            echo "ERROR: No state file found at $state_file" >&2
+            echo "Cannot resume without a previous run." >&2
+            exit 1
+        fi
+        # Load defaults from state
+        if [[ -z "$PLAN_FILE" ]]; then
+            PLAN_FILE=$(read_state_field "$WORKTREE" "plan_file")
+        fi
+        if [[ -z "$MODE" || "$MODE" == "headless" ]]; then
+            local saved_mode
+            saved_mode=$(read_state_field "$WORKTREE" "mode")
+            if [[ -n "$saved_mode" && "$saved_mode" != "null" ]]; then
+                MODE="$saved_mode"
+            fi
+        fi
+        if [[ -z "$START_BATCH" ]]; then
+            START_BATCH=$(read_state_field "$WORKTREE" "current_batch")
+        fi
+    fi
+
+    # Must have a plan file
+    if [[ -z "$PLAN_FILE" ]]; then
+        echo "ERROR: No plan file specified. Use: run-plan.sh <plan-file> or --resume" >&2
+        exit 1
+    fi
+
+    # Plan file must exist
+    if [[ ! -f "$PLAN_FILE" ]]; then
+        echo "ERROR: Plan file not found: $PLAN_FILE" >&2
+        exit 1
+    fi
+
+    # Validate mode
+    case "$MODE" in
+        headless|team|competitive) ;;
+        *)
+            echo "ERROR: Invalid mode: $MODE (must be headless, team, or competitive)" >&2
+            exit 1
+            ;;
+    esac
+
+    # Validate on-failure
+    case "$ON_FAILURE" in
+        stop|skip|retry) ;;
+        *)
+            echo "ERROR: Invalid --on-failure: $ON_FAILURE (must be stop, skip, or retry)" >&2
+            exit 1
+            ;;
+    esac
+
+    # Set batch range defaults
+    local total
+    total=$(count_batches "$PLAN_FILE")
+    if [[ -z "$START_BATCH" ]]; then
+        START_BATCH=1
+    fi
+    if [[ -z "$END_BATCH" ]]; then
+        END_BATCH="$total"
+    fi
+}
+
+# --- Banner ---
+print_banner() {
+    local total
+    total=$(count_batches "$PLAN_FILE")
+    local plan_display
+    plan_display=$(basename "$PLAN_FILE")
+
+    cat <<BANNER
+╔══════════════════════════════════════════════════════╗
+║  run-plan — $MODE mode
+║  Plan: $plan_display
+║  Batches: $START_BATCH → $END_BATCH (of $total)
+║  Worktree: $WORKTREE
+╚══════════════════════════════════════════════════════╝
+BANNER
+}
+
+# --- Mode stubs ---
+run_mode_competitive() {
+    echo "Competitive mode requires a Claude session with agent teams enabled."
+    echo ""
+    echo "Launch command:"
+    echo "  CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude -p \"/run-plan $PLAN_FILE --mode competitive --start-batch $START_BATCH --end-batch $END_BATCH --worktree $WORKTREE\" --allowedTools '*' --permission-mode bypassPermissions"
+}
+
+# --- Main ---
+main() {
+    parse_args "$@"
+    validate_args
+    print_banner
+
+    # Plan quality gate (skip on resume or explicit flag)
+    if [[ "$SKIP_PLAN_QUALITY" != true && "$RESUME" != true ]]; then
+        echo ""
+        echo "Running plan quality check..."
+        if ! bash "$SCRIPT_DIR/validate-plan-quality.sh" "$PLAN_FILE" --min-score 60; then
+            echo ""
+            echo "Plan quality below threshold. Use --skip-plan-quality to override."
+            exit 1
+        fi
+        echo ""
+    fi
+
+    case "$MODE" in
+        headless)
+            run_mode_headless
+            ;;
+        team)
+            run_mode_team
+            ;;
+        competitive)
+            run_mode_competitive
+            ;;
+    esac
+}
+
+main "$@"