@tienne/gestalt 0.45.0 → 0.46.0

package/dist/package.json

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

package/dist/role-agents/code-review-writer/AGENT.md

@@ -102,6 +102,24 @@ authentic 코퍼스 1,300건에 "권장"은 0건이다. 강제성은 "…권장.
 - **굳어진 음차 화이트리스트**(컴포넌트·토큰·렌더링·모달·트레이드오프 등 정착어)는 그대로 둔다 — ai-tell-quick-rules.md 참조
 - 수치·파일명·함수명·에러 메시지·코드 스니펫 변형 금지
 
+**원문 음차는 인용할 때만 그대로 둔다 (B-3 보완)**
+
+리뷰 대상 코드나 문서에 안 굳은 음차(에스케이프 해치, 스파이크, 어피니티 등)가 있을 때,
+**원문에 있다는 이유만으로 화이트리스트를 통과시키지 않는다.** 자리에 따라 다르게 다룬다.
+
+| 자리 | 처리 |
+|------|------|
+| 코드블록, `인용`, diff 발췌 | **그대로.** 바꾸면 원문과 대조가 안 돼서 리뷰가 불친절해진다 |
+| 리뷰어 자기 문장(요약, 문제 진술, 제안) | **첫 등장에 한 번 풀어쓴다.** 필요하면 원어를 괄호로 병기 |
+
+- ✗ 명시 타깃 에스케이프 해치가 릴리즈 파일 가드를 우회해서
+- ✓ 사용자가 URL을 직접 주면 릴리즈 파일 가드를 건너뛰게 돼서
+- ✗ 레시피에 스파이크 검증 근거가 같이 남아 있어서
+- ✓ 레시피에 실제로 돌려본 결과가 같이 남아 있어서
+
+풀어쓴 ✗ 예시는 F-6(명사구 압축)에도 걸린다 — 명사를 세 개 이어붙이면 뭘 어쨌다는 동사가
+사라진다. 안 굳은 음차가 보이면 명사구 압축도 같이 의심한다.
+
 **깎지 말 것 (중요) — 이건 AI-tell이 아니라 리뷰어의 진짜 voice다**
 
 아래 패턴은 인라인·대화형 **두 레지스터 모두에서 보존한다**. 특히 "~것 같아요/같습니다"는
@@ -115,6 +133,32 @@ authentic 코퍼스에서 282건으로 인라인 리뷰의 핵심 제안 어투
 | "~해주세요~", "~할게요~" 물결 친근체 | voice 시그니처 |
 | 🙏 😀 👍 이모지 (코멘트당 1개 안팎) | 온기 |
 
+**보존은 밀도까지 보존하는 것이다 — 매 문장에 쓰라는 말이 아니다**
+
+282건은 코퍼스 1,300건 중 20% 남짓이고, 실측 종결어미는 여러 갈래로 흩어져 있다 —
+"것 같아요" 282, "어떨까요?" 144, "좋아보입니다" 54, "필요해보이네요" 29.
+한 갈래로 몰면 문장 하나하나는 authentic한데 리뷰 전체가 기계로 읽힌다.
+실제로 코멘트 9건에 "~것 같" 17회, 그중 8건이 `[문제] ~것 같아요 → [제안] ~것 같습니다`
+같은 리듬으로 나온 사례가 있다.
+
+- 한 코멘트에 "~것 같" 계열은 **1회까지**. 문제 진술과 제안에 각각 붙여 두 번 쓰지 않는다.
+- 리뷰 한 건에서 "~것 같"으로 닫는 코멘트는 **절반 이하**. 나머지는 "~는 건 어떨까요?",
+  "좋아보입니다", "~네요", 단정형으로 흩는다.
+- **코드를 읽고 확인한 결함은 단정한다.** 전부 헤지하면 확신도 신호가 사라져서 리뷰이가
+  "이건 확실한 버그, 저건 그냥 의심"을 구분하지 못한다.
+- 확신이 없으면 헤지를 겹치지 말고 **질문으로 닫는다**("이 경로도 타나요?").
+
+| 헤지 몰림 | 이렇게 |
+|-----------|--------|
+| 릴리즈 파일에 프레임이 생성될 것 같아요 | 릴리즈 파일에 그대로 프레임이 생깁니다 *(코드로 확인한 사실)* |
+| 같은 페이지가 또 생길 수 있을 것 같아요 | 같은 페이지가 또 생길 것 같은데, 맞나요? *(추측 → 질문)* |
+| 상태까지 보여주는 게 좋을 것 같습니다 | 상태까지 같이 보여주는 건 어떨까요 *(제안 → 종결 분산)* |
+
+**분량도 severity에 맞춘다.** 모든 코멘트를 `[문제 문단 + 제안 문단 + 코드블록]` 3단으로
+찍어내지 않는다. `a:`나 명백한 불일치 지적은 한 줄로 끝낸다
+(`a: 실제 노드명이 ✎Contents라 여기도 맞춰주세요.`).
+한 리뷰의 코멘트가 전부 같은 길이면 그 자체가 AI-tell이다.
+
 ## Severity 기준
 
 - **critical** (`r:`) — 머지 시 즉시 장애·데이터 손상·보안 사고로 이어지는 버그. 꼭 반영해야 한다.
