multi-agent-mux/docs/contracts/issue-5/phase2b-autocomplete.md

# 📑 Issue #5 Phase 2b — 자동완료 운영 노트 (Flag-Gated / Opt-In)

- **문서 버전**: Rev.1
- **상태**: 구현 완료, **기본 비활성(`MAM_AUTO_COMPLETE=0`)**

---

## 1. 한 문장 요약

**끝났다는 사실을 아는 쪽(에이전트)이 확정을 선언하고, 읽는 쪽은 그 선언을 믿지 않고 해시를 다시 계산한다.**

워처가 스스로 해시를 계산해 매니페스트를 만들면 그것은 "워처가 안정된 파일을 봤다"는 자기 증명일 뿐이다. 이 이슈의 앞선 라운드에서 리뷰어가 기각한 증거 형태이며, 같은 실수를 반복하지 않기 위한 설계 결정이다.

## 2. 그래서 미지원 에이전트는 자동으로 안전하다

확정을 선언하지 않은 에이전트는 매니페스트를 남기지 않는다. 매니페스트가 없으면 정책이 이미 `hold`한다(Phase 2a에서 구현·테스트 완료). **"미지원 경로 100% 보존"은 새 분기가 아니라 기존 동작의 귀결이다.**

## 2-1. ⚠️ 아직 배선되지 않았다 (정직한 현황)

**`autocomplete.evaluate`와 `notifier.recover`를 호출하는 프로덕션 경로는 아직 없다.** `daemon.py`/`job_subscriber.py`/`cli.py`/`service.py` 어디도 이들을 임포트하지 않으며, `register`에 `auto_complete` opt-in 옵션도 없다. 즉 **현재 라이브 셸 루프에서 `MAM_AUTO_COMPLETE=1`은 무동작(no-op)이다.**

Phase 2b가 제공하는 것은 **검증된 라이브러리와 게이트**이며, 이를 감시 루프에 연결하는 배선은 Phase 3의 몫이다. 초기 문서가 "기동 시 재발행이 구독자에서 수행된다"고 적었던 것은 사실이 아니었으며 여기서 정정한다(교차 리뷰 `3fa76e08` O-1, `a0de0e5e` 잔여 1·2).

배선 시 필요한 것:
1. 감시 루프에서 `evaluate(...)` 호출 — **`report_dir`는 필수 인자다.**
2. 커밋 후 `notifier.flush(...)` 호출 — `evaluate`는 intent를 남길 뿐 발행하지 않는다.
3. 기동 시 `notifier.recover(...)` 호출.
4. `register`에 잡별 opt-in 경로 추가.

## 3. 3중 게이트 (전부 참일 때만 커밋)

| 게이트 | 기본값 | 근거 |
|---|---|---|
| `MAM_AUTO_COMPLETE=1` | **`0` (OFF)** | 전역 킬 스위치 |
| `MAM_ENGINE_CAS=1` | `1` | `0`이면 자동완료도 함께 중단된다. 추론 완료는 CAS 경계 위에 서 있으므로, 경계가 롤백된 상태의 커밋은 그 경계를 우회하는 것이다 |
| 백엔드 허용목록 | `claude,grok,codex` (+ `-code`/`-build`/`-cli` 정식 키) | 정지 상태(`idle`/`done`) **관측 증거가 있는 백엔드만**. `agy`는 `working`만 관측, `hermes`·`opencode`는 관측 0건. **정확 일치**로 비교한다 — 접두 일치라면 미래의 `claude-experimental`이 수집된 적 없는 증거를 물려받는다 |
| 잡별 opt-in | 레코드 `auto_complete: true` | 잡 단위 동의 |

`MAM_AUTO_COMPLETE_BACKENDS`로 목록을 **좁힐 수만** 있다. 관측된 적 없는 이름은 무시된다 — 넓히려면 설정이 아니라 증거가 필요하다.

## 4. 확정 계약 (P2B-01)

