sync: to agentic-framework v1.1.162

agent-ops/.version

@@ -1 +1 @@
-1.1.161
+1.1.162

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

@@ -15,6 +15,15 @@
 - SDD 사용자 리뷰가 필요하면 같은 디렉터리에 `USER_REVIEW.md`를 둔다. 해결된 리뷰는 `user_review_N.log`로 남긴다.
 - 완료 또는 폐기된 Milestone의 SDD는 `agent-roadmap/archive/sdd/<phase-slug>/<milestone-slug>/`로 이동한다.
 
+## 링크 표기
+
+- 사용자에게 보여주는 답변과 활성 로드맵 문서의 문서 포인터는 raw path만 쓰지 말고 `[표시 제목](상대경로)` Markdown 링크로 쓴다.
+- 로드맵 문서 안의 링크 target은 링크를 작성하는 Markdown 파일 위치 기준 상대경로로 쓴다. 예: `ROADMAP.md`에서는 `[PHASE.md](phase/<phase-slug>/PHASE.md)`, Phase 문서에서는 `[Milestone](milestones/<milestone-slug>.md)`, Milestone 문서에서는 `[ROADMAP.md](../../../ROADMAP.md)`와 `[PHASE.md](../PHASE.md)`를 쓴다.
+- 채팅 결과 보고처럼 저장 위치가 없는 출력은 repo root 기준 상대경로를 쓸 수 있다. 예: `[PHASE.md](agent-roadmap/phase/<phase-slug>/PHASE.md)`.
+- 실제 활성 로드맵 문서에는 `<phase-slug>`, `<milestone-slug>`, `<relative-...>` 같은 placeholder가 들어간 링크 target을 남기지 않는다. 템플릿 placeholder는 문서 생성/갱신 시 실제 파일 위치 기준 상대경로 또는 `없음`으로 치환한다.
+- 기존 raw path 또는 backtick path는 읽기 입력으로 허용한다. 갱신 범위에 포함된 활성 문서 포인터만 Markdown 링크로 보정하고, archive 스냅샷은 링크 표기만을 이유로 재포맷하지 않는다.
+- `.agent-roadmap-sync/locks.yaml`의 `locked`, `rely-on.target`, Milestone identity(`<project>:agent-roadmap/...`)처럼 machine-readable 계약 값은 raw 값을 유지할 수 있다. 사용자-facing 설명에는 가능하면 별도 Markdown 문서 링크를 함께 붙인다.
+
 ## Runtime Action Boundary
 
 - 로드맵 스킬은 기본적으로 로드맵 문서 작성, 의미 판단, 배치 제안, file-based fallback 갱신을 담당한다.
@@ -118,7 +127,7 @@
 - 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를 강제하지 않는다.
-- 로드맵 갱신으로 새 Milestone을 만들거나 `[스케치]` Milestone을 `[계획]`으로 승격하면서 `SDD: 필요`로 판정하면 같은 흐름에서 SDD 파일도 만든다. 사용자가 명시적으로 SDD 생성을 뒤로 미루지 않았는데 `SDD: 필요`와 SDD 경로만 있고 파일이 없는 상태로 종료하지 않는다.
+- 로드맵 갱신으로 새 Milestone을 만들거나 `[스케치]` Milestone을 `[계획]`으로 승격하면서 `SDD: 필요`로 판정하면 같은 흐름에서 SDD 파일도 만든다. 사용자가 명시적으로 SDD 생성을 뒤로 미루지 않았는데 `SDD: 필요`와 SDD 문서 링크만 있고 파일이 없는 상태로 종료하지 않는다.
 - SDD 문서는 `agent-ops/skills/common/_templates/roadmap-sdd-template.md`의 표준 섹션, 순서, 필수 표 컬럼을 유지해야 한다.
 - SDD의 `Acceptance Scenarios`는 Milestone 기능 Task id와 연결되어야 한다.
 - SDD의 `Evidence Map`은 code-review/complete.log의 `Roadmap Completion`과 최종 검증 evidence로 검증 가능해야 한다.

agent-ops/skills/common/_templates/roadmap-current-template.md

@@ -3,28 +3,28 @@
 ## 활성 Phase
 
 - [<스케치 | 계획 | 진행중 | 검토중 | 보류>] <phase-name>
-  - 경로: `agent-roadmap/phase/<phase-slug>/PHASE.md`
+  - 경로: [PHASE.md](phase/<phase-slug>/PHASE.md)
 
 ## 활성 Milestone
 
 - [<스케치 | 계획 | 진행중 | 검토중 | 보류>] <milestone-name>
-  - Phase: `agent-roadmap/phase/<phase-slug>/PHASE.md`
+  - Phase: [PHASE.md](phase/<phase-slug>/PHASE.md)
-  - 경로: `agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md`
+  - 경로: [<milestone-name>](phase/<phase-slug>/milestones/<milestone-slug>.md)
 
 ## 선택 규칙
 
 - 이 문서는 활성 Phase와 활성 Milestone 후보 목록이며, 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다.
 - 이 문서는 브랜치별 로컬 포인터이며 git 추적 대상이 아니다.
-- 활성 Phase는 `agent-roadmap/phase/<phase-slug>/PHASE.md`를 가리킨다.
+- 활성 Phase는 [PHASE.md](phase/<phase-slug>/PHASE.md)를 가리킨다.
-- 활성 Milestone은 `agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md`를 가리킨다.
+- 활성 Milestone은 [Milestone 문서](phase/<phase-slug>/milestones/<milestone-slug>.md)를 가리킨다.
 - 활성 항목은 아카이브 경로를 포함하지 않는다.
 - `[검토중]` 항목은 완료 근거와 archive 조건이 정리될 때까지 활성 항목으로 남길 수 있다.
 - `[스케치]` 항목은 활성 후보로 남길 수 있지만 구현 계획 생성 대상은 아니며, `[계획]` 승격 조건을 정리하는 대상으로만 다룬다.
 - `[완료]` 또는 `[폐기]` 항목은 archive 링크를 남긴 뒤 활성 항목에서 제거한다.
 - 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 Phase와 Milestone을 선택하고 같은 세션에서 1회 읽는다.
 - 활성 Phase 또는 Milestone 둘 이상에 걸치면 필요한 문서를 모두 읽고 작업 범위를 좁힌다.
