multi-agent-mux/.agents/reports/version_upgrade_recommendation.md

# 📦 Version Upgrade Recommendation: v3.1.0 → Next Release

## 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.

---

- **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. Changes Under Evaluation

Two feature branches landed on `main` since the `v3.1.0` release tag (`4a3328d`):

| Commit | Change | 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. |

`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.

## 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)?

## 3. Independent Reviewer Recommendations

| Reviewer | Session | Job | Recommendation | Core argument |
|---|---|---|---|---|
| `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. |

**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).**

## 4. My Own Verification

I independently confirmed the load-bearing facts before accepting the consensus:

- `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.

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.

## 5. Consensus Recommendation

# **→ v4.0.0 (MAJOR)**

- 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.

## 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`).
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)`.

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]