sync: from iop v1.1.165

agent-ops/.version

@@ -1 +1 @@
-1.1.164
+1.1.165

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

@@ -4,7 +4,7 @@
 
 ## 목적
 
-`agent-spec/`는 AI agent가 현재 구현된 기능의 동작, 책임 경계, 코드 진입점, 계약 링크, 검증 방법을 빠르게 파악하기 위한 living spec 저장소다.
+`agent-spec/`는 사람과 AI agent가 현재 구현된 기능 목록, 동작 흐름, 계약 링크, 검증 방법을 함께 파악하기 위한 living spec 저장소다.
 로드맵 완료 이력, SDD 설계 논의, 계약 원문, 사람용 가이드를 대체하지 않는다.
 
 ## 기본 구조
@@ -28,9 +28,11 @@ agent-spec/
 
 - `agent-spec/**`는 현재 구현 지도를 제공하지만 최종 truth는 코드, `agent-contract/`, 테스트, 설정 예시다.
 - API, wire protocol, runtime call, event/config schema, 프로세스 간 요청/응답 계약 원문은 `agent-contract/`에 두고 agent-spec에는 링크와 사용 맥락만 남긴다.
+- 코드 배치, 주요 구성 요소, 구현 진입점, 도메인 간 책임 경계, 유지할 패턴, 금지 사항은 domain rule에 둔다.
+- agent-spec에는 기능 이해에 필요한 최소 경계만 적고, 코딩할 때 따라야 하는 경계 규칙을 반복하지 않는다.
 - SDD는 구현 전 설계 게이트다. agent-spec은 구현 후 현재 상태를 설명한다.
 - 로드맵과 complete.log는 완료 근거와 변경 힌트로 사용한다. 현재 동작은 코드와 계약으로 재확인한다.
-- 사람용 최신 가이드는 `docs/`에 둔다. agent-spec은 agent 작업 문맥을 우선한다.
+- 사람용 최신 가이드는 `docs/`에 둔다. agent-spec은 기능 파악과 작업 문맥을 우선한다.
 
 ## Frontmatter Schema
 
@@ -51,10 +53,11 @@ agent-spec/
 ## 읽기 규칙
 
 - 일반 작업마다 `agent-spec/`를 읽지 않는다.
-- 기존 기능의 현재 동작, 책임 경계, 코드 진입점, 계약 링크가 필요한 작업에서만 세션 1회 `agent-spec/index.md`를 읽는다.
+- 기존 기능의 기능 목록, 주요 흐름, 계약 링크, 현재 구현 상태가 필요한 작업에서만 세션 1회 `agent-spec/index.md`를 읽는다.
 - `index.md`에서 매칭되는 spec 문서만 읽는다.
 - 매칭 spec이 없으면 스펙이 없다고 보고하고 코드, 계약, 테스트에서 직접 확인한다. 추측으로 spec 내용을 만들지 않는다.
 - spec 문서가 코드/계약과 충돌하면 코드/계약을 우선하고 `update-spec` 필요를 보고한다.
+- 코드 배치, 구현 위치, 패턴, 금지 사항, 도메인 간 상세 책임 경계가 필요하면 프로젝트 규칙의 도메인 매핑에 따라 domain rule을 읽는다.
 - API, wire protocol, runtime call, event/config schema, 프로세스 간 요청/응답 계약에 닿으면 `agent-contract/index.md`의 규칙에 따라 매칭 계약 문서도 읽는다.
 - `agent-spec/archive/**`는 일반 작업에서 읽지 않는다.
 - 예외: 사용자가 과거 스펙 확인, 복원, 비교, 특정 archive 경로 확인을 요청한 경우에만 필요한 archive 문서만 좁게 읽는다.
@@ -73,26 +76,31 @@ agent-spec/
 
 - 현재형으로 작성한다.
 - 과거 작업 일지, 설계 논쟁 전문, 완료된 roadmap task 전체 복사, 함수 단위 코드 설명을 넣지 않는다.
