feat(skill): add /resolve skill for context-aware conflict resolution (#1524)

* feat(skill): add /resolve skill for context-aware conflict resolution

* fix(skill/resolve): dynamic repo detection, safe temp names, merge guard, lint portability (#1524)

Author: carlos-alm

.claude/skills/resolve/SKILL.md

@@ -48,8 +48,27 @@ if ! echo "$PR_NUMBER" | grep -qE '^[0-9]+$'; then
   exit 1
 fi
 
+# Guard against a previously aborted merge left in place — if MERGE_HEAD exists but
+# .codegraph/resolve/ was already cleaned, the next `git merge` call would fail immediately.
+if git rev-parse --verify MERGE_HEAD > /dev/null 2>&1; then
+  echo "ERROR: An in-progress merge (MERGE_HEAD) already exists."
+  echo "Run: git merge --abort && rm -rf .codegraph/resolve"
+  echo "Then re-run /resolve $PR_NUMBER"
+  exit 1
+fi
+
+# Detect repo slug dynamically so the skill works in any fork or renamed org
+REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null \
+  || git remote get-url origin | sed -E 's|.*github\.com[:/](.+)(\.git)?$|\1|')
+if [ -z "$REPO" ]; then
+  echo "ERROR: could not detect GitHub repo slug — ensure 'gh' is authenticated or 'origin' points to GitHub"
+  exit 1
+fi
+echo "Detected repo: $REPO"
+
 # Verify PR exists and is open
-gh pr view "$PR_NUMBER" --repo optave/codegraph --json number,state,headRefName,baseRefName \
+gh pr view "$PR_NUMBER" --repo "$REPO" --json number,state,headRefName,baseRefName \
+
   --jq '"PR #\(.number) [\(.state)] \(.headRefName) → \(.baseRefName)"' \
   || { echo "ERROR: PR #$PR_NUMBER not found or inaccessible"; exit 1; }
 ```
@@ -58,18 +77,36 @@ Persist PR metadata for use in later phases (shell variables don't survive acros
 
 ```bash
 PR_NUMBER=$(echo "${ARGUMENTS:-}" | tr -d '[:space:]#')
+REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null \
+  || git remote get-url origin | sed -E 's|.*github\.com[:/](.+)(\.git)?$|\1|')
 mkdir -p .codegraph/resolve
-gh pr view "$PR_NUMBER" --repo optave/codegraph \
+# Trap ensures .codegraph/resolve/ is always cleaned up on non-zero exit, even after a crash.
+# This prevents stale state from corrupting a future re-run (Phase 1 reads head-branch / base-branch
+# from here, and an aborted merge would see stale values).
+trap 'rm -rf .codegraph/resolve' ERR
+echo "$REPO" > .codegraph/resolve/repo
+gh pr view "$PR_NUMBER" --repo "$REPO" \
+
   --json number,headRefName,baseRefName,title,body \
   > .codegraph/resolve/pr-meta.json \
   || { echo "ERROR: failed to fetch PR #$PR_NUMBER metadata"; exit 1; }
 jq -r '.headRefName' .codegraph/resolve/pr-meta.json > .codegraph/resolve/head-branch
 jq -r '.baseRefName' .codegraph/resolve/pr-meta.json > .codegraph/resolve/base-branch
 echo "$PR_NUMBER" > .codegraph/resolve/pr-number
