diff --git a/agent-ops/.version b/agent-ops/.version index 4743491..38dfb5f 100644 --- a/agent-ops/.version +++ b/agent-ops/.version @@ -1 +1 @@ -1.1.161 +1.1.162 diff --git a/agent-ops/rules/common/rules-roadmap.md b/agent-ops/rules/common/rules-roadmap.md index c5c7a0f..b60a39c 100644 --- a/agent-ops/rules/common/rules-roadmap.md +++ b/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///`로 이동한다. +## 링크 표기 + +- 사용자에게 보여주는 답변과 활성 로드맵 문서의 문서 포인터는 raw path만 쓰지 말고 `[표시 제목](상대경로)` Markdown 링크로 쓴다. +- 로드맵 문서 안의 링크 target은 링크를 작성하는 Markdown 파일 위치 기준 상대경로로 쓴다. 예: `ROADMAP.md`에서는 `[PHASE.md](phase//PHASE.md)`, Phase 문서에서는 `[Milestone](milestones/.md)`, Milestone 문서에서는 `[ROADMAP.md](../../../ROADMAP.md)`와 `[PHASE.md](../PHASE.md)`를 쓴다. +- 채팅 결과 보고처럼 저장 위치가 없는 출력은 repo root 기준 상대경로를 쓸 수 있다. 예: `[PHASE.md](agent-roadmap/phase//PHASE.md)`. +- 실제 활성 로드맵 문서에는 ``, ``, `` 같은 placeholder가 들어간 링크 target을 남기지 않는다. 템플릿 placeholder는 문서 생성/갱신 시 실제 파일 위치 기준 상대경로 또는 `없음`으로 치환한다. +- 기존 raw path 또는 backtick path는 읽기 입력으로 허용한다. 갱신 범위에 포함된 활성 문서 포인터만 Markdown 링크로 보정하고, archive 스냅샷은 링크 표기만을 이유로 재포맷하지 않는다. +- `.agent-roadmap-sync/locks.yaml`의 `locked`, `rely-on.target`, Milestone identity(`: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로 검증 가능해야 한다. diff --git a/agent-ops/skills/common/_templates/roadmap-current-template.md b/agent-ops/skills/common/_templates/roadmap-current-template.md index 0c71a92..13cda5f 100644 --- a/agent-ops/skills/common/_templates/roadmap-current-template.md +++ b/agent-ops/skills/common/_templates/roadmap-current-template.md @@ -3,28 +3,28 @@ ## 활성 Phase - [<스케치 | 계획 | 진행중 | 검토중 | 보류>] - - 경로: `agent-roadmap/phase//PHASE.md` + - 경로: [PHASE.md](phase//PHASE.md) ## 활성 Milestone - [<스케치 | 계획 | 진행중 | 검토중 | 보류>] - - Phase: `agent-roadmap/phase//PHASE.md` - - 경로: `agent-roadmap/phase//milestones/.md` + - Phase: [PHASE.md](phase//PHASE.md) + - 경로: [](phase//milestones/.md) ## 선택 규칙 - 이 문서는 활성 Phase와 활성 Milestone 후보 목록이며, 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다. - 이 문서는 브랜치별 로컬 포인터이며 git 추적 대상이 아니다. -- 활성 Phase는 `agent-roadmap/phase//PHASE.md`를 가리킨다. -- 활성 Milestone은 `agent-roadmap/phase//milestones/.md`를 가리킨다. +- 활성 Phase는 [PHASE.md](phase//PHASE.md)를 가리킨다. +- 활성 Milestone은 [Milestone 문서](phase//milestones/.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///USER_REVIEW.md)로 분리한다. - 완료된 과거 내용이 필요할 때만 `ROADMAP.md` 또는 `PHASE.md`에 있는 archive 링크를 따라가서 읽는다. - 선택된 Milestone의 `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 구현이나 구현 계획을 시작하기 전에 현재 요청에 직접 영향을 주는 `결정 필요` 항목만 확인한다. 관련 결정이 없고 표준선으로 처리 가능하면 잠금 해소용 roadmap-only 갱신으로 결정 항목을 정리한 뒤 진행하며, Milestone 전체에서 에이전트가 확정할 수 없는 결정 항목이 더 이상 없을 때만 `구현 잠금` 상태를 `해제`로 둔다. -- 선택된 Milestone에 `SDD: 필요`가 있으면 `agent-roadmap/sdd///SDD.md`가 `[승인됨]`이고 SDD 잠금이 해제되었으며 SDD `USER_REVIEW.md`가 없어야 구현이나 구현 계획을 시작한다. +- 선택된 Milestone에 `SDD: 필요`가 있으면 [SDD.md](sdd///SDD.md)가 `[승인됨]`이고 SDD 잠금이 해제되었으며 SDD [USER_REVIEW.md](sdd///USER_REVIEW.md)가 없어야 구현이나 구현 계획을 시작한다. - 선택된 Milestone 상태가 `[스케치]`이면 `구현 잠금` 상태와 관계없이 구현이나 구현 계획을 시작하지 않고 `[계획]` 승격 필요를 보고한다. diff --git a/agent-ops/skills/common/_templates/roadmap-milestone-template.md b/agent-ops/skills/common/_templates/roadmap-milestone-template.md index c240b56..1f1848c 100644 --- a/agent-ops/skills/common/_templates/roadmap-milestone-template.md +++ b/agent-ops/skills/common/_templates/roadmap-milestone-template.md @@ -2,8 +2,8 @@ ## 위치 -- Roadmap: `agent-roadmap/ROADMAP.md` -- Phase: `agent-roadmap/phase//PHASE.md` +- Roadmap: [ROADMAP.md](../../../ROADMAP.md) +- Phase: [PHASE.md](../PHASE.md) ## 목표 @@ -33,7 +33,7 @@ - 상태: <잠금 | 해제> - SDD: <필요 | 불필요> -- SDD 문서: <없음 | `agent-roadmap/sdd///SDD.md`> +- SDD 문서: <없음 | [SDD.md](../../../sdd///SDD.md)> - SDD 사유: <필요/불필요 판정 근거 한 줄> - 잠금 해제 조건: <없음 | 아래 체크리스트> - [ ] @@ -93,6 +93,6 @@ Task 체크리스트는 Epic 바로 아래의 flat list로 유지하고, 구현 - 관련 경로: `` - 표준선(선택): <기존 구조, 도메인 rule, 플랫폼 관례, 업계 표준으로 진행할 기본 기준> -- 선행 작업: <없음 또는 Milestone/태스크 이름> -- 후속 작업: <없음 또는 Milestone/태스크 이름> -- 확인 필요: <없음 | `구현 잠금 > 결정 필요` 또는 SDD USER_REVIEW.md로 분리할 항목> +- 선행 작업: <없음 또는 파일 위치 기준 Markdown 링크(예: [Milestone 이름](../other-milestone.md))/태스크 이름> +- 후속 작업: <없음 또는 파일 위치 기준 Markdown 링크(예: [Milestone 이름](../next-milestone.md))/태스크 이름> +- 확인 필요: <없음 | `구현 잠금 > 결정 필요` 또는 [USER_REVIEW.md](../../../sdd///USER_REVIEW.md)로 분리할 항목> diff --git a/agent-ops/skills/common/_templates/roadmap-phase-template.md b/agent-ops/skills/common/_templates/roadmap-phase-template.md index 08daa5d..ac51830 100644 --- a/agent-ops/skills/common/_templates/roadmap-phase-template.md +++ b/agent-ops/skills/common/_templates/roadmap-phase-template.md @@ -15,7 +15,7 @@ 스케치 Milestone은 아직 구현 가능한 계획이 아니므로 계획 Milestone보다 아래에 둔다. - [<스케치 | 계획 | 진행중 | 검토중 | 완료 | 보류 | 폐기>] - - 경로: `agent-roadmap/phase//milestones/.md` 또는 `agent-roadmap/archive/phase//milestones/.md` + - 경로: [](milestones/.md) 또는 [archive ](../../archive/phase//milestones/.md) - 요약: <목표 또는 결과 1문장> ## Phase 경계 diff --git a/agent-ops/skills/common/_templates/roadmap-position-report-template.md b/agent-ops/skills/common/_templates/roadmap-position-report-template.md index 854cff7..09a042e 100644 --- a/agent-ops/skills/common/_templates/roadmap-position-report-template.md +++ b/agent-ops/skills/common/_templates/roadmap-position-report-template.md @@ -1,16 +1,18 @@ # 로드맵 현지점 + + - [local current.md](agent-roadmap/current.md) - [로드맵: ](agent-roadmap/ROADMAP.md) - [Phase: ](agent-roadmap/phase//PHASE.md) - [Milestone: ](agent-roadmap/phase//milestones/.md) - [<상태>] <목표 또는 역할 한 줄> - - SDD: <없음 | [SDD.md](agent-roadmap/sdd///SDD.md) | 경로만 있음: `agent-roadmap/sdd///SDD.md`> + - SDD: <없음 | [SDD.md](agent-roadmap/sdd///SDD.md) | [SDD.md](agent-roadmap/sdd///SDD.md) (파일 없음)> - 사용자 리뷰: <없음 | [USER_REVIEW.md](agent-roadmap/sdd///USER_REVIEW.md)> - [Milestone: ](agent-roadmap/phase//milestones/.md) - [<상태>] <목표 또는 역할 한 줄> - - SDD: <없음 | [SDD.md](agent-roadmap/sdd///SDD.md) | 경로만 있음: `agent-roadmap/sdd///SDD.md`> + - SDD: <없음 | [SDD.md](agent-roadmap/sdd///SDD.md) | [SDD.md](agent-roadmap/sdd///SDD.md) (파일 없음)> - 사용자 리뷰: <없음 | [USER_REVIEW.md](agent-roadmap/sdd///USER_REVIEW.md)> ## 전체 Phase 흐름 @@ -22,8 +24,8 @@ ## 현재 Phase의 Milestone 흐름 - [<상태>] []() ← 현재 후보, <역할 태그> - - SDD: <없음 | [SDD.md]() | 경로만 있음: ``> + - SDD: <없음 | [SDD.md]() | [SDD.md]() (파일 없음)> - 사용자 리뷰: <없음 | [USER_REVIEW.md]()> - [<상태>] []() ← 현재 후보, <역할 태그> - - SDD: <없음 | [SDD.md]() | 경로만 있음: ``> + - SDD: <없음 | [SDD.md]() | [SDD.md]() (파일 없음)> - 사용자 리뷰: <없음 | [USER_REVIEW.md]()> diff --git a/agent-ops/skills/common/_templates/roadmap-sdd-template.md b/agent-ops/skills/common/_templates/roadmap-sdd-template.md index f0eccad..e811137 100644 --- a/agent-ops/skills/common/_templates/roadmap-sdd-template.md +++ b/agent-ops/skills/common/_templates/roadmap-sdd-template.md @@ -2,8 +2,8 @@ ## 위치 -- Milestone: `agent-roadmap/phase//milestones/.md` -- Phase: `agent-roadmap/phase//PHASE.md` +- Milestone: [Milestone 문서](../../../phase//milestones/.md) +- Phase: [PHASE.md](../../../phase//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 | `` | <장기 원장, 상태 반영 기준> | +| Roadmap | [Milestone 문서](../../../phase//milestones/.md) | <장기 원장, 상태 반영 기준> | | Code | `` | <구현 source of truth> | | External Provider | <없음 또는 provider> | | | User Decision | <없음 또는 D-id> | <사용자 결정이 필요한 기준> | @@ -39,7 +39,7 @@ ## Interface Contract -- 계약 원문: <없음 또는 `agent-contract/...` 링크> +- 계약 원문: <없음 또는 [계약 문서](../../../../agent-contract/...)> - 입력: - : <의미> - 출력: @@ -82,4 +82,4 @@ ## 작업 컨텍스트 - 표준선: <기존 구조, 도메인 rule, 플랫폼 관례> -- 후속 SDD: <없음 또는 SDD 경로> +- 후속 SDD: <없음 또는 [SDD.md](..//SDD.md)> diff --git a/agent-ops/skills/common/_templates/roadmap-sdd-user-review-template.md b/agent-ops/skills/common/_templates/roadmap-sdd-user-review-template.md index fc4f47b..4ab7099 100644 --- a/agent-ops/skills/common/_templates/roadmap-sdd-user-review-template.md +++ b/agent-ops/skills/common/_templates/roadmap-sdd-user-review-template.md @@ -6,8 +6,8 @@ ## 검토 대상 -- SDD: `agent-roadmap/sdd///SDD.md` -- Milestone: `agent-roadmap/phase//milestones/.md` +- SDD: [SDD.md](SDD.md) +- Milestone: [Milestone 문서](../../../phase//milestones/.md) ## 사용자 결정 항목 diff --git a/agent-ops/skills/common/_templates/roadmap-template.md b/agent-ops/skills/common/_templates/roadmap-template.md index 1f10e9d..79474d8 100644 --- a/agent-ops/skills/common/_templates/roadmap-template.md +++ b/agent-ops/skills/common/_templates/roadmap-template.md @@ -12,30 +12,30 @@ 스케치 Phase는 아직 구현 가능한 계획이 아니므로 계획 Phase보다 아래에 둔다. - [<스케치 | 계획 | 진행중 | 검토중 | 완료 | 보류 | 폐기>] - - 경로: `agent-roadmap/phase//PHASE.md` 또는 `agent-roadmap/archive/phase//PHASE.md` + - 경로: [PHASE.md](phase//PHASE.md) 또는 [archive PHASE.md](archive/phase//PHASE.md) - 요약: <이 Phase의 목표와 역할 1문장> ## 로딩 정책 -- 일반 작업에서는 `agent-roadmap/ROADMAP.md`를 매번 읽지 않는다. -- 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 `agent-roadmap/current.md`를 먼저 읽는다. +- 일반 작업에서는 [ROADMAP.md](ROADMAP.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.md`를 가리킨다. -- `current.md`의 활성 Milestone은 `agent-roadmap/phase//milestones/.md`를 가리킨다. +- `current.md`의 활성 Phase는 [PHASE.md](phase//PHASE.md)를 가리킨다. +- `current.md`의 활성 Milestone은 [Milestone 문서](phase//milestones/.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///SDD.md`에 두고, Milestone `구현 잠금`의 SDD 조건과 연결한다. -- SDD 사용자 리뷰가 필요하면 `agent-roadmap/sdd///USER_REVIEW.md`로 남기며, 해결 후 `user_review_N.log`로 보존한다. +- 큰 Milestone의 설계 게이트는 [SDD.md](sdd///SDD.md)에 두고, Milestone `구현 잠금`의 SDD 조건과 연결한다. +- SDD 사용자 리뷰가 필요하면 [USER_REVIEW.md](sdd///USER_REVIEW.md)로 남기며, 해결 후 `user_review_N.log`로 보존한다. - `[스케치]` Phase/Milestone은 방향성, 문제의식, 후보 범위, 미정 질문을 기록하는 컨셉 상태이며 구현 계획 생성 대상이 아니다. - `[스케치]` 항목은 `승격 조건`을 정리해 `[계획]`으로 전환한 뒤 구현 계획을 만든다. - 모든 기능 Task와 Task 안에 명시된 검증이 충족되고 `구현 잠금`이 해제된 Milestone은 먼저 `[검토중]`으로 두고, 완료 근거와 archive 조건이 정리되면 `[완료]`로 전환한다. -- 완료된 Phase는 `agent-roadmap/archive/phase//PHASE.md`로 이동하고, 하위 Milestone도 같은 archive Phase scaffold 아래에 둔다. -- 진행중 Phase 안에서 완료된 Milestone은 활성 Phase 문서에 짧은 링크를 남기고, 상세 문서는 `agent-roadmap/archive/phase//milestones/`로 이동한다. +- 완료된 Phase는 [archive PHASE.md](archive/phase//PHASE.md)로 이동하고, 하위 Milestone도 같은 archive Phase scaffold 아래에 둔다. +- 진행중 Phase 안에서 완료된 Milestone은 활성 Phase 문서에 짧은 링크를 남기고, 상세 문서는 [archive milestones](archive/phase//milestones/)로 이동한다. - archive `PHASE.md`는 Phase 자체가 완료 또는 폐기될 때만 만들며, 진행중 Phase의 완료 Milestone만 archive된 경우 archive Phase 디렉터리에 `milestones/`만 있을 수 있다. - `agent-roadmap/archive/**`는 일반 작업에서 읽지 않는다. 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `ROADMAP.md` 또는 `PHASE.md`의 archive 링크를 따라가서 읽는다. - 아카이브된 Phase/Milestone 문서는 최신 템플릿이나 스킬 규약에 맞춰 재포맷하지 않는다. diff --git a/agent-ops/skills/common/analyze-roadmap-position/SKILL.md b/agent-ops/skills/common/analyze-roadmap-position/SKILL.md index f3dc398..34a8862 100644 --- a/agent-ops/skills/common/analyze-roadmap-position/SKILL.md +++ b/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 문서 경로만 읽는다. - - `SDD 문서` 경로가 있고 해당 `SDD.md` 파일이 존재하면 Milestone 아래에 `SDD: [SDD.md]()`로 출력한다. - - `SDD 문서` 경로는 있으나 해당 파일이 없으면 Milestone 아래에 `SDD: 경로만 있음: ` 형식으로 출력한다. - - `SDD 문서` 경로가 없거나 `SDD: 불필요`이면 Milestone 아래에 `SDD: 없음`으로 출력한다. +6. current의 활성 Milestone 문서를 열고 제목, `목표`, `상태`, `구현 잠금`의 SDD 문서 링크/경로만 읽는다. + - `SDD 문서` 링크/경로가 있고 해당 `SDD.md` 파일이 존재하면 Milestone 아래에 `SDD: [SDD.md]()`로 출력한다. + - `SDD 문서` 링크/경로는 있으나 해당 파일이 없으면 Milestone 아래에 `SDD: [SDD.md]() (파일 없음)` 형식으로 출력한다. + - `SDD 문서` 링크/경로가 없거나 `SDD: 불필요`이면 Milestone 아래에 `SDD: 없음`으로 출력한다. - `SDD.md`와 같은 디렉터리에 `USER_REVIEW.md`가 있으면 Milestone 아래에 `사용자 리뷰: [USER_REVIEW.md]()`로 출력하고, 없으면 `사용자 리뷰: 없음`으로 출력한다. - 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를 채운다. +- 출력에는 ``, ``, ``, `` 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]() (파일 없음)`처럼 링크와 상태를 함께 쓴다. - 로드맵이 없는 프로젝트에서는 로드맵 없음으로 짧게 보고하고 템플릿을 억지로 채우지 않는다. ## 금지 사항 diff --git a/agent-ops/skills/common/check-roadmap-dependency/SKILL.md b/agent-ops/skills/common/check-roadmap-dependency/SKILL.md index b355a41..7c574ab 100644 --- a/agent-ops/skills/common/check-roadmap-dependency/SKILL.md +++ b/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//milestones/.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: `` +- target-document: <[Milestone 문서](agent-roadmap/phase//milestones/.md) | 해당 없음> - direction: `` - locks-file: `` - 결과: `` diff --git a/agent-ops/skills/common/code-review/templates/complete-log-template.md b/agent-ops/skills/common/code-review/templates/complete-log-template.md index d1840bd..a54ce8f 100644 --- a/agent-ops/skills/common/code-review/templates/complete-log-template.md +++ b/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//milestones/.md}` +- Milestone link: [Milestone 문서](agent-roadmap/phase//milestones/.md) - Completed task ids: - `{task-id}`: PASS; evidence=`{archived-plan-log}`, `{archived-review-log}`; verification=`{command or saved output path}` - Not completed task ids: 없음 diff --git a/agent-ops/skills/common/create-roadmap/SKILL.md b/agent-ops/skills/common/create-roadmap/SKILL.md index c5988b9..09f42a5 100644 --- a/agent-ops/skills/common/create-roadmap/SKILL.md +++ b/agent-ops/skills/common/create-roadmap/SKILL.md @@ -91,6 +91,11 @@ agent-roadmap/ - Milestone 파일명은 `agent-roadmap/phase//milestones/.md`로 만든다. - ``와 ``는 소문자 영문, 숫자, 하이픈만 사용하고, 공백/언더스코어/순번 prefix를 넣지 않는다. - 중간에 Phase나 Milestone을 끼워 넣을 수 있도록 기존 항목의 이름과 파일명을 불필요하게 바꾸지 않는다. +- 로드맵 문서 안에서 다른 로드맵 문서, SDD, `USER_REVIEW.md`, archive 문서를 가리킬 때는 raw path만 쓰지 말고 `[표시 제목](상대경로)` Markdown 링크로 쓴다. +- 문서 안의 링크 target은 링크를 작성하는 Markdown 파일 위치 기준 상대경로로 쓴다. 예: `ROADMAP.md`와 `current.md`에서는 `[PHASE.md](phase//PHASE.md)`, Phase 문서에서는 `[Milestone](milestones/.md)`, Milestone 문서에서는 `[ROADMAP.md](../../../ROADMAP.md)`와 `[PHASE.md](../PHASE.md)`를 쓴다. +- `경로:`, `Phase:`, `Milestone:`, `SDD 문서:` 같은 필드명을 유지해야 해도 값은 `경로: [PHASE.md](phase//PHASE.md)`처럼 링크로 작성한다. +- 실제 생성한 로드맵 문서에는 ``, ``, `` 같은 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///SDD.md`로 적고, SDD 잠금이 해제될 때까지 `구현 잠금`을 `잠금`으로 둔다. -- 로드맵 생성 흐름에서 SDD가 필요한 신규 Milestone은 SDD 경로만 남기지 않고 해당 경로에 SDD 초안을 만든다. +- SDD가 필요한 Milestone은 `SDD 문서` 값을 해당 Milestone 파일 위치 기준 `[SDD.md](../../../sdd///SDD.md)` Markdown 링크로 적고, 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.md`로 만들고 `ROADMAP.md`에서 archive 경로를 가리킨다. - 완료된 Milestone이 진행중 Phase에 포함되어야 하는 경우 `archive/phase//milestones/.md`로 만들고 해당 활성 `PHASE.md`에서 archive 경로를 가리킨다. - archive `PHASE.md`는 Phase 자체가 완료/폐기된 경우에만 만든다. 진행중 Phase의 완료 Milestone만 archive된 경우 archive Phase 디렉터리에 `milestones/`만 둘 수 있다. - - SDD가 필요한 Milestone은 `구현 잠금`에 SDD 경로와 잠금 해제 조건을 적고, 같은 흐름에서 `roadmap-sdd`의 `create` 절차를 적용해 `agent-roadmap/sdd///SDD.md` 초안을 만든다. + - SDD가 필요한 Milestone은 `구현 잠금`에 해당 Milestone 파일 위치 기준 `SDD 문서` Markdown 링크와 잠금 해제 조건을 적고, 같은 흐름에서 `roadmap-sdd`의 `create` 절차를 적용해 `agent-roadmap/sdd///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 -- 로컬 현재 컨텍스트: agent-roadmap/current.md +- 로드맵: [ROADMAP.md](agent-roadmap/ROADMAP.md) +- 로컬 현재 컨텍스트: [current.md](agent-roadmap/current.md) - Phase 문서: - Milestone 문서: - 활성 Phase: @@ -189,8 +196,8 @@ agent-roadmap/ ## 활성 항목 -- Phase: : agent-roadmap/phase//PHASE.md -- Milestone: : agent-roadmap/phase//milestones/.md +- Phase: : [PHASE.md](agent-roadmap/phase//PHASE.md) +- Milestone: : [](agent-roadmap/phase//milestones/.md) ## TODO 항목 diff --git a/agent-ops/skills/common/plan/SKILL.md b/agent-ops/skills/common/plan/SKILL.md index 0951fbd..250873c 100644 --- a/agent-ops/skills/common/plan/SKILL.md +++ b/agent-ops/skills/common/plan/SKILL.md @@ -233,6 +233,7 @@ Required sections: ## Roadmap Targets - Milestone: `agent-roadmap/phase//milestones/.md` +- Milestone link: [Milestone 문서](agent-roadmap/phase//milestones/.md) - Task ids: - ``: - Completion mode: check-on-pass diff --git a/agent-ops/skills/common/roadmap-sdd/SKILL.md b/agent-ops/skills/common/roadmap-sdd/SKILL.md index 3fe04b0..e3fb369 100644 --- a/agent-ops/skills/common/roadmap-sdd/SKILL.md +++ b/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///` 디렉터리 기준 상대경로로 쓴다. 예: `[Milestone 문서](../../../phase//milestones/.md)`, `[PHASE.md](../../../phase//PHASE.md)`, `[USER_REVIEW.md](USER_REVIEW.md)`. +- 실제 생성/갱신한 SDD에는 ``, ``, `` 같은 placeholder가 들어간 링크 target을 남기지 않는다. 템플릿 placeholder는 실제 파일 위치 기준 상대경로 또는 `없음`으로 치환한다. +- 코드 source path나 machine-readable identity는 raw 값이 필요하면 유지할 수 있다. ## SDD 대상 판정 @@ -80,7 +84,7 @@ SDD가 필요한 Milestone은 `구현 잠금`에 아래 필드를 둔다. ```md - 상태: 잠금 - SDD: 필요 -- SDD 문서: `agent-roadmap/sdd///SDD.md` +- SDD 문서: [SDD.md](../../../sdd///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: `` -- milestone: `` -- sdd: `` +- milestone: <[Milestone 문서](agent-roadmap/phase//milestones/.md) | 해당 없음> +- sdd: <[SDD.md](agent-roadmap/sdd///SDD.md) | 없음> - 결과: `` - 잠금: `<해제 | 잠금 | 해당 없음>` -- 사용자 리뷰: `<없음 | USER_REVIEW.md | user_review_N.log>` +- 사용자 리뷰: <없음 | [USER_REVIEW.md](agent-roadmap/sdd///USER_REVIEW.md) | [user_review_N.log](agent-roadmap/sdd///user_review_N.log)> - 다음 단계: `<없음 | 사용자 리뷰 필요 | Milestone 구현 잠금 해제 가능 | SDD 작성 필요>` ``` diff --git a/agent-ops/skills/common/sync-milestone-workstate/SKILL.md b/agent-ops/skills/common/sync-milestone-workstate/SKILL.md index 2bba4bc..8e22b12 100644 --- a/agent-ops/skills/common/sync-milestone-workstate/SKILL.md +++ b/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: +- 대상 Milestone: [](agent-roadmap/phase//milestones/.md) - 모드: - 수정 파일: - - + - <없음 | [문서명](path)> ## 반영 내용 @@ -152,9 +154,9 @@ description: 현 마일스톤과 작업현황 동기화, 현재 마일스톤 작 - 검토 필요 Task: - complete.log 후보: active 개, archive 개 - 반영한 complete.log: - - + - <[complete.log](path)> - 반영 제외 complete.log: - - - <사유> + - <[complete.log](path)> - <사유> - 파일/git evidence: - - <파일/커밋/검증 요약> - SDD gate: <불필요 | 충족 | 차단: 사유> diff --git a/agent-ops/skills/common/update-roadmap/SKILL.md b/agent-ops/skills/common/update-roadmap/SKILL.md index 1dcf3c6..876f1c0 100644 --- a/agent-ops/skills/common/update-roadmap/SKILL.md +++ b/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.md)`, Phase 문서에서는 `[Milestone](milestones/.md)`, Milestone 문서에서는 `[ROADMAP.md](../../../ROADMAP.md)`와 `[PHASE.md](../PHASE.md)`를 쓴다. +- 채팅 결과 보고처럼 저장 위치가 없는 출력은 repo root 기준 상대경로를 쓸 수 있다. 예: `[PHASE.md](agent-roadmap/phase//PHASE.md)`. +- `경로:`, `Phase:`, `Milestone:`, `SDD 문서:`, `수정 파일:` 같은 필드명을 유지해야 해도 값은 Markdown 링크로 작성한다. +- 실제 갱신한 활성 로드맵 문서에는 ``, ``, `` 같은 placeholder가 들어간 링크 target을 남기지 않는다. 템플릿 placeholder는 실제 파일 위치 기준 상대경로 또는 `없음`으로 치환한다. +- 기존 문서에 남아 있는 raw path나 backtick path는 읽기/마이그레이션 입력으로 허용한다. 갱신 범위에 포함된 활성 문서 포인터만 Markdown 링크로 보정하고, archive 스냅샷은 링크 표기만을 이유로 재포맷하지 않는다. +- `.agent-roadmap-sync/locks.yaml`의 `locked`, `rely-on.target`, Milestone identity(`: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 잠금이 해제될 때까지 `잠금`으로 둔다. -- 새 Milestone을 만들거나 `[스케치]`를 `[계획]`으로 승격하면서 `SDD: 필요`로 판정한 경우, 같은 `update-roadmap` 흐름 안에서 `roadmap-sdd create`까지 수행해 `agent-roadmap/sdd///SDD.md`를 만든다. `SDD: 필요`와 SDD 경로만 남기고 파일이 없는 상태로 종료하지 않는다. +- SDD gate가 필요한 Milestone은 `구현 잠금`에 `SDD: 필요`, 해당 Milestone 파일 위치 기준 `SDD 문서` Markdown 링크, 잠금 해제 조건을 남기고 SDD 잠금이 해제될 때까지 `잠금`으로 둔다. +- 새 Milestone을 만들거나 `[스케치]`를 `[계획]`으로 승격하면서 `SDD: 필요`로 판정한 경우, 같은 `update-roadmap` 흐름 안에서 `roadmap-sdd create`까지 수행해 `agent-roadmap/sdd///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로 처리한다 - 모드: - 수정 파일: - - agent-roadmap/ROADMAP.md - - agent-roadmap/current.md (local) - - agent-roadmap/phase//PHASE.md - - agent-roadmap/phase//milestones/.md - - agent-roadmap/sdd///SDD.md (SDD 작성/갱신 시) - - agent-roadmap/sdd///USER_REVIEW.md (SDD 사용자 리뷰 요청 시) - - agent-roadmap/archive/phase//... (archive 모드) - - agent-roadmap/archive/sdd///... (SDD archive 시) + - [ROADMAP.md](agent-roadmap/ROADMAP.md) + - [current.md](agent-roadmap/current.md) (local) + - [PHASE.md](agent-roadmap/phase//PHASE.md) + - [.md](agent-roadmap/phase//milestones/.md) + - [SDD.md](agent-roadmap/sdd///SDD.md) (SDD 작성/갱신 시) + - [USER_REVIEW.md](agent-roadmap/sdd///USER_REVIEW.md) (SDD 사용자 리뷰 요청 시) + - [archive PHASE.md](agent-roadmap/archive/phase//PHASE.md) 또는 [archive Milestone](agent-roadmap/archive/phase//milestones/.md) (archive 모드) + - [archive SDD.md](agent-roadmap/archive/sdd///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: <추가/수정/완료/제거 요약>