specpulse 1.0.4__py3-none-any.whl → 1.0.6__py3-none-any.whl

specpulse/resources/scripts/pulse-task.sh

@@ -1,23 +1,137 @@
 #!/bin/bash
 # Generate task breakdown
 
-FEATURE_DIR="${1}"
+set -euo pipefail  # Exit on error, unset vars, pipe failures
 
+# Configuration
+SCRIPT_NAME="$(basename "$0")"
+PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+
+# Function to log messages
+log() {
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $SCRIPT_NAME: $1" >&2
+}
+
+# Function to handle errors
+error_exit() {
+    log "ERROR: $1"
+    exit 1
+}
+
+# Validate arguments
+if [ $# -eq 0 ]; then
+    error_exit "Usage: $SCRIPT_NAME <feature-dir>"
+fi
+
+FEATURE_DIR="$1"
+
+# Sanitize feature directory
+SANITIZED_DIR=$(echo "$FEATURE_DIR" | sed 's/[^a-zA-Z0-9_-]//g')
+
+if [ -z "$SANITIZED_DIR" ]; then
+    error_exit "Invalid feature directory: '$FEATURE_DIR'"
+fi
+
+# Find feature directory if not provided
 if [ -z "$FEATURE_DIR" ]; then
-    # Find current feature from context
-    FEATURE_DIR=$(grep -A1 "Active Feature" memory/context.md | tail -1 | cut -d: -f2 | xargs)
+    CONTEXT_FILE="$PROJECT_ROOT/memory/context.md"
+    if [ -f "$CONTEXT_FILE" ]; then
+        FEATURE_DIR=$(grep -A1 "Active Feature" "$CONTEXT_FILE" | tail -1 | cut -d: -f2 | xargs)
+        if [ -z "$FEATURE_DIR" ]; then
+            error_exit "No active feature found in context file"
+        fi
+        log "Using active feature from context: $FEATURE_DIR"
+    else
+        error_exit "No feature directory provided and no context file found"
+    fi
 fi
 
-TASK_FILE="tasks/${FEATURE_DIR}/tasks.md"
+TASK_FILE="$PROJECT_ROOT/tasks/${FEATURE_DIR}/tasks.md"
+TEMPLATE_FILE="$PROJECT_ROOT/templates/task.md"
+PLAN_FILE="$PROJECT_ROOT/plans/${FEATURE_DIR}/plan.md"
+SPEC_FILE="$PROJECT_ROOT/specs/${FEATURE_DIR}/spec.md"
+
+# Ensure tasks directory exists
+mkdir -p "$(dirname "$TASK_FILE")"
+
+# Check if specification and plan exist first
+if [ ! -f "$SPEC_FILE" ]; then
+    error_exit "Specification file not found: $SPEC_FILE. Please create specification first."
+fi
 
-# Ensure template exists
+if [ ! -f "$PLAN_FILE" ]; then
+    error_exit "Implementation plan not found: $PLAN_FILE. Please create plan first."
+fi
+
+# Ensure task template exists
+if [ ! -f "$TEMPLATE_FILE" ]; then
+    error_exit "Template not found: $TEMPLATE_FILE"
+fi
+
+# Create task file if it doesn't exist
 if [ ! -f "$TASK_FILE" ]; then
-    cp templates/task.md "$TASK_FILE"
+    log "Creating task breakdown from template: $TASK_FILE"
+    cp "$TEMPLATE_FILE" "$TASK_FILE" || error_exit "Failed to copy task template"
+else
+    log "Task breakdown already exists: $TASK_FILE"
+fi
+
+# Validate task structure
+log "Validating task breakdown..."
+
+# Check for required sections
+REQUIRED_SECTIONS=("## Task List:" "## Task Organization" "## Critical Path" "## Execution Schedule")
+MISSING_SECTIONS=()
+
+for section in "${REQUIRED_SECTIONS[@]}"; do
+    if ! grep -q "$section" "$TASK_FILE"; then
+        MISSING_SECTIONS+=("$section")
+    fi
+done
+
+if [ ${#MISSING_SECTIONS[@]} -gt 0 ]; then
+    log "WARNING: Missing required sections: ${MISSING_SECTIONS[*]}"
+fi
+
+# Count tasks and analyze structure
+TOTAL_TASKS=$(grep -c "^- \[.\]" "$TASK_FILE" 2>/dev/null || echo "0")
+COMPLETED_TASKS=$(grep -c "^- \[x\]" "$TASK_FILE" 2>/dev/null || echo "0")
+PENDING_TASKS=$(grep -c "^- \[ \]" "$TASK_FILE" 2>/dev/null || echo "0")
+BLOCKED_TASKS=$(grep -c "^- \[!\]" "$TASK_FILE" 2>/dev/null || echo "0")
+
+# Check for parallel tasks
+PARALLEL_TASKS=$(grep -c "\[P\]" "$TASK_FILE" 2>/dev/null || echo "0")
+
+# Check constitutional gates compliance
+CONSTITUTIONAL_SECTION=$(grep -A 20 "Constitutional Gates Compliance" "$TASK_FILE" 2>/dev/null || echo "")
+GATES_COUNT=$(echo "$CONSTITUTIONAL_SECTION" | grep -c "\[ \]" 2>/dev/null || echo "0")
+
+# Check if plan has constitutional gates completed
+PLAN_GATE_STATUS=$(grep -A5 "Gate Status:" "$PLAN_FILE" | tail -1 | sed 's/.*\[\(.*\)\].*/\1/' || echo "PENDING")
+
+if [ "$PLAN_GATE_STATUS" != "COMPLETED" ]; then
+    log "WARNING: Implementation plan constitutional gates not completed. Task generation may be premature."
+fi
+
+# Calculate completion percentage
+if [ "$TOTAL_TASKS" -gt 0 ]; then
+    COMPLETION_PERCENTAGE=$((COMPLETED_TASKS * 100 / TOTAL_TASKS))
+else
+    COMPLETION_PERCENTAGE=0
 fi
 
-# Count tasks
-TASK_COUNT=$(grep -c "^- \[" "$TASK_FILE" 2>/dev/null || echo "0")
+log "Task analysis completed - Total: $TOTAL_TASKS, Completed: $COMPLETED_TASKS ($COMPLETION_PERCENTAGE%), Parallel: $PARALLEL_TASKS"
 
+# Output comprehensive status
 echo "TASK_FILE=$TASK_FILE"
-echo "TASK_COUNT=$TASK_COUNT"
+echo "SPEC_FILE=$SPEC_FILE"
+echo "PLAN_FILE=$PLAN_FILE"
+echo "TOTAL_TASKS=$TOTAL_TASKS"
+echo "COMPLETED_TASKS=$COMPLETED_TASKS"
+echo "PENDING_TASKS=$PENDING_TASKS"
+echo "BLOCKED_TASKS=$BLOCKED_TASKS"
+echo "PARALLEL_TASKS=$PARALLEL_TASKS"
+echo "CONSTITUTIONAL_GATES_PENDING=$GATES_COUNT"
+echo "COMPLETION_PERCENTAGE=$COMPLETION_PERCENTAGE"
+echo "MISSING_SECTIONS=${#MISSING_SECTIONS[@]}"
 echo "STATUS=generated"

specpulse/resources/templates/plan.md

@@ -1,13 +1,13 @@
-<!-- SpecPulse Implementation Plan Template v3.0 -->
-<!-- AI Instructions: Generate plan from specification following SDD methodology -->
+<!-- SpecPulse Implementation Plan Template v4.0 - AI-Optimized -->
+<!-- AI Instructions: Generate plan from specification following constitutional gates -->
 
-# Implementation Plan: [FEATURE_NAME]
+# Implementation Plan: {{ feature_name }}
 
 ## Specification Reference
-- **Spec ID**: SPEC-[XXX]
-- **Branch**: [feature-branch-name]
-- **Generated**: [DATE]
-- **Optimization Focus**: [PERFORMANCE|SECURITY|SIMPLICITY|COST]
+- **Spec ID**: SPEC-{{ feature_id }}
+- **Branch**: {{ branch_name }}
+- **Generated**: {{ date }}
+- **Optimization Focus**: {{ optimization_focus | default("SIMPLICITY") }}
 
 ## Phase -1: Pre-Implementation Gates
 
@@ -20,8 +20,6 @@
 - [ ] Direct framework usage (no unnecessary wrappers)?
 - [ ] Single model representation per concept?
 
-**If any checkbox is unchecked, document in Complexity Tracking below**
-
 #### Anti-Abstraction Gate (Article VII)
 - [ ] Using framework features directly?
 - [ ] No unnecessary abstraction layers?
@@ -44,308 +42,165 @@
 - [ ] Library options researched?
 - [ ] Performance implications documented?
 - [ ] Security considerations analyzed?
-- [ ] Trade-offs documented in research.md?
+- [ ] Trade-offs documented?
 
-**Gate Status**: [ ] PASSED / [ ] BLOCKED (See Complexity Tracking)
+**Gate Status**: {{ gate_status | default("[ ] PENDING") }}
 
 ## Complexity Tracking
+{% if complexity_exceptions %}
+{% for exception in complexity_exceptions %}
+### Exception {{ loop.index }}
+- **Article**: {{ exception.article }}
+- **Violation**: {{ exception.violation }}
+- **Justification**: {{ exception.justification }}
+- **Mitigation**: {{ exception.mitigation }}
+{% endfor %}
+{% else %}
+No complexity exceptions documented.
+{% endif %}
 
-### Justified Exceptions
-```yaml
-complexity_exceptions:
-  # Example:
-  # - article: VII
-  #   violation: "Using 4 modules instead of 3"
-  #   justification: "Authentication requires separate service for security isolation"
-  #   approved_by: "[Approver]"
-  #   date: "[DATE]"
-```
-
-### Simplification Opportunities
-- [ ] Areas identified for future simplification
-- [ ] Technical debt documented
-- [ ] Refactoring planned for Phase X
+## Technology Stack
 
-## Research Summary
-**[Link to detailed research.md]**
+### Core Technologies
+{% for tech in core_technologies %}
+- **{{ tech.name }}**: {{ tech.version }} - {{ tech.purpose }}
+{% endfor %}
 
-### Library Selection
-| Purpose | Options Evaluated | Selected | Rationale |
-|---------|------------------|----------|-----------|
-| [Need] | [Option1, Option2] | [Choice] | [Why] |
+### Dependencies
+{% for dep in dependencies %}
+- **{{ dep.name }}**: {{ dep.reason }}
+{% endfor %}
 
-### Performance Analysis
-- Expected load: [metrics]
-- Bottlenecks identified: [list]
-- Optimization strategy: [approach]
+## Architecture Overview
 
-### Security Considerations
-- Attack vectors considered: [list]
-- Mitigations planned: [list]
-- Compliance requirements: [list]
+### System Components
+{% for component in components %}
+#### {{ component.name }}
+- **Purpose**: {{ component.purpose }}
+- **Key Features**: {{ component.features }}
+- **Dependencies**: {{ component.dependencies | join(", ") }}
+{% endfor %}
+
+### Data Models
+{% for model in data_models %}
+#### {{ model.name }}
+- **Fields**: {{ model.fields | join(", ") }}
+- **Relationships**: {{ model.relationships }}
+- **Validation**: {{ model.validation }}
+{% endfor %}
 
-## Architecture Overview
+## Implementation Phases
 
-### Library-First Design (Article I)
-```
-[feature-name]-lib/
-├── cli/              # CLI interface (Article II)
-│   └── main.py       # Text in/out, JSON support
-├── core/             # Core library logic
-│   ├── __init__.py   # Public API
-│   └── [modules]/    # Internal modules
-├── tests/            # Test-First (Article III)
-│   ├── contracts/    # Contract tests first
-│   ├── integration/  # Integration tests second
-│   ├── e2e/         # End-to-end tests third
-│   └── unit/        # Unit tests last
-└── docs/            # Executable documentation (Article IX)
+### Phase 0: Critical Path (Week {{ phase_0.weeks | default(1) }})
+{% for task in phase_0.tasks %}
+- [ ] {{ task.description }}
+{% endfor %}
+
+### Phase 1: Foundation (Week {{ phase_1.weeks | default(2) }})
+{% for task in phase_1.tasks %}
+- [ ] {{ task.description }}
+{% endfor %}
+
+### Phase 2: Core Features (Week {{ phase_2.weeks | default(3) }})
+{% for task in phase_2.tasks %}
+- [ ] {{ task.description }}
+{% endfor %}
+
+### Phase 3: Polish (Week {{ phase_3.weeks | default(1) }})
+{% for task in phase_3.tasks %}
+- [ ] {{ task.description }}
+{% endfor %}
+
+## API Contracts
+
+### Endpoints
+{% for endpoint in endpoints %}
+#### {{ endpoint.method }} {{ endpoint.path }}
+- **Description**: {{ endpoint.description }}
+- **Request**: {{ endpoint.request }}
+- **Response**: {{ endpoint.response }}
+- **Authentication**: {{ endpoint.auth | default("Required") }}
+{% endfor %}
+
+### Data Schemas
+{% for schema in schemas %}
+#### {{ schema.name }}
+```json
+{{ schema.json | indent(4) }}
 ```
+{% endfor %}
 
-### System Architecture
-```mermaid
-graph TB
-    subgraph "Library Architecture"
-        CLI[CLI Interface] --> Core[Core Library]
-        Core --> Data[Data Layer]
-        Core --> Services[Service Layer]
-    end
-    
-    subgraph "Testing Strategy"
-        CT[Contract Tests] --> IT[Integration Tests]
-        IT --> E2E[E2E Tests]
-        E2E --> UT[Unit Tests]
-    end
-```
+## Testing Strategy
 
-## Technology Stack
+### Test Categories
+- **Unit Tests**: {{ testing.unit.target | default("80% coverage") }}
+- **Integration Tests**: {{ testing.integration.target | default("Critical paths") }}
+- **E2E Tests**: {{ testing.e2e.target | default("Key user workflows") }}
+- **Performance Tests**: {{ testing.performance.target | default("Load testing") }}
 
-### Core Technologies (Justified per Article VI)
-- **Language**: [Choice] - [Research-backed rationale]
-- **Framework**: [Choice] - [Why not alternatives]
-- **Database**: [Choice] - [Performance/scale rationale]
-- **Testing**: [Choice] - [Integration capability rationale]
+### Test Environment
+- **Database**: {{ testing.environment.database | default("PostgreSQL") }}
+- **Services**: {{ testing.environment.services | join(", ") }}
+- **Test Data**: {{ testing.environment.data_strategy | default("Seed with realistic data") }}
 
-### Complexity Budget (Article VII)
-- Module 1: [Purpose]
-- Module 2: [Purpose]
-- Module 3: [Purpose] (if needed)
-- **Total Modules**: [2-3] ✓
+## Security Considerations
 
-## Implementation Phases
+### Authentication & Authorization
+- **Method**: {{ security.auth_method | default("JWT tokens") }}
+- **Roles**: {{ security.roles | join(", ") }}
+- **Permissions**: {{ security.permissions_model | default("Role-based access control") }}
 
-### Phase 0: Test Infrastructure Setup
-**Duration**: [Estimate]
-**Gate**: Must pass all Article III requirements
-
-1. **Setup Test Environment**
-   - [ ] Real database instance (not mocks)
-   - [ ] Service dependencies running
-   - [ ] Production-like configuration
-
-2. **Write Contract Tests** (Article VIII priority)
-   ```python
-   # contracts/test_api_contract.py
-   def test_api_contract_failing():
-       """This test MUST fail initially per Article III"""
-       assert False  # Red phase
-   ```
-
-3. **Write Integration Tests**
-   ```python
-   # integration/test_service_integration.py
-   def test_service_integration_failing():
-       """Test service with real dependencies"""
-       assert False  # Red phase
-   ```
-
-### Phase 1: Library Core Implementation
-**Duration**: [Estimate]
-**Gate**: All tests from Phase 0 must be failing
-
-1. **CLI Interface** (Article II)
-   ```python
-   # cli/main.py structure
-   def main():
-       """Accept text input, produce text output"""
-       pass
-   ```
-
-2. **Core Library** (Article I)
-   - [ ] Minimal implementation to pass first test
-   - [ ] No premature optimization
-   - [ ] Direct framework usage
-
-3. **Make Tests Pass** (Green phase)
-   - [ ] Contract tests passing
-   - [ ] Integration tests passing
-   - [ ] Refactor while green
-
-### Phase 2: Feature Completion
-**Duration**: [Estimate]
-**Gate**: Core tests passing, ready for features
-
-1. **User Story Implementation**
-   - [ ] Story 1: [Title] - Tests first, then code
-   - [ ] Story 2: [Title] - Tests first, then code
-   - [ ] Story 3: [Title] - Tests first, then code
-
-2. **End-to-End Testing**
-   - [ ] Critical path tests with real services
-   - [ ] Performance benchmarks
-   - [ ] Security scenarios
-
-### Phase 3: Production Readiness
-**Duration**: [Estimate]
-**Gate**: All acceptance criteria met
-
-1. **Documentation** (Article IX - Executable)
-   ```markdown
-   # Quick Start (executable)
-   $ pip install feature-lib
-   $ feature-cli --help
-   $ echo "input" | feature-cli process
-   ```
-
-2. **Observability**
-   - [ ] Logging with structure
-   - [ ] Metrics exposed
-   - [ ] Health checks
-
-3. **Deployment**
-   - [ ] CI/CD pipeline
-   - [ ] Rollback capability
-   - [ ] Feature flags
-
-## Test-First Development Plan
-
-### Test Execution Order (Article III & VIII)
-1. **Contract Tests** → Define boundaries
-2. **Integration Tests** → Verify interactions
-3. **E2E Tests** → Validate workflows
-4. **Unit Tests** → Isolate logic
-
-### Test Coverage Requirements
-- Contract Tests: 100% of API surface
-- Integration Tests: 100% of service interactions
-- E2E Tests: 100% of critical paths
-- Unit Tests: 80% of business logic
-
-### Example Test Structure
-```python
-# Step 1: Write failing test (Red)
-def test_feature_behavior():
-    result = feature.process("input")
-    assert result == "expected"  # Fails
-
-# Step 2: Implement minimum to pass (Green)
-def process(input):
-    return "expected"  # Passes
-
-# Step 3: Refactor (Refactor)
-def process(input):
-    # Clean, maintainable implementation
-    return transform(validate(input))
-```
+### Data Protection
+- **Encryption**: {{ security.encryption.transit | default("TLS 1.3") }} in transit, {{ security.encryption.at_rest | default("AES-256") }} at rest
+- **Compliance**: {{ security.compliance | join(", ") }}
 
-## API Contracts (Article VIII - Contract First)
-
-### Contract: [Feature API]
-```yaml
-# contracts/feature-api.yaml
-openapi: 3.0.0
-paths:
-  /process:
-    post:
-      request:
-        required: true
-        content:
-          text/plain:
-            schema:
-              type: string
-      responses:
-        '200':
-          content:
-            application/json:
-              schema:
-                type: object
-```
+## Deployment Strategy
 
-### Contract Test
-```python
-# contracts/test_feature_contract.py
-def test_process_contract():
-    """Verify API contract compliance"""
-    response = client.post("/process", data="input")
-    assert response.status_code == 200
-    assert "result" in response.json()
-```
+### Environments
+{% for env in environments %}
+#### {{ env.name }}
+- **URL**: {{ env.url }}
+- **Auto-deploy**: {{ env.auto_deploy | default("Manual") }}
+- **Health Checks**: {{ env.health_checks | default("Basic monitoring") }}
+{% endfor %}
 
-## Data Models (Simple per Article VII)
-
-### Primary Entity
-```python
-# Single, simple model - no premature abstraction
-@dataclass
-class Feature:
-    id: str
-    data: str
-    created_at: datetime
-    
-    def process(self) -> str:
-        """Direct, simple processing"""
-        return self.data.upper()  # No unnecessary layers
-```
+### Rollback Plan
+- **Strategy**: {{ rollback.strategy | default("Blue-green deployment") }}
+- **Triggers**: {{ rollback.triggers | join(", ") }}
+- **Recovery Time**: {{ rollback.recovery_time | default("< 5 minutes") }}
 
-## Risk Mitigation
+## Success Criteria
 
-### Complexity Risks (Article VII)
-| Risk | Mitigation |
-|------|------------|
-| Over-engineering | Phase gates enforce simplicity |
-| Premature optimization | Start simple, measure first |
-| Abstraction creep | Direct framework usage required |
+### Must-Have Metrics
+{% for metric in success_criteria.must %}
+- {{ metric.name }}: {{ metric.target }} ({{ metric.measurement }})
+{% endfor %}
 
-### Testing Risks (Article III)
-| Risk | Mitigation |
-|------|------------|
-| Skipping TDD | Gates require failing tests first |
-| Mock overuse | Real services required |
-| Low coverage | Coverage gates enforced |
+### Should-Have Metrics
+{% for metric in success_criteria.should %}
+- {{ metric.name }}: {{ metric.target }} ({{ metric.measurement }})
+{% endfor %}
 
-## Success Criteria
+## Risk Assessment
+
+| Risk | Probability | Impact | Mitigation | Owner |
+|------|------------|--------|------------|-------|
+{% for risk in risks %}
+| {{ risk.description }} | {{ risk.probability }} | {{ risk.impact }} | {{ risk.mitigation }} | {{ risk.owner }} |
+{% endfor %}
+
+## Monitoring & Observability
+
+### Key Metrics
+{% for metric in monitoring.metrics %}
+- **{{ metric.name }}**: {{ metric.target }} ({{ metric.unit }})
+{% endfor %}
 
-### Constitutional Compliance
-- [ ] All Phase Gates passed
-- [ ] Complexity exceptions documented
-- [ ] Test-First cycle followed
-- [ ] Library-First architecture
-
-### Functional Completion
-- [ ] All user stories implemented
-- [ ] Acceptance criteria met
-- [ ] Contract tests passing
-- [ ] E2E scenarios validated
-
-### Quality Metrics
-- [ ] Test coverage > 80%
-- [ ] Performance targets met
-- [ ] Security audit passed
-- [ ] Documentation executable
-
-## Continuous Refinement (Article V)
-
-### Specification Feedback Loop
-- [ ] Implementation discoveries documented
-- [ ] Specification updated with learnings
-- [ ] [NEEDS CLARIFICATION] items resolved
-- [ ] Future improvements noted
-
-### Post-Implementation Review
-- [ ] Complexity assessment
-- [ ] Simplification opportunities
-- [ ] Architecture decisions validated
-- [ ] Constitution compliance verified
+### Alerting
+- **Critical Alerts**: {{ monitoring.alerts.critical | join(", ") }}
+- **Warning Alerts**: {{ monitoring.alerts.warnings | join(", ") }}
 
 ---
-**Note**: This plan is a living document. Update it as implementation progresses and learnings emerge.
+**Generated by**: {{ ai_assistant }} on {{ date }}
+**Constitutional Gates**: {{ gate_status | default("PENDING") }}
+**Next Steps**: Use `/task` to break down into executable tasks