relay-handoff

name	relay-handoff
description	다른 세션/에이전트(orch·캡틴·워커)에 작업·분석·지시를 전달(릴레이·핸드오프)하거나 herdr로 프롬프트를 주입할 때 반드시 사용. 핸드오프 프롬프트 5요소 템플릿 + herdr 주입·제출검증 레시피. 트리거 - "orch에 전달/넘겨줘", "세션에 릴레이", "워커에게 회신", "herdr로 보내", herdr agent prompt 사용 전.

relay-handoff — 세션 간 핸드오프·릴레이 표준 절차

ROB-NNN 은 비공개 이슈 트래커 참조이며, 각 규칙 옆 본문이 근거를 자립 설명한다.

🔴 도메인 오버레이: $AGENT_SKILLS_DOMAIN/relay-handoff.md 가 존재하면 이 스킬을 적용하기 전에 반드시 먼저 읽어라. 없으면 아래 추상 규칙만 적용한다.

원칙 1: 전송 주장 ≠ 전달 증거. 주입 명령의 정상 응답은 접수증거가 아니다 — 제출 검증(§3)을 완주해야 "전달 완료"를 보고할 수 있다. 원칙 2: 출처와 승인을 분리하라. 수신 세션은 릴레이된 판단의 출처를 검증할 수 없다 — "누가 분석했고, 운영자가 어디까지 승인했는지"를 명시하지 않으면 수신측이 전부 실행하거나 전부 보류한다.

1. 핸드오프 프롬프트 5요소 (전부 포함할 것)

1. 출처(provenance): 작성 세션/도구, 작성 시각, "미검증 단일 세션 산출물" 여부. 분석 원문이 길면 ~/work/herdr-inbox/<이름>-<날짜>.md로 저장(provenance 헤더 2줄 포함, 요약·변형 금지 — 줄 수로 자가검증)하고 프롬프트에는 경로만. 🔴 발신자 식별은 세션 이름 + 역할 + pane_id 로 한다. 모델명으로 하지 마라. herdr 주입에는 발신자 정보가 없어 수신측은 본문의 자기소개만 믿는다. 모델명은 정체성이 아니다 — 여러 세션이 같은 모델을 쓰고, /model 기본값이 바뀌면 하루아침에 겹친다 (2026-08-04 실사고: claude-mock(상류 분석)이 Fable 5 로 전환된 뒤 "fable"로 자기소개 → 수신측 orch 가 운영자 직속 fable 세션의 릴레이와 구분 못 하고 "fable 릴레이"로 정본 기록).
   • 형식: 출처: <세션이름> (<역할>, <pane_id>) — 예: claude-mock (상류 분석, wB:p4R)
   • "운영자 직속" 표기는 실제 운영자 직속 세션만 쓴다. 상류 분석 세션이 운영자 결정을 전달할 때는 "운영자가 <세션이름> 대화에서 확정"으로 쓴다 — 전달자와 결정자를 섞지 마라.
2. 운영자 결정 vs 분석가 권고 분리: "운영자 결정 (이것만이 승인 범위다)" 블록에 승인/보류를 항목별 명시. 권고는 "참고용 — 별도 승인 전 실행 금지"로 격리.
3. 검증 지시: 릴레이 내용의 무거운 주장(발견·부재 단정)은 실행 전 독립 재검증을 명시. 부재 단정("코드 0건" 류)은 전수 탐색 후에만 인용 가능. 시각 정보는 stale — 현재 시각 기준 재판단 지시.
4. 계약·레인 대조: 제안된 행동이 수신측 레인 계약 문서(자원 배정맵 등)와 충돌하는지 먼저 판정 — 충돌 시 실행 말고 결정 요청 회신.
5. 작업 방식 + 규모 T·스폰 방식 명시: Linear 이슈 등록, 최신 origin/main 기준 worktree (가능하면 wt switch --create — raw git worktree add는 .env 미복사), 하드 인바리언트 불변. T 제안: Tn (근거: …) 형식으로 반드시 적는다(spawn-worker §2-1, 최종 판정은 lane orch가 서명) — 명시가 없으면 수신측이 최대 강도로 해석해 과잉검증이 난다. "PR+적대검증"을 반사적으로 쓰지 말 것: T1은 워커 1명·자체검증, 적대검증은 T2부터다. 🔴 스폰 방식도 적어라 — T2 이상은 herdr 워커 필수(하네스 서브에이전트 금지, spawn-worker §2-3). 비워두면 수신측이 자기 서브에이전트로 처리해 급 배정·쿼타 분산·검증 독립성이 전부 우회된다(2026-08-01 ROB-1196 실사고: T3 실행계약 코드를 orch 세션 안에서 구현·검증까지 처리). 급(S+~C)은 모델명을 적지 말고 scopefuel --recommend 로 뽑게 한다. 급을 모르겠으면 비워두고 "작업 성격"만 적어라 — 급 판정은 스폰하는 쪽(orch) 책임이다. 상류가 어설프게 매기면 오배정이 난다(ROB-1189: 상류가 T1/B 로 매겨 두 번 BLOCKED).

