iop/agent-ops/skills/common/sync-milestone-workstate/SKILL.md

name	description
sync-milestone-workstate	현 마일스톤과 작업현황 동기화, 현재 마일스톤 작업현황 동기화, 마일스톤 완료내역 동기화, agent-task 완료를 마일스톤에 반영, complete.log의 milestone-task id별 증거 집계, active/archive 완료 로그 스캔, legacy Roadmap Completion 복구, 파일/git 기준 작업 상태 확인, 마일스톤 체크박스 재동기화 요청에서 Milestone Task와 상태를 실제 evidence에 맞추는 절차

sync-milestone-workstate

목적

현재 또는 지정 Milestone의 기능 Task 상태를 실제 작업 evidence와 동기화한다. 새 작업을 배치하거나 구현 계획을 수정하지 않는다.

새 계약의 complete.log 첫 줄 milestone-task=<id>[,<id>...]는 해당 완료 작업의 evidence가 어느 Milestone Task에 기여하는지 나타내는 인덱스다. 이 값만으로 Task 완료를 선언하지 않는다. 같은 Milestone task group의 모든 완료 로그를 id별로 모은 뒤 현재 Task 설명, Task 안의 검증:, 관련 파일/git evidence, 필요한 SDD Acceptance Scenario와 Evidence Map을 함께 평가해 계약 전체가 충족된 Task만 [x]로 바꾼다.

한 plan이 여러 Task id에 기여하거나 여러 plan이 같은 Task id에 기여할 수 있다. 따라서 plan 하나의 PASS와 Milestone Task 하나의 완료를 1:1로 가정하지 않는다.

언제 호출할지

• 사용자가 현 마일스톤과 작업현황 동기화, 마일스톤 완료내역 반영, 체크박스 재동기화를 요청할 때
• code-review가 m-* PASS completion event와 complete-log를 전달했을 때
• complete.log의 milestone-task id별 evidence를 모아 현재 Task 계약을 평가해야 할 때
• 과거 Roadmap Completion 또는 task metadata가 없는 완료 기록을 새 계약과 함께 복구해야 할 때
• agent-task 기록이 없지만 실제 파일/git 기준 완료 가능성을 감사해야 할 때

입력

• target-milestone: 활성 Milestone 이름, slug, 또는 경로. 없으면 agent-roadmap/current.md의 단일 활성 Milestone을 사용한다. (선택)
• complete-log: 방금 완료된 exact complete.log 경로. 이 파일을 우선 검증하되 같은 Milestone task group의 다른 완료 로그도 집계한다. (선택)
• mode: sync 또는 check-only. 기본값은 sync다. check-only에서는 어떤 파일도 수정하지 않는다. (선택)

first-line metadata 계약

새 m-* 완료 로그의 첫 줄은 다음 형식이다.

<!-- task=m-<milestone-slug>[/<subtask_dir>] plan=<N> tag=<TAG> milestone-task=<task-id>[,<task-id>...] -->

• 주석은 파일 첫 줄에 있어야 한다.
• task의 첫 path segment는 집계 대상 m-<milestone-slug>와 정확히 같아야 한다.
• milestone-task는 비어 있지 않은 쉼표 구분 목록이며 공백과 중복 id를 허용하지 않는다. 각 id는 rules-roadmap.md의 item-id 문법과 일치해야 한다.
• 모든 id는 대상 활성 Milestone 기능에 존재해야 한다.
• PLAN, CODE_REVIEW, complete.log는 같은 generation header를 보존한다.
• metadata는 evidence routing 범위다. PASS 또는 id 존재만으로 [x] 처리하지 않는다.

실행 절차

