nomadcode/agent-ops/skills/common/update-roadmap/SKILL.md

---
name: update-roadmap
version: 1.7.1
description: 기존 전체 목표, Phase, 구현 구체화 잠금이 있는 순번 없는 Milestone 기반 한국어 로드맵을 갱신하고 신규 작업의 삽입 위치와 단위를 사용자 지정 또는 자동 판단으로 배치하며 current.md의 활성 Milestone 창을 동기화하는 공통 스킬
---

# 로드맵 업데이트

## 목적

기존 `agent-ops/roadmap/` 구조를 현재 프로젝트 방향과 진행 상태에 맞게 한국어로 갱신한다.
로드맵 전체를 매 작업마다 읽지 않도록 유지하면서, `current.md`의 활성 Milestone 창이 실제 작업 후보 목록으로 동작하게 한다.
Milestone은 구현 전 방향성, 범위, 선행 조건, 브레이킹 포인트를 잡는 게이트 문서로 유지한다.
구현 구체화가 필요한 Milestone은 `구현 잠금` 상태를 `잠금`으로 두고, `구현 잠금` 섹션이 없는 Milestone도 구체화 상태 불명으로 보아 사용자가 단순히 "진행"을 요청해도 코드 구현이나 `agent-task` 구현 계획으로 내려가지 않게 한다.

## 언제 호출할지

- 사용자가 "로드맵 업데이트", "마일스톤 갱신", "phase 변경", "현재 활성 마일스톤 바꿔줘"라고 요청할 때
- 사용자가 "로드맵 한국어 전환", "로드맵 번역", "영문 로드맵을 한국어로 바꿔줘"라고 요청할 때
- Milestone 완료, 보류, 폐기, 신규 추가가 필요할 때
- 특정 기능이나 작업을 새 Milestone, 기존 Milestone의 태스크, 기존 태스크 하위 항목 중 적절한 위치에 추가해야 할 때
- 활성 Milestone 창에 포함할 Milestone 목록이 달라졌을 때
- 기본 목표, Phase, Milestone의 목표, 범위, 필수 기능, 완료 기준이 달라졌을 때
- `ROADMAP.md` 또는 `current.md` 형식이 템플릿과 달라 표준화해야 할 때
- Milestone 문서 형식이 제각각이라 템플릿 기준으로 표준화해야 할 때
- 실제 구현 상태와 로드맵 파일이 어긋난 것 같아 동기화가 필요할 때
- 사용자가 Milestone의 구현 구체화, 구현 잠금 해제, 또는 잠금 상태 점검을 요청할 때

## 입력

- `mode`: `status` / `milestone` / `phase` / `replan` / `sync` / `concretize` 중 하나 (선택, 요청에서 추론 가능)
- `target-milestone`: 갱신할 Milestone 이름, slug, 파일 경로 (선택)
- `active-milestones`: 활성 Milestone 창에 둘 Milestone 이름, slug, 파일 경로 목록 (선택)
- `new-feature`: 추가할 기능, 작업, 또는 새 Milestone 설명 (선택)
- `placement`: 새 작업 배치 위치. 예: `<anchor-milestone> 앞`, `<anchor-milestone> 뒤`, `<milestone-name> 안`, `<phase-name> 안`, `<anchor-task> 앞`, `<anchor-task> 아래`, `auto` (선택, 없으면 자동 판단)
- `placement-unit`: 삽입 단위. `milestone` / `task` / `subtask` / `auto` 중 하나 (선택, 없으면 작업 성격으로 판단)
- `lock-state`: Milestone 구현 잠금 상태. `잠금` / `해제` 중 하나 (선택, 없으면 기존 상태 유지 또는 신규 Milestone은 잠금)
- `concretization-evidence`: 구현 잠금 해제 근거가 되는 사용자 승인, 설계 문서, API/프로토콜 결정, 검증 기준 (선택)
- `change-summary`: 반영할 방향 변경 또는 진행 상황 요약 (선택)
- `evidence`: 완료 판단에 사용할 파일, PR, 테스트, 커밋, 사용자 설명 (선택)

## 모드