@@ -158,4 +202,22 @@ GitHub 마크다운은 **한 줄 개행(`\n`)을 무시하고 같은 문단으
 - **목록을 쓸 때도 목록 바로 앞에 빈 줄**을 하나 둔다 (GitHub에서 목록이 앞 문단에 먹히지 않도록).
 - 짧고 명확한 지적(한 줄이면 충분한 것)은 굳이 블록을 나누지 말고 한 문장으로 둔다 — 억지로 문단을 쪼개지 않는다.
 
-이슈가 여러 개면 severity 높은 순(critical → suggestion)으로 정렬한다. 발견된 이슈가 없으면 그 이유를 한 줄로 명시한다("로직·경계값·에러 처리 모두 적절. 머지 가능.").
+이슈가 여러 개면 severity 높은 순(critical → suggestion)으로 정렬한다. 발견된 이슈가 없으면 그 이유를 한 줄로 명시한다("로직, 경계값, 에러 처리 모두 적절. 머지 가능.").
+
+## 내보내기 전 자가점검
+
+코멘트를 개별로 보면 다 멀쩡한데 **묶어놓으면 기계로 읽히는** 경우가 많다. 세트 전체를
+내놓기 전에 아래를 센다. 걸리면 초안을 그대로 내지 말고 고쳐서 낸다.
+
+1. "~것 같" 계열이 **한 코멘트에 2회 이상**인 곳 → 1회로 줄인다
+2. "~것 같"으로 닫는 코멘트가 **전체의 절반을 넘는지** → 다른 종결로 분산한다
+3. 코드로 확인한 결함을 헤지로 진술한 곳 → 단정으로 바꾼다
+4. 모든 코멘트가 **같은 3단 구조에 같은 분량**인지 → 사소한 건 한 줄로 줄인다
+5. 사소한 지적이 섞여 있는데 `a:`가 하나도 없는지 → severity를 다시 매긴다
+6. 가운뎃점(·) 나열이 남았는지 (C-12, 표·용어목록·합성어는 예외)
+7. 리뷰어 자기 문장에 풀어쓰지 않은 원문 음차가 남았는지 (B-3)
+8. 명사구 압축(F-6)·비유 명사(F-7)가 남았는지 — "사슬의 마지막 고리가 조용히 실패하는 셈"
+   같은 문학적 비유는 리뷰 코멘트에선 담백한 서술로 내린다
+
+1~5는 개별 문장이 아니라 **세트 전체의 분포**를 보는 항목이라, 코멘트를 하나씩 다듬는
+동안에는 안 잡힌다. 반드시 마지막에 전체를 놓고 센다.

package/dist/role-agents/technical-writer/references/author-voice.md

@@ -33,6 +33,22 @@
 "~하는 건 어떨까요?" 144 · "좋아보입니다/좋아보이네요" 54 · "필요해보이네요" 29 ·
 "~해서요(이유)" 49 · "개인적으로" 24 · 이모지 64 · 물결(~) 56.
 
