@tienne/gestalt 0.35.0 → 0.36.1

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tienne/gestalt",
-  "version": "0.35.0",
+  "version": "0.36.1",
   "description": "TypeScript AI Development Harness - Gestalt psychology-driven requirement clarification",
   "type": "module",
   "main": "./dist/src/index.js",

package/dist/role-agents/change-context-writer/AGENT.md

@@ -48,11 +48,66 @@ You are the Change Context Writer role agent.
 
 **변경 의도**: (왜 바꿨는지 1-2문장)
 **영향 범위**: (변경 유형 라벨 + 핵심 파일)
-**변경 전 → 후**: (핵심 동작 비교)
+
+## 흐름 변화 (AS-IS → TO-BE)
+
+(아래 "흐름 변화 서술" 가이드에 따라 화살표 대비 / 대비 표 / Mermaid 중 diff 성격에 맞게 작성)
 
 ### [감지된 유형별 섹션]
 ```
 
+### 흐름 변화 서술 (AS-IS → TO-BE) — 필수 섹션
+
+PR은 결국 사람이 읽는다. 이번 변경으로 **흐름이 어떻게 달라지는지**를 리뷰어가 스캔하듯 한눈에 파악할 수 있도록, `## 흐름 변화 (AS-IS → TO-BE)` 섹션을 반드시 작성한다. diff의 성격을 보고 아래 두 포맷 중 맞는 쪽을 고른다. 하나의 변경에 두 성격이 섞여 있으면 둘 다 써도 된다.
+
+**1) 순서·경로가 바뀐 경우 → 화살표 대비**
+
+호출 순서, 처리 단계, 사용자 경로처럼 "거치는 순서"가 달라졌으면 단계 나열로 대비한다. 신규·삭제된 단계는 뒤에 한 줄로 짚어 준다.
+
+```
+**AS-IS**
+요청 → 검증 → 저장 → 응답
+
+**TO-BE**
+요청 → 검증 → 캐시 확인 → 저장 → 이벤트 발행 → 응답
+
+▸ 캐시 확인, 이벤트 발행 단계 신규 추가
+```
+
+**2) 항목별 정책·값이 바뀐 경우 → 대비 표**
+
+인증 방식, 기본값, 제약, 정책처럼 "항목별 값"이 달라졌으면 구분 열을 둔 표로 대비한다.
+
+```
+| 구분 | AS-IS | TO-BE |
+|------|-------|-------|
+| 인증 | 세션 쿠키 | JWT 토큰 |
+| 만료 | 없음 | 30분 |
+| 갱신 | 재로그인 | 자동 refresh |
+```
+
+**3) 분기·병렬·상태 전이가 얽힌 경우 → Mermaid flowchart (선택적)**
+
+직선 화살표로 나열하면 흐름이 왜곡되는 경우에만 쓴다. 조건 분기(if/else 경로), 병렬 처리, 상태 머신 전이처럼 **경로가 갈라지거나 합쳐지는 구조**가 이번 변경의 핵심일 때에 한한다. GitHub PR에서 렌더링되므로 리뷰어에게 효과적이지만, diff가 크면 부정확해지기 쉬우니 확실히 읽히는 흐름만 그린다.
+
+```mermaid
+flowchart LR
+  A[요청] --> B{캐시 히트?}
+  B -->|Yes| C[캐시 응답]
+  B -->|No| D[검증 → 저장]
+  D --> E[이벤트 발행]
+  E --> F[응답]
+```
+
+Mermaid를 쓸 때도 무엇이 바뀌었는지 한 줄로 짚어 준다 (예: `▸ 캐시 분기와 이벤트 발행 경로 신규`). AS-IS와 TO-BE 흐름이 둘 다 복잡하면 다이어그램 두 개로 나눠 대비한다.
+
+작성 원칙:
+
+- 포맷 판단은 diff에서 읽히는 변화의 성격을 근거로 한다. 순서/단계가 핵심이면 화살표, 항목/값이 핵심이면 표, **경로가 갈라지고 합쳐지는 게 핵심이면 Mermaid**.
+- Mermaid는 기본 선택지가 아니다. 화살표 나열로 충분히 읽히면 굳이 다이어그램을 만들지 않는다. 분기·병렬·상태 전이가 없는 선형 흐름에 Mermaid를 쓰지 않는다.
+- AS-IS는 변경 전 코드(기준 브랜치)에서 읽히는 흐름, TO-BE는 변경 후 흐름이다. 추측하지 말고 diff에서 확인되는 것만 대비한다.
+- 순수 리팩터링·문서 수정처럼 외부에서 관찰되는 흐름 변화가 없으면, 억지로 표를 만들지 말고 `흐름 변화 없음 — 내부 구조 정리` 한 줄로 명시한다.
+
 유형별 섹션 작성 가이드:
 
 - **사용자 앱**: `### 사용자 플로우 변화` / `### 정책 변화` — 사용자가 거치는 경로가 어떻게 달라지는지, 적용되는 규칙·제약·기본값이 어떻게 바뀌는지.

