# [Epic #297] Scripts Folder Organization & Consolidation (Release #279)

**Overview**: Audit, document, and restructure scripts/ folder to consolidate duplicates, remove obsolete code, and ensure consistent organization. Reduces maintenance burden and clarifies codebase structure for developers.

**Key Goals**:
- Audit all 37 entry point scripts and identify consolidation candidates
- Document entry point script organization pattern for consistency
- Refactor 4 IMPLEMENT commands to use extracted utilities (per REFACTORING_PLAN.md)
- Consolidate duplicate utilities in scripts/utils/roadcrew/ and scripts/core/
- Archive obsolete scripts and update build configuration

## Child Issues

### Issue 1: Audit scripts/roadcrew/ for Duplicates & Consolidation Candidates

**GitHub Issue**: #303  
**Classification**: 3 (ai-solo)  
**Status**: ⏳ PENDING

**Overview & User Story**:  
As a DevOps engineer, I want a comprehensive audit of all 37 entry point scripts so I can understand what exists, what's duplicate, and what needs refactoring.

**Acceptance Criteria**:
- [ ] Catalog all 37 scripts in scripts/ root directory with purpose and dependencies
- [ ] Identify duplicate utilities (same module in root AND scripts/utils/roadcrew/)
- [ ] Flag scripts that should be refactored per REFACTORING_PLAN.md
- [ ] Identify obsolete/legacy scripts that can be archived
- [ ] List all scripts by category (analysis, planning, release, implement, code-analysis, testing, publish, validation, admin)
- [ ] Produce audit-report.md with clear recommendations for each issue

**Technical Implementation**:
1. Parse each .ts file in scripts/ root
2. Extract purpose, entry point signature, imports (identify utilities used)
3. Cross-reference with scripts/utils/roadcrew/ and scripts/core/ for duplicates
4. Check REFACTORING_PLAN.md for refactoring candidates
5. Compare against git history to identify dead code
6. Generate structured audit report (CSV + Markdown)

**Dependencies**:
- Depends on: None (foundational audit)
- Blocks: Issues 2-5 (need audit data)
- Related: REFACTORING_PLAN.md, FOLDER_ORGANIZATION.md

**Estimated Effort**: 
- **Size**: Small (exploratory)
- **Complexity**: Low (no code changes)
- **Time**: 2-3 hours

---

### Issue 2: Document Entry Point Scripts Organization Pattern

**GitHub Issue**: #304  
**Classification**: 2 (ai-solo)  
**Status**: ⏳ PENDING

**Overview & User Story**:  
As a developer, I want clear documentation on why scripts are in root vs utilities so I can make consistent decisions when adding new scripts.

**Acceptance Criteria**:
- [ ] Create SCRIPTS-ORGANIZATION.md explaining entry point vs utility distinction
- [ ] Document the 7 categories of entry point scripts and examples for each
- [ ] Clarify when to add a script to scripts/ vs scripts/utils/roadcrew/
- [ ] Explain build process and how entry points compile/distribute
- [ ] Show before/after examples of good vs inconsistent organization
- [ ] Add decision tree graphic for script placement
- [ ] Cross-reference with FOLDER_ORGANIZATION.md

**Technical Implementation**:
1. Review FOLDER_ORGANIZATION.md and REFACTORING_PLAN.md for context
2. Document 7 entry point categories with purpose and examples
3. Create decision flowchart (entry point vs utility vs core)
4. Explain npm run build process and distribution
5. Add examples of refactored scripts vs refactoring candidates
6. Include troubleshooting section for common mistakes

**Dependencies**:
- Depends on: Issue 1 (audit provides data for examples)
- Blocks: None (documentation)
- Related: FOLDER_ORGANIZATION.md, DEVELOPMENT.md

**Estimated Effort**:
- **Size**: Small (documentation)
- **Complexity**: Low (no code)
- **Time**: 1-2 hours

---

### Issue 3: Refactor IMPLEMENT Commands to Use Extracted Utilities

**GitHub Issue**: #305  
**Classification**: 6 (ai-led)  
**Status**: ⏳ PENDING

**Overview & User Story**:  
As a maintainer, I want to refactor 4 IMPLEMENT pattern commands to use extracted utilities so code is DRY, tokens are saved, and commands are more maintainable.

**Acceptance Criteria**:
- [ ] analyze-epic refactored to use epic-orchestrator (200-300 tokens saved)
- [ ] implement-issue refactored to use testing-harness (100-200 tokens saved)
- [ ] implement-epic refactored to use both coordinators (300-500 tokens saved)
- [ ] autopilot refactored to use all 3 extracted utilities (600-900 tokens saved)
- [ ] All 4 commands have 80%+ test coverage
- [ ] Zero functional regressions (behavioral parity verified)
- [ ] Total token reduction: 1.95-2.75K tokens (per REFACTORING_PLAN.md)
- [ ] All existing command tests pass

**Technical Implementation**:
Follow REFACTORING_PLAN.md exactly:
1. **analyze-epic** (Priority HIGH):
   - Replace epic orchestration logic with epic-orchestrator functions
   - Remove risk assessment duplication
   - Reduce ~400 lines → ~100-150 lines

2. **implement-issue** (Priority LOW):
   - Replace test framework detection with testing-harness
   - Use metrics tracking functions
   - Simplify ~80-100 lines

