---
name: complete-milestone
description: "마일스톤 완료해도 될지 검토, 현 마일스톤 종료 검토, 현재 마일스톤 닫고 다음 마일스톤 지정, 검토중 Milestone 코드레벨 종료 감사 요청에 사용한다. 코드/테스트/계약/evidence를 점검하고 작은 보완은 처리하거나 큰 보완은 plan으로 넘기며, agent-spec이 있으면 update-spec을 필수 gate로 수행한 뒤 update-roadmap으로 완료/archive와 다음 Milestone 지정을 처리한다."
---

# complete-milestone

## 목적

`[검토중]` 또는 완료 후보 Milestone을 코드레벨에서 종료해도 되는지 감사하고, 종료 가능할 때 spec sync와 roadmap 완료/archive까지 이어지는 오케스트레이션을 수행한다.
`update-spec`과 `update-roadmap`의 책임을 합치지 않고, 이 스킬이 완료 workflow의 순서와 gate를 관리한다.

## 언제 호출할지

- 사용자가 "마일스톤 완료해도 될지 검토해봐"라고 요청할 때
- 사용자가 "현 마일스톤 종료 검토해", "현재 마일스톤 닫고 다음 마일스톤 지정해"라고 요청할 때
- `[검토중]` Milestone의 완료 리뷰 통과, archive, 다음 Milestone current 지정 여부를 코드레벨 evidence로 확인해야 할 때
- Milestone 종료 시점에 `agent-spec` 갱신이 함께 필요할 때

## 입력

- `target-milestone`: 종료 검토할 Milestone 경로, 이름, slug. 없으면 `agent-roadmap/current.md`의 활성 Milestone 단일 후보를 사용한다. (선택)
- `next-milestone`: 종료 후 `current.md`에 둘 다음 Milestone 후보. 없으면 Phase 흐름에서 자동 후보를 찾되 모호하면 보고한다. (선택)
- `mode`: `check-only` 또는 `close`. 기본값은 `close`다. (선택)
- `evidence`: 완료 판단에 사용할 complete.log, 테스트 결과, 사용자 설명, PR/커밋 등. (선택)
- `verification-context`: 환경, 출처, 명령, 기대 결과, precondition, 제약, gap, confidence를 담은 중립 검증 handoff. 있으면 사용하고 현재 checkout과 다시 대조한다. (선택)

## 먼저 확인할 것

- [ ] `agent-roadmap/current.md`와 대상 활성 Milestone, 대상 Phase `PHASE.md`를 읽는다.
- [ ] `agent-roadmap/priority-queue.md`가 있으면 종료 후 다음 후보와 archive 제거 대상 확인을 위해 읽는다.
- [ ] 대상 Milestone의 `상태`, `기능`, `구현 잠금`, `완료 리뷰`, `작업 컨텍스트`, SDD gate를 확인한다.
- [ ] 완료 근거 동기화가 필요하면 `sync-milestone-workstate` 절차를 확인한다.
- [ ] 종료/archive가 가능하면 `update-roadmap` 절차를 확인한다.
- [ ] `agent-spec/`가 있으면 `agent-ops/rules/common/rules-agent-spec.md`와 `update-spec` 절차를 확인한다.
- [ ] 코드, 계약, 테스트에 닿는 범위는 project/domain/test/contract 규칙을 따른다.

## 실행 절차

1. **대상 Milestone 확정**
   - `target-milestone`이 있으면 활성 Milestone에서 정확히 하나를 찾는다.
   - 없으면 `agent-roadmap/current.md`의 활성 Milestone 단일 후보를 사용한다.
   - 대상이 archive 경로이거나 둘 이상이면 수정하지 않고 target 불명확으로 보고한다.

2. **완료 후보 상태 확인**
   - 대상 Milestone이 `[검토중]`이면 종료 감사로 진행한다.
   - `[진행중]` 또는 `[계획]`이면 `sync-milestone-workstate` 기준으로 기능 Task/evidence를 동기화할 수 있는지 먼저 확인한다. 동기화 후 `[검토중]` 조건을 충족하지 못하면 종료 감사로 진행하지 않는다.
   - `[스케치]`, `[보류]`, `[폐기]`, `[완료]`이면 일반 종료 감사를 진행하지 않고 상태 불일치를 보고한다.
   - `구현 잠금`이 남아 있거나 미완료 `결정 필요`가 있으면 archive하지 않는다.

