Feature: Worktree isolation enforcement gaps -- hooks, SOP alignment, cleanup coverage

forgejo_admin commented

2026-03-28 01:56:22 +00:00

Contributor

Type

Feature

Lineage

Standalone — discovered during session reviewing worktree SOP alignment.
Related to forgejo_admin/pal-e-platform #188 (cross-repo isolation umbrella).

Repo

forgejo_admin/claude-custom

User Story

As a dev agent
I receive a well-scoped Forgejo issue and work in an isolated worktree
So that my changes don't pollute the main checkout or conflict with other agents

Context

Worktree workflow audit found 5 gaps between SOP documentation and actual enforcement. The highest severity gap: no hook enforces git fetch + pull before agent spawn, which caused a production incident (2026-03-06, 40K+ tokens wasted on stale branch).

File Targets

Files to modify (Dev agent — Ticket A):

hooks/check-agent-spawn.sh -- add freshness check (git fetch + compare HEAD to origin/main)
hooks/cleanup-worktrees.sh lines 17-25 -- update REPO_DIRS to cover all 17+ platform repos
agents/qa.md -- add isolation: worktree to frontmatter (reconcile with agent-spawn-requirements.json)
CLAUDE.md -- add cross-reference to worktree-workflow SOP

Files to update (Dottie — Ticket B, depends on Ticket A merging):

pal-e-docs note worktree-workflow -- align with implemented freshness hook
pal-e-docs note sop-claude-config-development -- add cross-reference to worktree-workflow

Decomposition

This issue decomposes into 2 sequential agent dispatches:

Ticket A (Dev agent on claude-custom): Items 1-4 above. Hook code changes + config fixes. Creates a PR.

Ticket B (Dottie on pal-e-docs): Items 5-6 above. SOP updates via MCP tools. Depends on Ticket A merging first — SOPs must describe the implemented hooks, not planned hooks.

Acceptance Criteria

check-agent-spawn.sh blocks spawn when local main is behind origin/main
cleanup-worktrees.sh covers all repos in ~/
agents/qa.md has isolation: worktree in frontmatter
CLAUDE.md references worktree-workflow SOP
worktree-workflow SOP describes freshness hook (after Ticket A merges)
sop-claude-config-development cross-references worktree-workflow

Test Expectations

Manual test: spawn dev agent with stale local main, verify blocked
Manual test: spawn dev agent with up-to-date main, verify allowed
Run command: manual hook testing via Claude Code session

Constraints

Freshness check must be fast (<2 sec) — use git fetch --dry-run or git rev-list HEAD..origin/main --count
Don't break existing spawn flow for agents that don't need worktrees (Dottie, Penny)

Checklist

PR opened (Ticket A)
Tests pass
No unrelated changes
SOPs updated (Ticket B)

project-pal-e-agency
forgejo_admin/pal-e-platform #188 -- cross-repo isolation umbrella
forgejo_admin/claude-custom #136 -- worktree auto-rebase (complementary)

Review History

review-184-2026-03-27: NEEDS_REFINEMENT — Missing explicit decomposition section and ordering constraint. Fixed in this update.

### Type Feature ### Lineage Standalone — discovered during session reviewing worktree SOP alignment. Related to `forgejo_admin/pal-e-platform #188` (cross-repo isolation umbrella). ### Repo `forgejo_admin/claude-custom` ### User Story As a dev agent I receive a well-scoped Forgejo issue and work in an isolated worktree So that my changes don't pollute the main checkout or conflict with other agents ### Context Worktree workflow audit found 5 gaps between SOP documentation and actual enforcement. The highest severity gap: no hook enforces `git fetch + pull` before agent spawn, which caused a production incident (2026-03-06, 40K+ tokens wasted on stale branch). ### File Targets Files to modify (Dev agent — Ticket A): - `hooks/check-agent-spawn.sh` -- add freshness check (git fetch + compare HEAD to origin/main) - `hooks/cleanup-worktrees.sh` lines 17-25 -- update REPO_DIRS to cover all 17+ platform repos - `agents/qa.md` -- add `isolation: worktree` to frontmatter (reconcile with agent-spawn-requirements.json) - `CLAUDE.md` -- add cross-reference to worktree-workflow SOP Files to update (Dottie — Ticket B, depends on Ticket A merging): - pal-e-docs note `worktree-workflow` -- align with implemented freshness hook - pal-e-docs note `sop-claude-config-development` -- add cross-reference to worktree-workflow ### Decomposition This issue decomposes into 2 sequential agent dispatches: **Ticket A (Dev agent on claude-custom):** Items 1-4 above. Hook code changes + config fixes. Creates a PR. **Ticket B (Dottie on pal-e-docs):** Items 5-6 above. SOP updates via MCP tools. Depends on Ticket A merging first — SOPs must describe the *implemented* hooks, not *planned* hooks. ### Acceptance Criteria - [ ] `check-agent-spawn.sh` blocks spawn when local main is behind origin/main - [ ] `cleanup-worktrees.sh` covers all repos in ~/ - [ ] `agents/qa.md` has `isolation: worktree` in frontmatter - [ ] `CLAUDE.md` references worktree-workflow SOP - [ ] worktree-workflow SOP describes freshness hook (after Ticket A merges) - [ ] sop-claude-config-development cross-references worktree-workflow ### Test Expectations - [ ] Manual test: spawn dev agent with stale local main, verify blocked - [ ] Manual test: spawn dev agent with up-to-date main, verify allowed - Run command: manual hook testing via Claude Code session ### Constraints - Freshness check must be fast (<2 sec) — use `git fetch --dry-run` or `git rev-list HEAD..origin/main --count` - Don't break existing spawn flow for agents that don't need worktrees (Dottie, Penny) ### Checklist - [ ] PR opened (Ticket A) - [ ] Tests pass - [ ] No unrelated changes - [ ] SOPs updated (Ticket B) ### Related - `project-pal-e-agency` - `forgejo_admin/pal-e-platform #188` -- cross-repo isolation umbrella - `forgejo_admin/claude-custom #136` -- worktree auto-rebase (complementary) ### Review History - review-184-2026-03-27: NEEDS_REFINEMENT — Missing explicit decomposition section and ordering constraint. Fixed in this update.

forgejo_admin commented

2026-03-28 04:55:17 +00:00

Author

Contributor

Closing as superseded by targeted tickets:

#193 (pre-spawn freshness hook)
#194 (post-merge worktree cleanup)
#195 (cleanup-worktrees.sh repo list fix)

These three tickets address the enforcement gaps identified in this issue with specific, reviewable scope.

Closing as superseded by targeted tickets: - #193 (pre-spawn freshness hook) - #194 (post-merge worktree cleanup) - #195 (cleanup-worktrees.sh repo list fix) These three tickets address the enforcement gaps identified in this issue with specific, reviewable scope.