@lvlup-sw/exarchos 2.0.1

package/scripts/verify-plan-coverage.sh

@@ -0,0 +1,228 @@
+#!/usr/bin/env bash
+# Verify Plan Coverage
+# Cross-reference design document sections to plan tasks. Replaces "Plan Verification" prose.
+#
+# Usage: verify-plan-coverage.sh --design-file <path> --plan-file <path>
+#
+# Exit codes:
+#   0 = complete coverage (every Technical Design subsection maps to >= 1 task)
+#   1 = gaps found (unmapped sections)
+#   2 = usage error (missing required args, empty design, missing files)
+
+set -euo pipefail
+
+# ============================================================
+# ARGUMENT PARSING
+# ============================================================
+
+DESIGN_FILE=""
+PLAN_FILE=""
+
+usage() {
+    cat << 'USAGE'
+Usage: verify-plan-coverage.sh --design-file <path> --plan-file <path>
+
+Required:
+  --design-file <path>   Path to the design document markdown file
+  --plan-file <path>     Path to the implementation plan markdown file
+
+Optional:
+  --help                 Show this help message
+
+Exit codes:
+  0  Complete coverage (all Technical Design subsections mapped to tasks)
+  1  Gaps found (unmapped design sections)
+  2  Usage error (missing required args, empty design, missing files)
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --design-file)
+            if [[ -z "${2:-}" ]]; then
+                echo "Error: --design-file requires a path argument" >&2
+                exit 2
+            fi
+            DESIGN_FILE="$2"
+            shift 2
+            ;;
+        --plan-file)
+            if [[ -z "${2:-}" ]]; then
+                echo "Error: --plan-file requires a path argument" >&2
+                exit 2
+            fi
+            PLAN_FILE="$2"
+            shift 2
+            ;;
+        --help)
+            usage
+            exit 0
+            ;;
+        *)
+            echo "Error: Unknown argument '$1'" >&2
+            usage >&2
+            exit 2
+            ;;
+    esac
+done
+
+if [[ -z "$DESIGN_FILE" || -z "$PLAN_FILE" ]]; then
+    echo "Error: --design-file and --plan-file are required" >&2
+    usage >&2
+    exit 2
+fi
+
+if [[ ! -f "$DESIGN_FILE" ]]; then
+    echo "Error: Design file not found: $DESIGN_FILE" >&2
+    exit 2
+fi
+
+if [[ ! -f "$PLAN_FILE" ]]; then
+    echo "Error: Plan file not found: $PLAN_FILE" >&2
+    exit 2
+fi
+
+# ============================================================
+# EXTRACT DESIGN SECTIONS
+# ============================================================
+
+# Extract ### subsections under ## Technical Design
+# We look for "## Technical Design" then collect all ### headers until the next ## header
+DESIGN_SECTIONS=()
+IN_TECH_DESIGN=false
+
+while IFS= read -r line; do
+    # Detect start of Technical Design section
+    if [[ "$line" =~ ^##[[:space:]]+Technical[[:space:]]+Design ]]; then
+        IN_TECH_DESIGN=true
+        continue
+    fi
+
+    # Detect next ## section (end of Technical Design)
+    if [[ "$IN_TECH_DESIGN" == true && "$line" =~ ^##[[:space:]] && ! "$line" =~ ^###[[:space:]] ]]; then
+        IN_TECH_DESIGN=false
+        continue
+    fi
+
+    # Collect ### subsection headers within Technical Design
+    if [[ "$IN_TECH_DESIGN" == true && "$line" =~ ^###[[:space:]]+(.+) ]]; then
+        section_name="${BASH_REMATCH[1]}"
+        # Trim trailing whitespace
+        section_name="$(echo "$section_name" | sed 's/[[:space:]]*$//')"
+        DESIGN_SECTIONS+=("$section_name")
+    fi
+done < "$DESIGN_FILE"
+
+# Validate we found sections
+if [[ ${#DESIGN_SECTIONS[@]} -eq 0 ]]; then
+    echo "Error: No Technical Design subsections found in design document" >&2
+    echo "Expected ### headers under '## Technical Design'" >&2
+    exit 2
+fi
+
+# ============================================================
+# EXTRACT PLAN TASKS
+# ============================================================
+
+# Extract ### Task headers from plan
+PLAN_TASKS=()
+while IFS= read -r line; do
+    if [[ "$line" =~ ^###[[:space:]]+Task[[:space:]]+[0-9]+ ]]; then
+        # Extract the full task title (everything after "### Task NNN: ")
+        task_title="${line#*: }"
+        if [[ -n "$task_title" && "$task_title" != "$line" ]]; then
+            PLAN_TASKS+=("$task_title")
+        else
+            PLAN_TASKS+=("$line")
+        fi
+    fi
+done < "$PLAN_FILE"
+
+# Also read the full plan content for free-text matching
+PLAN_CONTENT="$(cat "$PLAN_FILE")"
+
+# ============================================================
+# CROSS-REFERENCE: Design sections to plan tasks
+# ============================================================
+
+CHECK_PASS=0
+CHECK_FAIL=0
+GAPS=()
+MATRIX_ROWS=()
+
+for section in "${DESIGN_SECTIONS[@]}"; do
+    # Check if any task title or plan content references this design section
+    MATCHED_TASKS=()
+
+    for task in "${PLAN_TASKS[@]}"; do
+        # Case-insensitive substring match
+        if echo "$task" | grep -qiF "$section"; then
+            MATCHED_TASKS+=("$task")
+        fi
+    done
+
+    # If no task title matches, check the full plan content for the section name
+    if [[ ${#MATCHED_TASKS[@]} -eq 0 ]]; then
+        if echo "$PLAN_CONTENT" | grep -qiF "$section"; then
+            MATCHED_TASKS+=("(referenced in plan body)")
+        fi
+    fi
+
+    if [[ ${#MATCHED_TASKS[@]} -gt 0 ]]; then
+        task_list="$(printf '%s, ' "${MATCHED_TASKS[@]}")"
+        task_list="${task_list%, }"
+        MATRIX_ROWS+=("| $section | $task_list | Covered |")
+        CHECK_PASS=$((CHECK_PASS + 1))
+    else
+        MATRIX_ROWS+=("| $section | — | **GAP** |")
+        GAPS+=("$section")
+        CHECK_FAIL=$((CHECK_FAIL + 1))
+    fi
+done
+
+# ============================================================
+# STRUCTURED OUTPUT
+# ============================================================
+
+echo "## Plan Coverage Report"
+echo ""
+echo "**Design file:** \`$DESIGN_FILE\`"
+echo "**Plan file:** \`$PLAN_FILE\`"
+echo ""
+
+echo "### Coverage Matrix"
+echo ""
+echo "| Design Section | Task(s) | Status |"
+echo "|----------------|---------|--------|"
+for row in "${MATRIX_ROWS[@]}"; do
+    echo "$row"
+done
+echo ""
+
+TOTAL=$((CHECK_PASS + CHECK_FAIL))
+echo "### Summary"
+echo ""
+echo "- Design sections: $TOTAL"
+echo "- Covered: $CHECK_PASS"
+echo "- Gaps: $CHECK_FAIL"
+echo ""
+
+if [[ ${#GAPS[@]} -gt 0 ]]; then
+    echo "### Unmapped Sections"
+    echo ""
+    for gap in "${GAPS[@]}"; do
+        echo "- **$gap** — No task maps to this design section"
+    done
+    echo ""
+fi
+
+echo "---"
+echo ""
+
+if [[ $CHECK_FAIL -eq 0 ]]; then
+    echo "**Result: PASS** (${CHECK_PASS}/${TOTAL} sections covered)"
+    exit 0
+else
+    echo "**Result: FAIL** (${CHECK_FAIL}/${TOTAL} sections have gaps)"
+    exit 1
+fi

package/scripts/verify-review-triage.sh

@@ -0,0 +1,219 @@
+#!/usr/bin/env bash
+# verify-review-triage.sh
+# Verifies review triage was applied correctly to a stack of PRs.
+#
+# Usage: verify-review-triage.sh --state-file <path> --event-stream <path>
+#
+# Checks:
+#   1. All PRs in state file have a review.routed event in the event stream
+#   2. High-risk PRs (riskScore >= 0.4) were sent to CodeRabbit
+#   3. Self-hosted review ran for all PRs (destination is "self-hosted" or "both")
+#   4. No PR is missing review routing
+#
+# Exit codes:
+#   0  All checks pass
+#   1  Verification failed (details in output)
+#   2  Usage error
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+# ============================================================
+# USAGE
+# ============================================================
+
+usage() {
+    cat <<'EOF'
+Usage: verify-review-triage.sh --state-file <path> --event-stream <path>
+
+Verifies review triage was applied correctly to a stack of PRs.
+
+Options:
+  --state-file <path>     Path to workflow state JSON file (required)
+  --event-stream <path>   Path to event stream JSONL file (required)
+  --help                  Show this help message
+
+Checks:
+  1. All PRs have a review.routed event
+  2. High-risk PRs (score >= 0.4) sent to CodeRabbit
+  3. Self-hosted review ran for all PRs
+  4. No PR missing review routing
+
+Exit codes:
+  0   All checks pass
+  1   Verification failed (details in output)
+  2   Usage error (missing required arguments)
+EOF
+}
+
+# ============================================================
+# ARGUMENT PARSING
+# ============================================================
+
+STATE_FILE=""
+EVENT_STREAM=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --state-file)
+            if [[ $# -lt 2 ]]; then
+                echo -e "${RED}ERROR${NC}: --state-file requires a value" >&2
+                exit 2
+            fi
+            STATE_FILE="$2"
+            shift 2
+            ;;
+        --event-stream)
+            if [[ $# -lt 2 ]]; then
+                echo -e "${RED}ERROR${NC}: --event-stream requires a value" >&2
+                exit 2
+            fi
+            EVENT_STREAM="$2"
+            shift 2
+            ;;
+        --help)
+            usage
+            exit 0
+            ;;
+        -*)
+            echo -e "${RED}ERROR${NC}: Unknown option: $1" >&2
+            usage >&2
+            exit 2
+            ;;
+        *)
+            echo -e "${RED}ERROR${NC}: Unexpected argument: $1" >&2
+            usage >&2
+            exit 2
+            ;;
+    esac
+done
+
+# ============================================================
+# VALIDATION
+# ============================================================
+
+if [[ -z "$STATE_FILE" ]]; then
+    echo -e "${RED}ERROR${NC}: --state-file is required" >&2
+    usage >&2
+    exit 2
+fi
+
+if [[ ! -f "$STATE_FILE" ]]; then
+    echo -e "${RED}ERROR${NC}: State file not found: $STATE_FILE" >&2
+    exit 2
+fi
+
+if [[ -z "$EVENT_STREAM" ]]; then
+    echo -e "${RED}ERROR${NC}: --event-stream is required" >&2
+    usage >&2
+    exit 2
+fi
+
+if [[ ! -f "$EVENT_STREAM" ]]; then
+    echo -e "${RED}ERROR${NC}: Event stream file not found: $EVENT_STREAM" >&2
+    exit 2
+fi
+
+# ============================================================
+# DEPENDENCY CHECKS
+# ============================================================
+
+if ! command -v jq &> /dev/null; then
+    echo -e "${RED}ERROR${NC}: jq is not installed" >&2
+    exit 1
+fi
+
+# ============================================================
+# VERIFICATION LOGIC
+# ============================================================
+
+HAS_FAILURE=false
+CHECKS_PASSED=0
+CHECKS_FAILED=0
+REPORT_LINES=()
+
+report_pass() {
+    local msg="$1"
+    REPORT_LINES+=("| PASS | $msg |")
+    CHECKS_PASSED=$((CHECKS_PASSED + 1))
+}
+
+report_fail() {
+    local msg="$1"
+    REPORT_LINES+=("| FAIL | $msg |")
+    CHECKS_FAILED=$((CHECKS_FAILED + 1))
+    HAS_FAILURE=true
+}
+
+# Extract PR numbers from state file
+PR_NUMBERS=$(jq -r '.prs[].number' "$STATE_FILE" 2>/dev/null)
+if [[ -z "$PR_NUMBERS" ]]; then
+    echo -e "${RED}ERROR${NC}: No PRs found in state file" >&2
+    exit 1
+fi
+
+# Build a lookup of review.routed events from the event stream (one per line JSONL)
+# Parse each line that is a review.routed event
+for pr in $PR_NUMBERS; do
+    # Check 1: review.routed event exists for this PR
+    ROUTED_EVENT=$(jq -c "select(.type == \"review.routed\" and .data.pr == $pr)" "$EVENT_STREAM" 2>/dev/null | tail -1)
+
+    if [[ -z "$ROUTED_EVENT" ]]; then
+        report_fail "PR #$pr: missing review.routed event"
+        continue
+    fi
+
+    report_pass "PR #$pr: review.routed event exists"
+
+    # Check 2: High-risk PRs (riskScore >= 0.4) sent to CodeRabbit
+    RISK_SCORE=$(echo "$ROUTED_EVENT" | jq -r '.data.riskScore // 0')
+    IS_HIGH_RISK=$(echo "$RISK_SCORE" | jq -Rr 'tonumber >= 0.4')
+
+    if [[ "$IS_HIGH_RISK" == "true" ]]; then
+        HAS_CODERABBIT=$(echo "$ROUTED_EVENT" | jq -r '.data.destination == "coderabbit" or .data.destination == "both"')
+        if [[ "$HAS_CODERABBIT" == "true" ]]; then
+            report_pass "PR #$pr: high-risk (score=$RISK_SCORE) sent to CodeRabbit"
+        else
+            report_fail "PR #$pr: high-risk (score=$RISK_SCORE) NOT sent to CodeRabbit"
+        fi
+    fi
+
+    # Check 3: Self-hosted review ran for all PRs
+    SELF_HOSTED=$(echo "$ROUTED_EVENT" | jq -r '.data.destination == "self-hosted" or .data.destination == "both"')
+    if [[ "$SELF_HOSTED" == "true" ]]; then
+        report_pass "PR #$pr: self-hosted review enabled"
+    else
+        report_fail "PR #$pr: self-hosted review NOT enabled"
+    fi
+done
+
+# ============================================================
+# OUTPUT REPORT
+# ============================================================
+
+echo "## Review Triage Verification"
+echo ""
+echo "| Status | Check |"
+echo "|--------|-------|"
+for line in "${REPORT_LINES[@]}"; do
+    echo "$line"
+done
+echo ""
+echo "**Passed:** $CHECKS_PASSED | **Failed:** $CHECKS_FAILED"
+
+# ============================================================
+# EXIT CODE
+# ============================================================
+
+if [[ "$HAS_FAILURE" == true ]]; then
+    exit 1
+else
+    exit 0
+fi

package/scripts/verify-worktree-baseline.sh

@@ -0,0 +1,159 @@
+#!/usr/bin/env bash
+# verify-worktree-baseline.sh — Run baseline tests in a worktree before dispatch
+# Usage: verify-worktree-baseline.sh --worktree-path <path> [--help]
+# Exit codes: 0=baseline pass, 1=baseline fail, 2=project type unknown or usage error
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# ============================================================
+# ARGUMENT PARSING
+# ============================================================
+
+WORKTREE_PATH=""
+
+usage() {
+    cat << 'USAGE'
+Usage: verify-worktree-baseline.sh --worktree-path <path> [--help]
+
+Run baseline tests in a worktree to verify it is ready for implementation.
+Auto-detects project type and runs the appropriate test command.
+
+Required:
+  --worktree-path <path>   Path to the worktree directory
+
+Optional:
+  --help                   Show this help message
+
+Supported project types:
+  Node.js     package.json     → npm run test:run
+  .NET        *.csproj         → dotnet test
+  Rust        Cargo.toml       → cargo test
+
+Exit codes:
+  0  Baseline tests pass — worktree is ready
+  1  Baseline tests failed — investigate before proceeding
+  2  Unknown project type or usage error
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --worktree-path)
+            if [[ -z "${2:-}" ]]; then
+                echo "Error: --worktree-path requires a path argument" >&2
+                exit 2
+            fi
+            WORKTREE_PATH="$2"
+            shift 2
+            ;;
+        --help)
+            usage
+            exit 0
+            ;;
+        *)
+            echo "Error: Unknown argument '$1'" >&2
+            usage >&2
+            exit 2
+            ;;
+    esac
+done
+
+if [[ -z "$WORKTREE_PATH" ]]; then
+    echo "Error: --worktree-path is required" >&2
+    usage >&2
+    exit 2
+fi
+
+if [[ ! -d "$WORKTREE_PATH" ]]; then
+    echo "Error: Worktree path does not exist: $WORKTREE_PATH" >&2
+    exit 2
+fi
+
+# Verify it's actually a git worktree
+if ! git -C "$WORKTREE_PATH" rev-parse --git-dir > /dev/null 2>&1; then
+    echo "Error: Not a git worktree: $WORKTREE_PATH" >&2
+    exit 2
+fi
+
+# ============================================================
+# PROJECT TYPE DETECTION
+# ============================================================
+
+PROJECT_TYPE=""
+TEST_CMD=""
+
+detect_project_type() {
+    if [[ -f "$WORKTREE_PATH/package.json" ]]; then
+        PROJECT_TYPE="Node.js"
+        TEST_CMD="npm run test:run"
+    elif ls "$WORKTREE_PATH"/*.csproj 1>/dev/null 2>&1; then
+        PROJECT_TYPE=".NET"
+        TEST_CMD="dotnet test"
+    elif [[ -f "$WORKTREE_PATH/Cargo.toml" ]]; then
+        PROJECT_TYPE="Rust"
+        TEST_CMD="cargo test"
+    fi
+}
+
+detect_project_type
+
+# ============================================================
+# RUN BASELINE TESTS
+# ============================================================
+
+TEST_OUTPUT=""
+TEST_EXIT=0
+
+if [[ -z "$PROJECT_TYPE" ]]; then
+    echo "## Baseline Verification Report"
+    echo ""
+    echo "**Worktree:** \`$WORKTREE_PATH\`"
+    echo "**Project type detected:** Unknown"
+    echo ""
+    echo "No recognized project files found (package.json, *.csproj, Cargo.toml)."
+    echo "Manual verification required."
+    echo ""
+    echo "---"
+    echo ""
+    echo "**Result: UNKNOWN** — could not detect project type"
+    exit 2
+fi
+
+TEST_OUTPUT="$(cd "$WORKTREE_PATH" && $TEST_CMD 2>&1)" && TEST_EXIT=0 || TEST_EXIT=$?
+
+# ============================================================
+# STRUCTURED MARKDOWN OUTPUT
+# ============================================================
+
+echo "## Baseline Verification Report"
+echo ""
+echo "**Worktree:** \`$WORKTREE_PATH\`"
+echo "**Project type detected:** $PROJECT_TYPE"
+echo "**Test command:** \`$TEST_CMD\`"
+echo ""
+
+if [[ $TEST_EXIT -eq 0 ]]; then
+    echo "### Test Output"
+    echo ""
+    echo '```'
+    echo "$TEST_OUTPUT"
+    echo '```'
+    echo ""
+    echo "---"
+    echo ""
+    echo "**Result: PASS** — baseline tests succeeded"
+    exit 0
+else
+    echo "### Test Output"
+    echo ""
+    echo '```'
+    echo "$TEST_OUTPUT"
+    echo '```'
+    echo ""
+    echo "---"
+    echo ""
+    echo "**Result: FAIL** — baseline tests failed (exit code $TEST_EXIT)"
+    exit 1
+fi

package/scripts/verify-worktree.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# verify-worktree.sh — Verify execution is inside a git worktree
+# Usage: verify-worktree.sh [--cwd <path>] [--help]
+# Exit codes: 0=in worktree, 1=not in worktree, 2=usage error
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
+# ============================================================
+# ARGUMENT PARSING
+# ============================================================
+
+CWD=""
+
+usage() {
+    cat << 'USAGE'
+Usage: verify-worktree.sh [--cwd <path>] [--help]
+
+Verify that the current (or provided) working directory is inside a git worktree.
+
+Optional:
+  --cwd <path>    Directory to check (default: current working directory)
+  --help          Show this help message
+
+Exit codes:
+  0  In a valid worktree (path contains .worktrees/)
+  1  Not in a worktree
+  2  Usage error
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --cwd)
+            if [[ -z "${2:-}" ]]; then
+                echo "Error: --cwd requires a path argument" >&2
+                exit 2
+            fi
+            CWD="$2"
+            shift 2
+            ;;
+        --help)
+            usage
+            exit 0
+            ;;
+        *)
+            echo "Error: Unknown argument '$1'" >&2
+            usage >&2
+            exit 2
+            ;;
+    esac
+done
+
+# Default to current working directory if --cwd not provided
+if [[ -z "$CWD" ]]; then
+    CWD="$(pwd)"
+fi
+
+# Validate path exists and normalize to absolute
+if [[ ! -d "$CWD" ]]; then
+    echo "Error: Directory does not exist: $CWD" >&2
+    exit 2
+fi
+CWD="$(cd "$CWD" && pwd)"
+
+# ============================================================
+# WORKTREE CHECK
+# ============================================================
+
+if [[ "$CWD" =~ \.worktrees/ ]]; then
+    echo -e "${GREEN}OK:${NC} Working in worktree at ${CWD}"
+    exit 0
+else
+    echo -e "${RED}ERROR:${NC} Not in a worktree! Current directory: ${CWD}"
+    echo "Expected: path containing '.worktrees/'"
+    echo "ABORTING — DO NOT proceed with file modifications"
+    exit 1
+fi