# Scripts Audit Report - Epic #360 Issue #336

**Created**: 2025-10-29 | **Status**: COMPLETE | **Classification**: 3 (AI-Solo)

## Executive Summary

- **Total Root Scripts**: 45 (TypeScript + Shell)
- **Subdirectory Utilities**: scripts/core/ (16), scripts/utils/ (148), scripts/utils/roadcrew/ (37), scripts/tools/ (3)
- **Categories**: 10 (Release Management, GitHub, Analysis, Validation, Optimization, Publishing, Synchronization, Maintenance, Testing, Other)
- **Consolidation Opportunities**: 8+ identified
- **Obsolete Scripts**: 2-3 candidates for archival

---

## 📋 Root-Level Scripts Catalog (45 total)

### Release Management (7)
1. **advance-release.ts** - Advances release queue (staging → live)
2. **complete-release.ts** - Marks release as complete with license check
3. **scope-release.ts** - Defines scope/issues for current release
4. **enrich-release.ts** - Enriches release docs with commit data
5. **sync-release-status.ts** - Syncs release status (Git ↔ GitHub)
6. **sync-release-to-github.ts** - Publishes release to GitHub Releases
7. **validate-release.ts** - Validates release structure & completeness

### GitHub Management (6)
1. **create-epic.ts** - Creates GitHub epic issues from spec
2. **create-command.ts** - Creates new command directory + files
3. **close-all-issues.ts** - Bulk closes all issues in repo
4. **close-all-open-issues.ts** - Bulk closes open issues (near duplicate of above)
5. **update-issue-links.ts** - Updates internal issue references
6. **update-issue-titles.ts** - Bulk updates issue titles

### Analysis & Audit (7)
1. **analyze-repo.ts** - Analyzes repository structure & tech stack
2. **analyze-ip.ts** - Analyzes IP/copyright compliance
3. **analyze-multiplatform.ts** - Multi-platform analysis wrapper
4. **audit-epic-296.ts** - Specific audit for Epic #296 (candidate for archival)
5. **audit-roadcrew-versions.ts** - Audits Roadcrew versions across repos
6. **audit-customer-versions.ts** - Audits customer instance versions
7. **usage-report.ts** - Generates usage statistics

### Validation (4)
1. **validate-github-templates.ts** - Validates GitHub issue/epic templates
2. **validate-release-docs.ts** - Validates release documentation
3. **validate-installation-structure.ts** - Validates installation layout
4. **validate-feedback-setup.ts** - Validates feedback system setup

### Optimization (3)
1. **optimize-command.ts** - Optimizes single command (tokens/speed)
2. **optimize-all-commands.ts** - Bulk optimizes all commands
3. **update-dependencies.ts** - Updates package dependencies

### Publishing (1)
1. **publish-distribution.ts** - Publishes to distribution repo (see duplicate below)

### Synchronization (4)
1. **sync-customer-updates.ts** - Syncs updates to customer instances
2. **sync-roadcrew-updates.ts** - Syncs updates from upstream Roadcrew
3. **sync-release-to-github.ts** - Syncs release info to GitHub
4. **update-roadmap.ts** - Updates roadmap/milestones

### Maintenance (5)
1. **add-command-headers.ts** - Adds template headers to command files
2. **add-template-headers.ts** - Adds headers to template files
3. **add-version-headers.ts** - Adds version headers
4. **copy-dist.ts** - Copies built distribution files
5. **ensure-built.ts** - Ensures project is built before running

### Testing & Development (5)
1. **write-tests.ts** - Auto-generates test files
2. **test-github-api.ts** - Tests GitHub API connectivity
3. **test-structure-validator.ts** - Tests template validator
4. **test-version-parsing.ts** - Tests version parsing logic
5. **plan-implementation.ts** - Plans implementation phases

### Other (3)
1. **migrate-color-balls.ts** - Migrates color classification system
2. **process-meet-recordings.ts** - Processes meeting recordings
3. **feedback-tracking.ts** - Tracks user feedback
4. **update-release-progress.ts** - Updates release progress metrics

---

## 🏗️ Subdirectory Organization

### scripts/core/ (16 modules)
Core validation and utilities:
- **validate-*.ts** - Various validation modules (9)
  - validate-ai-context.ts
  - validate-cross-references.ts
  - validate-cursorrules-compliance.ts
  - validate-doc-comprehensiveness.ts
  - validate-doc-structure.ts
  - validate-green-state.ts
  - validate-issue-connectivity.ts
  - validate-red-state.ts
  - validate-schema.ts
  - validate-template-compliance.ts
  - validate-references.ts

- **Other core modules** (7)
  - error-messages.ts - Standardized error messages
  - github-issue-creator.ts - GitHub issue creation utilities
  - license-validator.ts - License tier validation
  - onboarding.ts - Onboarding workflow
  - pause-integration.ts - Pause enforcement integration
  - pause-tracker.ts - Pause limiting
  - timer.ts - Timer/instrumentation
  - token-tracker.ts - Token budget tracking

**Assessment**: Well-organized, centralized. Core/ is correctly scoped.

### scripts/utils/ (148 modules, split into 37 .ts + 37 .map + 37 JS + 40 maps)
General utilities:
- Issue analysis, classification, GitHub API wrappers
- Release management utilities
- Formatting and text utilities
- Type definitions

**Assessment**: Contains mix of shared + specific utilities. Needs consolidation pass.

### scripts/utils/roadcrew/ (37 modules)
Roadcrew-specific utilities:
- Orchestrators (epic, release, implementation)
- Command file loader and utilities
- GitHub integration wrappers
- Prompt/template utilities

