91 lines
6.3 KiB
Markdown
91 lines
6.3 KiB
Markdown
---
|
|
name: check-roadmap-dependency
|
|
version: 1.2.0
|
|
description: 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` 경로를 보고하고 멈춘다.
|
|
|
|
## 출력 형식
|
|
|
|
```markdown
|
|
## 의존성 판별 결과
|
|
|
|
- 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`와 설정 오류를 같은 상태로 보고하지 않는다.
|