<!-- task=m-change-aware-test-routing/05_user_entrypoint_runner_contract plan=0 tag=USER_ROUTE_RUN -->

# Plan - USER_ROUTE_RUN

## 이 파일을 읽는 구현 에이전트에게

`CODE_REVIEW-cloud-G07.md`의 구현 에이전트 소유 섹션을 채우는 것이 구현의 마지막 단계다. 구현 후 계획의 검증 명령을 실행하고 실제 stdout/stderr를 남긴 뒤 active 파일을 유지한 채 리뷰 준비 상태를 보고한다. 사용자 결정, 사용자 소유 환경, scope 충돌이 구현을 막으면 사용자에게 직접 묻지 말고 `사용자 리뷰 요청` 섹션에 근거와 재개 조건을 기록한다. finalization, `complete.log`, archive 이동은 code-review 전용이다.

## 배경

`user-entrypoints` 에픽의 요청 문구와 dry-run 보고 계약은 직접 보강되었다. 남은 큰 작업은 dry-run 추천을 실제 실행 wrapper와 결과 record 계약으로 연결하는 일이다. 현재 `run_test_by_change.sh`는 분류/추천만 출력하며, `run_speed_test.sh`와 `run_stability_test.sh`는 아직 없다.

## 사용자 리뷰 요청 흐름

구현 중 blocker는 active review stub의 `사용자 리뷰 요청` 섹션에 기록한다. 구현 에이전트는 chat에서 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. code-review가 사용자 리뷰 요청의 타당성을 검증하고 실제 `USER_REVIEW.md` 작성 여부를 결정한다.

## Roadmap Targets

- Milestone: `agent-roadmap/milestones/change-aware-test-routing.md`
- Task ids:
  - `routing-skill`: 프로젝트 스킬 또는 기존 `run-proto-socket-test-matrix` 스킬에 "작업된 내용을 바탕으로 테스트" 요청 라우팅 절차를 추가한다.
  - `auto-test-shell`: `run_test_by_change.sh` 자동 라우팅 shell을 추가해 `테스트 해봐` 요청의 기본 실행 단위로 쓴다.
  - `speed-test-shell`: `run_speed_test.sh` 속도 전용 shell을 추가해 quick/daytime과 full/nightly 후보를 관리한다.
  - `stability-test-shell`: `run_stability_test.sh` 안정성 전용 shell을 추가해 quick stress와 nightly long-run 후보를 관리한다.
  - `test-profile-docs`: `agent-test/local/rules.md`와 관련 profile 문서에 4개 shell entrypoint와 주야간 분리 기준을 반영한다.
  - `result-report-contract`: 결과 보고에 선택 이유, 실행 명령, 결과 record, skipped/nightly-pending 항목을 남긴다.
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- `agent-roadmap/current.md`
- `agent-roadmap/milestones/change-aware-test-routing.md`
- `agent-ops/rules/project/rules.md`
- `agent-ops/rules/common/rules-roadmap.md`
- `agent-ops/rules/common/philosophy.md`
- `agent-ops/skills/common/router.md`
- `agent-ops/skills/common/plan/SKILL.md`
- `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`
- `agent-ops/skills/project/run-proto-socket-test-matrix/SKILL.md`
- `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_test_by_change.sh`
- `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_full_test.sh`
- `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh`
- `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh`
- `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh`
- `agent-test/local/rules.md`
- `agent-test/local/proto-socket-full-matrix.md`
- `agent-test/local/proto-socket-performance-baseline.md`

### 테스트 환경 규칙

- test_env: `local`.
- `agent-test/local/rules.md` 존재 및 읽음.
- 적용 profile: `agent-test/local/proto-socket-full-matrix.md`, `agent-test/local/proto-socket-performance-baseline.md`.
- 적용 명령: shell syntax는 `bash -n`, route 계약은 `run_test_by_change.sh --route <mode> --dry-run`, 실제 성능/안정성 실행은 기존 `run_performance.sh --quick` 및 `run_stress.sh --quick ...` 계열을 사용한다.
- full matrix 실행은 `run_matrix.sh --all`, full route는 기존 `run_full_test.sh` 계약을 보존한다.
- route wrapper 검증은 temp repo smoke로 수행한다. 실제 long-running `--full` 성능/안정성은 nightly-pending 후보로만 남기고 즉시 PASS 근거로 쓰지 않는다.