-- 스펙 본문은 기능 단위의 작동 지도여야 한다.
+- 스펙 본문은 기능 단위의 작동 지도여야 한다. 먼저 기능 목록을 두고, 필요한 흐름만 뒤에 보강한다.
+- 기능 목록은 `기능`과 `설명` 중심으로 작성한다. 활성 spec은 구현된 기능만 기록하므로 기능별 `상태` 칼럼을 기본으로 두지 않는다.
+- 기능별 부분 지원, 조건부 동작, 한계는 설명 또는 `한계와 주의사항`에 짧게 적는다.
+- 주요 흐름은 텍스트만 길게 나열하지 말고 Mermaid `sequenceDiagram` 또는 `flowchart`를 우선 고려한다. 단순 기능은 짧은 목록으로 충분하다.
+- 책임 경계는 기능 오해를 막는 최소 수준만 허용한다. 패키지 배치, 구현 진입점, 유지할 패턴, 금지 사항은 domain rule에 둔다.
+- `코드 진입점` 섹션은 기본 섹션으로 두지 않는다. 필요한 코드 근거는 frontmatter `source_evidence`와 domain rule로 좁힌다.
 - 계약 원문, proto field 전체 목록, config schema 원문을 복제하지 말고 `agent-contract/` 또는 코드 경로를 링크한다.
 - 불확실한 내용은 단정하지 말고 `불명확` 또는 `확인 필요`로 남긴다.
 - spec 갱신이 필요 없으면 `Spec update not needed: <사유>`를 결과 보고나 Milestone 완료 리뷰에 남긴다.
 
-## 표준 섹션
+## 기본 섹션
 
-spec 문서는 아래 섹션 순서를 유지한다.
+spec 문서는 아래 섹션을 기본 순서로 작성한다. 해당 spec에 의미가 없는 섹션은 만들지 않는다.
 
 1. `목적`
-2. `현재 동작`
+2. `기능 목록`
 3. `범위`
 4. `주요 흐름`
-5. `책임 경계`
+5. `계약`
-6. `계약`
+6. `설정/데이터/이벤트`
-7. `코드 진입점`
+7. `검증`
-8. `설정/데이터/이벤트`
+8. `한계와 주의사항`
-9. `검증`
+9. `변경 기록`
-10. `한계와 주의사항`
+
-11. `변경 기록`
+`책임 경계`가 기능 이해에 꼭 필요하면 별도 섹션으로 짧게 둘 수 있다. 이때 domain rule의 구성 요소, 코드 배치, 금지 사항을 반복하지 않는다.
 
 ## 템플릿
 

agent-ops/skills/common/_templates/agent-spec/index-template.md

@@ -3,11 +3,11 @@ spec_doc_type: index
 status: 활성
 ---
 
-# Agent Spec Index
+# 구현 스펙 색인
 
 ## 목적
 
-이 디렉터리는 현재 구현된 기능의 agent-facing living spec을 관리한다.
+이 디렉터리는 사람과 agent가 함께 보는 현재 구현 기능 living spec을 관리한다.
 로드맵 완료 이력, SDD, 계약 원문, 사람용 docs를 대체하지 않는다.
 
 ## 읽기 규칙
@@ -15,16 +15,19 @@ status: 활성
 - 필요한 작업에서만 이 index를 읽고, 매칭되는 spec 문서만 읽는다.
 - `archive/**`는 과거 비교, 복원, 특정 근거 확인 요청이 있을 때만 읽는다.
 - API, wire protocol, config/event schema, 프로세스 간 계약 원문은 `agent-contract/`를 따른다.
+- 코드 배치, 구현 진입점, 도메인 간 상세 책임 경계는 domain rule을 따른다.
 
 ## Spec Map
 
-| id | 상태 | 읽는 조건 | path | 주요 evidence |
+| id | 상태 | 언제 읽나 | path | 주요 근거 |
-|----|------|-----------|------|---------------|
+|----|------|-----------|------|-----------|
 | 없음 | 없음 | 없음 | 없음 | 없음 |
 
 ## 작성 규칙
 
 - 현재 구현 기준으로 작성한다.
