@tienne/gestalt 0.15.0 → 0.15.2

package/CLAUDE.md

@@ -7,9 +7,9 @@
 ## Architecture
 - **Interview Engine**: 게슈탈트 원리 기반 Q&A로 해상도 점수를 0.8 이상으로 높임
 - **Spec Generator**: 완료된 인터뷰에서 구조화된 프로젝트 스펙(Spec) 생성
-- **Execute Engine**: Spec→ExecutionPlan 변환 (Figure-Ground→Closure→Proximity→Continuity)
+- **Execute Engine**: Spec→ExecutionPlan 변환 (Figure-Ground→Closure→Proximity→Continuity). 설계상 **항상 Passthrough 모드** — Claude Code가 도구(Bash/Edit 등)로 실제 파일 수정·코드 실행을 수행하므로 LLM 주체가 됨 (API 키 유무 무관)
 - **Resilience Engine**: Stagnation 감지 → Lateral Thinking Personas → Human Escalation
-- **MCP Server**: stdio transport, API 키 없으면 Passthrough 모드 자동 활성화
+- **MCP Server**: stdio transport, API 키 없으면 Passthrough 모드 자동 활성화 (Execute는 항상 Passthrough)
 - **Skill System**: SKILL.md 기반 확장, chokidar hot-reload
 - **Code Knowledge Graph**: 정적 분석 → 의존성 그래프 → Blast-Radius 영향 파일 추출
 - **Event Store**: better-sqlite3 WAL 모드 이벤트 소싱

package/README.ko.md

@@ -77,7 +77,9 @@ Gestalt는 코드를 작성하기 전에 요구사항을 함께 구체화해줘
 
 ### Passthrough 모드는 어떻게 작동하나요?
 
-Gestalt는 **MCP 서버**로 실행돼요. Claude Code를 통해 사용할 경우 Claude Code가 LLM 역할을 담당해요 — Gestalt는 프롬프트와 컨텍스트를 반환하고, 실제 추론은 Claude Code가 수행해요. 서버 자체는 별도 API 호출을 하지 않아요.
+Gestalt는 **MCP 서버**로 실행돼요. Claude Code를 통해 사용할 경우 Claude Code가 LLM 역할을 담당해요 — Gestalt는 프롬프트와 컨텍스트를 반환하고, 실제 추론은 Claude Code가 해요. 서버 자체는 별도 API 호출을 하지 않아요.
+
+> **참고해 주세요** — Execute 단계는 API 키 설정 여부와 무관하게 **항상 Passthrough 모드**로 동작해요. Execute는 Claude Code의 도구(Bash, Edit 등)로 실제 파일 수정과 코드 실행을 수행하기 때문에, Claude Code가 LLM 주체가 되는 게 설계 의도예요. 자체 LLM으로 대체하는 모드는 따로 없어요(미구현이 아니라 설계상 그래요).
 
 ```
 Claude Code
@@ -116,7 +118,7 @@ Spec과 실행 결과는 레포 루트의 `.gestalt/memory.json`에 자동으로
 }
 ```
 
-- **커밋하세요** — `.gestalt/memory.json`은 일반 JSON 파일이에요. 커밋하면 팀원도 `git pull` 후 이전 결정 사항을 그대로 이어받을 수 있어요.
+- **커밋하세요** — `.gestalt/memory.json`은 일반 JSON 파일이에요. 커밋해두면 팀원도 `git pull` 후 이전 결정 사항을 그대로 이어받을 수 있어요.
 - **컨텍스트 반영** — 다음 Spec을 생성할 때 이전 목표와 아키텍처 결정 사항이 프롬프트에 자동으로 반영돼요.
 - **User Profile** — 개인 설정은 `~/.gestalt/profile.json`에 저장돼요. git에는 올라가지 않아요.
 
@@ -126,7 +128,7 @@ Spec과 실행 결과는 레포 루트의 `.gestalt/memory.json`에 자동으로
 
 ### 옵션 1: Claude Code 플러그인 (권장)
 
-설치 한 번에 MCP 서버, 슬래시 커맨드, Gestalt 에이전트, 프로젝트 컨텍스트를 모두 사용할 수 있어요.
+설치 한 번에 MCP 서버, 슬래시 커맨드, Gestalt 에이전트, 프로젝트 컨텍스트를 모두 쓸 수 있어요.
 
 **터미널에서:**
 
@@ -208,7 +210,7 @@ claude mcp add gestalt -- npx -y @tienne/gestalt
 /interview "Stripe로 결제 플로우를 만들고 싶어"
 ```
 
-각 라운드는 모호한 부분을 집중해서 파악해요:
+각 라운드는 모호한 부분을 집중적으로 파악해요:
 
 - **Closure** — 빠진 요구사항과 말하지 않고 가정한 것을 찾아요
 - **Proximity** — 함께 묶여야 할 기능을 식별해요
@@ -226,7 +228,7 @@ claude mcp add gestalt -- npx -y @tienne/gestalt
 
 #### 인터뷰가 길어질 때 (Context Compression)
 
-라운드가 5개를 초과하면 Gestalt가 자동으로 압축을 제안해요. `compress` action을 사용하면 이전 대화를 요약해 컨텍스트를 줄일 수 있어요:
+라운드가 5개를 초과하면 Gestalt가 자동으로 압축을 제안해요. `compress` action을 쓰면 이전 대화를 요약해 컨텍스트를 줄일 수 있어요:
 
 ```
 1. respond 응답에 needsCompression: true + compressionContext 포함
