docs(issue-5): phase 1 benchmark results, contract mapping, task checklist

Records the measured numbers and syncs every document that names the delegation script paths, then bumps the framework to 4.3.0 in the three-way lockstep (lib.sh, VERSIONS.md current + matrix, eight SKILL.md frontmatters). phase1-benchmark.md carries both arms. The deterministic fake transport is what CI asserts on: 50 publishes cost 50 connections one-shot and 1 persistent, p50 54.813ms -> 0.002ms. The real broker run is informational, since the PoC default is a public broker: p50 1892.728ms -> 275.992ms, about 85% off. It also corrects the plan's own estimate rather than repeating it. D8 predicted the new shell path would drop from 3 forks to 2; the implementation is still 3, because keeping the `_delegate_script publish_event.py` lookup is the only thing that produces the "missing script tree does nothing" non-fatal contract that C-02 pins. Saving that fork would change the contract, so it is deferred to phase 4 rather than taken quietly. SKILL.md gains the context table saying which tree wins where, so an operator reading it knows a frozen loop runs frozen delegation code. The script paths in every document remain correct and every quoted command still works verbatim. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UrDNJkHmm18uu7n7JwV5Qd
2026-09-06 15:48:38 +09:00
1 parent a4b7b45e13
commit 508ca99d71
@@ -29,7 +29,7 @@ export WORKSPACE_ROOT
 # Framework semantic version. Single runtime source of truth; kept in lockstep
 # with VERSIONS.md and the 8 SKILL.md frontmatters by tests/test_version_consistency.py.
 # NOTE: unlike other MAM_* variables this one is intentionally NOT env-overridable.
-MAM_VERSION="4.2.0"
+MAM_VERSION="4.3.0"
 export MAM_VERSION
 AGENT_SESSIONS_YAML="${AGENT_SESSIONS_YAML:-$WORKSPACE_ROOT/.mam/agent-sessions.yaml}"

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-mux-create
 description: "Create a new agent session (claude, antigravity/agy) in a dedicated herdr session for context-preserving long-running work. Always creates a herdr session — never backgrounds with nohup/disown. Writes the new session to .mam/agent-sessions.yaml. Use when you want to start a fresh agent (no prior UUID) for a new project workspace."
-version: 4.2.0
+version: 4.3.0
 author: godopu
 license: MIT
 platforms: [linux, macos]
@@ -7,5 +7,6 @@
 - 브로커 PoC→운영 전환: [`mqtt-broker-setup.md`](./mqtt-broker-setup.md)
 - 레지스트리 포맷/동시성: [`registry.md`](./registry.md)
 - 참조 구현: [`multi-agent-mux-delegate-job`](./multi-agent-mux-delegate-job) (bash wrapper), [`scripts/publish_event.py`](./scripts/publish_event.py), [`scripts/job_subscriber.py`](./scripts/job_subscriber.py), [`scripts/registry.py`](./scripts/registry.py), [`scripts/mqtt_common.py`](./scripts/mqtt_common.py)
