# 사용자 여정: 에이전트가 비공개 레포를 쓰도록 내가 허락한다

## 0. 문서 정보

| 항목 | 내용 |
|---|---|
| 여정 식별자 | `JRN-repo-access` |
| 여정명 | 에이전트가 비공개 레포를 쓰도록 내가 허락한다 |
| 상태 | 초안 (v0.3.1) |
| 담당자 | 미지정 |
| 최종 수정일 | 2026-11-05 |
| 달성 가치 | V8 목적에 맞는 작업 환경 선택 · V1 격리된 작업 공간 |
| 연결 문서 | PRD [`repo-access`](../prd/repo-access.md)(AC-H1~H5) · [`approval-gate`](../prd/approval-gate.md)(AC-F3·F5·F6) · mockup `repo-access.html`·`gated-workspace.html` ([매핑](../mockups/README.md)) |

> 이 여정은 [`JRN-approval-gated-work`](./JRN-approval-gated-work.md)의 **갈래**다. 그 여정은
> "밖으로 나가는 호출마다 승인한다"를 다루고, 이 여정은 그중 **레포 클론**을 떼어 내
> "어느 레포를 받게 할지는 내가 미리 정해 둔다"로 바꾼다. 허용 목록이 있는 배포에서 `git_clone`은 호출마다
> 승인을 받지 않는다 — 여기서 하는 **레포 단위로 오래 남는 허락**이 그 호출의 문이다. 다른 외부 호출의 승인은
> 여전히 그 여정의 `STP-approval-decide`가 맡는다.
> 승인 게이트가 걸린 모든 타입의 세션(지금은 `minimax-code`)이 같은 경험을 한다.

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

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

## 2. 여정 정의

