devforgeai 1.0.4 → 1.0.6

package/src/claude/scripts/devforgeai_cli/session/__init__.py

@@ -0,0 +1,30 @@
+"""
+Session management for DevForgeAI CLI.
+
+Provides checkpoint functionality for TDD workflow session recovery.
+Enables resuming development sessions after context window fills.
+
+STORY-120: Session Checkpoint Protocol
+"""
+
+from .checkpoint import (
+    write_checkpoint,
+    read_checkpoint,
+    delete_checkpoint,
+    CHECKPOINT_FILENAME,
+    SESSIONS_DIR,
+    PHASE_NAMES,
+    PHASE_PROGRESS,
+    REQUIRED_FIELDS,
+)
+
+__all__ = [
+    'write_checkpoint',
+    'read_checkpoint',
+    'delete_checkpoint',
+    'CHECKPOINT_FILENAME',
+    'SESSIONS_DIR',
+    'PHASE_NAMES',
+    'PHASE_PROGRESS',
+    'REQUIRED_FIELDS',
+]

package/src/claude/scripts/devforgeai_cli/session/checkpoint.py

@@ -0,0 +1,268 @@
+"""
+Session Checkpoint Management for DevForgeAI CLI.
+
+Enables resuming TDD implementation across context window resets.
+Checkpoints are written at each phase completion and read by /resume-dev
+for automatic phase detection.
+
+STORY-120: Session Checkpoint Protocol
+
+Based on patterns from: devforgeai_cli/validators/dod_validator.py
+"""
+
+import json
+import os
+import re
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, Optional, Any
+
+
+# ============================================================================
+# CONSTANTS
+# ============================================================================
+
+CHECKPOINT_FILENAME = "checkpoint.json"
+SESSIONS_DIR = "devforgeai/sessions"
+
+# Phase 0-7 maps to TDD workflow phases (AC#1: phases 0-7)
+PHASE_NAMES: Dict[int, str] = {
+    0: "Pre-Flight",
+    1: "Red (Test Generation)",
+    2: "Green (Implementation)",
+    3: "Refactor",
+    4: "Integration",
+    5: "Deferral Challenge",
+    6: "DoD Update",
+    7: "Git Workflow",
+}
+
+PHASE_PROGRESS: Dict[int, int] = {
+    0: 10,
+    1: 20,
+    2: 30,
+    3: 40,
+    4: 50,
+    5: 60,
+    6: 75,
+    7: 100,
+}
+
+REQUIRED_FIELDS = [
+    "story_id",
+    "phase",
+    "phase_name",
+    "timestamp",
+    "progress_percentage",
+    "dod_completion",
+    "next_action",
+]
+
+# Validation patterns
+STORY_ID_PATTERN = re.compile(r"^STORY-\d{3,}$")
+
+
+# ============================================================================
+# HELPER FUNCTIONS
+# ============================================================================
+
+def _get_sessions_dir() -> str:
+    """Get sessions directory from environment or default."""
+    return os.environ.get("DEVFORGEAI_SESSIONS_DIR", SESSIONS_DIR)
+
+
+def _validate_story_id(story_id: str) -> bool:
+    """Validate story ID format (STORY-NNN)."""
+    if not story_id or not isinstance(story_id, str):
+        return False
+    return bool(STORY_ID_PATTERN.match(story_id))
+
+
+def _validate_phase(phase: int) -> bool:
+    """Validate phase is in valid range (0-7)."""
+    if not isinstance(phase, int):
+        return False
+    return 0 <= phase <= 7
+
+
+def _validate_dod_completion(dod_completion: Any) -> bool:
+    """Validate dod_completion has required keys."""
+    if not isinstance(dod_completion, dict):
+        return False
+    required_keys = ["implementation", "quality", "testing", "documentation"]
+    return all(key in dod_completion for key in required_keys)
+
+
+def _get_checkpoint_path(story_id: str) -> Path:
+    """Get standardized checkpoint file path."""
+    sessions_dir = _get_sessions_dir()
+    return Path(sessions_dir) / story_id / CHECKPOINT_FILENAME
+
+
+# ============================================================================
+# PUBLIC FUNCTIONS
+# ============================================================================
+
+def write_checkpoint(
+    story_id: str,
+    phase: int,
+    progress: Dict[str, Any],
+) -> bool:
+    """
+    Write checkpoint to session directory.
+
+    Args:
+        story_id: Story identifier (STORY-NNN format)
+        phase: Current phase number (0-7)
+        progress: Checkpoint data dict containing dod_completion and next_action
+
+    Returns:
+        True on success, False on failure
+
+    Raises:
+        ValueError: If story_id or phase are invalid (optional behavior)
+    """
+    # Validate inputs
+    if not _validate_story_id(story_id):
+        return False
+
+    if not _validate_phase(phase):
+        return False
+
+    # Extract or default dod_completion
+    dod_completion = progress.get("dod_completion", {
+        "implementation": [0, 0],
+        "quality": [0, 0],
+        "testing": [0, 0],
+        "documentation": [0, 0],
+    })
+
+    if not _validate_dod_completion(dod_completion):
+        return False
+
+    # Build checkpoint data
+    # Use progress_percentage from input if provided, else default from PHASE_PROGRESS
+    progress_pct = progress.get("progress_percentage", PHASE_PROGRESS.get(phase, 0))
+
+    checkpoint_data = {
+        "story_id": story_id,
+        "phase": phase,
+        "phase_name": progress.get("phase_name", PHASE_NAMES.get(phase, f"Phase {phase}")),
+        "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        "progress_percentage": progress_pct,
+        "dod_completion": dod_completion,
+        "last_action": progress.get("last_action", ""),
+        "next_action": progress.get("next_action", f"Phase {phase + 1}"),
+    }
+
+    try:
+        # Get checkpoint path
+        checkpoint_path = _get_checkpoint_path(story_id)
+
+        # Create directory if not exists
+        checkpoint_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Write JSON with atomic pattern (write to temp, then rename)
+        temp_path = checkpoint_path.with_suffix(".tmp")
+        with open(temp_path, "w", encoding="utf-8") as f:
+            json.dump(checkpoint_data, f, indent=2)
+
+        # Atomic rename
+        shutil.move(str(temp_path), str(checkpoint_path))
+
+        return True
+
+    except (IOError, OSError, json.JSONDecodeError) as e:
+        # Log error but don't crash
+        # Graceful failure - checkpoint is optional for workflow
+        return False
+
+
+def read_checkpoint(story_id: str) -> Optional[Dict[str, Any]]:
+    """
+    Read checkpoint from session directory.
+
+    Args:
+        story_id: Story identifier (STORY-NNN format)
+
+    Returns:
+        Checkpoint data dict if valid, None if missing or corrupted
+
+    AC#5: Graceful fallback if missing/corrupted
+    """
+    # Validate input
+    if not _validate_story_id(story_id):
+        return None
+
+    try:
+        checkpoint_path = _get_checkpoint_path(story_id)
+
+        # Check if file exists
+        if not checkpoint_path.exists():
+            return None
+
+        # Read and parse JSON
+        with open(checkpoint_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+
+        # Validate required fields (AC#5: graceful fallback)
+        if not isinstance(data, dict):
+            return None
+
+        for field in REQUIRED_FIELDS:
+            if field not in data:
+                return None
+
+        # Validate specific field types
+        if not isinstance(data.get("phase"), int):
+            return None
+
+        if not _validate_dod_completion(data.get("dod_completion")):
+            return None
+
+        return data
+
+    except (IOError, OSError, json.JSONDecodeError, KeyError, TypeError):
+        # Corrupted or unreadable - return None for graceful fallback
+        return None
+
+
+def delete_checkpoint(story_id: str) -> bool:
+    """
+    Delete checkpoint file and clean up empty directory.
+
+    Args:
+        story_id: Story identifier (STORY-NNN format)
+
+    Returns:
+        True on success (including if file didn't exist), False on error
+
+    AC#4: Checkpoint cleaned up on Released status
+    """
+    # Validate input (but still succeed if invalid - idempotent)
+    if not _validate_story_id(story_id):
+        return True  # Nothing to delete for invalid ID
+
+    try:
+        checkpoint_path = _get_checkpoint_path(story_id)
+
+        # Remove checkpoint file if exists
+        if checkpoint_path.exists():
+            checkpoint_path.unlink()
+
+        # Remove empty parent directory
+        session_dir = checkpoint_path.parent
+        if session_dir.exists() and session_dir.is_dir():
+            try:
+                # Only remove if empty
+                session_dir.rmdir()
+            except OSError:
+                # Directory not empty - that's fine
+                pass
+
+        return True
+
+    except (IOError, OSError) as e:
+        # Return False only on actual errors
+        return False

package/src/claude/scripts/devforgeai_cli/tests/__init__.py

@@ -0,0 +1 @@
+"""Tests for DevForgeAI CLI validators."""

package/src/claude/scripts/devforgeai_cli/tests/conftest.py

@@ -0,0 +1,29 @@
+"""
+Pytest configuration and shared fixtures for devforgeai_cli tests.
+
+Provides common fixtures for all test modules:
+- Environment setup
+- Temporary directories
+- Mock utilities
+"""
+
+import os
+from pathlib import Path
+
+import pytest
+
+
+@pytest.fixture(scope="session")
+def project_root():
+    """Get the project root directory."""
+    return Path(__file__).parent.parent.parent.parent.parent.parent
+
+
+@pytest.fixture
+def monkeypatch_devforgeai_home(monkeypatch, tmp_path):
+    """Set up a temporary DevForgeAI home directory for testing."""
+    devforgeai_home = tmp_path / "devforgeai"
+    devforgeai_home.mkdir(parents=True, exist_ok=True)
+
+    monkeypatch.setenv("DEVFORGEAI_HOME", str(devforgeai_home))
+    yield devforgeai_home

package/src/claude/scripts/devforgeai_cli/tests/feedback/TEST_EXECUTION_GUIDE.md

@@ -0,0 +1,298 @@
+# STORY-011: Configuration Management - Test Execution Guide
+
+## Quick Start
+
+### Run All Tests
+```bash
+cd /mnt/c/Projects/DevForgeAI2
+pytest .claude/scripts/devforgeai_cli/tests/feedback/test_configuration_management.py -v
+```
+
+### Run Specific Test Categories
+
+#### YAML Parsing Tests
+```bash
+pytest .claude/scripts/devforgeai_cli/tests/feedback/test_configuration_management.py::TestYamlParsing -v
+```
+
+#### Validation Tests
+```bash
+pytest .claude/scripts/devforgeai_cli/tests/feedback/test_configuration_management.py::TestConfigurationValidation -v
+```
+
+#### Integration Tests
+```bash
+pytest .claude/scripts/devforgeai_cli/tests/feedback/test_configuration_management.py::TestConfigurationLoading -v
+```
+
+#### Edge Cases
+```bash
+pytest .claude/scripts/devforgeai_cli/tests/feedback/test_configuration_management.py::TestEdgeCases -v
+```
+
+#### Performance Tests
+```bash
+pytest .claude/scripts/devforgeai_cli/tests/feedback/test_configuration_management.py::TestPerformance -v
+```
+
+## Advanced Usage
+
+### Run with Coverage Report
+```bash
+pytest .claude/scripts/devforgeai_cli/tests/feedback/test_configuration_management.py \
+  --cov=.claude/scripts/devforgeai_cli/feedback \
+  --cov-report=html \
+  --cov-report=term
+```
+
+### Run Single Test
+```bash
+pytest .claude/scripts/devforgeai_cli/tests/feedback/test_configuration_management.py::TestYamlParsing::test_valid_yaml_structure_parses_successfully -v
+```
+
+### Run with Verbose Output
+```bash
+pytest .claude/scripts/devforgeai_cli/tests/feedback/test_configuration_management.py -vv -s
+```
+
+### Run and Stop on First Failure
+```bash
+pytest .claude/scripts/devforgeai_cli/tests/feedback/test_configuration_management.py -x
+```
+
+### Run with Warnings
+```bash
+pytest .claude/scripts/devforgeai_cli/tests/feedback/test_configuration_management.py -W all
+```
+
+### Generate Test Report
+```bash
+pytest .claude/scripts/devforgeai_cli/tests/feedback/test_configuration_management.py \
+  --html=test_report.html \
+  --self-contained-html
+```
+
+## Installation Requirements
+
+### Ensure pytest is installed
+```bash
+pip install pytest pytest-cov pytest-html pytest-watch
+```
+
+### Install Dependencies (if needed)
+```bash
+pip install pyyaml
+```
+
+## Understanding Test Results
+
+### All Tests Pass (Green) ✅
+```
+========== 67 passed in 2.34s ===========
+```
+**Meaning:** Implementation correctly satisfies all requirements.
+
+### Tests Fail Initially (Red) ❌
+```
+========== 67 failed in 0.45s ===========
+```
+**Expected:** This is TDD Red phase - no implementation yet.
+
+### After Implementation (Green) ✅
+```
+========== 67 passed in 1.89s ===========
+Coverage: 96% ✅
+```
+**Expected:** All tests pass after implementation complete.
+
+## Test Execution Flow
+
+### Phase 1: Red (Currently Here)
+1. ✅ Tests written (this file)
+2. ✅ All tests fail (no implementation)
+3. Next: Implement code
+
+### Phase 2: Green (Next Step)
+1. ❌ Implement FeedbackConfiguration class
+2. ❌ Implement YAML parser
+3. ❌ Implement validation logic
+4. ❌ Implement hot-reload
+5. ✅ All tests pass
+
+### Phase 3: Refactor (After Green)
+1. ✅ Improve code quality
+2. ✅ Extract common patterns
+3. ✅ Optimize performance
+4. ✅ Ensure tests still pass
+
+## Test Categories and Expected Status
+
+| Category | Count | Expected Status | Time |
+|----------|-------|-----------------|------|
+| YAML Parsing | 5 | ❌ FAIL | <1s |
+| Validation | 10 | ❌ FAIL | <1s |
+| Defaults | 5 | ❌ FAIL | <1s |
+| Master Control | 3 | ❌ FAIL | <1s |
+| Trigger Modes | 6 | ❌ FAIL | <1s |
+| Conversation | 5 | ❌ FAIL | <1s |
+| Skip Tracking | 4 | ❌ FAIL | <1s |
+| Templates | 6 | ❌ FAIL | <1s |
+| Hot-Reload | 4 | ❌ FAIL | <1s |
+| Integration | 3 | ❌ FAIL | <1s |
+| Edge Cases | 7 | ❌ FAIL | <2s |
+| Performance | 4 | ❌ FAIL | <5s |
+| **TOTAL** | **~67** | **❌ ALL FAIL** | **<20s** |
+
+## Debugging Failed Tests
+
+### Identify Which Tests Failed
+```bash
+pytest .claude/scripts/devforgeai_cli/tests/feedback/test_configuration_management.py \
+  --tb=short  # Short traceback
+```
+
+### See Detailed Error
+```bash
+pytest .claude/scripts/devforgeai_cli/tests/feedback/test_configuration_management.py::TestYamlParsing::test_valid_yaml_structure_parses_successfully \
+  -vv --tb=long
+```
+
+### See Test Setup and Fixtures
+```bash
+pytest .claude/scripts/devforgeai_cli/tests/feedback/test_configuration_management.py \
+  --setup-show
+```
+
+## Implementation Checklist
+
+Use this checklist when implementing to ensure all requirements met:
+
+- [ ] FeedbackConfiguration dataclass created
+- [ ] ConversationSettings dataclass created
+- [ ] SkipTrackingSettings dataclass created
+- [ ] TemplateSettings dataclass created
+- [ ] TriggerMode enum defined
+- [ ] TemplateFormat enum defined
+- [ ] TemplateTone enum defined
+- [ ] YAML parser implemented
+- [ ] Configuration loader implemented with defaults
+- [ ] Validation logic for all 10 fields
+- [ ] Master enable/disable control
+- [ ] Trigger mode filtering
+- [ ] Question limit tracking
+- [ ] Skip tracking with atomic counter
+- [ ] Hot-reload with file watcher
+- [ ] Error logging
+- [ ] Performance optimization (<100ms load)
+
+## CI/CD Integration
+
+### GitHub Actions Example
+```yaml
+name: Test STORY-011
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: '3.9'
+      - run: pip install -r requirements.txt
+      - run: pytest .claude/scripts/devforgeai_cli/tests/feedback/test_configuration_management.py --cov --cov-report=xml
+      - uses: codecov/codecov-action@v2
+```
+
+## Expected Test Behavior
+
+### During Development
+
+```
+# Initial run (Red phase)
+$ pytest test_configuration_management.py
+FAILED ❌ test_valid_yaml_structure_parses_successfully - No such file
+FAILED ❌ test_enabled_true_allows_feedback_collection - AttributeError
+FAILED ❌ test_trigger_mode_always_triggers_unconditionally - NameError
+...
+========== 67 failed in 0.34s ===========
+
+# After implementation (Green phase)
+$ pytest test_configuration_management.py
+PASSED ✅ test_valid_yaml_structure_parses_successfully
+PASSED ✅ test_enabled_true_allows_feedback_collection
+PASSED ✅ test_trigger_mode_always_triggers_unconditionally
+...
+========== 67 passed in 1.89s ===========
+
+# After refactoring (Refactor phase - should still pass)
+$ pytest test_configuration_management.py --cov
+PASSED ✅ test_valid_yaml_structure_parses_successfully
+PASSED ✅ test_enabled_true_allows_feedback_collection
+PASSED ✅ test_trigger_mode_always_triggers_unconditionally
+...
+========== 67 passed in 1.92s ===========
+Coverage: 96% ✅
+```
+
+## Troubleshooting
+
+### Issue: "ModuleNotFoundError: No module named 'pytest'"
+**Solution:** `pip install pytest`
+
+### Issue: "ModuleNotFoundError: No module named 'yaml'"
+**Solution:** `pip install pyyaml`
+
+### Issue: Tests timeout
+**Solution:** Increase timeout: `pytest --timeout=10`
+
+### Issue: Permission errors on temp files
+**Solution:** Ensure temp directory is writable: `chmod 777 /tmp`
+
+### Issue: Cannot create temp directory
+**Solution:** Check disk space: `df -h`
+
+## Test Metrics
+
+### Test File Statistics
+- **Total Lines:** 1,338
+- **Test Classes:** 12
+- **Test Methods:** 67+
+- **Parametrized Tests:** 5 functions with multiple parameters
+- **Documentation Lines:** 200+
+- **Code Lines:** 900+
+
+### Coverage Targets
+- Acceptance Criteria: 100% (9/9 ACs tested)
+- Data Fields: 100% (10/10 fields tested)
+- Edge Cases: 100% (7/7 cases tested)
+- Business Logic: >95%
+
+### Execution Metrics
+- **Total Test Time:** <20 seconds
+- **Average Test:** <150ms
+- **Slowest Test:** ~5s (performance tests intentional)
+- **Fastest Test:** <1ms (mocked operations)
+
+## References
+
+- [pytest Documentation](https://docs.pytest.org/)
+- [Test Summary Report](./STORY-011-test-generation-summary.md)
+- [Configuration Management Story](../../../devforgeai/specs/Stories/STORY-011-configuration-management.story.md)
+- [DevForgeAI Framework](../../../CLAUDE.md)
+
+## Contact & Support
+
+For test-related questions:
+1. Review test docstrings (explain purpose)
+2. Check test comments (explain setup)
+3. Review the test summary document
+4. Check the story acceptance criteria
+
+---
+
+**Ready for Green Phase Implementation!** 🚀
+
+All 67 tests are ready to guide implementation of STORY-011.

package/src/claude/scripts/devforgeai_cli/tests/feedback/__init__.py

@@ -0,0 +1,3 @@
+"""
+Test suite for DevForgeAI Retrospective Feedback System
+"""