spec-kitty-cli 3.2.0rc2__tar.gz → 3.2.0rc4__tar.gz

{spec_kitty_cli-3.2.0rc2 → spec_kitty_cli-3.2.0rc4}/CHANGELOG.md

@@ -17,6 +17,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+## [3.2.0rc4] - 2026-05-11
+
+3.2.0rc4 tightens the TeamSpace release candidate against the published
+`spec-kitty-events` 5.0.0 contract and includes the latest migration rehearsal
+diagnostics.
+
+### Changed
+
+- Tightened the CLI `spec-kitty-events` dependency to `>=5.0.0,<6.0.0` now
+  that the 5.0.0 TeamSpace canonical event contract is published to PyPI
+  (#978).
+- Included the TeamSpace dry-run row mapping diagnostics merged after rc3 so
+  migration rehearsals can trace source rows to synthesized TeamSpace envelopes
+  (#1014).
+
+## [3.2.0rc3] - 2026-05-06
+
+3.2.0rc3 fixes a TeamSpace dry-run compatibility gap found during the
+historical mission-state migration rehearsal.
+
+### Fixed
+
+- Synthesized minimal repo evidence for historical done rows that only
+  preserved review evidence, allowing `doctor mission-state --teamspace-dry-run`
+  to validate those rows against the `spec-kitty-events` 5.0.0 payload contract
+  (#997).
+
 ## [3.2.0rc2] - 2026-05-05
 
 3.2.0rc2 adds the TeamSpace mission-state repair and validation surface needed

{spec_kitty_cli-3.2.0rc2 → spec_kitty_cli-3.2.0rc4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spec-kitty-cli
-Version: 3.2.0rc2
+Version: 3.2.0rc4
 Summary: Spec Kitty, a tool for Specification Driven Development (SDD) agentic projects, with kanban and git worktree isolation.
 Project-URL: Repository, https://github.com/Priivacy-ai/spec-kitty
 Project-URL: Issues, https://github.com/Priivacy-ai/spec-kitty/issues
@@ -65,7 +65,7 @@ Requires-Dist: readchar>=4.2.1
 Requires-Dist: requests>=2.33.0
 Requires-Dist: rich>=14.3.3
 Requires-Dist: ruamel-yaml>=0.18.0
-Requires-Dist: spec-kitty-events<6.0.0,>=4.0.0
+Requires-Dist: spec-kitty-events<6.0.0,>=5.0.0
 Requires-Dist: spec-kitty-tracker<0.5,>=0.4
 Requires-Dist: toml>=0.10.2
 Requires-Dist: transitions>=0.9.2

{spec_kitty_cli-3.2.0rc2 → spec_kitty_cli-3.2.0rc4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spec-kitty-cli"
-version = "3.2.0rc2"
+version = "3.2.0rc4"
 description = "Spec Kitty, a tool for Specification Driven Development (SDD) agentic projects, with kanban and git worktree isolation."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -70,9 +70,8 @@ dependencies = [
     # src/specify_cli/next/_internal_runtime/ (see WP01 of mission
     # shared-package-boundary-cutover-01KQ22DS), and absence is enforced by
     # tests/architectural/test_pyproject_shape.py.
-    # TeamSpace dry-run requires spec-kitty-events>=5.0.0 at runtime; keep
-    # this as a public bounded range until 5.0.0 is published on PyPI.
-    "spec-kitty-events>=4.0.0,<6.0.0",
+    # TeamSpace dry-run requires the canonical 5.0.0 event contract.
+    "spec-kitty-events>=5.0.0,<6.0.0",
     "spec-kitty-tracker>=0.4,<0.5",
     "websockets>=12.0",  # WebSocket client for sync protocol
     "toml>=0.10.2",  # Config file parsing

{spec_kitty_cli-3.2.0rc2 → spec_kitty_cli-3.2.0rc4}/src/specify_cli/cli/commands/_auth_doctor.py

@@ -584,8 +584,10 @@ def assemble_report(*, stuck_threshold_s: float = 60.0) -> DoctorReport:
     )
 
 
-def render_report(report: DoctorReport, console: Console, *, show_server_hint: bool = True) -> None:  # noqa: C901, PLR0912 — the 7-section layout is intentionally linear and section-by-section so reviewers can map each block to the contract; splitting it adds indirection without clarity.
+def render_report(report: DoctorReport, console: Console, *, show_server_hint: bool = True) -> None:  # noqa: C901, PLR0912
     """Render a :class:`DoctorReport` as the 7-section Rich layout."""
+    # The 7-section layout intentionally stays linear so reviewers can map each
+    # block to the contract without bouncing through helper indirection.
     # Section 1 — Identity.
     console.print("[bold]Identity[/bold]")
     if report.session is None:

{spec_kitty_cli-3.2.0rc2 → spec_kitty_cli-3.2.0rc4}/src/specify_cli/cli/commands/merge.py

@@ -19,7 +19,6 @@ import json
 import logging
 import os
 import re
-import subprocess
 import time
 from pathlib import Path
 
@@ -545,13 +544,13 @@ def _bake_mission_number_into_mission_branch(
 
 def _has_branch_ref(repo_root: Path, ref_name: str) -> bool:
     """Return True when a local branch/ref resolves to a commit."""
-    probe = subprocess.run(
+    retcode, _stdout, _stderr = run_command(
         ["git", "rev-parse", "--verify", f"{ref_name}^{{commit}}"],
-        cwd=str(repo_root),
-        capture_output=True,
-        text=True,
+        capture=True,
+        check_return=False,
+        cwd=repo_root,
     )
-    return probe.returncode == 0
+    return retcode == 0
 
 
 def _check_mission_branch(
@@ -568,17 +567,13 @@ def _check_mission_branch(
     if _has_branch_ref(repo_root, expected_branch):
         return True, None
 
-    try:
-        result = subprocess.run(
-            ["git", "rev-parse", "HEAD"],
-            cwd=str(repo_root),
-            capture_output=True,
-            text=True,
-            check=True,
-        )
-        base_sha = result.stdout.strip()[:12]
-    except subprocess.CalledProcessError:
-        base_sha = "<base-commit>"
+    retcode, stdout, _stderr = run_command(
+        ["git", "rev-parse", "HEAD"],
+        capture=True,
+        check_return=False,
+        cwd=repo_root,
+    )
+    base_sha = stdout.strip()[:12] if retcode == 0 else "<base-commit>"
 
     blocker_payload: MissionBranchBlocker = {
         "ready": False,
@@ -1522,30 +1517,6 @@ def merge(
                 console.print(f"[red]Error:[/red] {error_msg}")
             raise typer.Exit(1) from exc
 
-        _enforce_target_branch_sync_preflight(
-            get_main_repo_root(repo_root),
-            target_branch=resolved_target_branch,
-            mission_slug=resolved_feature,
-            mission_branch=lanes_manifest.mission_branch,
-            json_output=json_output,
-        )
-
-        branch_ok, branch_blocker = _check_mission_branch(
-            resolved_feature,
-            get_main_repo_root(repo_root),
-        )
-        if not branch_ok:
-            assert branch_blocker is not None
-            if json_output:
-                print(json.dumps(branch_blocker))
-            else:
-                console.print(
-                    "[red]Cannot proceed: mission branch missing.[/red]\n"
-                    f"Expected branch: {branch_blocker['expected_branch']}\n"
-                    f"Remediation: {branch_blocker['remediation']}"
-                )
-            raise typer.Exit(1)
-
         # WP10/T053: dry-run preview of merge-time mission_number assignment.
         feature_dir_for_preview = (
             get_main_repo_root(repo_root) / "kitty-specs" / resolved_feature

{spec_kitty_cli-3.2.0rc2 → spec_kitty_cli-3.2.0rc4}/src/specify_cli/cli/commands/sync.py

@@ -39,6 +39,32 @@ console = Console()
 _STATUS_ACCESS_TOKEN_LABEL = "Access token"  # noqa: S105
 _STATUS_REFRESH_TOKEN_LABEL = "Refresh token"  # noqa: S105
 _STATUS_LAST_SYNC_LABEL = "Last Sync"
+_UNAUTHENTICATED_SYNC_NOW_MESSAGE = (
+    "not authenticated: no valid access token. Run `spec-kitty auth login`."
+)
+
+
+def _sync_result_looks_unauthenticated(queue_size: int, result: object) -> bool:
+    """Detect the legacy auth-missing result shape from ``sync_now``."""
+    if queue_size <= 0:
+        return False
+
+    def _int_attr(name: str) -> int:
+        value = getattr(result, name, 0)
+        return value if isinstance(value, int) and not isinstance(value, bool) else 0
+
+    total_events = _int_attr("total_events")
+    synced_count = _int_attr("synced_count")
+    duplicate_count = _int_attr("duplicate_count")
+    error_count = _int_attr("error_count")
+    failed_results = getattr(result, "failed_results", ())
+    return (
+        total_events == 0
+        and synced_count == 0
+        and duplicate_count == 0
+        and error_count == 0
+        and len(failed_results) == 0
+    )
 
 
 def humanize_timedelta(td: timedelta) -> str:
@@ -975,7 +1001,13 @@ def now(
         return
 
     console.print(f"Syncing {queue_size} queued event(s)...")
-    result = service.sync_now()
+    result = service.sync_now(show_progress=True)
+
+    if _sync_result_looks_unauthenticated(queue_size, result):
+        console.print(f"[yellow]{_UNAUTHENTICATED_SYNC_NOW_MESSAGE}[/yellow]")
+        if strict:
+            raise typer.Exit(1)
+        return
 
     # Print actionable summary instead of bare counts
     summary = format_sync_summary(result)

{spec_kitty_cli-3.2.0rc2 → spec_kitty_cli-3.2.0rc4}/src/specify_cli/migration/mission_state.py

@@ -18,6 +18,7 @@ from contextlib import suppress
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Literal
+from urllib.parse import urlsplit
 
 from packaging.version import Version
 
@@ -66,6 +67,7 @@ _UUID_HYPHEN_RE = re.compile(
     re.IGNORECASE,
 )
 _UUID_BARE_RE = re.compile(r"^[0-9a-f]{32}$", re.IGNORECASE)
+_REMOTE_URL_SCHEMES = frozenset({"http", "https"})
 
 
 class MissionStateRepairError(RuntimeError):
@@ -174,6 +176,34 @@ class RepairReport:
         return json.dumps(self.to_dict(), indent=2, sort_keys=True) + "\n"
 
 
+@dataclass(frozen=True)
+class TeamspaceDryRunRowMapping:
+    """Mapping from one local status row to its synthesized TeamSpace event."""
+
+    mission_slug: str
+    artifact_path: str
+    line_number: int | None
+    source_event_id: str
+    synthesized_event_id: str
+    synthesized_event_type: str
+    aggregate_id: str
+    row_sha256: str | None
+    envelope_sha256: str
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "mission_slug": self.mission_slug,
+            "artifact_path": self.artifact_path,
+            "line_number": self.line_number,
+            "source_event_id": self.source_event_id,
+            "synthesized_event_id": self.synthesized_event_id,
+            "synthesized_event_type": self.synthesized_event_type,
+            "aggregate_id": self.aggregate_id,
+            "row_sha256": self.row_sha256,
+            "envelope_sha256": self.envelope_sha256,
+        }
+
+
 @dataclass(frozen=True)
 class TeamspaceDryRunReport:
     """Validation report for canonical envelopes synthesized from local state."""
@@ -183,6 +213,8 @@ class TeamspaceDryRunReport:
     envelope_count: int
     valid: bool
     errors: tuple[dict[str, object], ...]
+    row_mappings: tuple[TeamspaceDryRunRowMapping, ...] = ()
+    context_warnings: tuple[dict[str, object], ...] = ()
     side_logs: tuple[dict[str, object], ...] = ()
 
     def to_dict(self) -> dict[str, object]:
@@ -192,6 +224,8 @@ class TeamspaceDryRunReport:
             "envelope_count": self.envelope_count,
             "valid": self.valid,
             "errors": list(self.errors),
+            "row_mappings": [mapping.to_dict() for mapping in self.row_mappings],
+            "context_warnings": list(self.context_warnings),
             "side_logs": list(self.side_logs),
         }
 
@@ -277,8 +311,10 @@ def teamspace_dry_run(
     errors: list[dict[str, object]] = []
     side_logs: list[dict[str, object]] = []
     count = 0
-    project_slug = repo_root.resolve().name
     repo_slug = _repo_slug(repo_root.resolve())
+    project_slug = repo_slug or repo_root.resolve().name
+    row_mappings: list[TeamspaceDryRunRowMapping] = []
+    context_warnings = _teamspace_context_warnings(repo_root.resolve(), project_uuid)
 
     from specify_cli.status.store import read_events
 
@@ -288,6 +324,7 @@ def teamspace_dry_run(
         errors.extend(raw_status_errors)
         if raw_status_errors:
             continue
+        row_locations = _status_row_locations(mission_dir)
         try:
             events = read_events(mission_dir)
         except Exception as exc:
@@ -308,6 +345,26 @@ def teamspace_dry_run(
                 project_slug=project_slug,
                 repo_slug=repo_slug,
             )
+            row_location = row_locations.get(status_event.event_id)
+            row_mappings.append(
+                TeamspaceDryRunRowMapping(
+                    mission_slug=status_event.mission_slug,
+                    artifact_path=_repo_relpath(repo_root.resolve(), mission_dir / EVENTS_FILENAME),
+                    line_number=row_location.line_number if row_location is not None else None,
+                    source_event_id=status_event.event_id,
+                    synthesized_event_id=envelope["event_id"],
+                    synthesized_event_type=envelope["event_type"],
+                    aggregate_id=envelope["aggregate_id"],
+                    row_sha256=(
+                        hashlib.sha256(row_location.text.encode("utf-8")).hexdigest()
+                        if row_location is not None
+                        else None
+                    ),
+                    envelope_sha256=hashlib.sha256(
+                        json.dumps(envelope, sort_keys=True, separators=(",", ":")).encode("utf-8")
+                    ).hexdigest(),
+                )
+            )
             try:
                 event_cls.model_validate(envelope)
             except Exception as exc:
@@ -344,10 +401,59 @@ def teamspace_dry_run(
         envelope_count=count,
         valid=not errors,
         errors=tuple(errors),
+        row_mappings=tuple(row_mappings),
+        context_warnings=tuple(context_warnings),
         side_logs=tuple(side_logs),
     )
 
 
+def _teamspace_context_warnings(repo_root: Path, project_uuid: uuid.UUID) -> list[dict[str, object]]:
+    warnings: list[dict[str, object]] = []
+    try:
+        from specify_cli.identity.project import load_identity
+
+        identity = load_identity(repo_root / ".kittify" / "config.yaml")
+    except Exception:
+        identity = None
+
+    if identity is None or identity.project_uuid is None:
+        warnings.append(
+            {
+                "code": "TEAMSPACE_PROJECT_CONTEXT_MISSING",
+                "message": (
+                    "No persisted project.uuid was found; dry-run used a deterministic "
+                    "offline project_uuid for schema validation only."
+                ),
+                "dry_run_project_uuid": str(project_uuid),
+            }
+        )
+
+    warnings.append(
+        {
+            "code": "TEAMSPACE_TEAM_CONTEXT_NOT_VALIDATED",
+            "message": "Team/private TeamSpace membership is not checked by offline dry-run.",
+        }
+    )
+    return warnings
+
+
+def _status_row_locations(mission_dir: Path) -> dict[str, _RawJsonlRow]:
+    status_path = mission_dir / EVENTS_FILENAME
+    if not status_path.exists():
+        return {}
+    try:
+        rows = _read_jsonl_rows(status_path)
+    except Exception:
+        return {}
+
+    locations: dict[str, _RawJsonlRow] = {}
+    for row in rows:
+        event_id = _event_id(row.data)
+        if event_id is not None:
+            locations.setdefault(event_id, row)
+    return locations
+
+
 def _load_events_contract() -> tuple[type[Any], Any, str]:
     import spec_kitty_events
     from spec_kitty_events import Event
@@ -370,6 +476,18 @@ def _status_event_to_teamspace_envelope(
     project_slug: str,
     repo_slug: str | None,
 ) -> dict[str, Any]:
+    evidence = status_event.evidence.to_dict() if status_event.evidence else None
+    if evidence is not None and not evidence.get("repos"):
+        # Older done rows only recorded review evidence; the 5.0.0 TeamSpace
+        # contract requires at least one repo evidence entry.
+        evidence["repos"] = [
+            {
+                "repo": repo_slug or project_slug,
+                "branch": "historical-mission-state-repair",
+                "commit": "historical-mission-state-repair",
+            }
+        ]
+
     payload = {
         "mission_slug": status_event.mission_slug,
         "wp_id": status_event.wp_id,
@@ -380,7 +498,7 @@ def _status_event_to_teamspace_envelope(
         "reason": status_event.reason,
         "execution_mode": status_event.execution_mode,
         "review_ref": status_event.review_ref,
-        "evidence": status_event.evidence.to_dict() if status_event.evidence else None,
+        "evidence": evidence,
     }
     return {
         "event_id": status_event.event_id,
@@ -998,13 +1116,18 @@ def _resolve_repo_relative(repo_root: Path, path: Path) -> Path:
     return repo_root / path
 
 
+def _is_remote_url(slug: str) -> bool:
+    """Return True when *slug* is an HTTP(S) remote URL."""
+    return urlsplit(slug).scheme in _REMOTE_URL_SCHEMES
+
+
 def _repo_slug(repo_root: Path) -> str | None:
     result = _git(repo_root, "config", "--get", "remote.origin.url", check=False)
     remote = result.stdout.strip()
     if not remote:
         return repo_root.name
     slug = remote.removesuffix(".git").rstrip("/")
-    if ":" in slug and not slug.startswith(("http://", "https://")):
+    if ":" in slug and not _is_remote_url(slug):
         slug = slug.rsplit(":", 1)[1]
     elif "/" in slug:
         parts = slug.split("/")
@@ -1097,6 +1220,7 @@ __all__ = [
     "MissionStateDryRunError",
     "MissionStateRepairError",
     "RepairReport",
+    "TeamspaceDryRunRowMapping",
     "TeamspaceDryRunReport",
     "deterministic_ulid",
     "repair_repo",

{spec_kitty_cli-3.2.0rc2 → spec_kitty_cli-3.2.0rc4}/src/specify_cli/skills/installer.py

@@ -3,6 +3,9 @@
 from __future__ import annotations
 
 import shutil
+import stat
+from collections.abc import Callable
+from contextlib import suppress
 from datetime import datetime, timezone, UTC
 from pathlib import Path
 
@@ -27,6 +30,31 @@ DELIVERY_COPY = "copy"
 DELIVERY_SYMLINK = "symlink"
 
 
+def _make_path_writable(path: str | Path) -> None:
+    """Clear Windows ReadOnly before deleting managed files."""
+    path = Path(path)
+    with suppress(OSError):
+        path.chmod(path.stat().st_mode | stat.S_IWRITE)
+
+
+def _force_writable_and_retry(function: Callable[[str], object], path: str, _exc_info: object) -> None:
+    """shutil.rmtree onerror handler: clear readonly and retry the failed operation."""
+    _make_path_writable(path)
+    function(path)
+
+
+def _safe_unlink(path: Path) -> None:
+    try:
+        path.unlink()
+    except PermissionError:
+        _make_path_writable(path)
+        path.unlink()
+
+
+def _safe_rmtree(path: Path) -> None:
+    shutil.rmtree(path, onerror=_force_writable_and_retry)
+
+
 def _make_tree_read_only(root: Path) -> None:
     """Remove write bits from all files in a managed canonical skill tree."""
     for file_path in root.rglob("*"):
@@ -50,12 +78,12 @@ def _normalize_skill_md(skill: CanonicalSkill, dest_dir: Path) -> None:
 def _sync_global_skill(skill: CanonicalSkill, target_root: Path) -> Path:
     """Install one canonical skill into the user-global root."""
     target_root.mkdir(parents=True, exist_ok=True)
-    dest_dir = target_root / skill.name
+    dest_dir: Path = target_root / str(skill.name)
     if dest_dir.exists() or dest_dir.is_symlink():
         if dest_dir.is_symlink() or dest_dir.is_file():
-            dest_dir.unlink()
+            _safe_unlink(dest_dir)
         else:
-            shutil.rmtree(dest_dir)
+            _safe_rmtree(dest_dir)
     shutil.copytree(skill.skill_dir, dest_dir)
     _normalize_skill_md(skill, dest_dir)
     _make_tree_read_only(dest_dir)
@@ -77,6 +105,7 @@ def _archive_existing_path(dest: Path, project_path: Path, backup_root: Path | N
     backup_root = _ensure_backup_root(project_path, backup_root)
     backup_path = backup_root / dest.relative_to(project_path)
     backup_path.parent.mkdir(parents=True, exist_ok=True)
+    _make_path_writable(dest)
     shutil.move(str(dest), str(backup_path))
     return backup_root
 
@@ -100,11 +129,11 @@ def _project_skill_file(
                 return DELIVERY_SYMLINK, backup_root
         except OSError:
             pass
-        dest.unlink()
+        _safe_unlink(dest)
     elif dest.exists():
         try:
             if dest.is_file() and compute_content_hash(dest) == compute_content_hash(source_file):
-                dest.unlink()
+                _safe_unlink(dest)
             else:
                 backup_root = _ensure_backup_root(project_path, backup_root)
                 if archived_paths is not None:

{spec_kitty_cli-3.2.0rc2 → spec_kitty_cli-3.2.0rc4}/src/specify_cli/sync/background.py

@@ -280,14 +280,14 @@ class BackgroundSyncService:
     def is_running(self) -> bool:
         return self._running
 
-    def sync_now(self) -> BatchSyncResult:
+    def sync_now(self, *, show_progress: bool = False) -> BatchSyncResult:
         """Trigger an immediate sync, draining all queued events.
 
         Unlike the periodic timer (which syncs a single batch), this
         loops until the queue is empty or all remaining events have
         exceeded their retry limit.
         """
-        return self._perform_full_sync()
+        return self._perform_full_sync(show_progress=show_progress)
 
     # ── Internal ──────────────────────────────────────────────────
 
@@ -327,7 +327,7 @@ class BackgroundSyncService:
         with self._lock:
             return self._sync_once()
 
-    def _perform_full_sync(self) -> BatchSyncResult:
+    def _perform_full_sync(self, *, show_progress: bool = False) -> BatchSyncResult:
         """Drain the entire queue across multiple batches.
 
         Thread-safe: holds _lock for the full duration so background
@@ -355,7 +355,7 @@ class BackgroundSyncService:
                     auth_token=access_token,
                     server_url=self.config.get_server_url(),
                     batch_size=1000,
-                    show_progress=False,
+                    show_progress=show_progress,
                 )
                 # Treat auth failures as hard errors (#598)
                 if "auth_expired" in result.category_counts: