Project-Kiln/docs/handoff/phase-1-codex-cli.md

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 check passes.

Before coding, split this phase into narrow tasks and present any contract choice that would materially constrain future adapters to the project owner.