3. **코드레벨 종료 감사**
   - Milestone `기능` Task와 검증 문구, `완료 리뷰`, complete.log, SDD Evidence Map, 관련 코드/계약/테스트를 비교한다.
   - `agent-task/archive/**`는 같은 `m-<milestone-slug>` complete.log 후보처럼 규칙상 허용된 범위만 좁게 읽는다.
   - 코드/계약 변경에 닿으면 관련 domain rule과 `agent-contract/index.md` 라우팅을 따른다.
   - `verification-context`가 있으면 출처 경로, 명령, 기대 결과, precondition, 제약, gap, confidence가 현재 checkout에 맞는지 확인한다.
   - handoff가 없거나 불완전하면 repository manifest, script, workflow, domain rule, 관련 테스트와 안전한 read-only probe에서 부족한 검증 사실을 보완한다. 선택 handoff 누락만으로 종료 검토를 차단하지 않는다.

4. **보완 분기**
   - 작은 문서/코드/테스트 보완으로 바로 해결 가능한 이슈는 직접 수정하고 검증한다.
   - Milestone 범위 안의 큰 구현 보완이 필요하면 `plan`을 작성하고 종료를 중단한다.
   - 제품/범위/우선순위/책임 경계 결정이 필요하면 Milestone `구현 잠금 > 결정 필요` 또는 SDD `USER_REVIEW.md`로 분리하고 종료를 중단한다.
   - 보완이 발생하면 Milestone 완료 리뷰를 `보완 필요`로 남기고 `[완료]` 전환이나 archive를 하지 않는다.

5. **Spec Sync Gate**
   - `mode=check-only`이고 `agent-spec/`가 있으면 `update-spec mode=check-only`로 갱신 필요 여부만 확인한다.
   - `agent-spec/`가 없으면 `Spec sync: skipped-no-agent-spec`으로 기록하고 종료 흐름을 계속할 수 있다.
   - `agent-spec/`가 있고 `mode=close`이면 `update-spec`을 필수로 수행한다.
   - 관련 spec이 없고 Milestone 결과가 현재 구현 지도에 영향을 주면 `create-spec` 필요로 보고하고 종료를 중단한다.
   - 결과는 반드시 `Spec updated`, `Spec update not needed`, `create-spec needed`, `Spec blocked`, `skipped-no-agent-spec` 중 하나로 정리한다.
   - `Spec blocked` 또는 `create-spec needed`이면 Milestone을 `[완료]`로 전환하거나 archive하지 않는다.
   - `Spec updated` 또는 `Spec update not needed`이면 Milestone 완료 리뷰에 `Spec sync` 결과와 spec 문서 링크 또는 사유를 남긴다.

6. **Milestone 완료와 archive**
   - `mode=check-only`이면 여기서 쓰지 않고 종료 가능 여부만 보고한다.
   - 모든 기능 Task, 검증, 구현 잠금, SDD gate, code audit, spec sync gate가 충족되면 `update-roadmap` archive 흐름으로 Milestone을 `[완료]`로 전환하고 archive한다.
   - `.agent-roadmap-sync/locks.yaml`이 있으면 `update-roadmap`의 workspace lock 검사/동기화 규칙을 따른다.
   - Phase `PHASE.md`에는 archive 링크와 짧은 요약을 남긴다.
   - `priority-queue.md`가 있으면 완료/archive된 Milestone 항목을 제거하도록 `update-roadmap` archive 흐름에 포함한다.
   - `agent-roadmap/current.md`에서 완료 Milestone을 제거한다.

