Priivacy-ai/spec-kitty v0.4.9

on GitHub

Added

• Diagnostics CLI Command – New spec-kitty diagnostics command with human-readable and JSON output for comprehensive project health checks.
• Dashboard Process Tracking – Dashboard now stores process PID in .dashboard metadata file for reliable cleanup and monitoring.
• Feature Collision Detection – Added explicit warnings when creating features with duplicate names that would overwrite existing work.
• LLM Context Documentation – Enhanced all 13 command templates with location pre-flight checks, file discovery sections, and workflow context to prevent agents from getting lost.

Changed

• Dashboard Lifecycle – Enhanced ensure_dashboard_running() to automatically clean up orphaned dashboard processes on initialization, preventing port exhaustion.
• Feature Creation Warnings – create-new-feature.sh now warns when git is disabled or features already exist, with clear JSON indicators for LLM agents.
• Import Safety – Fixed detect_feature_slug import path in diagnostics module to use correct module location.
• Worktree Documentation – Updated WORKTREE_MODEL.md to accurately describe .kittify/ as a complete copy (not symlink) with disk space implications documented.

Fixed

• CRITICAL: Dashboard Process Orphan Leak – Fixed critical bug where background dashboard processes were orphaned and accumulated until all ports were exhausted. Complete fix includes:

  • PIDs are captured and stored in .dashboard file (commit b8c7394)
  • Orphaned processes with .dashboard files are automatically cleaned up on next init
  • HTTP shutdown failures fall back to SIGTERM/SIGKILL with PID tracking
  • Port range cleanup scans for orphaned dashboards without .dashboard files (commit 11340a4)
  • Safe fingerprinting via health check API prevents killing unrelated services
  • Automatic retry with cleanup when port exhaustion detected
  • Failed startup processes are cleaned up (no orphans from Ctrl+C during health check)
  • Multi-project scenarios remain fully isolated (per-project PIDs, safe port sweeps)
  • Handles all orphan types: with metadata, without metadata, deleted temp projects
  • Prevents "Could not find free port" errors after repeated uses

• Import Path Bug – Fixed detect_feature_slug import in src/specify_cli/dashboard/diagnostics.py to import from specify_cli.acceptance instead of package root.

• Worktree Documentation Accuracy – Corrected WORKTREE_MODEL.md which incorrectly stated .kittify/ was symlinked; it's actually a complete copy due to git worktree behavior.

LLM Context Improvements

All command templates enhanced with consistent context patterns:

• Location Pre-flight Checks: pwd/git branch verification with expected outputs and correction steps
• File Discovery: Lists what files {SCRIPT} provides, output locations, and available context
• Workflow Context: Documents before/after commands and feature lifecycle integration

Templates updated:

• merge.md: CRITICAL safety check preventing merges from wrong location
• clarify.md, research.md, analyze.md: HIGH priority core workflow commands
• specify.md, checklist.md: Entry point and utility commands
• constitution.md, dashboard.md: Project-level and monitoring commands

Testing

• ✅ Dashboard comprehensive test suite (34 tests, 100% coverage)
• ✅ All CLI commands validated
• ✅ Import paths verified
• ✅ Worktree behavior confirmed across test scenarios
• ✅ LLM context patterns applied consistently

Security

• Dashboard process cleanup prevents resource exhaustion attacks
• Explicit warnings when creating duplicate features prevent silent data overwrite
• Git disabled warnings ensure users know when version control is unavailable

Backward Compatibility

All changes are fully backward compatible:

• PID storage is optional (old .dashboard files still work)
• Feature collision detection is advisory (doesn't block creation)
• LLM context additions don't change command behavior
• Dashboard cleanup is automatic (users don't need to do anything)