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

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