# 사용자 여정: 밖으로 나가는 일마다 내가 승인하고 맡긴다

## 0. 문서 정보

| 항목 | 내용 |
|---|---|
| 여정 식별자 | `JRN-approval-gated-work` |
| 여정명 | 밖으로 나가는 일마다 내가 승인하고 맡긴다 |
| 상태 | 초안 (v0.1) |
| 담당자 | 미지정 |
| 최종 수정일 | 2026-09-03 |
| 달성 가치 | V8 목적에 맞는 작업 환경 선택 · V3 끊김 없는 세션 연속성 |
| 연결 문서 | PRD [`approval-gated-workload`](../prd/approval-gated-workload.md)(AC-F1~F6) · [`lifecycle`](../prd/lifecycle.md)(AC-B1~B3) · mockup `new-session.html`·`gated-workspace.html` ([매핑](../mockups/README.md)) |

> 이 여정은 `approval-gated` 타입의 **사용 루프**를 담는다. 타입을 고르는 순간은
> [`JRN-agent-prompt-loop`](./JRN-agent-prompt-loop.md)의 `STP-workload-choice`가 계속 담당하며,
> 그 화면에 세 번째 선택지가 생긴 것이 이 여정의 진입점이다.
> 같은 자리의 다른 타입은 `JRN-shell-interaction`(`shell`)과 `JRN-agent-prompt-loop`(`claude-code`)다.
> **타입이 달라도 플랫폼 보장은 같다**는 것이 V8의 핵심이고, 이 여정은 거기에
> "밖으로 나가는 순간만 사람이 끊는다"를 더한다.

## 1. 서비스 개요 (참고)

