<!-- task=03_command_catalog_samples plan=2 tag=REVIEW_REVIEW_REVIEW_SAMPLE -->

# Command Catalog Sample Field Follow-up

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

**구현의 마지막 단계는 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채우는 것이다. 이 파일이 채워지기 전에는 작업이 완료된 것이 아니다.** 구현 체크리스트를 기준으로 작업하고, 중간/최종 검증을 실행한 뒤 실제 구현 내용과 stdout/stderr를 review stub에 기록한다. review 파일의 archive/complete.log 지시는 코드리뷰 스킬 전용이며 구현 에이전트가 실행하거나 `코드리뷰 전용 체크리스트`를 수정하면 안 된다.

## 배경

2차 구현은 이전 Required 항목인 GitHub write tag, stale iOS field 테스트, samplePath allowlist 정책을 반영했다. 다만 samplePath 정책을 만족시키기 위해 새로 연결한 일부 샘플이 실제 데이터 모델 키 또는 YAML 문법과 맞지 않아 코드리뷰에서 다시 Required 문제가 확인되었다.

- AWS CLI 샘플이 `DataAwsCli`의 `sub-command` JSON 키 대신 `subCommand`를 사용한다.
- JIRA 샘플이 필수 `token` 필드를 누락하고 API 토큰 placeholder를 `id`에 넣었다.
- Protobuf 샘플의 `commands` list item이 닫힌 따옴표 뒤에 추가 토큰을 붙여 YAML scalar 문법을 깨뜨린다.
- catalog 테스트가 샘플 파일 존재와 command 포함 여부만 검사해서 위 회귀를 잡지 못한다.

## 분석 결과

### 읽은 파일

- `agent-task/03_command_catalog_samples/code_review_local_G05_1.log`
- `agent-task/03_command_catalog_samples/plan_local_G05_1.log`
- `assets/yaml/sample/18_protobuf.yaml`
- `assets/yaml/sample/19_awscli.yaml`
- `assets/yaml/sample/21_jira.yaml`
- `test/oto_command_catalog_test.dart`
- `lib/oto/data/infra_data.dart`
- `lib/oto/data/integration_data.dart`

### 범위 결정 근거

후속 작업은 리뷰 Required 항목만 다룬다. 런타임 커맨드 실행 로직, 데이터 모델, 기존 iOS/GitHub 샘플 수정은 이번 범위가 아니다. 필요한 경우 catalog 테스트 helper 추가는 허용한다.

### 빌드 등급

build=`local-G05`, review=`local-G05`: YAML 샘플과 정적 catalog 테스트 수정이며 외부 CLI 실행, 인터랙티브 터미널, 라이브 환경 검증이 필요하지 않다.

## 구현 체크리스트

- [ ] [REVIEW_REVIEW_REVIEW_SAMPLE-1] 새로 연결된 AWS/JIRA/Protobuf 샘플의 YAML/필수 파라미터 키를 실제 Data 모델과 맞춘다.
- [ ] [REVIEW_REVIEW_REVIEW_SAMPLE-2] catalog 테스트에 새 샘플 문법/필수 키 회귀 검사를 추가한다.
- [ ] 중간 검증과 최종 검증 명령을 실행하고 결과를 확인한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이다.

### [REVIEW_REVIEW_REVIEW_SAMPLE-1] 샘플 YAML/필수 키 수정

문제:

- [19_awscli.yaml](/config/workspace/oto/assets/yaml/sample/19_awscli.yaml:18), [19_awscli.yaml](/config/workspace/oto/assets/yaml/sample/19_awscli.yaml:26)의 `subCommand`는 `DataAwsCli`가 읽는 키가 아니다. [infra_data.dart](/config/workspace/oto/lib/oto/data/infra_data.dart:26)는 `@JsonKey(name: "sub-command")`를 사용한다.
- [21_jira.yaml](/config/workspace/oto/assets/yaml/sample/21_jira.yaml:18)는 `token` 필드를 누락했다. [integration_data.dart](/config/workspace/oto/lib/oto/data/integration_data.dart:13)는 `id`, [integration_data.dart](/config/workspace/oto/lib/oto/data/integration_data.dart:14)는 `token`을 모두 필수로 요구한다.
- [18_protobuf.yaml](/config/workspace/oto/assets/yaml/sample/18_protobuf.yaml:19)는 닫힌 따옴표 뒤에 `--dart_out=...`를 이어 붙였다.

