Federico closed issue #18: Cleanup orphaned Docker & Docs milestone at Genealogy MCP / genealogy-mcp-codemode

Federico
2026-04-14T23:12:07Z

Problem Statement

Milestone 3 ("Docker & Docs") in genealogy-mcp-codemode has 4 open issues (#11, #15, #16, #17) that were orphaned when PRD #1 was closed prematurely with the v1.0.0 Library Core milestone. All 4 issues are labeled status::blocked with no notes and no progress, yet investigation shows most of the described work has already been completed in the consumer repos. The milestone is open with stale tickets, creating a misleading picture of outstanding work.

Solution

Triage each orphaned ticket against current codebase reality, close tickets where work is already done or no longer relevant, and execute the one remaining piece of real work: updating org-level and per-repo CLAUDE.md files to reflect mcp-codemode's place in the genealogy-mcp ecosystem.

Phase 1 — Triage (close stale tickets):

Close #11 (Docker reference templates) as won't-do: all three consumer repos (gramps-mcp, wikitree-mcp, gedcom-mcp) already have standardised Dockerfiles with multi-stage builds, non-root users, healthchecks, and OCI labels. Real implementations supersede templates.

Close #15 (Standardise Docker images) as completed: all three repos already have non-root user (mcp/gramps:1000), HEALTHCHECK directive, OCI labels, EXPOSE 8000, and .dockerignore. The work was done during migration but the ticket was never closed.

Close #17 (GitHub push-mirror) as won't-do: mcp-codemode is an internal library consumed as a dependency, not a public-facing MCP server. It does not need GitHub discoverability the way the server repos do.

Close Milestone 3 ("Docker & Docs").

Create a new milestone for this PRD's remaining work.

Phase 2 — Docs update (#16):

Update the local org-level CLAUDE.md (lives at ../CLAUDE.md relative to cloned repos) to add mcp-codemode to the Repo Map and update MCP-ORG rules to reference it as the canonical Code Mode implementation.

Submit standalone CLAUDE.md MRs to gramps-mcp, wikitree-mcp, gedcom-mcp, and mcp-codemode to add mcp-codemode dependency notes and align documentation style.

Re-link #16 to the new milestone.

User Stories

As a developer cloning the genealogy-mcp org, I want the org CLAUDE.md repo map to list mcp-codemode, so that I know it exists and understand its role as the shared library.

As a developer working in gramps-mcp, I want the repo's CLAUDE.md to mention that Code Mode infrastructure comes from mcp-codemode, so that I know where to look when debugging search/execute behavior.

As a developer working in wikitree-mcp or gedcom-mcp, I want the CLAUDE.md to reference mcp-codemode as a dependency, so that I understand the architectural relationship.

As a project maintainer, I want orphaned milestone tickets resolved, so that the issue tracker reflects actual outstanding work.

As a project maintainer, I want milestone 3 closed with clear resolution notes on each ticket, so that the audit trail explains why each ticket was closed the way it was.

As a developer reading gramps-mcp's CLAUDE.md, I want it to follow the same structure as wikitree-mcp and gedcom-mcp (Git Hosting Policy section, Makefile commands), so that the org has consistent documentation conventions.

As an AI assistant (Claude) working across the genealogy-mcp org, I want each repo's CLAUDE.md to reference the org-level CLAUDE.md, so that I can discover cross-repo conventions without being told.

As a project maintainer, I want the MCP-ORG rules in the org CLAUDE.md to reference mcp-codemode as the canonical implementation, so that new MCP servers follow the established pattern.

Implementation Decisions

One MR per repo for CLAUDE.md updates: gramps-mcp, wikitree-mcp, gedcom-mcp, and mcp-codemode each get a standalone docs-only MR. Small, independently reviewable and mergeable.

Org CLAUDE.md is a local file (not tracked in any GitLab repo). It lives at the parent directory level alongside cloned repos. Updates are manual local edits, not MRs.

No TODO.md updates: GitLab issues are the source of truth for work tracking. TODO.md files are not maintained.

Execution order is sequential: Phase 1 (triage) completes before Phase 2 (docs) begins. This ensures milestone/ticket state is clean before new work starts.

Ticket closure notes: each closed ticket gets a comment explaining the resolution rationale (e.g., "work already completed in wikitree-mcp!abc123" or "superseded by real implementations in consumer repos").

gramps-mcp CLAUDE.md alignment: bring gramps-mcp's CLAUDE.md structure in line with wikitree-mcp and gedcom-mcp (add Git Hosting Policy section, Makefile commands reference, org CLAUDE.md cross-reference).

Testing Decisions

This PRD is docs-only with no code changes. No automated tests are applicable.

Each per-repo MR should be verified by confirming the CLAUDE.md renders correctly in GitLab's Markdown preview.

Org CLAUDE.md update should be verified by checking that ../CLAUDE.md resolves correctly from each repo's working directory.

Out of Scope

Docker template examples in mcp-codemode: decided against (won't-do #11). The real Dockerfiles in consumer repos serve as the reference.

GitHub push-mirror for mcp-codemode: decided against (won't-do #17). Internal library does not need GitHub discoverability.

New features or code changes: this is purely a cleanup and documentation PRD.

Process changes: the root cause (premature PRD closure) is already covered by existing convention (feedback_prd_milestone_closure memory). No tooling or template changes needed.

Architecture documentation or ADRs: out of scope for this cleanup pass.

Further Notes

The original PRD #1 was closed on 2026-04-12 with milestone "v1.0.0 Library Core". Issues #11, #15, #16, #17 belonged to a separate milestone ("Docker & Docs") and were never picked up.

Investigation revealed that Docker standardisation (#15) was completed as part of the Migration milestone work, but the ticket was never closed — a classic case of work outpacing ticket hygiene.

The three other repos all have working GitHub push-mirrors (gramps-mcp, wikitree-mcp, gedcom-mcp), but mcp-codemode was explicitly excluded from this pattern per this triage.

Milestone Definition of Done

Do not close this issue or the milestone until every box is checked.

All child issues in the milestone are closed

CHANGELOG.md updated with all user-facing changes

README.md updated if public interface, configuration, or setup changed (N/A — docs-only PRD, no interface changes)

Version bumped in pyproject.toml (if releasing) (N/A — no release)

make ci passes on the final state of main (all 4 repo MR pipelines passed before merge)

PRD acceptance criteria (above) re-read and confirmed met

Any deferred scope captured as new issues (not left as mental notes) (pytest CVE → separate PRD, dependency_scanning → codemode#23)

Milestone closed on GitLab

This PRD issue closed