SOP + hook: parallel agent file-target overlap detection

### Type Feature ### Lineage Standalone — discovered during 2026-04-03 email sprint. 3 parallel email PRs all touched email.py and admin.py, requiring 2 rebases and a ruff format fix before any deployed. ### Repo `forgejo_admin/claude-custom` (hook) + pal-e-docs (SOP + convention) ### User Story As a session orchestrator, I want to detect when multiple in-progress tickets target the same files So that I can either sequence merges or split modules before agents conflict. ### Context On 2026-04-03, three email feature tickets (#311, #312, #313) were dispatched in parallel. All three appended functions to the same two files: - `email.py` (1,400+ lines, 54 commits) - `admin.py` (1,000+ lines, 60 commits) Result: PR #318 merged clean, PR #317 needed rebase, PR #329 needed rebase. Each rebase required an agent dispatch. The ruff format step also failed silently, blocking all 3 deploys. The File Targets section already exists in issue templates but nothing checks for overlap between active tickets. ### Environment - claude-custom hooks directory - pal-e-docs convention/SOP notes ### File Targets Phase 1 (SOP + convention): - pal-e-docs: create `sop-file-target-overlap` note - pal-e-docs: create `convention-file-target-declaration` note Phase 2 (hook): - `hooks/check-pr-file-targets.sh` — PreToolUse hook on `mcp__forgejo__merge_approved_pr` - `settings.json` — register the new hook ### Acceptance Criteria Phase 1: - [ ] SOP note documents: symptom (rebase conflicts), prevention (check open PRs), resolution (merge FIFO), escalation (split files if >2 PRs overlap) - [ ] Convention note documents: large files (>1000 lines) must be flagged, file targets must be cross-referenced between related tickets - [ ] Main session checks for file overlap before dispatching parallel agents Phase 2: - [ ] Hook parses File Targets from issue body - [ ] Hook queries open PRs on same repo for overlapping targets - [ ] Hook warns if overlap detected, blocks if overlapping PR not yet merged - [ ] Fail-open: API errors never block merge ### Test Expectations Phase 1: - [ ] Notes exist and are tagged correctly - [ ] Next parallel dispatch session uses the convention Phase 2: - [ ] Create 2 test PRs with overlapping file targets, verify hook blocks second merge - [ ] Verify hook passes when no overlap exists ### Constraints - Phase 1 is documentation only — no code changes - Phase 2 hook must fail-open (never silently block a valid merge) - File Targets section already exists in issue templates — no template changes needed - Long-term fix (module splitting of email.py) is a separate ticket per repo ### Checklist - [ ] SOP note created - [ ] Convention note created - [ ] Hook implemented and tested (Phase 2) ### Related - `pal-e-agency` — project this affects - basketball-api#311, #312, #313 — the incident that triggered this

forgejo_admin commented

2026-04-04 04:11:56 +00:00

Contributor

Type

Feature

Lineage

Standalone — discovered during 2026-04-03 email sprint. 3 parallel email PRs all touched email.py and admin.py, requiring 2 rebases and a ruff format fix before any deployed.

Repo

forgejo_admin/claude-custom (hook) + pal-e-docs (SOP + convention)

User Story

As a session orchestrator,
I want to detect when multiple in-progress tickets target the same files
So that I can either sequence merges or split modules before agents conflict.

Context

On 2026-04-03, three email feature tickets (#311, #312, #313) were dispatched in parallel. All three appended functions to the same two files:

email.py (1,400+ lines, 54 commits)
admin.py (1,000+ lines, 60 commits)

Result: PR #318 merged clean, PR #317 needed rebase, PR #329 needed rebase. Each rebase required an agent dispatch. The ruff format step also failed silently, blocking all 3 deploys.

The File Targets section already exists in issue templates but nothing checks for overlap between active tickets.

Environment

claude-custom hooks directory
pal-e-docs convention/SOP notes

File Targets

Phase 1 (SOP + convention):

pal-e-docs: create sop-file-target-overlap note
pal-e-docs: create convention-file-target-declaration note

Phase 2 (hook):

hooks/check-pr-file-targets.sh — PreToolUse hook on mcp__forgejo__merge_approved_pr
settings.json — register the new hook

Acceptance Criteria

Phase 1:

SOP note documents: symptom (rebase conflicts), prevention (check open PRs), resolution (merge FIFO), escalation (split files if >2 PRs overlap)
Convention note documents: large files (>1000 lines) must be flagged, file targets must be cross-referenced between related tickets
Main session checks for file overlap before dispatching parallel agents

Phase 2:

Hook parses File Targets from issue body
Hook queries open PRs on same repo for overlapping targets
Hook warns if overlap detected, blocks if overlapping PR not yet merged
Fail-open: API errors never block merge

Test Expectations

Notes exist and are tagged correctly
Next parallel dispatch session uses the convention

Create 2 test PRs with overlapping file targets, verify hook blocks second merge
Verify hook passes when no overlap exists

Constraints

Phase 1 is documentation only — no code changes
Phase 2 hook must fail-open (never silently block a valid merge)
File Targets section already exists in issue templates — no template changes needed
Long-term fix (module splitting of email.py) is a separate ticket per repo

Checklist

SOP note created
Convention note created
Hook implemented and tested (Phase 2)

pal-e-agency — project this affects
basketball-api#311, #312, #313 — the incident that triggered this

Rows
Columns

SOP + hook: parallel agent file-target overlap detection #234