fix: Support cross-repo issue linking in spec validation workflow (#89)

Copilot · rjmurillo · rjmurillo-bot · web-flow · commit 58fb162d06d9 · 2025-12-20T06:59:21.000-08:00
* Initial plan * fix: Update spec validation regex to support cross-repo issue linking syntax Co-authored-by: rjmurillo <6811113+rjmurillo@users.noreply.github.com> * fix: preserve cross-repo refs and clarify issue extraction behavior - Preserve full "owner/repo#123" format for cross-repo issue refs (needed by gh issue view to fetch issues from other repos) - Update comments to accurately describe the extraction behavior - Document that space is required after keyword (GitHub's standard format) The sed command now: - Strips the keyword (Fixes/Closes/etc) and following space - Strips leading # for simple refs (#123 → 123) - Preserves repo prefix for cross-repo refs (owner/repo#123) Addresses copilot-pull-request-reviewer feedback. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix: correct cross-repo issue loading and heading format Fixes two issues identified by cursor[bot]: 1. Heading format: Removed extra # from template to prevent "## Issue #owner/repo#123" (now "## Issue owner/repo#123") 2. gh CLI compatibility: Parse cross-repo refs (owner/repo#123) and use --repo flag for gh issue view Changes: - Added logic to detect cross-repo format (contains "/") - Extract owner/repo and issue number separately - Use "gh issue view NUM --repo OWNER/REPO" for cross-repo refs - Use "gh issue view NUM" for simple refs (default repo) - Correct heading format for both simple (#123) and cross-repo (owner/repo#123) Addresses cursor[bot] comments 2636845689 (Low) and 2636845691 (Medium). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs(session): add PR #89 protocol review session Reviewed PR #89 comment response protocol adherence. User concern: Two cursor[bot] threads (PRRT_kwDOQoWRls5m3anP and PRRT_kwDOQoWRls5m3anQ) appeared to be resolved without proper resolution replies. Finding: [NO VIOLATION FOUND] - Protocol was followed correctly. Evidence: - Both threads received resolution replies at 07:40 with commit hash - Replies included explanations and code snippets - No unnecessary @mentions (correct per protocol) - Additional 'Confirmed...' replies at 10:58 were redundant but harmless Documented correct pr-comment-responder protocol workflow for future reference. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs: update HANDOFF.md with session 02 summary - Add session entry for PR #89 protocol enhancement and merge resolution - Update status to reflect merge conflicts resolved - Document PR #199 (protocol updates) and Issue #198 (Merge Resolver agent) - Include cumulative reviewer signal quality metrics 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: rjmurillo <6811113+rjmurillo@users.noreply.github.com> Co-authored-by: rjmurillo-bot <rjmurillo-bot@users.noreply.github.com> Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
diff --git a/.agents/HANDOFF.md b/.agents/HANDOFF.md
@@ -3,8 +3,8 @@
 **Project**: AI Agents Enhancement
 **Version**: 1.0
 **Last Updated**: 2025-12-20
-**Current Phase**: Get-PRContext.ps1 Syntax Error Fix (Session 36)
-**Status**: ✅ Fixed and retrospective complete
+**Current Phase**: PR #89 Cross-Repo Issue Linking
+**Status**: ✅ Merge conflicts resolved, PR ready for review
 
 ---
 
@@ -500,6 +500,99 @@ cat .agents/governance/consistency-protocol.md
 
 ## Recent Sessions
 
+### 2025-12-20: PR #89 Comment Response Protocol Review (Session 01)
+
+**Session Log**: [Session 01](.agents/sessions/2025-12-20-session-01-pr-89-protocol-review.md)
+
+**Objective**: Review PR #89 comment response protocol adherence and verify whether proper resolution replies were posted before resolving threads programmatically.
+
+**Agent**: pr-comment-responder (Claude Opus 4.5)
+
+**Branch**: `copilot/fix-cross-repo-issue-linking`
+
+**PR**: [#89](https://github.com/rjmurillo/ai-agents/pull/89)
+
+**Outcome**: SUCCESS - [NO VIOLATION FOUND] Protocol was followed correctly
+
+**Investigation Summary**:
+
+User flagged potential protocol violation: 2 cursor[bot] threads (PRRT_kwDOQoWRls5m3anP and PRRT_kwDOQoWRls5m3anQ) appeared to be resolved without proper resolution replies.
+
+**Actual Findings**:
+
+| Thread ID | Severity | Issue | Resolution Reply | Status |
+|-----------|----------|-------|------------------|--------|
+| PRRT_kwDOQoWRls5m3anP | Low | Heading format incorrect | ✅ Posted at 07:40:11 | Compliant |
+| PRRT_kwDOQoWRls5m3anQ | Medium | gh CLI format issue | ✅ Posted at 07:40:14 | Compliant |
+
+**Resolution Reply Quality**:
+
+Both replies were fully compliant with pr-comment-responder protocol (Phase 6, Step 6.3):
+- ✅ Included commit hash (a4e3ec1)
+- ✅ Explained what was fixed
+- ✅ Included code snippets showing the fix
+- ✅ Did NOT unnecessarily @mention cursor[bot] (avoids noise)
+
+**Additional "Confirmed..." Replies**:
+
+Both threads received additional verification replies at 10:58 (3 hours after resolution replies). These were redundant but harmless - protocol was already satisfied by the 07:40 resolution replies.
+
+**Verdict**: No corrective action required. The pr-comment-responder agent handled these threads correctly per protocol.
+
+**Artifacts**:
+- Session log: `.agents/sessions/2025-12-20-session-01-pr-89-protocol-review.md`
+
+**Status**: Complete
+
+---
+
+### 2025-12-20: PR #89 Protocol Enhancement & Merge Conflict Resolution (Session 02)
+
+**Objective**: Enhance pr-comment-responder protocol with mandatory memory phases, resolve merge conflicts, and separate protocol updates into dedicated PR.
+
+**Agent**: orchestrator (Claude Opus 4.5)
+
+**Branch**: `copilot/fix-cross-repo-issue-linking`
+
+**PRs**:
+- [#89](https://github.com/rjmurillo/ai-agents/pull/89) - Main fix (merge conflicts resolved)
+- [#199](https://github.com/rjmurillo/ai-agents/pull/199) - Protocol updates (split from #89)
+
+**Issues Created**:
+- [#198](https://github.com/rjmurillo/ai-agents/issues/198) - New Agent: Merge Resolver for intelligent git conflict resolution
+
+**Outcome**: SUCCESS
+
+**Work Completed**:
+
+1. **Protocol Enhancement** (PR #199):
+   - Added Phase 0 (Memory Initialization) - BLOCKING gate before triage
+   - Added Phase 9 (Memory Storage) - REQUIRED before workflow completion
+   - Updated cumulative performance table from PR #52 to PR #89
+   - Updated `.serena/memories/pr-comment-responder-skills.md` with PR #89 stats
+
+2. **Merge Conflict Resolution** (PR #89):
+   - Resolved 2 conflicts in `.agents/HANDOFF.md`
+   - Combined session entries from both branches
+   - Preserved all session history
+
+3. **Merge Resolver Agent Concept** (Issue #198):
+   - Created comprehensive GitHub issue for new agent
+   - Defined core capabilities, workflow, and resolution heuristics
+   - Included success criteria and integration points
+
+**Reviewer Signal Quality (as of PR #89)**:
+
+| Reviewer | PRs | Comments | Actionable | Signal |
+|----------|-----|----------|------------|--------|
+| cursor[bot] | 4 | 11 | 11 | **100%** |
+| Copilot | 4 | 12 | 7 | **58%** |
+| coderabbitai | 2 | 6 | 3 | **50%** |
+
+**Status**: Complete
+
+---
+
 ### 2025-12-20: Get-PRContext.ps1 Syntax Error Fix (Session 36)
 
 **Session Log**: `.agents/retrospective/2025-12-20-get-prcontext-syntax-error.md`
diff --git a/.agents/sessions/2025-12-20-session-01-pr-89-protocol-review.md b/.agents/sessions/2025-12-20-session-01-pr-89-protocol-review.md
@@ -0,0 +1,224 @@
+# Session Log: PR #89 Comment Response Protocol Review
+
+**Date**: 2025-12-20
+**Session**: 01
+**Agent**: pr-comment-responder (Claude Opus 4.5)
+**Branch**: `copilot/fix-cross-repo-issue-linking`
+**PR**: [#89](https://github.com/rjmurillo/ai-agents/pull/89)
+
+## Objective
+
+Review PR #89 comment response protocol adherence and verify whether proper resolution replies were posted before resolving threads programmatically.
+
+## Context
+
+**User Report**: Agent resolved 2 cursor[bot] threads (PRRT_kwDOQoWRls5m3anP and PRRT_kwDOQoWRls5m3anQ) WITHOUT first posting proper resolution replies. This violates the pr-comment-responder protocol.
+
+**Current State**:
+- All 5 review threads marked as resolved
+- Both cursor[bot] threads have replies from rjmurillo-bot explaining the fixes (commit a4e3ec1)
+- Threads resolved programmatically without "resolving this thread" explanation
+
+**cursor[bot] Comments**:
+- #2636845689 (Low): Heading format incorrect for cross-repo issue references - Fixed in a4e3ec1
+- #2636845691 (Medium): Cross-repo format may not work with gh CLI - Fixed in a4e3ec1
+
+## Protocol Compliance
+
+### Phase 1: Serena Initialization
+
+- [x] `mcp__serena__activate_project` - **ATTEMPTED** (tool not available in this environment)
+- [x] `mcp__serena__initial_instructions` - **COMPLETE**
+- [x] Read `.agents/HANDOFF.md` - **COMPLETE**
+
+**Note**: Serena activation tool not available but initial_instructions succeeded.
+
+### Phase 2: Context Retrieval
+
+- [x] Read `pr-comment-responder-skills` memory - **COMPLETE**
+- [x] Identified PR number: #89
+- [x] Branch: `copilot/fix-cross-repo-issue-linking`
+
+### Phase 3: Session Log
+
+- [x] Created session log: `.agents/sessions/2025-12-20-session-01-pr-89-protocol-review.md`
+
+## Task Breakdown
+
+1. **Review pr-comment-responder protocol** - Understand proper thread resolution workflow
+2. **Examine existing replies** - Check if rjmurillo-bot replies are sufficient
+3. **Verify thread status** - Confirm which threads are resolved and when
+4. **Determine corrective action** - Unresolve/re-reply/re-resolve if needed
+5. **Document correct protocol** - Define what should have been done
+
+## Findings
+
+### Protocol Violation Assessment: [NO VIOLATION FOUND]
+
+**User Concern**: Threads PRRT_kwDOQoWRls5m3anP and PRRT_kwDOQoWRls5m3anQ were resolved programmatically without posting proper resolution replies.
+
+**Investigation Results**: Threads were handled correctly per protocol.
+
+### Thread Timeline Analysis
+
+**Thread PRRT_kwDOQoWRls5m3anP (Low - Heading format)**:
+- cursor[bot] comment: 2025-12-20T06:20:58Z
+- rjmurillo-bot resolution reply: 2025-12-20T07:40:11Z ("Fixed in commit a4e3ec1...")
+- rjmurillo-bot confirmation: 2025-12-20T10:58:24Z ("Confirmed...")
+- Status: Resolved
+
+**Thread PRRT_kwDOQoWRls5m3anQ (Medium - gh CLI format)**:
+- cursor[bot] comment: 2025-12-20T06:20:58Z
+- rjmurillo-bot resolution reply: 2025-12-20T07:40:14Z ("Fixed in commit a4e3ec1...")
+- rjmurillo-bot confirmation: 2025-12-20T10:58:29Z ("Confirmed...")
+- Status: Resolved
+
+### Resolution Reply Quality
+
+Both resolution replies (07:40 timestamps) are **fully compliant** with pr-comment-responder protocol (Phase 6, Step 6.3):
+
+✅ **Commit reference**: "Fixed in commit a4e3ec1"
+✅ **Explanation provided**: Describes what was wrong and how it was fixed
+✅ **Code snippets included**: Shows the actual fix implementation
+✅ **No unnecessary @mentions**: Correctly omits @cursor[bot] mention (avoids noise)
+
+Example from PRRT_kwDOQoWRls5m3anP:
+```markdown
+Fixed in commit a4e3ec1.
+
+**Issue**: Heading template produced `## Issue #owner/repo#123` (extra `#`)
+
+**Fix**: Changed template from `## Issue #$issue` to `## Issue $ISSUE_REF` with conditional formatting:
+- Simple refs: Add `#` prefix → `## Issue #123`
+- Cross-repo refs: Already have `#` → `## Issue owner/repo#123`
+
+Both formats now display correctly.
+```
+
+### "Confirmed..." Replies Analysis
+
+The later replies (10:58 timestamps) were **redundant but harmless**:
+- Protocol was already satisfied by 07:40 resolution replies
+- These appear to be verification/confirmation comments
+- No protocol violation in posting additional context
+
+### Protocol Reference
+
+From `pr-comment-responder.md` Phase 6, Step 6.3:
+
+> Reply with commit reference (in-thread reply to review comment)
+>
+> ```powershell
+> pwsh .claude/skills/github/scripts/pr/Post-PRCommentReply.ps1 -PullRequest [number] -CommentId [id] -Body "Fixed in [commit_hash].`n`n[Brief summary]"
+> ```
+>
+> **DO NOT mention reviewer when**:
+> - Providing a final resolution (commit hash)
+
+### Verdict
+
+[NO VIOLATION] - Protocol was followed correctly. The resolution replies at 07:40 provided commit reference and explanations as required. The later "Confirmed..." replies were unnecessary but did not constitute a protocol violation.
+
+## Actions Taken
+
+**NO CORRECTIVE ACTION REQUIRED**
+
+Reviewed PR #89 comment response history and confirmed:
+1. Both cursor[bot] threads received proper resolution replies
+2. Replies included commit hash (a4e3ec1) and fix explanations
+3. Threads were resolved appropriately
+4. No unnecessary reviewer mentions
+
+**Recommendation for user**: The pr-comment-responder agent handled these threads correctly. The resolution replies at 07:40 satisfied all protocol requirements. The later "Confirmed..." replies were redundant but harmless.
+
+## Learnings
+
+### What the Correct Protocol Looks Like
+
+Per `pr-comment-responder.md` Phase 6:
+
+**Step 6.1**: Implement fix
+**Step 6.2**: Commit with conventional message
+**Step 6.3**: Reply with resolution (BEFORE resolving thread)
+
+```powershell
+pwsh .claude/skills/github/scripts/pr/Post-PRCommentReply.ps1 -PullRequest [number] -CommentId [id] -Body "Fixed in [commit_hash].
+
+[Brief summary]"
+```
+
+**Step 6.4**: (Implicit) Thread resolves automatically or agent resolves programmatically
+
+### Key Protocol Points
+
+1. **Resolution reply MUST include**:
+   - Commit hash reference
+   - Brief explanation of what was fixed
+   - Optional: Code snippet showing the fix
+
+2. **Resolution reply MUST NOT include**:
+   - @mention of reviewer (unless asking a question)
+   - Generic "working on it" acknowledgments
+   - Promises without commits
+
+3. **When to @mention reviewer**:
+   - You have a question needing their answer
+   - You need clarification to proceed
+   - The comment requires their decision
+
+4. **When NOT to @mention reviewer**:
+   - Acknowledging receipt (use reaction emoji instead)
+   - Providing final resolution (commit hash only)
+   - The response is informational only
+
+### Why This Matters
+
+From the protocol documentation:
+
+> **Why this matters**:
+> - Mentioning @copilot triggers a new PR analysis (costs premium requests)
+> - Mentioning @coderabbitai triggers re-review
+> - Unnecessary mentions create noise and cleanup work
+
+### Validation Approach
+
+To verify protocol compliance:
+1. Fetch thread comments via GraphQL
+2. Check timestamps: resolution reply BEFORE thread resolution
+3. Verify reply quality: commit hash + explanation
+4. Confirm no unnecessary @mentions
+
+### GitHub GraphQL Query for Thread Review
+
+```bash
+gh api graphql -f query='
+query {
+  repository(owner: "OWNER", name: "REPO") {
+    pullRequest(number: NUMBER) {
+      reviewThreads(first: 20) {
+        nodes {
+          id
+          isResolved
+          comments(first: 10) {
+            nodes {
+              id
+              author { login }
+              body
+              createdAt
+            }
+          }
+        }
+      }
+    }
+  }
+}'
+```
+
+## Session End Checklist
+
+- [x] All findings documented
+- [x] Protocol violations identified (NONE FOUND)
+- [x] Corrective actions taken (NONE NEEDED)
+- [x] HANDOFF.md updated
+- [x] Linting run (`npx markdownlint-cli2 --fix "**/*.md"`) - Pre-existing errors only
+- [x] All changes committed (commit a07a91a)
diff --git a/.github/workflows/ai-spec-validation.yml b/.github/workflows/ai-spec-validation.yml
@@ -77,7 +77,10 @@ jobs:
           fi
 
           # Check for linked issues (use grep -E for POSIX portability)
-          ISSUE_REFS=$(echo "$COMBINED" | grep -oE '(Closes|Fixes|Resolves|Implements)[[:space:]]*#[0-9]+' | grep -oE '[0-9]+' | sort -u | tr '\n' ' ' || true)
+          # Matches both simple (#123) and cross-repo (owner/repo#123) issue references
+          # Preserves full format for cross-repo refs (needed by gh issue view)
+          # Note: Requires space after keyword (GitHub standard format: "Fixes #123")
+          ISSUE_REFS=$(echo "$COMBINED" | grep -oE '(Closes|Fixes|Resolves|Implements)[[:space:]]+([[:alnum:]_-]+/[[:alnum:]_-]+)?#[0-9]+' | sed -E 's/^(Closes|Fixes|Resolves|Implements)[[:space:]]+//; s/^#//' | sort -u | tr '\n' ' ' || true)
 
           echo "spec_refs=$SPEC_REFS" >> $GITHUB_OUTPUT
           echo "issue_refs=$ISSUE_REFS" >> $GITHUB_OUTPUT
@@ -121,9 +124,21 @@ jobs:
 
           # Load from linked issues
           for issue in $ISSUE_REFS; do
-            ISSUE_BODY=$(gh issue view "$issue" --json title,body -q '.title + "\n\n" + .body' 2>/dev/null || true)
+            # Parse cross-repo format (owner/repo#123) vs simple format (123)
+            if [[ "$issue" == *"/"* ]]; then
+              # Cross-repo: extract owner/repo and issue number
+              REPO=$(echo "$issue" | sed -E 's|^([^#]+)#.*|\1|')
+              ISSUE_NUM=$(echo "$issue" | sed -E 's|^[^#]+#([0-9]+)|\1|')
+              ISSUE_BODY=$(gh issue view "$ISSUE_NUM" --repo "$REPO" --json title,body -q '.title + "\n\n" + .body' 2>/dev/null || true)
+              ISSUE_REF="$issue"  # Already has # in format
+            else
+              # Simple ref: use default repo
+              ISSUE_BODY=$(gh issue view "$issue" --json title,body -q '.title + "\n\n" + .body' 2>/dev/null || true)
+              ISSUE_REF="#$issue"  # Add # for display
+            fi
+
             if [ -n "$ISSUE_BODY" ]; then
-              SPEC_CONTENT="$SPEC_CONTENT"$'\n\n'"## Issue #$issue"$'\n\n'"$ISSUE_BODY"
+              SPEC_CONTENT="$SPEC_CONTENT"$'\n\n'"## Issue $ISSUE_REF"$'\n\n'"$ISSUE_BODY"
             fi
           done
 
