chore(release): bump framework and 8 skills to v3.1.0 (MINOR)

- Define immutable MAM_VERSION="3.1.0" runtime constant in lib.sh
- Bump YAML frontmatter version to 3.1.0 across all 8 skill packages
- Document v3.1.0 changelog, 2-tier TUI readiness architecture, and migration guide in VERSIONS.md
- Document new tuning knobs (MAM_KILL_ON_READY_TIMEOUT, MAM_DIALOG_TAIL_LINES, MAM_READY_EMPTY_GIVEUP) in .mam.env.example
- Add 3-way lockstep and immutability test suite in tests/test_version_consistency.py

tests/test_version_consistency.py

@@ -0,0 +1,90 @@
+# ==============================================================================
+# test_version_consistency.py — 3-Way Version Lockstep & Immutability Test Suite
+# ==============================================================================
+import os
+import re
+import subprocess
+from pathlib import Path
+import yaml
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+LIB_SH = REPO_ROOT / ".agents" / "skills" / "lib.sh"
+VERSIONS_MD = REPO_ROOT / "VERSIONS.md"
+SKILLS_DIR = REPO_ROOT / ".agents" / "skills"
+
+SKILL_NAMES = [
+    "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",
+]
+
+
+def _get_lib_sh_mam_version():
+    cmd = f'source "{LIB_SH}" && echo "$MAM_VERSION"'
+    res = subprocess.run(["bash", "-c", cmd], capture_output=True, text=True, cwd=str(REPO_ROOT))
+    assert res.returncode == 0, f"Failed to source lib.sh: {res.stderr}"
+    return res.stdout.strip()
+
+
+def _get_versions_md_versions():
+    text = VERSIONS_MD.read_text(encoding="utf-8")
+    
+    # 1. Current release framework version
+    m_curr = re.search(r"-\s*\*\*프레임워크 버전\*\*:\s*`v(\d+\.\d+\.\d+)`", text)
+    assert m_curr, "Failed to parse Current Release framework version in VERSIONS.md"
+    current_framework_ver = m_curr.group(1)
+
+    # 2. Skill matrix table versions
+    table_matches = re.findall(r"\|\s*\*\*`([^`]+)`\*\*\s*\|\s*`(\d+\.\d+\.\d+)`\s*\|", text)
+    matrix_dict = dict(table_matches)
+    
+    return current_framework_ver, matrix_dict
+
+
+def _get_skill_md_frontmatter_version(skill_name: str):
+    skill_file = SKILLS_DIR / skill_name / "SKILL.md"
+    assert skill_file.is_file(), f"Skill file not found: {skill_file}"
+    content = skill_file.read_text(encoding="utf-8")
+    
+    # Strict frontmatter parsing
+    fm_match = re.match(r"^---\n(.*?)\n---", content, re.DOTALL)
+    assert fm_match, f"No YAML frontmatter found in {skill_file}"
+    fm_data = yaml.safe_load(fm_match.group(1))
+    assert isinstance(fm_data, dict) and "version" in fm_data, f"No version in frontmatter of {skill_file}"
+    return str(fm_data["version"])
+
+
+def test_three_way_version_lockstep():
+    """T-4: lib.sh(MAM_VERSION) == VERSIONS.md(Current + Matrix 8 items) == 8x SKILL.md frontmatters."""
+    # 1. lib.sh runtime constant
+    lib_ver = _get_lib_sh_mam_version()
+    assert lib_ver != "", "MAM_VERSION in lib.sh is empty"
+
+    # 2. VERSIONS.md
+    vmd_curr, vmd_matrix = _get_versions_md_versions()
+    assert lib_ver == vmd_curr, f"lib.sh MAM_VERSION ({lib_ver}) != VERSIONS.md current ({vmd_curr})"
+
+    for skill in SKILL_NAMES:
+        assert skill in vmd_matrix, f"Skill {skill} missing from VERSIONS.md matrix"
+        assert vmd_matrix[skill] == lib_ver, f"VERSIONS.md matrix for {skill} ({vmd_matrix[skill]}) != lib.sh ({lib_ver})"
+
+    # 3. 8x SKILL.md files
+    for skill in SKILL_NAMES:
+        fm_ver = _get_skill_md_frontmatter_version(skill)
+        assert fm_ver == lib_ver, f"{skill}/SKILL.md version ({fm_ver}) != lib.sh ({lib_ver})"
+
+
+def test_mam_version_is_not_env_overridable():
+    """T-0 (Constraint 1): MAM_VERSION cannot be spoofed by caller environment."""
+    cmd = f'source "{LIB_SH}" && echo "$MAM_VERSION"'
+    env = os.environ.copy()
+    env["MAM_VERSION"] = "9.9.9"
+    res = subprocess.run(["bash", "-c", cmd], capture_output=True, text=True, env=env, cwd=str(REPO_ROOT))
+    assert res.returncode == 0
+    assert res.stdout.strip() != "9.9.9", "MAM_VERSION was improperly overwritten by caller environment"
+    assert res.stdout.strip() == _get_lib_sh_mam_version()