+- 기능 목록과 주요 흐름을 먼저 파악할 수 있게 작성한다.
 - 코드/계약/테스트 evidence를 우선한다.
 - 계약 원문은 복제하지 않고 링크한다.
+- 코드 진입점과 도메인룰 성격의 상세 경계는 반복하지 않는다.
 - 불확실한 내용은 `불명확`으로 남긴다.

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

@@ -8,15 +8,17 @@ source_evidence:
     notes: <현재 구현 근거>
 ---
 
-# Spec: <title>
+# 스펙: <title>
 
 ## 목적
 
-<이 spec이 설명하는 현재 구현 기능과 agent가 이 문서를 읽어야 하는 이유>
+<이 spec이 설명하는 현재 구현 기능과 이 문서를 읽어야 하는 이유>
 
-## 현재 동작
+## 기능 목록
 
-- <현재 코드와 계약으로 확인된 동작>
+| 기능 | 설명 |
+|------|------|
+| <기능명> | <현재 코드와 계약으로 확인된 동작> |
 
 ## 범위
 
@@ -25,31 +27,28 @@ source_evidence:
 
 ## 주요 흐름
 
-1. <주요 실행 흐름>
+```mermaid
-
+sequenceDiagram
-## 책임 경계
+  participant A as <주체>
-
+  participant B as <주체>
-- <컴포넌트/프로세스/계층별 책임 경계>
+  A->>B: <주요 메시지 또는 동작>
+```
 
 ## 계약
 
-- <관련 agent-contract 문서 또는 없음>
+- <관련 agent-contract 문서 또는 코드 계약 포인터>
-
-## 코드 진입점
-
-- `<path>` - <역할>
 
 ## 설정/데이터/이벤트
 
-- <관련 config, 저장소, event, runtime state 요약. 원문 schema는 링크만 둔다.>
+- <관련 config, 저장소, event, runtime state 요약. 원문 schema는 복제하지 않는다.>
 
 ## 검증
 
-- `<command or profile>` - <기대 결과 또는 근거>
+- `<command or profile>` - <기대 결과>
 
 ## 한계와 주의사항
 
-- <현재 구현 한계, known limitation, 수정 시 주의점>
+- <현재 구현 한계 또는 조건부 동작>
 
 ## 변경 기록
 

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

@@ -8,8 +8,8 @@ description: agent-spec 최초 생성, 현재 구현 스펙 작성, living spec
 
 ## 목적
 
-현재 구현된 기능의 agent-facing living spec을 새로 만든다.
+현재 구현된 기능의 living spec을 새로 만든다.
-스펙은 로드맵 완료 이력이나 계약 원문을 복제하지 않고, agent가 작업 전에 현재 동작과 코드 진입점을 빠르게 찾는 지도로 유지한다.
+스펙은 로드맵 완료 이력이나 계약 원문을 복제하지 않고, 사람과 agent가 구현된 기능, 동작 흐름, 계약/검증 포인터를 함께 확인하는 문서로 유지한다.
 
 ## 언제 호출할지
 
@@ -55,14 +55,19 @@ description: agent-spec 최초 생성, 현재 구현 스펙 작성, living spec
    - 기존 같은 `spec-id` 문서가 있으면 새로 만들지 말고 `update-spec` 대상이라고 보고한다.
 
 4. **spec 문서 작성**
-   - spec template의 표준 섹션 순서를 유지한다.
+   - spec template의 기본 섹션 구조를 따른다.
    - frontmatter의 `spec_doc_type`, `spec_id`, `status`, `source_evidence`를 채운다.
    - `status`는 evidence 수준에 따라 `구현됨`, `부분`, `가정`, `불명확` 중 하나로 둔다.
+   - `기능 목록`을 `목적` 다음에 바로 둔다.
+   - 기능 목록은 `기능`과 `설명` 중심으로 작성한다. 기능별 `상태` 칼럼은 기본 생성하지 않는다.
+   - `주요 흐름`은 Mermaid `sequenceDiagram` 또는 `flowchart`를 우선 고려한다. 단순 기능은 짧은 목록으로 둔다.
+   - 책임 경계는 기능 이해에 필요한 최소 수준만 적고, 도메인별 코드 배치나 금지 사항은 domain rule로 넘긴다.
    - 계약 원문, proto field 전체 목록, config schema 원문은 복제하지 않고 링크한다.
