spec-kitty-tracker 0.3.0

Universal tracker interface, connector SDK, and sync engine for Spec Kitty

spec-kitty-tracker

Shared task-tracker abstraction layer for Spec Kitty CLI and SaaS.

Scope

1. Canonical issue model (CanonicalIssue, ExternalRef, CanonicalLink)
2. Tracker connector protocol with capability negotiation
3. Doctrine-style source-of-truth ownership policies
4. Conflict resolution and deterministic sync engine
5. Bidirectional mission/issue sync bridge with decision reference traceability
6. Connector registry and vendor connector implementations

Included Connectors

SaaS-Backed (via create_hosted_connector)

1. LinearConnector
2. JiraConnector
3. GitHubConnector
4. GitLabConnector

Out of Scope for Hosted Transport (this release)

5. AzureDevOpsConnector

Local/Native (direct construction)

6. BeadsConnector — local-first bd CLI adapter
7. FPConnector — local-first fp CLI adapter

Test/Reference

8. InMemoryConnector — fully functional reference connector

Installation

pip install -e .

For development tools:

pip install -e ".[dev]"

Quick Example

The primary integration path for SaaS-backed providers (Linear, Jira, GitHub, GitLab) uses create_hosted_connector with host-provided transport context. See Local/Native and Test Connectors for direct construction.

import asyncio
from spec_kitty_tracker import (
    create_hosted_connector,
    HostedConnectorRequest,
    LinearHostedParams,
    NangoConnectionContext,
    InMemoryIssueStore,
    OwnershipPolicy,
    OwnershipMode,
    SyncEngine,
)


async def main() -> None:
    # SaaS host provides identity context per operation
    nango_ctx = NangoConnectionContext(
        connection_id="user-connection-id",
        provider_config_key="linear",
        nango_secret_key="nango-secret",
    )

    # Factory constructs a connector routed through SaaS-owned transport
    connector = create_hosted_connector(HostedConnectorRequest(
        provider="linear",
        nango_context=nango_ctx,
        params=LinearHostedParams(team_id="TEAM-UUID"),
    ))

    store = InMemoryIssueStore()
    policy = OwnershipPolicy(mode=OwnershipMode.EXTERNAL_AUTHORITATIVE)
    engine = SyncEngine(connector=connector, store=store, policy=policy)

    async with connector:
        await engine.pull()


asyncio.run(main())

Local/Native and Test Connectors

For connectors that do not use SaaS-hosted transport, construct them directly.

Local/Native (Beads)

from spec_kitty_tracker import BeadsConnector, BeadsConnectorConfig

config = BeadsConnectorConfig(workspace="my-project", cwd="/path/to/beads")
connector = BeadsConnector(config)

Test/Reference (InMemory)

from spec_kitty_tracker import InMemoryConnector

connector = InMemoryConnector(name="test", workspace="test-ws")

Migration/Advanced (direct SaaS-backed, non-product path)

# For test, migration, or advanced SDK use cases only.
# The Spec Kitty CLI/SaaS product path should use create_hosted_connector().
from spec_kitty_tracker import LinearConnector, LinearConnectorConfig

config = LinearConnectorConfig(api_key="test-key", team_id="TEAM-1")
connector = LinearConnector(config)

Design Notes

1. The core contract is intentionally tracker-agnostic.
2. OwnershipPolicy makes source-of-truth behavior explicit and auditable.
3. SyncEngine supports pull, push, and bidirectional sync with conflict records.
4. Capability flags gate optional features (e.g., hierarchy, dependencies, webhooks).
5. Mission updates are idempotent and persist decision references back to source issues.

Docs

1. Architecture
2. Connector Contract
3. Doctrine Policy Modes
4. P0 Provider Matrix
5. WP04 Contract Alignment Notes
6. WP11 Sync Core Notes