sync: agent-ops from agentic-framework v1.1.163

agent-ops/.version

@@ -1 +1 @@
-1.1.162
+1.1.163

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

@@ -18,8 +18,9 @@
 ## 링크 표기
 
 - 사용자에게 보여주는 답변과 활성 로드맵 문서의 문서 포인터는 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)`.
+- 로드맵 문서 안의 링크 target은 링크를 작성하는 Markdown 파일 위치 기준 상대경로로 쓴다. 예: `ROADMAP.md`에서는 `[PHASE.md](phase/example-phase/PHASE.md)`, Phase 문서에서는 `[Milestone](milestones/example-milestone.md)`, Milestone 문서에서는 `[ROADMAP.md](../../../ROADMAP.md)`와 `[PHASE.md](../PHASE.md)`를 쓴다.
+- 채팅 결과 보고처럼 저장 위치가 없는 출력은 repo root 기준 상대경로를 쓸 수 있다. 예: `[PHASE.md](agent-roadmap/phase/example-phase/PHASE.md)`.
+- 채팅 결과에 로드맵 문서에서 읽은 링크를 재사용할 때는 원본 Markdown 파일 위치 기준으로 target을 해석한 뒤 repo root 기준 상대경로로 다시 쓴다. 예: `agent-roadmap/current.md`에서 읽은 `(phase/foo/PHASE.md)`는 채팅 출력에서 `(agent-roadmap/phase/foo/PHASE.md)`로, `agent-roadmap/phase/foo/PHASE.md`에서 읽은 `(milestones/bar.md)`는 `(agent-roadmap/phase/foo/milestones/bar.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 문서 링크를 함께 붙인다.

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

@@ -1,31 +1,41 @@
 # 로드맵 현지점
 
-<!-- 링크 target의 <...-path> placeholder는 실제 출력 시 repo root 기준 상대경로로 치환한다. -->
+- local current: {없음 | [current.md](agent-roadmap/current.md)}
 
-- [local current.md](agent-roadmap/current.md)
+<!--
+작성 규칙:
+- 아래 {...} placeholder는 실제 출력에 남기지 않는다.
+- 링크는 반드시 [제목](repo-root-relative-path) 형식으로 쓴다.
+- 문서 안에서 읽은 file-location-relative 링크는 원본 파일 위치 기준으로 해석한 뒤 repo root 기준 target으로 다시 쓴다.
+- 경로를 확정할 수 없는 항목은 깨진 Markdown 링크 대신 `링크 없음: <사유>`로 쓴다.
+- {PHASE_LINK}, {MILESTONE_LINK}, {SDD_LINK}, {USER_REVIEW_LINK}는 실제 Markdown 링크로 치환한다.
+- 이 주석은 출력하지 않는다.
+-->
 
-- [로드맵: <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) | [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) | [SDD.md](agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md) (파일 없음)>
-      - 사용자 리뷰: <없음 | [USER_REVIEW.md](agent-roadmap/sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md)>
+## Breadcrumb
+
+- [로드맵: {roadmap-name}](agent-roadmap/ROADMAP.md)
+  - Phase: {PHASE_LINK}
+    - Milestone: {MILESTONE_LINK}
+      - [{상태}] {목표 또는 역할 한 줄}
+      - SDD: {없음 | SDD_LINK | SDD_LINK (파일 없음)}
+      - 사용자 리뷰: {없음 | USER_REVIEW_LINK}
+    - Milestone: {MILESTONE_LINK}
+      - [{상태}] {목표 또는 역할 한 줄}
+      - SDD: {없음 | SDD_LINK | SDD_LINK (파일 없음)}
+      - 사용자 리뷰: {없음 | USER_REVIEW_LINK}
 
 ## 전체 Phase 흐름
 
-- [<상태>] [<Phase 이름>](<phase-path>)
-- [<상태>] [<현재 Phase 이름>](<phase-path>) ← 현재
-- [<상태>] [<Phase 이름>](<phase-path>)
+- [{상태}] {PHASE_LINK}
+- [{상태}] {PHASE_LINK} ← 현재
+- [{상태}] {PHASE_LINK}
 
 ## 현재 Phase의 Milestone 흐름
 
-- [<상태>] [<Milestone 이름>](<milestone-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.md](<sdd-path>) (파일 없음)>
-  - 사용자 리뷰: <없음 | [USER_REVIEW.md](<user-review-path>)>
+- [{상태}] {MILESTONE_LINK} ← 현재 후보, {역할 태그}
+  - SDD: {없음 | SDD_LINK | SDD_LINK (파일 없음)}
+  - 사용자 리뷰: {없음 | USER_REVIEW_LINK}
+- [{상태}] {MILESTONE_LINK} ← 현재 후보, {역할 태그}
+  - SDD: {없음 | SDD_LINK | SDD_LINK (파일 없음)}
+  - 사용자 리뷰: {없음 | USER_REVIEW_LINK}

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

@@ -44,14 +44,26 @@ description: "여러 레포를 전환할 때 코드/git 분석 없이 전체 ROA
    - 각 Milestone은 상태, 이름, 링크만 남긴다.
    - current의 활성 Milestone과 일치하는 항목에 `← 현재 후보` 표시를 붙인다.
 6. current의 활성 Milestone 문서를 열고 제목, `목표`, `상태`, `구현 잠금`의 SDD 문서 링크/경로만 읽는다.
-   - `SDD 문서` 링크/경로가 있고 해당 `SDD.md` 파일이 존재하면 Milestone 아래에 `SDD: [SDD.md](<sdd-path>)`로 출력한다.
-   - `SDD 문서` 링크/경로는 있으나 해당 파일이 없으면 Milestone 아래에 `SDD: [SDD.md](<sdd-path>) (파일 없음)` 형식으로 출력한다.
+   - `SDD 문서` 링크/경로가 있고 해당 `SDD.md` 파일이 존재하면 Milestone 아래에 `SDD: SDD_LINK`로 출력한다.
+   - `SDD 문서` 링크/경로는 있으나 해당 파일이 없으면 Milestone 아래에 `SDD: SDD_LINK (파일 없음)` 형식으로 출력한다.
    - `SDD 문서` 링크/경로가 없거나 `SDD: 불필요`이면 Milestone 아래에 `SDD: 없음`으로 출력한다.
-   - `SDD.md`와 같은 디렉터리에 `USER_REVIEW.md`가 있으면 Milestone 아래에 `사용자 리뷰: [USER_REVIEW.md](<user-review-path>)`로 출력하고, 없으면 `사용자 리뷰: 없음`으로 출력한다.
+   - `SDD.md`와 같은 디렉터리에 `USER_REVIEW.md`가 있으면 Milestone 아래에 `사용자 리뷰: USER_REVIEW_LINK`로 출력하고, 없으면 `사용자 리뷰: 없음`으로 출력한다.
    - SDD 상태, 잠금, 승인 여부를 역할 태그나 상태 요약으로 출력하지 않는다. 필요한 독자는 출력된 SDD 링크를 열어 확인하게 한다.
    - SDD 본문은 읽지 않는다.
    - `기능`, `완료 리뷰`, `범위 제외`, `작업 컨텍스트`는 사용자가 명시적으로 요청한 경우에만 읽는다.
-7. 결과를 템플릿 형식 그대로 출력한다.
+7. 결과를 템플릿의 섹션 순서와 필드 의미에 맞춰 출력한다. 템플릿의 placeholder, 선택지 표기, HTML 주석은 출력하지 않는다.
+
+## 링크 정규화
+
+- 출력 링크는 채팅 결과이므로 항상 repo root 기준 상대경로를 target으로 쓴다. 예: `[PHASE.md](agent-roadmap/phase/example-phase/PHASE.md)`.
+- `current.md`, `ROADMAP.md`, `PHASE.md`, Milestone 문서에서 읽은 Markdown 링크는 그대로 복사하지 않는다. 반드시 링크가 들어 있던 원본 파일 위치 기준으로 target을 해석한 뒤 repo root 기준 상대경로로 다시 쓴다.
+- 예: `agent-roadmap/current.md`의 `[PHASE.md](phase/foo/PHASE.md)`는 출력에서 `[PHASE.md](agent-roadmap/phase/foo/PHASE.md)`로 쓴다.
+- 예: `agent-roadmap/phase/foo/PHASE.md`의 `[Milestone](milestones/bar.md)`는 출력에서 `[Milestone](agent-roadmap/phase/foo/milestones/bar.md)`로 쓴다.
+- 예: `agent-roadmap/phase/foo/PHASE.md`의 `[Archive](../../archive/phase/foo/milestones/bar.md)`는 출력에서 `[Archive](agent-roadmap/archive/phase/foo/milestones/bar.md)`로 쓴다. archive 문서는 읽지 않고 링크만 표시한다.
+- 링크 label은 사람이 이해할 수 있는 이름을 쓰고, target에는 `<phase-path>`, `<milestone-path>`, `<sdd-path>`, `<user-review-path>`, `<phase-slug>`, `<milestone-slug>` 또는 `{PHASE_LINK}` 같은 placeholder를 남기지 않는다.
+- 템플릿의 `{PHASE_LINK}`, `{MILESTONE_LINK}`, `{SDD_LINK}`, `{USER_REVIEW_LINK}`는 실제 `[제목](repo-root-relative-path)` Markdown 링크로 치환한다.
+- 대상 경로를 확정할 수 없으면 Markdown 링크를 만들지 말고 `링크 없음: <사유>`로 표시한다. raw path만 단독으로 출력하거나 깨진 링크를 만들지 않는다.
+- 출력 전 자체 점검으로 `](<`, `](...<...>)`, `{PHASE_LINK}` 같은 placeholder 링크가 남아 있지 않은지 확인한다.
 
 ## 실행 결과 검증
 
@@ -59,6 +71,8 @@ description: "여러 레포를 전환할 때 코드/git 분석 없이 전체 ROA
 - [ ] 로컬 `current.md`, `ROADMAP.md`, 활성 `PHASE.md`, 활성 Milestone의 제목/목표/상태/SDD 문서 링크/경로만 기본으로 읽었는가
 - [ ] 현재 후보 Milestone 아래에 SDD와 사용자 리뷰를 링크 또는 `없음`으로 출력했는가
 - [ ] Phase, Milestone, SDD, 사용자 리뷰 등 모든 문서 포인터가 raw path만 남지 않고 Markdown 링크로 출력되었는가
+- [ ] 문서에서 읽은 file-location-relative 링크를 채팅 출력용 repo root 상대 링크로 정규화했는가
+- [ ] 출력에 placeholder 링크 target이나 `(제목)[링크]`처럼 뒤집힌 Markdown 문법이 남지 않았는가
 - [ ] SDD 상태, 잠금, 승인 여부를 역할 태그나 상태 요약으로 출력하지 않았는가
 - [ ] 완료 또는 archive Phase/Milestone은 링크만 표시하고 archive 문서를 읽지 않았는가
 - [ ] current가 여러 Milestone을 가리키면 모두 `현재 후보`로 표시했는가
@@ -68,14 +82,15 @@ 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으로 치환한다.
+- 템플릿의 섹션 순서와 필드 의미를 따른다. placeholder 줄을 그대로 복사하지 말고, 실제 항목 수에 맞춰 행을 생성한다.
+- 출력에는 `<phase-path>`, `<milestone-path>`, `<sdd-path>`, `<user-review-path>`, `{PHASE_LINK}`, `{MILESTONE_LINK}`, `{SDD_LINK}`, `{USER_REVIEW_LINK}` placeholder를 그대로 남기지 않고 실제 repo root 기준 상대 링크 target으로 치환한다.
 - 섹션 제목과 필드명을 임의로 번역, 축약, 삭제하지 않는다.
 - current가 여러 Milestone을 가리키면 breadcrumb와 Milestone 흐름에 모두 표시한다.
 - 현재 후보의 역할 태그는 `선행 스케치`, `다음 구현 계획`, `검토 후보`, `보류 후보`처럼 짧게 쓰되 SDD 상태를 역할 태그에 넣지 않는다.
 - 현재 후보에 `SDD 문서` 링크/경로가 있으면 Milestone 아래에 SDD 링크를 배치한다. `USER_REVIEW.md`가 있으면 그 링크도 SDD 아래에 배치한다.
-- 문서 포인터는 항상 `[표시 제목](상대경로)` Markdown 링크로 출력한다. 파일이 없어도 raw path만 쓰지 말고 `[SDD.md](<sdd-path>) (파일 없음)`처럼 링크와 상태를 함께 쓴다.
+- 문서 포인터는 항상 `[표시 제목](상대경로)` Markdown 링크로 출력한다. 파일이 없어도 raw path만 쓰지 말고 `SDD_LINK (파일 없음)`처럼 링크와 상태를 함께 쓴다.
 - 로드맵이 없는 프로젝트에서는 로드맵 없음으로 짧게 보고하고 템플릿을 억지로 채우지 않는다.
+- 로컬 `current.md`가 없으면 `local current: 없음`으로 출력하고, `[current.md](agent-roadmap/current.md)` 링크를 만들지 않는다.
 
 ## 금지 사항