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

로드맵 규칙

agent-roadmap/ 디렉터리가 있는 프로젝트에서만 적용한다.

구조

• 최상위 로드맵은 agent-roadmap/ROADMAP.md다.
• 활성 Phase는 agent-roadmap/phase/<phase-slug>/PHASE.md에 둔다.
• 활성 Milestone은 해당 Phase 아래 agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md에 둔다.
• <phase-slug>와 <milestone-slug>는 소문자 영문, 숫자, 하이픈만 사용한다.
• 완료된 Phase는 scaffold 그대로 agent-roadmap/archive/phase/<phase-slug>/PHASE.md로 이동하고, 하위 Milestone도 archive/phase/<phase-slug>/milestones/ 아래에 둔다.
• 진행중 Phase 안에서 완료된 Milestone은 활성 PHASE.md에 짧은 archive 링크를 남기고, 상세 문서는 agent-roadmap/archive/phase/<phase-slug>/milestones/로 이동한다.
• archive PHASE.md는 Phase 자체가 완료/폐기될 때만 만들며, 진행중 Phase의 완료 Milestone만 archive된 경우 archive Phase 디렉터리에 milestones/만 있을 수 있다.
• 큰 Milestone의 설계 게이트는 agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md에 둔다.
• SDD 사용자 리뷰가 필요하면 같은 디렉터리에 USER_REVIEW.md를 둔다. 해결된 리뷰는 user_review_N.log로 남긴다.
• 완료 또는 폐기된 Milestone의 SDD는 agent-roadmap/archive/sdd/<phase-slug>/<milestone-slug>/로 이동한다.

Runtime Action Boundary

• 로드맵 스킬은 기본적으로 로드맵 문서 작성, 의미 판단, 배치 제안, file-based fallback 갱신을 담당한다.
• Core/MCP가 있는 프로젝트에서는 Phase/Milestone 상태 전환, archive 이동, 외부 의존 lock 동기화, 완료 이벤트 반영 같은 action을 Core/MCP 또는 런타임이 처리한다.
• Core/MCP가 없거나 아직 해당 action을 제공하지 않는 프로젝트에서만 update-roadmap 스킬이 file-based fallback으로 직접 문서를 갱신한다.
• update-roadmap은 fallback 갱신을 수행하더라도 런타임 action 경계를 문서화하고, Core/MCP로 넘길 수 있는 입력과 결과를 함께 남긴다.

로딩