+
+HEAD_BRANCH=$(cat .codegraph/resolve/head-branch)
+BASE_BRANCH=$(cat .codegraph/resolve/base-branch)
+if [ "$HEAD_BRANCH" = "$BASE_BRANCH" ]; then
+  echo "ERROR: PR head and base are the same branch ($HEAD_BRANCH) — nothing to merge"
+  rm -rf .codegraph/resolve
+  exit 1
+fi
+
 echo "Pre-flight passed. PR: $(jq -r '.title' .codegraph/resolve/pr-meta.json)"
 ```
 
-**Exit condition:** Git repo confirmed, `gh` and `jq` available, PR exists, metadata written to `.codegraph/resolve/`.
+**Exit condition:** Git repo confirmed, `gh` and `jq` available, repo slug detected, PR exists, metadata written to `.codegraph/resolve/`.
+
 
 ---
 
@@ -81,9 +118,11 @@ Check out the PR branch and run `git merge` to surface all conflicts.
 HEAD_BRANCH=$(cat .codegraph/resolve/head-branch)
 BASE_BRANCH=$(cat .codegraph/resolve/base-branch)
 PR_NUMBER=$(cat .codegraph/resolve/pr-number)
+REPO=$(cat .codegraph/resolve/repo)
 
 echo "Checking out PR branch: $HEAD_BRANCH"
-gh pr checkout "$PR_NUMBER" --repo optave/codegraph \
+gh pr checkout "$PR_NUMBER" --repo "$REPO" \
+
   || { echo "ERROR: failed to check out PR #$PR_NUMBER"; exit 1; }
 
 echo "Fetching latest origin/$BASE_BRANCH..."
@@ -141,6 +180,13 @@ For each conflicting file, identify **which commits and PRs on the base branch**
 BASE_BRANCH=$(cat .codegraph/resolve/base-branch)
 ORIG_HEAD=$(cat .codegraph/resolve/orig-head)
 MERGE_HEAD=$(cat .codegraph/resolve/merge-head)
+REPO=$(cat .codegraph/resolve/repo)
+
+# file_key: collision-resistant short name derived from file path
+# Uses printf+sha1sum to handle paths with underscores (src/foo_bar.ts and src/foo/bar.ts
+# both become different keys, unlike tr '/' '_')
+file_key() { printf '%s' "$1" | sha1sum | cut -c1-16; }
+
 
 # Find all commits that came in from the base branch and touched conflicting files
 mkdir -p .codegraph/resolve/incoming-prs
@@ -151,28 +197,36 @@ i=0
 while IFS= read -r FILE; do
   i=$((i + 1))
   echo "[$i/$TOTAL] Tracing incoming changes: $FILE"
+  KEY=$(file_key "$FILE")
+
 
   # Commits from origin/<base> that are not yet in the PR branch (what came in from main)
   # 2>/dev/null: suppress git's "unknown revision" if ORIG_HEAD or MERGE_HEAD are temporarily unavailable — the empty file case is handled below
   git log --oneline "$ORIG_HEAD..$MERGE_HEAD" -- "$FILE" \
-    > ".codegraph/resolve/incoming-commits-$(echo "$FILE" | tr '/' '_').txt" 2>/dev/null || true
+    > ".codegraph/resolve/incoming-commits-$KEY.txt" 2>/dev/null || true
 
-  if [ ! -s ".codegraph/resolve/incoming-commits-$(echo "$FILE" | tr '/' '_').txt" ]; then
+  if [ ! -s ".codegraph/resolve/incoming-commits-$KEY.txt" ]; then
     echo "  (no direct commit history for $FILE on incoming side — likely an add/add conflict)"
   else
     echo "  Incoming commits touching $FILE:"
-    cat ".codegraph/resolve/incoming-commits-$(echo "$FILE" | tr '/' '_').txt"
+    cat ".codegraph/resolve/incoming-commits-$KEY.txt"
+
   fi
 done < .codegraph/resolve/conflicting-files.txt
 ```
 
 For each incoming commit, find the PR that introduced it:
 
 ```bash
+REPO=$(cat .codegraph/resolve/repo)
 mkdir -p .codegraph/resolve/source-prs
 
+file_key() { printf '%s' "$1" | sha1sum | cut -c1-16; }
+
 while IFS= read -r FILE; do
-  COMMIT_FILE=".codegraph/resolve/incoming-commits-$(echo "$FILE" | tr '/' '_').txt"
+  KEY=$(file_key "$FILE")
+  COMMIT_FILE=".codegraph/resolve/incoming-commits-$KEY.txt"
+
   [ -f "$COMMIT_FILE" ] || continue
 
   while IFS= read -r COMMIT_LINE; do
@@ -188,7 +242,8 @@ while IFS= read -r FILE; do
     echo "Looking up PR for commit $SHA..."
     # gh api returns empty array if commit is not associated with a PR
     # 2>/dev/null: suppress gh's "HTTP 422" or network error output — the || clause writes an empty array so later steps handle it gracefully
-    gh api "repos/optave/codegraph/commits/$SHA/pulls" \
+    gh api "repos/$REPO/commits/$SHA/pulls" \
+
       --jq '[.[] | {number: .number, title: .title, body: .body, state: .state}]' \
       > "$PR_FILE" 2>/dev/null || echo '[]' > "$PR_FILE"
 
@@ -205,6 +260,8 @@ done < .codegraph/resolve/conflicting-files.txt
 Fetch full descriptions and diffs for each source PR:
 
 ```bash
