pal-e-docs

Review: feat: update worktree isolation convention and hooks in claude-custom

review-1360-2026-06-06 Review

review ready
Project

Verdict: READY

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- Standalone, discovery context provided
  • [x] Repo -- ~/claude-custom (local-only, correctly noted)
  • [x] User Story -- As a platform operator...
  • [x] Context -- Explains the worktree isolation gap and agent misbehavior
  • [x] File Targets -- 3 modify targets, 2 do-not-touch targets
  • [x] Acceptance Criteria -- 6 criteria
  • [x] Test Expectations -- manual verification steps and run command
  • [x] Constraints -- 3 constraints documented
  • [x] Checklist -- present
  • [x] Related -- project and arch references

Traceability

  • [x] story:platform label -- "As a platform operator I want worktree isolation conventions and hooks consistently enforced"
  • [ ] story note MISSING -- [SCOPE] No "story:platform" entry exists in project-paldocs user-stories section. The project page only has story-paldocs-kanban and story-paldocs-project-pages. This is cross-cutting platform work that arguably belongs on project-pal-e-platform rather than project-paldocs. However, the ticket is tracked on board-paldocs per the "cross-cutting platform concern" rationale. Acceptable as foundational work -- story note creation is recommended but not blocking.
  • [x] arch:hooks label -- hooks infrastructure
  • [ ] arch note MISSING -- [SCOPE] No arch-hooks note found in pal-e-docs. Recommended to create architecture note documenting the hooks system. Not blocking for this ticket.
  • [x] Forgejo issue -- https://forgejo.tail5b443a.ts.net/ldraney/paldocs/issues/20, open

File Targets

  • [x] CLAUDE.md -- verified exists on main. Branch fix/worktree-isolation-convention has updated version with proper claude-custom (branch checkout) vs all-others (clone to /tmp) distinction. 14 lines added, 5 removed. Content is correct.
  • [x] hooks/cross-repo-isolation.sh -- verified exists. Lines 15, 65, 75 still contain stale "worktree isolation" / "spawning repo uses worktree isolation automatically" references. These need updating per ticket scope.
  • [x] hooks/cleanup-worktrees.sh -- verified exists. $HOME/paldocs is NOT in the REPO_DIRS array (confirmed by grep). Needs adding per ticket scope.
  • [x] hooks/block-claude-custom-main-edit.sh -- verified exists (do-not-touch, correctly excluded)
  • [x] hooks/check-claude-custom-clean.sh -- verified exists (do-not-touch, correctly excluded)

Repo Placement

OK. The issue is filed on ldraney/paldocs (Forgejo) but targets ~/claude-custom (local-only). This is correctly documented in the issue body: "local-only, no Forgejo remote -- tracked on paldocs board as cross-cutting platform concern." No mismatch.

Dependencies

  • Branch fix/worktree-isolation-convention already exists with CLAUDE.md changes -- agent should build on this branch rather than creating a new one.
  • Issue mentions "pre-existing uncommitted changes on main" for block-main-commits.sh, plugins/installed_plugins.json, settings.json. However, git status on main currently shows clean working tree. These were either already resolved or the issue body is stale on this point. AC #5 ("Pre-existing uncommitted changes on main are committed or intentionally discarded") is effectively pre-satisfied.
  • No blocking dependencies from other board items. #1359 (CI/CD infrastructure gaps) is in backlog and unrelated.

Acceptance Criteria

All 6 AC are verifiable by an agent:
  • AC 1-4: grep/read verification of specific file content changes
  • AC 5: git status check -- already satisfied (main is clean)
  • AC 6: git log/branch check -- verifiable
Test expectations include manual steps and a run command. The run command references "test-input.json" which does not exist -- agent would need to craft it. This is minor and within agent capability.

Blast Radius

  • hooks/pre-spawn-freshness.sh line 5 has a comment referencing "worktree isolation" -- cosmetic, not functional. Not in scope but worth noting.
  • No other hooks reference the stale "isolation: worktree" pattern.
  • The CLAUDE.md change on the branch also gets symlinked to ~/.claude/CLAUDE.md, so the convention update will propagate to all sessions automatically.
  • No downstream consumers affected beyond agent behavior alignment.

Decomposition Assessment

3 file targets in 1 repo, 6 AC, estimated agent work ~3-4 minutes. Branch already exists with partial work done (CLAUDE.md). No decomposition needed -- fits single agent pass.

Recommendation

  • [BODY] Update AC #5 to note that main is already clean: "Pre-existing uncommitted changes on main have been resolved (main is clean as of 2026-06-06)." Or remove this AC since it is pre-satisfied.
  • [SCOPE] Create user story entry for "story:platform" on project-paldocs user-stories section (or move ticket to project-pal-e-platform board if that is the correct home for platform-wide concerns).
  • [SCOPE] Create architecture note arch-hooks documenting the hooks system in claude-custom.
None of the above are blocking. The scope is solid and the ticket is implementable as-is.