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

Phase 00 — Phase Index & Global Invariants

Objective

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

Prerequisites

• None. This is the first artefact read by any executing agent.
• Source of truth for all phase content: Megaplan M1 (session plan deluxe-crystal, created 2026-09-18). 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.

Specification

Phase table

ID	Title	Prerequisite phases	Target artefacts	Gate status
00	Phase Index & Global Invariants	—	docs/megaplans/m1/00-phase-index.md	This file
01	Tool Namespace & Catalogue Realignment	00	docs/schema/02-tool-mapping.md, 03-input-schemas.md, 04-results.md, 05-endpoint-coverage.md, 06-verification.md, 07-settings-types.md, README.md, AGENTS.md (names only)	See 01-tool-namespace-catalogue.md
02	Upstream Authentication & Credential Architecture	00 (01 recommended for name consistency in prose)	docs/schema/01-authentication.md	See 02-upstream-authentication.md
03	Input Schema Defect Rectification	01 (rename must land first so ## headings match)	docs/schema/03-input-schemas.md	See 03-input-schema-rectification.md
04	Semantic Abstraction & Enum Translation Layer	01 (names); informs 03, 05, 06	docs/schema/02-tool-mapping.md (routing rule #4), 06-verification.md, internal translate package baseline (documented)	See 04-enum-translation-layer.md
05	Output Schema Modularisation	01 (operation enum values), 04 (label enums in issue/retry defs)	docs/schema/04-results.md	See 05-output-schema-modularisation.md
06	Specification Harmonisation & Go Interface Baseline	01–05	docs/schema/02-tool-mapping.md, 05-endpoint-coverage.md, 06-verification.md, 07-settings-types.md, README.md, new docs/schema/08-go-baseline.md, AGENTS.md	See 06-specification-harmonisation.md

Execution order

Phases execute strictly in numeric order: 00 → 01 → 02 → 03 → 04 → 05 → 06. Phase 01 (tool rename) is a textual precondition for clean diffs in every later phase; Phase 00 must complete first.

Global invariants (apply to every phase)

• Evidence labels persist: Documented (RAML-backed), Design (intentional MCP contract), Verify (needs live confirmation). The new enum label maps are Design contracts backed by upstream-source evidence; per-version drift stays a Verify item.
• Counts that must not drift: 31 tools (14 read_*, 17 write_*); bundles 18 core / 5 moderation / 8 administration; ledger 377 operations / 321 paths / dispositions D 257, A 37, P 59, I 12, X 12.
• JSON Schema Draft 2020-12 everywhere; every embedded JSON block must re-validate with jsonschema's Draft202012Validator.
• All embedded JSON schemas keep "$schema": "https://json-schema.org/draft/2020-12/schema", additionalProperties:false, minLength:1 on free text, integer minimum:1 IDs.
• Tool names are snake_case and start with read_ (GET/idempotent) or write_ (state-mutating, including the mutating GET newsletter unsubscribe and POST reads that can send messages).
• Bundle names core/moderation/administration are server-side policy groups only — never name segments.
• No tool accepts credentials; upstream auth is server config only.
• No environment-specific URL (never ombi.i3omb.com) in any committed doc.
• operation inside the output envelope equals the tool name (new names), not an upstream route.

Global acceptance criteria (checked after Phase 06)

• docs/megaplans/m1/ contains all 7 phase files, each with all mandatory sections.
• docs/schema/ reflects every defect fix: new tool namespace, JWT-first auth, by_request album enum, optional is_4k, season mode, string enums, relaxed status, sort_direction, unified override keys, no single-element oneOf, modular outputs, harmonised names.
• Every embedded JSON block in docs/schema/*.md and docs/megaplans/m1/*.md parses and validates under Draft202012Validator.
• Positive fixtures: {"action":"list","media":"movie"} valid for read_requests; {"action":"movie","tmdb_id":1} valid for write_request_create; {"mode":"season","season_numbers":[1,2]} valid in selection; {"request_type":"tv","request_id":1} valid for write_request_reprocess; {"issue_id":1,"comment":"x"} valid for write_issue_comment.
• Negative fixtures: {} rejected by all write tools; {"action":"list","media":"album","status":"unavailable"} rejected (album has no unavailable route); {"action":"by_request","media":"artist","request_id":1} rejected by read_media; integer status/request_type values rejected; is_4k non-boolean rejected.
• grep -c confirms exactly 31 ## read_*/## write_* sections in 03-input-schemas.md (14+17).
• No instance URL or secret anywhere in committed docs.

Target artefacts

• docs/megaplans/m1/00-phase-index.md — this file (created).
• docs/megaplans/m1/01-tool-namespace-catalogue.md
• docs/megaplans/m1/02-upstream-authentication.md
• docs/megaplans/m1/03-input-schema-rectification.md
• docs/megaplans/m1/04-enum-translation-layer.md
• docs/megaplans/m1/05-output-schema-modularisation.md
• docs/megaplans/m1/06-specification-harmonisation.md

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

Verification gates

• All seven files exist at the exact paths above.
• Every file contains all seven mandatory sections (Objective, Prerequisites, Specification, Target artefacts, Verification gates, Evidence labels — plus the # Phase 0N heading), none empty.
• Every JSON block inside the phase files parses and validates under Draft202012Validator.
• 00-phase-index.md lists all six execution phases with their target artefacts matching the Megaplan.
• No file modifies docs/schema/ content — Phase 00 only writes docs/megaplans/m1/.

Evidence labels

• Documented — phase structure, mandatory sections, and global invariants are copied verbatim from the authoritative Megaplan.
• Design — the phase table's target-artefact column expresses the Megaplan's locked decisions D1–D7.
• Verify — no new Verify claims introduced by this file; per-phase Verify items are listed in each phase file.