Phase K Step 1: Pool metadata schema + file

[aberson]

Build step 1 of 5 — Phase K (umbrella #215)

Build doc: documentation/plans/phase-k-build-plan.md §4 Step K.1

What to build

Define data/pool_metadata.json schema. Write the schema as a Python TypedDict in src/orchestrator/pool_metadata.py. Add load/save helpers with file-locking — concurrent evolve runs could write simultaneously and the file is cross-version state, not per-version (feedback_per_version_vs_cross_version_data_dir.md applies).

Existing context

• Per-version state lives under bots/<version>/data/. This file does NOT — it's pool-wide. Place at data/pool_metadata.json at repo root.
• File-locking: cross-platform fcntl doesn't work on Windows; use portalocker (already a dep) or os.replace atomic-rename pattern from existing evolve code.
• Schema (per build doc §5):

  class PoolMetadata(TypedDict):
      version: str
      themes: list[str]
      notable_moments: list[str]
      build_order_signature: list[tuple[str, int]]
      created_at: str  # ISO timestamp
      inferred_themes: list[str]  # auto-tagged, separate from explicit

• Top-level shape: {"versions": {"v0": PoolMetadata, "v1": ...}}.

Files to modify/create

• src/orchestrator/pool_metadata.py — NEW. TypedDict + load/save helpers + file-locking.
• data/pool_metadata.json — NEW (initial empty {"versions": {}}).
• tests/test_pool_metadata.py — NEW.

Done when

• Round-trip load/save tests pass.
• File-locking test passes (two writers serialize correctly).
• uv run mypy src --strict clean.
• uv run ruff check . clean.

Flags

--reviewers code --isolation worktree

Depends on

none.

Produces

pool_metadata.py module + initial empty JSON file + tests.

---

Synced from build doc by /repo-sync