| mode | 사용 상황 |
|------|-----------|
| `status` | 태스크 체크박스, Milestone 상태, 완료 기준만 갱신 |
| `milestone` | Milestone 목표, 범위, 태스크 체크리스트, 완료 기준 수정 |
| `phase` | Phase 설명 또는 활성 Milestone 창 전환 |
| `replan` | 전체 Phase/Milestone 흐름 재구성 |
| `sync` | 실제 프로젝트 상태와 로드맵 불일치 점검 후 보정 |
| `concretize` | 잠긴 Milestone을 구현 가능한 수준으로 구체화하고 잠금 해제 여부를 결정 |

## 작성 언어

- `agent-ops/roadmap/` 하위 로드맵 문서는 사람이 함께 검토하고 수정하는 협업 문서이므로 기본 작성 언어를 한국어로 한다.
- 전체 구성, 섹션 제목, 설명 문장, 기능 설명, 완료 기준, TODO, 가정은 한국어 문장으로 작성한다.
- Goal, Phase, Milestone, Scope, API, CLI처럼 개발자에게 자연스러운 일반 용어, 파일명, 경로, slug, 코드 식별자는 영어 또는 숫자를 유지할 수 있다.
- 상태 값은 `계획`, `진행 중`, `완료`, `보류`, `폐기` 중 하나만 사용한다.
- 기존 영문 상태 값은 `Planned` -> `계획`, `Active` -> `진행 중`, `Done` -> `완료`, `Paused` -> `보류`, `Dropped` -> `폐기`로 맞춘다.
- 기존 영문 섹션명이 갱신 범위에 포함되면 아래 한국어 표준 섹션명으로 정리한다.
  - `Goal` -> `목표`
  - `Phase` -> `단계`
  - `Status` -> `상태`
  - `Implementation Lock` / `구현 구체화` -> `구현 잠금`
  - `Scope` -> `범위`
  - `Required Features` -> `필수 기능`
  - `Success Criteria` -> `완료 기준`
  - `Non-Goals` -> `범위 제외`
  - `Context for Work` -> `작업 컨텍스트`

## 로드맵 문서 템플릿

- `agent-ops/roadmap/ROADMAP.md`는 `agent-ops/skills/common/_templates/roadmap-template.md` 형식을 기준으로 생성·갱신한다.
- `agent-ops/roadmap/current.md`는 `agent-ops/skills/common/_templates/roadmap-current-template.md` 형식을 기준으로 생성·갱신한다.
- `ROADMAP.md` 표준 섹션은 `전체 목표`, `Phase 흐름`, `Milestone 목록`, `로딩 정책`이다.
- `ROADMAP.md`에는 Phase/Milestone 흐름과 문서 링크만 두고, 상세 작업 체크리스트는 Milestone 문서에 둔다.
- `current.md` 표준 섹션은 `활성 Milestone`, `선택 규칙`이다.
- `current.md`는 활성 Milestone 후보 목록이며, 개인별 현재 작업 위치나 완료 상태의 진실로 쓰지 않는다.
- 갱신 범위에 포함된 `ROADMAP.md`나 `current.md`가 템플릿과 다르면, 프로젝트 로드맵 정보는 보존하면서 표준 섹션 순서로 재배치한다.
- `current.md`에 남아 있는 개인별 또는 세션별 작업 위치/완료 상태는 공유 로드맵 정보로 이관하지 말고 결과 보고의 확인 필요 항목에 남긴다.

## Milestone 문서 템플릿

