@lvlup-sw/exarchos 2.0.1

package/scripts/debug-review-gate.sh

@@ -0,0 +1,201 @@
+#!/usr/bin/env bash
+# Debug Review Gate
+# Verifies that a debug fix has proper test coverage for the bug scenario.
+# Replaces "Thorough Track Review" prose with deterministic validation.
+#
+# Usage: debug-review-gate.sh --repo-root <path> --base-branch <branch> [--skip-run]
+#
+# Exit codes:
+#   0 = review passed (tests added, tests pass, no regressions)
+#   1 = gaps found (missing tests or regressions)
+#   2 = usage error (missing required args)
+
+set -euo pipefail
+
+# ============================================================
+# ARGUMENT PARSING
+# ============================================================
+
+REPO_ROOT=""
+BASE_BRANCH=""
+SKIP_RUN=false
+
+usage() {
+    cat << 'USAGE'
+Usage: debug-review-gate.sh --repo-root <path> --base-branch <branch> [--skip-run]
+
+Required:
+  --repo-root <path>      Repository root directory
+  --base-branch <branch>  Base branch to diff against (e.g., main)
+
+Optional:
+  --skip-run              Skip test execution (only check for new test files)
+  --help                  Show this help message
+
+Exit codes:
+  0  Review passed — tests added, tests pass, no regressions
+  1  Gaps found — missing tests or test failures
+  2  Usage error (missing required args)
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo-root)
+            if [[ -z "${2:-}" ]]; then
+                echo "Error: --repo-root requires a path argument" >&2
+                exit 2
+            fi
+            REPO_ROOT="$2"
+            shift 2
+            ;;
+        --base-branch)
+            if [[ -z "${2:-}" ]]; then
+                echo "Error: --base-branch requires a branch name argument" >&2
+                exit 2
+            fi
+            BASE_BRANCH="$2"
+            shift 2
+            ;;
+        --skip-run)
+            SKIP_RUN=true
+            shift
+            ;;
+        --help)
+            usage
+            exit 0
+            ;;
+        *)
+            echo "Error: Unknown argument '$1'" >&2
+            usage >&2
+            exit 2
+            ;;
+    esac
+done
+
+if [[ -z "$REPO_ROOT" || -z "$BASE_BRANCH" ]]; then
+    echo "Error: --repo-root and --base-branch are required" >&2
+    usage >&2
+    exit 2
+fi
+
+if [[ ! -d "$REPO_ROOT" ]]; then
+    echo "Error: Repository root not found: $REPO_ROOT" >&2
+    exit 2
+fi
+
+# ============================================================
+# CHECK FUNCTIONS
+# ============================================================
+
+CHECK_PASS=0
+CHECK_FAIL=0
+RESULTS=()
+
+check_pass() {
+    local name="$1"
+    RESULTS+=("- **PASS**: $name")
+    CHECK_PASS=$((CHECK_PASS + 1))
+}
+
+check_fail() {
+    local name="$1"
+    local detail="${2:-}"
+    if [[ -n "$detail" ]]; then
+        RESULTS+=("- **FAIL**: $name — $detail")
+    else
+        RESULTS+=("- **FAIL**: $name")
+    fi
+    CHECK_FAIL=$((CHECK_FAIL + 1))
+}
+
+check_skip() {
+    local name="$1"
+    RESULTS+=("- **SKIP**: $name")
+}
+
+# ============================================================
+# CHECK 1: New test files added in the fix branch
+# ============================================================
+
+check_new_tests() {
+    local changed_files
+    changed_files="$(cd "$REPO_ROOT" && git diff --name-only "$BASE_BRANCH"...HEAD 2>/dev/null || \
+                     cd "$REPO_ROOT" && git diff --name-only "$BASE_BRANCH" HEAD 2>/dev/null || true)"
+
+    if [[ -z "$changed_files" ]]; then
+        check_fail "New test files added" "No changed files found between $BASE_BRANCH and HEAD"
+        return 1
+    fi
+
+    # Look for test files: .test.ts, .test.sh, .spec.ts, .test.js, .spec.js
+    local test_files
+    test_files="$(echo "$changed_files" | grep -E '\.(test|spec)\.(ts|js|sh)$' || true)"
+
+    if [[ -z "$test_files" ]]; then
+        check_fail "New test files added" "No test files found in changed files"
+        return 1
+    fi
+
+    local test_count
+    test_count="$(echo "$test_files" | wc -l | tr -d ' ')"
+    check_pass "New test files added ($test_count test file(s): $(echo "$test_files" | tr '\n' ', ' | sed 's/,$//'))"
+    return 0
+}
+
+# ============================================================
+# CHECK 2: Tests pass (npm run test:run)
+# ============================================================
+
+check_tests_pass() {
+    if [[ "$SKIP_RUN" == true ]]; then
+        check_skip "Tests pass (--skip-run)"
+        return 0
+    fi
+
+    local test_output
+    if ! test_output="$(cd "$REPO_ROOT" && npm run test:run 2>&1)"; then
+        check_fail "Tests pass" "npm run test:run failed"
+        return 1
+    fi
+
+    check_pass "Tests pass"
+    return 0
+}
+
+# ============================================================
+# EXECUTE CHECKS
+# ============================================================
+
+# Check 1: New test files
+check_new_tests || true
+
+# Check 2: Tests pass
+check_tests_pass || true
+
+# ============================================================
+# STRUCTURED OUTPUT
+# ============================================================
+
+echo "## Debug Review Gate"
+echo ""
+echo "**Repository:** \`$REPO_ROOT\`"
+echo "**Base branch:** \`$BASE_BRANCH\`"
+echo ""
+
+for result in "${RESULTS[@]}"; do
+    echo "$result"
+done
+
+echo ""
+TOTAL=$((CHECK_PASS + CHECK_FAIL))
+echo "---"
+echo ""
+
+if [[ $CHECK_FAIL -eq 0 ]]; then
+    echo "**Result: PASS** ($CHECK_PASS/$TOTAL checks passed)"
+    exit 0
+else
+    echo "**Result: FAIL** ($CHECK_FAIL/$TOTAL checks failed)"
+    exit 1
+fi