[`JRN-session-creation`](./JRN-session-creation.md#1-서비스-개요-참고)과 동일. 가치 정의는 [`../values.md`](../values.md).

## 2. 여정 정의

**대상 사용자 (페르소나)**
P1 멀티세션 작업자 ([README](./README.md#p1-멀티세션-작업자)).
이 여정에서 P1은 **일을 맡기는 사람이자 승인하는 사람**이다 — 알림을 받는 대상이 플랫폼 전역 단일 값이라
현재는 두 역할이 한 사람으로 겹친다. 두 역할을 나눠야 하는지는 [README 미해결 항목](./README.md#-열린-결정) 참고.

**진입 맥락**
에이전트에게 맡기고는 싶은데, 그 에이전트가 **내가 모르는 사이에 밖으로 나가는 것**은 곤란한 일이다.
사내망·미검증 스크립트·비용이 붙는 API가 섞인 작업이라 "무엇을 언제 불렀는지"가 사후 로그가 아니라
**사전 승인**으로 남아야 한다.

**트리거**
"맡기긴 할 건데, 밖으로 나갈 때는 나한테 물어봐"라는 판단.

**사용자 목표**
자연어로 일을 맡기되, 외부로 나가는 호출은 하나도 빠짐없이 자기 손을 거치게 하는 것.
그러면서도 승인 때문에 세션이 조용히 사라지거나 결과가 유실되지 않는 것.

**완료 기준**
작업자가 **승인한 외부 호출의 결과 위에서 후속 요청을 성공**시킨다 —
즉 승인이 만들어낸 결과물(파일·응답)이 다음 프롬프트의 문맥으로 이어진다.

## 3. 단계별 상세

> 단계 식별자는 순번이 아닌 슬러그다. 순서가 바뀌어도 식별자는 유지한다.

### `STP-gated-prompt-submit` 게이트가 걸린 채로 일을 맡긴다

- **사용자 행동**: 하려는 일을 자연어로 써서 보낸다. 보낸 뒤 응답을 기다리지 않고 다른 일을 봐도 된다.
  이 세션에서는 에이전트가 **스스로 밖에 나갈 수 없다**는 것을 알고 맡긴다 — 외부가 필요한 일이면
  반드시 자기에게 물어보러 온다.
- **터치포인트**: 승인 게이트 워크스페이스의 프롬프트 입력 행과 "외부 접근은 승인 필요" 표시 (mockup `gated-workspace.html`) · 프롬프트 write API
- **생각·감정**: "보낸 게 접수는 된 건가?" — 즉시 반환되므로 접수 표시가 없으면 두 번 보낸다.
  동시에 "얘가 몰래 밖에 나가진 않겠지?"라는 확인 욕구가 있다.
- **페인포인트 / 이탈 위험**: 게이트가 걸려 있다는 사실이 화면에 없으면, 작업자는 이 타입을 고른 이유를 잊고
  일반 에이전트 세션과 구분하지 못한다 → 워크스페이스에 **이 세션은 밖으로 나갈 때 승인을 받는다**는 사실을
  상시 표시하고, 접수 여부는 즉시 보여준다. 거절(너무 큼·대기열 포화)은 사유와 다음 행동을 함께 알린다.
- **관련 AC**: AC-F3, AC-F2 (보조 AC-F1)

### `STP-approval-wait` 승인을 기다리는 것이 보인다

- **사용자 행동**: 화면을 보고 있으면 응답이 이어지다가 **"승인 대기"에서 멈추는 것**을 본다.
  무엇을 하려다 멈췄는지(어떤 도구·어디로)가 그 자리에 적혀 있어서, 승인할지 판단할 재료가 화면 안에 있다.
  기다리는 동안 탭을 닫아도 되고, 세션이 그 사이 접히지 않는다는 것을 안다.
- **터치포인트**: 승인 게이트 워크스페이스의 출력 콘솔에 나타나는 대기 배지와 대기 항목 (mockup `gated-workspace.html`)
- **생각·감정**: "멈춘 건가, 기다리는 건가?" — 둘이 구분되지 않으면 실패로 읽고 같은 일을 다시 시킨다.
  "지금 자리를 비워도 되나?"라는 불안도 함께 온다.
- **페인포인트 / 이탈 위험**: 대기가 실패처럼 보이면 중복 제출이 쌓이고, 대기 중에 세션이 접히면
  승인해도 실행할 자리가 없어 승인 자체가 헛돈다
  → 대기를 **진행 중인 상태로** 표시하고, 대기하는 동안에는 자동 동결이 진행되지 않게 한다.
  대기 중에도 앞서 받은 출력은 그대로 남아 있고 이어 보기가 끊기지 않는다.
- **관련 AC**: AC-F3 (상위 AC-B1)

### `STP-approval-decide` 승인하거나 거절한다

- **사용자 행동**: 승인 요청을 받아 내용을 확인하고 승인하거나 거절한다. 자리를 비웠더라도 알림으로 받는다.
  결정은 세션 화면 밖(승인 게이트웨이)에서 이뤄지고, 결과는 세션 화면으로 돌아와 보인다.
- **터치포인트**: 외부 승인 게이트웨이의 알림과 승인 화면 (이 레포의 mockup 대상 아님 — 아래 페인포인트 참고) · 결정 후의 콘솔 표시 (mockup `gated-workspace.html`)
- **생각·감정**: "이걸 왜 하려는 거지?" — 요청만 있고 맥락이 없으면 판단할 수 없어 일단 거절하게 된다.
  반대로 승인이 너무 잦으면 내용을 안 보고 누르는 습관이 든다.
- **페인포인트 / 이탈 위험**: 승인 화면이 세션 화면과 완전히 분리되어 있어 **같은 일을 두 화면에서 따라가야 한다**
  → 세션 쪽 콘솔에 요청 식별자와 대상이 남아 두 화면을 눈으로 이을 수 있게 한다.
  승인 피로가 쌓이면 게이트가 형식이 되므로, 요청 하나가 무엇을 여는지 한 줄로 읽히게 한다.
- **관련 AC**: AC-F3, AC-F6

### `STP-gated-result` 승인한 결과 위에서 이어간다

- **사용자 행동**: 승인했다면 그 호출의 결과가 콘솔에 이어 붙고, 거절했다면 실패했다는 사실이 남는다.
  어느 쪽이든 세션은 살아 있어 다음 프롬프트를 바로 보낸다. 승인이 만들어낸 파일은 다음 실행이 그대로 이어 쓴다.
  한동안 두었다 돌아와도 그 파일과 대화 맥락이 남아 있다.
- **터치포인트**: 승인 게이트 워크스페이스의 출력 콘솔과 공유 작업물 패널 (mockup `gated-workspace.html`) · 세션 목록의 `snapshot` 배지 → 복원 후 같은 화면
- **생각·감정**: "거절했다고 세션이 죽지는 않네." — 거절이 세션을 끝내면 작업자는 애초에 거절하지 않게 된다.
  "쉘·에이전트 세션이랑 똑같이 돌아오네"라는 확인이 V8의 약속이다.
- **페인포인트 / 이탈 위험**: 거절이 세션 전체를 실패로 만들면 게이트가 위험 장치가 아니라 **작업 중단 장치**가 되어
  아무도 이 타입을 고르지 않는다 → 거절·만료는 그 도구 호출만 실패시키고 세션과 대기열은 유지한다.
  동결·복원 뒤 결과물이 사라지면 승인의 의미가 없어지므로, 승인으로 얻은 파일은 접었다 펴도 그대로 남긴다.
- **관련 AC**: AC-F5, AC-F3 (상위 AC-B1·B2·B3, 보조 AC-F4)

## 4. 분기·예외 흐름

| 상황 | 처리 | 이어지는 단계 |
|---|---|---|
| 승인함 | 그 호출만 실행하고 결과를 이어 붙인다 | `STP-gated-result` |
| 거절함 | 실제 호출 없이 도구만 실패시키고 세션·대기열은 유지 | `STP-gated-result` |
| 결정 없이 만료·시간 초과 | 거절과 동일하게 처리하고 사유를 표시 | `STP-gated-result` |
| 에이전트가 스스로 밖에 나가려 함 | 네트워크 경계에서 막혀 실패한다 — 우회 경로가 없다 | `STP-gated-prompt-submit` |
| 대기 중 자리를 오래 비움 | 대기 중에는 자동 동결이 진행되지 않는다 | `STP-approval-wait` |
| 대기 중 직접 접거나 지움 | 대기 중인 호출을 취소하고 실패로 마감 | `JRN-manual-freeze` · `JRN-session-deletion` |
| 프롬프트가 너무 큼 · 대기열 포화 · 누적 출력 한계 | `JRN-agent-prompt-loop`과 동일하게 사유와 함께 거절 | `STP-gated-prompt-submit` |
| 보고 있는 중 세션이 접힘 | 자동 복원하지 않고 복원 화면으로 안내 | `JRN-idle-resume`의 `STP-reaccess` |
| 게이트 없이 빠르게 쓰고 싶어짐 | 기존 세션을 바꾸지 않고 새 세션을 만든다 | `JRN-agent-prompt-loop`의 `STP-workload-choice` |

## 5. 측정 지표

| 지표 | 정의 | 목표 |
|---|---|---|
| 승인 대기 시간 | 대기 표시 → 결정까지 시간 (p50/p95) | TBD (게이트의 체감 비용) |
| 승인률 | 승인된 요청 수 / 전체 승인 요청 수 | TBD (지나치게 높으면 게이트가 형식화된 신호) |
| 무결정 비율 | 만료·타임아웃으로 끝난 요청 수 / 전체 승인 요청 수 | TBD (알림 도달 실패 신호) |
| 대기 중 중복 제출률 | 대기 표시 중에 같은 내용이 재제출된 비율 | TBD (대기≠실패 표시 실패 신호) |
| 대기 중 동결 발생 | 승인 대기 중에 동결된 세션 수 | TBD (0 유지 — AC-F3 위반 신호) |
| 게이트 우회 시도 | 네트워크 경계에서 차단된 워크로드 파드의 외부 연결 시도 수 | TBD (0이 아니어도 정상 — 차단 자체가 성공) |
| 타입 선택 분포 | `approval-gated` 선택 세션 수 / 전체 생성 세션 수 | TBD (V8 채택 신호) |

## 6. 변경 이력

| 버전 | 날짜 | 변경 내용 | 작성자 |
|---|---|---|---|
| v0.1 | 2026-09-03 | 최초 작성 — `approval-gated` 워크로드 타입(AC-F1~F6) 신설에 따라 신설. 계약 서술은 AC로 위임하고 사용자 관측 경험만 남김 | Claude |