1. 대상 Milestone 확정

   • target-milestone이 있으면 활성 agent-roadmap/phase/*/milestones/*.md에서 정확히 하나를 찾는다.
   • 없으면 agent-roadmap/current.md의 활성 Milestone 단일 후보를 사용한다.
   • 대상이 없거나 둘 이상이거나 archive 경로이면 어떤 상태도 수정하지 않고 target 불명확으로 보고한다.
   • 대상 Phase PHASE.md와 current.md의 현재 라벨도 함께 기록한다.

2. 현재 Task 계약 읽기

   • 대상 Milestone 기능의 - [ ] [id]와 - [x] [id]만 Task 후보로 추출한다.
   • 각 Task 설명, 같은 Task 안의 검증:, 관련 Epic 범위, 작업 컨텍스트 관련 경로를 기록한다.
   • 구현 잠금, 결정 필요, SDD: 필요|불필요, SDD 경로, SDD USER_REVIEW.md 존재 여부를 확인한다.
   • 동기화 기준은 과거 plan 문구가 아니라 현재 Milestone Task 계약이다. 계약이 변경되어 evidence가 부족해졌으면 자동 완료하지 않는다.

3. 같은 task group의 완료 로그 수집

   • task group을 m-<milestone-slug>로 고정한다.
   • active 후보: agent-task/m-<milestone-slug>/complete.log, agent-task/m-<milestone-slug>/**/complete.log
   • archive 후보: agent-task/archive/*/*/m-<milestone-slug>/complete.log, agent-task/archive/*/*/m-<milestone-slug>/**/complete.log
   • 전달된 complete-log도 포함하되 resolved path가 위 task group과 일치해야 한다.
   • 다른 slug의 agent-task/archive/**는 탐색하지 않는다.
   • 동일 resolved path는 한 번만 센다.

4. 로그 분류와 id별 인덱스 구성

   • canonical 로그는 first-line metadata를 파싱하고 task group, id 문법, 중복, 대상 Milestone의 기존 id 여부를 검증한다.
   • 유효한 canonical 로그를 각 milestone-task id bucket에 모두 넣는다. 한 로그가 여러 id를 가지면 각 bucket에 기여한다.
   • unknown id, 다른 task group, PLAN/review header 불일치, PASS가 아닌 terminal 결과, unresolved Required/Suggested, 상충하는 검증 결과가 있으면 해당 로그를 자동 완료 evidence에서 제외하고 이유를 보고한다.
   • 같은 id에 로그가 여러 개면 어느 하나를 대표로 고르지 말고 모두 보존한다.
   • first-line metadata가 없고 legacy Roadmap Completion이 있는 로그는 명시 완료 주장과 연결 evidence를 호환 근거로 분류한다. 현재 Task 계약과 SDD gate를 다시 평가하며 섹션만 보고 즉시 체크하지 않는다.
   • metadata와 Roadmap Completion이 모두 없는 legacy 로그는 관련 파일/git 탐색을 위한 힌트로만 사용한다.

5. Task별 evidence 집계

   • 각 Task id마다 bucket의 모든 complete.log에서 구현/정리 내용, 최종 검증, archived plan/review 포인터, final verdict를 모은다.
   • 필요한 경우 같은 완료 디렉터리의 exact plan_*.log와 code_review_*.log만 읽어 metadata 일치와 구체적인 구현·검증 evidence를 확인한다. sibling archive task group 밖으로 확장하지 않는다.
   • Milestone의 관련 경로를 rg --files와 Task 키워드로 확인하고, 현재 파일 내용이 Task 설명의 각 요구를 실제로 제공하는지 대조한다.
   • git log --oneline -- <관련 경로>와 필요한 git show --stat --name-only <commit>으로 provenance를 보조 확인한다. 커밋 메시지만으로 완료 처리하지 않는다.
   • 한 로그가 Task 계약 전체를 충족하면 단독으로 완료 evidence가 될 수 있다. 여러 로그가 각각 세분화된 하위 범위를 맡았다면 합집합이 계약 전체와 검증을 충족할 때 완료 evidence가 된다.
   • 로그 수, plan 수, 특정 tag 존재, 파일명 유사성은 완료 기준이 아니다.

6. 검증과 SDD gate 평가

   • Task에 검증:이 있으면 집계된 실제 실행 결과, 현재 재실행 결과, 또는 같은 범위를 검증하는 명시 evidence가 있어야 한다.
   • 테스트 자체가 산출물인 Task는 테스트 코드와 실행 evidence를 모두 요구한다.
   • SDD: 필요이면 해당 Task id에 연결된 모든 필요한 Acceptance Scenario와 Evidence Map row를 찾는다. 집계한 로그·파일·검증 evidence가 그 mapping을 충족해야 한다.
   • SDD 파일 부재, 미승인/잠금 상태, 남은 SDD USER_REVIEW.md, Task mapping 부재는 해당 Task 자동 체크를 차단한다.
   • evidence가 의미상 유사하지만 id와의 연결 또는 요구 범위가 불명확하면 검토 필요로 남긴다.

7. 완료 판정

   • 다음이 모두 참인 Task만 [x] 후보로 판정한다.
     • 현재 Task 설명의 capability와 산출물이 모두 확인된다.
     • 명시 검증:이 충족된다.
     • 필요한 SDD mapping과 evidence가 충족된다.
     • 집계 evidence 사이에 미완료 선언, 실패, scope 충돌이 없다.
   • canonical bucket이 비어 있어도 파일/git 감사로 계약 전체가 명확히 충족되면 완료 후보가 될 수 있으나, 어떤 evidence가 각 요구를 충족했는지 보고한다.
   • canonical 로그가 하나 이상 있어도 계약 일부만 충족하면 [x] 처리하지 않는다.

8. Milestone/Phase/current 반영

   • mode=check-only이면 후보만 보고하고 파일을 수정하지 않는다.
   • 새로 검증된 Task만 [x]로 바꾸고 기존 [x]는 유지한다. evidence가 상실된 기존 [x]는 자동으로 되돌리지 않고 불일치로 보고한다.
   • 미완료 Task가 남으면 일반적으로 [진행중]을 유지한다. 기존 [검토중], [보류], [폐기]는 자동 하향하지 않고 차이를 보고한다.
   • 모든 Task가 [x]이고 구현 잠금 해제, 결정 필요: 없음, SDD gate 충족이면 Milestone을 [검토중]으로 바꾸고 완료 리뷰에 id별 집계 로그와 파일/git evidence를 1~3줄로 요약한다.
   • 이 스킬은 [완료] 전환이나 archive 이동을 하지 않는다.
   • 대상 Phase PHASE.md와 agent-roadmap/current.md의 대상 라벨을 Milestone 본문과 맞춘다. current.md에는 [완료] 또는 [폐기]를 남기지 않는다.

9. workspace lock 확인

   • .agent-roadmap-sync/locks.yaml이 있으면 agent-ops/bin/roadmap-dependency-checker.sh --find-milestone "<project>:<milestone-path>" both "<locks-file>"를 실행한다.
   • 대상이 rely-on.target이면 [검토중] 또는 [완료]에서 enable, 그 외에는 disable로 동기화한다. check-only에서는 쓰지 않는다.
   • 새 lock을 만들거나 다른 Milestone 잠금을 직접 해제하지 않는다.

10. 검증과 보고

• git diff --check를 실행한다.
• active/archive 후보 수, canonical/legacy/제외 수, Task id별 연결 로그와 판정, 파일/git 범위, SDD gate, 상태 변경, 남은 차단을 보고한다.
• 문서와 산출물 포인터는 Markdown 링크로 쓴다.

판정 보고 형식

## 동기화 완료

- 대상 Milestone: [<milestone-name>](agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md)
- 모드: <sync | check-only>
- 상태: <변경 없음 | 이전 -> 이후>
- complete.log 후보: active <N>개, archive <N>개, canonical <N>개, legacy <N>개, 제외 <N>개

## Task별 집계

- `<task-id>`: <완료 | 미완료 | 검토 필요>
  - 연결 로그: <N>개
  - 충족 evidence: <요약 또는 없음>
  - 미충족/충돌: <요약 또는 없음>
  - SDD gate: <불필요 | 충족 | 차단>

## 반영 내용

- 새로 완료 처리한 Task: <id 목록 또는 없음>
- 남은 Task: <id 목록 또는 없음>
- 수정 파일: <Markdown 링크 목록 또는 없음>
- Workspace 잠금: <관련 lock 없음 | 상태 요약 | 미확인 사유>
- TODO: <남은 차단 항목 또는 없음>

금지 사항

• milestone-task id 존재, plan PASS, 로그 개수만으로 Task를 [x] 처리하지 않는다.
• plan 하나와 Task 하나를 1:1로 가정하거나, 같은 id의 여러 로그 중 하나만 임의 선택하지 않는다.
• 새 canonical 로그에 Roadmap Completion 작성을 요구하지 않는다.
• legacy Roadmap Completion도 현재 Task 계약과 SDD gate 재평가 없이 즉시 반영하지 않는다.
• active task만 보고 archive 후보를 생략하거나 complete.log 부재만으로 미완료를 단정하지 않는다.
• 커밋 메시지, 파일명, plan/review log만으로 완료 처리하지 않는다.
• 의미 유사도, 순서, 파일명으로 unknown id를 보정하지 않는다.
• 구현 잠금이나 SDD gate가 남은 상태에서 [검토중], [완료], archive를 수행하지 않는다.
• 새 Milestone/Epic/Task를 만들거나 기존 id를 바꾸지 않는다.