# PLAN cloud G07 - m-change-aware-test-routing/01_change_classifier_core

## 작업 목표

`변경 기반 테스트 라우팅 정형화` 마일스톤의 첫 Epic 중 마지막 PASS 지점 탐색, 실제 변경 파일 산정, path/domain 분류 기반을 구현한다. 이 단계는 테스트를 실행하지 않고, 후속 라우팅이 사용할 분류 결과를 재현 가능한 shell 출력으로 제공하는 데 집중한다.

## Roadmap Targets

- Milestone: `agent-roadmap/milestones/change-aware-test-routing.md`
- Completed task ids:
  - `last-pass-point`
  - `diff-source`
  - `path-domain-map`

## 분석 결과

현재 활성 마일스톤은 `변경 기반 테스트 라우팅 정형화`이며 첫 Epic `[change-classifier]`의 네 task 중 `risk-escalation`은 분류 결과를 입력으로 받는 후속 정책 작업이다. 따라서 이번 plan은 공통 분류 기반만 다루고, `risk-escalation`은 `02+01_risk_routing_rules`에서 처리한다.

현재 runner 구조는 `run_matrix.sh`, `run_performance.sh`, `run_stress.sh`가 실제 검증 실행과 record 생성을 담당한다. 새 분류 단계는 이 runner들을 대체하지 않고, 사용자 요청 라우팅 shell이 실행 전에 참조할 변경 분석 결과를 만든다.

`agent-test/runs/`는 gitignored local 결과 디렉터리이며, 최신 PASS record는 route별 record type/profile이 다르다. 따라서 단순 최신 파일이 아니라 요청 route와 맞는 PASS record를 선택해야 한다. PASS record가 없거나 record의 `git ref`가 현재 저장소에서 해석되지 않으면 현재 HEAD와 작업트리 diff만으로 보수 fallback해야 한다.

## 분할 판단

이 작업은 split task group `m-change-aware-test-routing`의 첫 번째 작업이다.

- `01_change_classifier_core`: 마지막 PASS record, diff source, path/domain 분류를 구현한다.
- `02+01_risk_routing_rules`: 01의 분류 결과를 받아 functional/performance/stability 후보와 wider/full 승격 규칙을 구현한다.

분리 이유는 classifier가 데이터 수집/분류 책임이고, risk routing은 정책 결정 책임이기 때문이다. classifier 출력 계약이 먼저 고정되어야 후속 라우팅 규칙을 안전하게 구현할 수 있다.

## 구현 범위

- 새 shell helper 또는 wrapper를 추가한다.
  - 권장 위치: `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/`
  - 권장 이름: `test_route_common.sh` 또는 `run_test_by_change.sh`의 `--classify-only` 경로
- 마지막 PASS record 선택 로직을 추가한다.
  - 입력 route: `auto`, `speed`, `stability`, `full`
  - route별 후보 profile:
    - `auto`: full matrix, performance quick/full, stress quick/full 중 PASS
    - `speed`: `proto-socket-performance-*` PASS/WARN 중 측정 성공 record
    - `stability`: stress/performance record 중 stability hard gate PASS
    - `full`: `proto-socket-full-matrix` PASS
  - record frontmatter의 `overall_result`와 실행 정보의 `git ref`를 읽는다.
- 실제 diff source를 만든다.
  - 마지막 PASS ref와 `HEAD` 사이의 tracked 변경
  - staged/unstaged/untracked 변경
  - 삭제 파일 포함
  - archive 제외 규칙 준수: `agent-task/archive/**`, 일반 `agent-roadmap/archive/**`는 분석 대상으로 삼지 않는다.
- path/domain 분류를 구현한다.
  - 언어 구현: `dart/`, `go/`, `kotlin/`, `python/`, `typescript/`
  - proto/schema: `proto/`, `**/*.proto`
  - transport: `tcp`, `ws`, `wss`, `transport`, 관련 crosstest/harness path
  - communicator/codec/framing: communicator, packet, protobuf binding, generated packet files, frame logic
  - queue/gateway/concurrency: queue, gateway, worker, parallel, sustained, stress harness
  - performance harness: `bench/`, `run_performance.sh`, `run_stress.sh`
  - test docs/rules: `agent-test/local/**`, runner skill docs
  - docs-only: tracked docs/README/PORTING guide만 변경된 경우
- classifier 결과 출력 계약을 만든다.
  - route
  - selected last PASS record/ref 또는 fallback reason
  - changed files
  - detected languages
  - detected domains
  - docs-only 여부
  - untracked 포함 여부

## 제외 범위

- 실제 테스트 실행은 하지 않는다.
- risk escalation, anchor x5 선택, nightly pending 판단은 이번 작업에서 최종 결정하지 않는다.
- `run_matrix.sh`, `run_performance.sh`, `run_stress.sh`의 기존 실행 의미를 바꾸지 않는다.
- 개인 remote host/path/credential 원문을 출력하거나 tracked 문서에 기록하지 않는다.

## 구현 체크리스트

- [ ] 기존 runner style을 따라 `set -u` 또는 `set -uo pipefail`를 사용하되, gitignored 디렉터리 부재를 안전하게 처리한다.
- [ ] `agent-test/runs/`가 없거나 PASS record가 없을 때 fallback 결과를 출력한다.
- [ ] route별 최신 PASS 후보 선택을 구현한다.
- [ ] record의 `git ref`가 없거나 `git rev-parse`로 해석되지 않으면 fallback reason을 남긴다.
- [ ] tracked diff, staged/unstaged diff, untracked 파일을 합쳐 중복 제거된 변경 파일 목록을 만든다.
- [ ] archive 접근 금지 범위를 분석 대상에서 제외한다.
- [ ] path/domain classifier를 shell 함수나 작은 awk/sed helper로 재사용 가능하게 둔다.
- [ ] classifier 출력이 후속 task에서 파싱 가능하도록 stable key/value 또는 Markdown table 형식을 사용한다.
- [ ] `--help` 또는 잘못된 option 처리로 사용법을 출력한다.

## 검증 계획

필수:

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

또는 공통 helper만 만든 경우:

```bash
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/test_route_common.sh --route auto --classify-only
```

보조:

```bash
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_test_by_change.sh --help
git diff --check -- agent-ops/skills/project/run-proto-socket-test-matrix/scripts
```

검증 기준:

- 마지막 PASS record가 있으면 record path와 ref를 출력한다.
- PASS record가 없거나 ref를 해석할 수 없으면 fallback reason을 출력한다.
- 현재 작업트리의 변경 파일이 누락되지 않는다.
- 변경 파일별 domain/language 분류가 출력된다.
- 테스트를 실제 실행하지 않는다.

## 완료 조건

- `last-pass-point`, `diff-source`, `path-domain-map` task의 검증 문구를 만족한다.
- 후속 `02+01_risk_routing_rules`가 classifier 출력을 읽어 라우팅 후보를 만들 수 있다.
- 구현 결과와 검증 결과가 `CODE_REVIEW-cloud-G07.md`에 기록된다.
