specpulse 1.3.3__py3-none-any.whl → 1.4.0__py3-none-any.whl

specpulse/resources/templates/task.md

@@ -1,165 +1,165 @@
-<!-- SpecPulse Task List Template v3.0 - AI-Optimized -->
-<!-- AI Instructions: Generate from implementation plan using constitutional gates -->
-
-# Task List: {{ feature_name }}
-
-## Metadata
-- **Plan Reference**: SPEC-{{ feature_id }}
-- **Total Tasks**: {{ task_count }}
-- **Estimated Duration**: {{ total_duration }}
-- **Parallel Groups**: {{ parallel_groups }}
-
-## Task Organization
-
-{% for group in parallel_groups %}
-### Parallel Group {{ loop.index }}
-*These tasks can be executed simultaneously*
-
-{% for task in group.tasks %}
-#### {{ task.id }}: {{ task.name }}
-- **Type**: {{ task.type }}
-- **Priority**: {{ task.priority }}
-- **Estimate**: {{ task.estimate }}
-- **Dependencies**: {{ task.dependencies | join(", ") | default("None") }}
-- **Description**: {{ task.description }}
-- **Acceptance**: {{ task.acceptance }}
-- **Files**: {{ task.files | join(", ") }}
-- **Assignable**: {{ task.assignable }}
-{% endfor %}
-{% endfor %}
-
-### Sequential Tasks
-*These tasks must be completed in order*
-
-{% for task in sequential_tasks %}
-#### {{ task.id }}: {{ task.name }}
-- **Dependencies**: {{ task.dependencies | join(", ") }}
-- **Type**: {{ task.type }}
-- **Priority**: {{ task.priority }}
-- **Estimate**: {{ task.estimate }}
-- **Description**: {{ task.description }}
-- **Acceptance**: {{ task.acceptance }}
-{% endfor %}
-
-### Critical Path
-*Tasks that directly impact timeline*
-
-{% for path in critical_path %}
-{{ loop.index }}. {{ path.tasks | join(" -> ") }}
-{% endfor %}
-- Estimated critical path duration: {{ critical_path_duration }}
-
-## Constitutional Gates Compliance
-
-### Pre-Implementation Validation
-{% for gate in constitutional_gates %}
-#### {{ gate.name }}
-- [ ] {{ gate.check_1 }}
-- [ ] {{ gate.check_2 }}
-- [ ] {{ gate.check_3 }}
-- [ ] {{ gate.check_4 }}
-**Status**: {{ gate.status | default("PENDING") }}
-{% endfor %}
-
-## Task Details by Category
-
-{% for category in task_categories %}
-### {{ category.name }} Tasks {% if category.parallel %}[P]{% endif %}
-{% for task in category.tasks %}
-- [ ] {{ task.id }}: {{ task.name }}
-{% endfor %}
-{% endfor %}
-
-## Execution Schedule
-
-{% for phase in execution_schedule %}
-### {{ phase.name }}
-{% for time_block in phase.time_blocks %}
-- {{ time_block.timing }}: {{ time_block.tasks | join(", ") }}{% if time_block.parallel %} (parallel){% endif %}
-{% endfor %}
-{% endfor %}
-
-## Progress Tracking
-```yaml
-status:
-  total: {{ task_count }}
-  completed: 0
-  in_progress: 0
-  blocked: 0
-  
-metrics:
-  velocity: {{ velocity | default("2-3 tasks/day") }}
-  estimated_completion: {{ estimated_completion }}
-  blockers: []
-  
-parallel_groups:
-{% for group in parallel_groups %}
-  - name: "{{ group.name }}"
-    tasks: [{{ group.tasks | map(attribute='id') | join(", ") }}]
-    can_start: {{ group.can_start }}
-{% endfor %}
-
-sequential_tasks:
-{% for task in sequential_tasks %}
-  - name: "{{ task.name }}"
-    id: {{ task.id }}
-    dependencies: [{{ task.dependencies | join(", ") }}]
-{% endfor %}
-```
-
-## Task Execution Guidelines
-
-### AI-Assisted Development Process
-All task execution should be handled by AI assistants (Claude or Gemini) following the SpecPulse methodology:
-
-1. **Task Selection**: AI assistants should select tasks based on:
-   - Dependency order (sequential tasks first)
-   - Parallel execution opportunities
-   - Current context and feature priorities
-   - Resource availability
-
-2. **Implementation Process**: For each task:
-   ```markdown
-   ## Task: {{ task.id }} - {{ task.name }}
-   
-   **Status**: [ ] Pending / [x] Completed / [-] In Progress / [!] Blocked
-   **Dependencies**: {{ task.dependencies | join(", ") | default("None") }}
-   **Acceptance**: {{ task.acceptance }}
-   ```
-
-3. **Parallel Execution Strategy**: When tasks can be executed in parallel:
-   - AI assistants should work on multiple tasks simultaneously
-   - Coordinate task completion status
-   - Handle cross-task dependencies
-   - Maintain code consistency
-
-### Task Dependencies Management
-
-- **Sequential Dependencies**: Tasks must be completed in specific order
-- **Parallel Opportunities**: Independent tasks can be worked on simultaneously
-- **Dependency Resolution**: AI should resolve conflicts and blocking issues
-- **Progress Coordination**: Multiple AI assistants should coordinate task completion
-
-## AI Integration Notes
-
-### Constitutional Gates
-- All tasks MUST pass constitutional compliance before implementation
-- Use `/sp-validate` command to check compliance status
-- Mark gates as completed only after actual validation
-
-### Progress Tracking
-- Update task status in real-time using markdown checkboxes: `[ ]` → `[-]` → `[x]`
-- Document blockers immediately with `[!]` status and resolution notes
-- Use velocity metrics to refine future estimates
-- Coordinate with other AI assistants for parallel task execution
-
-### Quality Assurance
-- Each task requires specific acceptance criteria
-- Test-first development mandated by Article III
-- Integration tests required before deployment
-
----
-**Generated by**: {{ ai_assistant }} on {{ date }}
-**Feature**: {{ feature_name }}
-**Constitutional Gates**: {{ constitutional_status | default("PENDING VALIDATION") }}
-**Next Steps**: Execute tasks following constitutional order
+<!-- SpecPulse Task List Template v3.0 - AI-Optimized -->
+<!-- AI Instructions: Generate from implementation plan using SDD gates -->
+
+# Task List: {{ feature_name }}
+
+## Metadata
+- **Plan Reference**: SPEC-{{ feature_id }}
+- **Total Tasks**: {{ task_count }}
+- **Estimated Duration**: {{ total_duration }}
+- **Parallel Groups**: {{ parallel_groups }}
+
+## Task Organization
+
+{% for group in parallel_groups %}
+### Parallel Group {{ loop.index }}
+*These tasks can be executed simultaneously*
+
+{% for task in group.tasks %}
+#### {{ task.id }}: {{ task.name }}
+- **Type**: {{ task.type }}
+- **Priority**: {{ task.priority }}
+- **Estimate**: {{ task.estimate }}
+- **Dependencies**: {{ task.dependencies | join(", ") | default("None") }}
+- **Description**: {{ task.description }}
+- **Acceptance**: {{ task.acceptance }}
+- **Files**: {{ task.files | join(", ") }}
+- **Assignable**: {{ task.assignable }}
+{% endfor %}
+{% endfor %}
+
+### Sequential Tasks
+*These tasks must be completed in order*
+
+{% for task in sequential_tasks %}
+#### {{ task.id }}: {{ task.name }}
+- **Dependencies**: {{ task.dependencies | join(", ") }}
+- **Type**: {{ task.type }}
+- **Priority**: {{ task.priority }}
+- **Estimate**: {{ task.estimate }}
+- **Description**: {{ task.description }}
+- **Acceptance**: {{ task.acceptance }}
+{% endfor %}
+
+### Critical Path
+*Tasks that directly impact timeline*
+
+{% for path in critical_path %}
+{{ loop.index }}. {{ path.tasks | join(" -> ") }}
+{% endfor %}
+- Estimated critical path duration: {{ critical_path_duration }}
+
+## SDD Gates Compliance
+
+### Pre-Implementation Validation
+{% for gate in SDD_gates %}
+#### {{ gate.name }}
+- [ ] {{ gate.check_1 }}
+- [ ] {{ gate.check_2 }}
+- [ ] {{ gate.check_3 }}
+- [ ] {{ gate.check_4 }}
+**Status**: {{ gate.status | default("PENDING") }}
+{% endfor %}
+
+## Task Details by Category
+
+{% for category in task_categories %}
+### {{ category.name }} Tasks {% if category.parallel %}[P]{% endif %}
+{% for task in category.tasks %}
+- [ ] {{ task.id }}: {{ task.name }}
+{% endfor %}
+{% endfor %}
+
+## Execution Schedule
+
+{% for phase in execution_schedule %}
+### {{ phase.name }}
+{% for time_block in phase.time_blocks %}
+- {{ time_block.timing }}: {{ time_block.tasks | join(", ") }}{% if time_block.parallel %} (parallel){% endif %}
+{% endfor %}
+{% endfor %}
+
+## Progress Tracking
+```yaml
+status:
+  total: {{ task_count }}
+  completed: 0
+  in_progress: 0
+  blocked: 0
+  
+metrics:
+  velocity: {{ velocity | default("2-3 tasks/day") }}
+  estimated_completion: {{ estimated_completion }}
+  blockers: []
+  
+parallel_groups:
+{% for group in parallel_groups %}
+  - name: "{{ group.name }}"
+    tasks: [{{ group.tasks | map(attribute='id') | join(", ") }}]
+    can_start: {{ group.can_start }}
+{% endfor %}
+
+sequential_tasks:
+{% for task in sequential_tasks %}
+  - name: "{{ task.name }}"
+    id: {{ task.id }}
+    dependencies: [{{ task.dependencies | join(", ") }}]
+{% endfor %}
+```
+
+## Task Execution Guidelines
+
+### AI-Assisted Development Process
+All task execution should be handled by AI assistants (Claude or Gemini) following the SpecPulse methodology:
+
+1. **Task Selection**: AI assistants should select tasks based on:
+   - Dependency order (sequential tasks first)
+   - Parallel execution opportunities
+   - Current context and feature priorities
+   - Resource availability
+
+2. **Implementation Process**: For each task:
+   ```markdown
+   ## Task: {{ task.id }} - {{ task.name }}
+   
+   **Status**: [ ] Pending / [x] Completed / [-] In Progress / [!] Blocked
+   **Dependencies**: {{ task.dependencies | join(", ") | default("None") }}
+   **Acceptance**: {{ task.acceptance }}
+   ```
+
+3. **Parallel Execution Strategy**: When tasks can be executed in parallel:
+   - AI assistants should work on multiple tasks simultaneously
+   - Coordinate task completion status
+   - Handle cross-task dependencies
+   - Maintain code consistency
+
+### Task Dependencies Management
+
+- **Sequential Dependencies**: Tasks must be completed in specific order
+- **Parallel Opportunities**: Independent tasks can be worked on simultaneously
+- **Dependency Resolution**: AI should resolve conflicts and blocking issues
+- **Progress Coordination**: Multiple AI assistants should coordinate task completion
+
+## AI Integration Notes
+
+### SDD Gates
+- All tasks MUST pass SDD compliance before implementation
+- Use `/sp-validate` command to check compliance status
+- Mark gates as completed only after actual validation
+
+### Progress Tracking
+- Update task status in real-time using markdown checkboxes: `[ ]` → `[-]` → `[x]`
+- Document blockers immediately with `[!]` status and resolution notes
+- Use velocity metrics to refine future estimates
+- Coordinate with other AI assistants for parallel task execution
+
+### Quality Assurance
+- Each task requires specific acceptance criteria
+- Testing strategy based on Principle 6: Quality Assurance
+- Appropriate tests for your project type
+
+---
+**Generated by**: {{ ai_assistant }} on {{ date }}
+**Feature**: {{ feature_name }}
+**SDD Gates**: {{ SDD_status | default("PENDING VALIDATION") }}
+**Next Steps**: Execute tasks following SDD order

