pal-e-docs

Review: Cross-repo worktree isolation for parallel agents

review-418-2026-03-28 Doc

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- Standalone, discovered during parallel agent incident 2026-03-26
  • [x] Repo -- Tracker (pal-e-platform), Primary PR (claude-custom), SOP updates (pal-e-docs)
  • [x] User Story -- platform operator spawning parallel Dev agents
  • [x] Context -- thorough incident description with root cause analysis
  • [x] File Targets -- 4 targets across 2 repos + pal-e-docs SOPs, with exclusions listed
  • [x] Acceptance Criteria -- 7 ACs, all verifiable
  • [x] Test Expectations -- 4 manual tests + run command
  • [x] Constraints -- 6 constraints including performance (< 50ms), QA exclusion
  • [x] Checklist -- 7 items tracking child issues and deliverables
  • [x] Related -- 5 cross-references to SOPs, conventions, adjacent issues
All required Feature template sections present and populated. Issue has been through 4 prior review rounds with body updated from comment refinements.

Traceability

  • [x] story:dev-execute -- present on board item #418
  • [ ] arch:worktree -- MISMATCH: board item has arch:ci-pipeline but issue body explicitly states arch:worktree (not arch:ci-pipeline -- this is worktree/hooks domain, not Woodpecker CI). The board label was never corrected.
  • [x] Forgejo issue -- forgejo_admin/pal-e-platform#188, state: open

File Targets

  • [x] hooks/cross-repo-isolation.sh (new) -- confirmed does not exist yet in ~/claude-custom/hooks/. Parent directory exists with 30 existing hooks. New file is appropriate.
  • [x] agents/dev.md -- verified exists at ~/claude-custom/agents/dev.md. Confirmed no cross-repo isolation content present (only isolation: worktree in frontmatter). Ready for update.
  • [x] cleanup-worktrees.sh -- verified exists at ~/claude-custom/hooks/cleanup-worktrees.sh. Currently handles .claude/worktrees/ cleanup across 22 repos. Does NOT handle /tmp/ clone cleanup -- confirming the gap this ticket addresses.
  • [x] worktree-workflow SOP (pal-e-docs) -- verified exists (slug: worktree-workflow, type: sop, status: active). Has no "Cross-Repo Isolation" section yet.
  • [x] agent-spawn-conventions (pal-e-docs) -- verified exists (slug: agent-spawn-conventions, type: convention, status: active). Pre-spawn checklist has 4 items, none address cross-repo isolation.
All targets verified. Specificity is high -- agent can act without guessing.

Repo Placement

OK. This is a tracking/umbrella issue filed on pal-e-platform (where the gap was discovered). Decomposition correctly routes:
  • Code work to claude-custom#205 (hook + agent profile + cleanup)
  • SOP work to Dottie (pal-e-docs MCP updates)
The umbrella/child structure is clean. No single-repo misfiling.

Dependencies

  • [x] claude-custom#184 (worktree isolation enforcement gaps) -- board item #485 is in done column. Issue body correctly states "no overlap": #184 covers freshness + cleanup, this covers cross-repo isolation. No blocker.
  • [x] claude-custom#205 (child issue, hook + agent profile) -- open, ready for execution.
  • [x] No items in in_progress block this ticket.

Acceptance Criteria

7 ACs, all agent-verifiable:
  • AC 1-2: /tmp/ clone or git worktree for non-spawning repos -- verifiable by code inspection of hook logic
  • AC 3-4: SOP updates -- verifiable by reading pal-e-docs notes post-update
  • AC 5: PreToolUse hook warns on unsafe cd ~/repo && git checkout pattern -- verifiable by running hook with mock input
  • AC 6: Dev agent profile updated -- verifiable by reading agents/dev.md
  • AC 7: /tmp/ cleanup mechanism -- verifiable by reading cleanup-worktrees.sh
All ACs are testable and specific. No ambiguous "works correctly" language. Test expectations include 4 manual tests and a concrete run command.

Blast Radius

  • No existing hook handles cd ~/repo && git checkout cross-repo detection. The new hook is purely additive -- no existing behavior modified.
  • cleanup-worktrees.sh currently scans 22 repos for .claude/worktrees/ but does NOT clean /tmp/ clones. Adding /tmp/ cleanup is a net-new code path -- low regression risk.
  • pre-spawn-freshness.sh and check-branch-freshness.sh handle freshness for worktrees. The cross-repo hook is orthogonal -- no overlap or conflict.
  • Only agents/dev.md needs updating among the 5 agent profiles (QA is read-only, Betty Sue/Dottie/Penny don't write code). Constraint correctly identified in issue.
  • Rollback: removing the hook file + reverting dev.md changes. Straightforward.

Decomposition Assessment

Already decomposed into 2 children per the 5-minute rule:
  • Child 1: claude-custom#205 -- hook + agent profile + cleanup (AC 1,2,5,6,7). 3 file targets in 1 repo. Fits three-thing limit and five-minute rule.
  • Child 2: Dottie SOP task -- 2 pal-e-docs note updates (AC 3,4). Fits five-minute rule.
Parent issue #188 is an umbrella tracker. The two children are independent and can be parallelized. No further decomposition needed.

Recommendation

  • [LABEL] Fix arch label on board item #418: change arch:ci-pipeline to arch:worktree. The issue body explicitly states this correction in its "Board Labels" section, but the board item was never updated to match.
One label fix and this ticket is READY. All other aspects are solid after 4 prior review rounds and a full body rewrite incorporating all comment refinements.