pal-e-docs

Review: Worktree flow — auto-rebase branches when main advances

review-241-2026-03-27 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — plan-pal-e-agency Phase 16, discovered scope
  • [x] Repo — forgejo_admin/claude-custom
  • [x] User Story — clear actor/want/so-that
  • [x] Context — explains the gap well
  • [x] File Targets — present (but see issues below)
  • [x] Acceptance Criteria — 3 criteria
  • [x] Test Expectations — present
  • [x] Constraints — 3 constraints listed
  • [x] Checklist — standard 4-item
  • [x] Related — references worktree-workflow SOP

Traceability

  • [x] story:dev-execute label — present on board item
  • [ ] arch:X label — MISSING. Should be arch:hooks. Board item #241 has no arch label.
  • [x] Forgejo issue — claude-custom#136, open

File Targets

  • [ ] hooks/post-merge-rebase-check.sh — ISSUE: This file does not exist, which is expected for a new feature. However, the naming conflicts with the existing hooks/post-merge-rebase.sh (which fast-forwards local main after gh pr merge). The ticket does not acknowledge this existing hook or explain the relationship.
  • [ ] plugins/worktree-rebase/ — ISSUE: The plugins/ directory exists but contains only config files for a plugin manager (blocklist.json, config.json, installed_plugins.json). There is no precedent for custom skill/plugin code living here. All custom automation lives in hooks/. This target path is likely wrong.

Repo Placement

OK — the issue is filed on forgejo_admin/claude-custom and the work targets hooks in that repo. The SOP update (worktree-workflow) would be a pal-e-docs change via Betty Sue/Dottie, not this agent — that is acceptable but should be noted in the Checklist.

Dependencies

  • Existing hooks solve part of the problem. post-merge-rebase.sh and post-mcp-merge-rebase.sh already fast-forward local main after PR merges. This means local main stays current automatically whenever the agent itself merges a PR. The remaining gap is: when a different agent (or CI) merges to main, the current agent's worktree branch falls behind. The ticket's Context section implies zero detection exists today, which is inaccurate.
  • Board item #418 (cross-repo worktree isolation, pal-e-platform#188) is related — it addresses parallel agent isolation for non-spawning repos. The two tickets are complementary but not dependent. The scope boundary should be explicit: #136 = branch freshness detection, #418 = workspace isolation.
  • No blockers found. No items in in_progress block this work.

Acceptance Criteria

  • AC1: "When main advances past a worktree branch, the divergence is detected" — Ambiguous. Detected when? On session start? On every tool call? On PR creation? The trigger event is unspecified. An agent cannot verify this without knowing when detection should fire.
  • AC2: "When conflicts exist, the agent is notified before PR creation" — Testable but vague on mechanism. Is this a PreToolUse hook on gh pr create? A SessionStart check?
  • AC3: "When no conflicts exist, rebase happens automatically or is flagged as safe" — "or" is ambiguous. Auto-rebase and "flag as safe" are very different implementations. Pick one.

Blast Radius

  • Auto-rebase risk: Automatic rebasing of in-progress branches can silently introduce merge conflicts mid-work. If the hook fires during a tool call, it could corrupt the working tree. The ticket should explicitly address when auto-rebase is safe vs. when notification-only is appropriate.
  • Existing hooks: The post-merge-rebase.sh and post-mcp-merge-rebase.sh hooks handle the same-session case. Adding another rebase hook creates risk of double-rebasing or conflicting fast-forward logic. The relationship must be documented.
  • Worktree-workflow SOP: The SOP already says "Always git fetch + pull before spawning agents." The pre-spawn freshness check is manual convention, not enforcement. This ticket could upgrade that to enforcement, but that intent is not stated.

Recommendation

Before this ticket is READY, fix these issues:
  • Add arch:hooks label to the board item for traceability.
  • Acknowledge existing hooks. The Context section should reference post-merge-rebase.sh and post-mcp-merge-rebase.sh and explain what gap remains after their coverage. The remaining gap is specifically: detection when main advances due to external merges (other agents, CI, manual pushes).
  • Fix file targets. Remove plugins/worktree-rebase/ — the plugins directory is not for custom code. Replace with a hook path (e.g., hooks/check-branch-freshness.sh) that follows existing naming conventions.
  • Sharpen acceptance criteria. Specify the trigger event (SessionStart? PreToolUse on gh pr create?). Remove the "or" in AC3 — pick auto-rebase or notification. Recommendation: notification-only is safer; auto-rebase has blast radius concerns.
  • Add SOP update to Checklist. The Checklist says "worktree-workflow SOP updated" but does not note this is a cross-repo pal-e-docs change. Clarify that SOP update is a separate deliverable via Betty Sue.