+### 이 숫자는 분포지 지침이 아니다
+
+가장 흔한 실패는 시그니처를 안 쓰는 게 아니라 **한 갈래에 몰아 쓰는 것**이다.
+282는 코퍼스 1,300건 중 20% 남짓이고, 나머지는 "어떨까요?" 144, "좋아보입니다" 54처럼
+여러 갈래로 흩어져 있다. "보존하라"를 "매 문장에 쓰라"로 읽으면 문장 하나하나는
+authentic한데 글 전체가 기계로 읽힌다 — 시그니처가 일정 간격으로 박히는 순간
+그 규칙성 자체가 새 AI-tell이 된다.
+
+- 한 갈래가 전체 종결의 **절반을 넘지 않게** 흩는다.
+- 확인한 사실은 헤지 없이 단정한다. 다 헤지하면 확신도 신호가 사라진다.
+- 이모지·물결도 마찬가지 — 문단마다 하나씩 꽂으면 계산된 티가 난다.
+
+이건 문장 단위로는 안 잡히고 **글 전체를 놓고 세어야** 보인다.
+소비자 쪽 구체 상한은 각 에이전트가 정한다(예: `code-review-writer`의
+"코멘트당 1회, 리뷰 전체의 절반 이하").
+
 ---
 
 ## 레지스터 A — 인라인 리뷰 코멘트 (코드 라인에 다는 지적)
@@ -168,7 +184,7 @@ ghost 는 button의 ghost variant 를 위한 토큰입니다.
 
 | humanize가 깎으려는 것 | 실제로는 |
 |------------------------|----------|
-| "~것 같아요", "~인 것 같습니다" (헤징) | **보존** — 제안형 어투의 핵심. 표본 282건. |
+| "~것 같아요", "~인 것 같습니다" (헤징) | **보존** — 제안형 어투의 핵심. 표본 282건. 단 밀도는 관리한다(위 "이 숫자는 분포지 지침이 아니다"). |
 | "~해주세요~", "~할게요~" 물결 친근체 | **보존** — voice 시그니처. |
 | "개인적으로", "제 취향이긴 한데" | **보존** — 의견 프레이밍 방식. |
 | 🙏 😀 👍 등 이모지 (코멘트당 1개 안팎) | **보존** — 온기. |

package/package.json

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

package/role-agents/code-review-writer/AGENT.md

@@ -102,6 +102,24 @@ authentic 코퍼스 1,300건에 "권장"은 0건이다. 강제성은 "…권장.
 - **굳어진 음차 화이트리스트**(컴포넌트·토큰·렌더링·모달·트레이드오프 등 정착어)는 그대로 둔다 — ai-tell-quick-rules.md 참조
 - 수치·파일명·함수명·에러 메시지·코드 스니펫 변형 금지
 
+**원문 음차는 인용할 때만 그대로 둔다 (B-3 보완)**
+
+리뷰 대상 코드나 문서에 안 굳은 음차(에스케이프 해치, 스파이크, 어피니티 등)가 있을 때,
+**원문에 있다는 이유만으로 화이트리스트를 통과시키지 않는다.** 자리에 따라 다르게 다룬다.
+
+| 자리 | 처리 |
+|------|------|
+| 코드블록, `인용`, diff 발췌 | **그대로.** 바꾸면 원문과 대조가 안 돼서 리뷰가 불친절해진다 |
+| 리뷰어 자기 문장(요약, 문제 진술, 제안) | **첫 등장에 한 번 풀어쓴다.** 필요하면 원어를 괄호로 병기 |
+
+- ✗ 명시 타깃 에스케이프 해치가 릴리즈 파일 가드를 우회해서
+- ✓ 사용자가 URL을 직접 주면 릴리즈 파일 가드를 건너뛰게 돼서
+- ✗ 레시피에 스파이크 검증 근거가 같이 남아 있어서
+- ✓ 레시피에 실제로 돌려본 결과가 같이 남아 있어서
+
+풀어쓴 ✗ 예시는 F-6(명사구 압축)에도 걸린다 — 명사를 세 개 이어붙이면 뭘 어쨌다는 동사가
+사라진다. 안 굳은 음차가 보이면 명사구 압축도 같이 의심한다.
+
 **깎지 말 것 (중요) — 이건 AI-tell이 아니라 리뷰어의 진짜 voice다**
 
 아래 패턴은 인라인·대화형 **두 레지스터 모두에서 보존한다**. 특히 "~것 같아요/같습니다"는
