Contracts

dependency-drift-guard.md

Contract: Dependency Drift Guard

Purpose

Prevent review or release evidence from being trusted when the active installed environment uses a critical Spec Kitty package version that differs from uv.lock.

Minimum Package Set

Required:

  • spec-kitty-events

Optional if verification proves equivalent risk:

  • spec-kitty-tracker

Inputs

  • /Users/robert/spec-kitty-dev/spec-kitty-20260504-195327-4esVAN/spec-kitty/uv.lock
  • /Users/robert/spec-kitty-dev/spec-kitty-20260504-195327-4esVAN/spec-kitty/pyproject.toml
  • Active Python environment package metadata from the command environment used for evidence

Pass Condition

For each checked package:

  • package exists in uv.lock
  • active installed version exists
  • active installed version equals the uv.lock resolved version
  • pyproject.toml constraint contains the lockfile version

Failure Shape

Failure output must include:

  • package name
  • installed version
  • lockfile version
  • constraint, when available
  • remediation command

Example:

spec-kitty-events installed version drift:
  installed: 4.0.0
  uv.lock:   4.1.0
  constraint: spec-kitty-events>=4.0.0,<5.0.0
Remediation: uv sync --extra test --extra lint

Closure Evidence If No Code Change Is Needed

If current gates already satisfy this contract, the mission must record:

  • workflow names and job names that enforce it
  • command output proving spec-kitty-events installed version matches uv.lock
  • a closure note suitable for #848

Non-Goals

  • Do not loosen pyproject.toml constraints to hide drift.
  • Do not vendor spec-kitty-events.
  • Do not require SaaS or tracker network access for the local drift guard.

smoke-workflow-contract.md

Contract: Fresh Workflow Smoke

Local-Only Smoke

Must cover:

  • init or project setup
  • specify
  • plan
  • tasks
  • implement/review or a bounded equivalent fixture path
  • merge
  • PR creation or PR-ready branch evidence

Rules:

  • Must not require hosted auth, tracker, SaaS, or sync.
  • Must run against the current prerelease line from this repository.
  • Must record command sequence and outcome in release evidence.

SaaS-Enabled Smoke

Must cover the same lifecycle shape where practical, with hosted/sync coverage added where current CLI surfaces support it.

Rules for this computer:

  • Every hosted auth, tracker, SaaS, or sync command path must set SPEC_KITTY_ENABLE_SAAS_SYNC=1.
  • Evidence must state which commands used the flag.
  • If auth or hosted state blocks the smoke, record the blocker and either file/reference an issue or mark it as a stable-release blocker.

Failure Handling

Each smoke failure must lead to one of:

  • narrow fix inside this mission
  • linked GitHub issue with repro
  • explicit stable 3.2.0 blocker decision

Evidence Format

Recommended fields:

{
  "mode": "local-only",
  "commands": ["..."],
  "result": "pass",
  "evidence": "path or issue link",
  "notes": "bounded fixture path used for implement/review"
}

task-progress-status.md

Contract: Task Progress Status Output

Human Output

Command:

spec-kitty agent tasks status --mission <mission>

Required behavior:

  • Show total WP count.
  • Show done count separately from weighted or ready progress.
  • Do not show a done-only numerator next to a weighted percentage unless the label states that the percentage is weighted/ready.
  • Approved-only boards must communicate readiness without implying that WPs are done.

Accepted examples:

Done: 0/6 (0.0% done)
Ready progress: 80.0% weighted
Ready: 6/6 ready (0 done, 80.0% weighted)

Rejected example:

Progress: 0/6 (80.0%)

JSON Output

Command:

spec-kitty agent tasks status --mission <mission> --json

Required behavior when JSON output is touched:

  • Output must remain valid JSON on stdout.
  • The existing mission identity fields must remain present.
  • total_wps must remain numeric.
  • Lane counts must remain machine-readable.
  • Any percentage field must have clear semantics through its name or accompanying label.

Recommended additive fields:

{
  "total_wps": 6,
  "done_count": 0,
  "done_percentage": 0.0,
  "weighted_percentage": 80.0,
  "progress_percentage": 80.0,
  "progress_semantics": "weighted_readiness"
}

Compatibility rule:

  • If progress_percentage remains weighted for compatibility, add progress_semantics or an equivalent explicit field.
  • If progress_percentage changes to done-only, document that as a compatibility break and update all call sites/tests touched by this mission.