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
- Add Mapping: When PR created or checked out
- Update Current: When session switches PR context
- Query Mapping: Lookup branch by PR number or vice versa
- 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
Related
Acceptance Criteria
Notes
This provides the data foundation for both static (pre-commit) and dynamic (Claude Code) verification hooks.
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-mappingUpdate 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
Integration Points
Session Protocol (Phase 1)
Git Hooks
Agent Handoffs
Implementation
Module:
PRBranchMapping.psm1Testing
Related
Acceptance Criteria
.agents/AGENT-INSTRUCTIONS.mdNotes
This provides the data foundation for both static (pre-commit) and dynamic (Claude Code) verification hooks.