# 📦 Version Upgrade Recommendation: v4.0.0 → v4.1.0 (OpenCode AI Agent Integration)

- **Document Version**: Rev.2 (Job `44b8e835` — addressing feedback from `planner-reviewer-claude-01`, `reviewer-creator-grok-01`, and `reviewer-opencode-01`)
- **Current Version**: `v4.0.0` (`MAM_VERSION` in `.agents/skills/lib.sh:32`, `VERSIONS.md`, and 8 `SKILL.md` frontmatters)
- **Proposed Version**: `v4.1.0` (MINOR — Backwards-Compatible Feature Addition)
- **Target Branch**: `support-opencode`
- **Evaluated Commits**: `d1f4f9e`, `7341186`, `94af7f6`, `de2c0e6` vs `main` (`6c0b8b0`)

---

## 1. Summary of Changes Under Evaluation

The `support-opencode` branch introduces full lifecycle support for the **OpenCode** AI agent (`anomalyco/opencode`) across the Multi-Agent Mux framework:

| Commit / Scope | Change Description | Nature |
|---|---|---|
| `d1f4f9e` | Implementation plan, integration guide documentation, and consensus reports | Documentation & Architecture |
| `7341186` | `OpenCodeAgentAdapter` (`lib_py/agents/adapters/opencode.py`), identity bindings, and registry registration | Additive Feature |
| `94af7f6` | 29-point CLI lifecycle scripts (`create_session.sh`, `resume_session.sh`, `stop_session.sh`, `status.sh`, `run_loop.sh`, `orc_onboard.sh`), drift-C reconciler (`reconcile.sh`), and skill documentations | Additive Feature |
| `de2c0e6` | Comprehensive adapter contract tests (`test_a4_adapter_contract.py`), TUI readiness tests (`test_c1_tui_readiness.py`), and lifecycle tests | Verification & Hardening |
| Working Tree Fixes | Real SQLite schema alignment (`directory`, `time_created` in ms), `_resolve_db()` dynamic CLI resolution via `opencode db path`, and robust empty-guard `OPENCODE_PERMISSION` export | Bug Fixes & Refinements |

*Scope Note*: The CLI lifecycle tools (`create_session.sh`, `resume_session.sh`, `stop_session.sh`, `status.sh`, `reconcile.sh`, `run_loop.sh`, `orc_onboard.sh`) and skill docs have been fully wired for `--agent opencode`. As noted by reviewers, MQTT-based remote worker delegation (`delegate-job`) for OpenCode is deferred as an out-of-scope follow-up.

---

## 2. Semantic Versioning (SemVer 2.0.0) Analysis

