feat: checkpoint device agent runtime milestones

openspec/changes/skill-catalog-subscription/specs/skill-subscription-sync/spec.md

@@ -0,0 +1,61 @@
+## ADDED Requirements
+
+### Requirement: Pull-based sync from the Subscription Platform
+The system SHALL periodically fetch, from the external Subscription Platform, the set of skills the current deployment (tenant/device/agent) is entitled to, and SHALL apply creates/updates/removals to the local Skill Catalog to match that entitled set.
+
+#### Scenario: New skill appears after sync
+- **WHEN** the Subscription Platform reports a new entitled skill that does not yet exist locally
+- **THEN** the next sync cycle creates it in the local Skill Catalog
+
+#### Scenario: Updated skill content is refreshed
+- **WHEN** the Subscription Platform reports a newer version of a skill already present locally
+- **THEN** the next sync cycle updates the local copy to the newer version
+
+#### Scenario: Revoked entitlement removes local visibility
+- **WHEN** the Subscription Platform no longer includes a previously-entitled skill in the current entitled set
+- **THEN** the next sync cycle removes or marks that skill as no longer visible in the local Skill Catalog
+
+#### Scenario: Sync interval is configurable
+- **WHEN** the deployment is configured with a sync poll interval
+- **THEN** the system performs pull sync on approximately that interval without requiring a restart to take effect on the next cycle
+
+### Requirement: Optional push-triggered sync
+The system MAY support receiving a change notification (e.g. webhook) from the Subscription Platform, and WHEN it does, SHALL trigger an immediate out-of-cycle pull sync rather than waiting for the next poll interval; correctness of the catalog SHALL NOT depend on push notifications being delivered.
+
+#### Scenario: Push notification triggers immediate sync
+- **WHEN** a change notification is received from the Subscription Platform
+- **THEN** the system performs a pull sync immediately, independent of the regular poll schedule
+
+#### Scenario: No push configured still stays eventually consistent
+- **WHEN** push notifications are not configured or not received
+- **THEN** the local Skill Catalog still reflects the Subscription Platform's entitled set within one poll interval via the baseline pull sync
+
+### Requirement: Subscription-based visibility enforcement
+The system SHALL enforce, at both sync time and query time, that only skills belonging to the caller's currently active subscription(s) are stored as visible or returned by catalog queries.
+
+#### Scenario: Query-time re-check catches stale entitlement
+- **WHEN** a skill's entitlement has been revoked but the local cache has not yet completed its next sync cycle
+- **AND** a catalog query for that skill is made using already-known revocation information
+- **THEN** the system does not return that skill as visible, even though its record may still exist locally pending cleanup
+
+#### Scenario: Multiple subscriptions compose visibility
+- **WHEN** a deployment holds more than one active subscription, each entitling a different set of skills
+- **THEN** catalog queries return the union of skills entitled across all of that deployment's active subscriptions
+
+### Requirement: Sync client contract is transport-replaceable
+The system SHALL define the Subscription Platform integration (fetch entitled skills, optional change notification receipt) behind a single internal interface, so the concrete HTTP client/auth mechanism can be adjusted to match the real Subscription Platform API without changes to the Skill Catalog or MCP tool layers.
+
+#### Scenario: Sync client swap does not affect catalog/tools
+- **WHEN** the concrete Subscription Platform client implementation is replaced (e.g. different auth scheme or request/response shape)
+- **THEN** `skill-catalog` and `skill-mcp-tools` behavior and their own specs remain unaffected, as long as the new client still satisfies the sync interface
+
+### Requirement: Sync failure handling
+The system SHALL treat a failed sync attempt (network error, auth failure, malformed response) as non-fatal to already-cached skills: the local catalog SHALL continue serving its last-known-good state, and the failure SHALL be recorded/observable rather than silently discarded.
+
+#### Scenario: Sync failure preserves last-known catalog
+- **WHEN** a sync attempt fails due to a network or platform error
+- **THEN** the local Skill Catalog is left unchanged (not cleared or partially corrupted) and remains queryable using its last successfully synced state
+
+#### Scenario: Sync failure is observable
+- **WHEN** a sync attempt fails
+- **THEN** the system records the failure (e.g. last-error timestamp/reason) so it can be surfaced to operators rather than failing silently forever