pal-e-docs

Review: Migrate MCP tool references -- pal-e-docs to paldocs + archive old server

review-1565-2026-06-22 Review

review ready
Project

Verdict: APPROVED

Round 2 review. Ticket is well-scoped after refinement. Missing file targets from Round 1 were added (commands, tests, hooks). PAL_E_API_URL correctly deferred. Minor issues remain but are informational, not blockers.

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- depends on paldocs#54
  • [x] Repo -- ldraney/claude-custom (primary), ldraney/paldocs (cleanup)
  • [x] User Story -- As the Overseer...
  • [x] Context -- thorough breakdown of reference categories and counts
  • [x] File Targets -- comprehensive list with should/should-not-touch sections
  • [x] Feature Flag -- none (clean swap)
  • [x] Acceptance Criteria -- 6 criteria, all testable
  • [x] Test Expectations -- automated and manual, includes grep commands
  • [x] Constraints -- dependency ordering, human gate, rollback plan
  • [x] Checklist -- 16-item checklist
  • [x] Related -- project, story, arch, upstream references

Traceability

  • [x] story:consolidation label -- story-paldocs-consolidation
  • [x] story note verified -- found in project-paldocs user-stories section
  • [x] arch:mcp label -- architecture component MCP
  • [ ] arch note MISSING -- search for "arch-mcp" returned zero results. [SCOPE] Create architecture note arch-mcp for MCP component
  • [x] Forgejo issue -- ldraney/paldocs#55, open

File Targets

  • [x] settings.json -- verified: 4 mcp__pal-e-docs matcher refs
  • [x] settings.local.json -- verified: 1 "pal-e-docs" ref in enabledMcpjsonServers
  • [x] agents/overseer.md -- verified: 1 mcp__pal-e-docs + 10 name refs (ticket claims 11 total, correct)
  • [x] agents/qa.md -- verified: has mcp__pal-e-docs refs + 4 name refs
  • [x] hooks/*.sh -- verified: 8 hooks with mcp__pal-e-docs refs, 16 hooks total with any pal-e-docs ref
  • [x] hooks/boards-config.sh -- verified: "board-pal-e-docs" slug ref
  • [x] hooks/cleanup-worktrees.sh -- verified: 3 repo path refs ($HOME/pal-e-docs etc)
  • [x] hooks/stop-doc-checkin.sh -- verified: 1 mcp ref + 2 name refs
  • [x] skills/*.md -- verified: 8 skill files with mcp__pal-e-docs refs
  • [x] commands/update-docs.md -- verified: 7 mcp__pal-e-docs refs
  • [x] docs/*.md -- verified: 8 doc files with pal-e-docs refs
  • [x] tests/test_check_board_advance.sh -- verified: 33 mcp__pal-e-docs refs (ticket says ~50, actual is 33+2 name refs = 35 total)
  • [x] ~/.mcp.json -- verified: "pal-e-docs" entry exists
Informational -- test fixture count: Ticket says "~50 test fixture references" for test_check_board_advance.sh. Actual count is 33 mcp__pal-e-docs + 2 name refs = 35 total. Not a blocker.
Informational -- hook count: Ticket says "15 hook scripts" for MCP tool name references. Actual: 8 hooks with mcp__pal-e-docs tool refs, 16 hooks total with any pal-e-docs reference (including name-only and PAL_E_API_URL). The hooks/*.sh glob instruction says "grep for mcp__pal-e-docs" which would miss 4 hooks with name-only refs (boards-config.sh, check-agent-spawn.sh, cleanup-worktrees.sh, inject-subagent-context.sh). However, 3 of these 4 are already called out as specific File Targets, and inject-subagent-context.sh is covered by the glob. Not a blocker.
Informational -- implicit targets covered by globs/intent:
  • agents/dev.md -- 2 name refs. Covered: inject-subagent-context.sh generates the context strings containing these refs, so updating the hook updates dev.md's runtime behavior. The static file itself also needs updating.
  • tests/test_check_note_template.sh -- 23 mcp__pal-e-docs refs. NOT listed explicitly but covered by tests/ intent if agent greps broadly.
  • hooks/inject-subagent-context.sh -- 3 name refs. Covered by hooks/*.sh glob.
  • hooks/check-agent-spawn.sh -- 1 name ref. Covered by hooks/*.sh glob.
  • README.md -- 1 pal-e-docs ref. Covered by docs intent.
  • spikes/133-penny-mcp-inventory.md -- 1 ref. Historical spike, may or may not need updating.

Repo Placement

OK. Ticket correctly identifies ldraney/claude-custom as primary and ldraney/paldocs for cleanup. Issue filed on paldocs is correct -- consolidation story lives there. Cross-repo concern tracked on consumer side is fine.

Dependencies

  • Upstream blocker: paldocs#54 (Paldocs MCP server) -- board item #1564, currently in backlog. Must be done first. Correctly documented.
  • Upstream for PAL_E_API_URL: paldocs#57-#59 (API endpoints) -- correctly deferred.
  • No downstream blockers on the board for this item.
  • Related parallel work: paldocs#52 (embeddings), #61 (hybrid search) -- not blocking.

Acceptance Criteria

6 ACs, all agent-verifiable:
  • AC1: grep mcp__pal-e-docs returns zero -- automatable, clear.
  • AC2: grep pal-e-docs in non-git non-memory files shows only PAL_E_API_URL refs remaining -- automatable. Note: 87 non-mcp, non-API_URL name references exist today across 30 files. Agent must rename ALL "pal-e-docs" strings (not just mcp__ prefix) except PAL_E_API_URL lines. The AC is correct and comprehensive.
  • AC3: session shows only paldocs MCP server -- manual verification.
  • AC4: hooks match mcp__paldocs__* tool names -- verifiable via settings.json grep.
  • AC5: ~/.mcp.json has no pal-e-docs entry -- automatable.
  • AC6: test_check_board_advance.sh passes -- automatable. Note: test_check_note_template.sh should also pass but is not mentioned in AC. Covered by general "no regressions" in checklist.

Blast Radius

  • 43 files confirmed. Grep output matches ticket claim exactly.
  • Mixed-reference hooks (6): check-board-advance.sh, check-issue-template.sh, check-note-template.sh, check-pr-template.sh, gate-validation-done.sh, session-start-context.sh all have BOTH rename-target refs AND PAL_E_API_URL refs. Agent must use line-level precision, not whole-file find-replace.
  • Highest complexity: session-start-context.sh (16 refs: 2 mcp + 7 name + 7 PAL_E_API_URL), block-docs-writes.sh (23 refs: 20 mcp + 3 name).
  • No sibling services affected outside claude-custom.

Decomposition Assessment

43 files across 1 primary repo + ~/.mcp.json. 6 ACs. The work is fundamentally a find-and-replace with careful exclusions (PAL_E_API_URL lines). Despite high file count, this is a single conceptual operation executable in one agent pass via grep + Edit. Estimated agent time: ~5 minutes. Borderline on the 5-minute rule but decomposition would add coordination overhead for what is a rename operation. No decomposition needed.

Recommendation

[SCOPE] Create architecture note arch-mcp for the MCP component. The arch:mcp label is used on board items #1564 and #1565 but no backing note exists in pal-e-docs.
All other aspects are solid. Ticket is APPROVED for backlog-to-todo after arch note is created.