tmpl/multi-agent-mux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: optimize multi-agent-mux-loop spec and clean up workspace docs

Browse Source 
- Add OPTIMIZATION.md detailing Invocation-Aware Scoped Guard, race-free lock design, and DoD verification gates approved via multi-agent loop
- Update root markdown files (README, BOOTSTRAP, MESSAGING) replacing legacy TMUX references with HERDR
- Remove redundant root markdown files and archive promoted reviewer PASS report
This commit is contained in:
Godopu
2026-08-02 19:20:43 +09:00
parent 002d9b268d
commit 03ba94a030
21 changed files with 234 additions and 1279 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/reports/canary-projects-multi-agent-mux-creator-cline/report-9c44c6b2.md
+114
View File
@@ -0,0 +1,114 @@
# Cross Code Review — Job 9c44c6b2
- **Reviewer**: cline (session: `canary-projects-multi-agent-mux-creator-cline`, role: `reviewer`)
- **Job ID**: 9c44c6b2
- **Task**: Review and verify final `OPTIMIZATION.md` specification for `multi-agent-mux-loop` improvements
- **Scope**: Accumulated `git diff` (working-tree changes vs `HEAD`) + new untracked `OPTIMIZATION.md`
- **Date**: 2026-08-02
---
## 1. Changeset Summary
The working tree contains 19 changed files (`52 insertions, 1279 deletions`):
| Category | Files | Nature |
| :--- | :--- | :--- |
| **New specification** | `OPTIMIZATION.md` (untracked) | New analysis doc defining 9 issues + resolutions for `multi-agent-mux-loop` |
| **Doc fix (spec ↔ doc alignment)** | `.agents/skills/multi-agent-mux-loop/SKILL.md` | Removes the erroneous `--all-reviewer` from the example that combined it with `--reviewer`; adds explicit "상호 배타적" (mutually exclusive) note |
| **Legacy terminology cleanup** | `README.md`, `README.ko.md`, `BOOTSTRAP.md`, `BOOTSTRAP.ko.md`, `MESSAGING.md` | `tmux` → `herdr` wording migration across user-facing docs |
| **Obsolete doc deletion** | `CLAUDE_WORK_LOGS.md`, `DONE.md`, `DONE.ko.md`, `FUTURE_WORKS.md`, `FUTURE_WORKS.ko.md`, `PLAN_HERDR.md`, `PLAN_LOOP.md`, `RECOMMENDED.md`, `REPORT.md`, `SKILL_FEATURES.md`, `TEST_INFRA.md`, `TEST_READY.md`, `mam_delegate_job_role_issue_report.md` | Removal of 13 superseded/archived markdown files |
No runtime shell/Python source under `.agents/skills/*/scripts/` is modified in this changeset — the loop skill's behavior code (`run_loop.sh`) is unchanged.
---
## 2. Lint & Syntax Verification
| Check | Target | Result |
| :--- | :--- | :--- |
| `bash -n` syntax | `.agents/skills/multi-agent-mux-loop/scripts/run_loop.sh` | ✅ `syntax OK` (no syntax errors) |
| `shellcheck` | `run_loop.sh` | ⚠️ not installed in environment — cannot run static analysis; flagging as a verification gap, not a defect |
| Markdown structure | `OPTIMIZATION.md` | ✅ Well-formed headings, fenced blocks, tables; consistent Korean/English bilingual style |
| Internal cross-references | `SKILL.md` ↔ `OPTIMIZATION.md` | ✅ ISSUE-1 SKILL.md edit matches the "상호 배타적" wording introduced in `OPTIMIZATION.md` §1.ISSUE-1 |
---
## 3. Operability & Spec ↔ Implementation Consistency Analysis
This is a **specification document review**, not a runtime code review. The central question is whether `OPTIMIZATION.md` is a coherent, implementable, and internally consistent spec, and whether the accompanying doc edits correctly align the existing `SKILL.md`/READMEs with it.
### 3.1 ✅ SKILL.md fix is correct and self-consistent (ISSUE-1 doc half)
The `SKILL.md` edit removes the contradictory `--all-reviewer` line from the example that simultaneously passed `--reviewer "A,B"`, and adds an explicit mutual-exclusivity note to the Phase 3: Consensus row. This directly implements the *documentation* portion of OPTIMIZATION.md ISSUE-1 item 2 ("`SKILL.md` 문서 내의 옵션 예시 ... 정정"). The fix is surgical — only the conflicting lines changed, surrounding text untouched. **Pass.**
### 3.2 ⚠️ SPEC GAP — ISSUE-1 code enforcement is *not* implemented (fail-fast missing)
`OPTIMIZATION.md` ISSUE-1 item 1 mandates: *"파라미터 파싱 단계에서 상호 배타적인 옵션이 포함된 경우 ... 즉시 에러(`exit 1`)를 반환하도록 검증 로직 강화."*
However, the actual `run_loop.sh` (lines 99–107) still only **warns** and proceeds:
```bash
# --all-reviewer silently takes precedence over an explicit --reviewer list; warn ... (P2-1).
if [ "$ALL_REVIEWERS" = true ] && [ -n "$REVIEWER_LIST" ]; then
log_warn "--all-reviewer takes precedence; ignoring --reviewer list ('$REVIEWER_LIST')."
fi
if [ "$PLAN_TALK_TURNS" -gt 0 ] && [ "$PLAN_MODE" = false ]; then
log_warn "--plan-talk was specified but --plan mode is not enabled. Discussion turns will be ignored."
fi
```
This is the *exact* "경고만 출력하고 무시" (warn-only) behavior OPTIMIZATION.md §1.ISSUE-1 identifies as the problem and resolves with `exit 1`. The spec is therefore **defining future work**, not describing an already-shipped fix. This is acceptable for a specification document, but the SKILL.md wording now states the options are "상호 배타적" while the code still silently allows both — a **doc/code divergence** that the spec itself flags as the very class of bug it intends to close.
**Direction (Reviewer per MULTI_AGENT_RULES §1 — must give concrete, verified alternative):**
The spec is sound; the implementation gap is expected because this changeset ships the *spec + doc alignment*, not the code enforcement. To close the loop in a follow-up Creator iteration, `run_loop.sh` lines 99–107 should become hard failures:
```bash
if [ "$ALL_REVIEWERS" = true ] && [ -n "$REVIEWER_LIST" ]; then
log_error "--all-reviewer and --reviewer are mutually exclusive. Aborting."
exit 1
fi
if [ "$PLAN_TALK_TURNS" -gt 0 ] && [ "$PLAN_MODE" = false ]; then
log_error "--plan-talk requires --plan. Aborting."
exit 1
fi
```
This is a stable, minimal patch that fulfills ISSUE-1 item 1 without altering any other control flow. **Not a blocker for this spec review** — but should be tracked as the first ticket off this spec.
### 3.3 ✅ ISSUE-2 (legacy tmux terminology) — fully executed in this diff
`BOOTSTRAP.md`, `BOOTSTRAP.ko.md`, `README.md`, `README.ko.md`, `MESSAGING.md` all migrate `tmux` → `herdr` consistently (e.g. `Tmux Workspace` → `Herdr Workspace`, `Tmux Server Isolation` → `Herdr Server Isolation`, `_init_tmux_isolation` → `_init_herdr_isolation`). The renaming is uniform across the English/Korean pairs. **Pass.**
### 3.4 ✅ ISSUE-3 through ISSUE-9 — defined as spec, not yet implemented (by design)
`OPTIMIZATION.md` §2–§3 define ISSUE-3 (verdict format mechanical validation), ISSUE-4 (`dod_changed_paths` + atomic-commit gate), ISSUE-5 (`[AGREEMENT: REACHED]` early-break), ISSUE-6 (review-rebuttal channel), ISSUE-7 (PID+lstart+workspace triple lock), ISSUE-8 (alive-ping fail-fast), ISSUE-9 (skill-invocation guardrail).
A `grep` of `run_loop.sh` confirms none of `dod_changed_paths`, `AGREEMENT`, `REACHED`, or `lstart` are present in the current code — i.e. these are **forward-looking spec items**, correctly scoped as a specification. Each issue statement follows a consistent *현상 → 문제점 → 해결 방안* structure with concrete, implementable directions. No issue is left without a remediation path. **Pass as a specification.**
### 3.5 ✅ No data-loss / orphan risk in the doc deletions
The 13 deleted markdown files are archived dev logs / superseded plans (e.g. `DONE.md`, `PLAN_LOOP.md`, `REPORT.md`, `mam_delegate_job_role_issue_report.md`). They contain no runtime config or referenced anchors. A spot check confirms:
- No `.agents/skills/*/scripts/` source references these deleted files.
- `README.md`/`SKILL.md` do not link to the deleted docs (the only internal links point to live files: `BOOTSTRAP.md`, `MESSAGING.md`, `MULTI_AGENT_RULES.md`).
- Their content (FW-W* future-work items, the role-issue report) is either absorbed into `OPTIMIZATION.md` or is purely historical.
Removing them is safe and reduces root clutter (aligns with the repo layout note that `.agents/` is the canonical home for protocol docs). **Pass.**
---
## 4. Issues Found (non-blocking, for follow-up tracking)
| # | Severity | Finding | Recommended Direction |
| :--- | :--- | :--- | :--- |
| R-1 | Low | `run_loop.sh` lines 99–107 still warn-only; contradicts the now-stated "상호 배타적" spec | Convert to `exit 1` per ISSUE-1 item 1 (patch shown in §3.2) |
| R-2 | Low | Untracked stray file `.agents/skills/multi-agent-mux-delegate-job/multi-agent-mux-delegate-job.17678_23708.tmp` present in the working tree and **not covered by `.gitignore`** (no `*.tmp` rule exists) | Add `*.tmp` (or the delegate-job tmp glob) to `.gitignore` and remove the stray file; prevents accidental commit of orchestrator scratch state |
| R-3 | Info | `shellcheck` not available in this environment — static-analysis gap for shell skills | Recommend installing `shellcheck` in CI/dev image; the repo's `deploy/gitea-ci.yml` already intends shellcheck coverage (per `FW-D4` notes) |
None of R-1..R-3 are blocking defects in the *specification* under review. R-1 is the spec's own next implementation step; R-2 is a hygiene nit outside the `OPTIMIZATION.md` scope; R-3 is an environment limitation, not a code defect.
---
## 5. Verdict
The `OPTIMIZATION.md` final specification is:
- **Internally consistent** — every issue has a 현상/문제점/해결 방안 triad with a concrete, implementable direction.
- **Lint-clean** — `bash -n` passes on the referenced `run_loop.sh`; markdown is well-formed.
- **Doc-aligned** — the shipped `SKILL.md` edit correctly resolves the documentation half of ISSUE-1, and the legacy tmux→herdr cleanup fully executes ISSUE-2.
- **Loss-free** — deleted obsolete docs are not referenced by any live code/doc; no orphan links introduced.
The single spec↔code divergence (R-1: warn-only vs. mandated `exit 1`) is *the very gap the spec exists to close* and is correctly scoped as follow-up implementation work, not a defect in the specification itself. No redesign/replanning is required; the spec is ready to drive the next Creator implementation iteration.
[VERDICT: PASS]
.agents/skills/multi-agent-mux-loop/SKILL.md
+2 -3
View File
@@ -164,7 +164,7 @@ sequenceDiagram
| **Phase 1: Debate** | `--plan-talk N` | Planner와 Creator가 상호 대화식 챌린지 루프를 `N`회 돌며 계획을 교차 정제합니다. |
| **Phase 2: Execution** | (기본값) | `--target-agent`로 명시한 주 작업 세션에 코딩 태스크를 주입합니다. |
| **Phase 3: Review** | `--reviewer "A,B"` | 지정된 리뷰어 세션 리스트(`A`, `B` 등)에 교차 Peer Review를 위임합니다. |
| **Phase 3: Consensus** | `--all-reviewer` | 레지스트리에 등록된 모든 active 리뷰어 세션을 자동으로 수집하여 리뷰를 돌립니다. (지정/수집된 모든 리뷰어의 PASS 만장일치가 항상 필요합니다.) |
| **Phase 3: Consensus** | `--all-reviewer` | 레지스트리에 등록된 모든 active 리뷰어 세션을 자동으로 수집하여 리뷰를 돌립니다. (`--reviewer` 옵션과는 상호 배타적이며, 지정/수집된 모든 리뷰어의 PASS 만장일치가 항상 필요합니다.) |
| **Iterative Loop** | `--max-loop M` | NOT PASS 판정 시 최대 `M`회까지 Creator가 자체 수정합니다. `--plan` 모드에서 리뷰어가 리포트에 `[ESCALATE: PLANNER]` 태그를 남기면 설계 변경 수준으로 판단하여 Planner에게 계획 갱신을 위임합니다 (린트는 리뷰어가 검토 관점 중 하나로 확인할 뿐, 별도의 자동 게이트는 아닙니다). |
---
@@ -178,12 +178,11 @@ bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \
--task "Fix typo in deploy/README.md"
# 2. Collaborative planning + Targeted Reviewers + Safety limits
# (실전 자율 루프 기동의 표준 패턴 — 리뷰어 2인 지정 + 전원 합의 + 최대 3회 반복)
# (실전 자율 루프 기동의 표준 패턴 — 리뷰어 2인 지정 + 최대 3회 반복)
bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \
--plan \
--plan-talk 1 \
--reviewer "<reviewer-session-name-1>,<reviewer-session-name-2>" \
--all-reviewer \
--max-loop 3 \
--verbose \
--target-agent "<creator-session-name>" \