```
에이전트:  publish_event.py --job <id> --event completed \
             --finalize-report <path> [--side-effect <kind>=<ref>] ...
   ① <path>.tmp → <path> 원자적 rename   (반쯤 쓰인 리포트를 최종본으로 볼 수 없게)
   ② SHA-256 계산
   ③ report-manifest.json 원자적 기록 (job_id, attempt_id, sha256, side_effects, declared_by)
```

- **리포트를 다시 쓰면 선언은 즉시 무효**가 된다. 해시를 다시 계산해 대조하기 때문이다. 새 본문에는 새 확정이 필요하다.
- **선언한 부수효과는 전부 증거가 있어야 한다.** 일부만 있는 것은 없는 것으로 취급한다 — 작업이 끝났다고 알 수 없기 때문이다.
- 확정은 발행 **앞에** 일어난다. 리포트를 아직 쓰는 중인 `completed` 이벤트는 계약이 금지하는 부분 리포트 채택을 부른다.

## 5. 지연 알림 (P2B-02)

```
락 안:   상태 커밋 + pending_notification 기록   ← 하나의 원자적 쓰기
락 밖:   발행 → 성공 시 notification_settled 전이로 정리
기동 시: pending_notification이 남은 레코드를 재발행 (멱등: 구독자가 seq로 중복 제거)
```

- **독립 Outbox 저장소를 만들지 않는다**(`state-transitions.md` §5 명시). 이미 쓰는 레코드에 필드 하나를 더 쓴다.
- **발행 실패는 의도적으로 intent를 남긴다.** 보내지 않은 알림이 보낸 것처럼 보이는 편이, 재시도되는 편보다 나쁘다.
- `notification_settled`는 **상태를 바꾸지 않는 bookkeeping 요청**이라 terminal 상태에서도 허용되며, **`pending_notification` 외의 필드는 쓸 수 없다**(경계에서 거부 — 현재 호출자가 그것만 넘긴다는 사실에 의존하지 않는다).
- 정리는 **실제로 보낸 intent와 일치할 때만** 이루어진다. 발행은 락 밖에서 일어나므로 그 사이에 새 intent가 정당하게 들어올 수 있고, 무조건 지우면 아무도 보내지 않은 알림이 사라진다.
- 발행 payload에 intent의 `seq`/`event`/`timestamp`를 실어 보낸다. **전송 계층 seq는 같은 intent의 재시도를 식별하지 못하므로**, 소비자는 `notification_intent`로 중복을 제거한다. 알림은 terminal에 *관한* 것이므로, terminal이 거부하는 요청으로는 영원히 정리할 수 없다.

## 5-1. 필수 검증 (교차 리뷰 반영, 전부 미충족 시 `hold`)

| 검증 | 없으면 |
|---|---|
| `report_dir` 인자 | `hold` — **선택이 아니다.** 생략하면 디스크 대조가 통째로 건너뛰어져 수집기의 자기 신고가 다시 판단 주체가 된다 |
| 기록된 dispatch | `hold` — 귀속시킬 대상이 없다 |
| 증거의 **대상 일치** | `hold` — 시나리오의 `job_id`·attempt·session·pane이 기록된 dispatch와 일치해야 한다. 정책은 시나리오 **내부**의 dispatch_context와만 비교하므로 구조상 항상 자기 일관적이다 |
| 매니페스트 재계산 대조 | `hold` |
| Reviewer 역할의 판정 토큰 | `hold` — Phase 0 안전 계약. 판정을 아직 쓰지 않은 리뷰어는 검토를 끝내지 않은 것이다 |

## 6. 무판정 fail-closed

매니페스트를 읽지 못함, 정책이 예외를 던짐, 알 수 없는 결정 — 전부 `hold`다. **"판정하지 못함"은 결코 "완료"가 아니다.** 늦게 도착한 명시 terminal이 있으면 전이 경계가 추론 완료를 거부하며, 그것은 경계가 제 일을 한 것이지 게이트의 오류가 아니다.