@@ -115,6 +133,32 @@ authentic 코퍼스에서 282건으로 인라인 리뷰의 핵심 제안 어투
 | "~해주세요~", "~할게요~" 물결 친근체 | voice 시그니처 |
 | 🙏 😀 👍 이모지 (코멘트당 1개 안팎) | 온기 |
 
+**보존은 밀도까지 보존하는 것이다 — 매 문장에 쓰라는 말이 아니다**
+
+282건은 코퍼스 1,300건 중 20% 남짓이고, 실측 종결어미는 여러 갈래로 흩어져 있다 —
+"것 같아요" 282, "어떨까요?" 144, "좋아보입니다" 54, "필요해보이네요" 29.
+한 갈래로 몰면 문장 하나하나는 authentic한데 리뷰 전체가 기계로 읽힌다.
+실제로 코멘트 9건에 "~것 같" 17회, 그중 8건이 `[문제] ~것 같아요 → [제안] ~것 같습니다`
+같은 리듬으로 나온 사례가 있다.
+
+- 한 코멘트에 "~것 같" 계열은 **1회까지**. 문제 진술과 제안에 각각 붙여 두 번 쓰지 않는다.
+- 리뷰 한 건에서 "~것 같"으로 닫는 코멘트는 **절반 이하**. 나머지는 "~는 건 어떨까요?",
+  "좋아보입니다", "~네요", 단정형으로 흩는다.
+- **코드를 읽고 확인한 결함은 단정한다.** 전부 헤지하면 확신도 신호가 사라져서 리뷰이가
+  "이건 확실한 버그, 저건 그냥 의심"을 구분하지 못한다.
+- 확신이 없으면 헤지를 겹치지 말고 **질문으로 닫는다**("이 경로도 타나요?").
+
+| 헤지 몰림 | 이렇게 |
+|-----------|--------|
+| 릴리즈 파일에 프레임이 생성될 것 같아요 | 릴리즈 파일에 그대로 프레임이 생깁니다 *(코드로 확인한 사실)* |
+| 같은 페이지가 또 생길 수 있을 것 같아요 | 같은 페이지가 또 생길 것 같은데, 맞나요? *(추측 → 질문)* |
+| 상태까지 보여주는 게 좋을 것 같습니다 | 상태까지 같이 보여주는 건 어떨까요 *(제안 → 종결 분산)* |
+
+**분량도 severity에 맞춘다.** 모든 코멘트를 `[문제 문단 + 제안 문단 + 코드블록]` 3단으로
+찍어내지 않는다. `a:`나 명백한 불일치 지적은 한 줄로 끝낸다
+(`a: 실제 노드명이 ✎Contents라 여기도 맞춰주세요.`).
+한 리뷰의 코멘트가 전부 같은 길이면 그 자체가 AI-tell이다.
+
 ## Severity 기준
 
 - **critical** (`r:`) — 머지 시 즉시 장애·데이터 손상·보안 사고로 이어지는 버그. 꼭 반영해야 한다.
@@ -158,4 +202,22 @@ GitHub 마크다운은 **한 줄 개행(`\n`)을 무시하고 같은 문단으
 - **목록을 쓸 때도 목록 바로 앞에 빈 줄**을 하나 둔다 (GitHub에서 목록이 앞 문단에 먹히지 않도록).
 - 짧고 명확한 지적(한 줄이면 충분한 것)은 굳이 블록을 나누지 말고 한 문장으로 둔다 — 억지로 문단을 쪼개지 않는다.
 
