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
This commit is contained in:
GodopuandClaude Opus 5 committed 2026-09-06 15:48:38 +09:00
1 parent a4b7b45e13
commit 508ca99d71
18 files changed
+179 -30

No files matched your search

@@ -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이다.