<!-- task=m-agent-shell-package-iop-backend-boundary plan=0 tag=REFACTOR -->

# Plan - REFACTOR Scaffold Cleanup

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

`CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션 작성은 필수다. 구현 후 검증을 실행하고 실제 변경 내용, 검증 출력, 계획 대비 변경 사항을 채운 뒤 active 파일을 그대로 두고 리뷰 준비 상태를 보고한다. 최종 판정, log archive, `complete.log` 작성, task directory archive 이동은 code-review 스킬 전용이다. 구현 중 사용자 결정, 사용자 소유 외부 환경, scope conflict 없이는 진행할 수 없으면 review stub의 `사용자 리뷰 요청` 섹션에 정확한 근거를 남기고 중단한다. 구현 에이전트는 사용자에게 직접 질문하거나 선택지를 제시하거나 `request_user_input`, `USER_REVIEW.md`, `complete.log`, archive 이동을 수행하지 않는다. 후속 에이전트가 재실행이나 증거 수집으로 닫을 수 있는 검증 공백은 사용자 리뷰 요청이 아니다.

## 배경

현재 마일스톤은 `../agent-shell`을 Flutter UI/package로, `../iop`를 backend/runtime owner로 정리한다. Gito에는 아직 `gito-shell` command와 `internal/agentshell` scaffold가 남아 있어 README, build artifact, config가 새 책임 경계와 어긋날 수 있다. 이 계획은 legacy scaffold를 제거하거나 compatibility placeholder로 축소하는 정리 경로를 구현 단위로 고정한다.

## 사용자 리뷰 요청 흐름

구현 중 blocker는 active review stub의 `사용자 리뷰 요청` 섹션에 기록한다. 해당 섹션은 `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` 형식을 따른다. 구현 에이전트는 직접 사용자 프롬프트를 만들지 않고, code-review가 사용자 리뷰 필요성을 검증하고 실제 `USER_REVIEW.md` 작성을 담당한다.

## 분석 결과

### 읽은 파일

- `agent-ops/rules/project/rules.md`
- `agent-ops/rules/project/domain/core/rules.md`
- `agent-ops/rules/project/domain/workspace-ops/rules.md`
- `agent-ops/rules/project/domain/contracts/rules.md`
- `agent-ops/rules/project/domain/client/rules.md`
- `agent-ops/rules/common/rules-roadmap.md`
- `agent-ops/skills/common/plan/SKILL.md`
- `agent-ops/skills/common/create-test/SKILL.md`
- `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`
- `agent-roadmap/current.md`
- `agent-roadmap/phase/agent-shell-iop-execution/PHASE.md`
- `agent-roadmap/phase/agent-shell-iop-execution/milestones/agent-shell-package-iop-backend-boundary.md`
- `agent-contract/index.md`
- `agent-test/local/rules.md`
- `agent-test/local/core-smoke.md`
- `agent-test/local/workspace-ops-smoke.md`
- `README.md`
- `docs/architecture.md`
- `packages/contracts/notes/gito-control-plane.md`
- `apps/client/README.md`
- `bin/build`
- `bin/test`
- `bin/lint`
- `services/core/go.mod`
- `apps/client/pubspec.yaml`
- `services/core/cmd/shell/main.go`
- `services/core/internal/agentshell/shell.go`
- `services/core/internal/config/config.go`
- `services/core/internal/config/config_test.go`

### 테스트 환경 규칙

- test_env: `local`
- `agent-test/local/rules.md`는 기존 tracked 규칙을 보존한 상태로 읽었다.
- 라우팅된 smoke profile 문서들은 작업 시작 시 worktree에 없어서 create-test 흐름으로 local profile baseline을 생성한 뒤 읽었다.
- 매칭 profile:
  - `agent-test/local/core-smoke.md`: Go scaffold 변경은 `cd services/core && go test ./...`를 필수 검증으로 둔다.
  - `agent-test/local/workspace-ops-smoke.md`: README/docs/bin 변경은 `rg --sort path -n "Gito|agent-shell|agent_shell|iop|gito-shell|control plane" README.md docs packages/contracts agent-roadmap -g '!agent-roadmap/archive/**'` smoke를 둔다.
- fallback verification: `bin/build`는 README와 build artifact 계약을 직접 검증하기 위해 추가한다.
- `<확인 필요>` 값: 없음.

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

- `gito-shell` command 제거/rename은 기존 unit test가 직접 보장하지 않는다. `bin/build`와 `cd services/core && go test ./...`로 compile break를 잡는다.
- `GITO_SHELL_ID` 제거 여부는 `services/core/internal/config/config_test.go`를 갱신해야 보장된다.
- README/docs 계약 문구는 automated assertion이 없으므로 deterministic `rg --sort path` smoke와 reviewer inspection으로 확인한다.

### 심볼 참조

- `agentshell`: `services/core/cmd/shell/main.go`, `services/core/internal/agentshell/shell.go`, `agent-ops/rules/project/domain/core/rules.md`, roadmap references.
- `gito-shell`: `README.md`, `bin/build`, roadmap references.
- `GITO_SHELL_ID`: `README.md`, `services/core/internal/config/config.go`, `services/core/internal/config/config_test.go`.
- 변경 전 `rg --sort path -n "gito-shell|cmd/shell|internal/agentshell|agent shell scaffold|GITO_SHELL_ID|agentshell" . -g '!agent-task/archive/**' -g '!agent-roadmap/archive/**' -g '!agent-test/local/**'`를 다시 실행해 call site를 확정한다.

### 분할 판단

- split decision policy를 먼저 평가했다.
- 이 plan은 단일 active plan으로 둔다. 핵심 변경은 legacy shell scaffold 정리 하나이며, `bin/build`, Go config, README/docs가 같은 compatibility 결정을 공유한다.
- core와 workspace-ops를 함께 건드리지만 변경은 legacy artifact 제거/rename에 따른 기계적 동기화다. core만 먼저 바꾸면 README/build 문서가 깨지고, docs만 먼저 바꾸면 실제 binary 계약과 어긋난다.
- API/foundation 대 call-site rollout, migration, storage, auth, concurrency split은 없다.

### 범위 결정 근거

- `../agent-shell` package 내부와 `../iop` backend 구현은 제외한다.
- provider adapter, proto-socket action 구현, operation/event bridge 구현은 후속 Milestone 범위다.
- 이번 plan은 `gito-shell`/`internal/agentshell` scaffold와 그 직접 참조만 정리한다.
- `agent-ops/rules/project/domain/core/rules.md`의 "Agent command execution belongs in internal/agentshell" 문구는 실제 scaffold 정리 후 같은 구현에서 함께 갱신해야 한다.

### 빌드 등급

- `local-G05`: bounded legacy scaffold cleanup이며 compile/search 검증으로 review 가능하지만, build artifact와 docs 계약이 같이 움직여 중간 정도 주의가 필요하다.

## 구현 체크리스트

- [ ] `gito-shell`/`internal/agentshell` 정리 전략을 compatibility placeholder 유지, command 제거, rename 중 하나로 확정하고 코드와 docs에 일관되게 적용한다.
- [ ] 선택한 전략에 맞춰 `bin/build`, `services/core/cmd/shell/main.go`, `services/core/internal/agentshell/shell.go`, `services/core/internal/config/config.go`, `services/core/internal/config/config_test.go`를 정리한다.
- [ ] README, architecture, contract notes, domain rule에서 legacy shell wording과 build artifact 목록을 실제 상태와 맞춘다.
- [ ] `rg --sort path -n "gito-shell|cmd/shell|internal/agentshell|agent shell scaffold|GITO_SHELL_ID|agentshell" . -g '!agent-task/archive/**' -g '!agent-roadmap/archive/**' -g '!agent-test/local/**'`로 남은 참조가 의도된 예외뿐인지 확인한다.
- [ ] `cd services/core && go test ./...`와 `bin/build`를 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [REFACTOR-1] Legacy shell scaffold cleanup

#### 문제

- [README.md](/config/workspace/gito/README.md:46)는 build output에 `bin/gito-shell`을 포함한다.
- [bin/build](/config/workspace/gito/bin/build:10)는 `./cmd/shell`을 `bin/gito-shell`로 빌드한다.
- [services/core/cmd/shell/main.go](/config/workspace/gito/services/core/cmd/shell/main.go:7)는 `internal/agentshell`을 import하고 실행한다.
- [services/core/internal/agentshell/shell.go](/config/workspace/gito/services/core/internal/agentshell/shell.go:18)는 scaffold ready log만 남긴다.
- [services/core/internal/config/config.go](/config/workspace/gito/services/core/internal/config/config.go:18)는 shell-only `ShellID`를 전역 config에 둔다.

#### 해결 방법

기본 구현 방향은 legacy command 제거다. `../iop`가 backend/runtime owner이므로 Gito root build artifact에서 `gito-shell`을 제거하고, `cmd/shell`, `internal/agentshell`, `GITO_SHELL_ID`를 삭제한다. 단, 구현 중 active compatibility consumer가 발견되면 사용자에게 직접 묻지 말고 review stub의 `사용자 리뷰 요청`에 compatibility 유지가 필요한 근거를 남긴다.

Before:

```sh
# bin/build:8-10
(cd "$ROOT_DIR/services/core" && go build -o "$OUT_DIR/gito-server" ./cmd/server)
(cd "$ROOT_DIR/services/core" && go build -o "$OUT_DIR/gito-worker" ./cmd/worker)
(cd "$ROOT_DIR/services/core" && go build -o "$OUT_DIR/gito-shell" ./cmd/shell)
```

After:

```sh
(cd "$ROOT_DIR/services/core" && go build -o "$OUT_DIR/gito-server" ./cmd/server)
(cd "$ROOT_DIR/services/core" && go build -o "$OUT_DIR/gito-worker" ./cmd/worker)
```

Before:

```go
// services/core/internal/config/config.go:17-18
WorkerEnabled            bool
ShellID                  string
```

After:

```go
WorkerEnabled            bool
```

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

- [ ] `bin/build`: `gito-shell` build step 제거.
- [ ] `services/core/cmd/shell/main.go`: command 제거 또는 compatibility 유지가 필요하면 명시적 deprecation command로 축소.
- [ ] `services/core/internal/agentshell/shell.go`: package 제거 또는 deprecation-only package로 축소.
- [ ] `services/core/internal/config/config.go`: `ShellID`와 `GITO_SHELL_ID` load 제거.
- [ ] `services/core/internal/config/config_test.go`: shell env override assertion 제거.
- [ ] `README.md`: build artifact, structure table, environment variable table, current scope wording 갱신.
- [ ] `docs/architecture.md`: Gito가 arbitrary shell command를 직접 실행하지 않는다는 경계를 유지하고 legacy command 상태를 반영.
- [ ] `packages/contracts/notes/gito-control-plane.md`: `agent_shell` placeholder 문구가 실제 compatibility 상태와 맞는지 확인.
- [ ] `agent-ops/rules/project/domain/core/rules.md`: `internal/agentshell` 소유권 문구를 실제 구조에 맞게 갱신.

#### 테스트 작성

- 새 테스트는 작성하지 않는다. 제거/rename은 compile, config unit test 갱신, deterministic reference search로 검증한다.

#### 중간 검증

```sh
rg --sort path -n "gito-shell|cmd/shell|internal/agentshell|agent shell scaffold|GITO_SHELL_ID|agentshell" . -g '!agent-task/archive/**' -g '!agent-roadmap/archive/**' -g '!agent-test/local/**'
cd services/core && go test ./...
bin/build
```

Expected: search output은 의도된 compatibility/roadmap references만 남고, Go tests와 build는 exit 0.

## 수정 파일 요약

| 파일 | 항목 |
| --- | --- |
| `bin/build` | REFACTOR-1 |
| `services/core/cmd/shell/main.go` | REFACTOR-1 |
| `services/core/internal/agentshell/shell.go` | REFACTOR-1 |
| `services/core/internal/config/config.go` | REFACTOR-1 |
| `services/core/internal/config/config_test.go` | REFACTOR-1 |
| `README.md` | REFACTOR-1 |
| `docs/architecture.md` | REFACTOR-1 |
| `packages/contracts/notes/gito-control-plane.md` | REFACTOR-1 |
| `agent-ops/rules/project/domain/core/rules.md` | REFACTOR-1 |

## 최종 검증

```sh
rg --sort path -n "gito-shell|cmd/shell|internal/agentshell|agent shell scaffold|GITO_SHELL_ID|agentshell" . -g '!agent-task/archive/**' -g '!agent-roadmap/archive/**' -g '!agent-test/local/**'
cd services/core && go test ./...
bin/build
rg --sort path -n "Gito|agent-shell|agent_shell|iop|gito-shell|control plane" README.md docs packages/contracts agent-roadmap -g '!agent-roadmap/archive/**'
```

Expected: only intentional legacy/roadmap references remain; Go tests pass; `bin/build` produces the documented binaries; docs smoke exits 0. Go test cache output is acceptable because this is a compile/reference cleanup, not timing-sensitive behavior.

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