package/scripts/extract-fix-tasks.sh

@@ -0,0 +1,179 @@
+#!/usr/bin/env bash
+# extract-fix-tasks.sh — Parse review findings into fix tasks
+# Replaces "Fix Mode Task Extraction" prose in delegation SKILL.md.
+#
+# Usage: extract-fix-tasks.sh --state-file <path> [--review-report <path>] [--repo-root <path>]
+#
+# Exit codes:
+#   0 = tasks extracted (outputs JSON array to stdout)
+#   1 = parse error
+#   2 = usage error (missing required args)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# ============================================================
+# ARGUMENT PARSING
+# ============================================================
+
+STATE_FILE=""
+REVIEW_REPORT=""
+REPO_ROOT=""
+
+usage() {
+    cat << 'USAGE'
+Usage: extract-fix-tasks.sh --state-file <path> [--review-report <path>] [--repo-root <path>]
+
+Required:
+  --state-file <path>       Path to the workflow state JSON file
+
+Optional:
+  --review-report <path>    External review report JSON file (overrides state findings)
+  --repo-root <path>        Repository root for worktree resolution
+  --help                    Show this help message
+
+Output:
+  JSON array of fix tasks to stdout. Each task has: id, file, line, worktree, description, severity
+
+Exit codes:
+  0  Tasks extracted (JSON array output, may be empty if no findings)
+  1  Parse error (invalid JSON, missing file)
+  2  Usage error (missing required args)
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --state-file)
+            if [[ -z "${2:-}" ]]; then
+                echo "Error: --state-file requires a path argument" >&2
+                exit 2
+            fi
+            STATE_FILE="$2"
+            shift 2
+            ;;
+        --review-report)
+            if [[ -z "${2:-}" ]]; then
+                echo "Error: --review-report requires a path argument" >&2
+                exit 2
+            fi
+            REVIEW_REPORT="$2"
+            shift 2
+            ;;
+        --repo-root)
+            if [[ -z "${2:-}" ]]; then
+                echo "Error: --repo-root requires a path argument" >&2
+                exit 2
+            fi
+            REPO_ROOT="$2"
+            shift 2
+            ;;
+        --help)
+            usage
+            exit 0
+            ;;
+        *)
+            echo "Error: Unknown argument '$1'" >&2
+            usage >&2
+            exit 2
+            ;;
+    esac
+done
+
+if [[ -z "$STATE_FILE" ]]; then
+    echo "Error: --state-file is required" >&2
+    usage >&2
+    exit 2
+fi
+
+# ============================================================
+# DEPENDENCY CHECK
+# ============================================================
+
+if ! command -v jq &>/dev/null; then
+    echo "Error: jq is required but not installed" >&2
+    exit 2
+fi
+
+# ============================================================
+# VALIDATE INPUTS
+# ============================================================
+
+if [[ ! -f "$STATE_FILE" ]]; then
+    echo "Error: State file not found: $STATE_FILE" >&2
+    exit 1
+fi
+
+if ! jq empty "$STATE_FILE" 2>/dev/null; then
+    echo "Error: Invalid JSON in state file: $STATE_FILE" >&2
+    exit 1
+fi
+
+if [[ -n "$REVIEW_REPORT" ]]; then
+    if [[ ! -f "$REVIEW_REPORT" ]]; then
+        echo "Error: Review report not found: $REVIEW_REPORT" >&2
+        exit 1
+    fi
+    if ! jq empty "$REVIEW_REPORT" 2>/dev/null; then
+        echo "Error: Invalid JSON in review report: $REVIEW_REPORT" >&2
+        exit 1
+    fi
+fi
+
+# ============================================================
+# EXTRACT FINDINGS
+# ============================================================
+
+# Collect all findings from either the review report or the state file
+if [[ -n "$REVIEW_REPORT" ]]; then
+    # Use external review report
+    ALL_FINDINGS="$(jq -c '.findings // []' "$REVIEW_REPORT" 2>/dev/null || echo '[]')"
+else
+    # Extract findings from state file reviews
+    ALL_FINDINGS="$(jq -c '
+        [
+            (.reviews // {} | to_entries[] | .value.findings // [] | .[])
+        ]
+    ' "$STATE_FILE" 2>/dev/null || echo '[]')"
+fi
+
+# ============================================================
+# BUILD FIX TASKS
+# ============================================================
+
+# Get all worktrees from tasks for file-to-worktree mapping
+WORKTREES_JSON="$(jq -c '[.tasks[] | select(.worktree != null) | {worktree: .worktree, branch: (.branch // "unknown")}] | unique_by(.worktree)' "$STATE_FILE" 2>/dev/null || echo '[]')"
+
+# Fail fast when multiple worktrees exist — deterministic mapping not yet implemented
+WORKTREE_COUNT="$(echo "$WORKTREES_JSON" | jq 'length')"
+FINDING_COUNT="$(echo "$ALL_FINDINGS" | jq 'length')"
+if [[ "$WORKTREE_COUNT" -gt 1 && "$FINDING_COUNT" -gt 0 ]]; then
+    echo "Error: $WORKTREE_COUNT worktrees detected but cannot deterministically map $FINDING_COUNT findings to worktrees." >&2
+    echo "  Assign worktrees manually in the fix task file." >&2
+    exit 1
+fi
+
+# Transform findings into fix tasks with IDs and worktree mapping
+FIX_TASKS="$(echo "$ALL_FINDINGS" | jq -c --argjson worktrees "$WORKTREES_JSON" '
+    [to_entries[] | {
+        id: ("fix-\(.key + 1 | tostring | if length < 3 then ("00" + .)[-3:] else . end)"),
+        file: .value.file,
+        line: (.value.line // null),
+        worktree: (
+            ($worktrees | length) as $n |
+            if $n == 1 then $worktrees[0].worktree else null end
+        ),
+        description: .value.description,
+        severity: (.value.severity // "MEDIUM")
+    }]
+' 2>/dev/null)"
+
+if [[ -z "$FIX_TASKS" || "$FIX_TASKS" == "null" ]]; then
+    echo "[]"
+    exit 0
+fi
+
+# Output the fix tasks JSON array
+echo "$FIX_TASKS"
+exit 0

package/scripts/extract-task.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+#
+# extract-task.sh - Extract single task from implementation plan
+#
+# Usage: extract-task.sh <plan-path> <task-id>
+#
+# Output: Just the task section from the plan, not the full document.
+#         This reduces context by ~90% when delegating tasks.
+#
+# Examples:
+#   extract-task.sh docs/plans/2026-01-05-auth.md 001
+#   extract-task.sh docs/plans/2026-01-05-auth.md A1
+#
+
+set -euo pipefail
+
+PLAN="${1:-}"
+TASK_ID="${2:-}"
+
+if [ -z "$PLAN" ] || [ -z "$TASK_ID" ]; then
+    echo "Usage: extract-task.sh <plan-path> <task-id>" >&2
+    exit 1
+fi
+
+if [ ! -f "$PLAN" ]; then
+    echo "ERROR: Plan file not found: $PLAN" >&2
+    exit 1
+fi
+
+# Extract task section using awk
+# Matches: ### Task 001, ### Task A1, ### Task 1:, etc.
+# Stops at next task header or major section header
+
+awk -v task_id="$TASK_ID" '
+    BEGIN {
+        found = 0
+        # Build pattern to match task header
+        # Handles: "### Task 001:", "### Task A1:", "## Task 1", etc.
+        pattern = "^##+ *Task *" task_id "([: ]|$)"
+    }
+
+    # Start capturing when we find the task
+    $0 ~ pattern {
+        found = 1
+        print
+        next
+    }
+
+    # Stop at next task or major section
+    found && /^##+ *(Task [0-9A-Za-z]+|[A-Z])/ {
+        exit
+    }
+
+    # Print while capturing
+    found {
+        print
+    }
+' "$PLAN"
+
+# Check if we found anything
+if ! grep -qE "^##+ *Task *$TASK_ID([: ]|$)" "$PLAN"; then
+    echo "WARNING: Task $TASK_ID not found in $PLAN" >&2
+    echo "" >&2
+    echo "Available tasks:" >&2
+    grep -E "^##+ *Task " "$PLAN" | head -20 >&2
+    exit 1
+fi

package/scripts/generate-traceability.sh

@@ -0,0 +1,209 @@
+#!/usr/bin/env bash
+# Generate Traceability Matrix
+# Pre-populate traceability matrix from design and plan headers.
+#
+# Usage: generate-traceability.sh --design-file <path> --plan-file <path> [--output <path>]
+#
+# Exit codes:
+#   0 = generated successfully
+#   1 = parse error (no sections found)
+#   2 = usage error (missing required args, missing files)
+
+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'
+
+# ============================================================
+# ARGUMENT PARSING
+# ============================================================
+
+DESIGN_FILE=""
+PLAN_FILE=""
+OUTPUT_FILE=""
+
+usage() {
+    cat << 'USAGE'
+Usage: generate-traceability.sh --design-file <path> --plan-file <path> [--output <path>]
+
+Required:
+  --design-file <path>   Path to the design document markdown file
+  --plan-file <path>     Path to the implementation plan markdown file
+
+Optional:
+  --output <path>        Write output to file instead of stdout
+  --help                 Show this help message
+
+Exit codes:
+  0  Generated successfully
+  1  Parse error (no sections found in design)
+  2  Usage error (missing required args, 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
+            ;;
+        --output)
+            if [[ -z "${2:-}" ]]; then
+                echo "Error: --output requires a path argument" >&2
+                exit 2
+            fi
+            OUTPUT_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 (## and ### headers)
+# ============================================================
+
+DESIGN_SECTIONS=()
+DESIGN_LEVELS=()
+
+while IFS= read -r line; do
+    if [[ "$line" =~ ^(#{2,3})[[:space:]]+(.+) ]]; then
+        level="${BASH_REMATCH[1]}"
+        section_name="${BASH_REMATCH[2]}"
+        section_name="$(echo "$section_name" | sed 's/[[:space:]]*$//')"
+        DESIGN_SECTIONS+=("$section_name")
+        DESIGN_LEVELS+=("$level")
+    fi
+done < "$DESIGN_FILE"
+
+if [[ ${#DESIGN_SECTIONS[@]} -eq 0 ]]; then
+    echo "Error: No ## or ### headers found in design document" >&2
+    exit 1
+fi
+
+# ============================================================
+# EXTRACT PLAN TASKS (### Task headers)
+# ============================================================
+
+PLAN_TASKS=()
+PLAN_TASK_IDS=()
+
+while IFS= read -r line; do
+    if [[ "$line" =~ ^###[[:space:]]+Task[[:space:]]+([0-9]+) ]]; then
+        task_id="${BASH_REMATCH[1]}"
+        # Extract the full task title
+        task_title="${line#*: }"
+        if [[ -n "$task_title" && "$task_title" != "$line" ]]; then
+            PLAN_TASKS+=("$task_title")
+        else
+            PLAN_TASKS+=("$line")
+        fi
+        PLAN_TASK_IDS+=("$task_id")
+    fi
+done < "$PLAN_FILE"
+
+# Read full plan content for matching
+PLAN_CONTENT="$(cat "$PLAN_FILE")"
+
+# ============================================================
+# GENERATE TRACEABILITY TABLE
+# ============================================================
+
+generate_table() {
+    echo "## Spec Traceability"
+    echo ""
+    echo "### Traceability Matrix"
+    echo ""
+    echo "| Design Section | Key Requirements | Task ID(s) | Status |"
+    echo "|----------------|-----------------|------------|--------|"
+
+    for i in "${!DESIGN_SECTIONS[@]}"; do
+        section="${DESIGN_SECTIONS[$i]}"
+        level="${DESIGN_LEVELS[$i]}"
+
+        # Find matching tasks
+        matched_ids=()
+        for j in "${!PLAN_TASKS[@]}"; do
+            task="${PLAN_TASKS[$j]}"
+            tid="${PLAN_TASK_IDS[$j]}"
+            if echo "$task" | grep -qiF "$section"; then
+                matched_ids+=("$tid")
+            fi
+        done
+
+        # Also check plan body
+        if [[ ${#matched_ids[@]} -eq 0 ]]; then
+            if echo "$PLAN_CONTENT" | grep -qiF "$section"; then
+                matched_ids+=("?")
+            fi
+        fi
+
+        # Format output
+        if [[ ${#matched_ids[@]} -gt 0 ]]; then
+            ids="$(printf '%s, ' "${matched_ids[@]}")"
+            ids="${ids%, }"
+            echo "| $section | (to be filled) | $ids | Covered |"
+        else
+            echo "| $section | (to be filled) | — | Uncovered |"
+        fi
+    done
+    echo ""
+    echo "### Scope Declaration"
+    echo ""
+    echo "**Target:** (to be filled)"
+    echo "**Excluded:** (to be filled)"
+}
+
+# ============================================================
+# OUTPUT
+# ============================================================
+
+if [[ -n "$OUTPUT_FILE" ]]; then
+    generate_table > "$OUTPUT_FILE"
+    echo "Traceability matrix written to: $OUTPUT_FILE"
+else
+    generate_table
+fi
+
+exit 0