### 테스트 커버리지 공백

- `run_test_by_change.sh`는 현재 dry-run 추천 출력만 검증되어 있고, 추천을 실행 결과 record로 연결하는 regression test file은 없다.
- 신규 wrapper shell은 deterministic temp repo smoke와 `bash -n`으로 검증한다.
- 실제 전체 matrix/performance/stress 장시간 실행은 이 plan의 구현 검증에서 강제하지 않는다. quick 실행 wrapper와 nightly-pending 출력 계약을 확인한다.

### 심볼 참조

- renamed/removed symbol: none.

### 분할 판단

- split decision policy를 평가했다.
- single plan으로 둔다. 변경은 하나의 ownership boundary(`run-proto-socket-test-matrix` skill/script contract) 안에 있고, `run_test_by_change.sh`, `run_speed_test.sh`, `run_stability_test.sh`, docs/report wording을 분리하면 실행 command와 문서 계약이 중간 상태에서 어긋날 수 있다.
- API-vs-call-site split은 적용하지 않는다. 새 shell entrypoint는 기존 wrapper들과 같은 디렉터리의 얇은 CLI 계약이며 call site는 skill/docs뿐이다.
- test strategy는 동일한 shell syntax + temp repo route smoke로 묶어 검증 가능하다.
- terminal/CLI workflow라 review lane은 cloud로 올린다.

### 범위 결정 근거

- `anchor-runner-options`는 범위 밖이다. 수정 언어 중심 x5를 full 5x5 없이 실행하는 세부 anchor executor는 별도 Task로 남긴다.
- 실제 야간 `run_performance.sh --full`, `run_stress.sh --full` 실행은 범위 밖이다. wrapper는 nightly-pending 후보 command와 PASS 제외 계약만 남긴다.
- `run_full_test.sh` 동작 변경은 범위 밖이다. full route는 이미 완료된 `full-test-route`/`full-test-shell` 계약을 보존한다.
- 언어별 구현 코드, proto, transport 동작 변경은 범위 밖이다.

### 빌드 등급

- build: `cloud-G07`; review: `cloud-G07`.
- shell/CLI workflow, stdout/stderr parsing, exit-status and result-record contracts가 중심이므로 cloud review가 필요하다.

## 구현 체크리스트

- [ ] [USER_ROUTE_RUN-1] `run_test_by_change.sh`의 dry-run 계약을 보존하면서 non-dry-run auto route가 실행 계획, 실행 결과, record 경로를 남기게 한다.
- [ ] [USER_ROUTE_RUN-2] `run_speed_test.sh`를 추가해 speed route dry-run 보고 후 낮 시간 quick 성능 실행과 nightly-pending full 후보 보고를 수행한다.
- [ ] [USER_ROUTE_RUN-3] `run_stability_test.sh`를 추가해 stability route dry-run 보고 후 quick stability 실행과 hard gate/nightly-pending 후보 보고를 수행한다.
- [ ] [USER_ROUTE_RUN-4] `run-proto-socket-test-matrix` skill과 `agent-test/local` profile 문서를 새 실행 wrapper 및 결과 보고 계약과 일치시킨다.
- [ ] [USER_ROUTE_RUN-5] shell syntax, focused temp repo route smoke, deterministic `rg --sort path`로 검증하고 실제 stdout/stderr를 review stub에 남긴다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [USER_ROUTE_RUN-1] Auto route execution contract

`문제`: `run_test_by_change.sh:13` usage는 `--dry-run`을 지원하지만 현재 script는 dry-run 여부와 관계없이 분류/추천 출력만 수행한다. `auto-test-shell`은 `테스트 해봐` 요청의 기본 실행 단위와 결과 기록을 요구한다.

`해결 방법`: `run_test_by_change.sh`에 dry-run 보존과 non-dry-run 실행 분기를 명확히 둔다. 실행 분기는 먼저 현재 추천 표를 출력하고, 지원 가능한 `recommended` 후보를 기존 wrapper command로 실행하며, unsupported anchor 후보는 PASS가 아닌 skipped 항목으로 record에 남긴다. 최소 지원 범위는 `performance-quick`, `stability-quick`, `functional-full`, `runner-docs-selfcheck`이며 `functional-server-x5`/`functional-client-x5`/`functional-both-x5`의 precise anchor 실행은 `anchor-runner-options` 범위로 남긴다.

