hub-launch 1.0.3

package/dist/templates/scripts/hula-fix-setup.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+# hula-fix-setup.sh — Steps 2-6 of the hula.fix workflow
+# Usage: bash .github/scripts/hula-fix-setup.sh <issue-number> [--repo-root <path>]
+#
+# Performs: issue lookup → worktree creation → session file writing
+# Outputs structured JSON to stdout; all other output goes to stderr
+# Exit codes: 0=success, 1=user error, 2=tool error
+
+set -euo pipefail
+
+# ── helpers ────────────────────────────────────────────────────────────────────
+
+json_escape() {
+  # Escape a string for safe embedding inside a JSON double-quoted value
+  printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g; s/$/\\n/g' | tr -d '\n' | sed 's/\\n$//'
+}
+
+die() {
+  local code="$1"; shift
+  local safe_msg
+  safe_msg=$(json_escape "$*")
+  printf '{"status":"error","code":%d,"message":"%s"}\n' "$code" "$safe_msg" >&1
+  exit "$code"
+}
+
+emit_json() {
+  # emit_json key value [key value ...]  — values are already JSON-safe strings
+  local out='{'
+  local sep=''
+  while [[ $# -ge 2 ]]; do
+    local k="$1" v="$2"; shift 2
+    out="${out}${sep}\"${k}\":\"${v}\""
+    sep=','
+  done
+  printf '%s}\n' "$out"
+}
+
+# ── argument parsing ────────────────────────────────────────────────────────────
+
+ISSUE_NUMBER=''
+REPO_ROOT=''
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo-root)
+      REPO_ROOT="$2"; shift 2 ;;
+    --repo-root=*)
+      REPO_ROOT="${1#--repo-root=}"; shift ;;
+    [0-9]*)
+      ISSUE_NUMBER="$1"; shift ;;
+    *)
+      die 1 "Unknown argument: $1" ;;
+  esac
+done
+
+if [[ -z "$ISSUE_NUMBER" ]]; then
+  die 1 "Usage: bash .github/scripts/hula-fix-setup.sh <issue-number> [--repo-root <path>]"
+fi
+
+if [[ -n "$REPO_ROOT" ]]; then
+  cd "$REPO_ROOT"
+fi
+
+# ── Step 1: Infer owner/repo and repo name from git remote ─────────────────────
+
+NAME_WITH_OWNER=$(gh repo view --json nameWithOwner -q '.nameWithOwner' 2>/dev/null) \
+  || die 2 "Failed to determine repo from git remote. Is this a GitHub repo?"
+
+REPO_NAME=$(gh repo view --json name -q '.name' 2>/dev/null) \
+  || die 2 "Failed to determine repo name."
+
+# ── Step 2: Fetch issue details ────────────────────────────────────────────────
+
+ISSUE_JSON=$(gh issue view "$ISSUE_NUMBER" --json title,body,labels 2>/dev/null) \
+  || die 1 "Issue #${ISSUE_NUMBER} not found or not accessible."
+
+ISSUE_TITLE=$(printf '%s' "$ISSUE_JSON" | grep -o '"title":"[^"]*"' | head -1 | sed 's/"title":"//;s/"$//')
+
+# ── Step 3: Validate issue is tracked and has a PR (via hula view) ─────────────
+
+HULA_VIEW=$(hula view 2>&1) || true
+
+if printf '%s' "$HULA_VIEW" | grep -qi "not tracked\|no issues"; then
+  die 1 "Issue #${ISSUE_NUMBER} is not tracked. Run: hula track ${ISSUE_NUMBER}"
+fi
+
+# ── Step 4: Find PR branch for the issue ──────────────────────────────────────
+
+PR_BRANCH=$(gh pr list --search "linked:${ISSUE_NUMBER}" --json headRefName -q '.[0].headRefName' 2>/dev/null) || true
+
+if [[ -z "$PR_BRANCH" ]]; then
+  # Fallback: search PR bodies for issue references
+  # Handles both short format (#N) and full-path format (owner/repo#N)
+  # Uses gh's built-in jq (-q) — no external jq required
+  JQ_EXPR='.[] | select(.body != null) | select(.body | test("(Fixes|Closes|Resolves)[ ]+([A-Za-z0-9._-]+/[A-Za-z0-9._-]+)?#'"${ISSUE_NUMBER}"'([^0-9]|$)|(^|[^0-9])#'"${ISSUE_NUMBER}"'([^0-9]|$)"; "i")) | .headRefName'
+  PR_BRANCH=$(gh pr list --json headRefName,body --limit 100 -q "$JQ_EXPR" 2>/dev/null | head -1) || true
+fi
+
+if [[ -z "$PR_BRANCH" ]]; then
+  die 1 "No PR found for issue #${ISSUE_NUMBER}. Create a PR first with: hula checkout ${ISSUE_NUMBER}"
+fi
+
+# ── Step 5: Determine worktree path ───────────────────────────────────────────
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/hula-read-config.sh"
+WORKTREE_PATH="${HULA_WORKTREE_BASE_PATH}/hula/${REPO_NAME}/fix-${ISSUE_NUMBER}"
+
+# ── Step 6: Create or reuse the worktree ─────────────────────────────────────
+
+WORKTREE_STATUS='reused'
+
+if git worktree list --porcelain 2>/dev/null | grep -qxF "worktree ${WORKTREE_PATH}"; then
+  printf 'ℹ️  Resuming existing fix worktree at %s\n' "$WORKTREE_PATH" >&2
+else
+  printf '🌳 Creating fix worktree at: %s\n' "$WORKTREE_PATH" >&2
+  git fetch origin >&2 2>&1 || die 2 "git fetch origin failed"
+  git worktree add "$WORKTREE_PATH" "$PR_BRANCH" >&2 2>&1 \
+    || die 2 "Failed to create worktree at ${WORKTREE_PATH}. Check that branch ${PR_BRANCH} exists."
+  WORKTREE_STATUS='created'
+fi
+
+# ── Step 7: Write session file ────────────────────────────────────────────────
+
+REPO_ROOT_SESSION=$(git rev-parse --show-toplevel 2>/dev/null) || REPO_ROOT_SESSION="$(pwd)"
+SESSION_DIR="${REPO_ROOT_SESSION}/.hublaunch/.fix-sessions"
+mkdir -p "$SESSION_DIR"
+
+STARTED_AT=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z" 2>/dev/null || date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+SESSION_FILE="${SESSION_DIR}/issue-${ISSUE_NUMBER}.json"
+SAFE_WT_SESSION=$(json_escape "$WORKTREE_PATH")
+SAFE_BR_SESSION=$(json_escape "$PR_BRANCH")
+printf '{\n  "issueNumber": %s,\n  "worktreePath": "%s",\n  "prBranch": "%s",\n  "startedAt": "%s"\n}\n' \
+  "$ISSUE_NUMBER" "$SAFE_WT_SESSION" "$SAFE_BR_SESSION" "$STARTED_AT" > "$SESSION_FILE"
+
+# ── Output result ─────────────────────────────────────────────────────────────
+
+SAFE_TITLE=$(json_escape "$ISSUE_TITLE")
+SAFE_BRANCH=$(json_escape "$PR_BRANCH")
+SAFE_WORKTREE=$(json_escape "$WORKTREE_PATH")
+SAFE_SESSION=$(json_escape "$SESSION_FILE")
+
+printf '{"status":"success","issueNumber":%s,"issueTitle":"%s","prBranch":"%s","worktreePath":"%s","sessionFile":"%s","worktreeStatus":"%s"}\n' \
+  "$ISSUE_NUMBER" "$SAFE_TITLE" "$SAFE_BRANCH" "$SAFE_WORKTREE" "$SAFE_SESSION" "$WORKTREE_STATUS"