## 7. 감사 표식

자동완료로 들어간 terminal에는 `completed_by: "auto_complete"`와 판정 사유가 남는다. 구독자와 래퍼는 자동/명시 완료를 구별하지 못하므로(`job_subscriber._check_disk_fallback`은 레지스트리 status만 본다), **사후에 구별할 수 있는 유일한 수단**이다.

## 8. 롤백

1. `MAM_AUTO_COMPLETE=0` — 신규 자동완료만 중단. **이미 확정된 terminal 레코드는 보존**한다.
2. `MAM_ENGINE_CAS=0` — Phase 2a 경로까지 되돌린다(자동완료는 그 위에 있으므로 함께 무력화).
3. `.mam/shadow/`는 레지스트리와 분리되어 있어 삭제해도 job 상태에 영향이 없다.

## 9. 계획 대비 이탈 1건 (레코드 스키마 미변경)

계획서 §D2는 `attempt_id`를 job 레코드의 1급 필드로 승격할 것을 권고하고, Phase 1이 동결한 "레코드 필드 불변" 계약의 변경이므로 **리뷰어 승인을 선행 조건**으로 걸었다.

구현 중 실측한 결과 **그 변경이 필요하지 않았다**:
- 엔진의 `expected_attempt`는 레코드의 `attempt_id`(없음)를 `iteration`(루프 회차)으로 대체 비교한다 — 두 개념이 달라 의미가 성립하지 않는다.
- 반면 **시도 식별은 이미 증거 계층에서 검증된다**: `policy`가 관측 식별자와 shadow 저장소의 dispatch 레코드를 대조하며, 시도가 어긋나면 `hold`한다(실측 확인).

따라서 자동완료는 엔진에 `expected_attempt`를 넘기지 않고 `expected_status="running"`(엔진의 고유 영역인 상태)만 전제조건으로 준다. **시도 보증은 시도 정체성이 실제로 사는 곳에 둔다.** 레코드 스키마는 바뀌지 않았고, Phase 1 계약도 유지된다.

`attempt_id` 승격은 열린 질문으로 남긴다. 승격하면 엔진에 2차 방어선이 생기지만 동결 계약을 바꿔야 하며, 현재는 필요하지 않다. `test_x03_the_record_carries_iteration_not_an_attempt_id`가 이 전제를 감시한다 — 레코드가 `attempt_id`를 갖게 되는 순간 실패하며, 그때가 재검토 시점이다.

## 9-1. 구현 중 정정 1건 — `finalize`의 패키지 위치

처음에는 `finalize.py`를 `lib_py/loop/`에 두었는데, 그러면 `publish_event`(=`lib_py.delegation`)가 **형제 패키지를 임포트**하게 되어 freeze 하에서 트리가 섞인다. Phase 1이 명문화하고 Phase 2a에서 엔진 배치를 정정하게 만들었던 바로 그 규칙이며, 기존 가드 테스트(`test_delegation_package_imports_no_sibling_lib_py_modules`)가 전체 스위트에서 이를 검출했다.

**매니페스트는 job의 리포트 디렉터리에 쓰이고 에이전트가 호출하는 CLI는 delegation 진입점이므로, `finalize`는 `lib_py/delegation/`에 속한다.** `lib_py.loop`가 `lib_py.delegation`을 임포트하는 방향은 허용된다. 같은 규칙에 두 번 걸린 셈이며, 가드가 두 번 다 잡았다.

## 10. Phase 3 인계

1. `preexec_fn`: 2b도 데몬을 스폰하지 않아 미노출 유지. 알림 flush는 기존 구독자 프로세스 안에서 수행한다.
2. 부수효과의 **원격** 확인(실제 push 도달 여부 등)은 비범위 — 증거의 존재·대응까지만 검증한다.
3. `agy`/`hermes`/`opencode` 자동완료는 정지 상태 실측 증거 확보 후 별도 판단.