tmpl/multi-agent-mux
1
0 Fork 0
Code Issues 9 Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
07cae71667e82246d8cf008b62022dcbd67997e1
multi-agent-mux/docs/contracts/issue-5/phase3-loop.md
T

6.9 KiB
Raw Blame History

📑 Issue #5 Phase 3 — run_loop.sh Thin Wrapper 전환 및 lib_py.loop 승격 명세

  • 문서 버전: Rev.1
  • 상태: Phase 3 설계 및 이식 착수 기준선 (Implementation & Regression Specification)
  • 대상 파일:
    • lib_py/loop/runner.py, lib_py/loop/__main__.py, lib_py/loop/parser.py
    • .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh
    • tests/test_issue5_phase3_loop.py

1. 개요 및 한 문장 요약

936줄의 복잡한 Bash 오케스트레이션(run_loop.sh)을 단일 제어 구조의 Python 모듈(lib_py.loop)로 승격하고, run_loop.sh는 CLI 계약과 B-13 Freeze를 보존하는 얇은 래퍼(Thin Wrapper)로 전환한다.

Phase 2(CAS 전이 엔진, 이중 감지 자동완료 게이트)에서 구축된 상태 및 판정 기반을 실제 루프 제어 흐름에 유기적으로 결합하며, 기존 732개 테스트의 0-Fail 통과와 셸 레거시 롤백(MAM_LOOP_PY=0)을 보장합니다.

2. 모듈 아키텍처 (lib_py/loop/)

Phase 1/2a의 형제 패키지 격리 원칙(D1(b), G9: lib_py.loop는 lib_py.delegation 외의 다른 형제 패키지를 임포트하지 않음)을 엄격히 준수합니다.

lib_py/loop/
├── __init__.py           # 패키지 선언 및 export
├── __main__.py           # python3 -m lib_py.loop 진입점
├── parser.py             # 코드 펜스 제외 Strict 판정/태그 파서
├── runner.py             # 오케스트레이터 본체 (LoopRunner 클래스)
├── checkpoint.py         # 체크포인트 기록 및 복구 (.mam/loop-checkpoint.json)
├── attribution.py        # [Phase 2a] 관측 증거 수집
├── watcher.py            # [Phase 2a] herdr agent wait 래퍼
├── policy.py             # [Phase 2a] 상태 결정 정책
├── shadow.py             # [Phase 2a] Would-Complete shadow 실행기
├── store.py              # [Phase 2a] 증거 저장소
└── autocomplete.py       # [Phase 2b] 자동완료 평가기

3. 핵심 설계 요소

3-1. 엄격한 판정 파서 (Strict Parser, parser.py)

  • 코드 펜스(```) 무시:
    • 기존 셸 정규식은 리포트 본문 내 코드 블록(예: 마크다운 예시 등)에 적힌 [VERDICT: PASS]도 파일 끝에 위치하면 유효한 판정으로 오인하는 결함(baseline.md Gap)이 존재했습니다.
    • Python 파서는 텍스트를 파싱할 때 마크다운 코드 펜스(``` 또는 ~~~) 내부 라인을 제거한 뒤, **가장 마지막 비공백 라인(last non-blank line)**만을 검사합니다.
  • Fail-Closed 불변식:
    • 판정 라인이 없거나, [VERDICT: NOT PASS]와 [VERDICT: PASS]가 모호하게 충돌하거나, 알 수 없는 태그인 경우 예외 없이 NOT PASS로 처리합니다.
  • 태그 추출:
    • [ESCALATE: PLANNER]: 코드 펜스 외부 어디서든 단독 행으로 존재하면 감지
    • [REBUT: <reviewer>]: Creator 반론 대상 리뷰어 세션명 추출 (중복 제거 및 실제 거부한 리뷰어로 필터링)
    • [ADJUDICATION: SUSTAINED|OVERRULED]: 재심 판정 추출 (fail-closed: 명시적 SUSTAINED 외에는 모두 OVERRULED)
    • [ARBITRATION: CREATOR|REVIEWER]: Planner 중재 판정 추출