package/dist/templates/scripts/hula-launch-run.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# hula-launch-run.sh — Step 4 of the hula.launch workflow
+# Usage: bash .github/scripts/hula-launch-run.sh <plan-path> <branch-name> [--handoff <username>]
+#
+# Performs: hula launch (which handles plan upload automatically)
+# Outputs structured JSON to stdout; all other output goes to stderr.
+# Exit codes: 0=success, 1=user error, 2=tool error
+
+set -euo pipefail
+
+# ── helpers ────────────────────────────────────────────────────────────────────
+
+json_escape() {
+  printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g; s/$/\\n/g' | tr -d '\n' | sed 's/\\n$//'
+}
+
+die() {
+  local code="$1"; shift
+  local safe_msg
+  safe_msg=$(json_escape "$*")
+  printf '{"status":"error","code":%d,"message":"%s"}\n' "$code" "$safe_msg" >&1
+  exit "$code"
+}
+
+# ── argument parsing ────────────────────────────────────────────────────────────
+
+PLAN_PATH=''
+BRANCH_NAME=''
+HANDOFF=''
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --handoff)
+      HANDOFF="$2"; shift 2 ;;
+    --handoff=*)
+      HANDOFF="${1#--handoff=}"; shift ;;
+    *)
+      if [[ -z "$PLAN_PATH" ]]; then
+        PLAN_PATH="$1"
+      elif [[ -z "$BRANCH_NAME" ]]; then
+        BRANCH_NAME="$1"
+      else
+        die 1 "Unexpected argument: $1"
+      fi
+      shift ;;
+  esac
+done
+
+if [[ -z "$PLAN_PATH" || -z "$BRANCH_NAME" ]]; then
+  die 1 "Usage: bash .github/scripts/hula-launch-run.sh <plan-path> <branch-name> [--handoff <username>]"
+fi
+
+if [[ ! -f "$PLAN_PATH" ]]; then
+  die 1 "Plan file not found: ${PLAN_PATH}"
+fi
+
+# Reject paths with directory traversal sequences
+if printf '%s' "$PLAN_PATH" | grep -q '\.\.'; then
+  die 1 "Invalid plan path (path traversal not allowed): ${PLAN_PATH}"
+fi
+
+# ── Step 4: Run hula launch ─────────────────────────────────────────────────
+
+printf '🚀 Launching issue from plan: %s\n' "$PLAN_PATH" >&2
+
+if [[ -n "$HANDOFF" ]]; then
+  LAUNCH_OUTPUT=$(hula launch "$BRANCH_NAME" "$PLAN_PATH" --handoff "$HANDOFF" 2>&1) \
+    || die 2 "Launch failed: $(json_escape "$LAUNCH_OUTPUT")"
+else
+  LAUNCH_OUTPUT=$(hula launch "$BRANCH_NAME" "$PLAN_PATH" 2>&1) \
+    || die 2 "Launch failed: $(json_escape "$LAUNCH_OUTPUT")"
+fi
+
+# Extract issue number from CLI output (e.g. "Created issue #42" or "issue #42")
+ISSUE_NUMBER=$(printf '%s' "$LAUNCH_OUTPUT" | grep -oE '#[0-9]+' | head -1 | tr -d '#') || true
+
+# ── Output result ─────────────────────────────────────────────────────────────
+
+SAFE_PLAN=$(json_escape "$PLAN_PATH")
+SAFE_BRANCH=$(json_escape "$BRANCH_NAME")
+SAFE_HANDOFF=$(json_escape "$HANDOFF")
+SAFE_OUTPUT=$(json_escape "$LAUNCH_OUTPUT")
+
+printf '{"status":"success","issueNumber":"%s","branchName":"%s","planPath":"%s","handoff":"%s","cliOutput":"%s"}\n' \
+  "${ISSUE_NUMBER:-}" \
+  "$SAFE_BRANCH" \
+  "$SAFE_PLAN" \
+  "$SAFE_HANDOFF" \
+  "$SAFE_OUTPUT"

