aios-core 2.1.0

package/.aios-core/development/tasks/github-devops-version-management.md

@@ -0,0 +1,483 @@
+# version-management.md
+
+**Task**: Semantic Version Management (Repository-Agnostic)
+
+**Purpose**: Analyze changes, recommend version bumps, and manage semantic versioning for ANY repository using AIOS.
+
+**When to use**: Before creating a release, to determine appropriate version number based on changes.
+
+## 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: githubDevopsVersionManagement()
+responsável: Gage (Automator)
+responsavel_type: Agente
+atomic_layer: Organism
+
+**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: 5-15 min (estimated)
+cost_estimated: $0.003-0.010
+token_usage: ~3,000-10,000 tokens
+```
+
+**Optimization Notes:**
+- Break into smaller workflows; implement checkpointing; use async processing where possible
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - N/A
+tags:
+  - automation
+  - workflow
+updated_at: 2025-11-17
+```
+
+---
+
+
+## Prerequisites
+- Git repository with commit history
+- package.json with current version
+- Understanding of semantic versioning (MAJOR.MINOR.PATCH)
+
+## Semantic Versioning Rules
+
+- **MAJOR** (v4.0.0 → v5.0.0): Breaking changes, API redesign
+- **MINOR** (v4.31.0 → v4.32.0): New features, backward compatible
+- **PATCH** (v4.31.0 → v4.31.1): Bug fixes only
+
+## Keywords for Detection
+
+**Breaking Changes** (MAJOR):
+- `BREAKING CHANGE:`
+- `BREAKING:`
+- `!` in commit type (e.g., `feat!:`)
+- API redesign
+- Removed functionality
+- Incompatible changes
+
+**New Features** (MINOR):
+- `feat:`
+- `feature:`
+- New capability
+- Enhancement
+
+**Bug Fixes** (PATCH):
+- `fix:`
+- `bugfix:`
+- `hotfix:`
+- Patch
+
+## Workflow Steps
+
+### Step 1: Detect Repository Context
+
+```javascript
+const { detectRepositoryContext } = require('./../scripts/repository-detector');
+const context = detectRepositoryContext();
+
+if (!context) {
+  throw new Error('Unable to detect repository context. Run "aios init" first.');
+}
+
+console.log(`📦 Analyzing version for: ${context.packageName}`);
+console.log(`Current version: ${context.packageVersion}`);
+```
+
+### Step 2: Get Last Git Tag
+
+```bash
+git describe --tags --abbrev=0
+```
+
+If no tags exist, use `v0.0.0` as baseline.
+
+### Step 3: Analyze Commits Since Last Tag
+
+```bash
+git log <last-tag>..HEAD --oneline
+```
+
+Parse each commit message:
+- Count breaking changes
+- Count features
+- Count fixes
+
+### Step 4: Recommend Version Bump
+
+**Logic**:
+1. If `breakingChanges > 0` → MAJOR bump
+2. Else if `features > 0` → MINOR bump
+3. Else if `fixes > 0` → PATCH bump
+4. Else → No version bump needed
+
+### Step 5: User Confirmation
+
+Present recommendation:
+
+```
+📊 Version Analysis
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Current version:  v4.31.0
+Recommended:      v4.32.0 (MINOR)
+
+Changes since v4.31.0:
+  Breaking changes: 0
+  New features:     3
+  Bug fixes:        2
+
+Reason: New features detected (backward compatible)
+
+Proceed with version v4.32.0? (Y/n)
+```
+
+### Step 6: Update package.json
+
+```javascript
+const fs = require('fs');
+const path = require('path');
+
+const packageJsonPath = path.join(context.projectRoot, 'package.json');
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+
+packageJson.version = newVersion;
+
+fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n');
+console.log(`✓ Updated package.json to ${newVersion}`);
+```
+
+### Step 7: Create Git Tag
+
+```bash
+git tag -a v<newVersion> -m "Release v<newVersion>"
+```
+
+### Step 8: Generate Changelog
+
+Extract commits since last tag and format:
+
+```markdown
+## [4.32.0] - 2025-10-25
+
+### Added
+- New feature A
+- New feature B
+- New feature C
+
+### Fixed
+- Bug fix 1
+- Bug fix 2
+```
+
+## Example Implementation
+
+```javascript
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const inquirer = require('inquirer');
+const semver = require('semver');
+
+async function manageVersion() {
+  // Step 1: Detect context
+  const { detectRepositoryContext } = require('./../scripts/repository-detector');
+  const context = detectRepositoryContext();
+
+  if (!context) {
+    console.error('❌ Unable to detect repository context');
+    process.exit(1);
+  }
+
+  console.log(`\n📦 Version Management for ${context.packageName}`);
+  console.log(`Current version: ${context.packageVersion}\n`);
+
+  // Step 2: Get last tag
+  let lastTag;
+  try {
+    lastTag = execSync('git describe --tags --abbrev=0', {
+      cwd: context.projectRoot
+    }).toString().trim();
+  } catch (error) {
+    lastTag = 'v0.0.0';
+    console.log('⚠️  No tags found, using v0.0.0 as baseline');
+  }
+
+  console.log(`Last tag: ${lastTag}\n`);
+
+  // Step 3: Analyze commits
+  const commits = execSync(`git log ${lastTag}..HEAD --oneline`, {
+    cwd: context.projectRoot
+  }).toString().trim().split('\n').filter(Boolean);
+
+  let breakingChanges = 0;
+  let features = 0;
+  let fixes = 0;
+
+  const breakingPattern = /BREAKING CHANGE:|BREAKING:|^\w+!:/;
+  const featurePattern = /^feat:|^feature:/;
+  const fixPattern = /^fix:|^bugfix:|^hotfix:/;
+
+  commits.forEach(commit => {
+    if (breakingPattern.test(commit)) breakingChanges++;
+    else if (featurePattern.test(commit)) features++;
+    else if (fixPattern.test(commit)) fixes++;
+  });
+
+  // Step 4: Recommend version
+  const currentVersion = context.packageVersion.replace(/^v/, '');
+  let newVersion;
+  let bumpType;
+
+  if (breakingChanges > 0) {
+    newVersion = semver.inc(currentVersion, 'major');
+    bumpType = 'MAJOR';
+  } else if (features > 0) {
+    newVersion = semver.inc(currentVersion, 'minor');
+    bumpType = 'MINOR';
+  } else if (fixes > 0) {
+    newVersion = semver.inc(currentVersion, 'patch');
+    bumpType = 'PATCH';
+  } else {
+    console.log('ℹ️  No version bump needed (no changes detected)');
+    process.exit(0);
+  }
+
+  // Step 5: User confirmation
+  console.log('📊 Version Analysis');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log(`Current version:  v${currentVersion}`);
+  console.log(`Recommended:      v${newVersion} (${bumpType})`);
+  console.log('');
+  console.log(`Changes since ${lastTag}:`);
+  console.log(`  Breaking changes: ${breakingChanges}`);
+  console.log(`  New features:     ${features}`);
+  console.log(`  Bug fixes:        ${fixes}`);
+  console.log('');
+
+  const { confirm } = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'confirm',
+      message: `Proceed with version v${newVersion}?`,
+      default: true
+    }
+  ]);
+
+  if (!confirm) {
+    console.log('❌ Version update cancelled');
+    process.exit(0);
+  }
+
+  // Step 6: Update package.json
+  const packageJsonPath = path.join(context.projectRoot, 'package.json');
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  packageJson.version = newVersion;
+  fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n');
+  console.log(`\n✓ Updated package.json to v${newVersion}`);
+
+  // Step 7: Create git tag
+  execSync(`git tag -a v${newVersion} -m "Release v${newVersion}"`, {
+    cwd: context.projectRoot
+  });
+  console.log(`✓ Created git tag v${newVersion}`);
+
+  console.log('\n✅ Version management complete!');
+  console.log(`\nNext steps:`);
+  console.log(`  - Review changes: git show v${newVersion}`);
+  console.log(`  - Push tag: git push origin v${newVersion}`);
+  console.log(`  - Create release with @github-devops *release`);
+}
+
+module.exports = { manageVersion };
+```
+
+## Usage
+
+Called by `@github-devops` agent via `*version-check` command.
+
+## Validation
+
+- Version bump follows semantic versioning rules
+- User confirms version change
+- Git tag created successfully
+- package.json updated correctly
+
+## Notes
+
+- Works with ANY repository (framework or project)
+- Respects conventional commits format
+- User always has final approval
+- Does NOT push to remote (that's done by *push command)