• 세션 최초 1회 agent-roadmap/current.md가 있으면 읽고 활성 Phase, 활성 Milestone의 이름, 경로, 선택 규칙만 짧게 기억한다.
• agent-roadmap/current.md는 브랜치별 로컬 포인터이며 git 추적 대상이 아니다.
• current.md가 없고 로드맵 기반 계획 또는 갱신이 필요하면 agent-ops/skills/common/_templates/roadmap-current-template.md 형식으로 로컬 파일을 만들거나 ROADMAP.md와 활성 PHASE.md에서 후보를 고른다.
• 읽기 전용 로드맵 현지점 확인에서는 current.md가 없어도 만들지 않고, 로컬 current 없음으로 보고한 뒤 ROADMAP.md의 Phase 흐름만 보여준다.
• 일반 작업에서는 ROADMAP.md를 읽지 않는다.
• 일반 작업에서는 agent-roadmap/archive/**를 읽지 않는다.
• 기능 추가, 구조 변경, 구현 계획 전에는 요청과 변경 파일에 맞는 활성 Phase와 활성 Milestone 문서를 읽는다.
• 선택한 Milestone의 구현 잠금에 SDD: 필요가 있으면 agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md와 같은 디렉터리의 USER_REVIEW.md 존재 여부를 확인한다.
• 로드맵 현지점 확인은 로컬 current.md, ROADMAP.md의 Phase 흐름, 활성 PHASE.md의 Milestone 흐름, 활성 Milestone의 제목/목표/상태를 기본으로 읽고, SDD: 필요이면 SDD 상태/잠금/사용자 리뷰 요약도 함께 확인한다.
• ROADMAP.md는 로드맵 생성/갱신, Phase 추가/삭제/전환, 전체 구조 변경, 활성 범위 밖 작업 확인 때만 읽는다.
• 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 ROADMAP.md 또는 PHASE.md에 있는 archive 링크를 따라가서 필요한 archive 문서만 읽는다.

Phase와 Milestone 선택

• current.md는 현재 작업 위치가 아니라 활성 Phase와 활성 Milestone 후보 목록이다.
• current.md는 공유 진행 상태가 아니며, 공유해야 할 상태는 ROADMAP.md, PHASE.md, Milestone 문서, .agent-roadmap-sync/locks.yaml에 남긴다.
• 활성 Phase는 agent-roadmap/phase/**/PHASE.md만 대상으로 한다.
• 활성 Milestone은 agent-roadmap/phase/**/milestones/*.md만 대상으로 한다.
• current.md에는 [완료] 또는 [폐기] Phase/Milestone을 남기지 않는다. 완료 후보는 승인 전까지 [검토중]으로 둔다.
• "로드맵에 추가", "마일스톤에 추가"처럼 target 없는 신규 작업 추가 요청은 update-roadmap 스킬로 배치 제안 또는 file-based fallback 갱신을 처리하고, Phase/Milestone/Epic/Task 배치를 자동 판단한다.
• target 없는 신규 추가 요청은 먼저 요청 규모를 phase, milestone, epic, task, subtask, context 중 가장 작은 충분한 단위로 판정한다.
• target 없는 신규 추가 요청은 활성 창만으로 결정하지 말고 필요한 경우 ROADMAP.md의 Phase 흐름과 관련 Phase/Milestone 문서를 비교한다.
• 배치는 Phase -> Milestone -> Epic -> Task 순서로 내려가며 같은 레벨의 동일/유사 후보를 먼저 찾는다.
• 동일/유사 항목이 이미 있으면 새로 만들지 말고 기존 항목을 업데이트한다.
• 적절한 기존 후보가 없을 때만 판정한 규모에 맞는 새 항목을 만든다.
• 부모 후보는 있고 판정 규모의 항목만 없으면 부모 아래에 새 항목을 만들고, 부모도 없을 때만 필요한 부모 항목을 함께 만든다.
• 자동 배치할 때는 선택한 Phase/Milestone/Epic/Task와 밀린 후보의 이유를 결과에 남긴다.
• current.md가 아카이브 경로를 가리키면 해당 항목은 활성 후보로 읽지 말고 로드맵 갱신이 필요하다고 보고한다.
• 선택한 Phase/Milestone의 목표 또는 범위 제외와 요청이 충돌하면 구현 전에 사용자에게 확인한다.

상태 표기

• Phase와 Milestone 상태 표기는 [스케치], [계획], [진행중], [검토중], [완료], [보류], [폐기] 중 하나만 사용한다.
• [스케치]는 방향성, 문제의식, 후보 범위, 미정 질문을 기록하는 컨셉 상태다. 구현 가능한 계획이 아니므로 agent-task 구현 계획 생성과 코드 구현을 시작하지 않는다.
• [스케치] 항목은 [계획]으로 승격하기 위한 승격 조건, 사용자 결정, 범위 경계, 후속 Milestone 후보를 정리하는 것이 목적이다.
• [계획] 이상 상태의 Milestone에서 승격 조건 섹션은 선택 사항이다. 섹션이 없거나 - 없음이면 템플릿 오류로 보지 않는다.
• [스케치]를 [계획]으로 전환하려면 승격 조건의 미정 항목이 해소되고, 목표, 범위, 기능 Task, 직접적인 사용자 결정 항목, 후속 구현 단위가 구현 계획을 만들 수 있을 만큼 정리되어야 한다.
• [계획]은 목표, 범위, 기능 Task, 구현 잠금, 결정 필요 항목이 문서화되어 잠금 해제 후 구현 계획을 만들 수 있는 상태다.
• 갱신 범위에 포함된 기존 진행 상태 표기는 [진행중]으로 정리한다.
• [검토중]은 모든 기능 Task와 Task 안에 명시된 검증이 충족되고 구현 잠금이 해제되었으나, 사용자의 최종 완료 확인과 archive 승인이 아직 남은 완료 후보 상태다.
• [검토중] 항목은 활성 경로에 남기고 current.md의 활성 후보로 유지할 수 있다.
• 검토 결과 보완이 필요하면 별도 reopen 상태를 만들지 않고 [진행중]으로 되돌린 뒤 완료 리뷰 또는 작업 컨텍스트에 보완 방향을 남긴다.
• 검토 결과 보류 또는 폐기 결정이 나면 [보류] 또는 [폐기]로 전환한다.
• ROADMAP.md의 Phase 흐름과 PHASE.md의 Milestone 흐름은 완료, 검토중, 진행중, 계획, 스케치 순서를 기본으로 하며 아래로 갈수록 미래 작업에 가까워지게 정렬한다.

구현 잠금

• 구현 잠금은 승인 의식이 아니라 사용자 결정이 필요한지 표시하는 얇은 상태다.
• 제품 방향, 범위, 우선순위, 책임 경계처럼 사용자만 결정할 수 있는 항목이 남아 있으면 상태를 잠금으로 두고 결정 필요 체크리스트에 질문을 적는다.
• 기존 구조, 도메인 rule, 플랫폼 관례, 업계 표준으로 합리적으로 정할 수 있는 항목은 결정 필요가 아니라 작업 컨텍스트의 표준선이나 구현 가정으로 기록한다.
• Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 해제로 둔다.
• 선택한 Milestone에 구현 잠금 섹션이 없거나, 상태가 잠금이거나, 미완료 결정 필요 항목이 하나라도 있으면 코드 구현, agent-task 구현 계획, 세부 API/파일 구조 확정을 시작하지 않는다.
• 잠금 상태에서 허용되는 작업은 로드맵 현지점 확인, 잠금 해소, SDD gate 처리, 범위/후속 Milestone 정리 같은 roadmap-only 갱신뿐이다. 실구현 plan 요청이면 잠금 차단으로 보고하고 PLAN-*.md/CODE_REVIEW-*.md를 만들지 않는다.
• 남은 결정 필요 항목이 현재 Milestone 실구현 범위가 아니라면 먼저 update-roadmap으로 범위 제외, 후속 Milestone, 또는 작업 컨텍스트로 옮기고 구현 잠금을 해제한 뒤 별도 실구현 계획을 시작한다.
• 구현 잠금은 SDD gate를 포함할 수 있다. SDD: 필요이면 SDD 상태가 [승인됨]이고 SDD 잠금이 해제이며 SDD USER_REVIEW.md가 없어야 구현 잠금 해제 후보가 된다.
• SDD 사용자 리뷰는 채팅 질문으로 직접 처리하지 않고 agent-roadmap/sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md에 남긴다. 사용자의 답변이 반영되면 user_review_N.log로 이동한다.
• SDD가 필요한데 문서가 없거나 gate 정보가 부족하면 plan 스킬은 roadmap-sdd pre-plan gate로 SDD 작성/확인을 먼저 수행한다. 그 결과 SDD 잠금이 남거나 SDD 사용자 리뷰가 열려 있으면 구현 계획을 만들지 않는다.
• SDD가 불필요한 Milestone은 SDD: 불필요과 짧은 사유를 구현 잠금에 남긴다.
• 잠금 상태의 Milestone에서는 "현재 요청과 직접 관련 없음"을 이유로 실구현 plan이나 코드 구현을 진행하지 않는다. 관련 없음 판단은 잠금 해소용 roadmap-only 갱신으로 먼저 문서화한다.
• 잠금 상태를 바꾸더라도 기능 Task를 자동 완료 처리하지 않는다.
• [스케치] 상태의 Milestone은 구현 잠금이 해제로 보이더라도 구현 계획과 코드 구현 대상이 아니다. 먼저 [계획]으로 승격해야 한다.

프로젝트 간 잠금

• 프로젝트 상위 .agent-roadmap-sync/locks.yaml은 프로젝트 간 Milestone 잠금 인덱스다. 외부 의존 잠금을 생성하거나 동기화해야 하면 Core/MCP가 있으면 그쪽 action이 만들고, 없으면 update-roadmap file-based fallback이 디렉터리와 파일을 만든다.
• entry는 id, locked, rely-on[].target, rely-on[].status, rely-on[].note만 사용한다.
• locks.yaml은 root sequence block style을 기본으로 작성한다. 예: - id: ... 아래에 locked, rely-on을 둔다.
• id는 기본적으로 <잠긴-project>:<잠긴-milestone-slug>로 만든다.
• locked와 rely-on[].target은 <project>:agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md 형식으로 기록한다.
• Milestone 경로가 agent-roadmap/... 상대 경로이면 현재 프로젝트명을 prefix로 붙인다. workspace 하위 절대/상대 경로이면 workspace 바로 아래 디렉터리명을 project로 삼고, 그 뒤 agent-roadmap/... 경로를 붙인다.
• locked는 잠긴 Milestone, rely-on.target은 선행 조건 Milestone이다. 둘 다 같은 workspace의 어느 활성 Phase 하위 Milestone이어도 된다. 의존 대상이 current.md에 있어야 한다고 가정하지 않는다.
• "현재 마일스톤은 X 프로젝트 작업 뒤에 진행", "X 프로젝트 때문에 현재 작업 잠금", "의존성 설정해"처럼 잠긴 Milestone을 생략한 외부 의존 잠금 요청은 현재 프로젝트 로컬 current.md의 활성 Milestone 단일 후보를 잠긴 대상으로 삼는다.
• 의존 대상은 명시 경로, 명시 slug, 명시 제목, 잠긴 Milestone 문서의 선행 Milestone 힌트, 대상 프로젝트 로컬 current.md가 있을 때의 단일 후보 순서로 확정한다.
• 정규화 비교는 소문자 변환, backtick/따옴표 제거, 영문/숫자가 아닌 연속 문자를 - 하나로 치환, 앞뒤 - 제거 후 Milestone 파일 slug와 정규화한 제목에 대조한다.
• 의존 대상 탐색은 대상 프로젝트의 agent-roadmap/phase/*/milestones/*.md 활성 문서만 대상으로 한다. archive 문서는 사용자가 archive 경로를 명시한 경우 외에는 읽거나 후보로 삼지 않는다.
• 후보가 없거나 둘 이상이면 locks.yaml을 만들거나 고치지 말고 사용자에게 대상 Milestone 선택을 요청한다.
• 외부 의존 잠금을 만들 때 대상 Milestone의 구현 잠금은 잠금으로 둔다.
• 새 rely-on.status는 선행 Milestone 상태에서 파생한다. [검토중] 또는 [완료]이면 enable, 그 외 상태거나 상태를 확인할 수 없으면 disable이다.
• 같은 id entry를 upsert할 때 기존 rely-on 항목을 삭제하지 않는다. 같은 rely-on.target만 status/note를 갱신하고, 없는 target은 추가하며, locked 경로가 바뀐 경우에만 locked를 갱신한다.
• locks.yaml이 있고 Milestone을 갱신하거나 archive할 때는 대상 Milestone identity로 agent-ops/bin/roadmap-dependency-checker.sh --find-milestone "<identity>" both "<locks-file>"를 먼저 실행한다.
• find 결과가 none이면 결과 보고의 Workspace 잠금에 관련 lock 없음을 남긴다. 외부 의존 잠금 생성/동기화 요청이 아니라면 locks.yaml을 새로 만들거나 수정하지 않는다.
• Core/MCP action 또는 update-roadmap fallback이 갱신한 Milestone identity가 어느 entry의 rely-on.target과 일치하면 Milestone 상태 기준으로 status를 동기화한다. [검토중] 또는 [완료]이면 enable, 그 외 상태면 disable이다.
• Core/MCP action 또는 update-roadmap fallback이 갱신하거나 선택한 Milestone identity가 어느 entry의 locked와 일치하면 모든 rely-on.status가 enable인지 결과 보고에 남긴다. 모든 조건이 충족되어도 잠금 해제 실행은 Core/MCP 또는 런타임의 별도 action으로 처리한다.
• archive 모드에서는 파일 이동 전에 대상 Milestone의 활성 경로 identity를 보존하고, 그 identity로 --find-milestone "<identity>" both "<locks-file>"를 먼저 실행한다. 보존한 identity가 어느 entry의 rely-on.target과 일치하고 Milestone 상태가 [완료]이면 archive 이동 전에 해당 rely-on.status를 enable로 바꾼다.
• archive 모드에서 보존한 identity가 어느 entry의 locked와 일치하면 archive 이동 전에 모든 rely-on.status가 enable인지 결과 보고에 남긴다. 미충족이어도 archive 자체는 막지 않고 Workspace 잠금: 미충족으로 보고한다.
• 잠금 해제 조건 충족 여부만 확인할 때는 agent-ops/skills/common/check-roadmap-dependency/SKILL.md를 읽는다. lock id가 없으면 해당 스킬은 agent-ops/bin/roadmap-dependency-checker.sh --find-milestone "<identity>" "<direction>" "<locks-file>"로 현재 Milestone이 locked인지 rely-on.target인지 양방향으로 찾은 뒤 agent-ops/bin/roadmap-dependency-checker.sh "<lock-id>" "<locks-file>"를 사용한다.
• checker exit code는 0=true, 1=false, 2=설정/입력/파싱 오류로 해석한다.

SDD 게이트

• SDD는 큰 Milestone의 설계 계약을 로드맵에 녹이는 하위 문서다. 별도 작업 관리 체계로 쓰지 않는다.
• SDD 작성, 갱신, gate 확인, 사용자 리뷰 대기, 잠금 해제는 agent-ops/skills/common/roadmap-sdd/SKILL.md를 따른다.
• SDD는 cross-repo 계약, 외부 provider 쓰기, 상태 머신, idempotency/retry/identity map, API/proto/config/env/schema, field smoke, 사용자 승인 gate에 영향을 주는 Milestone에만 강제한다.
• 작은 리팩터링, 문서 정리, 테스트 보강, 작은 UI 보강, Milestone Task의 검증:만으로 닫히는 작업에는 SDD를 강제하지 않는다.
• SDD 문서는 agent-ops/skills/common/_templates/roadmap-sdd-template.md의 표준 섹션, 순서, 필수 표 컬럼을 유지해야 한다.
• SDD의 Acceptance Scenarios는 Milestone 기능 Task id와 연결되어야 한다.
• SDD의 Evidence Map은 plan/code-review/complete.log의 Spec Targets와 Spec Completion으로 검증 가능해야 한다.
• 외부 API 또는 프로젝트 간 호출 계약 원문은 agent-contract/에 두고 SDD에는 링크만 남긴다.
• SDD 전체 검토를 사용자에게 던지지 않는다. 사용자만 결정할 source of truth, 상태 전이, 책임 경계, 권한, 비용, 데이터 보존, 실패 처리만 USER_REVIEW.md로 분리한다.

Epic과 Task id

• Milestone 문서의 실행 체크리스트는 기능 섹션 하나로 작성한다. 새 Milestone이나 갱신 범위에 포함된 Milestone에는 별도 완료 기준 섹션을 만들지 않는다.
• 기존 Milestone에 필수 기능과 완료 기준이 분리되어 있으면, 갱신 시 완료 기준을 관련 기능 Task 안의 선택적 검증: 문구로 흡수하고 섹션을 제거한다.
• 기능 Task는 기능 또는 산출물 단위다. 검증이 필요한 기능만 같은 Task 안에 검증: <명령/확인 방법/기대 결과>를 붙인다.
• 검증이 명시된 Task의 [x]는 기능/산출물과 해당 검증이 모두 충족되었다는 뜻이다. 검증이 명시되지 않은 Task의 [x]는 기능/산출물 완료 근거가 충분하다는 뜻이다.
• 사용자만 결정할 수 있는 검토/선택/우선순위 항목은 기능 Task로 쓰지 않는다. 구현 잠금의 결정 필요 또는 작업 컨텍스트로 분리하고, 현재 구현에 직접 필요하면 plan 생성 전에 사용자 확인을 받는다.
• 기능 섹션의 Task 체크리스트는 Epic 바로 아래의 flat list를 기본으로 한다. 구현 세부, 테스트만 따로 떼어낸 하위 체크박스는 roadmap에 만들지 말고 plan 내부 체크리스트나 같은 Task의 검증:으로 흡수한다.
• Epic heading은 ### Epic: [epic-id] <이름> 형식을 사용한다.
• Task는 - [ ] [item-id] 설명 또는 - [x] [item-id] 설명 형식을 사용한다.
• epic-id와 item-id는 공백 없는 짧은 ASCII 토큰이며, 영문/숫자 segment 14개로 작성하고 segment 구분자는 -, _, +, =만 사용한다. 가능하면 13 segment를 우선하며, 전체 길이는 32자 이하를 권장한다.
• epic-id와 item-id는 해당 Milestone 안에서만 유일하면 된다.
• 다른 Milestone에서는 같은 id를 다시 사용할 수 있다. 여러 Milestone 후보에서 같은 id가 발견되면 Milestone 이름이나 문서 경로로 대상을 확정한다.
• 사용자가 epic-id 또는 item-id를 언급하면 해당 Milestone의 Epic/Task 항목을 우선 anchor로 삼고, 기존 id는 명시적 요청 없이 바꾸지 않는다.

Milestone 기반 agent-task

• plan 스킬이 활성 Milestone 범위의 구현 계획을 만들면 task group은 agent-task/m-<milestone-slug>/ 형식을 사용한다.
• <milestone-slug>는 활성 Milestone 파일명에서 .md를 제거한 값이며, Phase slug, Epic id, Task id, 별도 task slug를 task group에 넣지 않는다.
• split 작업은 기존 규칙 그대로 agent-task/m-<milestone-slug>/<subtask_dir>/ 아래에 둔다.
• m-<milestone-slug>는 Milestone 기반 작업 전용 예약 prefix이며, 일반 작업 task group은 m-으로 시작하지 않는다.
• 런타임은 파일 내부가 아니라 task group 이름만으로 Milestone 기반 작업 여부를 판별한다.
• code-review에서 m-<milestone-slug> 작업이 PASS되면 roadmap을 직접 수정하거나 update-roadmap을 직접 호출하지 않는다.
• 런타임은 PASS 완료 이벤트의 task group에서 m-<milestone-slug>를 판별하고, 상태 체크 후 Core/MCP action으로 Milestone 업데이트를 호출한다. Core/MCP action이 없으면 update-roadmap file-based fallback 흐름을 호출한다. 단, Milestone 기능 Task 체크는 complete.log에 Roadmap Completion 섹션과 명시 Task id가 있을 때만 수행하고, 섹션이 없으면 no-op으로 둔다.
• SDD 대상 Milestone은 런타임 완료 이벤트의 complete.log에 Spec Completion이 있어야 roadmap Task 체크 후보가 된다. SDD Evidence Map은 Spec Completion 검증 기준이며 단독 대체 근거가 아니다. 단, 사용자가 명시적으로 evidence를 전달한 수동 update-roadmap 갱신에서는 Evidence Map 충족 근거를 보조 근거로 사용할 수 있다.
• 런타임 완료 이벤트가 최종 archive 경로만 갖고 있으면 agent-task/archive/YYYY/MM/m-<milestone-slug>/...를 agent-task/m-<milestone-slug>/... 형태의 origin-task로 정규화해 전달한다.
• 런타임 호출에서 매칭되는 활성 Milestone이 없거나 둘 이상이면 추정하지 말고 수동 target 선택이 필요하다고 보고한다.
• WARN 또는 FAIL은 Milestone 완료 업데이트를 하지 않는다. 일반적으로 같은 m-<milestone-slug> task group에서 follow-up plan/review를 이어가지만, code-review의 user-review gate가 트리거되면 USER_REVIEW.md를 남기고 사용자 판단을 기다린다.
• [스케치] Milestone은 Milestone 기반 agent-task 생성 대상이 아니다. 런타임이나 plan 스킬은 이를 구현 작업으로 라우팅하지 않고 [계획] 승격 필요를 보고한다.

완료 리뷰

• Task 완료나 Milestone 갱신 시 모든 기능 Task와 Task 안에 명시된 검증이 evidence와 함께 [x]가 되었는지 확인하고, 구현 잠금이 해제이며 미완료 결정 필요 항목이 없는지 함께 확인한다.
• 기능 Task가 모두 충족되어도 구현 잠금이 남아 있으면 Milestone을 [검토중]으로 바꾸지 않는다. 완료 리뷰 또는 작업 컨텍스트에 잠금 차단 항목을 남기고, 잠금 해소 roadmap 갱신을 먼저 요구한다.
• 기능 Task와 구현 잠금이 모두 충족된 것으로 보이면 Milestone을 [완료]로 바로 바꾸거나 archive로 이동하지 말고 [검토중]으로 바꾼다.
• [검토중]으로 바꿀 때는 Milestone 문서에 완료 리뷰 섹션을 만들거나 갱신하고, 완료 근거 1~3줄과 사용자에게 필요한 최종 확인 항목을 남긴다.
• 사용자가 완료를 승인한 뒤에만 [완료]로 전환하고 archive 이동을 수행한다.
• Phase도 모든 하위 Milestone이 [완료] 또는 [폐기]로 정리되어 Phase 완료 후보가 되면 [검토중]으로 두고 사용자 최종 확인을 받은 뒤 [완료] 또는 [폐기]로 전환한다.

로드맵 현지점

• 현재 작업 지점이나 로드맵상 현 위치 확인 요청은 analyze-roadmap-position 스킬로 처리한다.
• 답변은 agent-ops/skills/common/_templates/roadmap-position-report-template.md 섹션과 필드 순서를 따른다.
• 기본 동작에서는 코드, git 상태, diff를 읽지 않고 로드맵 > Phase > Milestone breadcrumb와 흐름 목록으로 현재 좌표를 보여준다.
• current가 Phase 또는 Milestone 후보를 여럿 가리키면 모두 현재 후보로 표시하고 짧은 역할 태그만 붙인다.

아카이브

• 완료 또는 폐기되어 현재 작업 후보에서 제외할 Phase/Milestone은 Core/MCP action으로 아카이빙한다. Core/MCP action이 없으면 update-roadmap file-based fallback으로 아카이빙한다.
• [검토중] Phase/Milestone은 archive 대상이 아니며, 사용자 승인 전까지 활성 경로에 남긴다.
• Phase 아카이브 대상은 agent-roadmap/archive/phase/<phase-slug>/PHASE.md와 같은 scaffold로 이동한다.
• Milestone 아카이브 대상은 agent-roadmap/archive/phase/<phase-slug>/milestones/<milestone-slug>.md로 이동한다.
• 활성 SDD가 있으면 agent-roadmap/archive/sdd/<phase-slug>/<milestone-slug>/로 함께 이동한다. SDD USER_REVIEW.md가 남아 있으면 먼저 해결한다.
• Milestone 아카이브 전에는 이동 전 활성 경로 identity로 .agent-roadmap-sync/locks.yaml을 확인한다. 해당 identity가 rely-on.target이면 [완료] 상태에서 enable로 동기화하고, 해당 identity가 locked이면 의존 조건 충족 여부를 보고하며, 어느 쪽에도 없으면 관련 lock 없음으로 보고한다.
• 구현 잠금이 남아 있는 Milestone은 [완료] 전환이나 완료 archive 대상으로 삼지 않는다. 사용자 폐기 지시가 있는 [폐기] archive는 허용한다.
• 아카이빙할 때는 활성 ROADMAP.md 또는 활성 PHASE.md에 archive 문서 링크와 짧은 요약만 남긴다.
• 아카이브된 Phase/Milestone은 로컬 current.md에 남기지 않고, 일반 Phase/Milestone 선택이나 위치 분석의 후보로 삼지 않는다.
• 아카이브 문서는 과거 기록 스냅샷으로 보고, 최신 템플릿이나 스킬 규약에 맞춰 재포맷하지 않는다.