agent-ops 공통 파일과 프로젝트 로드맵 상태를 분리해 sync 대상과 로드맵 문서 관리를 독립적으로 유지한다.

2026-05-27 11:18:34 +09:00

6.2 KiB

Raw Blame History

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을 읽을 수 있는지 확인한다.

실행 절차

입력 확정
- 사용자 요청에서 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으로 보고한다.
판별 실행
- 확인 대상 lock id마다 agent-ops/bin/roadmap-dependency-checker.sh "<lock-id>" "<locks-file>"를 실행한다.
- locked 방향의 결과는 대상 Milestone의 잠금 해제 조건 충족 여부다.
- rely-on 방향의 결과는 대상 Milestone이 완료될 때 영향을 받는 downstream lock의 현재 충족 여부다.
결과 해석
- 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와 설정 오류를 같은 상태로 보고하지 않는다.

6.2 KiB Raw Blame History