spec-kitty-cli 3.2.0rc41__tar.gz → 3.2.0rc42__tar.gz

{spec_kitty_cli-3.2.0rc41 → spec_kitty_cli-3.2.0rc42}/CHANGELOG.md

@@ -9,6 +9,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.2.0rc42] - 2026-06-11
+
+### 💥 Changed
+
+- **Op record schema v2 (WP01, do-dispatch-open-op-lifecycle)**: the dual-purpose
+  `InvocationRecord` model is split into frozen `OpStartedEvent` /
+  `OpCompletedEvent` Pydantic v2 models. Completed events now require `outcome`
+  and `closed_by` and carry no started-only fields; blank-default records are
+  unrepresentable. Readers of `kitty-ops/*.jsonl` warn-and-skip legacy (pre-v2)
+  lines, pointing at `spec-kitty upgrade`; `parse_op_event` raises a catchable
+  `LegacyRecordError` for them. `spec-kitty invocations list` now shows
+  `outcome` and `closed_by` for closed Ops. `artifact_link`, `commit_link`, and
+  `glossary_checked` event shapes are unchanged.
+- **Breaking — `spec-kitty do` no longer auto-closes its Op as `done`
+  (do-dispatch-open-op-lifecycle)**: `do` / `ask` / `advise` now only OPEN the
+  Op and load governance context; the working agent closes it via
+  `spec-kitty profile-invocation complete --invocation-id <id>
+  --outcome <done|failed|abandoned>` (completed-event schema v2: `outcome`
+  required, new `closed_by` field). New `spec-kitty doctor ops --close-stale`
+  sweeps stale open Ops closed as `abandoned` (`closed_by: doctor_sweep`).
+  Legacy `kitty-ops` records are migrated (rewrite-or-delete) by
+  `spec-kitty upgrade`. Claude Code session presence now lists open Ops at
+  session start, a new `Stop` hook (`spec-kitty session-stop`) reminds at
+  session end, and the doctrine skill pack / standalone command templates
+  document the open→work→close contract.
+
+### 🐛 Fixed
+
+- Hardened the v2 Op migration and readers: `spec-kitty invocations list` skips
+  dangling `ops-index.jsonl` rows after unsalvageable Op files are deleted, and
+  migration idempotency now treats only v2-parseable `mode_of_work` / `closed_by`
+  values as already migrated.
+- Preserved machine-readable output for `do`, `ask`, and `advise --json` by
+  suppressing post-payload inline glossary notices on JSON paths; rich output
+  still shows the notices.
+- Updated the rich `ask` / `advise` close hint to include the now-required
+  `--outcome <done|failed|abandoned>` flag.
+- Replaced stale short profile aliases in shipped mission-runtime templates
+  (`researcher`, `architect`, `planner`, `implementer`, `reviewer`) with the
+  canonical shipped profile IDs, preventing fresh `software-dev` runs from
+  blocking on missing invocation profiles.
+- `spec-kitty merge` now skips empty post-merge bookkeeping commits after a
+  successful lane merge instead of failing the command after the target branch
+  has already been updated.
+
 ## [3.2.0rc41] - 2026-06-08
 
 ### ✨ Added

{spec_kitty_cli-3.2.0rc41 → spec_kitty_cli-3.2.0rc42}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spec-kitty-cli
-Version: 3.2.0rc41
+Version: 3.2.0rc42
 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

{spec_kitty_cli-3.2.0rc41 → spec_kitty_cli-3.2.0rc42}/docs/reference/README.md

@@ -1,6 +1,6 @@
 ---
 title: "Reference Documentation"
-description: "Reference for Reference Documentation in Spec Kitty 3.2, including exact CLI, file, schema, or runtime behavior."
+description: "Reference documentation overview for Spec Kitty. Access CLI commands, configuration parameters, slash command reference, and file layouts."
 ---
 
 # Reference Documentation

spec_kitty_cli-3.2.0rc42/kitty-specs/unblock-sync-identity-boundary-canary-01KRZJ07/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.0rc42/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.0rc41 → spec_kitty_cli-3.2.0rc42}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spec-kitty-cli"
-version = "3.2.0rc41"
+version = "3.2.0rc42"
 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.0rc41 → spec_kitty_cli-3.2.0rc42}/src/doctrine/missions/plan/mission-runtime.yaml

@@ -29,14 +29,14 @@ mission:
       description: Design and create planning artifacts
       order: 3
       depends_on: [research]
-      agent-profile: planner
+      agent-profile: planner-priti
 
     - id: review
       name: Review
       description: Review and validate planning artifacts
       order: 4
       depends_on: [plan]