package/dist/templates/scripts/hula-merge-local.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# hula-merge-local.sh — Path A of the hula.merge workflow (local session merge)
+# Usage: bash .github/scripts/hula-merge-local.sh <issue-number> <worktree-path> <commit-message> [--skip-tests] [--dry-run]
+#
+# Performs: commit + push from worktree → hula merge → remove worktree → delete session file
+# Outputs structured JSON to stdout; all other output goes to stderr.
+# Exit codes: 0=success, 1=user error, 2=tool error
+
+set -euo pipefail
+
+# ── helpers ────────────────────────────────────────────────────────────────────
+
+json_escape() {
+  printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g; s/$/\\n/g' | tr -d '\n' | sed 's/\\n$//'
+}
+
+die() {
+  local code="$1"; shift
+  local safe_msg
+  safe_msg=$(json_escape "$*")
+  printf '{"status":"error","code":%d,"message":"%s"}\n' "$code" "$safe_msg" >&1
+  exit "$code"
+}
+
+# ── argument parsing ────────────────────────────────────────────────────────────
+
+ISSUE_NUMBER=''
+WORKTREE_PATH=''
+COMMIT_MSG=''
+SKIP_TESTS=false
+DRY_RUN=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --skip-tests) SKIP_TESTS=true; shift ;;
+    --dry-run)    DRY_RUN=true;    shift ;;
+    *)
+      if [[ -z "$ISSUE_NUMBER" ]]; then
+        ISSUE_NUMBER="$1"
+      elif [[ -z "$WORKTREE_PATH" ]]; then
+        WORKTREE_PATH="$1"
+      elif [[ -z "$COMMIT_MSG" ]]; then
+        COMMIT_MSG="$1"
+      else
+        die 1 "Unexpected argument: $1"
+      fi
+      shift ;;
+  esac
+done
+
+if [[ -z "$ISSUE_NUMBER" || -z "$WORKTREE_PATH" || -z "$COMMIT_MSG" ]]; then
+  die 1 "Usage: bash .github/scripts/hula-merge-local.sh <issue-number> <worktree-path> <commit-message> [--skip-tests] [--dry-run]"
+fi
+
+if [[ ! -d "$WORKTREE_PATH" ]]; then
+  die 1 "Worktree not found at ${WORKTREE_PATH}."
+fi
+
+# Compute absolute session file path before cd (so it resolves correctly later)
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || REPO_ROOT="$(pwd)"
+SESSION_FILE="${REPO_ROOT}/.hublaunch/.fix-sessions/issue-${ISSUE_NUMBER}.json"
+
+# ── Step A3: Commit and push from worktree ────────────────────────────────────
+
+cd "$WORKTREE_PATH"
+
+PORCELAIN=$(git status --porcelain 2>/dev/null)
+COMMITTED=false
+FILES_CHANGED=0
+
+if [[ -n "$PORCELAIN" ]]; then
+  FILES_CHANGED=$(printf '%s' "$PORCELAIN" | grep -c '' || true)
+
+  if [[ "$DRY_RUN" == false ]]; then
+    git add -A >&2 2>&1 \
+      || die 2 "git add failed in worktree ${WORKTREE_PATH}"
+
+    git commit -m "$COMMIT_MSG" >&2 2>&1 \
+      || die 2 "Failed to commit changes. Ensure git user.name and user.email are configured."
+
+    git push >&2 2>&1 \
+      || die 2 "Push failed. Try: cd ${WORKTREE_PATH} && git push"
+
+    COMMITTED=true
+  else
+    printf '🔍 Dry run: would commit %d file(s) with message: %s\n' "$FILES_CHANGED" "$COMMIT_MSG" >&2
+    COMMITTED=false
+  fi
+else
+  printf 'ℹ️  No changes to commit, proceeding to merge...\n' >&2
+fi
+
+# ── Step A4: Merge the PR ─────────────────────────────────────────────────────
+
+# Return to the main repo root (parent of worktree if possible)
+cd - > /dev/null 2>&1 || true
+
+if [[ "$DRY_RUN" == false ]]; then
+  printf '🔀 Merging PR for issue #%s...\n' "$ISSUE_NUMBER" >&2
+  hula merge "$ISSUE_NUMBER" >&2 2>&1 \
+    || die 2 "Failed to merge PR for issue #${ISSUE_NUMBER}. Session preserved — run /hula-merge again after resolving."
+fi
+
+# ── Step A5: Remove fix worktree ──────────────────────────────────────────────
+
+if [[ "$DRY_RUN" == false ]]; then
+  printf '🧹 Removing fix worktree: %s\n' "$WORKTREE_PATH" >&2
+  git worktree remove "$WORKTREE_PATH" --force >&2 2>&1 \
+    || printf '⚠️  Could not remove worktree at %s (may already be gone)\n' "$WORKTREE_PATH" >&2
+fi
+
+# ── Step A6: Clean up session file ───────────────────────────────────────────
+
+SESSION_CLEANED=false
+
+if [[ -f "$SESSION_FILE" ]]; then
+  if [[ "$DRY_RUN" == false ]]; then
+    rm -f "$SESSION_FILE"
+    SESSION_CLEANED=true
+    printf '🧹 Cleaned up session file\n' >&2
+  else
+    printf '🔍 Dry run: would delete session file %s\n' "$SESSION_FILE" >&2
+  fi
+fi
+
+# ── Output result ─────────────────────────────────────────────────────────────
+
+SAFE_MSG=$(json_escape "$COMMIT_MSG")
+SAFE_PATH=$(json_escape "$WORKTREE_PATH")
+
+printf '{"status":"success","issueNumber":%s,"committed":%s,"filesChanged":%d,"worktreeRemoved":%s,"sessionCleaned":%s,"commitMessage":"%s","worktreePath":"%s"}\n' \
+  "$ISSUE_NUMBER" \
+  "$([ "$COMMITTED" == true ] && echo 'true' || echo 'false')" \
+  "$FILES_CHANGED" \
+  "$([ "$DRY_RUN" == false ] && echo 'true' || echo 'false')" \
+  "$([ "$SESSION_CLEANED" == true ] && echo 'true' || echo 'false')" \
+  "$SAFE_MSG" \
+  "$SAFE_PATH"

