Merge pull request #161 from helpfulengineering/phase-2

Phase 2

Author: touchthesun

.cursorrules

@@ -0,0 +1,332 @@
+# Cursor Rules - Unified Repository Map Strategy
+
+## Repository Context
+
+**CRITICAL WORKFLOW: Use the Right Section for the Right Question**
+
+This repository has a unified repository map (`.repo-map.md`) containing two complementary sections. Use them strategically based on question type:
+
+### Available Repository Map
+
+**`.repo-map.md`** - Unified repository map containing:
+
+1. **Aider-style section** (first section)
+   - **Format**: Hierarchical tree structure organized by file location
+   - **Best for**: Location questions, file structure, "where does X live?"
+   - **Shows**: File paths, directory structure, classes organized by file
+   - **Look for**: Section header "REPOSITORY MAP (Aider Style)"
+
+2. **Sourcegraph-style section** (second section)
+   - **Format**: Categorized by component role (Services, Models, Utilities, etc.)
+   - **Best for**: Relationship questions, APIs, dependencies, "what services exist?"
+   - **Shows**: Exports, imports, docstrings, public APIs, component relationships
+   - **Look for**: Section header "Repository Code Intelligence Map (Sourcegraph Style)"
+
+### Step 1: Identify Question Type and Select Section(s)
+
+**Use Aider-style section (first section of `.repo-map.md`) when the user asks:**
+- ✅ **"Where should I add [component]?"** → Location/structure question
+- ✅ **"Where does [functionality] live?"** → File location question
+- ✅ **"Show me the structure of [directory]..."** → Hierarchical structure question
+- ✅ **"What files exist in [directory]?"** → File listing question
+
+**Use Sourcegraph-style section (second section of `.repo-map.md`) when the user asks:**
+- ✅ **"What [services/utilities/models] exist?"** → Component discovery question
+- ✅ **"What's the public API of [service]?"** → API/interface question
+- ✅ **"What depends on [component]?"** → Dependency question
+- ✅ **"What patterns do [services/models] follow?"** → Pattern/relationship question
+- ✅ **"How do [component A] and [component B] relate?"** → Relationship question
+
+**Use BOTH sections when:**
+- ✅ **"What [utilities/services] exist and where are they?"** → Comprehensive discovery
+- ✅ **"I need to add a new [service/model] - what exists and where should it go?"** → Full context needed
+
+**Skip maps when:**
+- ❌ **"How does [specific function] work?"** → Implementation detail, use direct search
+- ❌ **"Fix this bug in [file]..."** → Specific file issue, use direct search
+
+### Step 2: Execute Repository Map Workflow
+
+**For Aider-style questions (location/structure):**
+
+1. **FIRST**: Read `.repo-map.md` using `read_file`, focusing on the Aider-style section (first section)
+2. **THEN**: Use `codebase_search` or `grep` for specific implementation details
+3. **FINALLY**: Cross-reference with actual code files
+
+**For Sourcegraph-style questions (relationships/APIs):**
+
+1. **FIRST**: Read `.repo-map.md` using `read_file`, focusing on the Sourcegraph-style section (second section) and relevant categories (Services, Models, Utilities, etc.)
+2. **THEN**: Use `codebase_search` or `grep` for specific implementation details
+3. **FINALLY**: Cross-reference with actual code files
+
+**For comprehensive questions (use both sections):**
+
+1. **FIRST**: Read `.repo-map.md` Sourcegraph-style section to understand what exists (component discovery)
+2. **SECOND**: Read `.repo-map.md` Aider-style section to understand where things are located (file structure)
+3. **THEN**: Use `codebase_search` or `grep` for specific implementation details
+4. **FINALLY**: Cross-reference with actual code files
+
+**Why this unified dual-section approach matters:**
+- Aider section: Fast location discovery, prevents missing files
+- Sourcegraph section: Fast component discovery, prevents missing utilities/services
+- Together: Complete understanding of both structure and relationships
+- Single file: Easier to maintain and keep in sync
+- Ensures architectural consistency and reduces duplicate code
+
+### Code Organization Rules
+
+1. **Check the appropriate section(s) first** - Use Aider section for location questions, Sourcegraph section for component/API questions
+2. **Follow existing patterns** - Both sections show how similar components are organized; maintain consistency
+3. **Understand relationships** - Use Sourcegraph section to understand dependencies and public APIs before modifying code
+4. **Avoid duplication** - Use Sourcegraph section to find existing utilities/services before creating new ones
+5. **Respect file structure** - Use Aider section to ensure new code goes in the correct location
+
+### Keeping Map Updated
+
+**The repository map should be regenerated when:**
+- Adding or removing Python files
+- Creating new services, models, or utilities
+- Changing public APIs or exports
+- Restructuring directories
+
+**To regenerate the unified map:**
+```bash
+python scripts/generate_repo_map.py
+```
+
+**Note:** The map is automatically regenerated by pre-commit hooks (if configured).
+
+### Quick Reference: Section Selection Examples
+
+**Example 1: "Where should I add a new service for handling component validation?"**
+- ✅ Use: **Aider section** of `.repo-map.md` (location question)
+- Look for: `src/core/services/` structure in Aider section
+- Then check: Sourcegraph section "Services" category to see existing service patterns
+
+**Example 2: "What storage-related utilities already exist? I need to cache API responses."**
+- ✅ Use: **Sourcegraph section** of `.repo-map.md` (component discovery question)
+- Look for: "Services" category → `cache_service.py`, "Utilities" category
+- Then check: Aider section to find exact file locations
+
+**Example 3: "I want to add a new CLI command for exporting data. Where does it go and what existing patterns should I follow?"**
+- ✅ Use: **BOTH sections** of `.repo-map.md` (comprehensive question)
+- Sourcegraph section: "Entry Points" category → `src/cli/main.py` to see CLI structure
+- Aider section: `src/cli/` directory structure to find where commands live
+- Sourcegraph section: "Utilities" or relevant category to see export patterns
+
+**Example 4: "What's the public API of the cache service?"**
+- ✅ Use: **Sourcegraph section** of `.repo-map.md` (API question)
+- Look for: "Services" category → `cache_service.py` → **Exports** and **Methods**
+
+**Example 5: "Show me the structure of the generation engine"**
+- ✅ Use: **Aider section** of `.repo-map.md` (structure question)
+- Look for: `src/core/generation/` tree structure
+
+## Development Philosophy: Incremental, Testable Development
+
+**PRIMARY RULE: Always prefer small, incremental changes over large, sweeping modifications.**
+
+### Change Management Principles
+
+1. **Incremental Development**
+   - Make the smallest possible change that moves toward the goal
+   - Each change should be independently testable and verifiable
+   - Break large features into multiple small, focused changes
+   - Never refactor multiple components simultaneously unless absolutely necessary
+
+2. **Test-First Approach**
+   - Write or update tests before implementing changes
+   - Ensure each change can be validated with existing or new tests
+   - If tests don't exist, create minimal tests to verify the change works
+   - Run tests after each small change to catch issues early
+
+3. **Scope Limitation**
+   - Focus on ONE specific problem or feature at a time
+   - Avoid "while we're at it" changes that expand scope
+   - Resist the urge to optimize or refactor unrelated code
+   - Clearly define the boundaries of each change
+
+### Code Change Guidelines
+
+#### Before Making Changes
+- [ ] Understand the current state of the code (use repository maps if needed)
+- [ ] Identify the minimal change needed
+- [ ] Plan the smallest possible implementation
+- [ ] Consider what tests need to be written/updated
+
+#### During Implementation
+- [ ] Make ONE focused change at a time
+- [ ] Test the change immediately after implementation
+- [ ] Fix any issues before proceeding to the next change
+- [ ] Document any assumptions or limitations
+
+#### After Each Change
+- [ ] Verify the change works as expected
+- [ ] Run relevant tests
+- [ ] Check for any unintended side effects
+- [ ] Commit the change if it's working correctly
+
+### Prohibited Practices
+
+**DO NOT:**
+- Make changes to multiple files simultaneously unless they're directly related
+- Refactor code that isn't part of the current task
+- Add new features while fixing bugs
+- Optimize performance unless specifically requested
+- Change code style/formatting unless it's the primary task
+- Remove "unused" code without explicit confirmation
+- Add dependencies without clear justification
+
+### Communication Guidelines
+
+#### When Proposing Changes
+- Clearly explain what the change does
+- Specify why this particular approach was chosen
+- Mention any assumptions or limitations
+- Suggest the next small step if the change is part of a larger goal
+
+#### When Uncertain
+- Ask for clarification rather than making assumptions
+- Propose the smallest possible change and ask for feedback
+- Suggest breaking down complex requests into smaller steps
+- Offer alternatives if the requested change seems too broad
+
+### Example Workflow
+
+**Instead of:** "I'll refactor the entire authentication system and add new features"
+
+**Do this:**
+1. "I'll add a single test for the current authentication behavior"
+2. "I'll make one small change to fix the specific bug"
+3. "I'll verify the fix works with the test"
+4. "I'll commit this change and move to the next small step"
+
+### File-Specific Guidelines
+
+#### For New Features
+- Start with a failing test
+- Implement the minimal code to make the test pass
+- Add one small piece of functionality at a time
+- Test each addition before moving to the next
+
+#### For Bug Fixes
+- Reproduce the bug with a test
+- Make the smallest possible change to fix it
+- Verify the fix works and doesn't break existing functionality
+- Add regression tests if appropriate
+
+#### For Refactoring
+- Ensure comprehensive test coverage exists first
+- Refactor one small piece at a time
+- Run tests after each small change
+- Never refactor and add features simultaneously
+
+### Temporary Test File Management
+
+#### Creating Temporary Tests
+- Use descriptive names for temporary test files (e.g., `test_temp_feature_xyz.py`, `temp_validation_abc.js`)
+- Clearly mark temporary files with comments indicating their purpose and expected cleanup
+- Keep temporary tests focused on the specific change being implemented
+- Document what the temporary test is validating
+
+#### Cleanup Protocol
+**Temporary test files should be cleaned up when:**
+1. ✅ All tests are passing consistently
+2. ✅ The changes they were testing are working correctly
+3. ✅ The user explicitly agrees to cleanup
+4. ✅ The functionality is properly covered by existing or permanent tests
+
+#### Cleanup Process
+1. **Before cleanup, verify:**
+   - All temporary tests are passing
+   - The implemented changes work as expected
+   - No regressions have been introduced
+   - Permanent test coverage exists for the functionality
+
+2. **Request cleanup approval:**
+   - List the temporary files to be removed
+   - Confirm what functionality they were testing
+   - Ask for explicit user approval before deletion
+
+3. **Clean up systematically:**
+   - Remove temporary test files one at a time
+   - Run tests after each removal to ensure nothing breaks
+   - Confirm the workspace is clean and functional
+
+#### Temporary File Naming Convention
+- Use prefix: `temp_` or `test_temp_`
+- Include purpose: `temp_validation_`, `temp_integration_`, `temp_unit_`
+- Add feature identifier: `temp_auth_bug_fix`, `temp_api_endpoint_test`
+- Example: `temp_validation_user_registration.py`
+
+#### When NOT to Clean Up
+- If tests are still failing and debugging is ongoing
+- If the user hasn't explicitly approved cleanup
+- If the temporary tests reveal issues that need further investigation
+- If permanent test coverage is insufficient
+
+### Success Metrics
+
+A good change should be:
+- ✅ **Focused**: Addresses one specific issue
+- ✅ **Testable**: Can be verified with automated tests
+- ✅ **Reversible**: Can be easily undone if needed
+- ✅ **Incremental**: Builds on previous working state
+- ✅ **Documented**: Clear purpose and scope
+
+### Emergency Override
+
+If a large change is truly necessary:
+1. Explicitly acknowledge this violates the incremental principle
+2. Explain why incremental changes aren't feasible
+3. Break the large change into the smallest possible phases
+4. Ensure comprehensive testing at each phase
+5. Get explicit approval before proceeding
+
+---
+
+**Remember: It's better to make 10 small, working changes than 1 large change that requires 10 bug fixes.**
+
+## Development Environment
+
+### Conda Environment
+
+**CRITICAL: This project uses a conda environment named "supply-graph-ai".**
+
+- **Environment Name**: `supply-graph-ai`
+- **Always activate this environment** before running any Python commands, tests, or scripts
+- **When executing Python code**, ensure the conda environment is active
+- **When installing dependencies**, use: `conda activate supply-graph-ai && pip install ...`
+- **When running tests**, use: `conda activate supply-graph-ai && pytest ...`
+- **When running scripts**, use: `conda activate supply-graph-ai && python ...`
+
+**Activation Command:**
+```bash
+conda activate supply-graph-ai
+```
+
+**Verification:**
+Before executing any Python-related commands, verify the environment is active:
+```bash
+conda info --envs  # Should show supply-graph-ai with *
+# or
+which python  # Should point to conda environment
+```
+
+**Important Notes:**
+- Never assume a different Python environment is active
+- Always explicitly activate the conda environment in commands
+- If the environment doesn't exist, create it: `conda create -n supply-graph-ai python=3.12`
+- Dependencies are managed via `requirements.txt` and `requirements-dev.txt`
+
+## Project Structure (from maps)
+
+The repository follows this structure:
+- `src/cli/` - CLI commands and interface
+- `src/config/` - Configuration and settings
+- `src/core/generation/` - Core BOM generation logic
+- `src/core/services/` - Business logic services
+- `src/core/storage/` - Data storage and management
+- `src/core/models/` - Data models
+
+When creating new code, place it in the appropriate directory according to this structure.