<!-- task=m-command-first-operator-workflow/05+03,04_operator_handoff plan=1 tag=REVIEW_DOCS -->

# Plan - Review Follow-up: Operator Handoff Key Contract

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

이 plan은 직전 code review FAIL을 해소하기 위한 좁은 후속 지시서다. 구현 완료 전 active `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 실제 내용과 검증 출력으로 채운다. 최종 판정, archive 이동, `complete.log` 작성은 code-review-skill 전용이다. 사용자-only blocker가 있으면 review stub의 `사용자 리뷰 요청`을 채우고 멈춘다.

## 배경

직전 리뷰는 handoff matrix가 machine-readable output key를 잘못 약속하고, 테스트가 그 약속을 실제 JSONL fixture와 대조하지 못하는 문제로 FAIL 처리되었다. 특히 `invalid_request_matrix` 행은 `code` key를 문서화했지만 실제 output fixture는 `error_code`를 사용한다. 이 follow-up은 문서와 테스트를 같은 계약으로 묶어, UI MVP handoff가 존재하지 않는 key에 의존하지 않게 한다.

## 사용자 리뷰 요청 흐름

구현 중 사용자-only blocker는 active review stub의 `사용자 리뷰 요청` 섹션에 기록한다. code-review가 이를 검증하고 실제 `USER_REVIEW.md` 작성 여부를 결정한다.

## Roadmap Targets

- Milestone: `agent-roadmap/phase/operator-surface/milestones/command-first-operator-workflow.md`
- Task ids:
  - `operator-handoff`: command-first workflow가 UI MVP로 넘길 화면 후보와 아직 화면으로 올리지 않을 항목을 분리한다.
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- `agent-task/m-command-first-operator-workflow/05+03,04_operator_handoff/plan_local_G05_0.log`
- `agent-task/m-command-first-operator-workflow/05+03,04_operator_handoff/code_review_local_G05_0.log`
- `apps/cli/testdata/operator/headless_validation.md`
- `apps/cli/testdata/operator/expected/invalid_request_matrix.jsonl`
- `apps/cli/internal/operator/handoff_test.go`
- `agent-test/local/rules.md`
- `agent-test/local/operations-smoke.md`
- `agent-ops/rules/project/domain/operations/rules.md`

### 실패 요약

- `apps/cli/testdata/operator/headless_validation.md`의 `invalid_request_matrix` row는 `Expected output keys`에 `code`를 적었지만 fixture는 `error_code`/`error_message`를 출력한다.
- `apps/cli/internal/operator/handoff_test.go`의 `requiredScenarioKeys`는 matrix row의 promised keys를 읽지 않고 일부 required scenario를 건너뛰어, 문서와 fixture의 key mismatch를 통과시킨다.

### 테스트 환경 규칙

- test_env: `local`.
- Matched profile: `operations-smoke`.
- Applied commands: focused handoff test, CLI package tests, matrix grep, `git diff --check`.

### 범위 결정 근거

- 포함: handoff matrix의 expected output key 정정, handoff guard test 보강.
- 제외: command behavior 변경, expected JSONL fixture content 변경(실제 output 계약이 틀린 경우가 아니라면), Flutter UI/wireframe/layout 확정, roadmap 상태 갱신 또는 archive 이동.

### 빌드 등급

- build=`local-G06`, review=`local-G06`: 실패 원인이 명시적이고 deterministic하지만, 기존 local-G05 구현이 key-contract 검증 공백을 놓쳤으므로 grade를 한 단계 올린다.

## 구현 체크리스트

- [ ] [REVIEW_DOCS-1] Align handoff matrix promised output keys with actual JSONL fixture keys for every required scenario, including `invalid_request_matrix` using `error_code` instead of nonexistent `code`.
- [ ] [REVIEW_DOCS-2] Strengthen handoff tests so the matrix's promised `Expected output keys` are verified against the matching expected JSONL fixture for every required scenario and no required scenario is silently skipped. 검증: reintroducing `code` for `invalid_request_matrix` would fail the focused handoff test.
- [ ] [REVIEW_DOCS-3] Run CLI verification and `git diff --check`.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## [REVIEW_DOCS-1] Matrix Key Alignment

### 문제

`apps/cli/testdata/operator/headless_validation.md` documents `code` for `invalid_request_matrix`, but `apps/cli/testdata/operator/expected/invalid_request_matrix.jsonl` emits `error_code`. This makes the UI handoff point at a key that the command-first workflow does not produce.

### 해결 방법

Update the matrix row so `Expected output keys` reflects the actual JSONL output contract. For `invalid_request_matrix`, use `error_code` and include `error_message` if that message is intentionally part of the handoff evidence. Review other rows for the same doc-vs-fixture drift and only list keys that actually appear in the fixture.

### 수정 파일 및 체크리스트

- [ ] `apps/cli/testdata/operator/headless_validation.md`: align promised keys with fixture keys.

### 테스트 작성

Covered by REVIEW_DOCS-2.

### 중간 검증

```bash
rg --sort path -n 'invalid_request_matrix|error_code|Expected output keys' apps/cli/testdata/operator/headless_validation.md apps/cli/testdata/operator/expected/invalid_request_matrix.jsonl
```

Expected: the matrix row promises `error_code` rather than `code`, and the fixture contains that key.

## [REVIEW_DOCS-2] Matrix-Promised Key Guard

### 문제

The current test comments say it verifies keys promised by the handoff matrix, but the implementation uses a hardcoded map and skips required scenarios not present in that map. This does not protect the actual matrix contract.

### 해결 방법

Prefer a test helper that reads `apps/cli/testdata/operator/headless_validation.md`, finds each required scenario row, extracts the `Expected output keys` cell, parses backtick-wrapped key names, and verifies each promised key appears at least once in that scenario's expected JSONL fixture.

If a full parser is too heavy for this bounded markdown table, keep the parser deliberately small but fail loudly when:

- a required scenario row is missing,
- the `Expected output keys` cell is empty,
- a required scenario has no parsed promised keys,
- a promised key is absent from the expected fixture.

Do not silently skip a required scenario. If a key should not be verified, remove it from the matrix rather than hiding it in the test.

### 수정 파일 및 체크리스트

- [ ] `apps/cli/internal/operator/handoff_test.go`: replace or supplement `requiredScenarioKeys` with matrix-driven promised key verification.
- [ ] `apps/cli/internal/operator/handoff_test.go`: keep the existing column/fixture existence guards.

### 테스트 작성

Strengthen `TestExpectedFixturesContainPromisedKeys` or add a new focused test name if clearer. The test must catch the previous `code` vs `error_code` mismatch.

### 중간 검증

```bash
go test ./apps/cli/internal/operator -run Handoff -count=1
```

Expected: focused handoff tests pass after the matrix and guard test are aligned.

## [REVIEW_DOCS-3] Verification

### 문제

The fix touches operator handoff docs and tests, so focused and package-level CLI checks must both stay green.

### 해결 방법

Run the focused handoff test, CLI package tests, matrix grep, and diff whitespace check.

### 수정 파일 및 체크리스트

- [ ] No extra files.

### 테스트 작성

No additional tests beyond REVIEW_DOCS-2.

### 중간 검증

```bash
git diff --check
```

Expected: no output.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `apps/cli/testdata/operator/headless_validation.md` | REVIEW_DOCS-1 |
| `apps/cli/internal/operator/handoff_test.go` | REVIEW_DOCS-2 |

## 최종 검증

```bash
go test ./apps/cli/internal/operator -run Handoff -count=1
go test ./apps/cli/... -count=1
rg --sort path -n 'invalid_request_matrix|error_code|Expected output keys' apps/cli/testdata/operator/headless_validation.md apps/cli/testdata/operator/expected/invalid_request_matrix.jsonl
git diff --check
```

Expected: all commands exit 0, and the grep output shows the documented key and fixture key are aligned.

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