iop/agent-ops/rules/common/rules-roadmap.md

# 로드맵 규칙

`agent-roadmap/`이 있는 프로젝트에서 로드맵 작업에만 적용한다.

- 최우선 방향은 **검증 게이트 최소화**다. roadmap은 새 차단 조건을 만드는 곳이 아니며, 기존 문서의 중복 잠금·승인·정합성·evidence 게이트도 제거·병합한다.

## 목적과 구조

- roadmap은 장기 목표와 기능 범위를 기록한다. 구현 절차와 검증 로그는 roadmap에 복제하지 않는다.
- 최상위는 `agent-roadmap/ROADMAP.md`, 전역 실행 순서는 `agent-roadmap/priority-queue.md`다.
- 활성 Phase는 `agent-roadmap/phase/<phase-slug>/PHASE.md`, 활성 Milestone은 그 아래 `milestones/<milestone-slug>.md`에 둔다.
- `agent-roadmap/current.md`는 브랜치별 활성 후보 창이며 현재 작업 하나나 완료 상태의 원본이 아니다.
- SDD는 필요한 설계 참고 문서로 `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md`에 둘 수 있다. SDD 자체가 구현 승인 게이트는 아니다.
- 완료·폐기 문서는 기존 archive scaffold로 이동한다.

## 로딩

- 일반 구현 작업에서는 roadmap을 읽지 않는다.
- 로드맵 작업에서는 `current.md`와 관련 Phase/Milestone만 먼저 읽는다.
- `ROADMAP.md`는 전체 Phase 구조를 바꿀 때, `priority-queue.md`는 실행 순서나 명시적 차단 관계를 바꿀 때만 읽는다.
- archive는 사용자가 과거 내용 확인·복원·비교를 요청했거나 활성 문서가 정확한 archive evidence를 가리킬 때만 필요한 파일 하나를 읽는다.

## 상태

- 상태는 `[스케치]`, `[계획]`, `[진행중]`, `[검토중]`, `[완료]`, `[보류]`, `[폐기]`를 사용한다.
- `[스케치]`는 아직 구현 단위가 정리되지 않은 후보이고 `[계획]`은 구현 가능한 범위가 정리된 상태다.
- `[검토중]`은 필요할 때만 사용하는 선택적 상태다. 기능과 필요한 검증이 충족되면 `[완료]`로 바로 전환할 수 있다.
- 상태만으로 코드 작업을 자동 차단하지 않는다. 다만 `[스케치]`에서 구현에 필요한 제품 결정이 실제로 빠져 있다면 해당 결정이 필요한 부분만 보류한다.
- 기존 `구현 잠금`, SDD 승인, Evidence Map, complete.log 형식은 호환 정보로 읽을 수 있지만 새 작업의 선행 게이트로 사용하지 않는다.

## 결정 사항

- 에이전트가 기존 구조와 요청 범위로 합리적으로 정할 수 있는 세부는 구현 가정으로 처리한다.
- 제품 방향·권한·비용·데이터 보존처럼 사용자가 결정해야 하고 현재 구현에 직접 필요한 항목만 Milestone의 `결정 사항`에 남긴다.
- 미정 결정은 그 결정에 의존하는 작업만 보류한다. 다른 Epic, Task, Milestone까지 연쇄 잠금하지 않는다.

## 실행 순서와 프로젝트 간 의존성

- 같은 prefix의 작은 index는 기본 순서이며 서로 다른 prefix는 기본적으로 병렬이다.
- `선행 차단`과 `.agent-roadmap-sync/locks.yaml`은 사용자가 실제 선행 의존성을 명시한 경우에만 만든다.
- 관련성, 권장 순서, SDD/spec/plan/review 미비, 테스트 미실행은 차단 관계가 아니다.
- 외부 의존 상태는 대상 Milestone 상태로 동기화할 수 있지만, 문서 정합성만을 이유로 새 잠금을 만들지 않는다.

## SDD

- SDD는 API·schema·상태 전이·권한·비가역 외부 쓰기처럼 구현 전에 합의가 유용한 큰 변경에 선택적으로 사용한다.
- 기존 계약과 범위가 명확하면 SDD 없이 구현할 수 있다.
- SDD의 상태, 사용자 리뷰, Acceptance Scenario, Evidence Map은 설계와 검증을 돕는 정보이며 plan·구현·완료의 자동 선행 조건이 아니다.
- 사용자 결정이 필요한 경우 질문과 결정 결과만 남긴다. 별도 승인 체크박스나 SDD 잠금 해제 의식을 만들지 않는다.

## Epic과 Task

- Milestone의 실행 체크리스트는 `기능` 섹션에 둔다.
- Epic은 `### Epic: [epic-id] <이름>`, Task는 `- [ ] [item-id] 설명` 형식을 사용한다.
- Task는 기능이나 산출물 단위로 작성한다. 구현 세부나 테스트만을 별도 하위 Task로 만들지 않는다.
- 검증이 실제로 필요한 Task에만 같은 줄의 `검증:`으로 가장 작은 확인 방법을 적는다.
- 기능이 구현됐고 필요한 검증이 확인되면 evidence 형식과 관계없이 `[x]`로 바꿀 수 있다.

## Plan, review, 완료 반영

- plan과 code review는 사용자가 요청했거나 변경 규모상 유용할 때만 사용한다. 로드맵 상태, SDD, preflight가 자동으로 plan을 요구하지 않는다.
- 시작 전 전체 정합성 preflight는 사용자가 요청한 경우에만 read-only로 수행한다.
- `complete.log`의 `milestone-task`와 `Roadmap Completion`은 자동 반영을 위한 선택적 힌트다. 정확한 Milestone과 Task가 확인되면 코드·테스트·사용자 설명 같은 다른 근거로도 완료를 반영할 수 있다.
- 모든 Task가 완료되면 별도 완료 리뷰 단계를 강제하지 않고 Milestone을 `[완료]`로 전환할 수 있다.
- 미실행 환경 검증은 남은 위험으로 기록하되, 보안·데이터 손상·비가역 외부 변경을 확인하는 필수 검증이 아닌 한 완료를 자동 차단하지 않는다.

## 링크와 갱신

- 사용자-facing 문서 포인터는 Markdown 링크를 사용한다. machine-readable identity는 raw path를 유지할 수 있다.
- target 없는 추가 요청은 같은 목표의 기존 Phase → Milestone → Epic → Task를 찾아 가장 작은 충분한 단위로 갱신한다.
- 중복 항목을 만들지 않고, 요청 범위를 넘어 기존 id나 실행 순서를 바꾸지 않는다.
- 갱신 후에는 수정한 링크가 존재하는지와 `git diff --check`만 확인한다. 전체 roadmap 정합성 검사를 자동 실행하지 않는다.

## 아카이브

- `[완료]` 또는 `[폐기]` Milestone만 archive한다.
- 활성 Phase 문서에는 archive 링크와 짧은 요약만 남기고, `priority-queue.md`와 `current.md`에서는 제거한다.
- archive 문서는 과거 스냅샷으로 보존하고 최신 형식으로 재작성하지 않는다.