specpulse/utils/version_check.py

@@ -0,0 +1,128 @@
+"""
+Version checking utility for SpecPulse
+"""
+
+import json
+import urllib.request
+import urllib.error
+from typing import Optional, Tuple
+from packaging import version
+import socket
+
+
+def check_pypi_version(package_name: str = "specpulse", timeout: int = 2) -> Optional[str]:
+    """
+    Check the latest version of a package on PyPI
+
+    Args:
+        package_name: Name of the package to check
+        timeout: Timeout in seconds for the request
+
+    Returns:
+        Latest version string or None if check fails
+    """
+    try:
+        # Set a short timeout to avoid blocking
+        socket.setdefaulttimeout(timeout)
+
+        url = f"https://pypi.org/pypi/{package_name}/json"
+        with urllib.request.urlopen(url) as response:
+            data = json.loads(response.read())
+            return data["info"]["version"]
+    except (urllib.error.URLError, urllib.error.HTTPError, json.JSONDecodeError, KeyError, socket.timeout):
+        # Silently fail - don't interrupt user workflow
+        return None
+    finally:
+        # Reset default timeout
+        socket.setdefaulttimeout(None)
+
+
+def compare_versions(current: str, latest: str) -> Tuple[bool, bool]:
+    """
+    Compare current version with latest version
+
+    Args:
+        current: Current installed version
+        latest: Latest available version
+
+    Returns:
+        Tuple of (is_outdated, is_major_update)
+    """
+    try:
+        current_v = version.parse(current)
+        latest_v = version.parse(latest)
+
+        is_outdated = current_v < latest_v
+
+        # Check if it's a major version update
+        is_major = False
+        if is_outdated:
+            # Major version changed
+            if latest_v.major > current_v.major:
+                is_major = True
+
+        return is_outdated, is_major
+    except:
+        return False, False
+
+
+def get_update_message(current: str, latest: str, is_major: bool) -> str:
+    """
+    Generate update notification message
+
+    Args:
+        current: Current version
+        latest: Latest version
+        is_major: Whether this is a major update
+
+    Returns:
+        Formatted update message
+    """
+    if is_major:
+        urgency = "[!] MAJOR"
+        color = "bright_red"
+    else:
+        urgency = "[i]"
+        color = "yellow"
+
+    message = f"""
+{urgency} Update Available!
+Current: v{current}
+Latest:  v{latest}
+
+Update with: pip install --upgrade specpulse
+"""
+
+    return message, color
+
+
+def should_check_version() -> bool:
+    """
+    Determine if we should check for updates
+
+    Returns:
+        True if we should check, False otherwise
+    """
+    import os
+    from pathlib import Path
+    from datetime import datetime, timedelta
+
+    try:
+        # Check once per day maximum
+        cache_file = Path.home() / ".specpulse" / "last_version_check"
+
+        if cache_file.exists():
+            # Check if last check was within 24 hours
+            last_check = datetime.fromtimestamp(cache_file.stat().st_mtime)
+            if datetime.now() - last_check < timedelta(hours=24):
+                return False
+
+        # Create cache directory if needed
+        cache_file.parent.mkdir(parents=True, exist_ok=True)
+
+        # Update timestamp
+        cache_file.touch()
+        return True
+    except:
+        # If anything fails, don't check
+        return False

