aios-core 2.1.5 → 2.2.0

package/.aios-core/development/tasks/cleanup-utilities.md

@@ -1,670 +1,670 @@
----
-tools:
-  - github-cli        # Git operations for archiving files
----
-
-# Cleanup Utilities Task
-
-## Purpose
-
-Safely archive deprecated utilities identified in Story 3.17 audit, reducing technical debt and developer confusion while maintaining the ability to restore utilities if needed.
-
-## Safety Principles
-
-**CRITICAL**: This task archives (not deletes) deprecated utilities using a fail-safe workflow:
-1. **Backup first** - Create timestamped backup before any changes
-2. **Verify dependencies** - Block removal if active code depends on utility
-3. **Archive, don't delete** - Preserve files for historical reference
-4. **Validate after** - Ensure framework still works after cleanup
-5. **Document rollback** - Clear instructions to undo if needed
-
-## Prerequisites
-
-- Story 3.17 complete (UTILITIES-AUDIT-REPORT.md exists)
-- List of DEPRECATED utilities from audit report
-- Git repository in clean state
-
-## Classification Review
-
-Before cleanup, verify utilities are truly deprecated:
-
-### ✅ SAFE TO ARCHIVE
-- No active code references (grep shows 0 results)
-- Classified as DEPRECATED in audit report
-- Obsolete concept or non-functional
-- Duplicate/refactored version exists
-
-### ⚠️ NEEDS REVIEW
-- Has active references in code (grep shows >0 results)
-- Classified as FIXABLE but needs deprecation
-- Unclear status from audit
-
-### ❌ DO NOT ARCHIVE
-- Classified as WORKING in audit report
-- Critical framework utility
-- Has active agent/task dependencies
-
-## Configuration Dependencies
-
-This task requires the following configuration keys from `core-config.yaml`:
-
-- **`devStoryLocation`**: Location of story files (typically docs/stories) - Required to access Story 3.17 audit results
-- **`core-config`**: Direct reference to core configuration file - This task updates the utility count in core-config.yaml
-- **`qaLocation`**: QA output directory (typically docs/qa) - Required to write quality reports
-
-**Loading Config:**
-```javascript
-const yaml = require('js-yaml');
-const fs = require('fs');
-const path = require('path');
-
-const configPath = path.join(__dirname, '../../.aios-core/core-config.yaml');
-const config = yaml.load(fs.readFileSync(configPath, 'utf8'));
-
-const devStoryLocation = config.devStoryLocation; // For accessing audit report
-const coreConfigPath = configPath; // For updating utility count
-const qaLocation = config.qa?.qaLocation || 'docs/qa'; // qaLocation
-```
-
-## Execution Steps
-
-### Step 1: Pre-Cleanup Preparation
-
-**1.1 Create Backup**
-```bash
-# Create timestamped backup of entire utils directory
-mkdir -p .backups
-cp -r .aios-core/utils ".backups/utils.backup-3.18-$(date +%Y%m%d-%H%M%S)"
-```
-
-**1.2 Verify Audit Report**
-```bash
-# Ensure audit report exists and is readable
-test -f UTILITIES-AUDIT-REPORT.md && echo "✅ Audit report found" || echo "❌ Audit report missing"
-```
-
-**1.3 Extract Deprecated List**
-
-From UTILITIES-AUDIT-REPORT.md, identify all utilities in:
-- Category A: Duplicate/Redundant Versions
-- Category B: Incomplete Experiments
-- Category C: Obsolete Concepts
-- Category D: Misplaced (move, don't archive)
-
-### Step 2: Dependency Verification (CRITICAL)
-
-For each deprecated utility, check for active references:
-
-**2.1 Automated Dependency Check**
-```bash
-# Check for require() statements
-grep -r "require.*utility-name" .aios-core/agents .aios-core/tasks .aios-core/workflows expansion-packs/
-
-# Check for string references (utility mentioned in docs/configs)
-grep -r "utility-name" .aios-core/agents/ .aios-core/tasks/ .aios-core/core-config.yaml
-
-# Count total references
-count=$(grep -r "utility-name" .aios-core/ expansion-packs/ 2>/dev/null | wc -l)
-echo "References found: $count"
-```
-
-**2.2 Manual Review**
-
-If references found (count > 0):
-- Review each reference context
-- Determine if reference is:
-  - Active usage (BLOCK removal)
-  - Comment/documentation (SAFE to remove)
-  - Obsolete reference (UPDATE then remove)
-
-**2.3 Create Exception List**
-
-Document utilities that cannot be archived due to dependencies:
-```markdown
-## Utilities with Active Dependencies
-
-1. utility-name.js
-   - References: 5 locations
-   - Reason: Still used by @agent-name
-   - Action: Defer until Story X.XX removes dependency
-```
-
-### Step 3: Create Archive Structure
-
-**3.1 Create Archive Directory**
-```bash
-mkdir -p .aios-core/utils-archive
-```
-
-**3.2 Create Archive README**
-
-Create `.aios-core/utils-archive/ARCHIVE-README.md`:
-
-```markdown
-# Archived Utilities - Story 3.18
-
-**Archive Date**: 2025-10-31
-**Story**: Epic 3c - Story 3.18 (Utilities Cleanup & Deprecation)
-**Audit Report**: UTILITIES-AUDIT-REPORT.md (Story 3.17)
-
-## Purpose
-
-This directory contains utilities that were deprecated and removed from active use during Epic 3 Phase 2. Files are preserved for historical reference and potential restoration.
-
-## Why Archive Instead of Delete?
-
-1. **Historical Reference** - Document what was tried and why it didn't work
-2. **Restoration Capability** - Enable future restoration if utility is needed
-3. **Audit Trail** - Maintain complete codebase history
-4. **Learning Resource** - Study patterns that didn't work out
-
-## Archive Categories
-
-### Category A: Duplicate/Redundant Versions (9 files)
-Utilities with `-refactored` or `-fixed` suffixes where original version works.
-
-### Category B: Incomplete Experiments (9 files)
-Partially implemented utilities that were abandoned before completion.
-
-### Category C: Obsolete Concepts (12 files)
-Utilities whose functionality is better handled by external tools or manual processes.
-
-### Category D: Misplaced Files (1 file)
-Test files that belong in `/tests` directory instead of `/utils`.
-
-## How to Restore a Utility
-
-If you need to restore an archived utility:
-
-1. **Copy file back**:
-   ```bash
-   cp .aios-core/utils-archive/utility-name.js .aios-core/scripts/
-   ```
-
-2. **Reinstall dependencies** (if needed):
-   ```bash
-   npm install missing-dependency
-   ```
-
-3. **Update references**:
-   - Add utility to agent dependencies if needed
-   - Update task workflows that use it
-   - Add to core-config.yaml registry
-
-4. **Test thoroughly**:
-   ```bash
-   node .aios-core/scripts/test-utilities.js
-   ```
-
-5. **Update Story 3.18**:
-   - Document which utility was restored and why
-   - Reclassify in audit report (DEPRECATED → WORKING/FIXABLE)
-
-## Archived Utilities
-
-Total: 28 files archived from 81 total utilities
-
-[Detailed list generated during cleanup]
-
-## Rollback Procedure
-
-If cleanup breaks something:
-
-**Immediate Rollback**:
-```bash
-rm -rf .aios-core/utils
-cp -r .backups/utils.backup-3.18-YYYYMMDD-HHMMSS .aios-core/utils
-```
-
-**Selective Restoration**:
-```bash
-cp .aios-core/utils-archive/specific-utility.js .aios-core/scripts/
-```
-
----
-
-## Execution Modes
-
-**Choose your execution mode:**
-
-### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
-- Autonomous decision making with logging
-- Minimal user interaction
-- **Best for:** Simple, deterministic tasks
-
-### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
-- Explicit decision checkpoints
-- Educational explanations
-- **Best for:** Learning, complex decisions
-
-### 3. Pre-Flight Planning - Comprehensive Upfront Planning
-- Task analysis phase (identify all ambiguities)
-- Zero ambiguity execution
-- **Best for:** Ambiguous requirements, critical work
-
-**Parameter:** `mode` (optional, default: `interactive`)
-
----
-
-## Task Definition (AIOS Task Format V1.0)
-
-```yaml
-task: cleanupUtilities()
-responsável: Dex (Builder)
-responsavel_type: Agente
-atomic_layer: Molecule
-
-**Entrada:**
-- campo: task
-  tipo: string
-  origem: User Input
-  obrigatório: true
-  validação: Must be registered task
-
-- campo: parameters
-  tipo: object
-  origem: User Input
-  obrigatório: false
-  validação: Valid task parameters
-
-- campo: mode
-  tipo: string
-  origem: User Input
-  obrigatório: false
-  validação: yolo|interactive|pre-flight
-
-**Saída:**
-- campo: execution_result
-  tipo: object
-  destino: Memory
-  persistido: false
-
-- campo: logs
-  tipo: array
-  destino: File (.ai/logs/*)
-  persistido: true
-
-- campo: state
-  tipo: object
-  destino: State management
-  persistido: true
-```
-
----
-
-## Pre-Conditions
-
-**Purpose:** Validate prerequisites BEFORE task execution (blocking)
-
-**Checklist:**
-
-```yaml
-pre-conditions:
-  - [ ] Task is registered; required parameters provided; dependencies met
-    tipo: pre-condition
-    blocker: true
-    validação: |
-      Check task is registered; required parameters provided; dependencies met
-    error_message: "Pre-condition failed: Task is registered; required parameters provided; dependencies met"
-```
-
----
-
-## Post-Conditions
-
-**Purpose:** Validate execution success AFTER task completes
-
-**Checklist:**
-
-```yaml
-post-conditions:
-  - [ ] Task completed; exit code 0; expected outputs created
-    tipo: post-condition
-    blocker: true
-    validação: |
-      Verify task completed; exit code 0; expected outputs created
-    error_message: "Post-condition failed: Task completed; exit code 0; expected outputs created"
-```
-
----
-
-## Acceptance Criteria
-
-**Purpose:** Definitive pass/fail criteria for task completion
-
-**Checklist:**
-
-```yaml
-acceptance-criteria:
-  - [ ] Task completed as expected; side effects documented
-    tipo: acceptance-criterion
-    blocker: true
-    validação: |
-      Assert task completed as expected; side effects documented
-    error_message: "Acceptance criterion not met: Task completed as expected; side effects documented"
-```
-
----
-
-## Tools
-
-**External/shared resources used by this task:**
-
-- **Tool:** task-runner
-  - **Purpose:** Task execution and orchestration
-  - **Source:** .aios-core/core/task-runner.js
-
-- **Tool:** logger
-  - **Purpose:** Execution logging and error tracking
-  - **Source:** .aios-core/utils/logger.js
-
----
-
-## Scripts
-
-**Agent-specific code for this task:**
-
-- **Script:** execute-task.js
-  - **Purpose:** Generic task execution wrapper
-  - **Language:** JavaScript
-  - **Location:** .aios-core/scripts/execute-task.js
-
----
-
-## Error Handling
-
-**Strategy:** retry
-
-**Common Errors:**
-
-1. **Error:** Task Not Found
-   - **Cause:** Specified task not registered in system
-   - **Resolution:** Verify task name and registration
-   - **Recovery:** List available tasks, suggest similar
-
-2. **Error:** Invalid Parameters
-   - **Cause:** Task parameters do not match expected schema
-   - **Resolution:** Validate parameters against task definition
-   - **Recovery:** Provide parameter template, reject execution
-
-3. **Error:** Execution Timeout
-   - **Cause:** Task exceeds maximum execution time
-   - **Resolution:** Optimize task or increase timeout
-   - **Recovery:** Kill task, cleanup resources, log state
-
----
-
-## Performance
-
-**Expected Metrics:**
-
-```yaml
-duration_expected: 2-5 min (estimated)
-cost_estimated: $0.001-0.003
-token_usage: ~1,000-3,000 tokens
-```
-
-**Optimization Notes:**
-- Parallelize independent operations; reuse atom results; implement early exits
-
----
-
-## Metadata
-
-```yaml
-story: N/A
-version: 1.0.0
-dependencies:
-  - N/A
-tags:
-  - automation
-  - workflow
-updated_at: 2025-11-17
-```
-
----
-
-*Generated during Story 3.18 - Epic 3c Phase 2*
-```
-
-### Step 4: Execute Cleanup
-
-**4.1 Archive Deprecated Utilities**
-
-For each utility in the deprecated list with 0 dependencies:
-
-```bash
-# Use git mv to preserve history
-git mv .aios-core/scripts/utility-name.js .aios-core/utils-archive/
-
-# Or for multiple files:
-git mv .aios-core/scripts/{aios-validator-fixed.js,aios-validator-refactored.js} .aios-core/utils-archive/
-```
-
-**4.2 Move Misplaced Files** (Category D)
-
-```bash
-# Create tests directory if it doesn't exist
-mkdir -p tests/utils
-
-# Move test files to proper location
-git mv .aios-core/scripts/aios-validator.test.js tests/utils/
-```
-
-**4.3 Update Archive README**
-
-Add complete list of archived files to ARCHIVE-README.md:
-
-```markdown
-## Archived Utilities
-
-### Category A: Duplicate/Redundant (9 files)
-1. aios-validator-fixed.js - Duplicate of aios-validator.js
-2. aios-validator-refactored.js - Duplicate of aios-validator.js
-...
-
-### Category B: Incomplete Experiments (9 files)
-1. change-propagation-predictor.js - 20% complete, no clear use case
-...
-
-### Category C: Obsolete Concepts (12 files)
-1. batch-creator.js - Batch processing not used
-...
-
-**Total Archived**: 30 files
-**Remaining Active**: 51 files
-```
-
-### Step 5: Update Documentation
-
-**5.1 Update core-config.yaml**
-
-Update utility count in `.aios-core/core-config.yaml`:
-
-```yaml
-framework:
-  entities:
-    utils:
-      count: 51  # Updated from 81
-      location: .aios-core/scripts/
-```
-
-**5.2 Add Changelog Entry**
-
-Add entry to Epic 3 changelog (or Story 3.18 change_log):
-
-```yaml
-- date: '2025-10-31'
-  version: 2.0.0
-  description: Utilities cleanup complete - 30 deprecated files archived
-  author: James (@dev)
-  changes:
-    - 'Archived 30 deprecated utilities (37% of total 81)'
-    - 'Created utils-archive/ with restoration documentation'
-    - 'Moved 1 test file to proper location'
-    - 'Updated core-config.yaml utility count: 81 → 51'
-    - 'Framework validation passed post-cleanup'
-    - 'All agents (@dev, @po, @qa) activate successfully'
-```
-
-**5.3 Update Developer Guides**
-
-If any developer guides reference archived utilities, update them:
-- Remove references to deprecated utilities
-- Update utility lists to reflect active utilities only
-- Add note about archived utilities location
-
-### Step 6: Validation (CRITICAL)
-
-**6.1 Framework Validation**
-
-Run framework validator to ensure no broken references:
-
-```bash
-node .aios-core/scripts/aios-validator.js
-```
-
-Expected: 0 errors related to missing utilities
-
-**6.2 Agent Activation Tests**
-
-Test that all core agents still activate:
-
-```bash
-# Test each agent manually or via script
-# @dev agent
-# @po agent
-# @qa agent
-```
-
-Expected: All agents load without errors
-
-**6.3 Grep Validation**
-
-Verify no broken references to archived utilities:
-
-```bash
-# Check for require() statements pointing to archived utilities
-for util in $(ls .aios-core/utils-archive/*.js); do
-  name=$(basename $util .js)
-  refs=$(grep -r "require.*$name" .aios-core/agents .aios-core/tasks 2>/dev/null | wc -l)
-  if [ $refs -gt 0 ]; then
-    echo "⚠️ Found $refs references to archived utility: $name"
-  fi
-done
-```
-
-Expected: 0 references to archived utilities
-
-**6.4 Test Utilities Scan**
-
-Re-run test-utilities.js to verify remaining utilities:
-
-```bash
-node .aios-core/scripts/test-utilities.js
-```
-
-Expected: Only active utilities tested, no errors loading utilities
-
-### Step 7: Create Rollback Documentation
-
-Document the exact rollback procedure in story completion notes:
-
-```markdown
-## Rollback Procedure
-
-**Backup Location**: `.backups/utils.backup-3.18-YYYYMMDD-HHMMSS`
-
-**Full Rollback**:
-```bash
-rm -rf .aios-core/utils
-cp -r .backups/utils.backup-3.18-YYYYMMDD-HHMMSS .aios-core/utils
-git checkout .aios-core/core-config.yaml
-```
-
-**Selective Restoration**:
-```bash
-cp .aios-core/utils-archive/utility-name.js .aios-core/scripts/
-```
-
-**Verification**:
-```bash
-node .aios-core/scripts/aios-validator.js
-```
-```
-
-## Output
-
-**Primary Deliverables**:
-1. `.aios-core/utils-archive/` - Archive directory with 30 deprecated utilities
-2. `.aios-core/utils-archive/ARCHIVE-README.md` - Archive documentation
-3. `.backups/utils.backup-3.18-YYYYMMDD-HHMMSS/` - Timestamped backup
-4. Updated `.aios-core/core-config.yaml` - Corrected utility count
-5. Updated story change_log - Cleanup completion entry
-
-**Expected Results**:
-- 30 utilities archived (37% of 81 total)
-- 51 utilities remain active (63% of total)
-- 1 test file moved to proper location
-- 0 broken references introduced
-- All agents activate successfully
-- Framework validation passes
-
-## Success Criteria
-
-- ✅ All 30 deprecated utilities archived without deletion
-- ✅ Zero broken references (grep validation passes)
-- ✅ Framework validation (aios-validator.js) passes
-- ✅ All agents (@dev, @po, @qa) activate successfully
-- ✅ Backup created before changes
-- ✅ Archive README created with restoration instructions
-- ✅ core-config.yaml updated accurately
-- ✅ Rollback procedure documented and tested
-- ✅ No utility references in agents point to archived utilities
-
-## Notes
-
-### Windows Compatibility
-- Use Git Bash for commands (git mv, grep, etc.)
-- Backup paths: `.backups/utils.backup-3.18-YYYYMMDD-HHMMSS`
-- Test on Windows 10/11 with Git for Windows
-
-### Safety Reminders
-- **NEVER** delete files, only archive
-- **ALWAYS** backup before making changes
-- **VERIFY** dependencies before archiving
-- **TEST** framework after cleanup
-- **DOCUMENT** rollback procedure
-
-### Integration with safe-removal-handler.js
-
-While this task can be executed manually following the steps above, the `safe-removal-handler.js` utility provides automated safety checks. For future cleanups, consider integrating with the handler for:
-- Automated dependency checking
-- Safety verification
-- Quarantine for uncertain utilities
-- Automated rollback capability
-
-For this cleanup, manual execution is preferred to maintain full control and visibility.
-
-## Estimated Time
-
-- Step 1-2: 1 hour (preparation + dependency checking)
-- Step 3: 30 minutes (archive structure)
-- Step 4: 1 hour (execution)
-- Step 5: 30 minutes (documentation)
-- Step 6: 1 hour (validation)
-- **Total**: 4 hours
-
-## Common Issues
-
-**Issue**: Git mv fails with "file not found"
-**Solution**: Verify file exists and path is correct, use forward slashes
-
-**Issue**: Grep shows false positives (references in comments)
-**Solution**: Manually review each reference, ignore comments/docs
-
-**Issue**: Agent activation fails after cleanup
-**Solution**: Check which utility is missing, restore from archive, investigate
-
-**Issue**: Validation script errors
-**Solution**: Rollback, identify which archived utility was needed, update audit classification
+---
+tools:
+  - github-cli        # Git operations for archiving files
+---
+
+# Cleanup Utilities Task
+
+## Purpose
+
+Safely archive deprecated utilities identified in Story 3.17 audit, reducing technical debt and developer confusion while maintaining the ability to restore utilities if needed.
+
+## Safety Principles
+
+**CRITICAL**: This task archives (not deletes) deprecated utilities using a fail-safe workflow:
+1. **Backup first** - Create timestamped backup before any changes
+2. **Verify dependencies** - Block removal if active code depends on utility
+3. **Archive, don't delete** - Preserve files for historical reference
+4. **Validate after** - Ensure framework still works after cleanup
+5. **Document rollback** - Clear instructions to undo if needed
+
+## Prerequisites
+
+- Story 3.17 complete (UTILITIES-AUDIT-REPORT.md exists)
+- List of DEPRECATED utilities from audit report
+- Git repository in clean state
+
+## Classification Review
+
+Before cleanup, verify utilities are truly deprecated:
+
+### ✅ SAFE TO ARCHIVE
+- No active code references (grep shows 0 results)
+- Classified as DEPRECATED in audit report
+- Obsolete concept or non-functional
+- Duplicate/refactored version exists
+
+### ⚠️ NEEDS REVIEW
+- Has active references in code (grep shows >0 results)
+- Classified as FIXABLE but needs deprecation
+- Unclear status from audit
+
+### ❌ DO NOT ARCHIVE
+- Classified as WORKING in audit report
+- Critical framework utility
+- Has active agent/task dependencies
+
+## Configuration Dependencies
+
+This task requires the following configuration keys from `core-config.yaml`:
+
+- **`devStoryLocation`**: Location of story files (typically docs/stories) - Required to access Story 3.17 audit results
+- **`core-config`**: Direct reference to core configuration file - This task updates the utility count in core-config.yaml
+- **`qaLocation`**: QA output directory (typically docs/qa) - Required to write quality reports
+
+**Loading Config:**
+```javascript
+const yaml = require('js-yaml');
+const fs = require('fs');
+const path = require('path');
+
+const configPath = path.join(__dirname, '../../.aios-core/core-config.yaml');
+const config = yaml.load(fs.readFileSync(configPath, 'utf8'));
+
+const devStoryLocation = config.devStoryLocation; // For accessing audit report
+const coreConfigPath = configPath; // For updating utility count
+const qaLocation = config.qa?.qaLocation || 'docs/qa'; // qaLocation
+```
+
+## Execution Steps
+
+### Step 1: Pre-Cleanup Preparation
+
+**1.1 Create Backup**
+```bash
+# Create timestamped backup of entire utils directory
+mkdir -p .backups
+cp -r .aios-core/utils ".backups/utils.backup-3.18-$(date +%Y%m%d-%H%M%S)"
+```
+
+**1.2 Verify Audit Report**
+```bash
+# Ensure audit report exists and is readable
+test -f UTILITIES-AUDIT-REPORT.md && echo "✅ Audit report found" || echo "❌ Audit report missing"
+```
+
+**1.3 Extract Deprecated List**
+
+From UTILITIES-AUDIT-REPORT.md, identify all utilities in:
+- Category A: Duplicate/Redundant Versions
+- Category B: Incomplete Experiments
+- Category C: Obsolete Concepts
+- Category D: Misplaced (move, don't archive)
+
+### Step 2: Dependency Verification (CRITICAL)
+
+For each deprecated utility, check for active references:
+
+**2.1 Automated Dependency Check**
+```bash
+# Check for require() statements
+grep -r "require.*utility-name" .aios-core/agents .aios-core/tasks .aios-core/workflows Squads/
+
+# Check for string references (utility mentioned in docs/configs)
+grep -r "utility-name" .aios-core/agents/ .aios-core/tasks/ .aios-core/core-config.yaml
+
+# Count total references
+count=$(grep -r "utility-name" .aios-core/ Squads/ 2>/dev/null | wc -l)
+echo "References found: $count"
+```
+
+**2.2 Manual Review**
+
+If references found (count > 0):
+- Review each reference context
+- Determine if reference is:
+  - Active usage (BLOCK removal)
+  - Comment/documentation (SAFE to remove)
+  - Obsolete reference (UPDATE then remove)
+
+**2.3 Create Exception List**
+
+Document utilities that cannot be archived due to dependencies:
+```markdown
+## Utilities with Active Dependencies
+
+1. utility-name.js
+   - References: 5 locations
+   - Reason: Still used by @agent-name
+   - Action: Defer until Story X.XX removes dependency
+```
+
+### Step 3: Create Archive Structure
+
+**3.1 Create Archive Directory**
+```bash
+mkdir -p .aios-core/utils-archive
+```
+
+**3.2 Create Archive README**
+
+Create `.aios-core/utils-archive/ARCHIVE-README.md`:
+
+```markdown
+# Archived Utilities - Story 3.18
+
+**Archive Date**: 2025-10-31
+**Story**: Epic 3c - Story 3.18 (Utilities Cleanup & Deprecation)
+**Audit Report**: UTILITIES-AUDIT-REPORT.md (Story 3.17)
+
+## Purpose
+
+This directory contains utilities that were deprecated and removed from active use during Epic 3 Phase 2. Files are preserved for historical reference and potential restoration.
+
+## Why Archive Instead of Delete?
+
+1. **Historical Reference** - Document what was tried and why it didn't work
+2. **Restoration Capability** - Enable future restoration if utility is needed
+3. **Audit Trail** - Maintain complete codebase history
+4. **Learning Resource** - Study patterns that didn't work out
+
+## Archive Categories
+
+### Category A: Duplicate/Redundant Versions (9 files)
+Utilities with `-refactored` or `-fixed` suffixes where original version works.
+
+### Category B: Incomplete Experiments (9 files)
+Partially implemented utilities that were abandoned before completion.
+
+### Category C: Obsolete Concepts (12 files)
+Utilities whose functionality is better handled by external tools or manual processes.
+
+### Category D: Misplaced Files (1 file)
+Test files that belong in `/tests` directory instead of `/utils`.
+
+## How to Restore a Utility
+
+If you need to restore an archived utility:
+
+1. **Copy file back**:
+   ```bash
+   cp .aios-core/utils-archive/utility-name.js .aios-core/scripts/
+   ```
+
+2. **Reinstall dependencies** (if needed):
+   ```bash
+   npm install missing-dependency
+   ```
+
+3. **Update references**:
+   - Add utility to agent dependencies if needed
+   - Update task workflows that use it
+   - Add to core-config.yaml registry
+
+4. **Test thoroughly**:
+   ```bash
+   node .aios-core/scripts/test-utilities.js
+   ```
+
+5. **Update Story 3.18**:
+   - Document which utility was restored and why
+   - Reclassify in audit report (DEPRECATED → WORKING/FIXABLE)
+
+## Archived Utilities
+
+Total: 28 files archived from 81 total utilities
+
+[Detailed list generated during cleanup]
+
+## Rollback Procedure
+
+If cleanup breaks something:
+
+**Immediate Rollback**:
+```bash
+rm -rf .aios-core/utils
+cp -r .backups/utils.backup-3.18-YYYYMMDD-HHMMSS .aios-core/utils
+```
+
+**Selective Restoration**:
+```bash
+cp .aios-core/utils-archive/specific-utility.js .aios-core/scripts/
+```
+
+---
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Autonomous decision making with logging
+- Minimal user interaction
+- **Best for:** Simple, deterministic tasks
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Explicit decision checkpoints
+- Educational explanations
+- **Best for:** Learning, complex decisions
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Task analysis phase (identify all ambiguities)
+- Zero ambiguity execution
+- **Best for:** Ambiguous requirements, critical work
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: cleanupUtilities()
+responsável: Dex (Builder)
+responsavel_type: Agente
+atomic_layer: Molecule
+
+**Entrada:**
+- campo: task
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Must be registered task
+
+- campo: parameters
+  tipo: object
+  origem: User Input
+  obrigatório: false
+  validação: Valid task parameters
+
+- campo: mode
+  tipo: string
+  origem: User Input
+  obrigatório: false
+  validação: yolo|interactive|pre-flight
+
+**Saída:**
+- campo: execution_result
+  tipo: object
+  destino: Memory
+  persistido: false
+
+- campo: logs
+  tipo: array
+  destino: File (.ai/logs/*)
+  persistido: true
+
+- campo: state
+  tipo: object
+  destino: State management
+  persistido: true
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Task is registered; required parameters provided; dependencies met
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check task is registered; required parameters provided; dependencies met
+    error_message: "Pre-condition failed: Task is registered; required parameters provided; dependencies met"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Task completed; exit code 0; expected outputs created
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify task completed; exit code 0; expected outputs created
+    error_message: "Post-condition failed: Task completed; exit code 0; expected outputs created"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Task completed as expected; side effects documented
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert task completed as expected; side effects documented
+    error_message: "Acceptance criterion not met: Task completed as expected; side effects documented"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** task-runner
+  - **Purpose:** Task execution and orchestration
+  - **Source:** .aios-core/core/task-runner.js
+
+- **Tool:** logger
+  - **Purpose:** Execution logging and error tracking
+  - **Source:** .aios-core/utils/logger.js
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** execute-task.js
+  - **Purpose:** Generic task execution wrapper
+  - **Language:** JavaScript
+  - **Location:** .aios-core/scripts/execute-task.js
+
+---
+
+## Error Handling
+
+**Strategy:** retry
+
+**Common Errors:**
+
+1. **Error:** Task Not Found
+   - **Cause:** Specified task not registered in system
+   - **Resolution:** Verify task name and registration
+   - **Recovery:** List available tasks, suggest similar
+
+2. **Error:** Invalid Parameters
+   - **Cause:** Task parameters do not match expected schema
+   - **Resolution:** Validate parameters against task definition
+   - **Recovery:** Provide parameter template, reject execution
+
+3. **Error:** Execution Timeout
+   - **Cause:** Task exceeds maximum execution time
+   - **Resolution:** Optimize task or increase timeout
+   - **Recovery:** Kill task, cleanup resources, log state
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 2-5 min (estimated)
+cost_estimated: $0.001-0.003
+token_usage: ~1,000-3,000 tokens
+```
+
+**Optimization Notes:**
+- Parallelize independent operations; reuse atom results; implement early exits
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - N/A
+tags:
+  - automation
+  - workflow
+updated_at: 2025-11-17
+```
+
+---
+
+*Generated during Story 3.18 - Epic 3c Phase 2*
+```
+
+### Step 4: Execute Cleanup
+
+**4.1 Archive Deprecated Utilities**
+
+For each utility in the deprecated list with 0 dependencies:
+
+```bash
+# Use git mv to preserve history
+git mv .aios-core/scripts/utility-name.js .aios-core/utils-archive/
+
+# Or for multiple files:
+git mv .aios-core/scripts/{aios-validator-fixed.js,aios-validator-refactored.js} .aios-core/utils-archive/
+```
+
+**4.2 Move Misplaced Files** (Category D)
+
+```bash
+# Create tests directory if it doesn't exist
+mkdir -p tests/utils
+
+# Move test files to proper location
+git mv .aios-core/scripts/aios-validator.test.js tests/utils/
+```
+
+**4.3 Update Archive README**
+
+Add complete list of archived files to ARCHIVE-README.md:
+
+```markdown
+## Archived Utilities
+
+### Category A: Duplicate/Redundant (9 files)
+1. aios-validator-fixed.js - Duplicate of aios-validator.js
+2. aios-validator-refactored.js - Duplicate of aios-validator.js
+...
+
+### Category B: Incomplete Experiments (9 files)
+1. change-propagation-predictor.js - 20% complete, no clear use case
+...
+
+### Category C: Obsolete Concepts (12 files)
+1. batch-creator.js - Batch processing not used
+...
+
+**Total Archived**: 30 files
+**Remaining Active**: 51 files
+```
+
+### Step 5: Update Documentation
+
+**5.1 Update core-config.yaml**
+
+Update utility count in `.aios-core/core-config.yaml`:
+
+```yaml
+framework:
+  entities:
+    utils:
+      count: 51  # Updated from 81
+      location: .aios-core/scripts/
+```
+
+**5.2 Add Changelog Entry**
+
+Add entry to Epic 3 changelog (or Story 3.18 change_log):
+
+```yaml
+- date: '2025-10-31'
+  version: 2.0.0
+  description: Utilities cleanup complete - 30 deprecated files archived
+  author: James (@dev)
+  changes:
+    - 'Archived 30 deprecated utilities (37% of total 81)'
+    - 'Created utils-archive/ with restoration documentation'
+    - 'Moved 1 test file to proper location'
+    - 'Updated core-config.yaml utility count: 81 → 51'
+    - 'Framework validation passed post-cleanup'
+    - 'All agents (@dev, @po, @qa) activate successfully'
+```
+
+**5.3 Update Developer Guides**
+
+If any developer guides reference archived utilities, update them:
+- Remove references to deprecated utilities
+- Update utility lists to reflect active utilities only
+- Add note about archived utilities location
+
+### Step 6: Validation (CRITICAL)
+
+**6.1 Framework Validation**
+
+Run framework validator to ensure no broken references:
+
+```bash
+node .aios-core/scripts/aios-validator.js
+```
+
+Expected: 0 errors related to missing utilities
+
+**6.2 Agent Activation Tests**
+
+Test that all core agents still activate:
+
+```bash
+# Test each agent manually or via script
+# @dev agent
+# @po agent
+# @qa agent
+```
+
+Expected: All agents load without errors
+
+**6.3 Grep Validation**
+
+Verify no broken references to archived utilities:
+
+```bash
+# Check for require() statements pointing to archived utilities
+for util in $(ls .aios-core/utils-archive/*.js); do
+  name=$(basename $util .js)
+  refs=$(grep -r "require.*$name" .aios-core/agents .aios-core/tasks 2>/dev/null | wc -l)
+  if [ $refs -gt 0 ]; then
+    echo "⚠️ Found $refs references to archived utility: $name"
+  fi
+done
+```
+
+Expected: 0 references to archived utilities
+
+**6.4 Test Utilities Scan**
+
+Re-run test-utilities.js to verify remaining utilities:
+
+```bash
+node .aios-core/scripts/test-utilities.js
+```
+
+Expected: Only active utilities tested, no errors loading utilities
+
+### Step 7: Create Rollback Documentation
+
+Document the exact rollback procedure in story completion notes:
+
+```markdown
+## Rollback Procedure
+
+**Backup Location**: `.backups/utils.backup-3.18-YYYYMMDD-HHMMSS`
+
+**Full Rollback**:
+```bash
+rm -rf .aios-core/utils
+cp -r .backups/utils.backup-3.18-YYYYMMDD-HHMMSS .aios-core/utils
+git checkout .aios-core/core-config.yaml
+```
+
+**Selective Restoration**:
+```bash
+cp .aios-core/utils-archive/utility-name.js .aios-core/scripts/
+```
+
+**Verification**:
+```bash
+node .aios-core/scripts/aios-validator.js
+```
+```
+
+## Output
+
+**Primary Deliverables**:
+1. `.aios-core/utils-archive/` - Archive directory with 30 deprecated utilities
+2. `.aios-core/utils-archive/ARCHIVE-README.md` - Archive documentation
+3. `.backups/utils.backup-3.18-YYYYMMDD-HHMMSS/` - Timestamped backup
+4. Updated `.aios-core/core-config.yaml` - Corrected utility count
+5. Updated story change_log - Cleanup completion entry
+
+**Expected Results**:
+- 30 utilities archived (37% of 81 total)
+- 51 utilities remain active (63% of total)
+- 1 test file moved to proper location
+- 0 broken references introduced
+- All agents activate successfully
+- Framework validation passes
+
+## Success Criteria
+
+- ✅ All 30 deprecated utilities archived without deletion
+- ✅ Zero broken references (grep validation passes)
+- ✅ Framework validation (aios-validator.js) passes
+- ✅ All agents (@dev, @po, @qa) activate successfully
+- ✅ Backup created before changes
+- ✅ Archive README created with restoration instructions
+- ✅ core-config.yaml updated accurately
+- ✅ Rollback procedure documented and tested
+- ✅ No utility references in agents point to archived utilities
+
+## Notes
+
+### Windows Compatibility
+- Use Git Bash for commands (git mv, grep, etc.)
+- Backup paths: `.backups/utils.backup-3.18-YYYYMMDD-HHMMSS`
+- Test on Windows 10/11 with Git for Windows
+
+### Safety Reminders
+- **NEVER** delete files, only archive
+- **ALWAYS** backup before making changes
+- **VERIFY** dependencies before archiving
+- **TEST** framework after cleanup
+- **DOCUMENT** rollback procedure
+
+### Integration with safe-removal-handler.js
+
+While this task can be executed manually following the steps above, the `safe-removal-handler.js` utility provides automated safety checks. For future cleanups, consider integrating with the handler for:
+- Automated dependency checking
+- Safety verification
+- Quarantine for uncertain utilities
+- Automated rollback capability
+
+For this cleanup, manual execution is preferred to maintain full control and visibility.
+
+## Estimated Time
+
+- Step 1-2: 1 hour (preparation + dependency checking)
+- Step 3: 30 minutes (archive structure)
+- Step 4: 1 hour (execution)
+- Step 5: 30 minutes (documentation)
+- Step 6: 1 hour (validation)
+- **Total**: 4 hours
+
+## Common Issues
+
+**Issue**: Git mv fails with "file not found"
+**Solution**: Verify file exists and path is correct, use forward slashes
+
+**Issue**: Grep shows false positives (references in comments)
+**Solution**: Manually review each reference, ignore comments/docs
+
+**Issue**: Agent activation fails after cleanup
+**Solution**: Check which utility is missing, restore from archive, investigate
+
+**Issue**: Validation script errors
+**Solution**: Rollback, identify which archived utility was needed, update audit classification