작성 주체별 결정 권한 (누가 무엇을 결정하는지 섞으면 ②급 오배정이 재발한다):

주체	결정·기록하는 것	결정하면 안 되는 것
상류 분석 세션	문제·AC, 근거와 exact ref, 운영자 승인 범위, 모름, 예상 변경 표면, mutation 가능성, T 제안과 근거	최종 grade, quota pool, worker 모델, merge 권한
lane orch	authoritative T 재판정, grade와 근거, scopefuel 후보, spawn mode, worktree·정지점·verifier	다른 lane job 동시 소유
운영자	정책 예외, destructive/live/deploy	일상적 배정

• 상류의 T는 제안일 뿐이다 — 위 항목 5에는 반드시 T 제안: Tn (근거: …) 형식으로 쓰고, 최종 판정은 orch가 서명한다(surface-derived floor는 spawn-worker §2-1 — 상류 제안보다 floor가 높으면 orch는 하향을 거부하고 상향만 받는다).
• 수신측: T 제안이 누락된 릴레이는 거부하지 말고 누락을 기록하고 직접 판정·서명한다 ("T 제안(상류) 없음 → T 확정(서명) = Tn" — 2026-08-03 orch-mock 관행의 성문화). 단 같은 상류에서 누락이 반복되면 판정은 하되 상류에 반송 한 줄을 남겨라 — 누락은 교차 확인(상류 제안 vs 수신 재판정의 불일치 신호)을 없앤다. kr-intraday-corpus 에서 상류 T2 vs orch T3 불일치가 토스 토큰 표면 누락을 드러낸 것이 그 신호의 가치다.
• 급(S+~C)은 상류가 정하지 않는다 — 항목 5에 이미 반영됨(비워두고 "작업 성격"만 적기).
• 긴 분석은 durable artifact 제출 순간 상류 세션에서 끝난다. orch가 추가 정보가 필요하면 job을 붙들지 말고 필드별 NEEDS_INFO를 남긴다.

머리에 항상: (같은 내용이 두 번 보이면 재실행 금지) + 접수 확인으로 <지정 도구/파일 읽기> 1회 먼저 실행해줘.

2. 대상 검증 (오배송 방지)

기억으로 라우팅 금지. wrk find가 표준 해석 경로다 — 이름 조회 → 없으면 탭 라벨 폴백 → 후보의 화면 마지막 줄까지 함께 낸다(실판별이 규율이 아니라 기본 동작이 된다).

wrk find <이름|라벨>              # pane_id + cwd + 화면 미리보기
wrk find <이름|라벨> --pane-only  # 스크립트용

화면을 보고 직전 작업 내용(KR/US/crypto·역할)이 기대와 맞는지 확인한 뒤에만 주입한다. 라벨이 여러 pane에 걸리면 wrk find가 전부 표시하고 실패한다 — 자동 선택하지 말 것.

⚠️ 이름은 유실될 수 있다 — 재부팅·세션 재시작으로 agent 이름이 날아가도 탭 라벨은 살아남는 경우가 많다(07-31 실측: 재부팅 후 orch 포함 다수가 무명이 됐으나 라벨은 보존). 그래서 이름 단독 조회로 "없다"고 단정하지 말고 라벨 폴백까지 확인한다. 이름이 붙어 있어도 화면이 기대와 다를 수 있다(같은 실측에서 이름은 orch인데 화면은 권한 오류 상태였다).

대상 부재 시(이름·라벨 모두 없음 — 세션 사망·herdr 재시작): 자동 재생성은 없다 — 릴레이를 실패로 보고하고 운영자 에스컬레이션. orch/캡틴을 임의 재스폰하지 않는다(재생성은 운영자 결정. 새 orch는 같은 cwd에서 claude --continue+auto-memory+Linear+inbox로 상태 복원 가능 — 상태 정본이 세션 밖에 있는 이유).