-      agent-profile: reviewer
+      agent-profile: reviewer-renata
 
   runtime:
     loop_type: sequential

{spec_kitty_cli-3.2.0rc41 → spec_kitty_cli-3.2.0rc42}/src/doctrine/missions/software-dev/mission-runtime.yaml

@@ -33,7 +33,7 @@ mission:
 steps:
   - id: discovery
     title: Discovery & Research
-    agent-profile: researcher
+    agent-profile: researcher-robbie
     prompt_template: research.md
     description: Research technologies and best practices
 
@@ -46,28 +46,28 @@ steps:
   - id: plan
     title: Implementation Planning
     depends_on: [specify]
-    agent-profile: architect
+    agent-profile: architect-alphonso
     prompt_template: plan.md
     description: Design technical architecture
 
   - id: tasks
     title: Tasks
     depends_on: [plan]
-    agent-profile: planner
+    agent-profile: planner-priti
     prompt_template: tasks.md
     description: Create task breakdown, work package prompts, and finalized dependencies
 
   - id: implement
     title: Implementation
     depends_on: [tasks]
-    agent-profile: implementer
+    agent-profile: implementer-ivan
     prompt_template: implement.md
     description: Execute implementation
 
   - id: review
     title: Code Review
     depends_on: [implement]
-    agent-profile: reviewer
+    agent-profile: reviewer-renata
     prompt_template: review.md
     description: Review and validate
 

{spec_kitty_cli-3.2.0rc41 → spec_kitty_cli-3.2.0rc42}/src/doctrine/skills/spec-kitty-runtime-next/SKILL.md

@@ -557,13 +557,15 @@ Spec Kitty never spawns a parallel LLM call. You are the host; Spec Kitty routes
 3. **Execute**:
    Do the work. Generate the code, analysis, or plan.
 
-4. **Close the record**:
+4. **Close the Op** (mandatory — `do`/`ask`/`advise` leave it open):
    ```bash
    spec-kitty profile-invocation complete \
      --invocation-id <invocation_id> \
-     --outcome done
+     --outcome <done|failed|abandoned>
    ```
-   Use `failed` or `abandoned` as appropriate.
+   Use the real outcome: `done` for completed work, `failed` for work that did
+   not succeed, `abandoned` for dropped work. Never leave an Op open
+   deliberately — `spec-kitty doctor ops` reports and sweeps orphans.
 
 ### Trail produced
 

