From ea8f36c0c23dc1eae65a09ad1c208ad734c832af Mon Sep 17 00:00:00 2001
From: Error <foamy125@gmail.com>
Date: Wed, 19 Nov 2025 18:52:49 -0600
Subject: [PATCH] Add release process documentation and open issues triage
 guide

- Add comprehensive RELEASE_PROCESS.md with step-by-step release workflow
- Add open-issues-triage.md for systematic issue management
- Both documents support better project governance and maintenance
---
 docs/development/RELEASE_PROCESS.md | 211 ++++++++++++++++++++++++++++
 spec/open-issues-triage.md          | 187 ++++++++++++++++++++++++
 2 files changed, 398 insertions(+)
 create mode 100644 docs/development/RELEASE_PROCESS.md
 create mode 100644 spec/open-issues-triage.md

diff --git a/docs/development/RELEASE_PROCESS.md b/docs/development/RELEASE_PROCESS.md
new file mode 100644
index 0000000..cf731b5
--- /dev/null
+++ b/docs/development/RELEASE_PROCESS.md
@@ -0,0 +1,211 @@
+# Release Process Guide
+
+This guide explains our automated release workflows and how contributors should work with them.
+
+## Overview
+
+We use a two-branch release system with full automation:
+
+- **`staging`** - All feature work and release preparation happens here
+- **`main`** - Only tracks published releases (deployment tracking)
+
+## Release Workflows
+
+### 1. Staging Release Preparation (`staging-release-prep.yml`)
+
+**Trigger**: When a PR merges into `staging`
+
+**What it does**:
+
+1. **Analyzes changes** using OpenCode AI to determine release type (patch/minor/major)
+2. **Bumps version** in `package.json` and `pnpm-lock.yaml`
+3. **Creates annotated git tag** with auto-generated release notes
+4. **Commits changes** with message `chore: release v{version}`
+5. **Pushes tag** to GitHub
+6. **Hotfix handling** - If PR has `hotfix` label, automatically fast-forwards `main`
+
+**Key features**:
+
+- **Semantic versioning** based on conventional commits and change analysis
+- **Automatic release notes** generated by AI analysis
+- **Hotfix fast-path** for critical fixes
+- **No manual version bumping required**
+
+### 2. Review Response Automation (`review-response.yml`)
+
+**Trigger**: When someone comments on a PR review
+
+**What it does**:
+
+1. **Validates commenter** - Only runs for whitelisted users or repository members
+2. **Creates fix branch** - Named `review/comment-{id}-{run-id}`
+3. **Runs AI agent** - Uses OpenCode's `review-response` agent with `opencode/big-pickle` model
+4. **Generates commit** - Single commit addressing the review comment
+5. **Opens PR** - Back to the original PR's base branch
+
+**Key features**:
+
+- **Automated fixes** for review comments
+- **Isolated branches** for each review response
+- **AI-powered code generation** using the same tools as human developers
+- **Traceable PRs** linking back to original review comments
+
+## Release Flow
+
+### Normal Release Process
+
+```mermaid
+graph LR
+    A[Feature Branch] --> B[PR to staging]
+    B --> C[CI checks pass]
+    C --> D[Merge to staging]
+    D --> E[staging-release-prep triggers]
+    E --> F[Version bump + tag]
+    F --> G[Create staging→main PR]
+    G --> H[Merge to main]
+    H --> I[Release job triggers]
+    I --> J[Publish to npm]
+    I --> K[Create GitHub Release]
+```
+
+### Hotfix Process
+
+```mermaid
+graph LR
+    A[Hotfix Branch] --> B[PR to staging + hotfix label]
+    B --> C[CI checks pass]
+    C --> D[Merge to staging]
+    D --> E[staging-release-prep triggers]
+    E --> F[Version bump + tag]
+    F --> G[Auto fast-forward main]
+    G --> H[Immediate release]
+```
+
+## Branch Rules
+
+### `staging` Branch
+
+- **All feature work** targets `staging`
+- **Every merge** creates a release commit/tag
+- **No direct commits** - only via PR merges
+- **Release preparation** happens automatically
+
+### `main` Branch
+
+- **Deployment tracking only** - no direct development
+- **Fast-forward merges only** from `staging`
+- **Protected by** `main-merge-guard` workflow
+- **Release commits** trigger npm publication
+
+## Required Secrets
+
+### `OPENCODE_API_KEY`
+
+- **Used by**: `staging-release-prep` for release analysis
+- **Create with**: `opencode auth token create --label "ci-release" --scopes responses.create`
+- **Optional**: `OPENCODE_API_URL` for self-hosted endpoints
+
+### `NPM_TOKEN`
+
+- **Used by**: `release` job for publishing
+- **Create with**: npm automation token from npmjs.com
+- **Scope**: Must have publish permissions for `@openhax/codex`
+
+## For Contributors
+
+### How to Release Features
+
+1. **Create feature branch** from `staging`
+2. **Develop and test** your changes
+3. **Open PR** to `staging` with clear description
+4. **Address reviews** - AI will automatically help with review comments
+5. **Merge to staging** - This automatically creates a release commit
+6. **Create deployment PR** - `staging → main` (maintainers only)
+7. **Merge to main** - This triggers npm publication
+
+### Hotfix Process
+
+1. **Create hotfix branch** from `staging`
+2. **Fix the issue** and test thoroughly
+3. **Open PR to staging** with `hotfix` label
+4. **Merge to staging** - This automatically fast-forwards `main` and releases
+
+### Review Comment Handling
+
+- **Anyone can request changes** in PR reviews
+- **AI automatically responds** to review comments from:
+  - Repository members (`OWNER`, `MEMBER`, `COLLABORATOR`)
+  - Whitelisted users (`coderabbitai`, `riatzukiza`)
+- **Fix PRs are created** automatically with single commits
+- **Human review** still required before merging fix PRs
+
+## Local Development
+
+### Testing Release Analysis
+
+```bash
+# Preview what release type will be generated
+OPENCODE_API_KEY=your-key node scripts/detect-release-type.mjs --output release-analysis.json
+cat release-analysis.json
+```
+
+### Syncing Secrets
+
+```bash
+# Export secrets locally
+export NPM_TOKEN=your-npm-token
+export OPENCODE_API_KEY=your-opencode-key
+
+# Sync to repository (dry run first)
+pnpm sync:secrets -- --dry-run
+pnpm sync:secrets
+```
+
+## Troubleshooting
+
+### Release Issues
+
+- **Analyzer fails**: Check `OPENCODE_API_KEY` validity and network connectivity
+- **Version conflicts**: Ensure only one release commit is queued at a time
+- **Hotfix not promoting**: Verify `hotfix` label is applied before merge
+
+### Review Response Issues
+
+- **No response**: Check if commenter is in whitelist or has repository permissions
+- **Wrong fixes**: Review the generated commit in the auto-created PR
+- **Missing permissions**: Ensure workflow has `contents: write` and `pull-requests: write`
+
+### Publishing Issues
+
+- **npm 403**: Verify `NPM_TOKEN` has automation scope and package ownership
+- **Tag conflicts**: Ensure tags are properly created in `staging-release-prep`
+
+## Configuration
+
+### Release Analysis Customization
+
+- **Base reference**: Set `RELEASE_BASE_REF` to override diff starting point
+- **Custom models**: Modify `scripts/detect-release-type.mjs` for different analysis
+- **Release notes**: Edit the analyzer prompt to change note generation
+
+### Workflow Permissions
+
+- **Contents**: Write (for commits, tags, and releases)
+- **Pull requests**: Write (for review response PRs)
+- **Actions**: Read (for workflow triggers)
+
+## Best Practices
+
+1. **Conventional commits** help the analyzer determine correct release types
+2. **Clear PR descriptions** improve release note quality
+3. **Test thoroughly** before merging to `staging` - every merge creates a release
+4. **Use hotfix label** sparingly for critical fixes only
+5. **Monitor release PRs** to ensure correct versions and notes
+6. **Keep secrets updated** and test them regularly
+
+## Related Documentation
+
+- [CI, Mutation Testing, and Release Automation](./development/ci.md) - Technical CI details
+- [Architecture](./development/ARCHITECTURE.md) - Plugin architecture overview
+- [Contributing Guidelines](../CONTRIBUTING.md) - General contribution process
+- [Configuration](./configuration.md) - Plugin configuration options
diff --git a/spec/open-issues-triage.md b/spec/open-issues-triage.md
new file mode 100644
index 0000000..869d84c
--- /dev/null
+++ b/spec/open-issues-triage.md
@@ -0,0 +1,187 @@
+# Open Issues Triage Analysis
+
+**Date**: 2025-11-19  
+**Repository**: open-hax/codex  
+**Total Open Issues**: 10
+
+## Proposed Labels
+
+### Topic Labels
+
+- `authentication` - OAuth, token management, cache file conflicts
+- `session-management` - SessionManager, prompt cache keys, fork handling
+- `compaction` - Conversation compaction, summary handling
+- `model-support` - New model variants, normalization
+- `metrics` - Request inspection, performance metrics
+- `documentation` - README updates, package naming
+
+### Priority Labels
+
+- `priority-high` - Breaking bugs, critical functionality
+- `priority-medium` - Important features, significant improvements
+- `priority-low` - Minor enhancements, documentation fixes
+
+### Effort Labels
+
+- `effort-small` - < 4 hours, simple changes
+- `effort-medium` - 4-12 hours, moderate complexity
+- `effort-large` - > 12 hours, complex implementation
+
+---
+
+## Issue Triage Details
+
+### #26: Feature: Add support for GPT-5.1-Codex-Max model
+
+**Labels**: `model-support`, `priority-medium`, `effort-small`  
+**Related Files**:
+
+- `lib/request/request-transformer.ts:217-244` - Model normalization logic
+- `test/request-transformer.test.ts:50-120` - Model normalization tests
+
+### #25: [BUG] Plugin fails with confusing errors if started with the other oauth plugin's cache files
+
+**Labels**: `authentication`, `priority-high`, `effort-medium`  
+**Related Files**:
+
+- `lib/auth/auth.ts:31-69` - Token validation and refresh logic
+- `lib/cache/session-cache.ts` - Cache file handling
+- `lib/prompts/codex.ts:79-146` - Cache file operations
+
+### #24: Tests: clarify extractTailAfterSummary semantics in codex-compaction
+
+**Labels**: `compaction`, `priority-low`, `effort-small`  
+**Related Files**:
+
+- `lib/compaction/codex-compaction.ts:119` - extractTailAfterSummary function
+- `test/codex-compaction.test.ts:86-93` - Related tests
+
+### #23: SessionManager: align fork identifier with prompt cache fork hints
+
+**Labels**: `session-management`, `priority-medium`, `effort-medium`  
+**Related Files**:
+
+- `lib/session/session-manager.ts:139-395` - SessionManager implementation
+- `lib/request/request-transformer.ts:755-925` - Fork handling and cache key logic
+- `test/session-manager.test.ts:161-181` - Fork session tests
+
+### #22: Compaction heuristics: prefer explicit metadata flag for OpenCode prompts
+
+**Labels**: `compaction`, `priority-medium`, `effort-medium`  
+**Related Files**:
+
+- `lib/request/request-transformer.ts:442-506` - OpenCode prompt filtering
+- `lib/compaction/codex-compaction.ts` - Compaction logic
+- `test/request-transformer.test.ts:596-624` - Compaction integration tests
+
+### #21: Compaction: make extractTailAfterSummary summary-aware
+
+**Labels**: `compaction`, `priority-medium`, `effort-medium`  
+**Related Files**:
+
+- `lib/compaction/codex-compaction.ts:119` - Core function
+- `lib/compaction/compaction-executor.ts:1-45` - Compaction execution
+- `test/codex-compaction.test.ts:86-93` - Function tests
+
+### #6: Feature: richer Codex metrics and request inspection commands
+
+**Labels**: `metrics`, `priority-medium`, `effort-large`  
+**Related Files**:
+
+- `lib/commands/codex-metrics.ts:1-343` - Metrics command implementation
+- `lib/cache/cache-metrics.ts` - Cache metrics collection
+- `test/codex-metrics-command.test.ts:1-342` - Comprehensive tests
+
+### #5: Feature: Codex-style conversation compaction and auto-compaction in plugin
+
+**Labels**: `compaction`, `priority-high`, `effort-large`  
+**Related Files**:
+
+- `lib/compaction/compaction-executor.ts:1-45` - Auto-compaction logic
+- `lib/request/fetch-helpers.ts:120-185` - Compaction integration
+- `lib/session/session-manager.ts:296-313` - Compaction state management
+- `test/compaction-executor.test.ts:11-131` - Compaction tests
+
+### #4: Feature: fork-aware prompt_cache_key handling and overrides
+
+**Labels**: `session-management`, `priority-high`, `effort-large`  
+**Related Files**:
+
+- `lib/request/request-transformer.ts:755-1036` - Fork-aware cache key logic
+- `lib/session/session-manager.ts:83-206` - Session ID derivation
+- `test/request-transformer.test.ts:715-850` - Cache key tests
+- `test/session-manager.test.ts:161-181` - Fork session tests
+
+### #11: Docs: Fix package name in test/README.md
+
+**Labels**: `documentation`, `priority-low`, `effort-small`  
+**Related Files**:
+
+- `test/README.md:1-4` - Package name reference
+
+---
+
+## Priority Summary
+
+### High Priority (3 issues)
+
+- #25: OAuth cache file conflicts (bug)
+- #5: Auto-compaction implementation (feature)
+- #4: Fork-aware cache keys (feature)
+
+### Medium Priority (5 issues)
+
+- #26: GPT-5.1-Codex-Max support (feature)
+- #23: SessionManager fork alignment (feature)
+- #22: Compaction metadata flags (feature)
+- #21: Summary-aware compaction (feature)
+- #6: Enhanced metrics (feature)
+
+### Low Priority (2 issues)
+
+- #24: Test clarification (maintenance)
+- #11: Documentation fix (maintenance)
+
+## Effort Distribution
+
+### Large Effort (>12 hours): 3 issues
+
+- #6: Enhanced metrics and inspection
+- #5: Auto-compaction implementation
+- #4: Fork-aware cache key handling
+
+### Medium Effort (4-12 hours): 5 issues
+
+- #25: OAuth cache file conflicts
+- #23: SessionManager fork alignment
+- #22: Compaction metadata flags
+- #21: Summary-aware compaction
+- #26: GPT-5.1-Codex-Max support
+
+### Small Effort (<4 hours): 2 issues
+
+- #24: Test clarification
+- #11: Documentation fix
+
+## Topic Distribution
+
+- Session Management: 2 issues (#4, #23)
+- Compaction: 4 issues (#5, #21, #22, #24)
+- Authentication: 1 issue (#25)
+- Model Support: 1 issue (#26)
+- Metrics: 1 issue (#6)
+- Documentation: 1 issue (#11)
+
+## Recommendations
+
+1. **Immediate Focus**: Address #25 (OAuth cache conflicts) as it's a breaking bug
+2. **Strategic Features**: Prioritize #4 and #5 for core functionality improvements
+3. **Quick Wins**: Complete #11 and #24 for immediate closure
+4. **Incremental Development**: #21, #22, #23 can be tackled in sequence as they're related
+5. **Future Enhancement**: #6 and #26 can be scheduled for future releases
+
+## Cross-Dependencies
+
+- #4 (fork-aware cache keys) enables #23 (SessionManager alignment)
+- #21 and #22 both enhance compaction heuristics and should be coordinated
+- #5 depends on improvements from #21 and #22 for optimal implementation