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

14 KiB
Raw Blame History

name version description
sync-milestone-workstate 1.1.0 현 마일스톤과 작업현황 동기화, 현재 마일스톤 작업현황 동기화, 마일스톤 완료내역 동기화, agent-task 완료를 마일스톤에 반영, active/archive complete.log 후보 스캔, 누락된 Roadmap Completion 복구, 작은 작업처럼 agent-task 기록이 없는 완료 내역을 관련 파일과 git 기록까지 종합 확인, 마일스톤 체크박스 재동기화 요청에서 Milestone Task, 상태, Phase/current 라벨을 실제 evidence와 맞추는 절차

sync-milestone-workstate

목적

현재 또는 지정 Milestone의 기능 Task 상태를 실제 작업 evidence와 동기화한다. 새 작업을 배치하거나 구현 계획을 수정하지 않는다. complete.log의 Roadmap Completion은 가장 강한 직접 근거로 사용하되, 그 파일이 있더라도 관련 파일과 git history로 최소 sanity pass를 수행한다. complete.log가 없거나 불완전해도 완료가 없다고 단정하지 않는다. 작은 작업이나 수동 수정처럼 agent-task 기록이 없을 수 있으므로 Milestone의 관련 경로, 실제 파일 내용, git history, 테스트/검증 흔적을 함께 확인한다. 런타임이 origin-task와 complete-log를 단건 완료 이벤트로 전달한 일반 반영은 update-roadmap을 사용한다.

언제 호출할지

  • 사용자가 "현 마일스톤과 작업현황 동기화", "현재 마일스톤 작업현황 동기화", "마일스톤 작업현황 동기화"라고 요청할 때
  • 사용자가 "마일스톤 완료내역 동기화", "agent-task 완료를 마일스톤에 반영", "complete.log 후보 스캔"이라고 요청할 때
  • 사용자가 "누락된 Roadmap Completion 복구", "마일스톤 체크박스 재동기화", "로드맵 작업 완료 상태 동기화"라고 요청할 때
  • 사용자가 agent-task에는 없지만 실제 파일/git 기준으로는 완료된 것 같다고 지적할 때
  • 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다. (선택)
    • check-only: 어떤 파일도 수정하지 않는다. Milestone, Phase, current.md, .agent-roadmap-sync/locks.yaml 모두 쓰기 금지이며 반영 후보만 보고한다.

먼저 확인할 것

  • 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으로 끝내지 않는다.
  • 관련 파일과 git history를 최소 확인한다. complete.log가 없거나 일부 Task만 설명하면 더 깊게 감사한다.

