feat: checkpoint device agent runtime milestones

docs/adr/0001-device-agnostic-runtime.md

@@ -0,0 +1,49 @@
+# ADR 0001: Device-Agnostic Runtime
+
+## Status
+
+Accepted
+
+## Context
+
+The project began as Apex Agent, centered on iPhone automation. The existing
+MVP already has a driver-independent `Driver` interface, WDA as the first
+driver, device lifecycle management, scene perception, runtime execution, task
+memory, and REST/MCP surfaces. The old names and package layout still implied
+that iPhone/WDA was the platform rather than the first adapter.
+
+The OpenSpec change `device-agent-runtime-foundation` records the detailed
+design decisions for this repositioning.
+
+## Decision
+
+Reposition the project as Device Agent Runtime:
+
+- Keep `core/` for shared domain models and errors.
+- Move the driver contract and concrete drivers into `driver/`.
+- Move device lifecycle management into `device/`.
+- Rename `vision/` to `perception/`.
+- Move driver-type factory selection into `driver/registry.py`.
+- Rename the shared error base to `DeviceRuntimeError`.
+- Treat iPhone/WDA as the first driver, not the product boundary.
+
+## Alternatives Considered
+
+Keeping the old Apex Agent/iPhone framing was rejected because it would make
+future Android, browser, desktop, and cloud-device support look like exceptions
+instead of first-class adapters.
+
+Eliminating `core/` entirely was rejected for this change because models such
+as `Scene`, `Task`, and `Device` are shared across several layers today.
+Forcing them into `perception/` or `runtime/` would add coupling without
+behavioral value.
+
+Keeping a deprecated `ApexAgentError` alias was rejected because there are no
+external consumers to preserve yet.
+
+## Consequences
+
+Future driver support is added in the driver layer and registry. Future
+perception techniques are added behind `PerceptionProvider`. User-facing
+runtime behavior remains unchanged, while package names and docs now match the
+device-agnostic direction.

docs/adr/0002-layered-hexagonal-architecture.md

@@ -0,0 +1,53 @@
+# ADR 0002: Layered Hexagonal Architecture
+
+## Status
+
+Accepted
+
+## Context
+
+Upcoming milestones add semantic understanding, world state, skill retrieval,
+workflow orchestration, multi-agent behavior, and cloud scheduling. Those
+features introduce LLM, embedding, HTTP, MCP, storage, and plugin concerns that
+must not leak into the device and domain contracts.
+
+The `device-agent-runtime-foundation` design decision D7 records the governing
+architecture: Hexagonal / Ports-and-Adapters with DDD-style domain boundaries.
+
+## Decision
+
+Use this dependency direction:
+
+1. `core`: domain models and errors. No framework, LLM, HTTP, MCP, or external
+   device SDK dependencies.
+2. `driver`: adapters over external device SDKs, implementing the `Driver`
+   contract.
+3. `device`: device lifecycle management and active driver ownership.
+4. `tools`: capability layer called by the runtime. Tools use device/driver
+   capabilities and do not import concrete drivers.
+5. `perception`: produces `Scene` behind `PerceptionProvider`.
+6. `storage`: persists timeline, task metadata, artifacts, and device config.
+7. `runtime`: application layer. Planner and Executor orchestrate tools,
+   perception, storage, retries, and task state. LLM-backed planning first
+   enters here.
+8. `api`: outermost transport adapter for REST, MCP, and future platform APIs.
+
+Future milestones must build bottom-up through these boundaries. LLM and
+transport dependencies may not be introduced into `core`, `driver`, `device`,
+or `tools`.
+
+## Alternatives Considered
+
+Leaving the layering implicit was rejected because upcoming AI-heavy milestones
+will otherwise tend to call LLM or transport APIs from convenient lower layers.
+
+Adding lint enforcement now was deferred. The written architecture is the
+current source of truth; mechanical enforcement can be added when a concrete
+boundary violation or second-driver pressure appears.
+
+## Consequences
+
+The runtime can add smarter planning and richer perception without changing the
+device capability contract. API and cloud concerns stay outside domain and
+adapter layers. Future OpenSpec designs must state how they uphold this
+dependency direction.