agentic-framework/agent-ops/skills/common/complete-milestone/SKILL.md

name	description
complete-milestone	마일스톤 완료해도 될지 검토, 현 마일스톤 종료 검토, 현재 마일스톤 닫고 다음 마일스톤 지정, 검토중 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 이동을 하지 않고 실패 사유와 필요한 후속 작업을 보고한다.

출력 형식

## 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 후보가 모호한데 자동으로 선택하지 않는다.