appsok/agent-ops/skills/common/check-roadmap-dependency/SKILL.md

name	version	description
check-roadmap-dependency	1.2.0	roadmap dependency lock 상태를 확인한다. 사용자가 roadmap-dependency-checker.sh, locks.yaml, 외부 의존 잠금 충족 여부, unlock-ready 판별, 프로젝트 간 잠금 해제 조건 확인을 요청할 때 사용하며, 현재 Milestone이 locked 쪽인지 rely-on.target 쪽인지 양방향으로 판별한다.

check-roadmap-dependency

목적

.agent-roadmap-sync/locks.yaml에서 특정 lock id의 locked, rely-on.target, rely-on.status가 유효한지 확인하고, 모든 rely-on.status가 enable인지 판별한다. lock id가 없으면 현재 Milestone identity가 locked에 있는지, rely-on.target에 있는지 모두 찾아 양방향으로 보고한다. Milestone identity 역검색과 개별 lock 판별은 agent-ops/bin/roadmap-dependency-checker.sh에 맡기고, 스킬은 입력 확정, 실행, 결과 해석만 담당한다.

언제 호출할지

• 사용자가 특정 roadmap lock id의 의존 조건 충족 여부를 확인할 때
• runtime에서 unlock-ready 트리거 전 locks.yaml 판별 절차를 확인할 때
• .agent-roadmap-sync/locks.yaml의 rely-on.status 기반 true/false 확인을 요청할 때
• 사용자가 현재 Milestone이 다른 Milestone을 잠그는지 또는 다른 Milestone에 의해 잠겼는지 확인할 때

입력

• lock-id: 확인할 lock entry id. 예: oto:oto-agent-registration. 명시되면 이 id만 판별한다 (선택)
• target-milestone: 확인할 Milestone path 또는 <project>:agent-roadmap/phase/.../milestones/<slug>.md. 없으면 현재 프로젝트 로컬 current.md의 활성 Milestone 단일 후보를 사용한다 (선택)
• direction: locked / rely-on / both. 기본값은 both다. locked는 대상 Milestone이 잠긴 entry만, rely-on은 대상 Milestone을 선행 조건으로 삼는 entry만 확인한다 (선택)
• locks-file: 기본값은 프로젝트 상위 .agent-roadmap-sync/locks.yaml이며, 다른 파일을 검사할 때만 지정한다 (선택)

먼저 확인할 것

• agent-ops/bin/roadmap-dependency-checker.sh가 있는지 확인한다.
• lock-id가 명시되었거나 target-milestone 또는 현재 프로젝트 로컬 current.md의 활성 Milestone 하나로 Milestone identity를 추론 가능한지 확인한다.
• 기본 경로 또는 지정된 locks-file을 읽을 수 있는지 확인한다.

실행 절차

1. 입력 확정

   • 사용자 요청에서 lock-id를 추출한다.
   • locks-file이 명시되지 않았으면 프로젝트 상위 .agent-roadmap-sync/locks.yaml을 사용한다.
   • locks-file이 없거나 읽을 수 없으면 결과를 error로 보고한다. 이를 미충족 의존성으로 해석하지 않는다.
   • lock-id가 있으면 그 id만 판별한다.
   • lock-id가 없으면 target-milestone 또는 현재 프로젝트 로컬 agent-roadmap/current.md의 활성 Milestone 단일 후보로 Milestone identity를 만든다.
   • Milestone identity는 <project>:agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md 형식이다.
   • target-milestone이 agent-roadmap/... 상대 경로이면 현재 프로젝트명을 prefix로 붙인다.
   • target-milestone이 workspace 하위 절대/상대 경로이면 workspace 바로 아래 디렉터리명을 project로 삼고, 그 뒤 agent-roadmap/... 경로를 붙인다.
   • target-milestone이 archive 경로이면 일반 의존 판별 후보로 쓰지 말고 활성 Milestone 대상이 모호하다고 보고한다.
   • 활성 Milestone 후보가 없거나 둘 이상이면 추정하지 말고 lock id 또는 Milestone 대상이 모호하다고 보고한다.
   • lock-id가 없으면 agent-ops/bin/roadmap-dependency-checker.sh --find-milestone "<identity>" "<direction>" "<locks-file>"로 Milestone identity와 일치하는 entry를 찾는다.
   • find 출력의 locked:<id>는 locked entries로, rely-on:<id>는 rely-on entries로 분류한다.
   • find 출력이 none이면 결과를 error가 아니라 no-lock으로 보고한다.

2. 판별 실행

   • 확인 대상 lock id마다 agent-ops/bin/roadmap-dependency-checker.sh "<lock-id>" "<locks-file>"를 실행한다.
   • locked 방향의 결과는 대상 Milestone의 잠금 해제 조건 충족 여부다.
   • rely-on 방향의 결과는 대상 Milestone이 완료될 때 영향을 받는 downstream lock의 현재 충족 여부다.

3. 결과 해석

   • stdout true와 exit code 0은 모든 의존 조건 충족으로 보고한다.
   • stdout false와 exit code 1은 아직 충족되지 않은 의존 조건이 있음을 보고한다.
   • exit code 2는 설정 오류, 입력 오류, 필수 필드 누락, 파싱 오류로 보고한다.
   • rely-on 방향에서 대상 Milestone이 [검토중] 또는 [완료]인데 status가 disable이면 update-roadmap 동기화가 필요한 stale lock으로 보고한다. 이 스킬은 status를 바꾸지 않는다.

실행 결과 검증

• 각 checker 실행의 stdout이 true 또는 false 하나로만 출력되었는가
• exit code 0, 1, 2 의미를 구분해 보고했는가
• exit code 2를 unlock 대기 상태로 해석하지 않았는가
• lock id가 없을 때 대상 Milestone을 locked와 rely-on.target 양쪽에서 찾았는가
• locks.yaml이 없는 경우 false가 아니라 error로 보고했는가
• 이 스킬이 locks.yaml이나 roadmap 문서를 수정하지 않았는가
• 검증 실패 시: 오류 메시지와 사용한 lock-id, locks-file 경로를 보고하고 멈춘다.

출력 형식

## 의존성 판별 결과

- target-milestone: `<identity | 해당 없음>`
- direction: `<locked | rely-on | both>`
- locks-file: `<locks-file>`
- 결과: `<true | false | error | no-lock>`
- locked entries: `<lock-id=result, ... | 없음>`
- rely-on entries: `<lock-id=result, ... | 없음>`
- 의미: <모든 의존 조건 충족 | 미충족 의존 조건 있음 | 설정/입력/필수 필드/파싱 오류 | 대상 Milestone 관련 lock 없음>

금지 사항

• locks.yaml의 status를 변경하지 않는다.
• roadmap Milestone의 구현 잠금 상태를 변경하지 않는다.
• false와 설정 오류를 같은 상태로 보고하지 않는다.