package/dist/role-agents/technical-writer/references/ai-tell-quick-rules.md

@@ -39,6 +39,7 @@
 | B-1 | 한글 + 괄호 영어 매번 ("~(Sovereign AI)" 처럼) | S2 | 첫 등장만 병기, 이후 한글만 |
 | B-2 | 영어 어휘 직역 가능한데 그대로 | S2 | 한국어로 옮기되 업계 표준은 유지 |
 | B-3 | 안 굳어진 영어 구·단어 음차 표기 ("소스 오브 트루스") | S1 | 한글 의역 + 첫 등장만 원어 괄호 병기("진실의 원천(source of truth)"), 이후 한글만. 단 위 "굳어진 음차 화이트리스트"에 있는 정착어는 Do-NOT — of/and 등 기능어까지 통째 음차한 구(룩 앤 필·로우 행잉 프룻)가 최우선 대상 |
+| B-4 | 영어 개념을 어색하게 옮긴 조어("소비처" ← consumer, "생산처") | S2 | 정착한 우리말로("소비처" → "사용처", 코드 맥락이면 "호출부"). 억지 신조어 대신 이미 쓰이는 말 |
 
 ## C. 구조적 AI 패턴
 

package/dist/skills/pr/SKILL.md

@@ -114,6 +114,10 @@ git diff {target}...HEAD             # 실제 diff (핵심 변경만)
 0단계의 `repoRules` 구조 + 3단계의 `changeContext` + 1단계의 `prIntent`를 합성해 PR description을 작성합니다.
 
 - **PR 제목**: `CLAUDE.md`가 있으면 그 커밋 컨벤션을 따릅니다 (예: `type(scope): subject`).
+- **흐름 변화 (AS-IS → TO-BE)**: `changeContext`에 담긴 `## 흐름 변화 (AS-IS → TO-BE)` 섹션을 PR description에 반드시 포함합니다. PR은 사람이 리뷰하므로, 이번 변경으로 흐름이 어떻게 달라지는지를 리뷰어가 스캔하듯 파악할 수 있어야 합니다. 화살표 대비/대비 표 포맷은 3단계 에이전트가 diff 성격에 맞게 이미 골라 둔 것을 그대로 씁니다.
+  - **PR 템플릿이 있는 경우**: 템플릿 구조를 깨지 않는 선에서, 변경 요약 성격의 섹션(예: Changes, 변경 사항) 안이나 바로 아래에 흐름 변화를 배치합니다. 템플릿에 이미 유사 섹션이 있으면 그 안에 녹입니다.
+  - **템플릿이 없는 경우**: `## Changes` 아래에 흐름 변화 섹션을 둡니다.
+  - 흐름 변화가 없는 변경(순수 리팩터링·문서 수정 등)이면 에이전트가 남긴 `흐름 변화 없음` 표기를 그대로 반영하고 억지로 표를 만들지 않습니다.
 - 생성된 description을 **사용자에게 미리보기로 먼저 표시**합니다.
 
 ### 5단계: gh pr create 확인 및 실행

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tienne/gestalt",
-  "version": "0.35.0",
+  "version": "0.36.1",
   "description": "TypeScript AI Development Harness - Gestalt psychology-driven requirement clarification",
   "type": "module",
   "main": "./dist/src/index.js",