package/dist/templates/scripts/hula-merge-remote.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# hula-merge-remote.sh — Path B of the hula.merge workflow (remote-only merge)
+# Usage: bash .github/scripts/hula-merge-remote.sh <issue-number> [--session-path <path>]
+#
+# Merges the PR directly on GitHub, then optionally cleans up a stale session file.
+# Outputs structured JSON to stdout; all other output goes to stderr.
+# Exit codes: 0=success, 1=user error, 2=tool error
+
+set -euo pipefail
+
+# ── helpers ────────────────────────────────────────────────────────────────────
+
+json_escape() {
+  printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g; s/$/\\n/g' | tr -d '\n' | sed 's/\\n$//'
+}
+
+die() {
+  local code="$1"; shift
+  local safe_msg
+  safe_msg=$(json_escape "$*")
+  printf '{"status":"error","code":%d,"message":"%s"}\n' "$code" "$safe_msg" >&1
+  exit "$code"
+}
+
+# ── argument parsing ────────────────────────────────────────────────────────────
+
+ISSUE_NUMBER=''
+SESSION_PATH=''
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --session-path)
+      SESSION_PATH="$2"; shift 2 ;;
+    --session-path=*)
+      SESSION_PATH="${1#--session-path=}"; shift ;;
+    [0-9]*)
+      ISSUE_NUMBER="$1"; shift ;;
+    *)
+      die 1 "Unknown argument: $1" ;;
+  esac
+done
+
+if [[ -z "$ISSUE_NUMBER" ]]; then
+  die 1 "Usage: bash .github/scripts/hula-merge-remote.sh <issue-number> [--session-path <path>]"
+fi
+
+# ── Step B1: Merge the PR via hula CLI ───────────────────────────────────────
+
+printf '🔀 Merging PR for issue #%s (remote-only)...\n' "$ISSUE_NUMBER" >&2
+
+hula merge "$ISSUE_NUMBER" 2>&1 >&2 \
+  || die 2 "Failed to merge PR for issue #${ISSUE_NUMBER}. Check the PR on GitHub."
+
+# ── Step B2: Clean up stale session file (if applicable) ─────────────────────
+
+SESSION_CLEANED=false
+
+# Default session file path if not provided (use absolute path so it works from any CWD)
+if [[ -z "$SESSION_PATH" ]]; then
+  REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || REPO_ROOT="$(pwd)"
+  SESSION_PATH="${REPO_ROOT}/.hublaunch/.fix-sessions/issue-${ISSUE_NUMBER}.json"
+fi
+
+if [[ -f "$SESSION_PATH" ]]; then
+  rm -f "$SESSION_PATH"
+  SESSION_CLEANED=true
+  printf '🧹 Cleaned up stale session file\n' >&2
+fi
+
+# ── Output result ─────────────────────────────────────────────────────────────
+
+printf '{"status":"success","issueNumber":%s,"sessionCleaned":%s}\n' \
+  "$ISSUE_NUMBER" \
+  "$([ "$SESSION_CLEANED" == true ] && echo 'true' || echo 'false')"