spec_kitty_cli-3.2.0rc42/src/doctrine/skills/spec-kitty.advise/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: spec-kitty.advise
+description: >-
+  Standalone profile-governed invocations: get governance context for an
+  action, open an Op, do the work under that context, and close the Op with
+  the real outcome. Documents the advise, ask, do, profiles list,
+  invocations list, and profile-invocation complete command surfaces.
+  Triggers: "use spec kitty to", "hey spec kitty", "spec kitty, fix/do/ask/advise",
+  ad-hoc requests that are not part of a running mission workflow.
+---
+
+# spec-kitty.advise
+
+Get governance context for an action and open an Op (invocation record).
+
+This skill documents the `advise`, `ask`, `do`, `profiles list`,
+`invocations list`, and `profile-invocation complete` command surfaces.
+
+## The open→work→close contract
+
+Every standalone invocation follows the same three-step lifecycle:
+
+1. **Open** — `spec-kitty do` (or `ask` / `advise`) opens the Op and loads
+   governance context. It does NOT do the work and it does NOT close the Op.
+2. **Work** — the agent does the work under that governance context.
+3. **Close** — the agent MUST close the Op with the real outcome:
+
+   ```bash
+   spec-kitty profile-invocation complete \
+     --invocation-id <id> \
+     --outcome <done|failed|abandoned> [--evidence <path>]
+   ```
+
+   Failed work closes as `failed` — an Op is never left open deliberately.
+   `spec-kitty doctor ops` reports orphaned (open) Ops, and
+   `spec-kitty doctor ops --close-stale` sweeps stale ones closed as
+   `abandoned` with `closed_by: doctor_sweep`.
+
+## Usage
+
+### Discover profiles
+```bash
+spec-kitty profiles list --json
+```
+
+### Get governance context (opens an Op)
+```bash
+spec-kitty advise "implement WP03" --json
+spec-kitty ask pedro "review WP05" --json
+spec-kitty do "implement the payment module" --json
+```
+
+Response fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `invocation_id` | string (ULID) | Unique ID for this Op |
+| `profile_id` | string | Resolved profile identifier |
+| `action` | string | Normalised action string |
+| `governance_context_text` | string | Full governance context assembled from the project DRG |
+| `governance_context_hash` | string | SHA-256 hash of `governance_context_text` |
+| `governance_context_available` | boolean | `false` when charter has not been synthesised |
+| `router_confidence` | string or null | Routing confidence score (auto-routing only) |
+| `status` | `"open"` | The Op is open until you close it |
+| `close_contract` | object | Exact close command, accepted outcomes, and flags |
+
+### Governance context injection
+
+After calling `advise`, `ask`, or `do`, the response includes a
+`governance_context_text` field.
+
+**You must inject this text into your working context before executing the task.**
+
+Steps:
+1. Read `governance_context_text` from the JSON response.
+2. Add the text to the beginning of your task execution context. Treat it as
+   binding governance: follow any directives, constraints, and guidelines it
+   contains when generating code, plans, or analyses.
+3. If `governance_context_available` is `false`, note it to the user
+   ("governance context unavailable — run `spec-kitty charter synthesize` to
+   build the DRG") but proceed with the task. The Op trail is still recorded.
+4. After completing the work, close the Op (see "Close the Op" below).
+
+The `governance_context_hash` field in the response is a checksum of the
+context used. It is stored in the Op record for provenance.
+
+### Close the Op
+```bash
+spec-kitty profile-invocation complete \
+  --invocation-id <id> \
+  --outcome <done|failed|abandoned>
+```
+
+`--outcome` is required and must reflect what actually happened: `done` for
+completed work, `failed` for work that did not succeed, `abandoned` for work
+that was dropped. Optional flags: `--evidence <path>`, `--artifact <ref>`,
+`--commit <sha>`.
+
+### Review recent invocations
+```bash
+# Newest 20 records (default)
+spec-kitty invocations list --json
+
+# Filter to one profile
+spec-kitty invocations list --profile pedro --json
+
+# Limit result count
+spec-kitty invocations list --limit 10 --json
+```
+
+## When to use
+
+| Situation | Command |
+|-----------|---------|
+| Before implementing — profile known | `spec-kitty ask <profile> "implement <mission>"` |
+| Before implementing — profile unknown | `spec-kitty do "implement <mission>"` |
+| After completing work | `spec-kitty profile-invocation complete --invocation-id <id> --outcome <done\|failed\|abandoned>` |
+| Audit what ran recently | `spec-kitty invocations list --json` |
+| Find orphaned (open) Ops | `spec-kitty doctor ops` |
+| Sweep stale open Ops | `spec-kitty doctor ops --close-stale` |
+
+## What gets recorded
+
+Every `advise` / `ask` / `do` call writes one JSONL file to
+`kitty-ops/<invocation_id>.jsonl` with a `started` event. Closing the Op
+appends a `completed` event carrying the real `outcome` and `closed_by`.
+
+An Op without a `completed` event is an **orphan** — visible in
+`spec-kitty invocations list` as `open`, reported by `spec-kitty doctor ops`,
+and surfaced at Claude Code session start/stop.
+
+## Invariants
+
+- `advise` / `ask` / `do` **never** spawn a separate LLM call.
+- `do` opens the Op and returns — it never closes the Op itself. The working
+  agent closes it with the real outcome.
+- `governance_context_text` is assembled from the project DRG; no network
+  calls are made if the charter has already been synthesised.
+- If `governance_context_available` is `false`, run
+  `spec-kitty charter synthesize` to build the DRG before the next invocation.

{spec_kitty_cli-3.2.0rc41 → spec_kitty_cli-3.2.0rc42}/src/mission_runtime/resolution.py

@@ -18,9 +18,9 @@ work package, workspace path, and any action-specific commands to run.
 """
 from __future__ import annotations
 
-from collections.abc import Mapping
+from collections.abc import Callable, Mapping, Sequence
 from pathlib import Path
-from typing import Literal, cast, get_args
+from typing import Any, Literal, cast, get_args
 
 from mission_runtime.context import ExecutionContext
 
@@ -162,35 +162,26 @@ def _resolve_review_wp_id(feature_dir: Path) -> str | None:
     try:
         events = read_events(feature_dir)
 
-        def _is_review_claimed(_wp_id: str) -> bool:
-            for event in reversed(events):
-                if getattr(event, "wp_id", None) == _wp_id:
-                    return bool(
-                        event.to_lane == Lane.IN_REVIEW  # new canonical shape
-                        or (
-                            event.to_lane == Lane.IN_PROGRESS  # legacy shape
-                            and event.review_ref == "action-review-claim"
-                        )
-                    )
-            return False
-
-        def _candidates() -> list[str]:
-            ids: list[str] = []
-            for wp_file in sorted(tasks_dir.glob("WP*.md")):
-                content = wp_file.read_text(encoding="utf-8-sig")
-                frontmatter, _, _ = split_frontmatter(content)
-                candidate_wp_id = extract_scalar(frontmatter, "work_package_id")
-                if candidate_wp_id:
-                    ids.append(str(candidate_wp_id))
-            return ids
-
-        for candidate_wp_id in _candidates():
-            if get_wp_lane(feature_dir, candidate_wp_id) == Lane.FOR_REVIEW:
-                return candidate_wp_id
+        candidate_wp_ids = _review_candidate_wp_ids(
+            tasks_dir,
+            extract_scalar=extract_scalar,
+            split_frontmatter=split_frontmatter,
+        )
 
-        for candidate_wp_id in _candidates():
+        review_ready_wp_id = _first_wp_in_lane(
+            feature_dir,
+            candidate_wp_ids,
+            target_lane=Lane.FOR_REVIEW,
+            get_wp_lane=get_wp_lane,
+        )
+        if review_ready_wp_id is not None:
+            return review_ready_wp_id
+
+        for candidate_wp_id in candidate_wp_ids:
             candidate_lane = get_wp_lane(feature_dir, candidate_wp_id)
-            if candidate_lane in (Lane.IN_PROGRESS, Lane.IN_REVIEW) and _is_review_claimed(candidate_wp_id):
+            if candidate_lane not in (Lane.IN_PROGRESS, Lane.IN_REVIEW):
+                continue
+            if _is_review_claimed(events, candidate_wp_id, Lane=Lane):
                 return candidate_wp_id
     except CanonicalStatusNotFoundError as exc:
         raise ActionContextError("CANONICAL_STATUS_NOT_FOUND", str(exc)) from exc
@@ -201,6 +192,54 @@ def _resolve_review_wp_id(feature_dir: Path) -> str | None:
     return None
 
 
+def _review_candidate_wp_ids(
+    tasks_dir: Path,
+    *,
+    extract_scalar: Callable[[str, str], str | None],
+    split_frontmatter: Callable[[str], tuple[str, str, str]],
+) -> list[str]:
+    candidate_wp_ids: list[str] = []
+    for wp_file in sorted(tasks_dir.glob("WP*.md")):
+        frontmatter = split_frontmatter(wp_file.read_text(encoding="utf-8-sig"))[0]
+        candidate_wp_id = extract_scalar(frontmatter, "work_package_id")
+        if candidate_wp_id:
+            candidate_wp_ids.append(str(candidate_wp_id))
+    return candidate_wp_ids
+
+
+def _first_wp_in_lane(
+    feature_dir: Path,
+    candidate_wp_ids: list[str],
+    *,
+    target_lane: object,
+    get_wp_lane: Callable[[Path, str], object],
+) -> str | None:
+    for candidate_wp_id in candidate_wp_ids:
+        if get_wp_lane(feature_dir, candidate_wp_id) == target_lane:
+            return candidate_wp_id
+    return None
+
+
+def _is_review_claimed(events: Sequence[Any], candidate_wp_id: str, *, Lane: Any) -> bool:
+    latest_event = next(
+        (
+            event
+            for event in reversed(events)
+            if getattr(event, "wp_id", None) == candidate_wp_id
+        ),
+        None,
+    )
+    if latest_event is None:
+        return False
+    return bool(
+        latest_event.to_lane == Lane.IN_REVIEW
+        or (
+            latest_event.to_lane == Lane.IN_PROGRESS
+            and latest_event.review_ref == "action-review-claim"
+        )
+    )
+
+
 def _resolve_wp_id(
     action: ActionName,
     feature_dir: Path,

{spec_kitty_cli-3.2.0rc41 → spec_kitty_cli-3.2.0rc42}/src/specify_cli/cli/commands/__init__.py

@@ -178,6 +178,7 @@ def register_commands(app: typer.Typer) -> None:
     from . import review as review_module
     from . import safe_commit_cmd as safe_commit_module
     from . import session_start as session_start_module
+    from . import session_stop as session_stop_module
     from . import sync as sync_module
     from . import upgrade as upgrade_module
     from . import validate_encoding as validate_encoding_module
@@ -220,6 +221,7 @@ def register_commands(app: typer.Typer) -> None:
     app.command(name="review")(review_module.review_mission)
     app.command(name="safe-commit")(safe_commit_module.safe_commit_command)
     app.command(name="session-start", help="Emit spec-kitty orientation for the Claude Code SessionStart hook.")(session_start_module.session_start)
+    app.command(name="session-stop", help="Emit the open-Ops reminder for the Claude Code Stop hook.")(session_stop_module.session_stop)
     app.add_typer(sync_module.app, name="sync", help="Synchronization commands")
     if tracker_module is not None:
         app.add_typer(tracker_module.app, name="tracker", help="Task tracker commands")