운영자가 대화 중인 세션(orch·kiro-mock 등 interactive 세션) 주입 주의: 주입은 컴포저에 텍스트를 넣으므로 사용자 타이핑과 충돌할 수 있다. read에서 컴포저에 입력 중 텍스트/슬래시 피커가 보이면 주입 보류 — 비어 있을 때 보내거나 운영자에게 직접 붙여넣기를 제안.

타겟 네이밍 관례: 1순위 타겟은 agent 이름(herdr agent rename <pane> <이름>), 폴백은 탭 라벨이다. 관례: 허브=orch / 운영자 대화 세션=<도구>-<용도>(예 kiro-mock) / 캡틴=<도메인>-captain / 워커=<이슈>-<역할>. 탭 생성 시 라벨을 같은 이름으로 넣어두면 이름이 유실돼도 wrk find가 찾고 wrk name-sync --apply로 일괄 복구된다. 이름이 좋아도 화면 실판별은 생략 금지.

3. herdr 주입 + 제출 검증 (생략 절대 금지)

# 1) 긴 프롬프트는 반드시 파일로 (인라인은 셸 이스케이프로 깨짐)
~/.local/bin/herdr agent prompt <target> "$(cat prompt.txt)"

# 2) 제출 검증 — 정상 JSON(agent_prompted)이 와도 믿지 마라
~/.local/bin/herdr agent read <target> --lines 10
#    🔴 "❯ 뒤 텍스트"는 미제출 증거가 아니다 — Claude Code 는 idle 에서 "다음에 이걸
#       쓰실래요?" 제안을 같은 자리에 렌더하고, 실입력과의 차이는 색뿐인데 agent read 는
#       색을 버린다(2026-08-02 실측: 이 기준으로 멀쩡한 세션에 2회 불필요 재주입 — 워커
#       pane 조차 "❯ orch에 검증 완료 보고 릴레이해줘" 제안을 달고 있었다).
#    ✅ 미제출의 확실한 증거 둘뿐: ① "[Pasted text #N +M lines]" 칩 잔존
#       ② 방금 주입한 원문이 컴포저에 그대로 보임(짧은 텍스트는 칩 없이 정착— 2026-08-04 실측)
#    ✅ 평시 판정은 상태 전이(idle→working). 대상이 이미 working 이면 전이 무증거 —
#       추측 재주입 말고 수신측 산출물을 기다려라.
#    "Press up to edit queued messages" + 칩 없음 = 제출됨(큐 대기) → return 보내지 마라(중복 위험)
#    (읽기 소스: 빈 recent 는 --source visible 재시도, 전사 회수는 herdr 0.8+
#     --source recent-unwrapped 권장)

# 3) 미제출일 때만:
~/.local/bin/herdr agent send-keys <pane_id> return   # 키 이름은 return (cr은 invalid)
#    최후수단: herdr pane run <pane_id> ""

# 4) 2)로 재확인. 중요 지시면 수신측의 접수 확인 도구 호출 흔적까지 확인.

함정: 대상이 이미 working이면 상태 전이로 판별 불가(JSON·status 둘 다 무증거). auto-compact 직후/resume 상태 세션은 주입을 조용히 삼킴 — 유실 의심 시 재주입 헤더에 [재주입 — 이전 미션 유실] 명시. 에이전트→orch 방향 보고는 send 금지(사용자 타이핑과 충돌) — 파일 인박스 ~/work/herdr-inbox/ 사용.

4. 완료 보고 형식

• 저장 파일 경로 + 줄 수 (원문 보존 증거)
• 주입 결과 요약 + 제출 검증에서 본 것(제출/미제출/큐잉) → 취한 조치 → 최종 상태
• 이 릴레이에서 실행하지 않은 것 한 줄 명시 (릴레이 내용의 조사·외부 mutation·이슈 변경 등)

실사례 (이 절차의 근거, 2026-07-29)

• herdr agent prompt가 스톨 에러 없이 정상 JSON을 반환하고도 3건 연속 미제출 → 수동 구제.
• kiro-cli가 이 절차를 프롬프트로 받아 완주: 223줄 원문 보존, 제출 검증에서 "큐 대기"를 정확히 판별해 불필요한 return을 억제, 미실행 명시 보고까지. 절차 자체는 도구 불문 실행 가능.
• 수신측(orch)이 5요소를 전부 소비: 접수 확인 → 계약 충돌 판정(실행 차단) → 승인 범위만 착수.