- Milestone 문서는 `agent-ops/skills/common/_templates/roadmap-milestone-template.md` 형식을 기준으로 생성·갱신한다.
- 표준 섹션 순서는 `목표`, `단계`, `상태`, `구현 잠금`, `범위`, `필수 기능`, `완료 기준`, `범위 제외`, `작업 컨텍스트`다.
- 갱신 범위에 포함된 Milestone 문서가 제각각 형식이면, 내용을 삭제하지 말고 표준 섹션 순서로 재배치한다.
- 기존 Milestone에 `구현 잠금` 섹션이 없으면 추가한다. 구현 구체화가 명시되지 않았거나 구현 가능한 수준인지 불확실하면 `잠금`으로 둔다.
- `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 이 Milestone은 구현 계획이 아니라 범위/방향성 게이트다. 코드 구현, `agent-task` 구현 계획, 세부 API/파일 구조 확정을 시작하지 않는다.
- `구현 잠금`을 `해제`하려면 사용자가 Milestone 구체화 업데이트 또는 잠금 해제를 명시해야 하며, 책임 경계, API/프로토콜, 검증 기준, 선행 조건이 문서에 반영되어야 한다.
- `필수 기능`은 구현 파일/함수 단위 작업 목록이 아니라 Milestone에서 달성해야 할 capability 또는 산출물 체크리스트로 유지한다.
- `완료 기준`은 검증 가능한 조건의 체크리스트로 유지한다.
- 일반 불릿이나 설명 문장에 숨어 있는 capability/산출물은 성격을 판단해 `필수 기능` 체크리스트 또는 기존 항목의 하위 체크리스트로 옮긴다.
- `범위`, `범위 제외`, `작업 컨텍스트`는 설명 목록으로 유지하고, 실행해야 할 작업을 이 섹션에 숨기지 않는다.

## 순서 정책

- Phase와 Milestone 이름에 `1`, `2`, `M01`, `P1` 같은 순번을 붙이지 않는다.
- 진행 순서는 `ROADMAP.md`에 적힌 위에서 아래 순서로만 해석한다.
- 새 Milestone 파일은 순번 없이 `agent-ops/roadmap/milestones/<milestone-slug>.md`로 만든다.
- 중간에 Phase나 Milestone을 끼워 넣을 수 있도록 기존 항목의 이름과 파일명을 불필요하게 바꾸지 않는다.
- 기존 프로젝트에 이미 순번 파일명이 있으면 대규모 rename을 하지 말고, 갱신 범위에 포함된 새 항목부터 순번 없는 형식을 적용한다.
- 새 작업은 습관적으로 새 Milestone으로 만들거나 목록 맨 앞/뒤에 붙이지 않는다.
- 사용자가 특정 Milestone 앞/뒤, 특정 Phase 안, 필수 기능 목록 내 위치, 또는 기존 태스크 앞/뒤/아래를 지정하면 목표와 범위 제외 항목에 충돌하지 않는 한 그 위치를 우선한다.
- 사용자가 위치를 지정하지 않으면 `ROADMAP.md`의 Phase 흐름, 기존 Milestone 목표, 기존 필수 기능/태스크, 선후 의존성, 활성 Milestone 창, 완료 기준을 보고 가장 자연스러운 위치를 자동으로 판단한다.
- 자동 배치한 경우 결과 보고에 선택한 삽입 단위, Phase/Milestone/태스크 위치, 판단 근거를 짧게 남긴다.

## 삽입 단위 정책

신규 추가 요청은 먼저 "어디에 둘지"와 "어떤 단위로 둘지"를 분리해서 판단한다. 여기서 태스크는 Milestone 문서 `필수 기능` 섹션의 체크리스트 항목 또는 기존 체크리스트 항목을 뜻한다.

| 삽입 단위 | 사용 기준 |
|-----------|-----------|
| 새 Milestone | 독립적인 목표와 완료 기준이 필요하거나, 여러 기능을 묶는 산출물이고, 별도 상태 추적이 필요하며, Phase 흐름이나 선후 의존성에 의미 있는 경계를 만든다 |
| 기존 Milestone의 태스크 | 기존 Milestone의 목표와 범위 안에 들어가며, 하나의 완료 가능한 capability/산출물이지만 별도 Milestone 상태 추적까지는 필요하지 않다 |
| 기존 태스크의 하위 작업 | 잠금 해제된 Milestone에서 기존 태스크의 구현 세부, 보완, 테스트, 문서화, 예외 처리, 완료 기준 구체화처럼 부모 태스크를 완성하기 위한 세부 항목이다 |
| 작업 컨텍스트/TODO | 요구가 아직 불확실하거나 조사/확인이 먼저 필요해 필수 기능으로 확정하기 어렵다 |

- 신규 Milestone은 기본적으로 `구현 잠금: 잠금`으로 생성한다. 사용자가 구현 구체화와 잠금 해제를 명시한 경우에만 `해제`를 검토한다.
- 잠긴 Milestone 안에 새 작업을 추가할 때는 구현 태스크가 아니라 capability, 결정 안건, 선행 조건, 완료 기준 후보로 작성한다.
- `구현 잠금`이 없거나 잠긴 Milestone에 대해 사용자가 "진행", "구현", "계획 작성"을 요청하면 로드맵을 우회하지 않는다. 먼저 Milestone 문서 구체화 업데이트와 잠금 해제를 요청한다.
- 위치 지정이 있으면 anchor의 레벨을 먼저 확인한다. `<anchor-task> 아래`처럼 하위 위치가 명시되면 기존 태스크 하위 항목으로 넣고, `<anchor-task> 앞/뒤`면 같은 목록 레벨의 형제 항목으로 넣는다.
- 위치는 지정됐지만 단위가 명시되지 않은 경우, anchor 레벨과 작업 성격을 함께 보고 새 Milestone, 태스크, 하위 작업 중 하나를 선택한다.
- 위치 지정이 `<phase-name> 안` 또는 `<milestone-name> 안`처럼 컨테이너만 지정된 경우, 잠금 해제된 Milestone에서 작업 내용이 기존 태스크의 세부 구현이면 해당 컨테이너 안에서 가장 관련 있는 태스크 아래에 넣을 수 있다. 이 경우 결과 보고에 "위치는 지정된 컨테이너를 따랐고, 단위는 하위 작업으로 판단"처럼 남긴다.
- 위치 지정이 `<anchor-milestone> 앞/뒤` 또는 `<anchor-task> 앞/뒤`처럼 순서 anchor인 경우, 같은 레벨의 앞/뒤 배치를 유지한다. 작업 성격상 다른 레벨이 더 적절해 보여도 조용히 재배치하지 말고 사용자에게 확인한다.
- `placement-unit`을 사용자가 명시한 경우 그 단위를 우선한다. 다만 지정 단위가 anchor 레벨, Milestone 목표, 범위 제외, 명백한 선후 의존성과 충돌하면 수정 전에 충돌 내용을 알리고 방향을 확인한다.
- 작업이 둘 이상의 Milestone에 걸치면 바로 하나의 기존 태스크에 넣지 않는다. 공통 기반 작업이면 새 Milestone을 고려하고, 단순 연계 작업이면 각 Milestone에 나눌지 사용자에게 확인한다.
- 기존 태스크와 중복되거나 기존 태스크의 완료 기준으로 자연스럽게 흡수되는 요청은 새 Milestone이나 새 형제 태스크로 만들지 말고 기존 태스크를 보완한다.

### current.md 형식

`agent-ops/roadmap/current.md`는 `agent-ops/skills/common/_templates/roadmap-current-template.md` 형식을 유지한다.

`current.md`는 개인별 작업 위치나 완료 상태의 진실이 아니다. 현재 열려 있는 Milestone 후보 목록이며, 실제 현 작업 지점과 남은 작업은 `analyze-roadmap-position` 스킬이 코드와 git 상태를 함께 읽고 분석한다.

## 먼저 확인할 것

- [ ] `agent-ops/roadmap/ROADMAP.md` 존재 여부 확인
- [ ] `agent-ops/roadmap/current.md` 존재 여부 확인
- [ ] `current.md`가 가리키는 활성 Milestone 문서 존재 여부 확인
- [ ] `current.md`가 정해진 한국어 형식을 유지하는지 확인
- [ ] `agent-ops/skills/common/_templates/roadmap-template.md`를 읽어 최신 ROADMAP 형식 확인
- [ ] `agent-ops/skills/common/_templates/roadmap-current-template.md`를 읽어 최신 current.md 형식 확인
- [ ] `agent-ops/skills/common/_templates/roadmap-milestone-template.md`를 읽어 최신 Milestone 형식 확인
- [ ] 로드맵 파일이 없으면 `create-roadmap` 스킬 사용을 안내하고 중단
- [ ] 완료 상태로 바꾸는 경우 사용자의 명시 또는 확인 가능한 evidence가 있는지 확인
- [ ] 대상 Milestone의 `구현 잠금` 상태를 확인. 섹션이 없거나 잠금 상태에서 구현/계획을 요청받은 경우 Milestone 구체화 업데이트가 먼저 필요함을 보고하고 구현으로 진행하지 않는다.
- [ ] 잠금 해제를 요청받은 경우 책임 경계, API/프로토콜, 검증 기준, 선행 조건이 Milestone 문서에 반영될 수 있는지 확인

## 실행 절차

1. **갱신 범위 결정**
   - 요청에서 mode, target Milestone, new feature, placement, placement-unit을 추론한다.
   - 요청이 Milestone 구체화 또는 잠금 해제이면 `concretize`로 본다.
   - 로드맵 언어 전환, ROADMAP/current 형식 표준화, 또는 Milestone 형식 표준화 요청이면 `sync`로 보고 `ROADMAP.md`, `current.md`, 전체 Milestone 문서를 갱신 범위에 포함할 수 있다.
   - `status` 갱신이면 `current.md`와 대상 Milestone 문서를 우선 읽는다.
   - 요청이 활성 Milestone에 없으면 `ROADMAP.md`의 Milestone 목록을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다.
   - Phase 전환, Milestone 추가/삭제, 순서 변경, 전체 재계획이면 `ROADMAP.md`도 읽는다.
   - 신규 작업 추가이고 placement가 명시되어 있으면 anchor의 종류(Phase, Milestone, 태스크), 앞/뒤/안/아래 방향, 대상 Phase 또는 Milestone을 함께 기록한다.
   - 불필요하게 모든 Milestone 문서를 읽지 않는다.

2. **현재 로드맵 상태 파악**
   - `ROADMAP.md`의 전체 목표, Phase 흐름, Milestone 목록을 확인한다.
   - `current.md`의 활성 Milestone 창과 선택 규칙을 확인한다.
   - `ROADMAP.md`와 `current.md`가 표준 템플릿 섹션 순서와 형식을 따르는지 확인한다.
   - 대상 또는 후보 Milestone 문서의 목표, 범위, 필수 기능, 완료 기준, 범위 제외 항목을 확인한다.
   - 대상 또는 후보 Milestone 문서의 `구현 잠금` 상태와 해제 조건을 확인한다.
   - `구현 잠금`이 없거나 잠긴 Milestone에 대한 구현, 구현 계획, 세부 API/파일 구조 확정 요청이면 수정으로 진행하지 않고 잠금 상태와 필요한 구체화 업데이트를 사용자에게 보고한다.
   - 대상 Milestone 문서가 표준 템플릿 섹션 순서와 체크리스트 형식을 따르는지 확인한다.
   - 신규 작업과 이름, 산출물, 코드 경계, 완료 기준이 겹치는 기존 태스크가 있는지 확인한다.

3. **신규 작업 삽입 단위와 위치 판단**
   - 추가 요청이면 placement, placement-unit, 작업 성격을 함께 보고 새 Milestone, 기존 Milestone의 태스크, 기존 태스크의 하위 작업, 작업 컨텍스트/TODO 중 어느 단위가 맞는지 결정한다.
   - 사용자가 위치를 지정한 경우 `ROADMAP.md`에서 anchor Phase/Milestone을 확인하고, 필요한 경우 대상 Milestone 문서의 태스크 anchor까지 확인해 충돌 여부를 확인한다.
   - 지정된 anchor가 없거나 여러 항목과 매칭되어 모호하면 임의 배치하지 말고 사용자에게 짧게 확인한다.
   - 사용자가 순서 anchor를 지정했으면 같은 레벨의 앞/뒤 배치를 유지하고, 컨테이너 anchor를 지정했으면 컨테이너 안에서 작업 성격에 맞는 하위 단위를 선택한다.
   - 위치 지정이 없으면 `ROADMAP.md`의 위아래 흐름, 현재 활성 Milestone, 선행되어야 할 작업, 후속 작업이 기대하는 산출물, 관련 코드/문서 경계, 기존 태스크와의 포함 관계를 기준으로 자동 배치한다.
   - 자동 배치는 "가장 빨리 할 수 있는 곳"이 아니라 "의존성과 완료 기준이 자연스럽게 이어지는 곳"을 우선한다.
   - 대상 Milestone이 잠겨 있으면 새 항목은 구현 작업이 아니라 capability/산출물/결정 안건/선행 조건/완료 기준 후보로만 배치한다.
   - 잠금 해제된 Milestone에서 기존 태스크를 완성하는 세부 구현이면 하위 작업으로 넣고, 기존 태스크와 같은 수준의 독립 완료 항목이면 같은 Milestone의 태스크로 넣는다.
   - 기존 Milestone의 목표/범위를 넓히거나 완료 기준을 과도하게 키우는 작업이면 새 Milestone으로 분리한다.
   - 사용자 지정 위치가 Phase 목표, Milestone 범위 제외, 명백한 선후 의존성과 충돌하면 수정 전에 충돌 내용을 알리고 방향을 확인한다.

4. **변경 내용 검증**
   - 기능 완료 체크는 사용자 설명 또는 파일/테스트/커밋 등 확인 가능한 근거를 기준으로 한다.
   - evidence 없이 완료 여부가 불확실하면 체크하지 않고 TODO 또는 확인 필요로 남긴다.
   - 변경 요청이 전체 목표 또는 Phase 목표와 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다.

5. **로드맵 파일 갱신**
   - `ROADMAP.md`는 전체 목표, Phase 흐름, Milestone 목록, 로딩 정책이 바뀔 때만 수정한다.
   - `current.md`는 활성 Milestone 창이 바뀔 때 `roadmap-current-template.md` 형식으로 수정한다.
   - 갱신 대상 `ROADMAP.md`가 표준 템플릿과 다르면 기존 내용을 보존하면서 `전체 목표`, `Phase 흐름`, `Milestone 목록`, `로딩 정책` 순서로 정리한다.
   - 갱신 대상 `current.md`가 표준 템플릿과 다르면 기존 활성 Milestone 목록을 보존하면서 `활성 Milestone`, `선택 규칙` 순서로 정리한다.
   - `ROADMAP.md`에 상세 작업 체크리스트가 있으면 삭제하지 말고 관련 Milestone 문서의 `필수 기능` 체크리스트로 옮긴다.
   - `current.md`에 개인별 현재 작업 위치나 완료 상태가 있으면 `current.md`에서는 제거하고 공유 로드맵으로 이관하지 않는다. 프로젝트에 의미 있는 근거가 명확한 내용만 관련 Milestone 문서나 작업 컨텍스트로 옮기고, 이관하지 않은 내용은 결과 보고의 확인 필요 항목에 남긴다.
   - Milestone 문서는 해당 Milestone의 목표, 범위, 필수 기능, 완료 기준, 범위 제외, 작업 컨텍스트가 바뀔 때 수정한다.
   - 갱신 대상 Milestone 문서가 표준 템플릿과 다르면 기존 내용을 보존하면서 템플릿 섹션 순서로 정리하고, 누락 섹션은 TODO 또는 확인 필요 표시와 함께 추가한다.
   - 갱신 대상 Milestone 문서에 `구현 잠금` 섹션이 없으면 추가한다. 구현 구체화가 불충분하면 상태를 `잠금`으로 둔다.
   - `concretize` 모드에서는 구현 세부를 무작정 채우지 말고, 책임 경계, 결정 안건, API/프로토콜 후보, 검증 기준, 선행 조건, 범위 제외를 사용자와 합의된 수준으로만 반영한다.
   - `구현 잠금`을 `해제`로 바꿀 때는 사용자 명시 승인 또는 문서화된 구체화 근거를 결과 보고에 남긴다.
   - 새 Milestone은 사용자 지정 또는 자동 판단 위치에 삽입하고, 기존 Milestone 이름이나 파일명을 순서 맞춤 목적으로 바꾸지 않는다.
   - 새 Milestone은 사용자가 구현 구체화와 잠금 해제를 명시하지 않는 한 `구현 잠금` 상태를 `잠금`으로 작성한다.
   - 기존 Milestone에 새 태스크를 넣는 경우 `필수 기능` 체크리스트에 사용자 지정 또는 자동 판단 위치로 삽입하고, 근거 없이 목록 맨 앞이나 맨 뒤에 붙이지 않는다.
   - 잠금 해제된 Milestone에서 기존 태스크의 하위 작업으로 넣는 경우 부모 태스크 아래의 하위 체크리스트로 작성하고, 부모 태스크의 의미가 바뀌면 부모 문장도 필요한 만큼만 보완한다.
   - 기존 `필수 기능`이 일반 불릿이면 상태 근거를 보존해 `- [ ]` 또는 `- [x]` 체크리스트로 변환한다.
   - 기존 `완료 기준`이 일반 불릿이면 검증 조건 단위의 체크리스트로 변환한다.
   - 상태 값은 `계획`, `진행 중`, `완료`, `보류`, `폐기` 중 하나만 사용한다.
   - 완료된 Milestone의 기록은 삭제하지 않고 상태만 변경한다.

6. **로드맵 룰 라우팅 점검**
   - `agent-ops/rules/common/rules.md`가 `agent-ops/roadmap/` 디렉터리 존재 시 `agent-ops/rules/common/rules-roadmap.md`를 읽도록 라우팅하는지 확인한다.
   - `agent-ops/rules/common/rules-roadmap.md`에 `current.md` 의미, Milestone 선택, `ROADMAP.md` 로딩 조건, 구현 잠금, 현재 작업 지점 확인 방법이 포함되어 있는지 확인한다.
   - 로드맵 컨텍스트 로딩 규칙은 공통 로드맵 룰에 둔다. 프로젝트 전용 `rules/project/rules.md`에는 중복 마일스톤 컨텍스트 로딩 섹션을 추가하지 않는다.
   - 기존 프로젝트 규칙에 마일스톤 컨텍스트 로딩 섹션이 남아 있으면 프로젝트 고유 내용이 아닌지 확인하고, 공통 룰과 중복되는 내용은 제거 대상으로 보고한다.

7. **결과 보고**
   - 수정한 파일 목록
   - 변경된 Phase / Milestone / 상태
   - 신규 작업의 삽입 단위와 배치 위치, 자동 배치인 경우 판단 근거
   - ROADMAP/current/Milestone 문서 템플릿 보정 여부
   - 활성 Milestone 창 변경 사항
   - 체크하거나 추가/제거한 태스크 또는 하위 작업
   - 확인 필요로 남긴 항목

## 실행 결과 검증

- [ ] `current.md`의 활성 Milestone 경로가 실제 파일을 가리키는가
- [ ] `ROADMAP.md`가 `roadmap-template.md`의 섹션 순서와 형식을 따르는가
- [ ] `current.md`가 `roadmap-current-template.md`의 섹션 순서와 형식을 따르는가
- [ ] `ROADMAP.md`의 Milestone 목록과 대상 Milestone 문서의 상태가 서로 충돌하지 않는가
- [ ] 갱신 대상 Milestone 문서가 `roadmap-milestone-template.md`의 섹션 순서와 형식을 따르는가
- [ ] 갱신 대상 Milestone 문서에 `구현 잠금` 섹션이 있는가
- [ ] `구현 잠금`이 없거나 잠긴 Milestone에 구현 태스크, `agent-task` 계획, 세부 API/파일 구조 확정을 추가하지 않았는가
- [ ] 잠금 해제한 경우 사용자 승인 또는 구체화 근거를 결과 보고에 남겼는가
- [ ] 갱신 대상 Milestone 문서의 `필수 기능`과 `완료 기준`이 체크리스트 형식인가
- [ ] 신규 작업이 사용자 지정 위치를 따랐거나, 위치 미지정 시 자동 배치 근거가 남아 있는가
- [ ] 신규 작업의 삽입 단위가 작업 성격과 기존 태스크 포함 관계에 맞는가
- [ ] 자동 배치 위치가 Phase/Milestone 목표, 범위 제외 항목, 선후 의존성과 충돌하지 않는가
- [ ] 대상 Milestone 문서의 상태가 `계획`, `진행 중`, `완료`, `보류`, `폐기` 중 하나인가
- [ ] 완료 처리한 기능에 사용자 설명 또는 확인 가능한 evidence가 있는가
- [ ] `rules/common/rules.md`가 로드맵 디렉터리 존재 시 `rules-roadmap.md`를 읽도록 라우팅하는가
- [ ] `rules/common/rules-roadmap.md`에 로드맵 컨텍스트 로딩과 구현 잠금 규칙이 유지되는가
- 검증 실패 시: 불일치한 파일만 다시 읽고 해당 항목만 수정한다.

## 출력 형식

```markdown
## 업데이트 완료

