spec-kitty-cli 3.2.0a9__tar.gz → 3.2.0a10__tar.gz

{spec_kitty_cli-3.2.0a9 → spec_kitty_cli-3.2.0a10}/CHANGELOG.md

@@ -17,6 +17,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+## [3.2.0a10] - 2026-05-04
+
+3.2.0a10 is a prerelease that stabilizes the implement-review-retrospect
+control loop after the 3.2.0 release-blocker triage.
+
+### Fixed
+
+- Rejection transitions from `in_review` now derive or require structured
+  rejected review results before mutating task state, closing the gap where
+  reviewer feedback could fail without a durable review result (#960).
+- Review feedback pointers are canonicalized to `review-cycle://...` URIs and
+  legacy `feedback://` references are normalized or resolved with a warning,
+  preserving focused fix-mode context across rejection cycles (#962).
+- Written `review-cycle-N.md` artifacts now include required YAML frontmatter
+  before they can be referenced, and invalid review artifacts fail closed
+  instead of leaving dangling status pointers (#963).
+- `spec-kitty next` now treats finalized task boards and work-package lane
+  state as authoritative in query mode without bypassing mutating runtime
+  composition or retrospective terminus handling (#961).
+- Completed missions now have a usable `agent retrospect synthesize` path when
+  `retrospective.yaml` is missing, with JSON output that distinguishes created,
+  synthesized, insufficient-artifacts, and mission-not-found outcomes (#965).
+
+### Internal
+
+- Added targeted regression coverage for the shared review-cycle domain,
+  rejection transitions, canonical feedback resolution, finalized routing,
+  retrospective synthesis, and the focused implement-review-retrospect smoke
+  path.
+
 ## [3.2.0a9] - 2026-05-03
 
 3.2.0a9 is a prerelease that adds mission-state audit diagnostics and hardens

{spec_kitty_cli-3.2.0a9 → spec_kitty_cli-3.2.0a10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spec-kitty-cli
-Version: 3.2.0a9
+Version: 3.2.0a10
 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
@@ -143,7 +143,7 @@ Spec Kitty addresses this with repository-native artifacts, work package workflo
 
 ---
 
-## 🚀 What You Get on `main` (`3.2.0a9`)
+## 🚀 What You Get on `main` (`3.2.0a10`)
 
 | Capability | What Spec Kitty provides |
 |------------|--------------------------|
@@ -205,7 +205,7 @@ graph LR
 
 **Current stable release line:** `v3.1.x` (current stable release: `3.1.8` on GitHub Releases and PyPI)
 
-**Current `main` development version:** `3.2.0a9`
+**Current `main` development version:** `3.2.0a10`
 
 **Current `main` highlights:**
 - **Brief-first and ticket-first intake** — `spec-kitty intake` ingests external plans into `.kittify/mission-brief.md`, and `spec-kitty mission create --from-ticket <provider:KEY>` seeds tracker context before `/spec-kitty.specify`
@@ -228,18 +228,18 @@ graph LR
 
 ## 📌 Release Channels
 
-Spec Kitty currently ships stable `3.1.x` releases while `main` carries the active `3.2.0a9` prerelease/dev line.
+Spec Kitty currently ships stable `3.1.x` releases while `main` carries the active `3.2.0a10` prerelease/dev line.
 The former `1.x` line is deprecated and lives on `1.x-maintenance` for maintenance-only fixes.
 
 | Source | Version | Status | Install |
 |--------|---------|--------|---------|
 | **PyPI / GitHub Releases** | **3.1.8** | Current stable line | `pip install spec-kitty-cli` |
-| **main** | **3.2.0a9** | Active prerelease / development line | Install from a source checkout or a published prerelease tag |
+| **main** | **3.2.0a10** | Active prerelease / development line | Install from a source checkout or a published prerelease tag |
 | **1.x-maintenance** | **1.x** | Deprecated, maintenance-only | Install from a pinned maintenance tag or source checkout |
 
 **For users:** install the stable line from PyPI with `pip install spec-kitty-cli`.
 **For testers following `main`:** use a source checkout or published prerelease builds to get the intake, profile-invocation, hosted tracker-read, and Teamspace-routing work that is newer than stable `3.1.x`.
-After `3.2.0a9` is published, testers can install the exact prerelease with `pip install "spec-kitty-cli==3.2.0a9"` or opt into prereleases with `pip install --pre spec-kitty-cli`.
+After `3.2.0a10` is published, testers can install the exact prerelease with `pip install "spec-kitty-cli==3.2.0a10"` or opt into prereleases with `pip install --pre spec-kitty-cli`.
 **For existing 3.0.x users:** upgrade to `3.1.x` and run `spec-kitty upgrade` in each project — the charter rename, mission identity, and prompt-neutrality migrations remain automatic.
 **For existing 1.x or 2.x users:** migrate to `3.1.x`; `1.x-maintenance` is maintenance-only and will no longer publish new PyPI releases.
 

{spec_kitty_cli-3.2.0a9 → spec_kitty_cli-3.2.0a10}/README.md

@@ -45,7 +45,7 @@ Spec Kitty addresses this with repository-native artifacts, work package workflo
 
 ---
 
-## 🚀 What You Get on `main` (`3.2.0a9`)
+## 🚀 What You Get on `main` (`3.2.0a10`)
 
 | Capability | What Spec Kitty provides |
 |------------|--------------------------|
@@ -107,7 +107,7 @@ graph LR
 
 **Current stable release line:** `v3.1.x` (current stable release: `3.1.8` on GitHub Releases and PyPI)
 
-**Current `main` development version:** `3.2.0a9`
+**Current `main` development version:** `3.2.0a10`
 
 **Current `main` highlights:**
 - **Brief-first and ticket-first intake** — `spec-kitty intake` ingests external plans into `.kittify/mission-brief.md`, and `spec-kitty mission create --from-ticket <provider:KEY>` seeds tracker context before `/spec-kitty.specify`
@@ -130,18 +130,18 @@ graph LR
 
 ## 📌 Release Channels
 
-Spec Kitty currently ships stable `3.1.x` releases while `main` carries the active `3.2.0a9` prerelease/dev line.
+Spec Kitty currently ships stable `3.1.x` releases while `main` carries the active `3.2.0a10` prerelease/dev line.
 The former `1.x` line is deprecated and lives on `1.x-maintenance` for maintenance-only fixes.
 
 | Source | Version | Status | Install |
 |--------|---------|--------|---------|
 | **PyPI / GitHub Releases** | **3.1.8** | Current stable line | `pip install spec-kitty-cli` |
-| **main** | **3.2.0a9** | Active prerelease / development line | Install from a source checkout or a published prerelease tag |
+| **main** | **3.2.0a10** | Active prerelease / development line | Install from a source checkout or a published prerelease tag |
 | **1.x-maintenance** | **1.x** | Deprecated, maintenance-only | Install from a pinned maintenance tag or source checkout |
 
 **For users:** install the stable line from PyPI with `pip install spec-kitty-cli`.
 **For testers following `main`:** use a source checkout or published prerelease builds to get the intake, profile-invocation, hosted tracker-read, and Teamspace-routing work that is newer than stable `3.1.x`.
-After `3.2.0a9` is published, testers can install the exact prerelease with `pip install "spec-kitty-cli==3.2.0a9"` or opt into prereleases with `pip install --pre spec-kitty-cli`.
+After `3.2.0a10` is published, testers can install the exact prerelease with `pip install "spec-kitty-cli==3.2.0a10"` or opt into prereleases with `pip install --pre spec-kitty-cli`.
 **For existing 3.0.x users:** upgrade to `3.1.x` and run `spec-kitty upgrade` in each project — the charter rename, mission identity, and prompt-neutrality migrations remain automatic.
 **For existing 1.x or 2.x users:** migrate to `3.1.x`; `1.x-maintenance` is maintenance-only and will no longer publish new PyPI releases.
 

spec_kitty_cli-3.2.0a10/kitty-specs/unified-charter-bundle-chokepoint-01KP5Q2G/tasks/README.md

@@ -0,0 +1,64 @@
+# Tasks Directory
+
+This directory contains work package (WP) prompt files.
+
+## Directory Structure (v0.9.0+)
+
+```
+tasks/
+├── WP01-setup-infrastructure.md
+├── WP02-user-authentication.md
+├── WP03-api-endpoints.md
+└── README.md
+```
+
+All WP files are stored flat in `tasks/`. Status is tracked in `status.events.jsonl`, not in WP frontmatter.
+
+## Work Package File Format
+
+Each WP file **MUST** use YAML frontmatter:
+
+```yaml
+---
+work_package_id: "WP01"
+title: "Work Package Title"
+dependencies: []
+planning_base_branch: "main"
+merge_target_branch: "main"
+branch_strategy: "Planning artifacts were generated on main; completed changes must merge back into main."
+subtasks:
+  - "T001"
+  - "T002"
+phase: "Phase 1 - Setup"
+assignee: ""
+agent: ""
+shell_pid: ""
+history:
+  - timestamp: "2025-01-01T00:00:00Z"
+    agent: "system"
+    action: "Prompt generated via /spec-kitty.tasks"
+---
+
+# Work Package Prompt: WP01 – Work Package Title
+
+[Content follows...]
+```
+
+## Status Tracking
+
+Status is tracked via the canonical event log (`status.events.jsonl`), not in WP frontmatter.
+Use `spec-kitty agent tasks move-task` to change WP status:
+
+```bash
+spec-kitty agent tasks move-task <WPID> --to <lane>
+```
+
+Example:
+```bash
+spec-kitty agent tasks move-task WP01 --to doing
+```
+
+## File Naming
+
+- Format: `WP01-kebab-case-slug.md`
+- Examples: `WP01-setup-infrastructure.md`, `WP02-user-auth.md`

{spec_kitty_cli-3.2.0a9 → spec_kitty_cli-3.2.0a10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spec-kitty-cli"
-version = "3.2.0a9"
+version = "3.2.0a10"
 description = "Spec Kitty, a tool for Specification Driven Development (SDD) agentic projects, with kanban and git worktree isolation."
 readme = "README.md"
 license = { file = "LICENSE" }

{spec_kitty_cli-3.2.0a9 → spec_kitty_cli-3.2.0a10}/src/specify_cli/auth/flows/revoke.py

@@ -53,7 +53,7 @@ class RevokeFlow:
         except httpx.RequestError as exc:
             log.warning("Revoke network error: %s", type(exc).__name__)
             return RevokeOutcome.NETWORK_ERROR
-        except Exception as exc:  # noqa: BLE001
+        except Exception as exc:  # noqa: BLE001 - revoke must never block local logout cleanup
             log.warning("Revoke unexpected error: %s", type(exc).__name__)
             return RevokeOutcome.SERVER_FAILURE
 

{spec_kitty_cli-3.2.0a9 → spec_kitty_cli-3.2.0a10}/src/specify_cli/cli/commands/agent/tasks.py

@@ -584,51 +584,23 @@ def _persist_review_feedback(
     reviewer_agent: str = "unknown",
     affected_files: list[dict[str, str]] | None = None,
 ) -> tuple[Path, str]:
-    """Persist review feedback as a versioned ReviewCycleArtifact in kitty-specs/.
+    """Persist review feedback through the shared review-cycle boundary.
 
-    Creates a committed artifact at:
-      kitty-specs/<mission>/tasks/<WP-slug>/review-cycle-{N}.md
-
-    Returns:
-        Tuple of (persisted_path, pointer) where pointer is a
-        ``review-cycle://`` URI.
+    Returns the created artifact path and canonical ``review-cycle://`` URI.
     """
-    from specify_cli.review.artifacts import AffectedFile, ReviewCycleArtifact
+    from specify_cli.review.cycle import create_rejected_review_cycle
 
     wp_slug = _resolve_wp_slug(main_repo_root, mission_slug, task_id)
-    sub_artifact_dir = main_repo_root / "kitty-specs" / mission_slug / "tasks" / wp_slug
-    cycle_n = ReviewCycleArtifact.next_cycle_number(sub_artifact_dir)
-
-    body = feedback_source.read_text(encoding="utf-8")
-    reviewed_at = datetime.now(UTC).strftime(UTC_SECOND_TIMESTAMP_FORMAT)
-
-    parsed_affected: list[AffectedFile] = []
-    if affected_files:
-        for af in affected_files:
-            parsed_affected.append(
-                AffectedFile(
-                    path=af["path"],
-                    line_range=af.get("line_range"),
-                )
-            )
-
-    artifact = ReviewCycleArtifact(
-        cycle_number=cycle_n,
-        wp_id=task_id,
+    cycle = create_rejected_review_cycle(
+        main_repo_root=main_repo_root,
         mission_slug=mission_slug,
+        wp_id=task_id,
+        wp_slug=wp_slug,
+        feedback_source=feedback_source,
         reviewer_agent=reviewer_agent,
-        verdict="rejected",
-        reviewed_at=reviewed_at,
-        affected_files=parsed_affected,
-        body=body,
+        affected_files=affected_files,
     )
-
-    filename = f"review-cycle-{cycle_n}.md"
-    persisted_path = sub_artifact_dir / filename
-    artifact.write(persisted_path)
-
-    pointer = f"review-cycle://{mission_slug}/{wp_slug}/{filename}"
-    return persisted_path, pointer
+    return cycle.artifact_path, cycle.pointer
 
 
 def _check_unchecked_subtasks(repo_root: Path, mission_slug: str, wp_id: str, _force: bool) -> list[str]:
@@ -1170,7 +1142,7 @@ def _validate_ready_for_review(
                     _meta = _load_meta_lggrd(feature_dir)
                     if _meta:
                         _planning_branch = _meta.get("planning_base_branch") or _meta.get("target_branch")
-                except Exception as _lane_meta_exc:  # noqa: BLE001
+                except Exception as _lane_meta_exc:  # noqa: BLE001 - lane guard still reports contamination without optional metadata
                     logger.debug(
                         "Could not resolve planning_base_branch for lane guard: %s", _lane_meta_exc
                     )
@@ -1443,6 +1415,7 @@ def move_task(
             resolved_feedback_source = feedback_candidate
 
         review_feedback_pointer: str | None = None
+        rejected_review_result = None
 
         # Strictly enforce deterministic review feedback capture on planned rollbacks.
         # This requirement is never bypassed, including with --force.
@@ -1464,13 +1437,18 @@ def move_task(
                 )
                 raise typer.Exit(1)
 
-            _, review_feedback_pointer = _persist_review_feedback(
+            from specify_cli.review.cycle import create_rejected_review_cycle
+
+            _review_cycle = create_rejected_review_cycle(
                 main_repo_root=main_repo_root,
                 mission_slug=mission_slug,
-                task_id=task_id,
+                wp_id=task_id,
+                wp_slug=_resolve_wp_slug(main_repo_root, mission_slug, task_id),
                 feedback_source=resolved_feedback_source,
                 reviewer_agent=agent or "unknown",
             )
+            review_feedback_pointer = _review_cycle.pointer
+            rejected_review_result = _review_cycle.review_result
 
         # Validate subtasks are complete when moving to for_review/approved/done (Issue #72)
         if target_lane in (Lane.FOR_REVIEW, Lane.APPROVED, Lane.DONE) and not force:
@@ -1679,12 +1657,31 @@ def move_task(
                 # (the review_result_required guard needs a structured outcome)
                 hop_review_result = None
                 if (
-                    event is not None
-                    and event.to_lane == Lane.IN_REVIEW
-                    and evidence_dict is not None
-                    or event is None
-                    and current_event_lane == Lane.IN_REVIEW
-                    and evidence_dict is not None
+                    (
+                        event is not None
+                        and event.to_lane == Lane.IN_REVIEW
+                        and target == Lane.PLANNED
+                        and rejected_review_result is not None
+                    )
+                    or (
+                        event is None
+                        and current_event_lane == Lane.IN_REVIEW
+                        and target == Lane.PLANNED
+                        and rejected_review_result is not None
+                    )
+                ):
+                    hop_review_result = rejected_review_result
+                elif (
+                    (
+                        event is not None
+                        and event.to_lane == Lane.IN_REVIEW
+                        and evidence_dict is not None
+                    )
+                    or (
+                        event is None
+                        and current_event_lane == Lane.IN_REVIEW
+                        and evidence_dict is not None
+                    )
                 ):
                     from specify_cli.status.models import ReviewResult
 

{spec_kitty_cli-3.2.0a9 → spec_kitty_cli-3.2.0a10}/src/specify_cli/cli/commands/agent/workflow.py

@@ -35,6 +35,7 @@ contract.
 from __future__ import annotations
 
 import logging
+import re
 import subprocess
 import tempfile
 from datetime import UTC
@@ -59,6 +60,7 @@ from specify_cli.review.prompt_metadata import (
     write_review_prompt_with_metadata,
 )
 from specify_cli.status.locking import feature_status_lock
+from specify_cli.review.cycle import REVIEW_FEEDBACK_SENTINELS, resolve_review_cycle_pointer
 from specify_cli.status.models import AgentAssignment, Lane
 from specify_cli.status.work_package_lifecycle import (
     WorkPackageClaimConflict,
@@ -79,7 +81,7 @@ from specify_cli.workspace.context import resolve_workspace_for_wp
 
 logger = logging.getLogger(__name__)
 
-_REVIEW_FEEDBACK_SENTINELS = frozenset({"force-override", "action-review-claim"})
+_REVIEW_FEEDBACK_SENTINELS = REVIEW_FEEDBACK_SENTINELS
 
 
 def _write_prompt_to_file(
@@ -161,35 +163,11 @@ def _resolve_review_feedback_pointer(repo_root: Path, pointer: str) -> Path | No
     ``"action-review-claim"``, or any
     unrecognised / non-existent pointer.
     """
-    value = pointer.strip()
-    if not value or value in _REVIEW_FEEDBACK_SENTINELS:
+    try:
+        return resolve_review_cycle_pointer(repo_root, pointer).path
+    except ValueError:
         return None
 
-    if value.startswith("review-cycle://"):
-        relative = value[len("review-cycle://") :]
-        parts = [p for p in relative.split("/") if p]
-        if len(parts) != 3:
-            return None
-        # parts: mission_slug / wp_slug / filename
-        candidate = repo_root / "kitty-specs" / parts[0] / "tasks" / parts[1] / parts[2]
-    elif value.startswith("feedback://"):
-        relative = value[len("feedback://") :]
-        parts = [p for p in relative.split("/") if p]
-        if len(parts) != 3:
-            return None
-        common_dir = _resolve_git_common_dir(repo_root)
-        if common_dir is None:
-            return None
-        candidate = common_dir / "spec-kitty" / "feedback" / parts[0] / parts[1] / parts[2]
-    else:
-        legacy = Path(value).expanduser()
-        candidate = legacy if legacy.is_absolute() else (repo_root / legacy)
-
-    candidate = candidate.resolve()
-    if candidate.exists() and candidate.is_file():
-        return candidate
-    return None
-
 
 def _read_wp_events(feature_dir: Path, wp_id: str):
     """Return canonical status events for a single work package."""
@@ -967,6 +945,8 @@ def implement(
             lines.append("⚠️  This work package has review feedback.")
             if review_feedback_ref:
                 lines.append(f"   Canonical feedback reference: {review_feedback_ref}")
+                if review_feedback_ref.startswith("feedback://"):
+                    lines.append("   WARNING: legacy feedback:// reference detected; readable but deprecated.")
                 if review_feedback_file is not None:
                     lines.append(f'   Read it first: cat "{review_feedback_file}"')
                 else:
@@ -1050,6 +1030,8 @@ def implement(
         if has_feedback:
             if review_feedback_ref:
                 print(f"⚠️  Has review feedback - read reference: {review_feedback_ref}")
+                if review_feedback_ref.startswith("feedback://"):
+                    print("   Warning: legacy feedback:// reference detected; readable but deprecated.")
             else:
                 print("⚠️  Has review feedback - but no review_feedback reference is set")
         if mission_type == "research" and deliverables_path:
@@ -1075,7 +1057,7 @@ def _resolve_review_context(
     repo_root: Path,
     mission_slug: str,
     wp_id: str,
-    _wp_frontmatter: str,
+    wp_frontmatter: str,
 ) -> dict:
     """Resolve git branch and base context for review prompts.
 
@@ -1172,6 +1154,7 @@ def _resolve_review_context(
         ctx["lane_branch"] = branch
     else:
         return ctx
+    branch = ctx["branch_name"]
 
     base_ref = "unknown"
     if workspace.context is not None and workspace.context.base_branch:
@@ -1180,10 +1163,60 @@ def _resolve_review_context(
         base_ref = mission_branch
 
     if base_ref == "unknown":
+        candidates: list[str] = []
+        dep_match = re.search(r"dependencies:\s*\[([^\]]*)\]", wp_frontmatter)
+        if dep_match:
+            dep_content = dep_match.group(1).strip()
+            if dep_content:
+                dep_ids = re.findall(r'"?(WP\d+)"?', dep_content)
+                for dep_id in dep_ids:
+                    try:
+                        dep_workspace = resolve_workspace_for_wp(repo_root, mission_slug, dep_id)
+                    except (ValueError, FileNotFoundError):
+                        continue
+                    dep_branch = dep_workspace.branch_name
+                    if dep_branch and dep_branch != branch:
+                        candidates.append(dep_branch)
+
+        candidates.extend(["main", "2.x", "master", "develop"])
+        best_base = None
+        best_count = -1
+        for candidate in candidates:
+            mb = subprocess.run(
+                ["git", "merge-base", branch, candidate],
+                cwd=repo_root,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                check=False,
+            )
+            if mb.returncode != 0:
+                continue
+            count_r = subprocess.run(
+                ["git", "rev-list", "--count", f"{mb.stdout.strip()}..{branch}"],
+                cwd=repo_root,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                check=False,
+            )
+            if count_r.returncode != 0:
+                continue
+            count = int(count_r.stdout.strip()) if count_r.stdout.strip().isdigit() else 0
+            if best_count == -1 or count < best_count:
+                best_count = count
+                best_base = candidate
+
+        if best_base is not None:
+            ctx["base_branch"] = best_base
+            ctx["base_ref"] = best_base
+            ctx["commit_count"] = best_count
         return ctx
 
     count_r = subprocess.run(
-        ["git", "rev-list", "--count", f"{base_ref}..{ctx['branch_name']}"],
+        ["git", "rev-list", "--count", f"{base_ref}..{branch}"],
         cwd=repo_root,
         capture_output=True,
         text=True,