[epic] Nexus 재편: 협업 산출물 엔진 코어 슬림화 + 기능 spin-off 분화 + 디스패치 효율화

[jinon86]

배경 — 무엇이 문제인가

이 레포의 주 사용 목적은 에이전트간 협업을 통한 코드 등 산출물 구현이다. 그런데 레포가 비대화되면서, 가장 자주 쓰는 기능인 A2A 산출물 구현 루프가 solo 작업 대비 느리고 비효율적으로 변하고 있다는 문제의식이 운영자로부터 제기됐다 (2026-07-22).

실측 (2026-07-22, main 기준):

항목	수치
packages/broker	620 ts 파일 / 222k LOC (src/core/만 396 파일)
packages/docker-runner	37k LOC
packages/openclaw-plugin-a2a	33k LOC
스크립트 표면	375개 (scripts/ 174 + packages/broker/scripts/ 201)

체감을 뒷받침하는 계측 근거:

• 에이전트 품질 벤치 파일럿 1회차: solo가 A2A 협업에 2:0 승리 (Family Wiki LOG-20260722-gwakga-2/3, ND-1319 프로토콜 v2)
• worker: generic implementation-intent tasks are auto-acked as succeeded with zero work (false success) #1593 — implementation 태스크가 무작업 succeeded로 auto-ack (false success)
• implementation-pipeline: verifier anchoring and non-synchronous gate completion observed live — harden the contract #1596 — verifier 앵커링/비동기 게이트 완료 관측
• implementation-lane readiness: 노드별 implementationCapability 프로파일 발행 + fleet 모델 티어 정책 #1597 — Claude-native implementation 워커가 T2에 1개뿐

목표

1. 코어 재정의: 이 레포의 주 기능 = 에이전트간 협업을 통한 산출물 구현 엔진 (디스패치 → 클레임 → 실행 → 검증 → 증거 회수 → 머지 루프). 이 루프의 속도와 신뢰성이 제1 지표.
2. 분화(spin-off): A2A를 통해 얻은 기능 중 독립 제품 가치가 있는 것을 정리해 별도 패키지/레포로 분화.
3. 단순화: 코어 코드를 깔끔하게 — 모듈 경계 명확, 스크립트 표면 축소, 실험 잔재 정리.
4. 효율화: 디스패치 루프가 solo 대비 경쟁력을 가지도록 레이턴시/세레모니 비용 절감.

핵심 원칙 — modularize-first, extract-second

222k LOC 모놀리스를 바로 다레포로 쪼개면 계약 버저닝·크로스레포 CI·릴리스 조율 비용이 먼저 발생한다. 그래서:

1. 1단계: 레포 내부에서 독립 packages/* 경계로 분리 (import 경계 + 버전 계약 강제)
2. 2단계: 경계가 안정되고 독립 릴리스 수요가 확인된 것만 별도 레포로 추출

전 과정 #1500 (core JSON-RPC TCK blocking gate)을 분할 회귀의 안전판으로 사용한다.

Spin-off 후보

기준: 독립 제품 가치 + 경계 명확성 + 계약 안정성.

후보	내용	근거/선행
a2a-policy-referee	선언적 정책 문서(a2a.broker.policy.v1) + create/claim 시점 warn/enforce 평가. 경계가 가장 깨끗 (broker-policy.ts + broker-task-admission.ts)	#1480 (이미 후보 등록), #1355 G1-d T1+T2 enforce 전환 완료(2026-07-22, LOG-20260722-soonwook-7)
에이전트 작업증명(attestation) 툴킷	"이 산출물을 어떤 에이전트가 어떤 검증으로 만들었는가"의 증명 체인: finalizer verdict 서명/keyring + 결정적 evidence assembly(JCS contentDigest) + redaction gate + spawn gate + budget counter. A2A 밖에서도 쓸 수 있는 독립 가치가 가장 큰 덩어리	#1383 V-c, #1537 Phase-1 패킷 체인
bounded-review-lifecycle	PR 리뷰 루프 거버넌스: 계약 4종(IntentContract/ReviewLineageBudget/FindingLedger/ReviewReceipt) + record-mode 엔진. PR 리뷰 관리 제품으로 독립 가능	#1518 Phase 1~3a 머지 완료

코어에 남기는 것: 디스패치/클레임/실행/완료/증거 회수 루프 + 워커·라운드·상태저장 + TCK.

코어 슬림화 축

• worker.ts churn-relief — ✅ 종료(2026-08-17): packages/broker/src/worker.ts 1,780 → 182줄(-89.8%), 잔여는 조합 루트(composition root) 최소 집합. 판정 readback: 코멘트
• 스크립트 375개 → [P1] Reverse-ratchet the 100/150 script surface and reduce broker-core complexity #1503 reverse-ratchet으로 사용 증거 없는 것부터 제거 (✅ [P1] Reverse-ratchet the 100/150 script surface and reduce broker-core complexity #1503 closed 07-27)
• src/core/ 396 파일의 실험 잔재(a2a-* 단발 모듈, dialectic 계열 등)를 기능별 cohesive 모듈로 통합
• [P2] Repository hygiene: prune stale branches and reduce review ownership concentration #1507 브랜치 위생 + 리뷰 소유 집중 완화 (✅ [P2] Repository hygiene: prune stale branches and reduce review ownership concentration #1507 closed 08-07)
• [P1] Define the shared-state and HA contract beyond process-local security and SQLite #1504 공유 상태/HA 계약은 슬림화 이후의 코어 형상을 전제로 재논의

효율화 축 — "왜 solo보다 느린가"를 정면으로

가설: 현재 A2A 경로는 단순 태스크에도 중량 세레모니(라운드/리뷰/증거/파이널라이저/독립리뷰)를 전부 태운다.

1. 레이턴시 예산 계측 (선행 필수): create→claim→start→complete 구간별 시간 계측. 지금은 체감만 있고 구간별 수치가 없다. 측정 없는 리팩토링 금지.
2. fast lane: 저위험·단순 태스크는 경량 경로(단일 워커, 간이 증거), 고위험만 풀 세레모니. G1 정책 엔진 enforce로 "어떤 태스크가 고위험인가"를 선언적으로 구분할 기반이 이미 있음.
3. 신뢰 비용 제거: worker: generic implementation-intent tasks are auto-acked as succeeded with zero work (false success) #1593 false success, implementation-pipeline: verifier anchoring and non-synchronous gate completion observed live — harden the contract #1596 게이트 계약 — 효율 이전에 신뢰 문제. 느린 것보다 "돌렸는데 안 한 것"이 더 비싸다.

단계 계획

• P0 — 계측: 디스패치 루프 레이턴시 예산 측정 + 비효율 지점 특정. 산출물: 구간별 레이턴시 리포트 + fast lane 대상 분류 초안.
• P1 — 첫 패키지 분리: packages/policy-referee (또는 packages/broker-policy)를 레포 내 독립 패키지로 추출. 경계가 가장 깨끗하고 실전 enforce 검증이 시작된 상태. #1480을 작업 이슈로 승격.
• P2 — attestation 패키지화: verdict 서명 + evidence assembly + redaction/spawn gate를 독립 패키지로 묶고, 독립 레포 분화 여부를 경계 안정성 보고 판단.
• P3 — fast lane 설계 + 코어 다이어트: 스펙 먼저(spec-first 관례 준수), 스크립트/모듈 정리와 병행.
• 전 단계: TCK blocking + 실 A2A 태스크 증거(카나리/벤치) 유지, broker reload·배포는 별도 운영자 승인.

성공 지표 (제안)

• 디스패치 루프 p50/p95 레이턴시의 계측 baseline 대비 개선
• 벤치 파일럿 재측정에서 A2A 협업이 solo와 최소 대등 (2:0 패배 → 역전 또는 조걸별 승부)
• 코어(broker) LOC/파일 수·스크립트 수 감소 추이
• spin-off 패키지의 독립 테스트/버저닝 통과

비목표 (non-goals)

• 당장의 다레포 분할 (extract는 2단계 판단)
• broker/Gateway 재시작·배포 자동화 (계속 별도 승인)
• A2A 공개(public readiness) 스코프 변경 — Repository hardening umbrella: 2026-07 Nexus 종합평가 후속 — 집행·호환성·구조·DX·위생 #1498/r3/r4 트랙과 별개로 조율

관련 이슈 매핑

• 우산/위생: Repository hardening umbrella: 2026-07 Nexus 종합평가 후속 — 집행·호환성·구조·DX·위생 #1498, [P1] Reverse-ratchet the 100/150 script surface and reduce broker-core complexity #1503, [P2] Add coverage and lint quality floors without duplicating the release gate #1506, [P2] Repository hygiene: prune stale branches and reduce review ownership concentration #1507
• 게이트: [P0] Promote core JSON-RPC TCK categories from measurement to blocking gates #1500, [P0] Enforce finalizer verdict and CodeQL policy in the active main ruleset #1499
• spin-off: Repo candidate: a2a-policy-referee — 브로커 강제 정책 엔진을 독립 제품으로 분화 #1480 (policy-referee), 심판(referee) 트랙: "반드시 A2A여야 하는 이유"의 제품화 — 내구 웨이브 + 정책 엔진 + 서명 출처증명 (G1–G3) #1354/G1: 정책 엔진 — 산재한 정책의 선언적 통합 + 브로커 강제 (warn→enforce) (#1354) #1355 (referee 트랙, G1 enforce 완료), [P0][Spec-first] Bound PR review loops and preserve frozen intent #1518 (review lifecycle), 서명된 파이널라이저 verdict + 게이트 강제 — 판단(외부·검증가능)과 강제(브로커·기계적)의 분리 (심판 트랙) #1383 (verdict 서명), [epic] Phase-1 guardrails for container-lane sub-agent fanout (cost counter · spawn gate · redaction gate · determinism) #1537/[epic] Phase-2: wire the claude-code container lane for sub-agent fanout (mode+rollback · Sonnet-5 tier · Task tool+roster · prompt/env/turns · runtime packet consumption) #1543 (subagent 패킷/fanout)
• 신뢰/효율: worker: generic implementation-intent tasks are auto-acked as succeeded with zero work (false success) #1593, implementation-pipeline: verifier anchoring and non-synchronous gate completion observed live — harden the contract #1596, implementation-lane readiness: 노드별 implementationCapability 프로파일 발행 + fleet 모델 티어 정책 #1597
• 상태/HA: [P1] Define the shared-state and HA contract beyond process-local security and SQLite #1504

[jinon86]

P0 계측 완료 — 디스패치 루프 레이턴시 예산 리포트 (2026-07-22, soonwook)

측정 방법

양 브로커의 broker_audit_events를 읽기 전용 SQL로 분석(라이브 변경 없음). 기간 2026-06-26 ~ 07-22(약 4주), T1 1,054태스크 / T2 558태스크, 태스크별 create→claim→start→terminal 타임스탬프 조인.

구간별 레이턴시 (terminal 태스크)

stage	T1 p50	T1 p90	T1 p95	T2 p50	T2 p90	T2 p95
queue (create→claim)	3.5s	15.7s	1.9m	3.4s	17.1s	32.9s
pickup (claim→start)	0.5s	2.0s	9.8s	0.7s	2.1s	3.0s
exec (start→end)	1.4m	3.5m	4.9m	35.8s	1.9m	2.3m
e2e (create→end)	1.6m	4.6m	5.7m	44.0s	2.3m	3.4m

발견 (확정)

• F1. 브로커 디스패치 자체는 병목이 아니다. queue+pickup p50이 ~4초. "A2A가 느리다"의 주 원인은 브로커 대기가 아니다.
• F2. 실패율 ~23%가 최대 낭비. T1 23.5%(245/1,044), T2 23.3%(130/558). 특정 노드 집중: sogyo 41%(73/177), dungae 62%(69/111) — 두 노드가 실패의 과반. 실패 태스크의 재디스패치/수동 수습이 체감 비효율의 큰 축일 것.
• F3. 테일 레이턴시는 워커 가용성 문제. T1 최대 queue 21.4h(nosuk 오프라인 대기), T2 daegyo(모바일) queue 3.7~4.8h + pickup 9.3h(클레임 후 기기 수면). p95 밖이지만 발생하면 당일 작업이 멈춘다.
• F4. propose_patch 테일이 길다. T1 p95 27.3m, T2 p95 2.8h — 산출물 구현 루프(사용자 주 사용)의 지연은 여기서 체감된다. intent별 e2e: analyze T1 p50 1.6m / T2 46.9s vs propose_patch T1 p50 2.2m.
• F5. exec이 e2e의 대부분 — 브로커 가시 범위에서 solo 대비 갭은 설명되지 않는다. 갭의 상당부분은 브로커 밖 세레모니(웨이브 계획, 번들 조립, finalizer, 리뷰 라운드, PR 플로우 대기)에서 발생한다는 것이 가설. 벤치 solo 2:0도 이 층을 가리킨다.

fast lane 대상 분류 초안

분류	근거	제안
fast lane 후보: analyze 단발	전체의 8294%. p50 e2e 46s1.6m, 단일 워커·단발·읽기 중심	경량 경로: 단일 워커, 간이 증거, 리뷰 라운드 생략
풀 세레모니 유지: propose_patch / implementation	산출물 변경, 실패 비용 큼, 테일 김	finalizer + 독립 리뷰 + 증거 체인 유지, 테일 개선은 워커 풀 확충으로
모바일/간헐 노드(daegyo 등)	pickup 9.3h 관측	fast lane라도 claim 게이트(가용성 확인 후 디스패치) — G1 정책 엔진 enforce와 연계 지점
실패 다발 노드(sogyo, dungae)	41%/62% 실패	fast lane 이전에 실패 원인 분류가 선행 (P0-2)

다음 계측 제안 (P0-2)

1. 브로커 밖 세레모니 시간: 디스패처 측 타이밍(웨이브 계획 수립→create, succeeded→finalizer→PR) — 브로커 DB만으로는 안 보이는 구간. 오케스트레이션 로그 계측 포인트 추가 설계 필요.
2. 실패 원인 분류: sogyo/dungae 실패 태스크의 실패 사유 분포(워커 오류 vs 타임아웃 vs false success 계열 worker: generic implementation-intent tasks are auto-acked as succeeded with zero work (false success) #1593).
3. exec 내부 분해: claim→첫 LLM 호출, evidence 조립 시간 (워커 측 계측).

원시 집계(태스크별 stage 타임스탬프)는 soonwook에 보관. 재현 쿼리는 코멘트 스레드에 추가 가능.

[jinon86]

P0-2(b) 완료 — 실패 원인 분류 리포트 (2026-07-22, soonwook)

P0 레이턴시 계측(issuecomment-5045766682)의 F2(실패율 23%) 후속. 양 브로커의 실패 태스크 전수 분류(읽기 전용): audit 실패 이벤트의 tombstone 마스킹을 걷어내고(태스크당 최초 실질 실패 사유 채택), broker_tasks.payload.error의 내부 코드/발췌로 2차 분류.

실패 분류 (4주, unique failed tasks)

원인 버킷	T1 (250)	T2 (132)
handler_exit_1 (워커 핸들러 exit 1)	176 (70%)	100 (76%)
acceptance_failed (수용 기준 미달)	30 (12%)	12 (9%)
finalizer (독립 리뷰/verdict 거부)	28 (11%)	3
provenance_invalid	—	8 (7/6 배포 갭 인시던트 시기)
reviewer_same_as_author (디스패치 오용)	6	—
기타 (칼나리/명세 오류/timeout 등)	10	9

포커스 노드: sogyo exit_1 59/73(81%), dungae exit_1 67/69(97%) — 두 노드의 실패는 거의 전부 워커 핸들러 실패.

발견

• F6. 실패의 본체는 브로커 세레모니가 아니라 워커 실행 실패. 그런데 그 70%+가 "handler exited with code 1"이라는 무정보 메시지로 끝난다.
• F7. dungae 스파이크는 일시적이었다. 주별: 6월말 6 → 7월 W1 118 → W2 14 → W34 0. cccb 러너 리빌드/sonnet-5 롤아웃(7/87/11) 시기와 정확히 겹치며, 이후 소멸 — 당시 러너 이미지/핸들러 문제였을 개연성이 높고 현재는 재발하지 않음.
• F8. sogyo는 지속적이다. 주별 72/38/28/8로 감소 추세지만 7/20·7/22에도 실패 발생 (baemin deepseek 수집 레인, nexus 독립 리뷰 레인). dungae와 원인 계열이 다를 가능성.
• F9. acceptance_failed/finalizer 거부는 게이트 정상 작동일 가능성이 크다 (실패가 아니라 방어). 효율 지표에서는 worker 실행 실패와 분리해서 봐야 한다.
• F10. 관측성 갭이 원인 규명의 제1 블로커. ① 브로커 error.details.excerpt가 핸들러 출력의 앞 ~2KB만 보존 — 실제 에러는 보통 출력 끝에 있어 유실. ② 러너 컨테이너는 종료 즉시 삭제돼 워커 측 로그 잔재 없음. ③ journald에도 미경유. sogyo는 excerpt 자체가 비어있는 경우가 다수.

제안 (우선순위)

1. 실패 시 에러 테일 보존 (broker 변경, 작고 효과 큼): excerpt를 head+tail 또는 tail 우선으로. 이것만으로 exit_1의 70%가 원인 가시화.
2. 실패 컨테이너 로그 보존 (docker-runner 옵션): 실패 시에만 bounded 보존 (예: 최근 N건, cap 바이트).
3. sogyo 재현 디버그 라운드: 1·2가 생긴 뒤 원인 확정. 그 전까지 sogyo는 fast lane/중요 레인 배정 보수적으로.
4. 효율 지표 정의 시 게이트성 실패(acceptance/finalizer)와 실행 실패(exit_1/timeout)를 분리 집계.

fast lane 설계에의 입력

• 브로커 세레모니 경량화(fast lane)만으로는 체감 실패율이 안 낮아진다 — 실패의 본체는 워커 실행 품질. fast lane 설계와 병행해서 핸들러 안정화/관측성(F10)이 선행 또는 동반되어야 한다.
• F7 교훈: 러너 롤아웃 시기의 실패 스파이크는 배포 등급/칼나리 체계([P1] Define the shared-state and HA contract beyond process-local security and SQLite #1504)와 연계하면 조기 차단 가능.

[jinon86]

P1 완료 — policy-referee 패키지 추출 (PR #1613 머지 7b755d8d, 2026-07-23 KST)

• packages/policy-referee (a2a-policy-referee, unscoped): 정책 엔진(스키마/validator/클스 도출/순수 평가)을 git mv 이력 보존 이관, 브로커는 패키지 경계(워크스페이스 의존 + exports)로 소비. 계약 불변 — 라이브 영향 없음
• 추출 과정에서 드러난 경계 강제 사항(다음 추출의 체크리스트): ① TS composite project references로 빌드 순서 ② 커버리지 플로어의 패키지별 이전(broker-policy 84% floor를 신 패키지 coverage:baseline로 보존) ③ broker-core isolation 게이트상 @openclaw 스코프 불가 → unscoped ④ README Package/Repository Map + parity surface + CI 잡 등록
• 검증: 브로커 4003/4003, 패키지 16/16, capstone/parity/layout/matrix/isolation 전 게이트 green, seoseo-ai 독립 승인
• 잔여 메모: policy-referee 커버리지 스크립트를 schema-v1 reporter 계약으로 승격 + capstone 패키지 목록 편입은 후속
• 다음: P2(attestation 패키지화) — 동일 패턴 적용