devforgeai 1.0.4 → 1.0.6

package/src/claude/scripts/devforgeai_cli/feedback/TEST_SPECS_INDEX.md

@@ -0,0 +1,398 @@
+# Test Specifications Index
+
+**STORY-011: Configuration Management System**
+**Status:** Test Specifications Complete
+**Date:** 2025-11-10
+
+---
+
+## Documents Overview
+
+This directory contains 4 comprehensive test specification documents:
+
+### 1. README_TEST_SPECS.md (START HERE)
+**Purpose:** Executive summary and quick start guide
+**Audience:** Anyone new to the test specifications
+**Length:** ~300 lines
+**Read Time:** 15-20 minutes
+
+**Contains:**
+- Overview and document guide
+- Quick start (5 steps)
+- Module breakdown
+- Implementation roadmap (4 phases)
+- FAQ and troubleshooting
+- Success criteria checklist
+
+**Key Takeaway:** Understanding of overall test plan, implementation approach, and next steps
+
+**Start here if:** You want to understand the big picture before diving into details
+
+---
+
+### 2. TEST_IMPLEMENTATION_GUIDE.md (FOR PLANNING)
+**Purpose:** Detailed implementation roadmap with timeline
+**Audience:** Project managers, sprint planners, developers
+**Length:** ~800 lines
+**Read Time:** 30-45 minutes
+
+**Contains:**
+- Summary statistics (263 tests, 435 statements)
+- Module-by-module breakdown with priorities
+- Implementation roadmap (4 phases, 35-41 hours)
+- Common testing patterns with code examples
+- Pytest configuration (pytest.ini, conftest.py)
+- Running tests (commands, examples)
+- AC to test mapping table
+- Implementation checklist (73 items)
+- Estimated hours by phase
+
+**Key Takeaway:** Detailed understanding of effort, timeline, and how to execute implementation
+
+**Start here if:** You're planning sprints or estimating effort
+
+---
+
+### 3. TEST_SPECIFICATIONS.md (IMPLEMENTATION REFERENCE)
+**Purpose:** Detailed test method specifications (implementation guide)
+**Audience:** Developers implementing tests
+**Length:** ~11,000 lines (comprehensive)
+**Read Time:** 2-3 hours (by module)
+
+**Contains:**
+- 6 module sections (config_manager, hot_reload, config_models, skip_tracker, config_schema, config_defaults)
+- 9 test classes per module (on average)
+- 263+ individual test method specifications
+- For each test:
+  - Purpose (what behavior is tested)
+  - Setup (how to initialize)
+  - Assertions (what to verify)
+  - Coverage targets (which lines)
+  - Edge cases and error paths
+
+**Key Takeaway:** Complete reference for implementing every test method
+
+**Start here if:** You're implementing test methods and need detailed specifications
+
+---
+
+### 4. AC_TO_TEST_MAPPING.md (REQUIREMENTS TRACEABILITY)
+**Purpose:** Map acceptance criteria to test methods
+**Audience:** QA, requirements verification, auditors
+**Length:** ~800 lines
+**Read Time:** 30-45 minutes
+
+**Contains:**
+- 9 acceptance criteria sections (AC-1 through AC-9)
+- For each AC:
+  - Requirement statement
+  - Test methods that verify it
+  - Assertion examples with code
+  - Related line numbers in code
+  - Specifications section
+- Summary matrix (tests per AC)
+- Test execution strategy by AC
+- Validation checklist
+
+**Key Takeaway:** 100% traceability from requirements to tests
+
+**Start here if:** You need to verify AC coverage or test a specific feature
+
+---
+
+## How to Use These Documents
+
+### Scenario 1: New to the Project
+1. **Read:** README_TEST_SPECS.md (15 min)
+2. **Understand:** 263 tests, 4 phases, 35-41 hours
+3. **Plan:** Use TEST_IMPLEMENTATION_GUIDE.md (30 min)
+4. **Execute:** Start with Phase 1 data models
+
+### Scenario 2: Implementing Tests
+1. **Reference:** TEST_SPECIFICATIONS.md
+2. **Search:** By test class name
+3. **Read:** Test method specification
+4. **Implement:** Copy purpose/setup/assertions structure
+
+### Scenario 3: Verifying AC Coverage
+1. **Reference:** AC_TO_TEST_MAPPING.md
+2. **Search:** By AC number (AC-1, AC-2, etc.)
+3. **Review:** Test methods listed
+4. **Verify:** All tests implemented and passing
+
+### Scenario 4: Sprint Planning
+1. **Reference:** TEST_IMPLEMENTATION_GUIDE.md
+2. **Section:** Implementation Roadmap
+3. **Plan:** Assign phases to team members
+4. **Track:** Use Implementation Checklist
+
+### Scenario 5: Coverage Validation
+1. **Reference:** TEST_IMPLEMENTATION_GUIDE.md or AC_TO_TEST_MAPPING.md
+2. **Coverage Table:** Module breakdown
+3. **Run:** pytest --cov
+4. **Verify:** 95%+ coverage per module
+
+---
+
+## Document Navigation
+
+### By Document
+
+#### README_TEST_SPECS.md
+- Overview
+- Quick start
+- Module breakdown
+- Implementation phases
+- FAQ
+
+#### TEST_IMPLEMENTATION_GUIDE.md
+- Summary statistics
+- Module-by-module breakdown
+- Implementation roadmap
+- Testing patterns
+- Pytest configuration
+- Running tests
+- AC mapping
+- Implementation checklist
+- Estimated time
+
+#### TEST_SPECIFICATIONS.md
+- test_config_manager.py (68 tests)
+- test_hot_reload.py (55 tests)
+- test_config_models.py (59 tests)
+- test_skip_tracker.py (51 tests)
+- test_config_schema.py (15 tests)
+- test_config_defaults.py (15 tests)
+
+#### AC_TO_TEST_MAPPING.md
+- AC-1: YAML loading
+- AC-2: Enable/disable
+- AC-3: Trigger modes
+- AC-4: Conversation settings
+- AC-5: Skip tracking
+- AC-6: Template preferences
+- AC-7: Invalid config errors
+- AC-8: Default config
+- AC-9: Hot-reload
+
+### By Module
+
+| Module | Tests | Guide | Specs | AC |
+|--------|-------|-------|-------|-----|
+| config_manager.py | 68 | ✓ | ✓ | 1,2,3,7,8,9 |
+| hot_reload.py | 55 | ✓ | ✓ | 9 |
+| config_models.py | 59 | ✓ | ✓ | 2,3,4,5,6,7 |
+| skip_tracker.py | 51 | ✓ | ✓ | 5 |
+| config_schema.py | 15 | ✓ | ✓ | - |
+| config_defaults.py | 15 | ✓ | ✓ | 8 |
+
+### By Acceptance Criterion
+
+| AC | Feature | Tests | Documents |
+|----|---------|-------|-----------|
+| AC-1 | YAML loads | 7 | Specs, AC-Map, Guide |
+| AC-2 | Enable/disable | 5 | Specs, AC-Map, Guide |
+| AC-3 | Trigger modes | 8 | Specs, AC-Map, Guide |
+| AC-4 | Conversation settings | 9 | Specs, AC-Map, Guide |
+| AC-5 | Skip tracking | 14 | Specs, AC-Map, Guide |
+| AC-6 | Template preferences | 11 | Specs, AC-Map, Guide |
+| AC-7 | Invalid config errors | 16 | Specs, AC-Map, Guide |
+| AC-8 | Default config | 15 | Specs, AC-Map, Guide |
+| AC-9 | Hot-reload | 14 | Specs, AC-Map, Guide |
+
+---
+
+## Quick Search Guide
+
+### Looking for...
+
+**Implementation timeline?**
+→ TEST_IMPLEMENTATION_GUIDE.md § "Implementation Roadmap"
+
+**Detailed test method specs?**
+→ TEST_SPECIFICATIONS.md § [Module name]
+
+**AC traceability?**
+→ AC_TO_TEST_MAPPING.md § "AC-[number]"
+
+**Testing patterns (threading, file I/O)?**
+→ TEST_IMPLEMENTATION_GUIDE.md § "Testing Patterns"
+
+**Pytest configuration?**
+→ TEST_IMPLEMENTATION_GUIDE.md § "Pytest Configuration"
+
+**Success criteria?**
+→ README_TEST_SPECS.md § "Success Criteria"
+→ TEST_IMPLEMENTATION_GUIDE.md § "Estimated Time by Phase"
+
+**Implementation checklist?**
+→ TEST_IMPLEMENTATION_GUIDE.md § "Implementation Checklist"
+
+**FAQ?**
+→ README_TEST_SPECS.md § "FAQ"
+
+---
+
+## Document Statistics
+
+| Document | Lines | Sections | Details |
+|----------|-------|----------|---------|
+| README_TEST_SPECS.md | ~300 | 12 | Overview, quick start, FAQ |
+| TEST_IMPLEMENTATION_GUIDE.md | ~800 | 14 | Roadmap, patterns, checklist |
+| TEST_SPECIFICATIONS.md | ~11,000 | 6 modules, 9 classes per module, 263 tests | Complete test method specs |
+| AC_TO_TEST_MAPPING.md | ~800 | 9 ACs, 263 tests | Requirements traceability |
+| **TOTAL** | **~13,000** | **Multiple** | **Complete specification package** |
+
+---
+
+## Implementation Phases
+
+### Phase 1: Data Models (4-5 hours) ← START HERE
+**Files to implement:**
+- test_config_models.py (59 tests)
+- test_config_defaults.py (15 tests)
+- test_config_schema.py (15 tests)
+
+**Reference:** TEST_SPECIFICATIONS.md § Test_config_models.py, test_config_defaults.py, test_config_schema.py
+
+### Phase 2: Configuration Management (10-12 hours)
+**Files to implement:**
+- test_config_manager.py (68 tests)
+
+**Reference:** TEST_SPECIFICATIONS.md § Test_config_manager.py
+
+### Phase 3: Hot-Reload System (11-13 hours)
+**Files to implement:**
+- test_hot_reload.py (55 tests)
+
+**Reference:** TEST_SPECIFICATIONS.md § Test_hot_reload.py
+
+### Phase 4: Skip Tracking (10-11 hours)
+**Files to implement:**
+- test_skip_tracker.py (51 tests)
+
+**Reference:** TEST_SPECIFICATIONS.md § Test_skip_tracker.py
+
+---
+
+## Key Statistics
+
+| Metric | Value |
+|--------|-------|
+| Total Tests | 263+ |
+| Total Statements | 435 |
+| Target Coverage | 95%+ |
+| Estimated Hours | 35-41 |
+| Documents | 4 |
+| Pages | ~50 |
+| AC Coverage | 9/9 (100%) |
+| Module Coverage | 6/6 (100%) |
+
+---
+
+## Implementation Checklist
+
+### Before Starting
+- [ ] Read README_TEST_SPECS.md
+- [ ] Review TEST_IMPLEMENTATION_GUIDE.md
+- [ ] Setup pytest environment
+- [ ] Create conftest.py with shared fixtures
+- [ ] Create pytest.ini
+
+### Phase 1: Data Models
+- [ ] Implement test_config_models.py (59 tests)
+- [ ] Run: `pytest test_config_models.py -v`
+- [ ] Verify: Coverage >95%
+- [ ] Implement test_config_defaults.py (15 tests)
+- [ ] Implement test_config_schema.py (15 tests)
+- [ ] Run: `pytest test_config_*.py -v --cov`
+
+### Phase 2: Configuration Manager
+- [ ] Implement test_config_manager.py (68 tests)
+- [ ] Run: `pytest test_config_manager.py -v`
+- [ ] Verify: Coverage >95%
+- [ ] Total: 172 tests passing
+
+### Phase 3: Hot-Reload
+- [ ] Implement test_hot_reload.py (55 tests)
+- [ ] Run: `pytest test_hot_reload.py -v`
+- [ ] Verify: Coverage >95%
+- [ ] Total: 227 tests passing
+
+### Phase 4: Skip Tracking
+- [ ] Implement test_skip_tracker.py (51 tests)
+- [ ] Run: `pytest test_skip_tracker.py -v`
+- [ ] Verify: Coverage >95%
+- [ ] Total: 278 tests passing
+
+### Final Validation
+- [ ] Run all tests: `pytest -v --cov`
+- [ ] Verify: 263+ tests passing
+- [ ] Coverage: >95% all modules
+- [ ] AC coverage: 9/9 ACs tested
+- [ ] Commit: All tests to repository
+
+---
+
+## Success Criteria
+
+**All 9 Acceptance Criteria Tested:**
+- [ ] AC-1: YAML loads (7 tests)
+- [ ] AC-2: Enable/disable (5 tests)
+- [ ] AC-3: Trigger modes (8 tests)
+- [ ] AC-4: Conversation settings (9 tests)
+- [ ] AC-5: Skip tracking (14 tests)
+- [ ] AC-6: Template preferences (11 tests)
+- [ ] AC-7: Invalid config errors (16 tests)
+- [ ] AC-8: Default config (15 tests)
+- [ ] AC-9: Hot-reload (14 tests)
+
+**All 6 Modules Covered:**
+- [ ] config_manager.py: 95%+ (153/161)
+- [ ] hot_reload.py: 95%+ (94/99)
+- [ ] config_models.py: 95%+ (81/85)
+- [ ] skip_tracker.py: 95%+ (74/78)
+- [ ] config_schema.py: 100% (4/4)
+- [ ] config_defaults.py: 100% (8/8)
+
+**Quality Standards Met:**
+- [ ] 263+ tests implemented
+- [ ] 100% test pass rate
+- [ ] AAA pattern applied
+- [ ] Thread safety validated
+- [ ] Error paths tested
+- [ ] Edge cases covered
+- [ ] Fixtures cleaned up
+
+---
+
+## Next Steps
+
+1. **Read README_TEST_SPECS.md** (15 min) ✓
+2. **Review TEST_IMPLEMENTATION_GUIDE.md** (30 min)
+3. **Setup environment** (30 min)
+4. **Start Phase 1: Data Models** (4-5 hours)
+5. **Continue through Phase 4** (35-41 hours total)
+6. **Validate coverage** (1 hour)
+
+---
+
+## Quick Links
+
+**Start Here:** README_TEST_SPECS.md
+**Implementation:** TEST_SPECIFICATIONS.md
+**Planning:** TEST_IMPLEMENTATION_GUIDE.md
+**Traceability:** AC_TO_TEST_MAPPING.md
+
+---
+
+## Document Version
+
+- **Created:** 2025-11-10
+- **Status:** Complete - Ready for Implementation
+- **Target Completion:** Within 1 sprint (2 weeks)
+- **Estimated Effort:** 35-41 hours
+
+---
+
+**This index helps navigate 13,000+ lines of test specifications across 4 documents. Start with README_TEST_SPECS.md.**

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

@@ -0,0 +1,34 @@
+"""
+DevForgeAI Retrospective Feedback System
+
+This module provides post-operation retrospective conversation capabilities
+for capturing structured user feedback after command/skill execution.
+"""
+
+__version__ = '0.1.0'
+
+from .retrospective import (
+    trigger_retrospective,
+    capture_feedback,
+    is_skip_selected,
+)
+
+from .skip_tracking import (
+    increment_skip,
+    get_skip_count,
+    reset_skip_count,
+)
+
+from .question_router import (
+    get_context_aware_questions,
+)
+
+__all__ = [
+    'trigger_retrospective',
+    'capture_feedback',
+    'is_skip_selected',
+    'increment_skip',
+    'get_skip_count',
+    'reset_skip_count',
+    'get_context_aware_questions',
+]