aios-core 2.1.5 → 2.2.0

package/.aios-core/development/tasks/propose-modification.md

@@ -1,843 +1,843 @@
----
-
-## 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: proposeModification()
-responsável: Atlas (Decoder)
-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
-```
-
----
-
-checklists:
-  - change-checklist.md
----
-
-# Propose Modification - AIOS Developer Task
-
-## Purpose
-Create and submit modification proposals for collaborative review and approval within the AIOS-FULLSTACK framework.
-
-## Command Pattern
-```
-*propose-modification <component-path> <modification-type> [options]
-```
-
-## Parameters
-- `component-path`: Path to the component to modify
-- `modification-type`: Type of modification (modify, refactor, deprecate, enhance)
-- `options`: Additional proposal configuration
-
-### Options
-- `--title <title>`: Title for the proposal
-- `--description <desc>`: Detailed description of changes
-- `--priority <level>`: Priority level (low, medium, high, critical)
-- `--tags <tags>`: Comma-separated tags for categorization
-- `--assignees <users>`: Comma-separated list of reviewers
-- `--draft`: Create as draft proposal
-- `--link-issues <ids>`: Link related issues or tasks
-- `--impact-analysis`: Include impact analysis report
-- `--test-results`: Attach test results
-
-## Examples
-```bash
-# Propose agent enhancement
-*propose-modification aios-core/agents/weather-agent.md enhance --title "Add caching support" --description "Implement response caching to reduce API calls" --priority medium
-
-# Propose critical refactoring with impact analysis
-*propose-modification aios-core/scripts/core-utility.js refactor --title "Optimize performance" --priority critical --impact-analysis --assignees "alice,bob"
-
-# Create draft proposal for workflow deprecation
-*propose-modification aios-core/workflows/legacy-workflow.yaml deprecate --draft --title "Deprecate legacy workflow" --link-issues "123,456"
-```
-
-## Implementation
-
-```javascript
-const fs = require('fs').promises;
-const path = require('path');
-const chalk = require('chalk');
-const inquirer = require('inquirer');
-
-class ProposeModificationTask {
-  constructor() {
-    this.taskName = 'propose-modification';
-    this.description = 'Create modification proposals for collaborative review';
-    this.rootPath = process.cwd();
-    this.proposalSystem = null;
-    this.impactAnalyzer = null;
-    this.notificationService = null;
-  }
-
-  async execute(params) {
-    try {
-      console.log(chalk.blue('📝 AIOS Modification Proposal'));
-      console.log(chalk.gray('Creating collaborative modification proposal\n'));
-
-      // Parse and validate parameters
-      const config = await this.parseParameters(params);
-      
-      // Initialize dependencies
-      await this.initializeDependencies();
-
-      // Validate target component
-      const component = await this.validateComponent(config.componentPath);
-
-      // Create proposal
-      console.log(chalk.gray('Creating modification proposal...'));
-      const proposal = await this.createProposal(component, config);
-
-      // Run impact analysis if requested
-      if (config.includeImpactAnalysis) {
-        console.log(chalk.gray('Running impact analysis...'));
-        proposal.impactAnalysis = await this.runImpactAnalysis(component, config);
-      }
-
-      // Attach test results if provided
-      if (config.testResults) {
-        console.log(chalk.gray('Attaching test results...'));
-        proposal.testResults = await this.attachTestResults(config.testResults);
-      }
-
-      // Get proposal details from user
-      const details = await this.getProposalDetails(proposal, config);
-      Object.assign(proposal, details);
-
-      // Submit proposal
-      console.log(chalk.gray('Submitting proposal...'));
-      const result = await this.submitProposal(proposal, config);
-
-      // Notify assignees
-      if (config.assignees.length > 0) {
-        await this.notifyAssignees(result, config.assignees);
-      }
-
-      // Display success
-      console.log(chalk.green('\n✅ Modification proposal created successfully'));
-      console.log(chalk.gray(`   Proposal ID: ${result.proposalId}`));
-      console.log(chalk.gray(`   Status: ${result.status}`));
-      console.log(chalk.gray(`   Reviewers: ${config.assignees.join(', ') || 'None assigned'}`));
-      
-      if (result.webUrl) {
-        console.log(chalk.blue(`   View proposal: ${result.webUrl}`));
-      }
-
-      return {
-        success: true,
-        proposalId: result.proposalId,
-        status: result.status,
-        component: component.path,
-        modificationType: config.modificationType,
-        priority: config.priority,
-        assignees: config.assignees
-      };
-
-    } catch (error) {
-      console.error(chalk.red(`\n❌ Proposal creation failed: ${error.message}`));
-      throw error;
-    }
-  }
-
-  async parseParameters(params) {
-    if (params.length < 2) {
-      throw new Error('Usage: *propose-modification <component-path> <modification-type> [options]');
-    }
-
-    const config = {
-      componentPath: params[0],
-      modificationType: params[1],
-      title: '',
-      description: '',
-      priority: 'medium',
-      tags: [],
-      assignees: [],
-      isDraft: false,
-      linkedIssues: [],
-      includeImpactAnalysis: false,
-      testResults: null
-    };
-
-    // Validate modification type
-    const validTypes = ['modify', 'refactor', 'deprecate', 'enhance'];
-    if (!validTypes.includes(config.modificationType)) {
-      throw new Error(`Invalid modification type: ${config.modificationType}. Must be one of: ${validTypes.join(', ')}`);
-    }
-
-    // Parse options
-    for (let i = 2; i < params.length; i++) {
-      const param = params[i];
-      
-      if (param === '--draft') {
-        config.isDraft = true;
-      } else if (param === '--impact-analysis') {
-        config.includeImpactAnalysis = true;
-      } else if (param.startsWith('--title') && params[i + 1]) {
-        config.title = params[++i];
-      } else if (param.startsWith('--description') && params[i + 1]) {
-        config.description = params[++i];
-      } else if (param.startsWith('--priority') && params[i + 1]) {
-        config.priority = params[++i];
-      } else if (param.startsWith('--tags') && params[i + 1]) {
-        config.tags = params[++i].split(',').map(t => t.trim());
-      } else if (param.startsWith('--assignees') && params[i + 1]) {
-        config.assignees = params[++i].split(',').map(a => a.trim());
-      } else if (param.startsWith('--link-issues') && params[i + 1]) {
-        config.linkedIssues = params[++i].split(',').map(id => id.trim());
-      } else if (param.startsWith('--test-results') && params[i + 1]) {
-        config.testResults = params[++i];
-      }
-    }
-
-    // Validate priority
-    const validPriorities = ['low', 'medium', 'high', 'critical'];
-    if (!validPriorities.includes(config.priority)) {
-      throw new Error(`Invalid priority: ${config.priority}. Must be one of: ${validPriorities.join(', ')}`);
-    }
-
-    return config;
-  }
-
-  async initializeDependencies() {
-    try {
-      const ProposalSystem = require('../scripts/proposal-system');
-      this.proposalSystem = new ProposalSystem({ rootPath: this.rootPath });
-
-      const ImpactAnalyzer = require('../scripts/dependency-impact-analyzer');
-      this.impactAnalyzer = new ImpactAnalyzer({ rootPath: this.rootPath });
-
-      const NotificationService = require('../scripts/notification-service');
-      this.notificationService = new NotificationService({ rootPath: this.rootPath });
-
-    } catch (error) {
-      throw new Error(`Failed to initialize dependencies: ${error.message}`);
-    }
-  }
-
-  async validateComponent(componentPath) {
-    const fullPath = path.resolve(this.rootPath, componentPath);
-    
-    try {
-      const stats = await fs.stat(fullPath);
-      if (!stats.isFile()) {
-        throw new Error(`Not a file: ${componentPath}`);
-      }
-
-      const content = await fs.readFile(fullPath, 'utf-8');
-      const componentType = this.determineComponentType(fullPath, content);
-
-      return {
-        path: componentPath,
-        fullPath: fullPath,
-        type: componentType,
-        content: content,
-        lastModified: stats.mtime
-      };
-
-    } catch (error) {
-      if (error.code === 'ENOENT') {
-        throw new Error(`Component not found: ${componentPath}`);
-      }
-      throw error;
-    }
-  }
-
-  async createProposal(component, config) {
-    const proposal = {
-      proposalId: `proposal-${Date.now()}-${Math.random().toString(36).substr(2, 6)}`,
-      componentPath: component.path,
-      componentType: component.type,
-      modificationType: config.modificationType,
-      title: config.title || `${config.modificationType} ${component.path}`,
-      description: config.description,
-      priority: config.priority,
-      status: config.isDraft ? 'draft' : 'pending_review',
-      tags: config.tags,
-      assignees: config.assignees,
-      linkedIssues: config.linkedIssues,
-      metadata: {
-        createdBy: process.env.USER || 'aios-developer',
-        createdAt: new Date().toISOString(),
-        lastModified: new Date().toISOString(),
-        version: 1
-      }
-    };
-
-    // Add modification type specific fields
-    switch (config.modificationType) {
-      case 'deprecate':
-        proposal.deprecationInfo = {
-          targetRemovalDate: null,
-          migrationPath: null,
-          affectedComponents: []
-        };
-        break;
-      case 'enhance':
-        proposal.enhancementInfo = {
-          newCapabilities: [],
-          performanceImpact: null,
-          backwardCompatible: true
-        };
-        break;
-      case 'refactor':
-        proposal.refactorInfo = {
-          scope: 'component', // component, module, system
-          breakingChanges: false,
-          codeQualityMetrics: {}
-        };
-        break;
-    }
-
-    return proposal;
-  }
-
-  async runImpactAnalysis(component, config) {
-    try {
-      const impact = await this.impactAnalyzer.analyzeDependencyImpact(component, {
-        modificationType: config.modificationType,
-        depth: 'deep'
-      });
-
-      return {
-        affectedComponents: impact.affectedComponents.length,
-        criticalDependencies: impact.impactCategories?.critical || [],
-        riskLevel: this.calculateRiskLevel(impact),
-        summary: this.generateImpactSummary(impact)
-      };
-
-    } catch (error) {
-      console.warn(chalk.yellow(`Impact analysis failed: ${error.message}`));
-      return null;
-    }
-  }
-
-  async attachTestResults(testResultsPath) {
-    try {
-      const content = await fs.readFile(testResultsPath, 'utf-8');
-      return {
-        source: testResultsPath,
-        content: content,
-        attachedAt: new Date().toISOString()
-      };
-    } catch (error) {
-      console.warn(chalk.yellow(`Failed to attach test results: ${error.message}`));
-      return null;
-    }
-  }
-
-  async getProposalDetails(proposal, config) {
-    const questions = [];
-
-    // Title if not provided
-    if (!config.title) {
-      questions.push({
-        type: 'input',
-        name: 'title',
-        message: 'Proposal title:',
-        default: proposal.title,
-        validate: input => input.length > 0 || 'Title is required'
-      });
-    }
-
-    // Description if not provided
-    if (!config.description) {
-      questions.push({
-        type: 'editor',
-        name: 'description',
-        message: 'Detailed description (opens editor):',
-        default: this.getDescriptionTemplate(config.modificationType)
-      });
-    }
-
-    // Modification-specific questions
-    if (config.modificationType === 'deprecate') {
-      questions.push({
-        type: 'input',
-        name: 'targetRemovalDate',
-        message: 'Target removal date (YYYY-MM-DD):',
-        validate: input => {
-          if (!input) return true;
-          return /^\d{4}-\d{2}-\d{2}$/.test(input) || 'Invalid date format';
-        }
-      });
-    }
-
-    if (config.modificationType === 'enhance') {
-      questions.push({
-        type: 'checkbox',
-        name: 'newCapabilities',
-        message: 'Select new capabilities:',
-        choices: [
-          'Performance optimization',
-          'New API endpoints',
-          'Additional configuration options',
-          'Extended error handling',
-          'Improved logging',
-          'New integrations',
-          'Other'
-        ]
-      });
-    }
-
-    if (config.modificationType === 'refactor') {
-      questions.push({
-        type: 'confirm',
-        name: 'breakingChanges',
-        message: 'Will this refactoring introduce breaking changes?',
-        default: false
-      });
-    }
-
-    // Review timeline
-    questions.push({
-      type: 'list',
-      name: 'reviewTimeline',
-      message: 'Expected review timeline:',
-      choices: [
-        { name: 'Urgent (1-2 days)', value: 'urgent' },
-        { name: 'Normal (3-5 days)', value: 'normal' },
-        { name: 'Low priority (1 week+)', value: 'low' }
-      ],
-      default: 'normal'
-    });
-
-    const answers = await inquirer.prompt(questions);
-
-    // Process answers
-    const details = {
-      title: answers.title || config.title,
-      description: answers.description || config.description,
-      reviewTimeline: answers.reviewTimeline
-    };
-
-    // Add modification-specific details
-    if (config.modificationType === 'deprecate' && answers.targetRemovalDate) {
-      details.deprecationInfo = {
-        targetRemovalDate: answers.targetRemovalDate
-      };
-    }
-
-    if (config.modificationType === 'enhance' && answers.newCapabilities) {
-      details.enhancementInfo = {
-        newCapabilities: answers.newCapabilities
-      };
-    }
-
-    if (config.modificationType === 'refactor') {
-      details.refactorInfo = {
-        breakingChanges: answers.breakingChanges
-      };
-    }
-
-    return details;
-  }
-
-  async submitProposal(proposal, config) {
-    try {
-      // Submit through proposal system
-      const result = await this.proposalSystem.submitProposal(proposal);
-
-      // Store in memory/database
-      await this.storeProposal(proposal, result);
-
-      return {
-        proposalId: proposal.proposalId,
-        status: proposal.status,
-        webUrl: this.generateProposalUrl(proposal.proposalId),
-        createdAt: proposal.metadata.createdAt
-      };
-
-    } catch (error) {
-      throw new Error(`Failed to submit proposal: ${error.message}`);
-    }
-  }
-
-  async storeProposal(proposal, result) {
-    const proposalsDir = path.join(this.rootPath, '.aios', 'proposals');
-    await fs.mkdir(proposalsDir, { recursive: true });
-
-    const proposalFile = path.join(proposalsDir, `${proposal.proposalId}.json`);
-    await fs.writeFile(proposalFile, JSON.stringify(proposal, null, 2));
-
-    // Update proposals index
-    const indexFile = path.join(proposalsDir, 'index.json');
-    let index = { proposals: [] };
-    
-    try {
-      const existing = await fs.readFile(indexFile, 'utf-8');
-      index = JSON.parse(existing);
-    } catch (error) {
-      // Index doesn't exist yet
-    }
-
-    index.proposals.push({
-      proposalId: proposal.proposalId,
-      title: proposal.title,
-      componentPath: proposal.componentPath,
-      modificationType: proposal.modificationType,
-      status: proposal.status,
-      priority: proposal.priority,
-      createdAt: proposal.metadata.createdAt,
-      createdBy: proposal.metadata.createdBy
-    });
-
-    await fs.writeFile(indexFile, JSON.stringify(index, null, 2));
-  }
-
-  async notifyAssignees(result, assignees) {
-    try {
-      await this.notificationService.notifyUsers(assignees, {
-        type: 'proposal_assigned',
-        proposalId: result.proposalId,
-        title: result.title,
-        priority: result.priority,
-        url: result.webUrl
-      });
-
-      console.log(chalk.gray(`   Notifications sent to: ${assignees.join(', ')}`));
-
-    } catch (error) {
-      console.warn(chalk.yellow(`Failed to send notifications: ${error.message}`));
-    }
-  }
-
-  // Helper methods
-
-  determineComponentType(filePath, content) {
-    if (filePath.includes('/agents/')) return 'agent';
-    if (filePath.includes('/tasks/')) return 'task';
-    if (filePath.includes('/workflows/')) return 'workflow';
-    if (filePath.includes('/utils/')) return 'util';
-    return 'unknown';
-  }
-
-  calculateRiskLevel(impact) {
-    const affectedCount = impact.affectedComponents.length;
-    const criticalCount = impact.impactCategories?.critical?.length || 0;
-
-    if (criticalCount > 0 || affectedCount > 20) return 'high';
-    if (affectedCount > 10) return 'medium';
-    return 'low';
-  }
-
-  generateImpactSummary(impact) {
-    return {
-      totalAffected: impact.affectedComponents.length,
-      byCategory: {
-        critical: impact.impactCategories?.critical?.length || 0,
-        high: impact.impactCategories?.high?.length || 0,
-        medium: impact.impactCategories?.medium?.length || 0,
-        low: impact.impactCategories?.low?.length || 0
-      }
-    };
-  }
-
-  getDescriptionTemplate(modificationType) {
-    const templates = {
-      enhance: `## Enhancement Description
-
-### Objective
-[Describe what this enhancement aims to achieve]
-
-### Implementation Details
-[Explain how the enhancement will be implemented]
-
-### Benefits
-- [List expected benefits]
-
-### Testing Plan
-[Describe how the enhancement will be tested]`,
-
-      refactor: `## Refactoring Description
-
-### Current Issues
-[Describe problems with current implementation]
-
-### Proposed Changes
-[Detail the refactoring approach]
-
-### Expected Improvements
-- [List expected improvements]
-
-### Risk Assessment
-[Identify potential risks]`,
-
-      deprecate: `## Deprecation Description
-
-### Reason for Deprecation
-[Explain why this component should be deprecated]
-
-### Migration Path
-[Describe how users should migrate]
-
-### Timeline
-[Specify deprecation timeline]
-
-### Affected Users
-[Identify who will be affected]`,
-
-      modify: `## Modification Description
-
-### Changes Overview
-[Summarize the modifications]
-
-### Rationale
-[Explain why these changes are needed]
-
-### Implementation
-[Detail how changes will be implemented]
-
-### Validation
-[Describe validation approach]`
-    };
-
-    return templates[modificationType] || templates.modify;
-  }
-
-  generateProposalUrl(proposalId) {
-    // In a real implementation, this would generate actual web URLs
-    return `http://aios-framework.local/proposals/${proposalId}`;
-  }
-}
-
-module.exports = ProposeModificationTask;
-```
-
-## Validation Rules
-
-### Input Validation
-- Component path must exist and be accessible
-- Modification type must be valid
-- Priority must be recognized level
-- Assignees should be valid user identifiers
-- Linked issues should be valid issue IDs
-
-### Proposal Requirements
-- Title and description are required (prompted if not provided)
-- Draft proposals can be incomplete
-- Non-draft proposals must have complete information
-- Impact analysis is recommended for high priority changes
-
-### Review Process
-- Proposals start in 'draft' or 'pending_review' status
-- Assignees are notified upon submission
-- Review timeline expectations are set
-- Modification type determines required fields
-
-## Integration Points
-
-### Proposal System
-- Manages proposal lifecycle and storage
-- Handles versioning and history tracking
-- Coordinates review workflows
-- Integrates with notification system
-
-### Impact Analysis
-- Optional but recommended for significant changes
-- Provides risk assessment for reviewers
-- Identifies affected components
-- Helps prioritize review efforts
-
-### Notification Service
-- Notifies assigned reviewers
-- Sends updates on proposal status changes
-- Supports multiple notification channels
-- Tracks notification delivery
-
-## Security Considerations
-- Validate all user inputs to prevent injection
-- Ensure proper access control for proposals
-- Sanitize file paths and content
-- Log all proposal activities for audit
+---
+
+## 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: proposeModification()
+responsável: Atlas (Decoder)
+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
+```
+
+---
+
+checklists:
+  - change-checklist.md
+---
+
+# Propose Modification - AIOS Developer Task
+
+## Purpose
+Create and submit modification proposals for collaborative review and approval within the Synkra AIOS framework.
+
+## Command Pattern
+```
+*propose-modification <component-path> <modification-type> [options]
+```
+
+## Parameters
+- `component-path`: Path to the component to modify
+- `modification-type`: Type of modification (modify, refactor, deprecate, enhance)
+- `options`: Additional proposal configuration
+
+### Options
+- `--title <title>`: Title for the proposal
+- `--description <desc>`: Detailed description of changes
+- `--priority <level>`: Priority level (low, medium, high, critical)
+- `--tags <tags>`: Comma-separated tags for categorization
+- `--assignees <users>`: Comma-separated list of reviewers
+- `--draft`: Create as draft proposal
+- `--link-issues <ids>`: Link related issues or tasks
+- `--impact-analysis`: Include impact analysis report
+- `--test-results`: Attach test results
+
+## Examples
+```bash
+# Propose agent enhancement
+*propose-modification aios-core/agents/weather-agent.md enhance --title "Add caching support" --description "Implement response caching to reduce API calls" --priority medium
+
+# Propose critical refactoring with impact analysis
+*propose-modification aios-core/scripts/core-utility.js refactor --title "Optimize performance" --priority critical --impact-analysis --assignees "alice,bob"
+
+# Create draft proposal for workflow deprecation
+*propose-modification aios-core/workflows/legacy-workflow.yaml deprecate --draft --title "Deprecate legacy workflow" --link-issues "123,456"
+```
+
+## Implementation
+
+```javascript
+const fs = require('fs').promises;
+const path = require('path');
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+
+class ProposeModificationTask {
+  constructor() {
+    this.taskName = 'propose-modification';
+    this.description = 'Create modification proposals for collaborative review';
+    this.rootPath = process.cwd();
+    this.proposalSystem = null;
+    this.impactAnalyzer = null;
+    this.notificationService = null;
+  }
+
+  async execute(params) {
+    try {
+      console.log(chalk.blue('📝 AIOS Modification Proposal'));
+      console.log(chalk.gray('Creating collaborative modification proposal\n'));
+
+      // Parse and validate parameters
+      const config = await this.parseParameters(params);
+      
+      // Initialize dependencies
+      await this.initializeDependencies();
+
+      // Validate target component
+      const component = await this.validateComponent(config.componentPath);
+
+      // Create proposal
+      console.log(chalk.gray('Creating modification proposal...'));
+      const proposal = await this.createProposal(component, config);
+
+      // Run impact analysis if requested
+      if (config.includeImpactAnalysis) {
+        console.log(chalk.gray('Running impact analysis...'));
+        proposal.impactAnalysis = await this.runImpactAnalysis(component, config);
+      }
+
+      // Attach test results if provided
+      if (config.testResults) {
+        console.log(chalk.gray('Attaching test results...'));
+        proposal.testResults = await this.attachTestResults(config.testResults);
+      }
+
+      // Get proposal details from user
+      const details = await this.getProposalDetails(proposal, config);
+      Object.assign(proposal, details);
+
+      // Submit proposal
+      console.log(chalk.gray('Submitting proposal...'));
+      const result = await this.submitProposal(proposal, config);
+
+      // Notify assignees
+      if (config.assignees.length > 0) {
+        await this.notifyAssignees(result, config.assignees);
+      }
+
+      // Display success
+      console.log(chalk.green('\n✅ Modification proposal created successfully'));
+      console.log(chalk.gray(`   Proposal ID: ${result.proposalId}`));
+      console.log(chalk.gray(`   Status: ${result.status}`));
+      console.log(chalk.gray(`   Reviewers: ${config.assignees.join(', ') || 'None assigned'}`));
+      
+      if (result.webUrl) {
+        console.log(chalk.blue(`   View proposal: ${result.webUrl}`));
+      }
+
+      return {
+        success: true,
+        proposalId: result.proposalId,
+        status: result.status,
+        component: component.path,
+        modificationType: config.modificationType,
+        priority: config.priority,
+        assignees: config.assignees
+      };
+
+    } catch (error) {
+      console.error(chalk.red(`\n❌ Proposal creation failed: ${error.message}`));
+      throw error;
+    }
+  }
+
+  async parseParameters(params) {
+    if (params.length < 2) {
+      throw new Error('Usage: *propose-modification <component-path> <modification-type> [options]');
+    }
+
+    const config = {
+      componentPath: params[0],
+      modificationType: params[1],
+      title: '',
+      description: '',
+      priority: 'medium',
+      tags: [],
+      assignees: [],
+      isDraft: false,
+      linkedIssues: [],
+      includeImpactAnalysis: false,
+      testResults: null
+    };
+
+    // Validate modification type
+    const validTypes = ['modify', 'refactor', 'deprecate', 'enhance'];
+    if (!validTypes.includes(config.modificationType)) {
+      throw new Error(`Invalid modification type: ${config.modificationType}. Must be one of: ${validTypes.join(', ')}`);
+    }
+
+    // Parse options
+    for (let i = 2; i < params.length; i++) {
+      const param = params[i];
+      
+      if (param === '--draft') {
+        config.isDraft = true;
+      } else if (param === '--impact-analysis') {
+        config.includeImpactAnalysis = true;
+      } else if (param.startsWith('--title') && params[i + 1]) {
+        config.title = params[++i];
+      } else if (param.startsWith('--description') && params[i + 1]) {
+        config.description = params[++i];
+      } else if (param.startsWith('--priority') && params[i + 1]) {
+        config.priority = params[++i];
+      } else if (param.startsWith('--tags') && params[i + 1]) {
+        config.tags = params[++i].split(',').map(t => t.trim());
+      } else if (param.startsWith('--assignees') && params[i + 1]) {
+        config.assignees = params[++i].split(',').map(a => a.trim());
+      } else if (param.startsWith('--link-issues') && params[i + 1]) {
+        config.linkedIssues = params[++i].split(',').map(id => id.trim());
+      } else if (param.startsWith('--test-results') && params[i + 1]) {
+        config.testResults = params[++i];
+      }
+    }
+
+    // Validate priority
+    const validPriorities = ['low', 'medium', 'high', 'critical'];
+    if (!validPriorities.includes(config.priority)) {
+      throw new Error(`Invalid priority: ${config.priority}. Must be one of: ${validPriorities.join(', ')}`);
+    }
+
+    return config;
+  }
+
+  async initializeDependencies() {
+    try {
+      const ProposalSystem = require('../scripts/proposal-system');
+      this.proposalSystem = new ProposalSystem({ rootPath: this.rootPath });
+
+      const ImpactAnalyzer = require('../scripts/dependency-impact-analyzer');
+      this.impactAnalyzer = new ImpactAnalyzer({ rootPath: this.rootPath });
+
+      const NotificationService = require('../scripts/notification-service');
+      this.notificationService = new NotificationService({ rootPath: this.rootPath });
+
+    } catch (error) {
+      throw new Error(`Failed to initialize dependencies: ${error.message}`);
+    }
+  }
+
+  async validateComponent(componentPath) {
+    const fullPath = path.resolve(this.rootPath, componentPath);
+    
+    try {
+      const stats = await fs.stat(fullPath);
+      if (!stats.isFile()) {
+        throw new Error(`Not a file: ${componentPath}`);
+      }
+
+      const content = await fs.readFile(fullPath, 'utf-8');
+      const componentType = this.determineComponentType(fullPath, content);
+
+      return {
+        path: componentPath,
+        fullPath: fullPath,
+        type: componentType,
+        content: content,
+        lastModified: stats.mtime
+      };
+
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        throw new Error(`Component not found: ${componentPath}`);
+      }
+      throw error;
+    }
+  }
+
+  async createProposal(component, config) {
+    const proposal = {
+      proposalId: `proposal-${Date.now()}-${Math.random().toString(36).substr(2, 6)}`,
+      componentPath: component.path,
+      componentType: component.type,
+      modificationType: config.modificationType,
+      title: config.title || `${config.modificationType} ${component.path}`,
+      description: config.description,
+      priority: config.priority,
+      status: config.isDraft ? 'draft' : 'pending_review',
+      tags: config.tags,
+      assignees: config.assignees,
+      linkedIssues: config.linkedIssues,
+      metadata: {
+        createdBy: process.env.USER || 'aios-developer',
+        createdAt: new Date().toISOString(),
+        lastModified: new Date().toISOString(),
+        version: 1
+      }
+    };
+
+    // Add modification type specific fields
+    switch (config.modificationType) {
+      case 'deprecate':
+        proposal.deprecationInfo = {
+          targetRemovalDate: null,
+          migrationPath: null,
+          affectedComponents: []
+        };
+        break;
+      case 'enhance':
+        proposal.enhancementInfo = {
+          newCapabilities: [],
+          performanceImpact: null,
+          backwardCompatible: true
+        };
+        break;
+      case 'refactor':
+        proposal.refactorInfo = {
+          scope: 'component', // component, module, system
+          breakingChanges: false,
+          codeQualityMetrics: {}
+        };
+        break;
+    }
+
+    return proposal;
+  }
+
+  async runImpactAnalysis(component, config) {
+    try {
+      const impact = await this.impactAnalyzer.analyzeDependencyImpact(component, {
+        modificationType: config.modificationType,
+        depth: 'deep'
+      });
+
+      return {
+        affectedComponents: impact.affectedComponents.length,
+        criticalDependencies: impact.impactCategories?.critical || [],
+        riskLevel: this.calculateRiskLevel(impact),
+        summary: this.generateImpactSummary(impact)
+      };
+
+    } catch (error) {
+      console.warn(chalk.yellow(`Impact analysis failed: ${error.message}`));
+      return null;
+    }
+  }
+
+  async attachTestResults(testResultsPath) {
+    try {
+      const content = await fs.readFile(testResultsPath, 'utf-8');
+      return {
+        source: testResultsPath,
+        content: content,
+        attachedAt: new Date().toISOString()
+      };
+    } catch (error) {
+      console.warn(chalk.yellow(`Failed to attach test results: ${error.message}`));
+      return null;
+    }
+  }
+
+  async getProposalDetails(proposal, config) {
+    const questions = [];
+
+    // Title if not provided
+    if (!config.title) {
+      questions.push({
+        type: 'input',
+        name: 'title',
+        message: 'Proposal title:',
+        default: proposal.title,
+        validate: input => input.length > 0 || 'Title is required'
+      });
+    }
+
+    // Description if not provided
+    if (!config.description) {
+      questions.push({
+        type: 'editor',
+        name: 'description',
+        message: 'Detailed description (opens editor):',
+        default: this.getDescriptionTemplate(config.modificationType)
+      });
+    }
+
+    // Modification-specific questions
+    if (config.modificationType === 'deprecate') {
+      questions.push({
+        type: 'input',
+        name: 'targetRemovalDate',
+        message: 'Target removal date (YYYY-MM-DD):',
+        validate: input => {
+          if (!input) return true;
+          return /^\d{4}-\d{2}-\d{2}$/.test(input) || 'Invalid date format';
+        }
+      });
+    }
+
+    if (config.modificationType === 'enhance') {
+      questions.push({
+        type: 'checkbox',
+        name: 'newCapabilities',
+        message: 'Select new capabilities:',
+        choices: [
+          'Performance optimization',
+          'New API endpoints',
+          'Additional configuration options',
+          'Extended error handling',
+          'Improved logging',
+          'New integrations',
+          'Other'
+        ]
+      });
+    }
+
+    if (config.modificationType === 'refactor') {
+      questions.push({
+        type: 'confirm',
+        name: 'breakingChanges',
+        message: 'Will this refactoring introduce breaking changes?',
+        default: false
+      });
+    }
+
+    // Review timeline
+    questions.push({
+      type: 'list',
+      name: 'reviewTimeline',
+      message: 'Expected review timeline:',
+      choices: [
+        { name: 'Urgent (1-2 days)', value: 'urgent' },
+        { name: 'Normal (3-5 days)', value: 'normal' },
+        { name: 'Low priority (1 week+)', value: 'low' }
+      ],
+      default: 'normal'
+    });
+
+    const answers = await inquirer.prompt(questions);
+
+    // Process answers
+    const details = {
+      title: answers.title || config.title,
+      description: answers.description || config.description,
+      reviewTimeline: answers.reviewTimeline
+    };
+
+    // Add modification-specific details
+    if (config.modificationType === 'deprecate' && answers.targetRemovalDate) {
+      details.deprecationInfo = {
+        targetRemovalDate: answers.targetRemovalDate
+      };
+    }
+
+    if (config.modificationType === 'enhance' && answers.newCapabilities) {
+      details.enhancementInfo = {
+        newCapabilities: answers.newCapabilities
+      };
+    }
+
+    if (config.modificationType === 'refactor') {
+      details.refactorInfo = {
+        breakingChanges: answers.breakingChanges
+      };
+    }
+
+    return details;
+  }
+
+  async submitProposal(proposal, config) {
+    try {
+      // Submit through proposal system
+      const result = await this.proposalSystem.submitProposal(proposal);
+
+      // Store in memory/database
+      await this.storeProposal(proposal, result);
+
+      return {
+        proposalId: proposal.proposalId,
+        status: proposal.status,
+        webUrl: this.generateProposalUrl(proposal.proposalId),
+        createdAt: proposal.metadata.createdAt
+      };
+
+    } catch (error) {
+      throw new Error(`Failed to submit proposal: ${error.message}`);
+    }
+  }
+
+  async storeProposal(proposal, result) {
+    const proposalsDir = path.join(this.rootPath, '.aios', 'proposals');
+    await fs.mkdir(proposalsDir, { recursive: true });
+
+    const proposalFile = path.join(proposalsDir, `${proposal.proposalId}.json`);
+    await fs.writeFile(proposalFile, JSON.stringify(proposal, null, 2));
+
+    // Update proposals index
+    const indexFile = path.join(proposalsDir, 'index.json');
+    let index = { proposals: [] };
+    
+    try {
+      const existing = await fs.readFile(indexFile, 'utf-8');
+      index = JSON.parse(existing);
+    } catch (error) {
+      // Index doesn't exist yet
+    }
+
+    index.proposals.push({
+      proposalId: proposal.proposalId,
+      title: proposal.title,
+      componentPath: proposal.componentPath,
+      modificationType: proposal.modificationType,
+      status: proposal.status,
+      priority: proposal.priority,
+      createdAt: proposal.metadata.createdAt,
+      createdBy: proposal.metadata.createdBy
+    });
+
+    await fs.writeFile(indexFile, JSON.stringify(index, null, 2));
+  }
+
+  async notifyAssignees(result, assignees) {
+    try {
+      await this.notificationService.notifyUsers(assignees, {
+        type: 'proposal_assigned',
+        proposalId: result.proposalId,
+        title: result.title,
+        priority: result.priority,
+        url: result.webUrl
+      });
+
+      console.log(chalk.gray(`   Notifications sent to: ${assignees.join(', ')}`));
+
+    } catch (error) {
+      console.warn(chalk.yellow(`Failed to send notifications: ${error.message}`));
+    }
+  }
+
+  // Helper methods
+
+  determineComponentType(filePath, content) {
+    if (filePath.includes('/agents/')) return 'agent';
+    if (filePath.includes('/tasks/')) return 'task';
+    if (filePath.includes('/workflows/')) return 'workflow';
+    if (filePath.includes('/utils/')) return 'util';
+    return 'unknown';
+  }
+
+  calculateRiskLevel(impact) {
+    const affectedCount = impact.affectedComponents.length;
+    const criticalCount = impact.impactCategories?.critical?.length || 0;
+
+    if (criticalCount > 0 || affectedCount > 20) return 'high';
+    if (affectedCount > 10) return 'medium';
+    return 'low';
+  }
+
+  generateImpactSummary(impact) {
+    return {
+      totalAffected: impact.affectedComponents.length,
+      byCategory: {
+        critical: impact.impactCategories?.critical?.length || 0,
+        high: impact.impactCategories?.high?.length || 0,
+        medium: impact.impactCategories?.medium?.length || 0,
+        low: impact.impactCategories?.low?.length || 0
+      }
+    };
+  }
+
+  getDescriptionTemplate(modificationType) {
+    const templates = {
+      enhance: `## Enhancement Description
+
+### Objective
+[Describe what this enhancement aims to achieve]
+
+### Implementation Details
+[Explain how the enhancement will be implemented]
+
+### Benefits
+- [List expected benefits]
+
+### Testing Plan
+[Describe how the enhancement will be tested]`,
+
+      refactor: `## Refactoring Description
+
+### Current Issues
+[Describe problems with current implementation]
+
+### Proposed Changes
+[Detail the refactoring approach]
+
+### Expected Improvements
+- [List expected improvements]
+
+### Risk Assessment
+[Identify potential risks]`,
+
+      deprecate: `## Deprecation Description
+
+### Reason for Deprecation
+[Explain why this component should be deprecated]
+
+### Migration Path
+[Describe how users should migrate]
+
+### Timeline
+[Specify deprecation timeline]
+
+### Affected Users
+[Identify who will be affected]`,
+
+      modify: `## Modification Description
+
+### Changes Overview
+[Summarize the modifications]
+
+### Rationale
+[Explain why these changes are needed]
+
+### Implementation
+[Detail how changes will be implemented]
+
+### Validation
+[Describe validation approach]`
+    };
+
+    return templates[modificationType] || templates.modify;
+  }
+
+  generateProposalUrl(proposalId) {
+    // In a real implementation, this would generate actual web URLs
+    return `http://aios-framework.local/proposals/${proposalId}`;
+  }
+}
+
+module.exports = ProposeModificationTask;
+```
+
+## Validation Rules
+
+### Input Validation
+- Component path must exist and be accessible
+- Modification type must be valid
+- Priority must be recognized level
+- Assignees should be valid user identifiers
+- Linked issues should be valid issue IDs
+
+### Proposal Requirements
+- Title and description are required (prompted if not provided)
+- Draft proposals can be incomplete
+- Non-draft proposals must have complete information
+- Impact analysis is recommended for high priority changes
+
+### Review Process
+- Proposals start in 'draft' or 'pending_review' status
+- Assignees are notified upon submission
+- Review timeline expectations are set
+- Modification type determines required fields
+
+## Integration Points
+
+### Proposal System
+- Manages proposal lifecycle and storage
+- Handles versioning and history tracking
+- Coordinates review workflows
+- Integrates with notification system
+
+### Impact Analysis
+- Optional but recommended for significant changes
+- Provides risk assessment for reviewers
+- Identifies affected components
+- Helps prioritize review efforts
+
+### Notification Service
+- Notifies assigned reviewers
+- Sends updates on proposal status changes
+- Supports multiple notification channels
+- Tracks notification delivery
+
+## Security Considerations
+- Validate all user inputs to prevent injection
+- Ensure proper access control for proposals
+- Sanitize file paths and content
+- Log all proposal activities for audit
 - Protect sensitive component information