실행 절차

  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와 evidence scope 읽기

    • Milestone 기능 섹션의 Task id만 완료 후보로 본다.
    • Task id는 - [ ] [item-id] 또는 - [x] [item-id] 형식에서 추출한다.
    • 각 Task의 설명과 검증: 문구를 기록한다.
    • 구현 잠금의 상태, 결정 필요, SDD: 필요|불필요, SDD 경로를 확인한다.
    • 작업 컨텍스트의 관련 경로, Milestone 범위, Task 설명의 코드/문서 키워드를 evidence scope로 삼는다.
    • 관련 경로가 전혀 없으면 Task 설명에서 검색어를 만들되, 후보가 넓거나 모호하면 Task를 자동 완료하지 않고 scope 불명확으로 보고한다.

  3. complete.log 후보 수집

    • 대상 Milestone slug를 <milestone-slug>로 두고 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 입력이 있으면 그 파일도 후보에 포함하되, Roadmap Completion의 Milestone 경로가 대상과 일치해야 직접 반영한다.
    • 일반 agent-task/archive/** 전체를 훑지 말고 위 패턴에 맞는 같은 milestone task group만 읽는다.

  4. Roadmap Completion 직접 근거 검증

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

  5. 파일/git evidence 감사

    • 항상 대상 Milestone의 관련 파일과 git history를 최소 확인한다.
    • Roadmap Completion으로 확인되지 않은 Task가 있거나 사용자가 실제 구현 완료를 지적하면 Task별 상세 감사를 수행한다.
    • 관련 파일을 rg --files <관련 경로>와 Task 키워드 rg로 찾고, 필요한 파일 본문을 읽어 Task 설명과 직접 대응되는 구현/문서/테스트 변경을 확인한다.
    • git log --oneline -- <관련 경로>와 필요한 경우 git show --stat --name-only <commit>로 Milestone 관련 커밋을 확인한다.
    • 커밋 메시지만으로 Task를 완료 처리하지 않는다. 커밋이 변경한 파일과 현재 파일 내용이 Task 설명을 충족해야 한다.
    • Task 완료 인정 기준:
      • 구현/산출물 evidence가 Task 설명과 직접 대응한다.
      • Task에 검증:이 있으면 해당 검증 명령의 기록, 현재 테스트 실행 결과, 또는 같은 범위를 검증하는 명시 evidence가 있다.
      • validation-tests 같은 테스트 Task는 테스트 코드와 검증 실행 evidence가 모두 있어야 한다.
    • evidence가 의미상 유사하지만 Task id와 연결이 불분명하면 [x] 처리하지 않고 검토 필요로 보고한다.

  6. SDD Evidence Map 확인

    • SDD: 필요인 Milestone은 direct evidence와 file/git evidence 모두 SDD gate를 통과해야 한다.
    • SDD Acceptance Scenarios와 Evidence Map에서 각 완료 후보 Task id와 연결된 scenario가 있는지 확인한다.
    • 연결된 scenario의 evidence가 확인한 complete log, 파일 변경, git commit, verification 중 하나로 설명 가능해야 한다.
    • SDD 파일이 없거나 USER_REVIEW.md가 남아 있거나 Evidence Map 연결이 비어 있으면 Task 체크 또는 [검토중] 전환을 하지 않고 차단 사유로 보고한다.

  7. Milestone 문서 반영

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

  8. Phase와 current 라벨 동기화

    • mode=check-only이면 이 단계를 쓰기 없이 확인만 한다.
    • 대상 Phase PHASE.md의 Milestone 흐름에서 대상 Milestone 상태 라벨을 Milestone 본문 상태와 맞춘다.
    • agent-roadmap/current.md에 대상 Milestone이 있으면 상태 라벨을 Milestone 본문 상태와 맞춘다.
    • current.md에는 [완료] 또는 [폐기]를 남기지 않는다. 이 스킬은 [검토중]까지 유지할 수 있다.

  9. workspace lock 확인

    • mode=check-only이면 관련 lock 여부와 필요한 동기화 후보만 보고하고 locks.yaml을 수정하지 않는다.
    • .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의 구현 잠금을 직접 해제하지 않는다.

  10. 결과 보고

  • 수정 파일과 변경 전/후 상태를 보고한다.
  • 읽은 active/archive complete.log 후보 수, 확인한 관련 파일/git 범위, 반영한 Task id를 보고한다.
  • 반영하지 않은 complete.log나 Task가 있으면 이유를 보고한다.
  • SDD gate, 완료 리뷰, Workspace lock, 남은 미완료 Task, 검토 필요 Task를 보고한다.

실행 결과 검증

  • 대상 Milestone이 활성 경로에서 정확히 하나로 확정되었는가
  • 같은 m-<milestone-slug>의 active/root/nested complete.log와 archive/root/nested complete.log 후보를 모두 확인했는가
  • archive 확인을 생략하고 active task만 근거로 no-op 처리하지 않았는가
  • complete.log 부재만으로 완료 Task 없음이라고 단정하지 않았는가
  • 관련 파일과 git history를 확인했거나, scope 불명확 사유를 보고했는가
  • Roadmap Completion의 Milestone 경로와 Task id가 대상 Milestone과 exact match였는가
  • SDD: 필요인 경우 SDD 파일, USER_REVIEW.md 부재, Acceptance Scenario, Evidence Map 연결을 확인했는가
  • 완료 근거가 있는 Task만 [x]로 바꾸었는가
  • 모든 Task 완료와 구현 잠금 해제 조건이 충족된 경우에만 [검토중]으로 전환했는가
  • [검토중]으로 전환했다면 완료 리뷰에 complete.log, 파일/git evidence, 남은 차단 항목이 남았는가
  • 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 목록 또는 없음>
- 검토 필요 Task: <id 목록 또는 없음>
- complete.log 후보: active <N>개, archive <N>개
- 반영한 complete.log:
  - <path>
- 반영 제외 complete.log:
  - <path> - <사유>
- 파일/git evidence:
  - <task-id 또는 범위> - <파일/커밋/검증 요약>
- SDD gate: <불필요 | 충족 | 차단: 사유>
- 완료 리뷰: <변경 없음 | 검토중 갱신 | 잠금 차단 기록>
- Workspace 잠금: <관련 lock 없음 | 상태 요약 | 미확인 사유>

## TODO 항목

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

금지 사항

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