{specpulse-1.3.3.dist-info → specpulse-1.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specpulse
-Version: 1.3.3
+Version: 1.4.0
 Summary: Specification-Driven Development Framework
 Home-page: https://github.com/specpulse
 Author: SpecPulse
@@ -32,6 +32,7 @@ Requires-Dist: rich>=13.0
 Requires-Dist: jinja2>=3.0
 Requires-Dist: gitpython>=3.1
 Requires-Dist: toml>=0.10
+Requires-Dist: packaging>=21.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0; extra == "dev"
@@ -56,7 +57,7 @@ Dynamic: requires-python
 
 *Build better software faster by putting specifications first and letting AI handle the implementation details.*
 
-[Installation](#-installation) • [Quick Start](#-quick-start) • [Features](#-features) • [Documentation](#-documentation) • [Contributing](#-contributing)
+[Installation](#-installation) • [Quick Start](#-quick-start) • [Usage Guide](#-usage-guide) • [Features](#-features) • [Documentation](#-documentation) • [Contributing](#-contributing)
 
 </div>
 
@@ -64,21 +65,22 @@ Dynamic: requires-python
 
 ## 🎯 What is SpecPulse?
 
-SpecPulse revolutionizes AI-assisted development by enforcing a **specification-first approach**. Instead of jumping straight into code, SpecPulse ensures every feature starts with clear specifications, validated plans, and tracked tasks - guaranteeing quality from day one.
+SpecPulse is a universal **Specification-Driven Development (SDD)** framework that works with ANY software project - web apps, mobile apps, desktop software, games, APIs, ML projects, and more. It ensures every feature starts with clear specifications, validated plans, and tracked tasks.
 
-> **Latest Update (v1.3.0)**:
-> - 🚀 **Continuous Task Execution**: New `/sp-execute` command for non-stop task completion
-> - ⚡ **Flow State Development**: Execute all tasks without interruptions
-> - 🔄 **Smart Task Progression**: Automatic advancement through task lists
-> - 🎯 **Batch Processing**: Complete entire features in one command
-> - **Previous (v1.2.0)**: Microservice decomposition, service-based planning, smart workflow detection
-> - **Previous (v1.1.0)**: Command prefix system, multi-spec workflow, versioned files
+> **Latest Update (v1.4.0)** - Complete Framework Revolution:
+> - 🚀 **Universal SDD Framework**: Transformed from Constitutional to Specification-Driven Development
+> - 🎯 **No Technology Restrictions**: Support for ANY technology stack - web, mobile, desktop, games, ML
+> - 🧪 **86% Test Coverage**: Complete test suite rewrite with 98.3% success rate
+> - ✨ **9 Universal Principles**: Flexible principles replacing rigid articles
+> - 🔄 **Major API Updates**: All methods renamed from `constitution` to `sdd_compliance`
+> - 📝 **Enhanced Documentation**: Complete overhaul of docs and templates
 
 ### Why SpecPulse?
 
+- **🎯 Universal**: Works with ANY project type - web, mobile, desktop, games, APIs, ML
 - **🔍 Clarity First**: No more ambiguous requirements or scope creep
 - **🤖 AI-Optimized**: Designed specifically for Claude and Gemini workflows
-- **✅ Quality Gates**: Built-in checks prevent bad code from entering your codebase
+- **✅ Quality Gates**: Built-in checks ensure quality for your specific project type
 - **📊 Full Traceability**: Every decision, change, and requirement is tracked
 - **🚀 Faster Delivery**: Structured approach reduces rework and debugging time
 
@@ -175,21 +177,21 @@ specpulse sync
 
 ## ✨ Features
 
-### 🏛️ Constitutional Development
+### 🏛️ Universal SDD Principles
 
-Nine immutable principles guide every line of code:
+Nine principles that enable Specification-Driven Development for ANY project:
 
-| Article | Principle | Benefit |
-|---------|-----------|---------|
-| **I** | Library-First | Every feature is modular and reusable |
-| **II** | CLI Interface | Text-based interaction for automation |
-| **III** | Test-First | Tests before code, always |
-| **IV** | Staged Implementation | Incremental, validated progress |
-| **V** | Direct Framework Usage | No unnecessary abstractions |
-| **VI** | No Abstraction Layers | Keep it simple, keep it maintainable |
-| **VII** | Simplicity Enforcement | Maximum 3 modules per feature |
-| **VIII** | Complexity Tracking | Document and justify exceptions |
-| **IX** | Framework-First | Don't reinvent the wheel |
+| # | Principle | Purpose | Applies To |
+|---|-----------|---------|------------|
+| **1** | Specification First | Start with clear requirements | All projects |
+| **2** | Incremental Planning | Phased implementation | Web, mobile, desktop, games |
+| **3** | Task Decomposition | Concrete, executable tasks | Any technology stack |
+| **4** | Traceable Implementation | Link code to specs | All languages |
+| **5** | Continuous Validation | Ensure spec alignment | Any framework |
+| **6** | Quality Assurance | Appropriate testing | GUI, CLI, API, games |
+| **7** | Architecture Documentation | Record decisions | Any architecture |
+| **8** | Iterative Refinement | Evolve with learnings | All methodologies |
+| **9** | Stakeholder Alignment | Shared understanding | Any team size |
 
 ### 🚦 Phase Gates System
 
@@ -201,10 +203,10 @@ Before any code is written, features must pass:
 └────────┬────────┘
          ↓
 ┌─────────────────┐
-│ Phase Gates     │ → Constitutional compliance check
-└────────┬────────┘     Simplicity validation (≤3 modules)
-         ↓              Test strategy defined
-┌─────────────────┐     Framework selected
+│ Phase Gates     │ → SDD compliance check
+└────────┬────────┘     Quality assurance strategy defined
+         ↓              Architecture documented
+┌─────────────────┐     Stakeholder alignment confirmed
 │ Implementation  │     Research completed
 └────────┬────────┘
          ↓
@@ -253,7 +255,7 @@ memory/
 
 - **Persistent Context**: Never lose track of project state
 - **Decision History**: Understand why choices were made
-- **Constitutional Enforcement**: Principles that can't be violated
+- **SDD Enforcement**: Universal principles for any software project
 
 ### 🔍 [NEEDS CLARIFICATION] Markers
 
@@ -573,6 +575,45 @@ pytest tests/
 - **[GitHub Repository](https://github.com/specpulse/specpulse)** - Source code and issues
 - **Command Reference** - See AI Integration section above for full command list
 
+## 📚 Usage Guide
+
+### How to Break Your Project into Features (Pulses)
+
+A complete guide is available in **[SPECPULSE_USAGE_GUIDE.md](SPECPULSE_USAGE_GUIDE.md)** which covers:
+- Feature decomposition strategies
+- Sizing guidelines (3-15 tasks per pulse)
+- Naming conventions (001-feature-name format)
+- Real-world examples for different project types
+- Best practices for feature boundaries
+
+#### Quick Examples
+
+**E-Commerce Platform:**
+```
+001-user-authentication    # Registration, login, sessions
+002-product-catalog        # Products, categories, search
+003-shopping-cart          # Cart management, calculations
+004-payment-processing     # Gateway, transactions, receipts
+005-order-management       # History, tracking, refunds
+```
+
+**SaaS Application:**
+```
+001-tenant-management      # Multi-tenancy, workspaces
+002-subscription-billing   # Plans, payments, invoices
+003-api-management        # Keys, rate limiting, docs
+004-admin-dashboard       # Analytics, reports, settings
+005-webhook-system        # Events, notifications, logs
+```
+
+**Key Principles:**
+- Each pulse should be **independent** and **testable**
+- Size appropriately for your project type
+- Use **sequential numbering** (001, 002, 003...)
+- Follow the **9 universal SDD principles**
+
+See the full guide for detailed breakdowns and strategies.
+
 ## 📄 License
 
 MIT License - see [LICENSE](LICENSE) file for details.