3-2. run_loop.sh Thin Wrapper 및 하위 호환성

  • 하위 호환 롤백 플래그:
    • MAM_LOOP_PY=1 (기본값): Python lib_py.loop 실행
    • MAM_LOOP_PY=0: 기존 인라인 셸 루프 실행 (안전 롤백 경로)
  • B-13 Freeze 및 인자 보존:
    • Phase 4에서 Freeze가 제거되기 전까지, run_loop.sh는 기존처럼 기동 시 /tmp/mam-loop-freeze.XXXXXX로 트리를 복제하여 실행 격리를 유지합니다.
    • MAM_REAL_ROOT, WORKSPACE_ROOT, MAM_ENV_FILE 환경변수 export를 그대로 유지하여 기존 테스트의 문자열 검증을 만족합니다.
  • 기존 테스트 텍스트 앵커 보존:
    • test_o1_rebuttal.py (has_tag_line() {, extract_tag_values() {, find_report() {)
    • test_b7_diff_untracked.py (CHANGES_DIFF=$(mam_collect_changes_diff ...)
    • test_deploy_freshness.py (export MAM_ENV_FILE=)
    • test_o3_scoped_guard.py (mam_release_loop_lock)
    • 위 앵커들은 run_loop.sh 내에 셸 헬퍼 또는 주석/shim 블록으로 보존되어 기존 정적 검사 테스트들을 100% 통과시킵니다.

3-3. 체크포인트 및 정지 프로토콜 (checkpoint.py)

  • 원자적 체크포인트 (.mam/loop-checkpoint.json):
    • 루프 회차(iteration), 활성 Job ID 목록(created_jobs), 현재 계획(current_plan), 리뷰 상태(review_status), 기준 커밋(base_commit), 타임스탬프 기록.
    • 임시 파일 쓰기 후 원자적 rename(replace)으로 커밋.
  • 우아한 정지 (Quiesce on Signal):
    • SIGINT/SIGTERM 수신 시 즉시 강제 종료하지 않고, 현재 진행 중인 서브프로세스를 정리하고 체크포인트를 기록한 뒤 가드를 해제하고 안전하게 종료(exit 130/143)합니다.

4. 단계별 세부 구현 및 검증 게이트 (P3-01 ~ P3-03)

📌 P3-01: lib_py/loop/parser.py 및 오케스트레이션 로직 이식

  1. parser.py 구현: 코드 펜스 분리 및 엄격한 판정/태그 추출 로직 작성.
  2. runner.py 구현:
    • CLI 인자 파싱 및 검증 (--creator, --task, --plan, --plan-talk, --reviewer, --all-reviewer, --max-loop, --max-rebut, --cleanup, --verbose)
    • 세션 조회 및 상태 검증 (Planner, Target Agent, Reviewers)
    • Phase 1 플래닝 및 토론 (Plan ➔ Critique ➔ Refine)
    • Phase 2 구현 디스패치 (Worker)
    • Phase 3 리뷰 루프 (병렬 디스패치, Strict 판정 수렴, Escalation 분기, Rebuttal/Adjudication/Arbitration)
    • Phase 4 산출물 승격 (Plan 및 Report 원자적 복사/이동) 및 임시 디렉터리 정리
  3. tests/test_issue5_phase3_loop.py 작성:
    • 코드 펜스 내부 허위 판정 무시 검증 (Strict Parser)
    • Rebuttal 예산(iteration budget vs run-wide budget) 및 중재 흐름 검증
    • 만장일치 PASS 수렴 검증

📌 P3-02: run_loop.sh Thin Wrapper 전환 및 런타임 호환성

  1. run_loop.sh에 MAM_LOOP_PY 분기 도입:
    • MAM_LOOP_PY=1일 때 Python lib_py.loop로 위임
    • 기존 CLI 파싱, --help exit 1 유지, B-13 freeze 격리 유지
    • 기존 테스트 텍스트 앵커 보존
  2. CWD, 공백 경로, 시그널 트랩, 인터프리터 앵커링 검증:
    • Freeze 사본 내에서 실행 시 _delegate_py_bin이 WORKSPACE_ROOT 기준 인터프리터를 정확히 해석하는지 검증 (O-4 인계 해결)

📌 P3-03: 전면 회귀 검증 및 체크포인트 핸드오프

  1. 전체 732개 테스트 회귀 검증:
    • test_loop_cli.py, test_o1_rebuttal.py, test_tier4_e2e.py (Scenario 5 E2E 루프 포함) 전체 0-Fail 통과
  2. 체크포인트 기록 및 시그널 인터럽트 시뮬레이션 검증.
  3. 롤백 드릴: MAM_LOOP_PY=0으로 기존 셸 루프 전환 시 정상 작동 확인.
Reference in new issue View Git Blame Copy Permalink