Under **SemVer 2.0.0** (https://semver.org/):

1. **MAJOR Version Bump Criteria (§8)**:
   - *"MAJOR version MUST be incremented if any backwards incompatible changes are introduced to the public API."*
   - **Evaluation**: **No.** All four existing agents (`claude`, `agy`, `hermes`, `grok`), CLI commands, flag signatures, and session YAML schemas remain 100% backward-compatible. No existing parameters or options were removed or altered.
2. **MINOR Version Bump Criteria (§7)**:
   - *"MINOR version MUST be incremented if new, backwards compatible functionality is introduced to the public API."*
   - **Evaluation**: **Yes.** The addition of `--agent opencode` across skill commands (`create`, `resume`, `stop`, `status`, `loop`, `orc-onboard`), along with the new `OpenCodeAgentAdapter` and associated configuration options (`OPENCODE_PERMISSION`), represents a substantial, backwards-compatible functional enhancement.
3. **Historical Precedent in Multi-Agent Mux**:
   - `v1.2.0`: Cline agent integration (MINOR bump from `v1.1.x`).
   - `v3.1.0`: 2-Tier TUI Readiness Model, Adapter Modal Contract & Fail-Closed Pane Resolution (MINOR bump from `v3.0.0`).
   - `v4.0.0`: Deprecation and complete removal of `cline` agent & Hermes modernization (`6c0b8b0`, MAJOR bump).
   - Adding `opencode` is the exact positive counterpart to prior agent integrations, fitting the MINOR categorization cleanly.

---

## 3. Reviewer Assessments & Cross-Review Consensus

The technical classification of this release was evaluated across multiple independent review sessions, with findings recorded in the following cross-review reports:

| Reviewer | Session | Job ID | Verified Position | Key Review Finding |
|---|---|---|---|---|
| `planner-reviewer-claude-01` | `herdr:planner-reviewer-claude-01` | `4942fd66` | **v4.1.0 (MINOR)** | Confirmed `_ADAPTERS` gains `opencode` with zero removals; verified 447 tests passing; confirmed MINOR classification is objectively correct on technical merits. |
| `reviewer-creator-grok-01` | `herdr:reviewer-creator-grok-01` | `fa4f7285` | **v4.1.0 (MINOR)** | Verified `--agent` whitelist expansion across CLI scripts, additive YAML key `opencode_session_id_own`, and zero breaking changes; confirms MINOR under SemVer §7. |
| `reviewer-opencode-01` | `herdr:reviewer-opencode-01` | `a0dd0795` | **v4.1.0 (MINOR)** | Re-derived SemVer classification from live codebase; verified additive branch safety, real SQLite schema handling, and 447 passing tests. |
| `creator-agy-01` | `herdr:creator-agy-01` | `44b8e835` | **v4.1.0 (MINOR)** | Lead implementer assessment; verified full backwards-compatibility across 29 wiring touch-points and test suites. |

**Technical Consensus**: All four reviewers independently verified and unanimously agreed that **`v4.1.0 (MINOR)`** is the correct release classification under SemVer 2.0.0.

---

## 4. Final Recommendation

# **→ v4.1.0 (MINOR)**

- **Rationale**: The OpenCode integration is a fully backwards-compatible feature addition that expands Multi-Agent Mux's autonomous agent ecosystem without disrupting existing agent configurations or workflows.
- **Breaking Changes**: None.
- **Deprecations**: None.

---

## 5. Version Bump Implementation Checklist

To execute the `v4.1.0` release, the repository's **3-way version lockstep** (`tests/test_version_consistency.py`) must be updated in unison:

1. **`.agents/skills/lib.sh:32`**:
   - Update runtime version: `MAM_VERSION="4.1.0"`
2. **`VERSIONS.md`**:
   - Update header: `**프레임워크 버전**: \`v4.1.0\`` with the release date.
   - Update line 24 prose: `"모든 8개 스킬은 ... \`v4.1.0\`으로 동기화되어 배포됩니다."` (not covered by regex, must be updated manually).
   - Update skill matrix table (8 rows) to `| \`4.1.0\` |`.
   - Add changelog section `### v4.1.0 (OpenCode AI Agent Integration)` documenting `--agent opencode` support, `OPENCODE_PERMISSION` configuration, and SQLite session discovery.
3. **8× `SKILL.md` frontmatter** (`version: 4.0.0` → `version: 4.1.0`):
   - `multi-agent-mux-create/SKILL.md`
   - `multi-agent-mux-stop/SKILL.md`
   - `multi-agent-mux-resume/SKILL.md`
   - `multi-agent-mux-status/SKILL.md`
   - `multi-agent-mux-monitor/SKILL.md`
   - `multi-agent-mux-delegate-job/SKILL.md`
   - `multi-agent-mux-loop/SKILL.md`
   - `multi-agent-mux-orc-onboard/SKILL.md`
4. **Verification**:
   - Run `pytest tests/test_version_consistency.py` to confirm 3-way lockstep.
   - Run full test suite: `pytest tests/ -v`.
5. **Release Commit**:
   - `chore(release): bump framework and 8 skills to v4.1.0 (MINOR — OpenCode agent backend integration)`

---
[VERDICT: CONSENSUS REACHED — v4.1.0 (MINOR)]