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 additional in comment only)
• [x] Test Expectations — present (4 items)
• [x] Constraints — present (5 items in body; 1 additional in comment only)
• [x] Checklist — present
• [x] Related — present (4 items)

Traceability

• [x] story:dev-execute label — present on board item #418
• [ ] arch:ci-pipeline label — MISLABELED. Per convention-architecture-ids, arch:ci-pipeline = Woodpecker CI. This work is agent spawn hooks and worktree isolation. Should be arch:worktree (used by board items #507, #508, #509 in the same domain) or arch:hooks.
• [x] Forgejo issue — valid, open: forgejo_admin/pal-e-platform#188

Prior Findings Status (from R3)

• Update the issue body with refinements from comments: NOT DONE. Issue body last updated 2026-03-27T21:07:11Z (same time as R3 comment posting). The three refinements from comment #7900 — (a) PR target is ldraney/claude-custom, (b) /tmp/ cleanup acceptance criterion, (c) QA exclusion constraint — still exist only in comments. A Dev agent reads the body via API, not comments.
• Decompose the ticket: PARTIALLY DONE (externally). claude-custom#184 ("Worktree isolation enforcement gaps") exists as a separate issue that explicitly references #188 as its umbrella. It covers hooks, agent config, and SOP updates with its own decomposition (Ticket A: Dev agent, Ticket B: Dottie). However, #184's scope does NOT fully match #188. Key gaps:

File Targets

• [x] hooks/cross-repo-isolation.sh (new) — confirmed: file does NOT exist in ~/claude-custom/hooks/. 39 hooks present, none address cross-repo isolation.
• [x] agents/dev.md — verified: exists (117 lines). Has isolation: worktree in frontmatter. No cross-repo isolation instructions. 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.
• [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 #485 (claude-custom#184, "Worktree isolation enforcement gaps") — marked done on board but Forgejo issue still open. Covers adjacent worktree gaps (freshness, cleanup, QA config) but NOT the cross-repo isolation hook. Related, not blocking.
• Board item #508 (claude-custom#194, "Post-merge worktree cleanup") — in next_up. Forgejo issue is closed. Addresses /tmp/ cleanup which is tangentially relevant.
• Board item #507 (claude-custom#193, "Pre-spawn freshness hook") — done, Forgejo issue closed. Completed. Related but independent.
• Board item #241 (#136: Worktree auto-rebase) — in todo. Same worktree domain, not blocking.
• No blocking dependencies identified.

Acceptance Criteria

• AC 1-2 (isolation behavior) — convention-based, enforced by proposed hook. Testable manually.
• AC 3-4 (SOP updates) — Dottie's domain. Verifiable by reading updated notes.
• AC 5 (PreToolUse hook warns on unsafe pattern) — testable with mock inputs per Test Expectations.
• AC 6 (Dev agent profile update) — verifiable by reading agents/dev.md.
• AC 7 (/tmp/ cleanup, comment-only) — NOT in the issue body. A Dev agent will not see this criterion.

Blast Radius

• check-issue.sh (lines 49-58): Already has cross-repo write detection via file path resolution. The new cross-repo-isolation.sh hook must not conflict — different trigger (PreToolUse on Bash commands) vs. check-issue (PreToolUse on Write/Edit).
• block-claude-custom-main-edit.sh: Error message suggests cd ~/claude-custom && git checkout -b. The new hook must not false-positive on this guidance or on legitimate branch creation in the spawning repo.
• cleanup-worktrees.sh: Only handles .claude/worktrees/ paths. Does NOT clean /tmp/{repo}-{branch} clones. Without a cleanup mechanism, /tmp/ clones will accumulate indefinitely.
• CLAUDE.md Worktree Isolation section: Currently only documents claude-custom /tmp/ clones. Not in the acceptance criteria to generalize.

Decomposition

• >3 file targets across >2 repos: YES. 4+ targets across 3 systems (claude-custom hooks/agents, pal-e-docs SOPs, pal-e-platform CLAUDE.md).
• >5 acceptance criteria: YES. 7 total.
• Estimated agent work >5 minutes: YES.

Recommendation

• [BODY] Update the issue body. Merge the three refinements from comment #7900 into the body: (a) clarify ### Repo — tracker on pal-e-platform, primary PR on claude-custom, SOP updates via pal-e-docs MCP; (b) add AC 7 (/tmp/ cleanup convention or script); (c) add QA exclusion constraint. This is the same finding from R3 — it persists.
• [DECOMPOSE] Create proper child issues. The existing claude-custom#184 covers adjacent gaps but NOT #188's core scope (cross-repo isolation hook + /tmp/ clone convention). Create:
• [LABEL] Fix arch label. Change arch:ci-pipeline to arch:worktree on board item #418. ci-pipeline = Woodpecker CI per convention-architecture-ids; this work is worktree/hooks domain.

• Board item #485 (claude-custom#184) is marked done but Forgejo issue is still open. State mismatch should be resolved.
• Board item #508 (claude-custom#194) is in next_up but Forgejo issue is closed. Another state mismatch.
• CLAUDE.md Worktree Isolation section should be generalized beyond claude-custom after implementation.