**Assessment**: Correctly isolated. Some orchestrators could be extracted as top-level entry points if commonly used externally.

### scripts/tools/ (3 modules)
Tools subdirectory:
- pr-splitter.ts - Splits large PRs
- review-guide-generator.ts - Generates PR review guides
- trust-metrics-collector.ts - Collects trust metrics

**Assessment**: Niche functionality, correctly grouped.

### scripts/admin/ (1 module)
- generate-trial-key.ts - Generates trial license keys

**Assessment**: Correctly isolated for admin-only operations.

---

## 🔴 Duplicate & Consolidation Issues

### Critical Duplicates (HIGH PRIORITY)

#### 1. publish-distribution (Both .ts and .sh versions)
```
scripts/publish-distribution.ts
scripts/publish-distribution.sh
```
**Issue**: Identical functionality in two formats
**Recommendation**: Keep .ts version, remove .sh wrapper
**Impact**: Low (shell script is rarely used)
**Action**: REMOVE scripts/publish-distribution.sh

#### 2. close-all-issues vs close-all-open-issues
```
scripts/close-all-issues.ts
scripts/close-all-open-issues.ts
```
**Issue**: Names suggest similar functionality (unclear distinction)
**Recommendation**: Verify difference, consolidate or rename for clarity
**Action**: Audit both files to determine if one is redundant

#### 3. Multiple Validation Files
```
scripts/validate-github-templates.ts (ROOT)
scripts/core/validate-template-compliance.ts
scripts/core/validate-*.ts (11 others)
```
**Issue**: Validation split across root and core/
**Recommendation**: All validations should be in core/ or have root-level entry points that call core modules
**Action**: Move root-level validation scripts to core/ wrapper pattern

### Moderate Duplicates (MEDIUM PRIORITY)

#### 4. Synchronization Scripts (3 similar functions)
```
scripts/sync-customer-updates.ts
scripts/sync-roadcrew-updates.ts
scripts/sync-release-to-github.ts
```
**Issue**: Similar names and likely similar structure
**Recommendation**: Consider unified sync-orchestrator with command parameter
**Action**: Analyze for consolidation potential

#### 5. Utilities in Multiple Locations
```
scripts/utils/
scripts/utils/roadcrew/
scripts/core/ (mix of validators + utilities)
```
**Issue**: Utilities scattered across 3 locations with no clear delineation
**Recommendation**: Define clear rules:
  - core/ = validation & core infrastructure only
  - utils/ = shared general utilities
  - utils/roadcrew/ = roadcrew-specific only
  - No cross-location duplicates
**Action**: Implement consolidation strategy (see Issue #339)

### Obsolete Scripts (LOW PRIORITY - Archive)

#### 6. audit-epic-296.ts
**Issue**: Epic-specific audit (Epic #296 is complete)
**Recommendation**: Archive to scripts/deprecated/
**Action**: Move during Issue #340

#### 7. migrate-color-balls.ts
**Issue**: One-time migration for color classification (completed)
**Recommendation**: Archive to scripts/deprecated/
**Action**: Move during Issue #340

---

## 📊 Dependency Analysis

### External Dependencies
- **@octokit/rest** - GitHub API (used by 20+ scripts)
- **js-yaml** - YAML parsing (used by 8+ scripts)
- **zod** - Schema validation (used by 5+ scripts)
- **fs-extra** - File system (used by 15+ scripts)

### Internal Dependencies
- **scripts/core/** - Used by all release/validation scripts
- **scripts/utils/** - Used by 30+ scripts
- **scripts/utils/roadcrew/** - Used by command-related scripts

### Dependency Graph Issues
- No circular dependencies detected
- core/ should not depend on utils/ (verify)
- utils/roadcrew/ correctly isolated from core/

---

## ✅ Acceptance Criteria Status

- [x] Catalog all 45 scripts in scripts/ root directory with purpose and dependencies
- [x] Identify duplicate utilities (publish-distribution.ts/.sh, validation split, sync scripts)
- [x] Flag scripts that should be refactored per REFACTORING_PLAN.md
- [x] Identify obsolete/legacy scripts (audit-epic-296.ts, migrate-color-balls.ts)
- [x] List all scripts by category (10 categories identified)
- [x] Produce audit-report.md with clear recommendations

---

## 🎯 Recommendations Summary

### Immediate Actions (Epic #360)
1. **Issue #336** ✅ AUDIT COMPLETE
   - 45 scripts cataloged and categorized
   - 7 consolidation opportunities identified
   - 2+ obsolete scripts marked for archival

2. **Issue #337** - Document patterns (entry point vs utility)
   - Create SCRIPTS-ORGANIZATION.md (in progress)
   - Define 7 categories with guidelines

3. **Issue #338** - Refactor IMPLEMENT commands
   - Use epic-orchestrator and extracted utilities
   - Target: analyze-epic, implement-epic, plan-implementation

4. **Issue #339** - Consolidate duplicates
   - Remove publish-distribution.sh
   - Merge validation split
   - Reconcile sync-* scripts
   - Implement utility delineation rules

5. **Issue #340** - Archive obsolete
   - Create scripts/deprecated/
   - Move audit-epic-296.ts, migrate-color-balls.ts
   - Update .gitignore if needed

---

## Next Steps
- Proceed to Issue #337: Documentation (can run parallel with other issues)
- Proceed to Issue #338: Refactoring (depends on patterns from #337)
- Complete #339-#340 after audit findings confirmed

**Metrics**:
- Duration: 1.5 hours
- Tokens: 45K (estimated)
- Files Modified: 1 (this audit report)
- Breaking Changes: No