---
name: sync-milestone-workstate
version: 1.0.0
description: 현 마일스톤과 작업현황 동기화, 현재 마일스톤 작업현황 동기화, 마일스톤 완료내역 동기화, agent-task 완료를 마일스톤에 반영, active/archive complete.log 후보 스캔, 누락된 Roadmap Completion 복구, 마일스톤 체크박스 재동기화 요청에서 complete.log 근거를 Milestone Task, 상태, Phase/current 라벨에 반영하는 절차
---

# sync-milestone-workstate

## 목적

현재 또는 지정 Milestone의 기능 Task 상태를 `agent-task` 완료 산출물과 동기화한다.
이 스킬은 새 작업을 배치하거나 계획을 수정하지 않고, `complete.log`의 `Roadmap Completion` 근거만 사용해 Milestone 체크박스와 상태 라벨을 reconcile한다.
런타임이 `origin-task`와 `complete-log`를 단건 완료 이벤트로 전달한 일반 반영은 `update-roadmap`을 사용한다.
이 스킬은 완료 이벤트 반영 누락을 복구하거나 active/archive 후보를 스캔해 현재 상태를 확인하는 수동 reconcile 전용이다.

## 언제 호출할지

- 사용자가 "현 마일스톤과 작업현황 동기화", "현재 마일스톤 작업현황 동기화", "마일스톤 작업현황 동기화"라고 요청할 때
- 사용자가 "마일스톤 완료내역 동기화", "agent-task 완료를 마일스톤에 반영", "complete.log 후보 스캔"이라고 요청할 때
- 사용자가 "누락된 Roadmap Completion 복구", "마일스톤 체크박스 재동기화", "로드맵 작업 완료 상태 동기화"라고 요청할 때
- code-review PASS/archive 이후 runtime completion event 반영이 누락되었는지 확인하고 file-based fallback으로 복구해야 할 때

## 입력

- `target-milestone`: 동기화할 Milestone 이름, slug, 또는 경로. 없으면 `agent-roadmap/current.md`의 활성 Milestone 단일 후보를 사용한다. (선택)
- `complete-log`: 특정 `complete.log` 경로. 지정되면 이 파일을 우선 검증하되, 같은 Milestone slug의 active/archive 후보도 함께 확인한다. (선택)
- `mode`: `sync` 또는 `check-only`. 기본값은 `sync`다. (선택)

## 먼저 확인할 것

- [ ] `agent-roadmap/current.md`를 읽어 활성 Milestone 후보를 확인한다.
- [ ] 대상 Milestone 문서의 `상태`, `구현 잠금`, `기능`, `완료 리뷰`를 확인한다.
- [ ] 대상 Phase `PHASE.md`의 `Milestone 흐름`에 대상 Milestone 항목이 있는지 확인한다.
- [ ] 대상 Milestone의 `SDD: 필요` 여부와 `SDD 문서`, `USER_REVIEW.md` 존재 여부를 확인한다.
- [ ] 같은 slug의 active task와 archive task `complete.log` 후보를 모두 탐색한다. active만 보고 no-op으로 끝내지 않는다.

## 실행 절차

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

2. **Milestone Task와 gate 읽기**
   - Milestone `기능` 섹션의 Task id만 완료 후보로 본다.
   - Task id는 `- [ ] [item-id]` 또는 `- [x] [item-id]` 형식에서 추출한다.
   - `구현 잠금`의 상태, `결정 필요`, `SDD: 필요|불필요`, SDD 경로를 확인한다.
   - `SDD: 필요`이면 SDD 파일 존재와 같은 디렉터리의 `USER_REVIEW.md` 존재 여부를 확인하고, SDD의 `Acceptance Scenarios`와 `Evidence Map`에서 대상 Task id 연결만 확인한다.

3. **complete.log 후보 수집**
   - 대상 Milestone slug를 `<milestone-slug>`로 두고 task group은 `m-<milestone-slug>`로 고정한다.
   - active 후보를 찾는다: `agent-task/m-<milestone-slug>/**/complete.log`
   - archive 후보를 찾는다: `agent-task/archive/*/*/m-<milestone-slug>/**/complete.log`
   - `complete-log` 입력이 있으면 그 파일도 후보에 포함하되, `Roadmap Completion`의 Milestone 경로가 대상과 일치해야 반영한다.
   - 이 단계는 필수다. active 후보가 없더라도 archive 후보를 반드시 확인한다.
   - 일반 `agent-task/archive/**` 전체를 훑지 말고 위 패턴에 맞는 같은 milestone task group만 읽는다.