-- 활성 범위 밖의 작업이면 `agent-roadmap/ROADMAP.md`의 Phase 흐름을 확인하고 범위 충돌을 보고한다. 제품/범위 결정이 필요하면 대상 Milestone의 `구현 잠금 > 결정 필요` 또는 SDD `USER_REVIEW.md`로 분리한다.
+- 활성 범위 밖의 작업이면 [ROADMAP.md](ROADMAP.md)의 Phase 흐름을 확인하고 범위 충돌을 보고한다. 제품/범위 결정이 필요하면 대상 Milestone의 `구현 잠금 > 결정 필요` 또는 SDD [USER_REVIEW.md](sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md)로 분리한다.
 - 완료된 과거 내용이 필요할 때만 `ROADMAP.md` 또는 `PHASE.md`에 있는 archive 링크를 따라가서 읽는다.
 - 선택된 Milestone의 `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 구현이나 구현 계획을 시작하기 전에 현재 요청에 직접 영향을 주는 `결정 필요` 항목만 확인한다. 관련 결정이 없고 표준선으로 처리 가능하면 잠금 해소용 roadmap-only 갱신으로 결정 항목을 정리한 뒤 진행하며, Milestone 전체에서 에이전트가 확정할 수 없는 결정 항목이 더 이상 없을 때만 `구현 잠금` 상태를 `해제`로 둔다.
-- 선택된 Milestone에 `SDD: 필요`가 있으면 `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md`가 `[승인됨]`이고 SDD 잠금이 해제되었으며 SDD `USER_REVIEW.md`가 없어야 구현이나 구현 계획을 시작한다.
+- 선택된 Milestone에 `SDD: 필요`가 있으면 [SDD.md](sdd/<phase-slug>/<milestone-slug>/SDD.md)가 `[승인됨]`이고 SDD 잠금이 해제되었으며 SDD [USER_REVIEW.md](sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md)가 없어야 구현이나 구현 계획을 시작한다.
 - 선택된 Milestone 상태가 `[스케치]`이면 `구현 잠금` 상태와 관계없이 구현이나 구현 계획을 시작하지 않고 `[계획]` 승격 필요를 보고한다.

agent-ops/skills/common/_templates/roadmap-milestone-template.md

@@ -2,8 +2,8 @@
 
 ## 위치
 
-- Roadmap: `agent-roadmap/ROADMAP.md`
+- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
-- Phase: `agent-roadmap/phase/<phase-slug>/PHASE.md`
+- Phase: [PHASE.md](../PHASE.md)
 
 ## 목표
 
@@ -33,7 +33,7 @@
 
 - 상태: <잠금 | 해제>
 - SDD: <필요 | 불필요>
-- SDD 문서: <없음 | `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md`>
+- SDD 문서: <없음 | [SDD.md](../../../sdd/<phase-slug>/<milestone-slug>/SDD.md)>
 - SDD 사유: <필요/불필요 판정 근거 한 줄>
 - 잠금 해제 조건: <없음 | 아래 체크리스트>
   - [ ] <SDD가 필요한 경우: SDD 잠금이 해제되어 있다>
@@ -93,6 +93,6 @@ Task 체크리스트는 Epic 바로 아래의 flat list로 유지하고, 구현
 
 - 관련 경로: `<path>`
 - 표준선(선택): <기존 구조, 도메인 rule, 플랫폼 관례, 업계 표준으로 진행할 기본 기준>
-- 선행 작업: <없음 또는 Milestone/태스크 이름>
+- 선행 작업: <없음 또는 파일 위치 기준 Markdown 링크(예: [Milestone 이름](../other-milestone.md))/태스크 이름>
-- 후속 작업: <없음 또는 Milestone/태스크 이름>
+- 후속 작업: <없음 또는 파일 위치 기준 Markdown 링크(예: [Milestone 이름](../next-milestone.md))/태스크 이름>
-- 확인 필요: <없음 | `구현 잠금 > 결정 필요` 또는 SDD USER_REVIEW.md로 분리할 항목>
+- 확인 필요: <없음 | `구현 잠금 > 결정 필요` 또는 [USER_REVIEW.md](../../../sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md)로 분리할 항목>

agent-ops/skills/common/_templates/roadmap-phase-template.md

@@ -15,7 +15,7 @@
 스케치 Milestone은 아직 구현 가능한 계획이 아니므로 계획 Milestone보다 아래에 둔다.
 
 - [<스케치 | 계획 | 진행중 | 검토중 | 완료 | 보류 | 폐기>] <Milestone 이름>
-  - 경로: `agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md` 또는 `agent-roadmap/archive/phase/<phase-slug>/milestones/<milestone-slug>.md`
+  - 경로: [<Milestone 이름>](milestones/<milestone-slug>.md) 또는 [archive <Milestone 이름>](../../archive/phase/<phase-slug>/milestones/<milestone-slug>.md)
   - 요약: <목표 또는 결과 1문장>
 
 ## Phase 경계

agent-ops/skills/common/_templates/roadmap-position-report-template.md

@@ -1,16 +1,18 @@
 # 로드맵 현지점
 
+<!-- 링크 target의 <...-path> placeholder는 실제 출력 시 repo root 기준 상대경로로 치환한다. -->
+
 - [local current.md](agent-roadmap/current.md)
 
 - [로드맵: <roadmap-name>](agent-roadmap/ROADMAP.md)
   - [Phase: <phase-name>](agent-roadmap/phase/<phase-slug>/PHASE.md)
     - [Milestone: <milestone-name>](agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md)
       - [<상태>] <목표 또는 역할 한 줄>
-      - SDD: <없음 | [SDD.md](agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md) | 경로만 있음: `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md`>
+      - SDD: <없음 | [SDD.md](agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md) | [SDD.md](agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md) (파일 없음)>
       - 사용자 리뷰: <없음 | [USER_REVIEW.md](agent-roadmap/sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md)>
     - [Milestone: <milestone-name>](agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md)
       - [<상태>] <목표 또는 역할 한 줄>
-      - SDD: <없음 | [SDD.md](agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md) | 경로만 있음: `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md`>
+      - SDD: <없음 | [SDD.md](agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md) | [SDD.md](agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md) (파일 없음)>
       - 사용자 리뷰: <없음 | [USER_REVIEW.md](agent-roadmap/sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md)>
 
 ## 전체 Phase 흐름
@@ -22,8 +24,8 @@
 ## 현재 Phase의 Milestone 흐름
 
 - [<상태>] [<Milestone 이름>](<milestone-path>) ← 현재 후보, <역할 태그>
-  - SDD: <없음 | [SDD.md](<sdd-path>) | 경로만 있음: `<sdd-path>`>
+  - SDD: <없음 | [SDD.md](<sdd-path>) | [SDD.md](<sdd-path>) (파일 없음)>
   - 사용자 리뷰: <없음 | [USER_REVIEW.md](<user-review-path>)>
 - [<상태>] [<Milestone 이름>](<milestone-path>) ← 현재 후보, <역할 태그>
-  - SDD: <없음 | [SDD.md](<sdd-path>) | 경로만 있음: `<sdd-path>`>
+  - SDD: <없음 | [SDD.md](<sdd-path>) | [SDD.md](<sdd-path>) (파일 없음)>
   - 사용자 리뷰: <없음 | [USER_REVIEW.md](<user-review-path>)>

agent-ops/skills/common/_templates/roadmap-sdd-template.md

@@ -2,8 +2,8 @@
 
 ## 위치
 
-- Milestone: `agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md`
+- Milestone: [Milestone 문서](../../../phase/<phase-slug>/milestones/<milestone-slug>.md)
-- Phase: `agent-roadmap/phase/<phase-slug>/PHASE.md`
+- Phase: [PHASE.md](../../../phase/<phase-slug>/PHASE.md)
 
 ## 상태
 
@@ -12,7 +12,7 @@
 ## SDD 잠금
 
 - 상태: <잠금 | 해제>
-- 사용자 리뷰: <없음 | `USER_REVIEW.md`>
+- 사용자 리뷰: <없음 | [USER_REVIEW.md](USER_REVIEW.md)>
 - 잠금 항목:
   - [ ] [D01] <사용자만 결정할 source of truth, 상태 전이, 책임 경계, 범위, 권한, 비용, 실패 처리 항목>
 
@@ -26,7 +26,7 @@
 
 | 영역 | 기준 | 메모 |
 |------|------|------|
-| Roadmap | `<path>` | <장기 원장, 상태 반영 기준> |
+| Roadmap | [Milestone 문서](../../../phase/<phase-slug>/milestones/<milestone-slug>.md) | <장기 원장, 상태 반영 기준> |
 | Code | `<path>` | <구현 source of truth> |
 | External Provider | <없음 또는 provider> | <provider id/revision/status 기준> |
 | User Decision | <없음 또는 D-id> | <사용자 결정이 필요한 기준> |
@@ -39,7 +39,7 @@
 
 ## Interface Contract
 
-- 계약 원문: <없음 또는 `agent-contract/...` 링크>
+- 계약 원문: <없음 또는 [계약 문서](../../../../agent-contract/...)>
 - 입력:
   - <field>: <의미>
 - 출력:
@@ -82,4 +82,4 @@
 ## 작업 컨텍스트
 
 - 표준선: <기존 구조, 도메인 rule, 플랫폼 관례>
-- 후속 SDD: <없음 또는 SDD 경로>
+- 후속 SDD: <없음 또는 [SDD.md](../<other-milestone-slug>/SDD.md)>

agent-ops/skills/common/_templates/roadmap-sdd-user-review-template.md

@@ -6,8 +6,8 @@
 
 ## 검토 대상
 
-- SDD: `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md`
+- SDD: [SDD.md](SDD.md)
-- Milestone: `agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md`
+- Milestone: [Milestone 문서](../../../phase/<phase-slug>/milestones/<milestone-slug>.md)
 
 ## 사용자 결정 항목
 

agent-ops/skills/common/_templates/roadmap-template.md

@@ -12,30 +12,30 @@
 스케치 Phase는 아직 구현 가능한 계획이 아니므로 계획 Phase보다 아래에 둔다.
 
 - [<스케치 | 계획 | 진행중 | 검토중 | 완료 | 보류 | 폐기>] <Phase 이름>
-  - 경로: `agent-roadmap/phase/<phase-slug>/PHASE.md` 또는 `agent-roadmap/archive/phase/<phase-slug>/PHASE.md`
+  - 경로: [PHASE.md](phase/<phase-slug>/PHASE.md) 또는 [archive PHASE.md](archive/phase/<phase-slug>/PHASE.md)
   - 요약: <이 Phase의 목표와 역할 1문장>
 
 ## 로딩 정책
 
-- 일반 작업에서는 `agent-roadmap/ROADMAP.md`를 매번 읽지 않는다.
+- 일반 작업에서는 [ROADMAP.md](ROADMAP.md)를 매번 읽지 않는다.
-- 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 `agent-roadmap/current.md`를 먼저 읽는다.
+- 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 [current.md](current.md)를 먼저 읽는다.
 - `current.md`는 현재 작업 위치가 아니라 활성 Phase와 활성 Milestone 후보 목록이다.
 - `current.md`는 브랜치별 로컬 포인터이며 git 추적 대상이 아니다. 로드맵 기반 계획/갱신에서 없으면 `agent-ops/skills/common/_templates/roadmap-current-template.md` 형식으로 생성해 사용하고, 읽기 전용 현지점 확인에서는 생성하지 않는다.
 - `current.md`에는 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다.
-- `current.md`의 활성 Phase는 `agent-roadmap/phase/<phase-slug>/PHASE.md`를 가리킨다.
+- `current.md`의 활성 Phase는 [PHASE.md](phase/<phase-slug>/PHASE.md)를 가리킨다.
-- `current.md`의 활성 Milestone은 `agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md`를 가리킨다.
+- `current.md`의 활성 Milestone은 [Milestone 문서](phase/<phase-slug>/milestones/<milestone-slug>.md)를 가리킨다.
 - `current.md`는 `agent-roadmap/archive/**` 경로를 활성 항목으로 포함하지 않는다.
 - 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 활성 Phase와 Milestone 문서를 같은 세션에서 1회 읽는다.
 - 활성 Phase 또는 Milestone 밖의 작업이면 이 문서의 Phase 흐름을 확인하고 범위 충돌을 보고한다. 제품/범위 결정이 필요하면 대상 Milestone의 `구현 잠금 > 결정 필요` 또는 SDD `USER_REVIEW.md`로 분리한다.
 - 이 문서는 로드맵 생성/갱신, Phase 전환, Phase 추가/수정, 전체 구조 변경 요청이 있을 때만 읽는다.
 - 상세 작업은 각 Milestone 문서의 `기능`으로 관리한다. 검증이 필요한 기능만 같은 Task 안에 `검증:`으로 통합한다.
-- 큰 Milestone의 설계 게이트는 `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md`에 두고, Milestone `구현 잠금`의 SDD 조건과 연결한다.
+- 큰 Milestone의 설계 게이트는 [SDD.md](sdd/<phase-slug>/<milestone-slug>/SDD.md)에 두고, Milestone `구현 잠금`의 SDD 조건과 연결한다.
-- SDD 사용자 리뷰가 필요하면 `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md`로 남기며, 해결 후 `user_review_N.log`로 보존한다.
+- SDD 사용자 리뷰가 필요하면 [USER_REVIEW.md](sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md)로 남기며, 해결 후 `user_review_N.log`로 보존한다.
 - `[스케치]` Phase/Milestone은 방향성, 문제의식, 후보 범위, 미정 질문을 기록하는 컨셉 상태이며 구현 계획 생성 대상이 아니다.
 - `[스케치]` 항목은 `승격 조건`을 정리해 `[계획]`으로 전환한 뒤 구현 계획을 만든다.
 - 모든 기능 Task와 Task 안에 명시된 검증이 충족되고 `구현 잠금`이 해제된 Milestone은 먼저 `[검토중]`으로 두고, 완료 근거와 archive 조건이 정리되면 `[완료]`로 전환한다.
-- 완료된 Phase는 `agent-roadmap/archive/phase/<phase-slug>/PHASE.md`로 이동하고, 하위 Milestone도 같은 archive Phase scaffold 아래에 둔다.
+- 완료된 Phase는 [archive PHASE.md](archive/phase/<phase-slug>/PHASE.md)로 이동하고, 하위 Milestone도 같은 archive Phase scaffold 아래에 둔다.
-- 진행중 Phase 안에서 완료된 Milestone은 활성 Phase 문서에 짧은 링크를 남기고, 상세 문서는 `agent-roadmap/archive/phase/<phase-slug>/milestones/`로 이동한다.
+- 진행중 Phase 안에서 완료된 Milestone은 활성 Phase 문서에 짧은 링크를 남기고, 상세 문서는 [archive milestones](archive/phase/<phase-slug>/milestones/)로 이동한다.
 - archive `PHASE.md`는 Phase 자체가 완료 또는 폐기될 때만 만들며, 진행중 Phase의 완료 Milestone만 archive된 경우 archive Phase 디렉터리에 `milestones/`만 있을 수 있다.
 - `agent-roadmap/archive/**`는 일반 작업에서 읽지 않는다. 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `ROADMAP.md` 또는 `PHASE.md`의 archive 링크를 따라가서 읽는다.
 - 아카이브된 Phase/Milestone 문서는 최신 템플릿이나 스킬 규약에 맞춰 재포맷하지 않는다.

agent-ops/skills/common/analyze-roadmap-position/SKILL.md

@@ -27,7 +27,7 @@ description: "여러 레포를 전환할 때 코드/git 분석 없이 전체 ROA
 - [ ] 로드맵이 있으면 `ROADMAP.md`의 `Phase 흐름`을 확인
 - [ ] 로컬 `current.md`의 활성 Phase와 활성 Milestone 이름, 상태, 경로 확인
 - [ ] 활성 Phase 문서의 `Milestone 흐름` 확인
-- [ ] 활성 Milestone 문서의 제목, `목표`, `상태`, `구현 잠금`의 SDD 문서 경로만 확인
+- [ ] 활성 Milestone 문서의 제목, `목표`, `상태`, `구현 잠금`의 SDD 문서 링크/경로만 확인
 
 ## 실행 절차
 
@@ -43,10 +43,10 @@ description: "여러 레포를 전환할 때 코드/git 분석 없이 전체 ROA
 5. current의 활성 Phase 경로를 열고 `Milestone 흐름`을 읽는다.
    - 각 Milestone은 상태, 이름, 링크만 남긴다.
    - current의 활성 Milestone과 일치하는 항목에 `← 현재 후보` 표시를 붙인다.
-6. current의 활성 Milestone 문서를 열고 제목, `목표`, `상태`, `구현 잠금`의 SDD 문서 경로만 읽는다.
+6. current의 활성 Milestone 문서를 열고 제목, `목표`, `상태`, `구현 잠금`의 SDD 문서 링크/경로만 읽는다.
-   - `SDD 문서` 경로가 있고 해당 `SDD.md` 파일이 존재하면 Milestone 아래에 `SDD: [SDD.md](<sdd-path>)`로 출력한다.
+   - `SDD 문서` 링크/경로가 있고 해당 `SDD.md` 파일이 존재하면 Milestone 아래에 `SDD: [SDD.md](<sdd-path>)`로 출력한다.
-   - `SDD 문서` 경로는 있으나 해당 파일이 없으면 Milestone 아래에 `SDD: 경로만 있음: <sdd-path>` 형식으로 출력한다.
+   - `SDD 문서` 링크/경로는 있으나 해당 파일이 없으면 Milestone 아래에 `SDD: [SDD.md](<sdd-path>) (파일 없음)` 형식으로 출력한다.
-   - `SDD 문서` 경로가 없거나 `SDD: 불필요`이면 Milestone 아래에 `SDD: 없음`으로 출력한다.
+   - `SDD 문서` 링크/경로가 없거나 `SDD: 불필요`이면 Milestone 아래에 `SDD: 없음`으로 출력한다.
    - `SDD.md`와 같은 디렉터리에 `USER_REVIEW.md`가 있으면 Milestone 아래에 `사용자 리뷰: [USER_REVIEW.md](<user-review-path>)`로 출력하고, 없으면 `사용자 리뷰: 없음`으로 출력한다.
    - SDD 상태, 잠금, 승인 여부를 역할 태그나 상태 요약으로 출력하지 않는다. 필요한 독자는 출력된 SDD 링크를 열어 확인하게 한다.
    - SDD 본문은 읽지 않는다.
@@ -56,8 +56,9 @@ description: "여러 레포를 전환할 때 코드/git 분석 없이 전체 ROA
 ## 실행 결과 검증
 
 - [ ] `roadmap-position-report-template.md`의 출력 구조를 유지했는가
-- [ ] 로컬 `current.md`, `ROADMAP.md`, 활성 `PHASE.md`, 활성 Milestone의 제목/목표/상태/SDD 문서 경로만 기본으로 읽었는가
+- [ ] 로컬 `current.md`, `ROADMAP.md`, 활성 `PHASE.md`, 활성 Milestone의 제목/목표/상태/SDD 문서 링크/경로만 기본으로 읽었는가
 - [ ] 현재 후보 Milestone 아래에 SDD와 사용자 리뷰를 링크 또는 `없음`으로 출력했는가
+- [ ] Phase, Milestone, SDD, 사용자 리뷰 등 모든 문서 포인터가 raw path만 남지 않고 Markdown 링크로 출력되었는가
 - [ ] SDD 상태, 잠금, 승인 여부를 역할 태그나 상태 요약으로 출력하지 않았는가
 - [ ] 완료 또는 archive Phase/Milestone은 링크만 표시하고 archive 문서를 읽지 않았는가
 - [ ] current가 여러 Milestone을 가리키면 모두 `현재 후보`로 표시했는가
@@ -68,10 +69,12 @@ description: "여러 레포를 전환할 때 코드/git 분석 없이 전체 ROA
 
 - 템플릿 경로: `agent-ops/skills/common/_templates/roadmap-position-report-template.md`
 - 템플릿을 그대로 복사해 placeholder를 채운다.
+- 출력에는 `<phase-path>`, `<milestone-path>`, `<sdd-path>`, `<user-review-path>` placeholder를 그대로 남기지 않고 실제 repo root 기준 상대 링크 target으로 치환한다.
 - 섹션 제목과 필드명을 임의로 번역, 축약, 삭제하지 않는다.
 - current가 여러 Milestone을 가리키면 breadcrumb와 Milestone 흐름에 모두 표시한다.
 - 현재 후보의 역할 태그는 `선행 스케치`, `다음 구현 계획`, `검토 후보`, `보류 후보`처럼 짧게 쓰되 SDD 상태를 역할 태그에 넣지 않는다.
-- 현재 후보에 `SDD 문서` 경로가 있으면 Milestone 아래에 SDD 링크를 배치한다. `USER_REVIEW.md`가 있으면 그 링크도 SDD 아래에 배치한다.
+- 현재 후보에 `SDD 문서` 링크/경로가 있으면 Milestone 아래에 SDD 링크를 배치한다. `USER_REVIEW.md`가 있으면 그 링크도 SDD 아래에 배치한다.
+- 문서 포인터는 항상 `[표시 제목](상대경로)` Markdown 링크로 출력한다. 파일이 없어도 raw path만 쓰지 말고 `[SDD.md](<sdd-path>) (파일 없음)`처럼 링크와 상태를 함께 쓴다.
 - 로드맵이 없는 프로젝트에서는 로드맵 없음으로 짧게 보고하고 템플릿을 억지로 채우지 않는다.
 
 ## 금지 사항

agent-ops/skills/common/check-roadmap-dependency/SKILL.md

@@ -59,6 +59,7 @@ Milestone identity 역검색과 개별 lock 판별은 `agent-ops/bin/roadmap-dep
    - stdout `false`와 exit code `1`은 아직 충족되지 않은 의존 조건이 있음을 보고한다.
    - exit code `2`는 설정 오류, 입력 오류, 필수 필드 누락, 파싱 오류로 보고한다.
    - `rely-on` 방향에서 대상 Milestone이 `[검토중]` 또는 `[완료]`인데 status가 `disable`이면 `update-roadmap` 동기화가 필요한 stale lock으로 보고한다. 이 스킬은 status를 바꾸지 않는다.
+   - 사용자-facing 결과에 대상 Milestone 문서를 표시할 수 있으면 identity raw 값만 쓰지 말고 `[Milestone 문서](agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md)` 링크를 함께 보고한다.
 
 ## 실행 결과 검증
 
@@ -68,6 +69,7 @@ Milestone identity 역검색과 개별 lock 판별은 `agent-ops/bin/roadmap-dep
 - [ ] lock id가 없을 때 대상 Milestone을 `locked`와 `rely-on.target` 양쪽에서 찾았는가
 - [ ] `locks.yaml`이 없는 경우 `false`가 아니라 `error`로 보고했는가
 - [ ] 이 스킬이 `locks.yaml`이나 roadmap 문서를 수정하지 않았는가
+- [ ] 대상 Milestone 문서를 표시할 수 있으면 Markdown 링크로 함께 보고했는가
 - 검증 실패 시: 오류 메시지와 사용한 `lock-id`, `locks-file` 경로를 보고하고 멈춘다.
 
 ## 출력 형식
@@ -76,6 +78,7 @@ Milestone identity 역검색과 개별 lock 판별은 `agent-ops/bin/roadmap-dep
 ## 의존성 판별 결과
 
 - target-milestone: `<identity | 해당 없음>`
+- target-document: <[Milestone 문서](agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md) | 해당 없음>
 - direction: `<locked | rely-on | both>`
 - locks-file: `<locks-file>`
 - 결과: `<true | false | error | no-lock>`

agent-ops/skills/common/code-review/templates/complete-log-template.md

@@ -28,6 +28,7 @@
 {optional; include only when archived plan/review had Roadmap Targets. Remove this entire section when there are no Roadmap Targets.}
 
 - Milestone: `{agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md}`
+- Milestone link: [Milestone 문서](agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md)
 - Completed task ids:
   - `{task-id}`: PASS; evidence=`{archived-plan-log}`, `{archived-review-log}`; verification=`{command or saved output path}`
 - Not completed task ids: 없음

agent-ops/skills/common/create-roadmap/SKILL.md

@@ -91,6 +91,11 @@ agent-roadmap/
 - Milestone 파일명은 `agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md`로 만든다.
 - `<phase-slug>`와 `<milestone-slug>`는 소문자 영문, 숫자, 하이픈만 사용하고, 공백/언더스코어/순번 prefix를 넣지 않는다.
 - 중간에 Phase나 Milestone을 끼워 넣을 수 있도록 기존 항목의 이름과 파일명을 불필요하게 바꾸지 않는다.
+- 로드맵 문서 안에서 다른 로드맵 문서, SDD, `USER_REVIEW.md`, archive 문서를 가리킬 때는 raw path만 쓰지 말고 `[표시 제목](상대경로)` Markdown 링크로 쓴다.
+- 문서 안의 링크 target은 링크를 작성하는 Markdown 파일 위치 기준 상대경로로 쓴다. 예: `ROADMAP.md`와 `current.md`에서는 `[PHASE.md](phase/<phase-slug>/PHASE.md)`, Phase 문서에서는 `[Milestone](milestones/<milestone-slug>.md)`, Milestone 문서에서는 `[ROADMAP.md](../../../ROADMAP.md)`와 `[PHASE.md](../PHASE.md)`를 쓴다.
+- `경로:`, `Phase:`, `Milestone:`, `SDD 문서:` 같은 필드명을 유지해야 해도 값은 `경로: [PHASE.md](phase/<phase-slug>/PHASE.md)`처럼 링크로 작성한다.
+- 실제 생성한 로드맵 문서에는 `<phase-slug>`, `<milestone-slug>`, `<relative-...>` 같은 placeholder가 들어간 링크 target을 남기지 않는다. 템플릿 placeholder는 실제 파일 위치 기준 상대경로 또는 `없음`으로 치환한다.
+- 코드 경로, 명령 입력, `.agent-roadmap-sync/locks.yaml`의 machine-readable identity는 raw 값이 필요하면 유지할 수 있지만, 사용자에게 보여주는 문서 포인터에는 Markdown 링크를 함께 둔다.
 
 ## Milestone 작성 규칙
 
@@ -103,8 +108,8 @@ agent-roadmap/
 - `구현 잠금`에는 상태, SDD 필요 여부, 잠금 해제 조건, `결정 필요` 체크리스트를 적는다. 결정할 항목이 없으면 `결정 필요: 없음`으로 적는다.
 - SDD가 필요한 기준: cross-repo 계약, 외부 provider 쓰기, 상태 머신/lifecycle, idempotency/retry/identity map, API/proto/config/env/schema 변경, field smoke, 사용자 승인 gate 영향.
 - SDD가 불필요한 기준: 단일 repo 내부의 작은 리팩터링, 문서 정리, 테스트 보강, 작은 UI 보강, Milestone Task `검증:`만으로 닫히는 작업.
-- SDD가 필요한 Milestone은 `SDD 문서` 경로를 `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md`로 적고, SDD 잠금이 해제될 때까지 `구현 잠금`을 `잠금`으로 둔다.
+- SDD가 필요한 Milestone은 `SDD 문서` 값을 해당 Milestone 파일 위치 기준 `[SDD.md](../../../sdd/<phase-slug>/<milestone-slug>/SDD.md)` Markdown 링크로 적고, SDD 잠금이 해제될 때까지 `구현 잠금`을 `잠금`으로 둔다.
-- 로드맵 생성 흐름에서 SDD가 필요한 신규 Milestone은 SDD 경로만 남기지 않고 해당 경로에 SDD 초안을 만든다.
+- 로드맵 생성 흐름에서 SDD가 필요한 신규 Milestone은 SDD 문서 링크만 남기지 않고 해당 파일에 SDD 초안을 만든다.
 - 새 Milestone이 다른 프로젝트 Milestone 완료 전까지 잠겨야 하면 `구현 잠금`을 `잠금`으로 두고 프로젝트 상위 `.agent-roadmap-sync/locks.yaml`에 entry를 만든다. 의존 대상 확정과 entry 형식은 `update-roadmap`의 프로젝트 간 잠금 규칙을 따른다.
 - `기능`은 Epic heading과 Task 체크리스트로 작성한다.
 - Epic heading은 `### Epic: [epic-id] <이름>` 형식으로 작성한다.
@@ -152,18 +157,20 @@ agent-roadmap/
    - 완료된 Phase가 초기 구조에 포함되어야 하는 경우 `archive/phase/<phase-slug>/PHASE.md`로 만들고 `ROADMAP.md`에서 archive 경로를 가리킨다.
    - 완료된 Milestone이 진행중 Phase에 포함되어야 하는 경우 `archive/phase/<phase-slug>/milestones/<milestone-slug>.md`로 만들고 해당 활성 `PHASE.md`에서 archive 경로를 가리킨다.
    - archive `PHASE.md`는 Phase 자체가 완료/폐기된 경우에만 만든다. 진행중 Phase의 완료 Milestone만 archive된 경우 archive Phase 디렉터리에 `milestones/`만 둘 수 있다.
-   - SDD가 필요한 Milestone은 `구현 잠금`에 SDD 경로와 잠금 해제 조건을 적고, 같은 흐름에서 `roadmap-sdd`의 `create` 절차를 적용해 `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md` 초안을 만든다.
+   - SDD가 필요한 Milestone은 `구현 잠금`에 해당 Milestone 파일 위치 기준 `SDD 문서` Markdown 링크와 잠금 해제 조건을 적고, 같은 흐름에서 `roadmap-sdd`의 `create` 절차를 적용해 `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md` 초안을 만든다.
    - `roadmap-sdd create` 결과 SDD 결정 항목이 있으면 `roadmap-sdd`의 `review-ready` 절차에 따라 같은 디렉터리에 `USER_REVIEW.md`를 만들고, SDD와 Milestone 구현 잠금을 `잠금`으로 둔다.
    - 외부 의존 잠금이 있으면 프로젝트 상위 `.agent-roadmap-sync/locks.yaml`을 생성하거나 기존 entry를 upsert한다. 의존 대상이 명시 경로, slug, 제목, 문서 힌트, 로컬 current 단일 후보 중 하나로 확정되지 않으면 lock entry를 만들지 않고 TODO로 남긴다.
 
 5. **검증**
    - 생성한 링크가 실제 파일을 가리키는지 확인한다.
+   - 생성한 로드맵 문서의 문서/산출물 포인터가 raw path만 남지 않고 Markdown 링크로 작성되었는지 확인한다.
+   - 생성한 로드맵 문서의 Markdown 링크 target에 템플릿 placeholder가 남지 않았는지 확인한다.
    - 로컬 `current.md` 활성 항목에 `agent-roadmap/archive/**` 경로가 없는지 확인한다.
    - Epic heading과 Task 체크리스트 id가 형식을 따르는지 확인한다.
    - 상태 표기가 `[진행중]`처럼 공백 없는 표준값인지 확인한다.
    - `[스케치]` Milestone에 `승격 조건` 섹션이 있고 `구현 잠금`이 `잠금`인지 확인한다.
    - 각 Milestone의 `구현 잠금`에 `SDD: 필요|불필요`와 판정 사유가 있는지 확인한다.
-   - `SDD: 필요` Milestone은 SDD 경로와 잠금 해제 조건이 있고, 해당 `SDD.md` 파일이 실제 존재하는지 확인한다.
+   - `SDD: 필요` Milestone은 SDD 문서 링크와 잠금 해제 조건이 있고, 해당 `SDD.md` 파일이 실제 존재하는지 확인한다.
    - 생성된 각 `SDD.md`는 `roadmap-sdd`의 `check-gate` 절차로 표준 top-level 섹션, 필수 표 컬럼, SDD 상태, SDD 잠금, `USER_REVIEW.md` 존재 여부, Acceptance Scenario와 Milestone 기능 Task 연결, Evidence Map 연결성을 최종 확인한다.
    - `check-gate` 결과는 `SDD gate` 항목에 `pass`, `review-required`, `blocked`, `invalid` 중 하나로 분리해 남긴다. `review-ready`로 만든 `USER_REVIEW.md` 때문에 막힌 경우는 `review-required`로 보고하고 형식 보완 실패로 보지 않는다.
    - `[검토중]` Milestone이 있다면 `구현 잠금`이 해제되어 있고 미완료 `결정 필요` 항목이 없는지 확인한다.
@@ -175,8 +182,8 @@ agent-roadmap/
 ```markdown
 ## 생성 결과
 
-- 로드맵: agent-roadmap/ROADMAP.md
+- 로드맵: [ROADMAP.md](agent-roadmap/ROADMAP.md)
-- 로컬 현재 컨텍스트: agent-roadmap/current.md
+- 로컬 현재 컨텍스트: [current.md](agent-roadmap/current.md)
 - Phase 문서: <N개>
 - Milestone 문서: <N개>
 - 활성 Phase: <N개>
@@ -189,8 +196,8 @@ agent-roadmap/
 
 ## 활성 항목
 
-- Phase: <phase-name>: agent-roadmap/phase/<phase-slug>/PHASE.md
+- Phase: <phase-name>: [PHASE.md](agent-roadmap/phase/<phase-slug>/PHASE.md)
-- Milestone: <milestone-name>: agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md
+- Milestone: <milestone-name>: [<milestone-name>](agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md)
 
 ## TODO 항목
 

agent-ops/skills/common/plan/SKILL.md

@@ -233,6 +233,7 @@ Required sections:
 ## Roadmap Targets
 
 - Milestone: `agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md`
+- Milestone link: [Milestone 문서](agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md)
 - Task ids:
   - `<task-id>`: <Task text or concise label>
 - Completion mode: check-on-pass

agent-ops/skills/common/roadmap-sdd/SKILL.md

@@ -53,6 +53,10 @@ agent-roadmap/
 - `update`는 기존 SDD의 내용을 갱신하더라도 표준 섹션과 순서를 유지한다. 누락된 표준 섹션이 있으면 먼저 복원한 뒤 변경을 반영한다.
 - `check-gate`는 표준 섹션이나 필수 표 컬럼이 누락된 SDD를 `invalid`로 보고하고, Milestone 구현 잠금 해제 대상으로 보지 않는다.
 - SDD별 추가 설명은 `작업 컨텍스트` 또는 해당 표준 섹션 안에 넣고 임의 top-level 섹션을 늘리지 않는다.
+- SDD 안에서 Milestone, Phase, 계약 문서, `USER_REVIEW.md`, 후속 SDD 같은 문서 포인터를 남길 때는 raw path만 쓰지 말고 `[표시 제목](상대경로)` Markdown 링크로 쓴다.
+- SDD 링크 target은 `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/` 디렉터리 기준 상대경로로 쓴다. 예: `[Milestone 문서](../../../phase/<phase-slug>/milestones/<milestone-slug>.md)`, `[PHASE.md](../../../phase/<phase-slug>/PHASE.md)`, `[USER_REVIEW.md](USER_REVIEW.md)`.
+- 실제 생성/갱신한 SDD에는 `<phase-slug>`, `<milestone-slug>`, `<path>` 같은 placeholder가 들어간 링크 target을 남기지 않는다. 템플릿 placeholder는 실제 파일 위치 기준 상대경로 또는 `없음`으로 치환한다.
+- 코드 source path나 machine-readable identity는 raw 값이 필요하면 유지할 수 있다.
 
 ## SDD 대상 판정
 
@@ -80,7 +84,7 @@ SDD가 필요한 Milestone은 `구현 잠금`에 아래 필드를 둔다.
 ```md
 - 상태: 잠금
 - SDD: 필요
-- SDD 문서: `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md`
+- SDD 문서: [SDD.md](../../../sdd/<phase-slug>/<milestone-slug>/SDD.md)
 - 잠금 해제 조건:
   - [ ] SDD 잠금이 해제되어 있다
   - [ ] SDD 사용자 리뷰가 없거나 승인/해결되었다
@@ -131,7 +135,7 @@ SDD 문서는 자체 잠금을 가진다.
 1. 관련 Milestone 또는 신규 작업 설명을 읽는다.
 2. SDD 대상 판정 기준을 적용한다.
 3. 결과를 `필요`, `불필요`, `불명확` 중 하나로 보고한다.
-4. `필요`이면 Milestone `구현 잠금`에 SDD 경로와 잠금 해제 조건을 갱신한다.
+4. `필요`이면 Milestone `구현 잠금`에 해당 Milestone 파일 위치 기준 `SDD 문서` Markdown 링크와 잠금 해제 조건을 갱신한다.
 5. 신규 Milestone 생성 또는 `[스케치] -> [계획]` 승격 흐름에서 호출된 경우, `classify`에서 멈추지 않고 같은 턴에 `create`까지 이어간다. 사용자만 결정할 항목이 없으면 승인 가능한 SDD로 만들고, 사용자 결정이 있으면 SDD 초안과 `USER_REVIEW.md`를 함께 만든다.
 
 ### create
@@ -192,11 +196,11 @@ SDD 문서는 자체 잠금을 가진다.
 ## SDD 결과
 
 - mode: `<classify|create|update|check-gate|review-ready|resolve-review|archive>`
-- milestone: `<path>`
+- milestone: <[Milestone 문서](agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md) | 해당 없음>
-- sdd: `<path | 없음>`
+- sdd: <[SDD.md](agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md) | 없음>
 - 결과: `<pass | blocked | not-required | created | updated | review-required | archived | invalid>`
 - 잠금: `<해제 | 잠금 | 해당 없음>`
-- 사용자 리뷰: `<없음 | USER_REVIEW.md | user_review_N.log>`
+- 사용자 리뷰: <없음 | [USER_REVIEW.md](agent-roadmap/sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md) | [user_review_N.log](agent-roadmap/sdd/<phase-slug>/<milestone-slug>/user_review_N.log)>
 - 다음 단계: `<없음 | 사용자 리뷰 필요 | Milestone 구현 잠금 해제 가능 | SDD 작성 필요>`
 ```
 

agent-ops/skills/common/sync-milestone-workstate/SKILL.md

@@ -51,7 +51,7 @@ description: 현 마일스톤과 작업현황 동기화, 현재 마일스톤 작
    - Milestone `기능` 섹션의 Task id만 완료 후보로 본다.
    - Task id는 `- [ ] [item-id]` 또는 `- [x] [item-id]` 형식에서 추출한다.
    - 각 Task의 설명과 `검증:` 문구를 기록한다.
-   - `구현 잠금`의 상태, `결정 필요`, `SDD: 필요|불필요`, SDD 경로를 확인한다.
+   - `구현 잠금`의 상태, `결정 필요`, `SDD: 필요|불필요`, SDD 문서 링크/경로를 확인한다.
    - `작업 컨텍스트`의 관련 경로, Milestone 범위, Task 설명의 코드/문서 키워드를 evidence scope로 삼는다.
    - 관련 경로가 전혀 없으면 Task 설명에서 검색어를 만들되, 후보가 넓거나 모호하면 Task를 자동 완료하지 않고 scope 불명확으로 보고한다.
 
@@ -115,6 +115,7 @@ description: 현 마일스톤과 작업현황 동기화, 현재 마일스톤 작
    - 읽은 active/archive `complete.log` 후보 수, 확인한 관련 파일/git 범위, 반영한 Task id를 보고한다.
    - 반영하지 않은 `complete.log`나 Task가 있으면 이유를 보고한다.
    - SDD gate, 완료 리뷰, Workspace lock, 남은 미완료 Task, 검토 필요 Task를 보고한다.
+   - 대상 Milestone, 수정 파일, `complete.log`, SDD, 사용자 리뷰 같은 문서/산출물 포인터는 raw path만 쓰지 말고 `[표시 제목](상대경로)` Markdown 링크로 보고한다.
 
 ## 실행 결과 검증
 
@@ -131,6 +132,7 @@ description: 현 마일스톤과 작업현황 동기화, 현재 마일스톤 작
 - [ ] Phase `PHASE.md`와 `agent-roadmap/current.md`의 상태 라벨이 Milestone 본문과 일치하는가
 - [ ] `[검토중]` 전환만 수행하고 `[완료]` 전환 또는 archive 이동을 하지 않았는가
 - [ ] `.agent-roadmap-sync/locks.yaml`이 있으면 관련 lock 여부와 필요한 `rely-on.status` 동기화를 결과에 반영했는가
+- [ ] 결과 보고의 문서/산출물 포인터가 raw path만 남지 않고 Markdown 링크로 작성되었는가
 - [ ] `git diff --check`를 실행했는가
 - 검증 실패 시: 파일을 추가로 추정 수정하지 말고 실패한 항목, 차단 사유, 필요한 evidence 경로를 보고한다.
 
@@ -139,10 +141,10 @@ description: 현 마일스톤과 작업현황 동기화, 현재 마일스톤 작
 ```markdown
 ## 동기화 완료
 
-- 대상 Milestone: <path>
+- 대상 Milestone: [<milestone-name>](agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md)
 - 모드: <sync | check-only>
 - 수정 파일:
-  - <path 또는 없음>
+  - <없음 | [문서명](path)>
 
 ## 반영 내용
 
@@ -152,9 +154,9 @@ description: 현 마일스톤과 작업현황 동기화, 현재 마일스톤 작
 - 검토 필요 Task: <id 목록 또는 없음>
 - complete.log 후보: active <N>개, archive <N>개
 - 반영한 complete.log:
-  - <path>
+  - <[complete.log](path)>
 - 반영 제외 complete.log:
-  - <path> - <사유>
+  - <[complete.log](path)> - <사유>
 - 파일/git evidence:
   - <task-id 또는 범위> - <파일/커밋/검증 요약>
 - SDD gate: <불필요 | 충족 | 차단: 사유>

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

@@ -132,6 +132,16 @@ agent-roadmap/
 - SDD: `agent-ops/skills/common/_templates/roadmap-sdd-template.md`
 - SDD 사용자 리뷰: `agent-ops/skills/common/_templates/roadmap-sdd-user-review-template.md`
 
+## 링크 표기
+
+- 사용자에게 보여주는 결과 보고와 새로 생성/갱신하는 로드맵 문서에서 `ROADMAP.md`, `current.md`, `PHASE.md`, Milestone 문서, SDD, `USER_REVIEW.md`, archive 문서, `complete.log` 같은 문서/산출물 포인터는 raw path만 쓰지 말고 `[표시 제목](상대경로)` Markdown 링크로 쓴다.
+- 로드맵 문서 안의 링크 target은 링크를 작성하는 Markdown 파일 위치 기준 상대경로로 쓴다. 예: `ROADMAP.md`와 `current.md`에서는 `[PHASE.md](phase/<phase-slug>/PHASE.md)`, Phase 문서에서는 `[Milestone](milestones/<milestone-slug>.md)`, Milestone 문서에서는 `[ROADMAP.md](../../../ROADMAP.md)`와 `[PHASE.md](../PHASE.md)`를 쓴다.
+- 채팅 결과 보고처럼 저장 위치가 없는 출력은 repo root 기준 상대경로를 쓸 수 있다. 예: `[PHASE.md](agent-roadmap/phase/<phase-slug>/PHASE.md)`.
+- `경로:`, `Phase:`, `Milestone:`, `SDD 문서:`, `수정 파일:` 같은 필드명을 유지해야 해도 값은 Markdown 링크로 작성한다.
+- 실제 갱신한 활성 로드맵 문서에는 `<phase-slug>`, `<milestone-slug>`, `<relative-...>` 같은 placeholder가 들어간 링크 target을 남기지 않는다. 템플릿 placeholder는 실제 파일 위치 기준 상대경로 또는 `없음`으로 치환한다.
+- 기존 문서에 남아 있는 raw path나 backtick path는 읽기/마이그레이션 입력으로 허용한다. 갱신 범위에 포함된 활성 문서 포인터만 Markdown 링크로 보정하고, archive 스냅샷은 링크 표기만을 이유로 재포맷하지 않는다.
+- `.agent-roadmap-sync/locks.yaml`의 `locked`, `rely-on.target`, Milestone identity(`<project>:agent-roadmap/...`), 명령 입력값처럼 machine-readable 계약 값은 raw 값을 유지할 수 있다. 다만 사용자-facing 설명에는 가능한 경우 별도 Markdown 문서 링크를 함께 붙인다.
+
 ## 구현 잠금
 
 - `구현 잠금`은 승인 절차가 아니라 에이전트가 확정할 수 없는 결정이 필요한지 표시하는 얇은 상태다.
@@ -141,8 +151,8 @@ agent-roadmap/
 - `구현 잠금` 섹션이 없거나, 상태가 `잠금`이거나, 미완료 `결정 필요` 항목이 하나라도 있으면 실구현 계획, 코드 구현, Milestone 완료 후보 전환을 차단한다.
 - 잠금 상태에서 허용되는 갱신은 잠금 해소, SDD gate 처리, 범위 제외/후속 Milestone 이동, 작업 컨텍스트 정리 같은 roadmap-only 변경뿐이다.
 - 남은 `결정 필요` 항목이 현재 Milestone 실구현 범위가 아니면 먼저 그 항목을 `범위 제외`, 후속 Milestone, 또는 `작업 컨텍스트`로 옮긴 뒤 `구현 잠금`을 `해제`한다. 잠금 해제 전에는 기능 Task 완료 근거가 있어도 `[검토중]`으로 올리지 않는다.
-- SDD gate가 필요한 Milestone은 `구현 잠금`에 `SDD: 필요`, SDD 경로, 잠금 해제 조건을 남기고 SDD 잠금이 해제될 때까지 `잠금`으로 둔다.
+- SDD gate가 필요한 Milestone은 `구현 잠금`에 `SDD: 필요`, 해당 Milestone 파일 위치 기준 `SDD 문서` Markdown 링크, 잠금 해제 조건을 남기고 SDD 잠금이 해제될 때까지 `잠금`으로 둔다.
-- 새 Milestone을 만들거나 `[스케치]`를 `[계획]`으로 승격하면서 `SDD: 필요`로 판정한 경우, 같은 `update-roadmap` 흐름 안에서 `roadmap-sdd create`까지 수행해 `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md`를 만든다. `SDD: 필요`와 SDD 경로만 남기고 파일이 없는 상태로 종료하지 않는다.
+- 새 Milestone을 만들거나 `[스케치]`를 `[계획]`으로 승격하면서 `SDD: 필요`로 판정한 경우, 같은 `update-roadmap` 흐름 안에서 `roadmap-sdd create`까지 수행해 `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md`를 만든다. `SDD: 필요`와 SDD 문서 링크만 남기고 파일이 없는 상태로 종료하지 않는다.
 - SDD 작성에 필요한 목표, 범위, 기능 Task, Acceptance Scenario 후보를 이미 판단했고 사용자만 결정할 항목이 없으면 SDD 상태를 `[승인됨]`, SDD 잠금을 `해제`로 두고 Milestone `구현 잠금`도 `해제`한다.
 - 사용자만 결정할 항목이 있으면 SDD 초안을 만들고 `roadmap-sdd review-ready` 방식으로 `USER_REVIEW.md`를 남긴다. 이 경우 Milestone `구현 잠금`은 `잠금`으로 둔다.
 - SDD 파일을 만들 수 없는 예외는 사용자가 명시적으로 SDD 생성을 뒤로 미룬 경우뿐이다. 이때 결과 보고에 `SDD gate: 필요-작성 전`과 구체적인 지연 사유를 남긴다.
@@ -336,7 +346,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
    - 로컬 `current.md`의 활성 Phase와 활성 Milestone 후보를 확인한다.
    - target이 명시된 경우 대상 Phase의 `PHASE.md`를 읽고 Milestone 흐름과 Phase 경계를 확인한다.
    - target이 없거나 활성 창 밖 배치 가능성이 있으면 `ROADMAP.md`의 Phase 흐름을 확인하고, 관련성이 높은 Phase 문서를 읽는다.
-   - 대상 또는 후보 Milestone 문서의 목표, 상태, 승격 조건, 범위, 기능 Task, 완료 리뷰, 범위 제외, 구현 잠금을 확인한다. SDD가 필요한 Milestone이면 SDD 경로와 사용자 리뷰 상태도 확인한다. 기존 문서에 `필수 기능`/`완료 기준`이 분리되어 있으면 갱신 범위에서 `기능` Task로 흡수할 후보를 기록한다.
+   - 대상 또는 후보 Milestone 문서의 목표, 상태, 승격 조건, 범위, 기능 Task, 완료 리뷰, 범위 제외, 구현 잠금을 확인한다. SDD가 필요한 Milestone이면 SDD 문서 링크와 사용자 리뷰 상태도 확인한다. 기존 문서에 `필수 기능`/`완료 기준`이 분리되어 있으면 갱신 범위에서 `기능` Task로 흡수할 후보를 기록한다.
    - Phase -> Milestone -> Epic -> Task 순서로 내려가며 같은 레벨의 동일/유사 후보를 먼저 찾는다.
    - 로컬 `current.md`에 archive 경로가 있으면 읽지 말고 제거 대상으로 기록한다.
    - 필요한 경우에만 `ROADMAP.md`를 읽어 전체 Phase 흐름을 확인한다.
@@ -355,7 +365,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
    - `.gitignore`의 Agent-Ops 관리 block에 `agent-roadmap/current.md`가 있는지 확인하고 없으면 추가한다.
    - `PHASE.md`는 Phase 목표, 상태, Milestone 흐름, Phase 경계가 바뀔 때 수정한다.
    - Milestone 문서는 목표, 상태, 승격 조건, 구현 잠금, 범위, Epic/Task, Task 안의 검증 문구, 완료 리뷰, 범위 제외, 작업 컨텍스트가 바뀔 때 수정한다.
-   - 신규 또는 갱신 Milestone이 SDD 대상이면 `구현 잠금`에 `SDD: 필요`, SDD 경로, 잠금 해제 조건을 남기고 같은 흐름에서 `roadmap-sdd create`로 SDD 본문을 작성한다. 사용자 결정이 필요 없고 gate가 충족되면 SDD와 Milestone 잠금을 함께 해제한다.
+   - 신규 또는 갱신 Milestone이 SDD 대상이면 `구현 잠금`에 `SDD: 필요`, 해당 Milestone 파일 위치 기준 `SDD 문서` Markdown 링크, 잠금 해제 조건을 남기고 같은 흐름에서 `roadmap-sdd create`로 SDD 본문을 작성한다. 사용자 결정이 필요 없고 gate가 충족되면 SDD와 Milestone 잠금을 함께 해제한다.
    - SDD 대상이 아니면 `구현 잠금`에 `SDD: 불필요`와 짧은 사유를 남긴다.
    - 동일/유사 후보가 있으면 기존 항목을 업데이트하고 중복 항목을 만들지 않는다.
    - 새 Milestone은 해당 Phase의 `milestones/` 아래에 만든다.
@@ -399,7 +409,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
    - `agent-ui 상태 반영: 대기`인 Milestone을 `[완료]`로 전환하는 경우, 완료 evidence가 가리키는 agent-ui 문서의 status/code evidence 반영 여부와 `validate-agent-ui` 결과가 완료 리뷰에 남았는지 확인한다.
    - `agent-ui 상태 반영: 대기`가 아닌 Milestone 완료 리뷰에서 agent-ui 문서 status를 변경하지 않았는지 확인한다.
    - 각 Milestone의 `구현 잠금`에 SDD 필요 여부와 사유가 있는지 확인한다.
-   - `SDD: 필요` Milestone은 SDD 경로, SDD 파일 존재, 잠금 해제 조건, SDD 사용자 리뷰 상태가 일관되는지 확인한다. 사용자가 명시적으로 SDD 생성을 뒤로 미루지 않았는데 SDD 파일이 없으면 검증 실패로 본다.
+   - `SDD: 필요` Milestone은 SDD 문서 링크, SDD 파일 존재, 잠금 해제 조건, SDD 사용자 리뷰 상태가 일관되는지 확인한다. 사용자가 명시적으로 SDD 생성을 뒤로 미루지 않았는데 SDD 파일이 없으면 검증 실패로 본다.
    - Epic heading과 Task id 형식이 맞는지 확인한다.
    - 요청 규모가 판정되었고 결과 보고에 남았는지 확인한다.
    - 동일/유사 기존 항목을 검색했고 신규/업데이트 판정이 결과 보고에 남았는지 확인한다.
@@ -409,6 +419,8 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
    - 갱신 대상 Milestone identity가 `locked` 또는 `rely-on.target` 어느 쪽에 있든 결과 보고의 `Workspace 잠금`에 반영했는지 확인한다.
    - `locks.yaml`이 있는데 갱신 대상 Milestone identity가 `locked`와 `rely-on.target` 어느 쪽에도 없으면 `Workspace 잠금: 관련 lock 없음`으로 보고했는지 확인한다.
    - archive 모드이면 이동 전 active Milestone identity로 `locks.yaml`을 검사하고 필요한 `rely-on.status` 동기화 또는 `관련 lock 없음` 보고를 수행했는지 확인한다.
+   - 결과 보고와 갱신한 활성 로드맵 문서의 문서/산출물 포인터가 raw path만 남지 않고 Markdown 링크로 작성되었는지 확인한다.
+   - 갱신한 활성 로드맵 문서의 Markdown 링크 target에 템플릿 placeholder가 남지 않았는지 확인한다.
    - `git diff --check`로 공백 오류를 확인한다.
 
 7. **결과 보고**
@@ -434,14 +446,14 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
 
 - 모드: <status | milestone | phase | replan | sync | concretize | archive>
 - 수정 파일:
-  - agent-roadmap/ROADMAP.md
+  - [ROADMAP.md](agent-roadmap/ROADMAP.md)
-  - agent-roadmap/current.md (local)
+  - [current.md](agent-roadmap/current.md) (local)
-  - agent-roadmap/phase/<phase-slug>/PHASE.md
+  - [PHASE.md](agent-roadmap/phase/<phase-slug>/PHASE.md)
-  - agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md
+  - [<milestone-slug>.md](agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md)
-  - agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md (SDD 작성/갱신 시)
+  - [SDD.md](agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md) (SDD 작성/갱신 시)
-  - agent-roadmap/sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md (SDD 사용자 리뷰 요청 시)
+  - [USER_REVIEW.md](agent-roadmap/sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md) (SDD 사용자 리뷰 요청 시)
-  - agent-roadmap/archive/phase/<phase-slug>/... (archive 모드)
+  - [archive PHASE.md](agent-roadmap/archive/phase/<phase-slug>/PHASE.md) 또는 [archive Milestone](agent-roadmap/archive/phase/<phase-slug>/milestones/<milestone-slug>.md) (archive 모드)
-  - agent-roadmap/archive/sdd/<phase-slug>/<milestone-slug>/... (SDD archive 시)
+  - [archive SDD.md](agent-roadmap/archive/sdd/<phase-slug>/<milestone-slug>/SDD.md) (SDD archive 시)
 
 ## 변경 사항
 
@@ -462,7 +474,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
 - runtime m-task 라우팅: <해당 없음 | origin-task -> target Milestone | target 불명확>
 - Workspace 잠금: <변경 없음 | 관련 lock 없음 | entry 생성/갱신 | rely-on enable | rely-on disable | 미충족 | 런타임 해제 대기>
 - 활성 항목: <변경 없음 | Phase/Milestone 추가/제거 요약>
-- 아카이브: <변경 없음 | 이동 경로와 남긴 링크>
+- 아카이브: <변경 없음 | 이동 링크와 남긴 링크>
 - 상태: <변경 없음 | 이전 -> 이후>
 - Epic/Task: <추가/수정/완료/제거 요약>