해결 방법:

```yaml
# AwsCli
sub-command: s3 ls

# Jira
id: "user@example.com"
token: "jira-api-token"

# Protobuf
commands:
- "<!property.protoPath>/google/api/http.proto --dart_out=generated:./generated"
```

수정 파일 및 체크리스트:

- [ ] `assets/yaml/sample/19_awscli.yaml`: 두 AwsCli block의 `subCommand`를 `sub-command`로 수정.
- [ ] `assets/yaml/sample/21_jira.yaml`: `id`를 사용자/account placeholder로 바꾸고 `token` placeholder 추가.
- [ ] `assets/yaml/sample/18_protobuf.yaml`: `commands` 항목을 유효한 단일 문자열 scalar로 수정.
- [ ] 커맨드 런타임과 데이터 모델은 변경하지 않는다.

테스트 작성: REVIEW_REVIEW_REVIEW_SAMPLE-2에서 회귀 테스트를 작성한다.

중간 검증:

```bash
dart test test/oto_command_catalog_test.dart
```

기대 결과: All tests passed.

### [REVIEW_REVIEW_REVIEW_SAMPLE-2] 샘플 문법/필수 키 회귀 테스트

문제: 현재 catalog 테스트는 `samplePath` 파일 존재와 `- command: <Type>` 포함만 확인한다. 그래서 CommandSpec에 연결된 샘플이 실제 YAML로 파싱되지 않거나 필수 파라미터 키가 틀려도 통과한다.

해결 방법:

- `test/oto_command_catalog_test.dart`에 `Application.getMapFromYamlA()` 또는 `package:yaml` 기반 파싱 검사를 추가한다.
- 최소한 모든 unique `CommandSpec.samplePath`가 YAML map으로 파싱되고 `commands` list를 가진다는 것을 검증한다.
- 이번 회귀를 직접 고정한다.
  - AwsCli param은 `sub-command`를 포함하고 `subCommand`를 포함하지 않는다.
  - Jira param은 `id`와 `token`을 모두 포함한다.
  - Protobuf param의 `commands`는 문자열 리스트로 파싱된다.

수정 파일 및 체크리스트:

- [ ] `test/oto_command_catalog_test.dart`: samplePath YAML parse 회귀 테스트 추가.
- [ ] `test/oto_command_catalog_test.dart`: AWS/JIRA/Protobuf 필수 키 회귀 테스트 추가.
- [ ] 기존 GitHub write tag, stale iOS field, samplePath allowlist 테스트는 유지한다.

테스트 작성: 작성. 임시로 위 세 샘플을 다시 깨뜨리면 실패할 정도로 assertion이 구체적이어야 한다. 임시 변경은 남기지 않는다.

중간 검증:

```bash
dart test test/oto_command_catalog_test.dart
```

기대 결과: All tests passed.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `assets/yaml/sample/18_protobuf.yaml` | REVIEW_REVIEW_REVIEW_SAMPLE-1 |
| `assets/yaml/sample/19_awscli.yaml` | REVIEW_REVIEW_REVIEW_SAMPLE-1 |
| `assets/yaml/sample/21_jira.yaml` | REVIEW_REVIEW_REVIEW_SAMPLE-1 |
| `test/oto_command_catalog_test.dart` | REVIEW_REVIEW_REVIEW_SAMPLE-2 |

## 최종 검증

```bash
dart analyze
dart test test/oto_command_catalog_test.dart
dart test
```

기대 결과: `No issues found!`, catalog test pass, full test pass.

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