@@ -286,6 +288,8 @@ Spec에서 실행 계획을 만들어 실행해요:
 /execute
 ```
 
+> Execute는 **항상 Passthrough 모드**로 동작해요 — 실제 파일 수정과 코드 실행은 Claude Code가 도구(Bash, Edit 등)로 수행해요. API 키를 설정해도 Execute가 자체 LLM 모드로 바뀌지 않아요. 그런 모드는 설계상 존재하지 않아요.
+
 **Planning 단계**에서 4가지 게슈탈트 원리를 고정 순서로 적용해요:
 
 | 단계 | 원리 | 역할 |
@@ -343,7 +347,7 @@ ges_execute({
 
 #### 실행 진행 패널
 
-`/execute` 실행 중 Claude Code Task 패널에 진행 상태가 실시간으로 표시돼요. Planning 단계부터 Evaluate까지 각 완료 태스크 수, 현재 태스크 이름, 실패 수, 병렬 그룹 구조가 자동으로 갱신돼요.
+`/execute` 실행 중 Claude Code Task 패널에 진행 상태가 실시간으로 표시돼요. Planning 단계부터 Evaluate까지 완료 태스크 수, 현재 태스크 이름, 실패 수, 병렬 그룹 구조가 자동으로 갱신돼요.
 
 #### 하위 에이전트 생성 (Spawn)
 
@@ -390,7 +394,7 @@ evolve_fix → 수정 태스크 제출 → 재평가
 evolve → Spec 패치 (AC/constraints) → 영향받은 태스크 재실행 → 재평가
 ```
 
-Spec 패치 범위: AC와 constraints는 자유 수정; ontology는 추가/변경만; **goal은 변경 불가**.
+Spec 패치 범위: AC와 constraints는 자유롭게 수정할 수 있어요. ontology는 추가/변경만 가능하고, **goal은 변경할 수 없어요**.
 
 **Flow C — Lateral Thinking** (답보 상태 감지 시)
 
@@ -403,7 +407,7 @@ Spec 패치 범위: AC와 constraints는 자유 수정; ontology는 추가/변
 | 진전 없음 (no drift) | **Reification** | 빠진 것 채우기 |
 | 효과 감소 | **Invariance** | 성공한 패턴 복제 |
 
-4개 Persona를 모두 소진하면 세션이 **Human Escalation**으로 종료돼요. 직접 해결할 수 있도록 구체적인 제안도 함께 제공해요.
+4개 Persona를 모두 소진하면 세션이 **Human Escalation**으로 종료돼요. 직접 해결할 수 있도록 구체적인 제안도 함께 알려줘요.
 
 **종료 조건:**
 
@@ -448,7 +452,7 @@ review_start → 에이전트 관점 제출 → 합의 → 자동 수정
 | `performance-reviewer` | 메모리 누수, N+1 쿼리, 번들 크기, 비동기 |
 | `quality-reviewer` | 가독성, SOLID, 에러 핸들링, DRY |
 
-파이프라인 밖에서도 `/agent`로 언제든 에이전트를 사용할 수 있어요:
+파이프라인 밖에서도 `/agent`로 언제든 에이전트를 쓸 수 있어요:
 
 ```bash
 # 사용 가능한 에이전트 목록 조회
@@ -460,7 +464,7 @@ review_start → 에이전트 관점 제출 → 합의 → 자동 수정
 /agent technical-writer "이 모듈의 README를 작성해줘"
 ```
 
-인터뷰 결과에서 커스텀 Role 에이전트를 생성할 수도 있어요:
+인터뷰 결과에서 커스텀 Role 에이전트를 만들 수도 있어요:
 
 ```
 # 인터뷰 완료 후 커스텀 에이전트 생성
@@ -478,15 +482,12 @@ ges_create_agent  →  action: "submit", sessionId: "<id>", agentContent: "..."
 
 ### CLI 모드 (Claude Code 없이 사용하기)
 
-Claude Code 없이 터미널에서 바로 사용하고 싶다면 CLI 모드를 이용할 수 있어요. **`ANTHROPIC_API_KEY`가 필요해요.**
+Claude Code 없이 터미널에서 바로 쓰고 싶다면 CLI 모드를 이용할 수 있어요. **`ANTHROPIC_API_KEY`가 필요해요.**
 
 ```bash
 # 인터랙티브 인터뷰 시작
 npx @tienne/gestalt interview "주제"
 
-# 터미널 세션을 GIF로 녹화
-npx @tienne/gestalt interview "주제" --record
-
 # 완료된 세션에서 Spec 생성
 npx @tienne/gestalt spec <session-id>
 
@@ -500,24 +501,6 @@ npx @tienne/gestalt setup
 npx @tienne/gestalt serve
 ```
 
-#### 인터뷰 세션 녹화
-
-`--record` (또는 `-r`) 플래그를 추가하면 터미널 세션을 GIF로 녹화할 수 있어요:
-
-```bash
-npx @tienne/gestalt interview "주제" --record
-```
-
-인터뷰가 완료되면 현재 디렉토리에 GIF 파일이 생성돼요:
-
-```
-user-auth-interview-20260327.gif
-```
-
-파일명은 LLM이 인터뷰 주제를 기반으로 kebab-case로 생성하고, `YYYYMMDD` 날짜를 붙여요. 외부 바이너리는 필요하지 않아요 — `gifencoder`와 `jimp` npm 패키지만 사용해요.
-
-**중단된 세션 이어 녹화:** 녹화 중 세션이 중단되더라도 걱정하지 않아도 돼요. 동일 세션을 다시 실행하면 `.frames` 파일을 자동으로 감지해 이어서 녹화해요. 임시 프레임 데이터는 `.gestalt/recordings/{sessionId}.frames`에 저장되고, GIF 생성이 완료되면 자동으로 삭제돼요.
-
 ---
 
 ## 설정