package/dist/templates/scripts/hula-read-config.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# hula-read-config.sh — Shared config reader for hula shell scripts
+# Source this file; do NOT execute directly.
+#
+# After sourcing, the following variables are set:
+#   HULA_WORKTREE_BASE_PATH  — absolute resolved worktreeBasePath
+#
+# Reads worktreeBasePath from .hublaunch/hublaunch.config.js.
+# Falls back to ".hula-worktrees" (resolved relative to repo root).
+
+_hula_read_worktree_base_path() {
+  local repo_root
+  repo_root=$(git rev-parse --show-toplevel 2>/dev/null) || {
+    printf 'Warning: could not determine repo root\n' >&2
+    repo_root="$(pwd)"
+  }
+  local config_file="${repo_root}/.hublaunch/hublaunch.config.js"
+  local base_path=""
+
+  if [[ -f "$config_file" ]]; then
+    base_path=$(grep 'worktreeBasePath' "$config_file" \
+      | grep -v '^\s*//' \
+      | sed "s/.*worktreeBasePath[^'\"]*['\"]\\([^'\"]*\\)['\"].*/\\1/" \
+      | head -1) || true
+  fi
+
+  # Default to .hula-worktrees if not found or empty
+  base_path="${base_path:-.hula-worktrees}"
+
+  # Resolve relative paths against repo root
+  if [[ "$base_path" != /* ]]; then
+    base_path="${repo_root}/${base_path}"
+  fi
+
+  printf '%s' "$base_path"
+}
+
+HULA_WORKTREE_BASE_PATH=$(_hula_read_worktree_base_path)

package/dist/templates/scripts/hula-verify-gather.sh

@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+# hula-verify-gather.sh — Steps 2-5 of the hula.verify workflow
+# Usage: bash .github/scripts/hula-verify-gather.sh <issue-number>
+#
+# Fetches issue details, finds associated PR, gathers PR files and diff.
+# Outputs structured JSON to stdout; all other output goes to stderr.
+# Exit codes: 0=success, 1=user error, 2=tool error
+
+set -euo pipefail
+
+# ── helpers ────────────────────────────────────────────────────────────────────
+
+json_escape() {
+  printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g; s/$/\\n/g' | tr -d '\n' | sed 's/\\n$//'
+}
+
+die() {
+  local code="$1"; shift
+  local safe_msg
+  safe_msg=$(json_escape "$*")
+  printf '{"status":"error","code":%d,"message":"%s"}\n' "$code" "$safe_msg" >&1
+  exit "$code"
+}
+
+# ── argument parsing ────────────────────────────────────────────────────────────
+
+ISSUE_NUMBER=''
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    [0-9]*)
+      ISSUE_NUMBER="$1"; shift ;;
+    *)
+      die 1 "Unknown argument: $1" ;;
+  esac
+done
+
+if [[ -z "$ISSUE_NUMBER" ]]; then
+  die 1 "Usage: bash .github/scripts/hula-verify-gather.sh <issue-number>"
+fi
+
+# ── Step 2: Fetch issue details ────────────────────────────────────────────────
+
+printf '🔍 Fetching issue #%s...\n' "$ISSUE_NUMBER" >&2
+
+ISSUE_JSON=$(gh issue view "$ISSUE_NUMBER" --json title,body,number,url,state 2>/dev/null) \
+  || die 1 "Issue #${ISSUE_NUMBER} not found or not accessible."
+
+ISSUE_TITLE=$(printf '%s' "$ISSUE_JSON" | grep -o '"title":"[^"]*"' | head -1 | sed 's/"title":"//;s/"$//')
+ISSUE_STATE=$(printf '%s' "$ISSUE_JSON" | grep -o '"state":"[^"]*"' | head -1 | sed 's/"state":"//;s/"$//')
+ISSUE_URL=$(printf '%s' "$ISSUE_JSON" | grep -o '"url":"[^"]*"' | head -1 | sed 's/"url":"//;s/"$//')
+
+# ── Step 3: Find associated PR ────────────────────────────────────────────────
+
+printf '🔗 Looking for PR linked to issue #%s...\n' "$ISSUE_NUMBER" >&2
+
+# Try linked search first (works when PR is formally linked via GitHub)
+PR_NUMBER=$(gh pr list --search "linked:${ISSUE_NUMBER}" --json number -q '.[0].number' 2>/dev/null) || true
+
+if [[ -z "$PR_NUMBER" ]]; then
+  # Fallback: search PR bodies for issue references
+  # Handles both short format (#N) and full-path format (owner/repo#N)
+  # Uses gh's built-in jq (-q) — no external jq required
+  JQ_EXPR='.[] | select(.body != null) | select(.body | test("(Fixes|Closes|Resolves)[ ]+([A-Za-z0-9._-]+/[A-Za-z0-9._-]+)?#'"${ISSUE_NUMBER}"'([^0-9]|$)|(^|[^0-9])#'"${ISSUE_NUMBER}"'([^0-9]|$)"; "i")) | .number'
+  PR_NUMBER=$(gh pr list --json number,body --limit 100 -q "$JQ_EXPR" 2>/dev/null | head -1) || true
+fi
+
+if [[ -z "$PR_NUMBER" ]]; then
+  die 1 "No PR found for issue #${ISSUE_NUMBER}. The implementation may not have started yet."
+fi
+
+# Fetch full PR details via pr view (reliable single-object JSON)
+PR_DETAILS=$(gh pr view "$PR_NUMBER" --json number,title,url,state,headRefName,isDraft 2>/dev/null) \
+  || die 2 "Failed to fetch details for PR #${PR_NUMBER}."
+
+PR_TITLE=$(printf '%s' "$PR_DETAILS" | grep -o '"title":"[^"]*"' | head -1 | sed 's/"title":"//;s/"$//')
+PR_URL=$(printf '%s' "$PR_DETAILS" | grep -o '"url":"[^"]*"' | head -1 | sed 's/"url":"//;s/"$//')
+PR_STATE=$(printf '%s' "$PR_DETAILS" | grep -o '"state":"[^"]*"' | head -1 | sed 's/"state":"//;s/"$//')
+PR_BRANCH=$(printf '%s' "$PR_DETAILS" | grep -o '"headRefName":"[^"]*"' | head -1 | sed 's/"headRefName":"//;s/"$//')
+PR_DRAFT=$(printf '%s' "$PR_DETAILS" | grep -o '"isDraft":[a-z]*' | head -1 | sed 's/"isDraft"://')
+
+# ── Step 4: Fetch PR file changes ─────────────────────────────────────────────
+
+printf '📊 Fetching changed files for PR #%s...\n' "$PR_NUMBER" >&2
+
+PR_FILES_JSON=$(gh pr view "$PR_NUMBER" --json files,additions,deletions 2>/dev/null) \
+  || die 2 "Failed to fetch PR files for PR #${PR_NUMBER}."
+
+TOTAL_ADDITIONS=$(printf '%s' "$PR_FILES_JSON" | grep -o '"additions":[0-9]*' | tail -1 | sed 's/"additions"://')
+TOTAL_DELETIONS=$(printf '%s' "$PR_FILES_JSON" | grep -o '"deletions":[0-9]*' | tail -1 | sed 's/"deletions"://')
+
+# Count files by category (rough heuristic)
+FILES_LIST=$(printf '%s' "$PR_FILES_JSON" | grep -o '"path":"[^"]*"' | sed 's/"path":"//;s/"$//')
+
+CODE_COUNT=0
+TEST_COUNT=0
+DOC_COUNT=0
+CONFIG_COUNT=0
+TOTAL_COUNT=0
+
+while IFS= read -r fpath; do
+  [[ -z "$fpath" ]] && continue
+  TOTAL_COUNT=$((TOTAL_COUNT + 1))
+  case "$fpath" in
+    *.test.*|*.spec.*|*/__tests__/*|*/test/*|*/tests/*) TEST_COUNT=$((TEST_COUNT + 1)) ;;
+    *.md|docs/*|README*|CHANGELOG*|DOCUMENTATION*) DOC_COUNT=$((DOC_COUNT + 1)) ;;
+    package.json|package-lock.json|tsconfig*|*.config.*|*.json|*.yaml|*.yml) CONFIG_COUNT=$((CONFIG_COUNT + 1)) ;;
+    *) CODE_COUNT=$((CODE_COUNT + 1)) ;;
+  esac
+done <<< "$FILES_LIST"
+
+# ── Step 5: Fetch PR diff ─────────────────────────────────────────────────────
+
+printf '📄 Fetching PR diff...\n' >&2
+
+DIFF_FILE="/tmp/hula-verify-diff-${PR_NUMBER}.patch"
+gh pr diff "$PR_NUMBER" > "$DIFF_FILE" 2>/dev/null \
+  || printf '⚠️  Could not fetch PR diff (PR may be too large or not accessible)\n' >&2
+
+# ── Output result ─────────────────────────────────────────────────────────────
+
+SAFE_ISSUE_TITLE=$(json_escape "$ISSUE_TITLE")
+SAFE_PR_TITLE=$(json_escape "$PR_TITLE")
+SAFE_PR_URL=$(json_escape "$PR_URL")
+SAFE_ISSUE_URL=$(json_escape "$ISSUE_URL")
+SAFE_PR_BRANCH=$(json_escape "$PR_BRANCH")
+SAFE_DIFF_FILE=$(json_escape "$DIFF_FILE")
+PR_DRAFT_VAL="${PR_DRAFT:-false}"
+
+printf '{"status":"success","issueNumber":%s,"issueTitle":"%s","issueState":"%s","issueUrl":"%s","prNumber":%s,"prTitle":"%s","prUrl":"%s","prState":"%s","prBranch":"%s","prIsDraft":%s,"diffFile":"%s","filesChanged":{"total":%d,"code":%d,"test":%d,"doc":%d,"config":%d},"lines":{"additions":%s,"deletions":%s}}\n' \
+  "$ISSUE_NUMBER" "$SAFE_ISSUE_TITLE" "$ISSUE_STATE" "$SAFE_ISSUE_URL" \
+  "$PR_NUMBER" "$SAFE_PR_TITLE" "$SAFE_PR_URL" "$PR_STATE" "$SAFE_PR_BRANCH" "$PR_DRAFT_VAL" \
+  "$SAFE_DIFF_FILE" \
+  "$TOTAL_COUNT" "$CODE_COUNT" "$TEST_COUNT" "$DOC_COUNT" "$CONFIG_COUNT" \
+  "${TOTAL_ADDITIONS:-0}" "${TOTAL_DELETIONS:-0}"