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

name	description
sync-milestone-workstate	현재 또는 지정 Milestone을 시작하기 전 전체 활성 workstate와 대상의 코드·SDD·spec·contract 정합성을 검사해 Plan 준비 상태를 판정하거나, 진행·종료 시 complete.log·파일·git evidence를 Task별로 집계해 상태를 동기화하는 절차. "현재 마일스톤 정합성 체크해", "특정 마일스톤 정합성 체크해", Plan 전 리프레시, 완료내역 반영, 체크박스 재동기화 요청에서 사용한다.

sync-milestone-workstate

목적

현재 또는 지정 Milestone의 시작 전 정합성과 진행·종료 workstate를 실제 repository evidence에 맞춘다.

• 시작 전 consistency-check는 프로젝트 전체 활성 작업현황을 얕게 확인하고 대상 Milestone의 목표·범위·기능·SDD·spec·contract 가정을 현재 코드와 깊게 대조해 Plan 준비 상태를 판정한다.
• 진행·종료의 check-only와 sync는 같은 Milestone task group의 완료 evidence를 현재 기능 Task 계약에 집계한다.

consistency-check와 check-only는 read-only다. 이 스킬은 새 작업을 배치하거나 구현 계획을 만들지 않는다. 시작 전 발견한 미반영 완료는 같은 스킬의 sync로 검증·반영하고, 문서 drift는 update-roadmap, roadmap-sdd, update-spec, update-contract 책임으로 넘긴다.

새 계약의 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로 가정하지 않는다.

언제 호출할지

• 사용자가 "현재 마일스톤 정합성 체크해", "<이름> 마일스톤 정합성 체크해"처럼 현재 또는 지정 Milestone을 시작하기 전 실제 프로젝트 상태와 대조해 달라고 요청할 때
• 사용자가 마일스톤 시작, Plan 전 마일스톤 리프레시, 전체 프로젝트 작업현황과 대상 Milestone 정합성 확인을 요청할 때
• 사용자가 현 마일스톤과 작업현황 동기화, 마일스톤 완료내역 반영, 체크박스 재동기화를 요청할 때
• 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 경로. sync 또는 check-only에서 이 파일을 우선 검증하되 같은 Milestone task group의 다른 완료 로그도 집계한다. (선택)
• mode: consistency-check, sync, check-only 중 하나다. 기본값은 sync다. consistency-check와 check-only에서는 어떤 파일도 수정하지 않는다. (선택)

모드 경계

mode	lifecycle	책임	쓰기
consistency-check	시작 전	전역 활성 workstate를 얕게 확인하고 대상 Milestone과 현재 repository의 semantic drift 및 Plan 준비 상태를 판정	금지
check-only	진행·종료	완료 evidence를 Task별로 집계하고 반영 후보만 판정	금지
sync	진행·종료	검증된 완료 evidence를 Task 체크와 허용된 Milestone/Phase/current 상태에 반영	허용

check-only는 완료 evidence dry-run이고 consistency-check는 시작 전 semantic drift 감사다. 두 모드를 같은 의미로 사용하지 않는다.

consistency-check 실행 절차