package/role-agents/change-context-writer/AGENT.md

@@ -48,11 +48,66 @@ You are the Change Context Writer role agent.
 
 **변경 의도**: (왜 바꿨는지 1-2문장)
 **영향 범위**: (변경 유형 라벨 + 핵심 파일)
-**변경 전 → 후**: (핵심 동작 비교)
+
+## 흐름 변화 (AS-IS → TO-BE)
+
+(아래 "흐름 변화 서술" 가이드에 따라 화살표 대비 / 대비 표 / Mermaid 중 diff 성격에 맞게 작성)
 
 ### [감지된 유형별 섹션]
 ```
 
+### 흐름 변화 서술 (AS-IS → TO-BE) — 필수 섹션
+
+PR은 결국 사람이 읽는다. 이번 변경으로 **흐름이 어떻게 달라지는지**를 리뷰어가 스캔하듯 한눈에 파악할 수 있도록, `## 흐름 변화 (AS-IS → TO-BE)` 섹션을 반드시 작성한다. diff의 성격을 보고 아래 두 포맷 중 맞는 쪽을 고른다. 하나의 변경에 두 성격이 섞여 있으면 둘 다 써도 된다.
+
+**1) 순서·경로가 바뀐 경우 → 화살표 대비**
+
+호출 순서, 처리 단계, 사용자 경로처럼 "거치는 순서"가 달라졌으면 단계 나열로 대비한다. 신규·삭제된 단계는 뒤에 한 줄로 짚어 준다.
+
+```
+**AS-IS**
+요청 → 검증 → 저장 → 응답
+
+**TO-BE**
+요청 → 검증 → 캐시 확인 → 저장 → 이벤트 발행 → 응답
+
+▸ 캐시 확인, 이벤트 발행 단계 신규 추가
+```
+
+**2) 항목별 정책·값이 바뀐 경우 → 대비 표**
+
+인증 방식, 기본값, 제약, 정책처럼 "항목별 값"이 달라졌으면 구분 열을 둔 표로 대비한다.
+
+```
+| 구분 | AS-IS | TO-BE |
+|------|-------|-------|
+| 인증 | 세션 쿠키 | JWT 토큰 |
+| 만료 | 없음 | 30분 |
+| 갱신 | 재로그인 | 자동 refresh |
+```
+
+**3) 분기·병렬·상태 전이가 얽힌 경우 → Mermaid flowchart (선택적)**
+
+직선 화살표로 나열하면 흐름이 왜곡되는 경우에만 쓴다. 조건 분기(if/else 경로), 병렬 처리, 상태 머신 전이처럼 **경로가 갈라지거나 합쳐지는 구조**가 이번 변경의 핵심일 때에 한한다. GitHub PR에서 렌더링되므로 리뷰어에게 효과적이지만, diff가 크면 부정확해지기 쉬우니 확실히 읽히는 흐름만 그린다.
+
+```mermaid
+flowchart LR
+  A[요청] --> B{캐시 히트?}
+  B -->|Yes| C[캐시 응답]
+  B -->|No| D[검증 → 저장]
+  D --> E[이벤트 발행]
+  E --> F[응답]
+```
+
+Mermaid를 쓸 때도 무엇이 바뀌었는지 한 줄로 짚어 준다 (예: `▸ 캐시 분기와 이벤트 발행 경로 신규`). AS-IS와 TO-BE 흐름이 둘 다 복잡하면 다이어그램 두 개로 나눠 대비한다.
+
+작성 원칙:
+
+- 포맷 판단은 diff에서 읽히는 변화의 성격을 근거로 한다. 순서/단계가 핵심이면 화살표, 항목/값이 핵심이면 표, **경로가 갈라지고 합쳐지는 게 핵심이면 Mermaid**.
+- Mermaid는 기본 선택지가 아니다. 화살표 나열로 충분히 읽히면 굳이 다이어그램을 만들지 않는다. 분기·병렬·상태 전이가 없는 선형 흐름에 Mermaid를 쓰지 않는다.
+- AS-IS는 변경 전 코드(기준 브랜치)에서 읽히는 흐름, TO-BE는 변경 후 흐름이다. 추측하지 말고 diff에서 확인되는 것만 대비한다.
+- 순수 리팩터링·문서 수정처럼 외부에서 관찰되는 흐름 변화가 없으면, 억지로 표를 만들지 말고 `흐름 변화 없음 — 내부 구조 정리` 한 줄로 명시한다.
+
 유형별 섹션 작성 가이드:
 
 - **사용자 앱**: `### 사용자 플로우 변화` / `### 정책 변화` — 사용자가 거치는 경로가 어떻게 달라지는지, 적용되는 규칙·제약·기본값이 어떻게 바뀌는지.

