chore(release): bump framework and 8 skills to v4.1.0 (MINOR — OpenCode AI agent integration)
This commit is contained in:
@@ -1,94 +1,97 @@
|
||||
# 📦 Version Upgrade Recommendation: v3.1.0 → Next Release
|
||||
# 📦 Version Upgrade Recommendation: v4.0.0 → v4.1.0 (OpenCode AI Agent Integration)
|
||||
|
||||
## Rev.2 Changelog (Job `ec388212`)
|
||||
|
||||
`creator-agy-01` filed an architectural challenge (job `53b96f7a`) against Rev.1's §6 implementation checklist — not against the v4.0.0 consensus itself, which it explicitly reaffirmed. Both points were independently re-verified against the live codebase (not accepted at face value) and **both accepted, no `[REBUT:]` filed**:
|
||||
|
||||
1. **`VERSIONS.md:24` prose desync**: confirmed the lockstep test (`tests/test_version_consistency.py`) only regex-matches the "현재 버전 개요" header line and the 8-row skill matrix table — it does not check the free-text sentence on line 24 ("모든 8개 스킬은 ... `v3.1.0`으로 동기화되어 배포됩니다."). A literal-minded execution of Rev.1's §6 item 2 would leave that sentence stuck at `v3.1.0`, contradicting the header two lines above it. **Fixed**: §6 item 2 now names line 24 explicitly.
|
||||
2. **Orphaned `cline` session rows surviving the upgrade**: confirmed `deploy/update.sh` explicitly backs up and restores `.mam/agent-sessions.*` across an update (lines 111–166) — user session state is never wiped. Confirmed `lib_py/agents/registry.py::agent_of_row()` returns `None` for any row with `agent: cline` once the adapter is deregistered (its explicit-field fast path only matches keys still in `_ADAPTERS`). Confirmed `multi-agent-mux-resume/scripts/resume_session.sh` hard-rejects `--agent cline` with `exit 2` post-removal. I additionally verified the *fix* is actionable: `multi-agent-mux-stop/scripts/stop_session.sh` already handles a dead herdr pane ("herdr already dead, just updating YAML") and exposes `--purge-conversation`, but its own `--agent` whitelist is narrowed too — so purge-via-adapter is only possible **before** upgrading, while cline's adapter still exists. For rows already orphaned post-upgrade (adapter gone, so no artifact-path resolution is possible), the safe path is a YAML-only prune through the existing locked/atomic primitive (`lib.sh::atomic_dump_yaml`, confirmed it execs a caller-supplied Python mutation against the `d` dict under an `flock` + SQLite transaction — this is the same primitive every other script in this skill uses, not a new mechanism). **Fixed**: §6 item 2 now gives both a pre-upgrade and a post-upgrade concrete command.
|
||||
- **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`)
|
||||
|
||||
---
|
||||
|
||||
- **Job**: `a348e91c` (Planner: `planner-reviewer-claude-01`) · Refined under challenge in job `ec388212`
|
||||
- **Current version**: `v3.1.0` (`MAM_VERSION` in `.agents/skills/lib.sh:32`, lockstep with `VERSIONS.md` and 8 `SKILL.md` frontmatters — see `tests/test_version_consistency.py`)
|
||||
- **Method**: Real multi-agent consensus. Three independent sub-jobs were delegated over MQTT to live herdr sessions — `reviewer-creator-grok-01` (job `e0838148`), `reviewer-hermes-01` (job `baeb9f1c`), and `creator-agy-01` (job `05d8432b`) — each asked to form its own SemVer 2.0.0 recommendation and verify the underlying facts itself (not take this brief's framing at face value). All three reports are archived at `.mam/jobs/{e0838148,baeb9f1c,05d8432b}/*-reports/report-final.md`. This document synthesizes their findings plus my own independent verification.
|
||||
## 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:
|
||||
|
||||
## 1. Changes Under Evaluation
|
||||
|
||||
Two feature branches landed on `main` since the `v3.1.0` release tag (`4a3328d`):
|
||||
|
||||
| Commit | Change | Nature |
|
||||
| Commit / Scope | Change Description | Nature |
|
||||
|---|---|---|
|
||||
| `6208a7f` / merged `e0c0c10` | Hermes agent full modernization + Ollama live support: headless flags, TUI input-region delimiters, ready-token hardening, `reconcile.sh`/`verify_artifact()` C-ambiguous fix, `discover()` multi-candidate parity | Purely additive. `--agent hermes` already existed; no documented surface shrank. |
|
||||
| `f57cd5c` | Cline agent deprecation and complete removal: `adapters/cline.py` deleted, unregistered from `registry.py`, `--agent cline` rejected in `create_session.sh` and all 8 skill scripts, `lib.sh` narrowed to 4 agents, docs/tests updated (439/439 passing, verified in job `20d45d12`) | Removes a previously-valid, documented public value. |
|
||||
| `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 |
|
||||
|
||||
`cline` has been a first-class, documented `--agent` value since **v1.2.0** (2026-08-14, `VERSIONS.md`: "Cline 에이전트 통합") — roughly 14 releases of history. Post-`f57cd5c`, any invocation of `--agent cline` (script, saved `.mam/agent-sessions.yaml` row, delegate-job call, muscle memory) now fails outright with a non-zero exit.
|
||||
*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. The Question
|
||||
---
|
||||
|
||||
Under **SemVer 2.0.0** (https://semver.org/), does this pair of changes warrant:
|
||||
- **v4.0.0** (MAJOR — incompatible/breaking public-API change), or
|
||||
- **v3.2.0** (MINOR — additive functionality only)?
|
||||
## 2. Semantic Versioning (SemVer 2.0.0) Analysis
|
||||
|
||||
## 3. Independent Reviewer Recommendations
|
||||
Under **SemVer 2.0.0** (https://semver.org/):
|
||||
|
||||
| Reviewer | Session | Job | Recommendation | Core argument |
|
||||
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 |
|
||||
|---|---|---|---|---|
|
||||
| `reviewer-creator-grok-01` | herdr:reviewer-creator-grok-01 | `e0838148` | **v4.0.0** | `--agent` is the CLI's public API surface (documented in `--help`, `SKILL.md`, install guides); removing a documented value is a §8 incompatible change regardless of live caller count; hermes-only would be 3.2.0, but the highest-severity change in a release governs. |
|
||||
| `reviewer-hermes-01` | herdr:reviewer-hermes-01 | `baeb9f1c` | **v4.0.0** | Same §8 reasoning, plus: no deprecation window was offered (straight from documented-and-supported in v3.1.0 to deleted in the very next changeset), which strengthens rather than weakens the MAJOR case since SemVer's MINOR-for-deprecation escape hatch was never used; `VERSIONS.md`'s own precedent (adding cline in v1.2.0 was MINOR) mirrors removing it as the opposite-polarity, same-magnitude change. |
|
||||
| `creator-agy-01` | herdr:creator-agy-01 | `05d8432b` | **v4.0.0** | Public API is established by the documented CLI flag surface, not by a package-registry presence; caller-popularity and "low active usage" are explicitly irrelevant under SemVer's compatibility-only test. |
|
||||
| `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. |
|
||||
|
||||
**Result: 3/3 unanimous, independently derived (no cross-contamination — each session verified the underlying commits itself via `git show f57cd5c --stat`, `VERSIONS.md` history, and/or `create_session.sh`'s own argument whitelist rather than trusting the brief's summary).**
|
||||
**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. My Own Verification
|
||||
---
|
||||
|
||||
I independently confirmed the load-bearing facts before accepting the consensus:
|
||||
## 4. Final Recommendation
|
||||
|
||||
- `git show f57cd5c --stat` confirms the full deletion scope: `adapters/cline.py` removed, `registry.py` unregistered, `lib.sh` and all 9 skill scripts narrowed, `atomic_yaml.py`/`verify_session.py`/`workspace_uuid.py` key maps narrowed to 4 agents. This was independently reviewed end-to-end in job `20d45d12` (`[VERDICT: PASS]`, 439/439 tests passing, zero orphaned references).
|
||||
- `VERSIONS.md`'s own changelog history treats `--agent` enumeration changes as release-worthy events at every prior step (v1.2.0 added cline as MINOR; v3.0.0's agent-registry expansion was bundled into a MAJOR release for other reasons) — so there's no internal precedent for treating this specific surface as "not really public."
|
||||
- No deprecation cycle exists on `main`: `f57cd5c`'s own commit message is "deprecate and **completely remove**" in one step, confirming SemVer §7's minor-level deprecation warning path was skipped entirely.
|
||||
# **→ v4.1.0 (MINOR)**
|
||||
|
||||
I concur with the consensus: **the counter-argument ("MAM is an internal, single-repo tool, so `--agent` isn't really public API") does not hold.** SemVer 2.0.0 §1 defines the public API as whatever a project declares "in code, in documentation, or both" — it has no registry-distribution requirement and no caller-count threshold. MAM declares `--agent` exhaustively (help text, `SKILL.md`, `VERSIONS.md`, install guides) and enforces it at parse time; that is a public API by the spec's own definition, independent of how many external consumers currently exist.
|
||||
- **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. Consensus Recommendation
|
||||
---
|
||||
|
||||
# **→ v4.0.0 (MAJOR)**
|
||||
## 5. Version Bump Implementation Checklist
|
||||
|
||||
- Hermes modernization alone: would be MINOR (v3.2.0).
|
||||
- Cline removal alone or bundled with hermes: MAJOR (v4.0.0) — per SemVer's "a release MAY also include minor and patch level changes" rule, the highest-severity change in a release governs the release-level version, and MINOR/PATCH reset to 0.
|
||||
- Labeling this release `v3.2.0` would misrepresent a breaking CLI/config change as backward-compatible, which is precisely the failure mode SemVer exists to prevent.
|
||||
To execute the `v4.1.0` release, the repository's **3-way version lockstep** (`tests/test_version_consistency.py`) must be updated in unison:
|
||||
|
||||
## 6. Implementation Checklist for the Bump
|
||||
|
||||
This repo enforces a **3-way version lockstep** (`tests/test_version_consistency.py::test_three_way_version_lockstep`), so a version bump is not a single edit. All three must move to `4.0.0` together or the lockstep test fails:
|
||||
|
||||
1. **`.agents/skills/lib.sh:32`** — `MAM_VERSION="3.1.0"` → `MAM_VERSION="4.0.0"` (runtime source of truth; env-override-proof per `test_mam_version_is_not_env_overridable`).
|
||||
1. **`.agents/skills/lib.sh:32`**:
|
||||
- Update runtime version: `MAM_VERSION="4.1.0"`
|
||||
2. **`VERSIONS.md`**:
|
||||
- "현재 버전 개요" header: `**프레임워크 버전**: \`v3.1.0\`` → `v4.0.0`, update release date.
|
||||
- **Line 24 prose** (not caught by the lockstep test's regex): `"...v3.1.0으로 동기화되어 배포됩니다."` → `"...v4.0.0으로 동기화되어 배포됩니다."` — must be edited by hand alongside the header, since `test_three_way_version_lockstep` never inspects this sentence.
|
||||
- Skill matrix table (8 rows): every `| \`3.1.0\` |` cell → `| \`4.0.0\` |`.
|
||||
- New `### v4.0.0` changelog section, following the project's own `⚠️ 동작 변경 및 마이그레이션 안내` (breaking-change/migration notice) convention already used for v3.1.0's B-1…B-5 entries. Document, in order:
|
||||
- **What broke**: `--agent cline` removed from every entry point (`create_session.sh`, `resume_session.sh`, `stop_session.sh`, `reconcile.sh`, delegate-job, etc.).
|
||||
- **Detect impact**: `grep -rn "agent: cline\|cline_conversation_id_own\|--agent cline" .mam/ *.sh 2>/dev/null` across saved configs/scripts.
|
||||
- **Pre-upgrade cleanup (preferred — do this on v3.1.0, before running `deploy/update.sh`)**: for any live or resumable cline session, run `multi-agent-mux-stop --session <name> --agent cline --purge-conversation --yes` — this still works pre-upgrade (the adapter and its `--agent` whitelist entry are both still present), cleanly removing both the on-disk conversation artifact and the YAML row via the normal, tested stop path.
|
||||
- **Post-upgrade cleanup (for rows nobody purged beforehand)**: `deploy/update.sh` preserves `.mam/agent-sessions.*` verbatim across the upgrade, and once on v4.0.0 the cline adapter no longer exists, so `--agent cline` is rejected everywhere and there is no artifact-aware purge path left — only a YAML-only prune is possible:
|
||||
```bash
|
||||
source .agents/skills/lib.sh
|
||||
atomic_dump_yaml .mam/agent-sessions.yaml <<'MUT'
|
||||
d['herdr_sessions'] = [
|
||||
s for s in d.get('herdr_sessions', [])
|
||||
if s.get('agent') != 'cline' and not str(s.get('name', '')).endswith('-cline')
|
||||
]
|
||||
MUT
|
||||
```
|
||||
This reuses the existing locked/atomic write primitive (`flock` + SQLite transaction inside `atomic_dump_yaml_main()`) that every other skill script already uses — no new tooling. It does not delete on-disk conversation artifacts (those are orphaned, not corrupting anything); it only removes the now-unresolvable registry rows so `reconcile.sh`/`status.sh` stop reporting drift on them.
|
||||
- **No forward migration for the adapter itself**: git history is the only way to recover `adapters/cline.py` if cline support is ever needed again.
|
||||
3. **8× `SKILL.md` frontmatter** (`version: 3.1.0` → `version: 4.0.0`) in: `multi-agent-mux-create`, `multi-agent-mux-stop`, `multi-agent-mux-resume`, `multi-agent-mux-status`, `multi-agent-mux-monitor`, `multi-agent-mux-delegate-job`, `multi-agent-mux-loop`, `multi-agent-mux-orc-onboard`.
|
||||
4. Run `tests/test_version_consistency.py` after the edits to confirm lockstep holds before the release commit.
|
||||
5. Recommended commit style, consistent with existing history (`4a3328d chore(release): bump framework and 8 skills to v3.1.0 (MINOR)`): `chore(release): bump framework and 8 skills to v4.0.0 (MAJOR — cline removal)`.
|
||||
- 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)`
|
||||
|
||||
No other file in the repo hardcodes the version literal (`create_session.sh` only echoes `${MAM_VERSION:-unknown}` at runtime — confirmed via grep), so this is the complete edit surface.
|
||||
|
||||
[VERDICT: N/A — consensus/planning artifact, not a code review]
|
||||
---
|
||||
[VERDICT: CONSENSUS REACHED — v4.1.0 (MINOR)]
|
||||
|
||||
Reference in New Issue
Block a user