@tienne/gestalt 0.90.0 → 0.90.1

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tienne/gestalt",
-  "version": "0.90.0",
+  "version": "0.90.1",
   "description": "TypeScript AI Development Harness - Gestalt psychology-driven requirement clarification",
   "repository": {
     "type": "git",

package/dist/plugin/skills/architecture/SKILL.md

@@ -448,7 +448,7 @@ FE가 부르는 BE 레포나 배포 매니페스트 레포처럼 지금 레포
 2. 이 머신에 있는 로컬 클론 (같은 remote org 아래 체크아웃)
 3. `gh repo list <org>`로 본 같은 org의 레포 목록
 
-**후보가 0개거나 2개 이상이면 사용자에게 묻는다.** 이름이 비슷하다고 고르지 않는다. 확정한 레포는 IR의 `repos`에 `{ id, name, root, remote? }`로 넣는다. `root`는 로컬 경로다. 로컬 클론을 마련하는 법은 아래 [로컬 클론 받기](#로컬-클론-받기)를 따른다.
+**후보가 0개거나 2개 이상이면 사용자에게 묻는다.** 이름이 비슷하다고 고르지 않는다. 확정한 레포는 IR의 `repos`에 `{ id, name, root, remote? }`로 넣는다. `root`는 로컬 경로다. 로컬 클론을 마련하는 법은 아래 [로컬 클론 받기](#로컬-클론-받기)를, 이미 있는 클론을 읽는 법은 [사용자가 체크아웃해 둔 레포](#사용자가-체크아웃해-둔-레포)를 따른다.
 
 **예외가 하나 있다. 근거 줄이 다음 레포를 하나로 가리키면 묻지 않고 따라간다.** Step 3-3의 `gateway` 사슬이 그렇다. 라우트의 `uri` 줄이나 설정 서버 import 줄이 다음 레포를 정하므로 후보가 하나인 경우다. 로컬 클론이 없으면 이때도 아래대로 받는다.
 
@@ -458,12 +458,36 @@ FE가 부르는 BE 레포나 배포 매니페스트 레포처럼 지금 레포
 
 - 위치는 분석 대상 레포 밖의 캐시 `~/.gestalt/architecture/clones/<host>/<org>/<repo>`다. 분석 대상 레포의 `.gestalt/` 아래에 받으면 그 레포가 `.gestalt`를 ignore하지 않을 때 받은 레포가 커밋에 섞인다.
 - `git clone --depth 1`로 받는다. SSH로 받을 수 있으면 SSH를 쓴다.
-- 캐시에 이미 있으면 `git fetch --depth 1` 뒤 기본 브랜치로 맞춰 다시 쓴다.
-- 사용자가 이미 체크아웃해 둔 레포는 읽기만 한다. 브랜치를 바꾸거나 파일을 쓰지 않는다.
+- 캐시에 이미 있으면 아래 명령으로 원격 기본 브랜치의 최신 커밋에 맞춘 뒤 다시 쓴다. `origin HEAD`가 원격 기본 브랜치를 가리키므로 브랜치 이름을 몰라도 된다. 캐시는 게슈탈트만 쓰는 자리라 `reset --hard`로 덮어도 잃을 게 없다. shallow 클론이라 `git pull`은 쓰지 않는다.
+
+  ```bash
+  git -C <캐시 경로> fetch --depth 1 origin HEAD
+  git -C <캐시 경로> reset --hard FETCH_HEAD
+  ```
+
 - 받은 레포는 `repos`의 `root`에 그 캐시 경로로 넣는다.
 - 권한이 없거나 404라서 받지 못하면 그 사실을 미해결 질문으로 남긴다.
 - 받은 레포 목록은 Step 8 보고에서 알린다.
 
+### 사용자가 체크아웃해 둔 레포
+
+사용자가 작업하던 클론은 기능 브랜치에 있거나 pull을 안 해서 기본 브랜치보다 뒤처져 있을 수 있다. 그대로 읽으면 그 시점 코드로 그림이 나온다. 그래서 작업 트리는 그대로 두고 원격 기본 브랜치를 따로 꺼내 읽는다.
+
+1. `git -C <클론> fetch origin`으로 원격 ref만 갱신한다. 작업 트리와 지금 브랜치는 바뀌지 않는다.
+2. `git -C <클론> symbolic-ref --short refs/remotes/origin/HEAD`로 기본 브랜치를 찾는다 (예: `origin/main`). 비어 있으면 `git -C <클론> remote set-head origin --auto`를 먼저 부른다.
+3. 지금 체크아웃이 그 커밋과 같으면(`git -C <클론> rev-parse HEAD`가 같으면) 클론을 그대로 읽고 `root`에 클론 경로를 넣는다.
+4. 다르면 클론 밖에 분리된 워크트리를 만들어 읽는다. `root`에는 그 워크트리 경로를 넣는다.
+
+   ```bash
+   git -C <클론> worktree add --detach ~/.gestalt/architecture/worktrees/<host>/<org>/<repo> <기본 브랜치>
+   ```
+
+   이미 있으면 `git -C <워크트리> checkout --detach <기본 브랜치>`로 옮긴다. 워크트리는 `.git/worktrees/` 아래 메타데이터만 남기고 사용자의 브랜치와 작업 트리는 건드리지 않는다.
+
+5. fetch가 권한이나 네트워크 문제로 실패하면 지금 체크아웃을 그대로 읽는다. 대신 읽은 브랜치 이름을 미해결 질문으로 남긴다 (예: "`org/api-server`는 원격을 못 받아 `feat/coupon` 브랜치로 읽었다").
+
+사용자 클론에서 브랜치를 바꾸거나 pull, reset, stash를 하지 않는다. 작업 트리에 파일도 쓰지 않는다.
+
 ## Step 6 — IR 작성과 validate
 
 `schemaPath`의 JSON Schema대로 IR을 쓴다. `schemaVersion`은 `"1.0.0"`이다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tienne/gestalt",
-  "version": "0.90.0",
+  "version": "0.90.1",
   "description": "TypeScript AI Development Harness - Gestalt psychology-driven requirement clarification",
   "repository": {
     "type": "git",

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gestalt",
-  "version": "0.90.0",
+  "version": "0.90.1",
   "description": "Gestalt psychology-driven AI development harness. Transforms scattered requirements into structured, validated specifications through interactive interviews.",
   "author": {
     "name": "tienne"

package/plugin/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "gestalt": {
       "command": "npx",
-      "args": ["-y", "@tienne/gestalt@0.90.0", "serve"],
+      "args": ["-y", "@tienne/gestalt@0.90.1", "serve"],
       "startup_timeout_sec": 180,
       "tool_timeout_sec": 900
     }

package/plugin/mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "gestalt": {
       "command": "npx",
-      "args": ["-y", "@tienne/gestalt@0.90.0", "serve"],
+      "args": ["-y", "@tienne/gestalt@0.90.1", "serve"],
       "startup_timeout_sec": 180,
       "tool_timeout_sec": 900
     }

package/plugin/skills/architecture/SKILL.md

@@ -448,7 +448,7 @@ FE가 부르는 BE 레포나 배포 매니페스트 레포처럼 지금 레포
 2. 이 머신에 있는 로컬 클론 (같은 remote org 아래 체크아웃)
 3. `gh repo list <org>`로 본 같은 org의 레포 목록
 
-**후보가 0개거나 2개 이상이면 사용자에게 묻는다.** 이름이 비슷하다고 고르지 않는다. 확정한 레포는 IR의 `repos`에 `{ id, name, root, remote? }`로 넣는다. `root`는 로컬 경로다. 로컬 클론을 마련하는 법은 아래 [로컬 클론 받기](#로컬-클론-받기)를 따른다.
+**후보가 0개거나 2개 이상이면 사용자에게 묻는다.** 이름이 비슷하다고 고르지 않는다. 확정한 레포는 IR의 `repos`에 `{ id, name, root, remote? }`로 넣는다. `root`는 로컬 경로다. 로컬 클론을 마련하는 법은 아래 [로컬 클론 받기](#로컬-클론-받기)를, 이미 있는 클론을 읽는 법은 [사용자가 체크아웃해 둔 레포](#사용자가-체크아웃해-둔-레포)를 따른다.
 
 **예외가 하나 있다. 근거 줄이 다음 레포를 하나로 가리키면 묻지 않고 따라간다.** Step 3-3의 `gateway` 사슬이 그렇다. 라우트의 `uri` 줄이나 설정 서버 import 줄이 다음 레포를 정하므로 후보가 하나인 경우다. 로컬 클론이 없으면 이때도 아래대로 받는다.
 
@@ -458,12 +458,36 @@ FE가 부르는 BE 레포나 배포 매니페스트 레포처럼 지금 레포
 
 - 위치는 분석 대상 레포 밖의 캐시 `~/.gestalt/architecture/clones/<host>/<org>/<repo>`다. 분석 대상 레포의 `.gestalt/` 아래에 받으면 그 레포가 `.gestalt`를 ignore하지 않을 때 받은 레포가 커밋에 섞인다.
 - `git clone --depth 1`로 받는다. SSH로 받을 수 있으면 SSH를 쓴다.
-- 캐시에 이미 있으면 `git fetch --depth 1` 뒤 기본 브랜치로 맞춰 다시 쓴다.
-- 사용자가 이미 체크아웃해 둔 레포는 읽기만 한다. 브랜치를 바꾸거나 파일을 쓰지 않는다.
+- 캐시에 이미 있으면 아래 명령으로 원격 기본 브랜치의 최신 커밋에 맞춘 뒤 다시 쓴다. `origin HEAD`가 원격 기본 브랜치를 가리키므로 브랜치 이름을 몰라도 된다. 캐시는 게슈탈트만 쓰는 자리라 `reset --hard`로 덮어도 잃을 게 없다. shallow 클론이라 `git pull`은 쓰지 않는다.
+
+  ```bash
+  git -C <캐시 경로> fetch --depth 1 origin HEAD
+  git -C <캐시 경로> reset --hard FETCH_HEAD
+  ```
+
 - 받은 레포는 `repos`의 `root`에 그 캐시 경로로 넣는다.
 - 권한이 없거나 404라서 받지 못하면 그 사실을 미해결 질문으로 남긴다.
 - 받은 레포 목록은 Step 8 보고에서 알린다.
 
+### 사용자가 체크아웃해 둔 레포
+
+사용자가 작업하던 클론은 기능 브랜치에 있거나 pull을 안 해서 기본 브랜치보다 뒤처져 있을 수 있다. 그대로 읽으면 그 시점 코드로 그림이 나온다. 그래서 작업 트리는 그대로 두고 원격 기본 브랜치를 따로 꺼내 읽는다.
+
+1. `git -C <클론> fetch origin`으로 원격 ref만 갱신한다. 작업 트리와 지금 브랜치는 바뀌지 않는다.
+2. `git -C <클론> symbolic-ref --short refs/remotes/origin/HEAD`로 기본 브랜치를 찾는다 (예: `origin/main`). 비어 있으면 `git -C <클론> remote set-head origin --auto`를 먼저 부른다.
+3. 지금 체크아웃이 그 커밋과 같으면(`git -C <클론> rev-parse HEAD`가 같으면) 클론을 그대로 읽고 `root`에 클론 경로를 넣는다.
+4. 다르면 클론 밖에 분리된 워크트리를 만들어 읽는다. `root`에는 그 워크트리 경로를 넣는다.
+
+   ```bash
+   git -C <클론> worktree add --detach ~/.gestalt/architecture/worktrees/<host>/<org>/<repo> <기본 브랜치>
+   ```
+
+   이미 있으면 `git -C <워크트리> checkout --detach <기본 브랜치>`로 옮긴다. 워크트리는 `.git/worktrees/` 아래 메타데이터만 남기고 사용자의 브랜치와 작업 트리는 건드리지 않는다.
+
+5. fetch가 권한이나 네트워크 문제로 실패하면 지금 체크아웃을 그대로 읽는다. 대신 읽은 브랜치 이름을 미해결 질문으로 남긴다 (예: "`org/api-server`는 원격을 못 받아 `feat/coupon` 브랜치로 읽었다").
+
+사용자 클론에서 브랜치를 바꾸거나 pull, reset, stash를 하지 않는다. 작업 트리에 파일도 쓰지 않는다.
+
 ## Step 6 — IR 작성과 validate
 
 `schemaPath`의 JSON Schema대로 IR을 쓴다. `schemaVersion`은 `"1.0.0"`이다.