package/role-agents/technical-writer/references/ai-tell-quick-rules.md

@@ -39,6 +39,7 @@
 | B-1 | 한글 + 괄호 영어 매번 ("~(Sovereign AI)" 처럼) | S2 | 첫 등장만 병기, 이후 한글만 |
 | B-2 | 영어 어휘 직역 가능한데 그대로 | S2 | 한국어로 옮기되 업계 표준은 유지 |
 | B-3 | 안 굳어진 영어 구·단어 음차 표기 ("소스 오브 트루스") | S1 | 한글 의역 + 첫 등장만 원어 괄호 병기("진실의 원천(source of truth)"), 이후 한글만. 단 위 "굳어진 음차 화이트리스트"에 있는 정착어는 Do-NOT — of/and 등 기능어까지 통째 음차한 구(룩 앤 필·로우 행잉 프룻)가 최우선 대상 |
+| B-4 | 영어 개념을 어색하게 옮긴 조어("소비처" ← consumer, "생산처") | S2 | 정착한 우리말로("소비처" → "사용처", 코드 맥락이면 "호출부"). 억지 신조어 대신 이미 쓰이는 말 |
 
 ## C. 구조적 AI 패턴
 

package/skills/pr/SKILL.md

@@ -114,6 +114,10 @@ git diff {target}...HEAD             # 실제 diff (핵심 변경만)
 0단계의 `repoRules` 구조 + 3단계의 `changeContext` + 1단계의 `prIntent`를 합성해 PR description을 작성합니다.
 
 - **PR 제목**: `CLAUDE.md`가 있으면 그 커밋 컨벤션을 따릅니다 (예: `type(scope): subject`).
+- **흐름 변화 (AS-IS → TO-BE)**: `changeContext`에 담긴 `## 흐름 변화 (AS-IS → TO-BE)` 섹션을 PR description에 반드시 포함합니다. PR은 사람이 리뷰하므로, 이번 변경으로 흐름이 어떻게 달라지는지를 리뷰어가 스캔하듯 파악할 수 있어야 합니다. 화살표 대비/대비 표 포맷은 3단계 에이전트가 diff 성격에 맞게 이미 골라 둔 것을 그대로 씁니다.
+  - **PR 템플릿이 있는 경우**: 템플릿 구조를 깨지 않는 선에서, 변경 요약 성격의 섹션(예: Changes, 변경 사항) 안이나 바로 아래에 흐름 변화를 배치합니다. 템플릿에 이미 유사 섹션이 있으면 그 안에 녹입니다.
+  - **템플릿이 없는 경우**: `## Changes` 아래에 흐름 변화 섹션을 둡니다.
+  - 흐름 변화가 없는 변경(순수 리팩터링·문서 수정 등)이면 에이전트가 남긴 `흐름 변화 없음` 표기를 그대로 반영하고 억지로 표를 만들지 않습니다.
 - 생성된 description을 **사용자에게 미리보기로 먼저 표시**합니다.
 
 ### 5단계: gh pr create 확인 및 실행