Skip to content

Contract pinning workflow (`spec-kitty-events`)

Who is this for (1)

Contract pinning workflow (spec-kitty-events)

Status: stable (2026-04-26)

Authority:

Why this exists

Contract tests under tests/contract/ are the hard mission-review gate (FR-023). They pin the upstream spec-kitty-events envelope at the resolved version (uv.lock), not at a literal hard-coded one. Bumping spec-kitty-events without regenerating the snapshot is, by design, a hard contract failure with a clear diagnostic.

The two-step bump workflow

When you need to bump spec-kitty-events:

  1. Update the dependency.

    Either edit the compatibility range in pyproject.toml:

    [project]
    dependencies = [
    # ...
    "spec-kitty-events>=X.Y.0,<X+1", # choose the supported range; uv.lock records the exact version
    # ...
    ]

    …or just let uv pick a newer compatible version:

    Terminal window
    uv lock --upgrade-package spec-kitty-events
    uv sync
  2. Regenerate the envelope snapshot.

    Terminal window
    python scripts/snapshot_events_envelope.py --force

    The script:

    • Resolves the version from uv.lock (falling back to importlib.metadata).
    • Captures spec_kitty_events.Event.model_json_schema().
    • Writes tests/contract/snapshots/spec-kitty-events-<resolved-version>.json.
    • Prints the resolved version it pinned, so you can sanity-check against uv.lock.
  3. Verify the contract gate is green.

    Terminal window
    pytest tests/contract/ -q

    This is the same one-liner the mission-review skill runs.

  4. Commit both files together.

    Terminal window
    spec-kitty safe-commit --message "chore: bump spec-kitty-events to <version>" \
    pyproject.toml \
    uv.lock \
    tests/contract/snapshots/spec-kitty-events-*.json

If you skip step 2, the contract test tests/contract/test_events_envelope_matches_resolved_version.py will fail with a structured message pointing at this doc and the snapshot script. That is intentional.

What the snapshot script does and does not do

The script (scripts/snapshot_events_envelope.py) is intentionally small. It:

  • Does resolve the version from uv.lock first, then importlib.metadata.
  • Does capture the full Event JSON schema, plus a sorted list of field names and required-field names for ergonomic diffs.
  • Does print the resolved version it used.
  • Does not overwrite an existing snapshot unless --force is passed.
  • Does not install spec-kitty-events. Run uv sync first.

Useful flags:

FlagPurpose
--output-dir DIRWrite the snapshot to a different directory (used by tests).
--repo-root DIROverride repo root (used to point at a different uv.lock).
--forceOverwrite an existing snapshot for the current version.
--print-versionPrint only the resolved version and exit (useful in CI scripts).

What happens when you forget step 2

pytest tests/contract/ will fail with one of:

  • Missing envelope snapshot for spec-kitty-events <version> — you resolved a new version but did not regenerate the snapshot. Run the script with --force and re-run the contract suite.
  • Envelope field drift detected / required-field drift — the live envelope schema does not match the snapshot. Either the upstream package made a real shape change (in which case investigate), or the snapshot file is from a different version (regenerate).
  • spec_kitty_events.__version__ = '...' but uv.lock pins '...' — installed version disagrees with uv.lock. Run uv sync.

Each diagnostic includes a pointer back to this doc.

Snapshot lifetime

Snapshot files are version-controlled and intentionally accumulate one-per-bump. They are small (a few KB) and serve as historical anchors for upstream-shape regression reviews. Do not delete old snapshots when bumping; just add the new one.