`수정 파일 및 체크리스트`:

- [ ] `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_test_by_change.sh`

`테스트 작성`: 별도 test file은 만들지 않는다. shell smoke와 temp repo route smoke로 검증한다.

`중간 검증`:

```bash
bash -n agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_test_by_change.sh
```

### [USER_ROUTE_RUN-2] Speed route wrapper

`문제`: `agent-roadmap/milestones/change-aware-test-routing.md:77`은 `run_speed_test.sh`를 요구하지만 `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/`에는 해당 파일이 없다.

`해결 방법`: `run_speed_test.sh [--dry-run]`을 추가한다. dry-run은 `run_test_by_change.sh --route speed --dry-run`만 출력한다. non-dry-run은 `performance-quick` recommended가 있으면 `run_performance.sh --quick`을 실행하고, `performance-full`/`stability-full` nightly-pending은 실행하지 않은 후보와 command를 출력/record한다.

`수정 파일 및 체크리스트`:

- [ ] `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_speed_test.sh`

`테스트 작성`: 별도 test file은 만들지 않는다. temp repo smoke로 speed route recommendation과 nightly-pending 후보를 검증한다.

`중간 검증`:

```bash
bash -n agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_speed_test.sh
```

### [USER_ROUTE_RUN-3] Stability route wrapper

`문제`: `agent-roadmap/milestones/change-aware-test-routing.md:78`은 `run_stability_test.sh`를 요구하지만 해당 파일이 없다.

`해결 방법`: `run_stability_test.sh [--dry-run]`을 추가한다. dry-run은 `run_test_by_change.sh --route stability --dry-run`만 출력한다. non-dry-run은 `stability-quick` recommended가 있으면 `run_stress.sh --quick --profile sustained,parallel,payload` 또는 기존 quick hard-gate에 맞는 좁은 profile 조합을 실행하고, `stability-full` nightly-pending은 실행하지 않은 후보와 command를 출력/record한다.

`수정 파일 및 체크리스트`:

- [ ] `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stability_test.sh`

`테스트 작성`: 별도 test file은 만들지 않는다. temp repo smoke로 stability route recommendation과 hard gate wording을 검증한다.

`중간 검증`:

```bash
bash -n agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stability_test.sh
```

### [USER_ROUTE_RUN-4] Skill and local test docs

`문제`: `SKILL.md:49`의 script list는 아직 auto/speed/stability 실행 wrapper를 보여주지 않고, local profile도 새 wrappers와 결과 record 계약을 고정하지 않는다.

`해결 방법`: `SKILL.md`와 local profiles에 `run_test_by_change.sh`, `run_speed_test.sh`, `run_stability_test.sh`, `run_full_test.sh`의 dry-run/non-dry-run 차이, result record, skipped/nightly-pending PASS 제외 기준을 맞춰 쓴다.

`수정 파일 및 체크리스트`:

- [ ] `agent-ops/skills/project/run-proto-socket-test-matrix/SKILL.md`
- [ ] `agent-test/local/rules.md`
- [ ] `agent-test/local/proto-socket-full-matrix.md`
- [ ] `agent-test/local/proto-socket-performance-baseline.md`

`테스트 작성`: 별도 test file은 만들지 않는다. deterministic search로 문서 계약을 검증한다.

`중간 검증`:

```bash
rg --sort path -n "run_test_by_change.sh|run_speed_test.sh|run_stability_test.sh|run_full_test.sh|nightly-pending|PASS 아님|결과 기록|hard gate" agent-ops/skills/project/run-proto-socket-test-matrix agent-test/local
```

### [USER_ROUTE_RUN-5] Route smoke and final verification

`문제`: shell route 변경은 현재 작업트리 diff에 따라 출력이 달라진다. 실제 검증은 고정된 temp repo 입력으로 추천/실행/record 계약을 확인해야 한다.

`해결 방법`: temp repo를 만들고 `run_test_by_change.sh`, `run_speed_test.sh`, `run_stability_test.sh`를 복사해 transport/performance/stability 파일 변경을 만든 뒤 dry-run과 가능한 non-dry-run command를 확인한다. long-running full은 실행하지 않고 nightly-pending 후보로 남는지만 확인한다.

