aios-core 2.1.6 → 2.2.1

package/.aios-core/development/tasks/sync-documentation.md

@@ -1,865 +1,865 @@
-# sync-documentation
-
-**Task ID:** `sync-documentation`  
-**Version:** 2.0.0  
-**Status:** Active
-
----
-
-## Purpose
-
-Automatically synchronize documentation with code changes to ensure documentation stays up-to-date with implementation.
-
----
-
-## 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`)
-
-**Valid values:** `yolo`, `interactive`, `preflight`
-
----
-
-## Task Definition (AIOS Task Format V1.0)
-
-```yaml
-task: syncDocumentation()
-responsável: Morgan (Strategist)
-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"
-```
-
----
-
-## Step-by-Step Execution
-
-### Step 1: Parse Parameters
-
-**Purpose:** Parse and validate command-line parameters
-
-**Actions:**
-1. Parse command-line options (--component, --all, --check, etc.)
-2. Validate sync strategies
-3. Set default values
-4. Validate file paths if provided
-
-**Validation:**
-- Parameters are valid
-- Strategies are supported
-- File paths exist (if specified)
-
----
-
-### Step 2: Initialize Dependencies
-
-**Purpose:** Set up documentation synchronizer and required tools
-
-**Actions:**
-1. Load DocumentationSynchronizer module
-2. Initialize synchronizer with root path
-3. Set up event listeners
-4. Verify all dependencies available
-
-**Validation:**
-- Synchronizer initialized successfully
-- Event listeners registered
-- Dependencies available
-
----
-
-### Step 3: Execute Requested Action
-
-**Purpose:** Execute the requested synchronization action
-
-**Actions:**
-1. Determine action type (check, sync, auto-sync, report)
-2. Execute corresponding method
-3. Handle errors gracefully
-4. Return results
-
-**Validation:**
-- Action executed successfully
-- Results returned
-- Errors handled appropriately
-
----
-
-## 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
-    rollback: false
-    error_message: "Post-condition failed: Task completed; exit code 0; expected outputs created"
-```
-
----
-
-## Acceptance Criteria
-
-**Purpose:** Validate story requirements AFTER workflow (non-blocking, can be manual)
-
-**Checklist:**
-
-```yaml
-acceptance-criteria:
-  - [ ] Task completed as expected; side effects documented
-    tipo: acceptance-criterion
-    blocker: false
-    story: N/A
-    manual_check: false
-    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)
-
-**Purpose:** Catalog reusable tools used by multiple agents
-
-```yaml
-**Tools:**
-- task-runner:
-    version: latest
-    used_for: Task execution and orchestration
-    shared_with: [dev, qa, po]
-    cost: $0
-
-- logger:
-    version: latest
-    used_for: Execution logging and error tracking
-    shared_with: [dev, qa, po, sm]
-    cost: $0
-```
-
----
-
-## Scripts (Agent-Specific)
-
-**Purpose:** Agent-specific code for this task
-
-```yaml
-**Scripts:**
-- execute-task.js:
-    description: Generic task execution wrapper
-    language: JavaScript
-    location: .aios-core/scripts/execute-task.js
-
-- documentation-synchronizer.js:
-    description: Core documentation synchronization engine
-    language: JavaScript
-    location: .aios-core/scripts/documentation-synchronizer.js
-```
-
----
-
-## Error Handling
-
-**Strategy:** fallback
-
-**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: STORY-6.1.7.2
-version: 2.0.0
-dependencies:
-  - N/A
-tags:
-  - automation
-  - workflow
-updated_at: 2025-01-17
-```
-
-## Command Pattern
-```
-*sync-documentation [options]
-```
-
-## Parameters
-- `options`: Documentation synchronization configuration
-
-### Options
-- `--component <path>`: Sync documentation for specific component
-- `--all`: Sync all registered components
-- `--check`: Check for out-of-sync documentation without updating
-- `--strategies <types>`: Comma-separated sync strategies (jsdoc,markdown,schema,api,examples)
-- `--auto-sync`: Enable automatic synchronization monitoring
-- `--report <file>`: Generate synchronization report
-- `--force`: Force synchronization even if up-to-date
-- `--interactive`: Interactive mode for reviewing changes
-
-## Examples
-```bash
-# Check documentation status
-*sync-documentation --check
-
-# Sync specific component
-*sync-documentation --component aios-core/scripts/pattern-learner.js
-
-# Sync all components with specific strategies
-*sync-documentation --all --strategies jsdoc,examples
-
-# Enable auto-sync monitoring
-*sync-documentation --auto-sync
-
-# Generate sync report
-*sync-documentation --report sync-report.json
-
-# Interactive sync review
-*sync-documentation --all --interactive
-```
-
-## Implementation
-
-```javascript
-const fs = require('fs').promises;
-const path = require('path');
-const chalk = require('chalk');
-const inquirer = require('inquirer');
-
-class SyncDocumentationTask {
-  constructor() {
-    this.taskName = 'sync-documentation';
-    this.description = 'Synchronize documentation with code changes';
-    this.rootPath = process.cwd();
-    this.documentationSynchronizer = null;
-    this.syncResults = [];
-  }
-
-  async execute(params) {
-    try {
-      console.log(chalk.blue('📚 AIOS Documentation Synchronization'));
-      console.log(chalk.gray('Keeping documentation in sync with code\n'));
-
-      // Parse parameters
-      const config = await this.parseParameters(params);
-      
-      // Initialize dependencies
-      await this.initializeDependencies();
-
-      // Execute requested action
-      let result;
-      
-      if (config.check) {
-        result = await this.checkSyncStatus(config);
-      } else if (config.autoSync) {
-        result = await this.enableAutoSync(config);
-      } else if (config.report) {
-        result = await this.generateReport(config.report);
-      } else if (config.component) {
-        result = await this.syncComponent(config.component, config);
-      } else if (config.all) {
-        result = await this.syncAllComponents(config);
-      } else {
-        // Default: show sync status
-        result = await this.showSyncStatus();
-      }
-
-      return {
-        success: true,
-        ...result
-      };
-
-    } catch (error) {
-      console.error(chalk.red(`\n❌ Documentation sync failed: ${error.message}`));
-      throw error;
-    }
-  }
-
-  async parseParameters(params) {
-    const config = {
-      component: null,
-      all: false,
-      check: false,
-      strategies: ['jsdoc', 'markdown', 'schema', 'api', 'examples'],
-      autoSync: false,
-      report: null,
-      force: false,
-      interactive: false
-    };
-
-    for (let i = 0; i < params.length; i++) {
-      const param = params[i];
-
-      if (param === '--all') {
-        config.all = true;
-      } else if (param === '--check') {
-        config.check = true;
-      } else if (param === '--auto-sync') {
-        config.autoSync = true;
-      } else if (param === '--force') {
-        config.force = true;
-      } else if (param === '--interactive') {
-        config.interactive = true;
-      } else if (param.startsWith('--component') && params[i + 1]) {
-        config.component = params[++i];
-      } else if (param.startsWith('--strategies') && params[i + 1]) {
-        config.strategies = params[++i].split(',').map(s => s.trim());
-      } else if (param.startsWith('--report') && params[i + 1]) {
-        config.report = params[++i];
-      }
-    }
-
-    // Validate strategies
-    const validStrategies = ['jsdoc', 'markdown', 'schema', 'api', 'examples'];
-    for (const strategy of config.strategies) {
-      if (!validStrategies.includes(strategy)) {
-        throw new Error(`Invalid sync strategy: ${strategy}`);
-      }
-    }
-
-    return config;
-  }
-
-  async initializeDependencies() {
-    try {
-      const DocumentationSynchronizer = require('../scripts/documentation-synchronizer');
-      this.documentationSynchronizer = new DocumentationSynchronizer({ 
-        rootPath: this.rootPath,
-        autoSync: false // We'll manage auto-sync manually
-      });
-
-      // Initialize synchronizer
-      await this.documentationSynchronizer.initialize();
-
-      // Listen to events
-      this.documentationSynchronizer.on('synchronized', (data) => {
-        this.syncResults.push(data);
-      });
-
-      this.documentationSynchronizer.on('error', (data) => {
-        console.error(chalk.red(`Sync error: ${data.error.message}`));
-      });
-
-    } catch (error) {
-      throw new Error(`Failed to initialize dependencies: ${error.message}`);
-    }
-  }
-
-  async checkSyncStatus(config) {
-    console.log(chalk.blue('🔍 Checking documentation sync status...\n'));
-
-    const components = this.documentationSynchronizer.syncedComponents;
-    const outOfSync = [];
-    const upToDate = [];
-
-    for (const [componentPath, component] of components) {
-      try {
-        const stats = await fs.stat(componentPath);
-        const lastModified = stats.mtime.toISOString();
-        
-        if (!component.lastSync || lastModified > component.lastSync) {
-          outOfSync.push({
-            component: componentPath,
-            doc: component.docPath,
-            lastModified,
-            lastSync: component.lastSync
-          });
-        } else {
-          upToDate.push({
-            component: componentPath,
-            doc: component.docPath
-          });
-        }
-      } catch (error) {
-        console.warn(chalk.yellow(`Cannot check: ${componentPath}`));
-      }
-    }
-
-    // Display results
-    if (outOfSync.length > 0) {
-      console.log(chalk.yellow(`📋 Out of sync (${outOfSync.length}):\n`));
-      
-      for (const item of outOfSync) {
-        console.log(chalk.red('  ⚠️ ') + path.relative(this.rootPath, item.component));
-        console.log(chalk.gray(`     Doc: ${path.relative(this.rootPath, item.doc)}`));
-        console.log(chalk.gray(`     Last modified: ${this.formatDate(item.lastModified)}`));
-        if (item.lastSync) {
-          console.log(chalk.gray(`     Last sync: ${this.formatDate(item.lastSync)}`));
-        } else {
-          console.log(chalk.gray(`     Last sync: Never`));
-        }
-        console.log('');
-      }
-    }
-
-    if (upToDate.length > 0) {
-      console.log(chalk.green(`✅ Up to date (${upToDate.length}):\n`));
-      
-      const shown = Math.min(5, upToDate.length);
-      for (let i = 0; i < shown; i++) {
-        const item = upToDate[i];
-        console.log(chalk.green('  ✓ ') + path.relative(this.rootPath, item.component));
-      }
-      
-      if (upToDate.length > shown) {
-        console.log(chalk.gray(`  ... and ${upToDate.length - shown} more`));
-      }
-    }
-
-    console.log(chalk.blue('\n📊 Summary:'));
-    console.log(`  Total components: ${components.size}`);
-    console.log(`  Out of sync: ${chalk.yellow(outOfSync.length)}`);
-    console.log(`  Up to date: ${chalk.green(upToDate.length)}`);
-
-    if (outOfSync.length > 0) {
-      console.log(chalk.yellow('\n💡 Run with --all to sync all out-of-date documentation'));
-    }
-
-    return {
-      totalComponents: components.size,
-      outOfSync: outOfSync.length,
-      upToDate: upToDate.length
-    };
-  }
-
-  async syncComponent(componentPath, config) {
-    const fullPath = path.resolve(this.rootPath, componentPath);
-    
-    console.log(chalk.blue(`🔄 Syncing documentation for: ${componentPath}\n`));
-
-    try {
-      const changes = await this.documentationSynchronizer.synchronizeComponent(fullPath, {
-        strategies: config.strategies,
-        force: config.force
-      });
-
-      if (changes.length === 0) {
-        console.log(chalk.green('✅ Documentation is already up to date'));
-        return { synced: 0 };
-      }
-
-      // Display changes
-      await this.displaySyncChanges(changes, config);
-
-      return {
-        synced: 1,
-        changes: changes.length
-      };
-
-    } catch (error) {
-      console.error(chalk.red(`Failed to sync: ${error.message}`));
-      return { synced: 0, error: error.message };
-    }
-  }
-
-  async syncAllComponents(config) {
-    const components = Array.from(this.documentationSynchronizer.syncedComponents.entries());
-    
-    console.log(chalk.blue(`🔄 Syncing ${components.length} components...\n`));
-
-    const results = {
-      synced: 0,
-      skipped: 0,
-      failed: 0,
-      totalChanges: 0
-    };
-
-    for (const [componentPath, component] of components) {
-      try {
-        // Check if needs sync
-        if (!config.force) {
-          const stats = await fs.stat(componentPath);
-          const lastModified = stats.mtime.toISOString();
-          
-          if (component.lastSync && lastModified <= component.lastSync) {
-            results.skipped++;
-            continue;
-          }
-        }
-
-        console.log(chalk.gray(`\nSyncing: ${path.relative(this.rootPath, componentPath)}`));
-        
-        const changes = await this.documentationSynchronizer.synchronizeComponent(componentPath, {
-          strategies: config.strategies
-        });
-
-        if (changes.length > 0) {
-          results.synced++;
-          results.totalChanges += changes.length;
-          
-          if (config.interactive) {
-            await this.displaySyncChanges(changes, config);
-          } else {
-            console.log(chalk.green(`  ✅ Applied ${changes.length} changes`));
-          }
-        } else {
-          results.skipped++;
-        }
-
-      } catch (error) {
-        results.failed++;
-        console.error(chalk.red(`  ❌ Failed: ${error.message}`));
-      }
-    }
-
-    // Display summary
-    console.log(chalk.blue('\n📊 Synchronization Summary:'));
-    console.log(chalk.green(`  ✅ Synced: ${results.synced}`));
-    console.log(chalk.gray(`  ⏭️  Skipped: ${results.skipped}`));
-    if (results.failed > 0) {
-      console.log(chalk.red(`  ❌ Failed: ${results.failed}`));
-    }
-    console.log(`  Total changes: ${results.totalChanges}`);
-
-    return results;
-  }
-
-  async displaySyncChanges(changes, config) {
-    console.log(chalk.blue('📝 Changes applied:\n'));
-
-    for (const strategyChanges of changes) {
-      if (!strategyChanges.success) {
-        console.log(chalk.red(`❌ ${strategyChanges.strategy}: ${strategyChanges.error}`));
-        continue;
-      }
-
-      console.log(chalk.yellow(`${strategyChanges.strategy}:`));
-      
-      for (const change of strategyChanges.changes) {
-        console.log(`  - ${change.description}`);
-        
-        if (config.interactive && change.type === 'updated') {
-          // Show diff preview
-          console.log(chalk.gray('    Preview of changes...'));
-        }
-      }
-    }
-  }
-
-  async enableAutoSync(config) {
-    console.log(chalk.blue('🔄 Enabling automatic documentation sync...\n'));
-
-    // Configure auto-sync
-    this.documentationSynchronizer.options.autoSync = true;
-    this.documentationSynchronizer.options.syncInterval = 60000; // 1 minute
-    
-    // Start auto-sync
-    await this.documentationSynchronizer.startAutoSync();
-
-    console.log(chalk.green('✅ Auto-sync enabled'));
-    console.log(chalk.gray('Documentation will be checked every minute for changes'));
-    console.log(chalk.gray('Press Ctrl+C to stop auto-sync'));
-
-    // Set up monitoring
-    this.documentationSynchronizer.on('auto-sync', (data) => {
-      if (data.changes.length > 0) {
-        console.log(chalk.blue(`\n[${this.formatTime(new Date())}] Auto-sync detected changes:`));
-        
-        for (const change of data.changes) {
-          console.log(`  - ${path.relative(this.rootPath, change.componentPath)}`);
-        }
-      }
-    });
-
-    // Keep process running
-    await new Promise((resolve) => {
-      process.on('SIGINT', () => {
-        console.log(chalk.yellow('\n\nStopping auto-sync...'));
-        this.documentationSynchronizer.stopAutoSync();
-        resolve();
-      });
-    });
-
-    return {
-      autoSyncEnabled: true
-    };
-  }
-
-  async generateReport(reportPath) {
-    console.log(chalk.blue('📊 Generating synchronization report...\n'));
-
-    const report = await this.documentationSynchronizer.generateSyncReport();
-    
-    // Add sync results
-    report.syncResults = this.syncResults;
-    
-    // Save report
-    await fs.writeFile(reportPath, JSON.stringify(report, null, 2));
-    
-    console.log(chalk.green(`✅ Report generated: ${reportPath}`));
-    
-    // Display summary
-    console.log(chalk.blue('\n📋 Report Summary:'));
-    console.log(`  Total components: ${report.summary.totalComponents}`);
-    console.log(`  Total documentation: ${report.summary.totalDocumentation}`);
-    console.log(`  Sync history entries: ${report.summary.syncHistory}`);
-    
-    if (report.summary.lastSync) {
-      console.log(`  Last sync: ${this.formatDate(report.summary.lastSync)}`);
-    }
-
-    return {
-      reportGenerated: true,
-      reportPath
-    };
-  }
-
-  async showSyncStatus() {
-    const components = this.documentationSynchronizer.syncedComponents;
-    const docs = this.documentationSynchronizer.documentationIndex;
-
-    console.log(chalk.blue('📚 Documentation Sync Status\n'));
-
-    console.log(chalk.gray('Registered components:'));
-    console.log(`  Components with docs: ${components.size}`);
-    console.log(`  Documentation files: ${docs.size}`);
-    
-    // Show sync strategies
-    console.log(chalk.gray('\nActive sync strategies:'));
-    for (const [name, strategy] of this.documentationSynchronizer.syncStrategies) {
-      console.log(`  - ${name}: ${strategy.description}`);
-    }
-
-    // Recent sync history
-    const history = this.documentationSynchronizer.syncHistory.slice(-5);
-    if (history.length > 0) {
-      console.log(chalk.gray('\nRecent synchronizations:'));
-      for (const entry of history) {
-        console.log(`  ${this.formatDate(entry.timestamp)} - ${path.basename(entry.componentPath)}`);
-      }
-    }
-
-    console.log(chalk.blue('\n📌 Commands:'));
-    console.log('  Check status: *sync-documentation --check');
-    console.log('  Sync all: *sync-documentation --all');
-    console.log('  Enable auto-sync: *sync-documentation --auto-sync');
-    console.log('  Generate report: *sync-documentation --report <file>');
-
-    return {
-      status: 'ready',
-      components: components.size,
-      documentation: docs.size
-    };
-  }
-
-  formatDate(dateString) {
-    const date = new Date(dateString);
-    const now = new Date();
-    const diff = now - date;
-    
-    // Less than 1 hour
-    if (diff < 3600000) {
-      const minutes = Math.floor(diff / 60000);
-      return `${minutes} minute${minutes !== 1 ? 's' : ''} ago`;
-    }
-    
-    // Less than 24 hours
-    if (diff < 86400000) {
-      const hours = Math.floor(diff / 3600000);
-      return `${hours} hour${hours !== 1 ? 's' : ''} ago`;
-    }
-    
-    // Less than 7 days
-    if (diff < 604800000) {
-      const days = Math.floor(diff / 86400000);
-      return `${days} day${days !== 1 ? 's' : ''} ago`;
-    }
-    
-    // Otherwise show date
-    return date.toLocaleDateString();
-  }
-
-  formatTime(date) {
-    return date.toLocaleTimeString();
-  }
-}
-
-module.exports = SyncDocumentationTask;
-```
-
-## Integration Points
-
-### Documentation Synchronizer
-- Core synchronization engine
-- Multi-strategy sync support
-- Automatic change detection
-- Real-time monitoring
-
-### Sync Strategies
-- **JSDoc**: Sync code comments with markdown
-- **Markdown**: Update documentation sections
-- **Schema**: Sync YAML/JSON schemas
-- **API**: Update API documentation
-- **Examples**: Validate and update code examples
-
-### Documentation Sources
-- Markdown files (.md)
-- YAML manifests (.yaml, .yml)
-- JSON schemas (.json)
-- README files
-- Inline documentation
-
-### Code Sources
-- JavaScript files (.js, .jsx)
-- TypeScript files (.ts, .tsx)
-- Task definitions
-- Agent manifests
-- Workflow configurations
-
-## Synchronization Workflow
-
-### Detection Phase
-1. Monitor file changes
-2. Identify linked documentation
-3. Detect content differences
-4. Calculate sync requirements
-5. Prioritize updates
-
-### Analysis Phase
-1. Parse code changes
-2. Extract documentation elements
-3. Compare with existing docs
-4. Identify gaps and conflicts
-5. Generate sync plan
-
-### Update Phase
-1. Apply sync strategies
-2. Update documentation files
-3. Preserve formatting
-4. Validate changes
-5. Record sync history
-
-## Best Practices
-
-### Documentation Structure
-- Keep docs near code
-- Use consistent naming
-- Link explicitly in docs
-- Maintain clear sections
-- Update examples regularly
-
-### Sync Configuration
-- Choose appropriate strategies
-- Set reasonable intervals
-- Review changes regularly
-- Monitor sync history
-- Handle conflicts gracefully
-
-### Quality Assurance
-- Validate after sync
-- Test code examples
-- Check API accuracy
-- Verify schema alignment
-- Maintain version history
-
-## Security Considerations
-- Validate file paths
-- Prevent injection in docs
-- Protect sensitive information
-- Audit sync operations
+# sync-documentation
+
+**Task ID:** `sync-documentation`  
+**Version:** 2.0.0  
+**Status:** Active
+
+---
+
+## Purpose
+
+Automatically synchronize documentation with code changes to ensure documentation stays up-to-date with implementation.
+
+---
+
+## 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`)
+
+**Valid values:** `yolo`, `interactive`, `preflight`
+
+---
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: syncDocumentation()
+responsável: Morgan (Strategist)
+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"
+```
+
+---
+
+## Step-by-Step Execution
+
+### Step 1: Parse Parameters
+
+**Purpose:** Parse and validate command-line parameters
+
+**Actions:**
+1. Parse command-line options (--component, --all, --check, etc.)
+2. Validate sync strategies
+3. Set default values
+4. Validate file paths if provided
+
+**Validation:**
+- Parameters are valid
+- Strategies are supported
+- File paths exist (if specified)
+
+---
+
+### Step 2: Initialize Dependencies
+
+**Purpose:** Set up documentation synchronizer and required tools
+
+**Actions:**
+1. Load DocumentationSynchronizer module
+2. Initialize synchronizer with root path
+3. Set up event listeners
+4. Verify all dependencies available
+
+**Validation:**
+- Synchronizer initialized successfully
+- Event listeners registered
+- Dependencies available
+
+---
+
+### Step 3: Execute Requested Action
+
+**Purpose:** Execute the requested synchronization action
+
+**Actions:**
+1. Determine action type (check, sync, auto-sync, report)
+2. Execute corresponding method
+3. Handle errors gracefully
+4. Return results
+
+**Validation:**
+- Action executed successfully
+- Results returned
+- Errors handled appropriately
+
+---
+
+## 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
+    rollback: false
+    error_message: "Post-condition failed: Task completed; exit code 0; expected outputs created"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Validate story requirements AFTER workflow (non-blocking, can be manual)
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Task completed as expected; side effects documented
+    tipo: acceptance-criterion
+    blocker: false
+    story: N/A
+    manual_check: false
+    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)
+
+**Purpose:** Catalog reusable tools used by multiple agents
+
+```yaml
+**Tools:**
+- task-runner:
+    version: latest
+    used_for: Task execution and orchestration
+    shared_with: [dev, qa, po]
+    cost: $0
+
+- logger:
+    version: latest
+    used_for: Execution logging and error tracking
+    shared_with: [dev, qa, po, sm]
+    cost: $0
+```
+
+---
+
+## Scripts (Agent-Specific)
+
+**Purpose:** Agent-specific code for this task
+
+```yaml
+**Scripts:**
+- execute-task.js:
+    description: Generic task execution wrapper
+    language: JavaScript
+    location: .aios-core/scripts/execute-task.js
+
+- documentation-synchronizer.js:
+    description: Core documentation synchronization engine
+    language: JavaScript
+    location: .aios-core/scripts/documentation-synchronizer.js
+```
+
+---
+
+## Error Handling
+
+**Strategy:** fallback
+
+**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: STORY-6.1.7.2
+version: 2.0.0
+dependencies:
+  - N/A
+tags:
+  - automation
+  - workflow
+updated_at: 2025-01-17
+```
+
+## Command Pattern
+```
+*sync-documentation [options]
+```
+
+## Parameters
+- `options`: Documentation synchronization configuration
+
+### Options
+- `--component <path>`: Sync documentation for specific component
+- `--all`: Sync all registered components
+- `--check`: Check for out-of-sync documentation without updating
+- `--strategies <types>`: Comma-separated sync strategies (jsdoc,markdown,schema,api,examples)
+- `--auto-sync`: Enable automatic synchronization monitoring
+- `--report <file>`: Generate synchronization report
+- `--force`: Force synchronization even if up-to-date
+- `--interactive`: Interactive mode for reviewing changes
+
+## Examples
+```bash
+# Check documentation status
+*sync-documentation --check
+
+# Sync specific component
+*sync-documentation --component aios-core/scripts/pattern-learner.js
+
+# Sync all components with specific strategies
+*sync-documentation --all --strategies jsdoc,examples
+
+# Enable auto-sync monitoring
+*sync-documentation --auto-sync
+
+# Generate sync report
+*sync-documentation --report sync-report.json
+
+# Interactive sync review
+*sync-documentation --all --interactive
+```
+
+## Implementation
+
+```javascript
+const fs = require('fs').promises;
+const path = require('path');
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+
+class SyncDocumentationTask {
+  constructor() {
+    this.taskName = 'sync-documentation';
+    this.description = 'Synchronize documentation with code changes';
+    this.rootPath = process.cwd();
+    this.documentationSynchronizer = null;
+    this.syncResults = [];
+  }
+
+  async execute(params) {
+    try {
+      console.log(chalk.blue('📚 AIOS Documentation Synchronization'));
+      console.log(chalk.gray('Keeping documentation in sync with code\n'));
+
+      // Parse parameters
+      const config = await this.parseParameters(params);
+      
+      // Initialize dependencies
+      await this.initializeDependencies();
+
+      // Execute requested action
+      let result;
+      
+      if (config.check) {
+        result = await this.checkSyncStatus(config);
+      } else if (config.autoSync) {
+        result = await this.enableAutoSync(config);
+      } else if (config.report) {
+        result = await this.generateReport(config.report);
+      } else if (config.component) {
+        result = await this.syncComponent(config.component, config);
+      } else if (config.all) {
+        result = await this.syncAllComponents(config);
+      } else {
+        // Default: show sync status
+        result = await this.showSyncStatus();
+      }
+
+      return {
+        success: true,
+        ...result
+      };
+
+    } catch (error) {
+      console.error(chalk.red(`\n❌ Documentation sync failed: ${error.message}`));
+      throw error;
+    }
+  }
+
+  async parseParameters(params) {
+    const config = {
+      component: null,
+      all: false,
+      check: false,
+      strategies: ['jsdoc', 'markdown', 'schema', 'api', 'examples'],
+      autoSync: false,
+      report: null,
+      force: false,
+      interactive: false
+    };
+
+    for (let i = 0; i < params.length; i++) {
+      const param = params[i];
+
+      if (param === '--all') {
+        config.all = true;
+      } else if (param === '--check') {
+        config.check = true;
+      } else if (param === '--auto-sync') {
+        config.autoSync = true;
+      } else if (param === '--force') {
+        config.force = true;
+      } else if (param === '--interactive') {
+        config.interactive = true;
+      } else if (param.startsWith('--component') && params[i + 1]) {
+        config.component = params[++i];
+      } else if (param.startsWith('--strategies') && params[i + 1]) {
+        config.strategies = params[++i].split(',').map(s => s.trim());
+      } else if (param.startsWith('--report') && params[i + 1]) {
+        config.report = params[++i];
+      }
+    }
+
+    // Validate strategies
+    const validStrategies = ['jsdoc', 'markdown', 'schema', 'api', 'examples'];
+    for (const strategy of config.strategies) {
+      if (!validStrategies.includes(strategy)) {
+        throw new Error(`Invalid sync strategy: ${strategy}`);
+      }
+    }
+
+    return config;
+  }
+
+  async initializeDependencies() {
+    try {
+      const DocumentationSynchronizer = require('../scripts/documentation-synchronizer');
+      this.documentationSynchronizer = new DocumentationSynchronizer({ 
+        rootPath: this.rootPath,
+        autoSync: false // We'll manage auto-sync manually
+      });
+
+      // Initialize synchronizer
+      await this.documentationSynchronizer.initialize();
+
+      // Listen to events
+      this.documentationSynchronizer.on('synchronized', (data) => {
+        this.syncResults.push(data);
+      });
+
+      this.documentationSynchronizer.on('error', (data) => {
+        console.error(chalk.red(`Sync error: ${data.error.message}`));
+      });
+
+    } catch (error) {
+      throw new Error(`Failed to initialize dependencies: ${error.message}`);
+    }
+  }
+
+  async checkSyncStatus(config) {
+    console.log(chalk.blue('🔍 Checking documentation sync status...\n'));
+
+    const components = this.documentationSynchronizer.syncedComponents;
+    const outOfSync = [];
+    const upToDate = [];
+
+    for (const [componentPath, component] of components) {
+      try {
+        const stats = await fs.stat(componentPath);
+        const lastModified = stats.mtime.toISOString();
+        
+        if (!component.lastSync || lastModified > component.lastSync) {
+          outOfSync.push({
+            component: componentPath,
+            doc: component.docPath,
+            lastModified,
+            lastSync: component.lastSync
+          });
+        } else {
+          upToDate.push({
+            component: componentPath,
+            doc: component.docPath
+          });
+        }
+      } catch (error) {
+        console.warn(chalk.yellow(`Cannot check: ${componentPath}`));
+      }
+    }
+
+    // Display results
+    if (outOfSync.length > 0) {
+      console.log(chalk.yellow(`📋 Out of sync (${outOfSync.length}):\n`));
+      
+      for (const item of outOfSync) {
+        console.log(chalk.red('  ⚠️ ') + path.relative(this.rootPath, item.component));
+        console.log(chalk.gray(`     Doc: ${path.relative(this.rootPath, item.doc)}`));
+        console.log(chalk.gray(`     Last modified: ${this.formatDate(item.lastModified)}`));
+        if (item.lastSync) {
+          console.log(chalk.gray(`     Last sync: ${this.formatDate(item.lastSync)}`));
+        } else {
+          console.log(chalk.gray(`     Last sync: Never`));
+        }
+        console.log('');
+      }
+    }
+
+    if (upToDate.length > 0) {
+      console.log(chalk.green(`✅ Up to date (${upToDate.length}):\n`));
+      
+      const shown = Math.min(5, upToDate.length);
+      for (let i = 0; i < shown; i++) {
+        const item = upToDate[i];
+        console.log(chalk.green('  ✓ ') + path.relative(this.rootPath, item.component));
+      }
+      
+      if (upToDate.length > shown) {
+        console.log(chalk.gray(`  ... and ${upToDate.length - shown} more`));
+      }
+    }
+
+    console.log(chalk.blue('\n📊 Summary:'));
+    console.log(`  Total components: ${components.size}`);
+    console.log(`  Out of sync: ${chalk.yellow(outOfSync.length)}`);
+    console.log(`  Up to date: ${chalk.green(upToDate.length)}`);
+
+    if (outOfSync.length > 0) {
+      console.log(chalk.yellow('\n💡 Run with --all to sync all out-of-date documentation'));
+    }
+
+    return {
+      totalComponents: components.size,
+      outOfSync: outOfSync.length,
+      upToDate: upToDate.length
+    };
+  }
+
+  async syncComponent(componentPath, config) {
+    const fullPath = path.resolve(this.rootPath, componentPath);
+    
+    console.log(chalk.blue(`🔄 Syncing documentation for: ${componentPath}\n`));
+
+    try {
+      const changes = await this.documentationSynchronizer.synchronizeComponent(fullPath, {
+        strategies: config.strategies,
+        force: config.force
+      });
+
+      if (changes.length === 0) {
+        console.log(chalk.green('✅ Documentation is already up to date'));
+        return { synced: 0 };
+      }
+
+      // Display changes
+      await this.displaySyncChanges(changes, config);
+
+      return {
+        synced: 1,
+        changes: changes.length
+      };
+
+    } catch (error) {
+      console.error(chalk.red(`Failed to sync: ${error.message}`));
+      return { synced: 0, error: error.message };
+    }
+  }
+
+  async syncAllComponents(config) {
+    const components = Array.from(this.documentationSynchronizer.syncedComponents.entries());
+    
+    console.log(chalk.blue(`🔄 Syncing ${components.length} components...\n`));
+
+    const results = {
+      synced: 0,
+      skipped: 0,
+      failed: 0,
+      totalChanges: 0
+    };
+
+    for (const [componentPath, component] of components) {
+      try {
+        // Check if needs sync
+        if (!config.force) {
+          const stats = await fs.stat(componentPath);
+          const lastModified = stats.mtime.toISOString();
+          
+          if (component.lastSync && lastModified <= component.lastSync) {
+            results.skipped++;
+            continue;
+          }
+        }
+
+        console.log(chalk.gray(`\nSyncing: ${path.relative(this.rootPath, componentPath)}`));
+        
+        const changes = await this.documentationSynchronizer.synchronizeComponent(componentPath, {
+          strategies: config.strategies
+        });
+
+        if (changes.length > 0) {
+          results.synced++;
+          results.totalChanges += changes.length;
+          
+          if (config.interactive) {
+            await this.displaySyncChanges(changes, config);
+          } else {
+            console.log(chalk.green(`  ✅ Applied ${changes.length} changes`));
+          }
+        } else {
+          results.skipped++;
+        }
+
+      } catch (error) {
+        results.failed++;
+        console.error(chalk.red(`  ❌ Failed: ${error.message}`));
+      }
+    }
+
+    // Display summary
+    console.log(chalk.blue('\n📊 Synchronization Summary:'));
+    console.log(chalk.green(`  ✅ Synced: ${results.synced}`));
+    console.log(chalk.gray(`  ⏭️  Skipped: ${results.skipped}`));
+    if (results.failed > 0) {
+      console.log(chalk.red(`  ❌ Failed: ${results.failed}`));
+    }
+    console.log(`  Total changes: ${results.totalChanges}`);
+
+    return results;
+  }
+
+  async displaySyncChanges(changes, config) {
+    console.log(chalk.blue('📝 Changes applied:\n'));
+
+    for (const strategyChanges of changes) {
+      if (!strategyChanges.success) {
+        console.log(chalk.red(`❌ ${strategyChanges.strategy}: ${strategyChanges.error}`));
+        continue;
+      }
+
+      console.log(chalk.yellow(`${strategyChanges.strategy}:`));
+      
+      for (const change of strategyChanges.changes) {
+        console.log(`  - ${change.description}`);
+        
+        if (config.interactive && change.type === 'updated') {
+          // Show diff preview
+          console.log(chalk.gray('    Preview of changes...'));
+        }
+      }
+    }
+  }
+
+  async enableAutoSync(config) {
+    console.log(chalk.blue('🔄 Enabling automatic documentation sync...\n'));
+
+    // Configure auto-sync
+    this.documentationSynchronizer.options.autoSync = true;
+    this.documentationSynchronizer.options.syncInterval = 60000; // 1 minute
+    
+    // Start auto-sync
+    await this.documentationSynchronizer.startAutoSync();
+
+    console.log(chalk.green('✅ Auto-sync enabled'));
+    console.log(chalk.gray('Documentation will be checked every minute for changes'));
+    console.log(chalk.gray('Press Ctrl+C to stop auto-sync'));
+
+    // Set up monitoring
+    this.documentationSynchronizer.on('auto-sync', (data) => {
+      if (data.changes.length > 0) {
+        console.log(chalk.blue(`\n[${this.formatTime(new Date())}] Auto-sync detected changes:`));
+        
+        for (const change of data.changes) {
+          console.log(`  - ${path.relative(this.rootPath, change.componentPath)}`);
+        }
+      }
+    });
+
+    // Keep process running
+    await new Promise((resolve) => {
+      process.on('SIGINT', () => {
+        console.log(chalk.yellow('\n\nStopping auto-sync...'));
+        this.documentationSynchronizer.stopAutoSync();
+        resolve();
+      });
+    });
+
+    return {
+      autoSyncEnabled: true
+    };
+  }
+
+  async generateReport(reportPath) {
+    console.log(chalk.blue('📊 Generating synchronization report...\n'));
+
+    const report = await this.documentationSynchronizer.generateSyncReport();
+    
+    // Add sync results
+    report.syncResults = this.syncResults;
+    
+    // Save report
+    await fs.writeFile(reportPath, JSON.stringify(report, null, 2));
+    
+    console.log(chalk.green(`✅ Report generated: ${reportPath}`));
+    
+    // Display summary
+    console.log(chalk.blue('\n📋 Report Summary:'));
+    console.log(`  Total components: ${report.summary.totalComponents}`);
+    console.log(`  Total documentation: ${report.summary.totalDocumentation}`);
+    console.log(`  Sync history entries: ${report.summary.syncHistory}`);
+    
+    if (report.summary.lastSync) {
+      console.log(`  Last sync: ${this.formatDate(report.summary.lastSync)}`);
+    }
+
+    return {
+      reportGenerated: true,
+      reportPath
+    };
+  }
+
+  async showSyncStatus() {
+    const components = this.documentationSynchronizer.syncedComponents;
+    const docs = this.documentationSynchronizer.documentationIndex;
+
+    console.log(chalk.blue('📚 Documentation Sync Status\n'));
+
+    console.log(chalk.gray('Registered components:'));
+    console.log(`  Components with docs: ${components.size}`);
+    console.log(`  Documentation files: ${docs.size}`);
+    
+    // Show sync strategies
+    console.log(chalk.gray('\nActive sync strategies:'));
+    for (const [name, strategy] of this.documentationSynchronizer.syncStrategies) {
+      console.log(`  - ${name}: ${strategy.description}`);
+    }
+
+    // Recent sync history
+    const history = this.documentationSynchronizer.syncHistory.slice(-5);
+    if (history.length > 0) {
+      console.log(chalk.gray('\nRecent synchronizations:'));
+      for (const entry of history) {
+        console.log(`  ${this.formatDate(entry.timestamp)} - ${path.basename(entry.componentPath)}`);
+      }
+    }
+
+    console.log(chalk.blue('\n📌 Commands:'));
+    console.log('  Check status: *sync-documentation --check');
+    console.log('  Sync all: *sync-documentation --all');
+    console.log('  Enable auto-sync: *sync-documentation --auto-sync');
+    console.log('  Generate report: *sync-documentation --report <file>');
+
+    return {
+      status: 'ready',
+      components: components.size,
+      documentation: docs.size
+    };
+  }
+
+  formatDate(dateString) {
+    const date = new Date(dateString);
+    const now = new Date();
+    const diff = now - date;
+    
+    // Less than 1 hour
+    if (diff < 3600000) {
+      const minutes = Math.floor(diff / 60000);
+      return `${minutes} minute${minutes !== 1 ? 's' : ''} ago`;
+    }
+    
+    // Less than 24 hours
+    if (diff < 86400000) {
+      const hours = Math.floor(diff / 3600000);
+      return `${hours} hour${hours !== 1 ? 's' : ''} ago`;
+    }
+    
+    // Less than 7 days
+    if (diff < 604800000) {
+      const days = Math.floor(diff / 86400000);
+      return `${days} day${days !== 1 ? 's' : ''} ago`;
+    }
+    
+    // Otherwise show date
+    return date.toLocaleDateString();
+  }
+
+  formatTime(date) {
+    return date.toLocaleTimeString();
+  }
+}
+
+module.exports = SyncDocumentationTask;
+```
+
+## Integration Points
+
+### Documentation Synchronizer
+- Core synchronization engine
+- Multi-strategy sync support
+- Automatic change detection
+- Real-time monitoring
+
+### Sync Strategies
+- **JSDoc**: Sync code comments with markdown
+- **Markdown**: Update documentation sections
+- **Schema**: Sync YAML/JSON schemas
+- **API**: Update API documentation
+- **Examples**: Validate and update code examples
+
+### Documentation Sources
+- Markdown files (.md)
+- YAML manifests (.yaml, .yml)
+- JSON schemas (.json)
+- README files
+- Inline documentation
+
+### Code Sources
+- JavaScript files (.js, .jsx)
+- TypeScript files (.ts, .tsx)
+- Task definitions
+- Agent manifests
+- Workflow configurations
+
+## Synchronization Workflow
+
+### Detection Phase
+1. Monitor file changes
+2. Identify linked documentation
+3. Detect content differences
+4. Calculate sync requirements
+5. Prioritize updates
+
+### Analysis Phase
+1. Parse code changes
+2. Extract documentation elements
+3. Compare with existing docs
+4. Identify gaps and conflicts
+5. Generate sync plan
+
+### Update Phase
+1. Apply sync strategies
+2. Update documentation files
+3. Preserve formatting
+4. Validate changes
+5. Record sync history
+
+## Best Practices
+
+### Documentation Structure
+- Keep docs near code
+- Use consistent naming
+- Link explicitly in docs
+- Maintain clear sections
+- Update examples regularly
+
+### Sync Configuration
+- Choose appropriate strategies
+- Set reasonable intervals
+- Review changes regularly
+- Monitor sync history
+- Handle conflicts gracefully
+
+### Quality Assurance
+- Validate after sync
+- Test code examples
+- Check API accuracy
+- Verify schema alignment
+- Maintain version history
+
+## Security Considerations
+- Validate file paths
+- Prevent injection in docs
+- Protect sensitive information
+- Audit sync operations
 - Control write permissions