chore: establish phase 0 baseline

2026-07-18 18:20:34 -04:00
commit b38da7d53f
42 changed files with 2618 additions and 0 deletions
@@ -0,0 +1,42 @@
+# Phase 1 Codex CLI handoff
+
+## Objective
+
+Implement and aggressively test provider-independent versioned contracts before any real
+Steam, native, Heroic, Lutris, or UMU integration begins.
+
+## Required contract areas
+
+- game identity and installation-instance identity;
+- durable installation registry and move aliases;
+- store, adapter, configuration owner, execution backend, and runtime separation;
+- provider and runtime capability interfaces;
+- versioned JSON records and machine output;
+- argument-safe launch plans and dry-run representation;
+- lifecycle confidence and its allowed policy effects;
+- structured errors, including ambiguous-name candidates and unsupported versions;
+- versioned TOML configuration precedence and provenance;
+- a deterministic mock adapter covering success, absence, ambiguity, malformed input,
+  unsupported capability, moved installation, and launch-planning failure.
+
+## Exclusions
+
+- No real provider parsing or process launching.
+- No daemon, IPC transport, cache, SQLite discovery index, GUI, session supervisor, or
+  installation management.
+- No public API stability claim.
+- No final public naming work.
+
+## Required gates
+
+- Unit tests for value objects, parsing, validation, precedence, and errors.
+- Contract tests for serialization, schema rejection, capability behavior, and launch
+  plans.
+- Isolated integration tests using only synthetic temporary state and the mock adapter.
+- Adversarial tests required by R-024 and the threat model where Phase 1 code accepts
+  strings, paths, manifests, environment values, or serialized data.
+- `make verify` and `make audit` both pass.
+
+Before coding, split this phase into narrow tasks and present any contract choice that
+would materially constrain future adapters to the project owner.
+