4. **Roadmap Completion 검증**
   - 각 `complete.log`에 `Roadmap Completion` 섹션이 없으면 해당 파일은 Task 체크 근거로 쓰지 않고 no-op 사유에 남긴다.
   - `Milestone:` 경로가 대상 Milestone 경로와 정확히 일치하지 않으면 해당 파일을 반영하지 않고 mismatch로 보고한다.
   - `Completed task ids`의 id가 대상 Milestone의 기존 Task id와 정확히 일치하지 않으면 수정하지 않고 unknown task id로 보고한다.
   - Task id는 의미 유사도나 파일명으로 추정하지 않는다.
   - 완료 근거는 `PASS` 또는 동등한 완료 판정과 검증 evidence가 있는 항목만 인정한다.
   - 같은 Task id에 여러 `complete.log`가 있으면 PASS 근거가 있는 항목을 모으고, 서로 충돌하는 `Not completed task ids`가 있으면 충돌을 보고한다.

5. **SDD Evidence Map 확인**
   - `SDD: 필요`인 Milestone은 `Roadmap Completion`만으로 완료 처리하지 않는다.
   - SDD `Acceptance Scenarios`와 `Evidence Map`에서 각 완료 후보 Task id와 연결된 scenario가 있는지 확인한다.
   - 연결된 scenario의 evidence가 해당 `complete.log`의 verification 또는 evidence 경로로 설명 가능해야 한다.
   - SDD 파일이 없거나 `USER_REVIEW.md`가 남아 있거나 Evidence Map 연결이 비어 있으면 Task 체크 또는 `[검토중]` 전환을 하지 않고 차단 사유로 보고한다.

6. **Milestone 문서 반영**
   - `mode=check-only`이면 파일을 수정하지 않고 반영 후보만 보고한다.
   - 검증된 완료 Task id만 `[x]`로 바꾼다. 이미 `[x]`인 항목은 유지한다.
   - 일부 Task만 완료되었고 미완료 Task가 남으면 Milestone 상태는 `[진행중]`으로 둔다. 단, 기존 상태가 `[검토중]`, `[보류]`, `[폐기]`이면 자동으로 낮추지 않고 차이만 보고한다.
   - 모든 기능 Task가 `[x]`이고 `구현 잠금`이 `해제`, `결정 필요: 없음`, SDD 사용자 리뷰 없음, SDD evidence 충족이면 Milestone 상태를 `[검토중]`으로 바꾼다.
   - `[검토중]`으로 바꾸면 `완료 리뷰` 섹션을 만들거나 갱신하고, 반영한 `complete.log`, 완료 Task id, 남은 차단 항목 없음 또는 요약을 1~3줄로 남긴다.
   - 모든 Task가 `[x]`여도 구현 잠금이나 SDD gate가 남으면 `[검토중]`으로 바꾸지 않고 `완료 리뷰` 또는 `작업 컨텍스트`에 차단 항목을 남긴다.
   - 이 스킬은 Milestone을 `[완료]`로 바꾸거나 archive로 이동하지 않는다.

7. **Phase와 current 라벨 동기화**
   - 대상 Phase `PHASE.md`의 `Milestone 흐름`에서 대상 Milestone 상태 라벨을 Milestone 본문 상태와 맞춘다.
   - `agent-roadmap/current.md`에 대상 Milestone이 있으면 상태 라벨을 Milestone 본문 상태와 맞춘다.
   - `current.md`에는 `[완료]` 또는 `[폐기]`를 남기지 않는다. 이 스킬은 `[검토중]`까지 유지할 수 있다.

8. **workspace lock 확인**
   - `.agent-roadmap-sync/locks.yaml`이 있으면 대상 Milestone identity로 `agent-ops/bin/roadmap-dependency-checker.sh --find-milestone "<project>:<milestone-path>" both "<locks-file>"`를 실행한다.
   - 관련 lock이 없으면 결과에 `Workspace 잠금: 관련 lock 없음`을 남긴다.
   - 대상 Milestone identity가 어느 entry의 `rely-on.target`과 일치하면 대상 Milestone 상태 기준으로 해당 `rely-on.status`를 동기화한다. `[검토중]` 또는 `[완료]`이면 `enable`, 그 외 상태면 `disable`이다.
   - 대상 Milestone identity가 어느 entry의 `locked`와 일치하면 모든 `rely-on.status`가 `enable`인지 결과에 남긴다.
   - 이 스킬에서 새 lock을 만들거나 다른 Milestone의 구현 잠금을 직접 해제하지 않는다.