-이슈가 여러 개면 severity 높은 순(critical → suggestion)으로 정렬한다. 발견된 이슈가 없으면 그 이유를 한 줄로 명시한다("로직·경계값·에러 처리 모두 적절. 머지 가능.").
+이슈가 여러 개면 severity 높은 순(critical → suggestion)으로 정렬한다. 발견된 이슈가 없으면 그 이유를 한 줄로 명시한다("로직, 경계값, 에러 처리 모두 적절. 머지 가능.").
+
+## 내보내기 전 자가점검
+
+코멘트를 개별로 보면 다 멀쩡한데 **묶어놓으면 기계로 읽히는** 경우가 많다. 세트 전체를
+내놓기 전에 아래를 센다. 걸리면 초안을 그대로 내지 말고 고쳐서 낸다.
+
+1. "~것 같" 계열이 **한 코멘트에 2회 이상**인 곳 → 1회로 줄인다
+2. "~것 같"으로 닫는 코멘트가 **전체의 절반을 넘는지** → 다른 종결로 분산한다
+3. 코드로 확인한 결함을 헤지로 진술한 곳 → 단정으로 바꾼다
+4. 모든 코멘트가 **같은 3단 구조에 같은 분량**인지 → 사소한 건 한 줄로 줄인다
+5. 사소한 지적이 섞여 있는데 `a:`가 하나도 없는지 → severity를 다시 매긴다
+6. 가운뎃점(·) 나열이 남았는지 (C-12, 표·용어목록·합성어는 예외)
+7. 리뷰어 자기 문장에 풀어쓰지 않은 원문 음차가 남았는지 (B-3)
+8. 명사구 압축(F-6)·비유 명사(F-7)가 남았는지 — "사슬의 마지막 고리가 조용히 실패하는 셈"
+   같은 문학적 비유는 리뷰 코멘트에선 담백한 서술로 내린다
+
+1~5는 개별 문장이 아니라 **세트 전체의 분포**를 보는 항목이라, 코멘트를 하나씩 다듬는
+동안에는 안 잡힌다. 반드시 마지막에 전체를 놓고 센다.

package/role-agents/technical-writer/references/author-voice.md

@@ -33,6 +33,22 @@
 "~하는 건 어떨까요?" 144 · "좋아보입니다/좋아보이네요" 54 · "필요해보이네요" 29 ·
 "~해서요(이유)" 49 · "개인적으로" 24 · 이모지 64 · 물결(~) 56.
 
+### 이 숫자는 분포지 지침이 아니다
+
+가장 흔한 실패는 시그니처를 안 쓰는 게 아니라 **한 갈래에 몰아 쓰는 것**이다.
+282는 코퍼스 1,300건 중 20% 남짓이고, 나머지는 "어떨까요?" 144, "좋아보입니다" 54처럼
+여러 갈래로 흩어져 있다. "보존하라"를 "매 문장에 쓰라"로 읽으면 문장 하나하나는
+authentic한데 글 전체가 기계로 읽힌다 — 시그니처가 일정 간격으로 박히는 순간
+그 규칙성 자체가 새 AI-tell이 된다.
+
+- 한 갈래가 전체 종결의 **절반을 넘지 않게** 흩는다.
+- 확인한 사실은 헤지 없이 단정한다. 다 헤지하면 확신도 신호가 사라진다.
+- 이모지·물결도 마찬가지 — 문단마다 하나씩 꽂으면 계산된 티가 난다.
+
+이건 문장 단위로는 안 잡히고 **글 전체를 놓고 세어야** 보인다.
+소비자 쪽 구체 상한은 각 에이전트가 정한다(예: `code-review-writer`의
+"코멘트당 1회, 리뷰 전체의 절반 이하").
+
 ---
 
 ## 레지스터 A — 인라인 리뷰 코멘트 (코드 라인에 다는 지적)
@@ -168,7 +184,7 @@ ghost 는 button의 ghost variant 를 위한 토큰입니다.
 
 | humanize가 깎으려는 것 | 실제로는 |
 |------------------------|----------|
-| "~것 같아요", "~인 것 같습니다" (헤징) | **보존** — 제안형 어투의 핵심. 표본 282건. |
+| "~것 같아요", "~인 것 같습니다" (헤징) | **보존** — 제안형 어투의 핵심. 표본 282건. 단 밀도는 관리한다(위 "이 숫자는 분포지 지침이 아니다"). |
 | "~해주세요~", "~할게요~" 물결 친근체 | **보존** — voice 시그니처. |
 | "개인적으로", "제 취향이긴 한데" | **보존** — 의견 프레이밍 방식. |
 | 🙏 😀 👍 등 이모지 (코멘트당 1개 안팎) | **보존** — 온기. |