From 7d549cab99733e1f10a6fbc2476c2dec24e2e203 Mon Sep 17 00:00:00 2001 From: toki Date: Fri, 3 Jul 2026 05:32:23 +0900 Subject: [PATCH] sync: from iop v1.1.161 --- agent-ops/.version | 2 +- agent-ops/skills/common/router.md | 4 +- .../common/sync-milestone-workstate/SKILL.md | 94 ++++++++++++------- 3 files changed, 63 insertions(+), 37 deletions(-) diff --git a/agent-ops/.version b/agent-ops/.version index 350e5c8..4743491 100644 --- a/agent-ops/.version +++ b/agent-ops/.version @@ -1 +1 @@ -1.1.160 +1.1.161 diff --git a/agent-ops/skills/common/router.md b/agent-ops/skills/common/router.md index d422b6a..fe1dee1 100644 --- a/agent-ops/skills/common/router.md +++ b/agent-ops/skills/common/router.md @@ -7,7 +7,7 @@ - 구현 계획 요청에서 선택 Milestone의 구현 잠금이 남아 있으면 `plan`은 구현 계획을 만들지 않고 잠금 차단을 보고한다. - SDD 생성/갱신/잠금 해제는 `roadmap-sdd` 또는 `update-roadmap` 요청으로 처리한다. - 런타임이 `origin-task`/`complete-log` 단건 완료 이벤트를 전달한 경우는 `update-roadmap`으로 처리한다. -- active/archive `complete.log` 후보를 스캔해 누락된 Milestone 체크를 복구하거나 확인하는 요청은 `sync-milestone-workstate`로 처리한다. +- active/archive `complete.log`, 관련 파일, git history를 종합해 Milestone 작업 상태를 복구하거나 확인하는 요청은 `sync-milestone-workstate`로 처리한다. | 요청 키워드 | SKILL.md | |------------|----------| @@ -25,7 +25,7 @@ | README 작성해줘, README 만들어줘, 프로젝트 설명 문서 만들어줘 | `agent-ops/skills/common/create-readme/SKILL.md` | | 핸즈오프 남겨, handoff 작성, 인수인계 작성, 다른 세션에서 이어가게 정리, 작업을 이어받도록 기록 | `agent-ops/skills/common/create-handoff/SKILL.md` | | 로드맵 만들어줘, roadmap 생성, 마일스톤 설계, goal/phase 구조 잡아줘 | `agent-ops/skills/common/create-roadmap/SKILL.md` | -| 현 마일스톤과 작업현황 동기화, 현재 마일스톤 작업현황 동기화, 마일스톤 작업현황 동기화, 마일스톤 완료내역 동기화, agent-task 완료를 마일스톤에 반영, complete.log 후보 스캔, 누락된 Roadmap Completion 복구, 마일스톤 체크박스 재동기화, 로드맵 작업 완료 상태 동기화 | `agent-ops/skills/common/sync-milestone-workstate/SKILL.md` | +| 현 마일스톤과 작업현황 동기화, 현재 마일스톤 작업현황 동기화, 마일스톤 작업현황 동기화, 마일스톤 완료내역 동기화, agent-task 완료를 마일스톤에 반영, complete.log 후보 스캔, 누락된 Roadmap Completion 복구, 파일/git 기준 작업 상태 확인, 작은 작업 완료 반영, 마일스톤 체크박스 재동기화, 로드맵 작업 완료 상태 동기화 | `agent-ops/skills/common/sync-milestone-workstate/SKILL.md` | | 로드맵 업데이트, roadmap 갱신, 로드맵에 추가, 로드맵 작업 추가, 로드맵 기능 추가, 로드맵 Epic 추가, 로드맵 에픽 추가, 로드맵 Task 추가, 로드맵 태스크 추가, 로드맵 테스크 추가, 로드맵 TODO 추가, 마일스톤에 추가, 마일스톤 추가, 마일스톤 갱신, 마일스톤 아카이브, phase 추가, phase 변경, 페이즈 추가, 페이즈 변경, 현재 마일스톤 변경, 로드맵 한국어 전환, 로드맵 번역 | `agent-ops/skills/common/update-roadmap/SKILL.md` | | SDD 작성, SDD 생성, SDD 갱신, SDD 필요 여부, SDD gate 확인, SDD 사용자 리뷰, SDD 잠금 해제, SDD 승인 준비, SDD archive, spec gate, 설계 게이트 | `agent-ops/skills/common/roadmap-sdd/SKILL.md` | | 이 마일스톤은 X가 끝나야 가능해, A 전까지 B 잠가둬, 잠금 해제 조건은 X야, X 프로젝트 작업 뒤에 현재 마일스톤 진행, 의존성 설정해, 외부 의존 잠금 | `agent-ops/skills/common/update-roadmap/SKILL.md` | diff --git a/agent-ops/skills/common/sync-milestone-workstate/SKILL.md b/agent-ops/skills/common/sync-milestone-workstate/SKILL.md index c77cc6d..2bba4bc 100644 --- a/agent-ops/skills/common/sync-milestone-workstate/SKILL.md +++ b/agent-ops/skills/common/sync-milestone-workstate/SKILL.md @@ -1,23 +1,26 @@ --- name: sync-milestone-workstate -version: 1.0.0 -description: 현 마일스톤과 작업현황 동기화, 현재 마일스톤 작업현황 동기화, 마일스톤 완료내역 동기화, agent-task 완료를 마일스톤에 반영, active/archive complete.log 후보 스캔, 누락된 Roadmap Completion 복구, 마일스톤 체크박스 재동기화 요청에서 complete.log 근거를 Milestone Task, 상태, Phase/current 라벨에 반영하는 절차 +version: 1.1.0 +description: 현 마일스톤과 작업현황 동기화, 현재 마일스톤 작업현황 동기화, 마일스톤 완료내역 동기화, agent-task 완료를 마일스톤에 반영, active/archive complete.log 후보 스캔, 누락된 Roadmap Completion 복구, 작은 작업처럼 agent-task 기록이 없는 완료 내역을 관련 파일과 git 기록까지 종합 확인, 마일스톤 체크박스 재동기화 요청에서 Milestone Task, 상태, Phase/current 라벨을 실제 evidence와 맞추는 절차 --- # sync-milestone-workstate ## 목적 -현재 또는 지정 Milestone의 기능 Task 상태를 `agent-task` 완료 산출물과 동기화한다. -이 스킬은 새 작업을 배치하거나 계획을 수정하지 않고, `complete.log`의 `Roadmap Completion` 근거만 사용해 Milestone 체크박스와 상태 라벨을 reconcile한다. +현재 또는 지정 Milestone의 기능 Task 상태를 실제 작업 evidence와 동기화한다. +새 작업을 배치하거나 구현 계획을 수정하지 않는다. +`complete.log`의 `Roadmap Completion`은 가장 강한 직접 근거로 사용하되, 그 파일이 있더라도 관련 파일과 git history로 최소 sanity pass를 수행한다. +`complete.log`가 없거나 불완전해도 완료가 없다고 단정하지 않는다. +작은 작업이나 수동 수정처럼 `agent-task` 기록이 없을 수 있으므로 Milestone의 관련 경로, 실제 파일 내용, git history, 테스트/검증 흔적을 함께 확인한다. 런타임이 `origin-task`와 `complete-log`를 단건 완료 이벤트로 전달한 일반 반영은 `update-roadmap`을 사용한다. -이 스킬은 완료 이벤트 반영 누락을 복구하거나 active/archive 후보를 스캔해 현재 상태를 확인하는 수동 reconcile 전용이다. ## 언제 호출할지 - 사용자가 "현 마일스톤과 작업현황 동기화", "현재 마일스톤 작업현황 동기화", "마일스톤 작업현황 동기화"라고 요청할 때 - 사용자가 "마일스톤 완료내역 동기화", "agent-task 완료를 마일스톤에 반영", "complete.log 후보 스캔"이라고 요청할 때 - 사용자가 "누락된 Roadmap Completion 복구", "마일스톤 체크박스 재동기화", "로드맵 작업 완료 상태 동기화"라고 요청할 때 +- 사용자가 agent-task에는 없지만 실제 파일/git 기준으로는 완료된 것 같다고 지적할 때 - code-review PASS/archive 이후 runtime completion event 반영이 누락되었는지 확인하고 file-based fallback으로 복구해야 할 때 ## 입력 @@ -25,14 +28,16 @@ description: 현 마일스톤과 작업현황 동기화, 현재 마일스톤 작 - `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 문서의 `상태`, `구현 잠금`, `기능`, `완료 리뷰`를 확인한다. +- [ ] 대상 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만 설명하면 더 깊게 감사한다. ## 실행 절차 @@ -42,71 +47,87 @@ description: 현 마일스톤과 작업현황 동기화, 현재 마일스톤 작 - 대상이 없거나 둘 이상이면 Milestone을 수정하지 않고 target 불명확으로 보고한다. - 대상 경로가 `agent-roadmap/archive/**`이면 수정하지 않고 archive target 불가로 보고한다. -2. **Milestone Task와 gate 읽기** +2. **Milestone Task와 evidence scope 읽기** - Milestone `기능` 섹션의 Task id만 완료 후보로 본다. - Task id는 `- [ ] [item-id]` 또는 `- [x] [item-id]` 형식에서 추출한다. + - 각 Task의 설명과 `검증:` 문구를 기록한다. - `구현 잠금`의 상태, `결정 필요`, `SDD: 필요|불필요`, SDD 경로를 확인한다. - - `SDD: 필요`이면 SDD 파일 존재와 같은 디렉터리의 `USER_REVIEW.md` 존재 여부를 확인하고, SDD의 `Acceptance Scenarios`와 `Evidence Map`에서 대상 Task id 연결만 확인한다. + - `작업 컨텍스트`의 관련 경로, Milestone 범위, Task 설명의 코드/문서 키워드를 evidence scope로 삼는다. + - 관련 경로가 전혀 없으면 Task 설명에서 검색어를 만들되, 후보가 넓거나 모호하면 Task를 자동 완료하지 않고 scope 불명확으로 보고한다. 3. **complete.log 후보 수집** - 대상 Milestone slug를 ``로 두고 task group은 `m-`로 고정한다. - - active 후보를 찾는다: `agent-task/m-/**/complete.log` - - archive 후보를 찾는다: `agent-task/archive/*/*/m-/**/complete.log` - - `complete-log` 입력이 있으면 그 파일도 후보에 포함하되, `Roadmap Completion`의 Milestone 경로가 대상과 일치해야 반영한다. - - 이 단계는 필수다. active 후보가 없더라도 archive 후보를 반드시 확인한다. + - active 후보를 찾는다: `agent-task/m-/complete.log`, `agent-task/m-/**/complete.log` + - archive 후보를 찾는다: `agent-task/archive/*/*/m-/complete.log`, `agent-task/archive/*/*/m-/**/complete.log` + - `complete-log` 입력이 있으면 그 파일도 후보에 포함하되, `Roadmap Completion`의 Milestone 경로가 대상과 일치해야 직접 반영한다. - 일반 `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가 있는 항목만 인정한다. +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. **SDD Evidence Map 확인** - - `SDD: 필요`인 Milestone은 `Roadmap Completion`만으로 완료 처리하지 않는다. +5. **파일/git evidence 감사** + - 항상 대상 Milestone의 관련 파일과 git history를 최소 확인한다. + - `Roadmap Completion`으로 확인되지 않은 Task가 있거나 사용자가 실제 구현 완료를 지적하면 Task별 상세 감사를 수행한다. + - 관련 파일을 `rg --files <관련 경로>`와 Task 키워드 `rg`로 찾고, 필요한 파일 본문을 읽어 Task 설명과 직접 대응되는 구현/문서/테스트 변경을 확인한다. + - `git log --oneline -- <관련 경로>`와 필요한 경우 `git show --stat --name-only `로 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`의 verification 또는 evidence 경로로 설명 가능해야 한다. + - 연결된 scenario의 evidence가 확인한 complete log, 파일 변경, git commit, verification 중 하나로 설명 가능해야 한다. - SDD 파일이 없거나 `USER_REVIEW.md`가 남아 있거나 Evidence Map 연결이 비어 있으면 Task 체크 또는 `[검토중]` 전환을 하지 않고 차단 사유로 보고한다. -6. **Milestone 문서 반영** - - `mode=check-only`이면 파일을 수정하지 않고 반영 후보만 보고한다. +7. **Milestone 문서 반영** + - `mode=check-only`이면 어떤 파일도 수정하지 않고 반영 후보만 보고한다. - 검증된 완료 Task id만 `[x]`로 바꾼다. 이미 `[x]`인 항목은 유지한다. - 일부 Task만 완료되었고 미완료 Task가 남으면 Milestone 상태는 `[진행중]`으로 둔다. 단, 기존 상태가 `[검토중]`, `[보류]`, `[폐기]`이면 자동으로 낮추지 않고 차이만 보고한다. - 모든 기능 Task가 `[x]`이고 `구현 잠금`이 `해제`, `결정 필요: 없음`, SDD 사용자 리뷰 없음, SDD evidence 충족이면 Milestone 상태를 `[검토중]`으로 바꾼다. - - `[검토중]`으로 바꾸면 `완료 리뷰` 섹션을 만들거나 갱신하고, 반영한 `complete.log`, 완료 Task id, 남은 차단 항목 없음 또는 요약을 1~3줄로 남긴다. + - `[검토중]`으로 바꾸면 `완료 리뷰` 섹션을 만들거나 갱신하고, 사용한 `complete.log`, 파일/git evidence 요약, 완료 Task id, 남은 차단 항목 없음 또는 요약을 1~3줄로 남긴다. - 모든 Task가 `[x]`여도 구현 잠금이나 SDD gate가 남으면 `[검토중]`으로 바꾸지 않고 `완료 리뷰` 또는 `작업 컨텍스트`에 차단 항목을 남긴다. - 이 스킬은 Milestone을 `[완료]`로 바꾸거나 archive로 이동하지 않는다. -7. **Phase와 current 라벨 동기화** +8. **Phase와 current 라벨 동기화** + - `mode=check-only`이면 이 단계를 쓰기 없이 확인만 한다. - 대상 Phase `PHASE.md`의 `Milestone 흐름`에서 대상 Milestone 상태 라벨을 Milestone 본문 상태와 맞춘다. - `agent-roadmap/current.md`에 대상 Milestone이 있으면 상태 라벨을 Milestone 본문 상태와 맞춘다. - `current.md`에는 `[완료]` 또는 `[폐기]`를 남기지 않는다. 이 스킬은 `[검토중]`까지 유지할 수 있다. -8. **workspace lock 확인** +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 ":" both ""`를 실행한다. - 관련 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. **결과 보고** +10. **결과 보고** - 수정 파일과 변경 전/후 상태를 보고한다. - - 읽은 active/archive `complete.log` 후보 수와 반영한 Task id를 보고한다. - - 반영하지 않은 `complete.log`가 있으면 이유를 보고한다. - - SDD gate, 완료 리뷰, Workspace lock, 남은 미완료 Task를 보고한다. + - 읽은 active/archive `complete.log` 후보 수, 확인한 관련 파일/git 범위, 반영한 Task id를 보고한다. + - 반영하지 않은 `complete.log`나 Task가 있으면 이유를 보고한다. + - SDD gate, 완료 리뷰, Workspace lock, 남은 미완료 Task, 검토 필요 Task를 보고한다. ## 실행 결과 검증 - [ ] 대상 Milestone이 활성 경로에서 정확히 하나로 확정되었는가 -- [ ] 같은 `m-`의 active `complete.log`와 archive `complete.log` 후보를 모두 확인했는가 +- [ ] 같은 `m-`의 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` 동기화를 결과에 반영했는가 @@ -128,11 +149,14 @@ description: 현 마일스톤과 작업현황 동기화, 현재 마일스톤 작 - 상태: <변경 없음 | 이전 -> 이후> - 완료 Task: - 미완료 Task: +- 검토 필요 Task: - complete.log 후보: active 개, archive 개 - 반영한 complete.log: - - 반영 제외 complete.log: - - <사유> +- 파일/git evidence: + - - <파일/커밋/검증 요약> - SDD gate: <불필요 | 충족 | 차단: 사유> - 완료 리뷰: <변경 없음 | 검토중 갱신 | 잠금 차단 기록> - Workspace 잠금: <관련 lock 없음 | 상태 요약 | 미확인 사유> @@ -145,9 +169,11 @@ description: 현 마일스톤과 작업현황 동기화, 현재 마일스톤 작 ## 금지 사항 - active `agent-task/m-`만 확인하고 archive `complete.log` 확인 없이 no-op 처리하지 않는다. +- `complete.log` 부재만으로 Task 미완료를 단정하지 않는다. - 대상 slug와 다른 `agent-task/archive/**` 문서를 일반 탐색하지 않는다. -- `complete.log`의 `Roadmap Completion` 없이 파일명, 커밋 메시지, plan/review log만으로 Task를 `[x]` 처리하지 않는다. -- Task id를 의미 유사도, 순서, 파일명으로 추정하지 않는다. +- 커밋 메시지, 파일명, plan/review log만으로 Task를 `[x]` 처리하지 않는다. +- `complete.log`의 Task id를 의미 유사도, 순서, 파일명으로 보정하지 않는다. +- 파일/git evidence가 있어도 Task 설명과 직접 대응되지 않으면 완료 처리하지 않는다. - SDD gate가 필요한데 Evidence Map 연결을 확인하지 않고 `[검토중]`으로 전환하지 않는다. - 구현 잠금이 남아 있거나 `결정 필요`가 있으면 `[검토중]`, `[완료]`, archive를 수행하지 않는다. - 이 스킬에서 새 Milestone/Epic/Task를 만들거나 기존 id를 바꾸지 않는다.