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:

       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]