+REPO=$(cat .codegraph/resolve/repo)
+
 mkdir -p .codegraph/resolve/source-pr-diffs
 
 for PR_FILE in .codegraph/resolve/source-prs/*.json; do
@@ -220,7 +277,8 @@ for PR_FILE in .codegraph/resolve/source-prs/*.json; do
     if [ ! -f "$META_FILE" ]; then
       echo "Fetching source PR #$SOURCE_PR description..."
       # 2>/dev/null: suppress gh's auth/network error text — the || clause writes a stub so the skill continues gracefully
-      gh pr view "$SOURCE_PR" --repo optave/codegraph \
+      gh pr view "$SOURCE_PR" --repo "$REPO" \
+
         --json number,title,body,baseRefName,headRefName \
         > "$META_FILE" 2>/dev/null \
         || { echo "WARN: could not fetch PR #$SOURCE_PR metadata — skipping"; echo '{}' > "$META_FILE"; }
@@ -229,7 +287,8 @@ for PR_FILE in .codegraph/resolve/source-prs/*.json; do
     if [ ! -f "$DIFF_FILE" ]; then
       echo "Fetching source PR #$SOURCE_PR diff..."
       # 2>/dev/null: suppress gh's auth/network error text — the || clause creates an empty file so the skill continues gracefully
-      gh pr diff "$SOURCE_PR" --repo optave/codegraph \
+      gh pr diff "$SOURCE_PR" --repo "$REPO" \
+
         > "$DIFF_FILE" 2>/dev/null \
         || { echo "WARN: could not fetch PR #$SOURCE_PR diff — skipping"; touch "$DIFF_FILE"; }
     fi
@@ -309,6 +368,9 @@ MERGE_HEAD=$(cat .codegraph/resolve/merge-head)
 TOTAL=$(wc -l < .codegraph/resolve/conflicting-files.txt | tr -d '[:space:]')
 i=0
 
+file_key() { printf '%s' "$1" | sha1sum | cut -c1-16; }
+
+
 while IFS= read -r FILE; do
   i=$((i + 1))
   echo "=== [$i/$TOTAL] Resolving: $FILE ==="
@@ -329,7 +391,9 @@ while IFS= read -r FILE; do
   echo ""
   echo "--- Source PR context for $FILE ---"
   # Show which source PRs touched this file (from Phase: Conflict Archaeology)
-  COMMIT_FILE=".codegraph/resolve/incoming-commits-$(echo "$FILE" | tr '/' '_').txt"
+  KEY=$(file_key "$FILE")
+  COMMIT_FILE=".codegraph/resolve/incoming-commits-$KEY.txt"
+
   if [ -s "$COMMIT_FILE" ]; then
     while IFS= read -r COMMIT_LINE; do
       SHA=$(echo "$COMMIT_LINE" | awk '{print $1}')
@@ -435,31 +499,41 @@ Run tests and lint to confirm the resolution didn't break anything.
 
 ```bash
 echo "=== Detecting test runner ==="
-if [ -f "pnpm-lock.yaml" ]; then TEST_CMD="pnpm test"
+if [ -f "pnpm-lock.yaml" ] && command -v pnpm > /dev/null 2>&1; then TEST_CMD="pnpm test"
+elif [ -f "pnpm-lock.yaml" ]; then TEST_CMD="npx pnpm test"
+
 elif [ -f "yarn.lock" ] && command -v yarn > /dev/null 2>&1; then TEST_CMD="yarn test"
 elif [ -f "package.json" ]; then TEST_CMD="npm test"
 else
   echo "WARN: No recognised test runner found — skipping tests"
-  TEST_CMD="true"
+  TEST_CMD=""
 fi
-echo "Running: $TEST_CMD"
-$TEST_CMD || { echo "ERROR: tests failed after conflict resolution — fix before committing"; exit 1; }
+if [ -n "$TEST_CMD" ]; then
+  echo "Running: $TEST_CMD"
+  eval "$TEST_CMD" || { echo "ERROR: tests failed after conflict resolution — fix before committing"; exit 1; }
+fi
+
 ```
 
 ```bash
 echo "=== Detecting lint runner ==="
 if [ -f "biome.json" ] && command -v npx > /dev/null 2>&1; then
-  LINT_CMD="npx biome check --reporter=summary src/ tests/"
-elif find . -maxdepth 1 -name "eslint.config.*" | grep -q .; then
+  # Point biome at . and let biome.json's files.include/files.ignore govern scope
+  LINT_CMD="npx biome check --reporter=summary ."
+elif ls eslint.config.* > /dev/null 2>&1; then
+
   LINT_CMD="npx eslint ."
 elif [ -f "package.json" ] && grep -q '"lint"' package.json; then
   LINT_CMD="npm run lint"
 else
   echo "WARN: No recognised lint runner found — skipping lint"
-  LINT_CMD="true"
+  LINT_CMD=""
+fi
+if [ -n "$LINT_CMD" ]; then
+  echo "Running: $LINT_CMD"
+  eval "$LINT_CMD" || { echo "ERROR: lint failed after conflict resolution — fix before committing"; exit 1; }
 fi
-echo "Running: $LINT_CMD"
-$LINT_CMD || { echo "ERROR: lint failed after conflict resolution — fix before committing"; exit 1; }
+
 ```
 
 **Exit condition:** Tests and lint pass (or were not applicable). No new failures introduced by the resolution.
@@ -524,4 +598,5 @@ echo "Conflict resolution complete."
 - **Run tests and lint before pushing.** A clean merge that breaks tests is not ready to push.
 - **No co-author lines** in commit messages.
 - **No Claude Code references** in commit messages or comments.
-- **Cleanup:** `.codegraph/resolve/` is created during the skill and removed after a successful push. If the skill exits early (due to ambiguity or error), remove it with `rm -rf .codegraph/resolve` before re-running.
+- **Cleanup:** `.codegraph/resolve/` is created during the skill, removed automatically on any error exit (via `trap`), and removed after a successful push. If a crash left both `.codegraph/resolve/` stale **and** an in-progress merge (MERGE_HEAD), run `git merge --abort && rm -rf .codegraph/resolve` before re-running — Phase 0 will detect the leftover MERGE_HEAD and remind you.
+