-   - 주요 코드 진입점과 검증 방법을 경로와 명령으로 남긴다.
+   - `코드 진입점` 섹션은 만들지 않는다. 코드 근거는 `source_evidence`에 남긴다.
+   - 검증 방법은 실행 가능한 명령 또는 확인 기준으로 남긴다.
 
 5. **index 갱신**
-   - `Spec Map`에 새 spec id, 상태, 읽는 조건, path, 주요 evidence를 추가하거나 보정한다.
+   - `Spec Map`에 새 spec id, 상태, 읽는 조건, path, 주요 근거를 추가하거나 보정한다.
    - 매칭 조건은 agent가 좁게 읽을 수 있도록 기능명, 코드 경로, 계약 id, 운영 표면 중심으로 쓴다.
    - 기존 행을 삭제하거나 재정렬하지 않는다. 명백히 placeholder인 `없음` 행은 첫 실제 spec 추가 시 제거할 수 있다.
 
@@ -73,7 +78,9 @@ description: agent-spec 최초 생성, 현재 구현 스펙 작성, living spec
 ## 실행 결과 검증
 
 - [ ] `agent-spec/index.md`가 존재하고 Spec Map에 생성한 spec이 들어 있는가
-- [ ] 생성한 spec 문서가 `rules-agent-spec.md`의 표준 섹션 순서를 유지하는가
+- [ ] 생성한 spec 문서가 `rules-agent-spec.md`의 기본 섹션 기준을 따르는가
+- [ ] 기능 목록이 기능/설명 중심이며 불필요한 상태 칼럼이나 과한 상세 설명을 만들지 않았는가
+- [ ] 코드 진입점, 패키지 배치, 도메인별 금지 사항을 spec 본문에 반복하지 않았는가
 - [ ] frontmatter의 `spec_doc_type`, `spec_id`, `status`, `source_evidence`가 채워졌는가
 - [ ] source evidence path가 실제 파일이거나 `path: null`인 사용자 근거인가
 - [ ] 계약 원문을 복제하지 않고 `agent-contract/` 또는 코드 링크로 연결했는가
@@ -91,7 +98,7 @@ description: agent-spec 최초 생성, 현재 구현 스펙 작성, living spec
   - [index.md](agent-spec/index.md)
   - [<spec-id>.md](agent-spec/<area>/<spec-id>.md)
 - 상태: <구현됨 | 부분 | 가정 | 불명확>
-- 주요 evidence:
+- 주요 근거:
   - <path 또는 사용자 근거> - <요약>
 
 ## TODO 항목
@@ -105,5 +112,6 @@ description: agent-spec 최초 생성, 현재 구현 스펙 작성, living spec
 - 현재 코드/계약으로 확인하지 않은 내용을 구현 사실처럼 쓰지 않는다.
 - archive 전체를 훑지 않는다.
 - 기존 spec이 있으면 중복 spec을 만들지 않는다.
+- 코드 진입점, 구현 배치, 도메인 간 상세 책임 경계, 유지할 패턴, 금지 사항을 domain rule 대신 agent-spec에 길게 쓰지 않는다.
 - 사람용 공개 가이드를 agent-spec에 장황하게 작성하지 않는다.
 - spec 생성과 무관한 코드 파일을 수정하지 않는다.

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

@@ -50,7 +50,9 @@ description: agent-spec 갱신, 구현 스펙 업데이트, 완료 기능 스펙
    - spec과 코드/계약이 충돌하면 코드/계약을 우선하고 spec을 수정한다.
 
 3. **영향 판정**
