toki/gito
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
gito/agent-ops/skills/common/sync-milestone-workstate/SKILL.md

11 KiB
Raw Blame History

name version description
sync-milestone-workstate 1.0.0 현 마일스톤과 작업현황 동기화, 현재 마일스톤 작업현황 동기화, 마일스톤 완료내역 동기화, 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 경로를 보고한다.

출력 형식

## 동기화 완료

- 대상 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 이동하지 않는다.