agentic-mobile-control/openspec/changes/uv-workspace-packaging/specs/workspace-packaging/spec.md

ADDED Requirements

Requirement: Repository uses a uv workspace with a shared lockfile

The repository SHALL define a uv workspace containing the root device-agent-runtime project and the extracted device-cloud-platform project, and SHALL commit one generated uv.lock that resolves all workspace members.

Scenario: Clean workspace synchronization

• WHEN a developer synchronizes the repository from a clean checkout using uv
• THEN uv installs the workspace members and their locked dependencies without requiring manual editable-install commands

Scenario: Lockfile consistency check

• WHEN CI validates dependency metadata without updating dependencies
• THEN the committed lockfile is accepted as current for every workspace member

Requirement: Cloud packaging has an explicit one-way Runtime dependency

The device-cloud-platform project SHALL declare device-agent-runtime as a uv workspace dependency, and the device-agent-runtime project MUST NOT depend on device-cloud-platform or import the cloud package.

Scenario: Cloud modules consume Runtime contracts

• WHEN the cloud platform is installed through the workspace
• THEN its imports of existing Runtime, workflow, storage, and driver contracts resolve through the declared Runtime workspace dependency

Scenario: Runtime remains cloud-independent

• WHEN dependency-direction tests inspect Runtime-owned source packages
• THEN no Runtime-owned package imports cloud or requires the cloud distribution to execute existing local capabilities

Requirement: Existing cloud import paths and behavior remain compatible

The packaging migration SHALL preserve the existing cloud.* Python import paths and SHALL NOT change REST, MCP, scheduling, dispatch, persistence, or SDK behavior.

Scenario: Existing cloud tests run after extraction

• WHEN the existing cloud test suite runs from the workspace root after the package is moved
• THEN the tests import the same cloud.* modules and retain their pre-migration behavior

Scenario: Local Runtime runs without cloud application members

• WHEN a developer starts or tests the root Runtime project without starting a cloud application
• THEN existing Runtime entry points and local device behavior remain available

Requirement: Workspace members are independently buildable and selectable

Each Python workspace member SHALL contain valid build metadata, SHALL produce an installable distribution, and SHALL support member-scoped uv commands while root-level tests remain supported.

Scenario: Build all distributions

• WHEN CI builds the Runtime and cloud platform workspace members
• THEN each build produces a wheel whose declared packages can be imported in an isolated environment

Scenario: Run a member-scoped command

• WHEN a developer selects a workspace member with uv's package selection option
• THEN the command executes with that member's declared dependencies and workspace sources

Requirement: Frontend package management remains separate

The Vue/Vite console project SHALL remain managed by its existing JavaScript package manager and SHALL NOT become a Python uv workspace member.

Scenario: Synchronize Python workspace

• WHEN a developer runs uv synchronization at the repository root
• THEN uv does not install or modify the console's JavaScript dependencies