grimoire-framework 1.0.0

package/.grimoire/development/tasks/release-management.md

@@ -0,0 +1,754 @@
+---
+id: release-management
+name: Manage Software Releases
+agent: github-devops
+category: devops
+complexity: high
+tools:
+  - github-cli # Create releases, tags, manage artifacts
+  - semantic-release # Automate versioning and changelog
+checklists:
+  - github-devops-checklist.md
+---
+
+# Manage Software Releases
+
+## Purpose
+
+To automate the complete software release process, including:
+
+- Semantic versioning (major.minor.patch)
+- Changelog generation from commits
+- Git tagging
+- GitHub/GitLab Release creation
+- Package publishing (npm, PyPI, Docker, etc.)
+- Release notes generation
+
+## Input
+
+### Required Parameters
+
+- **repository_path**: `string`
+  - **Description**: Local path or URL of repository
+  - **Example**: `/path/to/project` or `https://github.com/user/repo`
+  - **Validation**: Must be valid Git repository
+
+- **release_type**: `string`
+  - **Description**: Type of release to create
+  - **Options**: `"auto"` (detect from commits), `"major"`, `"minor"`, `"patch"`, `"prerelease"`
+  - **Default**: `"auto"`
+
+### Optional Parameters
+
+- **release_branch**: `string`
+  - **Description**: Branch to release from
+  - **Default**: `"main"`
+  - **Note**: Must be default branch for production releases
+
+- **changelog_format**: `string`
+  - **Description**: Changelog style
+  - **Options**: `"keep-a-changelog"`, `"angular"`, `"conventional-commits"`
+  - **Default**: `"conventional-commits"`
+
+- **package_registry**: `array<string>`
+  - **Description**: Where to publish package
+  - **Options**: `["npm"]`, `["pypi"]`, `["docker-hub"]`, `["github-packages"]`
+  - **Default**: Auto-detect from project type
+
+- **dry_run**: `boolean`
+  - **Description**: Test release without publishing
+  - **Default**: `false`
+
+- **prerelease_tag**: `string`
+  - **Description**: Tag for prerelease (if release_type="prerelease")
+  - **Examples**: `"alpha"`, `"beta"`, `"rc"`
+  - **Default**: `"beta"`
+
+- **skip_ci**: `boolean`
+  - **Description**: Skip CI checks (emergency releases only)
+  - **Default**: `false`
+  - **Warning**: Only use for critical hotfixes
+
+## Output
+
+- **new_version**: `string`
+  - **Description**: Version number created
+  - **Example**: `"2.1.3"`
+
+- **git_tag**: `string`
+  - **Description**: Git tag created
+  - **Example**: `"v4.0.4.3"`
+
+- **changelog**: `string`
+  - **Description**: Generated CHANGELOG.md content for this release
+
+- **release_url**: `string`
+  - **Description**: URL to GitHub/GitLab Release
+  - **Example**: `"https://github.com/user/repo/releases/tag/v4.0.4.3"`
+
+- **published_packages**: `array<object>`
+  - **Description**: Published packages with URLs
+  - **Structure**: `{ registry, package_name, version, url }`
+  - **Example**: `[{ registry: "npm", package_name: "grimoire", version: "2.1.3", url: "https://npmjs.com/package/grimoire" }]`
+
+- **release_notes**: `string`
+  - **Description**: Formatted release notes (for announcements)
+
+- **breaking_changes**: `array<string>`
+  - **Description**: List of breaking changes (if any)
+  - **Note**: Empty array if backward compatible
+
+## Process
+
+### Phase 1: Pre-Release Validation (2 min)
+
+1. **Validate Repository State**
+   - Check if on release branch
+   - Verify no uncommitted changes
+   - Ensure branch is up-to-date with remote
+   - Check CI status (must be passing unless skip_ci=true)
+
+2. **🔴 CRITICAL: Validate Tag Reachability**
+   - Check which version tags are reachable from HEAD
+   - Run: `git merge-base --is-ancestor <tag> HEAD` for each tag
+   - **If NO tags are reachable** → semantic-release will create v1.0.0!
+   - This can happen after `git filter-repo` rewrites history
+   - **Resolution**: Create a baseline tag at current package.json version:
+     ```bash
+     git tag v$(node -p "require('./package.json').version")
+     git push origin v$(node -p "require('./package.json').version")
+     ```
+
+3. **Analyze Commits Since Last Release**
+   - Get last version tag (e.g., `v4.0.4.2`)
+   - Get commits since last tag: `git log v4.0.4.2..HEAD`
+   - Parse commit messages (Conventional Commits)
+
+4. **Determine Version Bump**
+   - If `release_type="auto"`:
+     - **BREAKING CHANGE** in commits → **major** bump (2.1.2 → 3.0.0)
+     - **feat:** commits → **minor** bump (2.1.2 → 2.2.0)
+     - **fix:** commits → **patch** bump (2.1.2 → 2.1.3)
+     - No eligible commits → **HALT** (nothing to release)
+   - Else: Use specified `release_type`
+   - Calculate new version: `{major}.{minor}.{patch}`
+
+5. **Check Breaking Changes**
+   - Scan for `BREAKING CHANGE:` or `!` in commit messages
+   - Extract breaking change descriptions
+   - If found and major bump not planned → **WARN** user
+
+### Phase 2: Changelog Generation (2 min)
+
+5. **Generate CHANGELOG.md Updates**
+   - Group commits by type:
+     - **Breaking Changes** (⚠️)
+     - **Features** (✨ feat:)
+     - **Bug Fixes** (🐛 fix:)
+     - **Performance** (⚡ perf:)
+     - **Documentation** (📝 docs:)
+     - **Refactoring** (♻️ refactor:)
+     - **Tests** (✅ test:)
+     - **Chores** (🔧 chore:)
+   - Format according to `changelog_format`
+   - Prepend to CHANGELOG.md
+
+   **Example Output (Conventional Commits format):**
+
+   ```markdown
+   ## [2.1.3] - 2025-11-13
+
+   ### ⚠️ Breaking Changes
+
+   - API endpoint `/v1/users` renamed to `/v2/users` (#42)
+
+   ### ✨ Features
+
+   - Add user authentication with OAuth2 (#38)
+   - Implement rate limiting for API (#40)
+
+   ### 🐛 Bug Fixes
+
+   - Fix memory leak in database connection pool (#39)
+   - Correct timezone handling in date filters (#41)
+
+   ### 📝 Documentation
+
+   - Update API documentation with new endpoints (#43)
+   ```
+
+6. **Generate Release Notes**
+   - Extract highlights (most impactful changes)
+   - Format for social media / announcements
+   - Include contributor credits
+   - Add migration guide if breaking changes
+
+### Phase 3: Version Bumping (1 min)
+
+7. **Update Version Files**
+   - **Node.js**: Update `package.json` version
+   - **Python**: Update `setup.py` or `pyproject.toml` version
+   - **Rust**: Update `Cargo.toml` version
+   - **Go**: Update VERSION file or version constant
+   - **Docker**: Update Dockerfile labels
+
+8. **Commit Version Changes**
+   - Create commit: `chore(release): bump version to {new_version}`
+   - Include updated CHANGELOG.md
+   - **DO NOT PUSH YET** (will push after tagging)
+
+### Phase 4: Git Tagging & Release (3 min)
+
+9. **Create Git Tag**
+   - Create annotated tag: `git tag -a v{new_version} -m "Release v{new_version}"`
+   - Include release notes in tag message
+
+10. **Push to Remote**
+    - Push commits: `git push origin {release_branch}`
+    - Push tags: `git push origin v{new_version}`
+    - Wait for remote to accept
+
+11. **Create GitHub/GitLab Release**
+    - Use GitHub CLI:
+      ```bash
+      gh release create v{new_version} \
+        --title "Release v{new_version}" \
+        --notes-file release-notes.md \
+        --latest
+      ```
+    - Attach build artifacts (if applicable):
+      - Binary executables
+      - Docker images
+      - Tarball archives
+
+### Phase 5: Package Publishing (5 min)
+
+12. **Publish to Package Registries** (if configured)
+
+    **npm:**
+
+    ```bash
+    npm publish --access public
+    # Or for scoped packages:
+    npm publish @scope/package --access public
+    ```
+
+    **PyPI:**
+
+    ```bash
+    python -m build
+    twine upload dist/*
+    ```
+
+    **Docker Hub:**
+
+    ```bash
+    docker build -t user/image:{new_version} .
+    docker push user/image:{new_version}
+    docker tag user/image:{new_version} user/image:latest
+    docker push user/image:latest
+    ```
+
+    **GitHub Packages:**
+
+    ```bash
+    docker tag image:latest ghcr.io/user/repo:{new_version}
+    docker push ghcr.io/user/repo:{new_version}
+    ```
+
+13. **Verify Publication**
+    - Check package registry for new version
+    - Test installation: `npm install package@{new_version}`
+    - Confirm download count increments
+
+### Phase 6: Post-Release Tasks (2 min)
+
+14. **Update Documentation**
+    - If docs versioned, create new version folder
+    - Update README badges (version, downloads)
+    - Update CHANGELOG.md link in README
+
+15. **Create Release Announcement**
+    - Generate social media posts
+    - Update project website (if applicable)
+    - Send notification to mailing list / Discord / Slack
+
+16. **Create Post-Release Report**
+    - Summary of changes
+    - Links to release, packages, documentation
+    - Next steps or planned features
+
+## Checklist
+
+### Pre-conditions
+
+- [ ] On correct release branch
+  - **Validation**: `git branch --show-current === release_branch`
+  - **Error**: "Not on release branch. Switch to {release_branch} first."
+
+- [ ] No uncommitted changes
+  - **Validation**: `git status --porcelain` returns empty
+  - **Error**: "Uncommitted changes detected. Commit or stash before releasing."
+
+- [ ] CI passing (unless skip_ci=true)
+  - **Validation**: GitHub API check status
+  - **Error**: "CI checks failing. Fix before releasing or use --skip-ci for emergency."
+
+- [ ] New commits since last release
+  - **Validation**: `git log {last_tag}..HEAD` not empty
+  - **Error**: "No new commits since last release. Nothing to release."
+
+### Post-conditions
+
+- [ ] Git tag created and pushed
+  - **Validation**: `git tag -l v{new_version}` exists remotely
+  - **Test**: `git ls-remote --tags origin | grep v{new_version}`
+
+- [ ] CHANGELOG.md updated
+  - **Validation**: File contains new version section
+  - **Test**: `grep "## \[{new_version}\]" CHANGELOG.md`
+
+- [ ] GitHub Release created
+  - **Validation**: `gh release view v{new_version}` succeeds
+  - **Test**: Visit `{release_url}` and verify
+
+- [ ] Package published (if configured)
+  - **Validation**: Package registry returns new version
+  - **Test**: `npm view package version` === `{new_version}`
+
+### Acceptance Criteria
+
+- [ ] Release follows semantic versioning
+  - **Type**: acceptance
+  - **Test**: Version format is `{major}.{minor}.{patch}` or `{major}.{minor}.{patch}-{prerelease}`
+
+- [ ] Changelog is accurate and complete
+  - **Type**: acceptance
+  - **Manual Check**: true
+  - **Criteria**: All significant changes documented
+
+- [ ] Package is installable
+  - **Type**: acceptance
+  - **Test**: Fresh install succeeds: `npm install -g package@{new_version}`
+
+## Templates
+
+### Release Notes Template
+
+````markdown
+# Release v{new_version}
+
+**Date**: {release_date}
+**Type**: {release_type} ({major|minor|patch})
+
+## Highlights
+
+{top_3_most_impactful_changes}
+
+## What's Changed
+
+{changelog_content}
+
+## Breaking Changes
+
+{breaking_changes_section if any}
+
+### Migration Guide
+
+{migration_steps if breaking changes}
+
+## Contributors
+
+Thank you to all contributors who made this release possible:
+
+{contributor_list with GitHub handles}
+
+## Install
+
+\`\`\`bash
+npm install {package_name}@{new_version}
+
+# or
+
+pip install {package_name}=={new_version}
+\`\`\`
+
+## Links
+
+- [Full Changelog]({compare_url})
+- [Documentation]({docs_url})
+- [Issues]({issues_url})
+
+---
+
+## 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 (grimoire Task Format V1.0)
+
+```yaml
+task: releaseManagement()
+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"
+```
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** execute-task.js
+  - **Purpose:** Generic task execution wrapper
+  - **Language:** JavaScript
+  - **Location:** .grimoire/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
+```
+
+---
+
+**Full Changelog**: {compare_url}
+
+```
+
+### Social Media Announcement Template
+
+```
+
+🚀 {package_name} v{new_version} is out!
+
+{highlight_1}
+{highlight_2}
+{highlight_3}
+
+Install: npm install {package_name}@{new_version}
+
+Release notes: {release_url}
+
+#opensource #release #{package_name}
+
+````
+
+## Tools
+
+- **github-cli**:
+  - **Version**: 2.0.0
+  - **Used For**: Create releases, tags, manage repository
+  - **Required**: true
+
+- **semantic-release**:
+  - **Version**: 20.0.0
+  - **Used For**: Automate versioning based on commits
+  - **Optional**: true (can use manual versioning)
+
+- **conventional-changelog**:
+  - **Version**: 4.0.0
+  - **Used For**: Generate CHANGELOG from Conventional Commits
+  - **Optional**: true
+
+## Performance
+
+- **Duration Expected**: 15 minutes (including publishing)
+- **Cost Estimated**: $0 (uses free GitHub Actions, public registries)
+- **Cacheable**: false (each release is unique)
+- **Parallelizable**: false (sequential process required)
+
+## Error Handling
+
+- **Strategy**: abort
+- **Fallback**: N/A (releases cannot be partially done)
+- **Retry**:
+  - **Max Attempts**: 2 (for network failures)
+  - **Backoff**: linear
+  - **Backoff MS**: 5000
+- **Abort Workflow**: true (release must succeed completely or rollback)
+- **Notification**: log + email + Slack (if configured)
+- **Rollback**: If publish fails, delete Git tag and revert version bump commit
+
+## Metadata
+
+- **Story**: Epic 10 (Critical Dependency Resolution)
+- **Version**: 1.0.0
+- **Dependencies**: `github-cli`, optional: `semantic-release`
+- **Author**: Brad Frost Clone
+- **Created**: 2025-11-13
+- **Updated**: 2025-11-13
+- **Breaking Changes**: None (new task)
+
+---
+
+## Usage Examples
+
+### Example 1: Automatic Semantic Release
+
+```bash
+grimoire activate Otto  # github-devops agent
+grimoire release create --repo="." --type="auto"
+````
+
+**Output**: Analyzes commits, determines version bump, creates release
+
+### Example 2: Major Release (Breaking Changes)
+
+```bash
+grimoire release create \
+  --repo="." \
+  --type="major" \
+  --publish="npm,docker-hub"
+```
+
+**Output**: Major version bump (e.g., 2.1.3 → 3.0.0), publishes to npm + Docker
+
+### Example 3: Prerelease (Beta)
+
+```bash
+grimoire release create \
+  --repo="." \
+  --type="prerelease" \
+  --prerelease-tag="beta" \
+  --branch="develop"
+```
+
+**Output**: Beta release (e.g., 2.2.0-beta.1)
+
+### Example 4: Dry Run (Test Release Process)
+
+```bash
+grimoire release create \
+  --repo="." \
+  --type="minor" \
+  --dry-run=true
+```
+
+**Output**: Simulates release, shows what would be created, NO actual changes
+
+---
+
+## Conventional Commits Reminder
+
+For automatic versioning, follow **Conventional Commits** format:
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+**Types:**
+
+- `feat:` - New feature (MINOR bump)
+- `fix:` - Bug fix (PATCH bump)
+- `docs:` - Documentation only
+- `style:` - Code style changes (formatting)
+- `refactor:` - Code refactoring
+- `perf:` - Performance improvements
+- `test:` - Adding tests
+- `chore:` - Maintenance tasks
+
+**Breaking Changes:**
+
+- Add `!` after type: `feat!: ...` (MAJOR bump)
+- Or add `BREAKING CHANGE:` in footer (MAJOR bump)
+
+**Examples:**
+
+```
+feat(auth): add OAuth2 login support
+
+Implements OAuth2 authentication flow for GitHub, Google, and Microsoft.
+
+Closes #42
+```
+
+```
+fix(api): correct timezone handling in date filters
+
+Previously, date filters were not respecting user timezone settings.
+
+Fixes #41
+```
+
+```
+feat!: rename /v1/users to /v2/users
+
+BREAKING CHANGE: API endpoint changed. Update all client calls.
+
+Migration: Replace /v1/users with /v2/users in API calls.
+```
+
+---
+
+**Related Tasks:**
+
+- `ci-cd-configuration` - Set up CI to run before releases
+- `pr-automation` - Help users create PRs with proper commit formats
+
+