9. **결과 보고**
   - 수정 파일과 변경 전/후 상태를 보고한다.
   - 읽은 active/archive `complete.log` 후보 수와 반영한 Task id를 보고한다.
   - 반영하지 않은 `complete.log`가 있으면 이유를 보고한다.
   - SDD gate, 완료 리뷰, Workspace lock, 남은 미완료 Task를 보고한다.

## 실행 결과 검증

- [ ] 대상 Milestone이 활성 경로에서 정확히 하나로 확정되었는가
- [ ] 같은 `m-<milestone-slug>`의 active `complete.log`와 archive `complete.log` 후보를 모두 확인했는가
- [ ] archive 확인을 생략하고 active task만 근거로 no-op 처리하지 않았는가
- [ ] `Roadmap Completion`의 Milestone 경로와 Task id가 대상 Milestone과 exact match였는가
- [ ] `SDD: 필요`인 경우 SDD 파일, `USER_REVIEW.md` 부재, Acceptance Scenario, Evidence Map 연결을 확인했는가
- [ ] 완료 근거가 있는 Task만 `[x]`로 바꾸었는가
- [ ] 모든 Task 완료와 구현 잠금 해제 조건이 충족된 경우에만 `[검토중]`으로 전환했는가
- [ ] `[검토중]`으로 전환했다면 `완료 리뷰`에 완료 근거와 남은 차단 항목이 남았는가
- [ ] Phase `PHASE.md`와 `agent-roadmap/current.md`의 상태 라벨이 Milestone 본문과 일치하는가
- [ ] `[검토중]` 전환만 수행하고 `[완료]` 전환 또는 archive 이동을 하지 않았는가
- [ ] `.agent-roadmap-sync/locks.yaml`이 있으면 관련 lock 여부와 필요한 `rely-on.status` 동기화를 결과에 반영했는가
- [ ] `git diff --check`를 실행했는가
- 검증 실패 시: 파일을 추가로 추정 수정하지 말고 실패한 항목, 차단 사유, 필요한 evidence 경로를 보고한다.

## 출력 형식

```markdown
## 동기화 완료

- 대상 Milestone: <path>
- 모드: <sync | check-only>
- 수정 파일:
  - <path 또는 없음>

## 반영 내용

- 상태: <변경 없음 | 이전 -> 이후>
- 완료 Task: <id 목록 또는 없음>
- 미완료 Task: <id 목록 또는 없음>
- complete.log 후보: active <N>개, archive <N>개
- 반영한 complete.log:
  - <path>
- 반영 제외 complete.log:
  - <path> - <사유>
- SDD gate: <불필요 | 충족 | 차단: 사유>
- 완료 리뷰: <변경 없음 | 검토중 갱신 | 잠금 차단 기록>
- Workspace 잠금: <관련 lock 없음 | 상태 요약 | 미확인 사유>

## TODO 항목

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

## 금지 사항

- active `agent-task/m-<milestone-slug>`만 확인하고 archive `complete.log` 확인 없이 no-op 처리하지 않는다.
- 대상 slug와 다른 `agent-task/archive/**` 문서를 일반 탐색하지 않는다.
- `complete.log`의 `Roadmap Completion` 없이 파일명, 커밋 메시지, plan/review log만으로 Task를 `[x]` 처리하지 않는다.
- Task id를 의미 유사도, 순서, 파일명으로 추정하지 않는다.
- SDD gate가 필요한데 Evidence Map 연결을 확인하지 않고 `[검토중]`으로 전환하지 않는다.
- 구현 잠금이 남아 있거나 `결정 필요`가 있으면 `[검토중]`, `[완료]`, archive를 수행하지 않는다.
- 이 스킬에서 새 Milestone/Epic/Task를 만들거나 기존 id를 바꾸지 않는다.
- 이 스킬에서 Milestone을 `[완료]`로 전환하거나 archive 이동하지 않는다.
