ombi-mcp/docs/megaplans/m2/00-phase-index.md

Phase 00 — Phase Index & Global Invariants

Objective

Provide the master index for Megaplan M2 execution: the ordered phase table, the global invariants that constrain every phase, the deterministic execution order, and the global acceptance matrix checked after Phase 02 completes. This file carries no schema or code mutations of its own; it is the coordination document for Phases 01–02.

Megaplan M2 fixes Gitea issue #1 (read_media details resolves wrong TV series) end-to-end. The root cause is upstream: Ombi's v2 TV-details routes are TMDB-keyed aliases despite the {tvdbId} placeholder name, and the TVMaze-backed v1 TV search emits the TVDB id in a field named theMovieDbId. The fix repoints TVDB lookups to the real v1 info route, relabels identifiers per origin route, and adds a tvmaze identifier namespace.

Prerequisites

• None. This is the first artefact read by any executing agent.
• Source of truth for all phase content: Megaplan M2 (session plan sincere-hide, created 2026-09-19) and Gitea issue #1. Every phase file in this directory is self-contained — an executor must be able to complete any phase with zero re-derivation from the Megaplan.
• Root cause verified against Ombi-app/Ombi develop and a live 4.53.10 instance; evidence is cited inline in Phase 01.

Specification

Phase table

ID	Title	Prerequisite phases	Target artefacts	Gate status
00	Phase Index & Global Invariants	—	docs/megaplans/m2/00-phase-index.md	This file
01	TV Identifier Namespaces	00	internal/tools/media.go, project.go, search.go, discover.go, library.go, requestswrite.go, families.go, internal/integration_test/{mockombi_test,contract_test,live_test}.go	See 01-tv-identifier-namespaces.md
02	Specification Harmonisation	01	docs/schema/02-tool-mapping.md, 03-input-schemas.md, 04-results.md, 05-endpoint-coverage.md, 06-verification.md, regenerated internal/tools/schemas.json	See 02-spec-harmonisation.md

Execution order

Phases execute strictly in numeric order: 00 → 01 → 02. Phase 01 lands the behaviour fix and its tests; Phase 02 harmonises the specification documents and regenerates the embedded schema bundle so the docs, the advertised schemas and the code agree.

Global invariants (apply to every phase)

• Evidence labels persist: Documented (RAML/upstream-source-backed), Design (intentional MCP contract), Verify (needs live confirmation).
• Counts that must not drift: 31 tools (14 read_*, 17 write_*); bundles 18 core / 5 moderation / 8 administration; ledger 377 operations / 321 paths. Disposition totals stay D 257 / A 37 / P 59 / I 12 / X 12 — ledger #193 demotes D→A (TMDB alias) and #235 promotes A→D (true TVDB route) for a net-zero change.
• The identifier.namespace enum gains exactly one value: tvmaze. The addition is additive and backwards-compatible.
• JSON Schema Draft 2020-12 everywhere; internal/tools/schemas.json is generated, never hand-edited — regenerate via go run ./tools/schemagen from the repository root.
• No tool accepts credentials; upstream auth is server config only.
• No environment-specific URL (never ombi.i3omb.com) in any committed file.
• Identifier labels are per origin route, never per upstream field name: TVMaze-backed v1 TV routes emit theMovieDbId as tvdb and seriesId as tvmaze; TMDB-keyed v2 routes emit theMovieDbId as tmdb.

Global acceptance criteria (checked after Phase 02)

• docs/megaplans/m2/ contains all 3 phase files, each with all mandatory sections.
• read_media details {media:tv, provider:tvdb} calls GET /api/v1/Search/tv/info/{id} and never /api/v2/Search/tv/{id}.
• write_request_create TV season mode with provider:tvdb expands episodes from the v1 info route.
• v1-origin TV results emit tvdb + tvmaze identifiers and no tmdb label; v2-origin TV results keep tmdb.
• projectFullTV preserves genre-string genres when the richer genres/cast object arrays are absent.
• identifier.namespace enum includes tvmaze in docs/schema/04-results.md and the regenerated internal/tools/schemas.json.
• CGO_ENABLED=0 go build ./..., go test ./..., go test -tags integration ./internal/integration_test/, go vet ./... and gofmt -l . are all clean.
• Live check: read_media details {media:tv, provider:tvdb, id:75150} returns Button Moon, matching read_search.

Target artefacts

• docs/megaplans/m2/00-phase-index.md — this file (created).
• docs/megaplans/m2/01-tv-identifier-namespaces.md
• docs/megaplans/m2/02-spec-harmonisation.md

No docs/schema/ or internal/ file is created or modified by Phase 00.

Verification gates

• All three files exist at the exact paths above.
• Every file contains all mandatory sections (Objective, Prerequisites, Specification, Target artefacts, Verification gates, Evidence labels — plus the # Phase 0N heading), none empty.
• 00-phase-index.md lists both execution phases with their target artefacts matching the Megaplan.
• No file modifies docs/schema/ or internal/ content — Phase 00 only writes docs/megaplans/m2/.

Evidence labels

• Documented — phase structure, mandatory sections and global invariants follow the M1 phase-file convention; the root-cause findings are verified against upstream source (TvSearchEngineV2.GetShowInformation → _movieApi.GetTVInfo; TvProfile mapping Id ← show.externals.thetvdb, SeriesId ← show.id; ProcessResult setting TheMovieDbId = Id) and a live 4.53.10 instance.
• Design — the per-origin identifier labelling and the tvmaze namespace are intentional MCP contract decisions.
• Verify — no new Verify claims introduced by this file; per-phase Verify items are listed in each phase file and consolidated in docs/schema/06-verification.md.