**대상 사용자 (페르소나)**
P1 멀티세션 작업자 ([README](./README.md#p1-멀티세션-작업자)).
이 여정에서 P1은 **일을 맡기는 사람이자 레포 접근을 허락하는 사람**이다.

**진입 맥락**
게이트가 걸린 에이전트 세션에 일을 맡겼는데, 그 일에 **내 레포**가 필요하다. 비공개 레포는 자격 증명이 있어야 하고,
그렇다고 에이전트에게 계정 전체에 닿는 토큰을 줄 수는 없다. 클론할 때마다 휴대폰으로 승인하는 것도 번거롭다.

**트리거**
에이전트가 "이 레포를 받아야 하는데 허용 목록에 없다"며 접근을 요청해 오거나, 작업자가 앞으로 맡길 일을 위해
레포를 미리 열어 두려고 한다.

**사용자 목표**
에이전트가 받을 수 있는 레포를 **레포 단위로** 내가 정하고, 그 밖의 레포에는 어떤 경로로도 닿지 않게 하는 것.
허락은 한 번 하면 다음 세션에서도 유지되고, 언제든 거둘 수 있어야 한다.

**완료 기준**
작업자가 허락한 레포를 에이전트가 **승인 없이 바로 받아 그 위에서 작업을 이어간다.**
허락하지 않은 레포는 공개 레포라도 받아지지 않는다.

## 3. 단계별 상세

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

### `STP-access-request` 에이전트가 레포 접근을 요청한다

- **사용자 행동**: 세션 콘솔에서 에이전트가 "이 레포는 허용 목록에 없다"는 이유로 클론에 실패한 것과,
  이어서 **접근 요청을 남겼다**는 표시를 본다. 어떤 레포를 왜 원하는지가 그 자리에 적혀 있다.
  요청을 남긴 것만으로는 아무것도 열리지 않는다는 것을 안다.
- **터치포인트**: 승인 게이트 워크스페이스의 출력 콘솔 (mockup `gated-workspace.html`) · 세션 MCP의 접근 요청 도구
- **생각·감정**: "얘가 뭘 열어 달라는 거지?" — 레포 이름과 이유가 없으면 판단을 미루게 된다.
  "요청했다고 바로 열리는 건 아니겠지?"라는 확인 욕구도 있다.
- **페인포인트 / 이탈 위험**: 클론 실패만 보이고 다음 할 일이 안 보이면 작업자는 에이전트가 막혔다고 읽고
  일을 거둔다 → 실패 사유(허용 목록에 없음)와 **요청이 접수되어 어디서 결정하는지**를 함께 남긴다.
- **관련 AC**: AC-H4 (보조 AC-H5)

### `STP-access-review` 대기 중인 요청을 검토한다

- **사용자 행동**: control plane의 레포 접근 화면을 연다. 다른 화면과 같이 Authelia 로그인(인그레스) 뒤에 있어,
  이미 로그인한 사람에게는 따로 묻지 않고 곧바로 열린다.
  대기 중인 요청이 맨 위에 보이고, 각 요청에 레포·요청한 세션·이유·요청 시각이 있다.
  그 아래에 지금 허락된 레포 목록이 있다.
- **터치포인트**: control plane 레포 접근 화면의 대기 요청 목록 · 허용 목록 (mockup `repo-access.html`)
- **생각·감정**: "어느 세션이 왜 이걸 원하지?" — 요청한 세션을 알아볼 수 없으면 승인 근거가 사라진다.
  "지금 열려 있는 게 뭐였더라?"도 같은 화면에서 확인하고 싶다.
- **페인포인트 / 이탈 위험**: 요청과 허용 목록이 다른 화면에 흩어져 있으면 중복 허락·누락이 생긴다
  → 대기 요청과 허용 목록을 한 화면에 두고, 이미 허락된 레포에 대한 요청은 그 사실을 표시한다.
  같은 Authelia 세션을 화면마다 다시 묻으면 확인 절차만 늘어나므로, 이 화면도 다른 화면과 같은 문 하나 뒤에 둔다.
- **관련 AC**: AC-H2 (보조 AC-H4)

### `STP-access-decide` 허락하거나 거절한다

- **사용자 행동**: 요청을 허락하면 그 레포가 허용 목록에 오르고 요청은 목록에서 빠진다. 거절하면 요청만 사라진다.
  요청 없이 레포를 직접 추가하거나, 더는 필요 없는 레포를 목록에서 지울 수도 있다.
- **터치포인트**: 레포 접근 화면의 요청 카드 허락·거절 버튼, 허용 목록의 추가 입력과 삭제 버튼 (mockup `repo-access.html`)
- **생각·감정**: "이 레포 하나만 열리는 거 맞지?" — 계정 전체가 열리는 것처럼 보이면 허락을 주저한다.
  "나중에 거둘 수 있나?"를 알아야 가볍게 허락한다.
- **페인포인트 / 이탈 위험**: 허락의 범위가 화면에서 읽히지 않으면 허락 자체를 피한다
  → 항목은 `owner/repo` 하나이고 읽기 전용이라는 것을 버튼 옆에 적고, 삭제가 바로 효력을 갖는다는 것을 보인다.
- **관련 AC**: AC-H2, AC-H1

### `STP-private-clone` 허락한 레포를 받아 이어간다

- **사용자 행동**: 에이전트가 같은 레포를 다시 받으려 하면 이번에는 승인 요청 없이 바로 클론되고,
  에이전트가 그 위에서 일을 이어간다. 허락하지 않은 레포는 같은 순서로도 받아지지 않는다.
- **터치포인트**: 승인 게이트 워크스페이스의 출력 콘솔과 공유 작업물 패널 (mockup `gated-workspace.html`)
- **생각·감정**: "열어 줬으니 이제 알아서 받겠지" — 허락한 레포를 받을 때 다시 묻지 않아야 허락이 결정으로 느껴진다.
- **페인포인트 / 이탈 위험**: 허락했는데도 실패하면 어느 단계가 막았는지 몰라 같은 요청을 반복한다
  → 실패는 사유별로(허용 목록에 없음 · 허용 목록을 확인할 수 없음 · 레포를 찾을 수 없음 · 토큰 발급 실패) 구분해 남긴다.
- **관련 AC**: AC-H5 (상위 AC-F3·F5)

## 4. 분기·예외 흐름

| 상황 | 처리 | 이어지는 단계 |
|---|---|---|
| 요청을 거절함 | 요청만 지우고 허용 목록은 그대로 — 에이전트의 다음 클론도 같은 사유로 실패 | `STP-private-clone` |
| Authelia에 로그인하지 않은 채 화면을 엶 | 인그레스가 화면에 닿기 전에 Authelia 로그인으로 돌려보내고, 로그인하면 이 화면으로 돌아온다 | `STP-access-review` |
| 이미 허용된 레포에 대한 요청 | 요청을 새로 만들지 않고 이미 허용됨을 알림 | `STP-private-clone` |
| 요청 없이 미리 열어 두고 싶음 | 허용 목록에 직접 추가 | `STP-access-decide` |
| 허용 목록에서 지운 뒤 다시 클론 | 허용 목록에 없음으로 실패하고 다시 요청 | `STP-access-request` |
| 허용 목록을 확인할 수 없음 | 클론하지 않고 사유를 남김 — 허용 목록이 유일한 문이라 닫힌 쪽으로 실패한다 | `STP-private-clone` |
| 공개 레포를 받음 | 공개 레포도 허용 목록에 있어야 받는다 — 없으면 같은 요청 절차 | `STP-access-request` |

## 5. 측정 지표

| 지표 | 정의 | 목표 |
|---|---|---|
| 요청 결정 시간 | 접근 요청 → 허락·거절까지 시간 (p50/p95) | TBD (허락 절차의 체감 비용) |
| 요청 허락률 | 허락된 요청 수 / 전체 요청 수 | TBD (지나치게 낮으면 에이전트가 불필요한 레포를 찾는 신호) |
| 허용 목록 크기 | 허용 목록 항목 수 | TBD (계속 늘기만 하면 정리 동작이 안 쓰이는 신호) |
| 허용 목록 밖 클론 시도 | 허용 목록에 없음으로 실패한 비공개 클론 수 | TBD (0이 아니어도 정상 — 거부 자체가 성공) |

## 6. 변경 이력

| 버전 | 날짜 | 변경 내용 | 작성자 |
|---|---|---|---|
| v0.3.1 | 2026-11-05 | `approval-gated` 타입 제거 반영 — 이 갈래가 붙는 세션을 「승인 게이트가 걸린 세션」으로 고쳐 적고 PRD 링크를 `approval-gate.md`로 옮겼다. 단계·식별자 변화 없음 | Claude |
| v0.3 | 2026-10-24 | 레포 접근 화면의 앱 자체 로그인을 걷었다(사용자 결정) — 화면은 다른 화면과 같은 Authelia forward-auth 하나 뒤에 있다. `STP-access-review`의 로그인 단계·로그인 안내 터치포인트를 지우고 분기 2행을 인그레스 로그인으로 바꿨다. 허용 목록에서 「Added by」(추가한 사람)를 지우고 출처만 남겼다 | Claude |
| v0.2 | 2026-10-24 | 허용 목록이 있는 배포에서 `git_clone`의 호출 승인을 걷었다(사용자 결정) — 허락한 레포는 승인 없이 받고, 공개 레포도 목록에 있어야 받는다. 분기 6·7행을 그에 맞게 바꿨다 | Claude |
| v0.1 | 2026-10-24 | 최초 작성 — 비공개 레포 허용 목록과 접근 요청(AC-H1~H5) 신설에 따라 신설. 계약 서술은 AC로 위임하고 사용자 관측 경험만 남김 | Claude |