`수정 파일 및 체크리스트`:

- [ ] `CODE_REVIEW-cloud-G07.md`의 `검증 결과`에 실제 명령과 stdout/stderr를 기록한다.

`테스트 작성`: 별도 test file은 만들지 않는다.

`중간 검증`:

```bash
tmp="$(mktemp -d /tmp/proto-user-route-run.XXXXXX)" && repo="$tmp/repo" && mkdir -p "$repo/agent-ops/skills/project/run-proto-socket-test-matrix/scripts" "$repo/agent-test/runs" "$repo/go/transport" && cp agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_test_by_change.sh agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_speed_test.sh agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stability_test.sh "$repo/agent-ops/skills/project/run-proto-socket-test-matrix/scripts/" && cd "$repo" && git init -q && git config user.email smoke@example.com && git config user.name Smoke && printf 'package transport\n' > go/transport/server.go && git add . && git commit -q -m baseline && base_ref="$(git rev-parse --short HEAD)" && for profile in proto-socket-full-matrix proto-socket-performance-quick proto-socket-stress-quick; do record="agent-test/runs/20260610-000000-${profile}.md"; printf '%s\n' '---' 'overall_result: PASS' '---' '' "- git ref: $base_ref" > "$record"; done && git add agent-test/runs && git commit -q -m records && printf 'package transport\n' > go/transport/stress_payload_1mb.go && bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_test_by_change.sh --route auto --dry-run && bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_speed_test.sh --dry-run && bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stability_test.sh --dry-run
```

## 수정 파일 요약

| 파일 | 항목 |
|---|---|
| `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_test_by_change.sh` | USER_ROUTE_RUN-1, USER_ROUTE_RUN-5 |
| `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_speed_test.sh` | USER_ROUTE_RUN-2, USER_ROUTE_RUN-5 |
| `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stability_test.sh` | USER_ROUTE_RUN-3, USER_ROUTE_RUN-5 |
| `agent-ops/skills/project/run-proto-socket-test-matrix/SKILL.md` | USER_ROUTE_RUN-4 |
| `agent-test/local/rules.md` | USER_ROUTE_RUN-4 |
| `agent-test/local/proto-socket-full-matrix.md` | USER_ROUTE_RUN-4 |
| `agent-test/local/proto-socket-performance-baseline.md` | USER_ROUTE_RUN-4 |
| `agent-task/m-change-aware-test-routing/05_user_entrypoint_runner_contract/CODE_REVIEW-cloud-G07.md` | USER_ROUTE_RUN-5 |

## 최종 검증

```bash
bash -n agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_test_by_change.sh
bash -n agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_speed_test.sh
bash -n agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stability_test.sh
rg --sort path -n "run_test_by_change.sh|run_speed_test.sh|run_stability_test.sh|run_full_test.sh|nightly-pending|PASS 아님|결과 기록|hard gate" agent-ops/skills/project/run-proto-socket-test-matrix agent-test/local
tmp="$(mktemp -d /tmp/proto-user-route-run.XXXXXX)" && repo="$tmp/repo" && mkdir -p "$repo/agent-ops/skills/project/run-proto-socket-test-matrix/scripts" "$repo/agent-test/runs" "$repo/go/transport" && cp agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_test_by_change.sh agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_speed_test.sh agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stability_test.sh "$repo/agent-ops/skills/project/run-proto-socket-test-matrix/scripts/" && cd "$repo" && git init -q && git config user.email smoke@example.com && git config user.name Smoke && printf 'package transport\n' > go/transport/server.go && git add . && git commit -q -m baseline && base_ref="$(git rev-parse --short HEAD)" && for profile in proto-socket-full-matrix proto-socket-performance-quick proto-socket-stress-quick; do record="agent-test/runs/20260610-000000-${profile}.md"; printf '%s\n' '---' 'overall_result: PASS' '---' '' "- git ref: $base_ref" > "$record"; done && git add agent-test/runs && git commit -q -m records && printf 'package transport\n' > go/transport/stress_payload_1mb.go && bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_test_by_change.sh --route auto --dry-run && bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_speed_test.sh --dry-run && bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stability_test.sh --dry-run
git diff --check
```

모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
