gronod
722108ebd0
Schema docs (docs/schema) cover tool mapping, input/output contracts and endpoint coverage for all 31 MCP tools; megaplan M1 phases 01-03 applied (namespace rename to read_*/write_*, input schema rectification). Go module provides config loading, Ombi client, and tool registry skeleton for implementation.
77 lines
6.6 KiB
Markdown
77 lines
6.6 KiB
Markdown
# 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.
|