7. **다음 Milestone 지정**
   - `next-milestone`이 있으면 활성 Milestone에서 정확히 하나인지 확인하고 `current.md`에 반영한다.
   - 없고 `priority-queue.md`가 있으면 각 prefix의 가장 작은 active index 중 `선행 차단`이 없고, 현재 진행 중인 `동시 차단` target이 없는 lane head를 다음 후보로 찾는다. 여러 후보가 열리면 방금 완료한 prefix의 다음 항목을 우선하고, 없으면 queue group 순서를 tie-breaker로 쓴다.
   - `priority-queue.md`가 없으면 같은 Phase의 Milestone 흐름에서 완료/폐기/archive가 아닌 다음 후보를 찾는다.
   - 후보가 없거나 둘 이상이면 자동 지정하지 않고 후보와 이유를 보고한다.
   - 다음 후보가 `[스케치]`이면 구현 대상이 아니라 구체화 대상임을 보고한다.

8. **결과 보고**
   - 종료 가능 여부, 수정/생성한 파일, 실행 검증, spec sync 결과, roadmap archive 결과, 다음 Milestone을 보고한다.

## 실행 결과 검증

- [ ] 대상 Milestone이 활성 경로에서 정확히 하나로 확정되었는가
- [ ] Milestone 상태, 기능 Task, 구현 잠금, 완료 리뷰, SDD gate를 확인했는가
- [ ] 코드/계약/테스트 evidence를 확인했거나 범위 불명확 사유를 보고했는가
- [ ] 전달된 verification context와 repository-native fallback의 출처·gap·confidence를 구분했는가
- [ ] 작은 보완은 검증까지 수행하고, 큰 보완은 plan으로 넘겼는가
- [ ] `agent-spec/`가 있으면 `update-spec` 결과를 확인하고 완료 진행 가능 상태가 `Spec updated` 또는 `Spec update not needed`인지 판단했는가
- [ ] `Spec blocked` 또는 `create-spec needed` 상태에서 Milestone 완료/archive를 하지 않았는가
- [ ] `update-roadmap` 완료/archive 규칙과 workspace lock 규칙을 따랐는가
- [ ] `priority-queue.md`가 있으면 완료/archive된 Milestone과 충족된 blocker 참조가 제거되었고 다음 후보 판단에 prefix index와 차단 예외가 반영되었는가
- [ ] 완료 Milestone이 `current.md`에 남아 있지 않은가
- [ ] 다음 Milestone 지정이 모호하면 자동 선택하지 않았는가
- [ ] `git diff --check`를 실행했는가
- 검증 실패 시: archive 이동을 하지 않고 실패 사유와 필요한 후속 작업을 보고한다.

## 출력 형식

```markdown
## Milestone 종료 검토 결과

- 대상 Milestone: [<title>](agent-roadmap/phase/<phase>/milestones/<milestone>.md)
- 판정: <종료 완료 | 종료 가능-check-only | 보완 필요 | plan 작성 | 차단>
- 코드레벨 감사: <통과 | 보완 내용 | 차단 사유>
- 검증:
  - `<command>` - <PASS | FAIL | BLOCKED>; <요약>
- Spec sync: <updated | not-needed | create-spec needed | blocked | skipped-no-agent-spec>
  - <[spec](agent-spec/<area>/<spec-id>.md) | 사유>
- Roadmap: <archive 완료 | 변경 없음 | 차단>
- 다음 Milestone: <[title](agent-roadmap/phase/<phase>/milestones/<next>.md) | 미지정: 사유>
- 수정 파일:
  - <없음 | [path](path)>

## TODO 항목

- <남은 차단 항목 또는 없음>
```

## 금지 사항

- `update-spec`과 `update-roadmap`의 책임을 이 스킬 본문에 합쳐서 재정의하지 않는다.
- `Spec blocked` 또는 `create-spec needed`인데 Milestone을 `[완료]`로 전환하거나 archive하지 않는다.
- 큰 구현 보완을 종료 검토 중 임의로 처리하지 않는다. `plan`으로 넘긴다.
- archive 전체를 일반 탐색하지 않는다.
- 구현 잠금이나 미해결 SDD 사용자 리뷰가 남은 Milestone을 완료 처리하지 않는다.
- 다음 Milestone 후보가 모호한데 자동으로 선택하지 않는다.