+- **v4.3.0 이후**: 위 `scripts/*.py`는 호환 shim이며 실제 구현은 `.agents/skills/lib_py/delegation/`에 있다 (issue #5 phase 1). 스크립트 경로와 CLI 계약은 그대로이며, `lib.sh` 헬퍼는 `python -m lib_py.delegation.cli`를 호출한다.
 - 영구 감사 로그: `.mam/delegate_job_logs/<job_id>/` (`meta.json`·`events.ndjson`·`status.json`)
  — `multi-agent-mux-delegate-job logs <id>` 또는 `multi-agent-mux-delegate-job logs --list`로 조회 (SKILL.md "Audit Logs" 참조)
@@ -1,7 +1,7 @@
 ---
 name: multi-agent-mux-delegate-job
 description: "Delegate a unit of work to any autonomous agent (claude-code, hermes, agy, grok-build, codex, or a human) and observe it asynchronously over an MQTT event channel. Supported roles include orchestrator, worker, and reviewer."
-version: 4.2.0
+version: 4.3.0
 author: godopu
 license: MIT
 platforms: [linux, macos, windows]
@@ -70,6 +70,31 @@ For detailed state machine diagrams and configurations, see [DELEGATION_TYPES.md

 ---

+## Where the Implementation Lives (v4.3.0)
+
+The implementation moved to the `lib_py.delegation` package in issue #5 phase 1.
+`scripts/{mqtt_common,registry,publish_event,job_subscriber}.py` remain as
+compatibility shims and **their paths are unchanged** -- every command in this
+document still works verbatim. Each shim binds the `lib_py.delegation` package
+to the tree next to itself, once per process, without touching `sys.path`, so
+`import mqtt_common` yields the same module object as
+`lib_py.delegation.mqtt_common`.
+
+Which tree wins, by execution context:
+
+| Context | Resolved by | Tree that wins |
+|---|---|---|
+| Loop process and its children (frozen `lib.sh` sourced) | `PYTHONPATH` | the frozen snapshot |
+| Agent session running a **frozen** script path while `PYTHONPATH` still points live | the shim, from its own location | the frozen snapshot (B-13 preserved) |
+| Live helpers (create/stop/resume/reconcile) | `PYTHONPATH` or the shim (same tree) | the live tree |
+| Standalone, no `PYTHONPATH` | the shim's fallback append | the shim's own tree |
+
+`lib.sh` calls the package through `python -m lib_py.delegation.cli`. Setting
+`MAM_DELEGATION_PY=0` switches the shell helpers back to their preserved legacy
+bodies with no redeploy.
+
+---
+
 ## The Event Protocol Contract

 Every agent participating in the delegation contract must follow the same lifecycle publishing protocol using `publish_event.py`:
@@ -112,3 +112,7 @@ On `broker.hivemq.com` anyone can publish/subscribe the same topic. Therefore:
  subscriber **before** the agent (ordering dependency), or rely on retained
  terminal events in production.
 - Real operational decisions belong to the own-broker stage with auth + ACL.
+
+---
+
+> **구현 위치 각주 (v4.3.0)**: 본 문서가 인용하는 `scripts/*.py` 경로는 유효하며 계약도 불변이다. 실제 구현은 issue #5 phase 1에서 `.agents/skills/lib_py/delegation/`으로 이동했고, `scripts/*.py`는 그 패키지를 자기 옆 트리에 바인딩하는 호환 shim이다.
@@ -183,3 +183,7 @@ $PY scripts/registry.py logs <job_id> --tail 20  # last 20 events
 $PY scripts/registry.py logs <job_id> --json     # raw JSON lines
 $PY scripts/registry.py logs --list              # every job, live status
 ```
+
+---
+
+> **구현 위치 각주 (v4.3.0)**: 본 문서가 인용하는 `scripts/*.py` 경로는 유효하며 계약도 불변이다. 실제 구현은 issue #5 phase 1에서 `.agents/skills/lib_py/delegation/`으로 이동했고, `scripts/*.py`는 그 패키지를 자기 옆 트리에 바인딩하는 호환 shim이다.
@@ -1,7 +1,7 @@
 ---
 name: multi-agent-mux-loop
 description: "Run an autonomous planning-execution-review loop using multiple agents (Planner, Creator, Reviewers) in the workspace. Automatically orchestrates plan discussion, code changes, and peer reviews until a unanimous PASS is achieved or the maximum iteration limit is reached."
-version: 4.2.0
+version: 4.3.0
 author: godopu
 license: MIT
 platforms: [linux, macos]
@@ -1,7 +1,7 @@
 ---
 name: multi-agent-mux-monitor
 description: "Run a long-lived reconciler that watches .mam/agent-sessions.yaml against the actual herdr/agent runtime state and reconciles them. Use when you want live visibility into which agent sessions are running, which are dead, which have stale YAML entries, and which have new session ids that haven't been recorded yet. Runs as a persistent loop (`reconcile.sh --subscribe`) that keeps going until it times out, idles out, or is interrupted."
-version: 4.2.0
+version: 4.3.0
 author: godopu
 license: MIT
 platforms: [linux, macos]
@@ -1,7 +1,7 @@
 ---
 name: multi-agent-mux-orc-onboard
 description: "Register current or specified orchestrator session UUID into agent-sessions.yaml orchestrator_uuids list to prevent sub-agent discovery capture."
-version: 4.2.0
+version: 4.3.0
 author: godopu
 license: MIT
 platforms: [linux, macos]
@@ -1,7 +1,7 @@
 ---
 name: multi-agent-mux-resume
 description: "Resume an existing agent (claude, antigravity/agy) conversation by UUID into a herdr session. Reads .mam/agent-sessions.yaml for the saved session/conversation id, spawns (or reuses) a herdr session of the matching name, and runs `claude -r <id>` or `agy --conversation <id>` inside. Use when you want to reattach to a previous session's context, or revive a session whose herdr died but the agent's conversation is still on disk."
-version: 4.2.0
+version: 4.3.0
 author: godopu
 license: MIT
 platforms: [linux, macos]
@@ -1,7 +1,7 @@
 ---
 name: multi-agent-mux-status
 description: "Read-only instant snapshot of all agent herdr sessions — name, YAML status, herdr alive, pane cmd/cwd, resume UUID on disk, and any drift. No mutation. Reuses reconcile.sh --dry-run for the diff logic. Use when you want to know 'what's running RIGHT NOW' without spinning up the monitor loop."
-version: 4.2.0
+version: 4.3.0
 author: godopu
 license: MIT
 platforms: [linux, macos]
@@ -1,7 +1,7 @@
 ---
 name: multi-agent-mux-stop
 description: "Stop an agent herdr session (claude, antigravity/agy) and update .mam/agent-sessions.yaml. Default stops gracefully and marks status=stopped with conversation preserved for resume. Does NOT delete on-disk conversation artifacts (jsonl/db) — those are preserved unless --purge-conversation is passed. Use when ending a work session, switching to a different one, or cleaning up before a fresh start."
-version: 4.2.0
+version: 4.3.0
 author: godopu
 license: MIT
 platforms: [linux, macos]