feat(agent-memory): maintain explicit PR-to-branch mapping in Serena

[rjmurillo-bot]

Summary

Maintain an explicit mapping of PR numbers to branch names in Serena memory to enable automated branch verification during multi-PR sessions.

Background

From PR co-mingling retrospective (PR #669): Agents lacked awareness of which branch corresponded to which PR, leading to cross-PR commits. An explicit mapping enables verification hooks and session handoffs.

Specification

Memory Name: pr-branch-mapping
Update Trigger: PR creation, branch switches, session handoffs

Data Structure

{
  "mappings": [
    {
      "pr_number": 669,
      "branch_name": "docs/pr-co-mingling-retrospective",
      "created_at": "2025-12-31T05:53:35Z",
      "status": "open",
      "last_session": "2025-12-31-session-110"
    }
  ],
  "current_session": {
    "session_id": "2025-12-31-session-110",
    "pr_number": 669,
    "branch_name": "docs/pr-co-mingling-retrospective"
  }
}

Operations

1. Add Mapping: When PR created or checked out
2. Update Current: When session switches PR context
3. Query Mapping: Lookup branch by PR number or vice versa
4. Validate Branch: Check current branch matches active PR

Integration Points

Session Protocol (Phase 1)

# During session initialization
$prNumber = 669
$branch = git branch --show-current

# Update Serena memory
Update-PRBranchMapping -PRNumber $prNumber -Branch $branch -SessionId "session-110"

Git Hooks

# Pre-commit hook queries mapping
$currentBranch = git branch --show-current
$expectedPR = Get-PRForBranch -Branch $currentBranch

if ($env:SESSION_PR -and $env:SESSION_PR -ne $expectedPR) {
    Write-Error "Branch/PR mismatch: expected PR $expectedPR, session context shows PR $env:SESSION_PR"
    exit 1
}

Agent Handoffs

## Handoff Context
**PR**: #669
**Branch**: docs/pr-co-mingling-retrospective (verified from Serena mapping)
**Status**: Open

Implementation

Module: PRBranchMapping.psm1

function Add-PRBranchMapping {
    param(
        [int]$PRNumber,
        [string]$BranchName,
        [string]$SessionId
    )
    
    # Read current mapping from Serena
    $mapping = Read-SerenaMemory -Name "pr-branch-mapping"
    
    # Add/update entry
    $mapping.mappings += @{
        pr_number = $PRNumber
        branch_name = $BranchName
        created_at = (Get-Date).ToUniversalTime().ToString("o")
        last_session = $SessionId
    }
    
    # Update current session
    $mapping.current_session = @{
        session_id = $SessionId
        pr_number = $PRNumber
        branch_name = $BranchName
    }
    
    # Write back to Serena
    Write-SerenaMemory -Name "pr-branch-mapping" -Content $mapping
}

function Get-PRForBranch {
    param([string]$BranchName)
    
    $mapping = Read-SerenaMemory -Name "pr-branch-mapping"
    $entry = $mapping.mappings | Where-Object { $_.branch_name -eq $BranchName } | Select-Object -First 1
    
    return $entry.pr_number
}

function Test-BranchPRConsistency {
    $currentBranch = git branch --show-current
    $mapping = Read-SerenaMemory -Name "pr-branch-mapping"
    
    if ($mapping.current_session.branch_name -ne $currentBranch) {
        Write-Warning "Branch mismatch: current=$currentBranch, expected=$($mapping.current_session.branch_name)"
        return $false
    }
    
    return $true
}

Testing

• Test add mapping for new PR
• Test update mapping on session switch
• Test query by PR number
• Test query by branch name
• Test validation when branch/PR mismatch
• Test cleanup of merged PRs

Related

• PR docs(retrospective): PR co-mingling root cause analysis #669: Root cause analysis
• Issue feat(git-hooks): add pre-commit branch validation hook #681: Pre-commit hook (uses this mapping)
• Issue feat(agent-workflow): add git command verification hook for Claude Code #682: Claude Code hook (uses this mapping)
• ADR-011: Session State MCP

Acceptance Criteria

• Serena memory stores PR-to-branch mappings
• Helper functions for add/query/validate
• Integration with session protocol (Phase 1)
• Integration with git hooks (feat(git-hooks): add pre-commit branch validation hook #681, feat(agent-workflow): add git command verification hook for Claude Code #682)
• Documented in .agents/AGENT-INSTRUCTIONS.md

Notes

This provides the data foundation for both static (pre-commit) and dynamic (Claude Code) verification hooks.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Related Issues

• feat(agent-workflow): add git command verification hook for Claude Code #682
• feat(protocol): add branch verification gate to SESSION-PROTOCOL #679

🔗 Related PRs

#53 - Create PRD for Visual Studio 2026 install support [merged]
#301 - docs: autonomous PR monitoring prompt and retrospective [merged]
#322 - feat: Implement PR merge state verification to prevent wasted review effort [merged]
#610 - fix(ci): reconcile pre-commit session validation with CI requirements [merged]
#669 - docs(retrospective): PR co-mingling root cause analysis [closed]

👤 Suggested Assignees

• rjmurillo-bot
• rjmurillo

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[github-actions]

Product Requirements Document

Important

This PRD was automatically generated based on issue triage escalation.
Complexity Score: 9/12 (Detailed)
Escalation Criteria: feature_request,multi_phase_work,external_dependency

About this PRD

This PRD was generated by the Explainer Agent after the issue was flagged
for detailed analysis. The document is designed to be self-contained - it can
be passed to a separate AI agent instance for implementation without additional
context.

PRD Depth Levels:

• Standard (4-6): Brief analysis, clear requirements
• Detailed (7-9): Research section, blocking questions
• Comprehensive (10-12): Phased implementation, risk analysis

---

Now I have gathered sufficient context. Let me create the PRD.

The directory exists. The file creation was denied due to permissions. I'll output the PRD content directly for the user since I cannot write to the filesystem:

---

PRD: PR-to-Branch Mapping in Serena Memory

Executive Summary

Agents lack awareness of which branch corresponds to which PR during multi-PR sessions, causing cross-PR commits and co-mingled changes. This PRD defines a PR-to-branch mapping system stored in Serena memory with helper functions for add, query, and validate operations.

Scope	Status	Blocker
Serena memory storage	🟢 READY	None
PowerShell helper module	🟢 READY	None
Session Protocol integration	🟢 READY	None
Pre-commit hook integration	🟡 PARTIAL	Depends on Issue #681
Claude Code hook integration	🟡 PARTIAL	Depends on Issue #682

Verdict: READY for Phase 1 implementation. Phase 2 integrations depend on hook issues.

---

Problem Statement

Current State

Component	Current Behavior
Session logs	Record branch name but no PR association
Pre-commit hook	No branch/PR consistency validation
Agent sessions	No persistent PR-to-branch mapping
Multi-PR sessions	Context switches without branch verification

Gap Analysis

1. No persistent mapping: When an agent creates or switches to a PR, there is no memory of which branch belongs to which PR
2. Trust-based verification: SESSION-PROTOCOL.md recommends git branch --show-current but does not enforce PR/branch consistency
3. Session handoffs lose context: New sessions inherit branch state but not PR context
4. Parallel session conflicts: Multiple sessions may operate on different PRs without awareness

User Impact

Primary user: AI agents executing development sessions

Impact severity: HIGH

Evidence from PR #669 retrospective:

• 3 PRs contained co-mingled changes from 6+ issues
• Root cause: agent committed to wrong branch (feat/97) when working on Issue chore: Convert workflows for ARM runner migration (ubuntu-24.04-arm) #197
• 8 branch switches in 11 minutes with 2 wrong-branch commits

---

Research Findings

Primary Sources

ADR-011: Session State MCP (Proposed)

• Defines state machine for session phases including branch/PR tracking
• Proposes session-current-state memory with branch and PR fields
• Confidence: CONFIRMED

SESSION-PROTOCOL.md (Phase 4: Git State Verification)

• "The agent SHOULD run git branch --show-current to verify correct branch"
• Requirement level: SHOULD (not MUST)
• Confidence: CONFIRMED

PR co-mingling root cause analysis (2025-12-31)

• "Trust-based compliance for git operations (no verification before commit)"
• "Agent didn't verify current branch before committing"
• Confidence: CONFIRMED

Secondary Sources

Pre-commit hook (.githooks/pre-commit)

• Already validates: HANDOFF.md protection, session protocol, bash detection
• Does NOT validate: PR/branch consistency
• Confidence: CONFIRMED

Empirical Data

Git reflog from 2025-12-29 incident:

22:54:09 - On feat/97: commit session-164 (CORRECT)
22:55:05 - On feat/97: commit ARM changes (WRONG - should be chore/197)
22:55:40 - On chore/197: commit ARM changes (DUPLICATE)

---

Proposed Solution

Phase 1: Core Memory and Helper Functions (READY)

Estimated Effort: M (Medium)
Blockers: None

Task	Description
1.1	Create pr-branch-mapping.md Serena memory schema
1.2	Create PRBranchMapping.psm1 PowerShell module
1.3	Implement Add-PRBranchMapping function
1.4	Implement Get-PRForBranch function
1.5	Implement Test-BranchPRConsistency function
1.6	Add Pester tests for module

Phase 2: Session Protocol Integration (READY)

Estimated Effort: S (Small)
Blockers: None

Task	Description
2.1	Update SESSION-PROTOCOL.md Phase 4 to include PR mapping
2.2	Update session log template with PR field
2.3	Document memory usage in AGENT-INSTRUCTIONS.md

Phase 3: Hook Integration (DEPENDS on #681, #682)

Estimated Effort: S (Small)
Blockers: Issues #681 and #682 must be implemented first

Task	Description
3.1	Integrate with pre-commit hook (after #681)
3.2	Integrate with Claude Code hook (after #682)

---

Functional Requirements

FR-1: Memory Storage

Priority: P0

ID	Requirement	Acceptance Criteria
FR-1.1	The system MUST store PR-to-branch mappings in Serena memory	Memory file .serena/memories/pr-branch-mapping.md exists with JSON content block
FR-1.2	The system MUST track PR number, branch name, creation time, and status	All fields present in JSON schema
FR-1.3	The system MUST track current session context (PR, branch, session ID)	current_session object populated during active sessions
FR-1.4	The system MUST support multiple concurrent PR mappings	mappings array accepts N entries

FR-2: Helper Functions

Priority: P0

ID	Requirement	Acceptance Criteria
FR-2.1	Add-PRBranchMapping MUST add or update a PR-to-branch mapping	Function creates/updates entry in memory
FR-2.2	Get-PRForBranch MUST return PR number for given branch name	Function returns integer or null
FR-2.3	Get-BranchForPR MUST return branch name for given PR number	Function returns string or null
FR-2.4	Test-BranchPRConsistency MUST validate current branch matches active PR	Function returns boolean with warning on mismatch
FR-2.5	All functions MUST read from Serena memory file	No hardcoded state outside memory

FR-3: Integration Points

Priority: P1

ID	Requirement	Acceptance Criteria
FR-3.1	Session initialization SHOULD update current_session when PR known	Session log shows PR context
FR-3.2	Pre-commit hook SHOULD validate branch/PR consistency	Hook calls Test-BranchPRConsistency
FR-3.3	Agent handoffs SHOULD include PR/branch verification	Handoff context includes verified mapping

---

Non-Functional Requirements

Consistency

• PowerShell module follows existing patterns in scripts/lib/
• Memory file follows Serena memory format (Markdown with embedded JSON)
• Function naming follows PowerShell verb-noun convention

Testability

• Pester tests cover all public functions
• Tests use mock Serena memory (file-based)
• Test coverage target: 80%

Documentation

• Module functions include complete comment-based help
• Memory schema documented in file header
• Integration documented in AGENT-INSTRUCTIONS.md

---

Technical Design

Memory Schema

File: .serena/memories/pr-branch-mapping.md

# PR-to-Branch Mapping

Maintains mapping of PR numbers to branch names for branch/PR consistency validation.

## Data

\`\`\`json
{
  "mappings": [
    {
      "pr_number": 669,
      "branch_name": "docs/pr-co-mingling-retrospective",
      "created_at": "2025-12-31T05:53:35Z",
      "status": "open",
      "last_session": "2025-12-31-session-110"
    }
  ],
  "current_session": {
    "session_id": "2025-12-31-session-110",
    "pr_number": 669,
    "branch_name": "docs/pr-co-mingling-retrospective"
  }
}
\`\`\`

## Keywords

pr-branch-mapping, branch-validation, session-context, git-safety

PowerShell Module

File: scripts/lib/PRBranchMapping.psm1

<#
.SYNOPSIS
    PR-to-Branch mapping functions for Serena memory.

.DESCRIPTION
    Provides functions to add, query, and validate PR-to-branch mappings
    stored in Serena memory. Used by session protocol and git hooks.

.NOTES
    Related: Issue #680, ADR-011, SESSION-PROTOCOL.md
#>

$script:MemoryPath = ".serena/memories/pr-branch-mapping.md"

function Get-PRBranchMapping {
    <#
    .SYNOPSIS
        Reads the PR-to-branch mapping from Serena memory.
    #>
    [CmdletBinding()]
    param(
        [string]$Path = $script:MemoryPath
    )

    if (-not (Test-Path $Path)) {
        return @{
            mappings = @()
            current_session = $null
        }
    }

    $Content = Get-Content -Path $Path -Raw
    
    # Extract JSON from markdown code block
    if ($Content -match '```json\s*\n([\s\S]*?)\n```') {
        return $Matches[1] | ConvertFrom-Json -AsHashtable
    }

    return @{
        mappings = @()
        current_session = $null
    }
}

function Add-PRBranchMapping {
    <#
    .SYNOPSIS
        Adds or updates a PR-to-branch mapping.

    .PARAMETER PRNumber
        The PR number to map.

    .PARAMETER BranchName
        The branch name associated with the PR.

    .PARAMETER SessionId
        Current session ID for tracking.
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [int]$PRNumber,

        [Parameter(Mandatory)]
        [string]$BranchName,

        [string]$SessionId
    )

    $Mapping = Get-PRBranchMapping
    
    # Find existing entry for this PR
    $ExistingIndex = -1
    for ($i = 0; $i -lt $Mapping.mappings.Count; $i++) {
        if ($Mapping.mappings[$i].pr_number -eq $PRNumber) {
            $ExistingIndex = $i
            break
        }
    }

    $Entry = @{
        pr_number = $PRNumber
        branch_name = $BranchName
        created_at = (Get-Date).ToUniversalTime().ToString("o")
        status = "open"
        last_session = $SessionId
    }

    if ($ExistingIndex -ge 0) {
        $Entry.created_at = $Mapping.mappings[$ExistingIndex].created_at
        $Mapping.mappings[$ExistingIndex] = $Entry
    } else {
        $Mapping.mappings += $Entry
    }

    if ($SessionId) {
        $Mapping.current_session = @{
            session_id = $SessionId
            pr_number = $PRNumber
            branch_name = $BranchName
        }
    }

    Save-PRBranchMapping -Mapping $Mapping
}

function Get-PRForBranch {
    <#
    .SYNOPSIS
        Returns the PR number for a given branch name.
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$BranchName
    )

    $Mapping = Get-PRBranchMapping
    $Entry = $Mapping.mappings | Where-Object { $_.branch_name -eq $BranchName } | Select-Object -First 1
    
    if ($Entry) {
        return $Entry.pr_number
    }
    return $null
}

function Get-BranchForPR {
    <#
    .SYNOPSIS
        Returns the branch name for a given PR number.
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [int]$PRNumber
    )

    $Mapping = Get-PRBranchMapping
    $Entry = $Mapping.mappings | Where-Object { $_.pr_number -eq $PRNumber } | Select-Object -First 1
    
    if ($Entry) {
        return $Entry.branch_name
    }
    return $null
}

function Test-BranchPRConsistency {
    <#
    .SYNOPSIS
        Validates that current branch matches the active PR context.

    .OUTPUTS
        [bool] True if consistent, False if mismatch detected.
    #>
    [CmdletBinding()]
    param()

    $CurrentBranch = git branch --show-current 2>$null
    if (-not $CurrentBranch) {
        Write-Warning "Could not determine current branch"
        return $false
    }

    $Mapping = Get-PRBranchMapping

    if (-not $Mapping.current_session) {
        return $true
    }

    if ($Mapping.current_session.branch_name -ne $CurrentBranch) {
        Write-Warning "Branch mismatch: current='$CurrentBranch', expected='$($Mapping.current_session.branch_name)'"
        Write-Warning "Active PR: #$($Mapping.current_session.pr_number)"
        return $false
    }

    return $true
}

function Save-PRBranchMapping {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [hashtable]$Mapping,
        [string]$Path = $script:MemoryPath
    )

    $Json = $Mapping | ConvertTo-Json -Depth 10

    $Content = @"
# PR-to-Branch Mapping

Maintains mapping of PR numbers to branch names for branch/PR consistency validation.

## Data

``````json
$Json

Keywords

pr-branch-mapping, branch-validation, session-context, git-safety
"@

$Dir = Split-Path -Parent $Path
if (-not (Test-Path $Dir)) {
    New-Item -ItemType Directory -Path $Dir -Force | Out-Null
}

Set-Content -Path $Path -Value $Content -Encoding utf8

}

Export-ModuleMember -Function @(
'Get-PRBranchMapping'
'Add-PRBranchMapping'
'Get-PRForBranch'
'Get-BranchForPR'
'Test-BranchPRConsistency'
)

---

## Implementation Plan

### Prerequisites

- PowerShell 7.x installed (already required)
- Serena memory system operational (confirmed)
- `.serena/memories/` directory exists (confirmed)

### Phase 1 Tasks

1. Create `PRBranchMapping.psm1` at `scripts/lib/PRBranchMapping.psm1`
2. Create initial memory file at `.serena/memories/pr-branch-mapping.md`
3. Add Pester tests at `scripts/tests/PRBranchMapping.Tests.ps1`
4. Validate module with `Import-Module -Force` and test functions

### Phase 2 Tasks

1. Update SESSION-PROTOCOL.md Phase 4 with PR mapping guidance
2. Update session log template to include PR field
3. Update AGENT-INSTRUCTIONS.md with module documentation

### Decision Tree

```text
Is PR number known at session start?
├── YES → Call Add-PRBranchMapping immediately
│         └── Session log includes PR reference
└── NO → Skip mapping until PR created
         └── When PR created → Call Add-PRBranchMapping
                               └── Update session log

---

Risks and Mitigations

Risk	Likelihood	Impact	Mitigation
Memory file corruption	Low	Medium	JSON validation on read; fallback to empty state
Stale mappings for closed PRs	Medium	Low	Add Update-PRBranchMappingStatus function
Parallel session conflicts	Medium	Medium	Serena memory handles file-level atomicity
Agent skips mapping update	Medium	High	Pre-commit hook validation (Phase 3)

---

Success Metrics

Metric	Target
Wrong-branch commits after implementation	0 per week
PR/branch consistency validation coverage	100% of sessions with known PR
Helper function test coverage	≥80%

---

Blocking Questions

None. All requirements are clear from the issue specification and root cause analysis.

---

Open Questions (Non-Blocking)

1. Q: Should closed PRs be automatically removed from mapping?

   • Hypothesis: No, keep for audit trail; add status: closed field
   • Status: Would be validated during Phase 3 integration

2. Q: Should mapping support multiple PRs per session?

   • Hypothesis: No, SESSION-PROTOCOL should limit to 1-2 issues per session
   • Status: Aligns with root cause finding about cognitive load

---

Appendices

Appendix A: Research Sources

Source	Link	Confidence
ADR-011 Session State MCP	.agents/architecture/ADR-011-session-state-mcp.md	CONFIRMED
SESSION-PROTOCOL.md	.agents/SESSION-PROTOCOL.md	CONFIRMED
PR co-mingling RCA	.serena/memories/pr-co-mingling-root-cause-2025-12-31.md	CONFIRMED
Pre-commit hook	.githooks/pre-commit	CONFIRMED

Appendix B: Related Issues/PRs

Reference	Description
PR #669	Root cause analysis source
Issue #681	Pre-commit hook (uses this mapping)
Issue #682	Claude Code hook (uses this mapping)
ADR-011	Session State MCP (architectural context)

Appendix C: File Locations

Artifact	Path
PowerShell module	scripts/lib/PRBranchMapping.psm1
Pester tests	scripts/tests/PRBranchMapping.Tests.ps1
Serena memory	.serena/memories/pr-branch-mapping.md
Session Protocol	.agents/SESSION-PROTOCOL.md

---

_{Generated by AI PRD Generation | View Workflow}

[github-actions]

AI Triage Summary

Note

This issue has been automatically triaged by AI agents

What is AI Triage?

This issue was analyzed by AI agents:

• Analyst Agent: Categorizes the issue and suggests appropriate labels
• Roadmap Agent: Aligns the issue with project milestones and priorities
• Explainer Agent (if escalated): Generates comprehensive PRD

Triage Results

Property	Value
Category	enhancement
Labels	["enhancement","agent-memory"]
Priority	P1
Milestone	v1.1
PRD Escalation	Generated (see below)

Categorization Analysis

```json
{
  "labels": ["enhancement", "agent-memory"],
  "category": "enhancement",
  "confidence": 0.95,
  "reasoning": "Issue proposes a new PR-to-branch mapping feature for the memory agent to prevent cross-PR commits during multi-PR sessions."
}

</details>

<details>
<summary>Roadmap Alignment</summary>

```json
```json
{
  "milestone": "v1.1",
  "priority": "P1",
  "epic_alignment": "",
  "confidence": 0.80,
  "reasoning": "New memory module for PR/branch mapping addresses workflow reliability; aligns with v1.1 maintainability focus but no existing epic covers agent-memory infrastructure.",
  "escalate_to_prd": true,
  "escalation_criteria": ["feature_request", "multi_phase_work", "external_dependency"],
  "complexity_score": 9
}

</details>

---

<sub>Powered by [AI Issue Triage](https://github.com/rjmurillo/ai-agents) workflow</sub>