- 모드: <status | milestone | phase | replan | sync | concretize>
- 수정 파일:
  - agent-ops/roadmap/ROADMAP.md
  - agent-ops/roadmap/current.md
  - agent-ops/roadmap/milestones/<milestone-slug>.md

## 변경 사항

- Phase: <변경 없음 | 요약>
- 삽입 단위: <Milestone | 태스크 | 하위 작업 | 작업 컨텍스트/TODO | 변경 없음>
- 배치: <사용자 지정 위치 반영 | 자동 배치 위치와 근거 | 변경 없음>
- 템플릿 보정: <ROADMAP 적용 | current.md 적용 | Milestone 적용 | 이미 일치 | 변경 없음>
- 구현 잠금: <잠금 유지 | 잠금 추가 | 해제 | 변경 없음>
- 활성 Milestone: <변경 없음 | 추가/제거 요약>
- 상태: <변경 없음 | 이전 -> 이후>
- 태스크: <추가/수정/완료/제거 요약>

## TODO 항목

- <확인이 필요한 항목> (해당 시)
```

## 금지 사항

- 로드맵 파일이 없는데 새 구조를 임의로 만들지 않는다. 이 경우 `create-roadmap`을 사용한다.
- evidence 없이 기능이나 Milestone을 완료 처리하지 않는다.
- 전체 `ROADMAP.md`를 모든 작업의 필수 로딩 파일로 만들지 않는다.
- `ROADMAP.md`에 상세 작업 체크리스트를 남기지 않는다.
- `current.md`에 개인별 현재 작업 위치나 완료 상태를 남기지 않는다.
- 완료된 Milestone 기록을 삭제하지 않는다.
- Phase와 Milestone 이름 또는 파일명에 순번을 강제하지 않는다.
- 기존 순번 파일명을 대규모 rename하지 않는다.
- 신규 작업을 근거 없이 항상 새 Milestone으로 만들거나 맨 앞/맨 뒤에 추가하지 않는다.
- 작업 성격과 기존 태스크 포함 관계를 확인하지 않고 모든 신규 작업을 같은 단위로 처리하지 않는다.
- `구현 잠금`이 없거나 잠긴 Milestone에 대해 사용자의 단순 "진행" 요청만으로 코드 구현, `agent-task` 구현 계획, 세부 API/파일 구조 확정을 시작하지 않는다.
- 사용자 명시 승인과 구체화 근거 없이 Milestone의 `구현 잠금`을 `해제`로 바꾸지 않는다.
- 구현 구체화가 필요한 초기 Milestone을 구현 계획처럼 자세한 package/file/function 체크리스트로 채우지 않는다.
- 사용자가 지정한 앞/뒤/아래 anchor 또는 대상 Phase/Milestone 컨테이너를 무시하지 않는다.
- Milestone 목표와 범위 제외 항목을 무시하고 태스크 체크리스트만 갱신하지 않는다.
- 해야 할 작업을 `필수 기능` 체크리스트 밖의 설명 문장에 숨기지 않는다.
- 갱신 대상 Milestone의 형식이 다르다는 이유로 기존 내용이나 완료 체크 근거를 삭제하지 않는다.
- 타겟 프로젝트에서 `agent-ops/rules/common/` 또는 `agent-ops/skills/common/`을 직접 수정하지 않는다.