-   - 현재 동작, 범위, 주요 흐름, 책임 경계, 계약 링크, 코드 진입점, 설정/데이터/이벤트, 검증, 한계 중 바뀐 항목을 식별한다.
+   - 기능 목록, 범위, 주요 흐름, 계약 링크, 설정/데이터/이벤트, 검증, 한계 중 바뀐 항목을 식별한다.
+   - 기능 이해에 필요한 최소 책임 설명이 바뀐 경우만 spec에 반영한다.
+   - 코드 배치, 구현 진입점, 유지할 패턴, 금지 사항 변경은 domain rule 갱신 대상으로 본다.
    - 변경이 테스트 fixture, 내부 리팩터링, 문구 정리처럼 현재 구현 spec에 영향을 주지 않으면 `Spec update not needed: <사유>`를 남긴다.
    - 판단 불가이면 spec을 추정 갱신하지 않고 `Spec blocked: <필요 evidence>`로 보고한다.
 
@@ -58,12 +60,15 @@ description: agent-spec 갱신, 구현 스펙 업데이트, 완료 기능 스펙
    - `mode=check-only`이면 쓰지 않고 갱신 후보만 보고한다.
    - 영향이 있는 spec 문서만 수정한다.
    - frontmatter `status`와 `source_evidence`를 현재 evidence에 맞게 보강한다.
-   - 표준 섹션 순서를 유지한다.
+   - `rules-agent-spec.md`의 기본 섹션 기준을 따른다.
+   - 기능 목록은 `기능`과 `설명` 중심으로 유지한다. 기능별 `상태` 칼럼은 기본 추가하지 않는다.
+   - `주요 흐름`은 긴 텍스트보다 Mermaid `sequenceDiagram` 또는 `flowchart`를 우선 고려한다.
+   - `코드 진입점` 섹션은 추가하지 않는다. 기존 spec에 있으면 현재 기준에 맞춰 제거하거나 `source_evidence`로 옮긴다.
    - 계약 원문을 복제하지 않고 링크만 보강한다.
    - 변경 기록에 날짜, 변경 근거, 관련 Milestone/complete.log/코드 경로를 남긴다.
 
 5. **index 동기화**
-   - spec 상태, 읽는 조건, path, 주요 evidence가 바뀌었으면 `agent-spec/index.md`의 Spec Map을 갱신한다.
+   - spec 상태, 읽는 조건, path, 주요 근거가 바뀌었으면 `agent-spec/index.md`의 Spec Map을 갱신한다.
    - 새 spec 문서가 필요하면 `create-spec` 대상으로 보고하고 index를 추정 갱신하지 않는다.
    - 폐기된 spec은 활성 문서에 남기지 않고 archive log로 이동할 후보로 보고한다. 명시 요청 없이 archive 이동하지 않는다.
 
@@ -77,7 +82,9 @@ description: agent-spec 갱신, 구현 스펙 업데이트, 완료 기능 스펙
 
 - [ ] `agent-spec/index.md`에서 관련 spec만 읽었는가
 - [ ] 코드/계약/테스트 기준으로 현재 동작을 재확인했는가
-- [ ] spec 문서의 표준 섹션과 frontmatter가 유지되는가
+- [ ] spec 문서의 기본 섹션 기준과 frontmatter가 유지되는가
+- [ ] 기능 목록이 기능/설명 중심이며 불필요한 상태 칼럼이나 과한 상세 설명을 만들지 않았는가
+- [ ] 코드 진입점, 패키지 배치, 도메인별 금지 사항을 spec 본문에 반복하지 않았는가
 - [ ] index의 Spec Map이 갱신한 spec 상태와 일치하는가
 - [ ] 계약 원문을 복제하지 않았는가
 - [ ] 갱신/불필요/create 필요/차단 중 하나의 결과가 명확한가
@@ -114,3 +121,4 @@ description: agent-spec 갱신, 구현 스펙 업데이트, 완료 기능 스펙
 - 매칭되지 않는 spec을 광범위하게 읽거나 전부 갱신하지 않는다.
 - archive spec을 명시 요청 없이 읽거나 갱신하지 않는다.
 - complete.log나 roadmap 문구만으로 현재 동작을 단정하지 않는다.
+- 코드 진입점, 구현 배치, 도메인 간 상세 책임 경계, 유지할 패턴, 금지 사항을 domain rule 대신 agent-spec에 길게 쓰지 않는다.