1. 대상 Milestone 확정

   • target-milestone이 있으면 활성 agent-roadmap/phase/*/milestones/*.md에서 정확히 하나를 찾는다.
   • 없으면 agent-roadmap/current.md의 단일 활성 Milestone을 사용한다.
   • 대상이 없거나 둘 이상이거나 archive 경로이면 어떤 파일도 수정하지 않고 blocked로 보고한다.

2. 프로젝트 활성 workstate snapshot 구성

   • agent-roadmap/current.md와 priority-queue.md는 존재할 때만 읽고, 없으면 만들지 않은 채 각각 local current 없음, 전역 실행 순서 없음으로 기록한다. 명시 target이 있으면 current 부재만으로 차단하지 않고, queue 부재·파싱 오류는 refresh-required로 판정한다.
   • ROADMAP.md의 Phase 흐름, 모든 active Phase PHASE.md의 Milestone 흐름, active Milestone 문서의 H1·상태·구현 잠금 상태와 .agent-roadmap-sync/locks.yaml 존재 시 관련 lock을 얕게 읽는다.
   • 각 prefix의 active lane head, 대상의 선행 차단과 실제 진행 중인 참조 대상에 대한 동시 차단, Milestone/Phase/current 라벨 불일치와 구현 잠금 상태를 확인한다. prefix 그룹 순서와 일반적인 관련성은 의존성으로 만들지 않는다.
   • current.md는 활성 후보 창이지 실제 진행 상태가 아니다. 실제 진행 중 여부는 사용자 명시와 active task evidence로 구분한다.
   • agent-task/의 active task group 이름과 PLAN/CODE_REVIEW/USER_REVIEW 존재 상태를 얕게 확인한다. unrelated task 본문을 전부 읽지 않는다.
   • git status --short로 checkout의 활성 변경을 확인하되 사용자 변경을 수정하거나 완료 evidence로 간주하지 않는다.

3. 대상 Milestone 계약 읽기

   • 목표, 상태, 구현 잠금, 범위, 기능, 범위 제외, 작업 컨텍스트와 관련 Phase/queue 설명을 읽는다.
   • SDD: 필요이면 SDD의 현재 책임 경계, Acceptance Scenario, Evidence Map과 같은 디렉터리의 USER_REVIEW.md 존재 여부를 확인한다.
   • 대상 task group이 이미 있으면 이 스킬의 완료 로그 수집·Task별 evidence 집계 기준을 재사용해 구현됐지만 Milestone에 반영되지 않은 capability가 있는지 확인한다. 다른 slug의 archive는 읽지 않는다.

4. 현재 repository 기준선 확인

   • 프로젝트와 대상 경로의 domain rule을 먼저 읽는다.
   • agent-spec/이 있으면 rules-agent-spec.md, agent-spec/index.md, 매칭되는 현재 spec만 읽는다.
   • API, wire, config, schema 또는 컴포넌트 간 계약이 관련되며 agent-contract/index.md가 있으면 index와 매칭되는 active contract만 읽는다.
   • Milestone 작업 컨텍스트의 관련 경로에서 rg --files, symbol 검색, 현재 코드·config·proto·테스트를 확인한다. 필요할 때만 관련 경로의 git log, git show, git diff를 사용한다.
   • 전체 repository를 무차별 감사하지 않고 전역 workstate는 얕게, 대상 Milestone과 직접 의존 기반만 깊게 확인한다.

5. semantic drift 분류

   • already-implemented: 현재 capability가 구현됐지만 Task/evidence에 반영되지 않았다.
   • stale-assumption: Milestone 또는 SDD가 현재 존재하지 않는 owner, 경로, 상태 전이, API/wire/config 구조를 전제한다.
   • dependency-drift: 선행 기반이나 공통 coordinator가 변경돼 계획한 구현·검증·retry/identity 경계를 다시 써야 한다.
   • scope-drift: 현재 기능 Task가 중복·누락됐거나 현재 책임 경계와 충돌한다.
   • queue-lock-drift: 실제 의존·배타적 변경 책임과 priority queue blocker 또는 workspace lock이 충돌한다. 경로 중복이나 일반적인 관련성만으로 동시 차단을 만들지 않는다.
   • evidence-gap: 구현 가능성 판단에 필요한 spec, contract, test 또는 provenance가 부족하다.
   • 아직 구현되지 않은 미래 capability 자체는 정상 planned delta다. 현재 구조와 충돌하거나 이미 대체된 경우에만 drift로 분류한다.

6. Plan 준비 상태 판정

   • ready: 대상이 [계획] 또는 [진행중], 구현 잠금과 SDD gate가 해제되고 blocker가 없으며 Plan 입력을 바꿀 semantic drift가 없다.
   • refresh-required: 대상 identity는 유효하지만 Milestone/SDD/spec/contract/queue를 현재 기준으로 갱신해야 Plan 범위를 확정할 수 있다.
   • blocked: 대상이 모호하거나 [스케치]·[보류], 해당 prefix의 active lane head가 아니거나 구현 잠금·사용자 결정·SDD review·선행/동시/외부 의존이 남아 Plan을 시작할 수 없다.

7. read-only 보고와 후속 라우팅

   • 어떤 파일도 수정하지 않고 아래 consistency-check 판정 보고 형식으로 결과를 남긴다.
   • 사용자가 "체크해", "확인해"만 요청했으면 보고 후 멈춘다.
   • 사용자가 "정합성 맞춰줘", "리프레시해", "검사하고 반영해"까지 요청했으면 caller/router가 보고 evidence를 유지한다. already-implemented Task는 같은 스킬의 mode=sync, Milestone/queue/lock은 update-roadmap, SDD는 roadmap-sdd, living spec은 update-spec, contract는 update-contract로 넘긴다.
   • 후속 갱신 뒤 consistency-check를 다시 실행한다. ready가 확인되고 별도 Plan 요청 또는 연결된 사용자 요청이 있을 때만 plan으로 진행한다.

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] 처리하지 않는다.

sync/check-only 실행 절차

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 링크로 쓴다.

판정 보고 형식

consistency-check 판정 보고 형식

## 마일스톤 시작 정합성 체크

- 대상 Milestone: [<milestone-name>](agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md)
- 모드: consistency-check
- Plan 준비 상태: <ready | refresh-required | blocked>

## 프로젝트 작업현황

- current/Phase/Milestone 상태: <정합 | 불일치 요약>
- queue/lock: <실행 가능 | 차단 요약 | 정리 필요>
- active agent-task: <관련 상태 요약 또는 없음>
- checkout 변경: <관련 변경 요약 또는 없음>
- 깊게 확인한 범위: <문서·코드·config·proto·테스트 링크 또는 없음>

## Drift 판정

- <already-implemented | stale-assumption | dependency-drift | scope-drift | queue-lock-drift | evidence-gap>: <evidence와 영향 또는 없음>

## 후속 라우팅

- 필요한 갱신: <쉼표로 구분한 sync-milestone-workstate mode=sync | update-roadmap | roadmap-sdd | update-spec | update-contract 목록 또는 없음>
- Plan 진행 조건: <충족 | 필요한 선행 조치>

sync/check-only 판정 보고 형식

## 동기화 완료

- 대상 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: <남은 차단 항목 또는 없음>

금지 사항

• consistency-check에서 파일을 수정하거나 Task 체크박스·Milestone 상태·queue·lock을 변경하지 않는다.
• 정상 planned delta를 현재 미구현이라는 이유만으로 drift 또는 차단으로 판정하지 않는다.
• 전역 workstate 확인을 이유로 unrelated 코드, unrelated active task 본문 또는 다른 Milestone의 archive를 무차별 탐색하지 않는다.
• refresh-required 또는 blocked 상태에서 Plan을 만들거나 구현을 시작하지 않는다.
• 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를 바꾸지 않는다.