<!-- task=m-control-plane-jenkins-menu-ia-code-sync/01_definition_guardrails plan=0 tag=JENKINS_IA_DEF -->

# Plan - Jenkins IA Definition Guardrails

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

`CODE_REVIEW-cloud-G07.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채우는 것이 구현의 마지막 단계다. 구현 후 active 파일을 유지하고 리뷰 준비만 보고한다. 선택된 Milestone `구현 잠금 > 결정 필요` 항목이 실구현을 차단할 때만 리뷰 스텁의 `사용자 리뷰 요청` 섹션을 채우고 멈춘다. 구현 중 직접 사용자에게 질문하거나 선택지를 제시하거나 `request_user_input`, `USER_REVIEW.md`, `complete.log`, archive 이동을 수행하지 않는다. 환경/secret/service 차단과 증거 공백은 사용자 리뷰 요청이 아니라 검증 결과나 후속 plan으로 남긴다.

## 배경

사용자가 지적한 대로 현재 Flutter UI는 `agent-ui` 검증상 통과하지만 Jenkins 정보구조와는 어긋난다. 정의서가 `rough alignment`, `60px rail 유지`, `stage graph 후속 후보`를 허용해, 실제 Jenkins `2.516+`의 통합 header/breadcrumb/action 구조와 Pipeline Graph View 중심성을 acceptance로 강제하지 못했다. 사용자 결정으로 메뉴 구조는 Jenkins 모델 중 OTO에 적용 가능한 항목만 맞추는 것으로 확정되었으므로, 이 작업은 구현 전에 정의서와 기준을 좁혀 다음 코드 작업의 실패 조건을 명확히 한다.

## 사용자 리뷰 요청 흐름

사용자 리뷰 요청은 선택된 Milestone lock 결정이 구현을 막을 때만 active `CODE_REVIEW-cloud-G07.md`의 `사용자 리뷰 요청` 섹션에 기록한다. 구현 에이전트는 직접 사용자 프롬프트를 띄우지 않으며, code-review가 해당 요청을 검증하고 실제 `USER_REVIEW.md` 작성을 소유한다.

## Roadmap Targets

- Milestone: `agent-roadmap/phase/control-plane-product-surface/milestones/control-plane-jenkins-menu-ia-code-sync.md`
- Task ids:
  - `definition-guardrail`: 화면정의서에 적용 가능한 Jenkins 메뉴 기준과 제외/후순위 메뉴가 명확히 남아 있고, 후속 코드 검증 label이 고정되어 있다.
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- `agent-roadmap/current.md`
- `agent-roadmap/phase/control-plane-product-surface/PHASE.md`
- `agent-roadmap/phase/control-plane-product-surface/milestones/control-plane-jenkins-menu-ia-code-sync.md`
- `agent-test/local/rules.md`
- `agent-test/local/framework-smoke.md`
- `agent-ui/definition/index.md`
- `agent-ui/definition/views/index.md`
- `agent-ui/definition/components/index.md`
- `packages/flutter/oto_console/lib/src/oto_console_shell.dart`
- `packages/flutter/oto_console/lib/src/oto_jobs_surface.dart`
- `packages/flutter/oto_console/lib/src/oto_executions_surface.dart`
- `packages/flutter/oto_console/lib/src/oto_runners_surface.dart`
- `packages/flutter/oto_console/lib/src/oto_console_overview.dart`
- `packages/flutter/oto_console/lib/src/oto_console_contract.dart`
- `packages/flutter/oto_console/lib/src/oto_console_models.dart`
- `packages/flutter/oto_console/lib/oto_console.dart`
- `packages/flutter/oto_console/pubspec.yaml`
- `packages/flutter/oto_console/test/oto_console_test.dart`
- `apps/client/lib/src/app/oto_client_app.dart`
- `apps/client/lib/src/app/bootstrap.dart`
- `apps/client/lib/main.dart`
- `apps/client/pubspec.yaml`
- `apps/client/test/widget_test.dart`

### SDD 기준

Milestone: `agent-roadmap/phase/control-plane-product-surface/milestones/control-plane-jenkins-menu-ia-code-sync.md`. SDD: 불필요. 사유: 기존 Flutter/agent-ui IA 정렬이며 새 API/schema/proto/config/env 계약 또는 외부 provider 쓰기 경계를 만들지 않는다.

### 테스트 환경 규칙

test_env는 `local`이다. `agent-test/local/rules.md`와 `agent-test/local/framework-smoke.md`를 읽었다. Flutter console/client 변경 검증에는 원격 runner 기준 `cd packages/flutter/oto_console && flutter analyze && flutter test`, `cd apps/client && flutter analyze && flutter test`를 적용한다. 정의서-only 1단계는 `git diff --check`와 deterministic `rg --sort path` 확인을 중간 검증으로 둔다.

테스트 환경 프리플라이트: local `/config/workspace/oto`는 branch `master`, HEAD `92d2376`, Flutter `3.41.5`, Dart `3.11.3`이다. 원격 runner `ssh toki@toki-labs.com`, checkout `/Users/toki/agent-work/oto`는 branch `master`, HEAD `7e51ef9`, unrelated dirty files가 있으며 Flutter `3.44.0`, Dart `3.12.0`, port `13020`은 Python preview PID `97833`이 listen 중이다. 원격 checkout을 그대로 source로 쓰지 말고 구현 후 build artifact 또는 별도 동기화 단계로 preview를 갱신한다.

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

- Jenkins IA acceptance: 기존 테스트는 header/breadcrumb/action/task 영역과 Jenkins 좌측 메뉴 모델을 단언하지 않는다.
- Pipelines dashboard: 기존 테스트는 `Build Job`, `RUNNING`, `Job ID`, execution link만 확인한다.
- Executions run detail: 기존 테스트가 `Stage summary unavailable` placeholder를 정상으로 인정한다.
- Runners/settings: 기존 테스트가 Jenkins Nodes/Agents 또는 Manage Jenkins 구조를 단언하지 않는다.

### 심볼 참조

none. 이 단계는 rename/remove를 계획하지 않는다.

### 분할 판단

split decision policy를 먼저 평가했다. 공유 task group은 `m-control-plane-jenkins-menu-ia-code-sync`이다.

- `01_definition_guardrails`: 정의서 acceptance와 status 기준을 먼저 고정한다.
- `02+01_shell_jobs`: 01 완료 후 shell/header/navigation과 pipelines dashboard를 구현한다.
- `03+01_executions_ops`: 01 완료 후 executions, runners, settings를 구현하고 최종 원격 preview smoke를 수행한다.

02와 03은 모두 01의 `complete.log`에만 의존한다. 서로 간 의존은 두지 않는다.

### 범위 결정 근거

보안·감사 UI/계약, Core 권한/audit schema, runner transport, artifact storage는 제외한다. Jenkins pixel parity, 색상/spacing parity, Blue Ocean 기반 재설계도 제외한다. 이번 기준은 Jenkins `2.516+` header/breadcrumb/action, dashboard job table, Pipeline Graph View/Stage View, Nodes/Agents, Manage OTO 정보구조이다.

### 빌드 등급

`cloud-G07`. 로컬 테스트만으로 통과 가능한 UI가 실제 Jenkins IA 기준을 놓칠 수 있으므로 제품/외부 reference 판단과 후속 구현 범위 조정이 필요하다.

## 구현 체크리스트

- [x] [JENKINS_IA_DEF-1] `agent-ui/definition`의 Jenkins reference 기준을 rough alignment에서 structural acceptance로 강화하고, 현재 구현 status를 후속 구현 대기 상태로 정정한다.
- [x] [JENKINS_IA_DEF-2] 후속 구현자가 테스트로 검증할 Jenkins IA primitives와 Jenkins menu model primitives를 정의서에 명시한다.
- [x] `git diff --check`와 정의서 검색 검증을 실행한다.
- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [JENKINS_IA_DEF-1] Tighten Agent UI Status And Baseline

#### 문제

[agent-ui/definition/index.md](/config/workspace/oto/agent-ui/definition/index.md:45)는 pixel parity가 아니라 정보 구조와 러프한 배치를 맞춘다고 하지만, [agent-ui/definition/index.md](/config/workspace/oto/agent-ui/definition/index.md:57)는 현재 Flutter 구현을 Jenkins 정렬 evidence로 선언한다. [agent-ui/definition/views/index.md](/config/workspace/oto/agent-ui/definition/views/index.md:61)는 60px rail 유지를 허용하고, [agent-ui/definition/views/index.md](/config/workspace/oto/agent-ui/definition/views/index.md:56)는 stage graph를 후속 후보로만 둔다.

#### 해결 방법

`agent-ui/definition/index.md`, `views/index.md`, `components/index.md`를 수정해 Jenkins IA 기준을 structural gate로 바꾼다. 후속 구현 전까지 affected docs의 Jenkins IA alignment status는 `계획` 또는 `변경 필요`로 표현하고, 보안·감사 문서 계획 항목과 섞지 않는다.

Before:

```markdown
57 - 현재 Flutter 구현은 Jenkins 정렬 레이아웃 패스가 반영된 OTO console layout의 code evidence다.
64 - 현재 OTO 구현의 60px rail은 유지하며...
```

After:

```markdown
- 현재 Flutter 구현은 운영 밀도 일부만 반영했으며 Jenkins IA gate는 미충족이다.
- Jenkins IA gate는 통합 header/breadcrumb/action, dashboard job table, run stage graph, node/manage 구조가 테스트로 확인될 때만 `구현됨`으로 둔다.
```

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

- [x] `agent-ui/definition/index.md`: `Target Layout Status`를 Jenkins IA gate 기준으로 정정한다.
- [x] `agent-ui/definition/views/index.md`: affected views `overview`, `runners`, `pipelines`, `executions`, `settings` 설명에 structural acceptance를 추가한다.
- [x] `agent-ui/definition/components/index.md`: `console-shell`, `console-rail`, `record-list`, `execution-action-toolbar`, `section-surface` 기준을 rough reference에서 required primitive로 바꾼다.

#### 테스트 작성

문서-only 변경이므로 새 widget test는 02/03에서 작성한다. 이 단계는 deterministic 검색으로 acceptance 문구 존재와 기존 loose 문구 제거를 확인한다.

#### 중간 검증

```bash
git diff --check
rg --sort path -n "Jenkins IA gate|통합 header|breadcrumb|stage graph|Manage (Jenkins|OTO)" agent-ui/definition
rg --sort path -n "stage graph는 후속 조정 후보|rail은 유지" agent-ui/definition
```

예상: 첫 두 명령 PASS 및 structural gate 문구 출력. 마지막 명령은 legacy loose 문구가 남아 있지 않아 no matches가 기대값이다.

### [JENKINS_IA_DEF-2] Define Testable IA Primitives

#### 문제

[packages/flutter/oto_console/test/oto_console_test.dart](/config/workspace/oto/packages/flutter/oto_console/test/oto_console_test.dart:52)는 shell render만 확인하고, [packages/flutter/oto_console/test/oto_console_test.dart](/config/workspace/oto/packages/flutter/oto_console/test/oto_console_test.dart:519)는 `Stage summary unavailable`를 정상으로 인정한다.

#### 해결 방법

정의서에 후속 테스트 명칭과 required labels를 명시한다. 예: `Jenkins breadcrumb`, `New Item`, `Build History`, `Manage OTO`, `Status`, `Console Output`, `Pipeline Overview`, `Stage Graph`, `Nodes`, `Artifacts`.

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

- [x] `agent-ui/definition/views/index.md`: view별 required visible primitives와 메뉴 매핑 target을 추가한다.
- [x] `agent-ui/definition/components/index.md`: component별 후속 widget assertion 목표와 menu target을 추가한다.
- [x] `agent-ui/definition/components/console-rail/index.md`: Jenkins Dashboard/job/run left menu target을 current/target으로 분리한다.

#### 테스트 작성

새 테스트 작성은 02/03에서 수행한다. 이 단계에서는 테스트 요구사항을 정의서에 명시한다.

#### 중간 검증

```bash
rg --sort path -n "New Item|Build History|Manage OTO|Status|Console Output|Pipeline Overview|Stage Graph|Nodes|Artifacts" agent-ui/definition
```

예상: 각 required primitive가 정의서에 최소 1회 이상 나타난다.

## 의존 관계 및 구현 순서

이 작업은 02와 03의 선행 작업이다. 02/03 구현 전 `agent-task/m-control-plane-jenkins-menu-ia-code-sync/01_definition_guardrails/complete.log`가 있어야 한다.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `agent-ui/definition/index.md` | JENKINS_IA_DEF-1 |
| `agent-ui/definition/views/index.md` | JENKINS_IA_DEF-1, JENKINS_IA_DEF-2 |
| `agent-ui/definition/components/index.md` | JENKINS_IA_DEF-1, JENKINS_IA_DEF-2 |

## 최종 검증

```bash
git diff --check
rg --sort path -n "Jenkins IA gate|New Item|Build History|Manage (Jenkins|OTO)|Status|Console Output|Pipeline Overview|Stage Graph|Nodes|Artifacts" agent-ui/definition
```

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