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`.