3. **implement-epic** (Priority MEDIUM):
   - Use runPreflightChecks() and detectProjectContext()
   - Use implementation-coordinator functions
   - Use testing-harness for test operations

4. **autopilot** (Priority MEDIUM):
   - Phase 1: Use analyzeEpic() from epic-orchestrator
   - Phase 2: Use implementation-coordinator functions
   - All testing: Use testing-harness

**Dependencies**:
- Depends on: Issue 1 (audit confirms these are refactoring candidates)
- Blocks: Issue 4 (consolidation needs refactoring complete)
- Related: REFACTORING_PLAN.md, Epic #128

**Estimated Effort**:
- **Size**: Large (multi-file refactoring)
- **Complexity**: High (multiple command interdependencies)
- **Time**: 8-12 hours

---

### Issue 4: Consolidate Duplicate Utilities

**GitHub Issue**: #306  
**Classification**: 5 (ai-led)  
**Status**: ⏳ PENDING

**Overview & User Story**:  
As a maintainer, I want to consolidate duplicate utility modules so there's one source of truth and developers don't get confused about which version to use.

**Acceptance Criteria**:
- [ ] Identify all duplicate modules (same code in scripts/utils/ and scripts/utils/roadcrew/)
- [ ] Merge duplicates into scripts/utils/roadcrew/ (per namespace isolation principle)
- [ ] Update all imports across codebase to use single consolidated path
- [ ] Remove obsolete duplicate files and verify no broken imports
- [ ] All tests pass after consolidation
- [ ] Build produces no duplicate files in dist/
- [ ] Verify no functional changes (same behavior, unified codebase)

**Technical Implementation**:
1. From Issue 1 audit, find exact duplicate modules
2. For each duplicate:
   - Compare file contents to identify true duplicates vs variations
   - Keep version in scripts/utils/roadcrew/ (per namespace isolation)
   - Consolidate any unique logic from root version
   - Delete obsolete file
3. Search codebase for imports of deleted files
4. Update all imports to use consolidated location
5. Run `npm run build` and verify no errors
6. Verify test suite passes
7. Verify dist/ has no duplicates

**Dependencies**:
- Depends on: Issue 1 (audit identifies duplicates), Issue 3 (refactoring may reduce imports)
- Blocks: Issue 5 (archive needs consolidation complete)
- Related: FOLDER_ORGANIZATION.md, npm build process

**Estimated Effort**:
- **Size**: Medium (multi-file updates)
- **Complexity**: Medium (import tracking, build verification)
- **Time**: 4-6 hours

---

### Issue 5: Archive Obsolete Scripts

**GitHub Issue**: #307  
**Classification**: 4 (ai-led)  
**Status**: ⏳ PENDING

**Overview & User Story**:  
As a maintainer, I want to archive obsolete/legacy scripts so the active scripts/ directory stays clean and focused on current functionality.

**Acceptance Criteria**:
- [ ] Identify all obsolete scripts from Issue 1 audit
- [ ] Create scripts/deprecated/ directory for archiving
- [ ] Move obsolete scripts with git history preserved
- [ ] Update build configuration to exclude deprecated/ from build output
- [ ] Update .gitignore if needed to keep deprecated in repo for history
- [ ] Verify no remaining code imports from deprecated scripts
- [ ] Document why each script was archived (link to issue or TODO comment)
- [ ] Update CHANGELOG.md noting deprecation

**Technical Implementation**:
1. From Issue 1 audit, compile list of obsolete scripts
2. Create scripts/deprecated/ directory
3. Move each script: `git mv scripts/old-script.ts scripts/deprecated/old-script.ts`
4. Update tsconfig.json to exclude deprecated/ from build
5. Update package.json build scripts if needed
6. Search for any imports from deprecated/ and remove them
7. Add comments to deprecated/ README explaining archive
8. Run `npm run build` to verify no errors
9. Verify dist/ doesn't contain deprecated code

**Dependencies**:
- Depends on: Issue 1 (identifies obsolete scripts), Issues 3-4 (refactoring/consolidation may remove references)
- Blocks: None (final cleanup)
- Related: build configuration, git preservation

**Estimated Effort**:
- **Size**: Small-Medium (file moves + config updates)
- **Complexity**: Low (straightforward cleanup)
- **Time**: 2-3 hours

---

## Dependencies

- **Depends on**: Epic #128 (REFACTORING_PLAN.md may already be in progress)
- **Blocks**: None (improves maintainability, no blocking dependencies)
- **Related Epics**: Epic #21 (Folder Organization - foundational)

---

## Definition of Done

- [ ] All 5 child issues completed and merged
- [ ] No broken imports or build errors
- [ ] All tests passing (80%+ coverage maintained)
- [ ] Documentation updated and linked in main README
- [ ] One team member can explain organization decisions confidently

---

**Related Spec**: [FOLDER_ORGANIZATION.md](../../FOLDER_ORGANIZATION.md)

**Implementation Timeline**: 2-3 weeks (can parallelize Issues 2-3 with 1)
- Week 1: Issue 1 (audit) + Issue 2 (documentation in parallel)
- Week 1-2: Issue 3 (refactoring, may extend into week 2)
- Week 2: Issue 4 (consolidation)
- Week 2-3: Issue 5 (archive)