Review: Cross-repo worktree isolation for parallel agents

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type -- present ("Feature")
• [x] Lineage -- present (standalone, discovered-scope)
• [x] Repo -- present (pal-e-platform, claude-custom)
• [x] User Story -- present and well-formed
• [x] Context -- present, thorough, includes incident details
• [x] File Targets -- present with both "modify" and "should NOT touch" lists
• [x] Acceptance Criteria -- present (6 items in body, 1 added in comment #7900)
• [x] Test Expectations -- present (4 items)
• [x] Constraints -- present (5 items in body, 1 added in comment #7900)
• [x] Checklist -- present
• [x] Related -- present (4 items)

Traceability

• [x] story:dev-execute label -- present on board item #418 (added after first review)
• [x] arch:ci-pipeline label -- present. Acceptable, though arch:agent-spawn would be more precise.
• [x] Forgejo issue -- valid, open: forgejo_admin/pal-e-platform#188

Prior Findings Status

• [x] Type mismatch (R1, R2): RESOLVED. Board item now says type:feature, matching the issue body ### Type: Feature.
• [x] Missing story label (R1): RESOLVED. story:dev-execute added to board item #418.
• [ ] Issue body not updated (R2): PERSISTS. Comment #7900 posts a "consolidated spec" that supersedes the body, but the body was never edited. A Dev agent reads the issue body via API, not comments. Three refinements from comment #7887 (PR target clarification, /tmp/ cleanup criterion, QA exclusion) and the final consolidated spec in #7900 exist only as comments.

File Targets

• [x] hooks/cross-repo-isolation.sh (new) -- confirmed: file does NOT exist. Path valid within ~/claude-custom/hooks/.
• [x] agents/dev.md -- verified: exists at ~/claude-custom/agents/dev.md (117 lines). Has isolation: worktree in frontmatter but no cross-repo isolation section. Gap confirmed.
• [x] worktree-workflow SOP (pal-e-docs) -- verified: exists, active. No "Cross-Repo Isolation" section. Worktree Location table notes /tmp/ as "Not standard" -- the issue proposes making it standard for cross-repo.
• [x] agent-spawn-conventions (pal-e-docs) -- verified: exists, active. Pre-Spawn Checklist has 4 items, none mention cross-repo isolation.
• [x] terraform/, salt/ (should NOT touch) -- confirmed present, excluded correctly.

Repo Placement

Dependencies

• Board item #241 (#136: Worktree flow -- auto-rebase branches when main advances) in todo on board-pal-e-agency -- related but independent. Both address worktree gaps.
• Board item #347 (arch:agent-spawn bug, backlog) -- same domain, not blocking.
• No blocking dependencies. Ticket is independently deliverable.

Acceptance Criteria

• AC 1-2 (isolation behavior) -- convention-based, partially enforced by the hook. Acceptable.
• AC 3-4 (SOP updates) -- Dottie's domain. Verifiable by reading updated notes.
• AC 5 (PreToolUse hook) -- testable with mock inputs.
• AC 6 (Dev agent profile update) -- verifiable by reading agents/dev.md.
• AC 7 (/tmp/ cleanup, from comment) -- verifiable but only exists in comments, not body.

Blast Radius

• QA agents: Comment #7900 clarifies QA agents are read-only and don't need cross-repo isolation. This is correct -- QA has no Write/Edit/Bash-write tools. However, QA does have isolation: worktree in agent-spawn-requirements.json. Not a problem since QA doesn't push changes, but worth noting.
• cleanup-worktrees.sh: Only scans .claude/worktrees/ in known repos. Does NOT clean /tmp/{repo}-{branch} clones. The /tmp/ cleanup AC added in comment #7900 is critical -- without it, /tmp/ clones will accumulate. The hook or convention needs a cleanup mechanism.
• check-issue.sh: Already has worktree path resolution logic (lines 37-46). The new hook should not conflict.
• block-claude-custom-main-edit.sh: Its error message suggests cd ~/claude-custom && git checkout -b. The new hook detects cd ~/repo && git checkout patterns. Needs to distinguish between "checkout a branch in a shared dir" (unsafe) vs "checkout a new branch" (also unsafe in shared dir context).
• CLAUDE.md Worktree Isolation section: Currently only documents claude-custom /tmp/ clones. Should be updated to reference the generalized pattern, but this is not in the acceptance criteria.

Decomposition Assessment (5-Minute Rule)

• >3 file targets across >2 repos: YES. 4 targets (hook, dev.md, worktree-workflow SOP, agent-spawn-conventions SOP) across 3 systems (claude-custom, pal-e-docs MCP, pal-e-platform CLAUDE.md).
• >5 acceptance criteria: YES. 7 total (6 in body + 1 in comment).
• Estimated agent work >5 minutes: YES. Hook implementation + agent profile update + SOP updates + testing exceeds single-agent scope.

• Dev agent ticket (claude-custom): Create hooks/cross-repo-isolation.sh, update agents/dev.md, wire hook into settings.json. AC 1, 2, 5, 6, 7.
• Dottie ticket (pal-e-docs): Update worktree-workflow SOP with Cross-Repo Isolation section, update agent-spawn-conventions Pre-Spawn Checklist. AC 3, 4.

Recommendation

• Update the issue body with refinements from comments. Comment #7900's consolidated spec must be merged into the issue body. A Dev agent reads the body, not comments. Specifically: (a) clarify PR target is ldraney/claude-custom, (b) add the /tmp/ cleanup acceptance criterion, (c) add the QA exclusion constraint. Use mcp__forgejo__* or curl PATCH to edit the issue body.
• Decompose the ticket. 7 ACs across 3 systems exceeds single-agent scope. Create two child issues: one on claude-custom for hook + agent profile work, one tracking Dottie's SOP updates. Keep #188 as the umbrella tracker.

• Consider updating the CLAUDE.md Worktree Isolation section to reference the generalized cross-repo pattern (currently only covers claude-custom).
• Add cleanup-worktrees.sh awareness: the /tmp/ cleanup mechanism should either extend the existing cleanup hook or establish a separate convention.